Riferimento dell’SDK frontend per i plugin

Il codice frontend dei plugin viene eseguito in un iframe con isolamento sandbox. Questo documento è il riferimento di basso livello. Per un’introduzione di livello superiore, consulta README.md.

---

Modello di sicurezza

Proprietà	Valore
Sandbox dell’iframe	Solo allow-scripts (senza allow-same-origin)
CSP script-src	Vincolata a un nonce; viene caricato solo lo script del punto di ingresso
CSP connect-src	'self' - il plugin può inviare POST a /plugins/{id}/api/* e interrogare periodicamente /plugins/{id}/events/poll
CSP default-src	'none'
Accesso al DOM della pagina principale	Bloccato (senza allow-same-origin)
Cookie di sessione Ogma	Inaccessibili al plugin
Comunicazione tra plugin	Non disponibile

Le chiamate dati del bridge vengono autorizzate sul server a ogni richiesta; le azioni di visualizzazione e navigazione vengono gestite dall’interfaccia dell’applicazione principale. La cache delle autorizzazioni mostrata nella scheda Autorizzazioni è solo informativa; non controlla l’accesso ai dati.

---

Protocollo del bridge

Il JavaScript del plugin comunica con l’applicazione principale Ogma tramite postMessage. Il componente principale si trova in PluginsView.vue e gestisce i messaggi bridge_request.

Struttura della richiesta

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
}

Dimensione totale massima del messaggio: 65 536 byte.

Struttura della risposta

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

Uso dell’SDK (consigliato)

Non inviare manualmente richieste grezze al bridge tramite postMessage. Usa l’oggetto globale ogmaSDK:

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

L’SDK incapsula tutta la comunicazione del bridge e gestisce la correlazione delle richieste, la gestione di sessionId e la risoluzione delle promesse.

---

Riferimento dei comandi

ogma.meta.get

Non è richiesto alcun payload.

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

ogma.requests.get

Payload: { id: string }

Restituisce una voce HTTP proiettata. Campi: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Questa proiezione non include intestazioni o byte del corpo.

Richiede: read_http_history (concessa automaticamente).

ogma.requests.getRaw

Payload: { id: string }. Effettua la chiamata tramite sdk.requests.getRaw(id).

Restituisce requestBodyBase64, responseBodyBase64, le loro lunghezze decodificate (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated e maxBodyBytes. Nonostante il nome, questa operazione restituisce i byte del corpo, non un messaggio HTTP grezzo completo. Le codifiche del contenuto supportate vengono decodificate prima della proiezione. Ogni corpo è limitato a 256 KiB; verifica gli indicatori di troncamento prima di elaborare una risorsa completa.

Richiede: read_http_history (concessa automaticamente).

ogma.requests.search

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

query supporta espressioni di filtro HTTPQL. Valore massimo di limit: 20. Restituisce { items: [...], total: number, limit: number, offset: number }.

Richiede: read_http_history (concessa automaticamente).

ogma.findings.list

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

Restituisce { items: [...], total: number, limit: number, offset: number }, con al massimo 20 rilievi di sicurezza per pagina. Gli elementi sono riepiloghi; i campi includono id, title, severity, status, reporter, tags e created_at.

Richiede: read_findings (concessa automaticamente).

ogma.scope.getActive

Nessun payload. Restituisce la preimpostazione di ambito attiva o null.

Richiede: read_scope (concessa automaticamente).

ogma.projects.getCurrent

Nessun payload. Restituisce { id, name, status } o null.

Richiede: read_projects (concessa automaticamente).

ogma.log

Payload: { message: string }

Scrive nel buffer dei log del plugin.

ogma.ui.resize

Payload: { height: number } (massimo 2000)

Richiede all’applicazione principale di impostare l’altezza dell’iframe.

ogma.ui.sidebar.registerItem

Payload: { name: string, path: string } (nome massimo di 64 caratteri, percorso massimo di 256 caratteri)

Registra la navigazione all’interno del pannello del plugin. Massimo 20 elementi per plugin. Registra i corpi delle pagine corrispondenti con sdk.navigation.addPage(path, { title, body }); scegliendo l’elemento, quella pagina viene visualizzata nell’iframe, non come nuova rotta di livello superiore dell’area di lavoro Ogma.

ogma.backend.call

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

Chiama un gestore RPC backend registrato tramite sdk.api.register(method, fn). La lunghezza massima del nome del metodo è di 64 caratteri.

Restituisce ciò che il gestore backend ha restituito, serializzato come JSON.

ogma.backend.onEvent

Payload: non richiesto.

Viene solo confermata la ricezione. Usa ogma.events.poll per recuperare effettivamente gli eventi.

ogma.events.poll

Payload: { since: number } (indice dell’ultima interrogazione; inizia da 0)

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

ogma.navigation.addPage

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

Il bridge conferma la ricezione del percorso della pagina. L’SDK iniettato accetta anche { body: HTMLElement } come opzione di sdk.navigation.addPage(path, options), inserisce il corpo nell’iframe e cambia la visibilità della pagina quando l’applicazione principale seleziona l’elemento corrispondente della barra laterale. Il nodo DOM resta locale; non viene serializzato tramite il bridge.

ogma.window.showToast

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

Mostra una notifica temporanea nel pannello del plugin. Durata in ms (massimo 10000, valore predefinito 3000).

ogma.commands.register

Payload: { id: string, name: string }

Registra il comando del plugin nello store dei comandi dell’applicazione principale. L’esecuzione da parte dell’applicazione principale invia all’iframe un messaggio plugin_command contenente commandId e il contesto; il plugin deve fornire il callback corrispondente. La sola registrazione non esegue il comando.

ogma.menu.registerItem

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

Registra una voce del menu contestuale collegata a un comando del plugin. Registra prima il comando. L’etichetta usa per impostazione predefinita il nome registrato del comando e, in sua assenza, il suo ID; se type viene omesso, il valore predefinito è Request. Il bridge dell’applicazione principale non utilizza leadingIcon.

Funzioni di supporto per il tema

L’SDK iniettato offre anche sdk.theme.get() e sdk.theme.onChange(callback). Queste funzioni leggono il tema dell’iframe e si iscrivono agli aggiornamenti del tema dell’applicazione principale senza un comando dati del bridge separato. Usale per mantenere l’interfaccia del plugin coerente con l’aspetto chiaro/scuro di Ogma.

---

Codici di errore

Codice	Significato
PERMISSION_DENIED	Il plugin non dispone dell’autorizzazione richiesta.
PLUGIN_DISABLED	Il plugin non è attualmente abilitato.
UNKNOWN_COMMAND	Il comando non è nell’elenco di quelli supportati.
INVALID_PAYLOAD	Un campo obbligatorio del payload manca o ha un tipo errato.
NOT_FOUND	La risorsa richiesta non esiste.
LIMIT_EXCEEDED	È stato raggiunto un limite di quantità per plugin (ad esempio, per le voci della barra laterale).
SERVER_ERROR	Errore interno. Controlla i log del plugin.

---

Elenco dei comandi supportati

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.