Référence du SDK frontend des plugins

Le code frontend des plugins s'exécute dans une iframe isolée. Ce document est la référence de bas niveau. Pour une introduction plus générale, consultez README.md.

Modèle de sécurité

Propriété	Valeur
Bac à sable de l'iframe	`allow-scripts` uniquement (sans `allow-same-origin`)
CSP `script-src`	Contrôlée par un nonce ; seul le script du point d'entrée est chargé
CSP `connect-src`	`'self'` : le plugin peut effectuer des requêtes POST vers `/plugins/{id}/api/*` et interroger périodiquement `/plugins/{id}/events/poll`
CSP `default-src`	`'none'`
Accès au DOM parent	Bloqué (sans `allow-same-origin`)
Cookies de session Ogma	Inaccessibles au plugin
Communication entre plugins	Non disponible

Les appels de données à la passerelle font l'objet d'un contrôle d'autorisation côté serveur à chaque requête ; les actions d'affichage et de navigation sont prises en charge par l'interface hôte. Le cache des permissions présenté dans l'onglet Autorisations sert uniquement à l'affichage ; il ne contrôle pas l'accès aux données.

Protocole de la passerelle

Le JavaScript du plugin communique avec l'application hôte Ogma via postMessage. Le code hôte se trouve dans PluginsView.vue et traite les messages bridge_request.

Enveloppe de requête

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
}

Taille totale maximale d'un message : 65 536 octets.

Enveloppe de réponse

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

Utilisation du SDK (recommandée)

N'envoyez pas manuellement de requêtes brutes à la passerelle avec postMessage. Utilisez l'objet global ogmaSDK :

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

Le SDK encapsule toute la communication avec la passerelle et gère la corrélation des requêtes, le sessionId et la résolution des promesses.

Référence des commandes

`ogma.meta.get`

Aucune charge utile requise.

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

`ogma.requests.get`

Charge utile : { id: string }

Renvoie une entrée HTTP sous forme de projection. Champs : id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Cette projection n'inclut ni les en-têtes ni les octets du corps.

Permission requise : read_http_history (accordée automatiquement).

`ogma.requests.getRaw`

Charge utile : { id: string }. Appelez cette commande via sdk.requests.getRaw(id).

