---
url: https://docs.ogmabox.com/de/plugins/frontend-sdk.md
description: >-
  Referenz für Ogmas Frontend-Plugin-APIs, Iframe-Integration, Bridge-Aufrufe,
  UI-Panels, Befehle und Host-Kommunikation.
---

# Referenz des Plugin-Frontend-SDKs {#plugin-frontend-sdk-reference}

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](./README.md).

***

## Sicherheitsmodell {#security-model}

| 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 {#bridge-protocol}

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 {#request-envelope}

```ts
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 {#response-envelope}

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

### Verwendung des SDKs (empfohlen) {#using-the-sdk-recommended}

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

```js
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 {#command-reference}

### `ogma.meta.get` {#ogma-meta-get}

Keine Payload erforderlich.

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

### `ogma.requests.get` {#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` {#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` {#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` {#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` {#ogma-scope-getactive}

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

Erfordert: `read_scope` (automatisch erteilt).

### `ogma.projects.getCurrent` {#ogma-projects-getcurrent}

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

Erfordert: `read_projects` (automatisch erteilt).

### `ogma.log` {#ogma-log}

Payload: `{ message: string }`

Schreibt in den Protokollpuffer des Plugins.

### `ogma.ui.resize` {#ogma-ui-resize}

Payload: `{ height: number }` (maximal 2000)

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

### `ogma.ui.sidebar.registerItem` {#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` {#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` {#ogma-backend-onevent}

Payload: keine erforderlich.

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

### `ogma.events.poll` {#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` {#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` {#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` {#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` {#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 {#theme-helpers}

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 {#error-codes}

| 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 {#supported-commands-list}

`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`.