pipework 0.251.0 → 0.252.1

package/src/auth/auth/chain.ts

@@ -0,0 +1,84 @@
+import type { AuthStrategy, AuthRequest, AuthContext } from './types.js'
+import { UnauthorizedError, isPipeworkError } from '../../core/errors/index.js'
+
+/** Post-authentication hook — enrich the resolved auth with additional data (roles, permissions, etc.). */
+export interface AuthEnricher<TAuth> {
+  readonly name: string
+  enrich(auth: TAuth): Promise<TAuth>
+}
+
+/** Resolves tenant ID from auth context — called after authentication in the chain. */
+export interface TenantResolver<TAuth> {
+  resolve(auth: TAuth): string
+}
+
+/** Configuration for the auth chain — strategies, enrichers, tenant resolver. */
+export interface AuthChainConfig<TAuth> {
+  readonly strategies: readonly AuthStrategy<TAuth>[]
+  readonly enrichers?: readonly AuthEnricher<TAuth>[]
+  readonly tenantResolver?: TenantResolver<TAuth>
+}
+
+/** Result of running the auth chain — resolved auth and tenant (both nullable for public routes). */
+export interface AuthChainResult<TAuth> {
+  readonly auth: TAuth | null
+  readonly tenant: string | null
+}
+
+/** Executes the auth chain: tries strategies in order, enriches, resolves tenant. */
+export async function runAuthChain<TAuth>(
+  config: AuthChainConfig<TAuth>,
+  request: AuthRequest,
+  options: { optional: boolean },
+  context: AuthContext,
+): Promise<AuthChainResult<TAuth>> {
+  let extracted: TAuth | null = null
+  let matchedStrategy: AuthStrategy<TAuth> | null = null
+
+  for (const strategy of config.strategies) {
+    extracted = await strategy.extract(request, context)
+    if (extracted !== null) {
+      matchedStrategy = strategy
+      break
+    }
+  }
+
+  if (extracted === null) {
+    if (options.optional) return { auth: null, tenant: null }
+    throw new UnauthorizedError()
+  }
+
+  let auth: TAuth
+  try {
+    auth = await matchedStrategy!.verify(extracted, context)
+  } catch (error) {
+    // A PipeworkError from verify reaches the caller unchanged: UNAUTHORIZED is a refused credential
+    // (signed out on an optional route), FORBIDDEN and any other code (a 5xx from the strategy's own
+    // configuration) are not. Only a plain Error, such as a third-party strategy's, becomes a 401
+    // 'Authentication failed' without its detail.
+    if (isPipeworkError(error) && error.code === 'UNAUTHORIZED' && options.optional) return { auth: null, tenant: null }
+    if (isPipeworkError(error)) throw error
+    throw new UnauthorizedError('Authentication failed', {
+      strategy: matchedStrategy!.name,
+      cause: error instanceof Error ? error.message : String(error),
+    })
+  }
+
+  if (config.enrichers) {
+    for (const enricher of config.enrichers) {
+      auth = await enricher.enrich(auth)
+    }
+  }
+
+  const tenant = config.tenantResolver ? config.tenantResolver.resolve(auth) : extractTenant(auth)
+
+  return { auth, tenant }
+}
+
+function extractTenant(auth: unknown): string | null {
+  if (auth !== null && typeof auth === 'object' && 'tenantId' in auth) {
+    const tenantId = (auth as { tenantId: unknown }).tenantId
+    if (typeof tenantId === 'string') return tenantId
+  }
+  return null
+}

package/src/auth/auth/cookie.ts

