@daloyjs/core 0.39.1 → 0.42.0

package/README.md

@@ -438,6 +438,8 @@ if (!report.ok) process.exit(1);
 
 The contract runner verifies that declared examples actually match their schemas, flags duplicate/missing operationIds, dead routes, and accidental body schemas on safe methods.
 
+Gate it in CI two ways: `daloy inspect --check <entry>` exits non-zero on any error-level issue, or assert `report.ok` inside your test suite. **Every `create-daloy` template ships a contract-gate test** (`tests/contract.test.ts`, `tests/contract_test.ts` on Deno) wired into its `test` task, so scaffolded projects fail CI on a broken contract out of the box. For a localhost-only gate that runs before code leaves your machine, each template also ships an opt-in `pre-push` hook (`.githooks/pre-push`, enabled with `hooks:install` which points `core.hooksPath` at it); it runs `daloy inspect --check` on every `git push` and is bypassable with `git push --no-verify`.
+
 ---
 
 ## Plugin encapsulation (Fastify-style)
@@ -508,7 +510,7 @@ DaloyJS is in **public preview** (`0.x`). The public API may still change betwee
 - RFC 7231 + RFC 5789 HTTP-method allowlist enforced inside `app.route()` (WebDAV, `TRACE`, `CONNECT` rejected at the framework boundary).
 - AI-friendly route metadata via optional `meta: { examples, extensions, summary, description, tags }`; examples are validated against your schemas at build time, surfaced as OpenAPI `examples` + `x-daloy-*` extensions, and dumped as `routes.json` / `routes.yaml` via `daloy inspect --ai`.
 - API lifecycle and breaking-change detection: mark routes `deprecated` or give them a `sunset` date to emit RFC 8594 `Deprecation` / `Sunset` headers and an `x-sunset` OpenAPI extension, then gate CI with `diffOpenAPI()` / the `daloy diff` command, which fail on a breaking change versus the last published spec.
-- In-process test client (`app.request()`), contract-test runner, in-process typed client, and Hey API codegen via `pnpm gen`.
+- In-process test client (`app.request()`), contract-test runner (gated in CI via `daloy inspect --check` and shipped as a default test in every `create-daloy` template), in-process typed client, and Hey API codegen via `pnpm gen`.
 
 ### Runtimes and deployment
 
@@ -566,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.
@@ -596,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
 
