@daloyjs/core 0.37.0 → 0.38.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DaloyJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,11 +9,18 @@
 
 # DaloyJS
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/daloyjs/daloy/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/daloyjs/daloy/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/daloyjs/daloy/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/daloyjs/daloy/actions/workflows/codeql.yml)
 [![Publish](https://github.com/daloyjs/daloy/actions/workflows/release.yml/badge.svg)](https://github.com/daloyjs/daloy/actions/workflows/release.yml)
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/daloyjs/daloy/badge)](https://securityscorecards.dev/viewer/?uri=github.com/daloyjs/daloy)
 [![Zizmor](https://github.com/daloyjs/daloy/actions/workflows/zizmor.yml/badge.svg?branch=main)](https://github.com/daloyjs/daloy/actions/workflows/zizmor.yml)
+[![GitHub last commit](https://img.shields.io/github/last-commit/daloyjs/daloy)](https://github.com/daloyjs/daloy/commits/main)
+[![npm version](https://img.shields.io/npm/v/@daloyjs/core)](https://www.npmjs.com/package/@daloyjs/core)
+[![JSR](https://jsr.io/badges/@daloyjs/daloy)](https://jsr.io/@daloyjs/daloy)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13058/badge)](https://www.bestpractices.dev/projects/13058)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/daloyjs/daloy/badge)](https://securityscorecards.dev/viewer/?uri=github.com/daloyjs/daloy)
+[![Security Responsible
+Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg)](https://github.com/daloyjs/daloy/blob/main/SECURITY.md)
 
 > A **runtime-portable TypeScript web framework** with built-in **contract-first routing**, **validation**, **OpenAPI (Hey API)**, **typed client generation**, **large-scale maintainability**, and **security-focused runtime plus supply-chain posture**.
 
@@ -32,6 +39,7 @@ DaloyJS exists to be the framework you'd build if you took the best ideas from e
 | Mature **Swagger / docs / ops** in Node                    | [Fastify](https://fastify.dev/docs/latest/Reference/)                 | Encapsulated plugins, structured logger, graceful shutdown, request ids, and lifecycle hooks — all first-party.       |
 | Modern **TS-first DX**, Bun acceptable                     | [Elysia](https://elysiajs.com/at-glance.html)                         | End-to-end typed handlers, typed context, and a typed in-process client — no codegen step required.                   |
 | Best-in-class **typed client codegen** for any consumer    | [Hey API](https://heyapi.dev/openapi-ts/get-started)                  | One `pnpm gen` command emits a fully-typed fetch SDK from your live OpenAPI spec.                                     |
+| **Contract-first typed client, no codegen**                | [ts-rest](https://ts-rest.com/)                                       | Your route definition *is* the contract: an in-process typed client with zero codegen, plus OpenAPI 3.1 + a Hey API SDK for consumers that can't import your types. |
 | Opinionated **DI / module architecture** for large teams   | [NestJS](https://docs.nestjs.com/)                                    | Plugin encapsulation, `register()` prefixes, and `defineDependency()` typed-DI with per-request dedup — no decorators. |
 | Minimalist **async middleware cascade**                    | [Koa](https://koajs.com/)                                             | Koa-style `Context` on a web-standard core, with validation, OpenAPI, errors, and security headers in-box.            |
 | **Services + real-time** API framework                     | [FeathersJS](https://feathersjs.com/)                                 | First-party `app.ws()` with CSWSH refuse-to-boot guards, plus SSE / NDJSON streaming over explicit OpenAPI routes.    |
@@ -55,6 +63,7 @@ Each existing stack is excellent at one thing and forces tradeoffs everywhere el
 - Fastify has the best Node ops story but is Node-only and validation/types/docs are not unified.
 - FastAPI has the best docs ergonomics — but it's Python.
 - Hey API gives you the best typed client — but you still need a server that produces a clean spec.
+- ts-rest gives lovely end-to-end types from a shared contract — but it rides on top of another server (Express/Fastify/Nest/Next), its safety is TypeScript-only, and OpenAPI and security are bring-your-own.
 - npm leaves supply-chain protection up to you.
 
 DaloyJS combines the wins:
@@ -221,6 +230,10 @@ const r = await client.getBookById({ params: { id: "1" } });
 //    ^? { status: 200; body: { id: string; title: string } } | { status: 404; ... }
 ```
 
+> Method inference relies on **chaining** your `app.route(...)` calls (`new App().route(a).route(b)`) and letting
+> TypeScript infer the variable's type. A widening `const app: App` annotation, a `: App` factory return type, or
+> registering routes as separate statements erases the per-route types and collapses the client to an untyped surface.
+
 ---
 
 ## Built-in docs UI (Scalar / Swagger UI)
@@ -311,6 +324,7 @@ deployment.
 | **Header / response splitting**  | Core header sanitizers reject CRLF + NUL.                                                                                                                                                                             |
 | **Path traversal**               | Core router rejects `..` segments and `//` before walking.                                                                                                                                                            |
 | **Slow-loris / hung handlers**   | Core `requestTimeoutMs` aborts handlers (default 30 s); Node adapter sets `requestTimeout` + `headersTimeout` + `maxHeaderSize`.                                                                                      |
+| **HTTP/2 Bomb / header-count flood** | Core `maxHeaderCount` rejects requests with more than 100 header fields (`431`) before routing; Node adapter sets `server.maxHeadersCount`. See [SECURITY.md](SECURITY.md) for the upstream HTTP/2 mitigations.   |
 | **MIME sniffing**                | First-party `secureHeaders()` sets `X-Content-Type-Options: nosniff`; scaffolded apps enable it.                                                                                                                      |
 | **Clickjacking**                 | First-party `secureHeaders()` sets `X-Frame-Options: DENY` + CSP `frame-ancestors 'none'`; scaffolded apps enable it.                                                                                                 |
 | **XSS via injected scripts**     | First-party `secureHeaders()` provides a strict CSP `default-src 'self'` baseline; the directives-object form supports per-request **nonces** and **Trusted Types** (`require-trusted-types-for 'script'`).           |
@@ -328,6 +342,33 @@ deployment.
 
 ---
 
+## Authentication, OAuth2 & OpenID Connect
+
+DaloyJS is a **resource server** (and a toolkit for building a relying party),
+**not** an identity provider. Like Hono, Express, Fastify, or ASP.NET Core, it
+*verifies* and *enforces* tokens on each request — it does **not** ship a login
+UI, a user database, or an OAuth2 authorization server. It is **not** an
+"IdentityServer": it cannot, on its own, do what Duende IdentityServer,
+Keycloak, or Auth0 do (run login pages, manage clients/consent, mint tokens).
+
+To add login you bring an **OpenID Connect provider**. It does not have to be
+Auth0/Okta/Clerk specifically — any standards-compliant IdP works, including
+managed (Auth0, Okta, Clerk, Microsoft Entra ID, AWS Cognito) and **self-hosted
+open source** (Keycloak, Zitadel, Ory, Authentik, Logto, SuperTokens, Dex).
+Don't build your own authorization server — verify tokens from a vetted one.
+
+- **API as a resource server (default):** verify JWTs with `jwk()` against the
+  provider's JWKS (asymmetric-only algorithm allowlist, `issuer`/`audience`
+  enforced), then authorize per route with `requireScopes()`.
+- **Browser app:** use the back-end-for-frontend (BFF) pattern — run the
+  authorization-code + PKCE flow server-side, keep tokens in a `session()`
+  cookie (never in JavaScript), and protect mutations with `csrf()`.
+
+Read [Auth architecture: where DaloyJS fits in OAuth2 & OpenID Connect](https://daloyjs.dev/docs/auth/architecture)
+for the full picture, plus the per-provider guides under [`/docs/auth`](https://daloyjs.dev/docs/auth).
+
+---
+
 ## Performance
 
 ```text
@@ -418,6 +459,7 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 - Hono — portable web-standard router: <https://hono.dev/docs/>
 - Elysia — TS-first DX & typed context: <https://elysiajs.com/at-glance.html>
 - Fastify — production Node web framework: <https://fastify.dev/docs/latest/Reference/>
+- ts-rest — contract-first, RPC-like client/server over REST: <https://ts-rest.com/>
 - pnpm — strict, secure, content-addressable package manager: <https://pnpm.io/motivation>
 - Standard Schema — universal validator interface: <https://github.com/standard-schema/standard-schema>
 - RFC 9457 — Problem Details for HTTP APIs: <https://www.rfc-editor.org/rfc/rfc9457>
@@ -556,6 +598,7 @@ A growing suite of static gates runs on every push and PR:
 - Parity / governance / runtime-parity / routing-hardening audits: `verify:parity-audits`, `verify:governance-audits`, `verify:runtime-parity-audits`, `verify:routing-hardening-audits`.
 - Source-tree gates: `verify:no-shrinkwrap`, `verify:no-bin-shadowing`, `verify:no-native-addons`, `verify:no-polyfill-cdns` (hijacked-CDN IOCs and typosquats), `verify:no-redos-patterns`, `verify:no-encoded-payloads`, `verify:no-invisible-unicode`, `verify:no-weak-random`, `verify:no-unsafe-buffer`, `verify:no-leaked-credentials`, `verify:no-vulnerable-sandboxes`.
 - Agent-skill gates: `verify:no-leaky-agent-skills`, `verify:no-toxic-agent-skills`, `verify:no-toxic-skills` — scanning every agent-instruction surface (`SKILL.md`, `AGENTS.md`, `copilot-instructions.md`, `.cursorrules`, `CLAUDE.md`, `*.instructions.md`, `*.prompt.md`); the `.cursorrules` / `CLAUDE.md` filenames cover the **TrapDoor** crypto-stealer's AI-agent-config prompt-injection persistence ([Socket, 2026-05-24](https://socket.dev/blog/trapdoor-crypto-stealer)).
+- Agent / editor config-autorun gate: `verify:no-agent-config-autorun` — refuses editor / AI-coding-agent config files that auto-execute a command on folder open or session start (VS Code `folderOpen` task, Claude/Gemini `"type": "command"` hook, Cursor `alwaysApply` run-a-script rule, a `package.json` `"test": "node .github/setup.js"` hijack, or a loose `.github/` dropper), covering the **Miasma** worm's config-injection detonation surface ([SafeDep, 2026-06-05](https://safedep.io/miasma-worm-ai-coding-agent-config-injection/)).
 - Dependency gates: `verify:no-runtime-deps`, `verify:dep-licenses`, `verify:known-dep-names`, `verify:lockfile-sources`, `verify:no-registry-exfiltration`, `verify:no-remote-exec`, `verify:no-lifecycle-scripts`, `verify:runtime-eol` (refuses to release on a Node line past its EOL date).
 - IOC coverage in `verify:no-registry-exfiltration` and `verify:lockfile-sources` for active campaigns including Beamglea phishing-CDN, `naya-flore` / `nvlore-hsc` WhatsApp remote-kill-switch, the Toptal GitHub-org hijack, `xuxingfeng` and `xlsx-to-json-lh` destructive payloads, `react-login-page` keylogger, `@crypto-exploit` wallet drainers, Vietnam-Telegram-ban Fastlane typosquats, surveillance-malware packages, the Discord-webhook reconnaissance campaign, the `codexui-android` AI-coding-agent token theft (reads of `~/.codex/auth.json` / `~/.claude/`), and npm-package-aliasing dependency-confusion patterns.
 - `SECURITY-CONTACTS.md` rotation file with a machine-readable ACTIVE block and `<!-- last-exercise: -->` marker; the release workflow refuses to publish when `github.actor` is not on the ACTIVE rotation.

package/dist/adapters/node.d.ts

@@ -16,6 +16,20 @@ export interface NodeServerOptions {
     handleSignals?: boolean;
     /** Maximum HTTP header size bytes (DoS protection). Default: 16 KiB. */
     maxHeaderBytes?: number;
+    /**
+     * Maximum number of incoming HTTP header fields, forwarded to Node's
+     * `server.maxHeadersCount`. This is the native, parser-level counterpart to
+     * the framework's portable {@link "../app.js".AppOptions.maxHeaderCount}
+     * guard: a header-count flood is dropped by the HTTP parser before it ever
+     * becomes a `Request`, which is the cheapest place to shed header-count
+     * amplification (the dimension abused by the "HTTP/2 Bomb"). Node's own
+     * default is `2000`; this adapter tightens it to `100` to mirror the
+     * application-tier cap. Set `0` to disable (use Node's unbounded default).
+     * Default: 100.
+     *
+     * @since 0.38.0
+     */
+    maxHeaderCount?: number;
     /**
      * Maximum number of concurrent sockets the server will accept, forwarded to
      * Node's `server.maxConnections`. Acts as connection-layer admission

package/dist/adapters/node.js

@@ -36,6 +36,14 @@ export function serve(app, opts = {}) {
     server.requestTimeout = opts.connectionTimeoutMs ?? 30_000;
     server.headersTimeout = opts.connectionTimeoutMs ?? 30_000;
     server.keepAliveTimeout = 5_000;
+    // Native parser-level header-count cap. Drops header-count floods (the
+    // "HTTP/2 Bomb" amplification dimension) before they become a Request.
+    // `0` opts out and restores Node's unbounded-ish default (2000).
+    const maxHeaderCount = opts.maxHeaderCount;
+    server.maxHeadersCount =
+        typeof maxHeaderCount === "number" && maxHeaderCount >= 0
+            ? maxHeaderCount
+            : 100;
     // Connection-layer admission control. Reject overflow sockets at accept time
     // rather than queuing them into the event loop under overload.
     if (typeof opts.maxConnections === "number" && opts.maxConnections > 0) {

package/dist/app.d.ts

@@ -75,6 +75,19 @@ export interface AppOptions {
     allowedContentTypes?: string[];
     /** Per-request timeout in ms (handler + hooks). Default: 30000. Set 0 to disable. */
     requestTimeoutMs?: number;
+    /**
+     * Maximum number of distinct request header fields accepted before the
+     * request is rejected with `431 Request Header Fields Too Large`. This is
+     * the runtime-portable, application-tier defence against header-*count*
+     * amplification (the dimension abused by the "HTTP/2 Bomb", where
+     * per-header server-side bookkeeping — not header size — is the
+     * amplifier). It complements the native header-count caps a runtime/proxy
+     * terminating HTTP/2 must apply (NGINX `max_headers`, Node
+     * `server.maxHeadersCount`). Set `0` to disable. Default: 100.
+     *
+     * @since 0.38.0
+     */
+    maxHeaderCount?: number;
     /**
      * Per-request limits applied when parsing `multipart/form-data` bodies.
      * These run in addition to `bodyLimitBytes`. Use them to cap the size of
@@ -663,13 +676,37 @@ export declare const DALOY_RAW_STREAM: unique symbol;
  * serve(app, { port: 3000 });
  * ```
  *
+/**
+ * Append a freshly-registered route to an `App`'s accumulated route tuple.
+ *
+ * A newly-constructed `App` starts with the permissive default
+ * `readonly RouteDefinition<any, any, any, any>[]` so that bare `App`
+ * annotations (e.g. `serve(app: App)`) accept any instance. The first
+ * {@link App.route} call resets that wide default to a clean single-element
+ * tuple, so the typed client (`createClient(app)`) is keyed only by the
+ * routes the caller actually registered; subsequent calls append precisely.
+ *
+ * @typeParam Routes - The current accumulated route tuple.
+ * @typeParam R - The route definition being registered.
+ */
+type AppendRoute<Routes extends readonly RouteDefinition<any, any, any, any>[], R extends RouteDefinition<any, any, any, any>> = readonly RouteDefinition<any, any, any, any>[] extends Routes ? readonly [R] : readonly [...Routes, R];
+/**
  * @since 0.1.0
  */
-export declare class App {
+export declare class App<Routes extends readonly RouteDefinition<any, any, any, any>[] = readonly RouteDefinition<any, any, any, any>[]> {
     readonly options: Required<Pick<AppOptions, "validateResponses" | "bodyLimitBytes" | "requestTimeoutMs">> & AppOptions;
     readonly log: Logger;
-    /** Public registry: enables OpenAPI gen, typed-client gen, dead-route detection. */
-    readonly routes: RouteDefinition<any, any, any, any>[];
+    /**
+     * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
+     *
+     * Statically the property is typed as the `Routes` tuple so that
+     * {@link App.route} can accumulate each registered route's literal
+     * `operationId`, request, and response types. The typed client
+     * (`createClient(app)`) reads this tuple to derive a precisely-typed method
+     * per route. At runtime it is an ordinary growable array — the tuple typing
+     * is a compile-time view only.
+     */
+    readonly routes: Routes;
     private router;
     /**
      * Memoized result of `isProduction()`. The inputs (`options.env`,
@@ -797,6 +834,7 @@ export declare class App {
         trustProxy: true | false | "unconfigured";
         bodyLimitBytes: number;
         requestTimeoutMs: number;
+        maxHeaderCount: number;
         stripServerHeaders: boolean;
         production: boolean;
     };
@@ -921,10 +959,22 @@ export declare class App {
      * });
      * ```
      *
+     * The return type widens `Routes` with the freshly-registered route so
+     * that chained registration (`new App().route(a).route(b)`) accumulates a
+     * precise tuple. The typed client (`createClient(app)`) consumes that tuple
+     * to expose a method per `operationId` with parameters and responses
+     * inferred from the route's own schemas. Non-chained calls
+     * (`app.route(a); app.route(b);`) keep the variable's original type, so
+     * chain the calls when you want the inferred client surface.
+     *
      * @param def - The route definition.
-     * @returns This `App` instance for chaining.
+     * @returns This `App` instance (widened with the new route) for chaining.
      */
-    route<P extends PathString, M extends HttpMethod, Req extends RequestSchemas | undefined, Res extends ResponsesMap>(def: RouteDefinition<P, M, Req, Res>): this;
+    route<P extends PathString, M extends HttpMethod, Req extends RequestSchemas | undefined, Res extends ResponsesMap, const Op extends string | undefined = undefined>(def: RouteDefinition<P, M, Req, Res> & {
+        operationId?: Op;
+    }): App<AppendRoute<Routes, RouteDefinition<P, M, Req, Res> & {
+        operationId: Op;
+    }>>;
     /**
      * Register a WebSocket route. The handler runs when an HTTP client sends an
      * `Upgrade: websocket` request to `path`; the adapter performs the RFC 6455
@@ -1332,3 +1382,4 @@ export declare function createApp(options?: AppOptions): App;
  * @internal
  */
 export declare function _resetPackageJsonCacheForTests(): void;
+export {};

package/dist/app.js

@@ -2,7 +2,7 @@ import { Router } from "./router.js";
 import { WebSocketRegistry, normalizeWebSocketOptions, } from "./websocket.js";
 import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, TooManyRequestsError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
 import { validate } from "./schema.js";
-import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey } from "./security.js";
+import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey } from "./security.js";
 import { createLogger, noopLogger } from "./logger.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
 import { docsContentSecurityPolicy, scalarHtml, swaggerUiHtml, } from "./docs.js";
@@ -149,6 +149,7 @@ function applySecurityPreset(options) {
 const DEFAULTS = {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 30_000,
+    maxHeaderCount: DEFAULT_MAX_HEADER_COUNT,
     validateResponses: true,
 };
 const TEXT_ENCODER = new TextEncoder();
@@ -181,58 +182,21 @@ export const DALOY_REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
  */
 export const DALOY_RAW_STREAM = Symbol.for("daloyjs.response.rawStream");
 /**
- * Contract-first HTTP application.
- *
- * `App` is the top-level entry point: register {@link RouteDefinition routes}
- * with {@link App.route}, layer cross-cutting behavior with
- * {@link App.use}/{@link App.register}, then expose the application to a
- * runtime via {@link App.fetch} (Web standard) or one of the adapter subpaths
- * such as `@daloyjs/core/node`, `@daloyjs/core/cloudflare`, or
- * `@daloyjs/core/lambda`.
- *
- * The same `App` instance powers:
- *
- *  - request routing (`Router` under the hood)
- *  - request/response validation against Standard-Schema validators
- *  - OpenAPI 3.1 generation (`generateOpenAPI(app)`)
- *  - typed in-process client (`createClient(app)`) and generated SDK
- *  - graceful shutdown and lifecycle observability
- *
- * `App` is **runtime-agnostic**: the same instance runs on Node, Bun, Deno,
- * Cloudflare Workers, Vercel Edge, AWS Lambda, and Fastly Compute via the
- * dedicated adapters.
- *
- * @example
- * ```ts
- * import { App, secureHeaders } from "@daloyjs/core";
- * import { z } from "zod";
- *
- * const app = new App({ title: "Books API", version: "1.0.0" });
- *
- * app.use(secureHeaders());
- *
- * app.route({
- *   method: "GET",
- *   path: "/books/:id",
- *   operationId: "getBook",
- *   request: { params: z.object({ id: z.uuid() }) },
- *   responses: {
- *     200: { description: "OK", body: z.object({ id: z.string(), title: z.string() }) },
- *   },
- *   handler: ({ params }) => ({ status: 200, body: { id: params.id, title: "Dune" } }),
- * });
- *
- * // Node:
- * import { serve } from "@daloyjs/core/node";
- * serve(app, { port: 3000 });
- * ```
- *
  * @since 0.1.0
  */
 export class App {
     options;
     log;
-    /** Public registry: enables OpenAPI gen, typed-client gen, dead-route detection. */
+    /**
+     * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
+     *
+     * Statically the property is typed as the `Routes` tuple so that
+     * {@link App.route} can accumulate each registered route's literal
+     * `operationId`, request, and response types. The typed client
+     * (`createClient(app)`) reads this tuple to derive a precisely-typed method
+     * per route. At runtime it is an ordinary growable array — the tuple typing
+     * is a compile-time view only.
+     */
     routes = [];
     router = new Router();
     /**
@@ -328,6 +292,7 @@ export class App {
             validateResponses: resolved.validateResponses ?? DEFAULTS.validateResponses,
             bodyLimitBytes: resolved.bodyLimitBytes ?? DEFAULTS.bodyLimitBytes,
             requestTimeoutMs: resolved.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs,
+            maxHeaderCount: resolved.maxHeaderCount ?? DEFAULTS.maxHeaderCount,
             ...resolved,
         };
         this.log =
@@ -386,7 +351,8 @@ export class App {
                 "If you really need this in production, also pass " +
                 "acknowledgeInsecureDefaults: true to confirm. Prefer per-feature opt-outs " +
                 "(secureHeaders: false, corsCrossOriginGuard: false, crashOnUnhandledRejection: false, " +
-                "trustProxy: false, csrf: \"off\") instead.");
+                "trustProxy: false, csrf: \"off\") instead. " +
+                "See https://daloyjs.dev/docs/security/secure-defaults-enforcement.");
         }
         if (!insecureDefaultsLoggedThisProcess) {
             insecureDefaultsLoggedThisProcess = true;
@@ -456,6 +422,7 @@ export class App {
             trustProxy: o.trustProxy === undefined ? "unconfigured" : o.trustProxy,
             bodyLimitBytes: this.options.bodyLimitBytes,
             requestTimeoutMs: this.options.requestTimeoutMs,
+            maxHeaderCount: this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT,
             stripServerHeaders: o.stripServerHeaders !== false,
             production: this.isProduction(),
         });
@@ -700,8 +667,11 @@ export class App {
             return;
         const err = new Error(`session() is registered in the hook chain for a state-changing route ` +
             `(${stateChanging.method} ${stateChanging.path}) but no csrf() hook is installed. ` +
+            `Without CSRF protection a browser can be tricked into making authenticated ` +
+            `state-changing requests cross-site. ` +
             `Register csrf() via app.use(csrf({ strategy: "fetch-metadata", allowedOrigins: [...] })), ` +
-            `or pass app({ csrf: "off" }) to acknowledge that this app is not browser-facing.`);
+            `or pass app({ csrf: "off" }) to acknowledge that this app is not browser-facing. ` +
+            `See https://daloyjs.dev/docs/security/boot-guards.`);
         this.bootGuard.error = err;
         throw err;
     }
@@ -751,9 +721,12 @@ export class App {
             this.log.warn({ event: "trust-proxy.unconfigured", header: found }, `Request carried ${found} but app({ trustProxy }) is unset; refusing to honour spoofable proxy headers.`);
         }
         throw new InternalError(`Refusing to dispatch request: ${found} header is present but app({ trustProxy }) is unconfigured. ` +
+            `Honouring a spoofable forwarded header would let a client forge its source IP for the rate ` +
+            `limiter, audit log, and request-id propagation. ` +
             `Pass app({ trustProxy: true }) when running behind a trusted reverse proxy, ` +
             `or app({ trustProxy: false }) to ignore forwarded headers, ` +
-            `or app({ secureDefaults: false }) to disable this guard.`);
+            `or app({ secureDefaults: false }) to disable this guard. ` +
+            `See https://daloyjs.dev/docs/security/boot-guards.`);
     }
     /**
      * Resolve the {@link AppOptions.docs} option and, when enabled, register
@@ -915,8 +888,16 @@ export class App {
      * });
      * ```
      *
+     * The return type widens `Routes` with the freshly-registered route so
+     * that chained registration (`new App().route(a).route(b)`) accumulates a
+     * precise tuple. The typed client (`createClient(app)`) consumes that tuple
+     * to expose a method per `operationId` with parameters and responses
+     * inferred from the route's own schemas. Non-chained calls
+     * (`app.route(a); app.route(b);`) keep the variable's original type, so
+     * chain the calls when you want the inferred client surface.
+     *
      * @param def - The route definition.
-     * @returns This `App` instance for chaining.
+     * @returns This `App` instance (widened with the new route) for chaining.
      */
     route(def) {
         // Refuse non-canonical HTTP methods at runtime.
@@ -965,6 +946,9 @@ export class App {
             ...sources,
         ]);
         this.router.add(def.method, fullPath, { def: merged, hooks, mergedHooks, hasFinalizeHook, corsOriginAllows, fullCorsOriginAllows }, def.operationId);
+        // `routes` is statically a readonly tuple so the typed client can infer
+        // per-route methods; at runtime it is a growable array, so we push through
+        // a mutable view.
         this.routes.push(merged);
         this.routeSecurityMarkers.push({
             method: merged.method,
@@ -1834,6 +1818,7 @@ export class App {
         try {
             assertNoDuplicateSingletonHeaders(request.headers);
             assertNoReservedInternalHeaders(request.headers);
+            assertHeaderCountWithinLimit(request.headers, this.options.maxHeaderCount ?? DEFAULT_MAX_HEADER_COUNT);
             this.assertTrustProxyConfigured(request);
             this.assertBootGuards();
             if (globalHooks.onRequest !== undefined) {

package/dist/cli.js

@@ -651,6 +651,31 @@ async function runDoctor(opts, io) {
                     "JSON parsers are not DoS-amplified by a multipart-sized blob.",
             });
         }
+        // Header-count cap audit. The framework's portable maxHeaderCount
+        // guard is the application-tier defence against header-*count*
+        // amplification (the "HTTP/2 Bomb" dimension). Surface a finding when
+        // it is disabled (0) or raised to an implausibly generous value, both
+        // of which let a header flood reach routing.
+        const maxHeaderCount = o.maxHeaderCount;
+        if (maxHeaderCount === 0) {
+            findings.push({
+                level: "warn",
+                code: "audit.maxHeaderCount.disabled",
+                message: "maxHeaderCount is 0 — the header-count flood guard is disabled. " +
+                    "A request carrying thousands of header fields reaches routing. " +
+                    "Keep a finite cap (default 100) unless an upstream proxy already " +
+                    "enforces one (NGINX max_headers, Node server.maxHeadersCount).",
+            });
+        }
+        else if (typeof maxHeaderCount === "number" && maxHeaderCount > 1000) {
+            findings.push({
+                level: "warn",
+                code: "audit.maxHeaderCount.blanket",
+                message: `maxHeaderCount is ${maxHeaderCount} (> 1000). Realistic requests ` +
+                    "carry a few dozen headers; a cap this high weakens the " +
+                    "header-count amplification defence.",
+            });
+        }
         // Idle-timeout / request-timeout audit. Reaffirms the
         // existing requestTimeoutMs check; also surface an explicit zero
         // idleTimeoutMs in production. The framework also keeps adapter

package/dist/client.d.ts

@@ -17,6 +17,13 @@ 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 per-method types are recovered from the `App`'s accumulated route tuple,
+ * which is built up as you **chain** `app.route(...)` calls. If the `App` type
+ * is widened back to its bare default — e.g. a `const app: App` annotation, a
+ * `: App` factory return type, or registering routes as separate statements
+ * rather than a chain — the tuple is erased and this type collapses to an
+ * untyped, string-indexed record.
  */
 export type ClientFor<A extends App> = {
     [R in Extract<RoutesOf<A>, {
@@ -58,10 +65,26 @@ export interface ClientOptions {
  * For non-TypeScript consumers, run `pnpm gen` to emit a fully-typed SDK
  * from the OpenAPI document instead.
  *
+ * @remarks
+ * The method signatures are inferred from the `App`'s accumulated route tuple,
+ * so chain your `app.route(...)` registrations and let TypeScript infer the
+ * variable's type. A widening `const app: App` annotation, a `: App` factory
+ * return type, or registering routes as separate statements erases the
+ * per-route types and yields an untyped client.
+ *
  * @example
  * ```ts
  * import { createClient } from "@daloyjs/core/client";
  *
+ * const app = new App().route({
+ *   method: "GET",
+ *   path: "/books/:id",
+ *   operationId: "getBook",
+ *   request: { params: z.object({ id: z.string() }) },
+ *   responses: { 200: { description: "OK", body: z.object({ id: z.string(), title: z.string() }) } },
+ *   handler: ({ params }) => ({ status: 200, body: { id: params.id, title: "Dune" } }),
+ * });
+ *
  * const client = createClient(app, { baseUrl: "https://api.example.com" });
  * const res = await client.getBook({ params: { id: "123" } });
  * if (res.status === 200) console.log(res.body.title);

package/dist/client.js

@@ -22,10 +22,26 @@
  * For non-TypeScript consumers, run `pnpm gen` to emit a fully-typed SDK
  * from the OpenAPI document instead.
  *
+ * @remarks
+ * The method signatures are inferred from the `App`'s accumulated route tuple,
+ * so chain your `app.route(...)` registrations and let TypeScript infer the
+ * variable's type. A widening `const app: App` annotation, a `: App` factory
+ * return type, or registering routes as separate statements erases the
+ * per-route types and yields an untyped client.
+ *
  * @example
  * ```ts
  * import { createClient } from "@daloyjs/core/client";
  *
+ * const app = new App().route({
+ *   method: "GET",
+ *   path: "/books/:id",
+ *   operationId: "getBook",
+ *   request: { params: z.object({ id: z.string() }) },
+ *   responses: { 200: { description: "OK", body: z.object({ id: z.string(), title: z.string() }) } },
+ *   handler: ({ params }) => ({ status: 200, body: { id: params.id, title: "Dune" } }),
+ * });
+ *
  * const client = createClient(app, { baseUrl: "https://api.example.com" });
  * const res = await client.getBook({ params: { id: "123" } });
  * if (res.status === 200) console.log(res.body.title);

package/dist/errors.d.ts

@@ -299,6 +299,29 @@ export declare class MethodNotAllowedError extends HttpError {
 export declare class PayloadTooLargeError extends HttpError {
     constructor(limit: number);
 }
+/**
+ * `431 Request Header Fields Too Large` — thrown when an incoming request
+ * carries more distinct header fields than {@link AppOptions.maxHeaderCount}.
+ *
+ * This is the portable, JS-layer counterpart to the native "max header
+ * count" caps that web servers and proxies expose (e.g. NGINX's
+ * `max_headers`, Node's `server.maxHeadersCount`). It is defence-in-depth
+ * against header-*count* amplification — the dimension abused by the
+ * "HTTP/2 Bomb" (Calif, 2026), where per-header server-side bookkeeping is
+ * the amplifier rather than header size. A flood of nearly-empty headers
+ * never reaches the router because the count cap fires first.
+ *
+ * The native HPACK session-memory pinning that the bomb relies on must
+ * still be mitigated at the runtime/proxy that terminates HTTP/2 (apply the
+ * vendor fix and cap the header count there); this guard protects the
+ * application tier on every runtime regardless of upstream configuration.
+ *
+ * @param limit - The configured maximum header count that was exceeded.
+ * @since 0.38.0
+ */
+export declare class RequestHeaderFieldsTooLargeError extends HttpError {
+    constructor(limit: number);
+}
 /**
  * `415 Unsupported Media Type` — thrown when the request `Content-Type` is
  * not in {@link AppOptions.allowedContentTypes} for a route that declares a

package/dist/errors.js

@@ -395,6 +395,36 @@ export class PayloadTooLargeError extends HttpError {
         this.name = "PayloadTooLargeError";
     }
 }
+/**
+ * `431 Request Header Fields Too Large` — thrown when an incoming request
+ * carries more distinct header fields than {@link AppOptions.maxHeaderCount}.
+ *
+ * This is the portable, JS-layer counterpart to the native "max header
+ * count" caps that web servers and proxies expose (e.g. NGINX's
+ * `max_headers`, Node's `server.maxHeadersCount`). It is defence-in-depth
+ * against header-*count* amplification — the dimension abused by the
+ * "HTTP/2 Bomb" (Calif, 2026), where per-header server-side bookkeeping is
+ * the amplifier rather than header size. A flood of nearly-empty headers
+ * never reaches the router because the count cap fires first.
+ *
+ * The native HPACK session-memory pinning that the bomb relies on must
+ * still be mitigated at the runtime/proxy that terminates HTTP/2 (apply the
+ * vendor fix and cap the header count there); this guard protects the
+ * application tier on every runtime regardless of upstream configuration.
+ *
+ * @param limit - The configured maximum header count that was exceeded.
+ * @since 0.38.0
+ */
+export class RequestHeaderFieldsTooLargeError extends HttpError {
+    constructor(limit) {
+        super(431, {
+            type: "https://daloyjs.dev/errors/request-header-fields-too-large",
+            title: "Request Header Fields Too Large",
+            detail: `Request carries more than ${limit} header fields`,
+        });
+        this.name = "RequestHeaderFieldsTooLargeError";
+    }
+}
 /**
  * `415 Unsupported Media Type` — thrown when the request `Content-Type` is
  * not in {@link AppOptions.allowedContentTypes} for a route that declares a

package/dist/index.d.ts

@@ -11,13 +11,13 @@ 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 { HttpError, BadRequestError, ValidationError, NotFoundError, ConflictError, UnauthorizedError, ForbiddenError, MethodNotAllowedError, PayloadTooLargeError, UnsupportedMediaTypeError, TooManyRequestsError, RequestTimeoutError, InternalError, MessageLeakError, httpError, SAFE_CUSTOM_ERROR_RESPONSE_HEADERS, checkCustomErrorResponseHeaders, } from "./errors.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";
 export { validate, isStandardSchema } from "./schema.js";
 export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
 export type { ChangeSeverity, OpenAPIChange, OpenAPIDiffResult, } from "./openapi-diff.js";
-export { readBodyLimited, safeJsonParse, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, 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, 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, csrf, CSRF_HOOK_MARKER, fetchMetadata, requireScopes, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, _resetSharedRateLimitStoresForTests, } from "./middleware.js";
 export { etag } from "./etag.js";

package/dist/index.js

@@ -6,10 +6,10 @@ export { _resetInsecureDefaultsLogForTests } from "./app.js";
 export { getConnInfo, setConnInfo, assertBehindProxy, resolveClientIp, readRemoteAddress, readRemotePort, pickForwardedForByHops, } from "./conn-info.js";
 export { subdomains, PSL_SNAPSHOT_DATE, PSL_PUBLIC_SUFFIXES, MAX_SNAPSHOT_AGE_DAYS, } from "./subdomains.js";
 export { defineDependency, DEPENDENCY_MARKER } from "./dependency.js";
-export { HttpError, BadRequestError, ValidationError, NotFoundError, ConflictError, UnauthorizedError, ForbiddenError, MethodNotAllowedError, PayloadTooLargeError, UnsupportedMediaTypeError, TooManyRequestsError, RequestTimeoutError, InternalError, MessageLeakError, httpError, SAFE_CUSTOM_ERROR_RESPONSE_HEADERS, checkCustomErrorResponseHeaders, } from "./errors.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 { validate, isStandardSchema } from "./schema.js";
 export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
-export { readBodyLimited, safeJsonParse, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, 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, 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, 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";

package/dist/jwt.js

@@ -236,7 +236,10 @@ export function createJwtSigner(opts) {
     }
     const { alg } = opts;
     if (alg === "none") {
-        throw new JwtError("alg_none_refused", 'jwt(): alg "none" is refused.');
+        throw new JwtError("alg_none_refused", 'jwt(): alg "none" is refused — it disables signature verification, so anyone could forge a ' +
+            'token by setting the header alg to "none" (the classic JWT signature-stripping / algorithm-' +
+            "confusion attack). Choose a real signing algorithm such as HS256 (shared secret) or " +
+            "RS256 / ES256 (key pair). See https://daloyjs.dev/docs/security/secure-defaults-enforcement.");
     }
     if (!ALL_ALGS.has(alg)) {
         throw new JwtError("invalid_alg", `jwt(): unknown algorithm "${String(alg)}". Allowed: ${[...ALL_ALGS].sort().join(", ")}.`);
@@ -335,7 +338,10 @@ export function createJwtVerifier(opts) {
     const allow = new Set();
     for (const alg of opts.algorithms) {
         if (alg === "none") {
-            throw new JwtError("alg_none_refused", 'jwt(): alg "none" cannot appear in the allowlist.');
+            throw new JwtError("alg_none_refused", 'jwt(): alg "none" cannot appear in the algorithms allowlist — it disables signature ' +
+                "verification and would let any caller forge a token. Remove it and list only real " +
+                "algorithms such as HS256, RS256, or ES256. " +
+                "See https://daloyjs.dev/docs/security/secure-defaults-enforcement.");
         }
         if (!ALL_ALGS.has(alg)) {
             throw new JwtError("invalid_alg", `jwt(): unknown algorithm "${String(alg)}" in allowlist.`);

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:99cd0a75-d472-56c5-bd8e-c5247eb9e1df",
+  "serialNumber": "urn:uuid:51e4c48d-6a2e-5180-8452-1c9b9a5987d9",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-31T20:28:21.245Z",
+    "timestamp": "2026-06-11T09:54:26.041Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.37.0"
+        "version": "0.38.1"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@0.37.0",
+      "bom-ref": "pkg:npm/@daloyjs/core@0.38.1",
       "name": "@daloyjs/core",
-      "version": "0.37.0",
+      "version": "0.38.1",
       "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@0.37.0",
+      "purl": "pkg:npm/@daloyjs/core@0.38.1",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-0.37.0",
+        "tagId": "swidtag--daloyjs-core-0.38.1",
         "name": "@daloyjs/core",
-        "version": "0.37.0",
+        "version": "0.38.1",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@0.37.0",
+      "ref": "pkg:npm/@daloyjs/core@0.38.1",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-0.37.0",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.37.0-99cd0a75-d472-56c5-bd8e-c5247eb9e1df",
+  "name": "@daloyjs/core-0.38.1",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.38.1-51e4c48d-6a2e-5180-8452-1c9b9a5987d9",
   "creationInfo": {
-    "created": "2026-05-31T20:28:21.245Z",
+    "created": "2026-06-11T09:54:26.041Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "0.37.0",
+      "versionInfo": "0.38.1",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@0.37.0"
+          "referenceLocator": "pkg:npm/@daloyjs/core@0.38.1"
         }
       ]
     }

package/dist/security.d.ts

@@ -166,6 +166,40 @@ export declare const RESERVED_INBOUND_HEADER_PREFIXES: readonly string[];
  * @since 0.36.0
  */
 export declare function assertNoReservedInternalHeaders(headers: Headers): void;
+/**
+ * Default cap on the number of distinct request header fields accepted
+ * before {@link assertHeaderCountWithinLimit} rejects the request. Chosen to
+ * sit far above any realistic legitimate request (browsers, tracing layers,
+ * and reverse proxies rarely add more than a few dozen headers) yet far
+ * below the thousands-of-headers floods used by header-count amplification
+ * attacks such as the "HTTP/2 Bomb".
+ *
+ * @since 0.38.0
+ */
+export declare const DEFAULT_MAX_HEADER_COUNT = 100;
+/**
+ * Reject requests that carry more than `limit` distinct header fields.
+ *
+ * This is the runtime-portable, application-tier defence against
+ * header-*count* amplification (the dimension abused by the "HTTP/2 Bomb",
+ * where per-entry server bookkeeping — not header size — is the amplifier).
+ * It complements, and does not replace, the native header-count caps that a
+ * runtime/proxy terminating HTTP/2 must apply (NGINX `max_headers`, Node
+ * `server.maxHeadersCount`, etc.). Because the WHATWG `Headers` collection
+ * coalesces same-named fields, the count is over distinct header names —
+ * the truest signal available once a request has been normalised to a
+ * web-standard `Request`.
+ *
+ * A `limit` of `0` (or any non-positive / non-finite value) disables the
+ * check. Throws {@link RequestHeaderFieldsTooLargeError} (`431`) so the
+ * framework returns a structured `problem+json` response instead of routing
+ * a flood.
+ *
+ * @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;
 /**
  * Minimum acceptable secret length in bytes for HMAC / signing material in
  * production (boot guard). Matches the OWASP "Secret Management"

package/dist/security.js

@@ -8,7 +8,7 @@
  * - timingSafeEqual: length-independent string compare for fixed-length token checks.
  * - randomId: cryptographically strong request id.
  */
-import { PayloadTooLargeError, BadRequestError, } from "./errors.js";
+import { PayloadTooLargeError, BadRequestError, RequestHeaderFieldsTooLargeError, } from "./errors.js";
 // Resolved once at module load. Mirror of `DALOY_REQUEST_RAW_BODY` in
 // app.ts; defined here via the global Symbol registry to avoid an import
 // cycle (app.ts -> security.ts). Adapters attach a pre-validated
@@ -321,6 +321,53 @@ export function assertNoReservedInternalHeaders(headers) {
         }
     });
 }
+/**
+ * Default cap on the number of distinct request header fields accepted
+ * before {@link assertHeaderCountWithinLimit} rejects the request. Chosen to
+ * sit far above any realistic legitimate request (browsers, tracing layers,
+ * and reverse proxies rarely add more than a few dozen headers) yet far
+ * below the thousands-of-headers floods used by header-count amplification
+ * attacks such as the "HTTP/2 Bomb".
+ *
+ * @since 0.38.0
+ */
+export const DEFAULT_MAX_HEADER_COUNT = 100;
+/**
+ * Reject requests that carry more than `limit` distinct header fields.
+ *
+ * This is the runtime-portable, application-tier defence against
+ * header-*count* amplification (the dimension abused by the "HTTP/2 Bomb",
+ * where per-entry server bookkeeping — not header size — is the amplifier).
+ * It complements, and does not replace, the native header-count caps that a
+ * runtime/proxy terminating HTTP/2 must apply (NGINX `max_headers`, Node
+ * `server.maxHeadersCount`, etc.). Because the WHATWG `Headers` collection
+ * coalesces same-named fields, the count is over distinct header names —
+ * the truest signal available once a request has been normalised to a
+ * web-standard `Request`.
+ *
+ * A `limit` of `0` (or any non-positive / non-finite value) disables the
+ * check. Throws {@link RequestHeaderFieldsTooLargeError} (`431`) so the
+ * framework returns a structured `problem+json` response instead of routing
+ * a flood.
+ *
+ * @param headers - The incoming request headers.
+ * @param limit - Maximum distinct header fields to allow. `0` disables.
+ * @since 0.38.0
+ */
+export function assertHeaderCountWithinLimit(headers, limit) {
+    if (!(limit > 0) || !Number.isFinite(limit))
+        return;
+    let count = 0;
+    // Count via forEach (not keys()) so a same-named coalesced field counts
+    // once and the check works on any Headers-shaped object. Throwing from the
+    // callback bails the instant the cap is crossed, so a flood pays for at
+    // most `limit + 1` iterations rather than walking the whole set.
+    headers.forEach(() => {
+        if (++count > limit) {
+            throw new RequestHeaderFieldsTooLargeError(limit);
+        }
+    });
+}
 /**
  * Minimum acceptable secret length in bytes for HMAC / signing material in
  * production (boot guard). Matches the OWASP "Secret Management"

package/dist/session.js

@@ -57,7 +57,10 @@ function bytesToBase64Url(bytes) {
 }
 function makeSigner(secret) {
     if (typeof secret !== "string" || secret.length < 16) {
-        throw new Error("session(): each secret must be a string of at least 16 characters.");
+        throw new Error("session(): each secret must be a string of at least 16 characters — it is the HMAC key " +
+            "that signs every session cookie, so a short or guessable value lets an attacker forge sessions. " +
+            "Generate one with `openssl rand -base64 32` and load it from an env var or secret manager " +
+            "(never hard-code or commit it). See https://daloyjs.dev/docs/security/session.");
     }
     let keyPromise = null;
     const getKey = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "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.",
   "type": "module",
   "publishConfig": {
@@ -229,6 +229,7 @@
   "devDependencies": {
     "@hey-api/openapi-ts": "^0.97.1",
     "@types/node": "^25.7.0",
+    "fast-check": "^3.23.2",
     "prettier": "^3.8.3",
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
@@ -242,7 +243,7 @@
     "test": "node --import tsx --test tests/**/*.test.ts",
     "coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-lines=90 --test-coverage-functions=90 tests/**/*.test.ts",
     "coverage:branches": "tsc -p tsconfig.coverage.json && node --test --experimental-test-coverage --test-coverage-include='dist-coverage/src/**' --test-coverage-branches=92 dist-coverage/tests/**/*.test.js",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.typetest.json",
     "format": "prettier --write .",
     "gen:openapi": "node --import tsx scripts/dump-openapi.ts",
     "gen:client": "openapi-ts",
@@ -261,6 +262,7 @@
     "verify:no-leaked-credentials": "node --import tsx scripts/verify-no-leaked-credentials.ts",
     "verify:no-leaky-agent-skills": "node --import tsx scripts/verify-no-leaky-agent-skills.ts",
     "verify:no-toxic-agent-skills": "node --import tsx scripts/verify-no-toxic-agent-skills.ts",
+    "verify:no-agent-config-autorun": "node --import tsx scripts/verify-no-agent-config-autorun.ts",
     "verify:no-invisible-unicode": "node --import tsx scripts/verify-no-invisible-unicode.ts",
     "verify:no-encoded-payloads": "node --import tsx scripts/verify-no-encoded-payloads.ts",
     "verify:no-registry-exfiltration": "node --import tsx scripts/verify-no-registry-exfiltration.ts",