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

package/time-policy-DlER-7rf.d.mts

@@ -0,0 +1,385 @@
+/**
+ * ATT-01 shared browser-safe protocol DTOs, 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.
+ *
+ * Protocol summary (task section 4.2):
+ *
+ * ```text
+ * nonceHex    = lowercase hex of 16 cryptographically random bytes
+ * bodyHashHex = lowercase hex of SHA-256(exact submitted body bytes)
+ * macInput    = UTF8(JSON.stringify([
+ *   "wtt-request-signature", 1, replayNamespace, publicOrigin,
+ *   keyId, timestampMs, nonceHex, method, requestTarget, contentType, bodyHashHex
+ * ]))
+ * mac           = base64url(HMAC-SHA-256(key, macInput))
+ * transactionId = base64url(UTF8(JSON.stringify([1, keyId, timestampMs, nonceHex, mac])))
+ * ```
+ *
+ * All encodings are UTF-8. Base64url is unpadded and canonical
+ * (decode/re-encode must match). JSON arrays carry no whitespace.
+ */
+/** Frozen wire protocol version. Unknown versions are rejected. */
+declare const PROTOCOL_VERSION: 1;
+/** Domain-separation label that opens every MAC input tuple. */
+declare const MAC_INPUT_LABEL: "wtt-request-signature";
+/** Default signature header field name. */
+declare const DEFAULT_ATTESTATION_HEADER: "x-client-transaction-id";
+/** Package response marker used only for the pre-handler stale-key signal. */
+declare const ATTESTATION_ERROR_RESPONSE_HEADER: "x-attestation-error";
+/** Prefix for opaque replay keys derived per protection space + nonce. */
+declare const REPLAY_KEY_PREFIX: "att:v1:";
+/** Exact HMAC key length in bytes. */
+declare const KEY_BYTES_LENGTH: 32;
+/** Random nonce length in bytes (serialized as 32 lowercase hex chars). */
+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). */
+declare const MAX_KEY_ID_LENGTH: 64;
+/** Replay namespaces match `[A-Za-z0-9_-]{1,128}` (task section 4.2). */
+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;
+/** Canonical request target: at most 8192 UTF-8 bytes. */
+declare const MAX_REQUEST_TARGET_BYTES: 8192;
+/** Normalized content type: at most 256 UTF-8 bytes. */
+declare const MAX_CONTENT_TYPE_BYTES: 256;
+/** Canonical public origin: at most 512 UTF-8 bytes. */
+declare const MAX_PUBLIC_ORIGIN_BYTES: 512;
+/** Opaque replay keys: 1-256 printable ASCII bytes. */
+declare const MIN_REPLAY_KEY_BYTES: 1;
+declare const MAX_REPLAY_KEY_BYTES: 256;
+/** Configured signature header names: valid HTTP tokens, at most 128 bytes. */
+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). */
+declare const DEFAULT_MAX_AGE_MS: 30000;
+declare const MIN_MAX_AGE_MS: 1000;
+declare const MAX_MAX_AGE_MS: 120000;
+declare const DEFAULT_CLOCK_SKEW_MS: 5000;
+declare const MIN_CLOCK_SKEW_MS: 0;
+declare const MAX_CLOCK_SKEW_MS: 30000;
+declare const DEFAULT_CLUSTER_CLOCK_GUARD_MS: 5000;
+declare const MIN_CLUSTER_CLOCK_GUARD_MS: 0;
+declare const MAX_CLUSTER_CLOCK_GUARD_MS: 30000;
+/** Global retention ceiling, including the store-clock guard allowance. */
+declare const GLOBAL_MAX_RETENTION_MS: 240000;
+/** SHA-256 of zero bytes: the digest of an actually empty request body. */
+declare const EMPTY_BODY_SHA256_HEX: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/**
+ * 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
+ * without echoing key material, nonces, signatures, or request bodies.
+ */
+declare class AttestationProtocolError extends Error {
+    readonly name = "AttestationProtocolError";
+    constructor(message: string);
+}
+/**
+ * Decoded transaction-ID envelope: `[1, keyId, timestampMs, nonceHex, mac]`.
+ * Exactly 5 elements; extra array fields are rejected.
+ */
+type AttestationEnvelope = readonly [
+    version: 1,
+    keyId: string,
+    timestampMs: number,
+    nonceHex: string,
+    mac: string
+];
+/**
+ * MAC input tuple. EVERY protected field participates; altering method,
+ * target, query spelling/order, content type, body bytes, namespace, origin,
+ * version, key ID, timestamp, or nonce invalidates the MAC.
+ */
+type AttestationMacInput = readonly [
+    label: 'wtt-request-signature',
+    version: 1,
+    replayNamespace: string,
+    publicOrigin: string,
+    keyId: string,
+    timestampMs: number,
+    nonceHex: string,
+    method: string,
+    requestTarget: string,
+    contentType: string,
+    bodyHashHex: string
+];
+/** Fields needed to build the MAC input tuple. */
+interface MacInputFields {
+    readonly replayNamespace: string;
+    readonly publicOrigin: string;
+    readonly keyId: string;
+    readonly timestampMs: number;
+    readonly nonceHex: string;
+    /** Actual method, normalized to uppercase. */
+    readonly method: string;
+    /** Canonical origin-form request target (encoded bytes preserved). */
+    readonly requestTarget: string;
+    /** Single final content type with outer HTTP whitespace trimmed. */
+    readonly contentType: string;
+    /** Lowercase hex SHA-256 of the exact submitted body bytes. */
+    readonly bodyHashHex: string;
+}
+/** Fields carried by the encoded transaction-ID envelope. */
+interface TransactionIdFields {
+    readonly keyId: string;
+    readonly timestampMs: number;
+    readonly nonceHex: string;
+    /** 43 canonical unpadded base64url chars (32 raw bytes). */
+    readonly mac: string;
+}
+/**
+ * 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.
+ */
+interface SignInput {
+    readonly method: string;
+    readonly requestTarget: string;
+    readonly contentType: string;
+    readonly bodyHashHex: string;
+    readonly timestampMs: number;
+    readonly nonceHex: string;
+}
+/**
+ * Low-level HMAC signer (implemented with WebCrypto in ATT-06). A returned
+ * signer exposes immutable protection-space binding plus `sign(input)`.
+ */
+interface RequestSigner {
+    readonly version: 1;
+    readonly keyId: string;
+    readonly publicOrigin: string;
+    readonly replayNamespace: string;
+    sign(input: SignInput): Promise<string>;
+}
+/** Options accepted by `createRequestSigner` (ATT-06). */
+interface RequestSignerOptions {
+    readonly keyId: string;
+    /** Exactly 32 bytes; copied on input, never exposed. */
+    readonly key: Uint8Array;
+    readonly publicOrigin: string;
+    readonly replayNamespace: string;
+}
+/** Partial time-policy overrides in milliseconds. */
+interface TimePolicyOptions {
+    readonly maxAgeMs?: number;
+    readonly clockSkewMs?: number;
+    readonly clusterClockGuardMs?: number;
+}
+/** Validated, frozen time policy. All values are safe-integer milliseconds. */
+interface ResolvedTimePolicy {
+    readonly maxAgeMs: number;
+    readonly clockSkewMs: number;
+    readonly clusterClockGuardMs: number;
+}
+/** Proof-timing verdicts. Key lookup happens first: unknown/inactive keys are `stale-key`. */
+type ProofTimingDecision = 'valid' | 'future' | 'expired' | 'stale-key';
+/**
+ * Result of evaluating one proof's timing. Deadline fields are `null` only
+ * when the timestamp is so large that deadline arithmetic leaves safe-integer
+ * range; that proof is rejected as `expired`.
+ */
+interface ProofTiming {
+    readonly decision: ProofTimingDecision;
+    /** `timestampMs + maxAgeMs + clockSkewMs`. */
+    readonly timeDeadlineMs: number | null;
+    /** `min(timeDeadlineMs, acceptUntil)`. */
+    readonly proofDeadlineMs: number | null;
+    /** `proofDeadlineMs + clusterClockGuardMs`: full replay retention deadline. */
+    readonly retainUntilMs: number | null;
+}
+/** 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). */
+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;
+/** Nonces are exactly 32 lowercase hex chars (16 random bytes). */
+declare function validateNonceHex(nonceHex: unknown): asserts nonceHex is string;
+/** Body digests are lowercase hex SHA-256 (32 bytes). */
+declare function validateBodyHashHex(bodyHashHex: unknown): asserts bodyHashHex is string;
+/** MACs are exactly 43 canonical base64url chars decoding to 32 bytes. */
+declare function validateMac(mac: unknown): asserts mac is string;
+/** HMAC key material is exactly 32 bytes. */
+declare function validateKeyBytes(key: unknown): asserts key is Uint8Array;
+/**
+ * Canonical HTTP(S) origin validation. The value must already be canonical:
+ * lowercase scheme/host, no userinfo, no path/query/fragment, no trailing
+ * slash, no redundant default port. HTTPS is required except for loopback
+ * development (`localhost`, `127.0.0.0/8`, `[::1]`). Never derive this from
+ * `Host`, `Forwarded`, or `X-Forwarded-*` — it is static configuration.
+ */
+declare function validatePublicOrigin(origin: unknown): asserts origin is string;
+/**
+ * Actual method normalized to uppercase. The method is a valid HTTP token;
+ * lowercase input such as `get` normalizes to `GET` on both sides.
+ */
+declare function normalizeMethod(method: unknown): string;
+/**
+ * Single final `Content-Type` value with outer HTTP whitespace (SP/HTAB)
+ * trimmed; remaining bytes — including a generated multipart boundary — are
+ * preserved. Missing values normalize to `""`. Controls are rejected and
+ * the normalized value is bounded to 256 UTF-8 bytes.
+ */
+declare function normalizeContentType(contentType: unknown): string;
+/**
+ * Canonical origin-form request target.
+ *
+ * The signer uses the final `Request.url` pathname plus raw search string;
+ * Express uses `req.originalUrl` plus a configured stripped-proxy prefix.
+ * Either way the ENCODED bytes are preserved: reserved path escapes, case and
+ * spelling of percent escapes, trailing/doubled slashes, duplicate query
+ * parameters, query order, and `+` all survive untouched — no `req.query`
+ * sorting, no JSON query reserialization, no decoding.
+ *
+ * The single normalization both sides apply: a lone empty `?` is treated as
+ * no search string (`/items?` signs as `/items`).
+ *
+ * Rejected before any allocation: non-origin forms, `//authority` targets,
+ * fragments, backslashes, controls, raw spaces, malformed percent escapes,
+ * and canonical/noncanonical dot-segment forms (including `%2e` spellings).
+ */
+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.
+ */
+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.
+ */
+declare function extractSingleHeaderValue(raw: string | readonly string[] | undefined): string | null;
+/** Opaque replay keys are 1-256 printable ASCII bytes; never truncated. */
+declare function validateReplayKey(replayKey: unknown): asserts replayKey is string;
+/**
+ * Exact MAC input bytes: `UTF8(JSON(["wtt-request-signature",1,...])))`.
+ * Method, target, and content type are normalized exactly as the verifier
+ * normalizes them, so both sides frame identical bytes.
+ */
+declare function buildMacInputBytes(fields: MacInputFields): Uint8Array;
+/**
+ * Canonical replay-key preimage bytes: `UTF8(JSON([namespace, origin,
+ * nonceHex]))`. The caller hashes these with SHA-256 and prefixes the hex
+ * with `att:v1:` — the nonce stays single-use across accepted rotations in
+ * one protection space, while path, token, session, key ID, and instance
+ * stay OUT of the key.
+ */
+declare function buildReplayKeyPreimageBytes(input: {
+    readonly replayNamespace: string;
+    readonly publicOrigin: string;
+    readonly nonceHex: string;
+}): Uint8Array;
+/**
+ * Encode the transaction-ID envelope `[1,keyId,timestampMs,nonceHex,mac]`
+ * as unpadded base64url UTF-8 JSON. The 1024-byte bound is enforced on the
+ * encoded output.
+ */
+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.
+ */
+declare function decodeTransactionId(headerValue: unknown): TransactionIdFields;
+
+/** UTF-8 encode without BOM. */
+declare function utf8Encode(text: string): Uint8Array;
+/** UTF-8 decode; rejects lone surrogates and invalid sequences. */
+declare function utf8Decode(bytes: Uint8Array): string;
+/** UTF-8 byte length of a string. */
+declare function utf8ByteLength(text: string): number;
+/**
+ * Unpadded canonical base64url encode.
+ *
+ * @param bytes raw bytes to encode.
+ */
+declare function base64urlEncode(bytes: Uint8Array): string;
+/**
+ * Strict canonical base64url decode.
+ *
+ * Rejects padding (`=`), foreign alphabets, impossible lengths
+ * (`length % 4 === 1`), and non-canonical trailing bits (decode/re-encode
+ * must reproduce the input exactly).
+ */
+declare function base64urlDecode(input: string): Uint8Array;
+/**
+ * Whitespace-free canonical JSON serialization of a JSON value, as UTF-8
+ * bytes. `JSON.stringify` output is already whitespace-free; anything it
+ * cannot represent (`undefined`, functions, circular graphs) is rejected.
+ */
+declare function canonicalJsonBytes(value: unknown): Uint8Array;
+/**
+ * Strict canonical JSON array parse.
+ *
+ * The raw text must round-trip `JSON.parse`/`JSON.stringify` byte-for-byte,
+ * which rejects whitespace, alternate numeric spellings (`1.0`, `1e3`,
+ * `+1`, `-0`), non-minimal string escapes, and duplicate-key-tolerant
+ * reserialization. The parsed value must be an array of exactly
+ * `expectedLength` elements when given.
+ */
+declare function parseCanonicalJsonArray(text: string, expectedLength?: number): unknown[];
+/** Assert a value is a non-negative safe-integer epoch-millisecond count. */
+declare function assertTimestampMs(name: string, value: unknown): asserts value is number;
+
+/**
+ * Validate partial overrides and return the frozen effective policy.
+ * Unknown option keys are rejected so typos cannot silently widen windows.
+ */
+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
+ * 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).
+ *
+ * Deadline arithmetic must remain safe integers; a timestamp so large that
+ * `timestampMs + maxAgeMs + clockSkewMs` leaves safe-integer range cannot
+ * prove freshness and is rejected as `expired` with `null` deadlines.
+ */
+declare function evaluateProofTiming(input: {
+    readonly timestampMs: number;
+    readonly nowMs: number;
+    readonly acceptFrom: number;
+    readonly acceptUntil: number;
+    readonly policy: ResolvedTimePolicy;
+}): ProofTiming;
+/**
+ * Maximum remaining retention measured AT a verifier:
+ * `maxAgeMs + 2 * clockSkewMs + clusterClockGuardMs` (default 45000 ms).
+ */
+declare function maxVerifierRemainingMs(policy: ResolvedTimePolicy): number;
+/**
+ * Store admission bound: `maxAgeMs + 2 * clockSkewMs + 2 * clockGuardMs`
+ * (default 50000 ms). A store clock may additionally trail the verifier by
+ * the declared guard. Capped globally at 240000 ms.
+ */
+declare function maxStoreAdmissionMs(policy: ResolvedTimePolicy): number;
+/**
+ * Check whether a store may admit `retainUntilMs` at `nowMs`. Stores reject
+ * unsafe, already-expired, or overlong retention INSTEAD of truncating it.
+ */
+declare function checkRetentionAdmissible(input: {
+    readonly retainUntilMs: number;
+    readonly nowMs: number;
+    readonly policy: ResolvedTimePolicy;
+}): RetentionAdmission;
+
+export { evaluateProofTiming as $, ATTESTATION_ERROR_RESPONSE_HEADER as A, type ProofTimingDecision as B, REPLAY_KEY_PREFIX as C, DEFAULT_ATTESTATION_HEADER as D, EMPTY_BODY_SHA256_HEX as E, type RequestSigner as F, GLOBAL_MAX_RETENTION_MS as G, type RequestSignerOptions as H, type RetentionAdmission as I, type TransactionIdFields as J, KEY_BYTES_LENGTH as K, assertTimestampMs as L, MAC_BYTES_LENGTH as M, NONCE_BYTES_LENGTH as N, base64urlDecode as O, type ProofTiming as P, base64urlEncode as Q, type ResolvedTimePolicy as R, type SignInput as S, type TimePolicyOptions as T, buildMacInputBytes as U, buildReplayKeyPreimageBytes as V, canonicalJsonBytes as W, canonicalizeRequestTarget as X, checkRetentionAdmissible as Y, decodeTransactionId as Z, encodeTransactionId as _, type AttestationEnvelope as a, extractSingleHeaderValue as a0, maxStoreAdmissionMs as a1, maxVerifierRemainingMs as a2, normalizeContentType as a3, normalizeMethod as a4, parseCanonicalJsonArray as a5, resolveTimePolicy as a6, utf8ByteLength as a7, utf8Decode as a8, utf8Encode as a9, validateBodyHashHex as aa, validateHeaderName as ab, validateKeyBytes as ac, validateKeyId as ad, validateMac as ae, validateNonceHex as af, validatePublicOrigin as ag, validateReplayKey as ah, validateReplayNamespace as ai, type AttestationMacInput as b, AttestationProtocolError as c, DEFAULT_CLOCK_SKEW_MS as d, DEFAULT_CLUSTER_CLOCK_GUARD_MS as e, DEFAULT_MAX_AGE_MS as f, DEFAULT_MAX_BODY_BYTES as g, MAC_INPUT_LABEL as h, MAX_BODY_BYTES_HARD_CAP as i, MAX_CLOCK_SKEW_MS as j, MAX_CLUSTER_CLOCK_GUARD_MS as k, MAX_CONTENT_TYPE_BYTES as l, MAX_ENCODED_TRANSACTION_ID_BYTES as m, MAX_HEADER_NAME_BYTES as n, MAX_KEY_ID_LENGTH as o, MAX_MAX_AGE_MS as p, MAX_PUBLIC_ORIGIN_BYTES as q, MAX_REPLAY_KEY_BYTES as r, MAX_REPLAY_NAMESPACE_LENGTH as s, MAX_REQUEST_TARGET_BYTES as t, MIN_CLOCK_SKEW_MS as u, MIN_CLUSTER_CLOCK_GUARD_MS as v, MIN_MAX_AGE_MS as w, MIN_REPLAY_KEY_BYTES as x, type MacInputFields as y, PROTOCOL_VERSION as z };