Naslagwerk voor de frontend-SDK van plugins

De frontendcode van plugins wordt uitgevoerd in een afgeschermd iframe. Dit document is het naslagwerk op laag niveau. Zie README.md voor een inleiding op hoger niveau.

---

Beveiligingsmodel

Eigenschap	Waarde
Iframe-sandbox	Alleen allow-scripts (geen allow-same-origin)
CSP script-src	Afgeschermd met een nonce; alleen het toegangspuntscript wordt geladen
CSP connect-src	'self' - de plugin kan POST-verzoeken versturen naar /plugins/{id}/api/* en /plugins/{id}/events/poll pollen
CSP default-src	'none'
Toegang tot de bovenliggende DOM	Geblokkeerd (geen allow-same-origin)
Ogma-sessiecookies	Niet toegankelijk voor de plugin
Communicatie tussen plugins	Niet beschikbaar

Aanroepen via de gegevensbridge worden bij elk verzoek aan de serverzijde geautoriseerd; weergave- en navigatieacties worden door de hostinterface afgehandeld. De machtigingscache op het tabblad Rechten dient alleen voor weergave en wordt niet gebruikt om toegang tot gegevens te controleren.

---

Bridgeprotocol

JavaScript van plugins communiceert met de Ogma-host via postMessage. De host bevindt zich in PluginsView.vue en verwerkt bridge_request-berichten.

Verzoekenvelop

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 totale berichtgrootte: 65 536 bytes.

Responsenvelop

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

De SDK gebruiken (aanbevolen)

Verstuur geen ruwe postMessage-bridgeverzoeken handmatig. Gebruik de globale variabele ogmaSDK:

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

De SDK omvat alle bridgecommunicatie en verzorgt verzoekcorrelatie, sessionId-beheer en het afhandelen van Promises.

---

Naslagwerk voor opdrachten

ogma.meta.get

Geen payload vereist.

Retourneert { pluginId, packageId, name, version, ogmaVersion }.

ogma.requests.get

Payload: { id: string }

Retourneert een projectie van een HTTP-item. Velden: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Deze projectie bevat geen headers of bodybytes.

Vereist: read_http_history (automatisch verleend).

ogma.requests.getRaw

Payload: { id: string }. Roep dit aan via sdk.requests.getRaw(id).

Retourneert requestBodyBase64, responseBodyBase64, hun gedecodeerde lengtes (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated en maxBodyBytes. Ondanks de naam retourneert deze bewerking bodybytes, geen volledig ruw HTTP-bericht. Ondersteunde inhoudscoderingen worden vóór de projectie gedecodeerd. Elke body is beperkt tot 256 KiB; controleer de afkappingsindicatoren voordat je een volledige asset verwerkt.

Vereist: read_http_history (automatisch verleend).

ogma.requests.search

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

query ondersteunt HTTPQL-filterexpressies. Maximale limit: 20. Retourneert { items: [...], total: number, limit: number, offset: number }.

Vereist: read_http_history (automatisch verleend).

ogma.findings.list

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

Retourneert { items: [...], total: number, limit: number, offset: number }, met maximaal 20 bevindingen per pagina. De items zijn samenvattingen; de velden omvatten id, title, severity, status, reporter, tags en created_at.

Vereist: read_findings (automatisch verleend).

ogma.scope.getActive

Geen payload. Retourneert de actieve scopevoorinstelling of null.

Vereist: read_scope (automatisch verleend).

ogma.projects.getCurrent

Geen payload. Retourneert { id, name, status } of null.

Vereist: read_projects (automatisch verleend).

ogma.log

Payload: { message: string }

Schrijft naar de logbuffer van de plugin.

ogma.ui.resize

Payload: { height: number } (maximaal 2000)

Verzoekt de host om de hoogte van het iframe in te stellen.

ogma.ui.sidebar.registerItem

Payload: { name: string, path: string } (naam maximaal 64 tekens, pad maximaal 256 tekens)

Registreert navigatie binnen het pluginpaneel. Maximaal 20 items per plugin. Registreer bijbehorende pagina-inhoud met sdk.navigation.addPage(path, { title, body }); wanneer je het item kiest, wordt die pagina binnen het iframe getoond, niet als een nieuwe Ogma-werkruimteroute op het hoogste niveau.

ogma.backend.call

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

Roept een backend-RPC-handler aan die is geregistreerd via sdk.api.register(method, fn). De methodenaam mag maximaal 64 tekens lang zijn.

Retourneert de waarde die de backendhandler heeft geretourneerd, geserialiseerd als JSON.

ogma.backend.onEvent

Payload: niet vereist.

Wordt alleen bevestigd. Gebruik ogma.events.poll om daadwerkelijk gebeurtenissen op te halen.

ogma.events.poll

Payload: { since: number } (index van de laatste poll; begin bij 0)

Retourneert { events: [{ event: string, args: unknown[] }], next_since: number }.

ogma.navigation.addPage

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

De bridge bevestigt het paginapad. De geïnjecteerde SDK accepteert daarnaast { body: HTMLElement } als optie voor sdk.navigation.addPage(path, options), voegt de inhoud binnen het iframe toe en schakelt de zichtbaarheid van pagina's om wanneer de host het bijbehorende zijbalkitem selecteert. De DOM-node blijft lokaal en wordt niet via de bridge geserialiseerd.

ogma.window.showToast

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

Toont een toastmelding in het pluginpaneel. Duur in ms (maximaal 10000, standaard 3000).

ogma.commands.register

Payload: { id: string, name: string }

Registreert de pluginopdracht in de opdrachtenstore van de host. Bij uitvoering door de host wordt een plugin_command-bericht met commandId en context teruggestuurd naar het iframe; de plugin moet de bijbehorende callback leveren. Registratie alleen voert de opdracht niet uit.

ogma.menu.registerItem

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

Registreert een contextmenu-item dat aan een pluginopdracht is gekoppeld. Registreer eerst de opdracht. Het label gebruikt standaard de geregistreerde naam van de opdracht en valt terug op de ID als er geen naam beschikbaar is; als type wordt weggelaten, is de standaardwaarde Request. leadingIcon wordt niet gebruikt door de hostbridge.

Themahulpfuncties

De geïnjecteerde SDK biedt ook sdk.theme.get() en sdk.theme.onChange(callback). Deze lezen het iframe-thema en abonneren zich op themawijzigingen van de host zonder een afzonderlijke gegevensbridgeopdracht. Gebruik ze om de plugininterface af te stemmen op de lichte of donkere weergave van Ogma.

---

Foutcodes

Code	Betekenis
PERMISSION_DENIED	De plugin heeft niet de vereiste machtiging.
PLUGIN_DISABLED	De plugin is momenteel niet ingeschakeld.
UNKNOWN_COMMAND	De opdracht staat niet in de lijst met ondersteunde opdrachten.
INVALID_PAYLOAD	Een verplicht payloadveld ontbreekt of heeft het verkeerde type.
NOT_FOUND	De opgevraagde resource bestaat niet.
LIMIT_EXCEEDED	Een aantalslimiet per plugin is bereikt (bijvoorbeeld voor zijbalkitems).
SERVER_ERROR	Interne fout. Controleer de pluginlogs.

---

Lijst met ondersteunde opdrachten

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.