heyquilt 0.0.1 → 0.3.90

package/src/api/routes/issues.js

@@ -0,0 +1,47 @@
+// src/api/routes/issues.js
+// Issue reports from the desktop app and the website: errors, 404s, crashes and how long
+// actions took. Who is reporting decides the surface and who the events belong to; the
+// body never does.
+import crypto from 'node:crypto'
+import { HttpError, UUID } from '../http.js'
+import { cleanEvent, MAX_BATCH } from '../issues.js'
+
+// Compares by byte length, not by UTF-16 string length: a header with the right character
+// count but non-ASCII (or otherwise multi-byte) bytes would otherwise reach
+// timingSafeEqual with mismatched buffer lengths, which throws rather than answering false.
+const sameKey = (a, b) => {
+  const bufA = Buffer.from(a); const bufB = Buffer.from(b)
+  return bufA.length === bufB.length && crypto.timingSafeEqual(bufA, bufB)
+}
+
+export function issueRoutes ({ store, device, bearer, now, reportKey = '', limitReports }) {
+  /** Who is reporting: { surface, userId, deviceId }. */
+  async function reporter (req, body) {
+    const surface = String(body.surface || '')
+    if (bearer(req).startsWith('qd_')) {
+      const d = await device(req)
+      if (surface !== 'app') throw new HttpError(400, 'a computer reports for the app')
+      return { surface, userId: d.userId, deviceId: d.id }
+    }
+    const key = String(req.headers['x-quilt-report-key'] || '')
+    if (key) {
+      if (!reportKey || !sameKey(key, reportKey)) throw new HttpError(401, 'bad report key')
+      if (surface !== 'web') throw new HttpError(400, 'the website reports for the web')
+      return { surface, userId: UUID.test(String(body.userId || '')) ? String(body.userId) : null, deviceId: null }
+    }
+    // Nobody signed in: the app before sign-in (a failed sign-in is worth knowing about).
+    if (surface !== 'app') throw new HttpError(401, 'sign in first')
+    limitReports(req)
+    return { surface, userId: null, deviceId: null }
+  }
+
+  return [
+    ['POST', /^\/v1\/issues$/, async (req, body) => {
+      const who = await reporter(req, body)
+      if (!Array.isArray(body.events) || body.events.length < 1 || body.events.length > MAX_BATCH) throw new HttpError(400, `events must hold 1 to ${MAX_BATCH} items`)
+      const events = body.events.map((raw) => cleanEvent(raw, { ...who, appVersion: body.appVersion, platform: body.platform, now }))
+      const recorded = await store.recordEvents(events)
+      return { ok: true, recorded }
+    }]
+  ]
+}

package/src/api/routes/join.js