@@ -0,0 +1,136 @@
+import { CrossSiteRequestError } from '../../core/errors/index.js'
+
+/** Cookie configuration for token delivery — name, domain, path, secure, sameSite, httpOnly. */
+export interface CookieConfig {
+  readonly name?: string
+  readonly secure?: 'auto' | boolean
+  readonly sameSite?: 'strict' | 'lax' | 'none'
+  readonly path?: string
+}
+
+/** CookieConfig with all defaults resolved — every field is required. */
+export interface ResolvedCookieConfig {
+  readonly name: string
+  readonly secure: boolean
+  readonly sameSite: string
+  readonly path: string
+  readonly httpOnly: true
+}
+
+/** Resolves a partial CookieConfig into a ResolvedCookieConfig with secure defaults. */
+export function resolveCookieConfig(
+  cookie: CookieConfig,
+  env: string,
+  defaults: { readonly name: string; readonly sameSite: 'strict' | 'lax' | 'none' } = { name: '__pipework_refresh', sameSite: 'strict' },
+): ResolvedCookieConfig {
+  const secure = cookie.secure === 'auto' || cookie.secure === undefined
+    ? env === 'production'
+    : cookie.secure
+
+  return {
+    name: cookie.name ?? defaults.name,
+    secure,
+    sameSite: cookie.sameSite ?? defaults.sameSite,
+    path: cookie.path ?? '/',
+    httpOnly: true,
+  }
+}
+
+/** Builds a Set-Cookie header string from name, value, and resolved config. */
+export function buildSetCookieHeader(resolved: ResolvedCookieConfig, value: string, maxAge: number): string {
+  const parts = [
+    `${resolved.name}=${encodeURIComponent(value)}`,
+    `HttpOnly`,
+    `Path=${resolved.path}`,
+    `Max-Age=${maxAge}`,
+    `SameSite=${capitalize(resolved.sameSite)}`,
+  ]
+  if (resolved.secure) parts.push('Secure')
+  return parts.join('; ')
+}
+
+/** Builds a Set-Cookie header that expires (clears) a cookie. */
+export function buildClearCookieHeader(resolved: ResolvedCookieConfig): string {
+  const parts = [
+    `${resolved.name}=`,
+    `HttpOnly`,
+    `Path=${resolved.path}`,
+    `Max-Age=0`,
+    `SameSite=${capitalize(resolved.sameSite)}`,
+  ]
+  if (resolved.secure) parts.push('Secure')
+  return parts.join('; ')
+}
+
+/** Parses a Cookie header string into a Record of key-value pairs. */
+export function parseCookieHeader(header: string | undefined, name: string): string | undefined {
+  if (header === undefined) return undefined
+  for (const pair of header.split(';')) {
+    const trimmed = pair.trim()
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx === -1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    if (key === name) {
+      return decodeURIComponent(trimmed.slice(eqIdx + 1).trim())
+    }
+  }
+  return undefined
+}
+
+/** Parses every name=value pair of a Cookie header. */
+export function parseCookies(header: string | undefined): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (header === undefined) return out
+  for (const pair of header.split(';')) {
+    const trimmed = pair.trim()
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx === -1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    if (key in out) continue
+    try {
+      out[key] = decodeURIComponent(trimmed.slice(eqIdx + 1).trim())
+    } catch {
+      continue
+    }
+  }
+  return out
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/**
+ * Refuses a cookie-authenticated request a browser says came from another site (403 CROSS_SITE_REQUEST).
+ * A write (any method but GET/HEAD/OPTIONS, or none) needs `Sec-Fetch-Site` same-origin/none or a trusted
+ * or same-host `Origin`. A read also passes as a top-level navigation, or with neither `Sec-Fetch-Site`
+ * nor `Origin` (a non-browser client); `crossSiteReads: 'allow'` skips the check for reads.
+ */
+export function assertSameSiteRequest(
+  request: { readonly headers: Readonly<Record<string, string | undefined>>; readonly method?: string | undefined },
+  trusted: readonly string[],
+  crossSiteReads: 'refuse' | 'allow' = 'refuse',
+): void {
+  const read = request.method !== undefined && SAFE_METHODS.has(request.method.toUpperCase())
+  if (read && crossSiteReads === 'allow') return
+  const site = request.headers['sec-fetch-site']
+  if (site === 'same-origin' || site === 'none') return
+  const origin = request.headers['origin']
+  if (read) {
+    if (request.headers['sec-fetch-mode'] === 'navigate') return
+    if (site === undefined && origin === undefined) return
+  }
+  // same-site, cross-site, any other value, or no header: only the Origin can vouch.
+  if (origin !== undefined) {
+    if (trusted.includes(origin)) return
+    try {
+      const host = request.headers['host']
+      if (host !== undefined && new URL(origin).host === host.toLowerCase()) return
+    } catch {
+      // an unparseable Origin (such as "null") is refused below
+    }
+  }
+  throw new CrossSiteRequestError()
+}

