pipework 0.252.0 → 0.253.0

package/src/infra/fetch/handle.ts

@@ -0,0 +1,329 @@
+import { request as httpRequest, type ClientRequest, type IncomingMessage } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import { lookup as dnsLookup } from 'node:dns/promises'
+import { isIP, type Socket } from 'node:net'
+import { connect as tlsConnect } from 'node:tls'
+import { __flowStep } from '../../trace/runtime/flow-step.js'
+import { isPublicAddress } from './address.js'
+
+/** What the app is shown of a response before the body is kept. */
+export interface FetchHead {
+  status: number
+  contentType: string | null
+  /** The first bytes of the body: up to 1024, fewer when the body is shorter. */
+  firstBytes: Uint8Array
+}
+
+/** The connection the fetch is about to open, after the address check passed. */
+export interface FetchTarget {
+  address: string
+  port: number
+  hostname: string
+  protocol: 'http:' | 'https:'
+}
+
+/** Options for `untrustedFetch.get`. The three limits are required: the app says. */
+export interface UntrustedFetchOptions {
+  /** The most body bytes kept; the fetch stops the moment the total passes it. */
+  maxBytes: number
+  /** One time limit for the whole fetch, DNS and redirects included. */
+  timeoutMs: number
+  /** The most redirects followed. */
+  maxRedirects: number
+  /** Called with the status, content type and first bytes before the rest of the body is kept. Return false, or a message string, to refuse. */
+  accept?: (head: FetchHead) => boolean | string
+  /**
+   * Called before each redirect hop with the hop's absolute URL and the URL it came from. Return true to follow it; false, or a
+   * message string, refuses with `rejected`. The address check still runs on every hop that is followed.
+   */
+  followRedirect?: (to: string, from: string) => boolean | string
+  /** Headers sent to the first URL's origin only, never to another origin after a redirect. */
+  headers?: Record<string, string>
+  /** When true the full URL is recorded in the trace step; otherwise only scheme and host. */
+  urlIsSafeToTrace?: boolean
+  /** For tests: replaces DNS. Its answer is still address-checked. */
+  resolve?: (hostname: string) => Promise<string[]>
+  /** For tests: replaces the socket, after the address check passed for `target.address`. */
+  connect?: (target: FetchTarget) => Socket
+}
+
+/** Options for `untrustedFetch.post`: the same rules and limits as `get`, plus the body sent. */
+export interface UntrustedPostOptions extends UntrustedFetchOptions {
+  /** The request body, sent as given; the app sets its own `content-type` in `headers`. */
+  body: string | Uint8Array
+}
+
+/** What is sent: GET has no body. */
+interface Spec { method: 'GET' | 'POST'; body: Buffer | null }
+
+export type FetchRefusal = 'scheme' | 'address' | 'redirects' | 'too_large' | 'timeout' | 'status' | 'rejected' | 'network'
+
+/** A fetched body, or the rule that refused. Never thrown. */
+export type UntrustedFetchResult =
+  | { ok: true; url: string; status: number; contentType: string | null; etag: string | null; lastModified: string | null; body: Uint8Array; bytes: number }
+  | { ok: false; reason: FetchRefusal; message: string; status?: number }
+
+const REDIRECTS = new Set([301, 302, 303, 307, 308])
+const HEAD_BYTES = 1024
+
+class Refusal extends Error {
+  constructor(readonly reason: FetchRefusal, message: string, readonly status?: number) { super(message) }
+}
+
+const MESSAGES = {
+  scheme: 'Only http and https links can be fetched.',
+  address: 'The link points to a private network address.',
+  redirects: 'The link redirects too many times.',
+  too_large: 'The file is larger than allowed.',
+  timeout: 'The server took too long to answer.',
+  network: 'The server could not be reached.',
+} as const
+
+async function defaultResolve(hostname: string): Promise<string[]> {
+  return (await dnsLookup(hostname, { all: true, verbatim: true })).map(a => a.address)
+}
+
+interface Run { aborted: boolean; current: ClientRequest | null }
+
+function bareHost(url: URL): string {
+  return url.hostname.startsWith('[') ? url.hostname.slice(1, -1) : url.hostname
+}
+
+async function fetchOnce(
+  run: Run, url: URL, options: UntrustedFetchOptions, headers: Record<string, string>, spec: Spec,
+): Promise<{ redirect: string; status: number } | { final: IncomingMessage; req: ClientRequest }> {
+  const hostname = bareHost(url)
+  const protocol = url.protocol as 'http:' | 'https:'
+  let addresses: string[]
+  if (isIP(hostname) !== 0) {
+    addresses = [hostname]
+  } else {
+    try {
+      addresses = await (options.resolve ?? defaultResolve)(hostname)
+    } catch {
+      throw new Refusal('network', MESSAGES.network)
+    }
+  }
+  if (run.aborted) throw new Refusal('timeout', MESSAGES.timeout)
+  if (addresses.length === 0) throw new Refusal('network', MESSAGES.network)
+  if (!addresses.every(isPublicAddress)) throw new Refusal('address', MESSAGES.address)
+  const address = addresses[0]!
+  const port = url.port === '' ? (protocol === 'https:' ? 443 : 80) : Number(url.port)
+
+  const base = {
+    method: spec.method, hostname, port, path: url.pathname + url.search,
+    headers: {
+      'accept-encoding': 'identity', ...headers, host: url.host,
+      ...(spec.body !== null ? { 'content-length': String(spec.body.length) } : {}),
+    },
+  }
+  const doRequest = protocol === 'https:' ? httpsRequest : httpRequest
+  const req = options.connect !== undefined
+    ? doRequest({
+      ...base, agent: undefined,
+      createConnection: () => {
+        const socket = options.connect!({ address, port, hostname, protocol })
+        return protocol === 'https:' ? tlsConnect({ socket, ...(isIP(hostname) === 0 ? { servername: hostname } : {}) }) : socket
+      },
+    })
+    : doRequest({
+      ...base, agent: false,
+      lookup: (_h, opts, cb) => {
+        const entry = { address, family: isIP(address) }
+        if ((opts as { all?: boolean }).all === true) (cb as unknown as (e: null, a: unknown) => void)(null, [entry])
+        else cb(null, address, entry.family)
+      },
+    })
+  run.current = req
+  return await new Promise((resolve, reject) => {
+    req.on('error', () => { reject(run.aborted ? new Refusal('timeout', MESSAGES.timeout) : new Refusal('network', MESSAGES.network)) })
+    req.on('response', res => {
+      const status = res.statusCode ?? 0
+      const location = res.headers['location']
+      if (REDIRECTS.has(status) && typeof location === 'string') {
+        res.destroy()
+        req.destroy()
+        resolve({ redirect: location, status })
+        return
+      }
+      resolve({ final: res, req })
+    })
+    if (spec.body !== null) req.end(spec.body)
+    else req.end()
+  })
+}
+
+async function readBody(
+  res: IncomingMessage, req: ClientRequest, options: UntrustedFetchOptions, run: Run, spec: Spec,
+): Promise<{ body: Uint8Array; contentType: string | null; etag: string | null; lastModified: string | null }> {
+  const status = res.statusCode ?? 0
+  const rawType = res.headers['content-type']
+  const contentType = typeof rawType === 'string' ? rawType : null
+  const header = (name: string): string | null => { const v = res.headers[name]; return typeof v === 'string' ? v : null }
+  const etag = header('etag')
+  const lastModified = header('last-modified')
+  const stop = (refusal: Refusal): never => { req.destroy(); res.destroy(); throw refusal }
+  if (status < 200 || status > 299) return stop(new Refusal('status', `The server answered with HTTP status ${status}.`, status))
+  const declared = Number(res.headers['content-length'])
+  const tooLarge = (): Refusal => new Refusal('too_large', MESSAGES.too_large, spec.method === 'POST' ? status : undefined)
+  if (Number.isFinite(declared) && declared > options.maxBytes) return stop(tooLarge())
+
+  return await new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let total = 0
+    let accepted = options.accept === undefined
+    const fail = (r: Refusal): void => { reject(r); req.destroy(); res.destroy() }
+    const runAccept = (): boolean => {
+      accepted = true
+      const first = Buffer.concat(chunks).subarray(0, HEAD_BYTES)
+      let verdict: boolean | string
+      try {
+        verdict = options.accept!({ status, contentType, firstBytes: new Uint8Array(first) })
+      } catch (err) {
+        reject(err)
+        req.destroy()
+        res.destroy()
+        return false
+      }
+      if (verdict === true) return true
+      fail(new Refusal('rejected', typeof verdict === 'string' ? verdict : 'The file was not accepted.'))
+      return false
+    }
+    res.on('data', (chunk: Buffer) => {
+      total += chunk.length
+      if (total > options.maxBytes) { fail(tooLarge()); return }
+      chunks.push(chunk)
+      if (!accepted && total >= HEAD_BYTES) runAccept()
+    })
+    res.on('end', () => {
+      if (!accepted && !runAccept()) return
+      resolve({ body: new Uint8Array(Buffer.concat(chunks)), contentType, etag, lastModified })
+    })
+    const broken = (): void => reject(run.aborted ? new Refusal('timeout', MESSAGES.timeout) : new Refusal('network', MESSAGES.network))
+    res.on('error', broken)
+    res.on('aborted', broken)
+  })
+}
+
+async function runFetch(
+  run: Run, rawUrl: string, options: UntrustedFetchOptions, first: Spec,
+): Promise<Extract<UntrustedFetchResult, { ok: true }>> {
+  let url: URL
+  try {
+    url = new URL(rawUrl)
+  } catch {
+    throw new Refusal('scheme', MESSAGES.scheme)
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Refusal('scheme', MESSAGES.scheme)
+  const firstOrigin = url.origin
+  let spec = first
+  for (let hops = 0; ; hops++) {
+    let headers: Record<string, string> = url.origin === firstOrigin ? (options.headers ?? {}) : {}
+    if (spec.body === null && first.body !== null) {
+      headers = Object.fromEntries(Object.entries(headers).filter(([k]) => !k.toLowerCase().startsWith('content-')))
+    }
+    const step = await fetchOnce(run, url, options, headers, spec)
+    if ('final' in step) {
+      const status = step.final.statusCode ?? 0
+      const { body, contentType, etag, lastModified } = await readBody(step.final, step.req, options, run, spec)
+      return { ok: true, url: url.href, status, contentType, etag, lastModified, body, bytes: body.length }
+    }
+    if (hops >= options.maxRedirects) throw new Refusal('redirects', MESSAGES.redirects)
+    let next: URL
+    try {
+      next = new URL(step.redirect, url)
+    } catch {
+      throw new Refusal('scheme', MESSAGES.scheme)
+    }
+    if (next.protocol !== 'http:' && next.protocol !== 'https:') throw new Refusal('scheme', MESSAGES.scheme)
+    if (options.followRedirect !== undefined) {
+      const verdict = options.followRedirect(next.href, url.href)
+      if (verdict !== true) throw new Refusal('rejected', typeof verdict === 'string' ? verdict : 'The redirect was not followed.')
+    }
+    // 301, 302 and 303 turn a POST into a GET without a body; 307 and 308 resend it.
+    if (spec.method === 'POST' && step.status !== 307 && step.status !== 308) spec = { method: 'GET', body: null }
+    url = next
+  }
+}
+
+interface TraceInfo { host: string | null; url?: string }
+interface TraceOutcome { host: string | null; status: number | null; bytes: number | null; reason: FetchRefusal | null }
+
+/** Records the outcome as the captured input of a child step: a step's own capture is limited to its arguments. */
+const recordOutcome = __flowStep({ ref: 'pipework/fetch:outcome', capture: [null] }, (o: TraceOutcome): TraceOutcome => o)
+
+/** Fail-closed projection: the raw URL and options are never captured. */
+const DROP = (): undefined => undefined
+
+async function runTraced(info: TraceInfo, rawUrl: string, options: UntrustedFetchOptions, spec: Spec): Promise<UntrustedFetchResult> {
+    const run: Run = { aborted: false, current: null }
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timedOut = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        run.aborted = true
+        run.current?.destroy()
+        reject(new Refusal('timeout', MESSAGES.timeout))
+      }, options.timeoutMs)
+    })
+    let result: UntrustedFetchResult
+    try {
+      const work = runFetch(run, rawUrl, options, spec)
+      work.catch(() => undefined)
+      result = await Promise.race([work, timedOut])
+    } catch (err) {
+      if (!(err instanceof Refusal)) throw err
+      result = { ok: false, reason: err.reason, message: err.message, ...(err.status !== undefined ? { status: err.status } : {}) }
+    } finally {
+      clearTimeout(timer)
+    }
+    recordOutcome({
+      host: info.host,
+      status: result.ok ? result.status : (result.status ?? null),
+      bytes: result.ok ? result.bytes : null,
+      reason: result.ok ? null : result.reason,
+    })
+    return result
+}
+
+const tracedGet = __flowStep(
+  { ref: 'pipework/fetch:get', capture: [null, DROP, DROP] },
+  (info: TraceInfo, rawUrl: string, options: UntrustedFetchOptions): Promise<UntrustedFetchResult> =>
+    runTraced(info, rawUrl, options, { method: 'GET', body: null }),
+)
+
+const tracedPost = __flowStep(
+  { ref: 'pipework/fetch:post', capture: [null, DROP, DROP] },
+  (info: TraceInfo, rawUrl: string, options: UntrustedPostOptions): Promise<UntrustedFetchResult> =>
+    runTraced(info, rawUrl, options, { method: 'POST', body: Buffer.from(options.body) }),
+)
+
+function traceInfo(url: string, options: UntrustedFetchOptions): TraceInfo {
+  let host: string | null = null
+  try {
+    host = new URL(url).host
+  } catch { /* the fetch refuses it as scheme */ }
+  return options.urlIsSafeToTrace === true ? { host, url } : { host }
+}
+
+/**
+ * Fetches one URL a stranger gave, with GET: http(s) only, public addresses only (every address the name resolves
+ * to is checked and the connection goes to a checked one), redirects up to `maxRedirects` with each hop checked
+ * as the first, a byte limit stopped the moment it is passed, one time limit for the whole fetch, and the
+ * content type and first bytes shown to `accept` before the body is kept. A refusal is returned with the rule
+ * that refused (`reason`) and a plain message that never carries an address or anything the server sent; it is
+ * not thrown. Recorded as the trace step `pipework/fetch:get` with a child step `pipework/fetch:outcome`
+ * holding host, status, bytes and reason; an ok result also carries the `ETag` and `Last-Modified` the server sent (null when absent); the full URL only when `urlIsSafeToTrace` is true.
+ */
+export function untrustedGet(url: string, options: UntrustedFetchOptions): Promise<UntrustedFetchResult> {
+  return tracedGet(traceInfo(url, options), url, options)
+}
+
+/**
+ * `untrustedGet` with POST: every rule of `get` applies. A 307 or 308 redirect resends the body; 301, 302 and 303
+ * become a GET without a body. The app's `headers` go to the first origin only. A non-2xx answer is returned as
+ * `reason: 'status'` with the status and no body; a 2xx body over `maxBytes` is `too_large` and carries the status.
+ * Recorded as the trace step `pipework/fetch:post`.
+ */
+export function untrustedPost(url: string, options: UntrustedPostOptions): Promise<UntrustedFetchResult> {
+  return tracedPost(traceInfo(url, options), url, options)
+}

