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

package/signer.d.ts

@@ -1,16 +1,14 @@
-import { H as RequestSignerOptions, F as RequestSigner } 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, P as ProofTiming, B as ProofTimingDecision, C as REPLAY_KEY_PREFIX, R as ResolvedTimePolicy, 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 { H as RequestSignerOptions, F as RequestSigner } 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, P as ProofTiming, B as ProofTimingDecision, C as REPLAY_KEY_PREFIX, R as ResolvedTimePolicy, 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';
 
 /**
- * ATT-06 typed browser client failures (task sections 4.1/4.6).
+ * Typed browser preparation and signer-loading failures.
  *
- * Browser-safe ONLY: no Node built-ins, Express/Redis types, `Buffer`,
- * `NodeJS`, or `node:*` imports. This module is part of the `./signer`
- * closure typechecked by `tsconfig.signer-browser.json` (`types: []`).
+ * Available from the browser-safe `/signer` entry without server dependencies.
  *
  * These are LOCAL preparation/loading errors. Server rejections arrive as
- * HTTP responses with section 4.5 codes; only a pre-handler stale-key marker
- * plus 403 triggers one reload/re-sign retry (ATT-07). Public HMAC material
+ * HTTP responses; only a pre-handler stale-key marker plus 403 triggers one
+ * reload/re-sign retry in `fetchWithAttestation`. Public HMAC material
  * delivered in JavaScript remains accessible to every caller despite
  * non-extractable `CryptoKey` wrapping; this error taxonomy does not imply
  * device or browser authenticity.
@@ -38,12 +36,10 @@ declare class SignerClientError extends Error {
 declare function isSignerClientError(error: unknown): error is SignerClientError;
 
 /**
- * ATT-06 browser WebCrypto request signer (task sections 4.1/4.2/4.6).
+ * Browser WebCrypto request signer.
  *
- * Browser-safe ONLY: this module and everything it imports (`src/shared/*`,
- * `./client-errors.js`) must never import Express, Redis, `Buffer`, `NodeJS`,
- * or `node:*` values or types. Typechecked by
- * `tsconfig.signer-browser.json` with `types: []`.
+ * Import from `@web-ts-toolkit/express-request-attestation/signer`; no Node,
+ * Express, Redis, or MongoDB dependencies/types are required.
  *
  * `createRequestSigner({ keyId, key, publicOrigin, replayNamespace })`
  * copies and validates 32-byte material, then returns the typed
@@ -52,7 +48,7 @@ declare function isSignerClientError(error: unknown): error is SignerClientError
  * (`buildMacInputBytes`) and returns the transaction ID
  * (`encodeTransactionId`). With explicit timestamp/nonce/body hash the
  * operation is deterministic; automatic nonce/timestamp selection belongs to
- * ATT-07's request wrapper, never to this low-level API.
+ * `fetchWithAttestation`, never to this low-level API.
  *
  * Key handling:
  *
@@ -63,6 +59,8 @@ declare function isSignerClientError(error: unknown): error is SignerClientError
  *   { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])`. Non-extractable
  *   wrapping does NOT make publicly delivered material confidential: any
  *   caller that can fetch the module can sign fresh proofs.
+ *   Concurrent calls share the import; a rejected import is cleared so a
+ *   later explicit signing attempt can recover.
  * - Required capabilities (`TextEncoder`, `crypto.subtle`,
  *   `crypto.getRandomValues`, secure context) are feature-detected ON USE,
  *   never at import. Importing this module performs no network requests,
@@ -87,20 +85,26 @@ declare function generateNonceHex(): string;
  * material and returns immutable protection-space binding plus
  * `sign(input)`. The HMAC key is imported lazily (non-extractable) on first
  * `sign`; the factory itself performs no crypto, network, timer, or storage
- * work.
+ * work. Concurrent calls share the import. Import failure rejects with
+ * `SignerClientError`; a later `sign` call can retry the import. Callers supply
+ * timestamp, nonce, final Content-Type, and exact body digest themselves;
+ * prefer `fetchWithAttestation` for automatic preparation and fresh proofs.
+ * Public HMAC material remains accessible to every caller and does not
+ * authenticate a user/session. Invalid options throw `AttestationProtocolError`;
+ * missing WebCrypto capability and crypto failure use SIGNER_PREPARATION_FAILED.
  */
 declare function createRequestSigner(options: RequestSignerOptions): RequestSigner;
 
 /**
- * ATT-06 generation-aware ESM signer client (task sections 4.1/4.6).
+ * Generation-aware ESM signer discovery and loading.
  *
- * Browser-safe ONLY: no Node built-ins, Express/Redis types, `Buffer`,
- * `NodeJS`, or `node:*` imports. Part of the `./signer` closure typechecked
- * by `tsconfig.signer-browser.json` (`types: []`).
+ * Browser-safe: import from `@web-ts-toolkit/express-request-attestation/signer`.
+ * Requires standard Fetch/byte-stream APIs; no server dependencies or Node types.
  *
  * - `fetchSignerBundle({ metadataUrl, apiOrigin, replayNamespace, fetch?,
  *   loadModule?, signal? })` fetches bounded discovery metadata
- *   (`4096`-byte cap) with noncached, credential-omitting, redirect-rejecting
+ *   (`4096`-byte incremental cap, 5000 ms response-body read deadline) with
+ *   noncached, credential-omitting, redirect-rejecting
  *   defaults, validates origin/namespace/version, resolves the key-specific
  *   asset URL against the metadata location, and loads it through native
  *   dynamic `import()` (default) or an injectable typed loader. No `eval`,
@@ -112,20 +116,22 @@ declare function createRequestSigner(options: RequestSignerOptions): RequestSign
  *   loadModule?, loadTimeoutMs? })` owns at most one active signer and one
  *   in-flight load (single-flight within this context, no cross-tab claim).
  *   `invalidate(observedKeyId)` is generation-aware: a late rejection for an
- *   old key never evicts a newer signer. `dispose()` is terminal. Failure
- *   clears the rejected load so a later explicit call can recover. A late
+ *   old key never evicts a newer signer or its pending replacement, including
+ *   challenges from multiple rotations ago. `dispose()` is terminal.
+ *   Failure clears the rejected load so a later explicit call can recover. A late
  *   old-generation result never installs. One metadata-to-module retirement
- *   race may refetch discovery once; repeated failure stops. Timeout/abort
- *   stops waiting; native import evaluation is not cancellable, so late
- *   results are discarded without claiming rollback of module execution.
+ *   race may refetch discovery once; a changed validated module URL can recover
+ *   even under the same key ID, while unchanged identity/repeated failure stops.
+ *   Timeout stops waiting; disposal signals current metadata cancellation and
+ *   prevents late installation. Native import evaluation is not cancellable,
+ *   so discarding late results does not roll back module execution.
  * - Runtime module-cache retention is documented: invalidation cannot erase
  *   the browser module cache or guarantee immediate key deletion from RAM.
  *   Publicly distributed HMAC material remains accessible to every caller.
  *
  * No storage API, cookies, DOM mutation, global network patch, import-time
- * requests, or polling timers. One-shot load timeouts use a single
- * `setTimeout` per load with cleanup (`sideEffects: false` still holds:
- * timers exist only while a load is in flight).
+ * requests, or polling timers. Load/read deadlines and the reader's cooperative
+ * yield timer exist only during the operation and are cleaned up on settlement.
  */
 
 /** Bounded discovery metadata body: at most 4096 UTF-8 bytes. */
