Talking to the platform

A module UI runs in a sandboxed iframe with an opaque origin: it has no cookies, no access to the shell's DOM, and no direct API access. Everything it needs from the platform goes through `postMessage`, brokered by the host (the shell) which holds the user's authenticated session.

 module UI (sandboxed iframe)                     Hanabi shell (trusted parent)
 ───────────────────────────                      ─────────────────────────────
 postHanabiMessage(req)  ───── postMessage ─────▶  capability bridge
                                                    1. verify event.source is this iframe
                                                    2. check manifest declares the permission
                                                    3. check the user granted it
                                                    4. scope to the module's folders
                                                    5. call the authenticated REST API
        result/event   ◀───── postMessage ──────  reply { rid, ok, data | error }

Envelope #

Every message is a JSON object with a protocol version and a type:

{ "v": 1, "type": "HANABI_<NAME>", "rid": "<correlation-id>", /* …payload… */ }

• v — protocol version (currently 1). The host supports a range and replies { ok: false, error: { code: "UNSUPPORTED" } } for types/versions it doesn't know — never a silent drop.
• rid — correlation id the module generates per request; the host echoes it on the reply. Events pushed by the host (e.g. job progress) omit rid.

Module → host requests #

Host → module replies & events #

• Reply to any request: { "v": 1, "type": "<TYPE>_RESULT", "rid": "...", "ok": true, "data": {...} } or { "ok": false, "error": { "code": "...", "message": "..." } }.
• Event, correlated by the rid of the originating streaming request (HANABI_CREATE_JOB or a stream: true HANABI_MODULE_REQUEST). The originating request stays open until its terminal _RESULT reply resolves it:
• progress — { "v": 1, "type": "HANABI_JOB_PROGRESS", "rid": "...", "jobId": "...", "progressPct": 50, "message": "…" }.
• streamed output — { "v": 1, "type": "HANABI_JOB_OUTPUT", "rid": "...", "jobId": "...", "seq": 1, "chunk": "…", "encoding": "text" | "base64" }. A progress worker emits these by yielding {"output": "…", "encoding": "text"|"base64"}; use them for live logs, progressive/token output, or incremental results. Chunks are transient (not persisted) and arrive in seq order, interleaved with progress.
• streamed module-route line — { "v": 1, "type": "HANABI_MODULE_STREAM", "rid": "...", "event": { … } } — one parsed newline-delimited-JSON object from a stream: true HANABI_MODULE_REQUEST (moduleStream). The host reads the route's NDJSON response and relays each line as it lands; a terminal { "error": "…" } line rejects the call.

Error codes

File associations (Open with) #

A module can declare the file types it opens in its manifest:

"desktop": { "file_associations": ["md", "txt"] }

Extensions are lowercased and dot-stripped. An installed module that declares an extension then appears in File Explorer's Open with menu (and can be set as the default app) for matching files. Choosing it launches the module with the file delivered as openedFile in the module context (HANABI_READY).

Because the user explicitly chose “open this file with this module”, that single file is readable for the launch — via HANABI_READ_FILE or HANABI_OPEN_MEDIA using openedFile.id — even though it lives outside the module's own folders. No other out-of-scope file becomes reachable. The module still needs files.read.

Jump-list actions #

A module can contribute quick actions to the Start menu (a jump-list) in its manifest:

"desktop": { "jump_list": [{ "id": "new-note", "label": "New note" }] }

Each action appears as an indented sub-row under the module in All programs. Choosing one launches the module with the action's id delivered as launchAction in the module context (HANABI_READY / HANABI_GET_CONTEXT); the module reads it on load and runs the matching action (e.g. open a blank document). Entries are validated and clamped (up to 6 actions; ids and labels are length-limited). No permission is required — a jump-list only ever launches the module that declares it, with no file or data access implied.

Using the SDK (module side) #

The @hanabi/module-sdk ships createHanabiClient(), which handles the versioned envelope and rid correlation so you write await calls instead of wiring postMessage by hand:

import { createHanabiClient } from '@hanabi/module-sdk';

const hanabi = createHanabiClient();

// Read the grant + folder context (also answers HANABI_READY).
const ctx = await hanabi.getContext();