package/src/infra/fetch/index.ts

@@ -0,0 +1,7 @@
+export { untrustedGet, untrustedPost } from './handle.js'
+export { isPublicAddress } from './address.js'
+export type {
+  UntrustedFetchOptions, UntrustedPostOptions, UntrustedFetchResult, FetchHead, FetchTarget, FetchRefusal,
+} from './handle.js'
+export { isUnsentFault, retryUnsent, fetchRetryingUnsent } from './connect-retry.js'
+export type { ConnectRetryOptions } from './connect-retry.js'

package/src/infra/fetch/namespace.ts

@@ -0,0 +1,70 @@
+import { untrustedGet, untrustedPost } from './handle.js'
+import { retryUnsent, fetchRetryingUnsent, isUnsentFault } from './connect-retry.js'
+
+/** Untrusted fetch — fetch one URL a stranger gave without letting them reach the app's private network. */
+export const untrustedFetch = {
+  /**
+   * Fetches `url` with GET and returns `{ ok: true, url, status, contentType, etag, lastModified, body, bytes }` (`etag` and `lastModified` are the response headers, null when absent), or `{ ok: false, reason, message }`
+   * naming the rule that refused: `scheme`, `address`, `redirects`, `too_large`, `timeout`, `status`, `rejected` or `network`.
+   * It does not throw for these.
+   *
+   * Rules, none of which can be switched off: only `http:` and `https:`; the name is resolved and every address is checked
+   * (loopback, private, link-local including cloud metadata, CGNAT, unique-local and site-local IPv6, multicast, reserved,
+   * unspecified, and IPv4-mapped or NAT64 forms of these; literal IP URLs likewise) and the connection goes to a checked
+   * address; redirects are followed up to `maxRedirects` and each hop is checked as the first, and the app's `headers` go only to the first origin;
+   * the body is stopped the moment it passes `maxBytes`, whatever Content-Length says; `timeoutMs` covers the whole fetch.
+   * `accept({ status, contentType, firstBytes })` sees the first 1024 bytes before the body is kept: return false, or a string
+   * (your own message), to refuse with `rejected`. Messages never contain an address or anything a server sent.
+   *
+   * `followRedirect(to, from)` is asked before each redirect hop: true follows it; false, or a string (your message), refuses with `rejected`.
+   * A 304 answer is a `status` refusal with `status: 304`; send `If-None-Match` / `If-Modified-Since` through `headers`.
+   *
+   * `resolve` and `connect` are for tests: `resolve(hostname)` replaces DNS and `connect(target)` replaces the socket after the
+   * address check passed, so a test sends a fake public address to a local server. The address check always runs on what `resolve` returns.
+   *
+   * The call is the trace step `pipework/fetch:get`; its child `pipework/fetch:outcome` carries host, status, bytes and reason.
+   * The full URL is recorded only when `urlIsSafeToTrace` is true; otherwise only the host.
+   *
+   * ```ts
+   * const got = await untrustedFetch.get(pasted, { maxBytes: 5_000_000, timeoutMs: 10_000, maxRedirects: 3,
+   *   accept: h => h.firstBytes[0] === 0x25 || 'That does not look like a PDF.' })
+   * if (!got.ok) return tell(got.message)
+   * ```
+   */
+  get: untrustedGet,
+  /**
+   * Posts `body` to `url` with every rule of `get`: scheme, every resolved address checked and the connection made to a checked one,
+   * each redirect hop re-checked, `maxBytes`, one `timeoutMs` for the whole fetch, `headers` to the first origin only.
+   * A 307 or 308 resends the body; 301, 302 and 303 become a GET without a body; `maxRedirects: 0` refuses any redirect.
+   * A non-2xx answer is `{ ok: false, reason: 'status', status }` with no body, as in `get`; a 2xx body over `maxBytes` is
+   * `too_large` and carries `status`. `resolve` and `connect` are for tests, as in `get`.
+   * The call is the trace step `pipework/fetch:post`; the full URL is recorded only when `urlIsSafeToTrace` is true.
+   *
+   * ```ts
+   * const sent = await untrustedFetch.post(endpoint.url, { body: json, headers: { 'content-type': 'application/json' },
+   *   maxBytes: 65_536, timeoutMs: 10_000, maxRedirects: 0 })
+   * if (!sent.ok) return record(sent.reason)
+   * ```
+   */
+  post: untrustedPost,
+} as const
+
+/** Connect retry — send again only when the connection could not be made, so nothing reached the server. */
+export const connectRetry = {
+  /**
+   * `fetch(input, init, opts)` that retries a fault in the connect phase (undici `UND_ERR_CONNECT_TIMEOUT`, `EAI_AGAIN`,
+   * `ENOTFOUND`, `ECONNREFUSED`, `ENETUNREACH`, `EHOSTUNREACH`), waiting `delaysMs` between tries (default 5 s, 15 s, 40 s: four
+   * tries over about a minute), then throws the last fault with its cause chain. A fault after the request was written
+   * (`ECONNRESET`, `UND_ERR_SOCKET`, a timeout, an abort) and a response of any status are never retried, because a POST may have taken effect.
+   * `signal` ends the waiting; `onRetry({ error, attempt, delayMs })` is called before each wait; `fetch` replaces the global fetch.
+   *
+   * ```ts
+   * const res = await connectRetry.fetch('https://api.github.com/repos/o/r/issues', { method: 'POST', body })
+   * ```
+   */
+  fetch: fetchRetryingUnsent,
+  /** Runs any `send()` with the same rule: retried only when `isUnsentFault(error)`; the last fault is thrown unchanged. */
+  call: retryUnsent,
+  /** True when the error, its `cause` chain or an `AggregateError`'s errors show a connect-phase fault and no sent-phase one. */
+  isUnsentFault,
+} as const

