🤖 Member apps: LLM-built or member-written, member-deployed, sandboxed

Members get an app two ways: ask a bot in plain chat ("build me a habit tracker"), or write the code themselves and deploy it from App Studio. Either way it lands in the Apps menu a moment later. This document is the design: what runs where, what the server can see, and why untrusted code can't touch anything that matters. The authoring rules live in docs/building-member-apps.md (served at /api/member-app-guide); the mini-app platform itself in web/static/apps/README.md.

Two trust tiers

| | custom apps (existing) | member apps (this doc) | |---|---|---| | who ships it | the instance admin | any member (usually via a bot) | | what it is | CODE the admin vetted | USER CONTENT | | stored as | plaintext JS (custom_apps) | instance-key-encrypted blob (member_apps) | | served as | an executable ES module | never — the server can't even read it | | runs | in the page, full trust | in an opaque-origin sandboxed iframe | | install gate | admin token | member token; author-only overwrite | | moderation | admin delete | author or admin delete |

The existing tier is unchanged. The new tier exists because "anyone can add code" and "code runs with access to everything a device can decrypt" cannot coexist — so member apps get a cage instead of a vetting step.

The loop, end to end

1. Ask. A member tells a model-enabled bot what they want. The bot's system prompt teaches it to interview briefly, then call its create_app tool with a name/title/glyph/spec (internal/bot/brain.go).
2. Build. The sidecar runs a dedicated generation call against the instance's own authoring guide (fetched from /api/member-app-guide, so bot and server can never disagree), then statically validates the module — allowed imports only, no network/storage APIs, one defineApp, namespaced event types — and regenerates on failure (internal/bot/appbuild.go). This validation is a quality gate; the sandbox below is the security boundary.
3. Deploy. The bot — an ordinary E2EE member holding its own wrapped copy of the instance key — encrypts { source, manifest } under that key and PUTs the blob to /api/member-apps/{id} with its member token (memberapps.go). The id is random; the server learns nothing but (id, author, size, time). apps_changed broadcasts and clients reload.
4. Launch. At boot the client fetches the list, decrypts each blob with the instance key, validates the manifest, and registers a proxy app through the ordinary defineApp (web/static/sandbox.js) — so the app appears in New chat's Apps list, gets its own personal thread, folds events, and snapshots exactly like a built-in. Opening it mounts the sandbox frame; the member sees their custom UI full-pane in the shell.

Fixing an existing app: the bot's eyes

Building is only half the loop — members come back with "the done button does nothing, fix it". The server can't help (it holds ciphertext), so the bot's sight is client-side, built from the same instance key it deploys with (internal/bot/appbuild.go):

• Discovery. Every model reply carries a per-sender system note listing the apps that member owns — exact app_id, title, name, version, builder — decrypted from the deployed list (briefly cached; the sidecar's own deploys invalidate it). Without this, the model only ever knew an id that happened to appear in the recent conversation, and "fix my habit tracker" from a fresh chat silently became a blind second build.
• Reading. A read_app_source tool returns one app's manifest + current source (owner-gated, exactly like updating), run in a short bounded tool loop inside the reply — so the bot can diagnose a bug or explain the app's behaviour before (or without) rebuilding.
• Updating. create_app with the app_id from the note; the build call regenerates from the app's current source, so the fix is an edit, not a from-scratch rewrite. The deploy verifies and announces the new version, and the old one stays in App Studio's History to revert to.

All three stay inside the ownership gate: the note lists only the sender's apps, reads and updates check the manifest's owner against the requester, and other members' apps are invisible and untouchable.

The sandbox

The proxy's render mounts:

<iframe src="/app-sandbox" sandbox="allow-scripts">

• Opaque origin. sandbox without allow-same-origin gives the document a null origin: no cookies, no localStorage/IndexedDB of the instance origin (where the session token and private key live), no DOM access to the parent page, no popups, no top navigation.
• Own CSP, not the page's. /app-sandbox is a real page (memberapps.go) served with default-src 'none'; connect-src 'none'; script-src '<sha256>' 'unsafe-eval'; img-src data: blob:; style-src 'unsafe-inline'; frame-src 'none'; form-action 'none'. No fetch/XHR/WebSocket/beacon to anywhere — including our own server. The script-src is a hash of the one inline runtime, deliberately NOT a nonce: a nonce is readable by same-document JS (document.querySelector('script').nonce), and a nonced <script src> bypasses the host allow-list — so hostile app code could read the nonce and pull remote code / exfiltrate despite connect-src 'none'. A hash authorises exactly that one script and nothing the app can mint, so every <script src> (and every other inline script) is refused. (A srcdoc frame would have inherited the chat page's CSP; a real page carries its own.)
• One trusted script. The page inlines web/static/sandbox-frame.js (its bytes are what the CSP hash covers). It receives { source, manifest, seed, me, theme } over the bridge, rewrites the module's imports into an SDK shim (transformModuleSource), evals it ('unsafe-eval' is scoped to this caged document), folds events with the app's real reducer, renders into the frame's own DOM, and reports state back.
• The bridge is the only doorway. A MessageChannel the host establishes on the iframe's load event — an unforgeable signal that fires on every genuine (re)load, unlike a postMessage "ready" which app code could spoof to hijack the port. The frame verifies init comes from window.parent with a real (non-null) origin, so one sandboxed app can't initialise a sibling. Everything a frame sends is validated host-side (web/static/sandbox.js): - emit/schedule/ephemeral — the event must be one of the app's own manifest types (all prefixed <name>.), deep-cleaned to plain JSON (no __proto__/constructor keys, depth- and size-capped), transport fields (name/ts/uid) stripped, notice clamped to plain strings with action chips removed, and rate-limited. A member app can never spoof chat.*, another app's events, or a plain chat message. - state — size-capped, JSON-normalized, installed only through installMemberAppState (apps.js), which is gated on the proxy marker.

