@web-ts-toolkit/express-request-attestation 0.48.0

package/index.d.mts

@@ -0,0 +1,712 @@
+import { P as ProofTiming, R as ResolvedTimePolicy } from './time-policy-DlER-7rf.mjs';
+export { A as ATTESTATION_ERROR_RESPONSE_HEADER, a as AttestationEnvelope, b as AttestationMacInput, c as AttestationProtocolError, D as DEFAULT_ATTESTATION_HEADER, d as DEFAULT_CLOCK_SKEW_MS, e as DEFAULT_CLUSTER_CLOCK_GUARD_MS, f as DEFAULT_MAX_AGE_MS, g as DEFAULT_MAX_BODY_BYTES, E as EMPTY_BODY_SHA256_HEX, G as GLOBAL_MAX_RETENTION_MS, K as KEY_BYTES_LENGTH, M as MAC_BYTES_LENGTH, h as MAC_INPUT_LABEL, i as MAX_BODY_BYTES_HARD_CAP, j as MAX_CLOCK_SKEW_MS, k as MAX_CLUSTER_CLOCK_GUARD_MS, l as MAX_CONTENT_TYPE_BYTES, m as MAX_ENCODED_TRANSACTION_ID_BYTES, n as MAX_HEADER_NAME_BYTES, o as MAX_KEY_ID_LENGTH, p as MAX_MAX_AGE_MS, q as MAX_PUBLIC_ORIGIN_BYTES, r as MAX_REPLAY_KEY_BYTES, s as MAX_REPLAY_NAMESPACE_LENGTH, t as MAX_REQUEST_TARGET_BYTES, u as MIN_CLOCK_SKEW_MS, v as MIN_CLUSTER_CLOCK_GUARD_MS, w as MIN_MAX_AGE_MS, x as MIN_REPLAY_KEY_BYTES, y as MacInputFields, N as NONCE_BYTES_LENGTH, z as PROTOCOL_VERSION, B as ProofTimingDecision, C as REPLAY_KEY_PREFIX, F as RequestSigner, H as RequestSignerOptions, I as RetentionAdmission, S as SignInput, T as TimePolicyOptions, J as TransactionIdFields, L as assertTimestampMs, O as base64urlDecode, Q as base64urlEncode, U as buildMacInputBytes, V as buildReplayKeyPreimageBytes, W as canonicalJsonBytes, X as canonicalizeRequestTarget, Y as checkRetentionAdmissible, Z as decodeTransactionId, _ as encodeTransactionId, $ as evaluateProofTiming, a0 as extractSingleHeaderValue, a1 as maxStoreAdmissionMs, a2 as maxVerifierRemainingMs, a3 as normalizeContentType, a4 as normalizeMethod, a5 as parseCanonicalJsonArray, a6 as resolveTimePolicy, a7 as utf8ByteLength, a8 as utf8Decode, a9 as utf8Encode, aa as validateBodyHashHex, ab as validateHeaderName, ac as validateKeyBytes, ad as validateKeyId, ae as validateMac, af as validateNonceHex, ag as validatePublicOrigin, ah as validateReplayKey, ai as validateReplayNamespace } from './time-policy-DlER-7rf.mjs';
+import { Router } from 'express';
+
+/**
+ * ATT-01 server-side interfaces and fixed HTTP errors (task section 4.5).
+ *
+ * Server-specific ONLY: this module may reference Express/Redis types but is
+ * imported exclusively by the `.` entry. The `./signer` entry never imports
+ * it, so browser declarations stay free of server types.
+ */
+/** One accepted key: exactly 32 bytes with an explicit acceptance window. */
+interface AttestationKeyEntry {
+    readonly keyId: string;
+    /** Exactly 32 bytes; snapshots are owned/copy-isolated. */
+    readonly key: Uint8Array;
+    /** Nonnegative safe-integer epoch ms; `acceptFrom < acceptUntil`. */
+    readonly acceptFrom: number;
+    readonly acceptUntil: number;
+}
+/** Keyring snapshot returned by `AttestationKeyProvider.getSnapshot()`. */
+interface AttestationKeySnapshot {
+    /** Must name a present active entry. At most 16 retained keys. */
+    readonly currentKeyId: string;
+    readonly keys: readonly AttestationKeyEntry[];
+}
+/** Input snapshot for static/rotating providers (owned/copied on entry). */
+interface AttestationKeySnapshotInput {
+    readonly currentKeyId: string;
+    readonly keys: readonly {
+        readonly keyId: string;
+        readonly key: Uint8Array;
+        readonly acceptFrom: number;
+        readonly acceptUntil: number;
+    }[];
+}
+/**
+ * Typed key provider. Returns an owned, copy-isolated snapshot (or a promise
+ * of one). Provider/read failure is operational `503`, never a stale-key
+ * client error. External cron/KMS/config code owns provisioning and refresh;
+ * there is no default polling timer.
+ */
+interface AttestationKeyProvider {
+    getSnapshot(): AttestationKeySnapshot | Promise<AttestationKeySnapshot>;
+}
+/** Rotating provider with explicit atomic replacement (ATT-05). */
+interface AttestationRotatingKeyProvider extends AttestationKeyProvider {
+    replace(snapshot: AttestationKeySnapshotInput): void;
+}
+/** Atomic bounded replay-store reservation input. */
+interface AttestationStoreReserveInput {
+    /** Opaque key: `att:v1:` + SHA-256 hex of `[namespace, origin, nonceHex]`. */
+    readonly replayKey: string;
+    /** Absolute retention deadline (safe-integer epoch ms, section 4.4). */
+    readonly retainUntilMs: number;
+}
+type AttestationStoreReserveResult = 'reserved' | 'duplicate' | 'expired';
+/**
+ * Bounded replay store. `reserve` returns `duplicate` for an admitted nonce,
+ * `expired` when the retention deadline has elapsed, and throws typed errors
+ * on capacity exhaustion or unavailability. The adapter never interprets
+ * caller-supplied nonce strings as already authenticated.
+ */
+interface AttestationStore {
+    reserve(input: AttestationStoreReserveInput): Promise<AttestationStoreReserveResult>;
+}
+/**
+ * Narrow structural Redis client contract (ATT-04). The library never creates,
+ * connects, or closes clients and never imports a Redis driver; callers
+ * inject any compatible client (e.g. `node-redis`). Redis stays a dev
+ * dependency for integration tests, not a runtime dependency.
+ */
+interface AttestationRedisClient {
+    sendCommand(args: string[]): Promise<unknown>;
+}
+/** Options for `createRequestAttestationMiddleware` (implemented in ATT-02). */
+interface CreateRequestAttestationMiddlewareOptions {
+    /** Static canonical HTTPS origin (loopback http allowed in development). */
+    readonly publicOrigin: string;
+    readonly replayNamespace: string;
+    /** Upstream-stripped prefix to re-prepend after `req.originalUrl`. */
+    readonly publicPathPrefix?: string;
+    readonly keyProvider: AttestationKeyProvider;
+    readonly store: AttestationStore;
+    readonly maxAgeMs?: number;
+    readonly clockSkewMs?: number;
+    readonly clusterClockGuardMs?: number;
+    readonly headerName?: string;
+    readonly now?: () => number;
+    /** Bounds async provider/store waits; default 5000 ms. */
+    readonly operationTimeoutMs?: number;
+}
+/** Options for `createAttestationBodyCapture` (implemented in ATT-02). */
+interface CreateAttestationBodyCaptureOptions {
+    /** Parser/body budget, default 1 MiB, hard cap 16 MiB. */
+    readonly maxBodyBytes?: number;
+}
+/**
+ * Package-owned body-capture integration: an Express parser `verify`
+ * callback storing digest/count in per-request state plus a narrow error
+ * handler mapping parser size/encoding failures to section 4.5 errors.
+ */
+interface AttestationBodyCapture {
+    readonly verify: (req: unknown, res: unknown, body: unknown, encoding: string) => void;
+    readonly errorHandler: (err: unknown, req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+}
+/** Options for `createSignerBundleRouter` (implemented in ATT-05). */
+interface CreateSignerBundleRouterOptions {
+    readonly publicOrigin: string;
+    readonly replayNamespace: string;
+    readonly keyProvider: AttestationKeyProvider;
+    /** Relative mount base path used only to publish external URLs. */
+    readonly basePath?: string;
+    readonly publicPathPrefix?: string;
+    readonly now?: () => number;
+    readonly operationTimeoutMs?: number;
+}
+/** Options for `createMemoryAttestationStore` (implemented in ATT-03). */
+interface CreateMemoryAttestationStoreOptions {
+    readonly maxEntries?: number;
+    readonly now?: () => number;
+}
+/** Options for `createRedisAttestationStore` (implemented in ATT-04). */
+interface CreateRedisAttestationStoreOptions {
+    readonly client: AttestationRedisClient;
+    readonly keyPrefix?: string;
+    readonly maxEntries?: number;
+}
+/** Fixed section 4.5 error codes with their HTTP status and message. */
+type AttestationErrorCode = 'ATTESTATION_MISSING' | 'ATTESTATION_MALFORMED' | 'ATTESTATION_STALE_KEY' | 'ATTESTATION_EXPIRED' | 'ATTESTATION_FUTURE' | 'ATTESTATION_INVALID_SIGNATURE' | 'ATTESTATION_REPLAY' | 'ATTESTATION_BODY_TOO_LARGE' | 'ATTESTATION_UNSUPPORTED_ENCODING' | 'ATTESTATION_BODY_CAPTURE_REQUIRED' | 'ATTESTATION_INTERNAL_ERROR' | 'ATTESTATION_KEYS_UNAVAILABLE' | 'ATTESTATION_REPLAY_UNAVAILABLE';
+/**
+ * Typed attestation failure carrying a fixed code/status/message. Responses
+ * use `{ code, message }` JSON with `Cache-Control: no-store` and never echo
+ * raw keys, nonces, signatures, bodies, provider errors, or requested IDs.
+ */
+declare class AttestationError extends Error {
+    readonly name = "AttestationError";
+    readonly code: AttestationErrorCode;
+    readonly status: number;
+    constructor(code: AttestationErrorCode);
+}
+declare function isAttestationError(error: unknown): error is AttestationError;
+/** Response payload shape for attestation failures (no raw diagnostics). */
+declare function toAttestationErrorPayload(error: AttestationError): {
+    readonly code: AttestationErrorCode;
+    readonly message: string;
+};
+
+interface AttestationDiagnosticEvent {
+    readonly code: AttestationErrorCode;
+    readonly status: number;
+}
+type AttestationDiagnosticHook = (event: AttestationDiagnosticEvent) => void;
+type CreateRequestAttestationMiddlewareOptionsWithDiagnostic = CreateRequestAttestationMiddlewareOptions & {
+    readonly onDiagnostic?: AttestationDiagnosticHook;
+};
+/**
+ * Create the verify-before-reserve Express guard.
+ *
+ * Required `publicOrigin`/`replayNamespace`/services are validated once and
+ * frozen; key snapshots are owned per request while service references stay
+ * live. Async provider/store waits are bounded by `operationTimeoutMs`
+ * (default 5000 ms, allowed 1-60000 ms); a late settlement after the bound
+ * can never resume the rejected request, call `next`, or release a possibly
+ * committed reservation.
+ */
+declare function createRequestAttestationMiddleware(options: CreateRequestAttestationMiddlewareOptionsWithDiagnostic): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+
+interface AttestationBodyRecord {
+    readonly digestHex: string;
+    readonly byteLength: number;
+}
+interface AttestationBodyCaptureWithRecord extends AttestationBodyCapture {
+    readonly getRecord: (req: unknown) => AttestationBodyRecord | undefined;
+    readonly maxBodyBytes: number;
+}
+/**
+ * Read the package-owned capture record for `req`, or `undefined` when the
+ * configured parser never invoked `verify` for this request. Returns a frozen
+ * copy; caller mutation cannot corrupt stored state. Never trusts
+ * `req.body` or any client-supplied digest field.
+ */
+declare function getAttestationBodyRecord(req: unknown): AttestationBodyRecord | undefined;
+/**
+ * Create the parser `verify` callback + narrow error mapper.
+ *
+ * `maxBodyBytes` defaults to 1 MiB and must be a positive safe integer up to
+ * the v1 hard cap of 16 MiB. Configure the SAME value as the Express parser
+ * `limit` option and always use `inflate: false`. Applications may choose a
+ * smaller limit. Over-limit bodies fail in the parser (mapped to 413 before
+ * the guard) before any replay allocation.
+ */
+declare function createAttestationBodyCapture(options?: CreateAttestationBodyCaptureOptions): AttestationBodyCaptureWithRecord;
+
+interface AttestationVerifyInput {
+    readonly headerValue: string | readonly string[] | undefined;
+    readonly method: unknown;
+    readonly originalUrl: unknown;
+    readonly publicPathPrefix?: string;
+    readonly contentTypeHeader: string | readonly string[] | undefined | null;
+    readonly contentEncodingHeader: string | readonly string[] | undefined | null;
+    readonly bodyDigestHex: unknown;
+    readonly snapshot: AttestationKeySnapshot;
+    readonly nowMs: number;
+    readonly policy: ResolvedTimePolicy;
+    readonly replayNamespace: string;
+    readonly publicOrigin: string;
+}
+interface AttestationVerifiedProof {
+    readonly keyId: string;
+    readonly timestampMs: number;
+    readonly nonceHex: string;
+    readonly keyEntry: AttestationKeyEntry;
+    readonly timing: ProofTiming;
+    readonly replayKey: string;
+    readonly retainUntilMs: number;
+    readonly method: string;
+    readonly requestTarget: string;
+    readonly contentType: string;
+    readonly bodyHashHex: string;
+}
+/** Validate + copy-isolate a provider snapshot. Malformed => KEYS_UNAVAILABLE. */
+declare function copyAttestationSnapshot(snapshot: unknown): AttestationKeySnapshot;
+/** Re-evaluate timing for a known key entry. Throws fixed FUTURE/EXPIRED/STALE. */
+declare function checkProofTiming(input: {
+    readonly timestampMs: number;
+    readonly nowMs: number;
+    readonly keyEntry: Pick<AttestationKeyEntry, 'acceptFrom' | 'acceptUntil'>;
+    readonly policy: ResolvedTimePolicy;
+}): ProofTiming;
+/** Concatenate the trusted prefix with `originalUrl` and canonicalize. */
+declare function resolveRequestTarget(originalUrl: unknown, publicPathPrefix: string): string;
+/** Single final Content-Type value. Duplicate/controls => MALFORMED. */
+declare function resolveContentType(header: string | readonly string[] | undefined | null): string;
+/** V1 accepts identity / absent Content-Encoding only. */
+declare function assertAllowedContentEncoding(header: string | readonly string[] | undefined | null): void;
+/** Opaque replay key `att:v1:` + SHA-256 of `[namespace, origin, nonceHex]`. */
+declare function deriveReplayKey(input: {
+    readonly replayNamespace: string;
+    readonly publicOrigin: string;
+    readonly nonceHex: string;
+}): string;
+/**
+ * Pure pre-reservation verification. Performs header/codec, snapshot lookup,
+ * time, target, content-type/encoding, body digest, and HMAC stages in order
+ * and returns the owned timing + replay key for the middleware to reserve.
+ */
+declare function verifyAttestationProof(input: AttestationVerifyInput): AttestationVerifiedProof;
+
+/**
+ * ATT-03 bounded atomic memory replay store (task section 4.4).
+ *
+ * Admission contract (shared with the future ATT-04 Redis adapter):
+ *
+ * - `reserve({ replayKey, retainUntilMs })` returns `'reserved' | 'duplicate' | 'expired'`.
+ * - The canonical deadline field is `retainUntilMs` (see `AttestationStoreReserveInput`).
+ *   A `retainUntil` alias is accepted at runtime for callers written against the
+ *   task-text shorthand; when both are present the canonical field wins.
+ * - Validation order per admission: input shape, store clock, opaque key bounds
+ *   (1-256 printable ASCII), deadline shape (nonnegative safe integer), input
+ *   expiry (`retainUntilMs <= now` returns `'expired'` with no allocation and no
+ *   clamping), global retention cap (`retainUntilMs - now > 240000` rejects
+ *   without allocating instead of truncating), then duplicate check, then bounded
+ *   expiry reclamation, then capacity, then atomic insert.
+ * - Duplicate detection precedes capacity rejection: a live duplicate returns
+ *   `'duplicate'` even when full. Duplicates never extend expiry and never
+ *   allocate a new heap node.
+ * - Each admission reclaims the requested expired entry (when the same key holds
+ *   one) plus at most 64 expired entries from the indexed expiry heap. No live
+ *   entry is ever evicted, there is no interval timer, and there is no full-map
+ *   rebuild or linear key scan.
+ * - An expired key is reservable again for a fresh proof whose deadline is
+ *   valid; the old proof still fails the verifier's age rules (the store never
+ *   sees signatures, only opaque already-derived replay keys).
+ *
+ * Sharing boundary: replay state is shared only by callers reusing this same
+ * store object in one process. Restart or state loss resets this replay memory.
+ * There is no multi-process coordination, durable exactly-once delivery, or
+ * cross-object sharing (independent store objects intentionally do not
+ * coordinate).
+ */
+
+/**
+ * Shared capacity exhaustion: no live reservation is evicted and no proof is
+ * admitted without replay state. Handle like any replay-store failure: fail
+ * closed. Also thrown by the future Redis adapter so callers handle one error
+ * type across backends.
+ */
+declare class AttestationCapacityError extends Error {
+    readonly name = "AttestationCapacityError";
+    constructor(message?: string);
+}
+/**
+ * Create a process-local bounded attestation replay store for local
+ * development and tests.
+ *
+ * Reservations are kept in memory, cleaned up opportunistically during
+ * `reserve` calls, and lost when the Node.js process exits. Do not use this
+ * store when replay state must survive restarts or be shared by multiple
+ * application instances. Replay is shared only by callers reusing this same
+ * object; the store does not verify request signatures. Capacity defaults to
+ * 50000 entries and never evicts live entries.
+ */
+declare function createMemoryAttestationStore(options?: CreateMemoryAttestationStoreOptions): AttestationStore;
+
+/**
+ * ATT-04 shared bounded Redis replay admission (task sections 4.1/4.4).
+ *
+ * Admission contract (shared with ATT-03 memory; see `test/store-conformance.ts`):
+ *
+ * - `reserve({ replayKey, retainUntilMs })` returns
+ *   `'reserved' | 'duplicate' | 'expired'`.
+ * - The canonical deadline field is `retainUntilMs`
+ *   (see `AttestationStoreReserveInput`). A `retainUntil` alias is accepted at
+ *   runtime for callers written against the task-text shorthand; when both are
+ *   present the canonical field wins.
+ * - Malformed inputs (non-object, bad opaque key bounds 1–256 printable
+ *   ASCII, non-safe-integer deadlines) reject with `AttestationProtocolError`
+ *   WITHOUT touching Redis (no allocation, `sendCommand` never called).
+ * - Live/overlong enforcement uses Redis server `TIME` inside one atomic Lua
+ *   admission (`src/stores/redis-script.ts`): `retainUntil <= now` returns
+ *   `'expired'`; `retainUntil - now > 240000` throws `AttestationProtocolError`
+ *   instead of truncating; duplicates return `'duplicate'` even when full and
+ *   never change their score; at most 64 expired entries plus the requested
+ *   expired one are reclaimed per admission; shared `ZCARD` capacity is checked
+ *   before `ZADD`; the ledger is `PEXPIREAT`ed through its latest retained
+ *   score so idle state is reclaimed without shortening any member.
+ * - Capacity throws the shared `AttestationCapacityError` (same class as
+ *   memory, so callers handle one type across backends). Wrong Redis data
+ *   type, invalid script replies, and transport/script failures throw the
+ *   typed operational `AttestationRedisStoreError`. Never silently accept
+ *   without a committed (`ZADD`) reservation.
+ *
+ * Wiring:
+ *
+ * - `createRedisAttestationStore({ client, keyPrefix = 'wtt-attestation',
+ *   maxEntries = 50000 })`. The public client type is the narrow structural
+ *   `sendCommand(args: string[]): Promise<unknown>` contract compatible with
+ *   `node-redis`; the library never creates, connects, or closes clients and
+ *   never imports a Redis driver (driver is a dev dependency for tests only).
+ * - One same-slot sorted set per shared prefix
+ *   (`<keyPrefix>:attestation-proofs`) holds opaque keys + absolute scores.
+ *   All clients sharing a prefix MUST configure identical `maxEntries`;
+ *   mixed capacities admit under the smallest view and reject under the
+ *   largest, breaking the shared bound.
+ * - Steady-state `EVALSHA`; on cold start / definite `NOSCRIPT`
+ *   nonexecution the runner `SCRIPT LOAD`s and retries exactly once. Uncertain
+ *   network timeouts are never retried as though nothing committed: a timeout
+ *   may have committed server-side but never executes a handler or falls back
+ *   to memory (the middleware maps it to `ATTESTATION_REPLAY_UNAVAILABLE`
+ *   without calling `next`). No non-atomic `GET`/`SET`, no separate capacity
+ *   counter, no `nowSkewToleranceMs` hidden clamp — the adapter receives
+ *   section 4.4's exact `retainUntil`.
+ *
+ * Capacity / failure / rate notes (no fabricated bytes-per-entry benchmark):
+ *
+ * - Size the ledger as unique accepted requests/second × maximum retention
+ *   (default at most 50000 ms at the store including the behind-verifier
+ *   guard, global cap 240000 ms) plus headroom; actual Redis memory and
+ *   throughput require measurement on your deployment.
+ * - Redis eviction, restore/state loss, or failover can erase replay
+ *   reservations. When relying on window-wide admission history, use a
+ *   suitably configured dedicated `noeviction` deployment with persistence /
+ *   replication appropriate to your recovery objectives; after state loss a
+ *   fresh proof is required and old proofs may be admitted once more (they
+ *   still fail verifier age rules once stale).
+ * - Sharing is one ledger key per prefix: independent prefixes (and memory
+ *   objects) intentionally do not coordinate. Restarts do not reset Redis
+ *   state, but `SCRIPT FLUSH` only forces a reload, never a second admission.
+ */
+
+/** Default namespace for the single same-slot ledger key. */
+declare const REDIS_ATTESTATION_STORE_DEFAULT_KEY_PREFIX: "wtt-attestation";
+/** Default capacity: at most this many live reservations per shared prefix. */
+declare const REDIS_ATTESTATION_STORE_DEFAULT_MAX_ENTRIES: 50000;
+/**
+ * Typed operational failure for the Redis replay adapter: wrong Redis data
+ * type, invalid script replies, and transport/script failures. Capacity uses
+ * the shared `AttestationCapacityError`; malformed inputs use
+ * `AttestationProtocolError`. The middleware maps both operational failures
+ * to fixed `ATTESTATION_REPLAY_UNAVAILABLE` without calling `next`, falling
+ * back to memory, or releasing a possibly committed reservation.
+ */
+declare class AttestationRedisStoreError extends Error {
+    readonly name = "AttestationRedisStoreError";
+    constructor(message?: string);
+}
+/**
+ * Create a shared bounded attestation replay store over one same-slot Redis
+ * sorted-set ledger.
+ *
+ * Pass an already-connected client (or compatible `sendCommand` adapter); the
+ * store never connects, disconnects, or attaches listeners. All clients of a
+ * prefix must use identical `maxEntries`. See the module header for capacity,
+ * failure, and lifecycle notes.
+ */
+declare function createRedisAttestationStore(options: CreateRedisAttestationStoreOptions): AttestationStore;
+
+/**
+ * MONGO-01 MongoDB replay adapter (task sections 4.1/4.4).
+ *
+ * Admission contract (shared with memory/Redis; see `test/store-conformance.ts`):
+ *
+ * - `reserve({ replayKey, retainUntilMs })` returns
+ *   `'reserved' | 'duplicate' | 'expired'`.
+ * - The canonical deadline field is `retainUntilMs`
+ *   (see `AttestationStoreReserveInput`). A `retainUntil` alias is accepted at
+ *   runtime for callers written against the task-text shorthand; when both are
+ *   present the canonical field wins.
+ * - Validation order per admission: input shape, store clock, opaque key
+ *   bounds (1-256 printable ASCII), deadline shape (nonnegative safe
+ *   integer), input expiry (`retainUntilMs <= now` returns `'expired'` with
+ *   no allocation and no clamping), global retention cap
+ *   (`retainUntilMs - now > 240000` rejects without allocating instead of
+ *   truncating), then duplicate check, then bounded expiry reclamation, then
+ *   capacity, then atomic insert.
+ * - Duplicate detection precedes capacity rejection: a live duplicate returns
+ *   `'duplicate'` even when full. Duplicates never extend expiry and never
+ *   rescore.
+ * - Each admission reclaims the requested expired entry (when the same key
+ *   holds one) plus at most 64 expired entries from the indexed accounting
+ *   ledger. No live entry is ever evicted and there is no interval timer.
+ * - An expired key is reservable again for a fresh proof whose deadline is
+ *   valid; the old proof still fails the verifier's age rules (the store never
+ *   sees signatures, only opaque already-derived replay keys).
+ *
+ * Storage design (follows the vault MongoDB store's DPoP replay
+ * reservations module):
+ *
+ * - One proof collection with unique `_id`s (`{ _id: replayKey,
+ *   retainUntilMs }`) plus a separate non-TTL capacity/accounting collection
+ *   (`{ _id, kind, replayKey?, retainUntilMs? }`) with one shared capacity
+ *   row (`{ _id: 'capacity' }` holding `entries`/`maxEntries`/`revision`).
+ * - Multi-document snapshot transaction per admission: duplicate check,
+ *   bounded expiry reclaim (64), capacity check, insert. Duplicates never
+ *   extend expiry; no live eviction.
+ * - Do not rely on a Mongo TTL index for correctness (coarse granularity);
+ *   the indexed, non-TTL accounting ledger is the source of truth. Create a
+ *   non-TTL index on `retainUntilMs` (for example
+ *   `{ kind: 1, retainUntilMs: 1 }` on the capacity collection) for the
+ *   bounded expiry queries; never add a TTL index to the accounting
+ *   collection.
+ * - App clock with a synchronized-clock requirement across instances (Mongo
+ *   has no `TIME` equivalent): all verifiers/stores sharing one database must
+ *   use synchronized clocks within the configured `clusterClockGuardMs`, and
+ *   an invalid clock fails closed without allocating or touching the
+ *   database.
+ *
+ * Wiring:
+ *
+ * - `createMongoAttestationStore({ db, proofsCollectionName?,
+ *   capacityCollectionName?, maxEntries?, now? })`. The `Db`/collection
+ *   handles are retained live without cloning, connecting, or closing; the
+ *   caller owns the underlying `MongoClient` lifecycle (connect/close).
+ *   Production deployments require a replica set (transactions).
+ * - The `mongodb` driver is a dev dependency for tests only. The library
+ *   uses narrow structural `Db`/collection/session types and never imports a
+ *   driver at runtime, so browser-only `/signer` consumers never need it.
+ * - Capacity throws the shared `AttestationCapacityError` (same class as
+ *   memory/Redis). Wrong collection types, transaction failures, and
+ *   malformed persisted rows throw the narrow `AttestationMongoStoreError`.
+ *   Malformed inputs throw `AttestationProtocolError` without touching the
+ *   database. The middleware already maps unknown store failures to fixed
+ *   `ATTESTATION_REPLAY_UNAVAILABLE` without calling `next`; do not change
+ *   middleware for this adapter.
+ *
+ * Sharing boundary: replay state is shared by all clients using the same
+ * database/collections with identical `maxEntries`. Independent databases or
+ * collection pairs intentionally do not coordinate. Mixed capacities break
+ * the shared bound; configure identically everywhere.
+ */
+
+/** Default capacity: at most this many live replay reservations per database. */
+declare const MONGO_ATTESTATION_STORE_DEFAULT_MAX_ENTRIES: 50000;
+/** Default proof collection name (unique `_id`s, no TTL). */
+declare const MONGO_ATTESTATION_STORE_DEFAULT_PROOFS_COLLECTION: "attestation_proofs";
+/** Default capacity/accounting collection name (non-TTL ledger). */
+declare const MONGO_ATTESTATION_STORE_DEFAULT_CAPACITY_COLLECTION: "attestation_replay_capacity";
+/**
+ * Typed operational failure for the Mongo replay adapter: transport,
+ * topology, transaction, and persisted-row inconsistency failures. Capacity
+ * uses the shared `AttestationCapacityError`; malformed inputs use
+ * `AttestationProtocolError`. The middleware maps this error to fixed
+ * `ATTESTATION_REPLAY_UNAVAILABLE` without calling `next`, falling back to
+ * memory, or releasing a possibly committed reservation.
+ */
+declare class AttestationMongoStoreError extends Error {
+    readonly name = "AttestationMongoStoreError";
+    constructor(message?: string);
+}
+/** Narrow structural session: only `withTransaction`/`endSession` are used. */
+interface MongoAttestationStoreSession {
+    withTransaction<T>(fn: () => Promise<T>, options?: unknown): Promise<T | undefined>;
+    endSession(): Promise<void>;
+}
+/** Narrow structural collection: only the replay-admission methods are used. */
+interface MongoAttestationStoreCollection {
+    readonly collectionName: string;
+    findOne(filter?: unknown, options?: unknown): Promise<unknown>;
+    findOneAndUpdate(filter: unknown, update: unknown, options?: unknown): Promise<unknown>;
+    insertOne(doc: unknown, options?: unknown): Promise<unknown>;
+    deleteOne(filter?: unknown, options?: unknown): Promise<unknown>;
+    deleteMany(filter?: unknown, options?: unknown): Promise<unknown>;
+    replaceOne(filter: unknown, replacement: unknown, options?: unknown): Promise<unknown>;
+    updateOne(filter: unknown, update: unknown, options?: unknown): Promise<unknown>;
+    find(filter?: unknown, options?: unknown): {
+        sort(spec: unknown): {
+            limit(n: number): {
+                toArray(): Promise<unknown[]>;
+            };
+        };
+    };
+}
+/** Narrow structural database handle: `collection` plus session creation. */
+interface MongoAttestationStoreDb {
+    collection(name: string): MongoAttestationStoreCollection;
+    readonly client: {
+        startSession(): MongoAttestationStoreSession;
+    };
+}
+/** Options for `createMongoAttestationStore` (MONGO-01). */
+interface CreateMongoAttestationStoreOptions {
+    /** Database handle from an already-connected caller-owned client. */
+    readonly db: MongoAttestationStoreDb;
+    /** Proof collection name; default `attestation_proofs`. */
+    readonly proofsCollectionName?: string;
+    /** Capacity/accounting collection name; default `attestation_replay_capacity`. */
+    readonly capacityCollectionName?: string;
+    /** Positive safe-integer shared capacity; default 50000. */
+    readonly maxEntries?: number;
+    /** App clock; default `Date.now`. Must stay synchronized across instances. */
+    readonly now?: () => number;
+}
+/**
+ * Create a shared bounded attestation replay store over two MongoDB
+ * collections.
+ *
+ * Pass a `Db` from an already-connected caller-owned `MongoClient`; the
+ * store never connects, disconnects, or attaches listeners. All clients
+ * sharing one database/collections must configure identical `maxEntries`
+ * and synchronized clocks. Production deployments require a replica set
+ * (transactions). Create a non-TTL index on `retainUntilMs` for the bounded
+ * expiry queries; never add a TTL index to the accounting collection.
+ */
+declare function createMongoAttestationStore(options: CreateMongoAttestationStoreOptions): AttestationStore;
+
+/**
+ * ATT-05 owned key rotation (task sections 4.1/4.6).
+ *
+ * - `generateAttestationKey(keyId, { acceptFrom, acceptUntil })` creates one
+ *   random 32-byte entry for an explicit acceptance window.
+ * - `createStaticKeyProvider(snapshot)` owns an immutable snapshot.
+ * - `createRotatingKeyProvider(snapshot)` supports explicit atomic
+ *   `replace(snapshot)`; external cron/KMS/config code owns provisioning and
+ *   refresh. No default polling timer, no hardcoded grace policy.
+ *
+ * Snapshot rules (section 4.1):
+ *
+ * - Snapshots have `currentKeyId` plus a bounded list of 1-16 entries
+ *   `{ keyId, key: Uint8Array(32), acceptFrom, acceptUntil }`.
+ * - Key bytes are exactly 32 bytes; times are nonnegative safe-integer epoch
+ *   milliseconds with `acceptFrom < acceptUntil`; identifiers match
+ *   `[A-Za-z0-9_-]{1,64}`.
+ * - `currentKeyId` must name a present entry. Snapshots are owned and
+ *   copy-isolated: input bytes are copied on entry, output bytes are copied
+ *   on every `getSnapshot()`, so later caller mutation (including in-place
+ *   `Uint8Array` writes) cannot change provider state and provider state
+ *   cannot be mutated through a returned snapshot.
+ * - Key IDs are unique across the application's provisioning history.
+ *   Providers reject remapping an ID that is present in their retained
+ *   snapshot (same ID with different bytes or a different acceptance
+ *   interval) without growing an unbounded historical ID ledger. Generate
+ *   unique version/random identifiers and never reintroduce a retired ID with
+ *   different material. Atomic replacement controls subsequent snapshots; it
+ *   is not cancellation of requests already using an owned preflight
+ *   snapshot.
+ * - Rejected replacements leave the previous valid snapshot intact
+ *   (atomic). Provider/read failure is operational `503` at the verifier,
+ *   never a stale-key client error (see `verify.ts`).
+ *
+ * Runbook (finite acceptance, application-configured):
+ *
+ * - Prepare new material on **all** verifiers, publish current
+ *   metadata/module, retain old material to its explicit deadline, retire
+ *   only after overlap requirements. Do not make one instance the
+ *   authoritative random-key generator for an uncoordinated cluster.
+ * - Finite acceptance/grace is application-configured, not automatically
+ *   `2 x rotation interval`.
+ *
+ * Public HMAC material delivered in JavaScript stays accessible to every
+ * caller despite rotation; rotation limits how long old material is
+ * accepted, it does not stop a caller from downloading the next version.
+ *
+ * No import-time network requests, timers, key generation, or storage
+ * access. Construction performs no I/O (`sideEffects: false`).
+ */
+
+/**
+ * Create one random 32-byte key entry for an explicit acceptance window.
+ * Uses `node:crypto` randomness; the returned entry owns its bytes (frozen).
+ */
+declare function generateAttestationKey(keyId: string, window: {
+    readonly acceptFrom: number;
+    readonly acceptUntil: number;
+}): AttestationKeyEntry;
+/**
+ * Create an immutable static key provider. The input snapshot is copied on
+ * entry; every `getSnapshot()` returns a fresh owned copy. No timers,
+ * network, or storage work occurs at construction or on reads.
+ */
+declare function createStaticKeyProvider(snapshot: AttestationKeySnapshotInput): AttestationKeyProvider;
+/**
+ * Create an explicit-replacement rotating key provider. `replace(snapshot)`
+ * validates the new snapshot shape first, then rejects atomically when any
+ * ID retained in the current snapshot would be remapped to different bytes
+ * or a different acceptance interval; the previous valid snapshot survives
+ * rejected replacements. Retirement (dropping an ID) and introduction of
+ * fresh IDs are allowed. No historical tombstone ledger is kept: an ID that
+ * is no longer retained may be reintroduced, but provisioners must never
+ * reintroduce a retired ID with different material (generate unique
+ * version/random identifiers).
+ */
+declare function createRotatingKeyProvider(snapshot: AttestationKeySnapshotInput): AttestationRotatingKeyProvider;
+
+/**
+ * ATT-05 relative signer-asset router (task sections 4.1/4.6).
+ *
+ * Server-only: may import Express and Node built-ins. Never imported by the
+ * `./signer` browser entry.
+ *
+ * - `createSignerBundleRouter({ publicOrigin, replayNamespace, keyProvider,
+ *   basePath = '/attestation', publicPathPrefix, now, operationTimeoutMs })`
+ *   returns a **relative** Express router. It does not mount itself at
+ *   `basePath`; the application mounts it (for example
+ *   `app.use('/attestation', router)`). `basePath` plus the trusted
+ *   `publicPathPrefix` are used solely to publish correct external URLs
+ *   (`publicOrigin + publicPathPrefix + basePath + /signer.<hash>.mjs`).
+ *   Request headers (`Host`, `Forwarded`, `X-Forwarded-*`) are never used
+ *   for URL construction.
+ * - Routes: `GET /signer-meta`, `GET /signer.<contenthash>.mjs`,
+ *   `GET /runtime.<contenthash>.mjs`. The runtime is the actual built browser
+ *   ESM entry from this installed package (see `signer-assets.ts` for CJS/ESM
+ *   + release-flattening lookup); the 64-hex content hash identifies exact
+ *   immutable bytes. Never serve different content from the same URL.
+ * - Key-specific modules import the runtime via relative
+ *   `./runtime.<hash>.mjs` and export `signer: RequestSigner` from
+ *   `createRequestSigner`. Key bytes use a simple canonical encoded literal;
+ *   no XOR/obfuscation is claimed as protection. All generated imports
+ *   resolve in a browser without an npm bare-module map.
+ * - Metadata is bounded JSON
+ *   `{ version: 1, keyId, signerUrl, publicOrigin, replayNamespace }` with
+ *   `Cache-Control: no-store`, serving the current active key only. The
+ *   current entry must be present and active at `nowMs`; otherwise metadata
+ *   fails with `503 ATTESTATION_KEYS_UNAVAILABLE`.
+ * - Immutable assets use `Content-Type: text/javascript; charset=utf-8`,
+ *   `X-Content-Type-Options: nosniff`, and
+ *   `Cache-Control: public, max-age=31536000, immutable`. Unknown hashes
+ *   return controlled `404`; syntactically valid but not currently retained
+ *   hashes return `410`; neither redirects to latest. CORS/CSP policy is
+ *   application-configured: this router sets no `Access-Control-*` headers
+ *   and grants no broad credentialed access. Documented host requirements:
+ *   serve metadata/modules over the pinned `publicOrigin`, allow
+ *   `script-src` for the module URLs, and configure CORS only as the
+ *   application requires (same-origin by default; cross-origin deployments
+ *   must explicitly allow `GET` metadata/module fetches which use
+ *   `cache: no-store`, `credentials: omit`, `redirect: error`).
+ * - Asset generation is bounded by the retained snapshot (max 16 keys) plus
+ *   fixed runtime (512 KiB) / module (8 KiB) / metadata (4096 byte) caps.
+ *   Key modules are derived deterministically per request from the current
+ *   snapshot; no unbounded retired-asset cache is kept. Dropping a retired
+ *   key's asset is safe because the client performs at most one bounded
+ *   discovery refetch on a module-phase retirement race.
+ *
+ * Runbook: prepare new material on **all** verifiers, publish current
+ * metadata/module, retain old material to its explicit deadline, retire only
+ * after overlap. Old modules remain usable while their keys are retained.
+ * Public asset caching does not make distributed material confidential.
+ *
+ * No timers, network requests, or storage work at construction. Per-request
+ * provider waits are bounded by `operationTimeoutMs` (default 5000 ms);
+ * late settlement cannot resume the request.
+ */
+
+/**
+ * Create the relative signer-asset router. The caller mounts it at
+ * `basePath` (for example `app.use('/attestation', router)`); this factory
+ * never mounts itself. All external URLs are built from trusted
+ * configuration (`publicOrigin` + `publicPathPrefix` + `basePath`), never
+ * from request headers.
+ */
+declare function createSignerBundleRouter(options: CreateSignerBundleRouterOptions): Router;
+
+/**
+ * SHA-256 hex digest of the exact submitted body bytes. An actually empty
+ * request hashes zero bytes (`EMPTY_BODY_SHA256_HEX`). The signed bytes and
+ * the captured bytes must be the same representation (parser capture uses
+ * `inflate: false`; identity/no content-encoding only).
+ */
+declare function hashBodySha256Hex(body: Uint8Array): string;
+/**
+ * Derive the opaque replay key `att:v1:` + SHA-256 hex of
+ * `JSON([replayNamespace, publicOrigin, nonceHex])`. The key carries no
+ * instance ID, path, token, session, or key ID, so nonce single-use spans
+ * accepted rotations in one protection space.
+ */
+declare function deriveAttestationReplayKey(input: {
+    readonly replayNamespace: string;
+    readonly publicOrigin: string;
+    readonly nonceHex: string;
+}): string;
+
+export { type AttestationBodyCapture, type AttestationBodyCaptureWithRecord, type AttestationBodyRecord, AttestationCapacityError, type AttestationDiagnosticEvent, type AttestationDiagnosticHook, AttestationError, type AttestationErrorCode, type AttestationKeyEntry, type AttestationKeyProvider, type AttestationKeySnapshot, type AttestationKeySnapshotInput, AttestationMongoStoreError, type AttestationRedisClient, AttestationRedisStoreError, type AttestationRotatingKeyProvider, type AttestationStore, type AttestationStoreReserveInput, type AttestationStoreReserveResult, type AttestationVerifiedProof, type AttestationVerifyInput, type CreateAttestationBodyCaptureOptions, type CreateMemoryAttestationStoreOptions, type CreateMongoAttestationStoreOptions, type CreateRedisAttestationStoreOptions, type CreateRequestAttestationMiddlewareOptions, type CreateRequestAttestationMiddlewareOptionsWithDiagnostic, type CreateSignerBundleRouterOptions, MONGO_ATTESTATION_STORE_DEFAULT_CAPACITY_COLLECTION, MONGO_ATTESTATION_STORE_DEFAULT_MAX_ENTRIES, MONGO_ATTESTATION_STORE_DEFAULT_PROOFS_COLLECTION, type MongoAttestationStoreCollection, type MongoAttestationStoreDb, type MongoAttestationStoreSession, ProofTiming, REDIS_ATTESTATION_STORE_DEFAULT_KEY_PREFIX, REDIS_ATTESTATION_STORE_DEFAULT_MAX_ENTRIES, ResolvedTimePolicy, assertAllowedContentEncoding, checkProofTiming, copyAttestationSnapshot, createAttestationBodyCapture, createMemoryAttestationStore, createMongoAttestationStore, createRedisAttestationStore, createRequestAttestationMiddleware, createRotatingKeyProvider, createSignerBundleRouter, createStaticKeyProvider, deriveAttestationReplayKey, deriveReplayKey, generateAttestationKey, getAttestationBodyRecord, hashBodySha256Hex, isAttestationError, resolveContentType, resolveRequestTarget, toAttestationErrorPayload, verifyAttestationProof };