package/src/infra/idempotency/index.ts

@@ -0,0 +1,3 @@
+export { createIdempotency, type IdempotencyMiddleware } from './middleware.js'
+export { createStore } from './store.js'
+export type { IdempotencyConfig, IdempotencyRecord, IdempotencyStore } from './types.js'

package/src/infra/idempotency/middleware.ts

@@ -0,0 +1,87 @@
+import type { IdempotencyConfig, IdempotencyStore } from './types.js'
+import type { DB } from '../../data/db/index.js'
+import type { Manifold } from '../../core/pipework.js'
+import { createStore } from './store.js'
+
+export interface IdempotencyMiddleware {
+  readonly store: IdempotencyStore
+  readonly config: Required<IdempotencyConfig>
+
+  check(
+    db: DB,
+    tenantId: string,
+    key: string,
+    method: string,
+    path: string,
+  ): Promise<{ status: 'new' } | { status: 'locked' } | { status: 'completed'; statusCode: number; body: unknown }>
+
+  complete(db: DB, tenantId: string, key: string, statusCode: number, body: unknown): Promise<void>
+  fail(db: DB, tenantId: string, key: string): Promise<void>
+  cleanup(db: DB): Promise<number>
+}
+
+const DEFAULTS = {
+  table: '__pipework_idempotency',
+  headerName: 'Idempotency-Key',
+  ttlSeconds: 86400,
+  lockTimeoutMs: 30_000,
+  methods: ['POST', 'PATCH', 'DELETE'] as const,
+} as const
+
+export function createIdempotency(instance: Manifold, config: IdempotencyConfig): IdempotencyMiddleware {
+  const resolved: Required<IdempotencyConfig> = {
+    database: config.database,
+    table: config.table ?? DEFAULTS.table,
+    headerName: config.headerName ?? DEFAULTS.headerName,
+    ttlSeconds: config.ttlSeconds ?? DEFAULTS.ttlSeconds,
+    lockTimeoutMs: config.lockTimeoutMs ?? DEFAULTS.lockTimeoutMs,
+    methods: config.methods ?? [...DEFAULTS.methods],
+  }
+
+  const store = createStore(resolved.table)
+
+  return {
+    store,
+    config: resolved,
+
+    async check(db, tenantId, key, method, path) {
+      const existing = await store.find(db, tenantId, key)
+
+      if (existing === null) {
+        const locked = await store.lock(db, tenantId, key, method, path, resolved.lockTimeoutMs)
+        if (!locked) {
+          return { status: 'locked' }
+        }
+        return { status: 'new' }
+      }
+
+      if (existing.statusCode !== null) {
+        return { status: 'completed', statusCode: existing.statusCode, body: existing.responseBody }
+      }
+
+      if (existing.lockedUntil !== null && existing.lockedUntil.getTime() > Date.now()) {
+        return { status: 'locked' }
+      }
+
+      // Lock expired — re-lock and retry
+      await store.remove(db, tenantId, key)
+      const locked = await store.lock(db, tenantId, key, method, path, resolved.lockTimeoutMs)
+      if (!locked) {
+        return { status: 'locked' }
+      }
+      return { status: 'new' }
+    },
+
+    async complete(db, tenantId, key, statusCode, body) {
+      await store.complete(db, tenantId, key, statusCode, body)
+    },
+
+    async fail(db, tenantId, key) {
+      await store.remove(db, tenantId, key)
+    },
+
+    async cleanup(db) {
+      return store.cleanup(db, resolved.ttlSeconds)
+    },
+  }
+}

