orbit/docs/SANDBOX.md

The sandbox

The sandbox is a core subsystem (src/modules/sandbox/): it runs code in an opaque-origin iframe (sandbox="allow-scripts", no allow-same-origin) that reaches the app only through a capability-gated message bridge. Sandboxed code cannot read the page DOM, cookies, localStorage (the SASL handoff password), or the store — only what its permissions grant.

Two things use it:

• Built-in features (bundled) — the app mounts them itself at boot via src/modules/sandbox/builtins.ts → mountSandboxed({ name, source, permissions }), with the source compiled into the app (?raw). They are opt-in per deployment: a built-in only mounts if its name is listed in config.json "builtins": [...]. Example: the dice 🎲/🪙 widget (src/modules/sandbox/features/dice.js). To add one, follow src/modules/sandbox/features/README.md.
• Operator plugins (config) — a config.json entry with sandbox: true is fetched and mounted the same way. Use for community / third-party / less-trusted plugins. (Plain string entries still load in-page as a trusted <script>.)

Plugin files live under public/plugins/third/ (served at /app/plugins/third/):

"plugins": [
  { "url": "/app/plugins/third/orbit-clock.js",                   // sandboxed, no permissions
    "sandbox": true, "permissions": [] },
  { "url": "/app/plugins/third/community-thing.js",               // sandboxed, community
    "sandbox": true, "permissions": ["irc", "storage"] }
]

Capabilities

A sandboxed plugin can do nothing privileged unless the operator grants the matching permission. Everything else (reading a cached state snapshot, rendering UI inside its own iframe) needs no grant because it is already contained.

permission	unlocks
none	nothing — an explicit "zero permissions" declaration; use ["none"] instead of []. It is fail-closed: "none" wins over any other entry in the list
irc	orbit.irc.say/msg/join/part/list — acts as the user
irc-raw	orbit.irc.send(line) — raw wire access (MODE/KICK/QUIT/…); grant deliberately
notify	orbit.notify(title, body)
storage	orbit.storage.set(k, v) (namespaced, persisted host-side)

Ungranted or unknown calls are refused host-side (fail-closed). The gate is unit tested in src/modules/sandbox/protocol.test.ts.

The guest is typed core source in src/modules/sandbox/guest/ (the SDK lives here too); a Vite plugin transpiles it into plugin-sandbox.html at build (served on the fly in dev). The sandboxed API (src/modules/sandbox/host.ts + the guest): orbit.log, orbit.on(event, fn) (forwarded connected / message / buffer.active / status), orbit.irc.*, orbit.notify, orbit.state.active/nick/account/buffers (from a pushed snapshot, synchronous), orbit.server.network/isupport/hasCap/caps (also from the snapshot, synchronous — gate cap-dependent behaviour so a plugin never 421s a lean server; no numeric() here since the sandbox gets no raw events), orbit.storage.get/set, and orbit.ui(slot, build) where build(el) populates the plugin's own iframe and the host sizes the frame to the content.

The app's theme CSS vars (--bg, --ink, --accent, --muted, --border, --accent-soft) are mirrored into the sandbox and kept in sync on theme change, so plugin UI can use var(--accent) and look native in light + dark.

Examples: src/modules/sandbox/features/dice.js (a built-in, bundled + mounted by core) and public/plugins/third/orbit-sandbox-demo.js (the minimal config-loaded form).

Required CSP (APPLIED 2026-07-04)

The sandbox iframe needs two nginx changes in chat-headers.conf. Both are contained: the sandbox doc is opaque-origin, so its looser script policy cannot touch the app.

1. Let the app embed the sandbox document — add 'self' to the app frame-src:

   frame-src 'self' https://challenges.cloudflare.com https://www.youtube-nocookie.com;
   

2. Serve /app/plugin-sandbox.html with its own tight CSP that allows the bootstrap to run and eval plugin code, but blocks all network egress (so even a malicious sandboxed plugin cannot phone home — it may only talk over the postMessage bridge):

   location = /app/plugin-sandbox.html {
     add_header Content-Security-Policy "default-src 'none'; script-src 'unsafe-inline' 'unsafe-eval'; style-src 'unsafe-inline'; img-src data:; media-src https:; connect-src 'none'; frame-ancestors 'self'" always;
   }
   

   media-src https: lets a sandboxed plugin play an audio/video stream in its own iframe (e.g. the orbit-radio footer player). Playback stays contained — the iframe still can't fetch, read the response, or reach the app. Drop it if no deployment plugin needs media.

Applied live in csp-app.conf / chat-headers.conf (added 'self' to frame-src) and a location = /app/plugin-sandbox.html block in tchatou-app-backend.conf. Note: nginx reload cannot rekey a shared-memory zone, so activating this needed a full systemctl restart nginx (an unrelated pre-existing limit_req key change had been blocking reloads).