@daloyjs/core 1.3.1 → 1.3.3

package/dist/http-signatures.js

@@ -167,7 +167,7 @@ async function importKey(alg, material, usage) {
     const spec = algSpec(alg);
     const c = getCrypto();
     if (isCryptoKey(material)) {
-        assertRsaModulusFloor(alg, material);
+        assertKeyPolicy(alg, material);
         return material;
     }
     if (material instanceof Uint8Array) {
@@ -177,15 +177,31 @@ async function importKey(alg, material, usage) {
         if (material.byteLength < MIN_HMAC_KEY_BYTES) {
             throw new TypeError(`http-signatures: hmac-sha256 secret must be at least ${MIN_HMAC_KEY_BYTES} bytes (RFC 7518 §3.2); got ${material.byteLength}.`);
         }
-        return c.subtle.importKey("raw", material, spec.importParams, false, [usage]);
+        return c.subtle.importKey("raw", material, spec.importParams, false, [
+            usage,
+        ]);
     }
     if (isJsonWebKey(material)) {
         const key = await c.subtle.importKey("jwk", material, spec.importParams, false, [usage]);
-        assertRsaModulusFloor(alg, key);
+        assertKeyPolicy(alg, key);
         return key;
     }
     throw new TypeError("http-signatures: unsupported key material.");
 }
+function assertKeyPolicy(alg, key) {
+    const expected = algSpec(alg).importParams;
+    const actual = key.algorithm;
+    if (actual.name !== expected.name ||
+        (expected.hash !== undefined && actual.hash?.name !== expected.hash) ||
+        (expected.namedCurve !== undefined && actual.namedCurve !== expected.namedCurve)) {
+        throw new TypeError(`http-signatures: key algorithm does not match ${alg}; family, hash and curve must match.`);
+    }
+    if (expected.name === "HMAC" &&
+        (!Number.isFinite(actual.length) || actual.length < MIN_HMAC_KEY_BYTES * 8)) {
+        throw new TypeError(`http-signatures: hmac-sha256 secret must be at least ${MIN_HMAC_KEY_BYTES} bytes (RFC 7518 §3.2).`);
+    }
+    assertRsaModulusFloor(alg, key);
+}
 function serializeSfString(s) {
     for (let i = 0; i < s.length; i++) {
         const code = s.charCodeAt(i);
@@ -518,7 +534,8 @@ function parseComponentSpec(spec) {
  * @returns The `Signature-Input` / `Signature` header values plus the exact
  *   signature base that was signed.
  * @throws {TypeError} for unsupported algorithms, weak HMAC keys, or
- *   unserializable parameter values.
+ *   unserializable parameter values. Imported keys must match the selected
+ *   algorithm's family, hash and curve and meet its strength floor.
  * @throws {Error} when a covered component cannot be resolved (e.g. a covered
  *   header is missing) or WebCrypto is unavailable.
  * @since 0.37.0
@@ -585,6 +602,7 @@ function fail(reason) {
  * Verify an HTTP Message Signature (RFC 9421) on a received message. Returns a
  * structured result and never throws on a bad/forged signature — only on a
  * programming error (e.g. WebCrypto unavailable).
+ * Imported keys that violate the algorithm or strength policy return invalid_key.
  *
  * @param opts - Received message plus verification policy (algorithm
  *   allowlist, key resolver, freshness / replay checks); see
@@ -671,12 +689,8 @@ export async function verifyMessage(opts) {
         return fail("signature_expired");
     }
     // Replay check.
-    if (opts.isReplay) {
-        if (params.nonce === undefined)
-            return fail("missing_nonce");
-        if (await opts.isReplay(params.nonce, info))
-            return fail("replay_detected");
-    }
+    if (opts.isReplay && params.nonce === undefined)
+        return fail("missing_nonce");
     // Resolve the key + effective algorithm (defeating algorithm-confusion).
     const resolved = await opts.resolveKey(info);
     if (resolved === undefined)
@@ -730,6 +744,9 @@ export async function verifyMessage(opts) {
     }
     if (!ok)
         return fail("invalid_signature");
+    if (opts.isReplay && (await opts.isReplay(params.nonce, info))) {
+        return fail("replay_detected");
+    }
     return {
         valid: true,
         label,
@@ -765,6 +782,8 @@ export function verifyRequest(request, opts) {
  * requests. On success the {@link VerifySuccess} is stamped on `ctx.state`; on
  * a missing (unless `optional`) or invalid signature it throws
  * {@link UnauthorizedError} (`401` + `Cache-Control: no-store`).
+ * Verification runs before body I/O and before stored-response middleware,
+ * so cache hits and idempotency replays cannot skip signature authentication.
  *
  * @param opts - Verification policy plus middleware knobs; see
  *   {@link HttpSignatureAuthOptions}.
@@ -775,7 +794,7 @@ export function httpSignatureAuth(opts) {
     const stateKey = opts.stateKey ?? "httpSignature";
     const message = opts.message ?? "Valid HTTP message signature required";
     const authHooks = {
-        async beforeHandle(ctx) {
+        async preBody(ctx) {
             const headers = ctx.request.headers;
             if (opts.optional && !headers.has("signature"))
                 return undefined;

package/dist/idempotency.d.ts

@@ -214,6 +214,8 @@ export interface IdempotencyOptions {
  * alone is not a bound — it only drops records that have *expired*, so a stream
  * of unique keys inside the TTL grew the map linearly no matter how often it ran,
  * with each entry pinning a stored response body.
+ * Late completions of evicted reservations use the same capacity policy;
+ * completing a retained entry updates it without evicting another record.
  *
  * Evicting a live record can only cost exactly-once semantics for a retry that
  * arrives after the eviction — it re-executes rather than replaying. That is the
@@ -235,7 +237,14 @@ export declare class MemoryIdempotencyStore implements IdempotencyStore {
      * the in-memory store derives expiry from `record.expiresAt`.
      */
     reserve(key: string, record: IdempotencyRecord, _ttlMs?: number): IdempotencyRecord | null;
-    /** @inheritDoc */
+    /**
+     * Persist a completed response, enforcing capacity even if its reservation
+     * was evicted while the handler ran.
+     * @param key - Reservation key to complete.
+     * @param record - Completed record with response data and expiry.
+     * @param _ttlMs - Unused; expiry is derived from record.expiresAt.
+     * @returns Nothing. A new entry may evict the oldest retained record.
+     */
     complete(key: string, record: IdempotencyRecord, _ttlMs?: number): void;
     /** @inheritDoc */
     release(key: string): void;
@@ -278,6 +287,12 @@ export declare const IDEMPOTENCY_HOOK_MARKER: unique symbol;
  * Responses that fail {@link IdempotencyOptions.cacheableStatus} (server errors
  * by default) or exceed {@link IdempotencyOptions.maxResponseBytes} are not
  * cached and the reservation is released so the client can retry.
+ * The byte cap is enforced while reading the response clone; exceeding it
+ * stops capture without waiting for EOF or consuming the client's branch.
+ * Replays require every scope aggregated from the route's requireScopes hooks;
+ * callers without those scopes continue to the normal authorization chain.
+ * Empty Authorization headers do not resolve a principal and cannot bypass
+ * the default cookie-bearing-request scope guard.
  *
  * @example
  * ```ts

package/dist/idempotency.js

@@ -33,6 +33,8 @@
  */
 import { BadRequestError, ConflictError, HttpError } from "./errors.js";
 import { markSchemaValidatedResponse } from "./internal-response.js";
+import { readResponseBodyUpTo } from "./internal-body.js";
+import { hasReplayScopes } from "./internal-replay.js";
 const enc = new TextEncoder();
 /** Internal `ctx.state` key carrying the reservation between hooks. */
 const PENDING_STATE_KEY = "__idempotencyPending";
@@ -73,6 +75,8 @@ const DEFAULT_MAX_IDEMPOTENCY_ENTRIES = 10_000;
  * alone is not a bound — it only drops records that have *expired*, so a stream
  * of unique keys inside the TTL grew the map linearly no matter how often it ran,
  * with each entry pinning a stored response body.
+ * Late completions of evicted reservations use the same capacity policy;
+ * completing a retained entry updates it without evicting another record.
  *
  * Evicting a live record can only cost exactly-once semantics for a retry that
  * arrives after the eviction — it re-executes rather than replaying. That is the
@@ -117,8 +121,19 @@ export class MemoryIdempotencyStore {
         this.map.set(key, record);
         return null;
     }
-    /** @inheritDoc */
+    /**
+     * Persist a completed response, enforcing capacity even if its reservation
+     * was evicted while the handler ran.
+     * @param key - Reservation key to complete.
+     * @param record - Completed record with response data and expiry.
+     * @param _ttlMs - Unused; expiry is derived from record.expiresAt.
+     * @returns Nothing. A new entry may evict the oldest retained record.
+     */
     complete(key, record, _ttlMs) {
+        if (!this.map.has(key)) {
+            this.reserve(key, record, _ttlMs);
+            return;
+        }
         this.map.set(key, record);
     }
     /** @inheritDoc */
@@ -266,8 +281,8 @@ const NEVER_REPLAYED_HEADERS = new Set([
     "x-request-id",
 ]);
 async function captureResponse(res, maxBytes) {
-    const buf = new Uint8Array(await res.clone().arrayBuffer());
-    if (buf.byteLength > maxBytes)
+    const buf = await readResponseBodyUpTo(res.clone(), maxBytes);
+    if (buf === null)
         return null;
     const headers = [];
     res.headers.forEach((value, name) => {
@@ -326,6 +341,12 @@ export const IDEMPOTENCY_HOOK_MARKER = Symbol.for("daloyjs.idempotency.hook");
  * Responses that fail {@link IdempotencyOptions.cacheableStatus} (server errors
  * by default) or exceed {@link IdempotencyOptions.maxResponseBytes} are not
  * cached and the reservation is released so the client can retry.
+ * The byte cap is enforced while reading the response clone; exceeding it
+ * stops capture without waiting for EOF or consuming the client's branch.
+ * Replays require every scope aggregated from the route's requireScopes hooks;
+ * callers without those scopes continue to the normal authorization chain.
+ * Empty Authorization headers do not resolve a principal and cannot bypass
+ * the default cookie-bearing-request scope guard.
  *
  * @example
  * ```ts
@@ -376,6 +397,8 @@ export function idempotency(opts = {}) {
     const keyPrefix = opts.groupId ? `${opts.groupId}:` : "";
     const hooks = {
         async beforeHandle(ctx) {
+            if (!hasReplayScopes(ctx))
+                return undefined;
             const method = ctx.request.method.toUpperCase();
             if (!methods.has(method))
                 return undefined;
@@ -423,11 +446,11 @@ export function idempotency(opts = {}) {
             // is never stored or replayed (see {@link NEVER_REPLAYED_HEADERS}), so a
             // coarse namespace cannot escalate into handing over a live session.
             if (!opts.scope &&
-                scopeRaw === undefined &&
+                !scopeRaw &&
                 !allowUnscopedCallers &&
                 ctx.request.headers.has("cookie")) {
                 throw new Error("idempotency(): cannot determine the calling principal for a cookie-bearing request. " +
-                    "The default scope reads the Authorization header, which this request does not carry, " +
+                    "The default scope reads the Authorization header, which this request does not carry with a non-empty value, " +
                     "so every cookie-authenticated caller would share one idempotency namespace and could " +
                     "replay another caller's stored response (CWE-524). Pass " +
                     "`scope: (ctx) => ctx.state.session?.id` (or another stable per-caller id), or set " +

package/dist/internal-body.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Read a response clone while enforcing an inclusive byte limit.
+ *
+ * @param response - A clone whose body may be consumed or cancelled.
+ * @param maxBytes - Maximum retained response bytes, validated by the caller.
+ * @returns Captured bytes, or null as soon as the stream exceeds the limit.
+ *   Cancelling a tee branch is not awaited because the other branch may still
+ *   be waiting for its consumer. The original response remains readable.
+ * @throws Propagates stream read errors without converting them to cached data.
+ * @internal
+ */
+export declare function readResponseBodyUpTo(response: Response, maxBytes: number): Promise<Uint8Array | null>;

package/dist/internal-body.js

@@ -0,0 +1,45 @@
+/**
+ * Read a response clone while enforcing an inclusive byte limit.
+ *
+ * @param response - A clone whose body may be consumed or cancelled.
+ * @param maxBytes - Maximum retained response bytes, validated by the caller.
+ * @returns Captured bytes, or null as soon as the stream exceeds the limit.
+ *   Cancelling a tee branch is not awaited because the other branch may still
+ *   be waiting for its consumer. The original response remains readable.
+ * @throws Propagates stream read errors without converting them to cached data.
+ * @internal
+ */
+export async function readResponseBodyUpTo(response, maxBytes) {
+    if (!response.body)
+        return new Uint8Array(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value.byteLength === 0)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                void reader.cancel().catch(() => undefined);
+                return null;
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (chunks.length === 1)
+        return chunks[0];
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}

package/dist/internal-replay.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Check the scope requirements aggregated by App before a stored-response hook.
+ *
+ * @param context - Current request state, including requirements installed by
+ *   App.mergeBeforeHandle and the user resolved by upstream authentication.
+ * @returns True when no scope guard applies or the current user owns every
+ *   required scope. False tells replay middleware to defer to the normal hook
+ *   chain without reading, reserving, or capturing a stored response. The
+ *   downstream requireScopes hook remains responsible for rejecting access.
+ * @internal
+ */
+export declare function hasReplayScopes(context: {
+    readonly state: Readonly<Record<string, unknown>>;
+}): boolean;

package/dist/internal-replay.js

@@ -0,0 +1,21 @@
+/**
+ * Check the scope requirements aggregated by App before a stored-response hook.
+ *
+ * @param context - Current request state, including requirements installed by
+ *   App.mergeBeforeHandle and the user resolved by upstream authentication.
+ * @returns True when no scope guard applies or the current user owns every
+ *   required scope. False tells replay middleware to defer to the normal hook
+ *   chain without reading, reserving, or capturing a stored response. The
+ *   downstream requireScopes hook remains responsible for rejecting access.
+ * @internal
+ */
+export function hasReplayScopes(context) {
+    const required = context.state.__daloyRequiredScopes;
+    if (!Array.isArray(required) || required.length === 0)
+        return true;
+    const user = context.state.user;
+    if (!user || typeof user !== "object")
+        return false;
+    const owned = user.scopes;
+    return (Array.isArray(owned) && required.every((scope) => owned.includes(scope)));
+}

package/dist/jwk.d.ts

@@ -9,7 +9,8 @@ export interface JwkSet {
 }
 /**
  * Source for the verifier's public keys. Either an in-memory JWKS, a
- * `https://` URL (fetched with TTL caching), or a custom async resolver.
+ * `https://` URL (fetched directly with TTL caching; redirects are refused),
+ * or a custom async resolver.
  */
 export type JwkSource = JwkSet | string | (() => JwkSet | Promise<JwkSet>);
 /**
@@ -61,7 +62,8 @@ export interface JwkOptions {
     maxStaleSeconds?: number;
     /**
      * Optional `fetch` implementation override (mainly for tests). Defaults
-     * to global `fetch`.
+      * to global `fetch`. Overrides must honor `redirect: "error"` to preserve
+      * the configured HTTPS signing-key authority.
      */
     fetch?: typeof fetch;
     /**
@@ -79,6 +81,8 @@ export interface JwkOptions {
  * algorithms at construction time, requires every token to carry a `kid`
  * header, matches that `kid` against the JWKS, and cross-checks the JWT
  * header `alg` against the JWK's own `alg` (when present).
+ * URL sources are fetched with redirects disabled; redirecting refreshes
+ * follow the existing last-good-key grace policy, never installing new keys.
  *
  * @example
  * ```ts

package/dist/jwk.js

@@ -16,6 +16,7 @@
  *   `alg`, the two MUST agree (RFC 7517 §4.4 cross-check).
  * - `exp` / `nbf` / `iat` validated on every verify.
  * - JWKS URLs MUST be `https://` (refused at construction otherwise).
+ *   Redirects are refused so the HTTPS/key-authority boundary is not bypassed.
  * - Optional `verify(payload, ctx)` revalidation hook for
  *   revocation lists, token-version counters, etc.
  *
@@ -93,6 +94,7 @@ function makeJwksLoader(source, fetchImpl, ttlSeconds, maxStaleSeconds) {
                 try {
                     const res = await fetchImpl(source, {
                         headers: { accept: "application/json" },
+                        redirect: "error",
                     });
                     if (!res.ok) {
                         throw new Error(`jwk(): JWKS fetch failed with status ${res.status}.`);
@@ -144,6 +146,8 @@ function makeJwksLoader(source, fetchImpl, ttlSeconds, maxStaleSeconds) {
  * algorithms at construction time, requires every token to carry a `kid`
  * header, matches that `kid` against the JWKS, and cross-checks the JWT
  * header `alg` against the JWK's own `alg` (when present).
+ * URL sources are fetched with redirects disabled; redirecting refreshes
+ * follow the existing last-good-key grace policy, never installing new keys.
  *
  * @example
  * ```ts

package/dist/jwt.d.ts

@@ -34,7 +34,11 @@ export interface JwtVerified {
     /** Decoded claims payload after signature and time-claim checks passed. */
     readonly payload: Record<string, unknown>;
 }
-/** Key material accepted by the signer/verifier. */
+/**
+ * Key material accepted by the signer/verifier. Imported keys must match the
+ * selected algorithm's family, hash and curve. Every HMAC key format must meet
+ * the 32-byte minimum, and every RSA key must have a 2048-bit modulus or larger.
+ */
 export type JwtKeyMaterial = CryptoKey | Uint8Array | JsonWebKey;
 /** Options for {@link createJwtSigner}. */
 export interface JwtSignerOptions {
@@ -116,11 +120,14 @@ export interface JwtVerifierOptions {
  * function refuses payloads without an `exp` claim (unless
  * `acknowledgeNoExp: true` was set at construction outside production) and
  * refuses payloads whose `exp - (iat | now)` exceeds `maxLifetimeSeconds`.
+ * Imported keys must match the algorithm's family, hash and curve; HMAC and
+ * RSA strength floors apply to CryptoKey and JWK inputs as well as raw bytes.
  *
  * @param opts - Algorithm, key, and lifetime policy; see {@link JwtSignerOptions}.
  * @returns An object whose `sign(payload)` resolves to the compact JWS string.
  * @throws {JwtError} for `alg: "none"`, unknown algorithms, weak keys, a
  *   missing/invalid `maxLifetimeSeconds`, or `acknowledgeNoExp` in production.
+ *   `sign()` also rejects imported keys that violate algorithm or strength policy.
  * @since 0.21.0
  */
 export declare function createJwtSigner(opts: JwtSignerOptions): {
@@ -132,12 +139,15 @@ export declare function createJwtSigner(opts: JwtSignerOptions): {
  * `alg: "none"` and any token whose header `alg` is not in the allowlist;
  * refuses-at-construction when a symmetric algorithm (`HS*`) is mixed with
  * a JWK / JWKS-shaped key source (the documented confused-deputy attack).
+ * Imported keys must match the algorithm's family, hash and curve; HMAC and
+ * RSA strength floors apply to CryptoKey and JWK inputs as well as raw bytes.
  *
  * @param opts - Allowlist, key source, and claim checks; see {@link JwtVerifierOptions}.
  * @returns An object whose `verify(token)` resolves to the decoded
  *   {@link JwtVerified} or rejects with {@link JwtError}.
  * @throws {JwtError} at construction for an empty/invalid allowlist, `"none"`
  *   in the allowlist, weak HS* secrets, or HS* mixed with a JWK source.
+ *   `verify()` also rejects imported keys that violate algorithm or strength policy.
  * @since 0.21.0
  */
 export declare function createJwtVerifier(opts: JwtVerifierOptions): {

package/dist/jwt.js

@@ -158,7 +158,7 @@ async function importKey(alg, material, usage) {
     const params = algParams(alg);
     const c = getCrypto();
     if (isCryptoKey(material)) {
-        assertRsaModulusFloor(alg, material);
+        assertKeyPolicy(alg, material);
         return material;
     }
     if (material instanceof Uint8Array) {
@@ -185,11 +185,24 @@ async function importKey(alg, material, usage) {
                         ? { name: "RSASSA-PKCS1-v1_5", hash: params.hash }
                         : { name: "Ed25519" };
         const imported = await c.subtle.importKey("jwk", material, importAlgorithm, false, [usage]);
-        assertRsaModulusFloor(alg, imported);
+        assertKeyPolicy(alg, imported);
         return imported;
     }
     throw new JwtError("invalid_key", "jwt(): unsupported key material.");
 }
+function assertKeyPolicy(alg, key) {
+    const params = algParams(alg);
+    const algorithm = key.algorithm;
+    if (algorithm.name !== params.name ||
+        (params.hash !== undefined && params.name !== "ECDSA" && algorithm.hash?.name !== params.hash) ||
+        (params.namedCurve !== undefined && algorithm.namedCurve !== params.namedCurve)) {
+        throw new JwtError("key_algorithm_mismatch", `jwt(): key algorithm does not match ${alg}; the key family, hash and curve must match the declared JWT algorithm.`);
+    }
+    if (params.name === "HMAC" && (!Number.isFinite(algorithm.length) || algorithm.length < MIN_HS_KEY_BYTES * 8)) {
+        throw new JwtError("weak_hs_secret", `jwt(): ${alg} secret must be at least ${MIN_HS_KEY_BYTES} bytes (RFC 7518 §3.2).`);
+    }
+    assertRsaModulusFloor(alg, key);
+}
 /**
  * Refuse RSA keys whose modulus is shorter than {@link MIN_RSA_KEY_BITS}.
  * Only applies to `RS*` / `PS*` algorithms — non-RSA keys are ignored. The
@@ -224,11 +237,14 @@ function buildSignAlgorithm(alg) {
  * function refuses payloads without an `exp` claim (unless
  * `acknowledgeNoExp: true` was set at construction outside production) and
  * refuses payloads whose `exp - (iat | now)` exceeds `maxLifetimeSeconds`.
+ * Imported keys must match the algorithm's family, hash and curve; HMAC and
+ * RSA strength floors apply to CryptoKey and JWK inputs as well as raw bytes.
  *
  * @param opts - Algorithm, key, and lifetime policy; see {@link JwtSignerOptions}.
  * @returns An object whose `sign(payload)` resolves to the compact JWS string.
  * @throws {JwtError} for `alg: "none"`, unknown algorithms, weak keys, a
  *   missing/invalid `maxLifetimeSeconds`, or `acknowledgeNoExp` in production.
+ *   `sign()` also rejects imported keys that violate algorithm or strength policy.
  * @since 0.21.0
  */
 export function createJwtSigner(opts) {
@@ -338,12 +354,15 @@ function normalizeStringSet(value) {
  * `alg: "none"` and any token whose header `alg` is not in the allowlist;
  * refuses-at-construction when a symmetric algorithm (`HS*`) is mixed with
  * a JWK / JWKS-shaped key source (the documented confused-deputy attack).
+ * Imported keys must match the algorithm's family, hash and curve; HMAC and
+ * RSA strength floors apply to CryptoKey and JWK inputs as well as raw bytes.
  *
  * @param opts - Allowlist, key source, and claim checks; see {@link JwtVerifierOptions}.
  * @returns An object whose `verify(token)` resolves to the decoded
  *   {@link JwtVerified} or rejects with {@link JwtError}.
  * @throws {JwtError} at construction for an empty/invalid allowlist, `"none"`
  *   in the allowlist, weak HS* secrets, or HS* mixed with a JWK source.
+ *   `verify()` also rejects imported keys that violate algorithm or strength policy.
  * @since 0.21.0
  */
 export function createJwtVerifier(opts) {

package/dist/logger.d.ts

@@ -58,7 +58,7 @@ export interface LoggerRedactionOptions {
      * @since 0.69.0
      */
     redactCredentialLikeStrings?: boolean;
-    /** Maximum recursion depth when walking nested objects. Default: 6. */
+    /** Maximum recursion depth when walking nested objects. Deeper objects and arrays are censored in full. Default: 6. */
     maxDepth?: number;
 }
 /**
@@ -98,6 +98,8 @@ interface ResolvedRedaction {
  * matches `cfg.keys` and any string value shaped like a JWT (when
  * `cfg.redactJwt` is on) with `cfg.censor`. Exported for direct use by
  * custom logger implementations that want the same defaults.
+ * Objects and arrays beyond the depth budget are replaced with the censor,
+ * rather than serialized without inspecting their contents.
  *
  * @param record - Log record to redact. Mutated in place (cycle-safe, depth-capped).
  * @param cfg - Resolved redaction settings (key set, censor, JWT/credential toggles, max depth).

package/dist/logger.js

@@ -133,6 +133,8 @@ function redactString(value, cfg) {
  * matches `cfg.keys` and any string value shaped like a JWT (when
  * `cfg.redactJwt` is on) with `cfg.censor`. Exported for direct use by
  * custom logger implementations that want the same defaults.
+ * Objects and arrays beyond the depth budget are replaced with the censor,
+ * rather than serialized without inspecting their contents.
  *
  * @param record - Log record to redact. Mutated in place (cycle-safe, depth-capped).
  * @param cfg - Resolved redaction settings (key set, censor, JWT/credential toggles, max depth).
@@ -159,6 +161,9 @@ function walkRedact(node, cfg, depth, seen) {
                 if (replaced !== v)
                     node[i] = replaced;
             }
+            else if (v !== null && typeof v === "object" && depth >= cfg.maxDepth) {
+                node[i] = cfg.censor;
+            }
             else {
                 walkRedact(v, cfg, depth + 1, seen);
             }
@@ -178,6 +183,9 @@ function walkRedact(node, cfg, depth, seen) {
             if (replaced !== v)
                 obj[key] = replaced;
         }
+        else if (v !== null && typeof v === "object" && depth >= cfg.maxDepth) {
+            obj[key] = cfg.censor;
+        }
         else {
             walkRedact(v, cfg, depth + 1, seen);
         }

package/dist/mtls.d.ts

@@ -128,6 +128,8 @@ export interface PeerCertificateLike {
  * Normalize a Node `getPeerCertificate(true)` result into a
  * {@link ClientCertificate}. Returns `undefined` for the empty object Node
  * returns when the peer presented no certificate.
+ * Quoted SAN values are decoded without treating their embedded commas as
+ * identity separators. Malformed SAN lists yield no identities for allowlists.
  *
  * @param raw - The structured peer-certificate object from the TLS socket.
  * @param verified - Whether the socket reported `authorized === true` (the
@@ -142,9 +144,10 @@ export declare function normalizePeerCertificate(raw: PeerCertificateLike | null
  * Parse an Envoy `X-Forwarded-Client-Cert` (XFCC) header value into a
  * {@link ClientCertificate}. XFCC is a comma-separated list of proxy elements,
  * each a `;`-delimited set of `Key=Value` pairs (`Hash`, `Subject`, `URI`,
- * `DNS`, `Cert`, …). The **first** element is the client closest to the origin
- * and is the one returned. Because Envoy only emits XFCC for connections it
- * mutually authenticated, the result is marked `verified: true`.
+ * `DNS`, `Cert`, …). The **first** element is returned. The `verified: true`
+ * result is a trusted-proxy assertion, not cryptographic verification by this
+ * parser. The terminator must verify client certificates, strip incoming XFCC,
+ * and replace it with its own value. Append-only forwarding is insufficient.
  *
  * @param headerValue Raw XFCC header value; `null`/`undefined` are tolerated.
  * @returns The certificate parsed from the first XFCC element, or `undefined`
@@ -220,6 +223,8 @@ export interface ClientCertAuthOptions {
     /**
      * If set, the certificate's SHA-256 fingerprint must match one of these
      * (compared in constant time; colons/spaces and case are ignored).
+    * An empty list denies every certificate; omit this option to disable
+    * fingerprint restrictions while retaining the other certificate checks.
      */
     allowFingerprints?: readonly string[];
     /**
@@ -254,6 +259,9 @@ export interface ClientCertAuthOptions {
  * parsed from a trusted-proxy header, enforces verification + optional
  * allow-lists + validity window + a custom hook, and stamps the accepted
  * certificate on `ctx.state` for downstream handlers.
+ * Header mode requires an origin reachable only through a trusted terminator
+ * that strips and replaces identity headers after certificate verification.
+ * Fingerprint allowlists do not authenticate client-supplied header values.
  *
  * Rejection semantics:
  * - **No certificate presented** → `401` `application/problem+json` with