@daloyjs/core 1.3.1 → 1.3.3

package/dist/app.d.ts

@@ -1049,7 +1049,7 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      */
     private responseBodySchemaAuditDone;
     /**
-     * Cached merge of `options.hooks` only. Used on the cold 404/405 path
+    * Cached merge of `options.hooks` and secure-header response hooks. Used on the cold 404/405 path
      * and as the baseline for cross-origin guard decisions when no route
      * matches.
      */
@@ -1405,7 +1405,9 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * Defaults (secure-by-default):
      *  - path: `/healthz`
-     *  - rate-limit: 60 req/min per remote IP, in-memory (per-process)
+    *  - rate-limit: 60 req/min per trusted identity, or a shared global bucket,
+    *    in-memory (per-process). Verified-token and rejected requests use
+    *    separate budgets so unauthenticated traffic cannot exhaust probe capacity.
      *  - auth: opt-in via `token`. In production with `secureDefaults: true`,
      *    registration refuses to add the route without a `token` unless
      *    `acknowledgeUnauthenticated: true` is set, so an unguarded
@@ -1416,6 +1418,9 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * app.healthcheck({ token: process.env.HEALTH_TOKEN! });
      * ```
      *
+    * @param opts - Probe path, token, and rate-limit policy.
+    * @returns This app for chaining.
+    * @throws {Error} If production authentication is missing without acknowledgment.
      * @since 0.18.0
      */
     healthcheck(opts?: HealthRouteOptions): this;
@@ -1428,6 +1433,9 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * Defaults match {@link App.healthcheck} (path defaults to `/readyz`).
      *
+    * @param opts - Probe path, token, and rate-limit policy.
+    * @returns This app for chaining.
+    * @throws {Error} If production authentication is missing without acknowledgment.
      * @since 0.18.0
      */
     readinesscheck(opts?: HealthRouteOptions): this;
@@ -1445,7 +1453,8 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * The scrape route inherits the same hardened posture as
      * {@link App.healthcheck}: optional bearer token compared via
-     * {@link timingSafeEqual}, a per-IP fixed-window rate limit, and a
+    * {@link timingSafeEqual}, a per-trusted-identity (otherwise global) fixed-window
+    * rate limit with separate verified-token and rejected-request budgets, and a
      * refuse-to-boot guard in production (an unauthenticated `/metrics`
      * endpoint leaks internal route names, latency, and traffic volume) unless
      * a token is supplied or `acknowledgeUnauthenticated: true` is passed.
@@ -1462,6 +1471,7 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * @param opts - Path, auth, rate-limit, registry, and label configuration.
      * @returns `this` for chaining.
+    * @throws {Error} If production authentication is missing without acknowledgment.
      * @since 0.37.0
      */
     metrics(opts?: MetricsRouteOptions): this;
@@ -1674,6 +1684,7 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * ```
      *
      * @param hooks - Hook bundle applied to subsequent routes.
+    * Secure-header hooks also apply to unmatched routes and early rejections.
      * @returns This `App` instance for chaining.
      */
     use(hooks: Hooks): this;

package/dist/app.js