package/src/infra/idempotency/store.ts

@@ -0,0 +1,92 @@
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import type { IdempotencyStore, IdempotencyRecord } from './types.js'
+import { unscopedExecutor, scopedExecutor, requireUnscopedExecutor } from '../../auth/tenant/scoped-db.js'
+
+export function createStore(table: string): IdempotencyStore {
+  return {
+    async ensureTable(handle: DB): Promise<void> {
+      const db = unscopedExecutor(handle).db
+      await db.execute(sql.raw(`
+        CREATE TABLE IF NOT EXISTS ${table} (
+          key TEXT NOT NULL,
+          tenant_id TEXT NOT NULL,
+          method TEXT NOT NULL,
+          path TEXT NOT NULL,
+          status_code INTEGER,
+          response_body JSONB,
+          locked_until TIMESTAMPTZ,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+          PRIMARY KEY (tenant_id, key)
+        )
+      `))
+    },
+
+    async find(handle: DB, tenantId: string, key: string): Promise<IdempotencyRecord | null> {
+      const db = scopedExecutor(handle, tenantId, 'idempotency.find()').db
+      const rows: unknown[] = await db.execute(
+        sql`SELECT key, tenant_id, method, path, status_code, response_body, locked_until, created_at
+            FROM ${sql.raw(table)}
+            WHERE tenant_id = ${tenantId} AND key = ${key}`,
+      )
+      const row = rows[0] as Record<string, unknown> | undefined
+      if (row === undefined) return null
+
+      return {
+        key: row['key'] as string,
+        tenantId: row['tenant_id'] as string,
+        method: row['method'] as string,
+        path: row['path'] as string,
+        statusCode: row['status_code'] as number | null,
+        responseBody: row['response_body'],
+        lockedUntil: row['locked_until'] !== null ? new Date(row['locked_until'] as string) : null,
+        createdAt: new Date(row['created_at'] as string),
+      }
+    },
+
+    async lock(handle: DB, tenantId: string, key: string, method: string, path: string, lockMs: number): Promise<boolean> {
+      const db = scopedExecutor(handle, tenantId, 'idempotency.lock()').db
+      const lockUntil = new Date(Date.now() + lockMs)
+      const rows: unknown[] = await db.execute(
+        sql`INSERT INTO ${sql.raw(table)} (key, tenant_id, method, path, locked_until)
+            VALUES (${key}, ${tenantId}, ${method}, ${path}, ${lockUntil.toISOString()})
+            ON CONFLICT (tenant_id, key) DO NOTHING
+            RETURNING key`,
+      )
+      return (rows as unknown[]).length > 0
+    },
+
+    async complete(handle: DB, tenantId: string, key: string, statusCode: number, responseBody: unknown): Promise<void> {
+      const db = scopedExecutor(handle, tenantId, 'idempotency.complete()').db
+      // JSON.stringify(undefined) returns undefined, which binds as an empty
+      // SQL placeholder and triggers a syntax error. A 204-style response
+      // legitimately has no body; persist it as JSON null so replay surfaces
+      // the same null and the cached statusCode.
+      const body = responseBody === undefined ? null : responseBody
+      await db.execute(
+        sql`UPDATE ${sql.raw(table)}
+            SET status_code = ${statusCode},
+                response_body = ${JSON.stringify(body)},
+                locked_until = NULL
+            WHERE tenant_id = ${tenantId} AND key = ${key}`,
+      )
+    },
+
+    async remove(handle: DB, tenantId: string, key: string): Promise<void> {
+      const db = scopedExecutor(handle, tenantId, 'idempotency.remove()').db
+      await db.execute(
+        sql`DELETE FROM ${sql.raw(table)} WHERE tenant_id = ${tenantId} AND key = ${key}`,
+      )
+    },
+
+    async cleanup(handle: DB, ttlSeconds: number): Promise<number> {
+      const db = requireUnscopedExecutor(handle, 'idempotency.cleanup()', 'it deletes every tenant\'s expired keys')
+      const rows: unknown[] = await db.execute(
+        sql`DELETE FROM ${sql.raw(table)}
+            WHERE created_at < now() - ${ttlSeconds.toString() + ' seconds'}::interval
+            RETURNING key`,
+      )
+      return (rows as unknown[]).length
+    },
+  }
+}

package/src/infra/idempotency/types.ts

@@ -0,0 +1,30 @@
+import type { DB } from '../../data/db/index.js'
+
+export interface IdempotencyConfig {
+  database: string
+  table?: string
+  headerName?: string
+  ttlSeconds?: number
+  lockTimeoutMs?: number
+  methods?: ReadonlyArray<'POST' | 'PUT' | 'PATCH' | 'DELETE'>
+}
+
+export interface IdempotencyRecord {
+  key: string
+  tenantId: string
+  method: string
+  path: string
+  statusCode: number | null
+  responseBody: unknown
+  lockedUntil: Date | null
+  createdAt: Date
+}
+
+export interface IdempotencyStore {
+  ensureTable(db: DB): Promise<void>
+  find(db: DB, tenantId: string, key: string): Promise<IdempotencyRecord | null>
+  lock(db: DB, tenantId: string, key: string, method: string, path: string, lockMs: number): Promise<boolean>
+  complete(db: DB, tenantId: string, key: string, statusCode: number, responseBody: unknown): Promise<void>
+  remove(db: DB, tenantId: string, key: string): Promise<void>
+  cleanup(db: DB, ttlSeconds: number): Promise<number>
+}