heyquilt 0.3.90 → 0.3.107

package/src/api/routes/secrets.js

@@ -0,0 +1,448 @@
+// Secrets (docs/superpowers/specs/2026-10-18-secrets.md): names and settings for people, run
+// tokens for `quilt run`, the app's inline "allow" for people-only secrets, and the vault's
+// internal routes. No route here ever answers a value; the API can't open one either (the
+// vault holds the keys). Sealed blobs pass through only to the vault, behind its shared secret.
+import crypto from 'node:crypto'
+import { HttpError, needId } from '../http.js'
+import { newToken, hashToken } from '../tokens.js'
+import { orgAccess } from '../org-access.js'
+import { workspaceReach } from '../workspace-reach.js'
+import { isAgentKey } from '../agent-auth.js'
+import { sessionMember, roomLevels, workspaceLevels, resolveLevels, mayUse, LEVEL_WORDS } from '../secrets-access.js'
+import { cleanSecretName, cleanUpstream, cleanFormat, formatLabel, formatId, envVarsFor, shortDigest, WHO, MAX_ENTRIES } from '../../ui/secret-rules.js'
+
+export const TICKET_TTL_MS = 5 * 60 * 1000
+export const RUN_TTL_MS = 60 * 60 * 1000
+// How long a waiting request is held, and how often it looks again (other API machines answer too).
+export const WAIT_MS = 25 * 1000
+const LOOK_EVERY_MS = 1000
+// One use logged per run and secret per minute: a busy process makes many requests.
+const USE_LOG_MS = 60 * 1000
+const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+const SCOPE = '(org|workspace|session)'
+const NAME = '([A-Z_][A-Z0-9_]{0,63})'
+const DIGEST = /^[0-9a-f]{64}$/
+const MAX_LABEL = 200
+
+export function secretRoutes (ctx) {
+  const { store, person, agentAuth, bearer, now, log = () => {}, vaultSecret = '', vaultUrl = 'https://vault.heyquilt.com', allowLocalUpstreams = false, waitMs = WAIT_MS } = ctx
+  const { caller: reachCaller, grantsIn, reach } = workspaceReach(ctx)
+  // Where people and processes reach the vault (a function in tests, whose vault starts later).
+  const vaultAt = () => String(typeof vaultUrl === 'function' ? vaultUrl() : vaultUrl).replace(/\/+$/, '')
+
+  // Small per-key limits: a person can't mint tickets or runs in a loop.
+  const hits = new Map()
+  const limit = (key, max, message) => {
+    const t = now()
+    const recent = (hits.get(key) || []).filter((x) => t - x < 60_000)
+    if (recent.length >= max) throw new HttpError(429, message)
+    recent.push(t)
+    hits.set(key, recent)
+    if (hits.size > 10_000) hits.delete(hits.keys().next().value)
+  }
+
+  // Woken when a run's asks are answered, or a person gets a new ask (this machine only; the
+  // waits also look at the store every second, for answers that came in on another machine).
+  const waiters = new Map() // key -> Set(fn)
+  const wake = (key) => { for (const fn of waiters.get(key) || []) fn(); waiters.delete(key) }
+  async function waitUntil (key, done, ms) {
+    const end = now() + ms
+    while (true) {
+      const r = await done()
+      if (r || now() >= end) return r
+      await new Promise((resolve) => {
+        const fn = () => { clearTimeout(timer); resolve() }
+        const timer = setTimeout(() => { waiters.get(key)?.delete(fn); resolve() }, Math.min(LOOK_EVERY_MS, Math.max(0, end - now())))
+        if (!waiters.has(key)) waiters.set(key, new Set())
+        waiters.get(key).add(fn)
+      })
+    }
+  }
+
+  const nameOf = async (account) => {
+    const [kind, id] = String(account || '').split(':')
+    if (kind === 'agent') return (await store.agentById(id).catch(() => null))?.name || 'An agent'
+    if (kind === 'person') return (await store.profile(id))?.name || 'Someone'
+    return ''
+  }
+
+  /** The person or agent calling: { account, kind, userId, agent }. Hosted agents come with a pass. */
+  async function whoCalls (req, { pass = false } = {}) {
+    // An agent's access key (qa_) or app key (qk_, a sandbox's QUILT_AGENT_KEY).
+    if (!pass && isAgentKey(bearer(req))) {
+      const { agent } = await agentAuth.agentFromRequest(req)
+      return { account: `agent:${agent.id}`, kind: 'agent', userId: null, agent }
+    }
+    if (pass) {
+      const c = await reachCaller(req)
+      return c.agent ? { account: c.account, kind: 'agent', userId: null, agent: c.agent, hosted: /^QuiltPass\s/i.test(String(req.headers.authorization || '')) } : { account: c.account, kind: 'person', userId: c.userId, agent: null }
+    }
+    const p = await person(req)
+    return { account: `person:${p.userId}`, kind: 'person', userId: p.userId, agent: null }
+  }
+
+  /**
+   * One scope as a person reaches it: { type, id, name, levels, canManage, me }. Teams by slug
+   * (members see, the owner and Org settings: Update manage); workspaces by id (anyone who
+   * reaches it sees, admins manage); sessions by room (members see, the owner manages).
+   */
+  async function scopeOf (req, type, rawId) {
+    const me = await whoCalls(req)
+    if (me.kind !== 'person') throw new HttpError(403, 'agents use secrets through quilt run; people manage them')
+    if (type === 'org') {
+      const a = await orgAccess(store, me.userId, rawId)
+      return { type, id: a.org.id, name: a.org.name, slug: a.org.slug, levels: [{ type, id: a.org.id, name: a.org.name, slug: a.org.slug }], canManage: a.can('org', 'u'), me }
+    }
+    if (type === 'workspace') {
+      const r = await reach(req, needId(rawId, 'workspace'))
+      return { type, id: r.ws.id, name: r.ws.name, levels: await workspaceLevels(store, r.ws), canManage: !!r.access.admin, me, ws: r.ws }
+    }
+    const room = String(rawId)
+    if (!ROOM.test(room)) throw new HttpError(404, 'no such session')
+    const found = await roomLevels(store, room)
+    if (!found || !(await sessionMember(store, room, me.account))) throw new HttpError(404, 'no such session')
+    return { type, id: room, name: found.session.name || '', levels: found.levels, canManage: found.session.ownerAccount === me.account, me, session: found.session }
+  }
+
+  const needManage = (s) => { if (!s.canManage) throw new HttpError(403, s.type === 'org' ? 'Only the team\'s owner, or a role with Org settings: Update, manages team secrets.' : s.type === 'workspace' ? 'Only the workspace\'s admins manage its secrets.' : 'Only the session owner manages its secrets.') }
+
+  const rowView = (s, level, extra = {}) => ({
+    id: s.id, name: s.name, level: level.type, levelName: level.name || '', digest: shortDigest(s.digest), upstream: s.upstream,
+    format: s.format, formatId: formatId(s.format), formatLabel: formatLabel(s.format), who: s.who, usedAt: s.lastUsedAt ?? null, updatedAt: s.updatedAt, ...extra
+  })
+
+  async function settingsView (settings) {
+    return {
+      inheritOff: !!settings.inheritOff,
+      inheritOffBy: settings.inheritOff && settings.inheritOffBy ? await nameOf(settings.inheritOffBy) : '',
+      inheritOffAt: settings.inheritOff ? settings.inheritOffAt ?? null : null,
+      agentsOn: !!settings.agentsOn,
+      agents: settings.agents === 'all' || !Array.isArray(settings.agents) ? 'all' : settings.agents
+    }
+  }
+
+  /** Agents one may pick for "Agents can use secrets": the scope's agents and the caller's own. */
+  async function agentChoices (s) {
+    const ids = new Set()
+    for (const a of await store.listPersonalAgents(s.me.userId)) ids.add(a.id)
+    if (s.type === 'org') for (const a of await store.listOrgAgents(s.id)) ids.add(a.id)
+    if (s.type === 'workspace') {
+      for (const m of await store.listWorkspaceMembers(s.id)) if (m.account.startsWith('agent:')) ids.add(m.account.slice(6))
+      if (s.ws.orgId) for (const a of await store.listOrgAgents(s.ws.orgId)) ids.add(a.id)
+    }
+    if (s.type === 'session') {
+      for (const g of await store.listGrants(s.id)) if (g.account.startsWith('agent:')) ids.add(g.account.slice(6))
+      for (const v of await store.visitsInRooms([s.id])) if (v.account.startsWith('agent:')) ids.add(v.account.slice(6))
+    }
+    const out = []
+    for (const id of ids) { const a = await store.agentById(id).catch(() => null); if (a && !a.revokedAt) out.push({ id: a.id, name: a.name }) }
+    return out.sort((a, b) => a.name.localeCompare(b.name))
+  }
+
+  async function scopeView (s) {
+    const { levels, effective } = await resolveLevels(store, s.levels)
+    const [own, ...parents] = levels
+    const inherited = []
+    for (const l of parents) {
+      for (const sec of l.secrets) {
+        const winner = effective.get(sec.name)
+        const overridden = !l.off && winner && winner.secret.id !== sec.id
+        inherited.push(rowView(sec, l, { off: l.off, overridden: !!overridden }))
+      }
+    }
+    return {
+      scope: { type: s.type, id: s.id, name: s.name, ...(s.slug ? { slug: s.slug } : {}) },
+      // The address of each level's own page: a team by its slug.
+      levels: s.levels.map((l) => ({ type: l.type, id: l.type === 'org' ? l.slug : l.id, name: l.name })),
+      canManage: s.canManage,
+      settings: await settingsView(own.settings),
+      secrets: own.secrets.map((sec) => rowView(sec, own)),
+      inherited,
+      offCount: inherited.filter((r) => r.off).length,
+      agentChoices: s.canManage ? await agentChoices(s) : [],
+      vault: vaultAt()
+    }
+  }
+
+  function cleanEntries (entries) {
+    if (!Array.isArray(entries) || !entries.length) throw new HttpError(400, 'Say which secrets to save.')
+    if (entries.length > MAX_ENTRIES) throw new HttpError(400, `At most ${MAX_ENTRIES} secrets at once.`)
+    const seen = new Set()
+    return entries.map((e) => {
+      try {
+        const name = cleanSecretName(e && e.name)
+        if (seen.has(name)) throw new Error(`${name} is there twice.`)
+        seen.add(name)
+        const who = WHO.includes(e.who) ? e.who : 'agents'
+        return { name, upstream: cleanUpstream(e.upstream, { allowLocal: allowLocalUpstreams }), format: cleanFormat(e.format ?? 'bearer'), who }
+      } catch (err) { throw new HttpError(400, `${e && e.name ? `${String(e.name).slice(0, 64)}: ` : ''}${err.message}`) }
+    })
+  }
+
+  // ---------------------------------------------------------------- runs (`quilt run`) --
+
+  /** What each name the session reaches comes to for this caller (and run): [{ name, level, …, state, why }]. */
+  async function namesFor (room, who, run = null) {
+    const found = await roomLevels(store, room)
+    if (!found) return null
+    const { effective } = await resolveLevels(store, found.levels)
+    const asks = run ? new Map((await store.listSecretRunAsks(run.id)).map((a) => [a.secretId, a])) : null
+    const out = []
+    for (const [name, { secret, level }] of [...effective].sort(([a], [b]) => a.localeCompare(b))) {
+      const verdict = mayUse({ kind: who.kind, agentId: who.agent?.id || null, secret, level, ask: asks ? asks.get(secret.id) || null : undefined })
+      out.push({ name, secretId: secret.id, level: level.type, levelName: level.name || '', upstream: secret.upstream, who: secret.who, state: verdict.state, ...(verdict.why ? { why: verdict.why } : {}), env: envVarsFor(name, secret.upstream) })
+    }
+    return out
+  }
+
+  const publicNames = (list) => list.map(({ secretId, ...rest }) => rest)
+
+  async function runOf (id, me) {
+    const run = await store.secretRunById(needId(id, 'run'))
+    if (!run || run.account !== me.account) throw new HttpError(404, 'no such run')
+    return run
+  }
+
+  const runLive = (run) => run && !run.revokedAt && run.expiresAt > now()
+
+  // ---------------------------------------------------------------- the vault's routes --
+
+  function needVault (req) {
+    const got = Buffer.from(String(req.headers['x-quilt-vault-secret'] || ''))
+    const want = Buffer.from(String(vaultSecret))
+    if (!vaultSecret || got.length !== want.length || !crypto.timingSafeEqual(got, want)) throw new HttpError(401, 'vault only')
+  }
+
+  const usesLogged = new Map() // `${run}\n${secret}` -> at
+
+  const routes = [
+    ['GET', new RegExp(`^/v1/secrets/${SCOPE}/([^/]+)$`), async (req, body, [type, id]) => scopeView(await scopeOf(req, type, id))],
+
+    ['PUT', new RegExp(`^/v1/secrets/${SCOPE}/([^/]+)/settings$`), async (req, body, [type, id]) => {
+      const s = await scopeOf(req, type, id)
+      needManage(s)
+      const patch = {}
+      if (body.inheritOff !== undefined) {
+        if (s.levels.length < 2) throw new HttpError(400, s.type === 'org' ? 'A team has nothing above it to switch off.' : 'Nothing above this to switch off: it is not in a workspace or team.')
+        patch.inheritOff = body.inheritOff === true
+        patch.inheritOffBy = patch.inheritOff ? s.me.account : null
+        patch.inheritOffAt = patch.inheritOff ? now() : null
+      }
+      if (body.agentsOn !== undefined) patch.agentsOn = body.agentsOn === true
+      if (body.agents !== undefined) {
+        if (body.agents === 'all') patch.agents = 'all'
+        else if (Array.isArray(body.agents) && body.agents.length <= 100) patch.agents = [...new Set(body.agents.map((a) => needId(a, 'agent')))]
+        else throw new HttpError(400, 'agents is "all" or a list of agent ids')
+      }
+      await store.putSecretSettings(s.type, s.id, patch)
+      return scopeView(s)
+    }],
+
+    // A write ticket: what this person may save here, once, for five minutes. The value goes
+    // from their app or browser straight to the vault (POST <vault>/v1/write), never through here.
+    ['POST', new RegExp(`^/v1/secrets/${SCOPE}/([^/]+)/tickets$`), async (req, body, [type, id]) => {
+      const s = await scopeOf(req, type, id)
+      needManage(s)
+      limit(`ticket:${s.me.account}`, 30, 'too many saves; wait a minute')
+      const entries = cleanEntries(body.entries)
+      const ticket = newToken('qst_')
+      const expiresAt = now() + TICKET_TTL_MS
+      await store.createSecretTicket({ tokenHash: hashToken(ticket), scopeType: s.type, scopeId: s.id, entries, createdBy: s.me.account, expiresAt })
+      return { ticket, vault: vaultAt(), expiresAt, names: entries.map((e) => e.name) }
+    }],
+
+    ['GET', new RegExp(`^/v1/secrets/${SCOPE}/([^/]+)/uses$`), async (req, body, [type, id]) => {
+      const s = await scopeOf(req, type, id)
+      needManage(s)
+      const secrets = await store.listSecrets(s.type, s.id)
+      const byId = new Map(secrets.map((x) => [x.id, x.name]))
+      const uses = await store.listSecretUses(secrets.map((x) => x.id), { limit: 100 })
+      const names = new Map()
+      const out = []
+      for (const u of uses) {
+        if (!names.has(u.account)) names.set(u.account, await nameOf(u.account))
+        out.push({ name: byId.get(u.secretId) || '', account: u.account, accountName: names.get(u.account), room: u.room, upstream: u.upstream, at: u.at })
+      }
+      return { uses: out }
+    }],
+
+    // Who can use it: agents, or people only. The host and format change only with a new value.
+    ['PATCH', new RegExp(`^/v1/secrets/${SCOPE}/([^/]+)/${NAME}$`), async (req, body, [type, id, name]) => {
+      const s = await scopeOf(req, type, id)
+      needManage(s)
+      if (body.upstream !== undefined || body.format !== undefined) throw new HttpError(400, 'Where a secret goes and how changes only with its value: use Replace.')
+      if (!WHO.includes(body.who)) throw new HttpError(400, 'who is agents or people')
+      const sec = await store.secretByName(s.type, s.id, name)
+      if (!sec) throw new HttpError(404, 'no such secret')
+      await store.updateSecret(sec.id, { who: body.who, updatedBy: s.me.account })
+      return scopeView(s)
+    }],
+
+    ['DELETE', new RegExp(`^/v1/secrets/${SCOPE}/([^/]+)/${NAME}$`), async (req, body, [type, id, name]) => {
+      const s = await scopeOf(req, type, id)
+      needManage(s)
+      const sec = await store.secretByName(s.type, s.id, name)
+      if (!sec || !(await store.deleteSecret(sec.id))) throw new HttpError(404, 'no such secret')
+      return scopeView(s)
+    }],
+
+    // The names a session reaches, for its members (people, agents with a key, hosted agents
+    // with a pass): where each goes, who can use it, whether the caller can, and the variables
+    // `quilt run` sets. Never a value.
+    ['GET', /^\/v1\/sessions\/([^/]+)\/secret-names$/, async (req, body, [room]) => {
+      const me = await whoCalls(req, { pass: /^QuiltPass\s/i.test(String(req.headers.authorization || '')) })
+      if (!ROOM.test(room) || !(await sessionMember(store, room, me.account, { agent: me.agent }))) throw new HttpError(404, 'no such session')
+      const names = await namesFor(room, me)
+      if (!names) throw new HttpError(404, 'no such session')
+      return { room, kind: me.kind, hosted: !!me.hosted, names: publicNames(names) }
+    }],
+
+    // A run token for `quilt run`: one member, one session, one hour. A person's people-only
+    // secrets wait for them to allow each in the app; an agent never gets them.
+    ['POST', /^\/v1\/secret-runs$/, async (req, body) => {
+      const me = await whoCalls(req)
+      if (me.hosted) throw new HttpError(403, 'Hosted agents run no commands, so they use no secrets.')
+      const room = String(body.room || '')
+      if (!ROOM.test(room) || !(await sessionMember(store, room, me.account, { agent: me.agent }))) throw new HttpError(404, 'no such session')
+      limit(`run:${me.account}`, 120, 'too many runs; wait a minute')
+      const names = await namesFor(room, me)
+      if (!names) throw new HttpError(404, 'no such session')
+      const label = String(body.label || '').replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, MAX_LABEL) // eslint-disable-line no-control-regex
+      const token = newToken('qrun_')
+      const run = await store.createSecretRun({ tokenHash: hashToken(token), room, account: me.account, kind: me.kind, label, expiresAt: now() + RUN_TTL_MS })
+      const asked = names.filter((n) => n.state === 'ask')
+      if (asked.length) {
+        await store.putSecretRunAsks(run.id, asked.map((n) => ({ secretId: n.secretId, name: n.name })))
+        wake(`asks:${me.account}`)
+      }
+      return { run: { id: run.id, room, expiresAt: run.expiresAt }, token, vault: vaultAt(), secrets: publicNames(await namesFor(room, me, run)) }
+    }],
+
+    // Holds until no secret of the run is waiting for the person (or 25 seconds): its secrets' states.
+    ['POST', /^\/v1\/secret-runs\/([^/]+)\/wait$/, async (req, body, [id]) => {
+      const me = await whoCalls(req)
+      const run = await runOf(id, me)
+      const waiting = async () => (await store.listSecretRunAsks(run.id)).some((a) => a.state === 'asked')
+      await waitUntil(`run:${run.id}`, async () => !(await waiting()), Math.min(Number(body.waitMs) || waitMs, waitMs))
+      return { run: { id: run.id, room: run.room, expiresAt: run.expiresAt, live: runLive(run) }, secrets: publicNames(await namesFor(run.room, me, run) || []) }
+    }],
+
+    // Ends a run at once: by its member (quilt run does when its command ends) or the session's owner.
+    ['DELETE', /^\/v1\/secret-runs\/([^/]+)$/, async (req, body, [id]) => {
+      const me = await whoCalls(req)
+      const run = await store.secretRunById(needId(id, 'run'))
+      const owner = run && (await store.sessionByRoom(run.room))?.ownerAccount === me.account
+      if (!run || (run.account !== me.account && !owner)) throw new HttpError(404, 'no such run')
+      await store.revokeSecretRun(run.id, now())
+      await store.answerSecretRunAsks(run.id, 'denied', now())
+      wake(`run:${run.id}`)
+      return { ok: true }
+    }],
+
+    // The app's inline confirm: runs of this person's waiting for them to allow people-only
+    // secrets. ?wait=1 holds until there is one (or 25 seconds).
+    ['GET', /^\/v1\/me\/secret-asks$/, async (req) => {
+      const me = await whoCalls(req)
+      if (me.kind !== 'person') throw new HttpError(403, 'only people allow secrets')
+      const q = new URL(req.url, 'http://x').searchParams
+      const list = () => store.pendingSecretAsks(me.account, now())
+      let pending = await list()
+      if (!pending.length && q.get('wait')) pending = (await waitUntil(`asks:${me.account}`, async () => { const p = await list(); return p.length ? p : null }, waitMs)) || []
+      const asks = []
+      for (const { run, asks: a } of pending) {
+        const s = await store.sessionByRoom(run.room)
+        asks.push({ runId: run.id, room: run.room, sessionName: s?.name || '', label: run.label, names: a.map((x) => x.name), askedAt: Math.min(...a.map((x) => x.askedAt)) })
+      }
+      return { asks }
+    }],
+
+    ['POST', /^\/v1\/me\/secret-asks\/([^/]+)$/, async (req, body, [id]) => {
+      const me = await whoCalls(req)
+      if (me.kind !== 'person') throw new HttpError(403, 'only people allow secrets')
+      const run = await runOf(id, me)
+      if (!runLive(run)) throw new HttpError(410, 'that run has ended')
+      const n = await store.answerSecretRunAsks(run.id, body.allow === true ? 'allowed' : 'denied', now())
+      wake(`run:${run.id}`)
+      return { ok: true, answered: n }
+    }],
+
+    // ------------------------------------------------ internal: the vault, by shared secret --
+
+    // A write ticket, once: what may be saved, where, and the scope's current data key.
+    ['POST', /^\/v1\/vault\/tickets\/redeem$/, async (req, body) => {
+      needVault(req)
+      const t = await store.redeemSecretTicket(hashToken(String(body.ticket || '')), now())
+      if (!t) throw new HttpError(401, 'this save link has expired or was used; try again')
+      const dk = await store.secretDataKey(t.scopeType, t.scopeId)
+      return { ticketId: t.id, scope: { type: t.scopeType, id: t.scopeId }, entries: t.entries, by: t.createdBy, dataKey: dk && { version: dk.version, sealedKey: dk.sealedKey, provider: dk.provider } }
+    }],
+
+    ['POST', /^\/v1\/vault\/data-keys$/, async (req, body) => {
+      needVault(req)
+      const { scopeType, scopeId, version, sealedKey, provider } = body
+      if (!['org', 'workspace', 'session'].includes(scopeType) || !scopeId || !Number.isInteger(version) || version < 1 || typeof sealedKey !== 'string' || !['env', 'aws-kms'].includes(provider)) throw new HttpError(400, 'bad data key')
+      const dk = await store.putSecretDataKey({ scopeType, scopeId: String(scopeId), version, sealedKey, provider })
+      return { dataKey: { version: dk.version, sealedKey: dk.sealedKey, provider: dk.provider } }
+    }],
+
+    // Sealed values for a redeemed ticket, stored with the ticket's names, hosts and formats.
+    ['POST', /^\/v1\/vault\/secrets$/, async (req, body) => {
+      needVault(req)
+      const t = await store.secretTicketById(needId(body.ticketId, 'ticket'))
+      if (!t || !t.redeemedAt || now() - t.redeemedAt > TICKET_TTL_MS) throw new HttpError(401, 'this save link has expired; try again')
+      const items = Array.isArray(body.items) ? body.items : []
+      const entries = new Map(t.entries.map((e) => [e.name, e]))
+      if (!items.length || items.some((i) => !entries.has(i?.name) || typeof i.sealedValue !== 'string' || !DIGEST.test(String(i.digest)) || !Number.isInteger(i.keyVersion))) throw new HttpError(400, 'those are not the names this save was for')
+      if (!(await store.markSecretTicketStored(t.id, now()))) throw new HttpError(409, 'this save was already stored')
+      const saved = []
+      for (const i of items) {
+        const e = entries.get(i.name)
+        const row = await store.putSecret({ scopeType: t.scopeType, scopeId: t.scopeId, name: e.name, sealedValue: i.sealedValue, keyVersion: i.keyVersion, digest: i.digest, upstream: e.upstream, format: e.format, who: e.who, by: t.createdBy })
+        saved.push({ name: row.name, id: row.id })
+      }
+      log(`secrets: ${saved.length} saved in ${t.scopeType} ${t.scopeId} by ${t.createdBy}`)
+      return { saved }
+    }],
+
+    // One gateway request: may this run use this name now? The answer carries the sealed value
+    // and its sealed data key, for the vault to open; every use is logged (once a minute).
+    ['POST', /^\/v1\/vault\/resolve$/, async (req, body) => {
+      needVault(req)
+      const run = await store.secretRunByToken(hashToken(String(body.token || '')))
+      if (!runLive(run)) throw new HttpError(401, 'this run has ended (or was revoked): start the command again with quilt run')
+      const name = String(body.name || '')
+      const [kind, id] = run.account.split(':')
+      const agent = kind === 'agent' ? await store.agentById(id).catch(() => null) : null
+      if (kind === 'agent' && (!agent || agent.revokedAt)) throw new HttpError(401, 'this agent was revoked')
+      if (!(await sessionMember(store, run.room, run.account, { agent }))) throw new HttpError(403, 'not in this session any more')
+      const found = await roomLevels(store, run.room)
+      const { effective } = await resolveLevels(store, found ? found.levels : [])
+      const hit = effective.get(name)
+      if (!hit) throw new HttpError(404, `${name.slice(0, 64)} is not a secret in this session (or it is switched off here)`)
+      const ask = run.kind === 'person' && hit.secret.who === 'people' ? (await store.listSecretRunAsks(run.id)).find((a) => a.secretId === hit.secret.id) || null : undefined
+      const verdict = mayUse({ kind: run.kind, agentId: agent?.id || null, secret: hit.secret, level: hit.level, ask })
+      if (!verdict.ok) throw new HttpError(403, `${name}: ${verdict.why}`)
+      const sealed = await store.secretSealed(hit.secret.id)
+      const dk = await store.secretDataKeyVersion(hit.secret.scopeType, hit.secret.scopeId, sealed.keyVersion)
+      const key = `${run.id}\n${hit.secret.id}`
+      if (!usesLogged.has(key) || now() - usesLogged.get(key) >= USE_LOG_MS) {
+        usesLogged.set(key, now())
+        if (usesLogged.size > 50_000) usesLogged.delete(usesLogged.keys().next().value)
+        await store.recordSecretUse({ secretId: hit.secret.id, runId: run.id, room: run.room, account: run.account, upstream: hit.secret.upstream, at: now() }).catch((err) => log(`secret use log: ${err.message}`))
+      }
+      return {
+        run: { id: run.id },
+        secret: { id: hit.secret.id, name, scopeType: hit.secret.scopeType, scopeId: hit.secret.scopeId, upstream: hit.secret.upstream, format: hit.secret.format, sealedValue: sealed.sealedValue, keyVersion: sealed.keyVersion },
+        dataKey: { version: dk.version, sealedKey: dk.sealedKey, provider: dk.provider }
+      }
+    }]
+  ]
+  // Off (a plain 503) until the vault is set up: QUILT_VAULT_SECRET on this API.
+  const on = (fn) => (...args) => {
+    if (!vaultSecret) throw new HttpError(503, 'Secrets are not switched on on this server yet.')
+    return fn(...args)
+  }
+  return routes.map(([method, pattern, fn, ...rest]) => [method, pattern, on(fn), ...rest])
+}
+
+export { LEVEL_WORDS }

