heyquilt 0.0.1 → 0.3.90

package/src/api/agent-auth.js

@@ -0,0 +1,130 @@
+// Agents' keys. An access key (qa_, 1 hour) signs an agent in; a refresh key
+// (qr_, 30 days, single use) swaps for a new pair. Pairs minted by refreshing
+// share a family, and presenting a spent refresh key revokes the whole family:
+// someone copied it, and we can't tell which holder is the real agent. Every
+// agent also gets a resume key (qs_) when it joins, which never expires: it swaps
+// for a pair in a new family once the refresh key stopped working, so a revoke
+// never locks an agent out (only a person revoking the agent does).
+// An app key (qk_) is for apps that can only hold one pasted key (Pipedream, Zapier,
+// a script): it signs the agent in like an access key but never runs out. Its owner
+// makes and revokes it on heyquilt.com.
+import crypto from 'node:crypto'
+import { newToken, hashToken } from './tokens.js'
+import { HttpError } from './http.js'
+
+export const ACCESS_TTL_MS = 60 * 60 * 1000
+export const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000
+// last_used_at is for people reading the dashboard; once a minute is plenty.
+const TOUCH_EVERY_MS = 60 * 1000
+export const REUSED = "This key was already used, so this agent's keys were revoked. Get new ones with your resume key: POST /v1/agents/resume with {\"resumeKey\": \"<resumeKey>\"}."
+const REVOKED = "This agent's keys were revoked. Get new ones with your resume key: POST /v1/agents/resume with {\"resumeKey\": \"<resumeKey>\"}."
+
+/** 'active' while some key can still refresh; 'reused' once a family was revoked; otherwise 'expired'. */
+export function keyStatus (rows, at) {
+  if (rows.some((k) => !k.revokedAt && k.refreshExpiresAt > at)) return 'active'
+  return rows.some((k) => k.revokedAt) ? 'reused' : 'expired'
+}
+
+/** Whether a bearer key is an agent's: an access key or an app key. */
+export const isAgentKey = (key) => key.startsWith('qa_') || key.startsWith('qk_')
+
+export function makeAgentAuth ({ store, now, bearer }) {
+  /** A fresh pair for an agent, in a new family unless one is given. The keys are shown once. */
+  async function mintKeys (agentId, familyId = crypto.randomUUID()) {
+    const accessKey = newToken('qa_'); const refreshKey = newToken('qr_')
+    const at = now()
+    const accessExpiresAt = at + ACCESS_TTL_MS; const refreshExpiresAt = at + REFRESH_TTL_MS
+    await store.createAgentKeys({ agentId, familyId, accessHash: hashToken(accessKey), refreshHash: hashToken(refreshKey), accessExpiresAt, refreshExpiresAt })
+    return { agentId, accessKey, accessExpiresAt, refreshKey, refreshExpiresAt }
+  }
+
+  /** Swaps a refresh key for a new pair in the same family, once. */
+  async function refresh (refreshKey) {
+    const key = typeof refreshKey === 'string' && refreshKey.startsWith('qr_') ? refreshKey : ''
+    const row = key && await store.agentKeyByRefresh(hashToken(key))
+    if (!row) throw new HttpError(401, "This key isn't valid. Invite the agent again.")
+    if (row.revokedAt) throw new HttpError(401, REVOKED)
+    if (row.refreshedAt) { await store.revokeFamily(row.familyId); throw new HttpError(401, REUSED) }
+    if (row.refreshExpiresAt <= now()) throw new HttpError(401, 'This key has expired. Invite the agent again.')
+    const agent = await store.agentById(row.agentId)
+    if (!agent || agent.revokedAt) throw new HttpError(401, 'This agent was revoked.')
+    // Two refreshes racing with one key: only one spends it, and the other is a reuse.
+    if (!await store.claimRefresh(row.id)) { await store.revokeFamily(row.familyId); throw new HttpError(401, REUSED) }
+    let pair
+    try {
+      pair = await mintKeys(agent.id, row.familyId)
+    } catch (err) {
+      // Minting failed after the claim went through: release it rather than
+      // leave the key stuck "spent" with no pair to show for it.
+      await store.releaseRefresh(row.id)
+      throw err
+    }
+    // A reuse caught while this pair was being made (the family revoked
+    // meanwhile) must not leave this new pair working.
+    if ((await store.agentKeyByRefresh(hashToken(key)))?.revokedAt) { await store.revokeFamily(row.familyId); throw new HttpError(401, REUSED) }
+    return pair
+  }
+
+  /** A new resume key for an agent that is joining: the key, and the hash to store. */
+  function newResumeKey () {
+    const resumeKey = newToken('qs_')
+    return { resumeKey, resumeHash: hashToken(resumeKey) }
+  }
+
+  /**
+   * New keys for an agent that proved who it is (its resume key, or a signature with the
+   * key it joined with: routes/agents.js), after its refresh key stopped working: a reply
+   * lost while offline, or a copy of the keys used in two places, leaves it holding a spent
+   * key, which revokes its keys. Every key it had is revoked and it starts a new family.
+   * Never for an agent a person revoked.
+   */
+  async function resume (agent) {
+    if (agent.revokedAt) throw new HttpError(401, 'This agent was revoked. Invite it again.')
+    const families = new Set((await store.listAgentKeys(agent.id)).filter((k) => !k.revokedAt).map((k) => k.familyId))
+    for (const f of families) await store.revokeFamily(f)
+    return mintKeys(agent.id)
+  }
+
+  /** resume() for the agent whose resume key this is. */
+  async function resumeByKey (resumeKey) {
+    const key = typeof resumeKey === 'string' && resumeKey.startsWith('qs_') ? resumeKey : ''
+    const agent = key && await store.agentByResume(hashToken(key))
+    if (!agent) throw new HttpError(401, "This resume key isn't valid. Invite the agent again.")
+    return resume(agent)
+  }
+
+  /** A new app key (qk_) for an agent: shown once, only its hash is stored. */
+  async function mintAppKey (agentId, name) {
+    const key = newToken('qk_')
+    const row = await store.createAgentAppKey({ agentId, name, keyHash: hashToken(key) })
+    return { id: row.id, name: row.name, createdAt: row.createdAt, key }
+  }
+
+  /** The agent behind an app key, or a 401. App keys don't run out: they work until revoked. */
+  async function agentFromAppKey (key) {
+    const row = await store.agentAppKeyByHash(hashToken(key))
+    if (!row) throw new HttpError(401, "this key isn't valid; make a new one on heyquilt.com (Agents)")
+    if (row.revokedAt) throw new HttpError(401, 'this key was revoked; make a new one on heyquilt.com (Agents)')
+    const agent = await store.agentById(row.agentId)
+    if (!agent || agent.revokedAt) throw new HttpError(401, 'this agent was revoked')
+    if (!row.lastUsedAt || now() - row.lastUsedAt >= TOUCH_EVERY_MS) await store.touchAgentAppKey(row.id)
+    if (!agent.lastUsedAt || now() - agent.lastUsedAt >= TOUCH_EVERY_MS) await store.touchAgent(agent.id)
+    return { agent, keyRow: null, appKey: row }
+  }
+
+  /** The agent behind a request's `qa_` (access) or `qk_` (app) bearer key, or a 401. */
+  async function agentFromRequest (req) {
+    const key = bearer(req)
+    if (key.startsWith('qk_')) return agentFromAppKey(key)
+    const keyRow = key.startsWith('qa_') ? await store.agentKeyByAccess(hashToken(key)) : null
+    if (!keyRow) throw new HttpError(401, 'sign the agent in first')
+    if (keyRow.revokedAt) throw new HttpError(401, "this agent's keys were revoked; get new ones with your resume key (POST /v1/agents/resume)")
+    if (keyRow.accessExpiresAt <= now()) throw new HttpError(401, 'this access key has expired; refresh it')
+    const agent = await store.agentById(keyRow.agentId)
+    if (!agent || agent.revokedAt) throw new HttpError(401, 'this agent was revoked')
+    if (!agent.lastUsedAt || now() - agent.lastUsedAt >= TOUCH_EVERY_MS) await store.touchAgent(agent.id)
+    return { agent, keyRow }
+  }
+
+  return { mintKeys, newResumeKey, refresh, resume, resumeByKey, agentFromRequest, mintAppKey }
+}

