pipework 0.252.0 → 0.253.0

package/src/infra/alerts/subsystem-sources.ts

@@ -0,0 +1,137 @@
+// Sources over the failures pipework's own subsystems already record: outboxes that gave up, webhook deliveries,
+// credit settlements. Each is a composition of `querySource` and `newRowsSource`.
+
+import { sql } from '../../data/db/sql.js'
+import { assertValidIdentifier, quoteIdentifier } from '../../data/db/identifiers.js'
+import { DEFAULT_WEBHOOK_DELIVERY_TABLE } from '../webhook/outbound.js'
+import { common, positive, text, FIFTEEN_MIN, HOUR, type Basics } from './source-options.js'
+import { composeSources, newRowsSource, querySource, type AlertSource } from './sources.js'
+
+/**
+ * Raises `delivery-failed:<table>:<sink>` for outbox rows that gave up (`failed_at`) since the last tick, and
+ * `delivery-stuck:<table>:<sink>` while rows are still pending more than `stuckAfterMs` (default 15 min) past
+ * `next_attempt_at`. `tables` defaults to `['pipework_alert_deliveries']`; name `support_event_delivery` to add the support outbox.
+ * The failed condition clears by the handle's quiet period; the stuck one resolves when the rows drain.
+ */
+export function deliveryFailedSource(options: Basics & { tables?: readonly string[]; stuckAfterMs?: number; settleMs?: number } = {}): AlertSource {
+  const tables = [...new Set(options.tables ?? ['pipework_alert_deliveries'])]
+  if (tables.length === 0) throw new Error('[pipework] alerts.source.deliveryFailed tables must not be empty; omit it to watch the alert outbox.')
+  for (const t of tables) assertValidIdentifier(t, 'deliveryFailed table')
+  const stuckAfter = positive(options.stuckAfterMs ?? FIFTEEN_MIN, 'stuckAfterMs', 'alerts.source.deliveryFailed')
+  const failed = tables.map(table => newRowsSource({
+    ...common(options),
+    name: 'delivery-failed',
+    stateKey: `delivery-failed:${table}`,
+    table,
+    at: 'failed_at',
+    groupBy: sql.raw(`'${table}:' || t."sink"`),
+    ...(options.settleMs !== undefined ? { settleMs: options.settleMs } : {}),
+    message: g => `${String(g.count)} delivery(ies) to ${String(g.last['sink'])} gave up; last error: ${text(g.last['last_error'])}`,
+    subject: g => ({ entity: 'sink', entityId: String(g.last['sink']) }),
+    context: g => ({ table, sink: String(g.last['sink']), count: g.count, lastError: g.last['last_error'] === null ? null : String(g.last['last_error']) }),
+  }))
+  const pending = tables.map(table => `
+    SELECT '${table}' AS tbl, sink, count(*)::int AS n,
+           (extract(epoch FROM clock_timestamp() - min(next_attempt_at)) * 1000)::bigint AS oldest_ms
+    FROM ${quoteIdentifier(table, 'deliveryFailed table')}
+    WHERE delivered_at IS NULL AND failed_at IS NULL
+      AND next_attempt_at < clock_timestamp() - ${String(stuckAfter)} * interval '1 millisecond'
+    GROUP BY sink`).join(' UNION ALL ')
+  const stuck = querySource({
+    ...common(options),
+    name: 'delivery-stuck',
+    query: sql`SELECT * FROM (${sql.raw(pending)}) p ORDER BY tbl, sink`,
+    id: r => `${String(r['tbl'])}:${String(r['sink'])}`,
+    message: r => `${String(r['n'])} delivery(ies) to ${String(r['sink'])} pending more than ${String(stuckAfter)} ms past their retry time (oldest ${String(r['oldest_ms'])} ms)`,
+    subject: r => ({ entity: 'sink', entityId: String(r['sink']) }),
+    context: r => ({ table: String(r['tbl']), sink: String(r['sink']), count: Number(r['n']), oldestMs: Number(r['oldest_ms']) }),
+  })
+  return composeSources('delivery-failed', [...failed, stuck])
+}
+
+/**
+ * Raises `webhook-failed:<endpointId>` for outbound webhook deliveries that gave up (completed with no 2xx status)
+ * since the last tick, and `webhook-stalled:<endpointId>` while deliveries are more than `stalledAfterMs`
+ * (default 15 min) past their `next_retry_at`. `table` is the delivery table (default the outbound webhook's).
+ */
+export function webhookFailedSource(options: Basics & { table?: string; stalledAfterMs?: number; settleMs?: number } = {}): AlertSource {
+  const table = options.table ?? DEFAULT_WEBHOOK_DELIVERY_TABLE
+  assertValidIdentifier(table, 'webhookFailed table')
+  const stalledAfter = positive(options.stalledAfterMs ?? FIFTEEN_MIN, 'stalledAfterMs', 'alerts.source.webhookFailed')
+  const failed = newRowsSource({
+    ...common(options),
+    name: 'webhook-failed',
+    stateKey: `webhook-failed:${table}`,
+    table,
+    at: 'completed_at',
+    where: sql`(t.status_code IS NULL OR t.status_code < 200 OR t.status_code >= 300)`,
+    groupBy: 'endpoint_id',
+    ...(options.settleMs !== undefined ? { settleMs: options.settleMs } : {}),
+    message: g => `${String(g.count)} webhook delivery(ies) to endpoint ${g.id} gave up; last status ${text(g.last['status_code'])}`,
+    subject: g => ({ tenantId: String(g.last['tenant_id']), entity: 'webhook-endpoint', entityId: g.id }),
+    context: g => ({ endpointId: g.id, count: g.count, lastStatus: g.last['status_code'] === null ? null : Number(g.last['status_code']) }),
+  })
+  const stalled = querySource({
+    ...common(options),
+    name: 'webhook-stalled',
+    query: sql`
+      SELECT endpoint_id, count(*)::int AS n, (extract(epoch FROM clock_timestamp() - min(next_retry_at)) * 1000)::bigint AS oldest_ms
+      FROM ${sql.raw(quoteIdentifier(table, 'webhookFailed table'))}
+      WHERE completed_at IS NULL AND next_retry_at < clock_timestamp() - ${stalledAfter} * interval '1 millisecond'
+      GROUP BY endpoint_id ORDER BY endpoint_id`,
+    id: r => String(r['endpoint_id']),
+    message: r => `${String(r['n'])} webhook delivery(ies) to endpoint ${String(r['endpoint_id'])} more than ${String(stalledAfter)} ms past their retry time (oldest ${String(r['oldest_ms'])} ms)`,
+    subject: r => ({ entity: 'webhook-endpoint', entityId: String(r['endpoint_id']) }),
+    context: r => ({ endpointId: String(r['endpoint_id']), count: Number(r['n']), oldestMs: Number(r['oldest_ms']) }),
+  })
+  return composeSources('webhook-failed', [failed, stalled])
+}
+
+/**
+ * Raises `credit-overdraft:<tenantId>` for settlements that overdrew a tenant since the last tick,
+ * `credit-held:<tenantId>` while a reservation has been held longer than `heldOlderThanMs` (default 1 h), and
+ * `credit-expiry-undrained:all` while grants expired more than `expiryGraceMs` (default 1 h) ago still have credit left,
+ * which means nothing is running the credits expiry job.
+ */
+export function creditsSource(options: Basics & { heldOlderThanMs?: number; expiryGraceMs?: number; settleMs?: number } = {}): AlertSource {
+  const held = positive(options.heldOlderThanMs ?? HOUR, 'heldOlderThanMs', 'alerts.source.credits')
+  const grace = positive(options.expiryGraceMs ?? HOUR, 'expiryGraceMs', 'alerts.source.credits')
+  const overdraft = newRowsSource({
+    ...common(options),
+    name: 'credit-overdraft',
+    table: 'credit_reservation',
+    at: 'settled_at',
+    where: sql`t.overdraft > 0`,
+    groupBy: 'tenant_id',
+    sum: 'overdraft',
+    ...(options.settleMs !== undefined ? { settleMs: options.settleMs } : {}),
+    message: g => `${String(g.count)} settlement(s) overdrew ${g.id} by ${String(g.sum)}`,
+    subject: g => ({ tenantId: g.id }),
+    context: g => ({ count: g.count, overdraft: g.sum }),
+  })
+  const stale = querySource({
+    ...common(options),
+    name: 'credit-held',
+    query: sql`
+      SELECT tenant_id, count(*)::int AS n, (extract(epoch FROM clock_timestamp() - min(created_at)) * 1000)::bigint AS oldest_ms
+      FROM credit_reservation
+      WHERE status = 'held' AND created_at < clock_timestamp() - ${held} * interval '1 millisecond'
+      GROUP BY tenant_id ORDER BY tenant_id`,
+    id: r => String(r['tenant_id']),
+    message: r => `${String(r['n'])} credit hold(s) for ${String(r['tenant_id'])} older than ${String(held)} ms (oldest ${String(r['oldest_ms'])} ms)`,
+    subject: r => ({ tenantId: String(r['tenant_id']) }),
+    context: r => ({ count: Number(r['n']), oldestMs: Number(r['oldest_ms']) }),
+  })
+  const expiry = querySource({
+    ...common(options),
+    name: 'credit-expiry-undrained',
+    query: sql`
+      SELECT count(*)::int AS n FROM credit_grant
+      WHERE remaining > 0 AND expires_at <= clock_timestamp() - ${grace} * interval '1 millisecond'
+      HAVING count(*) > 0`,
+    id: () => 'all',
+    message: r => `${String(r['n'])} expired grant(s) not drained; is the credits expiry job scheduled?`,
+    context: r => ({ count: Number(r['n']) }),
+  })
+  return composeSources('credits', [overdraft, stale, expiry])
+}

