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

package/README.md

@@ -28,11 +28,21 @@ Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yello
 
 DaloyJS is maintained in the GitHub organization at <https://github.com/daloyjs>; the canonical framework repository is <https://github.com/daloyjs/daloy>.
 
-## Partners
+## Acknowledgements
 
-<a href="https://snyk.io">
-  <img src="https://github.com/user-attachments/assets/da58db43-67cc-45d4-ade5-bdaa7b041465" alt="Snyk's Secure Developer Program" width="160">
-</a>
+We are grateful to the following companies for supporting DaloyJS with free access to their tools and services.
+
+<div align="center" style="background-color: #f5f5f5; padding: 25px; border-radius: 10px; margin: 20px 0;">
+
+<a href="https://snyk.io"><img src="https://github.com/user-attachments/assets/da58db43-67cc-45d4-ade5-bdaa7b041465" height="75" width="auto" alt="Snyk"></a>
+   
+<a href="https://socket.dev"><img src="https://github.com/user-attachments/assets/7d2dde1f-6b60-4f20-b05b-80ace5ae6862" height="75" width="auto" alt="Socket"></a>
+   
+<a href="https://www.aikido.dev"><img src="https://github.com/user-attachments/assets/67e62dd1-b907-4246-a0aa-95ef13fa491c" height="75" width="auto" alt="Aikido"></a>
+   
+<a href="https://www.coderabbit.ai"><img src="https://github.com/user-attachments/assets/0d9d8e68-eb21-41ec-978c-337b66ee34b6" height="75" width="auto" alt="CodeRabbit"></a>
+
+</div>
 
 ---
 
@@ -66,7 +76,7 @@ DaloyJS exists to be the framework you'd build if you took the best ideas from e
 | **Portable supply-chain hardening** for the apps you build | [pnpm](https://pnpm.io/motivation) defaults + a zero-runtime-dep core | Hardened `.npmrc`, source-verified lockfiles, zero runtime deps, CycloneDX + SPDX SBOM, and npm provenance attestations.                                                                                  |
 
 ```
-framework test suite passing · ≥90% line + function coverage / ≥90% branch coverage · typechecks on TypeScript 7 with `strict: true`
+framework test suite passing · ≥90% line + function coverage / ≥92% branch coverage · typechecks on TypeScript 7 with `strict: true`
 runs on Node, Bun, Deno, Cloudflare, Vercel
 ~12.3M static-route ops/sec · ~1.5M dynamic-route ops/sec on M-class CPU
 ```
@@ -196,7 +206,7 @@ app.get(
   async ({ params }) => ({
     status: 200,
     body: { id: params.id, title: `Book ${params.id}` },
-  }),
+  })
 );
 
 serve(app, { port: 3000 });
@@ -529,7 +539,7 @@ const usersPlugin = {
         operationId: "me",
         responses: { 200: { description: "ok" } },
       },
-      async () => ({ status: 200, body: { user: "alice" } }),
+      async () => ({ status: 200, body: { user: "alice" } })
     );
   },
 };
@@ -574,9 +584,9 @@ The core only ever sees `Request → Response`. Adapters live at the edge.
 
 ## Status
 
-DaloyJS is at **`1.0.0-rc.5`**, a security-hardening release candidate. Because the framework has no external users yet, this RC makes a few intentional changes (see the [CHANGELOG](CHANGELOG.md)) to get the secure-by-default posture right before the stable release rather than deferring them; the generated OpenAPI contract is unchanged. From `1.0.0` stable onward, the API follows SemVer with deprecations getting at least one minor cycle. The framework is already in use for production trials.
+DaloyJS is at **`1.0.0-rc.6`**, a security-hardening release candidate carrying the remediations from a live over-the-wire engagement against a realistic multi-tenant app — cross-principal response-cache disclosure (`SECURITY-AUDIT.md` F-4 … F-9), SQLi signature evasions in `waf()`, and an unbounded WebSocket frame buffer. Because the framework has no external users yet, this RC makes a few intentional changes (see the [CHANGELOG](CHANGELOG.md)) to get the secure-by-default posture right before the stable release rather than deferring them; the generated OpenAPI contract is unchanged. From `1.0.0` stable onward, the API follows SemVer with deprecations getting at least one minor cycle. The framework is already in use for production trials.
 
-**Release quality bar.** Every release ships with **≥90% line + function coverage and ≥90% branch coverage**, strict TypeScript, OpenSSF Scorecard, CodeQL + Opengrep dual SAST, zizmor workflow linting, and npm provenance. Coverage was relaxed from a former 100% gate so complex security work isn't blocked chasing throwaway tests for unreachable defensive branches or tsx source-map phantoms; see [AGENTS.md](AGENTS.md) for the policy.
+**Release quality bar.** Every release ships with **≥90% line + function coverage** (`pnpm coverage`) **and ≥92% branch coverage** (`pnpm coverage:branches` on compiled JS), strict TypeScript, OpenSSF Scorecard, CodeQL + Opengrep dual SAST, zizmor workflow linting, and npm provenance. Coverage was relaxed from a former 100% gate so complex security work isn't blocked chasing throwaway tests for unreachable defensive branches or tsx source-map phantoms; see [AGENTS.md](AGENTS.md) for the policy.
 
 ### Routing, validation, and docs
 
@@ -646,11 +656,11 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `requireScopes()` with RFC-6750 `WWW-Authenticate: Bearer` challenge and per-request scope aggregation.
 - `session()` with signed cookies and pluggable stores.
 - `idempotency()` with `Idempotency-Key` fingerprinting + byte-for-byte response replay, in-flight `409`, `422` on key reuse with a different payload, and a pluggable `IdempotencyStore` (in-memory default) at `@daloyjs/core/idempotency`.