@@ -136,47 +142,105 @@ declare const DEFAULT_SIGNER_LOAD_TIMEOUT_MS: 5000;
 interface SignerModule {
     readonly signer: RequestSigner;
 }
-/** Typed native ESM loader. Tests/host bundlers inject a fixture loader. */
+/** Loads a validated absolute module URL; defaults to native dynamic import, whose execution is not cancellable. */
 type SignerModuleLoader = (moduleUrl: string) => Promise<SignerModule>;
-/** Options for `fetchSignerBundle` (single metadata + import attempt). */
+/**
+ * Options for one discovery/import attempt. Metadata must have a readable byte
+ * stream (standard `Response`); whole-value-only fetch substitutes are rejected.
+ * Body consumption is capped at 4096 bytes and 5000 ms after the response arrives.
+ * This deadline excludes waiting for headers and module import/evaluation.
+ */
 interface FetchSignerBundleOptions {
+    /** Absolute metadata URL on `apiOrigin`, without userinfo; typically `/attestation/signer-meta` at that origin. */
     readonly metadataUrl: string;
+    /** Pinned canonical HTTPS origin (loopback HTTP allowed); metadata and module origins must match. */
     readonly apiOrigin: string;
+    /** Expected namespace, matching both verifier and imported signer. */
     readonly replayNamespace: string;
+    /** Default global fetch; called with no-store/omit/error and must return a readable byte-stream Response. */
     readonly fetch?: typeof fetch;
+    /** Default native dynamic import; receives a validated absolute `.mjs` URL. Host owns module CORS/CSP. */
     readonly loadModule?: SignerModuleLoader;
+    /** Signals cancellation to discovery fetch/body reading, not native module evaluation. */
     readonly signal?: AbortSignal;
 }