What's inside the frame when it runs: the app's source, its own thread's decrypted events and folded state, the member's uid/screen name, and the theme variables. What is never inside: keys, tokens, other threads, the roster, message content from anywhere else. The worst a malicious member app can do is lie about or destroy its own state — the same power its reducer always had.

Known residual channels, accepted and bounded: the frame can navigate itself back to /app-sandbox (a self-reload — it just resets its own cage, gaining nothing); cross-origin navigation and remote subresource loads are blocked by the parent's frame-src 'self' and the frame's own hash-pinned script-src + connect-src 'none' + img-src data: blob:. postMessage from app code is validated away (init rides the load event, not a message). Nothing touches the E2EE core: keys, tokens, other threads, and the parent DOM never enter the frame, so the worst a hostile app does is corrupt or spoof its own pane.

State: { v, vUpTo, pend }

The host never runs the untrusted reducer, but the framework's snapshot machinery needs some fold. The proxy's fold is a trusted generic queue:

• every wire event of the app's types appends { e, meta } to pend (bounded; overflow drops oldest and flags lost);
• the frame folds those events with the real reducer and reports { state, upTo }; the host swaps that in as v/vUpTo and trims pend.

At every moment v + pend is the fold at the thread's horizon — the swap is horizon-neutral — so takeSnapshot/seedThread persist and restore sandboxed state through the standard encrypted thread_state path, and a closed app still accumulates events safely (they queue in pend, fold on next open). Scheduled events and notice pushes ride the normal wire paths untouched.

Server surface (memberapps.go)

| route | gate | notes | |---|---|---| | GET /api/member-apps | member token | blobs included (only clients can decrypt) | | PUT /api/member-apps/{id} | member token | new id: any member (cap 200); existing: author, owner, or an agent asserting that same recorded owner | | DELETE /api/member-apps/{id} | author or admin | admin = moderation without readability | | GET /app-sandbox | none (static runtime) | the caged frame document | | GET /api/member-app-guide | none | the authoring guide the bot builds against |

