npm - @daloyjs/core - Versions diffs - 0.41.0 → 0.42.0 - Mend

@daloyjs/core 0.41.0 → 0.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/docs.d.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:b6ab6390-9d08-59eb-80b2-e39452c91f11",
+  "serialNumber": "urn:uuid:c3e0bc4b-403c-5789-b2e4-dbafa73b03ee",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-18T16:40:32.542Z",
+    "timestamp": "2026-06-19T08:56:49.249Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.41.0"
+        "version": "0.42.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.42.0",
       "name": "@daloyjs/core",
-      "version": "0.41.0",
+      "version": "0.42.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.42.0",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-0.41.0",
+        "tagId": "swidtag--daloyjs-core-0.42.0",
         "name": "@daloyjs/core",
-        "version": "0.41.0",
+        "version": "0.42.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.42.0",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json CHANGED Viewed

@@ -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.42.0",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-0.42.0-c3e0bc4b-403c-5789-b2e4-dbafa73b03ee",
   "creationInfo": {
-    "created": "2026-06-18T16:40:32.542Z",
+    "created": "2026-06-19T08:56:49.249Z",
     "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.42.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.42.0"
         }
       ]
     }

package/dist/tenancy.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "0.41.0",
+  "version": "0.42.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": {
@@ -113,6 +113,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"