Referencia del SDK de frontend para plugins
El código de frontend de los plugins se ejecuta en un iframe con aislamiento de sandbox. Este documento es la referencia de bajo nivel. Para una introducción de alto nivel, consulta README.md.
Modelo de seguridad
| Propiedad | Valor |
|---|---|
| Sandbox del iframe | Solo allow-scripts (sin allow-same-origin) |
CSP script-src | Restringida mediante nonce; solo se carga el script del punto de entrada |
CSP connect-src | 'self' - el plugin puede enviar POST a /plugins/{id}/api/* y consultar periódicamente /plugins/{id}/events/poll |
CSP default-src | 'none' |
| Acceso al DOM de la página principal | Bloqueado (sin allow-same-origin) |
| Cookies de sesión de Ogma | Inaccesibles para el plugin |
| Comunicación entre plugins | No disponible |
Las llamadas de datos del puente se autorizan en el servidor en cada solicitud; la interfaz de la aplicación principal gestiona las acciones de visualización y navegación. La caché de permisos que aparece en la pestaña Permisos es solo informativa; no controla el acceso a los datos.
Protocolo del puente
El JavaScript del plugin se comunica con la aplicación principal de Ogma mediante postMessage. El componente principal se encuentra en PluginsView.vue y procesa mensajes bridge_request.
Sobre de solicitud
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
}Tamaño total máximo del mensaje: 65 536 bytes.
Sobre de respuesta
ts
interface BridgeResponse {
type: 'bridge_response'
requestId: string
ok: boolean
result?: unknown
error?: string
code?: string
}Uso del SDK (recomendado)
No envíes manualmente solicitudes sin procesar al puente mediante postMessage. Utiliza el objeto global ogmaSDK:
js
ogmaSDK.ready(function(sdk) {
sdk.meta.get().then(function(meta) {
sdk.log.info("running as " + meta.pluginId);
});
});El SDK encapsula toda la comunicación del puente y gestiona la correlación de solicitudes, la gestión de sessionId y la resolución de promesas.
Referencia de comandos
ogma.meta.get
No se requiere carga útil.
Devuelve { pluginId, packageId, name, version, ogmaVersion }.
ogma.requests.get
Carga útil: { id: string }
Devuelve una entrada HTTP proyectada. Campos: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Esta proyección no incluye cabeceras ni bytes del cuerpo.
Requiere: read_http_history (concedido automáticamente).
ogma.requests.getRaw
Carga útil: { id: string }. Llámalo mediante sdk.requests.getRaw(id).
Devuelve requestBodyBase64, responseBodyBase64, sus longitudes decodificadas (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated y maxBodyBytes. A pesar del nombre, esta operación devuelve los bytes del cuerpo, no un mensaje HTTP completo sin procesar. Las codificaciones de contenido compatibles se decodifican antes de la proyección. Cada cuerpo se limita a 256 KiB; comprueba los indicadores de truncamiento antes de procesar un recurso completo.
Requiere: read_http_history (concedido automáticamente).
ogma.requests.search
Carga útil: { limit?: number, offset?: number, query?: string }
query admite expresiones de filtro HTTPQL. Valor máximo de limit: 20. Devuelve { items: [...], total: number, limit: number, offset: number }.
Requiere: read_http_history (concedido automáticamente).
ogma.findings.list
Carga útil: { limit?: number, offset?: number }
Devuelve { items: [...], total: number, limit: number, offset: number }, con un máximo de 20 hallazgos por página. Los elementos son resúmenes; sus campos incluyen id, title, severity, status, reporter, tags y created_at.
Requiere: read_findings (concedido automáticamente).
ogma.scope.getActive
Sin carga útil. Devuelve el ajuste predefinido de alcance activo o null.
Requiere: read_scope (concedido automáticamente).
ogma.projects.getCurrent
Sin carga útil. Devuelve { id, name, status } o null.
Requiere: read_projects (concedido automáticamente).
ogma.log
Carga útil: { message: string }
Escribe en el búfer de registros del plugin.
ogma.ui.resize
Carga útil: { height: number } (máximo 2000)
Solicita a la aplicación principal que establezca la altura del iframe.
ogma.ui.sidebar.registerItem
Carga útil: { name: string, path: string } (nombre de hasta 64 caracteres, ruta de hasta 256 caracteres)
Registra la navegación dentro del panel del plugin. Máximo de 20 elementos por plugin. Registra los cuerpos de las páginas correspondientes con sdk.navigation.addPage(path, { title, body }); al seleccionar el elemento se muestra esa página dentro del iframe, no una nueva ruta de nivel superior del espacio de trabajo de Ogma.
ogma.backend.call
Carga útil: { method: string, args: unknown[] }
Llama a un manejador RPC del backend registrado mediante sdk.api.register(method, fn). La longitud máxima del nombre del método es de 64 caracteres.
Devuelve lo que haya devuelto el manejador del backend, serializado como JSON.
ogma.backend.onEvent
Carga útil: no se requiere.
Solo se confirma la recepción. Utiliza ogma.events.poll para obtener realmente los eventos.
ogma.events.poll
Carga útil: { since: number } (índice de la última consulta; comienza en 0)
Devuelve { events: [{ event: string, args: unknown[] }], next_since: number }.
ogma.navigation.addPage
Carga útil: { path: string, title?: string }
El puente confirma la recepción de la ruta de la página. El SDK inyectado también acepta { body: HTMLElement } como opción de sdk.navigation.addPage(path, options), incorpora el cuerpo dentro del iframe y cambia la visibilidad de la página cuando la aplicación principal selecciona el elemento correspondiente de la barra lateral. El nodo DOM permanece local; no se serializa a través del puente.
ogma.window.showToast
Carga útil: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }
Muestra una notificación emergente en el panel del plugin. Duración en ms (máximo 10000, valor predeterminado 3000).
ogma.commands.register
Carga útil: { id: string, name: string }
Registra el comando del plugin en el almacén de comandos de la aplicación principal. La ejecución desde la aplicación principal envía al iframe un mensaje plugin_command que contiene commandId y el contexto; el plugin debe proporcionar el callback correspondiente. El registro por sí solo no ejecuta el comando.
ogma.menu.registerItem
Carga útil: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }
Registra un elemento de menú contextual vinculado a un comando del plugin. Registra primero el comando. La etiqueta toma por defecto el nombre registrado del comando y, en su defecto, su ID; si se omite type, se utiliza Request. El puente de la aplicación principal no utiliza leadingIcon.
Utilidades de tema
El SDK inyectado también proporciona sdk.theme.get() y sdk.theme.onChange(callback). Estas funciones leen el tema del iframe y se suscriben a las actualizaciones del tema de la aplicación principal sin un comando de datos del puente independiente. Utilízalas para mantener la interfaz del plugin coherente con la apariencia clara u oscura de Ogma.
Códigos de error
| Código | Significado |
|---|---|
PERMISSION_DENIED | El plugin no tiene el permiso necesario. |
PLUGIN_DISABLED | El plugin no está habilitado actualmente. |
UNKNOWN_COMMAND | El comando no figura en la lista de comandos compatibles. |
INVALID_PAYLOAD | Falta un campo obligatorio de la carga útil o tiene un tipo incorrecto. |
NOT_FOUND | El recurso solicitado no existe. |
LIMIT_EXCEEDED | Se ha alcanzado un límite de cantidad por plugin (por ejemplo, de elementos de la barra lateral). |
SERVER_ERROR | Error interno. Revisa los registros del plugin. |
Lista de comandos compatibles
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.