Renvoie requestBodyBase64, responseBodyBase64, leurs longueurs après décodage (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated et maxBodyBytes. Malgré son nom, cette opération renvoie les octets du corps, et non un message HTTP brut complet. Les encodages de contenu pris en charge sont décodés avant la projection. Chaque corps est limité à 256 KiB ; vérifiez les indicateurs de troncature avant de traiter une ressource complète.

Permission requise : read_http_history (accordée automatiquement).

`ogma.requests.search`

Charge utile : { limit?: number, offset?: number, query?: string }

query accepte les expressions de filtrage HTTPQL. Valeur maximale de limit : 20. Renvoie { items: [...], total: number, limit: number, offset: number }.

Permission requise : read_http_history (accordée automatiquement).

`ogma.findings.list`

Charge utile : { limit?: number, offset?: number }

Renvoie { items: [...], total: number, limit: number, offset: number }, avec au maximum 20 constats par page. Les éléments sont des résumés ; les champs comprennent id, title, severity, status, reporter, tags et created_at.

Permission requise : read_findings (accordée automatiquement).

`ogma.scope.getActive`

Aucune charge utile. Renvoie le préréglage de périmètre actif ou null.

Permission requise : read_scope (accordée automatiquement).

`ogma.projects.getCurrent`

Aucune charge utile. Renvoie { id, name, status } ou null.

Permission requise : read_projects (accordée automatiquement).

`ogma.log`

Charge utile : { message: string }

Écrit dans le tampon des journaux du plugin.

`ogma.ui.resize`

Charge utile : { height: number } (maximum : 2000)

Demande à l'application hôte de définir la hauteur de l'iframe.

`ogma.ui.sidebar.registerItem`

Charge utile : { name: string, path: string } (name : 64 caractères maximum, path : 256 caractères maximum)

Enregistre un élément de navigation dans le panneau du plugin. Maximum : 20 éléments par plugin. Enregistrez les contenus de page correspondants avec sdk.navigation.addPage(path, { title, body }) ; la sélection de l'élément affiche cette page dans l'iframe, sans créer de nouvelle route de premier niveau dans l'espace de travail Ogma.

`ogma.backend.call`

Charge utile : { method: string, args: unknown[] }

Appelle un gestionnaire RPC backend enregistré via sdk.api.register(method, fn). La longueur maximale du nom de méthode est de 64 caractères.

Renvoie la valeur retournée par le gestionnaire backend, sérialisée en JSON.

`ogma.backend.onEvent`

Charge utile : aucune requise.

Seul un accusé de réception est renvoyé. Utilisez ogma.events.poll pour récupérer effectivement les événements.

`ogma.events.poll`

Charge utile : { since: number } (indice issu de la dernière interrogation ; commencez à 0)

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

`ogma.navigation.addPage`

Charge utile : { path: string, title?: string }

La passerelle accuse réception du chemin de la page. Le SDK injecté accepte également { body: HTMLElement } comme option de sdk.navigation.addPage(path, options), attache le contenu dans l'iframe et change la page visible lorsque l'application hôte sélectionne l'élément correspondant de la barre latérale. Le nœud DOM reste local ; il n'est pas sérialisé via la passerelle.

`ogma.window.showToast`

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

Affiche une notification temporaire dans le panneau du plugin. Durée en ms (maximum : 10000, valeur par défaut : 3000).

`ogma.commands.register`

Charge utile : { id: string, name: string }

Enregistre la commande du plugin dans le store de commandes de l'application hôte. Lors de l'exécution par l'hôte, un message plugin_command contenant commandId et le contexte est renvoyé à l'iframe ; le plugin doit fournir la fonction de rappel correspondante. L'enregistrement seul n'exécute pas la commande.

`ogma.menu.registerItem`

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

Enregistre un élément de menu contextuel associé à une commande du plugin. Enregistrez d'abord la commande. Le libellé utilise par défaut le nom enregistré de la commande, puis son identifiant ; si type est omis, sa valeur par défaut est Request. leadingIcon n'est pas utilisé par la passerelle hôte.

Fonctions utilitaires de thème

Le SDK injecté fournit également sdk.theme.get() et sdk.theme.onChange(callback). Ces fonctions lisent le thème de l'iframe et permettent de s'abonner aux mises à jour du thème de l'hôte sans commande de données distincte sur la passerelle. Utilisez-les pour harmoniser l'interface du plugin avec l'apparence claire ou sombre d'Ogma.

Codes d'erreur

Code	Signification
`PERMISSION_DENIED`	Le plugin ne dispose pas de la permission requise.
`PLUGIN_DISABLED`	Le plugin n'est pas actuellement activé.
`UNKNOWN_COMMAND`	La commande ne figure pas dans la liste des commandes prises en charge.
`INVALID_PAYLOAD`	Un champ obligatoire de la charge utile est manquant ou son type est incorrect.
`NOT_FOUND`	La ressource demandée n'existe pas.
`LIMIT_EXCEEDED`	Le nombre maximal autorisé pour ce plugin a été atteint (par exemple, pour les éléments de la barre latérale).
`SERVER_ERROR`	Erreur interne. Consultez les journaux du plugin.

Liste des commandes prises en charge

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.

Référence du SDK frontend des plugins ​

Modèle de sécurité ​

Protocole de la passerelle ​

Enveloppe de requête ​

Enveloppe de réponse ​

Utilisation du SDK (recommandée) ​

Référence des commandes ​

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 ​

Fonctions utilitaires de thème ​

Codes d'erreur ​

Liste des commandes prises en charge ​

Référence du SDK frontend des plugins

Modèle de sécurité

Protocole de la passerelle

Enveloppe de requête

Enveloppe de réponse

Utilisation du SDK (recommandée)

Référence des commandes

`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`

Fonctions utilitaires de thème

Codes d'erreur

Liste des commandes prises en charge