Referência do SDK de frontend para plugins

O código de frontend dos plugins é executado em um iframe com isolamento de sandbox. Este documento é a referência de baixo nível. Para uma introdução de alto nível, consulte README.md.

---

Modelo de segurança

Propriedade	Valor
Sandbox do iframe	Somente allow-scripts (sem allow-same-origin)
CSP script-src	Restringida por nonce; somente o script do ponto de entrada é carregado
CSP connect-src	'self' - o plugin pode enviar POST para /plugins/{id}/api/* e consultar periodicamente /plugins/{id}/events/poll
CSP default-src	'none'
Acesso ao DOM da página principal	Bloqueado (sem allow-same-origin)
Cookies de sessão do Ogma	Inacessíveis ao plugin
Comunicação entre plugins	Não disponível

As chamadas de dados da ponte são autorizadas no servidor a cada requisição; a interface do aplicativo principal trata as ações de exibição e navegação. O cache de permissões mostrado na aba Permissões é apenas informativo; ele não controla o acesso aos dados.

---

Protocolo da ponte

O JavaScript do plugin se comunica com o aplicativo principal do Ogma por postMessage. O componente principal fica em PluginsView.vue e trata mensagens bridge_request.

Envelope de requisição

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
}

Tamanho total máximo da mensagem: 65 536 bytes.

Envelope de resposta

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

Uso do SDK (recomendado)

Não envie manualmente requisições brutas à ponte por postMessage. Use o objeto global ogmaSDK:

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

O SDK encapsula toda a comunicação da ponte e trata a correlação de requisições, o gerenciamento de sessionId e a resolução de promessas.

---

Referência de comandos

ogma.meta.get

Não é necessário payload.

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

ogma.requests.get

Payload: { id: string }

Retorna uma entrada HTTP projetada. Campos: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Essa projeção não inclui cabeçalhos nem bytes do corpo.

Exige: read_http_history (concedida automaticamente).

ogma.requests.getRaw

Payload: { id: string }. Faça a chamada por sdk.requests.getRaw(id).

Retorna requestBodyBase64, responseBodyBase64, seus comprimentos decodificados (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated e maxBodyBytes. Apesar do nome, essa operação retorna bytes do corpo, não uma mensagem HTTP bruta completa. As codificações de conteúdo compatíveis são decodificadas antes da projeção. Cada corpo é limitado a 256 KiB; verifique os indicadores de truncamento antes de processar um recurso completo.

Exige: read_http_history (concedida automaticamente).

ogma.requests.search

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

query aceita expressões de filtro HTTPQL. Valor máximo de limit: 20. Retorna { items: [...], total: number, limit: number, offset: number }.

Exige: read_http_history (concedida automaticamente).

ogma.findings.list

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

Retorna { items: [...], total: number, limit: number, offset: number }, com no máximo 20 achados por página. Os itens são resumos; os campos incluem id, title, severity, status, reporter, tags e created_at.

Exige: read_findings (concedida automaticamente).

ogma.scope.getActive

Sem payload. Retorna a predefinição de escopo ativa ou null.

Exige: read_scope (concedida automaticamente).

ogma.projects.getCurrent

Sem payload. Retorna { id, name, status } ou null.

Exige: read_projects (concedida automaticamente).

ogma.log

Payload: { message: string }

Grava no buffer de logs do plugin.

ogma.ui.resize

Payload: { height: number } (máximo 2000)

Solicita ao aplicativo principal que defina a altura do iframe.

ogma.ui.sidebar.registerItem

Payload: { name: string, path: string } (nome de até 64 caracteres, caminho de até 256 caracteres)

Registra a navegação dentro do painel do plugin. Máximo de 20 itens por plugin. Registre os corpos das páginas correspondentes com sdk.navigation.addPage(path, { title, body }); escolher o item exibe essa página dentro do iframe, não uma nova rota de nível superior do espaço de trabalho do Ogma.

ogma.backend.call

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

Chama um handler RPC do backend registrado por sdk.api.register(method, fn). O comprimento máximo do nome do método é de 64 caracteres.

Retorna o que o handler do backend tiver retornado, serializado como JSON.

ogma.backend.onEvent

Payload: não é necessário.

Apenas confirma o recebimento. Use ogma.events.poll para obter os eventos de fato.

ogma.events.poll

Payload: { since: number } (índice da última consulta; comece em 0)

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

ogma.navigation.addPage

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

A ponte confirma o recebimento do caminho da página. O SDK injetado também aceita { body: HTMLElement } como opção de sdk.navigation.addPage(path, options), insere o corpo dentro do iframe e alterna a visibilidade da página quando o aplicativo principal seleciona o item correspondente da barra lateral. O nó DOM permanece local; ele não é serializado pela ponte.

ogma.window.showToast

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

Exibe uma notificação temporária no painel do plugin. Duração em ms (máximo 10000, padrão 3000).

ogma.commands.register

Payload: { id: string, name: string }

Registra o comando do plugin no store de comandos do aplicativo principal. A execução pelo aplicativo principal envia de volta ao iframe uma mensagem plugin_command com commandId e contexto; o plugin deve fornecer o callback correspondente. O registro, por si só, não executa o comando.

ogma.menu.registerItem

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

Registra um item de menu de contexto vinculado a um comando do plugin. Registre o comando primeiro. O rótulo usa por padrão o nome registrado do comando e, na ausência dele, seu ID; se type for omitido, o padrão é Request. A ponte do aplicativo principal não utiliza leadingIcon.

Funções auxiliares de tema

O SDK injetado também oferece sdk.theme.get() e sdk.theme.onChange(callback). Essas funções leem o tema do iframe e se inscrevem nas atualizações de tema do aplicativo principal sem um comando separado de dados da ponte. Use-as para manter a interface do plugin consistente com a aparência clara/escura do Ogma.

---

Códigos de erro

Código	Significado
PERMISSION_DENIED	O plugin não tem a permissão exigida.
PLUGIN_DISABLED	O plugin não está habilitado no momento.
UNKNOWN_COMMAND	O comando não está na lista de comandos compatíveis.
INVALID_PAYLOAD	Um campo obrigatório do payload está ausente ou tem o tipo incorreto.
NOT_FOUND	O recurso solicitado não existe.
LIMIT_EXCEEDED	Um limite de quantidade por plugin foi atingido (por exemplo, de itens da barra lateral).
SERVER_ERROR	Erro interno. Verifique os logs do plugin.

---

Lista de comandos compatíveis

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.