pipework 0.252.0 → 0.253.0

package/src/request/http/sniff.ts

@@ -0,0 +1,261 @@
+/** Bytes of a file that decide its type: PDF uses all 1024, every other signature the first 512. */
+export const SNIFF_BYTES = 1024
+const SIGNATURE_BYTES = 512
+
+const ZIP = 'application/zip'
+const CFB = 'application/x-cfb'
+const MACHO = 'application/x-mach-binary'
+const PE = 'application/x-msdownload'
+
+const ZIP_REFINEMENTS = [
+  'application/vnd.openxmlformats-officedocument.',
+  'application/vnd.oasis.opendocument.',
+  'application/epub+zip',
+  'application/java-archive',
+  'application/vnd.android.package-archive',
+]
+const CFB_REFINEMENTS = [
+  'application/msword',
+  'application/vnd.ms-excel',
+  'application/vnd.ms-powerpoint',
+  'application/vnd.ms-outlook',
+  'application/x-msi',
+]
+
+const ZIP_EXTENSIONS: Readonly<Record<string, string>> = {
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  odt: 'application/vnd.oasis.opendocument.text',
+  ods: 'application/vnd.oasis.opendocument.spreadsheet',
+  odp: 'application/vnd.oasis.opendocument.presentation',
+  epub: 'application/epub+zip',
+  jar: 'application/java-archive',
+  apk: 'application/vnd.android.package-archive',
+}
+const CFB_EXTENSIONS: Readonly<Record<string, string>> = {
+  doc: 'application/msword',
+  xls: 'application/vnd.ms-excel',
+  ppt: 'application/vnd.ms-powerpoint',
+  msg: 'application/vnd.ms-outlook',
+  msi: 'application/x-msi',
+}
+
+interface Signature { readonly bytes: readonly number[]; readonly offset?: number; readonly type: string }
+
+const ascii = (s: string): number[] => [...s].map((c) => c.charCodeAt(0))
+
+const SIGNATURES: readonly Signature[] = [
+  { bytes: ascii('%PDF-'), type: 'application/pdf' },
+  { bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], type: 'image/png' },
+  { bytes: [0xff, 0xd8, 0xff], type: 'image/jpeg' },
+  { bytes: ascii('GIF87a'), type: 'image/gif' },
+  { bytes: ascii('GIF89a'), type: 'image/gif' },
+  { bytes: [0x49, 0x49, 0x2a, 0x00], type: 'image/tiff' },
+  { bytes: [0x4d, 0x4d, 0x00, 0x2a], type: 'image/tiff' },
+  { bytes: [0x00, 0x00, 0x01, 0x00], type: 'image/x-icon' },
+  { bytes: [0x1a, 0x45, 0xdf, 0xa3], type: 'video/x-matroska' }, // webm refined below
+  { bytes: ascii('OggS'), type: 'audio/ogg' },
+  { bytes: ascii('ID3'), type: 'audio/mpeg' },
+  { bytes: ascii('fLaC'), type: 'audio/flac' },
+  { bytes: [0x50, 0x4b, 0x03, 0x04], type: ZIP },
+  { bytes: [0x50, 0x4b, 0x05, 0x06], type: ZIP },
+  { bytes: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1], type: CFB },
+  { bytes: [0x1f, 0x8b], type: 'application/gzip' },
+  { bytes: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c], type: 'application/x-7z-compressed' },
+  { bytes: [...ascii('Rar!'), 0x1a, 0x07], type: 'application/vnd.rar' },
+  { bytes: ascii('%!PS'), type: 'application/postscript' },
+  { bytes: ascii('{\\rtf'), type: 'application/rtf' },
+  { bytes: ascii('8BPS'), type: 'image/vnd.adobe.photoshop' },
+  { bytes: [0xff, 0x4f, 0xff, 0x51], type: 'image/jp2' }, // bare JPEG 2000 codestream
+  { bytes: [0xff, 0x0a], type: 'image/jxl' }, // bare JPEG XL codestream
+  { bytes: [0x00, 0x00, 0x00, 0x0c, 0x4a, 0x58, 0x4c, 0x20, 0x0d, 0x0a, 0x87, 0x0a], type: 'image/jxl' },
+  { bytes: [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00], type: 'application/x-xz' },
+  { bytes: [0x28, 0xb5, 0x2f, 0xfd], type: 'application/zstd' },
+  { bytes: [0x00, 0x61, 0x73, 0x6d], type: 'application/wasm' },
+  { bytes: [...ascii('SQLite format 3'), 0x00], type: 'application/vnd.sqlite3' },
+  { bytes: ascii('wOFF'), type: 'font/woff' },
+  { bytes: ascii('wOF2'), type: 'font/woff2' },
+  { bytes: ascii('OTTO'), type: 'font/otf' },
+  { bytes: ascii('MThd'), type: 'audio/midi' },
+  { bytes: [0x7f, 0x45, 0x4c, 0x46], type: 'application/x-elf' },
+  { bytes: [0xfe, 0xed, 0xfa, 0xce], type: MACHO },
+  { bytes: [0xfe, 0xed, 0xfa, 0xcf], type: MACHO },
+  { bytes: [0xce, 0xfa, 0xed, 0xfe], type: MACHO },
+  { bytes: [0xcf, 0xfa, 0xed, 0xfe], type: MACHO },
+]
+
+const JP2_SIGNATURE = [0x00, 0x00, 0x00, 0x0c, 0x6a, 0x50, 0x20, 0x20, 0x0d, 0x0a, 0x87, 0x0a]
+const JP2_BRANDS: Readonly<Record<string, string>> = { 'jp2 ': 'image/jp2', 'jpx ': 'image/jpx', 'jpm ': 'image/jpm' }
+
+const FTYP_BRANDS: Readonly<Record<string, string>> = {
+  heic: 'image/heic', heix: 'image/heic', hevc: 'image/heic', hevx: 'image/heic', heim: 'image/heic', heis: 'image/heic',
+  mif1: 'image/heif', msf1: 'image/heif',
+  avif: 'image/avif', avis: 'image/avif',
+  'M4A ': 'audio/mp4',
+  'qt  ': 'video/quicktime',
+}
+
+const RIFF_FORMS: Readonly<Record<string, string>> = {
+  WEBP: 'image/webp',
+  WAVE: 'audio/wav',
+  'AVI ': 'video/x-msvideo',
+}
+
+/** Types whose files always show their signature. MP3 is left out: a file without an ID3 tag has none we detect. */
+export const sniffable: ReadonlySet<string> = new Set([
+  ...SIGNATURES.map((s) => s.type).filter((t) => t !== 'audio/mpeg'),
+  'image/bmp',
+  'video/webm',
+  ...Object.values(RIFF_FORMS),
+  ...Object.values(FTYP_BRANDS),
+  'video/3gpp',
+  'video/mp4',
+  ...Object.values(JP2_BRANDS),
+  'font/ttf',
+  'audio/aiff',
+  'application/x-bzip2',
+])
+
+function matches(head: Buffer, sig: Signature): boolean {
+  const offset = sig.offset ?? 0
+  if (head.length < offset + sig.bytes.length) return false
+  return sig.bytes.every((b, i) => head[offset + i] === b)
+}
+
+const OOXML_DIRS: ReadonlyArray<readonly [string, string]> = [
+  ['word/', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+  ['xl/', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+  ['ppt/', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'],
+]
+const ZIP_MEMBER_TYPE = /^(application\/vnd\.oasis\.opendocument\.[a-z0-9.+-]+|application\/epub\+zip)$/
+
+/** The subtype a zip's own first entries name, or null when they do not decide it. */
+function zipSubtype(h: Buffer): string | null {
+  let offset = 0
+  let found: string | null = null
+  let first = true
+  while (h.length >= offset + 30 && h.readUInt32LE(offset) === 0x04034b50) {
+    const flags = h.readUInt16LE(offset + 6)
+    const method = h.readUInt16LE(offset + 8)
+    const size = h.readUInt32LE(offset + 18)
+    const nameLength = h.readUInt16LE(offset + 26)
+    const dataStart = offset + 30 + nameLength + h.readUInt16LE(offset + 28)
+    if (h.length < offset + 30 + nameLength) return found
+    const name = h.toString('latin1', offset + 30, offset + 30 + nameLength)
+    if (first && name === 'mimetype' && method === 0 && size > 0 && dataStart + size <= h.length) {
+      const content = h.toString('latin1', dataStart, dataStart + size)
+      return ZIP_MEMBER_TYPE.test(content) ? content : null
+    }
+    first = false
+    for (const [dir, type] of OOXML_DIRS) {
+      if (!name.startsWith(dir)) continue
+      if (found !== null && found !== type) return null
+      found = type
+    }
+    if ((flags & 0x08) !== 0 && size === 0) break
+    offset = dataStart + size
+  }
+  return found
+}
+
+/** MPEG audio frame header at offset 0 with a valid version, layer, bitrate and sample rate. */
+function isMpegFrame(h: Buffer): boolean {
+  if (h.length < 4 || h[0] !== 0xff || (h[1]! & 0xe0) !== 0xe0) return false
+  const version = (h[1]! >> 3) & 3
+  const layer = (h[1]! >> 1) & 3
+  const bitrate = h[2]! >> 4
+  const rate = (h[2]! >> 2) & 3
+  return version !== 1 && layer !== 0 && bitrate !== 0 && bitrate !== 15 && rate !== 3
+}
+
+/** A PE image: 'MZ', and e_lfanew pointing inside the head at 'PE\0\0'. */
+function isPortableExecutable(h: Buffer): boolean {
+  if (h.length < 0x40 || h[0] !== 0x4d || h[1] !== 0x5a) return false
+  const pe = h.readUInt32LE(0x3c)
+  return pe >= 0x40 && pe + 4 <= h.length && h.readUInt32BE(pe) === 0x50450000
+}
+
+/**
+ * The media type the first bytes of a file say it is, or null when no signature
+ * matches. A PDF is named when `%PDF-` starts anywhere in the first `SNIFF_BYTES`
+ * bytes, unless another signature matches first. Give it at least the first
+ * `SNIFF_BYTES` bytes; fewer may give null (or, for a zip, plain `application/zip`).
+ */
+export function detectMediaType(bytes: Uint8Array | Buffer): string | null {
+  const head = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const h = head.length > SIGNATURE_BYTES ? head.subarray(0, SIGNATURE_BYTES) : head
+  if (h.length >= 12 && h.toString('latin1', 0, 4) === 'RIFF') {
+    const form = RIFF_FORMS[h.toString('latin1', 8, 12)]
+    if (form !== undefined) return form
+  }
+  if (h.length >= 12 && h.toString('latin1', 0, 4) === 'FORM') {
+    const form = h.toString('latin1', 8, 12)
+    if (form === 'AIFF' || form === 'AIFC') return 'audio/aiff'
+  }
+  if (matches(h, { bytes: JP2_SIGNATURE, type: '' })) {
+    const brand = h.length >= 24 && h.toString('latin1', 16, 20) === 'ftyp' ? JP2_BRANDS[h.toString('latin1', 20, 24)] : undefined
+    return brand ?? 'image/jp2'
+  }
+  if (h.length >= 12 && h.toString('latin1', 4, 8) === 'ftyp') {
+    const brand = h.toString('latin1', 8, 12)
+    const known = FTYP_BRANDS[brand]
+    if (known !== undefined) return known
+    return brand.startsWith('3gp') ? 'video/3gpp' : 'video/mp4'
+  }
+  // BM, reserved zeros at 6-9, and a known DIB header size at 14: 'BM' alone is common text.
+  if (h.length >= 18 && h.toString('latin1', 0, 2) === 'BM' && h.readUInt32LE(6) === 0 && [12, 40, 52, 56, 64, 108, 124].includes(h.readUInt32LE(14))) return 'image/bmp'
+  // A TrueType header starts 00 01 00 00; a plausible table count tells it from binary noise.
+  if (matches(h, { bytes: [0x00, 0x01, 0x00, 0x00], type: '' }) && h.length >= 12) {
+    const tables = h.readUInt16BE(4)
+    if (tables >= 1 && tables <= 64) return 'font/ttf'
+  }
+  if (isPortableExecutable(h)) return PE
+  // 'BZh' alone is common text: a level digit and the first block magic must follow.
+  if (h.length >= 10 && h.toString('latin1', 0, 3) === 'BZh' && h[3]! >= 0x31 && h[3]! <= 0x39 && h.toString('hex', 4, 10) === '314159265359') return 'application/x-bzip2'
+  for (const sig of SIGNATURES) {
+    if (!matches(h, sig)) continue
+    if (sig.type === 'video/x-matroska') return h.includes('webm', 4, 'latin1') ? 'video/webm' : sig.type
+    if (sig.type === ZIP) return zipSubtype(h) ?? ZIP
+    return sig.type
+  }
+  if (isMpegFrame(h)) return 'audio/mpeg'
+  const window = head.length > SNIFF_BYTES ? head.subarray(0, SNIFF_BYTES) : head
+  return window.indexOf('%PDF-', 0, 'latin1') >= 0 ? 'application/pdf' : null
+}
+
+function refinedBy(refinements: readonly string[], declared: string): boolean {
+  return refinements.some((r) => (r.endsWith('.') ? declared.startsWith(r) : declared === r))
+}
+
+/**
+ * The type a file is treated as: what its bytes say, unless the bytes name a
+ * container (zip, compound file) that the declared type or the filename
+ * extension narrows. A zip whose own bytes name its subtype (OpenDocument, EPUB,
+ * OOXML) is that subtype whatever is declared. `mediaType` is '' (matches nothing) when the declared type
+ * is one a signature would show and the bytes do not show it.
+ */
+export function resolveMediaType(input: { head: Uint8Array | Buffer; declared: string; extension: string | null }): { detectedType: string | null; mediaType: string } {
+  const { head, declared, extension } = input
+  const detectedType = detectMediaType(head)
+  const containers: ReadonlyArray<readonly [string, readonly string[], Readonly<Record<string, string>>]> = [
+    [ZIP, ZIP_REFINEMENTS, ZIP_EXTENSIONS],
+    [CFB, CFB_REFINEMENTS, CFB_EXTENSIONS],
+  ]
+  for (const [type, refinements, extensions] of containers) {
+    if (detectedType !== type) continue
+    if (refinedBy(refinements, declared)) return { detectedType, mediaType: declared }
+    const byExtension = extension === null ? undefined : extensions[extension]
+    if (byExtension !== undefined) return { detectedType, mediaType: byExtension }
+  }
+  if (detectedType !== null) return { detectedType, mediaType: detectedType }
+  return { detectedType, mediaType: sniffable.has(declared) ? '' : declared }
+}
+
+/** The lowercase filename extension after the last dot, or null. */
+export function extensionOf(filename: string | null): string | null {
+  if (filename === null) return null
+  const dot = filename.lastIndexOf('.')
+  const ext = dot < 0 ? '' : filename.slice(dot + 1).toLowerCase()
+  return ext === '' ? null : ext
+}

package/src/request/http/types.ts

@@ -0,0 +1,250 @@
+import type { AuthStrategy } from '../../auth/auth/types.js'
+import type { AuthEnricher, TenantResolver } from '../../auth/auth/chain.js'
+import type { Handler, HttpMethod } from '../di/types.js'
+import type { HealthCheck } from '../../core/lifecycle/types.js'
+import type { TenantConfig } from '../../auth/tenant/types.js'
+import type { Rbac } from '../../auth/rbac/types.js'
+import type { OpenAPIInfo } from '../openapi/generate.js'
+import type { LoggingConfig } from '../../core/logging/types.js'
+import type { PipeworkLogger } from '../../core/logging/types.js'
+
+/** Fastify request with pipework extensions — req.id (UUID), typed headers, client address (`ip`, `ips`). */
+export interface HttpRequest {
+  readonly headers: Readonly<Record<string, string | undefined>>
+  /** The client's address. With `trustProxy` off it is the socket's remote address, whatever `X-Forwarded-For` says; with `trustProxy` set it is the client address from `X-Forwarded-For` as far as the trusted proxies vouch for it. Pass it as `client` to `accessLinks` `resolve` and `beginUse` for the per-client limit. */
+  readonly ip: string
+  /** Every address in the chain, nearest first: `[ip]` with `trustProxy` off; with it on, the socket address followed by the `X-Forwarded-For` addresses read back through the trusted proxies, ending at `ip`. */
+  readonly ips: readonly string[]
+  readonly rawBody?: Buffer
+}
+
+/** Fastify reply with pipework extensions. */
+export interface HttpResponse {
+  header(name: string, value: string | readonly string[]): void
+  /**
+   * Calls `cb` once the response is over: `'sent'` when the whole response has been
+   * handed to the connection (the raw response's `finish`), `'aborted'` when the
+   * connection closed first (the client went away mid-stream). Each callback runs once.
+   * It runs after the request's transaction has ended, so anything it does opens its
+   * own transaction. A callback that throws or rejects is logged and never reaches
+   * the response.
+   */
+  onFinish(cb: (outcome: 'sent' | 'aborted') => void | Promise<void>): void
+}
+
+/** CORS configuration — origin, methods, headers, credentials, maxAge. */
+export interface CorsConfig {
+  origin?: string | readonly string[] | boolean | RegExp | ((origin: string) => boolean)
+  methods?: readonly string[]
+  allowedHeaders?: readonly string[]
+  exposedHeaders?: readonly string[]
+  credentials?: boolean
+  maxAge?: number
+}
+
+/** Security header configuration — passed to @fastify/helmet. */
+export interface SecurityConfig {
+  contentSecurityPolicy?: boolean | Record<string, readonly string[]>
+  crossOriginEmbedderPolicy?: boolean
+  crossOriginOpenerPolicy?: boolean | { policy: string }
+  crossOriginResourcePolicy?: boolean | { policy: string }
+  dnsPrefetchControl?: boolean
+  frameguard?: boolean | { action: string }
+  hidePoweredBy?: boolean
+  hsts?: boolean | { maxAge: number; includeSubDomains?: boolean }
+  ieNoOpen?: boolean
+  noSniff?: boolean
+  referrerPolicy?: boolean | { policy: string }
+  xssFilter?: boolean
+}
+
+/** Rate limiting configuration — max requests, time window, key generator. */
+export interface RateLimitConfig {
+  max?: number
+  timeWindow?: string | number
+  keyGenerator?: (request: HttpRequest) => string
+  allowList?: readonly string[]
+  ban?: number
+}
+
+/** One fixed window: at most `max` requests per `windowSeconds`. */
+export interface RateLimitWindow {
+  max: number
+  windowSeconds: number
+}
+
+/** The keys a limit class can count by; `total` counts every caller of the class together. */
+export type RateLimitWindowName = 'perUser' | 'perTenant' | 'perAddress' | 'total'
+
+/**
+ * A named limit class: any of a per-user, per-tenant, per-address and total window, each counted on its own.
+ * Each key takes one window or an array of windows (distinct `windowSeconds`); a request is counted against
+ * all of a key's windows and refused if any is over.
+ */
+export interface RateLimitClass {
+  perUser?: RateLimitWindow | readonly RateLimitWindow[]
+  perTenant?: RateLimitWindow | readonly RateLimitWindow[]
+  perAddress?: RateLimitWindow | readonly RateLimitWindow[]
+  total?: RateLimitWindow | readonly RateLimitWindow[]
+}
+
+/** What `onRefused` is told about one refused window of one request. */
+export interface RateLimitRefusal {
+  class: string
+  limit: RateLimitWindowName
+  /** The user id, tenant id or address that was counted; '*' for `total`. */
+  key: string
+  /** The request's tenant, whichever window refused; null when it has none. */
+  tenantId: string | null
+  /** The signed-in user; null when signed out. */
+  userId: string | null
+  /** The id on the response's X-Request-Id and the request's log lines. */
+  requestId: string
+  /** The pipework trace row of the request; null when tracing is off. */
+  /** The request's trace row id; null with tracing off. */
+  traceId: string | null
+  count: number
+  max: number
+  windowSeconds: number
+  retryAfterSeconds: number
+  route: { method: string; url: string }
+  /** The route's params parsed by its schema as the handler gets them; the raw params with no schema; null when they fail it. */
+  params: unknown
+  /** The route's query, on the same terms as `params`. */
+  query: unknown
+}
+
+/**
+ * Named limit classes, checked after auth and counted in Postgres (`pipework_rate_limit_counts`, opted in
+ * with the blueprint's `rateLimits: {}`), so every server process on the same database shares one count.
+ * Keys are counted perUser, perTenant, perAddress, total in turn, up to the first key with a window over its max, so one user's
+ * refused requests don't spend the tenant's budget. The 429's wait is the longest of the windows that refused, in both the Retry-After header and the body's `error.retryAfterSeconds`. A route is in `signedIn` (auth required, or optional with
+ * a user), `public` (no auth, or optional without a user) or the class its fitting names with `.rateLimit(name)`.
+ */
+export interface RateLimitClassesConfig {
+  classes: Record<string, RateLimitClass>
+  /**
+   * Called once per refused request (for the window that refused it), without delaying the 429; a throw is logged.
+   * Runs in the refused request's Flow with no transaction open: write with `pipe.system()`; those writes commit
+   * on their own and are kept although the request is refused.
+   */
+  onRefused?: (event: RateLimitRefusal) => void | Promise<void>
+}
+
+/** Options for server.inject() — method, url, headers, payload for testing without HTTP. */
+export interface InjectOptions {
+  method: string
+  url: string
+  headers?: Record<string, string | readonly string[] | undefined>
+  payload?: unknown
+  query?: Record<string, string | readonly string[]>
+  /** The socket address the request appears to come from (default `127.0.0.1`). Lets a test exercise `request.ip` and `trustProxy`. */
+  remoteAddress?: string
+}
+
+/** Response from server.inject() — statusCode, headers, body, rawPayload, json() helper. */
+export interface InjectResponse {
+  statusCode: number
+  headers: Record<string, string | number | string[] | undefined>
+  body: string
+  /** The exact bytes of the response body; use it for binary responses, where `body` is decoded as text. */
+  rawPayload: Buffer
+  json(): unknown
+}
+
+/** Configuration for http.createServer() — CORS, security headers, rate limiting, transaction timeout. */
+export interface ServerConfig {
+  port?: number
+  host?: string
+  gracefulShutdownMs?: number
+  /**
+   * Which proxies to believe when reading the client address (`request.ip`) from `X-Forwarded-For`. Passed to Fastify unchanged.
+   * `false` (default): ignore forwarding headers, the address is the socket's.
+   * `true`: trust every hop, so a client can set its own address; only right when every request comes through your proxy.
+   * a string or string[] of addresses or CIDRs (e.g. `'10.0.0.0/8'`): trust only proxies at those addresses.
+   * A hop count (number) is not accepted: Fastify cannot check the immediate peer from a count alone, so it trusts no one.
+   */
+  trustProxy?: boolean | string | readonly string[]
+  logger?: PipeworkLogger | false
+  health?: boolean
+  healthPath?: string
+  readyPath?: string
+  healthChecks?: readonly HealthCheck[]
+  transactionPerRequest?: boolean | readonly string[]
+  transactionTimeoutMs?: number
+  /** Maximum request body size in bytes. Forwarded to Fastify (default 1 MiB). A per-route `.route(m, p, { bodyLimit })` overrides this for that route. */
+  bodyLimit?: number
+  auth?: ServerAuthConfig
+  tenant?: TenantConfig | null
+  rbac?: Rbac
+  /**
+   * Default CORS grant for routes that declare no `.cors()` of their own. Unset or
+   * `false` grants nothing (closed); `{}` is an explicit object and allows all origins.
+   */
+  cors?: CorsConfig | false
+  security?: SecurityConfig | false
+  rateLimit?: RateLimitConfig | false
+  /** Per-route-class limits keyed by user, tenant or address, counted in Postgres. Separate from the server-wide `rateLimit`. */
+  rateLimits?: RateLimitClassesConfig
+  openapi?: OpenAPIInfo
+  openApiPath?: string
+  logging?: LoggingConfig
+  managed?: boolean
+  exposeErrorDetails?: boolean
+  /**
+   * Called, and awaited, before the server sends a 5xx for a thrown error (an unhandled error, a
+   * PipeworkError with httpStatus >= 500, a failed screen or file response). Runs in the request's Flow
+   * with no transaction open. A throw or rejection is logged and the response is unchanged.
+   */
+  onInternalError?: (fault: InternalErrorFault) => void | Promise<void>
+}
+
+/** What `onInternalError` is told about one request that ended in an internal error. */
+export interface InternalErrorFault {
+  error: unknown
+  method: string
+  /** The registered route pattern (`/things/:id`); the raw path where no route matched. */
+  route: string
+  requestId: string
+  tenantId: string | null
+  userId: string | null
+  /** The request's trace row id; null with tracing off. */
+  traceId: string | null
+  /**
+   * The route's params parsed by its schema as the handler gets them; the raw params with no schema;
+   * null when they fail it, and null when no route handler is known (an error raised outside a route, or no route matched).
+   */
+  params: unknown
+  /** The route's query, on the same terms as `params`. */
+  query: unknown
+}
+
+/** Server-level auth configuration — strategy, session config, optional enricher. */
+export type ServerAuthConfig =
+  | { strategy: AuthStrategy<unknown>; optional?: boolean }
+  | { strategies: AuthStrategy<unknown>[]; enrichers?: AuthEnricher<unknown>[]; tenantResolver?: TenantResolver<unknown>; optional?: boolean }
+
+/** Internal route registration record — used by OpenAPI generation to discover routes. */
+export interface RouteRegistration {
+  method: HttpMethod
+  path: string
+  handler: Handler<Record<string, unknown>, unknown>
+}
+
+/** Standard handler response shape — statusCode, headers, body. */
+export interface HandlerResponse {
+  readonly status: number
+  readonly body?: unknown
+}
+
+/** Standard error response shape — { error: { code, message }, statusCode }. */
+export interface ErrorResponse {
+  error: {
+    code: string
+    message: string
+    fields?: Record<string, readonly string[]>
+    /** On a 429: whole seconds to wait; the same number as the Retry-After header. */
+    retryAfterSeconds?: number
+    details?: { name: string; message: string }
+  }
+}