Referenz des Plugin-Frontend-SDKs

Plugin-Frontend-Code läuft in einem Iframe mit Sandbox. Dieses Dokument beschreibt die technischen Details der Schnittstelle. Eine allgemeine Einführung finden Sie in README.md.

---

Sicherheitsmodell

Eigenschaft	Wert
Iframe-Sandbox	Nur allow-scripts (kein allow-same-origin)
CSP script-src	Durch eine Nonce abgesichert; nur das Einstiegsskript wird geladen
CSP connect-src	'self' – das Plugin kann POST-Anfragen an /plugins/{id}/api/* senden und /plugins/{id}/events/poll abfragen
CSP default-src	'none'
Zugriff auf das übergeordnete DOM	Gesperrt (kein allow-same-origin)
Ogma-Sitzungscookies	Für das Plugin nicht zugänglich
Kommunikation zwischen Plugins	Nicht verfügbar

Datenaufrufe über die Bridge werden bei jeder Anfrage serverseitig autorisiert; Anzeige- und Navigationsaktionen werden von der Host-Oberfläche verarbeitet. Der auf der Registerkarte Berechtigungen angezeigte Berechtigungscache dient nur der Anzeige und steuert den Datenzugriff nicht.

---

Bridge-Protokoll

Plugin-JavaScript kommuniziert über postMessage mit dem Ogma-Host. Der Host befindet sich in PluginsView.vue und verarbeitet bridge_request-Nachrichten.

Nachrichtenformat für Anfragen

interface BridgeRequest {
  type: 'bridge_request'
  sessionId: string     // nonce assigned when the bridge is set up; prevents stale messages
  requestId: string     // caller-generated correlation id (max 128 chars)
  command: string       // e.g. "ogma.requests.get"
  payload?: unknown     // command-specific input
}

Maximale Gesamtgröße einer Nachricht: 65 536 Bytes.

Nachrichtenformat für Antworten

interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}

Verwendung des SDKs (empfohlen)

Senden Sie keine rohen postMessage-Bridge-Anfragen manuell. Verwenden Sie das globale Objekt ogmaSDK:

ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});

Das SDK kapselt die gesamte Bridge-Kommunikation und übernimmt die Zuordnung von Anfragen, die Verwaltung der sessionId und die Auflösung von Promises.

---

Befehlsreferenz

ogma.meta.get

Keine Payload erforderlich.

Gibt { pluginId, packageId, name, version, ogmaVersion } zurück.

ogma.requests.get

Payload: { id: string }

Gibt einen HTTP-Eintrag mit ausgewählten Feldern zurück. Felder: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Diese Projektion enthält weder Header noch Body-Bytes.

Erfordert: read_http_history (automatisch erteilt).

ogma.requests.getRaw

Payload: { id: string }. Rufen Sie den Befehl über sdk.requests.getRaw(id) auf.

Gibt requestBodyBase64, responseBodyBase64, die Längen der dekodierten Bodies (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated und maxBodyBytes zurück. Trotz des Namens liefert diese Operation Body-Bytes und keine vollständige rohe HTTP-Nachricht. Unterstützte Inhaltskodierungen werden vor der Projektion dekodiert. Jeder Body ist auf 256 KiB begrenzt; prüfen Sie die Kürzungsindikatoren, bevor Sie ein vollständiges Asset verarbeiten.

Erfordert: read_http_history (automatisch erteilt).

ogma.requests.search

Payload: { limit?: number, offset?: number, query?: string }

query unterstützt HTTPQL-Filterausdrücke. Maximaler Wert für limit: 20. Gibt { items: [...], total: number, limit: number, offset: number } zurück.

Erfordert: read_http_history (automatisch erteilt).

ogma.findings.list

Payload: { limit?: number, offset?: number }

Gibt { items: [...], total: number, limit: number, offset: number } mit höchstens 20 Befunden pro Seite zurück. Die Elemente sind Zusammenfassungen; zu den Feldern gehören id, title, severity, status, reporter, tags und created_at.

Erfordert: read_findings (automatisch erteilt).

ogma.scope.getActive

Keine Payload. Gibt die aktive Scope-Voreinstellung oder null zurück.

Erfordert: read_scope (automatisch erteilt).

ogma.projects.getCurrent

Keine Payload. Gibt { id, name, status } oder null zurück.

Erfordert: read_projects (automatisch erteilt).

ogma.log

Payload: { message: string }

Schreibt in den Protokollpuffer des Plugins.

ogma.ui.resize

Payload: { height: number } (maximal 2000)

Fordert den Host auf, die Iframe-Höhe festzulegen.

ogma.ui.sidebar.registerItem

Payload: { name: string, path: string } (Name maximal 64 Zeichen, Pfad maximal 256 Zeichen)

Registriert Navigation innerhalb des Plugin-Panels. Maximal 20 Einträge pro Plugin. Registrieren Sie die zugehörigen Seiteninhalte mit sdk.navigation.addPage(path, { title, body }); beim Auswählen des Eintrags wird diese Seite innerhalb des Iframes angezeigt, nicht als neue Ogma-Arbeitsbereichsroute auf oberster Ebene.

ogma.backend.call

Payload: { method: string, args: unknown[] }

Ruft einen über sdk.api.register(method, fn) registrierten Backend-RPC-Handler auf. Der Methodenname darf maximal 64 Zeichen lang sein.

Gibt den Rückgabewert des Backend-Handlers in JSON-serialisierter Form zurück.

ogma.backend.onEvent

Payload: keine erforderlich.

Wird lediglich bestätigt. Verwenden Sie ogma.events.poll, um Ereignisse tatsächlich abzurufen.

ogma.events.poll

Payload: { since: number } (Index der letzten Abfrage; mit 0 beginnen)

Gibt { events: [{ event: string, args: unknown[] }], next_since: number } zurück.

ogma.navigation.addPage

Payload: { path: string, title?: string }

Die Bridge bestätigt den Seitenpfad. Das injizierte SDK akzeptiert zusätzlich { body: HTMLElement } als Option für sdk.navigation.addPage(path, options), fügt den Seiteninhalt innerhalb des Iframes ein und wechselt die Sichtbarkeit der Seiten, wenn der Host den zugehörigen Seitenleisteneintrag auswählt. Der DOM-Knoten bleibt lokal; er wird nicht über die Bridge serialisiert.

ogma.window.showToast

Payload: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

Zeigt eine Toast-Benachrichtigung im Plugin-Panel an. Dauer in ms (maximal 10000, standardmäßig 3000).

ogma.commands.register

Payload: { id: string, name: string }

Registriert den Plugin-Befehl im Befehlsspeicher des Hosts. Bei der Ausführung durch den Host wird eine plugin_command-Nachricht mit commandId und Kontext an das Iframe zurückgesendet; das Plugin muss den entsprechenden Callback bereitstellen. Die Registrierung allein führt den Befehl nicht aus.

ogma.menu.registerItem

Payload: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

Registriert einen Kontextmenüeintrag, der mit einem Plugin-Befehl verknüpft ist. Registrieren Sie zuerst den Befehl. Als Beschriftung wird standardmäßig der registrierte Name des Befehls verwendet, ersatzweise seine ID; bei ausgelassenem type gilt Request. leadingIcon wird von der Host-Bridge nicht ausgewertet.

Hilfsfunktionen für das Farbschema

Das injizierte SDK stellt außerdem sdk.theme.get() und sdk.theme.onChange(callback) bereit. Diese lesen das Farbschema des Iframes und abonnieren Änderungen des Host-Farbschemas, ohne einen separaten Daten-Bridge-Befehl zu verwenden. Nutzen Sie sie, um die Plugin-Oberfläche an Ogmas helles bzw. dunkles Erscheinungsbild anzupassen.

---

Fehlercodes

Code	Bedeutung
PERMISSION_DENIED	Dem Plugin fehlt die erforderliche Berechtigung.
PLUGIN_DISABLED	Das Plugin ist derzeit nicht aktiviert.
UNKNOWN_COMMAND	Der Befehl ist nicht in der Liste unterstützter Befehle enthalten.
INVALID_PAYLOAD	Ein erforderliches Payload-Feld fehlt oder hat den falschen Typ.
NOT_FOUND	Die angeforderte Ressource existiert nicht.
LIMIT_EXCEEDED	Eine Mengenbegrenzung pro Plugin wurde erreicht (z. B. für Seitenleisteneinträge).
SERVER_ERROR	Interner Fehler. Prüfen Sie die Plugin-Protokolle.

---

Liste unterstützter Befehle

ogma.meta.get, ogma.log, ogma.ui.resize, ogma.ui.sidebar.registerItem, ogma.requests.get, ogma.requests.getRaw, ogma.requests.search, ogma.findings.list, ogma.scope.getActive, ogma.projects.getCurrent, ogma.backend.call, ogma.backend.onEvent, ogma.events.poll, ogma.navigation.addPage, ogma.window.showToast, ogma.commands.register, ogma.menu.registerItem.