heyquilt 0.0.1 → 0.3.90

package/src/api/server.js

@@ -0,0 +1,623 @@
+// src/api/server.js
+// The Quilt accounts API: links desktop apps to accounts (a device-code flow, like
+// signing in to a TV app) and manages agents. Plain node:http, like the relay.
+import http from 'node:http'
+import { pipeline } from 'node:stream/promises'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { newToken, hashToken, newUserCode, normalizeUserCode } from './tokens.js'
+import { parsePublicKey, verifyDeviceLink, verifyDeviceResume } from '../identity.js'
+import { signPass, passPublicKey, PASS_VERSION, PASS_TTL_MS } from '../passes.js'
+import { HttpError, Raw } from './http.js'
+import { DiskStore } from './file-store.js'
+import { contentDisposition } from './file-paths.js'
+import { orgRoutes } from './routes/orgs.js'
+import { memberRoutes } from './routes/members.js'
+import { teamRoutes } from './routes/teams.js'
+import { inviteRoutes } from './routes/invites.js'
+import { agentRoutes } from './routes/agents.js'
+import { makeAgentAuth, isAgentKey } from './agent-auth.js'
+import { agentInviteRoutes } from './routes/agent-invites.js'
+import { joinRoutes } from './routes/join.js'
+import { relayRoutes } from './routes/relay.js'
+import { relayClusterRoutes } from './routes/relay-cluster.js'
+import { relayCluster } from './relay-cluster.js'
+import crypto from 'node:crypto'
+import { githubRoutes } from './routes/github.js'
+import { githubApp, ensureWebhookSecret, redeliverFailed } from './github-app.js'
+import { sessionRoutes } from './routes/sessions.js'
+import { accessTypeRoutes } from './routes/access-types.js'
+import { grantRoutes } from './routes/grants.js'
+import { sessionInviteRoutes } from './routes/session-invites.js'
+import { workspaceRoutes } from './routes/workspaces.js'
+import { workspaceFileRoutes } from './routes/workspace-files.js'
+import { workspaceAgentRoutes } from './routes/workspace-agents.js'
+import { workspaceInviteRoutes } from './routes/workspace-invites.js'
+import { HOSTED_RELAY } from '../settings.js'
+import { roomAccessFrom } from './access.js'
+import { joiningRoom, sessionArg } from '../mcp-room.js'
+import { issueRoutes } from './routes/issues.js'
+import { aiVmRoutes, cloudAiOf, WAIT_MS as AI_VM_WAIT_MS } from './routes/ai-vm.js'
+import { personaName } from '../persona.js'
+import { CLOUD_LABEL } from '../cloud-ai.js'
+import { routeName, cleanEvent } from './issues.js'
+
+const API_VERSION = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf8')).version
+
+const LINK_TTL_MS = 10 * 60 * 1000
+const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+// An approved link the app never collects stops working this long after its code expires.
+const COLLECT_GRACE_MS = 5 * 60 * 1000
+// A linked computer signing back in with its key: how far its clock may be from ours.
+const RESUME_WINDOW_MS = 10 * 60 * 1000
+const POLL_INTERVAL_S = 3
+const MAX_BODY = 16 * 1024
+// A hosted agent's MCP request (a whole file, at most) and how long it may take on the relay.
+const MAX_MCP_BODY = 2 * 1024 * 1024
+// With workspaces on, room for a 2 MB library file sent as base64 (a third larger) and its call
+// around it: the relay's MCP reads up to 4 MB.
+const MAX_MCP_BODY_WORKSPACES = 4 * 1024 * 1024
+const MCP_TIMEOUT_MS = 30 * 1000
+// A pass minted for a hosted agent is reused until this close to its end: 5 minutes, so
+// a change to its grant reaches it as soon as it reaches a connected app.
+const PASS_REUSE_MARGIN_MS = 5 * 60 * 1000
+
+export function startApi ({ port = 0, host = '127.0.0.1', store, verifyUser, siteUrl, apiUrl = 'https://api.heyquilt.com', mailer = { send: async () => { throw new Error('no mailer configured') } }, now = Date.now, log = () => {}, startLimit = 10, inviteLimit = 10, inviteSendLimit = 20, tokenLimit = 30, joinLimit = 20, trustProxy = false, maxStartKeys = 10_000, passKey = '', passLimit = 60, relayUrl = HOSTED_RELAY, mcpLimit = 600, reportKey = '', reportLimit = 10, slowMs = 2000, pruneEveryMs = 60 * 60 * 1000, keepEventsMs = 30 * 24 * 60 * 60 * 1000, keepIssuesMs = 90 * 24 * 60 * 60 * 1000, pruneStartMs = 10_000, relaySecret = '', workspaces = false, fileStore = null, maxFileBytes = 500 * 1024 * 1024, workspaceQuotaBytes = 5 * 1024 * 1024 * 1024, maxWorkspaceFiles = 2000, webhookFetch = globalThis.fetch, webhookLookup, allowLocalWebhooks = false, github = null, githubFetch = globalThis.fetch, fly = null, aiVmWaitMs = AI_VM_WAIT_MS, relayFetch = null, relayFly = null, heavy = null, clusterTiming = {} }) {
+  // PASS_SIGNING_KEY. A bad one should stop the API at start, not fail every pass later.
+  if (passKey) passPublicKey(passKey)
+  const site = String(siteUrl || '').replace(/\/+$/, '')
+  // Where agents reach this API: invite links and the join instructions point here.
+  const api = String(apiUrl).replace(/\/+$/, '')
+  // Workspace files' bytes: the API's own disk (signed links it serves itself) unless a
+  // store (Supabase) was given. Defaulted so tests and a plain local run need nothing.
+  const files = fileStore || new DiskStore(fs.mkdtempSync(path.join(os.tmpdir(), 'quilt-api-files-')))
+  // The relay that hosts the agents' MCP (/mcp here hands requests on to it).
+  const relay = String(relayUrl).replace(/\/+$/, '').replace(/^ws(s?):\/\//, 'http$1://')
+
+  const bearer = (req) => (String(req.headers.authorization || '').match(/^Bearer\s+(.+)$/i) || [])[1] || ''
+  async function user (req) {
+    const u = await verifyUser(bearer(req))
+    if (!u) throw new HttpError(401, 'sign in first')
+    return u
+  }
+
+  async function device (req) {
+    const d = await store.deviceByToken(hashToken(bearer(req)))
+    if (!d) throw new HttpError(401, 'this computer is signed out')
+    await store.touchDevice(d.id)
+    return d
+  }
+
+  /** A signed-in person, from the website (JWT) or from the app on a linked computer (qd_ token). */
+  async function person (req) {
+    if (bearer(req).startsWith('qd_')) return { userId: (await device(req)).userId, email: '' }
+    return user(req)
+  }
+
+  // A few tries per minute per address is plenty for a person. Behind Fly,
+  // Fly-Client-IP is the real peer; X-Forwarded-For isn't used because Fly appends
+  // to whatever the client sent, so its first entry is client-controlled.
+  // `keyOf` lets a limiter key on something other than the caller's IP (e.g. a
+  // signed-in user id for invite sending) and `windowMs` lets it use a longer window.
+  function makeLimiter (limit, message, { windowMs = 60_000, keyOf } = {}) {
+    const hits = new Map()
+    const byIp = (req) => (trustProxy && String(req.headers['fly-client-ip'] || '').trim()) || req.socket.remoteAddress
+    const check = (req) => {
+      const key = (keyOf || byIp)(req)
+      const recent = (hits.get(key) || []).filter((t) => now() - t < windowMs)
+      if (recent.length >= limit) throw new HttpError(429, message)
+      hits.set(key, [...recent, now()])
+      // Keep the map bounded: forget keys with nothing in the last window.
+      if (hits.size > maxStartKeys) for (const [k, ts] of hits) if (ts.every((t) => now() - t >= windowMs)) hits.delete(k)
+    }
+    check.size = () => hits.size
+    return check
+  }
+  const limitStarts = makeLimiter(startLimit, 'too many sign-in attempts; try again in a minute')
+  const limitInvites = makeLimiter(inviteLimit, 'too many tries; wait a minute and try again')
+  // Sending (or resending) an email invite, capped per signed-in user rather than per IP.
+  const limitInviteSend = makeLimiter(inviteSendLimit, 'too many invites sent; wait a bit and try again', { windowMs: 60 * 60_000, keyOf: (userId) => userId })
+  const limitTokens = makeLimiter(tokenLimit, 'too many key refreshes; try again in a minute')
+  const limitJoin = makeLimiter(joinLimit, 'too many tries; wait a minute and try again')
+  // Session-started hand-offs, per room: a session is announced once, so a few covers retries.
+  const limitAnnounce = makeLimiter(5, 'this session was announced a moment ago', { windowMs: 10 * 60_000, keyOf: (room) => room })
+  // Passes, per token (keyed on its hash, counted once the token checks out).
+  const limitPasses = makeLimiter(passLimit, 'too many passes; try again in a minute', { keyOf: (tokenHash) => tokenHash })
+  // Reports with no sign-in (the app before it's linked): a few batches a minute per address.
+  const limitReports = makeLimiter(reportLimit, 'too many reports; try again in a minute')
+  const agentAuth = makeAgentAuth({ store, now, bearer })
+  // Hosted MCP calls, per agent.
+  const limitMcp = makeLimiter(mcpLimit, 'too many requests; slow down', { keyOf: (agentId) => agentId })
+
+  /** Who a pass is for: a linked computer's account, or an agent and the key it registered. */
+  async function passHolder (req) {
+    if (isAgentKey(bearer(req))) {
+      const { agent } = await agentAuth.agentFromRequest(req)
+      // No key: a hosted agent. Its pass works over HTTPS (the relay's /mcp), never for a WebSocket.
+      return agentHolder(agent)
+    }
+    const d = await device(req)
+    const p = await store.profile(d.userId)
+    return { sub: d.userId, kind: 'person', name: ((p && p.name) || 'Quilt user').slice(0, 64), key: d.publicKey }
+  }
+
+  /**
+   * Who a pass for an agent is for. A person's cloud AI (routes/ai-vm.js) is one of its person's
+   * AI sessions: named like one ("Dan · cloud"), with its person's account (`of`) and name
+   * (`ofName`), which the relay lets in where its person stands.
+   */
+  async function agentHolder (agent) {
+    const holder = { sub: agent.id, kind: 'agent', name: agent.name.slice(0, 64), key: agent.publicKey || '' }
+    const vm = await cloudAiOf(store, agent)
+    if (!vm) return holder
+    const p = await store.profile(vm.userId)
+    const person = String((p && p.name) || 'Quilt user').slice(0, 64)
+    return { ...holder, name: personaName(person, CLOUD_LABEL).slice(0, 64), of: `person:${vm.userId}`, ofName: person }
+  }
+
+  // Resume signatures seen in the last window, so a copied one can't be used again: here, and in
+  // the store, so it can't be used once on each API machine either.
+  const usedResumes = new Map() // signature -> at
+  async function spendResume (signature, at) {
+    for (const [sig, t] of usedResumes) if (Math.abs(now() - t) > RESUME_WINDOW_MS) usedResumes.delete(sig)
+    if (usedResumes.has(signature)) throw new HttpError(401, 'that sign-in was already used')
+    usedResumes.set(signature, at)
+    let fresh = true
+    try { fresh = await store.spendResumeSignature(crypto.createHash('sha256').update(signature).digest('hex'), RESUME_WINDOW_MS) } catch (err) { log(`resume signatures: ${err?.message || err}`) }
+    if (!fresh) throw new HttpError(401, 'that sign-in was already used')
+  }
+
+  const needPassKey = () => { if (!passKey) throw new HttpError(503, 'passes are not set up on this server') }
+
+  /**
+   * A signed pass for `holder`. For a room, it also carries the room, when it was issued
+   * (the relay won't let an older pass undo a removal), what its holder may do there
+   * (see access.js), and a person's confirmed email.
+   */
+  async function mintPass (holder, room) {
+    const iat = now()
+    const exp = iat + PASS_TTL_MS
+    const payload = { v: PASS_VERSION, ...holder, exp }
+    if (room) {
+      // A person's cloud AI has its person's grant here (agentHolder).
+      const personId = holder.kind === 'person' ? holder.sub : holder.of ? holder.of.slice('person:'.length) : null
+      const mail = personId ? await store.userEmail(personId) : null
+      const email = mail?.confirmed ? String(mail.email || '').toLowerCase() : ''
+      let { access, from } = await roomAccessFrom(store, room, holder.of || `${holder.kind}:${holder.sub}`, email)
+      // The owner's AI edits like them, but is never the owner.
+      if (holder.of && access && access.owner) { const { owner, ...rest } = access; access = rest; from = null }
+      // `from`: why they may (a grant here, the workspace, the org), shown on the session's member list.
+      Object.assign(payload, { room, iat, access }, from ? { from } : {}, email && holder.kind === 'person' ? { email } : {})
+    }
+    return { pass: signPass(payload, passKey), expiresAt: exp }
+  }
+
+  /** A person's profile and sign-in email, which the app keeps in account.json. */
+  async function profileWithEmail (userId) {
+    const p = await store.profile(userId)
+    return p && { ...p, email: (await store.userEmail(userId))?.email || '' }
+  }
+
+  const COLOR = /^#[0-9a-fA-F]{6}$/
+  function cleanProfile (b) {
+    const out = {}
+    if (b.name !== undefined) { const n = String(b.name).trim().slice(0, 60); if (!n) throw new HttpError(400, 'name is empty'); out.name = n }
+    if (b.color !== undefined) { if (b.color !== null && !COLOR.test(b.color)) throw new HttpError(400, 'color must be #RRGGBB'); out.color = b.color }
+    if (b.tool !== undefined) out.tool = b.tool === null ? null : String(b.tool).slice(0, 40)
+    return out
+  }
+
+  const routes = [
+    ['GET', /^\/healthz$/, async () => ({ ok: true })],
+
+    // Which optional parts this API has on, for the app and the MCPs to decide what to show. Public.
+    ['GET', /^\/v1\/features$/, async () => ({ workspaces: !!workspaces })],
+
+    ['POST', /^\/v1\/device\/start$/, async (req, body) => {
+      limitStarts(req)
+      const { publicKey, deviceName, platform } = body
+      if (!parsePublicKey(publicKey)) throw new HttpError(400, 'publicKey must be an Ed25519 key (spki, base64url)')
+      const deviceCode = newToken('dc_')
+      let userCode
+      do userCode = newUserCode(); while (await store.linkByUserCode(userCode))
+      await store.createLink({
+        deviceCodeHash: hashToken(deviceCode), userCode, publicKey,
+        deviceName: String(deviceName || 'A computer').slice(0, 80), platform: String(platform || '').slice(0, 20),
+        expiresAt: now() + LINK_TTL_MS
+      })
+      return { deviceCode, userCode, verificationUrl: `${site}/link?code=${userCode}`, interval: POLL_INTERVAL_S, expiresIn: LINK_TTL_MS / 1000 }
+    }],
+
+    ['POST', /^\/v1\/device\/poll$/, async (req, body) => {
+      const link = await store.linkByDeviceCode(hashToken(body.deviceCode))
+      if (!link) throw new HttpError(404, 'unknown device code')
+      const waiting = link.status === 'pending' || link.status === 'approving'
+      if (link.status === 'consumed' || (waiting && link.expiresAt < now())) throw new HttpError(410, 'expired')
+      if (link.status === 'approved' && link.expiresAt + COLLECT_GRACE_MS < now()) throw new HttpError(410, 'expired')
+      if (link.status === 'denied') throw new HttpError(403, 'denied')
+      // Pending polls skip the signature check so the app can poll cheaply; they
+      // reveal nothing. Only collecting the token needs proof of the key.
+      if (waiting) return [202, { status: 'pending' }]
+      // Proof of possession: anyone can start a link with a computer's public key
+      // (it's shared with session members), but only the computer can sign for it.
+      if (!verifyDeviceLink(parsePublicKey(link.publicKey), String(body.deviceCode), body.signature)) throw new HttpError(401, "this computer's signature doesn't match")
+      // Approved: claim the link before minting, so two polls racing on the same
+      // link can't both win a token — only the caller that flips it gets one.
+      if (!await store.claimLink(link.id, 'approved', 'consumed')) throw new HttpError(410, 'expired')
+      const token = newToken('qd_')
+      await store.setDeviceToken(link.deviceId, hashToken(token))
+      return { status: 'approved', token, profile: await profileWithEmail(link.userId) }
+    }],
+
+    // A computer that was linked (and not unlinked since) gets a new token by signing for its
+    // key: it lost its token (or another app on it replaced it), not its link. No browser needed.
+    // 404 means it isn't linked to anyone, and has to be approved on the website.
+    ['POST', /^\/v1\/device\/resume$/, async (req, body) => {
+      limitStarts(req)
+      const key = parsePublicKey(body.publicKey)
+      if (!key) throw new HttpError(400, 'publicKey must be an Ed25519 key (spki, base64url)')
+      const at = Number(body.at)
+      if (!Number.isFinite(at) || Math.abs(now() - at) > RESUME_WINDOW_MS) throw new HttpError(400, "this computer's clock is off; check its date and time")
+      if (!verifyDeviceResume(key, at, body.signature)) throw new HttpError(401, "this computer's signature doesn't match")
+      await spendResume(String(body.signature), at)
+      const d = await store.deviceByPublicKey(String(body.publicKey))
+      if (!d) throw new HttpError(404, 'this computer is not linked to an account')
+      const token = newToken('qd_')
+      await store.setDeviceToken(d.id, hashToken(token))
+      await store.touchDevice(d.id)
+      return { status: 'approved', token, profile: await profileWithEmail(d.userId) }
+    }],
+
+    // `known`: this account linked this computer's key before, so the website approves it
+    // without asking (only the computer holding the key can collect the token).
+    ['GET', /^\/v1\/device\/link\/([^/]+)$/, async (req, body, [code]) => {
+      const u = await user(req)
+      const link = await openLink(code)
+      return { userCode: link.userCode, deviceName: link.deviceName, platform: link.platform, expiresAt: link.expiresAt, known: await store.userHasDevice(u.userId, link.publicKey) }
+    }],
+
+    ['POST', /^\/v1\/device\/approve$/, async (req, body) => {
+      const u = await user(req)
+      const link = await openLink(body.userCode)
+      // Claim the link first, so two approvals racing on one code can't both make a device.
+      if (!await store.claimLink(link.id, 'pending', 'approving')) throw new HttpError(410, 'this code has expired or was already used')
+      if (!body.approve) { await store.updateLink(link.id, { status: 'denied', userId: u.userId }); return { status: 'denied' } }
+      let device
+      try {
+        device = await store.upsertDevice({ userId: u.userId, name: link.deviceName, platform: link.platform, publicKey: link.publicKey })
+      } catch (err) {
+        // Put the link back so the person can retry rather than being stuck mid-approval.
+        await store.updateLink(link.id, { status: 'pending' }).catch(() => {})
+        throw err
+      }
+      await store.updateLink(link.id, { status: 'approved', userId: u.userId, deviceId: device.id })
+      return { status: 'approved', device: { id: device.id, name: device.name } }
+    }],
+
+    ['GET', /^\/v1\/me$/, async (req) => {
+      const d = await device(req)
+      return { profile: await profileWithEmail(d.userId), device: { id: d.id, name: d.name } }
+    }],
+
+    ['PUT', /^\/v1\/me\/profile$/, async (req, body) => {
+      const d = await device(req)
+      const patch = cleanProfile(body)
+      if (!Object.keys(patch).length) return { profile: await store.profile(d.userId) }
+      return { profile: await store.updateProfile(d.userId, patch) }
+    }],
+
+    ['POST', /^\/v1\/me\/signout$/, async (req) => {
+      const d = await device(req)
+      await store.revokeDevice(d.id)
+      return { ok: true }
+    }],
+
+    // A pass lets its holder into sessions on the relay for 10 minutes (see src/passes.js).
+    // With { room }, it is for that room only and carries what its holder may do there.
+    ['POST', /^\/v1\/passes$/, async (req, body) => {
+      needPassKey()
+      const holder = await passHolder(req)
+      limitPasses(hashToken(bearer(req)))
+      if (body.room !== undefined && !ROOM.test(String(body.room))) throw new HttpError(400, 'room must be a session name')
+      return mintPass(holder, body.room)
+    }],
+
+    // The relay's QUILT_PASS_PUBLIC_KEY. Public: it only checks passes.
+    ['GET', /^\/v1\/passes\/key$/, async () => {
+      needPassKey()
+      return { publicKey: passPublicKey(passKey) }
+    }],
+
+    ['DELETE', /^\/v1\/me\/account$/, async (req) => {
+      const u = await user(req)
+      // Every org keeps exactly one owner, so an owner hands it on (or deletes it) first.
+      if ((await store.orgsForUser(u.userId)).some((o) => o.ownerId === u.userId)) throw new HttpError(409, 'you own an org; transfer it or delete it first')
+      // Their cloud AI machine and its disk go first: nothing of theirs keeps running.
+      try { await aiVm.destroyFor(u.userId) } catch (err) { throw new HttpError(502, `Couldn't delete your cloud AI machine; try again. ${err.message}`) }
+      await store.deleteUser(u.userId)
+      return { ok: true }
+    }]
+  ]
+
+  // Org routes live in their own modules and share the caller check and the limiter.
+  // Webhook deliveries in flight (the session-started hand-off), so tests can wait for them.
+  const deliveries = new Set()
+  const trackDelivery = (p) => { deliveries.add(p); p.finally(() => deliveries.delete(p)).catch(() => {}); return p }
+  // The relay on many machines: where each room lives, and heavy rooms' own machines (relay-cluster.js).
+  const cluster = relayCluster({ store, relayUrl: relay, relaySecret, fetch: relayFetch || githubFetch, now, log, fly: relayFly, ...(heavy ? { limits: heavy } : {}), ...clusterTiming })
+  const ctx = { store, user, person, device, bearer, now, site, apiUrl: api, mailer, log, limit: limitInvites, limitSend: limitInviteSend, limitTokens, limitStarts, spendResume, resumeWindowMs: RESUME_WINDOW_MS, limitJoin, agentAuth, reportKey, limitReports, relaySecret, files, maxFileBytes, workspaceQuotaBytes, maxWorkspaceFiles }
+  // GitHub's webhook secret: set on the app by this API at start (github-app.js), kept in the store when the environment gives none.
+  const hookSecret = { value: (github && github.webhookSecret) || '' }
+  const githubReady = (async () => {
+    if (!github) return
+    const app = githubApp(github, { fetch: githubFetch, now })
+    await ensureWebhookSecret({ cfg: github, app, store, hook: hookSecret, log })
+    await redeliverFailed({ app, log })
+  })().catch((err) => log(`github at start: ${err.message}`))
+  // A person's AI on its own cloud machine (routes/ai-vm.js): off (503) without Fly set up.
+  const aiVm = aiVmRoutes({ ...ctx, relayUrl, fly, waitMs: aiVmWaitMs })
+  routes.push(...aiVm.routes)
+  // A team's git rule or who is on a team changed: the relay asks its sessions' rules again now (relay /github/policy).
+  const policyChanged = () => {
+    if (!relay || !relaySecret) return
+    cluster.tellRelays('/github/policy', {}).catch((err) => log(`git rules to relay: ${err.message}`))
+  }
+  routes.push(...orgRoutes(ctx), ...memberRoutes(ctx), ...teamRoutes({ ...ctx, policyChanged }), ...inviteRoutes(ctx), ...agentRoutes(ctx), ...agentInviteRoutes({ ...ctx, workspaces }), ...joinRoutes(ctx), ...relayRoutes(ctx), ...githubRoutes({ ...ctx, github, githubFetch, relayHttp: relay, relayFetch: githubFetch, tellRelays: (path, body) => cluster.tellRelays(path, body), hookSecret, workspaces }), ...relayClusterRoutes({ ...ctx, cluster }), ...sessionRoutes(ctx), ...accessTypeRoutes(ctx), ...grantRoutes({ ...ctx, workspaces }), ...sessionInviteRoutes({ ...ctx, workspaces }), ...issueRoutes(ctx))
+  // Always routed: with the flag off each answers a plain 404 of its own, so the app's
+  // check at every launch isn't filed as a missing route.
+  // Only these take a hosted agent's pass (workspaceReach), so they alone get the pass key.
+  routes.push(...workspaceRoutes({ ...ctx, workspaces, passKey }), ...workspaceInviteRoutes({ ...ctx, workspaces, passKey }), ...workspaceAgentRoutes({ ...ctx, workspaces, passKey, relayUrl, webhookFetch, webhookLookup, allowLocalWebhooks, trackDelivery, limitAnnounce }))
+  const wsFiles = workspaceFileRoutes({ ...ctx, workspaces, passKey })
+  routes.push(...wsFiles.routes)
+
+  async function openLink (code) {
+    const userCode = normalizeUserCode(code)
+    const link = userCode && await store.linkByUserCode(userCode)
+    if (!link) throw new HttpError(404, 'no such code')
+    if (link.status !== 'pending' || link.expiresAt < now()) throw new HttpError(410, 'this code has expired or was already used')
+    return link
+  }
+
+  // The API's own trouble, straight into the store: no-route 404s, crashes (5xx) and
+  // slow requests of any status; the 4xx a route throws on purpose (including a
+  // deliberate 404, like an expired invite or an org you've left) is only kept when
+  // it was slow, and then as `slow`, never as an error. Never awaited by the request,
+  // and a failure to record is only logged — nothing here may escape and disturb an
+  // already-sent reply.
+  function recordOwn ({ method, pathname, status, startedAt, message, noRoute }) {
+    try {
+      const durationMs = now() - startedAt
+      const slow = durationMs > slowMs
+      const crash = status >= 500
+      const http404 = status === 404 && noRoute
+      if (!crash && !http404 && !slow) return
+      // A scanner path outside /v1/ (wp-login.php, .env, …) has no route shape worth
+      // keeping per-path; group every one of those under one name instead of letting
+      // each distinct path become its own permanent issue.
+      const name = http404 && !pathname.startsWith('/v1/') ? `${method} (no route)` : routeName(method, pathname)
+      const event = cleanEvent({
+        kind: http404 ? 'http404' : 'action',
+        name,
+        outcome: crash || http404 ? 'error' : 'slow',
+        status, durationMs, message
+      }, { surface: 'api', appVersion: API_VERSION, now })
+      Promise.resolve().then(() => store.recordEvents([event])).catch((err) => log(`issue record failed: ${err?.message || err}`))
+    } catch (err) { log(`issue record failed: ${err?.message || err}`) }
+  }
+
+  const server = http.createServer(async (req, res) => {
+    const startedAt = now()
+    // The parsed pathname (not the raw url string) decides this: it's what a route
+    // actually matches against, so "/v1/../v1/join/x" counts as a join link too.
+    let pathname
+    try { pathname = new URL(req.url, 'http://x').pathname } catch { pathname = '' }
+    // Join links are secrets in a URL: never cache them, and ask crawlers not to index them.
+    const extra = pathname.startsWith('/v1/join/') ? { 'x-robots-tag': 'noindex' } : {}
+    const send = (status, data, type = 'application/json', message = '', noRoute = false) => {
+      res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store', ...extra, ...cors(req) })
+      res.end(type === 'application/json' ? JSON.stringify(data) : data)
+      recordOwn({ method: req.method, pathname, status, startedAt, message, noRoute })
+    }
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, { 'cache-control': 'no-store', ...extra, ...cors(req), 'access-control-allow-methods': 'GET,POST,PUT,PATCH,DELETE', 'access-control-allow-headers': 'authorization,content-type', 'access-control-max-age': '600' })
+      return res.end()
+    }
+    try {
+      if (pathname.startsWith('/v1/file-data/') && files instanceof DiskStore) return await serveFileData(req, res, send, pathname.slice('/v1/file-data/'.length))
+      if (pathname === '/mcp') return await proxyMcp(req, res, send)
+      const url = new URL(req.url, 'http://x')
+      const route = routes.find(([m, re]) => m === req.method && re.test(url.pathname))
+      if (!route) throw Object.assign(new HttpError(404, 'not found'), { noRoute: true })
+      // A route may take a bigger body than usual (the relay's presence reports): route[3].maxBody.
+      // A route may want the bytes as sent (route[3].raw: GitHub's webhooks, signed over the raw body).
+      const body = route[3]?.raw ? await readRaw(req, route[3]?.maxBody || MAX_BODY) : ['POST', 'PUT', 'PATCH'].includes(req.method) ? await readJson(req, route[3]?.maxBody || MAX_BODY) : {}
+      const out = await route[2](req, body, url.pathname.match(route[1]).slice(1).map(decodePart))
+      if (out instanceof Raw) send(out.status, out.body, out.type)
+      else if (Array.isArray(out)) send(out[0], out[1])
+      else send(200, out)
+    } catch (err) {
+      // A unique index said no. Agents share one index on their public key; everything
+      // else that's unique (a taken team or role name) gets the generic message.
+      if (err?.code === '23505') {
+        const detail = `${err.constraint || ''} ${err.message || ''} ${err.details || ''}`
+        return send(409, { error: detail.includes('public_key') ? 'That public key already belongs to an agent.' : 'that name is already taken' })
+      }
+      // A foreign-key check said no (something from another org, or still referenced): a conflict, not a crash.
+      if (err?.code === '23503') return send(409, { error: 'that is still in use' })
+      // Supabase errors are plain objects, so fall back to their JSON.
+      if (!(err instanceof HttpError)) log(`api error: ${err?.stack || err?.message || JSON.stringify(err)}`)
+      send(err.status || 500, { error: err instanceof HttpError ? err.message : 'internal error' }, 'application/json', err instanceof HttpError ? err.message : String(err?.message || err?.stack || JSON.stringify(err) || 'error'), !!err.noRoute)
+    }
+  })
+
+  // Hosted agents' MCP: the agent's access key signs it in here; the relay gets the same
+  // request with a pass for the agent, and its answer comes straight back. Stateless on
+  // both sides, so each request stands alone. The pass is for the room the agent is joining
+  // (named in quilt_join_session) or is in (the relay says which in x-quilt-room), so it
+  // carries the agent's grant there.
+  const mintedPasses = new Map() // `${agent id}\n${room}` -> { pass, exp }
+  const agentRooms = new Map() // agent id -> the rooms the relay last said it is in (x-quilt-rooms)
+  const forget = (map) => { if (map.size > maxStartKeys) map.delete(map.keys().next().value) }
+  async function proxyMcp (req, res, send) {
+    needPassKey()
+    if (!isAgentKey(bearer(req))) throw new HttpError(401, 'send your agent access key (or app key) as "Authorization: Bearer <key>"')
+    const { agent } = await agentAuth.agentFromRequest(req)
+    limitMcp(agent.id)
+    const body = ['POST', 'PUT'].includes(req.method) ? await readRaw(req, workspaces ? MAX_MCP_BODY_WORKSPACES : MAX_MCP_BODY) : undefined
+    const holder = await agentHolder(agent)
+    const passFor = async (room) => {
+      const cacheKey = `${agent.id}\n${room}`
+      let minted = mintedPasses.get(cacheKey)
+      if (!minted || minted.exp - now() < PASS_REUSE_MARGIN_MS) {
+        const { pass, expiresAt } = await mintPass(holder, room)
+        minted = { pass, exp: expiresAt }
+        mintedPasses.set(cacheKey, minted)
+        if (mintedPasses.size > maxStartKeys) for (const [k, v] of mintedPasses) if (v.exp <= now()) mintedPasses.delete(k)
+        forget(mintedPasses)
+      }
+      return minted.pass
+    }
+    const ask = async (room) => {
+      const headers = { 'x-quilt-pass': await passFor(room) }
+      for (const h of ['accept', 'content-type', 'mcp-protocol-version', 'mcp-session-id', 'last-event-id']) if (req.headers[h]) headers[h] = String(req.headers[h])
+      try {
+        return await fetch(`${relay}/mcp`, { method: req.method, headers, body, signal: AbortSignal.timeout(MCP_TIMEOUT_MS) })
+      } catch (err) {
+        log(`mcp relay error: ${err.message}`)
+        throw new HttpError(502, 'the session relay did not answer; try again in a moment')
+      }
+    }
+    // The room this call is about: the invite it joins, the `session` it names, else the agent's only room.
+    const known = agentRooms.get(agent.id) || []
+    const room = joiningRoom(body) || sessionArg(body) || (known.length === 1 ? known[0] : '')
+    let upstream = await ask(room)
+    // The relay needs a pass for the room the agent is in (this server forgot it, after a
+    // restart): ask again, once, with one for the room it names. Tool calls are only refused
+    // there, never carried out, so the same call is safe to send again.
+    const named = upstream.headers.get('x-quilt-room') || ''
+    if (upstream.headers.get('x-quilt-retry') === 'room-pass' && ROOM.test(named) && named !== room) {
+      await upstream.arrayBuffer().catch(() => {})
+      upstream = await ask(named)
+    }
+    if (upstream.ok) {
+      const listed = String(upstream.headers.get('x-quilt-rooms') || upstream.headers.get('x-quilt-room') || '').split(',').map((r) => r.trim()).filter((r) => ROOM.test(r))
+      if (listed.length) { agentRooms.set(agent.id, listed); forget(agentRooms) } else agentRooms.delete(agent.id)
+    }
+    const type = upstream.headers.get('content-type') || 'application/json'
+    const out = Buffer.from(await upstream.arrayBuffer())
+    res.writeHead(upstream.status, { 'content-type': type, 'cache-control': 'no-store' })
+    res.end(out)
+  }
+
+  // The disk store's links: PUT streams an upload to the API's disk within the signed size; GET streams it back.
+  async function serveFileData (req, res, send, key) {
+    const q = new URL(req.url, 'http://x').searchParams
+    const method = req.method
+    if (!['PUT', 'GET'].includes(method) || q.get('m') !== method) return send(405, { error: 'method not allowed' })
+    const size = method === 'PUT' ? Number(q.get('n')) : undefined
+    const name = q.get('name') || ''
+    const type = q.get('type') || ''
+    if (!files.verify(key, method, q.get('exp'), q.get('sig'), size, name, type)) return send(403, { error: 'this link is not valid' })
+    const file = files.file(key)
+    if (method === 'PUT') {
+      // Like Supabase's upsert: false, an object that has landed is never replaced.
+      if (fs.existsSync(file)) return send(409, { error: 'already stored' })
+      const tmp = `${file}.part`
+      let out = null
+      let failed = null
+      try {
+        fs.mkdirSync(path.dirname(file), { recursive: true })
+        out = fs.createWriteStream(tmp)
+        // Without this, a write failure (disk full, permission denied) is an
+        // unhandled 'error' event on the stream, which crashes the whole process.
+        out.on('error', (err) => { failed = failed || err })
+        let got = 0
+        for await (const chunk of req) {
+          if (failed) throw failed
+          got += chunk.length
+          if (got > size) throw new HttpError(413, 'more bytes than the link allows')
+          if (!out.write(chunk)) await new Promise((resolve) => out.once('drain', resolve))
+          if (failed) throw failed
+        }
+        if (failed) throw failed
+        await new Promise((resolve, reject) => out.end((err) => (err || failed ? reject(err || failed) : resolve())))
+        fs.renameSync(tmp, file)
+        return send(200, { ok: true })
+      } catch (err) {
+        if (out) out.destroy()
+        fs.rmSync(tmp, { force: true })
+        return send(err.status || 500, { error: err.message })
+      }
+    }
+    let stat
+    try { stat = fs.statSync(file) } catch { return send(404, { error: 'not found' }) }
+    const headers = { 'content-type': type || 'application/octet-stream', 'content-length': stat.size, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', ...cors(req) }
+    if (name) headers['content-disposition'] = contentDisposition('attachment', name)
+    res.writeHead(200, headers)
+    // A read that fails once the headers are out can only cut the response short.
+    await pipeline(fs.createReadStream(file), res).catch(() => res.destroy())
+  }
+
+  // Only the website may call the API from a browser.
+  function cors (req) {
+    return site && req.headers.origin === site ? { 'access-control-allow-origin': site, vary: 'origin' } : {}
+  }
+
+  // Events are the detail (kept 30 days); issues are the summary people read (kept
+  // 90 days, so slower-moving problems don't vanish while their events still would).
+  async function pruneNow () {
+    try { await store.pruneEvents(now() - keepEventsMs) } catch (err) { log(`issue prune failed: ${err?.message || err}`) }
+    try { await store.pruneIssues(now() - keepIssuesMs) } catch (err) { log(`issue prune failed: ${err?.message || err}`) }
+    // Workspace files: uploads that never landed, and deleted files past their 30 days
+    // (only with the flag on: before then the tables may not exist yet).
+    if (workspaces) try { await wsFiles.sweep() } catch (err) { log(`file sweep failed: ${err?.message || err}`) }
+  }
+  const prune = setInterval(() => { pruneNow() }, pruneEveryMs)
+  prune.unref()
+  // Also soon after start, since every deploy restarts the hourly clock.
+  const firstPrune = setTimeout(() => { pruneNow() }, pruneStartMs)
+  firstPrune.unref()
+
+  /** Waits for every webhook delivery started so far (and any they start) to finish. */
+  async function flushWebhooks () {
+    while (deliveries.size) await Promise.allSettled([...deliveries])
+  }
+
+  return new Promise((resolve) => server.listen(port, host, () => {
+    const p = server.address().port
+    resolve({ port: p, url: `http://${host}:${p}`, cluster, close: () => { clearInterval(prune); clearTimeout(firstPrune); return new Promise((r) => server.close(r)) }, startKeys: () => limitStarts.size(), sweepFiles: (at) => wsFiles.sweep(at), flushWebhooks, githubReady })
+  }))
+}
+
+// Which room a hosted agent's MCP request is about: shared with the relay (src/mcp-room.js).
+export { joiningRoom, sessionArg } from '../mcp-room.js'
+
+function decodePart (s) {
+  try { return decodeURIComponent(s) } catch { throw new HttpError(400, 'bad path') }
+}
+
+function readRaw (req, max) {
+  return new Promise((resolve, reject) => {
+    let size = 0; const chunks = []
+    req.on('data', (c) => { size += c.length; if (size > max) { req.destroy(); reject(new HttpError(413, 'too large')) } else chunks.push(c) })
+    req.on('end', () => resolve(Buffer.concat(chunks)))
+    req.on('error', reject)
+  })
+}
+
+function readJson (req, limit) {
+  return new Promise((resolve, reject) => {
+    let size = 0; const chunks = []
+    req.on('data', (c) => { size += c.length; if (size > limit) { req.destroy(); reject(new HttpError(413, 'too large')) } else chunks.push(c) })
+    req.on('end', () => {
+      if (!chunks.length) return resolve({})
+      let body
+      try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { return reject(new HttpError(400, 'bad json')) }
+      // Handlers read fields off the body; null, arrays and scalars carry none.
+      resolve(body && typeof body === 'object' && !Array.isArray(body) ? body : {})
+    })
+    req.on('error', reject)
+  })
+}

package/src/api/slugs.js

@@ -0,0 +1,20 @@
+// Org addresses: /org/<slug>. Lowercase letters, digits and single hyphens.
+// "personal" is the space switcher's name for your own space; "new" and
+// "discover" are words routes might want.
+const RESERVED = new Set(['personal', 'new', 'discover'])
+
+export function slugify (name) {
+  const s = String(name || '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '')
+  if (!s) return 'org'
+  return RESERVED.has(s) ? `${s}-org` : s
+}
+
+/** The first of base, base-2, base-3, ... that `taken` says is free. */
+export async function uniqueSlug (name, taken) {
+  const base = slugify(name)
+  for (let n = 1; ; n++) {
+    const slug = n === 1 ? base : `${base}-${n}`
+    if (!await taken(slug)) return slug
+  }
+}