-/** Options for `createSignerClient`. */
+/** Pinned discovery configuration for a caller-owned, single-flight signer client. */
 interface SignerClientOptions {
+    /** Absolute discovery URL on `apiOrigin`, without userinfo; usually `${apiOrigin}/attestation/signer-meta`. */
     readonly metadataUrl: string;
+    /** Canonical API origin, identical to the server's configured `publicOrigin`. */
     readonly apiOrigin: string;
+    /** Pinned protection-space namespace. Recreate/reconfigure clients when migrating namespaces. */
     readonly replayNamespace: string;
+    /** Default global fetch; discovery omits credentials, rejects redirects, and requires a byte-stream Response. */
     readonly fetch?: typeof fetch;
+    /** Default native dynamic import. Timeout/disposal stops waiting or installation, not module execution/cache. */
     readonly loadModule?: SignerModuleLoader;
+    /**
+     * Whole load: headers, body reads, import, and one retirement refetch.
+     * Default 5000 ms; integer range 1–60000. Expiry is SIGNER_LOAD_TIMEOUT.
+     * There is no additional standalone 5000 ms body deadline inside client loads.
+     */
     readonly loadTimeoutMs?: number;
 }
-/** Minimal owned signer-client surface. */
+/** One active signer and one current pending load per client; no cross-tab sharing. */
 interface SignerClient {
+    /** Cached or shared current load. A later call can recover after failure; a disposed client throws SIGNER_LOAD_FAILED. */
     getSigner(): Promise<RequestSigner>;
+    /**
+     * Invalidate the observed installed key, or supersede an initial load. A
+     * different active key and malformed IDs are ignored. Pending replacements
+     * and their explicit recovery coalesce challenges from any older issued key,
+     * including multiple rotations behind. An installed same-key signer can be
+     * invalidated again. The next `getSigner()` starts/shares the replacement.
+     */
     invalidate(observedKeyId: string): void;
+    /** Terminal and idempotent: signals current metadata cancellation and prevents late installation; native import/cache persists. */
     dispose(): void;
 }
 /**
- * Bounded discovery fetch plus native dynamic import (single attempt, no
- * retirement refetch). Use `createSignerClient` when the one allowed
- * metadata-to-module retirement refetch is required.
+ * Incremental discovery (4096 bytes, fixed 5000 ms body-read deadline after
+ * the response arrives), then native dynamic import. Exceeding the cap/deadline
+ * or aborting discovery cancels its reader without awaiting producer cleanup
+ * and rejects with `SignerClientError` (`SIGNER_LOAD_FAILED`).
+ * Non-OK discovery responses discard their bodies without reading error payloads
+ * or awaiting cancellation, preserving the fixed metadata-fetch failure.
+ *
+ * The read deadline excludes the wait for response headers and module import.
+ * Use `signal` to abort native discovery fetch/read; it cannot cancel native
+ * module evaluation. Use `createSignerClient` for a configurable whole-load
+ * waiting bound and the one allowed metadata-to-module retirement refetch.
+ * Discovery defaults to global fetch with no-store/omit/error; module loading
+ * defaults to native dynamic import. Metadata and module must match the pinned
+ * API origin, namespace, version, and key. Native module CORS/CSP/cache rules
+ * apply independently of the discovery fetch options.
  */
 declare function fetchSignerBundle(options: FetchSignerBundleOptions): Promise<SignerModule>;