package/src/api/routes/workspaces.js

@@ -15,7 +15,7 @@ const ACCOUNT = /^(person|agent):[A-Za-z0-9_-]{1,64}$/
 const OPEN_MS = 10 * 60 * 1000
 
 export function workspaceRoutes (ctx) {
-  const { store, now, files: fileStore, workspaces = false, log = () => {} } = ctx
+  const { store, now, files: fileStore, workspaces = false, log = () => {}, policyChanged = null } = ctx
   const { caller, grantsIn, reach } = workspaceReach(ctx)
   /** A handler that answers 404 while the flag is off (a route's own 404, not a missing route). */
   const gated = (fn) => (...args) => {
@@ -163,7 +163,11 @@ export function workspaceRoutes (ctx) {
         for (const v of await store.listWorkspaceFileVersions(f.id)) if (v.objectKey) keys.push(v.objectKey)
       }
       if (fileStore) await removeObjects(fileStore, keys, log)
+      const had = (await store.listWorkspaceSessions(r.ws.id)).length
+      // Its secrets go with it (sealed blobs nobody could reach again); never in the way of the delete.
+      await store.deleteScopeSecrets('workspace', r.ws.id).catch((err) => log(`workspace secrets: ${err.message}`))
       await store.deleteWorkspace(r.ws.id)
+      if (had && policyChanged) policyChanged() // its sessions leave it, and its git rule with them
       return { ok: true }
     }],
 
