heyquilt 0.0.1 → 0.3.90

package/src/relay-filekey.js

@@ -0,0 +1,46 @@
+// The relay's own key for large files (plan §10): an X25519 key pair kept in its data folder, made
+// once; on many machines, one key they all share (QUILT_RELAY_FILE_KEY, a Fly secret). Apps wrap
+// the file keys of branches that sync with GitHub for its public key (largefiles.js wrapForRelay),
+// once the session owner agrees, so the relay can read those files to commit them.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { relayKeyId } from './largefiles.js'
+
+/** The key from QUILT_RELAY_FILE_KEY: the PEM itself, or base64 of it (a Fly secret is one line). */
+export function parseFileKey (value) {
+  const v = String(value || '').trim()
+  if (!v) return null
+  const pem = v.includes('-----BEGIN') ? v.replace(/\\n/g, '\n') : Buffer.from(v, 'base64').toString('utf8')
+  let key
+  try { key = crypto.createPrivateKey(pem) } catch { throw new Error('QUILT_RELAY_FILE_KEY is not a private key (PEM, or base64 of the PEM)') }
+  if (key.asymmetricKeyType !== 'x25519') throw new Error('QUILT_RELAY_FILE_KEY is not an X25519 key')
+  return key
+}
+
+/**
+ * { publicKey (spki DER, base64url), id, privateKey (KeyObject), shared }: the one every relay
+ * machine shares (`shared`, from QUILT_RELAY_FILE_KEY), else from `dataDir`, or made now (and
+ * saved there). A shared key that differs from the one on disk is logged: files wrapped for the
+ * disk's key can't be read until the owner agrees again.
+ */
+export function relayFileKey (dataDir, { pem = process.env.QUILT_RELAY_FILE_KEY || '', log = () => {} } = {}) {
+  const file = dataDir ? path.join(dataDir, 'relay-file-key.pem') : null
+  let privateKey = parseFileKey(pem)
+  const shared = !!privateKey
+  let onDisk = null
+  if (file) { try { onDisk = crypto.createPrivateKey(fs.readFileSync(file, 'utf8')) } catch {} }
+  if (shared) {
+    if (onDisk && !onDisk.equals(privateKey)) log(`relay file key: QUILT_RELAY_FILE_KEY differs from ${file}; using QUILT_RELAY_FILE_KEY`)
+  } else privateKey = onDisk
+  if (!privateKey || privateKey.asymmetricKeyType !== 'x25519') {
+    privateKey = crypto.generateKeyPairSync('x25519').privateKey
+    if (file) {
+      fs.mkdirSync(dataDir, { recursive: true })
+      fs.writeFileSync(file + '.tmp', privateKey.export({ format: 'pem', type: 'pkcs8' }), { mode: 0o600 })
+      fs.renameSync(file + '.tmp', file)
+    }
+  }
+  const publicKey = crypto.createPublicKey(privateKey).export({ format: 'der', type: 'spki' }).toString('base64url')
+  return { publicKey, id: relayKeyId(publicKey), privateKey, shared }
+}

package/src/relay-git.js

