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

package/dist/logger.js

@@ -34,6 +34,17 @@ export const DEFAULT_REDACT_KEYS = Object.freeze([
     "refresh_token",
     "id_token",
     "client_secret",
+    // A structured field literally named `private_key` is always a secret and
+    // has a negligible false-positive rate as a log-field name (mirrors the
+    // existing `client_secret`). The broader OAuth/session query-string names
+    // (`code`, `state`, `id`, `key`, `sid`, `session`, `signature`, `sig`,
+    // `auth`, …) are DELIBERATELY NOT here: those are extremely common,
+    // non-secret structured field names (record ids, sort keys, UI state) and
+    // redacting them at every depth would corrupt normal operational logs.
+    // Secrets that ride in a *URL query string* are handled instead by
+    // {@link sanitizeUrlForLog} / {@link SENSITIVE_URL_QUERY_KEYS}, which only
+    // applies to the `url` field where the query context makes them sensitive.
+    "private_key",
     // AI / LLM provider credential headers and body fields. Added in response
     // to the LiteLLM 2026 "AI blast radius" incident class (Snyk 2026,
     // CVE-2026-42208 + CVE-2026-33634) — an AI gateway that brokers prompts
@@ -265,3 +276,129 @@ export const noopLogger = {
         return noopLogger;
     },
 };
+/**
+ * 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 const SENSITIVE_URL_QUERY_KEYS = Object.freeze([
+    "authorization",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "token",
+    "api_key",
+    "apikey",
+    "api-key",
+    "key",
+    "password",
+    "passwd",
+    "secret",
+    "client_secret",
+    "code",
+    "state",
+    "session_state",
+    "session",
+    "sid",
+    "signature",
+    "sig",
+    "auth",
+    "private_key",
+    "x-api-key",
+    // AWS SigV4 presigned URL parameters. `X-Amz-Signature` is the secret; the
+    // credential (embeds the access-key id) and session token are equally
+    // sensitive. Also covered by the `x-amz-` prefix below.
+    "x-amz-signature",
+    "x-amz-credential",
+    "x-amz-security-token",
+    // Google Cloud Storage V4 signed URL parameters. Also covered by `x-goog-`.
+    "x-goog-signature",
+    "x-goog-credential",
+    "googleaccessid",
+]);
+/**
+ * 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 const SENSITIVE_URL_QUERY_KEY_PREFIXES = Object.freeze([
+    "x-amz-",
+    "x-goog-",
+]);
+const SENSITIVE_URL_QUERY_KEY_SET = new Set(SENSITIVE_URL_QUERY_KEYS.map((k) => k.toLowerCase()));
+/**
+ * Whether a URL query-parameter name is treated as secret-bearing when a
+ * request URL is bound into a log record. True when the lower-cased name is in
+ * {@link SENSITIVE_URL_QUERY_KEYS} or starts with a
+ * {@link SENSITIVE_URL_QUERY_KEY_PREFIXES} entry.
+ *
+ * @param lowerKey - Already-lower-cased query-parameter name.
+ * @returns `true` if the value should be redacted.
+ */
+function isSensitiveUrlQueryKey(lowerKey) {
+    if (SENSITIVE_URL_QUERY_KEY_SET.has(lowerKey))
+        return true;
+    for (const prefix of SENSITIVE_URL_QUERY_KEY_PREFIXES) {
+        if (lowerKey.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 function sanitizeUrlForLog(url) {
+    if (url.indexOf("?") === -1 &&
+        url.indexOf("#") === -1 &&
+        url.indexOf("@") === -1) {
+        return url;
+    }
+    try {
+        const parsed = new URL(url);
+        if (parsed.search === "" && parsed.hash === "") {
+            return `${parsed.origin}${parsed.pathname}`;
+        }
+        const safe = new URL(parsed.origin + parsed.pathname);
+        for (const [key, value] of parsed.searchParams) {
+            const lower = key.toLowerCase();
+            const sensitiveKey = isSensitiveUrlQueryKey(lower);
+            const sensitiveValue = JWT_LIKE_RE.test(value) || CREDENTIAL_LIKE_RE.test(value);
+            CREDENTIAL_LIKE_RE.lastIndex = 0;
+            safe.searchParams.append(key, sensitiveKey || sensitiveValue ? "[REDACTED]" : value);
+        }
+        return safe.toString();
+    }
+    catch {
+        const cut = url.search(/[?#]/);
+        return cut === -1 ? url : url.slice(0, cut);
+    }
+}

package/dist/mcp.js

@@ -355,10 +355,16 @@ function compileUriTemplate(template) {
 const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
 /**
  * Streamable HTTP DNS-rebinding defense: decide whether a browser `Origin`
- * may talk to this MCP endpoint. Same-origin and loopback origins are always
- * allowed; anything else must be explicitly allowlisted.
+ * may talk to this MCP endpoint.
+ *
+ * Loopback origins (`localhost` / `127.0.0.1` / `[::1]` / `*.localhost`) are
+ * allowed for local development. Every non-loopback origin must appear in
+ * the configured allowlist. We deliberately do **not** treat
+ * `Origin.host === request Host` as sufficient: under DNS rebinding both
+ * can be the attacker hostname resolving to the target IP, which would
+ * silently bypass an implicit same-origin check.
  */
-function isAllowedOrigin(origin, request, allowlist) {
+function isAllowedOrigin(origin, _request, allowlist) {
     const normalized = origin.toLowerCase();
     if (allowlist.has(normalized))
         return true;
@@ -374,12 +380,7 @@ function isAllowedOrigin(origin, request, allowlist) {
     const hostname = parsed.hostname;
     if (LOOPBACK_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost"))
         return true;
-    try {
-        return parsed.host === new URL(request.url).host;
-    }
-    catch {
-        return false;
-    }
+    return false;
 }
 /**
  * Create a dependency-free MCP Streamable HTTP endpoint handler.

package/dist/middleware.js

@@ -257,6 +257,8 @@ export function secureHeaders(opts = {}) {
         }
     }
     const headerEntries = Object.entries(headers);
+    // Lowercased name set for the common-path fast apply below.
+    const headerKeySet = headerEntries.length > 0 ? new Set(headerEntries.map(([k]) => k)) : null;
     const hooks = {};
     if (cspIsDynamic) {
         hooks.beforeHandle = (ctx) => {
@@ -276,12 +278,40 @@ export function secureHeaders(opts = {}) {
             return undefined;
         };
     }
-    if (headerEntries.length > 0) {
+    if (headerEntries.length > 0 && headerKeySet !== null) {
+        // Apply baseline security headers without overwriting values the handler
+        // (or an earlier hook) already set. Two paths, same accept/reject
+        // semantics:
+        //
+        //  1. Fast path (common): response carries none of our keys (typical
+        //     after serializeResult: content-type + content-length +
+        //     x-request-id only). One cheap forEach over the small response
+        //     header map, then unconditional set of each default — avoids N
+        //     `has()` probes that miss on every request.
+        //  2. Careful path: at least one of our keys is already present; fall
+        //     back to set-if-absent so user-supplied CSP / frame-options / etc.
+        //     still win.
         hooks.onResponse = (res) => {
-            for (const [k, v] of headerEntries) {
-                if (!res.headers.has(k))
+            let conflict = false;
+            // `for...of` over Headers.entries() is faster than the callback-based
+            // forEach and lets us break the instant we find a conflicting header.
+            // WHATWG Headers yields lowercased names, matching headerKeySet.
+            for (const [name] of res.headers) {
+                if (headerKeySet.has(name)) {
+                    conflict = true;
+                    break;
+                }
+            }
+            if (!conflict) {
+                for (const [k, v] of headerEntries)
                     res.headers.set(k, v);
             }
+            else {
+                for (const [k, v] of headerEntries) {
+                    if (!res.headers.has(k))
+                        res.headers.set(k, v);
+                }
+            }
         };
     }
     hooks[SECURE_HEADERS_MARKER] = true;

package/dist/mtls.js

@@ -415,7 +415,12 @@ function certFromHeaders(request, cfg) {
     const sanRaw = readHeader(request, cfg.san);
     const verifyRaw = cfg.verify ? readHeader(request, cfg.verify) : undefined;
     const successValue = (cfg.verifySuccessValue ?? "SUCCESS").toLowerCase();
-    const verified = cfg.verify === undefined ? true : (verifyRaw ?? "").toLowerCase() === successValue;
+    // Without a configured verification header there is no cryptographic proof
+    // the terminator validated the chain. Default to unverified so
+    // requireVerified (default true) rejects spoofed identity-only headers.
+    // Operators that intentionally trust a proxy which only forwards identity
+    // must set requireVerified: false (and keep a strict behindProxy posture).
+    const verified = cfg.verify === undefined ? false : (verifyRaw ?? "").toLowerCase() === successValue;
     const sans = [];
     if (sanRaw) {
         for (const piece of sanRaw.split(",")) {

package/dist/router.d.ts

@@ -2,9 +2,9 @@
  * Trie / radix-style router with a static-route fast path.
  *
  * Performance:
- *   - Static (parameter-free) paths resolve via a single Map.get — O(1).
+ *   - Exact static (parameter-free) paths resolve via a Map lookup — O(1).
  *   - Dynamic paths walk a trie, O(path-segments) regardless of route count.
- *   - Path string is split by `indexOf` rather than a regex/replace.
+ *   - Path normalization and splitting avoid regular expressions.
  *
  * Safety:
  *   - Path traversal (`..`) and empty segments are rejected at lookup time.

package/dist/router.js

@@ -2,9 +2,9 @@
  * Trie / radix-style router with a static-route fast path.
  *
  * Performance:
- *   - Static (parameter-free) paths resolve via a single Map.get — O(1).
+ *   - Exact static (parameter-free) paths resolve via a Map lookup — O(1).
  *   - Dynamic paths walk a trie, O(path-segments) regardless of route count.
- *   - Path string is split by `indexOf` rather than a regex/replace.
+ *   - Path normalization and splitting avoid regular expressions.
  *
  * Safety:
  *   - Path traversal (`..`) and empty segments are rejected at lookup time.
@@ -102,9 +102,12 @@ export class Router {
         if (path.includes("/../") || path.endsWith("/..") || path.includes("//")) {
             return undefined;
         }
-        // Static fast path.
-        const normalized = path.replace(/\/+$/, "") || "/";
-        const staticEntry = this.staticTable.get(normalized);
+        // Static fast path. Avoid allocating a normalized string for the common
+        // exact-path case; only trim when a trailing slash is actually present.
+        let staticEntry = this.staticTable.get(path);
+        if (!staticEntry && path.endsWith("/")) {
+            staticEntry = this.staticTable.get(trimTrailingSlashes(path));
+        }
         if (staticEntry && staticEntry[method]) {
             return { handler: staticEntry[method], params: {} };
         }
@@ -120,8 +123,10 @@ export class Router {
     }
     /** Returns the set of methods registered at this exact path (for 405 responses). */
     allowedMethods(path) {
-        const normalized = path.replace(/\/+$/, "") || "/";
-        const fromStatic = this.staticTable.get(normalized);
+        let fromStatic = this.staticTable.get(path);
+        if (!fromStatic && path.endsWith("/")) {
+            fromStatic = this.staticTable.get(trimTrailingSlashes(path));
+        }
         if (fromStatic)
             return Object.keys(fromStatic);
         const segments = splitPath(path);
@@ -165,6 +170,8 @@ export class Router {
  * than letting a `URIError` bubble up as a generic 500.
  */
 function safeDecodeURIComponent(segment) {
+    if (!segment.includes("%"))
+        return segment;
     try {
         return decodeURIComponent(segment);
     }
@@ -187,9 +194,17 @@ function decodeSegments(segs, index) {
     }
     return parts.join("/");
 }
+function trimTrailingSlashes(path) {
+    if (path.length === 0)
+        return "/";
+    let end = path.length;
+    while (end > 1 && path.charCodeAt(end - 1) === 47)
+        end--;
+    return end === path.length ? path : path.slice(0, end);
+}
 function splitPath(path) {
-    const clean = path.replace(/\/+$/, "") || "/";
+    const clean = trimTrailingSlashes(path);
     if (clean === "/")
         return [];
-    return clean.replace(/^\//, "").split("/");
+    return (clean.charCodeAt(0) === 47 ? clean.slice(1) : clean).split("/");
 }

package/dist/safe-redirect.d.ts

@@ -19,6 +19,10 @@
  *   Percent-encoded protocol-relative path prefixes such as `/%2f%2f`
  *   are also refused so downstream decoders cannot turn a same-origin
  *   `Location` into an origin-escaping redirect.
+ * - Same-origin paths carrying any code point above `U+00FF` are refused:
+ *   they cannot be represented in the ISO-8859-1 `Location` header, and this
+ *   also blocks the Unicode slash homographs (`U+2044` `⁄`, `U+2215` `∕`,
+ *   `U+FF0F` `／`) that `NFKC` normalization can fold into `/`.
  * - Absolute URLs are only allowed when their `origin` exactly matches
  *   one of the entries in `allowedOrigins`.
  * - `javascript:`, `data:`, `vbscript:`, and `file:` schemes are always
@@ -47,7 +51,7 @@
  * @since 0.35.0
  */
 /** Reason an open-redirect candidate was refused. */
-export type SafeRedirectBlockReason = "empty-target" | "invalid-control-characters" | "protocol-relative" | "backslash-path" | "path-not-allowed" | "origin-not-allowed" | "scheme-not-allowed" | "parse-failed";
+export type SafeRedirectBlockReason = "empty-target" | "invalid-control-characters" | "non-latin1-target" | "protocol-relative" | "backslash-path" | "path-not-allowed" | "origin-not-allowed" | "scheme-not-allowed" | "parse-failed";
 /** Thrown when {@link safeRedirect} refuses a candidate URL and no `fallback` is configured. */
 export declare class OpenRedirectBlockedError extends Error {
     /** Machine-readable {@link SafeRedirectBlockReason} explaining the refusal. */

package/dist/safe-redirect.js

@@ -19,6 +19,10 @@
  *   Percent-encoded protocol-relative path prefixes such as `/%2f%2f`
  *   are also refused so downstream decoders cannot turn a same-origin
  *   `Location` into an origin-escaping redirect.
+ * - Same-origin paths carrying any code point above `U+00FF` are refused:
+ *   they cannot be represented in the ISO-8859-1 `Location` header, and this
+ *   also blocks the Unicode slash homographs (`U+2044` `⁄`, `U+2215` `∕`,
+ *   `U+FF0F` `／`) that `NFKC` normalization can fold into `/`.
  * - Absolute URLs are only allowed when their `origin` exactly matches
  *   one of the entries in `allowedOrigins`.
  * - `javascript:`, `data:`, `vbscript:`, and `file:` schemes are always
@@ -65,6 +69,12 @@ const ALLOWED_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 // response-splitting via the `Location` header.
 // eslint-disable-next-line no-control-regex
 const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f-\u009f]/;
+// Any code point above U+00FF (outside Latin-1). Such characters cannot be
+// written to a `Location` header — which is serialized as an ISO-8859-1
+// ByteString, so `Headers.set` throws a raw `TypeError` — and they cover the
+// Unicode slash homographs (U+2044, U+2215, U+FF0F) used to smuggle a
+// protocol-relative redirect past a same-origin path check.
+const NON_LATIN1_RE = /[^\x00-\xff]/;
 function buildResponse(location, status, headers) {
     const merged = new Headers(headers);
     merged.set("Location", location);
@@ -97,6 +107,14 @@ function classify(target, allowedPaths, allowedOrigins) {
         // user agents and proxies — refuse them outright.
         if (target.includes("\\"))
             return { ok: false, reason: "backslash-path" };
+        // The path is written verbatim into the `Location` header (an ISO-8859-1
+        // ByteString). A code point above U+00FF cannot live there — `Headers.set`
+        // would throw a raw `TypeError`, escaping this helper's typed error
+        // contract and surfacing to callers as an uncaught 500 — so refuse it here
+        // with a proper `OpenRedirectBlockedError`. This also blocks Unicode slash
+        // homographs that normalization can fold into an origin-escaping `//`.
+        if (NON_LATIN1_RE.test(target))
+            return { ok: false, reason: "non-latin1-target" };
         if (allowedPaths.length === 0) {
             return { ok: false, reason: "path-not-allowed" };
         }
@@ -191,10 +209,14 @@ export function safeRedirect(target, options = {}) {
     if (result.ok)
         return buildResponse(result.location, status, options.headers);
     if (options.fallback !== undefined) {
-        if (!options.fallback.startsWith("/") || options.fallback.startsWith("//")) {
-            throw new TypeError(`safeRedirect: fallback must be a same-origin path starting with "/"; got ${options.fallback}`);
+        // Fallback must pass the same path safety checks as a primary same-origin
+        // target (no protocol-relative, no backslash confusion, no controls).
+        // Do not widen Location emission beyond what classify() would accept.
+        const fallbackResult = classify(options.fallback, ["/*"], []);
+        if (!fallbackResult.ok || !options.fallback.startsWith("/") || options.fallback.startsWith("//")) {
+            throw new TypeError(`safeRedirect: fallback must be a safe same-origin path starting with "/"; got ${options.fallback}`);
         }
-        return buildResponse(options.fallback, status, options.headers);
+        return buildResponse(fallbackResult.location, status, options.headers);
     }
     throw new OpenRedirectBlockedError(result.reason, target);
 }

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:6aa5f3fd-e017-5e4a-b206-49dc6d141768",
+  "serialNumber": "urn:uuid:4d7ef2ca-7207-5a53-933a-75950561ff0c",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-12T20:39:15.454Z",
+    "timestamp": "2026-07-20T09:04:35.490Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-rc.4"
+        "version": "1.0.0-rc.5"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.4",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.5",
       "name": "@daloyjs/core",
-      "version": "1.0.0-rc.4",
+      "version": "1.0.0-rc.5",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.4",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.5",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-rc.4",
+        "tagId": "swidtag--daloyjs-core-1.0.0-rc.5",
         "name": "@daloyjs/core",
-        "version": "1.0.0-rc.4",
+        "version": "1.0.0-rc.5",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.4",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.5",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-1.0.0-rc.4",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.4-6aa5f3fd-e017-5e4a-b206-49dc6d141768",
+  "name": "@daloyjs/core-1.0.0-rc.5",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.5-4d7ef2ca-7207-5a53-933a-75950561ff0c",
   "creationInfo": {
-    "created": "2026-07-12T20:39:15.454Z",
+    "created": "2026-07-20T09:04:35.490Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.0.0-rc.4",
+      "versionInfo": "1.0.0-rc.5",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.4"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.5"
         }
       ]
     }

package/dist/security.d.ts

@@ -141,6 +141,11 @@ export declare const SMUGGLING_SINGLETON_HEADERS: readonly string[];
  * Throws {@link BadRequestError} so the framework returns a structured
  * `400 problem+json` instead of forwarding a smuggling-class request.
  *
+ * The framework's dispatch path runs this check, the reserved-prefix check,
+ * and the header-count cap in a single shared walk internally (see
+ * {@link assertInboundHeaderGuards}); calling this helper directly is only
+ * needed for custom pipelines.
+ *
  * @param headers - Normalized request headers to inspect.
  * @since 0.15.0
  */
@@ -179,6 +184,10 @@ export declare const RESERVED_INBOUND_HEADER_PREFIXES: readonly string[];
  * `400 problem+json` instead of routing a request that may be probing
  * for an internal-dispatch bypass.
  *
+ * The framework's dispatch path runs this check and the header-count cap
+ * in a single shared walk internally (see {@link assertInboundHeaderGuards});
+ * calling this helper directly is only needed for custom pipelines.
+ *
  * @param headers - Normalized request headers to inspect (names arrive lowercased).
  * @since 0.36.0
  */
@@ -212,11 +221,43 @@ export declare const DEFAULT_MAX_HEADER_COUNT = 100;
  * framework returns a structured `problem+json` response instead of routing
  * a flood.
  *
+ * The framework's dispatch path runs this check and the reserved-prefix
+ * check in a single shared walk internally (see
+ * {@link assertInboundHeaderGuards}); calling this helper directly is only
+ * needed for custom pipelines.
+ *
  * @param headers - The incoming request headers.
  * @param limit - Maximum distinct header fields to allow. `0` disables.
  * @since 0.38.0
  */
 export declare function assertHeaderCountWithinLimit(headers: Headers, limit: number): void;
+/**
+ * Combined inbound header guards for the dispatch hot path (internal).
+ *
+ * Runs the singleton-duplicate check ({@link assertNoDuplicateSingletonHeaders}),
+ * the reserved-internal-prefix check ({@link assertNoReservedInternalHeaders}),
+ * and the header-count cap ({@link assertHeaderCountWithinLimit}) in a
+ * **single** walk of the header map, with the same observable semantics as
+ * calling the helpers in sequence: any `400`-class violation (duplicate
+ * singleton header or reserved internal header) anywhere in the map is
+ * rejected with `400` even when the map also exceeds the count cap. To
+ * preserve that precedence, the `431` count-cap rejection is deferred until
+ * the scan has covered every header — the same full-walk cost the
+ * sequential helpers already paid.
+ *
+ * A non-positive / non-finite `limit` disables the count cap (same as
+ * {@link assertHeaderCountWithinLimit}) while still rejecting duplicate
+ * singleton headers and reserved internal prefixes.
+ *
+ * @param headers - Normalized request headers (names arrive lowercased).
+ * @param limit - Maximum distinct header fields to allow. `0` disables the count cap.
+ * @throws {BadRequestError} When a duplicate singleton header or a reserved
+ *   internal header is present (takes precedence over the count cap).
+ * @throws {RequestHeaderFieldsTooLargeError} When no `400`-class violation is
+ *   present and the distinct-header count exceeds `limit`.
+ * @since 1.0.0
+ */
+export declare function assertInboundHeaderGuards(headers: Headers, limit: number): void;
 /**
  * Minimum acceptable secret length in bytes for HMAC / signing material in
  * production (boot guard). Matches the OWASP "Secret Management"