@@ -0,0 +1,167 @@
+// An AI opening an agent invite link. A GET without a name only explains, so
+// link previews and scanners never use the invite up; a POST, or a GET with
+// name, provider and type, uses it once and hands back the agent's first keys.
+// An agent that already joined once gives its agentId (public, like a person's id)
+// and comes back as itself instead of as a new agent with the same name.
+import { HttpError, Raw, cleanName, stripInvisible } from '../http.js'
+import { hashToken } from '../tokens.js'
+import { parsePublicKey } from '../../identity.js'
+import { joinInstructions, joinNext } from '../join-text.js'
+import { inviteStatus } from './agent-invites.js'
+
+const MAX_DESCRIPTION = 180
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const NEW_AGENT = 'leave agentId out to join as a new agent'
+const GONE = {
+  used: 'this invite was already used; ask for a new one',
+  expired: 'this invite has expired; ask for a new one',
+  cancelled: 'this invite was cancelled; ask for a new one'
+}
+
+export function joinRoutes ({ store, now, apiUrl, limitJoin, agentAuth, log = () => {} }) {
+  const inviteFor = async (token) => (String(token).startsWith('qj_') ? store.agentInviteByToken(hashToken(token)) : null)
+  const statusOf = (invite) => (invite ? inviteStatus(invite, now()) : 'unknown')
+
+  // Required as an actual string, never a stray number or object a loose client sent,
+  // and never the literal <placeholder> text from the join instructions.
+  function field (value, name, fallback) {
+    if (value === undefined && fallback !== undefined) value = fallback
+    if (typeof value !== 'string') throw new HttpError(400, `${name} must be a string`)
+    if (value.includes('<') || value.includes('>')) throw new HttpError(400, `${name} can't contain < or >`)
+    return value
+  }
+
+  // The agent's profile, checked in full before the invite is touched.
+  function profile (src) {
+    const publicKey = src.publicKey == null || src.publicKey === '' ? null : String(src.publicKey)
+    if (publicKey && !parsePublicKey(publicKey)) throw new HttpError(400, 'publicKey must be an Ed25519 key (spki, base64url)')
+    return {
+      name: cleanName(field(src.name, 'name'), 40, 'give your name (up to 40 characters)'),
+      provider: cleanName(field(src.provider, 'provider'), 40, 'give your provider, e.g. Anthropic, OpenAI or Cursor'),
+      type: cleanName(field(src.type, 'type'), 40, 'give your type, e.g. coding agent'),
+      description: stripInvisible(field(src.description, 'description', '')).slice(0, MAX_DESCRIPTION).join('').trim(),
+      publicKey
+    }
+  }
+
+  // The agent coming back, when the join names one (agentId is optional). The invite is
+  // what lets it in: the id only has to name an agent of the invite's person or org.
+  async function returning (src, invite) {
+    const id = src.agentId
+    if (id == null || id === '') return null
+    if (typeof id !== 'string' || !UUID.test(id)) throw new HttpError(400, `agentId must be the id Quilt gave you when you first joined; ${NEW_AGENT}`)
+    const agent = await store.agentById(id.toLowerCase())
+    if (!agent) throw new HttpError(404, `no agent has that agentId; ${NEW_AGENT}`)
+    const home = invite.orgId ? agent.orgId === invite.orgId : agent.ownerUserId === invite.ownerUserId
+    if (!home) throw new HttpError(403, `that agent belongs to someone else, and this invite can't bring it back; ${NEW_AGENT}`)
+    return agent
+  }
+
+  // A returning org agent gets the invite's role and teams; teams it has and the invite
+  // doesn't name are left as they are.
+  async function rejoinOrg (invite, agent) {
+    let m = await store.memberByAgent(invite.orgId, agent.id)
+    if (!m) m = await store.addAgentMember({ orgId: invite.orgId, agentId: agent.id, roleId: invite.roleId })
+    else if (invite.roleId && m.roleId !== invite.roleId) await store.setMemberRole(m.id, invite.roleId)
+    const mine = new Set((await store.teamsOfMember(m.id)).map((x) => x.teamId))
+    for (const x of invite.teams) {
+      if (!await store.teamById(invite.orgId, x.teamId)) continue
+      if (mine.has(x.teamId)) await store.setTeamAccess(x.teamId, m.id, x.access, x.scopes)
+      else await store.addTeamMember({ teamId: x.teamId, memberId: m.id, access: x.access, scopes: x.scopes })
+    }
+  }
+
+  const reply = (agent, keys, resumeKey, rejoined) => ({
+    ...keys,
+    resumeKey,
+    rejoined,
+    api: apiUrl,
+    refresh: `${apiUrl}/v1/agents/token`,
+    resume: `${apiUrl}/v1/agents/resume`,
+    mcp: `${apiUrl}/mcp`,
+    next: joinNext({ name: agent.name, agentId: agent.id, apiUrl, hasKey: !!agent.publicKey, rejoined })
+  })
+
+  async function join (token, src) {
+    const invite = await inviteFor(token)
+    const status = statusOf(invite)
+    if (status === 'unknown') throw new HttpError(404, "this invite link isn't valid")
+    if (status !== 'waiting') throw new HttpError(410, GONE[status])
+    // Everything the agent sent is checked first, so a typo never burns the invite.
+    const p = profile(src)
+    const back = await returning(src, invite)
+    const owner = p.publicKey && await store.agentByPublicKey(p.publicKey)
+    if (owner && owner.id !== back?.id) throw new HttpError(409, 'that publicKey already belongs to an agent')
+    // Claim first, so two joins racing on one link can't both make an agent.
+    if (!await store.claimAgentInvite(invite.id)) throw new HttpError(410, GONE.used)
+    const { resumeKey, resumeHash } = agentAuth.newResumeKey()
+    if (back) {
+      // Its keys from before keep working until they run out, like a person signing in
+      // on a second computer; its old resume key is replaced by this one.
+      try {
+        const agent = await store.rejoinAgent(back.id, { ...p, resumeHash })
+        if (invite.orgId) await rejoinOrg(invite, agent)
+        await store.setInviteAgent(invite.id, agent.id, true)
+        return reply(agent, await agentAuth.mintKeys(agent.id), resumeKey, true)
+      } catch (err) {
+        await store.releaseAgentInvite(invite.id).catch(() => {})
+        throw err
+      }
+    }
+    let agent
+    try {
+      agent = await store.createAgent({ ...p, resumeHash, ownerUserId: invite.ownerUserId, orgId: invite.orgId, invitedBy: invite.createdBy })
+      if (invite.orgId) {
+        const m = await store.addAgentMember({ orgId: invite.orgId, agentId: agent.id, roleId: invite.roleId })
+        for (const x of invite.teams) {
+          // A team deleted since the invite was made is skipped.
+          if (await store.teamById(invite.orgId, x.teamId)) await store.addTeamMember({ teamId: x.teamId, memberId: m.id, access: x.access, scopes: x.scopes })
+        }
+      }
+      // A workspace's invite (workspace-agents.js) makes the agent one of its members.
+      if (invite.workspaceId) {
+        await store.putWorkspaceMember({ workspaceId: invite.workspaceId, account: `agent:${agent.id}`, access: invite.workspaceAccess || 'edit', sessions: invite.workspaceSessions || 'invited', addedBy: invite.createdBy })
+      }
+      // A global agent's invite (workspaces on when it was made) places it in all its owner's
+      // workspaces, invited to every session there. Deleting the agent below takes it too.
+      if (invite.global) {
+        await store.putAgentPlacement({ agentId: agent.id, reach: 'all', workspaceIds: [], sessions: 'all', access: 'edit', scopes: [], updatedBy: `person:${invite.createdBy}` })
+      }
+      await store.setInviteAgent(invite.id, agent.id)
+      return reply(agent, await agentAuth.mintKeys(agent.id), resumeKey, false)
+    } catch (err) {
+      // Undo the half-made agent and reopen the link, so the AI can simply try again.
+      // But if the agent couldn't be deleted, it may still be half-wired into the org
+      // (team membership, etc): leave the invite used rather than hand out a link that
+      // would make a second, equally broken agent on top of the first.
+      let deleted = !agent
+      // Member rows name the agent as text, so deleting it leaves them: remove this one first.
+      if (agent && invite.workspaceId) await store.removeWorkspaceMember(invite.workspaceId, `agent:${agent.id}`).catch(() => {})
+      if (agent) {
+        try { await store.deleteAgent(agent.id); deleted = true } catch (delErr) {
+          log(`join rollback: couldn't delete half-made agent ${agent.id}: ${delErr?.stack || delErr?.message || delErr}`)
+        }
+      }
+      if (deleted) await store.releaseAgentInvite(invite.id).catch(() => {})
+      throw err
+    }
+  }
+
+  return [
+    ['POST', /^\/v1\/join\/([^/]+)$/, async (req, body, [token]) => {
+      limitJoin(req)
+      return join(token, body)
+    }],
+
+    ['GET', /^\/v1\/join\/([^/]+)$/, async (req, body, [token]) => {
+      limitJoin(req)
+      const q = new URL(req.url, 'http://x').searchParams
+      // Only a GET that names the agent uses the invite (agentId alone doesn't).
+      if (['name', 'provider', 'type'].some((k) => q.has(k))) return join(token, Object.fromEntries(q))
+      const invite = await inviteFor(token)
+      const status = statusOf(invite)
+      const text = joinInstructions({ link: `${apiUrl}/v1/join/${encodeURIComponent(token)}`, apiUrl, status, expiresAt: invite?.expiresAt })
+      return new Raw(status === 'waiting' ? 200 : status === 'unknown' ? 404 : 410, text)
+    }]
+  ]
+}