-/** Create the generation-aware single-flight signer client. */
+/**
+ * Create a caller-owned, generation-aware single-flight signer client. No I/O
+ * starts until `getSigner()`. One active signer and one current pending load
+ * are retained; concurrent callers share that load. Replacement/recovery is
+ * preserved across stale challenges from any older issued key, including
+ * multiple rotations behind. No historical key map or cross-tab state is kept.
+ *
+ * `loadTimeoutMs` bounds the whole headers/body/import/refetch wait (default
+ * 5000 ms, integer range 1–60000); expiry rejects with SIGNER_LOAD_TIMEOUT.
+ * Module-phase failure may refetch discovery once and reload only when the
+ * validated `(keyId, absolute module URL)` changes, including a same-key URL
+ * change. Unchanged identity or a second module failure ends that load.
+ * A later explicit `getSigner()` can recover after failure.
+ *
+ * `dispose()` is terminal and signals the current metadata fetch. Obsolete
+ * settlements cannot install a signer or alter its replacement. Timeout and
+ * disposal cannot cancel native module execution or erase its cache. This
+ * client loads public material; it does not authenticate a user or session.
+ */
 declare function createSignerClient(options: SignerClientOptions): SignerClient;
 
 /**
- * ATT-07 bounded request-body materialization (task sections 4.3/4.6).
+ * Bounded request-body materialization.
  *
- * Browser-safe ONLY: no Node built-ins, Express/Redis types, `Buffer`,
- * `NodeJS`, or `node:*` imports. Part of the `./signer` closure typechecked
- * by `tsconfig.signer-browser.json` (`types: []`).
+ * Browser-safe, using standard same-realm Request and readable byte-stream APIs.
  *
  * A `Request` body is internally a stream. This module reads supported finite
  * requests with a byte-counting reader, cancellation, and a bounded deadline
@@ -187,7 +251,8 @@ declare function createSignerClient(options: SignerClientOptions): SignerClient;
  * - `materializeRequestBodyBytes(request, { maxBodyBytes, signal, timeoutMs })`
  *   returns the exact serialized bytes for hashing and for both signed
  *   attempts. Empty (`body === null`) yields zero bytes. The reader is
- *   cancelled on limit/deadline/abort/error so no stream is left flowing.
+ *   signaled to cancel on limit/deadline/abort/error without waiting for the
+ *   producer's cancellation promise.
  * - `assertSupportedBodyInit(body)` rejects caller JSON objects (docs use
  *   `JSON.stringify`) and other non-`BodyInit` values before a `Request` is
  *   built. Supported finite values (`string`, `URLSearchParams`, `Blob`,
@@ -196,13 +261,12 @@ declare function createSignerClient(options: SignerClientOptions): SignerClient;
  *   it through a `Request` first and this module reads that request's bytes,
  *   preserving the generated multipart boundary.
  * - `FormData` boundary preservation is owned by the caller in
- *   `attested-fetch.ts`: the bytes captured here are reused verbatim for the
+ *   `fetchWithAttestation`: the bytes captured here are reused verbatim for the
  *   original attempt and the single stale-key retry, never reconstructed.
  *
  * No storage API, DOM mutation, global network patch, import-time I/O, or
- * polling timers. One-shot read deadlines use a single `setTimeout` per
- * materialization with cleanup (`sideEffects: false` still holds: timers
- * exist only while a read is in flight).
+ * polling timers. The internal reader owns a one-shot deadline and at most
+ * one cooperative-yield timer, both cleaned up when the read settles.
  */
 /** Default body budget for prepared fetch: 1 MiB (matches server default). */
 declare const DEFAULT_ATTESTED_FETCH_MAX_BODY_BYTES: number;
@@ -210,9 +274,13 @@ declare const DEFAULT_ATTESTED_FETCH_MAX_BODY_BYTES: number;
 declare const ATTESTED_FETCH_MAX_BODY_BYTES_HARD_CAP: number;
 /** Default bounded read deadline for one body materialization: 5000 ms. */
 declare const DEFAULT_ATTESTED_FETCH_BODY_READ_TIMEOUT_MS$1: 5000;
