@daloyjs/core 0.36.0 → 0.37.0

package/README.md

@@ -437,6 +437,7 @@ DaloyJS is in **public preview** (`0.x`). The public API may still change betwee
 - Zero-config OpenAPI `info` autofill from `package.json` (Node / Bun) or `deno.json` / `deno.jsonc` (Deno); explicit `openapi.info` values always win.
 - 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`.
 
 ### Runtimes and deployment
@@ -490,6 +491,23 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 - `jwk()` asymmetric-only JWKS middleware: refuses `HS*` at construction, cross-checks `kid` and JWT-vs-JWK `alg`, requires `https://` JWKS URLs with TTL caching + in-flight-promise dedup, normalizes `scope` / `scp` / `scopes` claims.
 - `requireScopes()` with RFC-6750 `WWW-Authenticate: Bearer` challenge and per-request scope aggregation.
 - `session()` with signed cookies and pluggable stores.
+- `idempotency()` with `Idempotency-Key` fingerprinting + byte-for-byte response replay, in-flight `409`, `422` on key reuse with a different payload, and a pluggable `IdempotencyStore` (in-memory default) at `@daloyjs/core/idempotency`.
+- `responseCache()` server-side body cache (cache-key + TTL with `s-maxage`/`max-age` orchestration, request `no-store`/`no-cache` directives, recursion-safe stale-while-revalidate, `Vary`-aware keying, `X-Cache` HIT/MISS/STALE marker, pluggable `ResponseCacheStore` in-memory default) at `@daloyjs/core/response-cache`. Never caches `Set-Cookie` or `private`/`no-store`/`no-cache` responses. Complements `etag()`/`compression()`, which do not cache bodies.
+- `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).
+- `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.
+- `clientCertAuth()` mTLS / client-certificate auth at `@daloyjs/core/mtls`: authenticate zero-trust / service-to-service callers by their TLS client certificate from two sources — **native TLS** (the Node adapter lazily reads the peer cert off the socket; plain requests pay nothing) or a **TLS-terminating proxy** (Envoy `X-Forwarded-Client-Cert` and nginx/HAProxy-style structured headers). `requireVerified` by default, exact `allowSubjectCNs` / `allowIssuerCNs`, **constant-time** `allowFingerprints`, `allowSANs` (SPIFFE/DNS/URI/IP, `TYPE:value` or bare), validity-window enforcement, and a custom async `verify()` hook. Missing cert → `401` problem+json with `Cache-Control: no-store`; any failed check → `403` (never echoes cert details). The accepted `ClientCertificate` is stamped on `ctx.state`. `parseForwardedClientCert()` / `normalizePeerCertificate()` exported standalone. Zero runtime dependencies.
+- `autoBan()` adaptive auto-ban (fail2ban-style) at `@daloyjs/core/auto-ban`: temporarily ban abusive clients after repeated suspicious responses (default `401` / `403` / `429`, configurable `watchStatuses`) within a rolling `windowMs`. Bans **escalate** exponentially for repeat offenders (`banMs` → `2×` → `4×`, capped at `maxBanMs`) and **decay** once the client goes quiet. Observes the outgoing status via `onSend` (counts failures from any downstream middleware/handler), enforces in `beforeHandle`. Secure-by-default identity attribution — refuses to construct without `keyGenerator` or `trustProxyHeaders` so one offender can never ban everyone; unattributable requests are skipped. Pluggable `AutoBanStore` (mirrors the `rateLimit()` store; in-memory default, Redis-able for multi-instance), `groupId` sharing across route groups, `429`/`403` ban response with `Retry-After`, and `onBan` / `onStrike` hooks. Zero runtime dependencies.
+- `botGuard()` bot / User-Agent management at `@daloyjs/core/bot-guard`: the in-app equivalent of Nginx/WAF bot rules. Blocks empty/missing `User-Agent` (default on) and known-abusive `User-Agent` strings / `RegExp`s, and **verifies declared crawlers** — a request claiming to be Googlebot/Bingbot is confirmed via reverse-DNS + forward-confirm (the method Google and Bing document), so a spoofed `User-Agent` can't impersonate a trusted crawler. Ships `GOOGLEBOT` / `BINGBOT` / `WELL_KNOWN_BOTS` presets and accepts custom `VerifiedBotRule`s. Allowlist-first (`allowUserAgents` bypasses every rule), secure-by-default (`verifiedBots` refuses to construct without an IP source; unverifiable crawlers blocked unless `blockUnverifiableBots: false`), subdomain-boundary-safe domain matching, per-IP verification cache to keep DNS off the hot path, `mode: "log"` monitor mode, `onBlock` callback, and a pluggable `BotResolver` (default lazy `node:dns/promises`). Zero runtime dependencies.
+- `ipReputation()` IP reputation / dynamic denylist feed at `@daloyjs/core/ip-reputation`: wires pluggable, periodically-refreshed abuse feeds (Tor exit lists, Spamhaus DROP, cloud-abuse ranges, or your own threat intel) into the request path without a redeploy, reusing the same SSRF-grade CIDR matcher as `ipRestriction()`. Ships `urlFeed()` (fetches newline / Spamhaus-DROP-style lists, skips comment lines, keeps good rows from a partially-malformed feed) plus a custom `IpReputationFeed` interface. **Fail-open by design** — a feed that can't be loaded (initial or refresh) never blocks traffic; the last-known-good list is retained per feed. Periodic `unref`'d refresh, `mode: "log"` monitor mode, `onMatch` / `onError` callbacks, manual `refresh()` / `stop()` / `has()` / `size` controller, and pluggable IP resolution (`trustProxyHeaders` / `resolveIp`). Zero runtime dependencies.
+- `geoBlock()` GeoIP / geo-blocking at `@daloyjs/core/geo-block`: country allow/deny middleware that maps the client IP to an ISO 3166-1 alpha-2 country and rejects (or logs) traffic from countries you don't serve. **No bundled GeoIP database and no runtime dependency** — supply either an operator-owned `lookupCountry(ip)` (a MaxMind / `ip2location` reader, or your own table, reusing the trusted-proxy `X-Forwarded-For` / `X-Real-IP` IP resolution) or a `resolveCountry(ctx)` that reads an edge-injected header (`CF-IPCountry`, `CloudFront-Viewer-Country`, `x-vercel-ip-country`). Deny wins over allow (least privilege); **allow-lists fail closed** on an unknown country while deny-only fails open (overridable via `allowUnknownCountry`). Country codes are validated at construction so typos throw instead of silently never matching. `mode: "log"` monitor mode with an `onBlock` decision hook (`denied_country` / `not_in_allowlist` / `unknown_country`), the resolved country stamped on `ctx.state.geo` for allowed requests, and a `403` problem+json rejection that never echoes the country/IP. Zero runtime dependencies.
+- `concurrencyLimit()` per-route / per-client concurrency limits + queueing at `@daloyjs/core/concurrency-limit`: HAProxy `maxconn`/queue parity at the app layer. Bounds in-flight requests through a surface with a per-bucket semaphore (`maxConcurrent`), a bounded FIFO queue (`maxQueue`) with an optional `queueTimeoutMs`, and a fast `503` + `Retry-After` once the queue is full or the wait times out. Partition the budget with `scope`: `"global"` (default), `"route"` (per `method + path`), `"client"` (per identity, needs `trustProxyHeaders`/`keyGenerator`), or a custom function (`undefined` skips limiting, fail-open). Acquires in `beforeHandle` and releases in `onSend`, so slots are freed on success, error, and short-circuit paths alike — never leaked. `onReject` observability hook, configurable `retryAfterSeconds`/`message`. Complements the `maxConnections` socket cap and `loadShedding()`. Zero runtime dependencies. HAProxy `maxconn`/queue parity at the app layer. Bounds in-flight requests through a surface with a per-bucket semaphore (`maxConcurrent`), a bounded FIFO queue (`maxQueue`) with an optional `queueTimeoutMs`, and a fast `503` + `Retry-After` once the queue is full or the wait times out. Partition the budget with `scope`: `"global"` (default), `"route"` (per `method + path`), `"client"` (per identity, needs `trustProxyHeaders`/`keyGenerator`), or a custom function (`undefined` skips limiting, fail-open). Acquires in `beforeHandle` and releases in `onSend`, so slots are freed on success, error, and short-circuit paths alike — never leaked. `onReject` observability hook, configurable `retryAfterSeconds`/`message`. Complements the `maxConnections` socket cap and `loadShedding()`. Zero runtime dependencies.
+- `requestDecompression()` inbound decompression-bomb guard at `@daloyjs/core/request-decompression`: core is safe by omission (it never decompresses request bodies), so this is the opt-in middleware for services that must accept compressed uploads. Inflates `gzip` / `deflate` bodies behind two caps enforced **during** inflation so a zip bomb is aborted before it is fully materialised: an absolute `maxDecompressedBytes` (required) and an expansion-ratio `maxRatio` (default `100`), both rejecting with `413`. The compressed upload itself is bounded by `maxCompressedBytes` (default 1 MiB) before a byte is inflated. Unknown, non-allowlisted, runtime-unsupported, or **layered** (`gzip, gzip`) encodings are refused `415`; malformed streams `400`; bodyless / uncompressed / `identity` / `GET` / `HEAD` traffic passes through untouched. Runs in `onRequest` and stashes the inflated bytes so schema-validated bodies and raw-body handlers both see the decompressed payload. `onBomb` observability hook, exported `decompressRequestBody()` for custom flows. Built on web-standard `DecompressionStream` (brotli excluded — not in the spec). Zero runtime dependencies.
+- `waf()` opt-in WAF-lite signature/anomaly inbound-inspection middleware at `@daloyjs/core/waf`: a first-party defense-in-depth layer for teams without an edge WAF (it does **not** replace ModSecurity / a CDN WAF). Wires DaloyJS' high-confidence injection signatures — SQLi, XSS, NoSQL-operator injection (reusing `hasMongoOperatorKeys` for a structural body check), and command injection — into a single scored inbound-inspection pass over the decoded path, the raw + decoded query string, an opt-in header allowlist, and the validated body. Each rule that fires adds an anomaly `score`; reaching `blockThreshold` (default `5`) rejects with a generic `403` (block mode) or merely reports via `onMatch` (log mode) so operators can tune against real traffic first. Per-rule enable/disable + score overrides, inspection-surface toggles, control-character-stripped log samples, and bounded scanning (`maxValueLength` / `maxBodyNodes`) keep a hostile payload from becoming CPU-DoS. The `403` body never names the rule that fired. Zero runtime dependencies.
+- Built-in docs UI Subresource Integrity (SRI): `DocsAssetOptions` lets `scalarHtml()` / `swaggerUiHtml()` and the `docs: { assets }` auto-mount pin version-exact `*Integrity` hashes (`sha256`/`sha384`/`sha512`) plus a `crossOrigin` value (default `"anonymous"`) on the CDN-loaded Scalar / Swagger UI `<script>` / `<link>` tags, so a poisoned jsDelivr asset can't execute. Malformed SRI values throw a `TypeError` at startup (browsers ignore unparseable `integrity`, so failing loud avoids a false sense of protection); self-hosting the assets via the same `assets` URLs stays supported. Zero runtime dependencies.
+- HTTP Message Signatures (RFC 9421) at `@daloyjs/core/http-signatures`: first-party sign/verify for server-to-server request authentication via the standard `Signature` / `Signature-Input` headers — complements the inbound-only webhook HMAC and `clientCertAuth()` mTLS. `signMessage()` / `signRequest()` build an RFC 9421 signature base over derived components (`@method`, `@target-uri`, `@authority`, `@scheme`, `@request-target`, `@path`, `@query`, `@query-param`, `@status`) and HTTP fields with Structured-Fields header serialization; `verifyMessage()` / `verifyRequest()` and the `httpSignatureAuth()` middleware check them. Algorithms `hmac-sha256` / `ed25519` / `ecdsa-p256-sha256` / `ecdsa-p384-sha384` / `rsa-pss-sha512` / `rsa-v1_5-sha256` via WebCrypto (no `node:` imports). Secure-by-default verify: a **mandatory `algorithms` allowlist** (no implicit "any alg"), optional per-key alg pinning to defeat algorithm-confusion, a required `created` timestamp with a 300s freshness window, `created`-in-future / `expires` skew rejection, configurable `requiredComponents`, a 32-byte raw-HMAC floor, and `nonce` replay defense; the middleware answers a missing/invalid signature with `401` + `Cache-Control: no-store` and stamps the verified result on `ctx.state.httpSignature`. Ships RFC 9530 `contentDigest()` / `verifyContentDigest()` to bind the request body. Zero runtime dependencies.
 - `compression()` built on web-standard `CompressionStream` (prefers `br` > `gzip` > `deflate`), with BREACH-aware always-on guards (skips `Set-Cookie`, `Authorization`, session / CSRF cookies, already-compressed content types), `minimumSize: 1024`, negative-compression-ratio post-check, no configurable `compressLevel` knob (CPU-DoS defense — `level: 9` is refused at construction), always-on `Vary: Accept-Encoding`, and strong → weak ETag downgrade per RFC 9110 §8.8.3.
 - `etag()` helper auto-skips on `Set-Cookie` and private / no-store / no-cache `Cache-Control` (cross-tenant fingerprinting defense).
 - `timing` / `timingSafeEqual` helpers.