package/src/infra/audit/emit.ts

@@ -0,0 +1,87 @@
+import { sql } from '../../data/db/sql.js'
+import type { AuditConfig, AuditEmitOptions, Audit } from './types.js'
+import { getContext } from '../../request/context/store.js'
+import { assertValidIdentifier, quoteIdentifier } from '../../data/db/identifiers.js'
+
+export function createAudit(config: AuditConfig): Audit {
+  const table = config.table ?? 'pipework_audit_events'
+  assertValidIdentifier(table, 'audit table')
+
+  return {
+    async emit(options: AuditEmitOptions): Promise<string> {
+      const ctx = getContext()
+      if (!ctx) {
+        throw new Error(
+          '[pipework] audit.emit() called outside a managed context. ' +
+          'It must run inside a request handler or job.',
+        )
+      }
+
+      if (ctx.tenant === null) {
+        throw new Error(
+          '[pipework] audit.emit() requires tenant context. ' +
+          'Configure tenant extraction in createServer().',
+        )
+      }
+
+      if (ctx.auth === null) {
+        throw new Error(
+          '[pipework] audit.emit() requires authenticated context. ' +
+          'Ensure the handler uses .auth() or the route is not .public().',
+        )
+      }
+
+      const userId = extractUserId(ctx.auth)
+      if (userId === null) {
+        throw new Error(
+          '[pipework] audit.emit() requires auth.userId. ' +
+          'Ensure the auth object has a userId field.',
+        )
+      }
+
+      const bound = ctx.transactions.get(config.database)
+      if (!bound) {
+        throw new Error(
+          `[pipework] audit.emit() requires an active transaction on database "${config.database}". ` +
+          `Configure transactionPerRequest: ['${config.database}'] in createServer().`,
+        )
+      }
+      const tx = bound.drizzle
+
+      const sessionId = config.sessionIdField !== undefined && typeof ctx.auth === 'object'
+        ? (ctx.auth as Record<string, unknown>)[config.sessionIdField] as string | null ?? null
+        : null
+
+      const beforeJson = options.before !== undefined ? JSON.stringify(options.before) : null
+      const afterJson = options.after !== undefined ? JSON.stringify(options.after) : null
+      const metadataJson = options.metadata !== undefined ? JSON.stringify(options.metadata) : null
+
+      const result = await tx.execute(sql`
+        INSERT INTO ${sql.raw(quoteIdentifier(table, 'audit table'))} (tenant_id, request_id, user_id, session_id, action_type, entity_type, entity_id, before_state, after_state, metadata)
+        VALUES (
+          ${ctx.tenant},
+          ${ctx.requestId},
+          ${userId},
+          ${sessionId ?? null},
+          ${options.actionType},
+          ${options.entityType ?? null},
+          ${options.entityId ?? null},
+          ${beforeJson !== null ? sql`${beforeJson}::jsonb` : sql`NULL`},
+          ${afterJson !== null ? sql`${afterJson}::jsonb` : sql`NULL`},
+          ${metadataJson !== null ? sql`${metadataJson}::jsonb` : sql`NULL`}
+        )
+        RETURNING id::text
+      `)
+
+      return (result[0] as { id: string }).id
+    },
+  }
+}
+
+function extractUserId(auth: unknown): string | null {
+  if (auth !== null && auth !== undefined && typeof auth === 'object' && 'userId' in auth) {
+    const val = (auth as { userId: unknown }).userId
+    return typeof val === 'string' ? val : null
+  }
+  return null
+}