@@ -479,7 +479,7 @@ export class App {
      */
     responseBodySchemaAuditDone = false;
     /**
-     * Cached merge of `options.hooks` only. Used on the cold 404/405 path
+    * Cached merge of `options.hooks` and secure-header response hooks. Used on the cold 404/405 path
      * and as the baseline for cross-origin guard decisions when no route
      * matches.
      */
@@ -487,7 +487,12 @@ export class App {
     _globalCorsAllowsCache;
     get globalHooks() {
         if (this._globalHooksCache === undefined) {
-            this._globalHooksCache = mergeHooks([this.options.hooks ?? {}]);
+            this._globalHooksCache = mergeHooks([
+                this.options.hooks ?? {},
+                ...this.groupHooks
+                    .filter(hook => hook[SECURE_HEADERS_MARKER] === true)
+                    .map(hook => ({ onSend: hook.onSend, onResponse: hook.onResponse })),
+            ]);
         }
         return this._globalHooksCache;
     }
@@ -829,8 +834,13 @@ export class App {
             return;
         }
         const origin = request.headers.get("origin");
-        if (!origin || origin === "null")
+        if (!origin)
             return;
+        if (origin === "null") {
+            if (corsOriginAllows.some((allows) => allows(origin)))
+                return;
+            throw new ForbiddenError("Cross-origin state-changing request rejected: opaque Origin requires an allowing cors() policy.");
+        }
         // Fast path: when both the Origin header and the request URL are in the
         // trivially-normalized shape (lowercase ASCII scheme://host[:port] with
         // no userinfo / percent-escapes / IPv6 brackets), their origins can be
@@ -1784,7 +1794,9 @@ export class App {
      *
      * Defaults (secure-by-default):
      *  - path: `/healthz`
-     *  - rate-limit: 60 req/min per remote IP, in-memory (per-process)
+    *  - rate-limit: 60 req/min per trusted identity, or a shared global bucket,
+    *    in-memory (per-process). Verified-token and rejected requests use
+    *    separate budgets so unauthenticated traffic cannot exhaust probe capacity.
      *  - auth: opt-in via `token`. In production with `secureDefaults: true`,
      *    registration refuses to add the route without a `token` unless
      *    `acknowledgeUnauthenticated: true` is set, so an unguarded
@@ -1795,6 +1807,9 @@ export class App {
      * app.healthcheck({ token: process.env.HEALTH_TOKEN! });
      * ```
      *
+    * @param opts - Probe path, token, and rate-limit policy.
+    * @returns This app for chaining.
+    * @throws {Error} If production authentication is missing without acknowledgment.
      * @since 0.18.0
      */
     healthcheck(opts = {}) {
@@ -1813,6 +1828,9 @@ export class App {
      *
      * Defaults match {@link App.healthcheck} (path defaults to `/readyz`).
      *
+    * @param opts - Probe path, token, and rate-limit policy.
+    * @returns This app for chaining.
+    * @throws {Error} If production authentication is missing without acknowledgment.
      * @since 0.18.0
      */
     readinesscheck(opts = {}) {
@@ -1847,7 +1865,8 @@ export class App {
      *
      * The scrape route inherits the same hardened posture as
      * {@link App.healthcheck}: optional bearer token compared via
-     * {@link timingSafeEqual}, a per-IP fixed-window rate limit, and a
+    * {@link timingSafeEqual}, a per-trusted-identity (otherwise global) fixed-window
+    * rate limit with separate verified-token and rejected-request budgets, and a
      * refuse-to-boot guard in production (an unauthenticated `/metrics`
      * endpoint leaks internal route names, latency, and traffic volume) unless
      * a token is supplied or `acknowledgeUnauthenticated: true` is passed.
@@ -1864,6 +1883,7 @@ export class App {
      *
      * @param opts - Path, auth, rate-limit, registry, and label configuration.
      * @returns `this` for chaining.
+    * @throws {Error} If production authentication is missing without acknowledgment.
      * @since 0.37.0
      */
     metrics(opts = {}) {
@@ -1931,8 +1951,11 @@ export class App {
             // Prometheus text exposition rendered by the framework registry.
             acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
+                const authMatch = token === undefined ? null : /^Bearer\s+(.+)$/i.exec(request.headers.get("authorization") ?? "");
+                const tokenAccepted = token !== undefined && authMatch !== null && timingSafeEqual(authMatch[1], token);
                 if (buckets && rateLimitConfig) {
-                    const key = healthRouteKey(request, trustProxyHeaders);
+                    const identity = healthRouteKey(request, trustProxyHeaders);
+                    const key = token === undefined ? identity : `${tokenAccepted ? "verified" : "unverified"}\u0000${identity}`;
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
@@ -1949,16 +1972,14 @@ export class App {
                     }
                 }
                 if (token !== undefined) {
-                    const h = request.headers.get("authorization") ?? "";
-                    const m = /^Bearer\s+(.+)$/i.exec(h);
-                    if (!m) {
+                    if (!authMatch) {
                         throw new HttpError(401, {
                             type: "https://daloyjs.dev/errors/unauthorized",
                             title: "Unauthorized",
                             detail: "Metrics scrape requires a bearer token.",
                         }, { "www-authenticate": 'Bearer realm="metrics"' });
                     }
-                    if (!timingSafeEqual(m[1], token)) {
+                    if (!tokenAccepted) {
                         throw new ForbiddenError("Invalid metrics scrape token.");
                     }
                 }
@@ -2222,8 +2243,11 @@ export class App {
             // Framework-serialized probe payload; missing schema is intentional.
             acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
+                const authMatch = token === undefined ? null : /^Bearer\s+(.+)$/i.exec(request.headers.get("authorization") ?? "");
+                const tokenAccepted = token !== undefined && authMatch !== null && timingSafeEqual(authMatch[1], token);
                 if (buckets && rateLimitConfig) {
-                    const key = healthRouteKey(request, trustProxyHeaders);
+                    const identity = healthRouteKey(request, trustProxyHeaders);
+                    const key = token === undefined ? identity : `${tokenAccepted ? "verified" : "unverified"}\u0000${identity}`;
                     const now = Date.now();
                     const entry = buckets.get(key);
                     if (!entry || entry.resetMs <= now) {
@@ -2240,16 +2264,14 @@ export class App {
                     }
                 }
                 if (token !== undefined) {
-                    const h = request.headers.get("authorization") ?? "";
-                    const m = /^Bearer\s+(.+)$/i.exec(h);
-                    if (!m) {
+                    if (!authMatch) {
                         throw new HttpError(401, {
                             type: "https://daloyjs.dev/errors/unauthorized",
                             title: "Unauthorized",
                             detail: "Health probe requires a bearer token.",
                         }, { "www-authenticate": 'Bearer realm="health"' });
                     }
-                    if (!timingSafeEqual(m[1], token)) {
+                    if (!tokenAccepted) {
                         throw new ForbiddenError("Invalid health probe token.");
                     }
                 }
@@ -2459,6 +2481,7 @@ export class App {
      * ```
      *
      * @param hooks - Hook bundle applied to subsequent routes.
+    * Secure-header hooks also apply to unmatched routes and early rejections.
      * @returns This `App` instance for chaining.
      */
     use(hooks) {
@@ -2480,6 +2503,7 @@ export class App {
         }
         this.groupHooks.push(hooks);
         this._coldPathHooksCache = undefined;
+        this._globalHooksCache = undefined;
         if (hooks[CORS_HOOK_MARKER] === true) {
             this.corsOriginAllows = corsOriginAllowsFromHooks(this.groupHooks);
         }

package/dist/compression.d.ts

@@ -115,6 +115,8 @@ export declare function _resetCompressionRuntimeProbeForTests(): void;
  * - response already declares a `Content-Encoding`;
  * - response declares a `Set-Cookie` (response is mutating auth state);
  * - response body byte length is below `minimumSize` (default `1024`);
+ * - response body exceeds `maxCompressibleBytes` while reading; only the
+ *   capture clone is cancelled, without waiting for the client to consume it;
  * - response `Content-Type` is in the always-on already-compressed
  *   deny-list (image/video/audio/archives/fonts/wasm/pdf, with
  *   `image/svg+xml` carved back in as compressible XML).

package/dist/compression.js

@@ -20,6 +20,7 @@
  *
  * @since 0.25.0
  */
+import { readResponseBodyUpTo } from "./internal-body.js";
 /**
  * Internal marker stamped on the hook so a future audit gate can confirm
  * the BREACH-aware middleware is installed (audit-item parity).
@@ -217,57 +218,6 @@ function normalizeOptionTokens(values, optionName) {
     }
     return Object.freeze(normalized);
 }
-/**
- * Read a response body up to `maxBytes`. Returns `null` if the stream
- * exceeds the cap (body is cancelled; caller should leave the response
- * uncompressed). Returns an empty buffer when there is no body.
- *
- * @param res - Response whose body will be consumed (pass a clone).
- * @param maxBytes - Inclusive upper bound on buffered size.
- */
-async function readBodyUpTo(res, maxBytes) {
-    if (!res.body)
-        return new Uint8Array(0);
-    const reader = res.body.getReader();
-    const chunks = [];
-    let total = 0;
-    try {
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            if (!value || value.byteLength === 0)
-                continue;
-            total += value.byteLength;
-            if (total > maxBytes) {
-                await reader.cancel();
-                return null;
-            }
-            chunks.push(value);
-        }
-    }
-    catch {
-        try {
-            await reader.cancel();
-        }
-        catch {
-            /* ignore */
-        }
-        return null;
-    }
-    if (chunks.length === 0)
-        return new Uint8Array(0);
-    if (chunks.length === 1)
-        return chunks[0];
-    const out = new Uint8Array(total);
-    let offset = 0;
-    for (const c of chunks) {
-        out.set(c, offset);
-        offset += c.byteLength;
-    }
-    return out;
-}
 async function compressBytes(bytes, encoding) {
     const Stream = globalThis.CompressionStream;
     const cs = new Stream(encoding);
@@ -317,6 +267,8 @@ async function compressBytes(bytes, encoding) {
  * - response already declares a `Content-Encoding`;
  * - response declares a `Set-Cookie` (response is mutating auth state);
  * - response body byte length is below `minimumSize` (default `1024`);
+ * - response body exceeds `maxCompressibleBytes` while reading; only the
+ *   capture clone is cancelled, without waiting for the client to consume it;
  * - response `Content-Type` is in the always-on already-compressed
  *   deny-list (image/video/audio/archives/fonts/wasm/pdf, with
  *   `image/svg+xml` carved back in as compressible XML).
@@ -407,7 +359,7 @@ export function compression(opts = {}) {
                 if (Number.isFinite(n) && n > maxCompressibleBytes)
                     return undefined;
             }
-            const original = await readBodyUpTo(res.clone(), maxCompressibleBytes);
+            const original = await readResponseBodyUpTo(res.clone(), maxCompressibleBytes).catch(() => null);
             if (original === null)
                 return undefined; // exceeded cap while streaming
             if (original.byteLength < minimumSize)

package/dist/conn-info.d.ts

@@ -108,7 +108,7 @@ export declare function assertBehindProxy(cfg: BehindProxyConfig | undefined): v
  * @param header - Raw `X-Forwarded-For` header value, or `null` when absent.
  * @param hops - Declared number of trusted proxy hops (must be >= 1).
  * @returns The client IP at the declared hop, or `undefined` when the chain
- *   is too short or `hops < 1`.
+ *   is too short, the selected slot is not an IP, or `hops < 1`.
  * @internal
  */
 export declare function pickForwardedForByHops(header: string | null, hops: number): string | undefined;
@@ -216,7 +216,8 @@ export declare function resolveTrustedProxyMatchers(name: string, opts: {
  *   {@link resolveTrustedProxyMatchers}. When supplied, forwarded headers
  *   are honoured only if the immediate peer matches; otherwise `undefined`.
  * @returns The resolved client IP, or `undefined` when no forwarded identity
- *   is available. Callers decide their own posture for `undefined`
+ *   is available. Placeholder and malformed identities are rejected without
+ *   shifting the selected hop. Callers decide their own posture for `undefined`
  *   (fail-closed 403, fail-open skip, or a shared `"global"` bucket).
  * @since 1.0.0-rc.7
  */

package/dist/conn-info.js

@@ -101,7 +101,7 @@ export function assertBehindProxy(cfg) {
  * @param header - Raw `X-Forwarded-For` header value, or `null` when absent.
  * @param hops - Declared number of trusted proxy hops (must be >= 1).
  * @returns The client IP at the declared hop, or `undefined` when the chain
- *   is too short or `hops < 1`.
+ *   is too short, the selected slot is not an IP, or `hops < 1`.
  * @internal
  */
 export function pickForwardedForByHops(header, hops) {
@@ -109,13 +109,13 @@ export function pickForwardedForByHops(header, hops) {
         return undefined;
     const parts = header
         .split(",")
-        .map((p) => p.trim())
-        .filter((p) => p.length > 0);
+        .map((p) => p.trim());
     if (parts.length < hops)
         return undefined;
     // Right-to-left: index 0 is the last hop closest to Daloy. The client
     // typically lives at parts[parts.length - hops].
-    return parts[parts.length - hops];
+    const selected = parts[parts.length - hops];
+    return selected && parseIp(selected) ? selected : undefined;
 }
 /**
  * Validate a middleware's forwarded-header trust options and resolve them into
@@ -274,7 +274,8 @@ function isTrustedPeer(request, trustedPeers) {
  *   {@link resolveTrustedProxyMatchers}. When supplied, forwarded headers
  *   are honoured only if the immediate peer matches; otherwise `undefined`.
  * @returns The resolved client IP, or `undefined` when no forwarded identity
- *   is available. Callers decide their own posture for `undefined`
+ *   is available. Placeholder and malformed identities are rejected without
+ *   shifting the selected hop. Callers decide their own posture for `undefined`
  *   (fail-closed 403, fail-open skip, or a shared `"global"` bucket).
  * @since 1.0.0-rc.7
  */
@@ -282,9 +283,9 @@ export function resolveForwardedClientIp(request, hops = 1, trustedPeers) {
     if (trustedPeers !== undefined && !isTrustedPeer(request, trustedPeers)) {
         return undefined;
     }
-    const picked = pickForwardedForByHops(request.headers.get("x-forwarded-for"), hops);
-    if (picked)
-        return picked;
+    const forwarded = request.headers.get("x-forwarded-for");
+    if (forwarded !== null)
+        return pickForwardedForByHops(forwarded, hops);
     // Fail closed past one hop. A chain that produced fewer than `hops` entries
     // means the request never traversed the declared topology — a direct-to-origin
     // request that skipped the CDN, say — so no forwarded value it carries is
@@ -298,7 +299,8 @@ export function resolveForwardedClientIp(request, hops = 1, trustedPeers) {
     // identity", not "the identity the caller asked me to believe".
     if (hops !== 1)
         return undefined;
-    return request.headers.get("x-real-ip") ?? undefined;
+    const realIp = request.headers.get("x-real-ip")?.trim();
+    return realIp && parseIp(realIp) ? realIp : undefined;
 }
 /**
  * Compiled-CIDR cache for {@link resolveClientIp}'s `{ cidrs }` branch. Keyed

package/dist/fetch-guard.d.ts

@@ -254,7 +254,16 @@ export interface FetchGuardOptions {
  * @param options - Guard configuration; see {@link FetchGuardOptions}. Omit
  *   for the strict default posture (public IPs over `http:`/`https:` only).
  * @returns A `fetch`-compatible function that validates every hop (including
- *   redirects) and throws {@link SsrfBlockedError} on refusal.
+ *   redirects). Cross-origin redirects remove `Authorization`, `Cookie`,
+ *   `Proxy-Authorization`, and explicit `Host` headers; same-origin redirects
+ *   preserve them. Custom credential headers must not be used with untrusted
+ *   redirect destinations; use `redirect: "error"` or `"manual"` in that case.
+ * @throws {Error} If no underlying fetch implementation is available.
+ * @throws {SsrfBlockedError} The returned function throws when a destination
+ *   or redirect chain violates policy, including malformed URLs and userinfo.
+ *   Userinfo is removed from error URLs; network errors propagate.
+ * @throws {TypeError} The returned function throws on invalid requests or
+ *   redirects when `redirect: "error"` is selected.
  * @since 0.34.0
  */
 export declare function fetchGuard(options?: FetchGuardOptions): typeof fetch;

package/dist/fetch-guard.js

@@ -176,7 +176,16 @@ const UNIQUE_LOCAL = ["fc00::/7"];
  * @param options - Guard configuration; see {@link FetchGuardOptions}. Omit
  *   for the strict default posture (public IPs over `http:`/`https:` only).
  * @returns A `fetch`-compatible function that validates every hop (including
- *   redirects) and throws {@link SsrfBlockedError} on refusal.
+ *   redirects). Cross-origin redirects remove `Authorization`, `Cookie`,
+ *   `Proxy-Authorization`, and explicit `Host` headers; same-origin redirects
+ *   preserve them. Custom credential headers must not be used with untrusted
+ *   redirect destinations; use `redirect: "error"` or `"manual"` in that case.
+ * @throws {Error} If no underlying fetch implementation is available.
+ * @throws {SsrfBlockedError} The returned function throws when a destination
+ *   or redirect chain violates policy, including malformed URLs and userinfo.
+ *   Userinfo is removed from error URLs; network errors propagate.
+ * @throws {TypeError} The returned function throws on invalid requests or
+ *   redirects when `redirect: "error"` is selected.
  * @since 0.34.0
  */
 export function fetchGuard(options = {}) {
@@ -303,9 +312,9 @@ export function fetchGuard(options = {}) {
                 pre = new URL(input);
             }
             catch {
-                pre = undefined;
+                throw new SsrfBlockedError("[invalid URL]", "invalid-url");
             }
-            if (pre && (pre.username !== "" || pre.password !== "")) {
+            if (pre.username !== "" || pre.password !== "") {
                 pre.username = "";
                 pre.password = "";
                 throw new SsrfBlockedError(pre.toString(), "credentials-in-url");
@@ -354,6 +363,12 @@ export function fetchGuard(options = {}) {
             catch {
                 throw new SsrfBlockedError(loc, "invalid-url");
             }
+            if (next.username !== "" || next.password !== "") {
+                next.username = "";
+                next.password = "";
+                void res.body?.cancel().catch(() => undefined);
+                throw new SsrfBlockedError(next.toString(), "credentials-in-url");
+            }
             // Per fetch spec: 303 (and 301/302 for non-GET/HEAD in practice) downgrade to GET.
             const method = request.method.toUpperCase();
             const shouldDowngrade = res.status === 303 ||
@@ -371,6 +386,12 @@ export function fetchGuard(options = {}) {
                     referrerPolicy: request.referrerPolicy,
                 })
                 : new Request(next, request);
+            if (next.origin !== currentUrl.origin) {
+                request.headers.delete("authorization");
+                request.headers.delete("cookie");
+                request.headers.delete("proxy-authorization");
+                request.headers.delete("host");
+            }
             currentUrl = next;
         }
     };

package/dist/fetch-resilience.d.ts

@@ -283,6 +283,10 @@ export interface ResilientFetchOptions {
  * Wrap a `fetch` with per-call timeout, retry-with-backoff, and a shared
  * circuit breaker. The returned function has the same call signature as
  * the global `fetch`.
+ * Response bodies discarded for a retry are cancelled before backoff without
+ * waiting for producer cancellation. The final response remains caller-owned.
+ * Caller cancellation preserves arbitrary abort reasons and never counts as
+ * an upstream failure or schedules another retry.
  *
  * Layer it over {@link fetchGuard} to keep SSRF protection underneath:
  *

package/dist/fetch-resilience.js

@@ -348,6 +348,10 @@ function isAbortError(err) {
  * Wrap a `fetch` with per-call timeout, retry-with-backoff, and a shared
  * circuit breaker. The returned function has the same call signature as
  * the global `fetch`.
+ * Response bodies discarded for a retry are cancelled before backoff without
+ * waiting for producer cancellation. The final response remains caller-owned.
+ * Caller cancellation preserves arbitrary abort reasons and never counts as
+ * an upstream failure or schedules another retry.
  *
  * Layer it over {@link fetchGuard} to keep SSRF protection underneath:
  *
@@ -416,6 +420,7 @@ export function resilientFetch(options = {}) {
         // the caller's signal can be combined per attempt.
         const request = new Request(input, init);
         const callerSignal = init?.signal ?? request.signal;
+        callerSignal?.throwIfAborted();
         const run = async () => {
             let lastError;
             for (let attempt = 1; attempt <= retries + 1; attempt++) {
@@ -428,8 +433,7 @@ export function resilientFetch(options = {}) {
                 catch (err) {
                     cleanup();
                     // Caller cancelled: never retry, never count as upstream failure.
-                    if (isAbortError(err) && callerSignal?.aborted)
-                        throw err;
+                    callerSignal?.throwIfAborted();
                     // An SSRF refusal from an underlying fetchGuard is a hard, terminal
                     // decision about the request itself — never retried.
                     if (err instanceof Error && err.name === "SsrfBlockedError")
@@ -441,8 +445,7 @@ export function resilientFetch(options = {}) {
                         const delay = backoffFor(attempt);
                         options.onRetry?.(ctx, delay);
                         await sleep(delay, callerSignal ?? undefined);
-                        if (callerSignal?.aborted)
-                            throw lastError;
+                        callerSignal?.throwIfAborted();
                         continue;
                     }
                     throw lastError;
@@ -452,9 +455,9 @@ export function resilientFetch(options = {}) {
                 if (attempt <= retries && shouldRetry(ctx)) {
                     const delay = backoffFor(attempt, response);
                     options.onRetry?.(ctx, delay);
+                    void response.body?.cancel().catch(() => undefined);
                     await sleep(delay, callerSignal ?? undefined);
-                    if (callerSignal?.aborted)
-                        return response;
+                    callerSignal?.throwIfAborted();
                     continue;
                 }
                 return response;
@@ -476,7 +479,7 @@ export function resilientFetch(options = {}) {
             // SSRF refusals and caller aborts are not upstream health signals.
             if (err instanceof CircuitOpenError)
                 throw err;
-            const isCallerAbort = isAbortError(err) && callerSignal?.aborted;
+            const isCallerAbort = callerSignal?.aborted;
             const isSsrf = err instanceof Error && err.name === "SsrfBlockedError";
             if (isCallerAbort || isSsrf)
                 breaker.release();

package/dist/http-signatures.d.ts

@@ -39,7 +39,11 @@ import type { Hooks } from "./types.js";
  * @since 0.37.0
  */
 export type HttpSignatureAlgorithm = "hmac-sha256" | "ed25519" | "ecdsa-p256-sha256" | "ecdsa-p384-sha384" | "rsa-pss-sha512" | "rsa-v1_5-sha256";
-/** 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, with the same 32-byte HMAC and
+ * 2048-bit RSA minimums as raw keys.
+ */
 export type HttpSignatureKeyMaterial = CryptoKey | Uint8Array | JsonWebKey;
 /**
  * A resolved verification key, optionally pinning the algorithm it may be used
@@ -134,7 +138,8 @@ export interface MessageSignature {
  * @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
@@ -245,7 +250,8 @@ export interface VerifyMessageOptions {
     requiredTag?: string;
     /**
      * Replay check. When provided, a `nonce` is required and the signature is
-     * rejected if this returns `true`.
+     * rejected if this returns `true`. Called only after cryptographic verification
+     * succeeds; implementations that record nonces must check and record atomically.
      */
     isReplay?: (nonce: string, info: KeyResolutionInfo) => boolean | Promise<boolean>;
     /** Clock used for age checks. Returns milliseconds. Defaults to `Date.now`. */
@@ -255,6 +261,7 @@ export interface VerifyMessageOptions {
  * 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
@@ -300,6 +307,8 @@ export interface HttpSignatureAuthOptions extends Omit<VerifyMessageOptions, "me
  * 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}.