package/src/auth/auth/email-links.ts

@@ -0,0 +1,311 @@
+import { createHash, createHmac, randomBytes, randomUUID } from 'node:crypto'
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { pipeSystem } from '../../data/db/db.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { __flowStep } from '../../trace/runtime/flow-step.js'
+import type { Mail } from '../../infra/email/mail.js'
+import type { Passwords } from './passwords.js'
+import type { Sessions } from './sessions.js'
+import { auditUnauthenticated } from './audit.js'
+import { refuseScopedHandle } from '../tenant/scoped-db.js'
+
+export type EmailLinkPurpose = 'reset' | 'verify'
+
+export interface EmailLinkPurposeConfig {
+  /** The name of the app's mail template; it reads `data.url`. */
+  readonly template: string
+  readonly expiresInSeconds: number
+  /** The link the person opens, built from the token. */
+  readonly url: (token: string) => string
+}
+
+export interface RequestLimit {
+  readonly max: number
+  readonly windowSeconds: number
+}
+
+export interface EmailLinksConfig {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- any app's templates
+  readonly mail: Mail<any>
+  readonly passwords: Passwords
+  /** When set, a completed reset revokes the user's refresh tokens and bumps their auth version. */
+  readonly sessions?: Pick<Sessions, 'revokeAll' | 'bumpVersion'>
+  /** Keys the token. At least 32 bytes; without it a copy of the database cannot make a token. */
+  readonly secret: string
+  /** Finds the user for an address (given trimmed, NFC and lower-cased), or null. Runs in the request's transaction. */
+  readonly lookup: (db: DB, address: string) => Promise<{ userId: string } | null>
+  readonly purposes: { readonly reset?: EmailLinkPurposeConfig; readonly verify?: EmailLinkPurposeConfig }
+  /** Defaults: 5 per address and 20 per client within 3600 seconds. */
+  readonly limits?: { readonly perAddress?: RequestLimit; readonly perClient?: RequestLimit }
+  /** Every `request` takes at least this long. Default 250. */
+  readonly minResponseMs?: number
+}
+
+/** The app's data for a message: an object, or a function called for a known, within-limit address in the request's transaction. */
+export type EmailLinkData =
+  | Readonly<Record<string, unknown>>
+  | ((db: DB, user: { userId: string; address: string }) => Promise<Record<string, unknown>>)
+
+export interface EmailLinkRequestInput {
+  readonly purpose: EmailLinkPurpose
+  readonly address: string
+  readonly client?: string
+  /** Stored with the message and given to its template beside `url`, which is reserved for the link. Not secret. */
+  readonly data?: EmailLinkData
+}
+
+export type EmailLinkRequestResult =
+  | { ok: true; limited: false }
+  | { ok: true; limited: true; retryAfterSeconds: number }
+
+export type EmailLinkState = 'active' | 'used' | 'expired' | 'ended' | 'unknown'
+export type EmailLinkRefusal = 'unknown' | 'used' | 'expired' | 'ended' | 'wrong-purpose'
+
+export interface EmailLinkCheck {
+  state: EmailLinkState
+  purpose?: EmailLinkPurpose
+  userId?: string
+  /** When the link stops working (the row's `expires_at`); absent only for an unknown token. */
+  expiresAt?: Date
+}
+
+/** A link `liveFor` found: usable now (not used, not ended, not expired). */
+export interface LiveEmailLink {
+  readonly id: string
+  /** The token `check` and `use` take. */
+  readonly token: string
+  /** The link the person opens, as the purpose builds it from the token. */
+  readonly url: string
+  readonly expiresAt: Date
+}
+
+export interface EmailLinks {
+  /**
+   * Asks for a link. Answers `{ ok: true, limited: false }` for a known address and an unknown one alike, and
+   * `{ ok: true, limited: true, retryAfterSeconds }` once over a limit (the longer wait of the limits exceeded),
+   * again whether or not the address exists; it takes at least `minResponseMs` for each. Only a known,
+   * within-limit address gets a message. `data` (an object, or a function called only for that address) goes
+   * with the message; a `url` key in it throws.
+   * Runs in `db` (the caller's transaction): a rollback drops the link and the message. The limit counts
+   * are kept on `pipe.system()`, so they survive a rollback. Needs an active Flow.
+   */
+  request(db: DB, input: EmailLinkRequestInput): Promise<EmailLinkRequestResult>
+  /** For tests and support tools: the address's live links of `purpose` (given in any case), oldest first, with the token each was mailed under. */
+  liveFor(db: DB, address: string, purpose: EmailLinkPurpose): Promise<readonly LiveEmailLink[]>
+  /** The state of a link, without using it. */
+  check(db: DB, token: string): Promise<EmailLinkCheck>
+  /** Uses a link of `purpose` in one atomic statement: of two concurrent uses exactly one succeeds. */
+  use(db: DB, token: string, purpose: EmailLinkPurpose): Promise<
+    { ok: true; userId: string; address: string } | { ok: false; reason: EmailLinkRefusal }>
+  /**
+   * Uses a reset link, hashes the new password, calls `store(db, userId, hash)` (the app keeps the hash),
+   * ends the user's other reset links and, when `sessions` is configured, revokes all their refresh tokens
+   * and bumps their auth version. A link that cannot be used changes nothing. The caller starts the new session.
+   */
+  completeReset(db: DB, token: string, newPassword: string, options: {
+    store: (db: DB, userId: string, passwordHash: string) => Promise<void>
+  }): Promise<{ ok: true; userId: string } | { ok: false; reason: EmailLinkRefusal }>
+  /** Ends the user's outstanding reset links (call it when a password changes). */
+  endResets(db: DB, userId: string): Promise<void>
+}
+
+const LATE_NAME = 'pipework.emailLink'
+const sha256 = (value: string): string => createHash('sha256').update(value).digest('hex')
+const normalize = (address: string): string => address.normalize('NFC').trim().toLowerCase()
+const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+
+/**
+ * Creates emailed single-use links that prove control of an address: password reset and address
+ * verification. Needs blueprint `emailLinks: {}` (tables `pipework_email_links`, `pipework_email_link_requests`)
+ * and `email: {}`; the app's mail module must run `mail.jobs`.
+ *
+ * The token is `base64url(HMAC-SHA256(secret, id || nonce))`. The link table holds only its sha256, and the
+ * stored message holds only a reference: the url is computed when the message is delivered, so no copy of the
+ * database holds a token or can make one without `secret`.
+ *
+ * Requesting, using and completing a reset are flow steps (`pipework/auth:email-link-request`,
+ * `pipework/auth:email-link-use`) and are audited (`PasswordReset:requested`, `PasswordReset:completed`,
+ * `PasswordReset:link-used`, `EmailAddress:verification-requested`, `EmailAddress:verified`; no tenant), never with the token,
+ * the password or an address that matched no user.
+ */
+export function createEmailLinks(config: EmailLinksConfig): EmailLinks {
+  if (Buffer.byteLength(config.secret, 'utf8') < 32) {
+    throw new Error('[pipework] auth.emailLinks: "secret" must be at least 32 bytes.')
+  }
+  const perAddress = config.limits?.perAddress ?? { max: 5, windowSeconds: 3600 }
+  const perClient = config.limits?.perClient ?? { max: 20, windowSeconds: 3600 }
+  const minResponseMs = config.minResponseMs ?? 250
+
+  const tokenFor = (id: string, nonce: string): string =>
+    createHmac('sha256', config.secret).update(id).update('\0').update(nonce).digest('base64url')
+
+  function purposeConfig(purpose: EmailLinkPurpose): EmailLinkPurposeConfig {
+    const found = config.purposes[purpose]
+    if (found === undefined) throw new Error(`[pipework] auth.emailLinks: no "${purpose}" purpose is configured.`)
+    return found
+  }
+
+  config.mail.registerLateData(LATE_NAME, async (db, ref) => {
+    const row = (await db.execute(sql`SELECT purpose, nonce FROM pipework_email_links WHERE id = ${ref}::uuid`))[0]
+    if (row === undefined) throw new Error('[pipework] auth.emailLinks: the link behind a message no longer exists.')
+    return { url: purposeConfig(row['purpose'] as EmailLinkPurpose).url(tokenFor(ref, row['nonce'] as string)) }
+  })
+
+  function assertNoUrl(data: Readonly<Record<string, unknown>>): void {
+    if (Object.hasOwn(data, 'url')) {
+      throw new Error('[pipework] auth.emailLinks: request "data" may not have a "url" key; "url" is the link, added when the message is delivered.')
+    }
+  }
+
+  // Counts the request against a key and says whether it is over the limit. Atomic per key.
+  async function countRequest(db: DB, key: string, limit: RequestLimit): Promise<{ over: boolean; retryAfterSeconds: number }> {
+    const rows = await db.execute(sql`
+      INSERT INTO pipework_email_link_requests AS r (key, count, window_start)
+      VALUES (${key}, 1, now())
+      ON CONFLICT (key) DO UPDATE SET
+        count = CASE WHEN r.window_start < now() - ${limit.windowSeconds}::int * interval '1 second' THEN 1 ELSE r.count + 1 END,
+        window_start = CASE WHEN r.window_start < now() - ${limit.windowSeconds}::int * interval '1 second' THEN now() ELSE r.window_start END
+      RETURNING count,
+        ceil(extract(epoch FROM (window_start + ${limit.windowSeconds}::int * interval '1 second' - now())))::int AS wait`)
+    return { over: Number(rows[0]!['count']) > limit.max, retryAfterSeconds: Math.max(1, Number(rows[0]!['wait'])) }
+  }
+
+  const requestStep = __flowStep({ ref: 'pipework/auth:email-link-request' }, async (
+    db: DB, input: EmailLinkRequestInput,
+  ): Promise<EmailLinkRequestResult> => {
+    const purposeCfg = purposeConfig(input.purpose)
+    const system = pipeSystem()
+    const address = normalize(input.address)
+    const counts = [await countRequest(system, 'address:' + sha256(address), perAddress)]
+    if (input.client !== undefined && input.client !== '') counts.push(await countRequest(system, 'client:' + input.client, perClient))
+    const exceeded = counts.filter(c => c.over)
+    const verbs = input.purpose === 'reset'
+      ? { entity: 'PasswordReset', verb: 'requested' }
+      : { entity: 'EmailAddress', verb: 'verification-requested' }
+    const client = input.client ?? null
+    if (exceeded.length > 0) {
+      getBaseLogger().warn({ event: 'email link refused', purpose: input.purpose, client }, 'email link request over its limit')
+      await auditUnauthenticated(system, verbs.entity, verbs.verb, null, { purpose: input.purpose, client, outcome: 'limited' })
+      return { ok: true, limited: true, retryAfterSeconds: Math.max(...exceeded.map(c => c.retryAfterSeconds)) }
+    }
+    const found = await config.lookup(db, address)
+    if (found === null) {
+      await auditUnauthenticated(system, verbs.entity, verbs.verb, null, { purpose: input.purpose, client, outcome: 'unknown' })
+      return { ok: true, limited: false }
+    }
+    const data = typeof input.data === 'function'
+      ? await input.data(db, { userId: found.userId, address })
+      : (input.data ?? {})
+    assertNoUrl(data)
+    const id = randomUUID()
+    const nonce = randomBytes(16).toString('base64url')
+    const tokenHash = sha256(tokenFor(id, nonce))
+    await db.execute(sql`
+      UPDATE pipework_email_links SET ended_at = now()
+      WHERE user_id = ${found.userId} AND purpose = ${input.purpose}
+        AND used_at IS NULL AND ended_at IS NULL AND expires_at > now()`)
+    await db.execute(sql`
+      INSERT INTO pipework_email_links (id, purpose, user_id, address, token_hash, nonce, created_at, expires_at)
+      VALUES (${id}::uuid, ${input.purpose}, ${found.userId}, ${address}, ${tokenHash}, ${nonce}, clock_timestamp(),
+        now() + ${purposeCfg.expiresInSeconds}::int * interval '1 second')`)
+    await config.mail.send(db, {
+      to: address, template: purposeCfg.template, data, key: `pipework.emailLink:${id}`,
+      lateData: { name: LATE_NAME, ref: id },
+    })
+    await auditUnauthenticated(system, verbs.entity, verbs.verb, found.userId, { purpose: input.purpose, client, outcome: 'sent' })
+    return { ok: true, limited: false }
+  })
+
+  async function request(db: DB, input: EmailLinkRequestInput): Promise<EmailLinkRequestResult> {
+    if (typeof input.data === 'object') assertNoUrl(input.data)
+    const started = performance.now()
+    let result: EmailLinkRequestResult
+    try {
+      result = await requestStep(db, input)
+    } finally {
+      for (let wait = minResponseMs - (performance.now() - started); wait > 0; wait = minResponseMs - (performance.now() - started)) {
+        await sleep(Math.ceil(wait))
+      }
+    }
+    return result
+  }
+
+  async function check(db: DB, token: string): Promise<EmailLinkCheck> {
+    const row = (await db.execute(sql`
+      SELECT purpose, user_id, expires_at, used_at IS NOT NULL AS used, ended_at IS NOT NULL AS ended, expires_at <= now() AS expired
+      FROM pipework_email_links WHERE token_hash = ${sha256(token)}`))[0]
+    if (row === undefined) return { state: 'unknown' }
+    const state: EmailLinkState = row['used'] === true ? 'used' : row['ended'] === true ? 'ended' : row['expired'] === true ? 'expired' : 'active'
+    return { state, purpose: row['purpose'] as EmailLinkPurpose, userId: row['user_id'] as string, expiresAt: new Date(row['expires_at'] as Date | string) }
+  }
+
+  async function liveFor(db: DB, address: string, purpose: EmailLinkPurpose): Promise<readonly LiveEmailLink[]> {
+    const purposeCfg = purposeConfig(purpose)
+    const rows = await db.execute(sql`
+      SELECT id::text, nonce, expires_at FROM pipework_email_links
+      WHERE address = ${normalize(address)} AND purpose = ${purpose}
+        AND used_at IS NULL AND ended_at IS NULL AND expires_at > now()
+      ORDER BY created_at, id`)
+    return rows.map((row) => {
+      const token = tokenFor(row['id'] as string, row['nonce'] as string)
+      return { id: row['id'] as string, token, url: purposeCfg.url(token), expiresAt: new Date(row['expires_at'] as Date | string) }
+    })
+  }
+
+  async function consume(db: DB, token: string, purpose: EmailLinkPurpose):
+    Promise<{ ok: true; userId: string; address: string } | { ok: false; reason: EmailLinkRefusal }> {
+    const hash = sha256(token)
+    const rows = await db.execute(sql`
+      UPDATE pipework_email_links SET used_at = now()
+      WHERE token_hash = ${hash} AND purpose = ${purpose}
+        AND used_at IS NULL AND ended_at IS NULL AND expires_at > now()
+      RETURNING user_id, address`)
+    if (rows.length > 0) return { ok: true, userId: rows[0]!['user_id'] as string, address: rows[0]!['address'] as string }
+    const seen = await check(db, token)
+    if (seen.state === 'unknown') return { ok: false, reason: 'unknown' }
+    if (seen.purpose !== purpose) return { ok: false, reason: 'wrong-purpose' }
+    return { ok: false, reason: seen.state === 'active' ? 'used' : seen.state }
+  }
+
+  const useStep = __flowStep({ ref: 'pipework/auth:email-link-use' }, async (db: DB, token: string, purpose: EmailLinkPurpose) => {
+    const result = await consume(db, token, purpose)
+    if (result.ok) {
+      const [entity, verb] = purpose === 'verify' ? ['EmailAddress', 'verified'] : ['PasswordReset', 'link-used']
+      await auditUnauthenticated(pipeSystem(), entity!, verb!, result.userId, { purpose })
+    }
+    return result
+  })
+
+  async function endResets(db: DB, userId: string): Promise<void> {
+    await db.execute(sql`
+      UPDATE pipework_email_links SET ended_at = now()
+      WHERE user_id = ${userId} AND purpose = 'reset' AND used_at IS NULL AND ended_at IS NULL`)
+  }
+
+  const completeStep = __flowStep({ ref: 'pipework/auth:email-link-use' }, async (
+    db: DB, token: string, newPassword: string,
+    options: { store: (db: DB, userId: string, passwordHash: string) => Promise<void> },
+  ): Promise<{ ok: true; userId: string } | { ok: false; reason: EmailLinkRefusal }> => {
+    const used = await consume(db, token, 'reset')
+    if (!used.ok) return used
+    const hash = await config.passwords.hash(newPassword)
+    await options.store(db, used.userId, hash)
+    await endResets(db, used.userId)
+    if (config.sessions !== undefined) {
+      await config.sessions.revokeAll(db, used.userId)
+      await config.sessions.bumpVersion(db, used.userId)
+    }
+    await auditUnauthenticated(pipeSystem(), 'PasswordReset', 'completed', used.userId, { purpose: 'reset' })
+    return { ok: true, userId: used.userId }
+  })
+
+  return refuseScopedHandle({
+    request,
+    check,
+    liveFor,
+    use: (db, token, purpose) => useStep(db, token, purpose),
+    completeReset: (db, token, newPassword, options) => completeStep(db, token, newPassword, options),
+    endResets,
+  }, 'emailLinks', 'email links belong to a user and act before any tenant is chosen')
+}