package/src/api/routes/members.js

@@ -0,0 +1,110 @@
+// An org's people and agents: the member list, changing a role, removing or leaving.
+import { HttpError, needId } from '../http.js'
+import { orgAccess } from '../org-access.js'
+
+export function memberRoutes ({ store, user }) {
+  const orgFor = async (req, slug) => { const u = await user(req); return { u, ...(await orgAccess(store, u.userId, slug)) } }
+
+  async function target (a, id) {
+    const m = await store.memberById(a.org.id, needId(id, 'member'))
+    if (!m) throw new HttpError(404, 'no such member')
+    if (m.userId && m.userId === a.org.ownerId) throw new HttpError(403, 'the owner only changes through a transfer')
+    return m
+  }
+
+  // You can't act on someone (or an agent) whose role holds checkboxes you don't.
+  async function outranks (a, m) {
+    const r = m.roleId && await store.roleById(a.org.id, m.roleId)
+    if (!a.covers(r?.grants)) throw new HttpError(403, m.agentId ? "this agent has permissions you don't have" : "this person has permissions you don't have")
+  }
+
+  return [
+    ['GET', /^\/v1\/orgs\/([^/]+)\/members$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      // One list: people for Members: Read, agents for Agents: Read.
+      const seePeople = a.can('members', 'r')
+      const seeAgents = a.can('agents', 'r')
+      if (!seePeople && !seeAgents) a.need('members', 'r')
+      const [everyone, roles] = await Promise.all([store.listMembers(a.org.id), store.listRoles(a.org.id)])
+      const members = everyone.filter((m) => (m.agentId ? seeAgents : seePeople))
+      const roleName = new Map(roles.map((r) => [r.id, r.name]))
+      // Team names only for people allowed to see who's in each team.
+      const teamsOf = new Map()
+      if (a.can('team_members', 'r')) {
+        for (const team of await store.listTeams(a.org.id)) {
+          for (const tm of await store.listTeamMembers(team.id)) {
+            teamsOf.set(tm.memberId, [...(teamsOf.get(tm.memberId) || []), { id: team.id, name: team.name, access: tm.access, scopes: tm.scopes || [] }])
+          }
+        }
+      }
+      const emails = await Promise.all(members.map((m) => (m.userId ? store.userEmail(m.userId) : null)))
+      return {
+        members: members.map((m, i) => ({
+          id: m.id,
+          kind: m.agentId ? 'agent' : 'person',
+          userId: m.userId ?? null,
+          agentId: m.agentId ?? null,
+          name: m.name,
+          provider: m.provider ?? null,
+          type: m.type ?? null,
+          // Only for an agent; whether it has a key, never the key itself.
+          // Agents always can: with a key from a computer running Quilt too, without one through the hosted MCP.
+          canJoinSessions: m.agentId ? true : null,
+          hosted: m.agentId ? !m.publicKey : null,
+          email: emails[i]?.email || '',
+          roleId: m.roleId,
+          role: roleName.get(m.roleId) || null,
+          isOwner: !!m.userId && m.userId === a.org.ownerId,
+          isYou: !!m.userId && m.userId === a.u.userId,
+          joinedAt: m.joinedAt,
+          teams: teamsOf.get(m.id) || []
+        }))
+      }
+    }],
+
+    ['PUT', /^\/v1\/orgs\/([^/]+)\/members\/([^/]+)$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      const m = await target(a, id)
+      if (m.agentId) {
+        // An agent's role is Agents: Update, and it may have none (team access only).
+        a.need('agents', 'u')
+        await outranks(a, m)
+        // roleId must be given explicitly: a body that omits it is never read as "clear
+        // the role", so a partial PUT (e.g. missing a field a future client meant to send)
+        // can't silently wipe one.
+        if (!('roleId' in body)) throw new HttpError(400, 'roleId is required; use null to clear the role')
+        const role = body.roleId ? await a.assignable(body.roleId) : null
+        const saved = await store.setMemberRole(m.id, role ? role.id : null)
+        return { member: { id: saved.id, roleId: saved.roleId } }
+      }
+      // Assigning a person's role is Members: Update together with Roles: Update.
+      a.need('members', 'u')
+      a.need('roles', 'u')
+      if (m.userId === a.u.userId) throw new HttpError(403, "you can't change your own role")
+      await outranks(a, m)
+      const role = await a.assignable(body.roleId || 'missing')
+      const saved = await store.setMemberRole(m.id, role.id)
+      return { member: { id: saved.id, roleId: saved.roleId } }
+    }],
+
+    ['DELETE', /^\/v1\/orgs\/([^/]+)\/members\/([^/]+)$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      const m = await target(a, id)
+      if (m.agentId) {
+        // An org agent has nowhere else to be, so removing it revokes it.
+        a.need('agents', 'd')
+        await outranks(a, m)
+        await store.revokeAgent(m.agentId)
+        await store.removeMember(m.id)
+        return { ok: true }
+      }
+      // Anyone may leave; removing someone else needs Members: Delete.
+      if (m.userId !== a.u.userId) {
+        a.need('members', 'd')
+        await outranks(a, m)
+      }
+      await store.removeMember(m.id)
+      return { ok: true }
+    }]
+  ]
+}