-- `responseCache()` server-side body cache (cache-key + TTL with `s-maxage`/`max-age` orchestration, request `no-store`/`no-cache` directives, recursion-safe stale-while-revalidate, `Vary`-aware keying, `X-Cache` HIT/MISS/STALE marker, pluggable `ResponseCacheStore` in-memory default) at `@daloyjs/core/response-cache`. Never caches `Set-Cookie` or `private`/`no-store`/`no-cache` responses. Complements `etag()`/`compression()`, which do not cache bodies.
+- `responseCache()` server-side body cache (cache-key + TTL with `s-maxage`/`max-age` orchestration, request `no-store`/`no-cache` directives, recursion-safe stale-while-revalidate, proactive `varyHeaders` keying, `X-Cache` HIT/MISS/STALE marker, pluggable `ResponseCacheStore` whose in-memory default is bounded on both entry count and retained bytes) at `@daloyjs/core/response-cache`. Never caches `Set-Cookie`, `private`/`no-store`/`no-cache`, or `Vary: *` responses, and strips `Age`/hop-by-hop/`X-Request-Id` from stored entries so a hit never replays another request's correlation id. **Fail-closed on every principal dimension (CWE-524):** the key is the full _effective request URI_ including the authority (RFC 9111 §4), so hostnames never share entries; requests carrying `Authorization` **or** `Cookie` bypass the shared cache unless a `principal` names the caller (then each gets its own entry) or the header is explicitly declared shareable; a tenant resolved by `tenancy()` is folded into the key automatically — with a boot guard that refuses to start if the cache is mounted ahead of `tenancy()`; and the response's **own `Vary` header** is honoured as a secondary key (RFC 9111 §4.1), so the `Vary: Origin` written by `cors()` and the `Vary: Accept-Encoding` written by `compression()` keep one caller's allowed origin — or their gzipped bytes — from being served to the next, with each variant stored separately so they all stay warm. Complements `etag()`/`compression()`, which do not cache bodies.
 - `paginationQuery()` / `encodeCursor()` / `decodeCursor()` / `buildPageLinks()` / `buildLinkHeader()` cursor-pagination helpers at `@daloyjs/core/pagination`: opaque base64url cursors (length-capped, prototype-pollution-safe decode → `400` on tamper), RFC 8288 `Link` header emission with CRLF / header-injection guards, and a Standard Schema that validates `cursor`/`limit` and auto-wires both into the OpenAPI spec + typed client via `toJSONSchema()`.
 - `app.metrics()` + `MetricsRegistry` / `httpMetrics()` Prometheus / OpenMetrics exposition at `@daloyjs/core/metrics`: dependency-free counters / gauges / histograms, RED instrumentation (`http_requests_total`, `http_request_duration_seconds`, `http_requests_in_flight`) plus process gauges, exposition-injection-safe name/label validation, a per-metric cardinality cap, and an opt-in `/metrics` route with the same hardened posture as `app.healthcheck()` (bearer token + `timingSafeEqual`, per-IP rate limit, refuse-to-boot unauthenticated in production). The repo ships an `examples/observability/` Docker Compose stack that starts a pre-configured Prometheus + Grafana pair (with an auto-provisioned RED + heatmap dashboard) against any local app via `docker compose -f examples/observability/docker-compose.yml up`.
 - `otelTracing()` OpenTelemetry-compatible distributed tracing at `@daloyjs/core/tracing`: a dependency-free `Hooks` bundle that opens one `SERVER` span per request, attaches HTTP semantic-convention attributes (`http.request.method`, `url.path`, `server.address` / `server.port`, `http.response.status_code`, …), records exceptions + escalates `5xx` to `ERROR`, guarantees a single `span.end()`, and exposes the live span on `ctx.state.otelSpan`. Bring any tracer matching the small `TracingTracer` interface (the real `@opentelemetry/api` SDK on Node, or a custom exporter on Workers/Deno) plus your own propagator via `contextFromRequest` for `traceparent` continuation — no OTel SDK is forced into your install. The `examples/observability/` stack also runs **Jaeger**, and `examples/otel-tracing-demo.ts` ships a ~120-line dependency-free OTLP/HTTP exporter that streams spans straight to it.
