heyquilt 0.0.1 → 0.3.90

package/src/api/routes/github.js

@@ -0,0 +1,380 @@
+// Connecting GitHub (github-app.js): a person starts from the app or the website, GitHub asks them
+// which repositories to install Quilt on and who they are, and comes back here. The relay then asks
+// for a repository's credentials for a session's owner when an agent commits.
+import crypto from 'node:crypto'
+import { HttpError, Raw } from '../http.js'
+import { githubApp, signState, readStateFull, WRITE_ROLES, READ_ROLES, GitHubAppError } from '../github-app.js'
+import { orgAccess, orgGrantsFor } from '../org-access.js'
+import { workspaceAccess } from '../workspace-access.js'
+export { ensureWebhookSecret, redeliverFailed } from '../github-app.js'
+
+const PART = /^[A-Za-z0-9_.-]{1,100}$/
+/** A lease lapses this long after its last heartbeat: two missed heartbeats (plan §8). */
+export const LEASE_TTL_MS = 2 * 60 * 1000
+const ACCOUNT = /^person:([A-Za-z0-9_-]{1,64})$/
+const ACTOR = /^(person|agent):([A-Za-z0-9_-]{1,64})$/
+const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const MAX_REPOS = 200
+/** owner/name from what a person typed ("github.com/acme/widgets.git", "acme/widgets"), or null. */
+const cleanRepo = (v) => { const m = /^(?:https?:\/\/)?(?:github\.com\/)?([A-Za-z0-9_.-]{1,100})\/([A-Za-z0-9_.-]{1,100}?)(?:\.git)?\/?$/.exec(String(v || '').trim()); return m ? `${m[1]}/${m[2]}` : null }
+const digest = (s) => crypto.createHash('sha256').update(String(s)).digest()
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+
+/** The page GitHub sends people back to: plain, so it works from any browser. */
+const page = (title, text) => new Raw(200, `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;background:#fdf6f0;color:#2b2420;display:grid;place-items:center;min-height:100vh;margin:0;padding:16px}main{max-width:420px;text-align:center}h1{font-size:22px}</style>
+<main><h1>${esc(title)}</h1><p>${esc(text)}</p></main>`, 'text/html; charset=utf-8')
+
+export function githubRoutes ({ store, person, bearer, relaySecret, github: cfg, githubFetch, relayHttp = '', relayFetch = globalThis.fetch, tellRelays = null, now, log, hookSecret = { value: cfg && cfg.webhookSecret }, workspaces = false }) {
+  const app = cfg ? githubApp(cfg, { fetch: githubFetch, now }) : null
+  const need = () => { if (!app) throw new HttpError(503, 'GitHub is not set up on this server') }
+  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')
+  }
+  // Credentials per account and repository, kept until a few minutes before they run out.
+  const cache = new Map()
+  // What agents may commit, for a whole workspace or org: '' (each session decides), 'off', 'branches' or 'any'.
+  const agentCommitsGiven = (v) => {
+    if (v === '' || v === null) return ''
+    if (['off', 'branches', 'any'].includes(v)) return v
+    throw new HttpError(400, 'agentCommits is "" (each session decides), off, branches or any.')
+  }
+  // A nudge for the relay: every relay machine gets it (src/api/relay-cluster.js), each for the sessions it holds.
+  const tell = tellRelays || (async (path, body) => {
+    await relayFetch(`${relayHttp}${path}`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${relaySecret}` }, body: JSON.stringify(body) })
+  })
+  const nudge = (path, body, what) => {
+    if (!relayHttp || !relaySecret) return Promise.resolve()
+    return Promise.resolve().then(() => tell(path, body)).catch((err) => log(`${what} to relay: ${err.message}`))
+  }
+  // The relay asks its sessions again now (relay /github/policy), so a change applies at once.
+  const policyChanged = () => { nudge('/github/policy', {}, 'agent policy') }
+
+  /** A workspace by id that `userId` may manage GitHub for (its admins), or an HttpError. */
+  const workspaceToManage = async (userId, id, { manage = true } = {}) => {
+    if (!workspaces) throw new HttpError(404, 'not found')
+    const ws = UUID.test(String(id || '')) ? await store.workspaceById(id) : null
+    const a = ws && await workspaceAccess(store, ws, `person:${userId}`, { orgGrants: ws.orgId ? await orgGrantsFor(store, ws.orgId, `person:${userId}`) : null })
+    if (!a) throw new HttpError(404, 'no such workspace')
+    if (manage && !a.admin) throw new HttpError(403, 'only the workspace\'s admins change its GitHub connection')
+    return { ws, admin: !!a.admin }
+  }
+  /** Where a connection attaches (plan §2): the caller ('person', the default), a workspace they manage, or an org whose settings they may change. */
+  const scopeFor = async (userId, b) => {
+    const scope = ['workspace', 'org'].includes(b.scope) ? b.scope : 'person'
+    if (scope === 'person') return { scope, scopeId: userId }
+    if (scope === 'workspace') { const { ws } = await workspaceToManage(userId, b.id); return { scope, scopeId: ws.id } }
+    const org = await orgAccess(store, userId, b.id)
+    org.need('org', 'u')
+    return { scope, scopeId: org.org.id }
+  }
+  /** Who connected GitHub for a scope, with their GitHub login. */
+  const connectionsOf = async (scope, scopeId) => {
+    const out = []
+    for (const c of await store.githubConnections({ scope, scopeId })) {
+      const link = await store.githubLink(c.connectedBy)
+      const p = await store.profile(c.connectedBy).catch(() => null)
+      out.push({ connectedBy: c.connectedBy, name: (p && p.name) || '', login: link ? link.login : '', at: c.createdAt })
+    }
+    return out
+  }
+  /** The person an account works for (Require GitHub): a person themselves; an agent, its owner, or (an org's agent) the session's owner. */
+  const personFor = async (actor, session) => {
+    const m = ACTOR.exec(actor || '')
+    if (!m) return null
+    if (m[1] === 'person') return m[2]
+    const agent = await store.agentById(m[2]).catch(() => null)
+    if (agent && agent.ownerUserId) return agent.ownerUserId
+    const owner = session && ACCOUNT.exec(session.ownerAccount || '')
+    return owner ? owner[1] : null
+  }
+  /**
+   * Whose GitHub connections may cover `owner/name` for a session (plan §2): its workspace's, then its
+   * org's, then its people's own, in that order; { ids } or { refused } when the workspace's access mode
+   * keeps the repository out. With the org's Require GitHub and an `actingFor`, only the person that
+   * account works for counts: an agent gets their live GitHub permissions, no more.
+   */
+  const coverFor = async ({ room, accounts, actingFor, owner, name }) => {
+    const ids = []
+    let session = null
+    let ws = null
+    if (room) session = await store.sessionByRoom(room).catch(() => null)
+    if (session && session.workspaceId) ws = await store.workspaceById(session.workspaceId).catch(() => null)
+    let require = false
+    if (ws) {
+      const g = await store.workspaceGithub(ws.id)
+      if (g.access === 'repos' && !g.repos.some((r) => r.toLowerCase() === `${owner}/${name}`.toLowerCase())) return { refused: { state: 'not-allowed', why: `the workspace ${ws.name} works only with the repositories it lists, and ${owner}/${name} isn't one of them` } }
+      for (const c of await store.githubConnections({ scope: 'workspace', scopeId: ws.id })) ids.push(c.connectedBy)
+      if (ws.orgId) {
+        require = (await store.orgGithub(ws.orgId)).requireGithub
+        for (const c of await store.githubConnections({ scope: 'org', scopeId: ws.orgId })) ids.push(c.connectedBy)
+      }
+    }
+    if (require && actingFor) {
+      const who = await personFor(actingFor, session)
+      return { ids: who ? [who] : [], require: true, actingFor }
+    }
+    return { ids: [...new Set([...ids, ...accounts])], require }
+  }
+
+  return [
+    // Where to send a person to connect GitHub: installing the app, then back to the callback.
+    ['POST', /^\/v1\/github\/connect$/, async (req, b) => {
+      need()
+      const { userId } = await person(req)
+      const where = await scopeFor(userId, b)
+      // For a repository: straight to its owner's (person's or organization's) install page, skipping the account picker.
+      const m = /^(?:github\.com\/)?([A-Za-z0-9_.-]{1,100})\/[A-Za-z0-9_.-]{1,100}$/.exec(String(b.repo || '').replace(/\.git$/, ''))
+      const target = m ? await app.accountId(m[1]).catch(() => null) : null
+      return { url: app.installUrl(signState(cfg, userId, now(), where.scope === 'person' ? {} : where), { targetId: target }) }
+    }],
+    ['GET', /^\/v1\/me\/github$/, async (req) => {
+      const { userId } = await person(req)
+      const link = await store.githubLink(userId)
+      return { available: !!app, connected: !!link, ...(link ? { login: link.login } : {}) }
+    }],
+    ['DELETE', /^\/v1\/me\/github$/, async (req) => {
+      const { userId } = await person(req)
+      await store.deleteGithubLink(userId)
+      cache.clear()
+      return { ok: true }
+    }],
+    // GitHub sends the person back here after the install, with who they are (code) and our state.
+    ['GET', /^\/v1\/github\/(callback|setup)$/, async (req) => {
+      need()
+      const q = new URL(req.url, 'http://x').searchParams
+      const st = readStateFull(cfg, q.get('state'), now())
+      const userId = st ? st.userId : null
+      if (!userId) return page('Start from Quilt', 'Open Quilt and click Connect GitHub in the commit panel, so Quilt knows which account to connect. Quilt is installed on GitHub either way.')
+      if (!q.get('code')) return page('GitHub did not sign you in', 'Try Connect GitHub again from Quilt.')
+      let who
+      try { who = await app.whoAuthorized(q.get('code')) } catch (err) { log(`github connect: ${err.message}`); return page('GitHub did not sign you in', 'Try Connect GitHub again from Quilt.') }
+      await store.setGithubLink(userId, { githubId: who.id, login: who.login })
+      // Connected for a workspace or an org (plan §2): its sessions use this connection before their people's own.
+      if (st.scope) {
+        const inst = Number(q.get('installation_id'))
+        await store.addGithubConnection({ scope: st.scope, scopeId: st.scopeId, connectedBy: userId, installationId: Number.isSafeInteger(inst) && inst > 0 ? inst : null })
+      }
+      cache.clear()
+      // The relay checks every session this person is in again now, so the card in their app clears as they come back.
+      nudge('/github/connected', { account: `person:${userId}` }, 'github connected')
+      // An organization that has its admins approve apps: the install is asked for, not done yet.
+      if (q.get('setup_action') === 'request') return page(`Asked, as @${who.login}`, 'The organization\'s admins have to approve Quilt on GitHub. As soon as they do, agents in your sessions on its repositories commit and merge on their own; nothing more to do on your side. You can close this tab.')
+      if (st.scope) return page(`Connected as @${who.login}`, `Sessions in this ${st.scope} use this connection now, before their people's own. You can close this tab.`)
+      return page(`Connected as @${who.login}`, 'Agents in your sessions can now commit and merge on the repositories you installed Quilt on, as far as each session\'s owner allows, and pushes reach the session within seconds. You can close this tab.')
+    }],
+    // A workspace's GitHub: its connections and access mode ('open', or 'repos' with the repositories it allows).
+    ['GET', /^\/v1\/workspaces\/([^/]+)\/github$/, async (req) => {
+      const { userId } = await person(req)
+      const { ws, admin } = await workspaceToManage(userId, req.url.split('/')[3], { manage: false })
+      let org = null
+      if (ws.orgId) {
+        const o = await store.orgById(ws.orgId)
+        const g = await orgGrantsFor(store, ws.orgId, `person:${userId}`)
+        const og = await store.orgGithub(ws.orgId)
+        org = { slug: o ? o.slug : '', name: o ? o.name : '', requireGithub: og.requireGithub, agentCommits: og.agentCommits, admin: !!(g && g.can('org', 'u')), connections: await connectionsOf('org', ws.orgId) }
+      }
+      return { ...(await store.workspaceGithub(ws.id)), connections: await connectionsOf('workspace', ws.id), admin, me: userId, ...(org ? { org } : {}) }
+    }],
+    ['PUT', /^\/v1\/workspaces\/([^/]+)\/github$/, async (req, b) => {
+      const { userId } = await person(req)
+      const { ws } = await workspaceToManage(userId, req.url.split('/')[3])
+      const patch = {}
+      if ('access' in b) {
+        const access = b.access === 'repos' ? 'repos' : b.access === 'open' ? 'open' : null
+        if (!access) throw new HttpError(400, 'Access is open or repos.')
+        const given = Array.isArray(b.repos) ? b.repos : []
+        const repos = [...new Set(given.map(cleanRepo))]
+        if (repos.includes(null)) throw new HttpError(400, 'Give repositories as owner/name.')
+        if (repos.length > MAX_REPOS) throw new HttpError(400, `List at most ${MAX_REPOS} repositories.`)
+        if (access === 'repos' && !repos.length) throw new HttpError(400, 'List the repositories this workspace may use.')
+        Object.assign(patch, { access, repos })
+      }
+      if ('agentCommits' in b) patch.agentCommits = agentCommitsGiven(b.agentCommits)
+      if (!Object.keys(patch).length) throw new HttpError(400, 'Give access (and repos) or agentCommits.')
+      await store.setWorkspaceGithub(ws.id, patch)
+      cache.clear()
+      if ('agentCommits' in patch) policyChanged()
+      return store.workspaceGithub(ws.id)
+    }],
+    ['DELETE', /^\/v1\/workspaces\/([^/]+)\/github\/connection$/, async (req, b) => {
+      const { userId } = await person(req)
+      const { ws, admin } = await workspaceToManage(userId, req.url.split('/')[3], { manage: false })
+      const whose = typeof b.connectedBy === 'string' && b.connectedBy ? b.connectedBy : userId
+      if (whose !== userId && !admin) throw new HttpError(403, 'only the workspace\'s admins remove others\' connections')
+      await store.removeGithubConnection({ scope: 'workspace', scopeId: ws.id, connectedBy: whose })
+      cache.clear()
+      return { ok: true }
+    }],
+    // An org's GitHub: its connections and the Require GitHub switch.
+    ['GET', /^\/v1\/orgs\/([^/]+)\/github$/, async (req) => {
+      const { userId } = await person(req)
+      const org = await orgAccess(store, userId, decodeURIComponent(req.url.split('/')[3]))
+      return { ...(await store.orgGithub(org.org.id)), connections: await connectionsOf('org', org.org.id), admin: org.can('org', 'u') }
+    }],
+    ['PUT', /^\/v1\/orgs\/([^/]+)\/github$/, async (req, b) => {
+      const { userId } = await person(req)
+      const org = await orgAccess(store, userId, decodeURIComponent(req.url.split('/')[3]))
+      org.need('org', 'u')
+      const patch = {}
+      if ('requireGithub' in b) {
+        if (typeof b.requireGithub !== 'boolean') throw new HttpError(400, 'Say requireGithub: true or false.')
+        patch.requireGithub = b.requireGithub
+      }
+      if ('agentCommits' in b) patch.agentCommits = agentCommitsGiven(b.agentCommits)
+      if (!Object.keys(patch).length) throw new HttpError(400, 'Give requireGithub or agentCommits.')
+      await store.setOrgGithub(org.org.id, patch)
+      cache.clear()
+      if ('agentCommits' in patch) policyChanged()
+      return store.orgGithub(org.org.id)
+    }],
+    ['DELETE', /^\/v1\/orgs\/([^/]+)\/github\/connection$/, async (req, b) => {
+      const { userId } = await person(req)
+      const org = await orgAccess(store, userId, decodeURIComponent(req.url.split('/')[3]))
+      const whose = typeof b.connectedBy === 'string' && b.connectedBy ? b.connectedBy : userId
+      if (whose !== userId) org.need('org', 'u')
+      await store.removeGithubConnection({ scope: 'org', scopeId: org.org.id, connectedBy: whose })
+      cache.clear()
+      return { ok: true }
+    }],
+    // GitHub's events, signed with the app's webhook secret (set by the API itself, github-app.js
+    // ensureWebhookSecret). Each is passed to the relay as a hint with what it needs; the relay
+    // trusts only the ref name and reads the truth from git.
+    ['POST', /^\/v1\/github\/webhook$/, async (req, raw) => {
+      const secret = hookSecret.value || ''
+      if (!cfg || !secret) throw new HttpError(503, 'GitHub webhooks are not set up on this server')
+      {
+        const sig = String(req.headers['x-hub-signature-256'] || '')
+        const want = 'sha256=' + crypto.createHmac('sha256', secret).update(raw).digest('hex')
+        if (sig.length !== want.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want))) throw new HttpError(401, 'bad signature')
+      }
+      const event = String(req.headers['x-github-event'] || '')
+      if (!['push', 'create', 'delete', 'pull_request', 'check_suite'].includes(event)) return { ok: true }
+      let e
+      try { e = JSON.parse(raw.toString('utf8')) } catch { throw new HttpError(400, 'bad json') }
+      const repo = e && e.repository && typeof e.repository.full_name === 'string' ? e.repository.full_name : ''
+      if (!repo || !relayHttp || !relaySecret) return { ok: true }
+      const tellHook = (path, body) => nudge(path, { repo: `github.com/${repo}`, ...body }, 'github webhook')
+      const sha = (v) => typeof v === 'string' && /^[0-9a-f]{40}$/.test(v) ? v : ''
+      if (event === 'pull_request') {
+        // A pull request changed (opened, closed, merged, synchronized): the relay looks at the one its tasks are in.
+        const pr = e.pull_request || {}
+        const number = Number.isInteger(pr.number) ? pr.number : (Number.isInteger(e.number) ? e.number : null)
+        const ref = (x) => x && typeof x.ref === 'string' ? x.ref : ''
+        if (number != null) await tellHook('/github/pull', { number, action: String(e.action || ''), ...(pr.merged === true ? { merged: true } : {}), ...(ref(pr.head) ? { head: ref(pr.head) } : {}), ...(ref(pr.base) ? { base: ref(pr.base) } : {}), ...(sha(pr.merge_commit_sha) ? { sha: pr.merge_commit_sha } : {}) })
+        return { ok: true }
+      }
+      if (event === 'check_suite') {
+        const cs = e.check_suite || {}
+        if (sha(cs.head_sha)) await tellHook('/github/checks', { sha: cs.head_sha, branch: typeof cs.head_branch === 'string' ? cs.head_branch : '', conclusion: String(cs.conclusion || '') })
+        return { ok: true }
+      }
+      if (event === 'create' || event === 'delete') {
+        if (e.ref_type !== 'branch' || typeof e.ref !== 'string' || !e.ref) return { ok: true }
+        await tellHook('/github/push', { ref: e.ref, ...(event === 'create' ? { created: true } : { deleted: true }) })
+        return { ok: true }
+      }
+      const ref = typeof e.ref === 'string' && e.ref.startsWith('refs/heads/') ? e.ref.slice('refs/heads/'.length) : ''
+      if (!ref) return { ok: true }
+      const after = e.deleted ? '' : sha(e.after)
+      await tellHook('/github/push', { ref, before: sha(e.before), after, sha: after, forced: !!e.forced, deleted: !!e.deleted })
+      return { ok: true }
+    }, { raw: true, maxBody: 25 * 1024 * 1024 }],
+    // The relay: whether git is on for everyone in a session, and what agents may push there, when a rule
+    // above the session says (docs/superpowers/specs/2026-10-17-git-for-everyone.md): its org's, the teams'
+    // its owner is on (in the org) and its workspace's. Each rule is a ceiling (off < branches < any), so the
+    // strictest is the one that holds; at equal strictness the broader is named, since that's the one to change.
+    // { agentCommits: '' } when none is set: the session's owner decides.
+    ['POST', /^\/v1\/relay\/session-policy$/, async (req, b) => {
+      fromRelay(req)
+      const room = typeof b.room === 'string' && ROOM.test(b.room) ? b.room : ''
+      if (!room) throw new HttpError(400, 'give the room')
+      const session = await store.sessionByRoom(room).catch(() => null)
+      const ws = session && session.workspaceId ? await store.workspaceById(session.workspaceId).catch(() => null) : null
+      if (!ws) return { agentCommits: '' }
+      const rules = []
+      if (ws.orgId) {
+        const o = await store.orgGithub(ws.orgId)
+        if (o.agentCommits) { const org = await store.orgById(ws.orgId).catch(() => null); rules.push({ agentCommits: o.agentCommits, by: 'org', name: (org && org.name) || '' }) }
+        const owner = ACCOUNT.exec(session.ownerAccount || '')
+        const member = owner ? await store.memberOf(ws.orgId, owner[1]).catch(() => null) : null
+        if (member) for (const r of await store.teamGitRules(member.id)) rules.push({ agentCommits: r.agentCommits, by: 'team', name: r.name })
+      }
+      const w = await store.workspaceGithub(ws.id)
+      if (w.agentCommits) rules.push({ agentCommits: w.agentCommits, by: 'workspace', name: ws.name || '' })
+      if (!rules.length) return { agentCommits: '' }
+      const rank = { off: 0, branches: 1, any: 2 }
+      // Stable: the first of the strictest, and rules are in order broadest first.
+      return rules.reduce((best, r) => rank[r.agentCommits] < rank[best.agentCommits] ? r : best)
+    }],
+    // The relay: one live session per repository and branch (plan §8). Leases lapse LEASE_TTL_MS after the last heartbeat.
+    ['POST', /^\/v1\/relay\/leases\/(take|heartbeat|release)$/, async (req, b) => {
+      fromRelay(req)
+      const what = new URL(req.url, 'http://x').pathname.split('/').pop()
+      const repo = String(b.repo || ''); const branch = String(b.branch || ''); const room = String(b.room || '')
+      if (!/^[A-Za-z0-9.-]{1,100}\/[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}$/.test(repo) || !branch || branch.length > 255 || !/^[A-Za-z0-9_-]{1,64}$/.test(room)) throw new HttpError(400, 'give repo (host/owner/name), branch and room')
+      const ttlMs = Math.max(1000, Math.min(10 * 60_000, Number(b.ttlMs) || LEASE_TTL_MS))
+      const generation = Number.isInteger(b.generation) ? b.generation : 0
+      if (what === 'take') return store.takeLease({ repo, branch, room, holder: String(b.holder || '').slice(0, 100), ttlMs })
+      if (what === 'heartbeat') return store.heartbeatLease({ repo, branch, room, generation, ttlMs })
+      return store.releaseLease({ repo, branch, room, generation })
+    }],
+    // The relay: which GitHub accounts the session's people linked (login and id), for commit authorship
+    // (relay-outbound.js: a person's commits carry their GitHub noreply address). Never a token.
+    ['POST', /^\/v1\/relay\/github-logins$/, async (req, b) => {
+      fromRelay(req)
+      const given = Array.isArray(b.accounts) ? b.accounts : []
+      const accounts = [...new Set(given.map((x) => { const m = ACCOUNT.exec(String(x || '')); return m ? m[1] : null }).filter(Boolean))].slice(0, 200)
+      const logins = {}
+      for (const id of accounts) { const l = await store.githubLink(id); if (l) logins[`person:${id}`] = { login: l.login, id: l.githubId } }
+      return { logins }
+    }],
+    // The relay: credentials for one repository, for the first of the session's people whose linked
+    // GitHub account may do what is asked there (write: commit, merge; read: fetch, clone).
+    ['POST', /^\/v1\/relay\/github-token$/, async (req, b) => {
+      fromRelay(req)
+      need()
+      const access = b.access === 'read' ? 'read' : 'write'
+      const given = Array.isArray(b.accounts) ? b.accounts : b.account ? [b.account] : []
+      const members = [...new Set(given.map((x) => { const m = ACCOUNT.exec(String(x || '')); return m ? m[1] : null }).filter(Boolean))].slice(0, 50)
+      const [owner, name] = String(b.repo || '').split('/')
+      if (!members.length || !PART.test(owner || '') || !PART.test(name || '')) throw new HttpError(400, 'give the session\'s people (person:<id>) and the repository (owner/name)')
+      // `room`: the session asking, for its workspace's and org's connections and access mode; `actingFor`: who the token is for.
+      const room = typeof b.room === 'string' && ROOM.test(b.room) ? b.room : ''
+      const actingFor = typeof b.actingFor === 'string' && ACTOR.test(b.actingFor) ? b.actingFor : ''
+      const cover = await coverFor({ room, accounts: members, actingFor, owner, name })
+      if (cover.refused) return cover.refused
+      const accounts = cover.ids
+      const linked = []
+      for (const id of accounts) { const l = await store.githubLink(id); if (l) linked.push({ id, ...l }) }
+      if (!linked.length) return { state: 'not-connected', ...(cover.require ? { require: true, actingFor } : {}) }
+      // `fresh`: a token of its own for one agent (minted anew, not kept): it can be revoked on its own.
+      const fresh = b.fresh === true
+      const key = (id) => `${id}\0${owner}/${name}\0${access}`.toLowerCase()
+      if (!fresh) for (const l of linked) { const hit = cache.get(key(l.id)); if (hit && hit.expiresAt - now() > 5 * 60 * 1000) return { state: 'ok', ...hit } }
+      try {
+        const inst = await app.installation(owner, name)
+        if (!inst) return { state: 'not-installed', login: linked[0].login, installUrl: `https://github.com/apps/${cfg.slug}/installations/new` }
+        // One token for the role checks (read is enough to ask), then one with what was asked for.
+        const probe = await app.repoToken(inst, name, { access: 'read' })
+        let first = null
+        for (const l of linked) {
+          const role = await app.role(probe.token, owner, name, l.login)
+          const ok = access === 'read' ? READ_ROLES.includes(role) : WRITE_ROLES.includes(role)
+          if (!first) first = { login: l.login, role }
+          if (!ok) continue
+          const t = access === 'read' && !fresh ? probe : await app.repoToken(inst, name, { access })
+          const out = { token: t.token, expiresAt: t.expiresAt, login: l.login }
+          if (!fresh) cache.set(key(l.id), out)
+          return { state: 'ok', ...out }
+        }
+        return { state: 'no-access', login: first.login, role: first.role }
+      } catch (err) {
+        if (err instanceof GitHubAppError) { log(`github token for ${owner}/${name}: ${err.message}`); return { state: 'error', error: err.message } }
+        throw err
+      }
+    }]
+  ]
+}