package/src/infra/audit/index.ts

@@ -0,0 +1,2 @@
+export type { AuditConfig, AuditEmitOptions, Audit } from './types.js'
+export { createAudit } from './emit.js'

package/src/infra/audit/namespace.ts

@@ -0,0 +1,22 @@
+import { createAudit } from './index.js'
+import { query } from '../../audit/query/index.js'
+import { auditEntityId } from '../../data/write/audit/primary-key.js'
+import { chainHead, verify, removeTenant } from '../../audit/chain/index.js'
+
+/** Audit logging namespace — structured audit trail for data changes. */
+export const audit = {
+  /** Creates an Audit instance that writes audit records to a Postgres table. */
+  create: createAudit,
+  /** Queries the framework-managed `audit_record` table. Tenant-scoped via the active Flow. `{ entity, entityId }` returns one row's history from an index; build a composite key's `entityId` with `audit.entityId`. */
+  query,
+  /**
+   * The `entityId` filter text for a written table's row: the primary key's value as text, or for a composite key a compact JSON array of the key values as strings in key order (`["a","7"]`). Pass the table and a row (or just its key fields). Dates become ISO strings.
+   */
+  entityId: auditEntityId,
+  /** The newest record's `{ seq, hash }` in the tenant's audit hash chain (blueprint `audit.chain`), to store outside the database; `null` when empty. */
+  chainHead,
+  /** Walks the tenant's audit hash chain and reports the first break (hash-mismatch, prev-mismatch, missing, head-mismatch, anchor-mismatch), or `{ ok: true }`. */
+  verify,
+  /** Deletes every audit record of one tenant and its hash chain, for the closure of that tenant's account. Irreversible; returns the number of records removed. Other tenants' records and chains are untouched. */
+  removeTenant,
+}