-- `tenancy()` secure-by-default multitenancy at `@daloyjs/core/tenancy`: a dependency-free `Hooks` bundle that resolves the calling tenant once per request and exposes it on `ctx.state.tenant`. Pluggable resolution (`tenantFromSubdomain` PSL-aware, `tenantFromHeader`, `tenantFromPathPrefix`, `tenantFromClaim`, or a custom `(ctx) => string`, tried in array order). **Refuse-unresolved by default** (no ambient "default" tenant leak), **format-validated ids** (rejects key/log-injection + cache-poisoning payloads before they reach a key), **no-enumeration `404`** for unknown tenants, and **host-spoof-safe** subdomain resolution. A `tenantScope()` key helper drops straight into `rateLimit` `keyGenerator` and `concurrencyLimit` / `idempotency` / `responseCache` `scope` to partition each per tenant (CWE-524 cross-tenant cache defense). Runnable `examples/multitenancy-demo.ts`.
+- `tenancy()` secure-by-default multitenancy at `@daloyjs/core/tenancy`: a dependency-free `Hooks` bundle that resolves the calling tenant once per request and exposes it on `ctx.state.tenant`. Pluggable resolution (`tenantFromSubdomain` PSL-aware, `tenantFromHeader`, `tenantFromPathPrefix`, `tenantFromClaim`, or a custom `(ctx) => string`, tried in array order). **Refuse-unresolved by default** (no ambient "default" tenant leak), **format-validated ids** (rejects key/log-injection + cache-poisoning payloads before they reach a key), **no-enumeration `404`** for unknown tenants, and **host-spoof-safe** subdomain resolution. A `tenantScope()` key helper drops straight into `rateLimit` `keyGenerator` and `concurrencyLimit` / `idempotency` `scope` to partition each per tenant (CWE-524 cross-tenant cache defense); `responseCache()` needs no wiring at all — it reads the resolved tenant itself and refuses to boot if mounted ahead of `tenancy()`. Runnable `examples/multitenancy-demo.ts`.
 - `resilientFetch()` + `CircuitBreaker` outbound resilience at `@daloyjs/core/fetch-resilience`: a dependency-free circuit breaker (`closed → open → half-open`), retry-with-backoff (exponential + full jitter, idempotent-method/transient-status scoped, honours `Retry-After`), and a per-call timeout (`AbortController` → `FetchTimeoutError`) designed to layer **on top of** `fetchGuard()` — an `SsrfBlockedError` is a terminal refusal that is never retried and never trips the breaker, so SSRF protection stays intact under the resilience layer.
 - `createWebhookSender()` + `MemoryWebhookDeadLetterSink` outbound webhook delivery at `@daloyjs/core/webhook-delivery`: the outbound counterpart to `verifyWebhookSignature()` — timestamped HMAC-signed `POST`s (`webhook-id` / `webhook-timestamp` / `webhook-signature`, computed over `"<timestamp>.<body>"` and reused across retries for safe deduping), bounded retry-with-backoff (transient-status + network scoped, honours `Retry-After`), per-attempt timeout, and dead-letter semantics. Transport defaults to `fetchGuard()`, so a subscriber URL pointing at cloud metadata or a private range is refused with a terminal `SsrfBlockedError` (never retried, dead-lettered once). Zero runtime dependencies.
 - `app.cron()` + standalone `Scheduler` in-process scheduled tasks at `@daloyjs/core/scheduler`: a queue-agnostic schedule primitive for periodic housekeeping (cache sweeps, token refresh, reconciliation). Fixed intervals or 5-field cron expressions (lists / ranges / steps / named months & days / `@hourly`–`@yearly` aliases / optional IANA `timeZone`), arithmetic cron parsing (no backtracking regex), fixed-rate **single-flight** (overlapping ticks are skipped, never run concurrently), per-run `timeoutMs` with `AbortSignal`, and graceful-shutdown integration (stop arming → await in-flight → abort after grace). Timers are `unref`'d. `parseCron()` / `nextCronRun()` exported standalone. Zero runtime dependencies.
@@ -697,7 +707,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - Adapter-independent `ConnInfo` abstraction: `getConnInfo()`, lazy `ctx.remoteAddress`, `ctx.remotePort` — populated by the Node, Bun, Deno, and Lambda adapters from the real peer socket / event source, never from spoofable headers.
 - `daloy doctor` production-posture validator with `--audit-secrets` and `--audit-defaults` (flags wildcard-credentials CORS, > 24h CORS `maxAge`, > 25 MiB blanket body limits, zero `idleTimeoutMs` in production, and unsafe opt-ins).
 - PSL-aware `subdomains()` helper with a `≤ 90 days` snapshot guard.
-- Secure-by-default multitenancy via `tenancy()` + `tenantScope()`: pluggable tenant resolution (subdomain / header / path / JWT claim / custom), refuse-unresolved + format-validated ids + no-enumeration `404` by default, and a key helper that partitions `rateLimit` / `concurrencyLimit` / `idempotency` / `responseCache` per tenant.
+- Secure-by-default multitenancy via `tenancy()` + `tenantScope()`: pluggable tenant resolution (subdomain / header / path / JWT claim / custom), refuse-unresolved + format-validated ids + no-enumeration `404` by default, a key helper that partitions `rateLimit` / `concurrencyLimit` / `idempotency` per tenant, and automatic per-tenant `responseCache` partitioning backed by a boot guard.
 - `defineDependency()` typed-DI helper with per-request deduplication.
 - Scheme-aware `ctx.state.auth` typed contract; named, optionally seeded stateful plugins.
 

package/dist/adapters/bun.js

@@ -273,8 +273,7 @@ function reportBunHandlerFailure(app, data, label, err, notifyError) {
     }
 }
 function validateControlPayload(data) {
-    if (data !== undefined &&
-        encodeSendPayload(data).payload.length > WS_MAX_CONTROL_PAYLOAD) {
+    if (data !== undefined && encodeSendPayload(data).payload.length > WS_MAX_CONTROL_PAYLOAD) {
         throw new WebSocketProtocolError("Control frame payload exceeds 125 bytes");
     }
 }

package/dist/adapters/node.js

@@ -2,7 +2,7 @@
  * Node adapter: translates IncomingMessage/ServerResponse to web-standard
  * Request/Response. Includes graceful shutdown wired to SIGTERM/SIGINT.
  */
-import { createServer, } from "node:http";
+import { createServer } from "node:http";
 import { Readable } from "node:stream";
 import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, DALOY_REQUEST_ABORT, } from "../app.js";
 import { BadRequestError } from "../errors.js";