+/** Bounds for consuming one Request body; this helper does not clone its input. */
 interface MaterializeRequestBodyOptions {
+    /** Positive safe-integer byte cap; default 1 MiB, hard cap 16 MiB. Covers reader-owned bytes, not native tee queues. */
     readonly maxBodyBytes?: number;
+    /** Explicit caller signal for this read; abort preserves its exact reason. Supply `request.signal` if desired. */
     readonly signal?: AbortSignal | null | undefined;
+    /** Body-read waiting bound only; default 5000 ms, integer range 1–60000. Expiry uses SIGNER_PREPARATION_FAILED. */
     readonly timeoutMs?: number;
 }
 /**
@@ -225,26 +293,33 @@ declare function assertSupportedBodyInit(body: unknown): void;
 /**
  * Materialize the exact serialized bytes of a `Request` with a byte-counting
  * reader, caller-abort propagation, and a bounded deadline.
+ * Defaults: 1 MiB (16 MiB hard cap), 5000 ms read deadline (1–60000), and no
+ * implicit signal; pass `signal: request.signal` to follow that Request's abort.
  *
  * - `request.body === null` yields zero bytes (actually empty request).
- * - A used (`bodyUsed`) or locked body fails locally; the original `Request`
- *   should be cloned before reading when reuse is required (see
- *   `attested-fetch.ts`, which clones for reading so the caller's `Request`
- *   stays reusable when feasible).
+ * - Consumes the supplied Request; it does not clone. A used (`bodyUsed`) or
+ *   locked body fails locally. Clone before calling when reuse is required.
+ *   `fetchWithAttestation` owns that clone for inherited bodies, leaving the
+ *   caller's finite Request readable for concurrent/repeated calls. Cancelling
+ *   the clone cannot cancel a producer still owned by the original tee branch;
+ *   native tee queues are outside the reader-owned storage bound.
  * - Exceeding `maxBodyBytes` cancels the reader and throws
  *   `SIGNER_PREPARATION_FAILED` (client-side 413 analogue: never sent).
  * - Deadline expiry cancels the reader and throws
- *   `SIGNER_PREPARATION_FAILED` (stalled read). Caller abort cancels and
+ *   `SIGNER_PREPARATION_FAILED`. Caller abort cancels and
  *   throws the abort reason.
+ * - Empty chunks retain no storage; tiny chunks share a geometrically grown
+ *   buffer capped at `maxBodyBytes`. Reads check elapsed time and yield
+ *   periodically so productive streams allow deadline/abort tasks to run.
+ * - Cancellation is best-effort and never awaited; its rejection is observed.
+ *   The reader lock, abort listener, and timers are released on settlement.
  */
 declare function materializeRequestBodyBytes(request: Request, options?: MaterializeRequestBodyOptions): Promise<Uint8Array>;
 
 /**
- * ATT-07 prepared signed fetch with one stale-key retry (task sections 4.5/4.6).
+ * Prepared signed fetch with one pre-handler stale-key retry.
  *
- * Browser-safe ONLY: no Node built-ins, Express/Redis types, `Buffer`,
- * `NodeJS`, or `node:*` imports. Part of the `./signer` closure typechecked
- * by `tsconfig.signer-browser.json` (`types: []`).
+ * Browser-safe: use the `/signer` entry without Express or Node dependencies/types.
  *
  * - `fetchWithAttestation(input, init, options)` builds one immutable request
  *   snapshot from `string | URL | Request` input plus `RequestInit`. Actual
@@ -254,14 +329,18 @@ declare function materializeRequestBodyBytes(request: Request, options?: Materia
  *   `keepalive`) are preserved. Only the configured API origin is signed;
  *   unrelated origins fail locally without sending auth or signature material.
  * - The serialized body is materialized ONCE within the byte cap/read
- *   deadline (`request-body.ts`), then those same bytes plus the final content
- *   type are hashed and reused for both attempts. Normal finite `BodyInit`
+ *   deadline, then those same bytes plus the final content
+ *   type and one body digest are reused for both attempts. Normal finite `BodyInit`
  *   values and replayable `Request`s are supported; caller JSON objects must
  *   be serialized with `JSON.stringify` first. `FormData` is serialized
  *   through a `Request` first and its bytes/boundary are preserved verbatim
  *   (never reconstructed on retry, never `.arrayBuffer()` on `FormData`
  *   itself). A `Request` body uses a byte-counting reader with cancellation
- *   and timeout rather than rejecting on stream type alone.
+ *   and timeout rather than rejecting on stream type alone. Inherited bodies
+ *   are cloned before reading so finite caller Requests remain reusable,
+ *   including concurrent calls. Non-null `init.body` supplies a replacement;
+ *   `null`/`undefined` inherit the body, as in Fetch. Explicit replacement
+ *   streams transfer ownership, including aliases of the original's body.
  * - Each attempt mints one fresh 128-bit nonce (`generateNonceHex`) and one
  *   validated `now()` timestamp. Loaded signer protection space must match
  *   the allowed `apiOrigin`/`replayNamespace` before signing. The caller
@@ -269,6 +348,9 @@ declare function materializeRequestBodyBytes(request: Request, options?: Materia
  * - Signed attempts use `redirect: 'manual'`; redirect results are
  *   exposed/returned without forwarding a signature. `Content-Encoding` other
  *   than identity/absent fails locally (v1 identity-only profile).
+ * - `no-cors` and browser-forbidden proof fields fail before body/signer work
+ *   when statically known. Each constructed Request must retain the exact proof
+ *   before transport is invoked; unrestricted temporary Headers are insufficient.
  * - At most one retry, only on the pre-handler stale-key signal: expected
  *   `403` plus `X-Attestation-Error: stale-key`. The error response is
  *   inspected via headers only (never consumed), only the observed key is
@@ -276,41 +358,29 @@ declare function materializeRequestBodyBytes(request: Request, options?: Materia
  *   timestamp/nonce. A second stale challenge stops. Expired/future/replay/
  *   invalid proofs, operational `5xx`, auth failures, redirects, network
  *   uncertainty, and handler uncertainty never retry.
+ * - The first stale response remains untouched until the retry Request is
+ *   built. Reload/signing/construction failure or a repeated envelope returns
+ *   that readable response. Abandoned bodies are cancelled without awaiting
+ *   producer cleanup, with cancellation rejection observed. Caller abort stops
+ *   this invocation's preparation wait without disposing the shared signer client.
  *
- * Composition (tested in `test/fetch-client.test.ts`, documented for ATT-08):
- *
- * ```ts
- * import express from 'express';
- * import { createOidcVaultMiddleware } from '@web-ts-toolkit/express-oidc-vault';
- * import {
- *   createAttestationBodyCapture,
- *   createRequestAttestationMiddleware,
- * } from '@web-ts-toolkit/express-request-attestation';
- *
- * const capture = createAttestationBodyCapture({ maxBodyBytes });
- * const guard = createRequestAttestationMiddleware({ publicOrigin, replayNamespace, keyProvider, store });
- * const app = express();
- * // Vault router owns its base path: mount once, never double-prefix.
- * app.use(createOidcVaultMiddleware({ basePath: '/auth/oidc', backendOrigin, storeProvider, config }));
- * // Capture JSON bytes before both validators on selected API routes only.
- * app.use(express.json({ limit: maxBodyBytes, verify: capture.verify, inflate: false }));
- * app.use(capture.errorHandler);
- * app.post('/api/submit', guard, requireBearerAuth, handler);
- * // Asset/OPTIONS/OIDC navigation/callback/backchannel routes stay reachable
- * // under their own policies; the guard never enrolls DPoP bindings or
- * // rewrites `req.auth`, and every auth refresh re-signs via a fresh wrapper call.
- * ```
+ * Application auth retries call this wrapper again for a fresh proof. The
+ * server guard never establishes or rewrites authentication. Auth-before-guard
+ * avoids replay allocation for rejected credentials; guard-first can reject
+ * bad proofs before auth work but reserves even if later auth fails. Durable
+ * business idempotency and retry decisions remain application-owned.
  *
- * Browser CORS/CSP (application-configured, verified in tests):
+ * Browser CORS/CSP (application-configured):
  *
  * - Allow the configured signature field plus actual `Content-Type`,
  *   `Authorization`/DPoP headers as needed; expose `X-Attestation-Error` so
  *   the wrapper can see the retry marker; allow credentialed origins only when
  *   the application explicitly uses `credentials: 'include'`.
- * - Native module imports require `script-src` + CORS for the public module
- *   URLs. Same-origin uses the native default; cross-origin deployments must
- *   explicitly configure CORS for metadata/module fetches (which use
- *   `cache: no-store`, `credentials: omit`, `redirect: error`).
+ * - Native module imports require `script-src` + CORS for key and runtime URLs;
+ *   metadata/API fetches need suitable `connect-src`. Discovery uses
+ *   no-store/omit/error, while dynamic imports follow native module rules.
+ *   Asset modules must not redirect to other origins. Let OPTIONS reach the
+ *   application's CORS handler before the server attestation guard.
  *
  * Public HMAC material stays accessible to every caller despite
  * non-extractable `CryptoKey` wrapping; this wrapper provides request-format
@@ -321,30 +391,63 @@ declare function materializeRequestBodyBytes(request: Request, options?: Materia
 declare const DEFAULT_ATTESTED_FETCH_BODY_READ_TIMEOUT_MS: 5000;
 /** Options for `fetchWithAttestation` (all validation is strict). */
 interface FetchWithAttestationOptions {
-    /** Generation-aware signer client (ATT-06). Required, retained by reference. */
+    /** Caller-owned shared signer client, retained by reference; abort never disposes it. */
     readonly signerClient: SignerClient;
     /** Pinned API origin; only this origin is signed. Required. */
     readonly apiOrigin: string;
     /** Protection-space namespace; must match the loaded signer. Required. */
     readonly replayNamespace: string;
-    /** Injected fetch (preferred name, matches task text). Defaults to global fetch. */
+    /** API transport, default global fetch. Must honor the Request signal; no package transport deadline or uncertain retry. */
     readonly fetch?: typeof fetch;
-    /** Alias for `fetch` (matches ATT-01 scaffold). At most one may be set. */
+    /** Compatibility alias for `fetch`; set at most one of the two options. */
     readonly fetchFn?: typeof fetch;
-    /** Signature header field. Defaults to `x-client-transaction-id`. */
+    /**
+     * Signature field, default `x-client-transaction-id`. Shared HTTP validation
+     * rejects malformed/reserved names with `AttestationProtocolError`. Otherwise
+     * valid browser-forbidden fields (including `sec-*`, `proxy-*`, `Cookie2`, and
+     * `User-Agent`) fail locally with `SIGNER_PREPARATION_FAILED` before body
+     * preparation or signer work. The field must be writable by browser Fetch.
+     */
     readonly headerName?: string;
     /** Body budget, default 1 MiB, hard cap 16 MiB. Must match server/parser limits. */
     readonly maxBodyBytes?: number;
-    /** Bounded body-read deadline, default 5000 ms, allowed 1–60000 ms. */
+    /** Body-read deadline only, default 5000 ms (integer 1–60000); distinct from signer load and API transport waits. */
     readonly bodyReadTimeoutMs?: number;
-    /** Epoch-millisecond clock for per-attempt timestamps. Defaults to `Date.now`. */
+    /** Per-attempt clock, default `Date.now`; must return nonnegative safe-integer epoch milliseconds. */
     readonly now?: () => number;
 }
 /**
  * Prepare one immutable request snapshot, sign the exact bytes sent, and
- * retry at most once on the pre-handler stale-key marker.
+ * retry at most once on `403` plus `X-Attestation-Error: stale-key`. Only the
+ * pinned API origin is signed; Authorization/credentials follow native Fetch
+ * options, and signed attempts always use manual redirects. Body bytes and
+ * their digest are reused, with a fresh nonce/timestamp on each attempt.
+ *
+ * After general option validation, `no-cors` and browser-forbidden fields reject with
+ * `SIGNER_PREPARATION_FAILED` before body/signer work when statically known.
+ * `init.mode` is sampled once before `init.body`; an undefined mode inherits the
+ * Request's mode (or Fetch's default). Supported `cors`/`same-origin` settings
+ * are preserved. Every constructed attempt must retain the exact proof.
+ *
+ * Inherited finite Request bodies are cloned, leaving the original readable for
+ * concurrent/repeated calls. Non-null `init.body` overrides even used/locked
+ * originals; `null`/`undefined` inherit and require an unused, unlocked body.
+ * Explicit stream bodies (even aliases of the original's body) transfer reading/
+ * cancellation ownership after native construction succeeds. The byte cap covers
+ * reader-owned storage, not native tee queues retained for the caller's original
+ * Request. Reuse refers to the original Request's current body, not the identity
+ * of a raw stream reference saved before native cloning. Construction failure
+ * leaves an unaccepted explicit stream caller-owned.
  *
- * See the module header for the full preparation/retry/composition contract.
+ * Reload/signing/retry-construction failure or a repeated envelope returns the
+ * untouched first stale response. Only a prepared retry (or caller abort)
+ * abandons it; cancellation is nonblocking with rejection observed. Caller abort
+ * stops waiting for preparation, without disposing the shared signer client or
+ * cancelling native module/crypto execution, and rejects with the caller's exact
+ * reason. Dispatched readers belong to native Fetch/the injected transport,
+ * which must honor the forwarded signal. Transport errors never retry. Every
+ * separate application auth/business retry needs a fresh wrapper call; public
+ * HMAC is not authentication or durable business idempotency.
  */
 declare function fetchWithAttestation(input: RequestInfo | URL, init: RequestInit | undefined, options: FetchWithAttestationOptions): Promise<Response>;