Справочник интерфейсного SDK плагинов

Код интерфейса плагина работает в изолированном iframe. Это низкоуровневый справочник. Введение более высокого уровня см. в README.md.

Модель безопасности

Свойство	Значение
Изоляция iframe	Только `allow-scripts` (без `allow-same-origin`)
CSP `script-src`	Ограничен nonce; загружается только скрипт точки входа
CSP `connect-src`	`'self'` — плагин может отправлять POST в `/plugins/{id}/api/*` и опрашивать `/plugins/{id}/events/poll`
CSP `default-src`	`'none'`
Доступ к родительскому DOM	Заблокирован (нет `allow-same-origin`)
Cookie сессии Ogma	Недоступны плагину
Связь между плагинами	Недоступна

Вызовы моста данных авторизуются на сервере при каждом запросе; отображение и навигацию обрабатывает интерфейс хоста. Кеш разрешений вкладки используется только для отображения и не управляет доступом к данным.

Протокол моста

JavaScript плагина общается с хостом Ogma через postMessage. Хост находится в PluginsView.vue и обрабатывает сообщения bridge_request.

Оболочка запроса

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
}

Максимальный общий размер сообщения: 65 536 байт.

Оболочка ответа

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

Использование SDK (рекомендуется)

Не формируйте и не отправляйте запросы к мосту через postMessage вручную. Используйте глобальный ogmaSDK:

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

SDK оборачивает всю связь через мост и управляет сопоставлением запросов и ответов, sessionId и завершением Promise.

Справочник команд

`ogma.meta.get`

Входные данные не требуются.

Возвращает { pluginId, packageId, name, version, ogmaVersion }.

`ogma.requests.get`

Вход: { id: string }

Возвращает представление HTTP-записи. Поля: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Представление не включает заголовки и байты тела.

Требуется: read_http_history (выдаётся автоматически).

`ogma.requests.getRaw`

Вход: { id: string }. Вызывайте через sdk.requests.getRaw(id).

