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

package/dist/client.d.ts

@@ -10,13 +10,15 @@
  * can still be generated from the OpenAPI doc for non-TS clients).
  */
 import type { App } from "./app.js";
-import type { HandlerReturn, InferRequest, RequestSchemas, ResponsesMap, RouteDefinition } from "./types.js";
+import type { HandlerReturn, InferRequest, ParamsOf, RequestSchemas, ResponsesMap, RouteDefinition } from "./types.js";
 /** Union of every {@link RouteDefinition} registered on an `App`. */
 export type RoutesOf<A extends App> = A["routes"][number];
 /**
  * Typed client surface generated from an `App`. The result is a record keyed
  * by each route's `operationId` whose values are async methods inferred from
- * the route's request and response schemas.
+ * the route's request and response schemas. Required query and header fields
+ * remain required on the client input, while schemas that accept an empty
+ * object keep their corresponding client field optional.
  *
  * The per-method types are recovered from the `App`'s accumulated route tuple,
  * built by chained registrations or `app.registerRoutes([...])`. If the result
@@ -28,18 +30,38 @@ export type ClientFor<A extends App> = {
         operationId: string;
     }> as R["operationId"]]: ClientMethod<R>;
 };
-type ClientMethod<R> = R extends RouteDefinition<infer P, infer _M, infer Req, infer Res> ? (input: ClientInput<P, Req>) => Promise<ClientOutput<Res>> : never;
-type ClientInput<P extends string, Req extends RequestSchemas | undefined> = {
+type ClientMethod<R> = R extends RouteDefinition<infer P, infer _M, infer Req, infer Res> ? {} extends ClientInput<P, Req> ? (input?: ClientInput<P, Req>) => Promise<ClientOutput<Res>> : (input: ClientInput<P, Req>) => Promise<ClientOutput<Res>> : never;
+type ClientInput<P extends string, Req extends RequestSchemas | undefined> = ([
+    ParamsOf<P>
+] extends [never] ? {
+    params?: Record<string, never>;
+} : {
     params: InferRequest<Req, P>["params"];
-    query?: Partial<InferRequest<Req, P>["query"]>;
-    headers?: Record<string, string>;
-} & (Req extends {
+}) & ClientQueryInput<P, Req> & ClientHeadersInput<P, Req> & (Req extends {
     body: infer _B;
 } ? {
     body: InferRequest<Req, P>["body"];
 } : {
     body?: undefined;
 });
+type ClientQueryInput<P extends string, Req extends RequestSchemas | undefined> = Req extends {
+    query: infer _Query;
+} ? {} extends NonNullable<InferRequest<Req, P>["query"]> ? {
+    query?: NonNullable<InferRequest<Req, P>["query"]>;
+} : {
+    query: NonNullable<InferRequest<Req, P>["query"]>;
+} : {
+    query?: Record<string, string | string[] | number | boolean | undefined>;
+};
+type ClientHeadersInput<P extends string, Req extends RequestSchemas | undefined> = Req extends {
+    headers: infer _Headers;
+} ? {} extends NonNullable<InferRequest<Req, P>["headers"]> ? {
+    headers?: NonNullable<InferRequest<Req, P>["headers"]>;
+} : {
+    headers: NonNullable<InferRequest<Req, P>["headers"]>;
+} : {
+    headers?: Record<string, string>;
+};
 type ClientOutput<Res extends ResponsesMap> = HandlerReturn<Res>;
 /** Options for {@link createClient}. */
 export interface ClientOptions {
@@ -62,6 +84,9 @@ export interface InProcessClientOptions {
  * `operationId`. Parameters and response types are inferred from the same
  * route definitions registered on `app`, so the client and server cannot
  * drift apart at the type level.
+ * Required `params`, `query`, `headers`, and `body` inputs are preserved from
+ * the route contract; query or header schemas that accept an empty object keep
+ * those top-level fields optional.
  *
  * The returned object is a plain `Record<operationId, (input) => Promise<...>>`
  * — each call serializes `params`/`query`/`headers`/`body` and dispatches
@@ -69,6 +94,8 @@ export interface InProcessClientOptions {
  *
  * For non-TypeScript consumers, run `pnpm gen` to emit a fully-typed SDK
  * from the OpenAPI document instead.
+ * Routes without path parameters omit the `params` input, and routes with no
+ * required request inputs may be called without an argument.
  *
  * @remarks
  * The method signatures are inferred from the `App`'s accumulated route tuple.
@@ -106,6 +133,8 @@ export declare function createClient<A extends App>(app: A, opts: ClientOptions)
  *
  * Requests still traverse the complete validation, middleware, security, and
  * serialization pipeline through {@link "./app.js".App.fetch}.
+ * Routes without path parameters omit the `params` input, and routes with no
+ * required request inputs may be called without an argument.
  *
  * @param app - App whose registered route tuple drives the client surface.
  * @param opts - Optional synthetic origin and default request headers.

package/dist/client.js

@@ -14,6 +14,9 @@
  * `operationId`. Parameters and response types are inferred from the same
  * route definitions registered on `app`, so the client and server cannot
  * drift apart at the type level.
+ * Required `params`, `query`, `headers`, and `body` inputs are preserved from
+ * the route contract; query or header schemas that accept an empty object keep
+ * those top-level fields optional.
  *
  * The returned object is a plain `Record<operationId, (input) => Promise<...>>`
  * — each call serializes `params`/`query`/`headers`/`body` and dispatches
@@ -21,6 +24,8 @@
  *
  * For non-TypeScript consumers, run `pnpm gen` to emit a fully-typed SDK
  * from the OpenAPI document instead.
+ * Routes without path parameters omit the `params` input, and routes with no
+ * required request inputs may be called without an argument.
  *
  * @remarks
  * The method signatures are inferred from the `App`'s accumulated route tuple.
@@ -98,6 +103,8 @@ export function createClient(app, opts) {
  *
  * Requests still traverse the complete validation, middleware, security, and
  * serialization pipeline through {@link "./app.js".App.fetch}.
+ * Routes without path parameters omit the `params` input, and routes with no
+ * required request inputs may be called without an argument.
  *
  * @param app - App whose registered route tuple drives the client surface.
  * @param opts - Optional synthetic origin and default request headers.

package/dist/compression.d.ts

@@ -38,6 +38,15 @@ export interface CompressionOptions {
      * below `0` or above `2 ** 31 - 1` are refused at construction.
      */
     minimumSize?: number;
+    /**
+     * Maximum response body size (in bytes) the middleware will buffer for
+     * compression. Larger (or unknown-and-growing) bodies are left uncompressed
+     * so a large GET cannot force unbounded heap growth. Default: `1_048_576`
+     * (1 MiB). Must be a positive integer.
+     *
+     * @since 1.0.0
+     */
+    maxCompressibleBytes?: number;
     /**
      * Allowed encodings, in caller-preferred order. Defaults to
      * `["br", "gzip", "deflate"]` — the middleware will pick the

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/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/index.d.ts

@@ -74,7 +74,7 @@ export { defineConfig, ConfigValidationError } from "./config.js";
 export type { ConfigSource, DefineConfigOptions } from "./config.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

@@ -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/logger.d.ts

@@ -133,4 +133,49 @@ export declare function createLogger(opts?: ConsoleLoggerOptions): Logger;
  * @since 0.1.0
  */
 export declare const noopLogger: Logger;
+/**
+ * Query parameter names whose values are redacted when a request URL is
+ * bound into a log record. Case-insensitive. Covers OAuth redirect params,
+ * API keys in query strings, signed-URL tokens, session identifiers, and the
+ * exact-named parameters of AWS SigV4 / GCS V4 presigned URLs (the `x-amz-*`
+ * and `x-goog-*` families are additionally matched by prefix — see
+ * {@link SENSITIVE_URL_QUERY_KEY_PREFIXES}).
+ *
+ * @since 1.0.0
+ */
+export declare const SENSITIVE_URL_QUERY_KEYS: readonly string[];
+/**
+ * Case-insensitive query-key prefixes whose values are always redacted in a
+ * logged URL. Covers the full AWS SigV4 (`X-Amz-*`) and GCS V4 (`X-Goog-*`)
+ * presigned-URL parameter families so a signature never leaks even if a
+ * provider adds a new signed parameter name. Redacting the non-secret members
+ * of the bundle (`X-Amz-Date`, `X-Amz-Expires`, …) is harmless in a log line.
+ *
+ * @since 1.0.0
+ */
+export declare const SENSITIVE_URL_QUERY_KEY_PREFIXES: readonly string[];
+/**
+ * Produce a log-safe form of a request URL.
+ *
+ * Keeps scheme, host, and path for operability. Redacts values of
+ * {@link SENSITIVE_URL_QUERY_KEYS} / {@link SENSITIVE_URL_QUERY_KEY_PREFIXES}
+ * (and JWT-like / credential-like query values) so OAuth `?code=`,
+ * `?access_token=`, and presigned-URL signatures (`?X-Amz-Signature=`,
+ * `?X-Goog-Signature=`) never land in durable error logs under the field name
+ * `url` (which the structured redactor does not rename-match).
+ *
+ * Malformed URLs fall back to the path-only prefix before `?` / `#`.
+ *
+ * This runs once per request on the logging path, so it fast-paths the common
+ * case: a URL with no query, no fragment, and no userinfo (`@`) delimiter is
+ * already log-safe and is returned verbatim without the WHATWG URL parse (about
+ * an order of magnitude cheaper). The `@` guard preserves userinfo stripping
+ * for the rare inputs that carry credentials in the authority — `request.url`
+ * itself never does, but this is a public utility.
+ *
+ * @param url - Absolute or relative request URL (typically `request.url`).
+ * @returns A string safe to attach as a logger binding.
+ * @since 1.0.0
+ */
+export declare function sanitizeUrlForLog(url: string): string;
 export {};