@@ -204,6 +208,8 @@ export function workspaceRoutes (ctx) {
       const existing = await store.sessionByRoom(room)
       if (existing && existing.ownerAccount && existing.ownerAccount !== r.me.account) throw new HttpError(403, 'only the session owner can move it')
       const session = await store.setSessionWorkspace(room, r.ws.id, { linkedBy: r.me.account, at: now() })
+      // The relay asked for the session's git rule when it made the room, before this link: it asks again now.
+      if (policyChanged) policyChanged(room)
       // Its people come along when the owner manages the workspace; an editor's move leaves
       // the workspace's people as they are, and says so (`peopleNeedAdmin`).
       const owner = existing && existing.ownerAccount === r.me.account
@@ -218,6 +224,7 @@ export function workspaceRoutes (ctx) {
       if (!s || s.workspaceId !== r.ws.id) throw new HttpError(404, 'that session is not in this workspace')
       if (s.ownerAccount !== r.me.account && !r.access.admin) throw new HttpError(403, 'only the session owner or a workspace admin can do that')
       await store.setSessionWorkspace(room, null, { linkedBy: null, at: now() })
+      if (policyChanged) policyChanged(room) // the workspace's rule no longer covers it
       return { ok: true }
     }]
   ]

package/src/api/sandbox-keys.js