@@ -611,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 }`). */
@@ -784,6 +853,14 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * dashboards see the misconfiguration without flooding on every retry.
      */
     private trustProxyWarned;
+    /**
+     * One-shot guard for the development-mode warning about `2xx` responses
+     * that declare no body schema (OWASP API3 output filtering is absent
+     * there). Flipped on the first {@link App.fetch} so all routes are
+     * registered by the time the scan runs, and so the scan never repeats on
+     * the hot path.
+     */
+    private responseBodySchemaAuditDone;
     /**
     * Cached merge of `options.hooks` only. Used on the cold 404/405 path
     * and as the baseline for cross-origin guard decisions when no route
@@ -949,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.
      *
@@ -1324,6 +1419,15 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * @returns Array of one {@link IntrospectedRoute} per registered route.
      */
+    /**
+     * Emit a one-time development warning when any route declares a `2xx`
+     * response without a body schema, because response-field stripping
+     * (OWASP API3) does not run for those responses — a handler returning
+     * undeclared fields would leak them. Silent in production (operators run
+     * `daloy doctor` in CI for the same finding) and when
+     * `secureDefaults: false`. See {@link findRoutesMissingResponseBodySchema}.
+     */
+    private warnMissingResponseBodySchemas;
     introspect(): IntrospectedRoute[];
     /**
      * Begin graceful shutdown.
@@ -1369,6 +1473,32 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
  * @internal
  */
 export declare function topoSortExtensions(exts: ReadonlyArray<PluginExtension>): PluginExtension[];
+/**
+ * Identify registered routes whose successful (`2xx`, excluding the
+ * body-less `204`/`205`) responses declare no `body` schema.
+ *
+ * Response-body validation — and the OWASP API3 ("Broken Object Property
+ * Level Authorization") output filtering that strips fields a handler
+ * returns but the contract does not declare — only runs when a response
+ * `body` schema is present. A `2xx` response without one therefore ships
+ * whatever the handler returns verbatim: a stray `passwordHash` or a
+ * spread ORM row would leak. This helper surfaces those routes so the gap
+ * is visible rather than silent.
+ *
+ * It powers both the `daloy doctor` `audit.response.bodySchema` finding and
+ * the development-mode boot warning emitted on the first request. The result
+ * is advisory — a route may legitimately return no body — so callers treat
+ * it as a `warn`, never a hard error.
+ *
+ * @param routes - Route definitions to inspect (typically `app.routes`).
+ * @returns One entry per offending route with the affected `2xx` status codes.
+ * @since 0.40.0
+ */
+export declare function findRoutesMissingResponseBodySchema(routes: readonly Pick<RouteDefinition<any, any, any, any>, "method" | "path" | "responses">[]): Array<{
+    method: string;
+    path: string;
+    statuses: number[];
+}>;
 /**
  * Factory alias for `new App(options)`. Lets callers who prefer a
  * functional style (or who avoid `new`) write:

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";
@@ -267,6 +268,14 @@ export class App {
      * dashboards see the misconfiguration without flooding on every retry.
      */
     trustProxyWarned = false;
+    /**
+     * One-shot guard for the development-mode warning about `2xx` responses
+     * that declare no body schema (OWASP API3 output filtering is absent
+     * there). Flipped on the first {@link App.fetch} so all routes are
+     * registered by the time the scan runs, and so the scan never repeats on
+     * the hot path.
+     */
+    responseBodySchemaAuditDone = false;
     /**
     * Cached merge of `options.hooks` only. Used on the cold 404/405 path
     * and as the baseline for cross-origin guard decisions when no route
@@ -312,6 +321,7 @@ export class App {
         this.installSecureDefaults();
         this.maybeInstallCrashHandlers();
         this.maybeMountDocs();
+        this.maybeMountAsyncAPI();
     }
     /**
      * Validate {@link AppOptions.disconnectStatusCode}.
@@ -881,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.
@@ -1772,6 +1922,10 @@ export class App {
      *   to RFC 9457 `application/problem+json` automatically.
      */
     fetch = async (request) => {
+        if (!this.responseBodySchemaAuditDone) {
+            this.responseBodySchemaAuditDone = true;
+            this.warnMissingResponseBodySchemas();
+        }
         const response = await this.dispatch(request);
         // In-flight responses that finish during draining advertise
         // `Connection: close` so HTTP/1.1 load balancers stop re-using the
@@ -1915,6 +2069,9 @@ export class App {
                         body: undefined,
                         state: { ...this.decorations, requestId, log },
                         set: { headers: new Headers() },
+                        // Cast through `unknown`: this is a deliberately minimal bootstrap
+                        // context for the cold 404 path (no user state populated yet), so
+                        // it must compile even when a consumer augments `AppState`.
                     };
                     ctx.set.headers.set("x-request-id", requestId);
                 }
@@ -1922,6 +2079,8 @@ export class App {
                     if (method === "OPTIONS") {
                         // Synthesize a preflight: let global hooks (e.g. CORS) intercept;
                         // otherwise return 204 with Allow header.
+                        // Cast through `unknown` so the synthetic preflight context still
+                        // compiles when a consumer augments `AppState` (no user state here).
                         const synthCtx = {
                             request,
                             params: {},
@@ -2127,6 +2286,31 @@ export class App {
      *
      * @returns Array of one {@link IntrospectedRoute} per registered route.
      */
+    /**
+     * Emit a one-time development warning when any route declares a `2xx`
+     * response without a body schema, because response-field stripping
+     * (OWASP API3) does not run for those responses — a handler returning
+     * undeclared fields would leak them. Silent in production (operators run
+     * `daloy doctor` in CI for the same finding) and when
+     * `secureDefaults: false`. See {@link findRoutesMissingResponseBodySchema}.
+     */
+    warnMissingResponseBodySchemas() {
+        if (this.isProduction())
+            return;
+        if (this.options.secureDefaults === false)
+            return;
+        const offending = findRoutesMissingResponseBodySchema(this.routes);
+        if (offending.length === 0)
+            return;
+        this.log.warn({
+            event: "security.response.bodySchemaMissing",
+            count: offending.length,
+            routes: offending.slice(0, 20),
+        }, `${offending.length} route(s) declare a 2xx response with no body schema; ` +
+            "response field-level stripping (OWASP API3) is not applied there, so a handler that " +
+            "returns undeclared fields will leak them. Declare a response body schema, or ignore if " +
+            "the route intentionally returns no body. Run `daloy doctor` to list them.");
+    }
     introspect() {
         return this.routes.map((r) => {
             const route = {
@@ -2628,6 +2812,51 @@ function copyContextHeaders(ctx, res) {
 function hasRequestSchema(request, key) {
     return !!request && !!request[key];
 }
+/**
+ * Identify registered routes whose successful (`2xx`, excluding the
+ * body-less `204`/`205`) responses declare no `body` schema.
+ *
+ * Response-body validation — and the OWASP API3 ("Broken Object Property
+ * Level Authorization") output filtering that strips fields a handler
+ * returns but the contract does not declare — only runs when a response
+ * `body` schema is present. A `2xx` response without one therefore ships
+ * whatever the handler returns verbatim: a stray `passwordHash` or a
+ * spread ORM row would leak. This helper surfaces those routes so the gap
+ * is visible rather than silent.
+ *
+ * It powers both the `daloy doctor` `audit.response.bodySchema` finding and
+ * the development-mode boot warning emitted on the first request. The result
+ * is advisory — a route may legitimately return no body — so callers treat
+ * it as a `warn`, never a hard error.
+ *
+ * @param routes - Route definitions to inspect (typically `app.routes`).
+ * @returns One entry per offending route with the affected `2xx` status codes.
+ * @since 0.40.0
+ */
+export function findRoutesMissingResponseBodySchema(routes) {
+    const offending = [];
+    for (const route of routes) {
+        const statuses = [];
+        const responses = route.responses;
+        for (const key of Object.keys(responses)) {
+            const status = Number(key);
+            // Only successful responses can carry an over-exposing body, and 204/205
+            // are body-less by HTTP semantics so they are never flagged.
+            if (!Number.isInteger(status) || status < 200 || status > 299)
+                continue;
+            if (status === 204 || status === 205)
+                continue;
+            const spec = responses[status];
+            if (spec && spec.body === undefined)
+                statuses.push(status);
+        }
+        if (statuses.length > 0) {
+            statuses.sort((a, b) => a - b);
+            offending.push({ method: route.method, path: route.path, statuses });
+        }
+    }
+    return offending;
+}
 /**
  * Stable-shape per-request context. All fields are initialised in fixed
  * order in the constructor so every dispatched request produces an instance
@@ -2868,7 +3097,16 @@ function serializeResult(result, def, validateResponses) {
     if (!spec) {
         throw new InternalError(`Handler returned status ${result.status} which is not declared in responses for ${def.method} ${def.path}`);
     }
-    const finish = () => {
+    // `outputBody` is the value actually serialized onto the wire. It defaults
+    // to the raw handler return, but when response-body validation runs it is
+    // replaced with the validator's parsed `value` (e.g. a Zod object with
+    // unknown keys stripped). This closes the OWASP API3 "excessive data
+    // exposure" hole: a handler that returns extra fields not declared in the
+    // response schema must not leak them — only declared fields are emitted,
+    // exactly as the OpenAPI contract and the security docs promise. Schemas
+    // that opt into pass-through (e.g. Zod `.passthrough()`) keep their extra
+    // keys because the validator itself returns them in `value`.
+    const finish = (outputBody) => {
         const headers = new Headers(result.headers);
         const explicitCt = headers.get("content-type");
         const treatAsJson = !explicitCt || explicitCt.includes("application/json");
@@ -2887,31 +3125,31 @@ function serializeResult(result, def, validateResponses) {
         let body;
         let rawBody = null;
         let isStream = false;
-        if (result.body === undefined || result.body === null) {
+        if (outputBody === undefined || outputBody === null) {
             body = null;
         }
-        else if (!treatAsJson && typeof result.body === "string") {
-            const bytes = TEXT_ENCODER.encode(result.body);
+        else if (!treatAsJson && typeof outputBody === "string") {
+            const bytes = TEXT_ENCODER.encode(outputBody);
             setContentLength(headers, bytes.byteLength);
             body = bytes;
             rawBody = bytes;
         }
-        else if (!treatAsJson && result.body instanceof Uint8Array) {
-            setContentLength(headers, result.body.byteLength);
-            body = result.body;
-            rawBody = result.body;
+        else if (!treatAsJson && outputBody instanceof Uint8Array) {
+            setContentLength(headers, outputBody.byteLength);
+            body = outputBody;
+            rawBody = outputBody;
         }
-        else if (!treatAsJson && result.body instanceof ArrayBuffer) {
-            setContentLength(headers, result.body.byteLength);
-            body = result.body;
-            rawBody = new Uint8Array(result.body);
+        else if (!treatAsJson && outputBody instanceof ArrayBuffer) {
+            setContentLength(headers, outputBody.byteLength);
+            body = outputBody;
+            rawBody = new Uint8Array(outputBody);
         }
-        else if (!treatAsJson && result.body instanceof ReadableStream) {
-            body = result.body;
+        else if (!treatAsJson && outputBody instanceof ReadableStream) {
+            body = outputBody;
             isStream = true;
         }
         else {
-            const bytes = TEXT_ENCODER.encode(JSON.stringify(result.body));
+            const bytes = TEXT_ENCODER.encode(JSON.stringify(outputBody));
             setContentLength(headers, bytes.byteLength);
             body = bytes;
             rawBody = bytes;
@@ -2935,7 +3173,9 @@ function serializeResult(result, def, validateResponses) {
                         .map((i) => i.message)
                         .join("; ")}`);
                 }
