@daloyjs/core 1.0.0-rc.3 → 1.0.0-rc.5

package/dist/compression.js

@@ -217,6 +217,57 @@ 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);
@@ -297,6 +348,16 @@ export function compression(opts = {}) {
         minimumSize > 2 ** 31 - 1) {
         throw new TypeError("compression(): `minimumSize` must be a finite non-negative integer.");
     }
+    const maxCompressibleBytes = opts.maxCompressibleBytes === undefined ? 1_048_576 : opts.maxCompressibleBytes;
+    if (!Number.isFinite(maxCompressibleBytes) ||
+        !Number.isInteger(maxCompressibleBytes) ||
+        maxCompressibleBytes <= 0 ||
+        maxCompressibleBytes > 2 ** 31 - 1) {
+        throw new TypeError("compression(): `maxCompressibleBytes` must be a positive integer <= 2**31-1.");
+    }
+    if (minimumSize > maxCompressibleBytes) {
+        throw new TypeError("compression(): `minimumSize` must not exceed `maxCompressibleBytes`.");
+    }
     const serverPreferred = opts.encodings && opts.encodings.length > 0
         ? Object.freeze([...opts.encodings])
         : Object.freeze(["br", "gzip", "deflate"]);
@@ -338,7 +399,17 @@ export function compression(opts = {}) {
             const chosen = pickEncoding(accept, serverPreferred, runtimeSupported);
             if (!chosen)
                 return undefined;
-            const original = new Uint8Array(await res.clone().arrayBuffer());
+            // Fast-path skip when Content-Length already exceeds the compress cap
+            // (avoids buffering a known-huge body just to discard it).
+            const declaredLength = res.headers.get("content-length");
+            if (declaredLength !== null) {
+                const n = Number(declaredLength);
+                if (Number.isFinite(n) && n > maxCompressibleBytes)
+                    return undefined;
+            }
+            const original = await readBodyUpTo(res.clone(), maxCompressibleBytes);
+            if (original === null)
+                return undefined; // exceeded cap while streaming
             if (original.byteLength < minimumSize)
                 return undefined;
             const compressed = await compressBytes(original, chosen);

package/dist/conn-info.d.ts

@@ -67,8 +67,11 @@ interface MutableConnInfo {
 }
 /**
  * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
- * by the Node / Bun / Deno / Cloudflare / Vercel / Lambda adapters before
- * `app.fetch(request)`.
+ * by the Node / Bun / Deno / Lambda adapters before `app.fetch(request)`.
+ * The pure edge delegators (Cloudflare, Vercel, Fastly) expose no peer
+ * socket to attach — on those platforms the client address arrives via
+ * platform-set headers, which are governed by the `behindProxy` /
+ * `trustProxyHeaders` policies instead.
  *
  * @param request - Incoming request to tag (stored under a private symbol).
  * @param info - Connection metadata gathered by the adapter.

package/dist/conn-info.js

@@ -21,8 +21,11 @@
 const CONN_INFO_SYMBOL = Symbol.for("daloyjs.connInfo");
 /**
  * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
- * by the Node / Bun / Deno / Cloudflare / Vercel / Lambda adapters before
- * `app.fetch(request)`.
+ * by the Node / Bun / Deno / Lambda adapters before `app.fetch(request)`.
+ * The pure edge delegators (Cloudflare, Vercel, Fastly) expose no peer
+ * socket to attach — on those platforms the client address arrives via
+ * platform-set headers, which are governed by the `behindProxy` /
+ * `trustProxyHeaders` policies instead.
  *
  * @param request - Incoming request to tag (stored under a private symbol).
  * @param info - Connection metadata gathered by the adapter.

package/dist/docs.d.ts

@@ -233,16 +233,12 @@ export interface RedocConfiguration {
     };
 }
 /**
- * Override CDN URLs and pin Subresource Integrity (SRI) hashes for the docs
- * UI assets.
+ * Override the version-pinned CDN URLs and Subresource Integrity (SRI) hashes
+ * used by the docs UI assets.
  *
- * Supplying an `*Integrity` value emits an `integrity="…"` attribute plus a
- * `crossorigin` attribute on the matching `<script>` / `<link>` tag so the
- * browser refuses to execute a CDN asset whose bytes don't match the pinned
- * hash. SRI is only meaningful against a **version-pinned** URL
- * (e.g. `…/@scalar/api-reference@1.25.0`); pair each integrity hash with a
- * pinned `*Url`, since the framework's default URLs intentionally track the
- * latest upstream release and therefore cannot carry a stable hash.
+ * Defaults use exact upstream versions with matching SHA-384 digests. A custom
+ * URL without a custom `*Integrity` value intentionally omits SRI; pair URL
+ * overrides with hashes whose exact bytes you control or have verified.
  *
  * @since 0.37.0
  */

package/dist/docs.js

@@ -8,6 +8,18 @@
  * (You can self-host the assets if your CSP forbids CDNs.)
  */
 const JSDELIVR_ORIGIN = "https://cdn.jsdelivr.net";
+const DEFAULT_SCALAR_SCRIPT_URL = `${JSDELIVR_ORIGIN}/npm/@scalar/api-reference@1.62.5`;
+const DEFAULT_SCALAR_SCRIPT_INTEGRITY = "sha384-jVBCKhcCfx34USN27x4iQK1SBNdL/HxKq3KuBAxTS4WPaP5w80K4fjpwB+DezJL5";
+const DEFAULT_SWAGGER_CSS_URL = `${JSDELIVR_ORIGIN}/npm/swagger-ui-dist@5.32.8/swagger-ui.css`;
+const DEFAULT_SWAGGER_CSS_INTEGRITY = "sha384-9Q2fpS+xeS4ffJy6CagnwoUl+4ldAYhOs9pgZuEKxypVModhmZFzeMlvVsAjf7uT";
+const DEFAULT_SWAGGER_BUNDLE_URL = `${JSDELIVR_ORIGIN}/npm/swagger-ui-dist@5.32.8/swagger-ui-bundle.js`;
+const DEFAULT_SWAGGER_BUNDLE_INTEGRITY = "sha384-IKpAWwsTL0pcw7/Amtnt2eXF4P1BK64WNuY2E/RG15SWLUW5HXzFuyqCSAr/DP8C";
+const DEFAULT_REDOC_SCRIPT_URL = `${JSDELIVR_ORIGIN}/npm/redoc@2.5.3/bundles/redoc.standalone.js`;
+const DEFAULT_REDOC_SCRIPT_INTEGRITY = "sha384-xiEssMQFSpSfLbzRZCGfxxIM5QDb2DTrU6vyoZdp2sV1L6pmOMy6MpTtUoLbpC96";
+const DEFAULT_ASYNCAPI_SCRIPT_URL = `${JSDELIVR_ORIGIN}/npm/@asyncapi/react-component@3.1.4/browser/standalone/index.js`;
+const DEFAULT_ASYNCAPI_SCRIPT_INTEGRITY = "sha384-ZI+8twyvBIiWAquvsA8HFRvWjFn7l9/JlCHI3sekdQ6s7xK8ZDT6TDQOickRDQ0t";
+const DEFAULT_ASYNCAPI_STYLE_URL = `${JSDELIVR_ORIGIN}/npm/@asyncapi/react-component@3.1.4/styles/default.min.css`;
+const DEFAULT_ASYNCAPI_STYLE_INTEGRITY = "sha384-hcBf581bZwhXX8SyfsmPFkODqlIruk2b6gfX+b2WuK+am42GxstWJlJLiosKZoiL";
 /**
  * Matches a single Subresource Integrity digest: a `sha256-`/`sha384-`/
  * `sha512-` prefix followed by standard base64 (with up to two `=` pads).
@@ -53,8 +65,10 @@ function integrityAttr(integrity, crossOrigin) {
 export function scalarHtml(opts) {
     const title = escapeHtml(opts.title ?? "API Reference");
     const url = escapeHtml(opts.specUrl);
-    const scriptUrl = escapeHtml(opts.assets?.scalarScriptUrl ?? `${JSDELIVR_ORIGIN}/npm/@scalar/api-reference`);
-    const scriptSri = integrityAttr(opts.assets?.scalarScriptIntegrity, opts.assets?.crossOrigin);
+    const usesDefaultScript = opts.assets?.scalarScriptUrl === undefined;
+    const scriptUrl = escapeHtml(opts.assets?.scalarScriptUrl ?? DEFAULT_SCALAR_SCRIPT_URL);
+    const scriptSri = integrityAttr(opts.assets?.scalarScriptIntegrity ??
+        (usesDefaultScript ? DEFAULT_SCALAR_SCRIPT_INTEGRITY : undefined), opts.assets?.crossOrigin);
     const nonce = nonceAttr(opts.scriptNonce);
     const configuration = scalarConfigurationAttr(opts.specUrl, opts.configuration);
     return `<!doctype html>
@@ -82,10 +96,14 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  */
 export function swaggerUiHtml(opts) {
     const title = escapeHtml(opts.title ?? "API Docs");
-    const cssUrl = escapeHtml(opts.assets?.swaggerUiCssUrl ?? `${JSDELIVR_ORIGIN}/npm/swagger-ui-dist/swagger-ui.css`);
-    const bundleUrl = escapeHtml(opts.assets?.swaggerUiBundleUrl ?? `${JSDELIVR_ORIGIN}/npm/swagger-ui-dist/swagger-ui-bundle.js`);
-    const cssSri = integrityAttr(opts.assets?.swaggerUiCssIntegrity, opts.assets?.crossOrigin);
-    const bundleSri = integrityAttr(opts.assets?.swaggerUiBundleIntegrity, opts.assets?.crossOrigin);
+    const usesDefaultCss = opts.assets?.swaggerUiCssUrl === undefined;
+    const usesDefaultBundle = opts.assets?.swaggerUiBundleUrl === undefined;
+    const cssUrl = escapeHtml(opts.assets?.swaggerUiCssUrl ?? DEFAULT_SWAGGER_CSS_URL);
+    const bundleUrl = escapeHtml(opts.assets?.swaggerUiBundleUrl ?? DEFAULT_SWAGGER_BUNDLE_URL);
+    const cssSri = integrityAttr(opts.assets?.swaggerUiCssIntegrity ??
+        (usesDefaultCss ? DEFAULT_SWAGGER_CSS_INTEGRITY : undefined), opts.assets?.crossOrigin);
+    const bundleSri = integrityAttr(opts.assets?.swaggerUiBundleIntegrity ??
+        (usesDefaultBundle ? DEFAULT_SWAGGER_BUNDLE_INTEGRITY : undefined), opts.assets?.crossOrigin);
     const nonce = nonceAttr(opts.scriptNonce);
     const configuration = jsonForScript({
         persistAuthorization: true,
@@ -125,8 +143,10 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  */
 export function redocHtml(opts) {
     const title = escapeHtml(opts.title ?? "API Docs");
-    const scriptUrl = escapeHtml(opts.assets?.redocScriptUrl ?? `${JSDELIVR_ORIGIN}/npm/redoc/bundles/redoc.standalone.js`);
-    const scriptSri = integrityAttr(opts.assets?.redocScriptIntegrity, opts.assets?.crossOrigin);
+    const usesDefaultScript = opts.assets?.redocScriptUrl === undefined;
+    const scriptUrl = escapeHtml(opts.assets?.redocScriptUrl ?? DEFAULT_REDOC_SCRIPT_URL);
+    const scriptSri = integrityAttr(opts.assets?.redocScriptIntegrity ??
+        (usesDefaultScript ? DEFAULT_REDOC_SCRIPT_INTEGRITY : undefined), opts.assets?.crossOrigin);
     const nonce = nonceAttr(opts.scriptNonce);
     const specArg = jsonForScript(opts.specUrl);
     const optionsArg = jsonForScript(opts.configuration ?? {});
@@ -163,12 +183,14 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  */
 export function asyncapiHtml(opts) {
     const title = escapeHtml(opts.title ?? "AsyncAPI");
-    const scriptUrl = escapeHtml(opts.assets?.asyncapiScriptUrl ??
-        `${JSDELIVR_ORIGIN}/npm/@asyncapi/react-component/browser/standalone/index.js`);
-    const styleUrl = escapeHtml(opts.assets?.asyncapiStyleUrl ??
-        `${JSDELIVR_ORIGIN}/npm/@asyncapi/react-component/styles/default.min.css`);
-    const scriptSri = integrityAttr(opts.assets?.asyncapiScriptIntegrity, opts.assets?.crossOrigin);
-    const styleSri = integrityAttr(opts.assets?.asyncapiStyleIntegrity, opts.assets?.crossOrigin);
+    const usesDefaultScript = opts.assets?.asyncapiScriptUrl === undefined;
+    const usesDefaultStyle = opts.assets?.asyncapiStyleUrl === undefined;
+    const scriptUrl = escapeHtml(opts.assets?.asyncapiScriptUrl ?? DEFAULT_ASYNCAPI_SCRIPT_URL);
+    const styleUrl = escapeHtml(opts.assets?.asyncapiStyleUrl ?? DEFAULT_ASYNCAPI_STYLE_URL);
+    const scriptSri = integrityAttr(opts.assets?.asyncapiScriptIntegrity ??
+        (usesDefaultScript ? DEFAULT_ASYNCAPI_SCRIPT_INTEGRITY : undefined), opts.assets?.crossOrigin);
+    const styleSri = integrityAttr(opts.assets?.asyncapiStyleIntegrity ??
+        (usesDefaultStyle ? DEFAULT_ASYNCAPI_STYLE_INTEGRITY : undefined), opts.assets?.crossOrigin);
     const nonce = nonceAttr(opts.scriptNonce);
     const specArg = jsonForScript(opts.specUrl);
     const configArg = jsonForScript(opts.configuration ?? { show: { sidebar: true, errors: true } });

package/dist/errors.d.ts

@@ -364,9 +364,18 @@ export declare class TooManyRequestsError extends HttpError {
 }
 /**
  * `408 Request Timeout` — thrown when a handler exceeds
- * {@link AppOptions.requestTimeoutMs}. The framework aborts the in-flight
- * handler when this fires (handlers should respect the `AbortSignal` on
- * `ctx.request.signal` to clean up).
+ * {@link AppOptions.requestTimeoutMs}.
+ *
+ * When the timeout fires the framework aborts `ctx.request.signal` (with a
+ * `TimeoutError` reason) so a handler that forwarded that signal to downstream
+ * I/O — `fetch`, a DB driver — sees those calls reject and can unwind. It does
+ * **not** forcibly terminate the handler: single-threaded JS cannot preempt
+ * running code, so CPU-bound or non-cooperative work continues in the
+ * background until it observes the aborted signal or finishes. Forward
+ * `ctx.request.signal` into every cancellable downstream call to get the
+ * benefit. (Signal firing is wired on the Node adapter and any runtime whose
+ * request shim honors the abort hook; direct `app.fetch()` callers still get
+ * the `408` but no signal abort.)
  *
  * @param ms - The configured timeout that was exceeded.
  * @since 0.1.0

package/dist/errors.js

@@ -483,9 +483,18 @@ export class TooManyRequestsError extends HttpError {
 }
 /**
  * `408 Request Timeout` — thrown when a handler exceeds
- * {@link AppOptions.requestTimeoutMs}. The framework aborts the in-flight
- * handler when this fires (handlers should respect the `AbortSignal` on
- * `ctx.request.signal` to clean up).
+ * {@link AppOptions.requestTimeoutMs}.
+ *
+ * When the timeout fires the framework aborts `ctx.request.signal` (with a
+ * `TimeoutError` reason) so a handler that forwarded that signal to downstream
+ * I/O — `fetch`, a DB driver — sees those calls reject and can unwind. It does
+ * **not** forcibly terminate the handler: single-threaded JS cannot preempt
+ * running code, so CPU-bound or non-cooperative work continues in the
+ * background until it observes the aborted signal or finishes. Forward
+ * `ctx.request.signal` into every cancellable downstream call to get the
+ * benefit. (Signal firing is wired on the Node adapter and any runtime whose
+ * request shim honors the abort hook; direct `app.fetch()` callers still get
+ * the `408` but no signal abort.)
  *
  * @param ms - The configured timeout that was exceeded.
  * @since 0.1.0

package/dist/fetch-guard.d.ts

@@ -54,13 +54,14 @@
  * a `127.0.0.1` / `169.254.169.254` at connect time, slipping past the
  * library-level check. To close the window:
  *
- *  0. **Built-in, `http:` only** (recommended for cloud-metadata defense):
- *     set {@link FetchGuardOptions.pinDns} `: true`. On Node, `http:`
- *     requests are then dispatched through `node:http` with the socket
- *     pinned to the validated IP (and the original `Host` header
- *     preserved), so there is no connect-time re-resolution to rebind.
- *     `https:` is not pinned by this knob — see its docs — so the items
- *     below still matter for TLS upstreams.
+ *  0. **Built-in, `http:` only** (default on Node):
+ *     {@link FetchGuardOptions.pinDns} defaults to `true` on Node-like
+ *     runtimes (and `false` elsewhere). On Node, `http:` requests are
+ *     then dispatched through `node:http` with the socket pinned to the
+ *     validated IP (and the original `Host` header preserved), so there
+ *     is no connect-time re-resolution to rebind. Set `pinDns: false` to
+ *     opt out. `https:` is not pinned by this knob — see its docs — so
+ *     the items below still matter for TLS upstreams.
  *  1. **Operator-side** (recommended): block egress to RFC1918 /
  *     loopback / link-local at the VPC / firewall layer. This neutralises
  *     the rebinding even if the application is naïve.
@@ -93,7 +94,7 @@
  *
  * @since 0.34.0
  */
-export type SsrfBlockReason = "protocol-not-allowed" | "host-not-allowed" | "dns-resolution-failed" | "address-not-allowed" | "too-many-redirects" | "invalid-url";
+export type SsrfBlockReason = "protocol-not-allowed" | "host-not-allowed" | "dns-resolution-failed" | "address-not-allowed" | "too-many-redirects" | "credentials-in-url" | "invalid-url";
 /**
  * Thrown by {@link fetchGuard} when an outbound request is refused. Never
  * thrown for ordinary network failures — those bubble through unchanged
@@ -188,14 +189,20 @@ export interface FetchGuardOptions {
      * by connecting the socket to the exact IP that was validated, instead of
      * letting the underlying client re-resolve the hostname at connect time.
      *
-     * When `true` (default `false`), a request to a hostname that resolves to a
-     * validated address is dispatched through Node's built-in `node:http` with
-     * the connection pinned to that address and the original `Host` header
-     * preserved — so virtual-host routing still works while an attacker's
-     * TTL=0 rebinding to `127.0.0.1` / `169.254.169.254` can no longer take
-     * effect between validation and connect.
+     * When `true`, a request to a hostname that resolves to a validated address
+     * is dispatched through Node's built-in `node:http` with the connection
+     * pinned to that address and the original `Host` header preserved — so
+     * virtual-host routing still works while an attacker's TTL=0 rebinding to
+     * `127.0.0.1` / `169.254.169.254` can no longer take effect between
+     * validation and connect.
      *
-     * **Scope and caveats** (read before enabling):
+     * **Default:** `true` on Node-like runtimes (`process.versions.node` is a
+     * non-empty string), `false` elsewhere (Workers / edge sandboxes without
+     * `node:http`). Pass `pinDns: false` to opt out on Node, or `pinDns: true`
+     * on a non-Node runtime only if you can tolerate the loud error when the
+     * pin path cannot load `node:http`.
+     *
+     * **Scope and caveats** (read before changing the default):
      *
      * - **`http:` only.** `https:` is intentionally NOT pinned here: pinning a
      *   TLS connection to an IP while keeping hostname-based SNI / certificate
@@ -204,16 +211,17 @@ export interface FetchGuardOptions {
      *   the documented TOCTOU caveat. The prime rebinding target — cloud
      *   metadata at `http://169.254.169.254` — is `http:`, so this still closes
      *   the highest-value vector.
-     * - **Node only.** It uses `node:http`; on runtimes without it (Workers,
-     *   some edge sandboxes) an `http:` pinned dispatch throws a clear error so
-     *   the misconfiguration is loud rather than a silent no-op.
+     * - **Node only for the pin path.** It uses `node:http`; when `pinDns` is
+     *   explicitly `true` on a runtime without it, an `http:` pinned dispatch
+     *   throws a clear error so the misconfiguration is loud rather than a
+     *   silent no-op.
      * - **Bypasses `options.fetch`** for the pinned `http:` path (it must own the
      *   socket), and negotiates no response compression (`Accept-Encoding:
      *   identity`) so body semantics match a plain `fetch`.
      *
      * Requests to a literal-IP host or an `allowHosts` entry are never pinned
      * (the former already connects to an exact IP; the latter is an explicit
-     * operator trust). Default `false`.
+     * operator trust).
      *
      * @since 0.44.0
      */

package/dist/fetch-guard.js

@@ -54,13 +54,14 @@
  * a `127.0.0.1` / `169.254.169.254` at connect time, slipping past the
  * library-level check. To close the window:
  *
- *  0. **Built-in, `http:` only** (recommended for cloud-metadata defense):
- *     set {@link FetchGuardOptions.pinDns} `: true`. On Node, `http:`
- *     requests are then dispatched through `node:http` with the socket
- *     pinned to the validated IP (and the original `Host` header
- *     preserved), so there is no connect-time re-resolution to rebind.
- *     `https:` is not pinned by this knob — see its docs — so the items
- *     below still matter for TLS upstreams.
+ *  0. **Built-in, `http:` only** (default on Node):
+ *     {@link FetchGuardOptions.pinDns} defaults to `true` on Node-like
+ *     runtimes (and `false` elsewhere). On Node, `http:` requests are
+ *     then dispatched through `node:http` with the socket pinned to the
+ *     validated IP (and the original `Host` header preserved), so there
+ *     is no connect-time re-resolution to rebind. Set `pinDns: false` to
+ *     opt out. `https:` is not pinned by this knob — see its docs — so
+ *     the items below still matter for TLS upstreams.
  *  1. **Operator-side** (recommended): block egress to RFC1918 /
  *     loopback / link-local at the VPC / firewall layer. This neutralises
  *     the rebinding even if the application is naïve.
@@ -112,6 +113,20 @@ export class SsrfBlockedError extends Error {
             this.address = address;
     }
 }
+/**
+ * Whether this runtime looks like Node (or a Node-compatible host such as Bun)
+ * where `node:http` DNS pinning is available.
+ *
+ * Used as the default for {@link FetchGuardOptions.pinDns} so Node apps get
+ * rebinding defense without an opt-in, while Workers / pure edge runtimes keep
+ * the non-pinning path.
+ */
+function defaultPinDnsEnabled() {
+    return (typeof process !== "undefined" &&
+        process.versions != null &&
+        typeof process.versions.node === "string" &&
+        process.versions.node.length > 0);
+}
 // Always-on deny matchers. No option flips these.
 const ALWAYS_DENY = [
     "0.0.0.0/8", // "this network"
@@ -185,7 +200,11 @@ export function fetchGuard(options = {}) {
         throw new Error("fetchGuard(): no global fetch available; pass options.fetch.");
     }
     const resolveFn = options.resolve ?? createDefaultResolver();
-    const pinDns = options.pinDns === true;
+    // Secure default on Node when using the built-in fetch: pin http: sockets
+    // to the validated IP. A custom `options.fetch` owns its own socket / DNS
+    // policy, so pinDns stays off unless the caller opts in. Non-Node runtimes
+    // default off (no node:http). Opt out on Node with `pinDns: false`.
+    const pinDns = options.pinDns ?? (options.fetch === undefined && defaultPinDnsEnabled());
     for (const c of ALWAYS_DENY)
         hardDenyMatchers.push(compileCidrMatcher(c));
     for (const c of options.denyAddresses ?? [])
@@ -269,6 +288,29 @@ export function fetchGuard(options = {}) {
         return addrs[0];
     }
     const guarded = async (input, init) => {
+        // A URL carrying userinfo (`http://user:pass@internal/`) is a classic SSRF
+        // obfuscation — the real host hides after the `@`. undici's `Request`
+        // constructor refuses such URLs with a raw `TypeError`, which would fire
+        // *before* our host validation and escape the `SsrfBlockedError` contract,
+        // so callers misclassify a blocked SSRF attempt as an ordinary upstream
+        // failure. Detect and refuse it ourselves with a typed error first. The
+        // credentials are stripped from the URL recorded on the error so a
+        // caller-supplied secret never leaks into logs. Malformed URLs fall
+        // through to the handling below, which raises `SsrfBlockedError("invalid-url")`.
+        if (typeof input === "string" || input instanceof URL) {
+            let pre;
+            try {
+                pre = new URL(input);
+            }
+            catch {
+                pre = undefined;
+            }
+            if (pre && (pre.username !== "" || pre.password !== "")) {
+                pre.username = "";
+                pre.password = "";
+                throw new SsrfBlockedError(pre.toString(), "credentials-in-url");
+            }
+        }
         let request = new Request(input, init);
         const userRedirect = (init?.redirect ?? request.redirect);
         // Always dispatch underlying calls with redirect: "manual" so we can

package/dist/http-signatures.d.ts

@@ -229,7 +229,10 @@ export interface VerifyMessageOptions {
     label?: string;
     /**
      * Component identifiers that MUST be covered. Defaults to
-     * `["@method", "@path"]`. Pass `[]` to disable the check (not recommended).
+     * `["@method", "@target-uri"]` so the verifier binds scheme, authority,
+     * path, **and query** (matching {@link signMessage}'s default covered set).
+     * Prefer this over bare `@path`, which leaves query parameters unsigned.
+     * Pass `[]` to disable the check (not recommended).
      */
     requiredComponents?: string[];
     /** Require the `created` parameter. Defaults to `true`. */

package/dist/http-signatures.js

@@ -435,6 +435,15 @@ function resolveComponentValue(c, msg) {
                 if (values.length === 0) {
                     throw new ComponentError(`@query-param;name="${c.paramName}" is not present in the query`);
                 }
+                // Reject multi-value params: signing only the first value while an app
+                // or intermediary uses the last value (or the full array) is a classic
+                // HTTP parameter-pollution differential. Prefer `@query` / `@target-uri`
+                // when multiple values are legitimate.
+                if (values.length > 1) {
+                    throw new ComponentError(`@query-param;name="${c.paramName}" appears ${values.length} times; ` +
+                        "duplicate query parameters are not supported (parameter pollution risk). " +
+                        "Cover `@query` or `@target-uri` instead, or send a single value.");
+                }
                 return values[0];
             }
             case "@status":
@@ -631,7 +640,10 @@ export async function verifyMessage(opts) {
         ...(params.tag !== undefined ? { tag: params.tag } : {}),
     };
     // Required components.
-    const requiredComponents = opts.requiredComponents ?? ["@method", "@path"];
+    // Align with signMessage()'s default covered components so a default sign
+    // is accepted by a default verify, and so query/authority cannot be swapped
+    // out under a signature that only bound `@path`.
+    const requiredComponents = opts.requiredComponents ?? ["@method", "@target-uri"];
     const coveredIds = input.components.map(serializeComponentId);
     for (const req of requiredComponents) {
         const wanted = serializeComponentId(parseComponentSpec(req));

package/dist/idempotency.js

@@ -32,6 +32,7 @@
  * @since 0.37.0
  */
 import { BadRequestError, ConflictError, HttpError } from "./errors.js";
+import { markSchemaValidatedResponse } from "./internal-response.js";
 const enc = new TextEncoder();
 /** Internal `ctx.state` key carrying the reservation between hooks. */
 const PENDING_STATE_KEY = "__idempotencyPending";
@@ -200,7 +201,7 @@ function buildReplayResponse(stored, replayHeaderName) {
         headers.set(name, value);
     headers.set(replayHeaderName, "true");
     const body = stored.body ? base64ToBytes(stored.body) : null;
-    return new Response(body, { status: stored.status, headers });
+    return markSchemaValidatedResponse(new Response(body, { status: stored.status, headers }));
 }
 // ---------- Middleware ----------
 /**

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { App } from "./app.js";
 export { createApp } from "./app.js";
+export { defineRoute } from "./types.js";
 export { findRoutesMissingResponseBodySchema } from "./app.js";
-export { _resetPackageJsonCacheForTests } from "./app.js";
 export { _resetCrashHandlersForTests } from "./app.js";
 export { _resetInsecureDefaultsLogForTests } from "./app.js";
 export { _resetIndeterminateEnvWarningForTests } from "./app.js";
@@ -12,7 +12,7 @@ export { subdomains, PSL_SNAPSHOT_DATE, PSL_PUBLIC_SUFFIXES, MAX_SNAPSHOT_AGE_DA
 export type { SubdomainsOptions, SubdomainsResult } from "./subdomains.js";
 export { defineDependency, DEPENDENCY_MARKER } from "./dependency.js";
 export type { DependencyHooks, DependencyOptions } from "./dependency.js";
-export type { RouteDefinition, HttpMethod, PathString, RequestSchemas, ResponsesMap, ResponseSpec, AuthSpec, Hooks, BaseContext, AppState, AuthScheme, AuthContext, HandlerReturn, InferRequest, ParamsOf, PathParams, CallbackDefinition, CallbackMap, CallbackOperation, RouteExample, RouteMeta, } from "./types.js";
+export type { RouteDefinition, HttpMethod, PathString, RequestSchemas, ResponsesMap, ResponseSpec, AuthSpec, Hooks, BaseContext, PreBodyContext, AppState, AuthScheme, AuthContext, HandlerReturn, InferRequest, ParamsOf, PathParams, CallbackDefinition, CallbackMap, CallbackOperation, RouteExample, RouteMeta, } from "./types.js";
 export { HttpError, BadRequestError, ValidationError, NotFoundError, ConflictError, UnauthorizedError, ForbiddenError, MethodNotAllowedError, PayloadTooLargeError, RequestHeaderFieldsTooLargeError, UnsupportedMediaTypeError, TooManyRequestsError, RequestTimeoutError, InternalError, MessageLeakError, httpError, SAFE_CUSTOM_ERROR_RESPONSE_HEADERS, checkCustomErrorResponseHeaders, } from "./errors.js";
 export type { ProblemDetails, ProblemRenderOptions, HttpErrorOptions } from "./errors.js";
 export type { StandardSchemaV1 } from "./schema.js";
@@ -21,7 +21,7 @@ export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
 export type { ChangeSeverity, OpenAPIChange, OpenAPIDiffResult } from "./openapi-diff.js";
 export { MCP_DEFAULT_MAX_BODY_BYTES, MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, McpToolError, createMcpHandler, mcpRoutes, validateMcpInput, } from "./mcp.js";
 export type { McpContent, McpEmbeddedResourceContent, McpHandler, McpHandlerOptions, McpIcon, McpImageContent, McpJsonObject, McpJsonRpcId, McpJsonSchema, McpJsonValue, McpPrompt, McpPromptArgument, McpPromptDefinition, McpPromptMessage, McpPromptResult, McpRequestContext, McpResource, McpResourceContents, McpResourceDefinition, McpResourceTemplate, McpResourceTemplateDefinition, McpRoutesOptions, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolHandler, McpToolResult, } from "./mcp.js";
-export { readBodyLimited, safeJsonParse, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
+export { readBodyLimited, safeJsonParse, safeJsonParseLimited, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
 export type { WebhookHmacAlgorithm } from "./security.js";
 export { requestId, secureHeaders, SECURE_HEADERS_MARKER, cors, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, rateLimit, loginThrottle, timing, bearerAuth, basicAuth, markAuthHook, AUTH_HOOK_MARKER, csrf, CSRF_HOOK_MARKER, fetchMetadata, requireScopes, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, _resetSharedRateLimitStoresForTests, } from "./middleware.js";
 export { etag } from "./etag.js";
@@ -72,9 +72,9 @@ export { loadShedding, LOAD_SHEDDING_MARKER } from "./load-shedding.js";
 export type { LoadSheddingOptions, LoadSheddingSnapshot } from "./load-shedding.js";
 export { defineConfig, ConfigValidationError } from "./config.js";
 export type { ConfigSource, DefineConfigOptions } from "./config.js";
-export type { RequestIdOptions, SecureHeadersOptions, CspDirectivesOptions, CorsOptions, CorsOriginAllow, RateLimitOptions, RateLimitStore, LoginThrottleOptions, CsrfOptions, CsrfCookieOptions, FetchMetadataOptions, BasicAuthOptions, } from "./middleware.js";
+export type { RequestIdOptions, SecureHeadersOptions, CspDirectivesOptions, CorsOptions, CorsOriginAllow, RateLimitOptions, RateLimitContext, RateLimitStore, LoginThrottleOptions, CsrfOptions, CsrfCookieOptions, FetchMetadataOptions, BasicAuthOptions, } from "./middleware.js";
 export type { BearerAuthOptions, BearerAuthVerifyHook } from "./middleware.js";
-export { createLogger, noopLogger, DEFAULT_REDACT_KEYS } from "./logger.js";
+export { createLogger, noopLogger, DEFAULT_REDACT_KEYS, SENSITIVE_URL_QUERY_KEYS, sanitizeUrlForLog, } from "./logger.js";
 export type { Logger, LogLevel, ConsoleLoggerOptions, LoggerRedactionOptions } from "./logger.js";
 export type { ScalarJsonPrimitive, ScalarJsonValue, ScalarReferenceConfiguration, ScalarTheme, RedocConfiguration, RedocHtmlOptions, SwaggerUiConfiguration, SwaggerUiHtmlOptions, AsyncApiHtmlOptions, DocsAssetOptions, DocsAuthLauncherOptions, } from "./docs.js";
 export { formatStartupBanner, printStartupBanner } from "./banner.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { App } from "./app.js";
 export { createApp } from "./app.js";
+export { defineRoute } from "./types.js";
 export { findRoutesMissingResponseBodySchema } from "./app.js";
-export { _resetPackageJsonCacheForTests } from "./app.js";
 export { _resetCrashHandlersForTests } from "./app.js";
 export { _resetInsecureDefaultsLogForTests } from "./app.js";
 export { _resetIndeterminateEnvWarningForTests } from "./app.js";
@@ -12,7 +12,7 @@ export { HttpError, BadRequestError, ValidationError, NotFoundError, ConflictErr
 export { validate, isStandardSchema } from "./schema.js";
 export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
 export { MCP_DEFAULT_MAX_BODY_BYTES, MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, McpToolError, createMcpHandler, mcpRoutes, validateMcpInput, } from "./mcp.js";
-export { readBodyLimited, safeJsonParse, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
+export { readBodyLimited, safeJsonParse, safeJsonParseLimited, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
 export { requestId, secureHeaders, SECURE_HEADERS_MARKER, cors, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, rateLimit, loginThrottle, timing, bearerAuth, basicAuth, markAuthHook, AUTH_HOOK_MARKER, csrf, CSRF_HOOK_MARKER, fetchMetadata, requireScopes, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, _resetSharedRateLimitStoresForTests, } from "./middleware.js";
 export { etag } from "./etag.js";
 export { compression, COMPRESSION_HOOK_MARKER, _resetCompressionRuntimeProbeForTests, } from "./compression.js";
@@ -38,7 +38,7 @@ export { waf } from "./waf.js";
 export { safeRedirect, OpenRedirectBlockedError } from "./safe-redirect.js";
 export { loadShedding, LOAD_SHEDDING_MARKER } from "./load-shedding.js";
 export { defineConfig, ConfigValidationError } from "./config.js";
-export { createLogger, noopLogger, DEFAULT_REDACT_KEYS } from "./logger.js";
+export { createLogger, noopLogger, DEFAULT_REDACT_KEYS, SENSITIVE_URL_QUERY_KEYS, sanitizeUrlForLog, } from "./logger.js";
 export { formatStartupBanner, printStartupBanner } from "./banner.js";
 export { sseStream, sseResponse, ndjsonStream, ndjsonResponse } from "./streaming.js";
 export { httpBearerScheme, httpBasicScheme, apiKeyScheme, oauth2Scheme, openIdConnectScheme, REQUIRE_PAYLOAD_AUTH_EXTENSION, securitySchemeRequiresPayloadAuth, toOpenAPISecurityScheme, } from "./security-schemes.js";

package/dist/internal-response.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mark a framework-generated replay as having crossed response validation.
+ * This is an internal capability and is not exported from the package barrel.
+ *
+ * @param response - Reconstructed response containing previously validated bytes.
+ * @returns The same response for allocation-free call-site composition.
+ */
+export declare function markSchemaValidatedResponse(response: Response): Response;
+/**
+ * Test whether a response is a trusted first-party replay of validated bytes.
+ *
+ * @param response - Hook response being considered for fail-closed handling.
+ * @returns `true` only for responses marked by first-party replay middleware.
+ */
+export declare function isSchemaValidatedResponse(response: Response): boolean;

package/dist/internal-response.js

@@ -0,0 +1,27 @@
+/**
+ * Responses reconstructed by first-party cache/idempotency middleware from a
+ * previously finalized response. The original response already crossed the
+ * route's schema-validation boundary, so replaying its stored bytes does not
+ * create the opaque-success bypass guarded by `App`.
+ */
+const schemaValidatedResponses = new WeakSet();
+/**
+ * Mark a framework-generated replay as having crossed response validation.
+ * This is an internal capability and is not exported from the package barrel.
+ *
+ * @param response - Reconstructed response containing previously validated bytes.
+ * @returns The same response for allocation-free call-site composition.
+ */
+export function markSchemaValidatedResponse(response) {
+    schemaValidatedResponses.add(response);
+    return response;
+}
+/**
+ * Test whether a response is a trusted first-party replay of validated bytes.
+ *
+ * @param response - Hook response being considered for fail-closed handling.
+ * @returns `true` only for responses marked by first-party replay middleware.
+ */
+export function isSchemaValidatedResponse(response) {
+    return schemaValidatedResponses.has(response);
+}