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

package/{time-policy-DlER-7rf.d.mts → time-policy-CquS0Zgm.d.mts}

@@ -1,12 +1,10 @@
 /**
- * ATT-01 shared browser-safe protocol DTOs, constants, and error type.
+ * Shared browser-safe v1 protocol types, constants, and error type.
  *
- * This module is imported by BOTH public entries (`.` and `./signer`), so it
- * must stay free of Node built-ins, Express/Redis types, `Buffer`, `NodeJS`,
- * and `node:*` imports. See `tsconfig.signer-browser.json`, which typechecks
- * the signer closure with `types: []` to enforce that boundary.
+ * Both public entries (`.` and `./signer`) export these types. The browser
+ * entry requires no Node, Express, Redis, or MongoDB dependencies or types.
  *
- * Protocol summary (task section 4.2):
+ * Protocol summary:
  *
  * ```text
  * nonceHex    = lowercase hex of 16 cryptographically random bytes
@@ -38,9 +36,9 @@ declare const KEY_BYTES_LENGTH: 32;
 declare const NONCE_BYTES_LENGTH: 16;
 /** Raw HMAC-SHA-256 output length in bytes (43 unpadded base64url chars). */
 declare const MAC_BYTES_LENGTH: 32;
-/** Key identifiers match `[A-Za-z0-9_-]{1,64}` (task section 4.1). */
+/** Key identifiers match `[A-Za-z0-9_-]{1,64}`. */
 declare const MAX_KEY_ID_LENGTH: 64;
-/** Replay namespaces match `[A-Za-z0-9_-]{1,128}` (task section 4.2). */
+/** Replay namespaces match `[A-Za-z0-9_-]{1,128}`. */
 declare const MAX_REPLAY_NAMESPACE_LENGTH: 128;
 /** Encoded transaction-ID header value: at most 1024 UTF-8 bytes. */
 declare const MAX_ENCODED_TRANSACTION_ID_BYTES: 1024;
@@ -58,7 +56,7 @@ declare const MAX_HEADER_NAME_BYTES: 128;
 /** Default parser/body byte budget (1 MiB); hard v1 cap is 16 MiB. */
 declare const DEFAULT_MAX_BODY_BYTES: 1048576;
 declare const MAX_BODY_BYTES_HARD_CAP: 16777216;
-/** Time policy defaults and bounds in milliseconds (task section 4.4). */
+/** Time policy defaults and bounds in milliseconds. */
 declare const DEFAULT_MAX_AGE_MS: 30000;
 declare const MIN_MAX_AGE_MS: 1000;
 declare const MAX_MAX_AGE_MS: 120000;
@@ -76,7 +74,7 @@ declare const EMPTY_BODY_SHA256_HEX: "e3b0c44298fc1c149afbf4c8996fb92427ae41e464
  * Error thrown by shared protocol helpers for malformed input, failed
  * canonical checks, bound violations, and invalid option values.
  *
