@web-ts-toolkit/express-request-attestation 0.51.0 → 0.53.0

package/index.d.ts

@@ -1,27 +1,28 @@
-import { P as ProofTiming, R as ResolvedTimePolicy } from './time-policy-DlER-7rf.js';
-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.js';
+import { P as ProofTiming, R as ResolvedTimePolicy } from './time-policy-CquS0Zgm.js';
+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-CquS0Zgm.js';
 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.
+ * Server-side key, replay-store, and Express integration contracts, exported
+ * from `@web-ts-toolkit/express-request-attestation`. Browser consumers use
+ * the separate `/signer` entry, which needs no server dependencies or types.
  */
 /** One accepted key: exactly 32 bytes with an explicit acceptance window. */
 interface AttestationKeyEntry {
+    /** Unique provisioning ID matching `[A-Za-z0-9_-]{1,64}`; never remap a live ID. */
     readonly keyId: string;
     /** Exactly 32 bytes; snapshots are owned/copy-isolated. */
     readonly key: Uint8Array;
-    /** Nonnegative safe-integer epoch ms; `acceptFrom < acceptUntil`. */
+    /** Inclusive activation, nonnegative safe-integer epoch ms; less than `acceptUntil`. */
     readonly acceptFrom: number;
+    /** Exclusive retirement in epoch ms. Identical for this ID on every verifier in the protection space. */
     readonly acceptUntil: number;
 }
 /** Keyring snapshot returned by `AttestationKeyProvider.getSnapshot()`. */
 interface AttestationKeySnapshot {
-    /** Must name a present active entry. At most 16 retained keys. */
+    /** Names a present entry; discovery additionally requires it active at its post-provider clock. */
     readonly currentKeyId: string;
+    /** 1–16 retained entries, with identical material/windows across the protection space. */
     readonly keys: readonly AttestationKeyEntry[];
 }
 /** Input snapshot for static/rotating providers (owned/copied on entry). */
@@ -36,61 +37,87 @@ interface AttestationKeySnapshotInput {
 }
 /**
  * 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.
+ * of one). Provider throws, rejected reads, malformed snapshots, and timeouts
+ * become fixed `503 ATTESTATION_KEYS_UNAVAILABLE`, without a stale-key marker.
+ * External cron/KMS/config code owns provisioning, refresh, and dependency
+ * deadlines; there is no polling timer or cancellation of underlying work.
  */
 interface AttestationKeyProvider {
     getSnapshot(): AttestationKeySnapshot | Promise<AttestationKeySnapshot>;
 }
-/** Rotating provider with explicit atomic replacement (ATT-05). */
+/** Rotating provider with explicit atomic replacement and copy-isolated reads. */
 interface AttestationRotatingKeyProvider extends AttestationKeyProvider {
+    /** Rejects invalid/remapped retained IDs atomically; does not cancel requests using an earlier snapshot. */
     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). */
+    /**
+     * Absolute safe-integer epoch-ms deadline:
+     * `min(timestampMs + maxAgeMs + clockSkewMs, key.acceptUntil) + clusterClockGuardMs`.
+     * Retain until this deadline; never clamp it or extend it on a duplicate.
+     */
     readonly retainUntilMs: number;
 }
+/** One atomic admission: inserted, already live (no extension), or deadline already elapsed. */
 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.
+ * on capacity exhaustion or unavailability. Verify proofs before reserving;
+ * the store does not verify signatures. Successful or possibly committed
+ * reservations are never released on handler failure, timeout, or lost response.
+ * Shared verifiers must use identical time policies and key acceptance windows.
+ * Direct calls have no package-level wait timeout; callers own driver deadlines.
  */
 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.
+ * Narrow structural Redis client contract. Inject an already-connected compatible
+ * client (for example `node-redis`). The caller owns connection, error listeners,
+ * command/queue deadlines, and shutdown; this package never imports a driver.
  */
 interface AttestationRedisClient {
     sendCommand(args: string[]): Promise<unknown>;
 }