// Pick and read an input file (requires files.read).
const { files } = await hanabi.pickFile(['xlsx', 'csv']);
const file = await hanabi.readFile(files[0].id);   // file.bytesB64

// Write an output file (requires files.write).
await hanabi.writeFile('result.txt', btoa('done'), 'output');

// Clean up the listener when your view tears down.
// hanabi.dispose();

SDK client methods

createHanabiClient() returns a typed client — one method per capability, plus call(type, payload, onProgress?, onOutput?) as the escape hatch:

// Stream a job's progress + live output, then raise a notification when done.
await hanabi.createJob({ mode: 'convert' }, refs,
  (p) => setProgress(p.progressPct),
  (o) => appendLog(o.encoding === 'base64' ? atob(o.chunk) : o.chunk));
await hanabi.notify('Conversion complete', { tone: 'success' });

// Stream a scoped video without copying bytes over the bridge.
const media = await hanabi.openMedia(fileId);
videoEl.src = media.url;            // supports HTTP range / seeking

// Persist a durable, cross-device setting (survives a cache clear).
await hanabi.setSetting('theme', 'dark');

// Edit a spreadsheet in place — the file this module was opened with.
const wb = await hanabi.readOffice(ctx.openedFile.id);          // { kind, sheets }
await hanabi.saveOffice(ctx.openedFile.id, { kind: 'spreadsheet', sheets: wb.sheets });

// Call this (first-party) module's own server route; stream a long one.
const preview = await hanabi.moduleRequest('POST', 'preview', { input_refs, options });
await hanabi.moduleStream('POST', 'generate-stream', { input_refs, options },
  (e) => markDone(e.index, e.total));     // one NDJSON line per finished item

If you can't bundle the SDK (a plain-HTML module), copy the ~20-line inline client from examples/modules/capability-demo/ui/index.html — it speaks the exact same protocol.

Capability tiers & admin governance #

Every permission has a security tier — the single source of truth is the backend capability registry (services/capabilities.py):

admin-HIGH capabilities are denied unless an admin individually grants them for a module and sets their quota (resource tier, egress budget, …). Grants are recorded on the module's developer draft and enforced at runtime by enforce_capability (capability_enforcement.py), which also audits each use. Adding or escalating any admin / admin-HIGH capability on an update forces a manual re-review (the module stays live on its prior approved version meanwhile). First-party / built-in modules are trusted.

The three enforcement checks (why this is safe) #

A capability is honored only if all three hold — this is the security spine, and it reuses the boundaries in ../security-model.md:

1. 1Declared — the manifest lists the matching permission.
2. 2Granted — the installing user consented (auto-granted for first-party; explicit consent UI for third-party — Phase 5).
3. 3ScopedClamped to your own Modules/<Name>/ folders for the current user — never another module or user. — file operations are clamped to the module's own Modules/<Name>/… folders for that user. A module can never name a file id or path belonging to another module or another user.

The bridge runs in the trusted parent and calls the same authenticated, CSRF-protected API the rest of the app uses; it never hands the iframe raw storage keys, cookies, or cross-scope data.

Isolation summary #

• <iframe sandbox="allow-scripts"> without allow-same-origin → opaque origin, no cookie/DOM access.
• Host validates event.source === iframe.contentWindow and ignores all other senders.
• Assets served read-only with X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, a locked-down Permissions-Policy, and a per-module Content-Security-Policy. With a distinct module-serving origin (HANABI_MODULE_ORIGIN, Phase 11) the CSP names that origin explicitly in the asset directives (default/script/style/img/media/font/frame-src/worker-src) — the iframe's opaque origin makes a bare 'self' match nothing for sub-resources — while keeping connect-src strict ('self' + any declared network origins) and object-src 'none'. frame-src and worker-src also allow blob:, so a module can frame a blob document it built from its own bytes and run a web worker it bundles inline — e.g. PDF.js, which a module uses to render a PDF preview to a <canvas> because the browser's built-in PDF viewer is blocked in the sandbox; <embed>/<object> stay blocked. The module document is served no-store so a header change (like the CSP) propagates on the next load.
• Outbound network from a module is denied by connect-src unless its manifest declares http(s) dependencies.services and holds the approved network.fetch permission — then only those origins are allowed (Phase 8).