- * Server middleware (ATT-02) maps these to the fixed section 4.5 HTTP errors
+ * Server middleware maps request failures to fixed HTTP errors
  * without echoing key material, nonces, signatures, or request bodies.
  */
 declare class AttestationProtocolError extends Error {
@@ -138,40 +136,58 @@ interface TransactionIdFields {
 }
 /**
  * Low-level signer input. Callers supply explicit timestamp/nonce/body digest
- * so identical inputs are deterministic; only the request wrapper (ATT-07)
- * chooses fresh timestamps/nonces automatically.
+ * so identical inputs are deterministic; `fetchWithAttestation` chooses fresh
+ * timestamps/nonces automatically. Public HMAC proofs do not authenticate users.
  */
 interface SignInput {
+    /** Actual request method, normalized to uppercase. */
     readonly method: string;
+    /** Externally visible origin-form path/query; preserve percent escapes, slashes, and query order. */
     readonly requestTarget: string;
+    /** Final Content-Type including multipart boundary, or empty for an absent field. */
     readonly contentType: string;
+    /** Lowercase SHA-256 hex of the exact submitted bytes; hash zero bytes for an empty body. */
     readonly bodyHashHex: string;
+    /** Nonnegative safe-integer epoch milliseconds. */
     readonly timestampMs: number;
+    /** Fresh 128-bit nonce as 32 lowercase hex characters; use `generateNonceHex()`. */
     readonly nonceHex: string;
 }
 /**
- * Low-level HMAC signer (implemented with WebCrypto in ATT-06). A returned
- * signer exposes immutable protection-space binding plus `sign(input)`.
+ * Low-level WebCrypto HMAC signer with immutable protection-space binding.
+ * Publicly delivered key material provides no caller/session authentication.
  */
 interface RequestSigner {
     readonly version: 1;
     readonly keyId: string;
     readonly publicOrigin: string;
     readonly replayNamespace: string;
+    /** Deterministic for explicit inputs; returns a canonical envelope or rejects with a local protocol/client error. */
     sign(input: SignInput): Promise<string>;
 }
-/** Options accepted by `createRequestSigner` (ATT-06). */
+/** Explicit key and protection-space binding for `createRequestSigner`. */
 interface RequestSignerOptions {
+    /** Provisioned key identifier matching `[A-Za-z0-9_-]{1,64}`. */
     readonly keyId: string;
-    /** Exactly 32 bytes; copied on input, never exposed. */
+    /** Exactly 32 bytes; copied on input. Non-extractable wrapping does not hide publicly delivered material. */
     readonly key: Uint8Array;
+    /** Static canonical HTTPS origin (loopback HTTP allowed), identical to the verifier. */
     readonly publicOrigin: string;
+    /** Namespace matching `[A-Za-z0-9_-]{1,128}`, identical to the verifier. */
     readonly replayNamespace: string;
 }
-/** Partial time-policy overrides in milliseconds. */
+/**
+ * Partial time-policy overrides in milliseconds. All verifiers in one
+ * `(publicOrigin, replayNamespace)` must share these values, replay state,
+ * and per-key acceptance windows. A live policy migration needs a coordinated
+ * new protection space, retaining the old ledger through its last `retainUntilMs`.
+ */
 interface TimePolicyOptions {
+    /** 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;
+    /** Pairwise verifier/store clock difference; default 5000 ms (0–30000). Extends retention, not freshness. */
     readonly clusterClockGuardMs?: number;
 }
 /** Validated, frozen time policy. All values are safe-integer milliseconds. */
@@ -199,7 +215,7 @@ interface ProofTiming {
 /** Retention admission verdicts for replay stores. */
 type RetentionAdmission = 'admissible' | 'expired' | 'overlong';
 
-/** Key IDs match `[A-Za-z0-9_-]{1,64}` (task section 4.1 snapshot rules). */
+/** Key IDs match `[A-Za-z0-9_-]{1,64}`. */
 declare function validateKeyId(keyId: unknown): asserts keyId is string;
 /** Replay namespaces match `[A-Za-z0-9_-]{1,128}`. */
 declare function validateReplayNamespace(namespace: unknown): asserts namespace is string;
@@ -252,13 +268,15 @@ declare function canonicalizeRequestTarget(target: unknown): string;
 /**
  * Configured signature header-name validation. Names must be valid HTTP
  * tokens and must not collide with auth, cookie, host/origin, body-metadata,
- * or the package's `x-attestation-error` response marker.
+ * or the package's `x-attestation-error` response marker. This is general HTTP
+ * validation; `fetchWithAttestation` additionally rejects browser-forbidden names.
  */
 declare function validateHeaderName(name: unknown): asserts name is string;
 /**
  * Exactly-one incoming signature field. Returns `null` when absent (the
  * server maps that to `ATTESTATION_MISSING`); throws on duplicate raw-header
- * presentations or comma-joined values instead of selecting one value.
+ * presentations, oversized fields, or comma-joined values instead of selecting
+ * one value. Envelope decoding performs the remaining canonicality checks.
  */
 declare function extractSingleHeaderValue(raw: string | readonly string[] | undefined): string | null;
 /** Opaque replay keys are 1-256 printable ASCII bytes; never truncated. */
@@ -291,8 +309,8 @@ declare function encodeTransactionId(fields: TransactionIdFields): string;
  * Strict envelope decode. The 1024-byte bound is enforced BEFORE decoding;
  * then canonical base64url, UTF-8, canonical JSON array shape, version 1,
  * and every field rule are enforced. Unknown versions, extra array fields,
- * alternate numeric spellings, padding, and duplicate protocol material all
- * throw.
+ * alternate numeric spellings, padding, UTF-8 BOMs, and duplicate protocol
+ * material all throw.
  */
 declare function decodeTransactionId(headerValue: unknown): TransactionIdFields;
 
@@ -338,17 +356,20 @@ declare function assertTimestampMs(name: string, value: unknown): asserts value
 /**
  * Validate partial overrides and return the frozen effective policy.
  * Unknown option keys are rejected so typos cannot silently widen windows.
+ * Defaults are 30000 ms age, 5000 ms skew, and 5000 ms cluster clock guard.
+ * A protection space must use identical policy values and key acceptance
+ * windows everywhere; the returned policy does not coordinate deployments.
  */
 declare function resolveTimePolicy(options?: TimePolicyOptions): ResolvedTimePolicy;
 /**
  * Evaluate one proof's timing against a KNOWN key entry's acceptance window.
  *
- * Key-status ordering follows section 4.5: unknown/inactive well-formed key
+ * Key-status ordering: unknown/inactive well-formed key
  * IDs are `stale-key` (the caller determines key lookup; pass the entry's
  * window here), a known active key with an elapsed timestamp is `expired`,
  * and excessive future skew is `future`. The verifier repeats this check
  * after async provider work, immediately before reservation, and before
- * calling the handler after reservation (ATT-02).
+ * calling the handler after reservation.
  *
  * Deadline arithmetic must remain safe integers; a timestamp so large that
  * `timestampMs + maxAgeMs + clockSkewMs` leaves safe-integer range cannot
@@ -367,7 +388,7 @@ declare function evaluateProofTiming(input: {
  */
 declare function maxVerifierRemainingMs(policy: ResolvedTimePolicy): number;
 /**
- * Store admission bound: `maxAgeMs + 2 * clockSkewMs + 2 * clockGuardMs`
+ * Store admission bound: `maxAgeMs + 2 * clockSkewMs + 2 * clusterClockGuardMs`
  * (default 50000 ms). A store clock may additionally trail the verifier by
  * the declared guard. Capped globally at 240000 ms.
  */

package/{time-policy-DlER-7rf.d.ts → time-policy-CquS0Zgm.d.ts}

@@ -1,12 +1,10 @@
 /**
- * ATT-01 shared browser-safe protocol DTOs, constants, and error type.
+ * Shared browser-safe v1 protocol types, constants, and error type.
  *
- * This module is imported by BOTH public entries (`.` and `./signer`), so it
- * must stay free of Node built-ins, Express/Redis types, `Buffer`, `NodeJS`,
- * and `node:*` imports. See `tsconfig.signer-browser.json`, which typechecks
- * the signer closure with `types: []` to enforce that boundary.
+ * Both public entries (`.` and `./signer`) export these types. The browser
+ * entry requires no Node, Express, Redis, or MongoDB dependencies or types.
  *
- * Protocol summary (task section 4.2):
+ * Protocol summary:
  *
  * ```text
  * nonceHex    = lowercase hex of 16 cryptographically random bytes
@@ -38,9 +36,9 @@ declare const KEY_BYTES_LENGTH: 32;
 declare const NONCE_BYTES_LENGTH: 16;
 /** Raw HMAC-SHA-256 output length in bytes (43 unpadded base64url chars). */
 declare const MAC_BYTES_LENGTH: 32;
-/** Key identifiers match `[A-Za-z0-9_-]{1,64}` (task section 4.1). */
+/** Key identifiers match `[A-Za-z0-9_-]{1,64}`. */
 declare const MAX_KEY_ID_LENGTH: 64;
-/** Replay namespaces match `[A-Za-z0-9_-]{1,128}` (task section 4.2). */
+/** Replay namespaces match `[A-Za-z0-9_-]{1,128}`. */
 declare const MAX_REPLAY_NAMESPACE_LENGTH: 128;
 /** Encoded transaction-ID header value: at most 1024 UTF-8 bytes. */
 declare const MAX_ENCODED_TRANSACTION_ID_BYTES: 1024;
@@ -58,7 +56,7 @@ declare const MAX_HEADER_NAME_BYTES: 128;
 /** Default parser/body byte budget (1 MiB); hard v1 cap is 16 MiB. */
 declare const DEFAULT_MAX_BODY_BYTES: 1048576;
 declare const MAX_BODY_BYTES_HARD_CAP: 16777216;
-/** Time policy defaults and bounds in milliseconds (task section 4.4). */
+/** Time policy defaults and bounds in milliseconds. */
 declare const DEFAULT_MAX_AGE_MS: 30000;
 declare const MIN_MAX_AGE_MS: 1000;
 declare const MAX_MAX_AGE_MS: 120000;
@@ -76,7 +74,7 @@ declare const EMPTY_BODY_SHA256_HEX: "e3b0c44298fc1c149afbf4c8996fb92427ae41e464
  * Error thrown by shared protocol helpers for malformed input, failed
  * canonical checks, bound violations, and invalid option values.
  *
- * Server middleware (ATT-02) maps these to the fixed section 4.5 HTTP errors
+ * Server middleware maps request failures to fixed HTTP errors
  * without echoing key material, nonces, signatures, or request bodies.
  */
 declare class AttestationProtocolError extends Error {
@@ -138,40 +136,58 @@ interface TransactionIdFields {
 }
 /**
  * Low-level signer input. Callers supply explicit timestamp/nonce/body digest
- * so identical inputs are deterministic; only the request wrapper (ATT-07)
- * chooses fresh timestamps/nonces automatically.
+ * so identical inputs are deterministic; `fetchWithAttestation` chooses fresh
+ * timestamps/nonces automatically. Public HMAC proofs do not authenticate users.
  */
 interface SignInput {
+    /** Actual request method, normalized to uppercase. */
     readonly method: string;
+    /** Externally visible origin-form path/query; preserve percent escapes, slashes, and query order. */
     readonly requestTarget: string;
+    /** Final Content-Type including multipart boundary, or empty for an absent field. */
     readonly contentType: string;
+    /** Lowercase SHA-256 hex of the exact submitted bytes; hash zero bytes for an empty body. */
     readonly bodyHashHex: string;
+    /** Nonnegative safe-integer epoch milliseconds. */
     readonly timestampMs: number;
+    /** Fresh 128-bit nonce as 32 lowercase hex characters; use `generateNonceHex()`. */
     readonly nonceHex: string;
 }
 /**
- * Low-level HMAC signer (implemented with WebCrypto in ATT-06). A returned
- * signer exposes immutable protection-space binding plus `sign(input)`.
+ * Low-level WebCrypto HMAC signer with immutable protection-space binding.
+ * Publicly delivered key material provides no caller/session authentication.
  */
 interface RequestSigner {
     readonly version: 1;
     readonly keyId: string;
     readonly publicOrigin: string;
     readonly replayNamespace: string;
+    /** Deterministic for explicit inputs; returns a canonical envelope or rejects with a local protocol/client error. */
     sign(input: SignInput): Promise<string>;
 }
-/** Options accepted by `createRequestSigner` (ATT-06). */
+/** Explicit key and protection-space binding for `createRequestSigner`. */
 interface RequestSignerOptions {
+    /** Provisioned key identifier matching `[A-Za-z0-9_-]{1,64}`. */
     readonly keyId: string;
-    /** Exactly 32 bytes; copied on input, never exposed. */
+    /** Exactly 32 bytes; copied on input. Non-extractable wrapping does not hide publicly delivered material. */
     readonly key: Uint8Array;
+    /** Static canonical HTTPS origin (loopback HTTP allowed), identical to the verifier. */
     readonly publicOrigin: string;
+    /** Namespace matching `[A-Za-z0-9_-]{1,128}`, identical to the verifier. */
     readonly replayNamespace: string;
 }
-/** Partial time-policy overrides in milliseconds. */
+/**
+ * Partial time-policy overrides in milliseconds. All verifiers in one
+ * `(publicOrigin, replayNamespace)` must share these values, replay state,
+ * and per-key acceptance windows. A live policy migration needs a coordinated
+ * new protection space, retaining the old ledger through its last `retainUntilMs`.
+ */
 interface TimePolicyOptions {
+    /** 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;
+    /** Pairwise verifier/store clock difference; default 5000 ms (0–30000). Extends retention, not freshness. */
     readonly clusterClockGuardMs?: number;
 }
 /** Validated, frozen time policy. All values are safe-integer milliseconds. */
@@ -199,7 +215,7 @@ interface ProofTiming {
 /** Retention admission verdicts for replay stores. */
 type RetentionAdmission = 'admissible' | 'expired' | 'overlong';
 
-/** Key IDs match `[A-Za-z0-9_-]{1,64}` (task section 4.1 snapshot rules). */
+/** Key IDs match `[A-Za-z0-9_-]{1,64}`. */
 declare function validateKeyId(keyId: unknown): asserts keyId is string;
 /** Replay namespaces match `[A-Za-z0-9_-]{1,128}`. */
 declare function validateReplayNamespace(namespace: unknown): asserts namespace is string;
@@ -252,13 +268,15 @@ declare function canonicalizeRequestTarget(target: unknown): string;
 /**
  * Configured signature header-name validation. Names must be valid HTTP
  * tokens and must not collide with auth, cookie, host/origin, body-metadata,
- * or the package's `x-attestation-error` response marker.
+ * or the package's `x-attestation-error` response marker. This is general HTTP
+ * validation; `fetchWithAttestation` additionally rejects browser-forbidden names.
  */
 declare function validateHeaderName(name: unknown): asserts name is string;
 /**
  * Exactly-one incoming signature field. Returns `null` when absent (the
  * server maps that to `ATTESTATION_MISSING`); throws on duplicate raw-header
- * presentations or comma-joined values instead of selecting one value.
+ * presentations, oversized fields, or comma-joined values instead of selecting
+ * one value. Envelope decoding performs the remaining canonicality checks.
  */
 declare function extractSingleHeaderValue(raw: string | readonly string[] | undefined): string | null;
 /** Opaque replay keys are 1-256 printable ASCII bytes; never truncated. */
@@ -291,8 +309,8 @@ declare function encodeTransactionId(fields: TransactionIdFields): string;
  * Strict envelope decode. The 1024-byte bound is enforced BEFORE decoding;
  * then canonical base64url, UTF-8, canonical JSON array shape, version 1,
  * and every field rule are enforced. Unknown versions, extra array fields,
- * alternate numeric spellings, padding, and duplicate protocol material all
- * throw.
+ * alternate numeric spellings, padding, UTF-8 BOMs, and duplicate protocol
+ * material all throw.
  */
 declare function decodeTransactionId(headerValue: unknown): TransactionIdFields;
 
@@ -338,17 +356,20 @@ declare function assertTimestampMs(name: string, value: unknown): asserts value
 /**
  * Validate partial overrides and return the frozen effective policy.
  * Unknown option keys are rejected so typos cannot silently widen windows.
+ * Defaults are 30000 ms age, 5000 ms skew, and 5000 ms cluster clock guard.
+ * A protection space must use identical policy values and key acceptance
+ * windows everywhere; the returned policy does not coordinate deployments.
  */
 declare function resolveTimePolicy(options?: TimePolicyOptions): ResolvedTimePolicy;
 /**
  * Evaluate one proof's timing against a KNOWN key entry's acceptance window.
  *
- * Key-status ordering follows section 4.5: unknown/inactive well-formed key
+ * Key-status ordering: unknown/inactive well-formed key
  * IDs are `stale-key` (the caller determines key lookup; pass the entry's
  * window here), a known active key with an elapsed timestamp is `expired`,
  * and excessive future skew is `future`. The verifier repeats this check
  * after async provider work, immediately before reservation, and before
- * calling the handler after reservation (ATT-02).
+ * calling the handler after reservation.
  *
  * Deadline arithmetic must remain safe integers; a timestamp so large that
  * `timestampMs + maxAgeMs + clockSkewMs` leaves safe-integer range cannot
@@ -367,7 +388,7 @@ declare function evaluateProofTiming(input: {
  */
 declare function maxVerifierRemainingMs(policy: ResolvedTimePolicy): number;
 /**
- * Store admission bound: `maxAgeMs + 2 * clockSkewMs + 2 * clockGuardMs`
+ * Store admission bound: `maxAgeMs + 2 * clockSkewMs + 2 * clusterClockGuardMs`
  * (default 50000 ms). A store clock may additionally trail the verifier by
  * the declared guard. Capped globally at 240000 ms.
  */