-/** Options for `createRequestAttestationMiddleware` (implemented in ATT-02). */
+/**
+ * Express guard configuration. All guards in one `(publicOrigin, replayNamespace)`
+ * share replay state, identical time policies, and identical per-key acceptance
+ * windows. Migrate live policy changes to a new namespace rather than mixing
+ * policies or extending old key deadlines over already-admitted proofs.
+ */
 interface CreateRequestAttestationMiddlewareOptions {
-    /** Static canonical HTTPS origin (loopback http allowed in development). */
+    /** Static canonical HTTPS origin (loopback HTTP allowed); never derive from request headers. */
     readonly publicOrigin: string;
+    /** Protection-space identifier matching `[A-Za-z0-9_-]{1,128}`; must match signers. */
     readonly replayNamespace: string;
-    /** Upstream-stripped prefix to re-prepend after `req.originalUrl`. */
+    /** Upstream-stripped prefix to prepend to `req.originalUrl`; default empty, no trailing slash. */
     readonly publicPathPrefix?: string;
+    /** Caller-owned live provider; each request validates and copies its bounded snapshot. */
     readonly keyProvider: AttestationKeyProvider;
+    /** Atomic shared nonce admission after successful verification; no fallback on store failure. */
     readonly store: AttestationStore;
+    /** Maximum proof age, default 30000 ms; safe integer in 1000–120000. */
     readonly maxAgeMs?: number;
+    /** Client clock allowance, default 5000 ms; safe integer in 0–30000. */
     readonly clockSkewMs?: number;
+    /** Maximum pairwise verifier/store clock difference, default 5000 ms (0–30000); retention only. */
     readonly clusterClockGuardMs?: number;
+    /** Single proof header; default `x-client-transaction-id`. Must pass shared HTTP name validation. */
     readonly headerName?: string;
+    /** Default `Date.now`; every call must return nonnegative safe-integer epoch ms or the guard fails with 500. */
     readonly now?: () => number;
-    /** Bounds async provider/store waits; default 5000 ms. */
+    /**
+     * Each async provider/store wait, default 5000 ms; integer range 1–60000.
+     * Does not cancel underlying work. Configure driver deadlines separately;
+     * a timed-out reservation may commit but can never resume the handler.
+     */
     readonly operationTimeoutMs?: number;
 }