@@ -0,0 +1,274 @@
+// The relay's git mirror: one bare repository per GitHub repository on the relay's volume
+// (data/git/<host>/<owner>/<repo>.git). Every piece of git data moves over the git protocol
+// (fetch and push), never GitHub's REST API, so a 300-file commit is one push and no
+// content quota is spent.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { execFile } from 'node:child_process'
+
+const GIT_TIMEOUT_MS = 60 * 1000
+const SAFE = /^[A-Za-z0-9._-]{1,100}$/
+
+/** Where `repo` ({ host, owner, name }, relay-upstream.js parseRepo) is mirrored under `dataDir`. */
+export function mirrorDir (dataDir, repo) {
+  for (const part of [repo.host, repo.owner, repo.name]) if (!SAFE.test(String(part || '')) || part === '.' || part === '..') throw new Error(`not a repository name: ${part}`)
+  return path.join(dataDir, 'git', repo.host, repo.owner, `${repo.name}.git`)
+}
+
+/** Runs git in `dir`: { ok, out, err }. Never rejects. `env` is added to the process's. */
+export function runGit (dir, args, { env = {}, timeout = GIT_TIMEOUT_MS, input, buffer = false } = {}) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = execFile(process.env.QUILT_GIT || 'git', args, { cwd: dir, encoding: buffer ? 'buffer' : 'utf8', timeout, maxBuffer: 256 * 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', ...env } },
+        (err, stdout, stderr) => resolve({ ok: !err, out: buffer ? (stdout || Buffer.alloc(0)) : String(stdout || ''), err: String(stderr || (err && err.message) || '') }))
+    } catch (err) { return resolve({ ok: false, out: '', err: err.message }) }
+    child.stdin.on('error', () => {})
+    child.stdin.end(input)
+  })
+}
+
+/**
+ * The mirror of `repo`, made if it isn't there yet: a bare repository whose `origin` is
+ * `url` (https://<host>/<owner>/<name>.git by default). Resolves { dir, created }.
+ */
+export async function ensureMirror (dataDir, repo, { url = `https://${repo.host}/${repo.owner}/${repo.name}.git` } = {}) {
+  const dir = mirrorDir(dataDir, repo)
+  if (fs.existsSync(path.join(dir, 'HEAD'))) return { dir, created: false }
+  fs.mkdirSync(dir, { recursive: true })
+  const init = await runGit(dir, ['init', '-q', '--bare'])
+  if (!init.ok) throw new Error(`could not make the mirror of ${repo.owner}/${repo.name}: ${init.err.trim()}`)
+  const remote = await runGit(dir, ['remote', 'add', 'origin', url])
+  if (!remote.ok) throw new Error(`could not set the mirror's origin: ${remote.err.trim()}`)
+  return { dir, created: true }
+}
+
+/** A git call that failed, with `kind`: 'auth' (refused sign-in), 'unreachable' (no answer), 'missing' (no such repository) or 'other'. */
+export class GitFailed extends Error {
+  constructor (what, err) {
+    const text = String(err || '').trim()
+    super(`${what}: ${text.split('\n').filter(Boolean).pop() || 'git failed'}`)
+    this.kind = /Authentication failed|returned error: 40[13]\b|could not read Username|Permission denied/i.test(text) ? 'auth'
+      : /Could not resolve host|Connection refused|Connection timed out|unable to access|timed out|Operation timed out|Empty reply/i.test(text) ? 'unreachable'
+        : /returned error: 404|repository .* not found|does not appear to be a git repository/i.test(text) ? 'missing' : 'other'
+    this.stderr = text
+  }
+}
+
+/**
+ * The environment that signs git in to the repository with `token`: GitHub takes an
+ * installation token as HTTP basic auth (x-access-token), given here in a header through
+ * git's environment, so it is never in a URL, on the command line or in the mirror's config.
+ */
+export function authEnv (token) {
+  if (!token) return {}
+  return { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'http.extraHeader', GIT_CONFIG_VALUE_0: `Authorization: Basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}` }
+}
+
+const remoteRef = (branch) => `refs/remotes/origin/${branch}`
+
+/**
+ * Fetches `branch` from origin into refs/remotes/origin/<branch>: { sha }, or { sha: null }
+ * when the remote has no such branch. Throws GitFailed otherwise. `depth` makes it a
+ * shallow fetch (a mirror over its size cap).
+ */
+export async function fetchBranch (dir, branch, { token = null, depth = 0 } = {}) {
+  const args = ['fetch', '-q', ...(depth > 0 ? [`--depth=${depth}`] : []), 'origin', `+refs/heads/${branch}:${remoteRef(branch)}`]
+  const r = await runGit(dir, args, { env: authEnv(token) })
+  if (!r.ok) {
+    if (/couldn't find remote ref/i.test(r.err)) return { sha: null }
+    throw new GitFailed(`fetching ${branch}`, r.err)
+  }
+  const sha = (await runGit(dir, ['rev-parse', '--verify', '-q', remoteRef(branch)])).out.trim()
+  return { sha: sha || null }
+}
+
+/**
+ * Pushes `sha` to origin's `branch`, forward only and never forced: { state: 'accepted', sha };
+ * { state: 'moved', head } when the remote isn't at `expected` any more (nothing is pushed over
+ * it: the caller brings the new head in first); { state: 'refused', why } when `sha` doesn't
+ * descend from `expected` (asked locally, no request made); { state: 'protected', why } when
+ * the remote's rules refuse direct pushes. Throws GitFailed for sign-in or network trouble.
+ */
+export async function pushBranch (dir, { branch, sha, expected = null, token = null }) {
+  if (expected) {
+    const anc = await runGit(dir, ['merge-base', '--is-ancestor', expected, sha])
+    if (!anc.ok) return { state: 'refused', why: 'not a descendant of the branch head' }
+  }
+  const r = await runGit(dir, ['push', '-q', 'origin', `${sha}:refs/heads/${branch}`], { env: authEnv(token) })
+  if (r.ok) return { state: 'accepted', sha }
+  if (/rate limit|too many requests|returned error: 429|secondary rate/i.test(r.err)) return { state: 'slow', why: r.err.trim().split('\n').pop() }
+  if (/protected branch|GH006|pre-receive hook declined|rules? (violation|prevent)/i.test(r.err)) return { state: 'protected', why: r.err.trim().split('\n').filter((l) => /remote:/.test(l)).map((l) => l.replace(/^\s*remote:\s*/, '').trim()).filter(Boolean).join(' ').slice(0, 300) || 'the branch is protected' }
+  if (/\[rejected\]|non-fast-forward|fetch first|stale info/i.test(r.err)) {
+    const { sha: head } = await fetchBranch(dir, branch, { token })
+    return { state: 'moved', head }
+  }
+  throw new GitFailed(`pushing ${branch}`, r.err)
+}
+
+/**
+ * One writer per branch: `queue(repoSlug, branch, fn)` runs `fn` after every operation
+ * queued before it on that branch (outbound commits, inbound bring-ins, clash steps never
+ * interleave), while other branches run alongside. Resolves or rejects with `fn`'s result;
+ * a failure never blocks the next. `queue.pending(repo, branch)` counts what is waiting or running.
+ */
+export function branchQueue () {
+  const tails = new Map() // "<repo>\0<branch>" -> { tail: Promise, n }
+  const queue = (repo, branch, fn) => {
+    const k = `${repo}\0${branch}`
+    const cur = tails.get(k) || { tail: Promise.resolve(), n: 0 }
+    cur.n++
+    const run = cur.tail.then(fn, fn)
+    cur.tail = run.catch(() => {}).then(() => { cur.n--; if (cur.n === 0 && tails.get(k) === cur) tails.delete(k) })
+    tails.set(k, cur)
+    return run
+  }
+  queue.pending = (repo, branch) => (tails.get(`${repo}\0${branch}`) || { n: 0 }).n
+  return queue
+}
+
+const emptyState = () => ({ base: null, pushed: null, pending: {}, held: [], lease: null })
+
+/**
+ * The sync state of session branch `key`, kept in room meta (`meta.sync[key]`): `base`, the
+ * GitHub commit the session's content is measured from; `pushed`, the last commit the relay
+ * pushed; `pending`, the files changed since `base` and not pushed yet (path -> when);
+ * `held`, files in a clash; `lease`, see §8. Made empty on first use; anything that isn't a
+ * record is replaced.
+ */
+export function syncStateOf (room, key) {
+  if (!room.meta.sync || typeof room.meta.sync !== 'object' || Array.isArray(room.meta.sync)) room.meta.sync = {}
+  const s = room.meta.sync[key]
+  if (!s || typeof s !== 'object' || Array.isArray(s) || !s.pending || typeof s.pending !== 'object' || !Array.isArray(s.held)) room.meta.sync[key] = emptyState()
+  return room.meta.sync[key]
+}
+
+/** Pushes to one repository are at least this far apart (addendum 16.11)… */
+export const PUSH_GAP_MS = 10 * 1000
+/** …and at most this many an hour, across all its branches. */
+export const PUSHES_PER_HOUR = 240
+
+/** A mirror unused this long after the last session on its repository ended is removed. */
+export const MIRROR_KEEP_MS = 7 * 24 * 60 * 60 * 1000
+/** Over this size a mirror is fetched shallow. */
+export const MIRROR_CAP_BYTES = 2 * 1024 * 1024 * 1024
+const STAMP = 'quilt-last-used'
+
+/** Records that the mirror was used now (`at`, for tests). */
+export function touchMirror (dir, at = Date.now()) {
+  try { fs.writeFileSync(path.join(dir, STAMP), String(at)) } catch {}
+}
+
+/** When the mirror was last used: its stamp, else when it was made. */
+function lastUsed (dir) {
+  try { const n = Number(fs.readFileSync(path.join(dir, STAMP), 'utf8')); if (Number.isFinite(n)) return n } catch {}
+  try { return fs.statSync(path.join(dir, 'HEAD')).mtimeMs } catch { return Date.now() }
+}
+
+/** Removes every mirror under `dataDir` unused for MIRROR_KEEP_MS (`keepMs`): the repositories removed, as host/owner/name. */
+export function pruneMirrors (dataDir, { now = Date.now(), keepMs = MIRROR_KEEP_MS } = {}) {
+  const removed = []
+  const root = path.join(dataDir, 'git')
+  let hosts = []
+  try { hosts = fs.readdirSync(root) } catch { return removed }
+  for (const host of hosts) {
+    let owners = []
+    try { owners = fs.readdirSync(path.join(root, host)) } catch { continue }
+    for (const owner of owners) {
+      let names = []
+      try { names = fs.readdirSync(path.join(root, host, owner)) } catch { continue }
+      for (const name of names) {
+        if (!name.endsWith('.git')) continue
+        const dir = path.join(root, host, owner, name)
+        if (now - lastUsed(dir) < keepMs) continue
+        try { fs.rmSync(dir, { recursive: true, force: true }); removed.push(`${host}/${owner}/${name.slice(0, -4)}`) } catch {}
+      }
+    }
+  }
+  return removed
+}
+
+/** git's own housekeeping, when git thinks it is due: whether it ran without error. */
+export async function gcMirror (dir) {
+  return (await runGit(dir, ['gc', '--auto', '-q'], { timeout: 10 * 60 * 1000 })).ok
+}
+
+/** How many bytes the mirror takes on disk. */
+export function mirrorBytes (dir) {
+  let total = 0
+  const walk = (d) => {
+    let entries = []
+    try { entries = fs.readdirSync(d, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.isFile()) { try { total += fs.statSync(p).size } catch {} }
+    }
+  }
+  walk(dir)
+  return total
+}
+
+/**
+ * The relay's mirrors as one thing: `ensure(repo, { url })` the mirror of a repository (touched
+ * as used), `queue(repoSlug, branch, fn)` the one writer per branch, `prune()` what the sweep
+ * runs. `dataDir` null (a relay with no data folder) keeps mirrors in a temporary folder.
+ */
+export function mirrorManager ({ dataDir, log = () => {}, capBytes = MIRROR_CAP_BYTES, pushGapMs = PUSH_GAP_MS, pushesPerHour = PUSHES_PER_HOUR, now = () => Date.now() }) {
+  const base = dataDir || fs.mkdtempSync(path.join(os.tmpdir(), 'quilt-mirrors-'))
+  const queue = branchQueue()
+  const budgets = new Map() // repo slug -> { last, hour: [times], until }
+  const budgetOf = (slug) => { if (!budgets.has(slug)) budgets.set(slug, { last: 0, hour: [], until: 0 }); return budgets.get(slug) }
+  return {
+    dataDir: base,
+    queue,
+    /**
+     * Addendum 16.11: every push to a repository, whichever branch and whoever asked (a batch, or a
+     * named commit), shares one budget: at least `pushGapMs` apart, at most `pushesPerHour` an hour,
+     * and nothing while GitHub asked to slow down. How long a push must wait now (0: go).
+     */
+    pushWait (slug) {
+      const b = budgetOf(slug)
+      const t = now()
+      b.hour = b.hour.filter((x) => t - x < 60 * 60 * 1000)
+      const gap = Math.max(0, b.last + pushGapMs - t)
+      const cap = b.hour.length >= pushesPerHour ? b.hour[0] + 60 * 60 * 1000 - t : 0
+      return Math.max(gap, cap, Math.max(0, b.until - t))
+    },
+    /** A push to `slug` is going out now. */
+    spendPush (slug) { const b = budgetOf(slug); b.last = now(); b.hour.push(b.last) },
+    /** GitHub asked this repository's pushes to slow down: none for `ms`. */
+    slowDown (slug, ms) { const b = budgetOf(slug); b.until = Math.max(b.until, now() + ms) },
+    /** fetchBranch, shallow once the mirror is over its size cap. */
+    async fetch (dir, branch, { token = null } = {}) {
+      touchMirror(dir)
+      return fetchBranch(dir, branch, { token, depth: mirrorBytes(dir) > capBytes ? 1 : 0 })
+    },
+    /** pushBranch, then git's housekeeping when due. */
+    async push (dir, opts) {
+      touchMirror(dir)
+      const r = await pushBranch(dir, opts)
+      if (r.state === 'accepted') gcMirror(dir).catch(() => {})
+      return r
+    },
+    async ensure (repo, opts) {
+      const m = await ensureMirror(base, repo, opts)
+      touchMirror(m.dir)
+      if (m.created) log(`mirror: made ${repo.host}/${repo.owner}/${repo.name}`)
+      return m
+    },
+    prune (opts) {
+      const gone = pruneMirrors(base, opts)
+      if (gone.length) log(`mirror: removed ${gone.length} unused for ${MIRROR_KEEP_MS / 86400000} days (${gone.join(', ')})`)
+      return gone
+    }
+  }
+}
+
+/** Deletes origin's `branch` (a live or agent branch after its pull request merged; never history on the branch itself). */
+export async function deleteRemoteBranch (dir, branch, { token = null } = {}) {
+  const r = await runGit(dir, ['push', '-q', 'origin', `:refs/heads/${branch}`], { env: authEnv(token) })
+  if (r.ok || /remote ref does not exist|unable to delete/i.test(r.err)) { await runGit(dir, ['update-ref', '-d', `refs/remotes/origin/${branch}`]); return true }
+  throw new GitFailed(`deleting ${branch}`, r.err)
+}

package/src/relay-githttp.js

@@ -0,0 +1,137 @@
+// Agents' folders use git through the relay (plan §9): the relay serves git's smart HTTP protocol at
+// /git/<room>.git. Each session has a bare "view" repository of its own whose objects come from the
+// relay's mirror of the GitHub repository (objects/info/alternates) and whose branches are only the
+// session's synced branches, at the GitHub commit the session is measured from. So a folder clones
+// and fetches what the session follows and nothing another session keeps in the shared mirror. A push
+// is checked by a pre-receive hook that asks the relay (relay-outbound.js receiveAgentPush): the owner's
+// policy, the workspace's access mode, no force-push, no ignored files; the relay then puts the commits
+// on GitHub (replayed onto its head when it moved) before the push is accepted. No GitHub token ever
+// reaches the agent's machine: git signs in to the relay with the agent's Quilt pass.
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { runGit, syncStateOf } from './relay-git.js'
+import { upstreamsOf } from './relay-upstream.js'
+
+const HOOK = path.join(path.dirname(fileURLToPath(import.meta.url)), 'git-hook.js')
+const ZERO = /^0{40}$/
+
+/** Where room `room`'s view repository lives. */
+export const viewDir = (dataDir, room) => path.join(dataDir, 'git-rooms', `${room}.git`)
+
+/** The GitHub repository a room's git view serves (its default branch's), as { rec, repo slug }, or null. */
+export function viewRepoOf (room) {
+  const recs = upstreamsOf(room)
+  const def = recs[room.defaultKey] || Object.values(recs).find((r) => r && r.repo)
+  return def && def.repo && /^github\.com\//.test(def.repo) ? def : null
+}
+
+/**
+ * Makes (or keeps) room `room`'s view repository over the mirror at `mirror`: bare, objects borrowed
+ * from the mirror, pushes refused when they would rewrite or delete a branch, and Quilt's hooks in place.
+ */
+export async function ensureView (dataDir, room, mirror) {
+  const dir = viewDir(dataDir, room)
+  if (!fs.existsSync(path.join(dir, 'HEAD'))) {
+    fs.mkdirSync(dir, { recursive: true })
+    const r = await runGit(dir, ['init', '-q', '--bare'])
+    if (!r.ok) throw new Error(`could not make the git view: ${r.err.trim()}`)
+  }
+  fs.mkdirSync(path.join(dir, 'objects', 'info'), { recursive: true })
+  fs.writeFileSync(path.join(dir, 'objects', 'info', 'alternates'), `${path.join(mirror, 'objects')}\n`)
+  for (const [k, v] of [['http.receivepack', 'true'], ['http.uploadpack', 'true'], ['receive.denyNonFastForwards', 'true'], ['receive.denyDeletes', 'true'], ['uploadpack.allowFilter', 'true'], ['gc.auto', '0']]) {
+    await runGit(dir, ['config', k, v])
+  }
+  const hooks = path.join(dir, 'hooks')
+  fs.mkdirSync(hooks, { recursive: true })
+  for (const phase of ['pre-receive', 'post-receive']) {
+    const file = path.join(hooks, phase)
+    const body = `#!/bin/sh\n# Quilt: pushes from agents' folders are checked and published by the relay.\nexec ${JSON.stringify(process.execPath)} ${JSON.stringify(HOOK)} ${phase}\n`
+    if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== body) fs.writeFileSync(file, body, { mode: 0o755 })
+  }
+  return dir
+}
+
+/**
+ * The view's branches are the session's synced branches on this repository, each at the commit the
+ * session is measured from (its sync base, else the branch record's); HEAD is the default branch.
+ * Branches the session no longer has go. A commit the mirror doesn't have yet is left out.
+ */
+export async function syncViewRefs (room, dir, repo) {
+  const recs = upstreamsOf(room)
+  const want = new Map()
+  for (const [key, rec] of Object.entries(recs)) {
+    if (!rec || rec.repo !== repo || !rec.ref || rec.gone) continue
+    const st = room.meta.sync && room.meta.sync[key] ? syncStateOf(room, key) : null
+    const sha = (st && st.base) || rec.sha
+    if (!/^[0-9a-f]{40}$/.test(sha || '')) continue
+    if (!(await runGit(dir, ['cat-file', '-e', `${sha}^{commit}`])).ok) continue
+    want.set(rec.ref, sha)
+  }
+  // Branches pushed through the view that the session doesn't follow (an agent's own): where GitHub took them.
+  for (const [ref, sha] of Object.entries(room.meta.viewBranches || {})) {
+    if (want.has(ref) || !/^[0-9a-f]{40}$/.test(sha || '')) continue
+    if ((await runGit(dir, ['cat-file', '-e', `${sha}^{commit}`])).ok) want.set(ref, sha)
+  }
+  const have = new Map((await runGit(dir, ['for-each-ref', '--format=%(refname:strip=2) %(objectname)', 'refs/heads/'])).out.split('\n').filter(Boolean).map((l) => l.split(' ')))
+  for (const [ref, sha] of want) if (have.get(ref) !== sha) await runGit(dir, ['update-ref', `refs/heads/${ref}`, sha])
+  for (const ref of have.keys()) if (!want.has(ref)) await runGit(dir, ['update-ref', '-d', `refs/heads/${ref}`])
+  const def = recs[room.defaultKey]
+  if (def && want.has(def.ref)) await runGit(dir, ['symbolic-ref', 'HEAD', `refs/heads/${def.ref}`])
+  return want
+}
+
+/**
+ * Serves one smart-HTTP request (`pathInfo`: /<room>.git/info/refs, …/git-upload-pack, …/git-receive-pack)
+ * with git's own CGI, `git http-backend`, over `root` (the folder of view repositories). `env` reaches
+ * the hooks of a push (who pushes, and how to ask the relay). Never throws; answers 500 when git fails.
+ */
+export function serveGit (req, res, { root, pathInfo, query = '', env = {} }) {
+  const cgi = spawn('git', ['http-backend'], {
+    env: {
+      ...process.env,
+      ...env,
+      GIT_PROJECT_ROOT: root,
+      GIT_HTTP_EXPORT_ALL: '1',
+      PATH_INFO: pathInfo,
+      REQUEST_METHOD: req.method,
+      QUERY_STRING: query,
+      CONTENT_TYPE: req.headers['content-type'] || '',
+      CONTENT_LENGTH: req.headers['content-length'] || '',
+      HTTP_CONTENT_ENCODING: req.headers['content-encoding'] || '',
+      GIT_PROTOCOL: req.headers['git-protocol'] || '',
+      REMOTE_ADDR: '127.0.0.1'
+    }
+  })
+  let head = Buffer.alloc(0)
+  let headed = false
+  cgi.stdout.on('data', (chunk) => {
+    if (headed) return res.write(chunk)
+    head = Buffer.concat([head, chunk])
+    const at = head.indexOf('\r\n\r\n')
+    if (at < 0) return
+    headed = true
+    const headers = {}
+    let status = 200
+    for (const line of head.subarray(0, at).toString().split('\r\n')) {
+      const i = line.indexOf(':')
+      if (i < 0) continue
+      const k = line.slice(0, i).trim().toLowerCase()
+      const v = line.slice(i + 1).trim()
+      if (k === 'status') status = parseInt(v, 10) || 200; else headers[k] = v
+    }
+    res.writeHead(status, headers)
+    res.write(head.subarray(at + 4))
+  })
+  cgi.stdout.on('end', () => { if (!headed) { res.writeHead(500); } res.end() })
+  cgi.stderr.on('data', () => {})
+  cgi.on('error', () => { if (!res.headersSent) res.writeHead(500); res.end() })
+  req.pipe(cgi.stdin)
+  cgi.stdin.on('error', () => {})
+}
+
+/** A ref update a push asks for: { old, new, ref }, from the hook's stdin lines. */
+export function parseUpdates (text) {
+  return String(text || '').split('\n').map((l) => l.trim().split(/\s+/)).filter((p) => p.length === 3 && /^[0-9a-f]{40}$/.test(p[0]) && /^[0-9a-f]{40}$/.test(p[1])).map(([o, n, ref]) => ({ old: ZERO.test(o) ? null : o, new: ZERO.test(n) ? null : n, ref }))
+}

