Dokumentacja referencyjna SDK frontendu wtyczek

Kod frontendu wtyczki działa w izolowanej ramce iframe. Ten dokument stanowi dokumentację niskiego poziomu. Wprowadzenie na wyższym poziomie znajdziesz w README.md.

---

Model bezpieczeństwa

Właściwość	Wartość
Piaskownica iframe	Tylko allow-scripts (bez allow-same-origin)
CSP script-src	Wymaga nonce; ładowany jest tylko skrypt punktu wejścia
CSP connect-src	'self' — wtyczka może wysyłać POST do /plugins/{id}/api/* i odpytywać /plugins/{id}/events/poll
CSP default-src	'none'
Dostęp do nadrzędnego DOM	Zablokowany (brak allow-same-origin)
Ciasteczka sesji Ogma	Niedostępne dla wtyczki
Komunikacja między wtyczkami	Niedostępna

Wywołania mostu dotyczące danych są autoryzowane po stronie serwera przy każdym żądaniu; operacje wyświetlania i nawigacji obsługuje interfejs hosta. Pamięć podręczna uprawnień widoczna na karcie Uprawnienia służy wyłącznie do prezentacji; nie kontroluje dostępu do danych.

---

Protokół mostu

Kod JS wtyczki komunikuje się z hostem Ogma przez postMessage. Host znajduje się w PluginsView.vue i obsługuje komunikaty bridge_request.

Struktura żądania

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
}

Maksymalny łączny rozmiar komunikatu: 65 536 bajtów.

Struktura odpowiedzi

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

Korzystanie z SDK (zalecane)

Nie wysyłaj ręcznie surowych żądań mostu postMessage. Używaj globalnego obiektu ogmaSDK:

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

SDK obsługuje całą komunikację przez most, w tym korelację żądań, zarządzanie sessionId i rozstrzyganie obiektów Promise.

---

Dokumentacja poleceń

ogma.meta.get

Nie wymaga danych wejściowych.

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

ogma.requests.get

Dane wejściowe: { id: string }

Zwraca projekcję wpisu HTTP. Pola: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Ta projekcja nie zawiera nagłówków ani bajtów treści.

Wymaga: read_http_history (przyznawane automatycznie).

ogma.requests.getRaw

Dane wejściowe: { id: string }. Wywołuj przez sdk.requests.getRaw(id).

Zwraca requestBodyBase64, responseBodyBase64, długości po dekodowaniu (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated i maxBodyBytes. Mimo nazwy ta operacja zwraca bajty treści, a nie pełną surową wiadomość HTTP. Obsługiwane kodowania treści są dekodowane przed utworzeniem projekcji. Każda treść jest ograniczona do 256 KiB; przed przetwarzaniem kompletnego zasobu sprawdź flagi obcięcia.

Wymaga: read_http_history (przyznawane automatycznie).

ogma.requests.search

Dane wejściowe: { limit?: number, offset?: number, query?: string }

query obsługuje wyrażenia filtrów HTTPQL. Maksymalny limit: 20. Zwraca { items: [...], total: number, limit: number, offset: number }.

Wymaga: read_http_history (przyznawane automatycznie).

ogma.findings.list

Dane wejściowe: { limit?: number, offset?: number }

Zwraca { items: [...], total: number, limit: number, offset: number }, z maksymalnie 20 ustaleniami na stronę. Elementy są podsumowaniami; pola obejmują id, title, severity, status, reporter, tags i created_at.

Wymaga: read_findings (przyznawane automatycznie).

ogma.scope.getActive

Bez danych wejściowych. Zwraca aktywną zapisaną konfigurację zakresu testów lub null.

Wymaga: read_scope (przyznawane automatycznie).

ogma.projects.getCurrent

Bez danych wejściowych. Zwraca { id, name, status } lub null.

Wymaga: read_projects (przyznawane automatycznie).

ogma.log

Dane wejściowe: { message: string }

Zapisuje do bufora dziennika wtyczki.

ogma.ui.resize

Dane wejściowe: { height: number } (maksymalnie 2000)

Żąda od hosta ustawienia wysokości ramki iframe.

ogma.ui.sidebar.registerItem

Dane wejściowe: { name: string, path: string } (nazwa do 64 znaków, ścieżka do 256 znaków)

Rejestruje nawigację wewnątrz panelu wtyczki. Maksymalnie 20 pozycji na wtyczkę. Zarejestruj odpowiadające im treści stron przez sdk.navigation.addPage(path, { title, body }); wybranie pozycji wyświetla tę stronę wewnątrz ramki iframe, a nie nową trasę na głównym poziomie obszaru roboczego Ogma.

ogma.backend.call

Dane wejściowe: { method: string, args: unknown[] }

Wywołuje procedurę obsługi RPC backendu zarejestrowaną przez sdk.api.register(method, fn). Maksymalna długość nazwy metody wynosi 64 znaki.

Zwraca wartość zwróconą przez procedurę obsługi backendu, zserializowaną do JSON.

ogma.backend.onEvent

Dane wejściowe: niewymagane.

Wyłącznie potwierdza wywołanie. Do faktycznego pobierania zdarzeń używaj ogma.events.poll.

ogma.events.poll

Dane wejściowe: { since: number } (indeks z ostatniego odpytania; zacznij od 0)

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

ogma.navigation.addPage

Dane wejściowe: { path: string, title?: string }

Most potwierdza ścieżkę strony. Wstrzyknięte SDK dodatkowo przyjmuje { body: HTMLElement } jako opcję w sdk.navigation.addPage(path, options), dołącza treść wewnątrz ramki iframe i przełącza widoczność stron, gdy host wybierze odpowiadającą im pozycję paska bocznego. Węzeł DOM pozostaje lokalny; nie jest serializowany i przesyłany przez most.

ogma.window.showToast

Dane wejściowe: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

Wyświetla krótkie powiadomienie w panelu wtyczki. Czas trwania w ms (maksymalnie 10000, domyślnie 3000).

ogma.commands.register

Dane wejściowe: { id: string, name: string }

Rejestruje polecenie wtyczki w magazynie poleceń hosta. Wykonanie przez hosta wysyła z powrotem do ramki iframe komunikat plugin_command zawierający commandId i kontekst; wtyczka musi zapewnić odpowiadającą mu funkcję zwrotną. Sama rejestracja nie wykonuje polecenia.

ogma.menu.registerItem

Dane wejściowe: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

Rejestruje pozycję menu kontekstowego powiązaną z poleceniem wtyczki. Najpierw zarejestruj polecenie. Domyślną etykietą jest zarejestrowana nazwa polecenia, a w razie jej braku — jego identyfikator; pominięte type ma domyślną wartość Request. Most hosta nie wykorzystuje leadingIcon.

Funkcje pomocnicze motywu

Wstrzyknięte SDK udostępnia również sdk.theme.get() i sdk.theme.onChange(callback). Odczytują one motyw ramki iframe i subskrybują aktualizacje motywu hosta bez osobnego polecenia mostu danych. Używaj ich, aby interfejs wtyczki był spójny z jasnym lub ciemnym wyglądem Ogma.

---

Kody błędów

Kod	Znaczenie
PERMISSION_DENIED	Wtyczka nie ma wymaganego uprawnienia.
PLUGIN_DISABLED	Wtyczka nie jest obecnie włączona.
UNKNOWN_COMMAND	Polecenie nie znajduje się na liście obsługiwanych.
INVALID_PAYLOAD	Brakuje wymaganego pola danych wejściowych lub ma ono niewłaściwy typ.
NOT_FOUND	Żądany zasób nie istnieje.
LIMIT_EXCEEDED	Osiągnięto limit liczby elementów na wtyczkę (np. pozycji paska bocznego).
SERVER_ERROR	Błąd wewnętrzny. Sprawdź dzienniki wtyczki.

---

Lista obsługiwanych poleceń

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.