package/src/api/agent-placement.js

@@ -0,0 +1,157 @@
+// Where an agent works without being added by hand (its placement), and who joins a
+// session inside a workspace. A placement never crosses owners: a personal agent reaches
+// only its owner's personal workspaces, an org agent only its org's. A workspace can
+// keep a placed agent out or change whether it joins sessions (its override), and a
+// session owner can keep any agent out of one session (an exclusion).
+import { HttpError, UUID } from './http.js'
+import { ACCESS, stillInOrg } from './workspace-access.js'
+import { cleanFolders } from '../session-access.js'
+
+export const REACH = ['all', 'workspaces', 'manual']
+export const SESSIONS = ['all', 'invited']
+const MAX_WORKSPACES = 100
+
+/** A placement as a route receives it, checked: { reach, workspaceIds, sessions, access, scopes }. HttpError 400 otherwise. */
+export function cleanPlacement (body) {
+  const b = body && typeof body === 'object' && !Array.isArray(body) ? body : {}
+  if (!REACH.includes(b.reach)) throw new HttpError(400, 'Reach is all, workspaces or manual.')
+  if (!SESSIONS.includes(b.sessions)) throw new HttpError(400, 'Sessions is all or invited.')
+  if (!ACCESS.includes(b.access)) throw new HttpError(400, 'Access is edit or view.')
+  let workspaceIds = []
+  if (b.reach === 'workspaces') {
+    const raw = b.workspaceIds ?? []
+    if (!Array.isArray(raw) || raw.some((id) => typeof id !== 'string' || !UUID.test(id))) throw new HttpError(400, 'workspaceIds must be a list of workspace ids.')
+    workspaceIds = [...new Set(raw.map((id) => id.toLowerCase()))]
+    if (workspaceIds.length > MAX_WORKSPACES) throw new HttpError(400, `A placement can list at most ${MAX_WORKSPACES} workspaces.`)
+  }
+  let scopes
+  try { scopes = cleanFolders(b.scopes ?? []) } catch (e) { throw new HttpError(400, e.message) }
+  return { reach: b.reach, workspaceIds, sessions: b.sessions, access: b.access, scopes }
+}
+
+/**
+ * A live agent (not revoked) from the same owner as `ws`, or null: for a personal workspace
+ * one of its owner's own agents, for an org's one of the org's agents still in it.
+ */
+export async function sameOwnerAgent (store, ws, agentId) {
+  if (!UUID.test(String(agentId || ''))) return null
+  const agent = await store.agentById(agentId)
+  if (!agent || agent.revokedAt) return null
+  if (ws.orgId) {
+    if (agent.orgId !== ws.orgId) return null
+    // Removing an agent from its org revokes it; this keeps a half-removed one out too.
+    if (!(await store.memberByAgent(ws.orgId, agentId))) return null
+  } else if (!ws.ownerUserId || agent.ownerUserId !== ws.ownerUserId) return null
+  return agent
+}
+
+/**
+ * `agentId`'s placement when it covers `ws`, before the workspace's override (so an admin
+ * can still find an agent they kept out, to let it back in); null otherwise.
+ */
+export async function placementIn (store, ws, agentId) {
+  if (!ws || !(await sameOwnerAgent(store, ws, agentId))) return null
+  const placement = await store.agentPlacement(agentId)
+  if (!placement || placement.reach === 'manual') return null
+  if (placement.reach === 'workspaces' && !(placement.workspaceIds || []).includes(ws.id)) return null
+  return placement
+}
+
+/**
+ * How `agentId`'s placement reaches `ws`: { access, scopes, via: 'placed' | 'global', sessions }
+ * or null. Ids in a placement that aren't `ws` are ignored, so a deleted workspace's id left
+ * in the list never matters.
+ */
+export async function agentReach (store, ws, agentId) {
+  const placement = await placementIn(store, ws, agentId)
+  if (!placement) return null
+  const override = await store.workspaceAgentOverride(ws.id, agentId)
+  if (override?.excluded) return null
+  return { access: placement.access, scopes: [...(placement.scopes || [])], via: placement.reach === 'all' ? 'global' : 'placed', sessions: override?.sessions ?? placement.sessions }
+}
+
+/** Whether `agentId` joins `session` (in `ws`) when it starts: { joins, via } (via null when nothing decided yes). */
+async function decide (store, session, ws, agentId) {
+  if (!UUID.test(String(agentId || ''))) return { joins: false, via: null }
+  if (await store.sessionAgentExcluded(session.room, agentId)) return { joins: false, via: null }
+  return inviteFor(store, ws, agentId)
+}
+
+/** What the workspace says about inviting `agentId` to its sessions, before any keep-out: { joins, via }. */
+async function inviteFor (store, ws, agentId) {
+  const no = { joins: false, via: null }
+  if (!UUID.test(String(agentId || ''))) return no
+  // A revoked agent never joins, whatever rows it left behind.
+  const agent = await store.agentById(agentId)
+  if (!agent || agent.revokedAt) return no
+  const account = `agent:${agentId}`
+  const member = await store.workspaceMember(ws.id, account)
+  // A member row decides, but it makes an agent join every session only when the agent is
+  // the workspace owner's own: anyone can add someone else's agent, never summon it.
+  if (member && await stillInOrg(store, ws, account, null)) return { joins: member.sessions === 'all' && !!(await sameOwnerAgent(store, ws, agentId)), via: 'member' }
+  const r = await agentReach(store, ws, agentId)
+  if (r) return { joins: r.sessions === 'all', via: r.via }
+  return no
+}
+
+/**
+ * The room's session and its workspace, or null when it isn't in one. As in roomAccess, a
+ * session counts as in a workspace only when its owner (as the relay reports it) put it there.
+ */
+async function sessionAndWorkspace (store, room) {
+  const session = await store.sessionByRoom(room)
+  if (!session || !session.workspaceId) return null
+  if (!session.ownerAccount || session.ownerAccount !== session.workspaceLinkedBy) return null
+  const ws = await store.workspaceById(session.workspaceId)
+  return ws ? { session, ws } : null
+}
+
+/**
+ * Whether an agent joins the session in `room` by itself: kept out of this session, no;
+ * a member row in the session's workspace decides next (yes only for the workspace owner's
+ * own agent); then its placement (with the workspace's override); otherwise no.
+ */
+export async function agentJoinsSession (store, room, agentId) {
+  const sw = await sessionAndWorkspace(store, room)
+  if (!sw) return false
+  return (await decide(store, sw.session, sw.ws, agentId)).joins
+}
+
+/** Every agent that joins the session in `room` by itself, with what decided it: [{ agentId, via }]. */
+export async function agentsJoiningSession (store, room) {
+  const sw = await sessionAndWorkspace(store, room)
+  if (!sw) return []
+  const { session, ws } = sw
+  const members = (await store.listWorkspaceMembers(ws.id)).filter((m) => m.account.startsWith('agent:')).map((m) => m.account.slice(6))
+  const own = ws.orgId ? await store.listOrgAgents(ws.orgId) : await store.listPersonalAgents(ws.ownerUserId)
+  const out = []
+  for (const agentId of new Set([...members, ...own.map((a) => a.id)])) {
+    const d = await decide(store, session, ws, agentId)
+    if (d.joins) out.push({ agentId, via: d.via })
+  }
+  return out
+}
+
+/**
+ * A session's agents as its owner manages them (the session's People): every agent its
+ * workspace invites to it, by name, with why (via 'member' | 'global' | 'placed'), who manages
+ * that ('workspace', 'owner' or 'org') and whether its owner said Don't invite (excluded: the
+ * keep-out). Sorted by name. A session outside a workspace invites nobody.
+ */
+export async function sessionAgents (store, room) {
+  const sw = await sessionAndWorkspace(store, room)
+  if (!sw) return []
+  const { ws } = sw
+  const excluded = new Set((await store.listSessionAgentExclusions(room)).map((e) => e.agentId))
+  const ids = new Set()
+  for (const m of await store.listWorkspaceMembers(ws.id)) if (m.account.startsWith('agent:')) ids.add(m.account.slice(6))
+  for (const a of ws.orgId ? await store.listOrgAgents(ws.orgId) : await store.listPersonalAgents(ws.ownerUserId)) ids.add(a.id)
+  const out = []
+  for (const agentId of ids) {
+    const d = await inviteFor(store, ws, agentId)
+    if (!d.joins) continue
+    const agent = await store.agentById(agentId)
+    out.push({ agentId, name: agent?.name || '', via: d.via, managedBy: d.via === 'member' ? 'workspace' : ws.orgId ? 'org' : 'owner', excluded: excluded.has(agentId) })
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name))
+}