Admins can switch the whole tier off with the member_apps_enabled setting (Admin → Features → "Let members make their own apps", default on) — narrower than the apps_enabled gate, which covers the entire apps feature. Off means: the PUT above 403s (new deploys and edits), the guide 404s (which flips the bot sidecar's create_app builder off — it treats a failed guide fetch as "building disabled"), and App Studio hides from the app pickers (an already-open App Studio thread drops its editor and says why; the deployed-apps list stays, minus Edit code / Revert). Apps already deployed keep listing and running, and DELETE stays open — the gate stops new use, never cleanup or moderation.

Ownership: the server's author is whoever deployed (the bot, for bot-built apps). The requester is recorded inside the encrypted manifest (owner), and the bot refuses to update an app for anyone but its requester — the gate lives where the plaintext lives. The server's overwrite gate mirrors that split: author or owner always may, and an agent that is neither may overwrite on the recorded owner's behalf by asserting that same owner_id (the visible half of the manifest check it already ran) — which is what lets a bot fix an app the member wrote in App Studio, or one a different bot built for them. Ownership never transfers via an overwrite, and owner-less legacy rows stay closed to agents. Residual: chat payloads aren't sender-authenticated (the thread key is symmetric — every member can encrypt one), so a determined member could assert another's uid to redirect an update, exactly as they could impersonate anyone in plain chat. That's a property of the messaging layer, not this gate; the blast radius is capped by the sandbox (a hijacked update only alters that app's own caged pane, never keys or data). What the gate does enforce firmly: an unknown requester (no uid) can't build or update anything, and an app with no recorded owner can't be updated by anyone — so it never silently opens.

Caps: a global bound (200 apps) and a per-author bound (40) are enforced in one transaction so concurrent deploys can't race past them; the per-author bound stops one member starving the shared global cap.

App Studio — self-serve deploy (web/static/apps/appstudio.js)

App Studio is the member-facing manager: a compiled-in trusted app (it holds the token + instance key to encrypt/deploy, so it can't be a sandboxed member app) that lists deployed apps and deploys pasted source directly — no bot. It's the same doorway the bot uses (PUT /api/member-apps), driven by a member instead. The privileged work lives in web/static/sandbox.js (listDeployedApps, deployMemberApp, retireMemberApp, extractManifest, openMemberApp); shell.js injects the token/instance-key/opener via setMemberAdmin.

The load-bearing piece is manifest extraction: rather than re-parse source with regexes, App Studio runs the pasted code in a throwaway sandbox frame (extract mode in sandbox-frame.js → evalMemberApp → manifestOf) and reads back the real defineApp spec's name/title/glyph/types/commands/chat. Untrusted code is evaluated only in the cage, and the extractor is the authoritative source of truth (no drift with the runtime). deployMemberApp then validates that manifest, encrypts { source, manifest } under the instance key, and PUTs it — minting a fresh id for a new app, or reusing the id to update one you own.

A new app registers live on deploy (usable immediately, no reload) and suppresses this client's own apps_changed reload (recentLocalDeploy); an update changes already-loaded code, so it rides the normal reload.

Picking up a new app: offer, don't force

When apps_changed arrives (a bot build, an App Studio deploy on another device, or an admin custom-app install), the client does NOT reload out from under you. It registers any new member apps live (so they work at once), then surfaces a subtle, dismissible "A new app is available — Reload / Later" nudge in the sidebar (offerAppReload, styled like the backup banner — inline, never a floating toast). Reload is the reliable pickup for every tier (custom apps are ES modules that need a fresh load); "Later" just hides it. The bot's deploy confirmation reinforces the same low-pressure framing.

Native

Member apps ride the web shell, so the embedded webview (iOS/Mac render one thread per webview) runs them without native code: bootEmbed registers the proxies before rendering. A native Apps launcher entry is follow-up work; until then an app thread created on the web appears in the native thread list like any thread.

Commands, companion chat, and formatting (in the frame)

Three capabilities cross the sandbox boundary by running the app's untrusted logic in the frame and letting the host act on the (validated) result:

• ../format.js — the pure text helpers are bundled ahead of the runtime into the one /app-sandbox module (memberapps.go sandboxBundle), so a member app's import { richTokens } from "../format.js" resolves with no extra fetch. The CSP hash covers the whole bundle.
• Slash commands — the manifest carries command metadata (names, for the / typeahead); the handlers live in the source and run in a frame. When the app's thread is open its live frame runs the command; otherwise the host mounts a transient hidden frame (seeded from the snapshot) just to execute it. The handler's ctx.emit bridges out; its ctx.reply({text,short}) comes back and shows as the private confirmation where the user typed, with a host-owned "Open <app>" chip (the app can't ship clickable code into the host). Bridge: host→frame {type:"command",…}, frame→host {type:"command-reply",spec}.
• Companion chat — the manifest flags chat:true (derived by the bot from the source's chatMessage); the proxy gains a chatMessage so the framework treats it as a companion (Chat + Interface views). The real projection runs in the frame: it computes chatMessage(event) on fold and reports the chat lines alongside state (snapshotted in the proxy's {v,vUpTo,pend,chat} so the Chat view survives the window). The host folds each line into the thread's Chat view via the same chat.msg path a trusted companion uses, deduped by server message id.

All three stay inside the trust model: only the app's own thread data, its own manifest event types, and the projected/replied strings ever cross, all size-capped and rate-limited; keys, tokens, other threads, and the parent DOM never enter the frame.

Legacy formats: the compat policy

Member-app blobs are instance-key-encrypted user content: the server can't read them, there is no census of what exists across (self-hosted, offline) instances, and only the OWNER's client may rewrite one. So superseded authoring vocabulary can't simply be dropped — but it doesn't get to sprawl either. The policy, in deprecation-ladder order:

1. Writers emit only the current vocabulary. The bot's builder, manifestOf (App Studio's extractor), and the check-app.mjs linter all produce/teach the current form — nothing mints a legacy blob, ever.
2. Readers accept legacy at exactly ONE tested funnel per boundary — today: normalizePlaces in defineApp (the scope enum and the personal/groupCapable/spaceCapable flags normalize into places and are deleted) and the manifest→places derivation in sandbox.js. When a concept is superseded, all first-party code migrates and the internal reads are DELETED in the same change, so the funnel is the only place the old vocabulary exists. (A concept that never reached the stored-manifest boundary can be deleted outright with no funnel at all — groupChatOnly.)
3. Upgrades are opportunistic and owner-driven. Any touch modernizes an app: bot updates regenerate source against the current guide, and App Studio flags legacy-format apps ("older format") with a one-tap Upgrade — redeploying the same source re-mints a current manifest, with the old version kept in History. Never rewrite a member's SOURCE automatically: it's user content, and a transform bug bricks an app we can't inspect.
4. The floor may eventually rise — but the accepted set is bounded and written down, never infinite. The full legacy set is currently: manifests with scope: "personal" and/or the capability booleans in place of places, and sources declaring the same fields in defineApp. After a long, announced deprecation window (upgrade offers shipped well before), validateManifest — the load gate — may refuse forms below the floor; a refused app fails to register with a reason, exactly like any invalid manifest, and its owner upgrades from App Studio. Raising the floor is a deliberate, documented decision, never a side effect.

Follow-ups (deliberately out of scope)

• messageAction / notify / preview / unread for sandboxed apps.
• ~~Shared-scope (group) member apps~~ — SHIPPED since: a member app's places may name any non-empty subset of you/chat/space, so chat-shared, space-wide, and even space-only (gif-shaped, listed: false) member apps are all legal (docs/building-member-apps.md).
• An admin-console list of member apps (App Studio lists a member's own; an admin can delete any via the API today).
• In-place update of a running app without a reload (updates currently reload to swap code).

🤖 Command panels (member apps)

A member app's command may open a command panel (ctx.panel — the transient surface above the composer). The trust posture is unchanged:

• The panel BODY is a fresh /app-sandbox frame — the same opaque-origin, no-network, no-keys cage as the app's own surface. The host never runs the app's panel code in the page.
• Everything crosses the bridge as validated JSON: the request (sanitizePanelSpec — clamped title, 64 KB data cap), emits from the panel frame (the standard sanitize + rate limit), composer inserts (length-capped), and content-height reports (clamped).
• A panel opens only while one of the app's commands is actually running (the host resolves the opener by the command's sequence number), so a frame can't pop panels spontaneously.
• The panel HEADER and ✕ are host-drawn, outside the frame — dismissal can't be trapped. A panel frame's state reports are ignored; the app-thread's own frame stays the single writer.

🤖 Platform limitations: what member apps structurally can't do (yet)

Building a full pack of real apps (a 21-app "family" set; web/static/apps-disabled/family/) surfaced a consistent boundary worth recording so it isn't rediscovered each time: member apps are well-suited to personal, cooperative, single-thread tools (lists, trackers, journals, games) and structurally can't express roles/authority, per-member privacy, targeted notification, or enforcement — even though the server already holds the primitives for most of it.

• No authority reaches apps. Access levels (tiers, docs/community-and-tiers.md) are admin-assignable roster roles — not just paid — each carrying its own key: a ready-made "parents/children" or "moderators/members" primitive with cryptographic backing. But ctx exposes no tiers and the sandbox withholds the roster, so an app can gate nothing on a role. (In the family pack, an "ask a parent" app degrades to "anyone but the asker".)
• No per-member privacy in a thread. One symmetric thread key → every member decrypts every event and snapshot. An app can only render-hide (a courtesy, not a vault); asymmetric secrecy needs cryptographic sealing the keyless sandbox can't perform.
• The fold can't authorise. Pure reducers see only e.uid; every member can emit every event, so "only X may do Y" is a render suggestion, never enforced.
• No roster, no targeting, no directed notice. Apps rebuild a pseudo-roster from participation (who has emitted an event); a notice reaches everyone who receives the event, not a chosen person or role.
• Convergent fold vs asymmetry. "The same events fold to the same state" (load-bearing for snapshots + native parity + the event vectors) is exactly what makes per-viewer or per-role state impossible except as a render illusion.

Widen-it path (roadmap, not built). Expose tier membership to ctx for admin-defined role gating (Level 1 — courtesy, but backed by a real role); add host-mediated seal-to-tier / seal-except primitives for real enforcement and privacy (Level 2 — the keyless sandbox can't do it alone); give notice a target so an app can reach a person or a role. Fuller write-up, with per-app evidence and the three-level "who sees what" model, lives in the family reference pack's DESIGN.md (§ "Fit for purpose?" and § "Viewer-aware rendering").