pipework 0.252.0 → 0.252.1

package/src/infra/access-links/handle.ts

@@ -0,0 +1,892 @@
+import { randomUUID } from 'node:crypto'
+import { openChildTrace } from '../../trace/entry/child-trace.js'
+import { finalizeTrace } from '../../trace/entry/finalize-trace.js'
+import { sql } from '../../data/db/sql.js'
+import { pipe, pipeRaw, pipeSystem } from '../../data/db/db.js'
+import type { DB, SQL } from '../../data/db/index.js'
+import { requireContext, runInContext } from '../../request/context/store.js'
+import { bindTransaction } from '../../request/context/guard.js'
+import { propagateLocals } from '../../request/context/run-in-transaction.js'
+import type { Flow } from '../../request/context/types.js'
+import type { HttpResponse } from '../../request/http/types.js'
+import { writeInfraAudit } from '../../data/write/audit/infra-audit.js'
+import { resolveActorId } from '../../data/write/audit/actor.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFault, faultMessage } from '../alerts/faults.js'
+import { ValidationError } from '../../core/errors/index.js'
+import { inTenant as runAsTenant } from '../../auth/tenant/in-tenant.js'
+import { encodeCursor, decodeCursor } from '../../request/fixture/paginate.js'
+import { createCodeGenerator, type CodeConfig } from './code.js'
+
+export interface RateLimitConfig {
+  readonly max: number
+  readonly windowMs: number
+}
+
+export interface AccessLinkTarget {
+  readonly type: string
+  readonly id: string
+}
+
+/** A link as its tenant sees it — includes the code and the app's `checkData`. */
+export interface AccessLink {
+  readonly id: string
+  readonly tenantId: string
+  readonly code: string
+  readonly target: AccessLinkTarget
+  readonly permissions: readonly string[]
+  readonly note: string | null
+  readonly createdBy: string | null
+  readonly createdAt: Date
+  readonly expiresAt: Date | null
+  readonly maxUses: number | null
+  readonly requireChecks: readonly string[]
+  readonly checkData: unknown
+  readonly revokedAt: Date | null
+  readonly revokedBy: string | null
+}
+
+/** A link as a public route sees it — never `checkData`, never the code. */
+export interface PublicLink {
+  readonly id: string
+  readonly target: AccessLinkTarget
+  readonly permissions: readonly string[]
+  readonly note: string | null
+  readonly expiresAt: Date | null
+  readonly maxUses: number | null
+  readonly usesCompleted: number
+  readonly requireChecks: readonly string[]
+}
+
+export interface AccessLinkUse {
+  readonly id: string
+  readonly linkId: string
+  readonly kind: string
+  readonly status: 'pending' | 'completed' | 'abandoned'
+  readonly startedAt: Date
+  readonly reservedUntil: Date
+  readonly completedAt: Date | null
+  readonly client: string | null
+  readonly location: string | null
+  /** App-defined detail given to `beginUse` / `completeUse` (shallow-merged); `null` when none was given. */
+  readonly detail: Readonly<Record<string, unknown>> | null
+  /** When `claimUse` took this use; `null` while unclaimed. */
+  readonly claimedAt: Date | null
+}
+
+export interface AccessLinkCheckArgs {
+  readonly link: AccessLink
+  readonly proof: unknown
+  readonly client: string | null
+}
+
+export type AccessLinkCheck = (args: AccessLinkCheckArgs) => Promise<boolean>
+
+export interface AccessLinksConfig {
+  /** The app's permission names, e.g. `['view', 'download']`. */
+  readonly permissions: readonly string[]
+  readonly code?: CodeConfig
+  /** Pre-use verifiers by name; a link lists the ones it requires in `requireChecks`. */
+  readonly checks?: Readonly<Record<string, AccessLinkCheck>>
+  /** How long a begun use holds its slot before it frees. Default 15 minutes. */
+  readonly reservationMs?: number
+  /** Per-client limit on codes that match no link, counted in Postgres across processes. Default 30 misses per 60 s; a client over it is refused for every code. `false` turns it off. */
+  readonly resolveRateLimit?: RateLimitConfig | false
+  /** Called for every code that is not found — the app's guessing signal. */
+  readonly onMiss?: (info: { client: string | null; code: string }) => void
+}
+
+export interface LinkOptions {
+  readonly target: AccessLinkTarget
+  readonly permissions: readonly string[]
+  readonly note?: string
+  readonly expiresAt?: Date
+  readonly maxUses?: number
+  readonly requireChecks?: readonly string[]
+  readonly checkData?: unknown
+}
+
+type LinkState = 'not-found' | 'revoked' | 'expired' | 'exhausted'
+
+/** A link in a listing: the link, its completed use count and its state. */
+export type AccessLinkListed = AccessLink & {
+  readonly usesCompleted: number
+  readonly state: 'active' | 'revoked' | 'expired' | 'exhausted'
+}
+
+export interface AccessLinkPage {
+  readonly items: AccessLinkListed[]
+  /** Pass as `cursor` for the next (older) page; `null` at the end. */
+  readonly nextCursor: string | null
+}
+
+export type ResolveResult =
+  | { readonly status: 'active'; readonly link: PublicLink; readonly tenantId: string }
+  | { readonly status: LinkState | 'rate-limited' }
+
+export type BeginUseResult =
+  | { readonly ok: true; readonly useToken: string; readonly link: PublicLink }
+  | { readonly ok: false; readonly reason: LinkState | 'kind-not-permitted' | 'check-failed' | 'rate-limited' }
+
+export type CompleteUseResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: 'not-found' | 'expired-reservation' | 'already-settled' }
+
+export type ClaimUseResult =
+  | { readonly ok: true; readonly link: PublicLink }
+  | { readonly ok: false; readonly reason: 'not-found' | 'already-claimed' | 'expired-reservation' | 'already-settled' }
+
+export type AbandonUseResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: 'not-found' | 'already-settled' }
+
+export interface AccessLinks {
+  /** Creates a link. When the Flow has a trace with an open step, an `audit_record` (`AccessLink`, verb `create`, the link without its code or `checkData`) is written in the same transaction. */
+  link(options: LinkOptions): Promise<AccessLink>
+  get(id: string): Promise<AccessLink | null>
+  list(options?: { target?: AccessLinkTarget }): Promise<AccessLink[]>
+  /** One page of the tenant's links, newest first, with completed use counts and state; `nextCursor` is `null` on the last page. `limit` defaults to 50, at most 500. */
+  listPage(options?: {
+    target?: AccessLinkTarget
+    createdBy?: string
+    state?: AccessLinkListed['state']
+    limit?: number
+    cursor?: string
+  }): Promise<AccessLinkPage>
+  /** Revokes a link; when this call revoked it and the Flow has an open trace step, an `AccessLink:revoke` audit record is written in the same transaction. */
+  revoke(id: string): Promise<AccessLink | null>
+  /**
+   * Deletes one link of the tenant with its `access_link_code` row and all its
+   * `access_link_use` rows, in one transaction (the caller's when there is one).
+   * Returns true when this call deleted it, false when the tenant has no such link.
+   * Writes an `AccessLink:delete` audit record (`{ id, target, usesDeleted }`, no
+   * personal fields) under the same open-step rule as `revoke`; the link's earlier
+   * audit records are left as they are. Afterwards `get`/`list`/`listPage` omit the
+   * link and `resolve`/`beginUse`/`completeUse`/`abandonUse`/`claimUse` with its code
+   * or tokens return `not-found`; a miss on the deleted code counts toward the
+   * guessing limit, as an unknown code does.
+   */
+  delete(id: string): Promise<boolean>
+  /**
+   * Deletes every link of the tenant whose target is `{ type, id }`, revoked and
+   * expired ones included, as `delete` does for each, in one transaction.
+   * Returns how many links it deleted.
+   */
+  deleteForTarget(target: AccessLinkTarget): Promise<number>
+  uses(linkId: string): Promise<AccessLinkUse[]>
+  resolve(code: string, options?: { client?: string | null }): Promise<ResolveResult>
+  beginUse(code: string, options: {
+    kind: string
+    client?: string | null
+    location?: string | null
+    proof?: Readonly<Record<string, unknown>>
+    /** App-defined detail stored on the use and shown by `uses()` (a JSON object). */
+    detail?: Readonly<Record<string, unknown>>
+  }): Promise<BeginUseResult>
+  /** `detail` is shallow-merged over the detail given to `beginUse` (new keys win). */
+  completeUse(useToken: string, options?: { detail?: Readonly<Record<string, unknown>> }): Promise<CompleteUseResult>
+  abandonUse(useToken: string): Promise<AbandonUseResult>
+  /**
+   * Takes a pending use exactly once, across processes: a single
+   * `UPDATE ... SET claimed_at = now() WHERE claimed_at IS NULL AND status = 'pending'
+   * AND reserved_until > clock_timestamp()`, so of any number of concurrent calls for
+   * one token exactly one gets `{ ok: true, link }`; the rest get `already-claimed`.
+   * Claiming does not count the use: `completeUse` / `abandonUse` still do. `link`
+   * is accepted by `asLink` like a `beginUse` result.
+   *
+   * Pattern for a single-use URL: `beginUse` when the URL is issued, hand out a URL
+   * carrying `useToken`, and on the follow `claimUse`, serve, then `completeUseWhenSent`.
+   * Other reasons: `not-found`, `expired-reservation` (reservation or link expiry
+   * passed), `already-settled` (completed or abandoned).
+   */
+  claimUse(useToken: string): Promise<ClaimUseResult>
+  /**
+   * Counts the use when the response has been sent, and frees it when the connection
+   * closed first: registers `response.onFinish`, then `completeUse(useToken, options)`
+   * on `'sent'` and `abandonUse(useToken)` on `'aborted'`. Call it before returning
+   * the handler's streamed body. The callback runs after the request's transaction
+   * has ended, with the Flow captured here and no transaction of its own, so it
+   * opens its own. The trace is closed by then, so the completion writes no
+   * `AccessLink:use` audit row; the use log row is the record. A failure is logged,
+   * never thrown into the response.
+   */
+  completeUseWhenSent(
+    response: HttpResponse,
+    useToken: string,
+    options?: { detail?: Readonly<Record<string, unknown>> },
+  ): void
+  /**
+   * Runs `fn` as the tenant an access link resolved to, from a `.public()` route.
+   * `grant` must be the object `resolve` returned with `status: 'active'` or
+   * `beginUse` or `claimUse` returned with `ok: true`; anything else (hand-built, copied,
+   * refused) throws, so a tenant cannot be named, only earned.
+   *
+   * Inside `fn` the Flow is a child of the current one — same request id — with `tenant` set to the link's tenant and
+   * `auth = { userId: 'link:<linkId>', accessLinkId }`, so `pipe()` is scoped to
+   * the tenant and an audited write records `actor_id = 'link:<linkId>'`. When
+   * the current Flow is traced, the work inside `fn` is recorded in a child trace
+   * (a child of the request's trace, opened at the step open on entry) that
+   * carries the link's tenant, so the tenant can read it; the request's own trace
+   * stays tenantless. The child trace closes when `fn`'s transaction settles. `fn`
+   * runs in its own transaction on the default database as the app role
+   * (row-level security applies), opened with the tenant's session variables.
+   * It commits when `fn` resolves and rolls back when `fn` throws; under the
+   * vitest harness it is a savepoint of the test's transaction. Nested
+   * `pipe.transaction` calls inside `fn` are savepoints of it.
+   *
+   * Only the default database is carried into `fn`: other databases bound in the
+   * outer Flow are not, so `pipe('<other>')` inside `fn` opens no bound
+   * transaction. Outside `fn` the Flow is unchanged: no tenant, no auth.
+   */
+  asLink<T>(grant: ResolveResult | BeginUseResult | ClaimUseResult, fn: () => Promise<T>): Promise<T>
+}
+
+const DEFAULT_RESERVATION_MS = 15 * 60 * 1000
+const MISS_CLEANUP_EVERY_MS = 60_000
+const DEFAULT_RATE_LIMIT: RateLimitConfig = { max: 30, windowMs: 60_000 }
+const MAX_CODE_ATTEMPTS = 5
+const DEFAULT_LIST_LIMIT = 50
+const MAX_LIST_LIMIT = 500
+const LIST_STATES: readonly string[] = ['active', 'revoked', 'expired', 'exhausted']
+
+type Row = Record<string, unknown>
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.map(String) : []
+}
+
+// Raw `execute` rows carry timestamps as driver strings.
+function toDate(value: unknown): Date {
+  return value instanceof Date ? value : new Date(String(value))
+}
+
+function toDateOrNull(value: unknown): Date | null {
+  return value === null || value === undefined ? null : toDate(value)
+}
+
+function rowToLink(row: Row): AccessLink {
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    code: row['code'] as string,
+    target: { type: row['target_type'] as string, id: row['target_id'] as string },
+    permissions: asStringArray(row['permissions']),
+    note: (row['note'] as string | null) ?? null,
+    createdBy: (row['created_by'] as string | null) ?? null,
+    createdAt: toDate(row['created_at']),
+    expiresAt: toDateOrNull(row['expires_at']),
+    maxUses: (row['max_uses'] as number | null) ?? null,
+    requireChecks: asStringArray(row['require_checks']),
+    checkData: row['check_data'] ?? null,
+    revokedAt: toDateOrNull(row['revoked_at']),
+    revokedBy: (row['revoked_by'] as string | null) ?? null,
+  }
+}
+
+function rowToPublic(row: Row): PublicLink {
+  const link = rowToLink(row)
+  return {
+    id: link.id,
+    target: link.target,
+    permissions: link.permissions,
+    note: link.note,
+    expiresAt: link.expiresAt,
+    maxUses: link.maxUses,
+    usesCompleted: Number(row['uses_completed'] ?? 0),
+    requireChecks: link.requireChecks,
+  }
+}
+
+function rowToUse(row: Row): AccessLinkUse {
+  return {
+    id: row['id'] as string,
+    linkId: row['link_id'] as string,
+    kind: row['kind'] as string,
+    status: row['status'] as AccessLinkUse['status'],
+    startedAt: toDate(row['started_at']),
+    reservedUntil: toDate(row['reserved_until']),
+    completedAt: toDateOrNull(row['completed_at']),
+    client: (row['client'] as string | null) ?? null,
+    location: (row['location'] as string | null) ?? null,
+    detail: (row['detail'] as Record<string, unknown> | null) ?? null,
+    claimedAt: toDateOrNull(row['claimed_at']),
+  }
+}
+
+function isUniqueViolation(err: unknown): boolean {
+  let current: unknown = err
+  for (let depth = 0; depth < 4 && typeof current === 'object' && current !== null; depth++) {
+    if ((current as { code?: unknown }).code === '23505') return true
+    current = (current as { cause?: unknown }).cause
+  }
+  return false
+}
+
+function splitToken(useToken: string): { code: string; useId: string } | null {
+  const dot = useToken.lastIndexOf('.')
+  if (dot <= 0 || dot === useToken.length - 1) return null
+  const useId = useToken.slice(dot + 1)
+  if (!/^[0-9a-f-]{36}$/i.test(useId)) return null
+  return { code: useToken.slice(0, dot), useId }
+}
+
+// A link row plus the state a use decision needs, all read with the database
+// clock. The caller that must serialize locks the row in its own statement first.
+function linkWithState(where: ReturnType<typeof sql>) {
+  return sql`
+    SELECT l.*,
+      (l.revoked_at IS NOT NULL) AS is_revoked,
+      (l.expires_at IS NOT NULL AND l.expires_at <= now()) AS is_expired,
+      (SELECT count(*)::int FROM access_link_use u WHERE u.link_id = l.id AND u.status = 'completed') AS uses_completed,
+      (SELECT count(*)::int FROM access_link_use u WHERE u.link_id = l.id
+         AND (u.status = 'completed' OR (u.status = 'pending' AND u.reserved_until > clock_timestamp()))) AS uses_held
+    FROM access_link l
+    WHERE ${where}
+  `
+}
+
+function stateOf(row: Row, mode: 'completed' | 'held'): LinkState | null {
+  if (row['is_revoked'] === true) return 'revoked'
+  if (row['is_expired'] === true) return 'expired'
+  const max = row['max_uses'] as number | null
+  const used = Number(mode === 'completed' ? row['uses_completed'] : row['uses_held'])
+  if (max !== null && used >= max) return 'exhausted'
+  return null
+}
+
+interface Grant {
+  readonly tenantId: string
+  readonly linkId: string
+}
+
+// The results `resolve` and `beginUse` handed out, by identity. `asLink` accepts
+// only these, so no caller can name a tenant by building an object.
+const grants = new WeakMap<object, Grant>()
+
+function issue<R extends object>(result: R, tenantId: string, linkId: string): R {
+  grants.set(result, { tenantId, linkId })
+  return result
+}
+
+export function createAccessLinks(config: AccessLinksConfig): AccessLinks {
+  const permissionSet = new Set(config.permissions)
+  if (permissionSet.size === 0) {
+    throw new Error('[pipework] accessLinks.create needs a non-empty `permissions` list.\n')
+  }
+  const generator = createCodeGenerator(config.code)
+  const checks = config.checks ?? {}
+  const reservationMs = config.reservationMs ?? DEFAULT_RESERVATION_MS
+  if (!Number.isFinite(reservationMs) || reservationMs <= 0) {
+    throw new Error('[pipework] accessLinks reservationMs must be a positive number of milliseconds.\n')
+  }
+  const rateConfig = config.resolveRateLimit === undefined ? DEFAULT_RATE_LIMIT : config.resolveRateLimit
+  if (rateConfig !== false) {
+    if (!Number.isInteger(rateConfig.max) || rateConfig.max <= 0) {
+      throw new Error('[pipework] accessLinks resolveRateLimit.max must be a positive integer.\n')
+    }
+    if (!Number.isFinite(rateConfig.windowMs) || rateConfig.windowMs <= 0) {
+      throw new Error('[pipework] accessLinks resolveRateLimit.windowMs must be a positive number of milliseconds.\n')
+    }
+  }
+  let lastMissCleanup = 0
+
+  function requireTenant(): { flow: Flow; tenantId: string } {
+    const flow = requireContext()
+    if (flow.tenant === null) {
+      throw new Error(
+        '[pipework] This accessLinks method needs a tenant in the Flow.\n\n' +
+        '  link/get/list/revoke/delete/uses manage one tenant\'s links. Call them from an authenticated\n' +
+        '  tenant route; resolve/beginUse/completeUse/abandonUse are the ones for public routes.\n',
+      )
+    }
+    return { flow, tenantId: flow.tenant }
+  }
+
+  function inTenant<T>(tenantId: string, fn: (tx: DB) => Promise<T>): Promise<T> {
+    return runAsTenant(requireContext(), tenantId, fn)
+  }
+
+  async function findTenant(code: string): Promise<string | null> {
+    const rows = await pipeSystem().execute(sql`SELECT tenant_id FROM access_link_code WHERE code = ${code}`)
+    return rows.length === 0 ? null : (rows[0]!['tenant_id'] as string)
+  }
+
+  // True when the client has used up its miss budget in the current window.
+  async function overBudget(client: string | null): Promise<boolean> {
+    if (rateConfig === false || client === null) return false
+    const rows = await pipeSystem().execute(sql`
+      SELECT count FROM access_link_miss
+      WHERE client = ${client} AND window_start > now() - ${rateConfig.windowMs}::float8 * interval '1 millisecond'`)
+    return rows.length > 0 && Number(rows[0]!['count']) >= rateConfig.max
+  }
+
+  // Counts one miss against the client; atomic per client, shared by every process.
+  async function recordMiss(client: string | null): Promise<void> {
+    if (rateConfig === false || client === null) return
+    const db = pipeSystem()
+    await db.execute(sql`
+      INSERT INTO access_link_miss AS m (client, count, window_start)
+      VALUES (${client}, 1, now())
+      ON CONFLICT (client) DO UPDATE SET
+        count = CASE WHEN m.window_start <= now() - ${rateConfig.windowMs}::float8 * interval '1 millisecond' THEN 1 ELSE m.count + 1 END,
+        window_start = CASE WHEN m.window_start <= now() - ${rateConfig.windowMs}::float8 * interval '1 millisecond' THEN now() ELSE m.window_start END`)
+    const now = Date.now()
+    if (now - lastMissCleanup < MISS_CLEANUP_EVERY_MS) return
+    lastMissCleanup = now
+    void Promise.resolve(db.execute(sql`
+      DELETE FROM access_link_miss WHERE window_start <= now() - ${rateConfig.windowMs}::float8 * interval '1 millisecond'`))
+      .catch((err: unknown) => getBaseLogger().error({ err }, 'accessLinks miss cleanup failed'))
+  }
+
+  async function missed(code: string, client: string | null): Promise<void> {
+    await recordMiss(client)
+    signalMiss(code, client)
+  }
+
+  function signalMiss(code: string, client: string | null): void {
+    getBaseLogger().warn({ event: 'access link resolve miss', client, codeLength: code.length }, 'access link resolve miss')
+    try {
+      config.onMiss?.({ client, code })
+    } catch (err) {
+      getBaseLogger().error({ err }, 'accessLinks onMiss callback threw')
+      void recordFault('access-link-on-miss', faultMessage(err))
+    }
+  }
+
+  function audit(flow: Flow, tx: DB, tenantId: string, verb: string, linkId: string, details: Record<string, unknown>): Promise<void> {
+    return writeInfraAudit(flow, tx, { tenantId, entity: 'AccessLink', verb, entityId: linkId, after: details })
+  }
+
+  function auditProjection(link: AccessLink): Record<string, unknown> {
+    return {
+      id: link.id, target: link.target, permissions: link.permissions, note: link.note,
+      createdBy: link.createdBy, expiresAt: link.expiresAt, maxUses: link.maxUses,
+      requireChecks: link.requireChecks, revokedAt: link.revokedAt, revokedBy: link.revokedBy,
+    }
+  }
+
+  async function newLink(options: LinkOptions): Promise<AccessLink> {
+    const { flow, tenantId } = requireTenant()
+    if (options.permissions.length === 0) {
+      throw new ValidationError({ permissions: ['must name at least one permission'] }, 'Access link needs at least one permission.')
+    }
+    const unknownPermissions = options.permissions.filter(p => !permissionSet.has(p))
+    if (unknownPermissions.length > 0) {
+      const detail = `not in the configured set (${[...permissionSet].join(', ')}): ${unknownPermissions.join(', ')}`
+      throw new ValidationError({ permissions: [detail] }, `Access link permissions ${detail}`)
+    }
+    const requireChecks = options.requireChecks ?? []
+    const unknownChecks = requireChecks.filter(c => checks[c] === undefined)
+    if (unknownChecks.length > 0) {
+      const detail = `no such check in accessLinks.create({ checks }): ${unknownChecks.join(', ')}`
+      throw new ValidationError({ requireChecks: [detail] }, `Access link requireChecks ${detail}`)
+    }
+    if (options.maxUses !== undefined && (!Number.isInteger(options.maxUses) || options.maxUses < 1)) {
+      throw new ValidationError({ maxUses: ['must be a positive integer'] }, 'Access link maxUses must be a positive integer.')
+    }
+
+    const id = randomUUID()
+    const createdBy = resolveActorId(flow)
+    const permissions = JSON.stringify([...new Set(options.permissions)])
+    const checkData = options.checkData === undefined ? null : JSON.stringify(options.checkData)
+
+    return pipe.transaction(async (tx: DB) => {
+      for (let attempt = 1; attempt <= MAX_CODE_ATTEMPTS; attempt++) {
+        const code = generator.next()
+        try {
+          // A savepoint per attempt: a collision aborts only the attempt.
+          return await tx.transaction(async (sp: DB) => {
+            await sp.execute(sql`
+              INSERT INTO access_link_code (code, tenant_id, link_id) VALUES (${code}, ${tenantId}, ${id})
+            `)
+            const rows = await sp.execute(sql`
+              INSERT INTO access_link
+                (id, tenant_id, code, target_type, target_id, permissions, note, created_by,
+                 expires_at, max_uses, require_checks, check_data)
+              VALUES (${id}, ${tenantId}, ${code}, ${options.target.type}, ${options.target.id},
+                ${permissions}::jsonb, ${options.note ?? null}, ${createdBy},
+                ${options.expiresAt?.toISOString() ?? null}, ${options.maxUses ?? null},
+                ${JSON.stringify(requireChecks)}::jsonb,
+                ${checkData === null ? sql`NULL` : sql`${checkData}::jsonb`})
+              RETURNING *
+            `)
+            const created = rowToLink(rows[0]!)
+            await audit(flow, sp, tenantId, 'create', created.id, auditProjection(created))
+            return created
+          })
+        } catch (err) {
+          if (!isUniqueViolation(err)) throw err
+        }
+      }
+      throw new Error(
+        `[pipework] accessLinks could not find a free code in ${MAX_CODE_ATTEMPTS} attempts.\n\n` +
+        `  Codes are ${generator.length} characters from an alphabet of ${generator.alphabet.length}; the space is\n` +
+        '  nearly full. Raise `code.length` or widen `code.alphabet`.\n',
+      )
+    })
+  }
+
+  // Locks the matching links first (serialising with beginUse), then removes uses, code and links.
+  async function deleteLinks(match: SQL): Promise<number> {
+    const { flow, tenantId } = requireTenant()
+    return pipe.transaction(async (tx: DB) => {
+      const found = await tx.execute(sql`
+        SELECT id FROM access_link WHERE tenant_id = ${tenantId} AND ${match} ORDER BY id FOR UPDATE
+      `)
+      if (found.length === 0) return 0
+      const ids = sql.inList(found.map(r => r['id'] as string), 'uuid')
+      const usesGone = await tx.execute(sql`
+        DELETE FROM access_link_use WHERE tenant_id = ${tenantId} AND link_id ${ids} RETURNING link_id
+      `)
+      const usesByLink = new Map<string, number>()
+      for (const u of usesGone) {
+        const k = u['link_id'] as string
+        usesByLink.set(k, (usesByLink.get(k) ?? 0) + 1)
+      }
+      await tx.execute(sql`DELETE FROM access_link_code WHERE tenant_id = ${tenantId} AND link_id ${ids}`)
+      const gone = await tx.execute(sql`
+        DELETE FROM access_link WHERE tenant_id = ${tenantId} AND id ${ids} RETURNING id, target_type, target_id
+      `)
+      for (const g of gone) {
+        const id = g['id'] as string
+        await audit(flow, tx, tenantId, 'delete', id, {
+          id,
+          target: { type: g['target_type'] as string, id: g['target_id'] as string },
+          usesDeleted: usesByLink.get(id) ?? 0,
+        })
+      }
+      return gone.length
+    })
+  }
+
+  const handle: AccessLinks = {
+    link: newLink,
+
+    async delete(id) {
+      return (await deleteLinks(sql`id = ${id}`)) > 0
+    },
+
+    async deleteForTarget(target) {
+      return deleteLinks(sql`target_type = ${target.type} AND target_id = ${target.id}`)
+    },
+
+    async get(id) {
+      const { tenantId } = requireTenant()
+      const rows = await pipeRaw().execute(sql`
+        SELECT * FROM access_link WHERE id = ${id} AND tenant_id = ${tenantId}
+      `)
+      return rows.length === 0 ? null : rowToLink(rows[0]!)
+    },
+
+    async list(options) {
+      const { tenantId } = requireTenant()
+      const target = options?.target
+      const rows = await pipeRaw().execute(sql`
+        SELECT * FROM access_link
+        WHERE tenant_id = ${tenantId}
+          ${target === undefined ? sql`` : sql`AND target_type = ${target.type} AND target_id = ${target.id}`}
+        ORDER BY created_at DESC, id
+      `)
+      return rows.map(rowToLink)
+    },
+
+    async listPage(options = {}) {
+      const { tenantId } = requireTenant()
+      const limit = options.limit ?? DEFAULT_LIST_LIMIT
+      if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIST_LIMIT) {
+        throw new ValidationError({ limit: [`must be an integer from 1 to ${MAX_LIST_LIMIT}`] }, 'Access link list limit is out of range.')
+      }
+      if (options.state !== undefined && !LIST_STATES.includes(options.state)) {
+        throw new ValidationError({ state: [`must be one of ${LIST_STATES.join(', ')}`] }, 'Access link list state is not valid.')
+      }
+      let cursor: { at: string; id: string } | null = null
+      if (options.cursor !== undefined) {
+        let parts: unknown[] = []
+        try { parts = decodeCursor(options.cursor) } catch { /* reported below */ }
+        if (parts.length !== 2 || typeof parts[0] !== 'string' || typeof parts[1] !== 'string'
+          || !/^[0-9a-f-]{36}$/i.test(parts[1]) || Number.isNaN(new Date(parts[0]).getTime())) {
+          throw new ValidationError('Invalid access link cursor: expected [createdAt, id]. Cursors are opaque — pass the value returned by listPage unchanged.')
+        }
+        cursor = { at: parts[0], id: parts[1] }
+      }
+      const { target, createdBy, state } = options
+      const rows = await pipeRaw().execute(sql`
+        SELECT * FROM (
+          SELECT s.*, s.created_at::text AS created_at_text,
+            CASE WHEN s.is_revoked THEN 'revoked'
+                 WHEN s.is_expired THEN 'expired'
+                 WHEN s.max_uses IS NOT NULL AND s.uses_completed >= s.max_uses THEN 'exhausted'
+                 ELSE 'active' END AS state
+          FROM (${linkWithState(sql`l.tenant_id = ${tenantId}`)}) s
+        ) p
+        WHERE true
+          ${target === undefined ? sql`` : sql`AND p.target_type = ${target.type} AND p.target_id = ${target.id}`}
+          ${createdBy === undefined ? sql`` : sql`AND p.created_by = ${createdBy}`}
+          ${state === undefined ? sql`` : sql`AND p.state = ${state}`}
+          ${cursor === null ? sql`` : sql`AND (p.created_at, p.id) < (${cursor.at}::timestamptz, ${cursor.id}::uuid)`}
+        ORDER BY p.created_at DESC, p.id DESC
+        LIMIT ${limit + 1}
+      `)
+      const page = rows.slice(0, limit)
+      const last = page[page.length - 1]
+      return {
+        items: page.map(row => ({
+          ...rowToLink(row),
+          usesCompleted: Number(row['uses_completed']),
+          state: row['state'] as AccessLinkListed['state'],
+        })),
+        nextCursor: rows.length > limit && last !== undefined
+          ? encodeCursor([last['created_at_text'] as string, last['id'] as string])
+          : null,
+      }
+    },
+
+    async revoke(id) {
+      const { flow, tenantId } = requireTenant()
+      const db = pipeRaw()
+      const rows = await db.execute(sql`
+        UPDATE access_link SET revoked_at = now(), revoked_by = ${resolveActorId(flow)}
+        WHERE id = ${id} AND tenant_id = ${tenantId} AND revoked_at IS NULL
+        RETURNING *
+      `)
+      if (rows.length > 0) {
+        const revoked = rowToLink(rows[0]!)
+        await audit(flow, db, tenantId, 'revoke', revoked.id, auditProjection(revoked))
+        return revoked
+      }
+      return handle.get(id)
+    },
+
+    async uses(linkId) {
+      const { tenantId } = requireTenant()
+      const rows = await pipeRaw().execute(sql`
+        SELECT * FROM access_link_use WHERE link_id = ${linkId} AND tenant_id = ${tenantId}
+        ORDER BY started_at, id
+      `)
+      return rows.map(rowToUse)
+    },
+
+    async resolve(code, options) {
+      const client = options?.client ?? null
+      if (await overBudget(client)) return { status: 'rate-limited' }
+
+      const tenantId = await findTenant(code)
+      const row = tenantId === null ? undefined : (await inTenant(tenantId, tx => tx.execute(
+        linkWithState(sql`l.code = ${code} AND l.tenant_id = ${tenantId}`),
+      )))[0]
+      if (tenantId === null || row === undefined) {
+        await missed(code, client)
+        return { status: 'not-found' }
+      }
+      const state = stateOf(row, 'completed')
+      if (state !== null) return { status: state }
+      const link = rowToPublic(row)
+      return issue({ status: 'active' as const, link, tenantId }, tenantId, link.id)
+    },
+
+    async beginUse(code, options) {
+      const client = options.client ?? null
+      // Same budget as resolve: beginUse takes a raw code too, so it is a guessing path.
+      if (await overBudget(client)) return { ok: false, reason: 'rate-limited' }
+      const tenantId = await findTenant(code)
+      if (tenantId === null) {
+        await missed(code, client)
+        return { ok: false, reason: 'not-found' }
+      }
+
+      // Read first, without a lock: refuse what is already decided and run the
+      // verifiers (which may be slow) before any row is held.
+      const first = (await inTenant(tenantId, tx => tx.execute(
+        linkWithState(sql`l.code = ${code} AND l.tenant_id = ${tenantId}`),
+      )))[0]
+      if (first === undefined) {
+        await missed(code, client)
+        return { ok: false, reason: 'not-found' }
+      }
+      const early = stateOf(first, 'held')
+      if (early !== null) return { ok: false, reason: early }
+      const link = rowToLink(first)
+      if (!link.permissions.includes(options.kind)) return { ok: false, reason: 'kind-not-permitted' }
+
+      for (const name of link.requireChecks) {
+        const verify = checks[name]
+        let passed = false
+        try {
+          passed = verify !== undefined && await verify({ link, proof: options.proof?.[name], client }) === true
+        } catch (err) {
+          getBaseLogger().warn({ err, check: name, linkId: link.id }, 'access link check threw; treated as failed')
+        }
+        if (!passed) return { ok: false, reason: 'check-failed' }
+      }
+
+      // Then decide under the link's row lock: concurrent begins queue here,
+      // and each counts the uses the one before it left. The lock and the count
+      // are separate statements: a count in the locking statement reads the
+      // snapshot taken before the wait, missing the use the holder committed.
+      return inTenant(tenantId, async (tx): Promise<BeginUseResult> => {
+        await tx.execute(sql`SELECT 1 FROM access_link WHERE id = ${link.id} AND tenant_id = ${tenantId} FOR UPDATE`)
+        const locked = (await tx.execute(
+          linkWithState(sql`l.id = ${link.id} AND l.tenant_id = ${tenantId}`),
+        ))[0]
+        if (locked === undefined) return { ok: false, reason: 'not-found' }
+        const state = stateOf(locked, 'held')
+        if (state !== null) return { ok: false, reason: state }
+
+        const useId = randomUUID()
+        await tx.execute(sql`
+          INSERT INTO access_link_use (id, tenant_id, link_id, kind, status, reserved_until, client, location, detail)
+          VALUES (${useId}, ${tenantId}, ${link.id}, ${options.kind}, 'pending',
+            clock_timestamp() + ${reservationMs} * interval '1 millisecond',
+            ${client}, ${options.location ?? null},
+            ${options.detail === undefined ? sql`NULL` : sql`${JSON.stringify(options.detail)}::jsonb`})
+        `)
+        return issue({ ok: true as const, useToken: `${code}.${useId}`, link: rowToPublic(locked) }, tenantId, link.id)
+      })
+    },
+
+    async completeUse(useToken, options) {
+      const flow = requireContext()
+      const parts = splitToken(useToken)
+      if (parts === null) return { ok: false, reason: 'not-found' }
+      const tenantId = await findTenant(parts.code)
+      if (tenantId === null) return { ok: false, reason: 'not-found' }
+
+      return inTenant(tenantId, async (tx): Promise<CompleteUseResult> => {
+        const rows = await tx.execute(sql`
+          SELECT u.id, u.link_id, u.kind, u.status,
+            (u.reserved_until > clock_timestamp()) AS reservation_live,
+            (l.expires_at IS NOT NULL AND l.expires_at <= now()) AS link_expired,
+            l.target_type, l.target_id
+          FROM access_link_use u JOIN access_link l ON l.id = u.link_id
+          WHERE u.id = ${parts.useId} AND l.code = ${parts.code} AND u.tenant_id = ${tenantId}
+          FOR UPDATE OF u
+        `)
+        const row = rows[0]
+        if (row === undefined) return { ok: false, reason: 'not-found' }
+        if (row['status'] !== 'pending') return { ok: false, reason: 'already-settled' }
+        if (row['reservation_live'] !== true || row['link_expired'] === true) {
+          return { ok: false, reason: 'expired-reservation' }
+        }
+        const detail = options?.detail
+        const settled = await tx.execute(sql`
+          UPDATE access_link_use SET status = 'completed', completed_at = now()
+            ${detail === undefined ? sql`` : sql`, detail = COALESCE(detail, '{}'::jsonb) || ${JSON.stringify(detail)}::jsonb`}
+          WHERE id = ${parts.useId}
+          RETURNING detail
+        `)
+        await audit(flow, tx, tenantId, 'use', String(row['link_id']), {
+          linkId: row['link_id'], useId: parts.useId, kind: row['kind'],
+          targetType: row['target_type'], targetId: row['target_id'],
+          ...(settled[0]?.['detail'] != null ? { detail: settled[0]['detail'] } : {}),
+        })
+        return { ok: true }
+      })
+    },
+
+    async abandonUse(useToken) {
+      const parts = splitToken(useToken)
+      if (parts === null) return { ok: false, reason: 'not-found' }
+      const tenantId = await findTenant(parts.code)
+      if (tenantId === null) return { ok: false, reason: 'not-found' }
+
+      return inTenant(tenantId, async (tx): Promise<AbandonUseResult> => {
+        const updated = await tx.execute(sql`
+          UPDATE access_link_use u SET status = 'abandoned'
+          FROM access_link l
+          WHERE u.id = ${parts.useId} AND l.id = u.link_id AND l.code = ${parts.code}
+            AND u.tenant_id = ${tenantId} AND u.status = 'pending'
+          RETURNING u.id
+        `)
+        if (updated.length > 0) return { ok: true }
+        const exists = await tx.execute(sql`
+          SELECT 1 FROM access_link_use u JOIN access_link l ON l.id = u.link_id
+          WHERE u.id = ${parts.useId} AND l.code = ${parts.code} AND u.tenant_id = ${tenantId}
+        `)
+        return { ok: false, reason: exists.length === 0 ? 'not-found' : 'already-settled' }
+      })
+    },
+
+    async claimUse(useToken) {
+      const parts = splitToken(useToken)
+      if (parts === null) return { ok: false, reason: 'not-found' }
+      const tenantId = await findTenant(parts.code)
+      if (tenantId === null) return { ok: false, reason: 'not-found' }
+
+      return inTenant(tenantId, async (tx): Promise<ClaimUseResult> => {
+        const claimed = await tx.execute(sql`
+          UPDATE access_link_use u SET claimed_at = now()
+          FROM access_link l
+          WHERE u.id = ${parts.useId} AND l.id = u.link_id AND l.code = ${parts.code}
+            AND u.tenant_id = ${tenantId} AND u.claimed_at IS NULL AND u.status = 'pending'
+            AND u.reserved_until > clock_timestamp()
+            AND NOT (l.expires_at IS NOT NULL AND l.expires_at <= now())
+          RETURNING l.id AS link_id
+        `)
+        if (claimed.length > 0) {
+          const row = (await tx.execute(
+            linkWithState(sql`l.id = ${claimed[0]!['link_id'] as string} AND l.tenant_id = ${tenantId}`),
+          ))[0]!
+          const link = rowToPublic(row)
+          return issue({ ok: true as const, link }, tenantId, link.id)
+        }
+        const rows = await tx.execute(sql`
+          SELECT u.status, (u.claimed_at IS NOT NULL) AS claimed
+          FROM access_link_use u JOIN access_link l ON l.id = u.link_id
+          WHERE u.id = ${parts.useId} AND l.code = ${parts.code} AND u.tenant_id = ${tenantId}
+        `)
+        const row = rows[0]
+        if (row === undefined) return { ok: false, reason: 'not-found' }
+        if (row['status'] !== 'pending') return { ok: false, reason: 'already-settled' }
+        if (row['claimed'] === true) return { ok: false, reason: 'already-claimed' }
+        return { ok: false, reason: 'expired-reservation' }
+      })
+    },
+
+    completeUseWhenSent(response, useToken, options) {
+      const flow = requireContext()
+      // The request's transaction is over when this runs: keep the instance and
+      // the trace, drop the bound transactions.
+      const detached: Flow = { ...flow, _nonce: randomUUID(), transactions: new Map() }
+      response.onFinish(async (outcome) => {
+        await runInContext(detached, async () => {
+          if (outcome === 'sent') await handle.completeUse(useToken, options)
+          else await handle.abandonUse(useToken)
+        })
+      })
+    },
+
+    async asLink(grant, fn) {
+      const issued = grants.get(grant)
+      if (issued === undefined) {
+        throw new Error(
+          '[pipework] accessLinks.asLink needs the result of resolve (status "active") or beginUse (ok) ' +
+          'exactly as this handle returned it.\n\n' +
+          '  A copied, rebuilt or refused result is not a grant. Check `status === "active"` / `ok` first.\n',
+        )
+      }
+      const flow = requireContext()
+      const dbName = flow.instance.config.defaultDatabaseName()
+      const auth = { userId: `link:${issued.linkId}`, accessLinkId: issued.linkId }
+      const childTrace = openChildTrace(flow, issued.tenantId, auth)
+      const child: Flow = {
+        ...flow,
+        _nonce: randomUUID(),
+        tenant: issued.tenantId,
+        user: null,
+        auth,
+        transactions: new Map(),
+        trace: childTrace,
+      }
+      // A NEW connection as the app role, with the link's tenant as its locals —
+      // the same transaction `pipe.transaction` opens, for the child's tenant.
+      const conn = flow.instance.pool.getOrCreate(flow.instance.config.database(dbName), 'app')
+      return finalizeTrace(flow.instance, childTrace, conn.drizzle.transaction(async (tx) => {
+        child.transactions.set(dbName, bindTransaction(child, dbName, tx))
+        await propagateLocals(tx, child, child.tenantConfig)
+        return runInContext(child, fn)
+      }))
+    },
+  }
+
+  return handle
+}