package/src/infra/audit/schema.sql

@@ -0,0 +1,35 @@
+CREATE TABLE IF NOT EXISTS pipework_audit_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id text NOT NULL,
+  request_id text NOT NULL,
+  user_id text NOT NULL,
+  session_id text,
+  action_type text NOT NULL,
+  entity_type text,
+  entity_id text,
+  before_state jsonb,
+  after_state jsonb,
+  metadata jsonb,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_tenant_action ON pipework_audit_events (tenant_id, action_type, created_at);
+CREATE INDEX IF NOT EXISTS idx_audit_tenant_entity ON pipework_audit_events (tenant_id, entity_type, entity_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_audit_tenant_user ON pipework_audit_events (tenant_id, user_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_audit_tenant_request ON pipework_audit_events (tenant_id, request_id);
+
+CREATE OR REPLACE FUNCTION pipework_audit_immutable() RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION 'pipework_audit_events is append-only: UPDATE and DELETE are not permitted';
+END;
+$$ LANGUAGE plpgsql;
+
+DO $$ BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_trigger WHERE tgname = 'pipework_audit_no_modify'
+  ) THEN
+    CREATE TRIGGER pipework_audit_no_modify
+      BEFORE UPDATE OR DELETE ON pipework_audit_events
+      FOR EACH ROW EXECUTE FUNCTION pipework_audit_immutable();
+  END IF;
+END $$;

package/src/infra/audit/types.ts

@@ -0,0 +1,18 @@
+export interface AuditConfig {
+  readonly database: string
+  readonly table?: string
+  readonly sessionIdField?: string
+}
+
+export interface AuditEmitOptions {
+  readonly actionType: string
+  readonly entityType?: string
+  readonly entityId?: string
+  readonly before?: unknown
+  readonly after?: unknown
+  readonly metadata?: Record<string, unknown>
+}
+
+export interface Audit {
+  emit(options: AuditEmitOptions): Promise<string>
+}

package/src/infra/aws/credentials.ts

@@ -0,0 +1,147 @@
+import { readFile as fsReadFile } from 'node:fs/promises'
+import { readAwsEnv, type AwsEnv } from '../../core/config/aws-env.js'
+import type { AwsCredentials } from './sigv4.js'
+
+export interface AwsCredentialsOptions {
+  /** For tests: where the AWS variables come from. Default: the process environment. */
+  readonly env?: () => AwsEnv
+  /** For tests: replaces global `fetch`. */
+  readonly fetch?: typeof fetch
+  /** For tests: the clock, in epoch milliseconds. */
+  readonly now?: () => number
+  /** For tests: reads AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE. */
+  readonly readFile?: (path: string) => Promise<string>
+}
+
+const REFRESH_BEFORE_MS = 5 * 60 * 1000
+const ECS_HOST = 'http://169.254.170.2'
+const IMDS_HOST = 'http://169.254.169.254'
+const IMDS_TIMEOUT_MS = 1000
+const CONTAINER_TIMEOUT_MS = 2000
+
+interface Cached { readonly credentials: AwsCredentials; readonly expiresAt: number }
+
+/**
+ * Default AWS credential provider: environment keys, then the ECS container
+ * endpoint, then EC2 instance metadata (IMDSv2). Container and IMDS credentials
+ * are cached until five minutes before `Expiration`. Profiles and SSO are not read.
+ * `storage.s3` and `mail.ses` use it when `credentials` is omitted.
+ */
+export function awsCredentials(options: AwsCredentialsOptions = {}): () => Promise<AwsCredentials> {
+  const env = options.env ?? readAwsEnv
+  const doFetch = options.fetch ?? fetch
+  const now = options.now ?? Date.now
+  const readFile = options.readFile ?? ((path: string) => fsReadFile(path, 'utf8'))
+  let cached: Cached | undefined
+  let inflight: Promise<Cached> | undefined
+
+  async function fetchJson(url: string, init: RequestInit, timeoutMs: number, what: string): Promise<Record<string, unknown>> {
+    let res: Response
+    try {
+      res = await doFetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) })
+    } catch (err) {
+      throw new Error(`[pipework] ${what} at ${url} could not be reached: ${err instanceof Error ? err.message : String(err)}`)
+    }
+    if (!res.ok) throw new Error(`[pipework] ${what} at ${url} answered HTTP ${res.status}`)
+    const raw = await res.text()
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      if (typeof parsed !== 'object' || parsed === null) throw new Error('not an object')
+      return parsed as Record<string, unknown>
+    } catch {
+      throw new Error(`[pipework] ${what} at ${url} answered HTTP ${res.status} with malformed JSON`)
+    }
+  }
+
+  function parse(body: Record<string, unknown>, url: string, what: string): Cached {
+    const id = body['AccessKeyId']
+    const secret = body['SecretAccessKey']
+    const token = body['Token']
+    const expiration = body['Expiration']
+    const expiresAt = typeof expiration === 'string' ? Date.parse(expiration) : NaN
+    if (typeof id !== 'string' || typeof secret !== 'string' || Number.isNaN(expiresAt)) {
+      throw new Error(`[pipework] ${what} at ${url} answered HTTP 200 without AccessKeyId, SecretAccessKey and Expiration`)
+    }
+    return {
+      credentials: { accessKeyId: id, secretAccessKey: secret, ...(typeof token === 'string' ? { sessionToken: token } : {}) },
+      expiresAt,
+    }
+  }
+
+  async function fromContainer(e: AwsEnv): Promise<Cached> {
+    const rel = e.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
+    const url = rel !== undefined ? `${ECS_HOST}${rel}` : e.AWS_CONTAINER_CREDENTIALS_FULL_URI!
+    let token = e.AWS_CONTAINER_AUTHORIZATION_TOKEN
+    if (e.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE !== undefined) {
+      token = (await readFile(e.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE)).trim()
+    }
+    const headers: Record<string, string> = token !== undefined ? { Authorization: token } : {}
+    const what = 'the ECS container credentials endpoint'
+    return parse(await fetchJson(url, { method: 'GET', headers }, CONTAINER_TIMEOUT_MS, what), url, what)
+  }
+
+  async function fromImds(): Promise<Cached> {
+    const tokenRes = await doFetch(`${IMDS_HOST}/latest/api/token`, {
+      method: 'PUT',
+      headers: { 'X-aws-ec2-metadata-token-ttl-seconds': '21600' },
+      signal: AbortSignal.timeout(IMDS_TIMEOUT_MS),
+    })
+    if (!tokenRes.ok) throw new Error(`token request answered HTTP ${tokenRes.status}`)
+    const token = (await tokenRes.text()).trim()
+    const headers = { 'X-aws-ec2-metadata-token': token }
+    const listUrl = `${IMDS_HOST}/latest/meta-data/iam/security-credentials/`
+    const listRes = await doFetch(listUrl, { method: 'GET', headers, signal: AbortSignal.timeout(IMDS_TIMEOUT_MS) })
+    if (!listRes.ok) throw new Error(`role lookup at ${listUrl} answered HTTP ${listRes.status}`)
+    const role = (await listRes.text()).split(/\r?\n/)[0]!.trim()
+    if (role === '') throw new Error(`no instance role attached (${listUrl} was empty)`)
+    const url = `${listUrl}${role}`
+    return parse(await fetchJson(url, { method: 'GET', headers }, IMDS_TIMEOUT_MS, 'EC2 instance metadata'), url, 'EC2 instance metadata')
+  }
+
+  async function resolve(): Promise<Cached> {
+    const e = env()
+    if (e.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI !== undefined || e.AWS_CONTAINER_CREDENTIALS_FULL_URI !== undefined) {
+      return fromContainer(e)
+    }
+    let imds: string
+    if (e.AWS_EC2_METADATA_DISABLED?.toLowerCase() === 'true') {
+      imds = 'disabled (AWS_EC2_METADATA_DISABLED=true)'
+    } else {
+      try {
+        return await fromImds()
+      } catch (err) {
+        imds = `failed (${err instanceof Error ? err.message : String(err)})`
+      }
+    }
+    throw new Error(
+      '[pipework] No AWS credentials found. Looked at:\n' +
+      '  - environment: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (AWS_SESSION_TOKEN optional), not set\n' +
+      '  - container endpoint: AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_CREDENTIALS_FULL_URI, not set\n' +
+      `  - EC2 instance metadata (IMDSv2): ${imds}`,
+    )
+  }
+
+  return async () => {
+    const e = env()
+    const id = e.AWS_ACCESS_KEY_ID
+    const secret = e.AWS_SECRET_ACCESS_KEY
+    if (id !== undefined || secret !== undefined) {
+      if (id === undefined) throw new Error('[pipework] AWS_SECRET_ACCESS_KEY is set but AWS_ACCESS_KEY_ID is missing.')
+      if (secret === undefined) throw new Error('[pipework] AWS_ACCESS_KEY_ID is set but AWS_SECRET_ACCESS_KEY is missing.')
+      return { accessKeyId: id, secretAccessKey: secret, ...(e.AWS_SESSION_TOKEN !== undefined ? { sessionToken: e.AWS_SESSION_TOKEN } : {}) }
+    }
+    if (cached !== undefined && now() < cached.expiresAt - REFRESH_BEFORE_MS) return cached.credentials
+    if (inflight === undefined) {
+      inflight = resolve().then(
+        (c) => { cached = c; inflight = undefined; return c },
+        (err: unknown) => { inflight = undefined; throw err },
+      )
+    }
+    try {
+      return (await inflight).credentials
+    } catch (err) {
+      if (cached !== undefined && now() < cached.expiresAt) return cached.credentials
+      throw err
+    }
+  }
+}

