# 🤖 App credentials: one key per space, asked once

The problem: an app that needs an API key shouldn't ask every member for one.
`/gif` is the worked example — it asks each person for their own free Giphy key
and keeps it in that device's `localStorage` — but the case that matters is the
one members *build*: "make me a weather app" is worthless if all twelve people
in the space have to go register for an OpenWeather key.

What we want: **the first person to use the app supplies the key; nobody in the
space is ever asked again.**

## The answer for most keys: put it in the fold

A space-placed app's state already *is* one shared, end-to-end-encrypted value
that every member of the space can read and nobody else can — including the
server. That is not a compromise to work around; it is precisely what "the key
belongs to the space, not to a device" means. So:

> **A shared app key lives in the space app's fold state, like any other space
> app data. No new store, no new table, no new sealing decision.**

`places: ["space"]` and the existing space thread (`docs/space-apps.md`) already
do the whole job. The first member to run the command is asked; the key folds
into the space log; every other member — and every later joiner, via the
instance key — reads it and is never asked.

### Why not the connected-services store?

Because it solves a different problem. `connected.go` holds one blob per
`(member, service)`, sealed to **that member's own public key**, and exists for
exactly one reason: to keep a credential secret *from other members* — "my
GitHub token is mine." Remove that requirement and the store's reason for
existing goes with it. A space key is *supposed* to be readable by the space.
Reaching for the per-member store here would be solving a problem we don't have.

### Why not the Vault?

The Vault is space-capable too, and "one credential shelf for the space" sounds
like it should host this. It shouldn't, and the line is a **category** one, not a
UX one: the Vault holds **secrets a person chose to keep** — things a member
decides are worth storing and would recognise on a shelf. An app key is **config
the app needs to function**: nobody wants it, the app just can't run without it.
Filing app config on the members' secret shelf would put an implementation detail
in a surface people curate, and make one app's data another app's dependency.

Two apps landing on the same trust posture — shared fold state, every member
reads it, additions attributed — is convergence on *how* to store a shared value,
not evidence they should share a *store*.

### The one case the fold doesn't cover

