外掛前端 SDK 參考

外掛前端程式碼在沙箱 iframe 內執行。本文提供底層參考。較高層次的介紹請參閱 README.md。

---

安全模型

屬性	值
iframe 沙箱	僅允許 allow-scripts（不包含 allow-same-origin）
CSP script-src	以 nonce 控制；只載入進入點指令碼
CSP connect-src	'self'：外掛可向 /plugins/{id}/api/* 發出 POST 請求，並輪詢 /plugins/{id}/events/poll
CSP default-src	'none'
父層 DOM 存取	已封鎖（不包含 allow-same-origin）
Ogma 工作階段 Cookie	外掛無法存取
跨外掛通訊	不提供

資料橋接呼叫的每個請求都會在伺服器端進行授權；顯示與導覽操作由主應用程式 UI 處理。權限分頁顯示的權限快取僅供顯示，不會控制資料存取。

---

橋接通訊協定

外掛 JS 透過 postMessage 與 Ogma 主應用程式通訊。主應用程式端的橋接位於 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。雖然名稱包含 Raw，但此操作傳回的是本文位元組，而非完整的原始 HTTP 訊息。支援的內容編碼會在投影前解碼。每個本文上限為 256 KiB；處理完整資源前，請先檢查截斷旗標。

需要：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 }（name 最多 64 個字元，path 最多 256 個字元）

註冊外掛面板內的導覽。每個外掛最多 20 個項目。使用 sdk.navigation.addPage(path, { title, body }) 註冊相符的頁面內容；選取項目時，會在 iframe 內顯示該頁面，而不是建立新的 Ogma 頂層工作區路由。

ogma.backend.call

酬載：{ method: string, args: unknown[] }

呼叫透過 sdk.api.register(method, fn) 註冊的後端 RPC 處理函式。方法名稱長度上限為 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 }

在主應用程式的命令儲存區中註冊外掛命令。主應用程式執行命令時，會將包含 commandId 和情境資訊的 plugin_command 訊息送回 iframe；外掛必須提供對應的回呼。僅註冊不會執行命令。

ogma.menu.registerItem

酬載：{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

註冊連結至外掛命令的快顯選單項目。請先註冊命令。標籤預設使用命令註冊的名稱，若無則使用其 ID；省略 type 時預設為 Request。主應用程式橋接不會使用 leadingIcon。

佈景主題輔助函式

注入的 SDK 也提供 sdk.theme.get() 和 sdk.theme.onChange(callback)。這些函式會讀取 iframe 的佈景主題，並訂閱主應用程式的佈景主題更新，不需要獨立的資料橋接命令。使用它們可讓外掛 UI 與 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.