package/src/infra/aws/sigv4.ts

@@ -0,0 +1,140 @@
+import { createHash, createHmac } from 'node:crypto'
+
+export interface AwsCredentials {
+  readonly accessKeyId: string
+  readonly secretAccessKey: string
+  readonly sessionToken?: string
+}
+
+export interface SigV4Request {
+  readonly method: string
+  readonly url: string
+  /** Headers to sign and send, other than host and x-amz-date, which are added. */
+  readonly headers: Readonly<Record<string, string>>
+  readonly body: string | Buffer
+  /**
+   * The hex SHA-256 of the body, or `UNSIGNED-PAYLOAD`, used in place of hashing `body`.
+   * For a streamed S3 body; the caller also sends and signs `x-amz-content-sha256`.
+   */
+  readonly payloadHash?: string
+  readonly region: string
+  readonly service: string
+  readonly credentials: AwsCredentials
+  readonly now?: Date
+}
+
+function sha256Hex(data: string | Buffer): string {
+  return createHash('sha256').update(data).digest('hex')
+}
+
+function hmac(key: string | Buffer, data: string): Buffer {
+  return createHmac('sha256', key).update(data).digest()
+}
+
+function uriEncode(s: string): string {
+  return encodeURIComponent(s).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+}
+
+function canonicalPathOf(url: URL, service: string): string {
+  // S3 encodes each path segment once; every other service encodes the already-encoded path again.
+  if (service === 's3') return url.pathname.split('/').map(seg => uriEncode(decodeURIComponent(seg))).join('/')
+  return url.pathname.split('/').map(uriEncode).join('/')
+}
+
+function canonicalQueryOf(params: Iterable<readonly [string, string]>): string {
+  return [...params]
+    .map(([k, v]) => [uriEncode(k), uriEncode(v)] as const)
+    .sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : (a[0] < b[0] ? -1 : 1)))
+    .map(([k, v]) => `${k}=${v}`)
+    .join('&')
+}
+
+function signingKey(secret: string, day: string, region: string, service: string): Buffer {
+  return hmac(hmac(hmac(hmac(`AWS4${secret}`, day), region), service), 'aws4_request')
+}
+
+function amzDate(d: Date): string {
+  return d.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '')
+}
+
+/**
+ * Signs a request with AWS Signature Version 4 and returns the headers to send:
+ * the given ones, `x-amz-date`, `x-amz-security-token` when the credentials carry
+ * a session token, and `authorization`. `host` is signed but not returned; the
+ * HTTP client sets it from the URL.
+ */
+export function signV4(req: SigV4Request): Record<string, string> {
+  const url = new URL(req.url)
+  const stamp = amzDate(req.now ?? new Date())
+  const day = stamp.slice(0, 8)
+
+  const headers: Record<string, string> = {}
+  for (const [name, value] of Object.entries(req.headers)) headers[name.toLowerCase()] = value.trim().replace(/\s+/g, ' ')
+  headers['x-amz-date'] = stamp
+  if (req.credentials.sessionToken !== undefined) headers['x-amz-security-token'] = req.credentials.sessionToken
+
+  const signed: Record<string, string> = { ...headers, host: url.host }
+  const names = Object.keys(signed).sort()
+  const canonicalHeaders = names.map(n => `${n}:${signed[n]!}\n`).join('')
+  const signedHeaders = names.join(';')
+
+  const canonicalRequest = [
+    req.method.toUpperCase(), canonicalPathOf(url, req.service), canonicalQueryOf(url.searchParams.entries()),
+    canonicalHeaders, signedHeaders, req.payloadHash ?? sha256Hex(req.body),
+  ].join('\n')
+
+  const scope = `${day}/${req.region}/${req.service}/aws4_request`
+  const stringToSign = ['AWS4-HMAC-SHA256', stamp, scope, sha256Hex(canonicalRequest)].join('\n')
+  const signature = createHmac('sha256', signingKey(req.credentials.secretAccessKey, day, req.region, req.service))
+    .update(stringToSign).digest('hex')
+
+  return {
+    ...headers,
+    authorization:
+      `AWS4-HMAC-SHA256 Credential=${req.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+  }
+}
+
+export interface PresignRequest {
+  readonly method: string
+  /** The full URL, query included (e.g. `response-content-disposition`); it is signed with the rest. */
+  readonly url: string
+  readonly region: string
+  readonly service: string
+  readonly credentials: AwsCredentials
+  /** 1 to 604800 (seven days). */
+  readonly expiresInSeconds: number
+  readonly now?: Date
+}
+
+/**
+ * Returns `url` with SigV4 query-string signing added (`X-Amz-Algorithm`, `-Credential`, `-Date`,
+ * `-Expires`, `-SignedHeaders=host`, `-Security-Token` for a session token, `-Signature`), so a client
+ * with no credentials can make the one request until it expires. The payload is `UNSIGNED-PAYLOAD`.
+ */
+export function presignV4(req: PresignRequest): string {
+  if (!Number.isInteger(req.expiresInSeconds) || req.expiresInSeconds < 1 || req.expiresInSeconds > 604800) {
+    throw new Error('[pipework] presigned URL expiry must be an integer from 1 to 604800 seconds.')
+  }
+  const url = new URL(req.url)
+  const stamp = amzDate(req.now ?? new Date())
+  const day = stamp.slice(0, 8)
+  const scope = `${day}/${req.region}/${req.service}/aws4_request`
+  url.searchParams.set('X-Amz-Algorithm', 'AWS4-HMAC-SHA256')
+  url.searchParams.set('X-Amz-Credential', `${req.credentials.accessKeyId}/${scope}`)
+  url.searchParams.set('X-Amz-Date', stamp)
+  url.searchParams.set('X-Amz-Expires', String(req.expiresInSeconds))
+  url.searchParams.set('X-Amz-SignedHeaders', 'host')
+  if (req.credentials.sessionToken !== undefined) url.searchParams.set('X-Amz-Security-Token', req.credentials.sessionToken)
+
+  const canonicalRequest = [
+    req.method.toUpperCase(), canonicalPathOf(url, req.service), canonicalQueryOf(url.searchParams.entries()),
+    `host:${url.host}\n`, 'host', 'UNSIGNED-PAYLOAD',
+  ].join('\n')
+  const stringToSign = ['AWS4-HMAC-SHA256', stamp, scope, sha256Hex(canonicalRequest)].join('\n')
+  const signature = createHmac('sha256', signingKey(req.credentials.secretAccessKey, day, req.region, req.service))
+    .update(stringToSign).digest('hex')
+  // Keep the query exactly as signed: rebuild it with the same encoding the canonical form used.
+  const query = canonicalQueryOf(url.searchParams.entries())
+  return `${url.origin}${url.pathname}?${query}&X-Amz-Signature=${signature}`
+}

package/src/infra/cache/create.ts

@@ -0,0 +1,58 @@
+import { getContext } from '../../request/context/store.js'
+import type { CacheConfig, Cache, CacheStats } from './types.js'
+import { loadWithDb, createEmptyEntry, isExpired, getOrLoad, preloadEntry, type CacheEntryState } from './entry.js'
+
+export function createCache<T>(config: CacheConfig<T>): Cache<T> {
+  const entry = createEmptyEntry<T>()
+  let lastLoadAt: number | null = null
+  let lastLoadDurationMs: number | null = null
+
+  async function doLoad(e: CacheEntryState<T>): Promise<T> {
+    const start = Date.now()
+    const result = await loadWithDb(config.database, config.name, getContext()?.tenant ?? null, db => config.load(db))
+    lastLoadDurationMs = Date.now() - start
+    lastLoadAt = Date.now()
+    e.loadedAt = Date.now()
+    e.data = result
+    e.loadPromise = null
+    return result
+  }
+
+  return {
+    async get(): Promise<T> {
+      return getOrLoad(entry, config.ttlMs, doLoad)
+    },
+
+    invalidate(): void {
+      entry.data = undefined
+      entry.loadedAt = null
+      entry.loadPromise = null
+    },
+
+    stats(): CacheStats {
+      let status: CacheStats['status']
+      if (entry.loadPromise !== null) {
+        status = 'loading'
+      } else if (entry.data === undefined) {
+        status = 'empty'
+      } else if (isExpired(entry, config.ttlMs)) {
+        status = 'stale'
+      } else {
+        status = 'loaded'
+      }
+
+      return {
+        name: config.name,
+        status,
+        hits: entry.hits,
+        misses: entry.misses,
+        lastLoadAt,
+        lastLoadDurationMs,
+      }
+    },
+
+    async preload(): Promise<void> {
+      return preloadEntry(entry, config.ttlMs, doLoad)
+    },
+  }
+}