@daloyjs/core 0.41.0 → 0.43.0

package/README.md

@@ -516,7 +516,7 @@ DaloyJS is in **public preview** (`0.x`). The public API may still change betwee
 
 - Adapters for Node (Heroku, Railway, Render, Fly.io), Bun, Deno, Cloudflare Workers, Vercel Node / Edge / Next.js / Netlify Edge, Fastly Compute, and AWS Lambda / Netlify Functions / Lambda Function URLs.
 - `daloy dev` watch loop delegates to the host runtime's native watcher (`node --import tsx --watch`, `bun --hot`, or `deno run --watch`) with a `--runtime` override for cross-runtime `package.json` scripts.
-- `pnpm create daloy` scaffolder with Node, Bun, Deno, Cloudflare Worker, and Vercel Edge templates, plus optional `--with-ci` GitHub Actions / Dependabot / CODEOWNERS / SECURITY.md hardening.
+- `pnpm create daloy` scaffolder with Node, Bun, Deno, Cloudflare Worker, and Vercel Edge templates, plus optional `--with-ci` GitHub Actions / Dependabot / CODEOWNERS / SECURITY.md hardening. The completion summary surfaces official install links (nodejs.org, pnpm.io, bun.sh) for any runtime or package manager your selections need but that is missing from `PATH`, and skips a doomed dependency install when the chosen package manager is absent.
 - Container-first templates: `HEALTHCHECK` to `/readyz`, `STOPSIGNAL SIGTERM`, non-root user, `tini` as PID 1.
 - Generated `deploy.yml` for container templates signs every pushed GHCR image with **Sigstore Cosign** (keyless OIDC) and attaches an **SPDX SBOM attestation** so consumers can `cosign verify` and `cosign verify-attestation --type spdxjson` instead of trusting the registry alone.
 - Pretty `printStartupBanner()` / `formatStartupBanner()` helpers at `@daloyjs/core/banner`, used by every starter template (TTY + `NO_COLOR` / `FORCE_COLOR` aware, ASCII fallback for dumb terminals).
@@ -568,6 +568,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `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`.
 - `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.
@@ -598,7 +599,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
   - an Origin policy (`allowedOrigins: "same-origin"` / `string[]` / predicate) or `acknowledgeCrossOriginUpgrade: true`.
 
   This closes the Cross-Site WebSocket Hijacking (CSWSH) class of bug — Storybook's [CVE-2026-27148](https://www.aikido.dev/blog/storybooks-websockets-attack) is the representative case: cookie auth alone does not stop a malicious site from opening an authenticated WS handshake from a victim's browser. The Origin check runs **before** `beforeUpgrade` in both adapters.
-- Contract-first **AsyncAPI 3.0** generation for `app.ws()` surfaces via `@daloyjs/core/asyncapi` (`generateAsyncAPI()` / `asyncapiToYAML()`) and `daloy inspect --asyncapi`. Each route becomes a channel (address + path params) with a `receive` operation for inbound client messages and an optional `send` operation for outbound messages, described via an optional handler `meta` block (`summary` / `description` / `tags` / `send` / `receive` / `operationId`).
+- Contract-first **AsyncAPI 3.0** generation for `app.ws()` surfaces via `@daloyjs/core/asyncapi` (`generateAsyncAPI()` / `asyncapiToYAML()`) and `daloy inspect --asyncapi`. Each route becomes a channel (address + path params) with a `receive` operation for inbound client messages and an optional `send` operation for outbound messages, described via an optional handler `meta` block (`summary` / `description` / `tags` / `send` / `receive` / `operationId`). Set `asyncapi: true` (mirroring `docs: true`) to **auto-mount an interactive AsyncAPI UI** at `/asyncapi` plus `/asyncapi.json` + `/asyncapi.yaml` — the WebSocket counterpart to the Scalar / Swagger / Redoc OpenAPI viewers, served from a CDN with the same SRI + strict-CSP hardening.
 
 ### Lifecycle and ops
 
@@ -613,6 +614,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - Adapter-independent `ConnInfo` abstraction: `getConnInfo()`, lazy `ctx.remoteAddress`, `ctx.remotePort`.
 - `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.
 - `defineDependency()` typed-DI helper with per-request deduplication.
 - Scheme-aware `ctx.state.auth` typed contract; named, optionally seeded stateful plugins.
 

package/dist/adapters/node.js

@@ -565,6 +565,17 @@ class NodeWebSocketConnection {
         this._fireClose(WS_CLOSE_CODE.ABNORMAL_CLOSURE, "");
     }
     _handleSocketError(err) {
+        // A socket error arriving after the connection is already closed — e.g. the
+        // peer resets the TCP connection right after the close handshake, or a
+        // terminate() raced the OS — is teardown noise. Surfacing it to the
+        // handler's error() callback would fire a lifecycle event *after* close(),
+        // breaking the "no events after close" contract and risking double cleanup.
+        // Swallow it and just make sure the socket is gone.
+        if (this.closeHandled || this.readyState === WS_READY_STATE.CLOSED) {
+            this.readyState = WS_READY_STATE.CLOSED;
+            this.socket.destroy();
+            return;
+        }
         this._invokeError(err);
         this.readyState = WS_READY_STATE.CLOSED;
         this.socket.destroy();

package/dist/app.d.ts

@@ -2,7 +2,8 @@ import { WebSocketRegistry, type WebSocketHandler } from "./websocket.js";
 import { type Logger } from "./logger.js";
 import type { HttpMethod, Hooks, PathString, RequestSchemas, ResponsesMap, RouteDefinition } from "./types.js";
 import { type OpenAPIInfo, type OpenAPIOptions } from "./openapi.js";
-import { type DocsAssetOptions, type DocsContentSecurityPolicyOptions, type RedocConfiguration, type ScalarReferenceConfiguration } from "./docs.js";
+import { type DocsAssetOptions, type DocsContentSecurityPolicyOptions, type RedocConfiguration, type ScalarJsonValue, type ScalarReferenceConfiguration } from "./docs.js";
+import { type AsyncAPIServer } from "./asyncapi.js";
 import { type SecureHeadersOptions } from "./middleware.js";
 import { type LoadSheddingOptions } from "./load-shedding.js";
 import { MetricsRegistry, type HttpMetricsOptions } from "./metrics.js";
@@ -320,6 +321,24 @@ export interface AppOptions {
      * @since 0.3.0
      */
     docs?: boolean | "auto" | DocsRouteOptions;
+    /**
+     * Enable the built-in AsyncAPI surface for your `app.ws()` channels — the
+     * WebSocket counterpart to {@link AppOptions.docs}. Mirrors the same modes:
+     *
+     * - `false` (default) — never mount.
+     * - `true` — always mount `/asyncapi.json`, `/asyncapi.yaml`, and an
+     *   interactive `/asyncapi` UI (the official AsyncAPI React component, loaded
+     *   from a CDN exactly like the Scalar / Swagger / Redoc OpenAPI viewers).
+     * - `"auto"` — mount everywhere except production.
+     * - object form — {@link AsyncAPIRouteOptions} for full control.
+     *
+     * The document is generated lazily per request, so `app.ws()` routes
+     * registered after construction are included. With no WebSocket routes the
+     * document simply has no channels.
+     *
+     * @since 0.42.0
+     */
+    asyncapi?: boolean | "auto" | AsyncAPIRouteOptions;
 }
 /**
  * Subset of {@link OpenAPIOptions} accepted by `new App({ openapi })`. All
@@ -395,6 +414,56 @@ export interface DocsRouteOptions {
      */
     assets?: DocsAssetOptions;
 }