@@ -0,0 +1,57 @@
+// Sandbox keys (QUILT_AGENT_KEY, ui/agent-env-key.js) as their person sees them on heyquilt.com
+// and in the app: each one's use over the last seven days, whether it is in use, a short hint
+// to tell it apart, and the session it works in. The session's invite link is kept so Rotate
+// can make the same key again, sealed: a copy of the database alone never reads as the link.
+import crypto from 'node:crypto'
+
+/** Used this recently: In use. Otherwise Idle. */
+export const IN_USE_MS = 60 * 60 * 1000
+export const USE_DAYS = 7
+const DAY_MS = 24 * 60 * 60 * 1000
+
+/** The UTC date of a moment, YYYY-MM-DD: requests are counted per key per day. */
+export const dayOf = (ms) => new Date(ms).toISOString().slice(0, 10)
+
+/** The last `n` days, oldest first, ending with today's. */
+export const lastDays = (at, n = USE_DAYS) => Array.from({ length: n }, (_, i) => dayOf(at - (n - 1 - i) * DAY_MS))
+
+/** A key's use rows ({ day, count }) as one count per day of the last seven, oldest first. */
+export function usesByDay (rows, at) {
+  const by = new Map(rows.map((r) => [r.day, r.count]))
+  return lastDays(at).map((d) => by.get(d) || 0)
+}
+
+/** 'revoked', 'in-use' (used in the last hour) or 'idle'. */
+export function keyState (row, at) {
+  if (row.revokedAt) return 'revoked'
+  return row.lastUsedAt && at - row.lastUsedAt < IN_USE_MS ? 'in-use' : 'idle'
+}
+
+/** The last four characters of a key: shown to tell keys apart, never enough to use one. */
+export const hintOf = (key) => String(key).slice(-4)
+
+/**
+ * Seals and opens session links with AES-256-GCM under a key derived from `secret` (the API's
+ * pass key). Without one, a random key for this process: links then open until it restarts.
+ */
+export function linkSealer (secret) {
+  const key = Buffer.from(crypto.hkdfSync('sha256', secret ? String(secret) : crypto.randomBytes(32), 'quilt sandbox keys', 'session link', 32))
+  const b64 = (b) => b.toString('base64url')
+  return {
+    seal (text) {
+      const iv = crypto.randomBytes(12)
+      const c = crypto.createCipheriv('aes-256-gcm', key, iv)
+      const body = Buffer.concat([c.update(String(text), 'utf8'), c.final()])
+      return `v1.${b64(iv)}.${b64(c.getAuthTag())}.${b64(body)}`
+    },
+    open (sealed) {
+      const [v, iv, tag, body] = String(sealed || '').split('.')
+      if (v !== 'v1' || !iv || !tag || body === undefined) return null
+      try {
+        const d = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'base64url'))
+        d.setAuthTag(Buffer.from(tag, 'base64url'))
+        return Buffer.concat([d.update(Buffer.from(body, 'base64url')), d.final()]).toString('utf8')
+      } catch { return null }
+    }
+  }
+}