-                return finish();
+                // Serialize the validated (and, for object schemas, key-stripped)
+                // value so undeclared fields never reach the client.
+                return finish(resolved.value);
             });
         }
         else {
@@ -2944,9 +3184,10 @@ function serializeResult(result, def, validateResponses) {
                     .map((i) => i.message)
                     .join("; ")}`);
             }
+            return finish(r.value);
         }
     }
-    return finish();
+    return finish(result.body);
 }
 function setContentLength(headers, byteLength) {
     if (!headers.has("content-length"))

package/dist/cli.js

@@ -9,6 +9,7 @@
  * a child process. The thin shim in `bin/daloy.mjs` wires this up to
  * `process.argv`, `process.stdout`, dynamic `import()`, and `process.exit`.
  */
+import { findRoutesMissingResponseBodySchema } from "./app.js";
 import { runContractTests } from "./contract.js";
 import { diffOpenAPI } from "./openapi-diff.js";
 import { generateOpenAPI, openapiToYAML } from "./openapi.js";
@@ -726,6 +727,27 @@ async function runDoctor(opts, io) {
                     "Disable or gate behind authenticated routes.",
             });
         }
+        // Response-body-schema coverage audit (OWASP API3 — Broken Object
+        // Property Level Authorization). Response-field stripping only runs when
+        // a 2xx response declares a body schema; a schema-less 2xx ships whatever
+        // the handler returns, so a stray `passwordHash` or spread ORM row would
+        // leak. Advisory (warn) because a route may legitimately return no body.
+        const routes = app.routes ?? [];
+        const missingBody = findRoutesMissingResponseBodySchema(routes);
+        if (missingBody.length > 0) {
+            const sample = missingBody
+                .slice(0, 5)
+                .map((r) => `${r.method} ${r.path} (${r.statuses.join("/")})`)
+                .join(", ");
+            findings.push({
+                level: "warn",
+                code: "audit.response.bodySchema",
+                message: `${missingBody.length} route(s) declare a 2xx response with no body schema, so ` +
+                    `response field-level stripping (OWASP API3) is not applied: ${sample}` +
+                    `${missingBody.length > 5 ? ", …" : ""}. Declare a response body schema so undeclared ` +
+                    "handler fields cannot leak, or ignore if the route intentionally returns no body.",
+            });
+        }
     }
     if (opts.auditSecrets === true) {
         const env = globalThis.process?.env ?? {};