+/**
+ * Options for the auto-mounted AsyncAPI surface — the WebSocket-channel
+ * counterpart to {@link DocsRouteOptions}. Enabled via {@link AppOptions.asyncapi}.
+ *
+ * @since 0.42.0
+ */
+export interface AsyncAPIRouteOptions {
+    /** Path the interactive AsyncAPI UI is served from. Default `"/asyncapi"`. */
+    path?: PathString;
+    /** Path the AsyncAPI 3.0 JSON document is served from. Default `"/asyncapi.json"`. */
+    jsonPath?: PathString;
+    /**
+     * Path the AsyncAPI 3.0 YAML document is served from. Default
+     * `"/asyncapi.yaml"`. Set to `false` to disable the YAML route.
+     */
+    yamlPath?: PathString | false;
+    /** Page `<title>`. Defaults to the resolved AsyncAPI `info.title`. */
+    title?: string;
+    /**
+     * Named AsyncAPI servers (`{ production: { host, protocol } }`). Defaults to
+     * the `openapi.servers` mapping when omitted, else no servers.
+     */
+    servers?: Record<string, AsyncAPIServer>;
+    /**
+     * Forwarded as the `config` object to `AsyncApiStandalone.render`. Defaults
+     * to showing the sidebar and inline errors.
+     */
+    configuration?: {
+        [key: string]: ScalarJsonValue | undefined;
+    };
+    /**
+     * Force the routes to mount regardless of `NODE_ENV`. When `"auto"` (default
+     * for the object form), skips mounting in production — same semantics as
+     * {@link DocsRouteOptions.enabled}.
+     */
+    enabled?: boolean | "auto";
+    /**
+     * Tags attached to the auto-mounted operations in the generated OpenAPI
+     * spec. Default: `["AsyncAPI"]`. Pass an empty array to omit tags.
+     */
+    tags?: string[];
+    /** Override the Content-Security-Policy applied to the UI HTML response. */
+    csp?: DocsContentSecurityPolicyOptions;
+    /**
+     * Override the UI asset URLs and pin SRI hashes (see {@link DocsAssetOptions}).
+     * The relevant fields are `asyncapiScriptUrl` / `asyncapiScriptIntegrity` /
+     * `asyncapiStyleUrl` / `asyncapiStyleIntegrity`.
+     */
+    assets?: DocsAssetOptions;
+}
 /** Information passed to {@link App.onPluginInstalled} listeners. */
 export interface PluginInstalledEvent {
     /** Name of the plugin (only set when registered with `{ name, register }`). */
@@ -957,6 +1026,24 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      */
     private maybeMountDocs;
     private mountDocs;
+    /**
+     * Resolve {@link AppOptions.asyncapi} and, when enabled, mount the AsyncAPI
+     * JSON / YAML / UI routes. Called once during construction; the document is
+     * generated lazily so `app.ws()` routes registered afterwards are included.
+     */
+    private maybeMountAsyncAPI;
+    /**
+     * Register the `/asyncapi.json`, `/asyncapi.yaml`, and `/asyncapi` (UI)
+     * routes. The WebSocket-channel counterpart to {@link App.mountDocs} — same
+     * lazy-generation, CDN-hosted-UI, SRI/CSP-hardened posture.
+     */
+    private mountAsyncAPI;
+    /**
+     * Best-effort conversion of the OpenAPI `servers` array into AsyncAPI's
+     * name-keyed server map, so an app that already declares HTTP servers gets
+     * sensible AsyncAPI servers for free. Returns `undefined` when none apply.
+     */
+    private asyncapiServersFromOpenAPI;
     /**
      * Register a single route on the application.
      *

package/dist/app.js

@@ -5,7 +5,8 @@ import { validate } from "./schema.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, redocHtml, scalarHtml, swaggerUiHtml, } from "./docs.js";
+import { asyncapiHtml, docsContentSecurityPolicy, redocHtml, scalarHtml, swaggerUiHtml, } from "./docs.js";
+import { generateAsyncAPI, asyncapiToYAML, } from "./asyncapi.js";
 import { secureHeaders as secureHeadersMiddleware, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, CSRF_HOOK_MARKER, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, SECURE_HEADERS_MARKER, } from "./middleware.js";
 import { COMPRESSION_HOOK_MARKER } from "./compression.js";
 import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
@@ -320,6 +321,7 @@ export class App {
         this.installSecureDefaults();
         this.maybeInstallCrashHandlers();
         this.maybeMountDocs();
+        this.maybeMountAsyncAPI();
     }
     /**
      * Validate {@link AppOptions.disconnectStatusCode}.
@@ -889,6 +891,146 @@ export class App {
             },
         });
     }
+    /**
+     * Resolve {@link AppOptions.asyncapi} and, when enabled, mount the AsyncAPI
+     * JSON / YAML / UI routes. Called once during construction; the document is
+     * generated lazily so `app.ws()` routes registered afterwards are included.
+     */
+    maybeMountAsyncAPI() {
+        const raw = this.options.asyncapi;
+        if (raw === undefined || raw === false)
+            return;
+        let resolvedOpts;
+        if (raw === true) {
+            resolvedOpts = {};
+        }
+        else if (raw === "auto") {
+            if (this.isProduction())
+                return;
+            resolvedOpts = {};
+        }
+        else {
+            const enabled = raw.enabled ?? true;
+            if (enabled === false)
+                return;
+            if (enabled === "auto" && this.isProduction())
+                return;
+            resolvedOpts = raw;
+        }
+        this.mountAsyncAPI(resolvedOpts);
+    }
+    /**
+     * Register the `/asyncapi.json`, `/asyncapi.yaml`, and `/asyncapi` (UI)
+     * routes. The WebSocket-channel counterpart to {@link App.mountDocs} — same
+     * lazy-generation, CDN-hosted-UI, SRI/CSP-hardened posture.
+     */
+    mountAsyncAPI(opts) {
+        const jsonPath = (opts.jsonPath ?? "/asyncapi.json");
+        const yamlPath = opts.yamlPath === false
+            ? null
+            : (opts.yamlPath ?? "/asyncapi.yaml");
+        const uiPath = (opts.path ?? "/asyncapi");
+        const tags = opts.tags ?? ["AsyncAPI"];
+        const resolveInfo = async () => {
+            const fromOpenapi = this.options.openapi?.info ?? {};
+            const fromPkg = await readHostPackageJsonInfo();
+            const title = fromOpenapi.title ?? this.options.title ?? fromPkg.title ?? "DaloyJS API";
+            const version = fromOpenapi.version ?? this.options.version ?? fromPkg.version ?? "0.0.0";
+            return { title, version };
+        };
+        const servers = opts.servers ?? this.asyncapiServersFromOpenAPI();
+        const generate = async () => generateAsyncAPI(this, {
+            info: await resolveInfo(),
+            ...(servers ? { servers } : {}),
+        });
+        this.route({
+            method: "GET",
+            path: jsonPath,
+            operationId: "getAsyncAPIDocument",
+            ...(tags.length ? { tags } : {}),
+            summary: "AsyncAPI 3.0 document",
+            responses: {
+                200: { description: "AsyncAPI 3.0 document for this application's WebSocket channels." },
+            },
+            handler: async () => ({ status: 200, body: await generate() }),
+        });
+        if (yamlPath) {
+            this.route({
+                method: "GET",
+                path: yamlPath,
+                operationId: "getAsyncAPIDocumentYaml",
+                ...(tags.length ? { tags } : {}),
+                summary: "AsyncAPI 3.0 document (YAML)",
+                responses: {
+                    200: { description: "AsyncAPI 3.0 document for this application, in YAML." },
+                },
+                handler: async () => ({
+                    status: 200,
+                    body: asyncapiToYAML(await generate()),
+                    headers: {
+                        "content-type": "text/yaml; charset=utf-8",
+                        "content-disposition": "inline",
+                        "x-content-type-options": "nosniff",
+                    },
+                }),
+            });
+        }
+        const uiCsp = docsContentSecurityPolicy(opts.csp);
+        this.route({
+            method: "GET",
+            path: uiPath,
+            operationId: "getAsyncAPIUI",
+            ...(tags.length ? { tags } : {}),
+            summary: "Interactive AsyncAPI reference",
+            responses: {
+                200: { description: "Interactive AsyncAPI documentation UI." },
+            },
+            handler: async () => {
+                const title = opts.title ?? (await resolveInfo()).title;
+                const html = asyncapiHtml({
+                    specUrl: jsonPath,
+                    title,
+                    ...(opts.configuration ? { configuration: opts.configuration } : {}),
+                    ...(opts.assets ? { assets: opts.assets } : {}),
+                });
+                return {
+                    status: 200,
+                    body: html,
+                    headers: {
+                        "content-type": "text/html; charset=utf-8",
+                        "content-security-policy": uiCsp,
+                        "x-content-type-options": "nosniff",
+                        "referrer-policy": "no-referrer",
+                    },
+                };
+            },
+        });
+    }
+    /**
+     * Best-effort conversion of the OpenAPI `servers` array into AsyncAPI's
+     * name-keyed server map, so an app that already declares HTTP servers gets
+     * sensible AsyncAPI servers for free. Returns `undefined` when none apply.
+     */
+    asyncapiServersFromOpenAPI() {
+        const servers = this.options.openapi?.servers;
+        if (!servers || servers.length === 0)
+            return undefined;
+        const out = {};
+        servers.forEach((srv, i) => {
+            try {
+                const u = new URL(srv.url);
+                const host = u.host || u.pathname;
+                // Map http(s) → ws(s); leave other schemes as-is minus the trailing ":".
+                const scheme = u.protocol.replace(/:$/, "");
+                const protocol = scheme === "https" ? "wss" : scheme === "http" ? "ws" : scheme;
+                out[`server${i + 1}`] = { host, protocol };
+            }
+            catch {
+                /* skip malformed server URLs */
+            }
+        });
+        return Object.keys(out).length > 0 ? out : undefined;
+    }
     // ---------- registration ----------
     /**
      * Register a single route on the application.

package/dist/banner.js

@@ -36,24 +36,44 @@ const GLYPHS_ASCII = {
     mid: "-",
 };
 const ANSI_REGEX = /\u001b\[[0-9;]*m/g;
+/**
+ * Read a single environment variable defensively. On runtimes with a
+ * capability-based permission model (Deno), reading an env var the process was
+ * not granted via `--allow-env` throws a `NotCapable` error. The startup
+ * banner is purely cosmetic, so a missing color/locale hint must never crash
+ * the host application — swallow the denial and treat the variable as unset.
+ * On Node and Bun `process.env` access never throws, so this is a no-op there.
+ *
+ * @param key - Environment variable name.
+ * @returns The value, or `undefined` when unset or inaccessible.
+ */
+function readEnv(key) {
+    try {
+        return process.env[key];
+    }
+    catch {
+        return undefined;
+    }
+}
 function detectColor() {
-    if (process.env.NO_COLOR)
+    if (readEnv("NO_COLOR"))
         return false;
-    if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0")
+    const force = readEnv("FORCE_COLOR");
+    if (force && force !== "0")
         return true;
     const stdout = process.stdout;
     return Boolean(stdout && stdout.isTTY);
 }
 function detectAscii() {
-    if (process.env.DALOY_ASCII)
+    if (readEnv("DALOY_ASCII"))
         return true;
     if (process.platform === "win32") {
-        return !(process.env.WT_SESSION || process.env.TERM_PROGRAM);
+        return !(readEnv("WT_SESSION") || readEnv("TERM_PROGRAM"));
     }
-    const lang = process.env.LANG ?? process.env.LC_ALL ?? "";
+    const lang = readEnv("LANG") ?? readEnv("LC_ALL") ?? "";
     if (/UTF-?8/i.test(lang))
         return false;
-    if (process.env.TERM_PROGRAM)
+    if (readEnv("TERM_PROGRAM"))
         return false;
     return true;
 }

package/dist/cli.js

@@ -547,9 +547,14 @@ async function runDiff(opts, io) {
 }
 /**
  * `daloy doctor` — boot-time + CLI audit. Loads the user's
- * App entry and runs the secure-by-default checklist. Exits non-zero on any
- * finding so the command can guard container `HEALTHCHECK` and CI deploy
- * steps.
+ * App entry and runs the secure-by-default checklist so the command can guard
+ * container `HEALTHCHECK` and CI deploy steps.
+ *
+ * Exit code: non-zero (`1`) only when at least one **`error`-level** finding is
+ * present; `warn`-level findings are advisory and leave the exit code at `0`.
+ * The `--json` output reports `ok: true` only when there are **no findings at
+ * all** (any level), so `ok` is a stricter signal than the exit code — a
+ * warn-only run prints `ok: false` but still exits `0`.
  *
  * @internal
  */

package/dist/docs.d.ts

@@ -226,6 +226,24 @@ export interface DocsAssetOptions {
      * @since 0.39.0
      */
     redocScriptIntegrity?: string;
+    /** Override the AsyncAPI React standalone bundle URL (useful for self-hosting). */
+    asyncapiScriptUrl?: string;
+    /**
+     * SRI hash for {@link asyncapiScriptUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.42.0
+     */
+    asyncapiScriptIntegrity?: string;
+    /** Override the AsyncAPI React component stylesheet URL (useful for self-hosting). */
+    asyncapiStyleUrl?: string;
+    /**
+     * SRI hash for {@link asyncapiStyleUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.42.0
+     */
+    asyncapiStyleIntegrity?: string;
     /**
      * `crossorigin` attribute value emitted alongside any pinned integrity
      * hash. SRI on a cross-origin asset requires CORS, so this defaults to
@@ -264,6 +282,20 @@ export interface RedocHtmlOptions extends DocsOptions {
     /** Forwarded as the options object to `Redoc.init(specUrl, configuration, element)`. */
     configuration?: RedocConfiguration;
 }
+/**
+ * Options for {@link asyncapiHtml}; adds AsyncAPI-specific UI configuration.
+ *
+ * @since 0.42.0
+ */
+export interface AsyncApiHtmlOptions extends DocsOptions {
+    /**
+     * Forwarded as the `config` object to `AsyncApiStandalone.render({ schema, config }, el)`.
+     * Defaults to showing the sidebar and inline errors.
+     */
+    configuration?: {
+        [key: string]: ScalarJsonValue | undefined;
+    };
+}
 /** Options for {@link docsContentSecurityPolicy}. */
 export interface DocsContentSecurityPolicyOptions {
     /** Extra origins to allow for `script-src` / `style-src` (defaults to jsDelivr). */
@@ -316,6 +348,23 @@ export declare function swaggerUiHtml(opts: DocsOptions): string;
  * @since 0.39.0
  */
 export declare function redocHtml(opts: RedocHtmlOptions): string;
+/**
+ * Render an AsyncAPI HTML page that loads `opts.specUrl` (an AsyncAPI 3.0
+ * document) into the official AsyncAPI React component. Same shape as
+ * {@link redocHtml}: a prebuilt standalone bundle is loaded from a CDN via a
+ * `<script>` tag (no build step, no extra deps) and the spec URL is handed to
+ * `AsyncApiStandalone.render(...)`. This is the AsyncAPI equivalent of the
+ * Scalar / Swagger UI / Redoc OpenAPI viewers.
+ *
+ * Serve it with the same CSP as the OpenAPI docs UIs ({@link docsContentSecurityPolicy}):
+ * it needs the asset origin (jsDelivr by default) in `script-src` / `style-src`
+ * and `connect-src 'self'` so the component can `fetch` the spec. The spec URL
+ * and configuration are embedded with `<`-escaped JSON so an attacker-controlled
+ * value cannot break out of the inline `<script>`.
+ *
+ * @since 0.42.0
+ */
+export declare function asyncapiHtml(opts: AsyncApiHtmlOptions): string;
 /**
  * Build a Content-Security-Policy string compatible with the docs HTML
  * produced by {@link scalarHtml} / {@link swaggerUiHtml}.

package/dist/docs.js

@@ -123,6 +123,45 @@ export function redocHtml(opts) {
 <script${nonce}>Redoc.init(${specArg},${optionsArg},document.getElementById("redoc"));</script>
 </body></html>`;
 }
+/**
+ * Render an AsyncAPI HTML page that loads `opts.specUrl` (an AsyncAPI 3.0
+ * document) into the official AsyncAPI React component. Same shape as
+ * {@link redocHtml}: a prebuilt standalone bundle is loaded from a CDN via a
+ * `<script>` tag (no build step, no extra deps) and the spec URL is handed to
+ * `AsyncApiStandalone.render(...)`. This is the AsyncAPI equivalent of the
+ * Scalar / Swagger UI / Redoc OpenAPI viewers.
+ *
+ * Serve it with the same CSP as the OpenAPI docs UIs ({@link docsContentSecurityPolicy}):
+ * it needs the asset origin (jsDelivr by default) in `script-src` / `style-src`
+ * and `connect-src 'self'` so the component can `fetch` the spec. The spec URL
+ * and configuration are embedded with `<`-escaped JSON so an attacker-controlled
+ * value cannot break out of the inline `<script>`.
+ *
+ * @since 0.42.0
+ */
+export function asyncapiHtml(opts) {
+    const title = escapeHtml(opts.title ?? "AsyncAPI");
+    const scriptUrl = escapeHtml(opts.assets?.asyncapiScriptUrl ??
+        `${JSDELIVR_ORIGIN}/npm/@asyncapi/react-component/browser/standalone/index.js`);
+    const styleUrl = escapeHtml(opts.assets?.asyncapiStyleUrl ??
+        `${JSDELIVR_ORIGIN}/npm/@asyncapi/react-component/styles/default.min.css`);
+    const scriptSri = integrityAttr(opts.assets?.asyncapiScriptIntegrity, opts.assets?.crossOrigin);
+    const styleSri = integrityAttr(opts.assets?.asyncapiStyleIntegrity, opts.assets?.crossOrigin);
+    const nonce = nonceAttr(opts.scriptNonce);
+    const specArg = jsonForScript(opts.specUrl);
+    const configArg = jsonForScript(opts.configuration ?? { show: { sidebar: true, errors: true } });
+    return `<!doctype html>
+<html><head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+<link rel="stylesheet" href="${styleUrl}"${styleSri} />
+</head><body>
+<div id="asyncapi"></div>
+<script src="${scriptUrl}"${scriptSri}${nonce}></script>
+<script${nonce}>AsyncApiStandalone.render({schema:{url:${specArg},options:{method:"GET"}},config:${configArg}},document.getElementById("asyncapi"));</script>
+</body></html>`;
+}
 /**
  * Build a Content-Security-Policy string compatible with the docs HTML
  * produced by {@link scalarHtml} / {@link swaggerUiHtml}.

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { findRoutesMissingResponseBodySchema } from "./app.js";
 export { _resetPackageJsonCacheForTests } from "./app.js";
 export { _resetCrashHandlersForTests } from "./app.js";
 export { _resetInsecureDefaultsLogForTests } from "./app.js";
-export type { AppOptions, AppOpenAPIOptions, DocsRouteOptions, HealthRouteOptions, CspReportRouteOptions, MetricsRouteOptions, IntrospectedRoute, PluginInstalledEvent, PluginExtension, ShutdownEvent, SecurityPreset, } from "./app.js";
+export type { AppOptions, AppOpenAPIOptions, DocsRouteOptions, AsyncAPIRouteOptions, HealthRouteOptions, CspReportRouteOptions, MetricsRouteOptions, IntrospectedRoute, PluginInstalledEvent, PluginExtension, ShutdownEvent, SecurityPreset, } from "./app.js";
 export { getConnInfo, setConnInfo, assertBehindProxy, resolveClientIp, readRemoteAddress, readRemotePort, pickForwardedForByHops, } from "./conn-info.js";
 export type { BehindProxyConfig, ConnInfo } from "./conn-info.js";
 export { subdomains, PSL_SNAPSHOT_DATE, PSL_PUBLIC_SUFFIXES, MAX_SNAPSHOT_AGE_DAYS, } from "./subdomains.js";
@@ -73,7 +73,7 @@ export type { RequestIdOptions, SecureHeadersOptions, CspDirectivesOptions, Cors
 export type { BearerAuthOptions, BearerAuthVerifyHook } from "./middleware.js";
 export { createLogger, noopLogger, DEFAULT_REDACT_KEYS } from "./logger.js";
 export type { Logger, LogLevel, ConsoleLoggerOptions, LoggerRedactionOptions, } from "./logger.js";
-export type { ScalarJsonPrimitive, ScalarJsonValue, ScalarReferenceConfiguration, ScalarTheme, RedocConfiguration, RedocHtmlOptions, DocsAssetOptions, } from "./docs.js";
+export type { ScalarJsonPrimitive, ScalarJsonValue, ScalarReferenceConfiguration, ScalarTheme, RedocConfiguration, RedocHtmlOptions, AsyncApiHtmlOptions, DocsAssetOptions, } from "./docs.js";
 export { formatStartupBanner, printStartupBanner } from "./banner.js";
 export type { StartupBannerLink, StartupBannerOptions } from "./banner.js";
 export { sseStream, sseResponse, ndjsonStream, ndjsonResponse, } from "./streaming.js";
@@ -96,5 +96,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 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

@@ -48,4 +48,5 @@ export { encodeCursor, decodeCursor, buildLinkHeader, buildPageLinks, pagination
 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 { 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/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:b6ab6390-9d08-59eb-80b2-e39452c91f11",
+  "serialNumber": "urn:uuid:66a4adf1-88f7-56e9-a00f-95633f473b23",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-18T16:40:32.542Z",
+    "timestamp": "2026-06-20T12:10:13.811Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.41.0"
+        "version": "0.43.0"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@0.41.0",
+      "bom-ref": "pkg:npm/@daloyjs/core@0.43.0",
       "name": "@daloyjs/core",
-      "version": "0.41.0",
+      "version": "0.43.0",
       "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.41.0",
+      "purl": "pkg:npm/@daloyjs/core@0.43.0",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-0.41.0",
+        "tagId": "swidtag--daloyjs-core-0.43.0",
         "name": "@daloyjs/core",
-        "version": "0.41.0",
+        "version": "0.43.0",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@0.41.0",
+      "ref": "pkg:npm/@daloyjs/core@0.43.0",
       "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.41.0",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.41.0-b6ab6390-9d08-59eb-80b2-e39452c91f11",
+  "name": "@daloyjs/core-0.43.0",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.43.0-66a4adf1-88f7-56e9-a00f-95633f473b23",
   "creationInfo": {
-    "created": "2026-06-18T16:40:32.542Z",
+    "created": "2026-06-20T12:10:13.811Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "0.41.0",
+      "versionInfo": "0.43.0",
       "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.41.0"
+          "referenceLocator": "pkg:npm/@daloyjs/core@0.43.0"
         }
       ]
     }

package/dist/tenancy.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Multitenancy primitive.
+ *
+ * `tenancy(opts)` returns a `Hooks` bundle that resolves the calling tenant
+ * once per request, validates and normalizes it, and exposes it on
+ * `ctx.state.tenant` for handlers and downstream middleware. It is the
+ * single source of truth for "who is this request for" so the per-tenant
+ * isolation knobs on the rest of the framework (`rateLimit` `keyGenerator`,
+ * `concurrencyLimit` / `idempotency` / `responseCache` `scope`) can all key
+ * off the same resolved value via {@link tenantScope}.
+ *
+ * Secure-by-default posture:
+ *
+ * - **Refuse-unresolved.** With the default `require: true`, a request whose
+ *   tenant cannot be resolved is rejected (`400`) rather than silently served
+ *   as some ambient "default" tenant — the failure mode that leaks one
+ *   tenant's data to another.
+ * - **Format-validated ids.** Resolved ids are normalized to a conservative
+ *   `[a-z0-9_-]` charset before they are stored or used as a key. A tenant id
+ *   pulled from a spoofable header can otherwise smuggle newlines, `:`, `/`,
+ *   or `*` into rate-limit keys, cache keys, and log lines (key/log injection,
+ *   cache poisoning). Anything that fails the pattern is treated as an unknown
+ *   tenant.
+ * - **No enumeration.** An id that resolves but is not in your `allow`
+ *   list/validator is rejected as `404 Not Found` by default, so probing for
+ *   valid tenant names cannot be distinguished from hitting a missing route.
+ * - **Host-spoof safe.** {@link tenantFromSubdomain} treats a `Host` that is
+ *   not under the declared `baseDomain` as unresolved instead of trusting it.
+ *
+ * Ordering: `tenancy()` resolves in `beforeHandle`, and so do the isolation
+ * primitives that consume the result. Register `tenancy()` **before** them
+ * (as the first group hook, or in `AppOptions.hooks`) so `ctx.state.tenant`
+ * is populated by the time their `keyGenerator` / `scope` callbacks run.
+ *
+ * ```ts
+ * import { App, tenancy, tenantFromSubdomain, tenantScope, rateLimit } from "@daloyjs/core";
+ *
+ * const app = new App({
+ *   hooks: tenancy({
+ *     resolve: tenantFromSubdomain({ baseDomain: "example.com" }),
+ *     allow: ["acme", "globex"],
+ *   }),
+ * });
+ *
+ * // Per-tenant rate-limit buckets keyed off the resolved tenant.
+ * app.use(rateLimit({ windowMs: 60_000, max: 100, keyGenerator: tenantScope() }));
+ * ```
+ *
+ * @since 0.42.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/**
+ * Resolves a raw (un-normalized) tenant id from a request, or a nullish value
+ * when this strategy cannot determine one. Resolvers are tried in order and
+ * the first non-empty result wins.
+ *
+ * @since 0.42.0
+ */
+export type TenantResolver = (ctx: BaseContext<any, any>) => string | null | undefined | Promise<string | null | undefined>;
+/**
+ * Default normalizer: trim, lowercase, and accept only ids matching
+ * {@link DEFAULT_TENANT_PATTERN}. Returns `undefined` for anything else, which
+ * the middleware treats as an unknown tenant.
+ *
+ * @param raw - The raw value produced by a {@link TenantResolver}.
+ * @returns The normalized id, or `undefined` when it is not a valid tenant id.
+ * @since 0.42.0
+ */
+export declare function defaultTenantNormalize(raw: string): string | undefined;
+/** Options for {@link tenantFromSubdomain}. @since 0.42.0 */
+export interface SubdomainTenantOptions {
+    /**
+     * Explicit registrable base domain (e.g. `"example.com"`). Strongly
+     * recommended in production: a `Host` that is not under this base is treated
+     * as unresolved rather than trusted, which defends against `Host`-header
+     * spoofing. When omitted, the PSL snapshot is used to split the host.
+     */
+    baseDomain?: string;
+    /**
+     * Which subdomain label to use, counting from the left (`0` = leftmost).
+     * For `acme.example.com` the default `0` yields `"acme"`. Default `0`.
+     */
+    index?: number;
+    /** Forwarded to {@link subdomains}: extra public-suffix entries. */
+    extraSuffixes?: readonly string[];
+    /**
+     * Forwarded to {@link subdomains}: enables the production staleness check on
+     * the bundled Public Suffix List snapshot. Default `false`.
+     */
+    production?: boolean;
+}
+/**
+ * Resolve the tenant from a request subdomain using the PSL-aware
+ * {@link subdomains} helper. `acme.example.com` → `"acme"`.
+ *
+ * A `Host` that is not under the declared `baseDomain` resolves to `undefined`
+ * (unresolved) instead of throwing, so a spoofed `Host` becomes a clean
+ * rejection rather than a `500`.
+ *
+ * @param opts - Subdomain resolution options.
+ * @returns A {@link TenantResolver}.
+ * @since 0.42.0
+ */
+export declare function tenantFromSubdomain(opts?: SubdomainTenantOptions): TenantResolver;
+/**
+ * Resolve the tenant from a request header (e.g. `"x-tenant-id"`).
+ *
+ * **Security:** request headers are client-controlled. Only use this behind a
+ * trusted proxy/load balancer that *overwrites* the header on every inbound
+ * request — otherwise a caller can set it to any tenant. Pair with
+ * {@link TenancyOptions.allow} to bound the accepted values.
+ *
+ * @param headerName - Header to read (case-insensitive).
+ * @returns A {@link TenantResolver}.
+ * @since 0.42.0
+ */
+export declare function tenantFromHeader(headerName: string): TenantResolver;
+/** Options for {@link tenantFromPathPrefix}. @since 0.42.0 */
+export interface PathPrefixTenantOptions {
+    /**
+     * Which non-empty path segment to use, counting from the left (`0` = first).
+     * For `/acme/orders` the default `0` yields `"acme"`. Default `0`.
+     */
+    segment?: number;
+}
+/**
+ * Resolve the tenant from a path segment. `/acme/orders` → `"acme"`.
+ *
+ * Note: this only reads the id; it does not rewrite the path, so your routes
+ * still include the tenant segment (e.g. register `/:tenant/orders`, or read
+ * `ctx.state.tenant` and ignore the segment in the handler).
+ *
+ * @param opts - Path-prefix resolution options.
+ * @returns A {@link TenantResolver}.
+ * @since 0.42.0
+ */
+export declare function tenantFromPathPrefix(opts?: PathPrefixTenantOptions): TenantResolver;
+/** Options for {@link tenantFromClaim}. @since 0.42.0 */
+export interface ClaimTenantOptions {
+    /**
+     * `ctx.state` key holding the authenticated principal. Default `"auth"`,
+     * matching the first-party auth helpers which write an
+     * `{ scheme, credentials }` context to `ctx.state.auth`. The claim is read
+     * from `credentials[claim]` when present, otherwise from `node[claim]`.
+     */
+    stateKey?: string;
+}
+/**
+ * Resolve the tenant from a verified auth claim already on `ctx.state`
+ * (e.g. an `org` / `tenant` JWT claim). Reads `ctx.state.auth.credentials`
+ * (the {@link AuthContext} shape) or, if there is no `credentials` field, the
+ * state node itself.
+ *
+ * **Ordering:** the auth middleware that populates the claim must run *before*
+ * `tenancy()`. Register your verifier first, then `tenancy()`.
+ *
+ * @param claim - Claim/property name carrying the tenant id.
+ * @param opts - Where to read the principal from.
+ * @returns A {@link TenantResolver}.
+ * @since 0.42.0
+ */
+export declare function tenantFromClaim(claim: string, opts?: ClaimTenantOptions): TenantResolver;
+/** Status codes acceptable for an unresolved-tenant rejection. @since 0.42.0 */
+export type UnresolvedStatus = 400 | 401 | 403 | 404;
+/** Status codes acceptable for an unknown/disallowed-tenant rejection. @since 0.42.0 */
+export type InvalidStatus = 400 | 403 | 404;
+/** Options for {@link tenancy}. @since 0.42.0 */
+export interface TenancyOptions {
+    /**
+     * One resolver, or several tried in order until one returns a non-empty
+     * value. Combine e.g. `[tenantFromClaim("org"), tenantFromSubdomain(...)]`
+     * to prefer a verified claim and fall back to the subdomain.
+     */
+    resolve: TenantResolver | TenantResolver[];
+    /**
+     * Reject requests whose tenant cannot be resolved. Default `true`. Set to
+     * `false` only when some routes are legitimately tenant-less; the request
+     * then proceeds with `ctx.state.tenant` left `undefined`.
+     */
+    require?: boolean;
+    /**
+     * Bound the accepted tenant space: an array allowlist, or an (optionally
+     * async) validator `(id, ctx) => boolean`. A resolved id that fails is
+     * rejected with {@link invalidStatus}. Array entries are validated against
+     * the normalizer at construction time (a malformed entry throws).
+     */
+    allow?: readonly string[] | ((tenantId: string, ctx: BaseContext<any, any>) => boolean | Promise<boolean>);
+    /**
+     * Normalize/validate a raw resolved id. Return `undefined` to reject it.
+     * Default {@link defaultTenantNormalize} (trim + lowercase + strict charset).
+     */
+    normalize?: (raw: string) => string | undefined;
+    /** `ctx.state` key the resolved tenant id is written to. Default `"tenant"`. */
+    stateKey?: string;
+    /** Status for an unresolved tenant when `require` is true. Default `400`. */
+    unresolvedStatus?: UnresolvedStatus;
+    /** Status for a resolved-but-disallowed tenant. Default `404` (no enumeration). */
+    invalidStatus?: InvalidStatus;
+}
+/**
+ * Multitenancy middleware. Resolves, validates, and normalizes the tenant for
+ * each request and stores it on `ctx.state[stateKey]` (default `tenant`).
+ * See the module overview for the secure-by-default posture and ordering
+ * rules.
+ *
+ * @param opts - Resolution, validation, and rejection configuration.
+ * @returns A `Hooks` object for `app.use(...)` or `new App({ hooks })`.
+ * @throws If no resolver is supplied, or an `allow` array entry is not a valid
+ *   tenant id under the configured normalizer.
+ * @since 0.42.0
+ */
+export declare function tenancy(opts: TenancyOptions): Hooks;
+/** Options for {@link tenantScope}. @since 0.42.0 */
+export interface TenantScopeOptions {
+    /** `ctx.state` key the tenant id was written to. Default `"tenant"`. */
+    stateKey?: string;
+    /**
+     * Key returned when no tenant is present (only reachable with
+     * `tenancy({ require: false })`). Default `"tenant:unknown"`.
+     */
+    fallback?: string;
+}
+/**
+ * Build a `(ctx) => string` key function that reads the resolved tenant and
+ * returns a `tenant:<id>` partition key. Drop it straight into the isolation
+ * knobs so each tenant gets its own bucket/namespace and cannot see, exhaust,
+ * or poison another tenant's:
+ *
+ * ```ts
+ * rateLimit({ windowMs: 60_000, max: 100, keyGenerator: tenantScope() });
+ * concurrencyLimit({ maxConcurrent: 20, scope: tenantScope() });
+ * idempotency({ scope: tenantScope() });    // CWE-524 cross-tenant cache defense
+ * responseCache({ ttlMs: 30_000, scope: tenantScope() });
+ * ```
+ *
+ * The `tenant:` prefix keeps these keys from colliding with other key spaces
+ * (e.g. `concurrencyLimit`'s literal `"global"` bucket).
+ *
+ * @param opts - Where to read the tenant from and the tenant-less fallback.
+ * @returns A key function suitable for `keyGenerator` / `scope`.
+ * @since 0.42.0
+ */
+export declare function tenantScope(opts?: TenantScopeOptions): (ctx: BaseContext<any, any>) => string;

package/dist/tenancy.js

@@ -0,0 +1,293 @@
+/**
+ * Multitenancy primitive.
+ *
+ * `tenancy(opts)` returns a `Hooks` bundle that resolves the calling tenant
+ * once per request, validates and normalizes it, and exposes it on
+ * `ctx.state.tenant` for handlers and downstream middleware. It is the
+ * single source of truth for "who is this request for" so the per-tenant
+ * isolation knobs on the rest of the framework (`rateLimit` `keyGenerator`,
+ * `concurrencyLimit` / `idempotency` / `responseCache` `scope`) can all key
+ * off the same resolved value via {@link tenantScope}.
+ *
+ * Secure-by-default posture:
+ *
+ * - **Refuse-unresolved.** With the default `require: true`, a request whose
+ *   tenant cannot be resolved is rejected (`400`) rather than silently served
+ *   as some ambient "default" tenant — the failure mode that leaks one
+ *   tenant's data to another.
+ * - **Format-validated ids.** Resolved ids are normalized to a conservative
+ *   `[a-z0-9_-]` charset before they are stored or used as a key. A tenant id
+ *   pulled from a spoofable header can otherwise smuggle newlines, `:`, `/`,
+ *   or `*` into rate-limit keys, cache keys, and log lines (key/log injection,
+ *   cache poisoning). Anything that fails the pattern is treated as an unknown
+ *   tenant.
+ * - **No enumeration.** An id that resolves but is not in your `allow`
+ *   list/validator is rejected as `404 Not Found` by default, so probing for
+ *   valid tenant names cannot be distinguished from hitting a missing route.
+ * - **Host-spoof safe.** {@link tenantFromSubdomain} treats a `Host` that is
+ *   not under the declared `baseDomain` as unresolved instead of trusting it.
+ *
+ * Ordering: `tenancy()` resolves in `beforeHandle`, and so do the isolation
+ * primitives that consume the result. Register `tenancy()` **before** them
+ * (as the first group hook, or in `AppOptions.hooks`) so `ctx.state.tenant`
+ * is populated by the time their `keyGenerator` / `scope` callbacks run.
+ *
+ * ```ts
+ * import { App, tenancy, tenantFromSubdomain, tenantScope, rateLimit } from "@daloyjs/core";
+ *
+ * const app = new App({
+ *   hooks: tenancy({
+ *     resolve: tenantFromSubdomain({ baseDomain: "example.com" }),
+ *     allow: ["acme", "globex"],
+ *   }),
+ * });
+ *
+ * // Per-tenant rate-limit buckets keyed off the resolved tenant.
+ * app.use(rateLimit({ windowMs: 60_000, max: 100, keyGenerator: tenantScope() }));
+ * ```
+ *
+ * @since 0.42.0
+ */
+import { BadRequestError, ForbiddenError, NotFoundError, UnauthorizedError, } from "./errors.js";
+import { subdomains } from "./subdomains.js";
+/**
+ * Conservative default tenant-id grammar: a DNS-label-like token, lowercase
+ * `a-z0-9` with internal `-`/`_`, 1–63 chars, no leading/trailing separator.
+ * Deliberately strict so a resolved id is always safe to embed in a key or a
+ * log line.
+ */
+const DEFAULT_TENANT_PATTERN = /^[a-z0-9](?:[a-z0-9_-]{0,61}[a-z0-9])?$/;
+/**
+ * Default normalizer: trim, lowercase, and accept only ids matching
+ * {@link DEFAULT_TENANT_PATTERN}. Returns `undefined` for anything else, which
+ * the middleware treats as an unknown tenant.
+ *
+ * @param raw - The raw value produced by a {@link TenantResolver}.
+ * @returns The normalized id, or `undefined` when it is not a valid tenant id.
+ * @since 0.42.0
+ */
+export function defaultTenantNormalize(raw) {
+    const id = raw.trim().toLowerCase();
+    return DEFAULT_TENANT_PATTERN.test(id) ? id : undefined;
+}
+/**
+ * Resolve the tenant from a request subdomain using the PSL-aware
+ * {@link subdomains} helper. `acme.example.com` → `"acme"`.
+ *
+ * A `Host` that is not under the declared `baseDomain` resolves to `undefined`
+ * (unresolved) instead of throwing, so a spoofed `Host` becomes a clean
+ * rejection rather than a `500`.
+ *
+ * @param opts - Subdomain resolution options.
+ * @returns A {@link TenantResolver}.
+ * @since 0.42.0
+ */
+export function tenantFromSubdomain(opts = {}) {
+    const index = opts.index ?? 0;
+    const base = opts.baseDomain?.toLowerCase();
+    return (ctx) => {
+        let hostname;
+        try {
+            hostname = new URL(ctx.request.url).hostname.toLowerCase();
+        }
+        catch {
+            return undefined;
+        }
+        if (!hostname)
+            return undefined;
+        if (base && hostname !== base && !hostname.endsWith(`.${base}`)) {
+            // Host is not under the declared base — possible spoofing. Resolve to
+            // unresolved instead of letting subdomains() throw.
+            return undefined;
+        }
+        const { labels } = subdomains(hostname, {
+            baseDomain: opts.baseDomain,
+            extraSuffixes: opts.extraSuffixes,
+            production: opts.production,
+        });
+        return labels[index];
+    };
+}
+/**
+ * Resolve the tenant from a request header (e.g. `"x-tenant-id"`).
+ *
+ * **Security:** request headers are client-controlled. Only use this behind a
+ * trusted proxy/load balancer that *overwrites* the header on every inbound
+ * request — otherwise a caller can set it to any tenant. Pair with
+ * {@link TenancyOptions.allow} to bound the accepted values.
+ *
+ * @param headerName - Header to read (case-insensitive).
+ * @returns A {@link TenantResolver}.
+ * @since 0.42.0
+ */
+export function tenantFromHeader(headerName) {
+    const name = headerName.toLowerCase();
+    return (ctx) => ctx.request.headers.get(name) ?? undefined;
+}
+/**
+ * Resolve the tenant from a path segment. `/acme/orders` → `"acme"`.
+ *
+ * Note: this only reads the id; it does not rewrite the path, so your routes
+ * still include the tenant segment (e.g. register `/:tenant/orders`, or read
+ * `ctx.state.tenant` and ignore the segment in the handler).
+ *
+ * @param opts - Path-prefix resolution options.
+ * @returns A {@link TenantResolver}.
+ * @since 0.42.0
+ */
+export function tenantFromPathPrefix(opts = {}) {
+    const segment = opts.segment ?? 0;
+    return (ctx) => {
+        let pathname;
+        try {
+            pathname = new URL(ctx.request.url).pathname;
+        }
+        catch {
+            return undefined;
+        }
+        const parts = pathname.split("/").filter(Boolean);
+        return parts[segment];
+    };
+}
+/**
+ * Resolve the tenant from a verified auth claim already on `ctx.state`
+ * (e.g. an `org` / `tenant` JWT claim). Reads `ctx.state.auth.credentials`
+ * (the {@link AuthContext} shape) or, if there is no `credentials` field, the
+ * state node itself.
+ *
+ * **Ordering:** the auth middleware that populates the claim must run *before*
+ * `tenancy()`. Register your verifier first, then `tenancy()`.
+ *
+ * @param claim - Claim/property name carrying the tenant id.
+ * @param opts - Where to read the principal from.
+ * @returns A {@link TenantResolver}.
+ * @since 0.42.0
+ */
+export function tenantFromClaim(claim, opts = {}) {
+    const stateKey = opts.stateKey ?? "auth";
+    return (ctx) => {
+        const node = ctx.state[stateKey];
+        if (!node || typeof node !== "object")
+            return undefined;
+        const withCreds = node;
+        const source = withCreds.credentials && typeof withCreds.credentials === "object"
+            ? withCreds.credentials
+            : node;
+        const value = source[claim];
+        if (typeof value === "string")
+            return value;
+        if (typeof value === "number" && Number.isFinite(value))
+            return String(value);
+        return undefined;
+    };
+}
+/** Build the right `HttpError` for a configured status. */
+function rejection(status, detail) {
+    switch (status) {
+        case 401:
+            return new UnauthorizedError(detail);
+        case 403:
+            return new ForbiddenError(detail);
+        case 404:
+            return new NotFoundError(detail);
+        default:
+            return new BadRequestError(detail);
+    }
+}
+/**
+ * Multitenancy middleware. Resolves, validates, and normalizes the tenant for
+ * each request and stores it on `ctx.state[stateKey]` (default `tenant`).
+ * See the module overview for the secure-by-default posture and ordering
+ * rules.
+ *
+ * @param opts - Resolution, validation, and rejection configuration.
+ * @returns A `Hooks` object for `app.use(...)` or `new App({ hooks })`.
+ * @throws If no resolver is supplied, or an `allow` array entry is not a valid
+ *   tenant id under the configured normalizer.
+ * @since 0.42.0
+ */
+export function tenancy(opts) {
+    const resolvers = Array.isArray(opts.resolve) ? opts.resolve : [opts.resolve];
+    if (resolvers.length === 0) {
+        throw new Error("tenancy(): at least one resolver is required.");
+    }
+    const stateKey = opts.stateKey ?? "tenant";
+    const required = opts.require ?? true;
+    const normalize = opts.normalize ?? defaultTenantNormalize;
+    const unresolvedStatus = opts.unresolvedStatus ?? 400;
+    const invalidStatus = opts.invalidStatus ?? 404;
+    // Pre-normalize an array allowlist so comparisons are apples-to-apples, and
+    // fail fast on a misconfigured entry rather than silently never matching it.
+    let allowSet;
+    let allowFn;
+    if (Array.isArray(opts.allow)) {
+        allowSet = new Set();
+        for (const entry of opts.allow) {
+            const n = normalize(entry);
+            if (n === undefined) {
+                throw new Error(`tenancy(): allowlist entry ${JSON.stringify(entry)} is not a valid tenant id.`);
+            }
+            allowSet.add(n);
+        }
+    }
+    else if (typeof opts.allow === "function") {
+        allowFn = opts.allow;
+    }
+    return {
+        async beforeHandle(ctx) {
+            let raw;
+            for (const resolve of resolvers) {
+                raw = await resolve(ctx);
+                if (raw != null && raw !== "")
+                    break;
+            }
+            if (raw == null || raw === "") {
+                if (required) {
+                    throw rejection(unresolvedStatus, "Could not determine the tenant for this request.");
+                }
+                return; // optional tenancy: proceed tenant-less
+            }
+            const id = normalize(raw);
+            if (id === undefined) {
+                // Malformed id — reject as unknown so a poisoned value never reaches a
+                // key or log line, and without revealing it was a format problem.
+                throw rejection(invalidStatus, "Unknown tenant.");
+            }
+            if (allowSet && !allowSet.has(id)) {
+                throw rejection(invalidStatus, "Unknown tenant.");
+            }
+            if (allowFn && !(await allowFn(id, ctx))) {
+                throw rejection(invalidStatus, "Unknown tenant.");
+            }
+            ctx.state[stateKey] = id;
+        },
+    };
+}
+/**
+ * Build a `(ctx) => string` key function that reads the resolved tenant and
+ * returns a `tenant:<id>` partition key. Drop it straight into the isolation
+ * knobs so each tenant gets its own bucket/namespace and cannot see, exhaust,
+ * or poison another tenant's:
+ *
+ * ```ts
+ * rateLimit({ windowMs: 60_000, max: 100, keyGenerator: tenantScope() });
+ * concurrencyLimit({ maxConcurrent: 20, scope: tenantScope() });
+ * idempotency({ scope: tenantScope() });    // CWE-524 cross-tenant cache defense
+ * responseCache({ ttlMs: 30_000, scope: tenantScope() });
+ * ```
+ *
+ * The `tenant:` prefix keeps these keys from colliding with other key spaces
+ * (e.g. `concurrencyLimit`'s literal `"global"` bucket).
+ *
+ * @param opts - Where to read the tenant from and the tenant-less fallback.
+ * @returns A key function suitable for `keyGenerator` / `scope`.
+ * @since 0.42.0
+ */
+export function tenantScope(opts = {}) {
+    const stateKey = opts.stateKey ?? "tenant";
+    const fallback = opts.fallback ?? "tenant:unknown";
+    return (ctx) => {
+        const value = ctx.state[stateKey];
+        return typeof value === "string" && value.length > 0 ? `tenant:${value}` : fallback;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "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": {
@@ -45,10 +45,6 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./app": {
-      "types": "./dist/app.d.ts",
-      "import": "./dist/app.js"
-    },
     "./node": {
       "types": "./dist/adapters/node.d.ts",
       "import": "./dist/adapters/node.js"
@@ -113,6 +109,10 @@
       "types": "./dist/tracing.d.ts",
       "import": "./dist/tracing.js"
     },
+    "./tenancy": {
+      "types": "./dist/tenancy.d.ts",
+      "import": "./dist/tenancy.js"
+    },
     "./multipart": {
       "types": "./dist/multipart.d.ts",
       "import": "./dist/multipart.js"