package/src/api/routes/grants.js

@@ -0,0 +1,70 @@
+// Who gets what in a session: the owner gives someone (an account) an access type,
+// optionally narrowed. The API is where access lives; passes carry it to the relay.
+import { HttpError } from '../http.js'
+import { cleanTighten } from '../../session-access.js'
+import { ownType, grantView } from '../access.js'
+
+export const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+export const ACCOUNT = /^(person|agent):[A-Za-z0-9_-]{1,64}$/
+const EMAIL_KEY = /^[^\s@,;<>"()\\]+@[^\s@,;<>"()\\]+$/
+export const NOT_YET = "That session hasn't reached heyquilt.com yet. Try again in a minute."
+
+/**
+ * The session's owner, from their request: { me: 'person:<id>', userId, session }. 404 for a
+ * session the API hasn't heard of (the relay reports new ones within seconds), 403 for anyone else.
+ */
+export async function sessionOwner (store, person, req, room, forbidden = 'Only the session owner can change who gets in.') {
+  const { userId } = await person(req)
+  const me = `person:${userId}`
+  if (!ROOM.test(room)) throw new HttpError(404, NOT_YET)
+  const session = await store.sessionByRoom(room)
+  if (!session) throw new HttpError(404, NOT_YET)
+  if (session.ownerAccount !== me) throw new HttpError(403, forbidden)
+  return { me, userId, session }
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * The owner letting an agent into a session again (a grant) also ends keeping it out of that
+ * session, which removing it from a session in a workspace starts. Only with workspaces on.
+ */
+export async function letAgentBackIn (store, room, account, workspaces, log = () => {}) {
+  if (!workspaces || !String(account).startsWith('agent:') || !UUID.test(account.slice(6))) return
+  // The grant is already written: a failure here is logged, never the request's answer.
+  try { await store.removeSessionAgentExclusion(room, account.slice(6)) } catch (err) { log(`could not end keeping ${account} out of ${room}: ${err.message}`) }
+}
+
+export function grantRoutes ({ store, person, now = Date.now, workspaces = false, log = () => {} }) {
+  return [
+    ['GET', /^\/v1\/sessions\/([^/]+)\/grants$/, async (req, body, [room]) => {
+      await sessionOwner(store, person, req, room)
+      return { grants: await Promise.all((await store.listGrants(room)).map((g) => grantView(store, g))) }
+    }],
+
+    ['PUT', /^\/v1\/sessions\/([^/]+)\/grants\/([^/]+)$/, async (req, body, [room, account]) => {
+      const { me } = await sessionOwner(store, person, req, room)
+      if (!ACCOUNT.test(account)) throw new HttpError(400, 'Grants are for people and agents (person:<id> or agent:<id>).')
+      if (account === me) throw new HttpError(400, 'The owner always has full access.')
+      const type = await ownType(store, me, body.typeId)
+      if (!type) throw new HttpError(400, 'no such access type')
+      let tighten
+      try { tighten = cleanTighten(body.tighten) } catch (err) { throw new HttpError(400, err.message) }
+      const grant = await store.putGrant({ room, account, typeId: type.id, tighten, grantedBy: me })
+      await letAgentBackIn(store, room, account, workspaces, log)
+      return { grant: await grantView(store, grant) }
+    }],
+
+    ['DELETE', /^\/v1\/sessions\/([^/]+)\/grants\/([^/]+)$/, async (req, body, [room, account]) => {
+      await sessionOwner(store, person, req, room)
+      // An account, or an email invite's grant (left by an invite that expired, say).
+      const email = account.startsWith('email:') ? account.slice('email:'.length) : ''
+      if (!ACCOUNT.test(account) && !(email && EMAIL_KEY.test(email))) throw new HttpError(400, 'no such account')
+      await store.deleteGrant(room, account)
+      // Their open invite would still list as waiting, for access they no longer have.
+      const open = await store.openSessionInvite(room, email ? { email } : { account }, now())
+      if (open) await store.cancelSessionInvite(open.id)
+      return { ok: true }
+    }]
+  ]
+}

package/src/api/routes/invites.js

@@ -0,0 +1,188 @@
+// Joining an org: email invites (the API sends them) and domain join requests.
+import { HttpError, needId, stripInvisible } from '../http.js'
+import { orgAccess } from '../org-access.js'
+import { newToken, hashToken } from '../tokens.js'
+import { emailDomain, isPublicDomain } from '../domains.js'
+import { inviteEmail } from '../invite-email.js'
+
+const INVITE_TTL_MS = 7 * 24 * 60 * 60 * 1000
+const GONE = {
+  accepted: 'this invite was already used',
+  cancelled: 'this invite was cancelled',
+  expired: 'this invite has expired; ask for a new one'
+}
+// One address, no separators or angle brackets/quotes/parens a mail header could
+// smuggle through, and exactly one '@' (so "a@x.com,b@y.com" can't sneak a second
+// recipient past nodemailer). `emailDomain` still checks the part after '@' is a real domain.
+const STRICT_EMAIL = /^[^\s@,;<>"()\\]+@[^\s@,;<>"()\\]+$/
+
+export function inviteRoutes ({ store, user, now, site, mailer, log, limit, limitSend }) {
+  const orgFor = async (req, slug) => { const u = await user(req); return { u, ...(await orgAccess(store, u.userId, slug)) } }
+  const statusOf = (i) => (i.acceptedAt ? 'accepted' : i.cancelledAt ? 'cancelled' : i.expiresAt < now() ? 'expired' : 'pending')
+  const inviteView = (i, role) => ({ id: i.id, email: i.email, roleId: i.roleId, role, expiresAt: i.expiresAt, createdAt: i.createdAt, expired: i.expiresAt < now() })
+
+  // The domain of the caller's confirmed email, unless it belongs to a public mail provider.
+  async function confirmedDomain (userId) {
+    const mine = await store.userEmail(userId)
+    const d = mine?.confirmed ? emailDomain(mine.email) : ''
+    return d && !isPublicDomain(d) ? d : null
+  }
+
+  // A single, real-looking address; never a list, and never one a mail header could split.
+  function cleanEmail (raw) {
+    const email = String(raw || '').trim().toLowerCase()
+    if (!email || email.length > 254 || !STRICT_EMAIL.test(email) || !emailDomain(email)) throw new HttpError(400, "that email doesn't look right")
+    return email
+  }
+
+  // Someone already in the org, by their signed-in email — so an invite (or its
+  // acceptance) can't hand a second membership, or a second role, to the same person.
+  async function memberWithEmail (orgId, email) {
+    for (const m of await store.listMembers(orgId)) {
+      // Agent members have no userId (and so no signed-in email) to collide with.
+      if (!m.userId) continue
+      const e = await store.userEmail(m.userId)
+      if (String(e?.email || '').toLowerCase() === email) return m
+    }
+    return null
+  }
+
+  // The link only ever travels by email; only its hash is stored.
+  async function mail (a, invite, role, token) {
+    const inviter = await store.profile(a.u.userId)
+    // A profile name is free text; strip anything that could hide or reorder
+    // characters before it lands in the invite email's subject line.
+    const inviterName = stripInvisible(inviter?.name || '').join('').trim() || undefined
+    const msg = inviteEmail({ orgName: a.org.name, inviterName, roleName: role.name, link: `${site}/invite/${token}` })
+    try {
+      await mailer.send({ to: invite.email, ...msg })
+    } catch (err) {
+      log(`invite email failed: ${err?.stack || err?.message || err}`)
+      throw new HttpError(502, "the invite was saved but the email didn't send; try Resend")
+    }
+  }
+
+  async function openInvite (a, id) {
+    const i = await store.inviteById(a.org.id, needId(id, 'invite'))
+    if (!i || i.acceptedAt || i.cancelledAt) throw new HttpError(404, 'no such invite')
+    return i
+  }
+
+  return [
+    ['GET', /^\/v1\/orgs\/([^/]+)\/invites$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      a.need('invites', 'r')
+      const roles = new Map((await store.listRoles(a.org.id)).map((r) => [r.id, r.name]))
+      const [invites, requests] = await Promise.all([store.listInvites(a.org.id), store.listJoinRequests(a.org.id)])
+      return {
+        invites: invites.map((i) => inviteView(i, roles.get(i.roleId) || null)),
+        requests: requests.map((r) => ({ id: r.id, userId: r.userId, name: r.name, email: r.email, createdAt: r.createdAt }))
+      }
+    }],
+
+    ['POST', /^\/v1\/orgs\/([^/]+)\/invites$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      a.need('invites', 'c')
+      limitSend(a.u.userId)
+      const email = cleanEmail(body.email)
+      const role = await a.assignable(body.roleId)
+      if (await memberWithEmail(a.org.id, email)) throw new HttpError(409, 'that person is already a member')
+      // Never cancel someone else's invite just by sending a new one to the same
+      // address: a narrow inviter (User invites: Create only) could otherwise
+      // swap out an owner's pending Admin invite for a Member one.
+      if ((await store.listInvites(a.org.id)).some((old) => old.email === email && statusOf(old) === 'pending')) {
+        throw new HttpError(409, 'That address already has an open invite. Resend or cancel it.')
+      }
+      const token = newToken('qi_')
+      const invite = await store.createInvite({ orgId: a.org.id, email, roleId: role.id, tokenHash: hashToken(token), invitedBy: a.u.userId, expiresAt: now() + INVITE_TTL_MS })
+      await mail(a, invite, role, token)
+      return { invite: inviteView(invite, role.name) }
+    }],
+
+    ['POST', /^\/v1\/orgs\/([^/]+)\/invites\/([^/]+)\/resend$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('invites', 'u')
+      limitSend(a.u.userId)
+      const invite = await openInvite(a, id)
+      const role = await store.roleById(a.org.id, invite.roleId)
+      if (!role) throw new HttpError(404, 'no such role')
+      if (!a.covers(role.grants)) throw new HttpError(403, 'you can only resend invites within your own permissions')
+      const token = newToken('qi_')
+      const fresh = await store.updateInvite(invite.id, { tokenHash: hashToken(token), expiresAt: now() + INVITE_TTL_MS })
+      await mail(a, fresh, role, token)
+      return { invite: inviteView(fresh, role.name) }
+    }],
+
+    ['DELETE', /^\/v1\/orgs\/([^/]+)\/invites\/([^/]+)$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('invites', 'd')
+      await store.updateInvite((await openInvite(a, id)).id, { cancelledAt: now() })
+      return { ok: true }
+    }],
+
+    ['GET', /^\/v1\/invites\/([^/]+)$/, async (req, body, [token]) => {
+      await user(req)
+      limit(req)
+      const invite = await store.inviteByToken(hashToken(token))
+      if (!invite) throw new HttpError(404, 'no such invite')
+      const org = await store.orgById(invite.orgId)
+      const role = await store.roleById(invite.orgId, invite.roleId)
+      return { org: { name: org.name, slug: org.slug }, email: invite.email, role: role?.name || null, status: statusOf(invite) }
+    }],
+
+    ['POST', /^\/v1\/invites\/accept$/, async (req, body) => {
+      const u = await user(req)
+      limit(req)
+      const invite = await store.inviteByToken(hashToken(body.token))
+      if (!invite) throw new HttpError(404, 'no such invite')
+      const status = statusOf(invite)
+      if (status !== 'pending') throw new HttpError(410, GONE[status])
+      // Only the person it was sent to, once they've proved they own the address.
+      const mine = await store.userEmail(u.userId)
+      if (String(mine?.email || '').toLowerCase() !== invite.email) throw new HttpError(403, `this invite is for ${invite.email}; sign in with that address`)
+      if (!mine.confirmed) throw new HttpError(403, 'confirm your email address first, then open the invite again')
+      if (await store.memberOf(invite.orgId, u.userId)) throw new HttpError(409, "You're already in this org.")
+      if (!await store.claimInvite(invite.id)) throw new HttpError(410, GONE.accepted)
+      const org = await store.orgById(invite.orgId)
+      await store.addMember({ orgId: org.id, userId: u.userId, roleId: invite.roleId })
+      return { org: { name: org.name, slug: org.slug } }
+    }],
+
+    ['GET', /^\/v1\/orgs\/discover$/, async (req) => {
+      const u = await user(req)
+      const domain = await confirmedDomain(u.userId)
+      if (!domain) return { domain: null, orgs: [] }
+      const [orgs, mine, asked] = await Promise.all([store.orgsByDomain(domain), store.orgsForUser(u.userId), store.joinRequestsForUser(u.userId)])
+      const joined = new Set(mine.map((o) => o.id))
+      const pending = new Set(asked.filter((r) => r.status === 'pending').map((r) => r.orgId))
+      return { domain, orgs: orgs.filter((o) => !joined.has(o.id)).map((o) => ({ name: o.name, slug: o.slug, requested: pending.has(o.id) })) }
+    }],
+
+    ['POST', /^\/v1\/orgs\/([^/]+)\/requests$/, async (req, body, [slug]) => {
+      const u = await user(req)
+      limit(req)
+      const org = await store.orgBySlug(String(slug).toLowerCase())
+      const domain = await confirmedDomain(u.userId)
+      // One answer for a missing org and one you can't ask to join, so addresses can't be probed.
+      if (!org || !org.domainRequests || !domain || org.domain !== domain) throw new HttpError(404, 'no such org')
+      if (await store.memberOf(org.id, u.userId)) throw new HttpError(409, "you're already in this org")
+      const mine = await store.userEmail(u.userId)
+      const r = await store.createJoinRequest({ orgId: org.id, userId: u.userId, email: mine.email.toLowerCase() })
+      return { request: { id: r.id, status: r.status } }
+    }],
+
+    ['POST', /^\/v1\/orgs\/([^/]+)\/requests\/([^/]+)$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      if (typeof body.approve !== 'boolean') throw new HttpError(400, 'approve must be true or false')
+      const approve = body.approve
+      // Approving is User invites: Create; denying is User invites: Delete.
+      a.need('invites', approve ? 'c' : 'd')
+      const r = await store.joinRequestById(a.org.id, needId(id, 'request'))
+      if (!r || r.status !== 'pending') throw new HttpError(404, 'no such request')
+      const role = approve ? await a.assignable(body.roleId) : null
+      if (!await store.decideJoinRequest(r.id, { status: approve ? 'approved' : 'denied', decidedBy: a.u.userId })) throw new HttpError(404, 'no such request')
+      if (approve) await store.addMember({ orgId: a.org.id, userId: r.userId, roleId: role.id })
+      return { status: approve ? 'approved' : 'denied' }
+    }]
+  ]
+}