Fold state can't keep a secret from a member of the thread — the guide says so
outright (`docs/building-member-apps.md:389`: a group-capable app has "no way to
keep a secret from one member of the group"). Every member decrypts every event
and snapshot by construction.

For a public client identifier (Giphy) that is a non-issue: exposure is
harmless, and sharing is the whole point. It only bites when a value must be
usable by the space but *not readable* by its members — a metered key with a
real bill, or a token with write access to something outside the space. That is
a genuinely different feature, and if it is ever wanted the shape is known:
seal it to the **bot's** public key, so no member reads it and it is usable only
through the grant path below. Out of scope here; noted so the boundary is
explicit.

One small consequence worth knowing either way: a log is immutable, so rotating
a key leaves the old value readable in the log's history forever. For a public
client id, who cares. For anything metered, that is a reason to think again.

## Using the key

This is the half with real difficulty, and it is unchanged by the above.

A member app **cannot fetch**. Not "shouldn't" — cannot, walled twice:

- its own document is `default-src 'none'; … connect-src 'none'`
  (`memberapps.go:263`), with a **hash-pinned** `script-src` (a nonce would be
  readable by same-document JS and could bypass the host allowlist);
- the frame's `ctx` is built from scratch and has **no `host`**
  (`sandbox-frame.js:468`); the init message carries only
  `{source, manifest, threadId, me, theme, seed}` — no keys, no tokens
  (`sandbox.js:321`).

So an external-API member app is **forced** through the bot sidecar. That is a
consequence of the cage, not a design choice — and it has a consequence the
product must own:

> **External-API member apps require a running, model-enabled bot sidecar. A
> space without one cannot run them.**

### Getting the key to the sidecar: two paths, both already built

It would be easy to read the sandbox walls as "so the backend can't have the
key". That is wrong, and the distinction matters because the two paths cover
different cases.

**Path A — the per-op grant (a member is present).** `shell.js:4492` seals
`{service, token, exp}` to the **bot's** public key for one operation; the
sidecar opens it with its own private key, acts once, and drops the token
(`internal/bot/connect.go`). The external HTTP call happens **in the sidecar,
never the browser** — which is why the page CSP never needed `api.github.com`.

> **A credential can be used by code that never sees it.**

This composes with fold state directly: the browser reads the key from the space
fold and seals it per-op. Nothing new. But it only works **while a member's tab
is open** — which is fine for "someone typed a command" and useless for "every
morning at 6am".

**Path B — the sidecar reads the fold itself (nobody is present).** The bot
already holds the **instance key**: it fetches its own wrapped copy and unwraps
it with its own private key (`internal/bot/appbuild.go:765-777`). That is not a
detail — it is how charters work at all, since a charter is sealed under the
instance key (`chartersched.go` calls `r.instanceKey()` before it can list
anything).

The space thread's key rides `open_key`, wrapped under that same instance key. So
a sidecar is **cryptographically capable** of reading the space fold. It is
excluded by *policy*, not by a wall: `spacethread.go:60` gates on
`isAgent(uid) && !threadMember(id, uid)` — an agent with an explicit membership
row **passes today**, and gets `open_key` from the existing endpoint with no new
server code. (Agents still can't *mint* the thread — `spacethread.go:115` — since
the creator necessarily knows the key it wraps.)

That is the path `docs/space-apps.md` already anticipated:

> Bots in the space thread: excluded by default; a deliberate opt-in flow
> (disclosed, like adding a bot to a group) would let a bot serve space-wide apps.

So autonomous, scheduled backend work needs **no browser and no new crypto** — it
needs a membership row and the disclosure flow around it. What's missing is the
*flow*, not the capability.

| | member present | nobody present |
|---|---|---|
| **Path A** — per-op grant | ✅ works today | ❌ no tab to seal it |
| **Path B** — bot in the space thread | ✅ | ✅ needs the opt-in flow (server side already allows it) |

Path B is the stronger claim and deserves the scrutiny: adding a bot to the space
thread means that machine can decrypt **every space app's data**, not just the one
credential it needed. That is the same bargain as adding a bot to a group — which
is why it must be disclosed and deliberate, and why "the app needs a key at 6am"
should not silently buy it.

The remaining plumbing is one sanitized bridge RPC (a sibling of `schedule` /
`panel-open` in `sandbox.js`'s `onFrameMessage`) forwarding `{service, op, args}`
from the frame to the host; the host mints the grant and routes to the sidecar;
the frame gets back cleaned JSON. The token never enters the frame. Both walls
stand.

### The crux: an arbitrary app has no reviewed ops

`requestOp` routes to a **closed, reviewed** op list per service
(`integrations/registry.go`: a manifest is "the WHOLE of what an integration can
do — the one API host its ops may touch and the closed list of operations"). A
member-built app that wants some API nobody has integrated has no manifest to
name — and the obvious escape hatch, a generic HTTP-proxy op, hands the app
control of the URL and body, which is precisely the exfiltration channel
`exec.go`'s invariant exists to deny:

> The manifest is reviewed code; the args and token are member input… **A value
> can steer WHAT an op says, never WHERE it goes.** (`integrations/exec.go:18`)

Grant that and the cage's guarantee — "the worst a hostile app can do is corrupt
its own pane" — is gone.

**The way out, proposed:** the registry is *declarative JSON*, and its validator
is already exported and fails closed — `integrations.Parse(raw []byte)` +
`validate()`. The security property lives in `validate()`, **not** in being
embedded in the binary. So the registry can become **admin-extensible per space**
without weakening anything: an admin adds a service manifest (pinned host, named
ops, declared args, declared response projection), the same validator accepts or
rejects it, and `exec.go` re-checks the final URL against `auth.base`'s host at
*request* time — so even a manifest that tried to smuggle a second host is caught
at execution, not merely at validation.

That moves the review step from "a PR to this repo" to "an admin of this space",
which is the same trust rung that already vets custom apps and sets the
space-install policy. It does **not** let a member point an app at an arbitrary
host — that remains impossible by construction, which is the point.

## `/gif` is the odd one out — and is SHIPPED

Worth saying plainly, because it motivated this and then turns out to be
atypical: gif's fetch is **client-side** (browser → `*.giphy.com`, CSP-pinned at
`main.go:710`), not sidecar-side. It needs no grant, no sidecar, and no op
manifest. It is a compiled-in trusted app reading a public client id.

So gif was fixed by the fold alone, and that half is **built**: `places:
["space"]` + `listed: false`, the key folding from a `gif.key` event in the space
log, and copy that says the key is shared with everyone here. It is not the
template for member apps — it is the one case that doesn't need the hard half at
all.

Two things the implementation taught, both worth knowing before the member-app
half is attempted:

- **A space-placed command app straddles two threads.** `ctx` addresses the space
  (its data); the panel and any posted content address the chat. `ctx.panel`
  already resolved this — it binds to `activeThreadId`, not `ctx.threadId`
  (`apps.js` runCommand) — but *posting* did not: gif used to
  `gifHost.upload(ctx.threadId)` + `ctx.emit`, which under space routing would
  have uploaded the GIF under the space key and posted it into a thread that
  renders nowhere. Posting moved into the host doorway (`gif.post`), which reads
  `activeId` itself. An app gets no say in the destination — the host owns "here".
  This is exactly `docs/space-apps.md`'s "app data lives space-wide, conversation
  content stays under the conversation's own key", and any future space-placed
  command app inherits the same split.
- **Unroutable commands used to fail silently.** `runCommand` returned without a
  word when `instanceThread` gave null, so `/gif` with no space thread (a native
  embed, or an instance key still syncing) would have done nothing at all. It now
  answers "`/gif` isn't available here yet" — true for every app, not just this
  one.

## Implicitly space-placed (the "unlisted" question) — RESOLVED

Space is the right *place* for an app like gif — its data (the key) belongs to
the space, and its commands already work in every chat. But a plain `places:
["space"]` would drag it into the Apps catalogue, which is wrong for a
command-only utility that "acts where you type, lives nowhere".

**No new flag was needed.** `listed: false` already meant "not user-instantiable"
(`apps.js`), and `normalizePlaces` only *defaults* `listed` from `places.length`
— an explicit flag wins. So `places: ["space"] + listed: false` says it exactly.

The rule that makes it work, in `instanceThread`: **an unlisted space-capable app
is implicitly space-placed** — it has no Add button, so there is no install event
to gate on, and its one shared copy simply *is* the space's. That mirrors the
space thread's own implicit membership, and it sidesteps the admins-only install
policy entirely: there is no install to be inert. The thread is minted on first
use by the resolver.

The rule is load-bearing, not cosmetic. Without it a `spaceCapable` app that
isn't *installed* falls through to `return activeThreadId`, and gif's key would
fold into whatever conversation the member happened to be typing in — readable by
that chat's members, in the wrong log, forever.

The other two surfaces needed nothing: both the widget bar and the sidebar band
filter on an app-level `render`, and gif has none (its `render` is the *panel's*).

## Scope

- **Web first, native follows** — consistent with how space apps shipped, and now
  the one loose end of the shipped half. `loadSpaceThread` bails on `embed` by
  design, so a native `/gif` finds no space thread and answers "isn't available
  here yet" rather than working. That is a **regression in reach** against the old
  device-local key, taken deliberately: a per-device fallback would resurrect
  exactly what this replaced, and silence would have been worse than either. Both
  natives already seed `instanceKey` into the embed
  (`ios/LChat/FeedWebCache.swift:172`, `ios/LChatMac/CommandPanelWebView.swift:51`),
  so the fix is short — let `bootEmbed` load the space thread when it has the key.
  **iOS first** (CLAUDE.md), and note only the Mac has a command host today.
- **Member apps depend on the sidecar** and carry the registry question above.

## Open questions

1. **Native `/gif`** (above) — the immediate follow-up, and the only thing the
   shipped half left undone.
2. **Admin-extensible registry** — is moving the review rung from repo to admin
   acceptable? It is the crux of the use-path and the one genuinely new trust
   claim here.
3. **The bot-in-the-space-thread opt-in (Path B).** The server already permits it
   (`spacethread.go:60`); what's missing is the disclosure flow and its blast
   radius, since a bot in the space thread reads *every* space app's data, not
   just the credential that motivated it. This — not key delivery — is what
   autonomous scheduled apps actually wait on.
4. **Rate-limit attribution.** A shared key means one member's quota (or bill)
   serves the space. Disclosure covers Giphy; a metered API deserves more thought
   — and is the case that might yet want the bot-sealed variant above.
5. **Event vectors deliberately skipped.** `gif.key` is a new app event, and
   CLAUDE.md's contract says new app features add a vector. gif has no native
   side (and, per the scope note, won't until `bootEmbed` learns the space
   thread), so there is no second implementation for a vector to hold in step
   yet. It gets one when native `/gif` lands — recorded here so the omission is a
   decision, not a miss.