package/src/api/audit.js

@@ -0,0 +1,83 @@
+// A session's audit trail, for its owner: every visit (who, a person or an agent, through
+// the app or as a hosted agent, with which tool), when it started and ended and why, and
+// what it did in between. Pure: routes/sessions.js hands it rows from the store.
+// The relay reports what it saw (see src/presence.js); this adds what only the accounts
+// API knows: an agent whose keys were revoked had its visit end because of that.
+
+// A hosted agent counts as gone after this long without a call (the relay's HOSTED_ONLINE_MS).
+export const HOSTED_QUIET_MS = 30 * 60 * 1000
+export const MAX_ACTIONS = 5000
+
+export const REASON_TEXT = {
+  left: 'Left',
+  disconnected: 'Connection dropped',
+  removed: 'Removed by the owner',
+  pass_expired: 'Sign-in ran out',
+  session_ended: 'Session ended',
+  relay_restart: 'Relay restarted',
+  idle: 'Done working (went quiet)',
+  replaced: 'Reconnected',
+  needs_update: 'Sent away to update',
+  revoked: 'Access revoked'
+}
+
+/**
+ * Why a visit ended, with what the relay couldn't know: an agent whose keys were revoked
+ * while it was in, or before it would have come back, ended because of that.
+ */
+export function endReasonOf (v, revokedAt) {
+  if (v.endedAt == null) return null
+  const r = v.endReason || null
+  if (revokedAt == null || revokedAt < v.startedAt) return r
+  if (r === 'idle') return revokedAt <= v.endedAt + HOSTED_QUIET_MS ? 'revoked' : r
+  if (r === 'pass_expired' || r === 'disconnected' || r == null) return revokedAt <= v.endedAt ? 'revoked' : r
+  return r
+}
+
+/**
+ * The trail: visits newest first, each with its actions oldest first.
+ * `revoked` maps an agent account ('agent:<id>') to when its keys were revoked.
+ */
+export function auditTrail ({ visits, actions, revoked = new Map() }) {
+  const byVisit = new Map()
+  for (const a of actions) {
+    if (!byVisit.has(a.visitStartId)) byVisit.set(a.visitStartId, [])
+    byVisit.get(a.visitStartId).push({ at: a.at, action: a.action, target: a.target || '' })
+  }
+  return [...visits]
+    .sort((a, b) => b.startedAt - a.startedAt)
+    .map((v) => ({
+      account: v.account,
+      name: v.accountName,
+      kind: v.kind,
+      via: v.via || null,
+      tool: v.tool || null,
+      startedAt: v.startedAt,
+      endedAt: v.endedAt ?? null,
+      endReason: endReasonOf(v, revoked.get(v.account) ?? null),
+      actions: byVisit.get(v.eventStartId) || [] // already oldest first, in arrival order
+    }))
+}
+
+const iso = (t) => (t == null ? '' : new Date(t).toISOString())
+const cell = (x) => {
+  const s = String(x ?? '')
+  // A cell a spreadsheet would run as a formula is quoted as text.
+  const safe = /^[=+\-@\t\r]/.test(s) ? `'${s}` : s
+  return /[",\n\r]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe
+}
+
+/** The trail as CSV, one row per event (joined, an action, left), oldest first, times in UTC. */
+export function auditCsv (trail) {
+  const rows = []
+  for (const v of trail) {
+    const who = [v.name, v.account, v.kind]
+    const how = [v.via || '', v.tool || '']
+    rows.push([v.startedAt, ...who, 'joined', '', ...how])
+    for (const a of v.actions) rows.push([a.at, ...who, a.action, a.target, ...how])
+    if (v.endedAt != null) rows.push([v.endedAt, ...who, 'left', v.endReason || '', ...how])
+  }
+  rows.sort((a, b) => a[0] - b[0])
+  const head = ['time_utc', 'member', 'account', 'kind', 'event', 'detail', 'via', 'tool']
+  return [head, ...rows.map(([t, ...rest]) => [iso(t), ...rest])].map((r) => r.map(cell).join(',')).join('\r\n') + '\r\n'
+}

package/src/api/auth.js

@@ -0,0 +1,17 @@
+// Website users sign in with Supabase; the API trusts a request from them when its
+// bearer token is a JWT signed by the project's keys (fetched from its JWKS).
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+
+export function createUserVerifier ({ supabaseUrl, jwks }) {
+  const base = String(supabaseUrl).replace(/\/+$/, '')
+  const keys = jwks || createRemoteJWKSet(new URL(`${base}/auth/v1/.well-known/jwks.json`))
+  return async (token) => {
+    if (!token) return null
+    try {
+      const { payload } = await jwtVerify(token, keys, { issuer: `${base}/auth/v1`, audience: 'authenticated' })
+      return payload.sub ? { userId: payload.sub, email: payload.email || '' } : null
+    } catch {
+      return null
+    }
+  }
+}

package/src/api/domains.js

@@ -0,0 +1,30 @@
+// Public mail providers: anyone can get an address there, so an org can never
+// claim one of these domains for join requests.
+const PUBLIC = new Set([
+  'gmail.com', 'googlemail.com', 'outlook.com', 'hotmail.com', 'live.com', 'msn.com', 'icloud.com', 'me.com', 'mac.com',
+  'aol.com', 'proton.me', 'protonmail.com', 'pm.me', 'mail.com', 'zoho.com', 'zohomail.com', 'fastmail.com', 'fastmail.fm',
+  'hey.com', 'qq.com', '163.com', '126.com', 'yeah.net', 'sina.com', 'naver.com', 'daum.net', 'mail.ru', 'inbox.ru', 'list.ru',
+  'bk.ru', 'rambler.ru', 'web.de', 't-online.de', 'tutanota.com', 'tuta.io', 'hushmail.com', 'rediffmail.com', 'ymail.com',
+  'rocketmail.com', 'outlook.co.uk', 'hotmail.co.uk', 'live.co.uk', 'duck.com', 'mailbox.org', 'posteo.de'
+])
+// Providers with a domain per country: yahoo.co.uk, gmx.de, yandex.ru, ...
+const FAMILIES = /^(yahoo|gmx|yandex)\.[a-z]{2,}(\.[a-z]{2,})?$/
+const DOMAIN = /^(?=.{4,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/
+
+export function isDomain (d) {
+  return DOMAIN.test(String(d || ''))
+}
+
+/** The lowercase domain of an email address, or '' if it doesn't have a real one. */
+export function emailDomain (email) {
+  const s = String(email || '').trim().toLowerCase()
+  const at = s.lastIndexOf('@')
+  if (at < 1) return ''
+  const d = s.slice(at + 1).replace(/\.$/, '')
+  return isDomain(d) ? d : ''
+}
+
+export function isPublicDomain (domain) {
+  const d = String(domain || '').trim().toLowerCase().replace(/\.$/, '')
+  return PUBLIC.has(d) || FAMILIES.test(d)
+}

package/src/api/file-paths.js

@@ -0,0 +1,40 @@
+// Rules for a workspace file's path and name. Pure.
+import { HttpError, stripInvisible } from './http.js'
+
+const MAX_PATH = 500
+const MIMES = {
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml',
+  mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', mp3: 'audio/mpeg', wav: 'audio/wav', m4a: 'audio/mp4',
+  pdf: 'application/pdf', csv: 'text/csv', txt: 'text/plain', md: 'text/markdown', json: 'application/json',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', xls: 'application/vnd.ms-excel',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', zip: 'application/zip'
+}
+
+/** 'cuts/teaser.mp4': trimmed, single slashes, no '.' or '..' segments, no backslashes or control characters. */
+export function cleanFilePath (value) {
+  const str = String(value ?? '')
+  // Checked on the raw string: stripInvisible would otherwise quietly erase the
+  // very control characters this is meant to catch.
+  if (/[\\\u0000-\u001f\u007f]/.test(str)) throw new HttpError(400, 'That path has characters a file name cannot have.')
+  const raw = stripInvisible(str).join('').trim()
+  const parts = raw.split('/').map((p) => p.trim()).filter((p) => p !== '')
+  if (!parts.length) throw new HttpError(400, 'Give the file a path.')
+  if (parts.some((p) => p === '.' || p === '..')) throw new HttpError(400, 'A path cannot contain . or .. parts.')
+  const out = parts.join('/')
+  if (out.length > MAX_PATH) throw new HttpError(400, `Keep the path under ${MAX_PATH} characters.`)
+  return out
+}
+
+export const parentOf = (p) => (p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '')
+export const nameOf = (p) => p.slice(p.lastIndexOf('/') + 1)
+export const mimeOf = (name) => MIMES[String(name).toLowerCase().split('.').pop()] || 'application/octet-stream'
+export const isTextual = (mime) => /^text\//.test(mime) || mime === 'application/json'
+
+/** A Content-Disposition header for any file name. Header values must be Latin-1 (Node
+ * throws on anything else), so `filename` is an ASCII fallback (anything outside printable
+ * ASCII, a quote or a backslash becomes `_`) and `filename*` carries the real name (RFC 6266). */
+export function contentDisposition (kind, name) {
+  const ascii = [...String(name)].map((c) => (/^[\x20-\x7e]$/.test(c) && c !== '"' && c !== '\\' ? c : '_')).join('')
+  const utf8 = encodeURIComponent(String(name)).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+  return `${kind}; filename="${ascii}"; filename*=UTF-8''${utf8}`
+}

package/src/api/file-store.js

@@ -0,0 +1,99 @@
+// Where workspace files' bytes live. The API only hands out short-lived links: apps upload
+// and download straight to storage (Supabase) or, without storage settings, to the API's
+// own disk through signed links the API serves itself.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { createClient } from '@supabase/supabase-js'
+
+export const LINK_MS = 10 * 60 * 1000
+const KEY = /^[0-9a-f-]{36}\/[0-9a-f-]{36}\/\d+$/
+
+const checkKey = (key) => { if (!KEY.test(String(key))) throw new Error('not a storage key'); return key }
+
+/** Files on the API's disk, reached through HMAC-signed links the API serves (tests, --memory, self-hosting). */
+export class DiskStore {
+  constructor (dir, { now = Date.now, signing = crypto.randomBytes(32) } = {}) {
+    this.dir = dir
+    this.now = now
+    this.signing = signing
+  }
+
+  file (key) { return path.join(this.dir, ...checkKey(key).split('/')) }
+
+  // `name` and `type` are only ever non-empty on a GET link; folding them into the
+  // signature means a link holder can't change the download's filename or content type
+  // (e.g. to have the bytes served back as `text/html` on the API's own origin).
+  sign (key, method, exp, size, name = '', type = '') {
+    return crypto.createHmac('sha256', this.signing).update(`${method} ${key} ${exp} ${size ?? ''} ${name} ${type}`).digest('hex')
+  }
+
+  verify (key, method, exp, sig, size, name = '', type = '') {
+    if (!KEY.test(String(key)) || !(Number(exp) > this.now())) return false
+    const want = Buffer.from(this.sign(key, method, exp, size, name, type), 'hex')
+    const got = Buffer.from(String(sig || ''), 'hex')
+    return got.length === want.length && crypto.timingSafeEqual(got, want)
+  }
+
+  async uploadTarget (key, size) {
+    checkKey(key)
+    const exp = this.now() + LINK_MS
+    return { method: 'PUT', url: `/v1/file-data/${key}?m=PUT&exp=${exp}&sig=${this.sign(key, 'PUT', exp, size)}&n=${size}`, headers: {} }
+  }
+
+  async downloadTarget (key, { name = '', type = '' } = {}) {
+    checkKey(key)
+    const exp = this.now() + LINK_MS
+    const sig = this.sign(key, 'GET', exp, undefined, name, type)
+    const q = new URLSearchParams({ m: 'GET', exp: String(exp), sig, name, type })
+    return { url: `/v1/file-data/${key}?${q}` }
+  }
+
+  async exists (key) {
+    try { return { size: fs.statSync(this.file(key)).size } } catch { return null }
+  }
+
+  async remove (keys) { for (const k of keys) fs.rmSync(this.file(k), { force: true }) }
+}
+
+/** Files in a private Supabase Storage bucket in the Quilt Files project. */
+export class SupabaseStore {
+  constructor ({ url, key, bucket, client }) {
+    const c = client || createClient(url, key, { auth: { persistSession: false, autoRefreshToken: false } })
+    this.bucket = c.storage.from(bucket)
+  }
+
+  async uploadTarget (key, size) {
+    const { data, error } = await this.bucket.createSignedUploadUrl(checkKey(key), { upsert: false })
+    if (error) throw new Error(`storage: ${error.message}`)
+    return { method: 'PUT', url: data.signedUrl, headers: {} }
+  }
+
+  async downloadTarget (key, { name = '', type = '' } = {}) {
+    const { data, error } = await this.bucket.createSignedUrl(checkKey(key), LINK_MS / 1000, name ? { download: name } : {})
+    if (error) throw new Error(`storage: ${error.message}`)
+    return { url: data.signedUrl }
+  }
+
+  async exists (key) {
+    checkKey(key)
+    const prefix = key.slice(0, key.lastIndexOf('/'))
+    const leaf = key.slice(key.lastIndexOf('/') + 1)
+    const { data, error } = await this.bucket.list(prefix, { limit: 100, search: leaf })
+    if (error) throw new Error(`storage: ${error.message}`)
+    const hit = (data || []).find((f) => f.name === leaf)
+    return hit ? { size: Number(hit.metadata?.size || 0) } : null
+  }
+
+  async remove (keys) {
+    if (!keys.length) return
+    const { error } = await this.bucket.remove(keys.map(checkKey))
+    if (error) throw new Error(`storage: ${error.message}`)
+  }
+}
+
+export function makeFileStore (cfg, dir) {
+  if (!cfg.storageUrl !== !cfg.storageKey) throw new Error('Workspace file storage is half set up: set both QUILT_STORAGE_URL and QUILT_STORAGE_KEY to use Supabase Storage, or neither to keep files on this server\'s disk.')
+  if (cfg.storageUrl && cfg.storageKey) return new SupabaseStore({ url: cfg.storageUrl, key: cfg.storageKey, bucket: cfg.storageBucket || 'workspace-files' })
+  return new DiskStore(dir)
+}

package/src/api/fly-machines.js

@@ -0,0 +1,76 @@
+// The Fly Machines API, for people's cloud AI machines (routes/ai-vm.js): one machine and one
+// volume per person, in the app AI_VM_APP (never the relay's). Plain fetch, so tests point it
+// at a fake server. See https://fly.io/docs/machines/api/.
+
+export const FLY_API = 'https://api.machines.dev/v1'
+// Small enough to suspend (Fly suspends machines of 2 GB or less) and to cost little.
+export const GUEST = { cpu_kind: 'shared', cpus: 2, memory_mb: 2048 }
+export const VOLUME_GB = 5
+const ID = /^[A-Za-z0-9_-]{1,64}$/
+
+const needId = (id, what) => {
+  if (!ID.test(String(id || ''))) throw new Error(`bad ${what} id`)
+  return id
+}
+
+/**
+ * A client for one Fly app. `token` is FLY_API_TOKEN; `image` the AI machine image
+ * (registry.fly.io/<app>:<tag>); `base` and `fetch` are for tests.
+ */
+export function flyMachines ({ token, app, image, region = 'iad', base = FLY_API, fetch: fetchImpl = globalThis.fetch }) {
+  const root = `${String(base).replace(/\/+$/, '')}/apps/${encodeURIComponent(app)}`
+
+  async function call (method, path, body, { gone = false } = {}) {
+    let res
+    try {
+      res = await fetchImpl(root + path, {
+        method,
+        headers: { authorization: `Bearer ${token}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(60_000)
+      })
+    } catch (err) {
+      throw Object.assign(new Error(`Fly did not answer (${err.cause?.code || err.message})`), { status: 502 })
+    }
+    const data = await res.json().catch(() => null)
+    // Destroying what is already gone is done.
+    if (gone && res.status === 404) return null
+    if (!res.ok) throw Object.assign(new Error(`Fly: ${(data && (data.error || data.message)) || `answered ${res.status}`}`), { status: res.status })
+    return data
+  }
+
+  return {
+    app,
+    image,
+    region,
+    /** A new volume for one person's machine; encrypted, in this app's region. */
+    createVolume: async ({ name, sizeGb = VOLUME_GB }) => call('POST', '/volumes', { name, region, size_gb: sizeGb, encrypted: true }),
+    /** A machine running the AI image with the volume as /data. It restarts on a crash, never on its own after a stop. */
+    createMachine: async ({ name, volumeId, env = {} }) => call('POST', '/machines', {
+      name,
+      region,
+      config: {
+        image,
+        env,
+        guest: GUEST,
+        mounts: [{ volume: needId(volumeId, 'volume'), path: '/data' }],
+        restart: { policy: 'on-failure', max_retries: 5 },
+        auto_destroy: false,
+        metadata: { quilt: 'ai-vm' }
+      }
+    }),
+    getMachine: async (id) => call('GET', `/machines/${needId(id, 'machine')}`),
+    /** Starts a stopped machine, or resumes a suspended one where it was. */
+    start: async (id) => call('POST', `/machines/${needId(id, 'machine')}/start`),
+    suspend: async (id) => call('POST', `/machines/${needId(id, 'machine')}/suspend`),
+    stop: async (id) => call('POST', `/machines/${needId(id, 'machine')}/stop`),
+    destroyMachine: async (id) => call('DELETE', `/machines/${needId(id, 'machine')}?force=true`, null, { gone: true }),
+    destroyVolume: async (id) => call('DELETE', `/volumes/${needId(id, 'volume')}`, null, { gone: true })
+  }
+}
+
+/** The client from the API's environment, or null when cloud AI machines aren't set up here. */
+export function flyFromEnv (env = process.env) {
+  if (!env.FLY_API_TOKEN || !env.AI_VM_APP || !env.AI_VM_IMAGE) return null
+  return flyMachines({ token: env.FLY_API_TOKEN, app: env.AI_VM_APP, image: env.AI_VM_IMAGE, region: env.AI_VM_REGION || 'iad' })
+}