# ADR-0009: Sandboxed Iframe Widgets with a postMessage Protocol

- **Status:** Accepted
- **Date:** 2024-06-03
- **Deciders:** FablePool core team
- **Related:** ADR-0002 (frontend), ADR-0006 (content format), ADR-0010
  (code judge), `docs/architecture/07-widget-sandboxing.md`,
  `docs/schemas/widget-manifest.schema.json`

## Context

Interactive widgets (graph manipulators, circuit builders, geometry
canvases, simulations) are core to the product — and they are
community-contributed *code*, which is categorically different from
community-contributed *content*. The brief mandates keeping interactive
widgets separate from trusted core content. Threats if widget code ran in
the host page: session/cookie theft, API calls as the user, DOM phishing
overlays, exfiltration of answers, cryptomining.

Candidate isolation strategies: trusted-only first-party widgets; reviewed
JS executed in-page; iframe sandboxing; WebAssembly/interpreter sandboxes;
server-side rendering of widget state.

## Decision

Adopt the model specified in `07-widget-sandboxing.md`:

1. **Every community widget runs in a sandboxed `<iframe>`** served from a
   **separate origin** (`widgets.<instance-domain>` or a distinct
   registered domain), with
   `sandbox="allow-scripts"` (no `allow-same-origin` — the frame gets an
   opaque origin), a strict frame CSP (no network access except the widget
   bundle origin: `default-src 'none'; script-src <widget-cdn>; …`), and
   `Permissions-Policy` denying camera, mic, geolocation, etc.
2. **The only channel is postMessage**, speaking the versioned protocol in
   `07-widget-sandboxing.md` (`widget:init`, `widget:state`,
   `widget:answer`, `host:config`, `host:locale`, …). The host validates
   every inbound message against the protocol schema and the widget's
   declared manifest capabilities before acting.
3. **Widgets are packaged artifacts**: a manifest
   (`widget-manifest.schema.json`) + a single self-contained JS/CSS bundle
   pinned by **content hash**, uploaded through review like content.
   Problems reference `widgetId@hash`, so a widget update never silently
   changes a published problem (mirrors ADR-0007's pinning philosophy).
4. **Grading never trusts the widget.** A widget reports a *state* object;
   the answer spec in the problem JSON evaluates that state server-side
   (or, for `widget-graded` types, the widget's declared pure grading
   function is re-executed server-side in an isolated JS runtime). A
   compromised widget can at worst mis-render — it cannot award itself a
   correct answer.
5. **First-party core widgets** (the standard library: function plotter,
   number line, etc.) ship in the platform repo, go through normal code
   review, and still run in the same sandbox — one code path, no privileged
   exceptions to audit.
6. **Resource hygiene:** frames are lazily mounted, hard-capped
   (`loading=lazy`, teardown off-viewport on memory pressure), and bundles
   have size budgets enforced at upload (default 300 KB gzipped).

## Alternatives Considered

- **Reviewed JS running in-page.** Human review does not reliably catch
  malicious or obfuscated JS; one miss is account takeover. Rejected.
- **First-party widgets only.** Safe but kills the community-extension
  goal; the widget library would bottleneck on core maintainers. Rejected
  as the *only* mechanism (it exists as item 5, inside the sandbox).
- **WASM/interpreter sandbox (e.g., QuickJS-in-WASM) in-page.** Strong
  isolation of *computation*, but widgets need DOM/canvas/SVG rendering,
  which would require us to design and audit a rendering bridge —
  effectively rebuilding the iframe boundary by hand. Rejected for MVP.
- **`ShadowRealm` / SES (Secure ECMAScript).** Not broadly available /
  requires deep auditing of the object graph we expose. Revisit later.
- **Server-rendered widget frames (no client code).** Fails interactivity
  and offline/low-bandwidth goals. Rejected.

## Consequences

- ✅ Compromised widget ⇒ contained: opaque origin, no cookies, no API
  reach, no DOM access to the host, no network beyond its own bundle.
- ✅ Hash-pinning gives reproducibility and supply-chain integrity for
  published problems.
- ⚠️ Separate widget origin is a deployment requirement; Docker Compose and
  the deployment docs (ADR-0019) must provision it, including for
  small self-hosts (a second subdomain + the same reverse proxy).
- ⚠️ postMessage protocol versioning is forever-work: the host must support
  old protocol versions for already-published widget hashes.
- ⚠️ Iframes cost memory on low-end devices; lazy mount/teardown (item 6)
  and the bundle budget are mandatory, not optional polish.
- ⚠️ Accessibility inside an opaque-origin frame can't be enforced by the
  host at runtime; the widget review checklist includes an accessibility
  pass, and the manifest requires declared keyboard support
  (`a11y.keyboard: true`) for acceptance.