heyquilt 0.0.1 → 0.3.90

package/src/api/routes/workspace-agents.js

@@ -0,0 +1,332 @@
+// Agents in workspaces: where an agent works (its placement, set by its owner), a
+// workspace's say over an agent placed there (its override), workspace agent invites,
+// a session owner keeping an agent out of one session, and an agent's own webhook for
+// workspace events. Behind the QUILT_WORKSPACES flag: off, every route answers 404.
+import { HttpError, needId } from '../http.js'
+import { newToken, hashToken } from '../tokens.js'
+import { orgAccess } from '../org-access.js'
+import { cleanAccess, stillInOrg } from '../workspace-access.js'
+import { workspaceReach } from '../workspace-reach.js'
+import { cleanPlacement, placementIn, agentsJoiningSession, sessionAgents, sameOwnerAgent, SESSIONS } from '../agent-placement.js'
+import { AGENT_INVITE_TTL_MS, inviteStatus } from './agent-invites.js'
+import crypto from 'node:crypto'
+import { parseWebhookUrl, newSecret, publicWebhookHost, deliverWebhook, MIN_SECRET, MAX_SECRET } from '../../webhooks.js'
+import { parseInvite, buildInvite } from '../../ui/invite.js'
+import { isHostedRelay, HOSTED_RELAY } from '../../settings.js'
+
+const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+export const AGENT_WEBHOOK_EVENTS = ['session.started']
+/** Why someone else's agent in a workspace is never invited to every session there. */
+export const FOREIGN_JOINS = 'Only its owner can have an agent invited to every session.'
+
+/** A placement as the routes answer it; an agent with none is 'manual' (it works only where it is added). */
+export function placementView (agentId, p) {
+  if (!p) return { agentId, reach: 'manual', workspaceIds: [], sessions: 'invited', access: 'edit', scopes: [], updatedAt: null }
+  return { agentId, reach: p.reach, workspaceIds: [...(p.workspaceIds || [])], sessions: p.sessions, access: p.access, scopes: [...(p.scopes || [])], updatedAt: p.updatedAt ?? null }
+}
+
+/** A member agent's `sessions`: 'all' or 'invited', and only for an agent. Undefined keeps what the member has. */
+export function cleanMemberSessions (value, kind) {
+  if (value === undefined) return undefined
+  if (kind !== 'agent') throw new HttpError(400, 'Only an agent joins sessions by itself.')
+  if (!SESSIONS.includes(value)) throw new HttpError(400, 'Sessions is all or invited.')
+  return value
+}
+
+/**
+ * The agents in `ws` for its page: member agents (via 'member', managed by the workspace),
+ * then agents of the workspace's owner placed there (via 'placed' or 'global', managed by
+ * the owner or the org), with the workspace's override applied. Agents the workspace kept
+ * out are listed (excluded: true) only for an admin, so they can be let back in. `foreign`
+ * marks someone else's agent added here: it joins only when invited, whatever its row says.
+ */
+export async function workspaceAgents (store, ws, { admin = false } = {}) {
+  const out = []
+  const seen = new Set()
+  for (const m of await store.listWorkspaceMembers(ws.id)) {
+    if (!m.account.startsWith('agent:')) continue
+    const agentId = m.account.slice(6)
+    const agent = await store.agentById(agentId)
+    if (!agent || agent.revokedAt || !(await stillInOrg(store, ws, m.account, null))) continue
+    seen.add(agentId)
+    const foreign = !(await sameOwnerAgent(store, ws, agentId))
+    out.push({ account: m.account, agentId, name: agent.name, provider: agent.provider, via: 'member', access: m.access, sessions: foreign ? 'invited' : (m.sessions || 'invited'), managedBy: 'workspace', excluded: false, foreign })
+  }
+  const own = ws.orgId ? await store.listOrgAgents(ws.orgId) : ws.ownerUserId ? await store.listPersonalAgents(ws.ownerUserId) : []
+  const placed = []
+  for (const agent of own) {
+    if (seen.has(agent.id)) continue
+    const p = await placementIn(store, ws, agent.id)
+    if (!p) continue
+    const override = await store.workspaceAgentOverride(ws.id, agent.id)
+    const excluded = !!override?.excluded
+    if (excluded && !admin) continue
+    placed.push({ account: `agent:${agent.id}`, agentId: agent.id, name: agent.name, provider: agent.provider, via: p.reach === 'all' ? 'global' : 'placed', access: p.access, sessions: override?.sessions ?? p.sessions, managedBy: ws.orgId ? 'org' : 'owner', excluded, foreign: false })
+  }
+  placed.sort((a, b) => a.name.localeCompare(b.name))
+  return [...out, ...placed]
+}
+
+/** Every workspace an agent can find by its placement: its owner's personal ones, or its org's. */
+export async function placementCandidates (store, agent) {
+  if (!agent) return []
+  if (agent.orgId) return store.listWorkspacesOfOrg(agent.orgId)
+  return agent.ownerUserId ? store.listWorkspacesOwnedBy(agent.ownerUserId) : []
+}
+
+/** A relay address as join links carry it (ws:// or wss://, no trailing slash). */
+const relayForm = (url) => String(url || '').replace(/\/+$/, '').replace(/^http(s?):\/\//, 'ws$1://')
+
+export function workspaceAgentRoutes (ctx) {
+  const { store, person, now, apiUrl, limitSend, limitAnnounce = () => {}, log = () => {}, workspaces = false } = ctx
+  // The session-started hand-off: how webhooks are sent (tests record them), how host names
+  // resolve, and whether a receiver on this computer is allowed (tests only).
+  const { relayUrl = HOSTED_RELAY, webhookFetch = globalThis.fetch, webhookLookup, allowLocalWebhooks = false, trackDelivery = (p) => p } = ctx
+  const ownRelay = relayForm(relayUrl)
+  const { caller, reach } = workspaceReach(ctx)
+  const gated = (fn) => (...args) => {
+    if (!workspaces) throw new HttpError(404, 'not found')
+    return fn(...args)
+  }
+
+  /** A placement body, checked, with every listed workspace one of `owns` (the owner's own). */
+  async function placementFrom (body, owns) {
+    const p = cleanPlacement(body)
+    for (const id of p.workspaceIds) {
+      const ws = await store.workspaceById(id)
+      if (!ws || !owns(ws)) throw new HttpError(400, 'An agent can only be placed in its owner\'s own workspaces.')
+    }
+    return p
+  }
+
+  async function myAgent (req, id) {
+    const u = await person(req)
+    const agent = await store.agentById(needId(id, 'agent'))
+    // Someone else's agent, an org's, or a revoked one: the same answer as a missing one.
+    if (!agent || agent.ownerUserId !== u.userId || agent.revokedAt) throw new HttpError(404, 'no such agent')
+    return { u, agent }
+  }
+
+  async function orgFor (req, slug) {
+    const u = await person(req)
+    return { u, ...(await orgAccess(store, u.userId, slug)) }
+  }
+
+  async function orgAgent (a, id) {
+    const agent = await store.agentById(needId(id, 'agent'))
+    if (!agent || agent.orgId !== a.org.id || agent.revokedAt) throw new HttpError(404, 'no such agent')
+    return agent
+  }
+
+  /** The room's session when the caller owns it (as the relay reports it). */
+  async function ownRoom (req, room) {
+    const me = await caller(req)
+    if (!ROOM.test(room)) throw new HttpError(404, 'no such session')
+    const session = await store.sessionByRoom(room)
+    if (!session) throw new HttpError(404, 'no such session')
+    if (!session.ownerAccount || session.ownerAccount !== me.account) throw new HttpError(403, 'Only the session owner can do that.')
+    return { me, session }
+  }
+
+  /** The room's session when the caller owns it, and the agent to keep out. */
+  async function ownSession (req, room, agentId) {
+    const { me, session } = await ownRoom(req, room)
+    const agent = await store.agentById(needId(agentId, 'agent'))
+    if (!agent) throw new HttpError(404, 'no such agent')
+    return { me, session, agent }
+  }
+
+  async function meAsAgent (req) {
+    const me = await caller(req)
+    if (!me.account.startsWith('agent:')) throw new HttpError(403, 'Only an agent has a webhook here.')
+    return me.agent || await store.agentById(me.account.slice(6))
+  }
+
+  /**
+   * Sends one agent its session.started event, after checking its webhook still points at the
+   * public internet as it resolves now (the URL was only checked as written when it was set).
+   * Never throws: a skipped or failed send is logged, without the link.
+   */
+  async function sendSessionStarted (agentId, hook, payload) {
+    try {
+      let url
+      try { url = parseWebhookUrl(hook.url, { allowLocal: allowLocalWebhooks }) } catch (e) {
+        log(`session.started to agent ${agentId} skipped: ${hook.url}: ${e.message}`)
+        return
+      }
+      if (!allowLocalWebhooks) {
+        const host = await publicWebhookHost(url, webhookLookup ? { lookup: webhookLookup } : {})
+        if (!host.ok) { log(`session.started to agent ${agentId} skipped: ${host.reason}`); return }
+      }
+      await deliverWebhook({ url, secret: hook.secret }, payload, { fetch: webhookFetch, now, log })
+    } catch (err) {
+      log(`session.started to agent ${agentId} failed: ${err?.message || err}`)
+    }
+  }
+
+  const routes = [
+    ['GET', /^\/v1\/me\/agents\/([^/]+)\/placement$/, async (req, body, [id]) => {
+      const { agent } = await myAgent(req, id)
+      return { placement: placementView(agent.id, await store.agentPlacement(agent.id)) }
+    }],
+
+    ['PUT', /^\/v1\/me\/agents\/([^/]+)\/placement$/, async (req, body, [id]) => {
+      const { u, agent } = await myAgent(req, id)
+      // A personal agent's workspaces are its owner's personal ones, never an org's.
+      const p = await placementFrom(body, (ws) => !ws.orgId && ws.ownerUserId === u.userId)
+      return { placement: placementView(agent.id, await store.putAgentPlacement({ agentId: agent.id, ...p, updatedBy: `person:${u.userId}` })) }
+    }],
+
+    ['GET', /^\/v1\/orgs\/([^/]+)\/agents$/, async (req, body, [slug]) => {
+      const a = await orgFor(req, slug)
+      a.need('agents', 'r')
+      const agents = await store.listOrgAgents(a.org.id)
+      const placements = new Map((await store.listAgentPlacements(agents.map((x) => x.id))).map((p) => [p.agentId, p]))
+      return { agents: agents.map((x) => ({ id: x.id, name: x.name, provider: x.provider, type: x.type, hosted: !x.publicKey, placement: placementView(x.id, placements.get(x.id)) })) }
+    }],
+
+    ['PUT', /^\/v1\/orgs\/([^/]+)\/agents\/([^/]+)\/placement$/, async (req, body, [slug, id]) => {
+      const a = await orgFor(req, slug)
+      a.need('agents', 'u')
+      // Placing an agent puts it in the org's workspaces, so it takes Workspaces: Update too.
+      a.need('workspaces', 'u')
+      const agent = await orgAgent(a, id)
+      const p = await placementFrom(body, (ws) => ws.orgId === a.org.id)
+      return { placement: placementView(agent.id, await store.putAgentPlacement({ agentId: agent.id, ...p, updatedBy: `person:${a.u.userId}` })) }
+    }],
+
+    // Only for an agent the workspace's owner placed there: an agent added by hand is
+    // managed through its member row instead.
+    ['PUT', /^\/v1\/workspaces\/([^/]+)\/agents\/([^/]+)$/, async (req, body, [id, agentId]) => {
+      const r = await reach(req, id)
+      r.needAdmin()
+      if (!(await placementIn(store, r.ws, agentId))) throw new HttpError(404, 'that agent is not placed in this workspace')
+      const b = body && typeof body === 'object' ? body : {}
+      if (b.sessions !== undefined && b.sessions !== null && !SESSIONS.includes(b.sessions)) throw new HttpError(400, 'Sessions is all, invited or null.')
+      if (b.excluded !== undefined && typeof b.excluded !== 'boolean') throw new HttpError(400, 'excluded is true or false.')
+      const old = await store.workspaceAgentOverride(r.ws.id, agentId)
+      const override = await store.putWorkspaceAgentOverride({
+        workspaceId: r.ws.id,
+        agentId,
+        sessions: b.sessions !== undefined ? b.sessions : (old?.sessions ?? null),
+        excluded: b.excluded !== undefined ? b.excluded : !!old?.excluded
+      })
+      return { override }
+    }],
+
+    ['DELETE', /^\/v1\/workspaces\/([^/]+)\/agents\/([^/]+)$/, async (req, body, [id, agentId]) => {
+      const r = await reach(req, id)
+      r.needAdmin()
+      await store.deleteWorkspaceAgentOverride(r.ws.id, needId(agentId, 'agent'))
+      return { ok: true }
+    }],
+
+    // A one-time link (good for an hour) for a new agent of the workspace's owner, which
+    // joins as a member of this workspace. An org's needs Agents: Create too.
+    ['POST', /^\/v1\/workspaces\/([^/]+)\/agent-invites$/, async (req, body, [id]) => {
+      const r = await reach(req, id)
+      r.needAdmin()
+      if (!r.me.userId) throw new HttpError(403, 'agents do not invite agents')
+      const workspaceAccess = cleanAccess(body.access ?? 'edit')
+      const workspaceSessions = body.sessions ?? 'invited'
+      if (!SESSIONS.includes(workspaceSessions)) throw new HttpError(400, 'Sessions is all or invited.')
+      let home
+      if (r.ws.orgId) {
+        const a = await orgAccess(store, r.me.userId, (await store.orgById(r.ws.orgId)).slug)
+        a.need('agents', 'c')
+        home = { orgId: a.org.id }
+      } else home = { ownerUserId: r.ws.ownerUserId }
+      limitSend(r.me.userId)
+      const token = newToken('qj_')
+      const invite = await store.createAgentInvite({ tokenHash: hashToken(token), createdBy: r.me.userId, expiresAt: now() + AGENT_INVITE_TTL_MS, ...home, workspaceId: r.ws.id, workspaceAccess, workspaceSessions })
+      return {
+        invite: { id: invite.id, kind: invite.orgId ? 'org' : 'personal', status: inviteStatus(invite, now()), workspaceId: invite.workspaceId, workspaceAccess: invite.workspaceAccess, workspaceSessions: invite.workspaceSessions, createdAt: invite.createdAt, expiresAt: invite.expiresAt },
+        link: `${apiUrl}/v1/join/${token}`
+      }
+    }],
+
+    // The session's agents for its People: the ones its workspace invites (and why), and the
+    // ones its owner keeps out (Don't invite), so the owner can change either.
+    ['GET', /^\/v1\/sessions\/([^/]+)\/agents$/, async (req, body, [room]) => {
+      await ownRoom(req, room)
+      return { agents: await sessionAgents(store, room) }
+    }],
+
+    // The agents its owner keeps out of this session, so the app can offer to let them back in.
+    ['GET', /^\/v1\/sessions\/([^/]+)\/agents\/excluded$/, async (req, body, [room]) => {
+      await ownRoom(req, room)
+      const agents = []
+      for (const e of await store.listSessionAgentExclusions(room)) agents.push({ agentId: e.agentId, name: (await store.agentById(e.agentId))?.name || '' })
+      return { agents }
+    }],
+
+    ['PUT', /^\/v1\/sessions\/([^/]+)\/agents\/([^/]+)\/exclude$/, async (req, body, [room, agentId]) => {
+      const { me, agent } = await ownSession(req, room, agentId)
+      await store.addSessionAgentExclusion({ room, agentId: agent.id, excludedBy: me.account })
+      return { ok: true }
+    }],
+
+    ['DELETE', /^\/v1\/sessions\/([^/]+)\/agents\/([^/]+)\/exclude$/, async (req, body, [room, agentId]) => {
+      const { agent } = await ownSession(req, room, agentId)
+      await store.removeSessionAgentExclusion(room, agent.id)
+      return { ok: true }
+    }],
+
+    // The session's owner, as soon as it has started a session in this workspace, hands over
+    // its join link; every agent that joins the session by itself and has a webhook is sent it
+    // at once. The link is used for these sends and never kept. 409 until the relay has said
+    // who owns the session (the app tries again shortly).
+    ['POST', /^\/v1\/workspaces\/([^/]+)\/sessions\/([^/]+)\/started$/, async (req, body, [id, room]) => {
+      const r = await reach(req, id)
+      if (!ROOM.test(room)) throw new HttpError(404, 'that session is not in this workspace')
+      const session = await store.sessionByRoom(room)
+      if (!session || session.workspaceId !== r.ws.id) throw new HttpError(404, 'that session is not in this workspace')
+      if (session.workspaceLinkedBy !== r.me.account) throw new HttpError(403, 'Only the session owner can do that.')
+      if (!session.ownerAccount) throw new HttpError(409, 'Quilt has not heard who owns this session yet; try again in a moment.')
+      if (session.ownerAccount !== r.me.account) throw new HttpError(403, 'Only the session owner can do that.')
+      let invite
+      try { invite = parseInvite(String(body.link || ''), { allowRelay: (s) => isHostedRelay(s) || relayForm(s) === ownRelay }) } catch { throw new HttpError(400, 'link must be this session\'s Quilt invite link') }
+      if (invite.room !== room || !invite.secret) throw new HttpError(400, 'link must be this session\'s Quilt invite link')
+      // `agents` (optional): only these of the agents it invites, e.g. one invited again.
+      const only = body.agents === undefined ? null : body.agents
+      if (only !== null && (!Array.isArray(only) || only.length > 100 || only.some((x) => typeof x !== 'string'))) throw new HttpError(400, 'agents must be a list of agent ids.')
+      limitAnnounce(room)
+      // Sent as Quilt writes it, whatever surrounded it in the request.
+      const link = buildInvite({ server: invite.relay || HOSTED_RELAY, room, secret: invite.secret }, isHostedRelay)
+      const by = r.me.userId ? ((await store.profile(r.me.userId))?.name || '') : (r.me.agent?.name || '')
+      const notified = []
+      const withoutWebhook = []
+      // An agent that started the session is in it already: it isn't sent its own link.
+      const starter = session.ownerAccount.startsWith('agent:') ? session.ownerAccount.slice(6) : null
+      for (const { agentId, via } of await agentsJoiningSession(store, room)) {
+        if (agentId === starter || (only && !only.includes(agentId))) continue
+        const hook = await store.agentWebhook(agentId)
+        if (!hook) { withoutWebhook.push(agentId); continue }
+        notified.push(agentId)
+        const payload = { event: 'session.started', id: crypto.randomUUID(), ts: now(), workspace: { id: r.ws.id, name: r.ws.name }, room, session: room, name: session.name || '', link, by, via }
+        trackDelivery(sendSessionStarted(agentId, hook, payload))
+      }
+      return { notified, withoutWebhook }
+    }],
+
+    // The agent's own webhook for workspace events. The secret signs deliveries: the agent's
+    // own (so one webhook, set from a session's relay, signs the same everywhere), or a new one
+    // on every PUT without, answered once.
+    ['PUT', /^\/v1\/agents\/me\/webhook$/, async (req, body) => {
+      const agent = await meAsAgent(req)
+      let url
+      try { url = parseWebhookUrl(body.url, { allowLocal: allowLocalWebhooks }) } catch (e) { throw new HttpError(400, e.message) }
+      const given = body.secret == null ? '' : String(body.secret)
+      if (given && (given.length < MIN_SECRET || given.length > MAX_SECRET)) throw new HttpError(400, `secret must be ${MIN_SECRET} to ${MAX_SECRET} characters (or leave it out and Quilt makes one).`)
+      const hook = await store.putAgentWebhook({ agentId: agent.id, url, secret: given || newSecret() })
+      return { url: hook.url, secret: hook.secret, events: [...AGENT_WEBHOOK_EVENTS] }
+    }],
+
+    ['DELETE', /^\/v1\/agents\/me\/webhook$/, async (req) => {
+      const agent = await meAsAgent(req)
+      await store.deleteAgentWebhook(agent.id)
+      return { ok: true }
+    }]
+  ]
+  return routes.map(([method, pattern, fn, ...options]) => [method, pattern, gated(fn), ...options])
+}

package/src/api/routes/workspace-files.js

@@ -0,0 +1,277 @@
+// A workspace's file library: the index in Postgres, the bytes behind signed links.
+// Behind the QUILT_WORKSPACES flag like the other workspace routes: off, each answers 404.
+import { HttpError, needId } from '../http.js'
+import { workspaceReach, canSeeFiles } from '../workspace-reach.js'
+import { cleanFilePath, parentOf, nameOf, mimeOf } from '../file-paths.js'
+import { LINK_MS } from '../file-store.js'
+
+const MAX_NOTE = 300
+const UNCONFIRMED_MS = 60 * 60 * 1000
+export const DELETED_KEEP_MS = 30 * 24 * 60 * 60 * 1000
+const KEEP_VERSIONS = 10
+
+export const fileView = (f) => ({ id: f.id, path: f.path, name: nameOf(f.path), folder: parentOf(f.path), kind: f.kind, size: f.size, mime: f.mime, sha256: f.sha256, version: f.version, note: f.note, uploadedBy: f.uploadedBy, uploadedAt: f.uploadedAt, confirmedAt: f.confirmedAt })
+const MIME = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i
+const LOOPBACK = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i
+
+/** The version people get of a file: its current one once that has landed; while a new
+ * version is still uploading, the newest earlier one (the row's own facts belong to the
+ * pending upload). Null for a file whose first upload hasn't landed. */
+async function servedVersion (store, f) {
+  if (f.kind !== 'file' || f.confirmedAt) return null
+  return (await store.listWorkspaceFileVersions(f.id))[0] || null
+}
+
+/** A row as people see it, or null while a new file's first upload hasn't landed. */
+export async function viewOf (store, f) {
+  if (f.kind === 'folder' || f.confirmedAt) return fileView(f)
+  const v = await servedVersion(store, f)
+  if (!v) return null
+  return { ...fileView(f), version: v.version, size: v.size, sha256: v.sha256, note: v.note, uploadedBy: v.uploadedBy, uploadedAt: v.uploadedAt, confirmedAt: v.uploadedAt }
+}
+
+/** Live rows people see, as views: folders, and files with a version that landed. */
+export async function listedFiles (store, rows) {
+  const views = await Promise.all(rows.map((f) => viewOf(store, f)))
+  return views.filter(Boolean)
+}
+
+/** A workspace's storage limit. The API's option is a ceiling on the row's own quota: a
+ * smaller server (or a test) can lower every workspace's limit without touching the rows.
+ * A row with no quota of its own gets the option; a quota of 0 means no storage. */
+export const quotaOf = (ws, ceiling = Infinity) => Math.min(ws.quotaBytes ?? ceiling ?? Infinity, ceiling ?? Infinity)
+
+/** What a workspace has used and may use, as the app shows it. */
+export async function usageView (store, ws, { workspaceQuotaBytes, maxWorkspaceFiles } = {}) {
+  const { usedBytes, fileCount } = await store.workspaceUsage(ws.id)
+  return { usedBytes, quotaBytes: quotaOf(ws, workspaceQuotaBytes), fileCount, maxFiles: maxWorkspaceFiles }
+}
+
+/** Removes objects from the file store, 100 keys a call (Supabase's limit per remove).
+ * A failed batch is logged and the rest still go: a leftover object costs storage, not data. */
+export async function removeObjects (fileStore, keys, log = () => {}) {
+  for (let i = 0; i < keys.length; i += 100) {
+    try { await fileStore.remove(keys.slice(i, i + 100)) } catch (err) { log(`file store: ${err.message}`) }
+  }
+}
+
+export function workspaceFileRoutes (ctx) {
+  const { store, now, files: fileStore, apiUrl, maxFileBytes, workspaceQuotaBytes, maxWorkspaceFiles, workspaces = false, log = () => {} } = ctx
+  const { reach: reachWorkspace } = workspaceReach(ctx)
+  /** The workspace, for a caller who may see its files; to anyone else the files aren't there. */
+  const reach = async (req, id) => {
+    const r = await reachWorkspace(req, id)
+    if (!canSeeFiles(r.access)) throw new HttpError(404, 'not found')
+    return r
+  }
+  const gated = (fn) => async (...a) => { if (!workspaces) throw new HttpError(404, 'not found'); return fn(...a) }
+  const cleanNote = (v) => { const s = String(v ?? '').trim(); if (s.length > MAX_NOTE) throw new HttpError(400, `Keep the note under ${MAX_NOTE} characters.`); return s }
+  const cleanFilePathOrRoot = (v) => (String(v) === '' ? '' : cleanFilePath(v))
+  // The disk store's links are paths on this API, made absolute on apiUrl. A caller on a
+  // loopback address (a local or test API, listening on a port apiUrl doesn't know) gets
+  // them on the address it used; any other Host header is ignored, so a forged one can't
+  // point links elsewhere. Storage links (Supabase) are absolute already and pass through.
+  const absolute = (url, req) => {
+    if (!url.startsWith('/')) return url
+    const host = String(req.headers.host || '')
+    return (LOOPBACK.test(host) ? `http://${host}` : apiUrl) + url
+  }
+
+  async function fileIn (r, id) {
+    const f = await store.workspaceFileById(needId(id, 'file'))
+    if (!f || f.workspaceId !== r.ws.id || f.deletedAt) throw new HttpError(404, 'no such file')
+    return f
+  }
+  const needEdit = (r) => { if (r.access.access !== 'edit') throw new HttpError(403, 'you can only view this workspace') }
+
+  async function refreshUsage (wsId) {
+    const u = await store.workspaceUsage(wsId)
+    await store.setWorkspaceUsage(wsId, u)
+    return u
+  }
+
+  /** Makes every missing folder on the way to `p` (not `p` itself). */
+  async function ensureFolders (ws, p, by) {
+    const parts = p.split('/').slice(0, -1)
+    for (let i = 1; i <= parts.length; i++) {
+      const fp = parts.slice(0, i).join('/')
+      const row = await store.workspaceFileByPath(ws.id, fp)
+      if (row && row.kind !== 'folder') throw new HttpError(409, `${fp} is a file, not a folder`)
+      if (!row) await store.createWorkspaceFile({ workspaceId: ws.id, path: fp, kind: 'folder', uploadedBy: by })
+    }
+  }
+
+  const removeKeys = (keys) => removeObjects(fileStore, keys, log)
+
+  /** Undoes an upload that never landed: a re-upload goes back to the version before it;
+   * a new file is forgotten. Either way the failed upload's object is removed. */
+  async function abandon (f) {
+    await removeKeys([f.objectKey].filter(Boolean))
+    if ((await store.listWorkspaceFileVersions(f.id)).length) return store.revertWorkspaceFileVersion(f.id)
+    await store.removeWorkspaceFile(f.id)
+    return null
+  }
+
+  /** Forgets uploads that never landed, and removes deleted files past their keep time. */
+  async function sweep (at = now()) {
+    const touched = new Set()
+    for (const f of await store.unconfirmedWorkspaceFiles(at - UNCONFIRMED_MS)) {
+      await abandon(f)
+      touched.add(f.workspaceId)
+    }
+    for (const wsId of touched) await refreshUsage(wsId)
+    await removeKeys(await store.sweepDeletedWorkspaceFiles(at - DELETED_KEEP_MS))
+  }
+
+  const routes = [
+    ['GET', /^\/v1\/workspaces\/([^/]+)\/files$/, gated(async (req, body, [id]) => {
+      const r = await reach(req, id)
+      const folder = new URL(req.url, 'http://x').searchParams.get('folder')
+      let rows = await store.listWorkspaceFiles(r.ws.id)
+      if (folder !== null) { const want = cleanFilePathOrRoot(folder); rows = rows.filter((f) => parentOf(f.path) === want) }
+      return { files: await listedFiles(store, rows) }
+    })],
+
+    // Starts an upload: the row now, the bytes straight to storage through the link, then /done.
+    ['POST', /^\/v1\/workspaces\/([^/]+)\/files$/, gated(async (req, body, [id]) => {
+      const r = await reach(req, id)
+      needEdit(r)
+      const p = cleanFilePath(body.path)
+      const size = Number(body.size)
+      if (!Number.isInteger(size) || size <= 0) throw new HttpError(400, 'Say how many bytes the file is.')
+      if (size > maxFileBytes) throw new HttpError(413, 'file too large')
+      const note = cleanNote(body.note)
+      // A type/subtype and nothing else (no parameters, spaces or line breaks), or the one the name suggests.
+      const given = String(body.mime || '')
+      const mime = given.length <= 100 && MIME.test(given) ? given : mimeOf(nameOf(p))
+      const sha256 = String(body.sha256 || '').slice(0, 64)
+      let existing = await store.workspaceFileByPath(r.ws.id, p)
+      if (existing && existing.kind === 'folder') throw new HttpError(409, `${p} is a folder`)
+      // An earlier upload to this path that hasn't landed. Once its link has expired it
+      // never will (a dropped connection): undo it, so it leaves no phantom version or bytes
+      // behind. Before then someone may still be uploading it: they go first.
+      if (existing && !existing.confirmedAt) {
+        // The same person may take over their own attempt (a retry after a dropped upload).
+        if (existing.uploadedBy !== r.me.account && now() - existing.uploadedAt <= LINK_MS) throw new HttpError(409, 'someone is uploading this file right now; try again in a moment')
+        existing = await abandon(existing)
+      }
+      const usage = await store.workspaceUsage(r.ws.id)
+      if (!existing && usage.fileCount >= maxWorkspaceFiles) throw new HttpError(413, 'this workspace has too many files')
+      if (usage.usedBytes + size > quotaOf(r.ws, workspaceQuotaBytes)) throw new HttpError(413, 'this workspace has used its storage')
+      await ensureFolders(r.ws, p, r.me.account)
+      let file
+      if (existing) {
+        // The version comes from the store (another upload may have got in since `existing`
+        // was read), so the object key, which holds it, is set once the store has answered.
+        const v = await store.newWorkspaceFileVersion(existing.id, { size, mime, sha256, objectKey: '', note, uploadedBy: r.me.account, at: now(), keep: KEEP_VERSIONS })
+        file = await store.setWorkspaceFileObjectKey(existing.id, `${r.ws.id}/${existing.id}/${v.file.version}`)
+        await removeKeys(v.droppedKeys)
+      } else {
+        // The object key holds the file's id, so it is set once the row exists.
+        file = await store.createWorkspaceFile({ workspaceId: r.ws.id, path: p, kind: 'file', size, mime, sha256, note, uploadedBy: r.me.account })
+        file = await store.setWorkspaceFileObjectKey(file.id, `${r.ws.id}/${file.id}/1`)
+      }
+      const upload = await fileStore.uploadTarget(file.objectKey, size)
+      return { file: fileView(file), upload: { ...upload, url: absolute(upload.url, req) } }
+    })],
+
+    ['POST', /^\/v1\/workspaces\/([^/]+)\/files\/([^/]+)\/done$/, gated(async (req, body, [id, fid]) => {
+      const r = await reach(req, id)
+      needEdit(r)
+      const f = await fileIn(r, fid)
+      if (f.kind !== 'file') throw new HttpError(404, 'no such file')
+      // Done twice (a client retrying after a lost answer): nothing to do; the checks below
+      // would otherwise count the file's own bytes against the quota and abandon a landed file.
+      if (f.confirmedAt) return { file: fileView(f) }
+      const there = await fileStore.exists(f.objectKey)
+      if (!there) throw new HttpError(409, 'the upload did not land')
+      // The declared size was checked when the upload started, but storage may hold more
+      // (or fewer) bytes than that: check what actually landed, against the same limits.
+      // Usage counts confirmed bytes only, so this row's pending upload is not in it yet.
+      const usage = await store.workspaceUsage(r.ws.id)
+      const refusal = there.size > maxFileBytes ? new HttpError(413, 'file too large')
+        : usage.usedBytes + there.size > quotaOf(r.ws, workspaceQuotaBytes) ? new HttpError(413, 'this workspace has used its storage')
+          : there.size !== f.size ? new HttpError(409, 'the upload did not match its declared size')
+            : null
+      if (refusal) {
+        await abandon(f)
+        await refreshUsage(r.ws.id)
+        throw refusal
+      }
+      const file = await store.confirmWorkspaceFile(f.id, { size: there.size, at: now() })
+      await refreshUsage(r.ws.id)
+      return { file: fileView(file) }
+    })],
+
+    ['GET', /^\/v1\/workspaces\/([^/]+)\/files\/([^/]+)\/download$/, gated(async (req, body, [id, fid]) => {
+      const r = await reach(req, id)
+      const f = await fileIn(r, fid)
+      if (f.kind !== 'file') throw new HttpError(400, 'that is a folder')
+      const want = new URL(req.url, 'http://x').searchParams.get('version')
+      let key = f.objectKey; let size = f.size
+      if (want && Number(want) !== f.version) {
+        const v = (await store.listWorkspaceFileVersions(f.id)).find((x) => x.version === Number(want))
+        if (!v) throw new HttpError(404, 'no such version')
+        key = v.objectKey; size = v.size
+      } else if (!f.confirmedAt) {
+        // A new version is still uploading: with no version asked for, serve the one before it.
+        const v = !want && await servedVersion(store, f)
+        if (!v) throw new HttpError(409, 'the upload has not landed yet')
+        key = v.objectKey; size = v.size
+      }
+      const name = nameOf(f.path)
+      const { url } = await fileStore.downloadTarget(key, { name, type: f.mime })
+      return { url: absolute(url, req), expiresAt: now() + LINK_MS, name, mime: f.mime, size }
+    })],
+
+    ['GET', /^\/v1\/workspaces\/([^/]+)\/files\/([^/]+)\/versions$/, gated(async (req, body, [id, fid]) => {
+      const r = await reach(req, id)
+      const f = await fileIn(r, fid)
+      return { versions: (await store.listWorkspaceFileVersions(f.id)).map((v) => ({ version: v.version, size: v.size, sha256: v.sha256, note: v.note, uploadedBy: v.uploadedBy, uploadedAt: v.uploadedAt })) }
+    })],
+
+    // Renames or moves (a folder takes everything in it), or changes the note.
+    ['PATCH', /^\/v1\/workspaces\/([^/]+)\/files\/([^/]+)$/, gated(async (req, body, [id, fid]) => {
+      const r = await reach(req, id)
+      needEdit(r)
+      const f = await fileIn(r, fid)
+      const patch = {}
+      if (body.note !== undefined) patch.note = cleanNote(body.note)
+      if (body.path !== undefined) {
+        const p = cleanFilePath(body.path)
+        if (p !== f.path) {
+          if (f.kind === 'folder' && p.startsWith(f.path + '/')) throw new HttpError(400, 'a folder cannot move into itself')
+          if (await store.workspaceFileByPath(r.ws.id, p)) throw new HttpError(409, 'something is already at that path')
+          await ensureFolders(r.ws, p, r.me.account)
+          if (f.kind === 'folder') await store.renameWorkspaceFolder(r.ws.id, f.path, p, now())
+          else patch.path = p
+        }
+      }
+      // A folder move has already happened, with nothing left to patch: an empty update is
+      // an error on Supabase, so read the row back instead.
+      const file = Object.keys(patch).length ? await store.updateWorkspaceFile(f.id, patch) : await store.workspaceFileById(f.id)
+      return { file: (await viewOf(store, file)) || fileView(file) }
+    })],
+
+    // Soft: the bytes stay 30 days (the sweep removes them); a folder takes its contents.
+    ['DELETE', /^\/v1\/workspaces\/([^/]+)\/files\/([^/]+)$/, gated(async (req, body, [id, fid]) => {
+      const r = await reach(req, id)
+      needEdit(r)
+      const f = await fileIn(r, fid)
+      await store.deleteWorkspaceFile(f.id, now())
+      await refreshUsage(r.ws.id)
+      return { ok: true }
+    })],
+
+    ['POST', /^\/v1\/workspaces\/([^/]+)\/folders$/, gated(async (req, body, [id]) => {
+      const r = await reach(req, id)
+      needEdit(r)
+      const p = cleanFilePath(body.path)
+      if (await store.workspaceFileByPath(r.ws.id, p)) throw new HttpError(409, 'something is already at that path')
+      await ensureFolders(r.ws, p, r.me.account)
+      return { file: fileView(await store.createWorkspaceFile({ workspaceId: r.ws.id, path: p, kind: 'folder', uploadedBy: r.me.account })) }
+    })]
+  ]
+
+  return { routes, sweep }
+}