@@ -507,6 +525,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`).
 
 ### Lifecycle and ops
 
@@ -536,9 +555,9 @@ A growing suite of static gates runs on every push and PR:
 
 - Parity / governance / runtime-parity / routing-hardening audits: `verify:parity-audits`, `verify:governance-audits`, `verify:runtime-parity-audits`, `verify:routing-hardening-audits`.
 - Source-tree gates: `verify:no-shrinkwrap`, `verify:no-bin-shadowing`, `verify:no-native-addons`, `verify:no-polyfill-cdns` (hijacked-CDN IOCs and typosquats), `verify:no-redos-patterns`, `verify:no-encoded-payloads`, `verify:no-invisible-unicode`, `verify:no-weak-random`, `verify:no-unsafe-buffer`, `verify:no-leaked-credentials`, `verify:no-vulnerable-sandboxes`.
-- Agent-skill gates: `verify:no-leaky-agent-skills`, `verify:no-toxic-agent-skills`, `verify:no-toxic-skills`.
+- Agent-skill gates: `verify:no-leaky-agent-skills`, `verify:no-toxic-agent-skills`, `verify:no-toxic-skills` — scanning every agent-instruction surface (`SKILL.md`, `AGENTS.md`, `copilot-instructions.md`, `.cursorrules`, `CLAUDE.md`, `*.instructions.md`, `*.prompt.md`); the `.cursorrules` / `CLAUDE.md` filenames cover the **TrapDoor** crypto-stealer's AI-agent-config prompt-injection persistence ([Socket, 2026-05-24](https://socket.dev/blog/trapdoor-crypto-stealer)).
 - Dependency gates: `verify:no-runtime-deps`, `verify:dep-licenses`, `verify:known-dep-names`, `verify:lockfile-sources`, `verify:no-registry-exfiltration`, `verify:no-remote-exec`, `verify:no-lifecycle-scripts`, `verify:runtime-eol` (refuses to release on a Node line past its EOL date).
-- IOC coverage in `verify:no-registry-exfiltration` and `verify:lockfile-sources` for active campaigns including Beamglea phishing-CDN, `naya-flore` / `nvlore-hsc` WhatsApp remote-kill-switch, the Toptal GitHub-org hijack, `xuxingfeng` and `xlsx-to-json-lh` destructive payloads, `react-login-page` keylogger, `@crypto-exploit` wallet drainers, Vietnam-Telegram-ban Fastlane typosquats, surveillance-malware packages, the Discord-webhook reconnaissance campaign, and npm-package-aliasing dependency-confusion patterns.
+- IOC coverage in `verify:no-registry-exfiltration` and `verify:lockfile-sources` for active campaigns including Beamglea phishing-CDN, `naya-flore` / `nvlore-hsc` WhatsApp remote-kill-switch, the Toptal GitHub-org hijack, `xuxingfeng` and `xlsx-to-json-lh` destructive payloads, `react-login-page` keylogger, `@crypto-exploit` wallet drainers, Vietnam-Telegram-ban Fastlane typosquats, surveillance-malware packages, the Discord-webhook reconnaissance campaign, the `codexui-android` AI-coding-agent token theft (reads of `~/.codex/auth.json` / `~/.claude/`), and npm-package-aliasing dependency-confusion patterns.
 - `SECURITY-CONTACTS.md` rotation file with a machine-readable ACTIVE block and `<!-- last-exercise: -->` marker; the release workflow refuses to publish when `github.actor` is not on the ACTIVE rotation.
 - Governance floor reaffirmed by audit: top-level `permissions:` on every workflow, `persist-credentials: false` on every `actions/checkout`, 40-hex SHA pinning on every third-party `uses:`, `step-security/harden-runner` on every workflow using third-party actions, and `.github/CODEOWNERS` on privileged files.
 - Mandatory hardware-backed 2FA for every contributor with publish access (documented in `SECURITY.md`).

package/bin/daloy.mjs

@@ -10,6 +10,7 @@
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { resolve, dirname } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { runCli } from "../dist/cli.js";
 
@@ -83,6 +84,7 @@ const result = await runCli(process.argv.slice(2), {
   importEntry,
   version: PKG.version,
   spawn: spawnDev,
+  readTextFile: (path) => readFile(resolve(process.cwd(), path), "utf8"),
 });
 
 process.exit(result.exitCode);

package/dist/adapters/bun.js

@@ -15,15 +15,22 @@ export function serve(app, opts = {}) {
                 return app.fetch(req);
             }
             : (req) => app.fetch(req),
-        error: (err) => new Response(JSON.stringify({
-            type: "https://daloyjs.dev/errors/internal",
-            title: "Internal Server Error",
-            status: 500,
-            detail: err.message,
-        }), {
-            status: 500,
-            headers: { "content-type": "application/problem+json" },
-        }),
+        error: (err) => {
+            // Last-resort handler reached only if app.fetch itself throws (it
+            // normally catches everything). Log the error server-side but never
+            // echo `err.message` to the client — that would leak internal details
+            // and bypass the framework's prod-mode error redaction. Mirrors the
+            // redacted problem+json body the Node adapter emits in writeAdapterError.
+            app.log.error({ err }, "Unhandled error in Bun fetch handler");
+            return new Response(JSON.stringify({
+                type: "https://daloyjs.dev/errors/internal",
+                title: "Internal Server Error",
+                status: 500,
+            }), {
+                status: 500,
+                headers: { "content-type": "application/problem+json" },
+            });
+        },
     };
     if (hasWs)
         cfg.websocket = buildBunWebSocketConfig(app);

package/dist/adapters/deno.js

@@ -32,14 +32,20 @@ export function serve(app, opts = {}) {
         if (stopped)
             return;
         stopped = true;
-        controller.abort();
         opts.signal?.removeEventListener("abort", onSignal);
         if (opts.handleSignals !== false && typeof D?.removeSignalListener === "function") {
             D.removeSignalListener("SIGTERM", onSignal);
             D.removeSignalListener("SIGINT", onSignal);
         }
+        // Drain app-level hooks first (while the HTTP server can still respond),
+        // then ask Deno to stop gracefully — `server.shutdown()` stops accepting
+        // new connections and lets in-flight requests finish. Aborting the listen
+        // signal happens last, purely as a safety net for runtimes that lack
+        // `HttpServer.shutdown()`. Doing it the other way around (aborting first)
+        // tears the listener down before in-flight requests can complete.
         await app.shutdown(opts.shutdownTimeoutMs ?? 10_000);
         await server.shutdown?.();
+        controller.abort();
     };
     return { shutdown };
 }

package/dist/adapters/node.d.ts

@@ -16,6 +16,17 @@ export interface NodeServerOptions {
     handleSignals?: boolean;
     /** Maximum HTTP header size bytes (DoS protection). Default: 16 KiB. */
     maxHeaderBytes?: number;
+    /**
+     * Maximum number of concurrent sockets the server will accept, forwarded to
+     * Node's `server.maxConnections`. Acts as connection-layer admission
+     * control: once the limit is reached, additional incoming connections are
+     * rejected at accept time instead of being queued into the event loop,
+     * where they would otherwise inflate tail latency for everyone under
+     * overload. Pair it with an upstream load balancer / API gateway that
+     * translates the rejection into a `503 Retry-After` for clients. Leave
+     * unset for Node's default (unbounded). Default: unset.
+     */
+    maxConnections?: number;
     /**
      * When true, honor `x-forwarded-proto` and `x-forwarded-host` headers when
      * constructing the request URL. Enable this only when running behind a

package/dist/adapters/node.js

@@ -5,6 +5,7 @@
 import { createServer, } from "node:http";
 import { Readable } from "node:stream";
 import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY } from "../app.js";
+import { setClientCertificate, normalizePeerCertificate, } from "../mtls.js";
 import { FrameSink, encodeFrame, encodeClosePayload, encodeSendPayload, validateUpgrade, validateSelectedSubprotocol, checkWebSocketOrigin, WS_OPCODE, WS_CLOSE_CODE, WS_READY_STATE, WS_MAX_CONTROL_PAYLOAD, WebSocketProtocolError, WebSocketPayloadTooLargeError, } from "../websocket.js";
 /** Start a Node.js HTTP (and optional WebSocket) server bound to the given {@link App}. */
 export function serve(app, opts = {}) {
@@ -35,6 +36,11 @@ export function serve(app, opts = {}) {
     server.requestTimeout = opts.connectionTimeoutMs ?? 30_000;
     server.headersTimeout = opts.connectionTimeoutMs ?? 30_000;
     server.keepAliveTimeout = 5_000;
+    // Connection-layer admission control. Reject overflow sockets at accept time
+    // rather than queuing them into the event loop under overload.
+    if (typeof opts.maxConnections === "number" && opts.maxConnections > 0) {
+        server.maxConnections = opts.maxConnections;
+    }
     const wsSockets = new Set();
     if (app.webSocketRoutes.size > 0) {
         server.on("upgrade", (req, socket, head) => {
@@ -90,6 +96,7 @@ function dispatchToApp(app, req, res, trustProxy, bufferedBody) {
         writeAdapterError(res, e);
         return;
     }
+    attachClientCertificate(req, request);
     const responseOrPromise = app.fetch(request);
     if (responseOrPromise instanceof Promise) {
         responseOrPromise.then((response) => {
@@ -175,6 +182,23 @@ function bufferRequestBody(req, expected) {
         req.on("aborted", onErr);
     });
 }
+/**
+ * Attach the TLS client certificate (if any) to the web `Request` so
+ * `clientCertAuth()` can enforce a mutual-TLS identity. The read is deferred
+ * behind a lazy thunk and only happens when a guarded route actually inspects
+ * the certificate, so plain-HTTP and ordinary TLS requests pay nothing beyond a
+ * single `encrypted` boolean check. Only runs when the peer socket is a
+ * `TLSSocket` exposing `getPeerCertificate`.
+ */
+function attachClientCertificate(req, request) {
+    const sock = req.socket;
+    if (!sock.encrypted || typeof sock.getPeerCertificate !== "function")
+        return;
+    setClientCertificate(request, () => {
+        const raw = sock.getPeerCertificate(true);
+        return normalizePeerCertificate(raw, sock.authorized === true);
+    });
+}
 function writeAdapterError(res, e) {
     if (!res.headersSent) {
         res.statusCode = 500;

package/dist/app.d.ts

@@ -2,9 +2,11 @@ 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 DocsContentSecurityPolicyOptions, type ScalarReferenceConfiguration } from "./docs.js";
+import { type DocsAssetOptions, type DocsContentSecurityPolicyOptions, type ScalarReferenceConfiguration } from "./docs.js";
 import { type SecureHeadersOptions } from "./middleware.js";
 import { type LoadSheddingOptions } from "./load-shedding.js";
+import { MetricsRegistry, type HttpMetricsOptions } from "./metrics.js";
+import { Scheduler, type TaskDefinition, type TaskHandler } from "./scheduler.js";
 import { type BehindProxyConfig } from "./conn-info.js";
 /** @internal Test-only helper to reset the latch between tests. */
 export declare function _resetCrashHandlersForTests(): void;
@@ -359,6 +361,15 @@ export interface DocsRouteOptions {
      * Forwarded to {@link docsContentSecurityPolicy}.
      */
     csp?: DocsContentSecurityPolicyOptions;
+    /**
+     * Override the docs UI asset URLs and pin Subresource Integrity (SRI)
+     * hashes so the browser refuses to execute a CDN asset whose bytes don't
+     * match. Pair each `*Integrity` hash with a version-pinned `*Url`, or point
+     * the URLs at self-hosted copies. See {@link DocsAssetOptions}.
+     *
+     * @since 0.37.0
+     */
+    assets?: DocsAssetOptions;
 }
 /** Information passed to {@link App.onPluginInstalled} listeners. */
 export interface PluginInstalledEvent {
@@ -434,6 +445,68 @@ export interface HealthRouteOptions {
      */
     acknowledgeUnauthenticated?: boolean;
 }
+/**
+ * Configuration accepted by {@link App.metrics}. Every field is optional.
+ *
+ * The `/metrics` route inherits the same hardened posture as
+ * {@link App.healthcheck}: an optional `Authorization: Bearer <token>`
+ * compared via {@link timingSafeEqual}, a per-IP fixed-window rate limit,
+ * and a refuse-to-boot guard that blocks an unauthenticated scrape endpoint
+ * in production (metrics leak internal route names, latency, and request
+ * volume) unless a token is set or {@link MetricsRouteOptions.acknowledgeUnauthenticated}
+ * is `true`.
+ *
+ * @since 0.37.0
+ */
+export interface MetricsRouteOptions {
+    /** Override the default path (`/metrics`). */
+    path?: PathString;
+    /**
+     * Require `Authorization: Bearer <token>` on the scrape request, compared
+     * via {@link timingSafeEqual}. When set in production with
+     * `secureDefaults: true`, no further opt-in is required.
+     */
+    token?: string;
+    /**
+     * Per-IP fixed-window rate limit. Defaults to `{ limit: 60, windowMs:
+     * 60_000 }` (in-memory, per-process). Pass `false` to disable.
+     */
+    rateLimit?: {
+        limit?: number;
+        windowMs?: number;
+    } | false;
+    /**
+     * Acknowledge that the scrape endpoint is intentionally reachable without
+     * credentials in production. Required when `secureDefaults` is on and
+     * `token` is omitted; otherwise registration throws.
+     */
+    acknowledgeUnauthenticated?: boolean;
+    /**
+     * Registry the RED metrics are recorded into and rendered from. Defaults
+     * to a fresh {@link MetricsRegistry}. Pass your own to register custom
+     * application metrics alongside the built-in HTTP series.
+     */
+    registry?: MetricsRegistry;
+    /**
+     * Resolve the low-cardinality `route` label. Strongly recommended: return
+     * the route template (e.g. `/books/:id`) instead of the raw path.
+     * Forwarded to {@link httpMetrics}.
+     */
+    route?: HttpMetricsOptions["route"];
+    /**
+     * Maximum distinct values for the default pathname-derived `route` label
+     * before further values collapse to `"<other>"`. Forwarded to
+     * {@link httpMetrics}. Default `100`.
+     */
+    maxRouteCardinality?: number;
+    /** Latency histogram buckets, in seconds. Forwarded to {@link httpMetrics}. */
+    buckets?: readonly number[];
+    /**
+     * Skip RED instrumentation for matching request paths, in addition to the
+     * scrape path itself (always excluded). Forwarded to {@link httpMetrics}.
+     */
+    exclude?: (path: string) => boolean;
+}
 /**
  * Configuration accepted by {@link App.cspReportRoute}. Every field is
  * optional.
@@ -626,6 +699,12 @@ export declare class App {
     private installedPlugins;
     private closeHooks;
     private closeHooksRun;
+    /**
+     * Lazily-created in-process scheduler backing {@link App.cron}. Started on
+     * the first `cron()` call and stopped from an `onClose` hook so its lifecycle
+     * is tied to graceful shutdown.
+     */
+    private scheduler?;
     /** Idle-connection close hooks (adapter-registered, sync). */
     private idleConnectionCloseHooks;
     private pluginInstalledListeners;
@@ -888,6 +967,70 @@ export declare class App {
      * @since 0.18.0
      */
     readinesscheck(opts?: HealthRouteOptions): this;
+    /**
+     * Register an opt-in, auth-guarded Prometheus / OpenMetrics scrape route
+     * and install RED (Rate / Errors / Duration) instrumentation for every
+     * route registered **after** this call. The third observability pillar
+     * alongside the structured logger and the OpenTelemetry tracer.
+     *
+     * Exposes, in the Prometheus text exposition format:
+     * - `<prefix>http_requests_total{method,route,status}` — request counter,
+     * - `<prefix>http_request_duration_seconds{method,route}` — latency histogram,
+     * - `<prefix>http_requests_in_flight` — concurrency gauge,
+     * - process gauges (resident memory, heap used, uptime) on Node-like runtimes.
+     *
+     * The scrape route inherits the same hardened posture as
+     * {@link App.healthcheck}: optional bearer token compared via
+     * {@link timingSafeEqual}, a per-IP fixed-window rate limit, and a
+     * refuse-to-boot guard in production (an unauthenticated `/metrics`
+     * endpoint leaks internal route names, latency, and traffic volume) unless
+     * a token is supplied or `acknowledgeUnauthenticated: true` is passed.
+     *
+     * Call this **before** registering the routes you want measured — like any
+     * `app.use(...)` middleware, the instrumentation only wraps routes added
+     * afterwards. Pass `opts.registry` to register custom application metrics
+     * that are rendered alongside the built-in HTTP series.
+     *
+     * @param opts - Path, auth, rate-limit, registry, and label configuration.
+     * @returns `this` for chaining.
+     * @since 0.37.0
+     */
+    metrics(opts?: MetricsRouteOptions): this;
+    /**
+     * Register an in-process scheduled task (cron). The first call lazily creates
+     * an app-managed {@link Scheduler}, wires it to the app logger, starts it,
+     * and registers an `onClose` hook so it is drained on graceful shutdown
+     * (in-flight runs are awaited, then aborted if they outlast the shutdown
+     * grace period).
+     *
+     * The schedule is **queue-agnostic** — it runs work in *this* process on a
+     * fixed interval or cron expression. Use it for periodic maintenance
+     * (cache sweeps, token refresh, reconciliation) rather than as a distributed
+     * job queue. Each task is **single-flight**: if a tick fires while the
+     * previous run is still in progress, the tick is skipped and counted, so a
+     * slow task can never pile up overlapping runs.
+     *
+     * @example
+     * ```ts
+     * app.cron({ name: "sweep", cron: "0 * * * *" }, async ({ signal }) => {
+     *   await purgeExpiredSessions({ signal });
+     * });
+     * ```
+     *
+     * @param def - The task definition. Exactly one of `intervalMs` or `cron`.
+     * @param handler - The function to run on each tick.
+     * @returns This `App` instance for chaining.
+     * @throws {RangeError} on invalid options (see {@link Scheduler.define}).
+     * @throws {@link CronParseError} if a `cron` expression is malformed.
+     */
+    cron(def: TaskDefinition, handler: TaskHandler): this;
+    /**
+     * The app-managed {@link Scheduler} backing {@link App.cron}, or `undefined`
+     * if no scheduled task has been registered. Exposed for inspection
+     * (`getState()` / `list()`) and manual triggering (`runNow()`); the lifecycle
+     * is owned by the app.
+     */
+    get scheduledTasks(): Scheduler | undefined;
     private registerHealthRoute;
     /**
      * Register a built-in receiver for CSP / Reporting API