@@ -74,9 +74,7 @@ export function serve(app, opts = {}) {
     // `0` opts out and restores Node's unbounded-ish default (2000).
     const maxHeaderCount = opts.maxHeaderCount;
     server.maxHeadersCount =
-        typeof maxHeaderCount === "number" && maxHeaderCount >= 0
-            ? maxHeaderCount
-            : 100;
+        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) {
@@ -125,7 +123,10 @@ export function serve(app, opts = {}) {
         await new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
     };
     if (opts.handleSignals !== false) {
-        const onSignal = (sig) => { app.log.info({ sig }, "DaloyJS received signal, shutting down"); void close().then(() => process.exit(0)); };
+        const onSignal = (sig) => {
+            app.log.info({ sig }, "DaloyJS received signal, shutting down");
+            void close().then(() => process.exit(0));
+        };
         process.once("SIGTERM", () => onSignal("SIGTERM"));
         process.once("SIGINT", () => onSignal("SIGINT"));
     }
@@ -133,9 +134,7 @@ export function serve(app, opts = {}) {
         server,
         get port() {
             const address = server.address();
-            return address !== null && typeof address === "object"
-                ? address.port
-                : requestedPort;
+            return address !== null && typeof address === "object" ? address.port : requestedPort;
         },
         close,
     };
@@ -280,11 +279,7 @@ function attachClientCertificate(req, request) {
  * Node's `connect` event rather than the request listener; it is included here
  * defensively for runtimes/proxies that surface it as a normal request.)
  */
-const FETCH_FORBIDDEN_METHODS = new Set([
-    "CONNECT",
-    "TRACE",
-    "TRACK",
-]);
+const FETCH_FORBIDDEN_METHODS = new Set(["CONNECT", "TRACE", "TRACK"]);
 /**
  * Refuse a Fetch-forbidden HTTP method with a spec-correct `501 Not
  * Implemented`. `501` is more accurate than `405` here because the method is
@@ -544,15 +539,10 @@ Object.setPrototypeOf(LightRequest.prototype, Request.prototype);
 LightRequest.prototype[DALOY_LIGHT_RESPONSE_OK] = true;
 function toWebRequest(req, trustProxy, bufferedBody) {
     const reqHeaders = req.headers;
-    const forwardedHost = trustProxy
-        ? firstHeader(reqHeaders["x-forwarded-host"])
-        : undefined;
+    const forwardedHost = trustProxy ? firstHeader(reqHeaders["x-forwarded-host"]) : undefined;
     const host = forwardedHost ?? reqHeaders.host ?? "localhost";
-    const forwardedProto = trustProxy
-        ? firstHeader(reqHeaders["x-forwarded-proto"])
-        : undefined;
-    const proto = forwardedProto ??
-        (req.socket.encrypted ? "https" : "http");
+    const forwardedProto = trustProxy ? firstHeader(reqHeaders["x-forwarded-proto"]) : undefined;
+    const proto = forwardedProto ?? (req.socket.encrypted ? "https" : "http");
     const url = `${proto}://${host}${normalizeRequestTarget(req.url)}`;
     // Reject malformed Host / request-target combinations at the adapter
     // boundary instead of letting the invalid URL propagate as a 500 later.
@@ -667,7 +657,8 @@ function sendWebResponse(res, out) {
     // which we must strip so Node falls back to chunked transfer-encoding.
     const rawStream = res[DALOY_RAW_STREAM];
     if (rawStream !== undefined) {
-        if (typeof rawStream.pipe === "function" && !(rawStream instanceof ReadableStream)) {
+        if (typeof rawStream.pipe === "function" &&
+            !(rawStream instanceof ReadableStream)) {
             // Node `Readable` from the handler: skip the Web-stream bridge entirely
             // and `.pipe(out)` like Fastify/Koa/Express do.
             out.removeHeader("content-length");
@@ -721,15 +712,10 @@ function pumpBody(body, out) {
 }
 // ---------- WebSocket upgrade ----------
 async function handleUpgrade(app, req, socket, head, trustProxy) {
-    const forwardedHost = trustProxy
-        ? firstHeader(req.headers["x-forwarded-host"])
-        : undefined;
+    const forwardedHost = trustProxy ? firstHeader(req.headers["x-forwarded-host"]) : undefined;
     const host = forwardedHost ?? req.headers.host ?? "localhost";
-    const forwardedProto = trustProxy
-        ? firstHeader(req.headers["x-forwarded-proto"])
-        : undefined;
-    const proto = forwardedProto ??
-        (req.socket.encrypted ? "https" : "http");
+    const forwardedProto = trustProxy ? firstHeader(req.headers["x-forwarded-proto"]) : undefined;
+    const proto = forwardedProto ?? (req.socket.encrypted ? "https" : "http");
     // A malformed `Host` header (e.g. containing a space) reaches this point:
     // Node's HTTP parser accepts it and fires `upgrade`, but WHATWG URL
     // parsing throws. Reject it as the client error it is instead of letting

package/dist/app.d.ts

@@ -1176,7 +1176,11 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *    auth hook unless it opted out with `mcpRoutes(path, handler, { public: true })`.
      *    MCP tools are model-controlled and side-effecting, so a public one is a
      *    high-impact default.
-     * 3. **Missing CSRF** — when `session()` is installed and any route accepts a
+     * 3. **Cache ahead of tenancy** — a `responseCache()` that runs before
+     *    `tenancy()` builds its key before the tenant exists in `ctx.state`, so
+     *    every tenant collides on one entry and one tenant's response is served to
+     *    the next caller (CWE-524).
+     * 4. **Missing CSRF** — when `session()` is installed and any route accepts a
      *    state-changing method (`POST`/`PUT`/`PATCH`/`DELETE`), a `csrf()` hook
      *    (or third-party equivalent stamped with {@link CSRF_HOOK_MARKER}) must
      *    also be present. Skipped when `app({ csrf: "off" })`.

package/dist/app.js

@@ -127,6 +127,15 @@ const CANONICAL_HTTP_METHODS = new Set([
  * `App` bundle. Must match the string used in `mcpRoutes`.
  */
 const MCP_ROUTE_MARKER = Symbol.for("daloyjs.mcp.route");
+/**
+ * Global-registry symbols stamped by `responseCache()` and `tenancy()` on the
+ * `Hooks` bundles they return. Read here — rather than imported from
+ * `response-cache.ts` / `tenancy.ts` — so neither module is pulled into the core
+ * `App` bundle (which would cost every serverless cold start). Must match the
+ * strings used in those modules.
+ */
+const RESPONSE_CACHE_HOOK_MARKER = Symbol.for("daloyjs.response-cache.hook");
+const TENANCY_HOOK_MARKER = Symbol.for("daloyjs.tenancy.hook");
 /**
  * Apply a topology-aware security preset on top of caller-supplied
  * options. Returns a new options object where preset defaults fill in
@@ -949,7 +958,11 @@ export class App {
      *    auth hook unless it opted out with `mcpRoutes(path, handler, { public: true })`.
      *    MCP tools are model-controlled and side-effecting, so a public one is a
      *    high-impact default.
-     * 3. **Missing CSRF** — when `session()` is installed and any route accepts a
+     * 3. **Cache ahead of tenancy** — a `responseCache()` that runs before
+     *    `tenancy()` builds its key before the tenant exists in `ctx.state`, so
+     *    every tenant collides on one entry and one tenant's response is served to
+     *    the next caller (CWE-524).
+     * 4. **Missing CSRF** — when `session()` is installed and any route accepts a
      *    state-changing method (`POST`/`PUT`/`PATCH`/`DELETE`), a `csrf()` hook
      *    (or third-party equivalent stamped with {@link CSRF_HOOK_MARKER}) must
      *    also be present. Skipped when `app({ csrf: "off" })`.
@@ -998,7 +1011,24 @@ export class App {
             this.bootGuard.error = err;
             throw err;
         }
-        // Guard 3: session() + state-changing route without csrf().
+        // Guard 3: responseCache() mounted ahead of tenancy(). The cache partitions
+        // on the tenant automatically, but only if the tenant is already in
+        // ctx.state when the key is built. Mounted first, it would key every
+        // tenant's response identically and serve one tenant's private body to the
+        // next caller (CWE-524) — silently, with a normal-looking cache HIT.
+        const cacheBeforeTenancy = this.routeSecurityMarkers.find((r) => r.cacheBeforeTenancy);
+        if (cacheBeforeTenancy) {
+            const err = new Error(`Route ${cacheBeforeTenancy.method} ${cacheBeforeTenancy.path} runs responseCache() ` +
+                `before tenancy() in its effective hook chain. The cache key is built before the tenant ` +
+                `is resolved, so every tenant would share one cache entry and one tenant's response ` +
+                `would be served to the next caller (CWE-524 cross-tenant cached-response disclosure). ` +
+                `Register tenancy() first — as a global hook (new App({ hooks: tenancy(...) })) or an ` +
+                `earlier app.use(...) — so the tenant is in ctx.state before the cache reads it. ` +
+                `See https://daloyjs.dev/docs/security/boot-guards.`);
+            this.bootGuard.error = err;
+            throw err;
+        }
+        // Guard 4: session() + state-changing route without csrf().
         if (this.options.csrf === "off")
             return;
         const stateChanging = this.routeSecurityMarkers.find((r) => isStateChangingMethod(r.method) && r.hasSession && !r.hasCsrf);
@@ -1068,13 +1098,21 @@ export class App {
             this.trustProxyWarned = true;
             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. ` +
+        const refusal = 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. ` +
             `See https://daloyjs.dev/docs/security/boot-guards.`);
+        // Every refused request throws from this one line, so the stack is
+        // identical each time and names framework internals rather than anything
+        // an operator can act on. Keep the 500 and keep a line per request — the
+        // refusal must stay visible — but drop the stack, so a client cannot
+        // multiply the bytes it pushes into the error tier by replaying the header.
+        // The actionable message is logged once per process by the warn above.
+        refusal[OMIT_STACK_IN_LOG] = true;
+        throw refusal;
     }
     /**
      * Resolve the {@link AppOptions.docs} option and, when enabled, register
@@ -3143,16 +3181,29 @@ function securityMarkersFromHooks(layers) {
     let hasSession = false;
     let hasCsrf = false;
     let hasAuth = false;
-    for (const hooks of layers) {
-        const record = hooks;
+    // `layers` is in execution order, so the first index of each marker is enough
+    // to tell whether the cache reads state before tenancy has written it.
+    let cacheIndex = -1;
+    let tenancyIndex = -1;
+    for (let i = 0; i < layers.length; i++) {
+        const record = layers[i];
         if (record[SESSION_HOOK_MARKER] === true)
             hasSession = true;
         if (record[CSRF_HOOK_MARKER] === true)
             hasCsrf = true;
         if (record[AUTH_HOOK_MARKER] === true)
             hasAuth = true;
+        if (cacheIndex === -1 && record[RESPONSE_CACHE_HOOK_MARKER] === true)
+            cacheIndex = i;
+        if (tenancyIndex === -1 && record[TENANCY_HOOK_MARKER] === true)
+            tenancyIndex = i;
     }
-    return { hasSession, hasCsrf, hasAuth };
+    return {
+        hasSession,
+        hasCsrf,
+        hasAuth,
+        cacheBeforeTenancy: cacheIndex !== -1 && tenancyIndex !== -1 && cacheIndex < tenancyIndex,
+    };
 }
 function isStateChangingMethod(method) {
     return method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
@@ -4079,8 +4130,25 @@ function withTimeout(p, ms, request) {
         });
     });
 }
+/**
+ * Marker set on an error whose stack carries no incident information because
+ * the same framework line throws it for every offending request — a rejected
+ * *configuration* or *request shape*, not a fault in the app's code.
+ *
+ * `serializeErr` omits the stack for these. The stack is byte-identical on every
+ * occurrence and points at framework internals, so logging it per request just
+ * multiplies the volume an unauthenticated client can push into the error tier
+ * (the expensive, alerting one) without telling an operator anything the
+ * message does not already say.
+ *
+ * @internal
+ */
+const OMIT_STACK_IN_LOG = Symbol.for("daloyjs.error.omitStackInLog");
 function serializeErr(err) {
     if (err instanceof Error) {
+        if (err[OMIT_STACK_IN_LOG] === true) {
+            return { name: err.name, message: err.message };
+        }
         return { name: err.name, message: err.message, stack: err.stack };
     }
     return { value: String(err) };

package/dist/auto-ban.js

@@ -207,9 +207,7 @@ export function autoBan(opts = {}) {
             opts.onStrike?.({ key, strikes, status: res.status });
             if (strikes >= maxStrikes) {
                 banCount += 1;
-                const duration = escalate
-                    ? Math.min(maxBanMs, banMs * 2 ** (banCount - 1))
-                    : banMs;
+                const duration = escalate ? Math.min(maxBanMs, banMs * 2 ** (banCount - 1)) : banMs;
                 bannedUntilMs = now + duration;
                 strikes = 0;
                 opts.onBan?.({ key, banCount, banDurationMs: duration, bannedUntilMs });

package/dist/cli.js

@@ -274,7 +274,11 @@ export function parseArgs(argv) {
     };
     let command = "inspect";
     let i = 0;
-    if (argv[0] === "inspect" || argv[0] === "dev" || argv[0] === "help" || argv[0] === "doctor" || argv[0] === "diff") {
+    if (argv[0] === "inspect" ||
+        argv[0] === "dev" ||
+        argv[0] === "help" ||
+        argv[0] === "doctor" ||
+        argv[0] === "diff") {
         command = argv[0];
         i = 1;
     }
@@ -593,7 +597,8 @@ async function runDoctor(opts, io) {
     const o = app.options;
     const isProd = o.env === "production" ||
         o.production === true ||
-        globalThis.process?.env?.NODE_ENV === "production";
+        globalThis.process?.env?.NODE_ENV ===
+            "production";
     if (opts.noAuditDefaults !== true) {
         if (isProd && o.trustProxy === undefined && o.behindProxy === undefined) {
             findings.push({
@@ -907,10 +912,8 @@ export function buildAiDump(app, opts) {
             method: def.method,
             path: def.path,
             ...(def.operationId ? { operationId: def.operationId } : {}),
-            ...(def.summary ?? meta?.summary
-                ? { summary: def.summary ?? meta?.summary }
-                : {}),
-            ...(def.description ?? meta?.description
+            ...((def.summary ?? meta?.summary) ? { summary: def.summary ?? meta?.summary } : {}),
+            ...((def.description ?? meta?.description)
                 ? { description: def.description ?? meta?.description }
                 : {}),
             tags: dedupeTags(def.tags, meta?.tags),

package/dist/config.js

@@ -24,9 +24,7 @@ export class ConfigValidationError extends Error {
     /** Every validation issue, as `{ key, message }` pairs (`key` is the dotted path, `"<root>"`/`"<source>"` for top-level failures). */
     issues;
     constructor(issues) {
-        const summary = issues
-            .map((i) => `  - ${i.key || "<root>"}: ${i.message}`)
-            .join("\n");
+        const summary = issues.map((i) => `  - ${i.key || "<root>"}: ${i.message}`).join("\n");
         super(`defineConfig(): configuration is invalid (${issues.length} issue${issues.length === 1 ? "" : "s"})\n${summary}`);
         this.name = "ConfigValidationError";
         this.issues = issues;

package/dist/errors.js

@@ -40,9 +40,7 @@ export class MessageLeakError extends Error {
     /** The refused headers, each with its name and the reason it was disallowed. */
     offendingHeaders;
     constructor(offendingHeaders) {
-        const summary = offendingHeaders
-            .map((h) => `${h.name} (${h.reason})`)
-            .join(", ");
+        const summary = offendingHeaders.map((h) => `${h.name} (${h.reason})`).join(", ");
         super(`httpError({ res }): custom error response carries disallowed header(s): ${summary}. ` +
             "Only WWW-Authenticate, Proxy-Authenticate, Retry-After, Content-Type, " +
             "Content-Language, Content-Length, and Cache-Control (no-store|no-cache) " +
@@ -212,8 +210,7 @@ export class HttpError extends Error {
      * @returns A `Response` with `Content-Type: application/problem+json`.
      */
     toResponse(opts = {}) {
-        const isProd = opts.production ??
-            (typeof process !== "undefined" && process.env?.NODE_ENV === "production");
+        const isProd = opts.production ?? (typeof process !== "undefined" && process.env?.NODE_ENV === "production");
         const out = { ...this.problem };
         if (isProd && this.status >= 500) {
             delete out.detail; // do not leak internals

package/dist/etag.js

@@ -38,7 +38,10 @@ async function sha1Hex(bytes) {
 }
 function inmMatches(headerValue, candidate) {
     // RFC 7232 §3.2: comma-separated list of entity tags or `*`.
-    const list = headerValue.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    const list = headerValue
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
     if (list.length === 0)
         return false;
     for (const tag of list) {
@@ -97,7 +100,14 @@ export function etag(opts = {}) {
             const inm = ctx?.request?.headers.get("if-none-match");
             if (inm && inmMatches(inm, value)) {
                 const stripped = new Headers();
-                for (const allow of ["cache-control", "content-location", "date", "etag", "expires", "vary"]) {
+                for (const allow of [
+                    "cache-control",
+                    "content-location",
+                    "date",
+                    "etag",
+                    "expires",
+                    "vary",
+                ]) {
                     const v = headers.get(allow);
                     if (v !== null)
                         stripped.set(allow, v);

package/dist/geo-block.js

@@ -90,12 +90,10 @@ export function geoBlock(opts) {
     const hasLookup = typeof opts.lookupCountry === "function";
     const hasResolve = typeof opts.resolveCountry === "function";
     if (hasLookup === hasResolve) {
-        throw new Error('geoBlock(): exactly one of "lookupCountry" or "resolveCountry" must ' +
-            "be provided.");
+        throw new Error('geoBlock(): exactly one of "lookupCountry" or "resolveCountry" must ' + "be provided.");
     }
     if (opts.mode !== undefined && opts.mode !== "block" && opts.mode !== "log") {
-        throw new Error(`geoBlock(): invalid mode ${JSON.stringify(opts.mode)}; expected ` +
-            '"block" or "log".');
+        throw new Error(`geoBlock(): invalid mode ${JSON.stringify(opts.mode)}; expected ` + '"block" or "log".');
     }
     const allow = new Set((opts.allow ?? []).map(normalizeConfiguredCode));
     const deny = new Set((opts.deny ?? []).map(normalizeConfiguredCode));
@@ -107,8 +105,7 @@ export function geoBlock(opts) {
     const onBlock = opts.onBlock;
     const lookupCountry = opts.lookupCountry;
     const resolveCountry = opts.resolveCountry;
-    const resolveIp = opts.resolveIp ??
-        (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
+    const resolveIp = opts.resolveIp ?? (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
     return {
         async beforeHandle(ctx) {
             let ip;
@@ -120,9 +117,7 @@ export function geoBlock(opts) {
                 ip = resolveIp(ctx) ?? undefined;
                 rawCountry = ip ? await lookupCountry(ip) : undefined;
             }
-            const country = rawCountry && rawCountry.trim()
-                ? rawCountry.trim().toUpperCase()
-                : undefined;
+            const country = rawCountry && rawCountry.trim() ? rawCountry.trim().toUpperCase() : undefined;
             let reason;
             if (!country) {
                 if (!allowUnknown)

package/dist/hashing.js

@@ -22,7 +22,7 @@
  *
  * @since 0.15.0
  */
-import { randomBytes, scrypt as scryptCb, timingSafeEqual as nodeTimingSafeEqual } from "node:crypto";
+import { randomBytes, scrypt as scryptCb, timingSafeEqual as nodeTimingSafeEqual, } from "node:crypto";
 // OWASP-aligned scrypt parameters (Password Storage Cheat Sheet, 2024).
 const SCRYPT_N = 1 << 17; // 131072
 const SCRYPT_R = 8;

package/dist/http-signatures.js

@@ -61,8 +61,7 @@ const ENC = new TextEncoder();
 // WebCrypto + encoding helpers
 // ---------------------------------------------------------------------------
 function getCrypto() {
-    const c = globalThis
-        .crypto;
+    const c = globalThis.crypto;
     if (!c?.subtle) {
         throw new Error("http-signatures: WebCrypto SubtleCrypto API is unavailable on this runtime.");
     }
@@ -181,9 +180,7 @@ async function importKey(alg, material, usage) {
         return c.subtle.importKey("raw", material, spec.importParams, false, [usage]);
     }
     if (isJsonWebKey(material)) {
-        const key = await c.subtle.importKey("jwk", material, spec.importParams, false, [
-            usage,
-        ]);
+        const key = await c.subtle.importKey("jwk", material, spec.importParams, false, [usage]);
         assertRsaModulusFloor(alg, key);
         return key;
     }
@@ -686,9 +683,7 @@ export async function verifyMessage(opts) {
         return fail("key_not_found");
     let keyMaterial;
     let pinnedAlg;
-    if (resolved instanceof Uint8Array ||
-        isCryptoKey(resolved) ||
-        isJsonWebKey(resolved)) {
+    if (resolved instanceof Uint8Array || isCryptoKey(resolved) || isJsonWebKey(resolved)) {
         keyMaterial = resolved;
     }
     else {

package/dist/index.d.ts

@@ -89,7 +89,7 @@ export { session, rotateSession, signValue, verifySignedValue, MemorySessionStor
 export type { SessionOptions, SessionCookieOptions, SessionContext, SessionRecord, SessionStore, SessionState, RotateSessionOptions, } from "./session.js";
 export { idempotency, MemoryIdempotencyStore, _resetSharedIdempotencyStoresForTests, } from "./idempotency.js";
 export type { IdempotencyOptions, IdempotencyStore, IdempotencyRecord, StoredIdempotentResponse, } from "./idempotency.js";
-export { responseCache, MemoryResponseCacheStore, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
+export { responseCache, MemoryResponseCacheStore, RESPONSE_CACHE_HOOK_MARKER, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
 export type { ResponseCacheOptions, ResponseCacheStore, CachedResponse } from "./response-cache.js";
 export { encodeCursor, decodeCursor, buildLinkHeader, buildPageLinks, paginationQuery, MAX_CURSOR_LENGTH, } from "./pagination.js";
 export type { PaginationLink, PageLinkOptions, PageLinks, PaginationQueryOptions, PaginationParams, PaginationQuerySchema, } from "./pagination.js";
@@ -99,7 +99,7 @@ export { fileField, multipartObject, isFileFieldSchema, isMultipartObjectSchema,
 export type { FileFieldSchema, FileFieldOptions, FileMagicBytesOption, FileMagicBytesSignature, MultipartObjectOptions, MultipartShape, UploadedFile, } from "./multipart.js";
 export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACING_SPAN_STATUS_OK, TRACING_SPAN_STATUS_ERROR, } from "./tracing.js";
 export type { OtelTracingOptions, TracingAttributes, TracingAttributeValue, TracingSpan, TracingStartSpanOptions, TracingTracer, } from "./tracing.js";
-export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, } from "./tenancy.js";
+export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, TENANCY_HOOK_MARKER, TENANCY_RESOLVED_MARKER, TENANT_UNRESOLVED, } from "./tenancy.js";
 export type { TenancyOptions, TenantResolver, TenantScopeOptions, SubdomainTenantOptions, PathPrefixTenantOptions, ClaimTenantOptions, UnresolvedStatus, InvalidStatus, } from "./tenancy.js";
 export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";
 export type { WebSocketConnection, WebSocketContext, WebSocketHandler, WebSocketMeta, WebSocketRouteEntry, NormalizedWebSocketOptions, WebSocketBeforeUpgrade, HandshakeResult, ParsedFrame, MessageEvent as WebSocketMessageEvent, FrameSinkEvents, } from "./websocket.js";

package/dist/index.js

@@ -45,10 +45,10 @@ export { httpBearerScheme, httpBasicScheme, apiKeyScheme, oauth2Scheme, openIdCo
 export { discriminator, discriminatedUnion } from "./discriminator.js";
 export { session, rotateSession, signValue, verifySignedValue, MemorySessionStore, SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
 export { idempotency, MemoryIdempotencyStore, _resetSharedIdempotencyStoresForTests, } from "./idempotency.js";
-export { responseCache, MemoryResponseCacheStore, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
+export { responseCache, MemoryResponseCacheStore, RESPONSE_CACHE_HOOK_MARKER, _resetSharedResponseCacheStoresForTests, } from "./response-cache.js";
 export { encodeCursor, decodeCursor, buildLinkHeader, buildPageLinks, paginationQuery, MAX_CURSOR_LENGTH, } from "./pagination.js";
 export { MetricsRegistry, Counter, Gauge, Histogram, httpMetrics, DEFAULT_DURATION_BUCKETS, PROMETHEUS_CONTENT_TYPE, } from "./metrics.js";
 export { fileField, multipartObject, isFileFieldSchema, isMultipartObjectSchema, } from "./multipart.js";
 export { otelTracing, TRACING_SPAN_KIND_SERVER, TRACING_SPAN_STATUS_UNSET, TRACING_SPAN_STATUS_OK, TRACING_SPAN_STATUS_ERROR, } from "./tracing.js";
-export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, } from "./tenancy.js";
+export { tenancy, tenantScope, tenantFromSubdomain, tenantFromHeader, tenantFromPathPrefix, tenantFromClaim, defaultTenantNormalize, TENANCY_HOOK_MARKER, TENANCY_RESOLVED_MARKER, TENANT_UNRESOLVED, } from "./tenancy.js";
 export { defineWebSocket, WebSocketRegistry, WebSocketProtocolError, WebSocketPayloadTooLargeError, WS_GUID, WS_READY_STATE, WS_OPCODE, WS_CLOSE_CODE, WS_MAX_CONTROL_PAYLOAD, DEFAULT_WS_BACKPRESSURE_LIMIT, DEFAULT_WS_MAX_PAYLOAD_LENGTH, DEFAULT_WS_IDLE_TIMEOUT_SECONDS, computeAcceptKey, parseSubprotocols, validateSelectedSubprotocol, validateUpgrade, checkWebSocketOrigin, parseFrame, encodeFrame, encodeClosePayload, decodeClosePayload, encodeSendPayload, normalizeWebSocketOptions, wsRateLimit, FrameSink, FRAME_INCOMPLETE, } from "./websocket.js";

package/dist/ip-reputation.js

@@ -46,7 +46,7 @@
  */
 import { ForbiddenError } from "./errors.js";
 import { fetchGuard } from "./fetch-guard.js";
-import { compileCidrMatcher, matchesMatcher, parseIp, } from "./ip-restriction.js";
+import { compileCidrMatcher, matchesMatcher, parseIp } from "./ip-restriction.js";
 const DEFAULT_REFRESH_MS = 60 * 60_000;
 const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
 const DEFAULT_MESSAGE = "IP address not permitted";