package/src/api/routes/orgs.js

@@ -0,0 +1,177 @@
+// Orgs: creating one, its settings and domain rule, ownership, and its roles.
+import { HttpError, needId, cleanName } from '../http.js'
+import { orgAccess } from '../org-access.js'
+import { BUILTIN, normalizeGrants } from '../permissions.js'
+import { emailDomain, isDomain, isPublicDomain } from '../domains.js'
+import { uniqueSlug } from '../slugs.js'
+
+const ROLE_ORDER = { owner: 0, admin: 1, member: 2 }
+const RESERVED_ROLE_NAMES = new Set(['owner', 'admin', 'member'])
+const checkNotReserved = (name) => {
+  if (RESERVED_ROLE_NAMES.has(name.toLowerCase())) throw new HttpError(400, 'That name is reserved for a built-in role.')
+}
+const sortRoles = (roles) => [...roles].sort((a, b) => (ROLE_ORDER[a.builtin] ?? 3) - (ROLE_ORDER[b.builtin] ?? 3) || a.name.localeCompare(b.name))
+const orgView = (o) => ({ id: o.id, name: o.name, slug: o.slug, domain: o.domain, domainRequests: o.domainRequests, createdAt: o.createdAt })
+const roleView = (r) => ({ id: r.id, name: r.name, builtin: r.builtin, grants: normalizeGrants(r.grants), createdAt: r.createdAt })
+
+export function orgRoutes ({ store, user, person }) {
+  const orgFor = async (req, slug) => { const u = await user(req); return { u, ...(await orgAccess(store, u.userId, slug)) } }
+
+  // Two orgs made at once can pick the same slug; the unique index decides and we try the next.
+  // first: true (a team sign-up's first dashboard visit) asks the store to
+  // hand back an org the owner is already in, rather than making a second one
+  // when two tabs (or a double click) both raced here with no org yet.
+  async function createOrg (name, ownerId, first = false) {
+    for (let attempt = 0; ; attempt++) {
+      const slug = await uniqueSlug(name, async (s) => !!await store.orgBySlug(s))
+      try {
+        return await store.createOrg({ name, slug, ownerId, grants: BUILTIN, first })
+      } catch (err) {
+        if (err?.code !== '23505' || attempt >= 2) throw err
+      }
+    }
+  }
+
+  // Only a domain the caller has proved they get mail at, and never a public provider's.
+  async function ownDomain (userId, domain) {
+    if (!isDomain(domain)) throw new HttpError(400, "that isn't a domain")
+    if (isPublicDomain(domain)) throw new HttpError(400, "public email domains can't be used")
+    const mine = await store.userEmail(userId)
+    if (!mine?.confirmed || emailDomain(mine.email) !== domain) throw new HttpError(403, 'you can only use the domain of your own confirmed email')
+    return domain
+  }
+
+  async function roleIn (a, id) {
+    const role = await store.roleById(a.org.id, needId(id, 'role'))
+    if (!role) throw new HttpError(404, 'no such role')
+    return role
+  }
+
+  return [
+    ['GET', /^\/v1\/orgs$/, async (req) => {
+      // The app lists your orgs too (where a new workspace goes), so a computer's qd_ token works here.
+      const u = await person(req)
+      const orgs = await store.orgsForUser(u.userId)
+      return {
+        orgs: await Promise.all(orgs.map(async (o) => ({
+          ...orgView(o), isOwner: o.ownerId === u.userId, role: (await store.roleById(o.id, o.roleId))?.name || null
+        })))
+      }
+    }],
+
+    // Only an org account can create an org, and only when it isn't in one yet
+    // (first: true, checked again by createOrg itself against a race).
+    ['POST', /^\/v1\/orgs$/, async (req, body) => {
+      const u = await user(req)
+      if (body.first !== true || await store.profileKind(u.userId) !== 'org') {
+        throw new HttpError(403, 'Orgs are created by signing up as an org.')
+      }
+      return { org: orgView(await createOrg(cleanName(body.name, 80, 'give the org a name'), u.userId, true)) }
+    }],
+
+    ['GET', /^\/v1\/orgs\/([^/]+)\/me$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      return {
+        org: { ...orgView(a.org), ownerId: a.org.ownerId },
+        role: a.role && { id: a.role.id, name: a.role.name, builtin: a.role.builtin },
+        grants: a.grants,
+        isOwner: a.isOwner,
+        memberId: a.me.id
+      }
+    }],
+
+    ['PUT', /^\/v1\/orgs\/([^/]+)$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      a.need('org', 'u')
+      const patch = {}
+      if (body.name !== undefined) patch.name = cleanName(body.name, 80, 'give the org a name')
+      if (body.domain !== undefined) {
+        const d = body.domain == null ? '' : String(body.domain).trim().toLowerCase().replace(/\.$/, '')
+        // Re-saving the current domain (say, alongside a rename) doesn't need re-proving.
+        patch.domain = !d ? null : d === a.org.domain ? d : await ownDomain(a.u.userId, d)
+      }
+      if (body.domainRequests !== undefined) patch.domainRequests = body.domainRequests === true
+      if (!Object.keys(patch).length) return { org: orgView(a.org) }
+      const domain = 'domain' in patch ? patch.domain : a.org.domain
+      if (patch.domainRequests && !domain) throw new HttpError(400, 'set a domain first')
+      if (!domain) patch.domainRequests = false
+      return { org: orgView(await store.updateOrg(a.org.id, patch)) }
+    }],
+
+    ['DELETE', /^\/v1\/orgs\/([^/]+)$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      a.needOwner()
+      await store.deleteOrg(a.org.id)
+      return { ok: true }
+    }],
+
+    ['POST', /^\/v1\/orgs\/([^/]+)\/transfer$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      a.needOwner()
+      const to = await store.memberById(a.org.id, needId(body.memberId, 'member'))
+      if (!to?.userId) throw new HttpError(404, 'no such member')
+      if (to.userId === a.u.userId) throw new HttpError(400, 'you already own this org')
+      try {
+        await store.transferOrg(a.org.id, a.u.userId, to.userId)
+      } catch (err) {
+        // Defensive: the checks above should make these unreachable, but a store
+        // that finds otherwise should answer cleanly rather than with a 500.
+        if (err?.code === 'QO001') throw new HttpError(404, 'the current owner is no longer a member of this org')
+        if (err?.code === 'QO002') throw new HttpError(400, 'that member is not part of this org')
+        // Someone else already became owner between this page loading and the click.
+        if (err?.code === 'QO003') throw new HttpError(409, 'Ownership already changed. Reload and try again.')
+        throw err
+      }
+      return { ok: true }
+    }],
+
+    ['GET', /^\/v1\/orgs\/([^/]+)\/roles$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      // People who hand out roles (changing members, inviting) need the list to pick from.
+      if (!a.can('members', 'u') && !a.can('invites', 'c')) a.need('roles', 'r')
+      return { roles: sortRoles(await store.listRoles(a.org.id)).map(roleView) }
+    }],
+
+    ['POST', /^\/v1\/orgs\/([^/]+)\/roles$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      a.need('roles', 'c')
+      const grants = normalizeGrants(body.grants)
+      if (!a.covers(grants)) throw new HttpError(403, 'a role can only have permissions you have')
+      const name = cleanName(body.name, 40, 'give the role a name')
+      checkNotReserved(name)
+      return { role: roleView(await store.createRole({ orgId: a.org.id, name, grants })) }
+    }],
+
+    ['PUT', /^\/v1\/orgs\/([^/]+)\/roles\/([^/]+)$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('roles', 'u')
+      const role = await roleIn(a, id)
+      if (role.builtin === 'owner') throw new HttpError(403, "the Owner role can't be edited")
+      if (!a.covers(role.grants)) throw new HttpError(403, "this role has permissions you don't have")
+      const patch = {}
+      if (body.name !== undefined) {
+        const name = cleanName(body.name, 40, 'give the role a name')
+        if (role.builtin && name !== role.name) throw new HttpError(400, 'built-in roles keep their names')
+        if (!role.builtin) checkNotReserved(name)
+        patch.name = name
+      }
+      if (body.grants !== undefined) {
+        patch.grants = normalizeGrants(body.grants)
+        if (!a.covers(patch.grants)) throw new HttpError(403, 'a role can only have permissions you have')
+      }
+      if (!Object.keys(patch).length) return { role: roleView(role) }
+      return { role: roleView(await store.updateRole(role.id, patch)) }
+    }],
+
+    ['DELETE', /^\/v1\/orgs\/([^/]+)\/roles\/([^/]+)$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('roles', 'd')
+      const role = await roleIn(a, id)
+      if (role.builtin) throw new HttpError(400, "built-in roles can't be deleted")
+      if (!a.covers(role.grants)) throw new HttpError(403, "this role has permissions you don't have")
+      if (await store.roleInUse(role.id)) throw new HttpError(409, 'this role is still assigned; move its people to another role first')
+      await store.deleteRole(role.id)
+      return { ok: true }
+    }]
+  ]
+}