package/src/api/secrets-access.js

@@ -0,0 +1,93 @@
+// Secrets (docs/superpowers/specs/2026-10-18-secrets.md): which secrets a session reaches, and
+// who may use which. Pure apart from store reads. Never touches a sealed value: the routes hand
+// that to the vault alone (routes/secrets.js, /v1/vault/resolve).
+import { roomAccessFrom } from './access.js'
+import { cloudAiOf } from './routes/ai-vm.js'
+
+export const LEVEL_WORDS = { org: 'Team', workspace: 'Workspace', session: 'Session' }
+
+/**
+ * Whether `account` is one of the session's members: its owner, someone with a grant or let in
+ * by the session's workspace, or someone who came in by the invite link and wasn't removed
+ * since. A person's cloud AI stands where its person does.
+ */
+export async function sessionMember (store, room, account, { agent = null } = {}) {
+  if ((await roomAccessFrom(store, room, account)).access) return true
+  const visits = (await store.visitsInRooms([room])).filter((v) => v.account === account)
+  if (visits.length && visits.at(-1).endReason !== 'removed') return true
+  if (agent) {
+    const vm = await cloudAiOf(store, agent)
+    if (vm) return sessionMember(store, room, `person:${vm.userId}`)
+  }
+  return false
+}
+
+/**
+ * A session's levels, nearest first: [{ type, id, name }] for the session, its workspace and
+ * the workspace's org (Team). null when the API doesn't know the session yet.
+ */
+export async function roomLevels (store, room) {
+  const session = await store.sessionByRoom(room)
+  if (!session) return null
+  const levels = [{ type: 'session', id: room, name: session.name || '' }]
+  const ws = session.workspaceId ? await store.workspaceById(session.workspaceId) : null
+  if (ws) levels.push({ type: 'workspace', id: ws.id, name: ws.name })
+  if (ws && ws.orgId) levels.push(await orgLevel(store, ws.orgId))
+  return { session, levels }
+}
+
+/** A workspace's levels: itself and its org. */
+export async function workspaceLevels (store, ws) {
+  const levels = [{ type: 'workspace', id: ws.id, name: ws.name }]
+  if (ws.orgId) levels.push(await orgLevel(store, ws.orgId))
+  return levels
+}
+
+async function orgLevel (store, orgId) {
+  const org = await store.orgById(orgId)
+  return { type: 'org', id: orgId, name: org?.name || '', slug: org?.slug || '' }
+}
+
+/**
+ * Every level's secrets and settings, and what each name comes to here: { levels (with
+ * `settings`, `secrets` and `off`), effective: Map name -> { secret, level } }. A level is off
+ * when a nearer level switched inherited secrets off (a session for its workspace and team, a
+ * workspace for its team). The nearest level that is on wins a name.
+ */
+export async function resolveLevels (store, levels) {
+  const out = []
+  let off = false
+  for (const [i, l] of levels.entries()) {
+    const settings = await store.secretSettings(l.type, l.id)
+    const secrets = await store.listSecrets(l.type, l.id)
+    out.push({ ...l, settings, secrets, off: i > 0 && off })
+    if (settings.inheritOff) off = true
+  }
+  const effective = new Map()
+  for (const l of out) {
+    if (l.off) continue
+    for (const s of l.secrets) if (!effective.has(s.name)) effective.set(s.name, { secret: s, level: l })
+  }
+  return { levels: out, effective }
+}
+
+/**
+ * Whether a run (or a caller, with no run) may use a secret: { ok } or { ok: false, why, state }.
+ * Agents: only secrets for agents, in a scope with agents on that chose them (or all). People:
+ * every secret; a people-only one once they allowed it for this run (`ask`: its ask row).
+ */
+export function mayUse ({ kind, agentId = null, secret, level, ask = undefined }) {
+  if (kind === 'agent') {
+    if (secret.who === 'people') return { ok: false, state: 'refused', why: 'people only: agents never get it' }
+    const s = level.settings
+    if (!s.agentsOn) return { ok: false, state: 'refused', why: `agents can't use ${LEVEL_WORDS[level.type].toLowerCase()} secrets here (switched off)` }
+    if (s.agents !== 'all' && !(Array.isArray(s.agents) && s.agents.includes(agentId))) return { ok: false, state: 'refused', why: 'this agent was not chosen to use secrets here' }
+    return { ok: true, state: 'ready' }
+  }
+  if (secret.who !== 'people') return { ok: true, state: 'ready' }
+  if (ask === undefined) return { ok: false, state: 'ask', why: 'people only: each run asks the person to allow it in the Quilt app' }
+  if (!ask) return { ok: false, state: 'refused', why: 'people only, and this run was not asked about it (it was added since): run the command again' }
+  if (ask.state === 'allowed') return { ok: true, state: 'ready' }
+  if (ask.state === 'denied') return { ok: false, state: 'refused', why: 'people only: not allowed for this run' }
+  return { ok: false, state: 'asked', why: 'people only: waiting for the person to allow it in the Quilt app' }
+}