Referensi SDK Frontend Plugin

Kode frontend plugin berjalan di dalam iframe sandbox. Dokumen ini adalah referensi tingkat rendah. Untuk pengantar tingkat lebih tinggi, lihat README.md.

---

Model keamanan

Properti	Nilai
Sandbox iframe	Hanya allow-scripts (tanpa allow-same-origin)
CSP script-src	Dikendalikan nonce; hanya skrip titik masuk yang dimuat
CSP connect-src	'self' - plugin dapat melakukan POST ke /plugins/{id}/api/* dan polling /plugins/{id}/events/poll
CSP default-src	'none'
Akses DOM induk	Diblokir (tanpa allow-same-origin)
Cookie sesi Ogma	Tidak dapat diakses plugin
Komunikasi antarplugin	Tidak tersedia

Pemanggilan bridge data diotorisasi di sisi server pada setiap permintaan; tindakan tampilan dan navigasi ditangani UI host. Cache izin yang ditampilkan di tab Izin hanya untuk tampilan; cache ini tidak mengendalikan akses data.

---

Protokol bridge

JS plugin berkomunikasi dengan host Ogma melalui postMessage. Host berada di PluginsView.vue dan menangani pesan bridge_request.

Envelope permintaan

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
}

Ukuran total pesan maksimum: 65.536 byte.

Envelope respons

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

Menggunakan SDK (direkomendasikan)

Jangan mengirim permintaan bridge postMessage dalam bentuk mentah secara manual. Gunakan global ogmaSDK:

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

SDK membungkus seluruh komunikasi bridge dan menangani korelasi permintaan, pengelolaan sessionId, dan penyelesaian Promise.

---

Referensi perintah

ogma.meta.get

Tidak memerlukan payload.

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

ogma.requests.get

Payload: { id: string }

Mengembalikan proyeksi entri HTTP. Kolom: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Proyeksi ini tidak menyertakan header atau byte isi.

Memerlukan: read_http_history (diberikan otomatis).

ogma.requests.getRaw

Payload: { id: string }. Panggil melalui sdk.requests.getRaw(id).

Mengembalikan requestBodyBase64, responseBodyBase64, panjang hasil dekodenya (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated, dan maxBodyBytes. Meskipun namanya demikian, operasi ini mengembalikan byte isi, bukan pesan HTTP lengkap dalam format transmisi. Pengodean konten yang didukung didekode sebelum proyeksi. Setiap isi dibatasi hingga 256 KiB; periksa penanda pemotongan sebelum memproses aset lengkap.

Memerlukan: read_http_history (diberikan otomatis).

ogma.requests.search

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

query mendukung ekspresi filter HTTPQL. limit maksimum: 20. Mengembalikan { items: [...], total: number, limit: number, offset: number }.

Memerlukan: read_http_history (diberikan otomatis).

ogma.findings.list

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

Mengembalikan { items: [...], total: number, limit: number, offset: number }, dengan paling banyak 20 temuan per halaman. Item berupa ringkasan; kolom mencakup id, title, severity, status, reporter, tags, dan created_at.

Memerlukan: read_findings (diberikan otomatis).

ogma.scope.getActive

Tanpa payload. Mengembalikan prasetel cakupan aktif atau null.

Memerlukan: read_scope (diberikan otomatis).

ogma.projects.getCurrent

Tanpa payload. Mengembalikan { id, name, status } atau null.

Memerlukan: read_projects (diberikan otomatis).

ogma.log

Payload: { message: string }

Menulis ke buffer log plugin.

ogma.ui.resize

Payload: { height: number } (maksimum 2000)

Meminta host menetapkan tinggi iframe.

ogma.ui.sidebar.registerItem

Payload: { name: string, path: string } (nama maksimum 64 karakter, path maksimum 256 karakter)

Mendaftarkan navigasi dalam panel plugin. Maksimum 20 item per plugin. Daftarkan isi halaman yang sesuai dengan sdk.navigation.addPage(path, { title, body }); memilih item menampilkan halaman tersebut di dalam iframe, bukan rute ruang kerja Ogma tingkat teratas yang baru.

ogma.backend.call

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

Memanggil handler RPC backend yang didaftarkan melalui sdk.api.register(method, fn). Panjang maksimum nama metode adalah 64 karakter.

Mengembalikan apa pun yang dikembalikan handler backend, diserialisasi sebagai JSON.

ogma.backend.onEvent

Payload: tidak diperlukan.

Hanya dikonfirmasi. Gunakan ogma.events.poll untuk pengambilan peristiwa sebenarnya.

ogma.events.poll

Payload: { since: number } (indeks dari polling terakhir; mulai dari 0)

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

ogma.navigation.addPage

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

Bridge mengonfirmasi path halaman. SDK yang disisipkan juga menerima { body: HTMLElement } sebagai opsi untuk sdk.navigation.addPage(path, options), melampirkan isi di dalam iframe, dan mengganti visibilitas halaman ketika host memilih item bilah sisi yang sesuai. Simpul DOM tetap lokal; tidak diserialisasi melalui bridge.

ogma.window.showToast

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

Menampilkan toast di panel plugin. Durasi dalam ms (maksimum 10000, default 3000).

ogma.commands.register

Payload: { id: string, name: string }

Mendaftarkan perintah plugin pada store perintah host. Eksekusi host mengirim pesan plugin_command yang berisi commandId dan konteks kembali ke iframe; plugin harus menyediakan callback yang sesuai. Pendaftaran saja tidak mengeksekusi perintah.

ogma.menu.registerItem

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

Mendaftarkan item menu konteks yang terikat ke perintah plugin. Daftarkan perintah terlebih dahulu. Label secara default adalah nama perintah yang terdaftar, lalu ID-nya; type yang tidak disertakan secara default adalah Request. leadingIcon tidak digunakan oleh bridge host.

Helper Tema

SDK yang disisipkan juga menyediakan sdk.theme.get() dan sdk.theme.onChange(callback). Keduanya membaca tema iframe dan berlangganan pembaruan tema host tanpa perintah bridge data terpisah. Gunakan untuk menjaga UI plugin konsisten dengan tampilan terang/gelap Ogma.

---

Kode kesalahan

Kode	Makna
PERMISSION_DENIED	Plugin tidak memiliki izin yang diperlukan.
PLUGIN_DISABLED	Plugin saat ini tidak diaktifkan.
UNKNOWN_COMMAND	Perintah tidak ada dalam daftar yang didukung.
INVALID_PAYLOAD	Kolom payload wajib tidak ada atau memiliki tipe yang salah.
NOT_FOUND	Sumber daya yang diminta tidak ada.
LIMIT_EXCEEDED	Batas jumlah per plugin tercapai (misalnya item bilah sisi).
SERVER_ERROR	Kesalahan internal. Periksa log plugin.

---

Daftar perintah yang didukung

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.