Возвращает requestBodyBase64, responseBodyBase64, декодированные длины (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated и maxBodyBytes. Несмотря на имя, возвращаются байты тел, а не полное сообщение в сетевом HTTP-формате. Поддерживаемые кодировки содержимого декодируются перед созданием представления. Каждое тело ограничено 256 КиБ; перед обработкой полного ресурса проверьте флаги усечения.

Требуется: read_http_history (выдаётся автоматически).

`ogma.requests.search`

Вход: { limit?: number, offset?: number, query?: string }

query поддерживает фильтры HTTPQL. Максимум limit: 20. Возвращает { items: [...], total: number, limit: number, offset: number }.

Требуется: read_http_history (выдаётся автоматически).

`ogma.findings.list`

Вход: { limit?: number, offset?: number }

Возвращает { items: [...], total: number, limit: number, offset: number }, не более 20 результатов проверки безопасности на страницу. Элементы — сводки; поля включают id, title, severity, status, reporter, tags и created_at.

Требуется: read_findings (выдаётся автоматически).

`ogma.scope.getActive`

Без входных данных. Возвращает активный набор области или null.

Требуется: read_scope (выдаётся автоматически).

`ogma.projects.getCurrent`

Без входных данных. Возвращает { id, name, status } или null.

Требуется: read_projects (выдаётся автоматически).

`ogma.log`

Вход: { message: string }

Пишет в буфер журнала плагина.

`ogma.ui.resize`

Вход: { height: number } (максимум 2000)

Просит хост задать высоту iframe.

`ogma.ui.sidebar.registerItem`

Вход: { name: string, path: string } (имя до 64 символов, путь до 256)

Регистрирует навигацию внутри панели плагина. Максимум 20 элементов на плагин. Зарегистрируйте соответствующие тела страниц через sdk.navigation.addPage(path, { title, body }); выбор элемента показывает страницу внутри iframe, а не новый маршрут верхнего уровня пространства Ogma.

`ogma.backend.call`

Вход: { method: string, args: unknown[] }

Вызывает серверный RPC-обработчик, зарегистрированный через sdk.api.register(method, fn). Имя метода — до 64 символов.

Возвращает результат обработчика, сериализованный в JSON.

`ogma.backend.onEvent`

Входные данные не требуются.

Только подтверждает. Для получения событий используйте ogma.events.poll.

`ogma.events.poll`

Вход: { since: number } (индекс последнего опроса; начните с 0)

Возвращает { events: [{ event: string, args: unknown[] }], next_since: number }.

`ogma.navigation.addPage`

Вход: { path: string, title?: string }

Мост подтверждает путь страницы. Внедрённый SDK дополнительно принимает { body: HTMLElement } в параметрах sdk.navigation.addPage(path, options), прикрепляет тело внутри iframe и переключает видимость, когда хост выбирает соответствующий элемент панели. Узел DOM остаётся локальным и не сериализуется через мост.

`ogma.window.showToast`

Вход: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

Показывает уведомление в панели плагина. Длительность в мс (максимум 10000, по умолчанию 3000).

`ogma.commands.register`

Вход: { id: string, name: string }

Регистрирует команду в хранилище команд хоста. При выполнении хост отправляет в iframe сообщение plugin_command с commandId и контекстом; плагин должен предоставить соответствующий обработчик. Одна регистрация не выполняет команду.

`ogma.menu.registerItem`

Вход: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

Регистрирует пункт контекстного меню, связанный с командой плагина. Сначала зарегистрируйте команду. Подпись по умолчанию — имя команды, затем ID; без type используется Request. leadingIcon не используется мостом хоста.

Помощники темы

Внедрённый SDK также предоставляет sdk.theme.get() и sdk.theme.onChange(callback). Они читают тему iframe и подписываются на обновления хоста без отдельной команды моста данных. Используйте для соответствия интерфейса плагина светлой или тёмной теме Ogma.

Коды ошибок

Код	Значение
`PERMISSION_DENIED`	У плагина нет нужного разрешения.
`PLUGIN_DISABLED`	Плагин сейчас отключён.
`UNKNOWN_COMMAND`	Команда отсутствует в списке поддерживаемых.
`INVALID_PAYLOAD`	Обязательное поле отсутствует или имеет неверный тип.
`NOT_FOUND`	Запрошенный ресурс не существует.
`LIMIT_EXCEEDED`	Достигнут предел числа объектов плагина (например, элементов панели).
`SERVER_ERROR`	Внутренняя ошибка. Проверьте журналы.

Список поддерживаемых команд

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.

Справочник интерфейсного SDK плагинов ​

Модель безопасности ​

Протокол моста ​

Оболочка запроса ​

Оболочка ответа ​

Использование SDK (рекомендуется) ​

Справочник команд ​

ogma.meta.get ​

ogma.requests.get ​

ogma.requests.getRaw ​

ogma.requests.search ​

ogma.findings.list ​

ogma.scope.getActive ​

ogma.projects.getCurrent ​

ogma.log ​

ogma.ui.resize ​

ogma.ui.sidebar.registerItem ​

ogma.backend.call ​

ogma.backend.onEvent ​

ogma.events.poll ​

ogma.navigation.addPage ​

ogma.window.showToast ​

ogma.commands.register ​

ogma.menu.registerItem ​

Помощники темы ​

Коды ошибок ​

Список поддерживаемых команд ​

Справочник интерфейсного SDK плагинов

Модель безопасности

Протокол моста

Оболочка запроса

Оболочка ответа

Использование SDK (рекомендуется)

Справочник команд

`ogma.meta.get`

`ogma.requests.get`

`ogma.requests.getRaw`

`ogma.requests.search`

`ogma.findings.list`

`ogma.scope.getActive`

`ogma.projects.getCurrent`

`ogma.log`

`ogma.ui.resize`

`ogma.ui.sidebar.registerItem`

`ogma.backend.call`

`ogma.backend.onEvent`

`ogma.events.poll`

`ogma.navigation.addPage`

`ogma.window.showToast`

`ogma.commands.register`

`ogma.menu.registerItem`

Помощники темы

Коды ошибок

Список поддерживаемых команд