package/src/auth/auth/guard.ts

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto'
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { pipeSystem } from '../../data/db/db.js'
+import { auditUnauthenticated } from './audit.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+
+export interface GuardConfig {
+  /** Names the guard; part of every stored key, so two guards never share a count. */
+  readonly name: string
+  /** Wrong tries allowed per key set within the window. */
+  readonly threshold: number
+  /** Seconds from the first counted try after which the count restarts. */
+  readonly windowSeconds: number
+}
+
+export type GuardKeys = Readonly<Record<string, string>>
+
+export type GuardTake =
+  | { readonly allowed: true; readonly remaining: number }
+  | { readonly allowed: false; readonly retryAfterSeconds: number }
+
+export type GuardStatus = { readonly remaining: number; readonly retryAfterSeconds: number | null }
+
+export interface Guard {
+  /** Counts a try before the secret is checked; refuses once the threshold is reached. */
+  take(keys: GuardKeys): Promise<GuardTake>
+  /** Forgets the count for these keys; call on a right answer. */
+  reset(keys: GuardKeys): Promise<void>
+  /** Reads the count without counting a try. */
+  peek(keys: GuardKeys): Promise<GuardStatus>
+}
+
+/**
+ * Creates a guard on wrong guesses at a secret the app checks itself. `keys`
+ * together form one counter (`{ document, user }` counts per pair). Call `take`
+ * before checking the secret: it counts the try atomically in
+ * `pipework_guard_attempts` (blueprint `guards: {}`), so a parallel burst cannot
+ * exceed `threshold` per `windowSeconds`, and refuses without counting once the
+ * threshold is reached. Call `reset` on a right answer. A wrong try needs no
+ * call. Needs an active Flow; statements run on `pipe.system()`, outside the
+ * request transaction, so a route that rolls back on a wrong try keeps the count.
+ * Route a refusal to 429 with `throw new TooManyRequestsError(take.retryAfterSeconds)`.
+ * Refusals and resets are logged and audited (entity `Guard`), never with the raw keys.
+ */
+export function createGuard(config: GuardConfig): Guard {
+  const { name, threshold, windowSeconds } = config
+  if (typeof name !== 'string' || name === '') throw new Error('createGuard: name must be a non-empty string')
+  if (!Number.isInteger(threshold) || threshold < 1) throw new Error('createGuard: threshold must be a positive integer')
+  if (!Number.isInteger(windowSeconds) || windowSeconds < 1) throw new Error('createGuard: windowSeconds must be a positive integer')
+
+  function keyFor(keys: GuardKeys): string {
+    if (typeof keys !== 'object' || (keys as unknown) === null) throw new Error('guard keys must be a non-empty object')
+    const entries = Object.entries(keys).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    if (entries.length === 0) throw new Error('guard keys must be a non-empty object')
+    for (const [k, v] of entries) {
+      if (typeof v !== 'string' || v === '') throw new Error(`guard keys.${k} must be a non-empty string`)
+    }
+    return name + ':' + createHash('sha256').update(JSON.stringify(entries)).digest('hex')
+  }
+
+  const expired = sql`a.first_failure_at < now() - ${windowSeconds}::int * interval '1 second'`
+
+  // One statement counts the try. The update applies only when the window has
+  // passed or the count is under the threshold; otherwise no row comes back.
+  async function count(db: DB, key: string): Promise<number | null> {
+    const rows = await db.execute(sql`
+      INSERT INTO pipework_guard_attempts AS a (key, failures, first_failure_at, last_failure_at, locked_until)
+      VALUES (${key}, 1, now(), now(),
+        CASE WHEN 1 >= ${threshold}::int THEN now() + ${windowSeconds}::int * interval '1 second' END)
+      ON CONFLICT (key) DO UPDATE SET
+        failures = CASE WHEN ${expired} THEN 1 ELSE a.failures + 1 END,
+        first_failure_at = CASE WHEN ${expired} THEN now() ELSE a.first_failure_at END,
+        last_failure_at = now(),
+        locked_until = CASE
+          WHEN (CASE WHEN ${expired} THEN 1 ELSE a.failures + 1 END) >= ${threshold}::int
+          THEN (CASE WHEN ${expired} THEN now() ELSE a.first_failure_at END) + ${windowSeconds}::int * interval '1 second'
+          END
+      WHERE ${expired} OR a.failures < ${threshold}::int
+      RETURNING failures`)
+    return rows.length > 0 ? Number(rows[0]!['failures']) : null
+  }
+
+  async function retryAfter(db: DB, key: string): Promise<number> {
+    const rows = await db.execute(sql`
+      SELECT greatest(ceil(extract(epoch FROM (first_failure_at + ${windowSeconds}::int * interval '1 second' - now())))::int, 1) AS retry
+      FROM pipework_guard_attempts WHERE key = ${key}`)
+    return Number(rows[0]?.['retry'] ?? 1)
+  }
+
+  async function take(keys: GuardKeys): Promise<GuardTake> {
+    const key = keyFor(keys)
+    const db = pipeSystem()
+    const failures = await count(db, key)
+    if (failures !== null) return { allowed: true, remaining: threshold - failures }
+    const retryAfterSeconds = await retryAfter(db, key)
+    getBaseLogger().warn({ event: 'guard refused', guard: name, key, retryAfterSeconds }, 'guard refused')
+    await auditUnauthenticated(db, 'Guard', 'refused', null, { guard: name, key, retryAfterSeconds })
+    return { allowed: false, retryAfterSeconds }
+  }
+
+  async function reset(keys: GuardKeys): Promise<void> {
+    const key = keyFor(keys)
+    const db = pipeSystem()
+    const rows = await db.execute(sql`DELETE FROM pipework_guard_attempts WHERE key = ${key} RETURNING key`)
+    if (rows.length === 0) return
+    getBaseLogger().info({ event: 'guard reset', guard: name, key }, 'guard reset')
+    await auditUnauthenticated(db, 'Guard', 'reset', null, { guard: name, key, retryAfterSeconds: null })
+  }
+
+  async function peek(keys: GuardKeys): Promise<GuardStatus> {
+    const key = keyFor(keys)
+    const rows = await pipeSystem().execute(sql`
+      SELECT failures,
+        first_failure_at < now() - ${windowSeconds}::int * interval '1 second' AS passed,
+        greatest(ceil(extract(epoch FROM (first_failure_at + ${windowSeconds}::int * interval '1 second' - now())))::int, 1) AS retry
+      FROM pipework_guard_attempts WHERE key = ${key}`)
+    const row = rows[0]
+    if (row === undefined || row['passed'] === true) return { remaining: threshold, retryAfterSeconds: null }
+    const failures = Number(row['failures'])
+    return {
+      remaining: Math.max(threshold - failures, 0),
+      retryAfterSeconds: failures >= threshold ? Number(row['retry']) : null,
+    }
+  }
+
+  return { take, reset, peek }
+}