package/src/api/routes/relay-cluster.js

@@ -0,0 +1,90 @@
+// The relay on many machines (src/api/relay-cluster.js): where each room lives, each machine's
+// minute, hosted agents' sessions across machines, and whether a session has someone in it.
+// Only the relay calls these, with RELAY_API_SECRET.
+import crypto from 'node:crypto'
+import { HttpError } from '../http.js'
+
+const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+const MACHINE = /^[A-Za-z0-9_-]{1,64}$/
+const ACCOUNT = /^(person|agent):[A-Za-z0-9_-]{1,64}$/
+const digest = (s) => crypto.createHash('sha256').update(String(s)).digest()
+// A machine's report lists every loaded room; hello lists every room on its disk.
+export const REPORT_BODY = 1024 * 1024
+export const HELLO_BODY = 2 * 1024 * 1024
+const MAX_ROOMS = 20000
+const MAX_WEBHOOK = 4096
+
+export function relayClusterRoutes ({ store, bearer, relaySecret, cluster }) {
+  const fromRelay = (req) => {
+    if (!relaySecret) throw new HttpError(503, 'the relay is not set up on this server')
+    if (!crypto.timingSafeEqual(digest(bearer(req)), digest(relaySecret))) throw new HttpError(401, 'only the relay may ask for this')
+  }
+  const machineOf = (b) => {
+    if (!MACHINE.test(String(b.machine || ''))) throw new HttpError(400, 'give the machine id')
+    return String(b.machine)
+  }
+  const roomOf = (r) => {
+    if (!ROOM.test(String(r || ''))) throw new HttpError(400, 'give the room')
+    return String(r)
+  }
+  const accountOf = (a) => {
+    if (!ACCOUNT.test(String(a || ''))) throw new HttpError(400, 'give the account')
+    return String(a)
+  }
+  const roomList = (v) => {
+    if (v === undefined) return []
+    if (!Array.isArray(v) || v.length > MAX_ROOMS) throw new HttpError(400, `rooms must be a list of at most ${MAX_ROOMS}`)
+    return v
+  }
+
+  return [
+    // A relay machine started: the rooms on its disk are its own, unless placed elsewhere (it moves those aside).
+    ['POST', /^\/v1\/relay\/machines\/hello$/, async (req, b) => {
+      fromRelay(req)
+      return cluster.hello({ machine: machineOf(b), region: String(b.region || ''), capacity: Number(b.capacity), rooms: roomList(b.rooms).filter((r) => ROOM.test(String(r))) })
+    }, { maxBody: HELLO_BODY }],
+    // A machine's minute: its load, and each loaded room's traffic and size.
+    ['POST', /^\/v1\/relay\/machines\/report$/, async (req, b) => {
+      fromRelay(req)
+      const load = b.load && typeof b.load === 'object' && !Array.isArray(b.load) ? Object.fromEntries(Object.entries(b.load).filter(([, v]) => typeof v === 'number' && Number.isFinite(v)).slice(0, 20)) : {}
+      return cluster.report({ machine: machineOf(b), load, rooms: roomList(b.rooms) })
+    }, { maxBody: REPORT_BODY }],
+    // Where a room lives (placing it now if nobody has).
+    ['POST', /^\/v1\/relay\/placement$/, async (req, b) => {
+      fromRelay(req)
+      return cluster.place({ room: roomOf(b.room), machine: machineOf(b), have: b.have === true, create: b.create !== false })
+    }],
+    // A machine deleted a room for good (ended and swept, or idle past its days).
+    ['POST', /^\/v1\/relay\/placement\/forget$/, async (req, b) => {
+      fromRelay(req)
+      return cluster.forget({ room: roomOf(b.room), machine: machineOf(b) })
+    }],
+    // A hosted agent's sessions (on any machine) and its one webhook.
+    ['GET', /^\/v1\/relay\/hosted\/([^/]+)$/, async (req, b, [account]) => {
+      fromRelay(req)
+      const a = accountOf(account)
+      return { rooms: await store.hostedRoomsOf(a), webhook: await store.hostedWebhookOf(a) }
+    }],
+    ['POST', /^\/v1\/relay\/hosted\/([^/]+)\/rooms$/, async (req, b, [account]) => {
+      fromRelay(req)
+      const a = accountOf(account)
+      if (b.add !== undefined) await store.addHostedRoom(a, roomOf(b.add))
+      if (b.remove !== undefined) await store.removeHostedRoom(a, roomOf(b.remove))
+      return { rooms: await store.hostedRoomsOf(a) }
+    }],
+    ['PUT', /^\/v1\/relay\/hosted\/([^/]+)\/webhook$/, async (req, b, [account]) => {
+      fromRelay(req)
+      const a = accountOf(account)
+      const w = b.webhook
+      if (w !== null && (!w || typeof w !== 'object' || Array.isArray(w) || JSON.stringify(w).length > MAX_WEBHOOK || !/^https?:\/\//.test(String(w.url || '')))) throw new HttpError(400, 'give the webhook, or null')
+      // Removed is kept as { off: true }, so a machine with an older copy drops it instead of sharing it again.
+      await store.putHostedWebhook(a, w || { off: true })
+      return { ok: true }
+    }],
+    // Whether `account` owns session `room` or has been in it (a branch's live session elsewhere, plan §8).
+    ['POST', /^\/v1\/relay\/same-owner$/, async (req, b) => {
+      fromRelay(req)
+      return { same: await store.roomHasAccount(roomOf(b.room), accountOf(b.account)) }
+    }]
+  ]
+}