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

package/signer.d.ts

@@ -0,0 +1,351 @@
+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';
+
+/**
+ * ATT-06 typed browser client failures (task sections 4.1/4.6).
+ *
+ * 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: []`).
+ *
+ * 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
+ * delivered in JavaScript remains accessible to every caller despite
+ * non-extractable `CryptoKey` wrapping; this error taxonomy does not imply
+ * device or browser authenticity.
+ *
+ * No storage API, DOM mutation, global network patch, import-time requests,
+ * or polling timers. Importing this module has no side effects
+ * (`sideEffects: false`).
+ */
+/** Typed client preparation/load failure codes. */
+type SignerClientErrorCode = 'SIGNER_LOAD_FAILED' | 'SIGNER_LOAD_TIMEOUT' | 'SIGNER_MODULE_INVALID' | 'SIGNER_ORIGIN_MISMATCH' | 'SIGNER_PREPARATION_FAILED';
+/**
+ * Typed client-side failure. Messages are actionable and never echo raw key
+ * bytes, nonces, MACs, request bodies, or provider diagnostics. Key IDs,
+ * origins, and namespaces in messages are public configuration/discovery
+ * values, never secrets.
+ */
+declare class SignerClientError extends Error {
+    readonly name = "SignerClientError";
+    readonly code: SignerClientErrorCode;
+    constructor(code: SignerClientErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/** Type guard for `SignerClientError`. */
+declare function isSignerClientError(error: unknown): error is SignerClientError;
+
+/**
+ * ATT-06 browser WebCrypto request signer (task sections 4.1/4.2/4.6).
+ *
+ * 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: []`.
+ *
+ * `createRequestSigner({ keyId, key, publicOrigin, replayNamespace })`
+ * copies and validates 32-byte material, then returns the typed
+ * `RequestSigner` (`version: 1` plus immutable protection-space binding plus
+ * `sign(input)`). `sign(input)` frames the exact shared MAC input
+ * (`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.
+ *
+ * Key handling:
+ *
+ * - Input bytes are copied on entry; later caller mutation cannot change the
+ *   signer, and the signer never exposes key bytes.
+ * - Exactly one non-extractable HMAC-SHA-256 `CryptoKey` is imported lazily
+ *   on first `sign` via `crypto.subtle.importKey('raw', copy,
+ *   { 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.
+ * - Required capabilities (`TextEncoder`, `crypto.subtle`,
+ *   `crypto.getRandomValues`, secure context) are feature-detected ON USE,
+ *   never at import. Importing this module performs no network requests,
+ *   timers, key generation, or storage access (`sideEffects: false`).
+ * - Body-hash (`hashBodySha256Hex`) and nonce (`generateNonceHex`) helpers
+ *   stay browser-safe with no `Math.random` or predictable fallback.
+ */
+
+/**
+ * Browser-safe SHA-256 hex digest of the exact body bytes. An actually empty
+ * request hashes zero bytes. Uses `crypto.subtle.digest`; no Node imports.
+ */
+declare function hashBodySha256Hex(body: Uint8Array): Promise<string>;
+/**
+ * Browser-safe 128-bit nonce as 32 lowercase hex chars via
+ * `crypto.getRandomValues`. No `Math.random` fallback: missing capability
+ * throws an actionable local error.
+ */
+declare function generateNonceHex(): string;
+/**
+ * Create the low-level WebCrypto HMAC signer. Copies/validates 32-byte
+ * 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.
+ */
+declare function createRequestSigner(options: RequestSignerOptions): RequestSigner;
+
+/**
+ * ATT-06 generation-aware ESM signer client (task sections 4.1/4.6).
+ *
+ * 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: []`).
+ *
+ * - `fetchSignerBundle({ metadataUrl, apiOrigin, replayNamespace, fetch?,
+ *   loadModule?, signal? })` fetches bounded discovery metadata
+ *   (`4096`-byte cap) 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`,
+ *   `new Function`, Blob-script workaround, or global `<script>` callback.
+ *   Native import follows browser module rules; the helper cannot intercept
+ *   its redirect chain, so the asset router must not redirect modules to
+ *   other origins and the host CSP must scope executable origins.
+ * - `createSignerClient({ metadataUrl, apiOrigin, replayNamespace, fetch?,
+ *   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-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.
+ * - 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).
+ */
+
+/** Bounded discovery metadata body: at most 4096 UTF-8 bytes. */
+declare const SIGNER_METADATA_BYTE_CAP: 4096;
+/** Default bound for one `getSigner()` load (metadata + import + one refetch). */
+declare const DEFAULT_SIGNER_LOAD_TIMEOUT_MS: 5000;
+/** Distributed-module shape: a module exports `signer`, nothing else trusted. */
+interface SignerModule {
+    readonly signer: RequestSigner;
+}
+/** Typed native ESM loader. Tests/host bundlers inject a fixture loader. */
+type SignerModuleLoader = (moduleUrl: string) => Promise<SignerModule>;
+/** Options for `fetchSignerBundle` (single metadata + import attempt). */
+interface FetchSignerBundleOptions {
+    readonly metadataUrl: string;
+    readonly apiOrigin: string;
+    readonly replayNamespace: string;
+    readonly fetch?: typeof fetch;
+    readonly loadModule?: SignerModuleLoader;
+    readonly signal?: AbortSignal;
+}
+/** Options for `createSignerClient`. */
+interface SignerClientOptions {
+    readonly metadataUrl: string;
+    readonly apiOrigin: string;
+    readonly replayNamespace: string;
+    readonly fetch?: typeof fetch;
+    readonly loadModule?: SignerModuleLoader;
+    readonly loadTimeoutMs?: number;
+}
+/** Minimal owned signer-client surface. */
+interface SignerClient {
+    getSigner(): Promise<RequestSigner>;
+    invalidate(observedKeyId: string): void;
+    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.
+ */
+declare function fetchSignerBundle(options: FetchSignerBundleOptions): Promise<SignerModule>;
+/** Create the generation-aware single-flight signer client. */
+declare function createSignerClient(options: SignerClientOptions): SignerClient;
+
+/**
+ * ATT-07 bounded request-body materialization (task sections 4.3/4.6).
+ *
+ * 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: []`).
+ *
+ * A `Request` body is internally a stream. This module reads supported finite
+ * requests with a byte-counting reader, cancellation, and a bounded deadline
+ * instead of claiming the mere stream type proves the body unsupported.
+ * Caller-supplied streaming uploads that exceed the cap, stall past the
+ * deadline, or abort are rejected locally without unbounded reads.
+ *
+ * - `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.
+ * - `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`,
+ *   `ArrayBuffer`/views, `FormData`, `ReadableStream`, `null`) pass through;
+ *   `FormData` itself is never read via `.arrayBuffer()` — callers serialize
+ *   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
+ *   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).
+ */
+/** Default body budget for prepared fetch: 1 MiB (matches server default). */
+declare const DEFAULT_ATTESTED_FETCH_MAX_BODY_BYTES: number;
+/** Hard v1 cap for prepared fetch: 16 MiB (matches server hard cap). */
+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;
+interface MaterializeRequestBodyOptions {
+    readonly maxBodyBytes?: number;
+    readonly signal?: AbortSignal | null | undefined;
+    readonly timeoutMs?: number;
+}
+/**
+ * Reject caller JSON objects and other non-`BodyInit` values before a
+ * `Request` is built. Docs use `JSON.stringify`; a plain object is never a
+ * valid Fetch body and must fail locally rather than serialize as
+ * `"[object Object]"`.
+ */
+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.
+ *
+ * - `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).
+ * - 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
+ *   throws the abort reason.
+ */
+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).
+ *
+ * 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: []`).
+ *
+ * - `fetchWithAttestation(input, init, options)` builds one immutable request
+ *   snapshot from `string | URL | Request` input plus `RequestInit`. Actual
+ *   method, headers (including `Authorization`), explicit `credentials`
+ *   (native default `same-origin`, never forced to `include`), `signal`, and
+ *   explicit request options (`mode`, `cache`, `referrer`, `integrity`,
+ *   `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`
+ *   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.
+ * - 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
+ *   signature field is replaced (never appended).
+ * - 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).
+ * - 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
+ *   invalidated, and the same serialized request is re-signed with a fresh
+ *   timestamp/nonce. A second stale challenge stops. Expired/future/replay/
+ *   invalid proofs, operational `5xx`, auth failures, redirects, network
+ *   uncertainty, and handler uncertainty never retry.
+ *
+ * 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.
+ * ```
+ *
+ * Browser CORS/CSP (application-configured, verified in tests):
+ *
+ * - 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`).
+ *
+ * Public HMAC material stays accessible to every caller despite
+ * non-extractable `CryptoKey` wrapping; this wrapper provides request-format
+ * consistency and replay detection, not device/browser authenticity.
+ */
+
+/** Default bounded body-read deadline for one prepared fetch: 5000 ms. */
+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. */
+    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. */
+    readonly fetch?: typeof fetch;
+    /** Alias for `fetch` (matches ATT-01 scaffold). At most one may be set. */
+    readonly fetchFn?: typeof fetch;
+    /** Signature header field. Defaults to `x-client-transaction-id`. */
+    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. */
+    readonly bodyReadTimeoutMs?: number;
+    /** Epoch-millisecond clock for per-attempt timestamps. Defaults to `Date.now`. */
+    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.
+ *
+ * See the module header for the full preparation/retry/composition contract.
+ */
+declare function fetchWithAttestation(input: RequestInfo | URL, init: RequestInit | undefined, options: FetchWithAttestationOptions): Promise<Response>;
+
+export { ATTESTED_FETCH_MAX_BODY_BYTES_HARD_CAP, DEFAULT_ATTESTED_FETCH_BODY_READ_TIMEOUT_MS$1 as DEFAULT_ATTESTED_FETCH_BODY_READ_TIMEOUT_MS, DEFAULT_ATTESTED_FETCH_BODY_READ_TIMEOUT_MS as DEFAULT_ATTESTED_FETCH_BODY_TIMEOUT_MS, DEFAULT_ATTESTED_FETCH_MAX_BODY_BYTES, DEFAULT_SIGNER_LOAD_TIMEOUT_MS, type FetchSignerBundleOptions, type FetchWithAttestationOptions, type MaterializeRequestBodyOptions, RequestSigner, RequestSignerOptions, SIGNER_METADATA_BYTE_CAP, type SignerClient, SignerClientError, type SignerClientErrorCode, type SignerClientOptions, type SignerModule, type SignerModuleLoader, assertSupportedBodyInit, createRequestSigner, createSignerClient, fetchSignerBundle, fetchWithAttestation, generateNonceHex, hashBodySha256Hex, isSignerClientError, materializeRequestBodyBytes };