-/** Options for `createAttestationBodyCapture` (implemented in ATT-02). */
+/** Exact-byte capture for Express parsers; use the same limit and `inflate: false` on the parser. */
 interface CreateAttestationBodyCaptureOptions {
     /** Parser/body budget, default 1 MiB, hard cap 16 MiB. */
     readonly maxBodyBytes?: number;
@@ -98,35 +125,51 @@ interface CreateAttestationBodyCaptureOptions {
 /**
  * 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.
+ * handler mapping parser size/encoding failures to fixed 413/415 errors.
+ * These callbacks assign directly to Express parser/error-handler types.
  */
 interface AttestationBodyCapture {
+    /** Attach as the parser's `verify` callback; observes bytes without changing `req.body`. */
     readonly verify: (req: unknown, res: unknown, body: unknown, encoding: string) => void;
+    /** Mount after parsers and before the guard; other parser errors pass to `next(err)`. */
     readonly errorHandler: (err: unknown, req: unknown, res: unknown, next: (err?: unknown) => void) => void;
 }
-/** Options for `createSignerBundleRouter` (implemented in ATT-05). */
+/** Trusted asset-distribution configuration; the caller owns mounting, CORS, and CSP. */
 interface CreateSignerBundleRouterOptions {
+    /** Static canonical HTTPS origin (loopback HTTP allowed); never derived from Host/Forwarded headers. */
     readonly publicOrigin: string;
+    /** Protection-space namespace matching the verifier and browser client. */
     readonly replayNamespace: string;
+    /** Caller-owned provider; discovery publishes only the current key active after the provider read. */
     readonly keyProvider: AttestationKeyProvider;
-    /** Relative mount base path used only to publish external URLs. */
+    /**
+     * Default `/attestation`. Mount the relative router at this path yourself.
+     * `/` publishes `/signer-meta`, `/signer.<hash>.mjs`, and `/runtime.<hash>.mjs`.
+     */
     readonly basePath?: string;
+    /** Prefix stripped by the upstream proxy, default empty; prepend once to published URLs, not the app mount. */
     readonly publicPathPrefix?: string;
+    /** Default `Date.now`; nonnegative safe-integer epoch ms, checked before and after discovery's provider read. */
     readonly now?: () => number;
+    /** Per-provider wait bound, default 5000 ms (1–60000); does not cancel provider work. Timeout returns fixed 503. */
     readonly operationTimeoutMs?: number;
 }
-/** Options for `createMemoryAttestationStore` (implemented in ATT-03). */
+/** Process-local replay storage, shared only by callers reusing the same store object. */
 interface CreateMemoryAttestationStoreOptions {
+    /** Positive safe-integer capacity; default 50000. Live entries are never evicted. */
     readonly maxEntries?: number;
+    /** Default `Date.now`; nonnegative safe-integer epoch ms, synchronized with verifier clocks. */
     readonly now?: () => number;
 }
-/** Options for `createRedisAttestationStore` (implemented in ATT-04). */
+/** Shared Redis replay ledger; the caller owns the connected client and dependency deadlines. */
 interface CreateRedisAttestationStoreOptions {
     readonly client: AttestationRedisClient;
+    /** Default `wtt-attestation`; 1–256 characters. All instances in a protection space share this ledger prefix. */
     readonly keyPrefix?: string;
+    /** Positive safe-integer capacity; default 50000, identical for every client sharing the prefix. */
     readonly maxEntries?: number;
 }
-/** Fixed section 4.5 error codes with their HTTP status and message. */
+/** Fixed verifier error codes; `AttestationError` supplies the stable 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
@@ -146,32 +189,51 @@ declare function toAttestationErrorPayload(error: AttestationError): {
     readonly message: string;
 };
 
+/** Sanitized failure observation; excludes request/key/body/provider diagnostics. */
 interface AttestationDiagnosticEvent {
     readonly code: AttestationErrorCode;
     readonly status: number;
 }
 type AttestationDiagnosticHook = (event: AttestationDiagnosticEvent) => void;
 type CreateRequestAttestationMiddlewareOptionsWithDiagnostic = CreateRequestAttestationMiddlewareOptions & {
+    /** Optional synchronous observation of fixed code/status only; hook failure never changes admission. */
     readonly onDiagnostic?: AttestationDiagnosticHook;
 };
 /**
  * Create the verify-before-reserve Express guard.
  *
+ * Mount after exact-byte parser capture and its error handler on selected API
+ * routes. The returned function assigns directly to `express.RequestHandler`.
+ * Missing/empty proofs fail with 403 ATTESTATION_MISSING; duplicate, comma-joined,
+ * oversized, or noncanonical proofs and raw duplicate Content-Type fields fail
+ * with 403 ATTESTATION_MALFORMED before provider/replay work. Only a stale-key failure
+ * carries `X-Attestation-Error: stale-key`; all provider read/snapshot failures
+ * use fixed 503 ATTESTATION_KEYS_UNAVAILABLE without that marker.
+ *
  * 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.
+ * committed reservation. Driver/provider cancellation and deadlines stay caller-owned.
+ *
+ * Public HMAC material does not authenticate a user/session. Auth before this
+ * guard can avoid replay allocation for unauthorized requests; guard-first can
+ * reject invalid proofs before auth work but reserves even if later auth fails.
+ * Reservations remain committed after downstream failure. Durable business
+ * idempotency and authorization are application responsibilities.
  */
 declare function createRequestAttestationMiddleware(options: CreateRequestAttestationMiddlewareOptionsWithDiagnostic): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
 
+/** Frozen observation of the exact parser bytes, never reconstructed from `req.body`. */
 interface AttestationBodyRecord {
     readonly digestHex: string;
     readonly byteLength: number;
 }
 interface AttestationBodyCaptureWithRecord extends AttestationBodyCapture {
+    /** Returns a frozen copy, or undefined if no parser capture ran for this request. */
     readonly getRecord: (req: unknown) => AttestationBodyRecord | undefined;
+    /** Validated byte budget; use the same value as the parser and browser wrapper limits. */
     readonly maxBodyBytes: number;
 }
 /**
@@ -182,16 +244,22 @@ interface AttestationBodyCaptureWithRecord extends AttestationBodyCapture {
  */
 declare function getAttestationBodyRecord(req: unknown): AttestationBodyRecord | undefined;
 /**
- * Create the parser `verify` callback + narrow error mapper.
+ * Create the Express parser `verify` callback and narrow error handler.
  *
  * `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.
+ * the guard) before any replay allocation. Pass `capture.verify` directly to
+ * `express.json`/`urlencoded`/`text`/`raw`; mount `capture.errorHandler` after
+ * parsers and before the guard. The callbacks are assignable to Express types.
+ * Size/encoding failures map to fixed 413/415; other parser errors go to
+ * `next(err)`. Capture observes the bytes without mutating `req.body`.
+ * Uncaptured nonempty bodies fail at the guard with BODY_CAPTURE_REQUIRED.
  */
 declare function createAttestationBodyCapture(options?: CreateAttestationBodyCaptureOptions): AttestationBodyCaptureWithRecord;
 
+/** Low-level verifier input. Supply trusted origin/policy/key state and a digest of captured exact bytes. */
 interface AttestationVerifyInput {
     readonly headerValue: string | readonly string[] | undefined;
     readonly method: unknown;
@@ -206,6 +274,7 @@ interface AttestationVerifyInput {
     readonly replayNamespace: string;
     readonly publicOrigin: string;
 }
+/** Signature/timing verification result; no nonce has been reserved yet. */
 interface AttestationVerifiedProof {
     readonly keyId: string;
     readonly timestampMs: number;
@@ -213,6 +282,7 @@ interface AttestationVerifiedProof {
     readonly keyEntry: AttestationKeyEntry;
     readonly timing: ProofTiming;
     readonly replayKey: string;
+    /** Absolute epoch-ms replay retention deadline, including the cluster clock guard. */
     readonly retainUntilMs: number;
     readonly method: string;
     readonly requestTarget: string;
@@ -230,7 +300,7 @@ declare function checkProofTiming(input: {
 }): 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. */
+/** Single final Content-Type value. Duplicate fields/controls => MALFORMED; commas within one field are preserved. */
 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;
@@ -244,18 +314,21 @@ declare function deriveReplayKey(input: {
  * 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.
+ * Always validates the raw proof first; malformed framing cannot be bypassed
+ * with a decoded envelope. Throws fixed `AttestationError` failures. This helper
+ * neither authenticates the caller nor reserves the nonce: prefer the Express
+ * guard for atomic admission and its final timing checks around asynchronous work.
  */
 declare function verifyAttestationProof(input: AttestationVerifyInput): AttestationVerifiedProof;
 
 /**
- * ATT-03 bounded atomic memory replay store (task section 4.4).
+ * Bounded atomic memory replay store.
  *
- * Admission contract (shared with the future ATT-04 Redis adapter):
+ * Admission contract shared by the memory, Redis, and MongoDB stores:
  *
  * - `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.
+ * - `retainUntilMs` is the absolute epoch-ms deadline from verified proof timing,
+ *   including the cluster clock guard, never a relative TTL.
  * - 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
@@ -283,8 +356,7 @@ declare function verifyAttestationProof(input: AttestationVerifyInput): Attestat
 /**
  * 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.
+ * closed. All three built-in backends use this same error type.
  */
 declare class AttestationCapacityError extends Error {
     readonly name = "AttestationCapacityError";
@@ -299,27 +371,29 @@ declare class AttestationCapacityError extends Error {
  * 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.
+ * 50000 entries and never evicts live entries. Admission uses absolute
+ * `retainUntilMs`, rejects retention over 240000 ms rather than truncating it,
+ * and never extends a duplicate's deadline. Capacity throws
+ * `AttestationCapacityError`; malformed inputs/clock values throw
+ * `AttestationProtocolError`. Keep its clock synchronized with the verifier.
  */
 declare function createMemoryAttestationStore(options?: CreateMemoryAttestationStoreOptions): AttestationStore;
 
 /**
- * ATT-04 shared bounded Redis replay admission (task sections 4.1/4.4).
+ * Shared bounded Redis replay admission.
  *
- * Admission contract (shared with ATT-03 memory; see `test/store-conformance.ts`):
+ * Admission contract shared with memory and MongoDB:
  *
  * - `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.
+ * - `retainUntilMs` is the absolute epoch-ms deadline from verified proof timing,
+ *   including the cluster clock guard, never a relative TTL.
  * - 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`
+ *   admission: `retainUntilMs <= nowMs` returns
+ *   `'expired'`; `retainUntilMs - nowMs > 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
@@ -337,20 +411,18 @@ declare function createMemoryAttestationStore(options?: CreateMemoryAttestationS
  *   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).
+ *   never imports a Redis driver. Callers own command/queue deadlines and retries.
  * - 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.
+ *   mixed capacities break 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`.
+ *   without calling `next`). The adapter preserves the verifier's exact
+ *   `retainUntilMs` rather than clamping it.
  *
  * Capacity / failure / rate notes (no fabricated bytes-per-entry benchmark):
  *
@@ -361,9 +433,8 @@ declare function createMemoryAttestationStore(options?: CreateMemoryAttestationS
  * - 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).
+ *   replication appropriate to your recovery objectives; after state loss old
+ *   proofs may be admitted again while still valid under verifier age rules.
  * - 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.
@@ -390,23 +461,30 @@ declare class AttestationRedisStoreError extends Error {
  * 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.
+ * caller owns connection, listeners, command deadlines, and shutdown. Defaults:
+ * `keyPrefix: 'wtt-attestation'`, `maxEntries: 50000`. All clients sharing the
+ * prefix need identical capacity; verifiers in a protection space also need
+ * identical time policy/key windows and clocks within `clusterClockGuardMs`
+ * of Redis `TIME`.
+ *
+ * Absolute `retainUntilMs` scores never slide on duplicates; live entries are
+ * never evicted by this adapter. Capacity throws `AttestationCapacityError`,
+ * malformed inputs throw `AttestationProtocolError`, and dependency failures
+ * throw `AttestationRedisStoreError`. There is no direct-call wait timeout or
+ * retry after uncertain command execution. Eviction/state loss/failover can
+ * erase replay history; configure Redis persistence and noeviction accordingly.
  */
 declare function createRedisAttestationStore(options: CreateRedisAttestationStoreOptions): AttestationStore;
 
 /**
- * MONGO-01 MongoDB replay adapter (task sections 4.1/4.4).
+ * Bounded transactional MongoDB replay adapter.
  *
- * Admission contract (shared with memory/Redis; see `test/store-conformance.ts`):
+ * Admission contract shared with memory and Redis:
  *
  * - `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.
+ * - `retainUntilMs` is the absolute epoch-ms deadline from verified proof timing,
+ *   including the cluster clock guard, never a relative TTL.
  * - 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
@@ -424,8 +502,7 @@ declare function createRedisAttestationStore(options: CreateRedisAttestationStor
  *   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):
+ * Storage design:
  *
  * - One proof collection with unique `_id`s (`{ _id: replayKey,
  *   retainUntilMs }`) plus a separate non-TTL capacity/accounting collection
@@ -453,16 +530,14 @@ declare function createRedisAttestationStore(options: CreateRedisAttestationStor
  *   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
+ * - 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.
+ *   database. The middleware maps store failures to fixed
+ *   `ATTESTATION_REPLAY_UNAVAILABLE` without calling `next`.
  *
  * Sharing boundary: replay state is shared by all clients using the same
  * database/collections with identical `maxEntries`. Independent databases or
@@ -518,34 +593,50 @@ interface MongoAttestationStoreDb {
         startSession(): MongoAttestationStoreSession;
     };
 }
-/** Options for `createMongoAttestationStore` (MONGO-01). */
+/** Caller-owned MongoDB replica-set connection, collection pair, capacity, and clock. */
 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`. */
+    /**
+     * Default `attestation_replay_capacity`, distinct from the proof collection.
+     * Provision a non-TTL `{ kind: 1, retainUntilMs: 1 }` index before traffic.
+     * Never TTL-delete accounting rows; the adapter maintains them transactionally.
+     */
     readonly capacityCollectionName?: string;
-    /** Positive safe-integer shared capacity; default 50000. */
+    /** Positive safe-integer shared capacity; default 50000, identical for every client of this collection pair. */
     readonly maxEntries?: number;
-    /** App clock; default `Date.now`. Must stay synchronized across instances. */
+    /** Default `Date.now`; nonnegative safe-integer epoch ms, synchronized within the verifier's cluster clock guard. */
     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.
+ * Pass a `Db` from an already-connected caller-owned `MongoClient`; replica-set
+ * transactions are required. Defaults: `attestation_proofs`,
+ * `attestation_replay_capacity`, `maxEntries: 50000`, and `Date.now`.
+ * All clients of the collection pair need identical capacity and synchronized
+ * clocks; verifiers in the protection space need identical time policy/key windows.
+ *
+ * Before traffic, use the driver's `createIndex({ kind: 1, retainUntilMs: 1 })`
+ * on the capacity collection with no `expireAfterSeconds`. The factory performs
+ * no database I/O/index creation. Never add TTL cleanup to the accounting ledger.
+ * Each admission checks duplicates, reclaims at most 64 expired rows plus the
+ * requested expired key, then inserts without live eviction or duplicate extension.
+ *
+ * The caller owns connection, server-selection/command/transaction deadlines,
+ * and shutdown. Per-admission sessions belong to the adapter, but driver retries
+ * and cleanup are not bounded by the middleware's waiting timeout. Capacity
+ * throws `AttestationCapacityError`; malformed inputs use `AttestationProtocolError`;
+ * dependency/row failures use `AttestationMongoStoreError`. State loss can erase
+ * replay history; this is not durable business idempotency or a failover guarantee.
  */
 declare function createMongoAttestationStore(options: CreateMongoAttestationStoreOptions): AttestationStore;
 
 /**
- * ATT-05 owned key rotation (task sections 4.1/4.6).
+ * Owned key rotation with explicit acceptance windows.
  *
  * - `generateAttestationKey(keyId, { acceptFrom, acceptUntil })` creates one
  *   random 32-byte entry for an explicit acceptance window.
@@ -554,7 +645,7 @@ declare function createMongoAttestationStore(options: CreateMongoAttestationStor
  *   `replace(snapshot)`; external cron/KMS/config code owns provisioning and
  *   refresh. No default polling timer, no hardcoded grace policy.
  *
- * Snapshot rules (section 4.1):
+ * Snapshot rules:
  *
  * - Snapshots have `currentKeyId` plus a bounded list of 1-16 entries
  *   `{ keyId, key: Uint8Array(32), acceptFrom, acceptUntil }`.
@@ -576,7 +667,7 @@ declare function createMongoAttestationStore(options: CreateMongoAttestationStor
  *   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`).
+ *   never a stale-key client error.
  *
  * Runbook (finite acceptance, application-configured):
  *
@@ -597,7 +688,10 @@ declare function createMongoAttestationStore(options: CreateMongoAttestationStor
 
 /**
  * Create one random 32-byte key entry for an explicit acceptance window.
- * Uses `node:crypto` randomness; the returned entry owns its bytes (frozen).
+ * Uses `node:crypto` randomness. Times are nonnegative safe-integer epoch ms
+ * with inclusive `acceptFrom` and exclusive `acceptUntil`. Distribute the same
+ * entry/window to every verifier; do not generate independent per-instance keys.
+ * The entry is frozen and owns its bytes; providers copy those bytes on input.
  */
 declare function generateAttestationKey(keyId: string, window: {
     readonly acceptFrom: number;
@@ -607,6 +701,8 @@ declare function generateAttestationKey(keyId: string, window: {
  * 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.
+ * Invalid snapshots throw `AttestationProtocolError`. Retain 1–16 keys;
+ * `currentKeyId` must name a present entry, which discovery checks for activity.
  */
 declare function createStaticKeyProvider(snapshot: AttestationKeySnapshotInput): AttestationKeyProvider;
 /**
@@ -618,12 +714,14 @@ declare function createStaticKeyProvider(snapshot: AttestationKeySnapshotInput):
  * 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).
+ * version/random identifiers). All verifiers need the same material, windows,
+ * and time policy. Provision/refresh externally; replacement starts no polling
+ * and does not cancel requests already holding a previous snapshot.
  */
 declare function createRotatingKeyProvider(snapshot: AttestationKeySnapshotInput): AttestationRotatingKeyProvider;
 
 /**
- * ATT-05 relative signer-asset router (task sections 4.1/4.6).
+ * Relative signer-asset router with content-addressed public modules.
  *
  * Server-only: may import Express and Node built-ins. Never imported by the
  * `./signer` browser entry.
@@ -634,13 +732,12 @@ declare function createRotatingKeyProvider(snapshot: AttestationKeySnapshotInput
  *   `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`).
+ *   (a root `basePath: '/'` adds no extra slash before the asset name).
  *   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
+ *   ESM entry from this installed package; 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
@@ -650,11 +747,12 @@ declare function createRotatingKeyProvider(snapshot: AttestationKeySnapshotInput
  * - 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`.
+ *   current entry must be present and active at the checked clock after the
+ *   provider read; otherwise metadata fails with `503 ATTESTATION_KEYS_UNAVAILABLE`.
+ *   Invalid or throwing clocks fail with `500 ATTESTATION_INTERNAL_ERROR`.
  * - 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
+ *   `Cache-Control: public, max-age=31536000, immutable`. Malformed asset paths/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
@@ -662,14 +760,14 @@ declare function createRotatingKeyProvider(snapshot: AttestationKeySnapshotInput
  *   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`).
+ *   must explicitly allow `GET` metadata/module fetches. Discovery uses
+ *   no-store/omit/error; dynamic imports follow native module-fetch rules).
  * - 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.
+ *   key's asset must account for the client's one bounded discovery refetch
+ *   on a module-phase retirement race; repeated retirement failures end the load.
  *
  * Runbook: prepare new material on **all** verifiers, publish current
  * metadata/module, retain old material to its explicit deadline, retire only
@@ -686,7 +784,18 @@ declare function createRotatingKeyProvider(snapshot: AttestationKeySnapshotInput
  * `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.
+ * from request headers. With `basePath: '/'`, assets are directly under the
+ * origin or configured stripped prefix; their runtime imports remain relative.
+ * The default base path is `/attestation`; root URLs are `/signer-meta`,
+ * `/signer.<hash>.mjs`, and `/runtime.<hash>.mjs`. With prefix `/prefix`, those
+ * external URLs begin `/prefix/` while the app still mounts at `/`.
+ * The caller owns actual upstream stripping and CORS/CSP configuration.
+ * Discovery checks the clock before provider work and current-key eligibility
+ * after it. Inactive keys/provider failures return fixed 503 errors; invalid or
+ * throwing clocks return a fixed 500 error. Both use `Cache-Control: no-store`.
+ * `operationTimeoutMs` bounds provider waiting (default 5000 ms, range 1–60000),
+ * without cancelling underlying provider work. Assets have immutable URLs and
+ * no redirect-to-latest behavior; only discovery chooses the current active key.
  */
 declare function createSignerBundleRouter(options: CreateSignerBundleRouterOptions): Router;