package/src/relay-github.js

@@ -0,0 +1,109 @@
+// The relay's GitHub credentials for a session, from its members' GitHub connections: the API
+// mints them with Quilt's GitHub App for one repository at a time, for the first member of the
+// session whose linked GitHub account may do what is asked (write, to commit and merge; read, to
+// fetch or clone), whether or not that member is online (src/api/routes/github.js). One person
+// connecting covers everyone in the session, agents included, so nobody else makes or pastes a
+// token. Kept until a few minutes before they run out.
+
+/** The accounts of the session's people, the owner first: whose connections may cover a repository. */
+export function memberAccounts (room) {
+  const out = []
+  const owner = room.meta && room.meta.ownerSub
+  if (/^person:/.test(owner || '')) out.push(owner)
+  for (const id of Object.keys((room.meta && room.meta.members) || {})) if (/^person:/.test(id) && !out.includes(id)) out.push(id)
+  return out
+}
+
+/**
+ * { token, expiresAt, login } for owner/name (`full`) with `access` ('write' or 'read'), or { state }
+ * saying why not: 'not-connected' (nobody in the session has connected GitHub), 'not-installed'
+ * (Quilt's app isn't on that repository), 'no-access' (with `login`: no connected member's GitHub
+ * account may do that there), 'off' (this relay has no API, or the session has no people) or
+ * 'error'. Never throws. A "no" is remembered a minute (`fresh`) or ten (the relay's own looks).
+ */
+export async function appCredentials (room, full, { access = 'write', fresh = true, share = true, actingFor = '' } = {}) {
+  const cfg = room.cfg || {}
+  const accounts = memberAccounts(room)
+  if (!cfg.apiUrl || !cfg.relayApiSecret || !accounts.length) return { state: 'off' }
+  // `actingFor` (person:<id> or agent:<id>): who the token is for; with the org's Require GitHub, only the person that account works for counts (plan §2).
+  const key = `${access}\0${full}\0${actingFor}`.toLowerCase()
+  if (!room.appTokens) room.appTokens = new Map()
+  const hit = room.appTokens.get(key)
+  // `share`: the relay's own token for this repository, kept and reused. Without it, a token of its
+  // own for whoever asked (an agent's folder): minted anew, never the kept one, and not kept here.
+  if (share && hit && hit.token && hit.expiresAt - Date.now() > 5 * 60 * 1000) return { token: hit.token, expiresAt: hit.expiresAt, login: hit.login }
+  if (hit && !hit.token && Date.now() - hit.at < (fresh ? 60 * 1000 : 10 * 60 * 1000)) return hit.no
+  try {
+    const res = await (room.apiFetch || globalThis.fetch)(`${String(cfg.apiUrl).replace(/\/+$/, '')}/v1/relay/github-token`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${cfg.relayApiSecret}` },
+      body: JSON.stringify({ accounts, repo: full, access, room: room.name, ...(actingFor ? { actingFor } : {}), ...(share ? {} : { fresh: true }) })
+    })
+    const r = res.ok ? await res.json() : { state: 'error' }
+    if (r.state === 'ok' && r.token) {
+      const out = { token: r.token, expiresAt: Number(r.expiresAt) || Date.now() + 30 * 60 * 1000, login: r.login || '' }
+      if (share) room.appTokens.set(key, out)
+      return out
+    }
+    const no = { state: r.state || 'error', ...(r.login ? { login: r.login } : {}), ...(r.why ? { why: r.why } : {}), ...(r.require ? { require: true } : {}) }
+    room.appTokens.set(key, { no, at: Date.now() })
+    return no
+  } catch { return { state: 'error' } }
+}
+
+/** Revokes an installation token at GitHub (an agent's, when it leaves or may no longer push). Never throws. */
+export async function revokeGitHubToken (token, { fetch = globalThis.fetch } = {}) {
+  if (!token) return false
+  try {
+    const res = await fetch('https://api.github.com/installation/token', { method: 'DELETE', headers: { 'user-agent': 'quilt-relay', 'x-github-api-version': '2022-11-28', accept: 'application/vnd.github+json', authorization: `Bearer ${token}` } })
+    return res.status === 204
+  } catch { return false }
+}
+
+/** Why the relay can't act on `full` for this session, in words for whoever asked, with what to do. */
+export function noCredentialsText (r, full, { verb = 'commit to' } = {}) {
+  const connect = 'Connect GitHub in the app\'s commit panel (one click, by any member whose GitHub account can write to the repository: it then covers everyone here, agents included)'
+  if (r.state === 'not-allowed') return `Not committed: ${r.why || `this session's workspace doesn't allow ${full}`}. Its admins list the repositories it may use (workspace settings, GitHub).`
+  if (r.state === 'not-connected' && r.require) return `This org requires GitHub: the person ${verb === 'commit to' ? 'the commit is for' : 'asking'} must connect a GitHub account that may write to ${full} (Connect GitHub in the app). Until then ask a person for the commit (quilt_request_commit).`
+  if (r.state === 'not-installed') return `Quilt's GitHub app isn't installed on ${full}: ${connect}, and pick that repository. Until then ask a person for the commit (quilt_request_commit).`
+  if (r.state === 'no-access') return `No connected member's GitHub account (${r.login ? `@${r.login}` : 'the ones connected'}) may ${verb} ${full}, so Quilt won't for this session. Ask a person for the commit (quilt_request_commit).`
+  if (r.state === 'not-connected') return `Nobody in this session has connected GitHub yet: ${connect}. Until then ask a person for the commit (quilt_request_commit).`
+  return `Quilt can't ${verb} ${full} right now${r.state === 'error' ? ' (GitHub or the accounts API did not answer)' : ''}: ${connect}. Until then ask a person for the commit (quilt_request_commit).`
+}
+
+/**
+ * Notes on the room's member records which GitHub account each person linked ({ login, id }, from
+ * the API), so their commits carry their GitHub noreply address (relay-outbound.js authorOf).
+ * Asked at most once an hour per room unless `force`. Resolves whether anything changed. Never throws.
+ */
+export async function noteMemberLogins (room, { force = false, fetch = room.apiFetch || globalThis.fetch } = {}) {
+  const cfg = room.cfg || {}
+  const accounts = memberAccounts(room)
+  if (!cfg.apiUrl || !cfg.relayApiSecret || !accounts.length) return false
+  if (!force && room.loginsAt && Date.now() - room.loginsAt < 60 * 60 * 1000) return false
+  room.loginsAt = Date.now()
+  try {
+    const res = await fetch(`${String(cfg.apiUrl).replace(/\/+$/, '')}/v1/relay/github-logins`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${cfg.relayApiSecret}` },
+      body: JSON.stringify({ accounts })
+    })
+    if (!res.ok) return false
+    const { logins = {} } = await res.json()
+    let changed = false
+    for (const id of accounts) {
+      if (id === room.meta.ownerSub) {
+        const l = logins[id]
+        const next = l && l.login ? { login: String(l.login), id: Number(l.id) || null } : null
+        if (JSON.stringify(room.meta.ownerGithub || null) !== JSON.stringify(next)) { if (next) room.meta.ownerGithub = next; else delete room.meta.ownerGithub; changed = true }
+      }
+      const m = room.meta.members && room.meta.members[id]
+      if (!m) continue
+      const l = logins[id]
+      const next = l && l.login ? { login: String(l.login), id: Number(l.id) || null } : null
+      if (JSON.stringify(m.github || null) !== JSON.stringify(next)) { if (next) m.github = next; else delete m.github; changed = true }
+    }
+    if (changed) room.saveMeta()
+    return changed
+  } catch { return false }
+}