@daloyjs/core 0.35.1 → 0.36.0

package/README.md

@@ -466,6 +466,7 @@ The framework refuses to start (or to construct) when configuration is unsafe:
 
 - Weak session secrets, `cors({ origin: "*" })` with credentials, `session()` + state-changing route without `csrf()`, and unconfigured `X-Forwarded-*` in production.
 - `secureDefaults: false` in production unless `acknowledgeInsecureDefaults: true` is set, plus a once-per-process `error` log naming every disabled default.
+- `preset: "internal-service"` topology preset for service-to-service deployments behind a mesh / sidecar / private network: turns OFF the browser-only guards (auto `secureHeaders`, `corsCrossOriginGuard`, `csrf` boot guard, unconfigured `X-Forwarded-*` guard) while keeping every input, parser, credential, SSRF, weak-secret, and refuse-to-boot guard ON. Per-knob options still win, the choice is logged at boot under `event: "security.preset.applied"`, and the live posture is auditable via `app.getSecurityPosture()`.
 - `createJwtSigner()` / `createJwtVerifier()` refuse `alg: "none"`, accept only an explicit allowlist, refuse HS + JWK combinations, refuse to sign without `exp`, and refuse HS-shaped secrets under 32 bytes (RFC 7518 §3.2).
 - `secureHeaders()` refuses to construct with `frameOptions: false` AND no CSP `frame-ancestors` directive (no clickjacking defense).
 - `cors()` refuses `methods: ['*']` at construction; default `allowMethods` narrowed to `[GET, HEAD, POST]` so `PUT` / `PATCH` / `DELETE` become explicit opt-ins.

package/dist/adapters/node.d.ts

@@ -23,6 +23,17 @@ export interface NodeServerOptions {
      * clients can spoof the scheme/host. Default: false.
      */
     trustProxy?: boolean;
+    /**
+     * Maximum declared `Content-Length` (in bytes) for which the Node adapter
+     * pre-buffers the request body into a `Uint8Array` before constructing the
+     * `Request`. Bodies above this threshold fall back to the streaming
+     * `Readable.toWeb(req)` path so the adapter never holds an unbounded buffer
+     * per in-flight request — important under high concurrency where N
+     * simultaneous large uploads would otherwise pin N × threshold bytes of
+     * memory. The threshold is independently capped by `App.bodyLimitBytes`,
+     * which is the actual security limit. Default: 256 KiB.
+     */
+    bufferedBodyMaxBytes?: number;
 }
 /** Handle returned by {@link serve} exposing the underlying Node `Server` plus a `close()` for graceful shutdown. */
 export interface NodeServerHandle {

package/dist/adapters/node.js

@@ -4,11 +4,14 @@
  */
 import { createServer, } from "node:http";
 import { Readable } from "node:stream";
-import { DALOY_RAW_BODY } from "../app.js";
+import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY } from "../app.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 = {}) {
     const trustProxy = opts.trustProxy === true;
+    const bufferedBodyMaxBytes = typeof opts.bufferedBodyMaxBytes === "number" && opts.bufferedBodyMaxBytes >= 0
+        ? opts.bufferedBodyMaxBytes
+        : DEFAULT_BUFFERED_BODY_MAX_BYTES;
     const server = createServer({ maxHeaderSize: opts.maxHeaderBytes ?? 16 * 1024 }, (req, res) => {
         // GET/HEAD: no body work, dispatch directly. Keep this first so the GET
         // hot path doesn't pay for any of the buffering bookkeeping below.
@@ -23,7 +26,7 @@ export function serve(app, opts = {}) {
         // WHATWG-stream adapter that dominates POST throughput on Node.
         const cl = req.headers["content-length"];
         const n = cl ? Number(cl) : NaN;
-        if (Number.isFinite(n) && n >= 0 && n <= BUFFERED_BODY_MAX_BYTES) {
+        if (Number.isFinite(n) && n >= 0 && n <= bufferedBodyMaxBytes) {
             bufferRequestBody(req, n).then((bytes) => dispatchToApp(app, req, res, trustProxy, bytes), (e) => writeAdapterError(res, e));
             return;
         }
@@ -70,12 +73,14 @@ export function serve(app, opts = {}) {
     return { server, port, close };
 }
 /**
- * Maximum content-length (in bytes) that the Node adapter will pre-buffer
- * before constructing the `Request`. Bodies above this fall back to the
- * streaming `Readable.toWeb` path so unbounded uploads can't exhaust
- * adapter memory. 1 MiB matches the default `App.bodyLimitBytes`.
+ * Default pre-buffer ceiling for the Node adapter. 256 KiB is a compromise:
+ * large enough that the vast majority of JSON / form requests stay on the
+ * fast (Uint8Array) path, small enough that N concurrent in-flight bodies
+ * don't pin huge amounts of memory. Override via
+ * {@link NodeServerOptions.bufferedBodyMaxBytes}. The actual security cap
+ * on body size remains `App.bodyLimitBytes`.
  */
-const BUFFERED_BODY_MAX_BYTES = 1024 * 1024;
+const DEFAULT_BUFFERED_BODY_MAX_BYTES = 256 * 1024;
 function dispatchToApp(app, req, res, trustProxy, bufferedBody) {
     let request;
     try {
@@ -111,21 +116,31 @@ function dispatchToApp(app, req, res, trustProxy, bufferedBody) {
 }
 function bufferRequestBody(req, expected) {
     return new Promise((resolve, reject) => {
-        const chunks = [];
+        // Pre-allocate to the declared Content-Length. The caller has already
+        // checked `expected <= BUFFERED_BODY_MAX_BYTES` (1 MiB) so this
+        // allocation is bounded and DoS-safe. Skipping the intermediate
+        // `chunks: Buffer[]` array + `Buffer.concat` avoids one full-body
+        // copy per request — significant at 1 MiB bodies under load.
+        // Use `Buffer.alloc` (zero-filled) rather than `Buffer.allocUnsafe`:
+        // the unsafe variant returns uninitialized memory and is forbidden by
+        // `verify:no-unsafe-buffer`. Any unwritten tail is sliced off below.
+        const out = expected > 0 ? Buffer.alloc(expected) : null;
         let received = 0;
         let settled = false;
         const onData = (chunk) => {
             if (settled)
                 return;
-            received += chunk.length;
-            if (received > expected) {
+            const next = received + chunk.length;
+            if (next > expected) {
                 settled = true;
                 cleanup();
                 req.destroy();
                 reject(new Error("Request body exceeded declared Content-Length"));
                 return;
             }
-            chunks.push(chunk);
+            // out is non-null here because next > 0 implies expected > 0.
+            chunk.copy(out, received);
+            received = next;
         };
         const onEnd = () => {
             if (settled)
@@ -136,7 +151,9 @@ function bufferRequestBody(req, expected) {
                 resolve(new Uint8Array(0));
                 return;
             }
-            const buf = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks, received);
+            // Trust Content-Length: if the client under-delivered we still
+            // resolve the prefix actually received (matches prior behavior).
+            const buf = received === expected ? out : out.subarray(0, received);
             resolve(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
         };
         const onErr = (err) => {
@@ -184,23 +201,40 @@ function toWebRequest(req, trustProxy, bufferedBody) {
     const proto = forwardedProto ??
         (req.socket.encrypted ? "https" : "http");
     const url = `${proto}://${host}${req.url ?? "/"}`;
-    const headers = new Headers();
-    for (const k in reqHeaders) {
-        const v = reqHeaders[k];
-        if (v === undefined)
+    // Build headers from `rawHeaders` (a flat [k0,v0,k1,v1,...] array) instead
+    // of the parsed `req.headers` object. This matches @hono/node-server's
+    // `newHeadersFromIncoming`: one `new Headers([[k,v],...])` constructor
+    // call rather than N `headers.set()` calls. It is also stricter for
+    // duplicate-Host smuggling — Node coalesces some singleton headers down
+    // to the first value on `req.headers`, but `rawHeaders` preserves every
+    // occurrence so `assertNoDuplicateSingletonHeaders` actually sees them.
+    // Skip HTTP/2 pseudo-headers (leading ':') defensively, even though
+    // node:http's createServer is HTTP/1.1 only today.
+    const rawHeaders = req.rawHeaders;
+    const headerPairs = [];
+    for (let i = 0; i < rawHeaders.length; i += 2) {
+        const k = rawHeaders[i];
+        if (k.charCodeAt(0) === 58 /* ':' */)
             continue;
-        headers.set(k, Array.isArray(v) ? v.join(", ") : v);
+        headerPairs.push([k, rawHeaders[i + 1]]);
     }
+    const headers = new Headers(headerPairs);
     const method = req.method ?? "GET";
     if (method === "GET" || method === "HEAD") {
         return new Request(url, { method, headers });
     }
     if (bufferedBody !== undefined) {
-        return new Request(url, {
+        const req2 = new Request(url, {
             method,
             headers,
             body: bufferedBody,
         });
+        // Stash the validated bytes so readBodyLimited (and any other internal
+        // body reader) can skip the WHATWG ReadableStream reader loop. The
+        // adapter has already enforced BUFFERED_BODY_MAX_BYTES + Content-Length
+        // here; readBodyLimited re-checks against the caller's limit.
+        req2[DALOY_REQUEST_RAW_BODY] = bufferedBody;
+        return req2;
     }
     return new Request(url, {
         method,
@@ -234,6 +268,30 @@ function sendWebResponse(res, out) {
         }
         return;
     }
+    // Fast-path: handler returned a raw stream. Check before `!res.body` —
+    // a Node Readable is stashed alongside a null Response body, and the
+    // `new Response(null)` constructor also auto-sets `content-length: 0`
+    // which we must strip so Node falls back to chunked transfer-encoding.
+    const rawStream = res[DALOY_RAW_STREAM];
+    if (rawStream !== undefined) {
+        if (typeof rawStream.pipe === "function" && !(rawStream instanceof ReadableStream)) {
+            // Node `Readable` from the handler: skip the Web-stream bridge entirely
+            // and `.pipe(out)` like Fastify/Koa/Express do.
+            out.removeHeader("content-length");
+            return new Promise((resolve, reject) => {
+                const r = rawStream;
+                const onError = (err) => {
+                    r.destroy();
+                    reject(err);
+                };
+                r.once("error", onError);
+                out.once("error", onError);
+                out.once("finish", () => resolve());
+                r.pipe(out);
+            });
+        }
+        return pumpBody(rawStream, out);
+    }
     if (!res.body) {
         out.end();
         return;
@@ -253,16 +311,20 @@ function sendWebResponse(res, out) {
     }
     return pumpBody(res.body, out);
 }
-async function pumpBody(body, out) {
-    const reader = body.getReader();
-    while (true) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        if (value)
-            out.write(value);
-    }
-    out.end();
+function pumpBody(body, out) {
+    // Delegate to Node's native pipe: it honors backpressure and avoids the
+    // per-chunk microtask overhead of an explicit `await reader.read()` loop.
+    return new Promise((resolve, reject) => {
+        const readable = Readable.fromWeb(body);
+        const onError = (err) => {
+            readable.destroy();
+            reject(err);
+        };
+        readable.once("error", onError);
+        out.once("error", onError);
+        out.once("finish", () => resolve());
+        readable.pipe(out);
+    });
 }
 // ---------- WebSocket upgrade ----------
 async function handleUpgrade(app, req, socket, head, trustProxy) {

package/dist/app.d.ts

@@ -10,6 +10,33 @@ import { type BehindProxyConfig } from "./conn-info.js";
 export declare function _resetCrashHandlersForTests(): void;
 /** @internal Test-only helper to reset the latch between tests. */
 export declare function _resetInsecureDefaultsLogForTests(): void;
+/**
+ * Named security posture preset. Currently only one value is supported:
+ *
+ * - `"internal-service"` — relaxes the *topology-dependent* defaults that
+ *   only make sense when an HTTP boundary faces a browser or the public
+ *   internet (auto `secureHeaders`, cross-origin write guard, the
+ *   session+state-changing-route CSRF boot guard, and the unconfigured
+ *   `X-Forwarded-*` guard). Everything that protects the service from
+ *   malformed input, confused dependencies, or compromised callers —
+ *   body limits, request timeouts, JWT algorithm allowlists, weak-secret
+ *   refuse-to-boot, `cors({ origin: '*' })` refuse-to-boot, anonymous
+ *   stateful plugin refuse-to-boot, `crashOnUnhandledRejection`, schema
+ *   strictness, prototype-pollution-safe parsers, SSRF-safe `fetchGuard`
+ *   defaults, RFC 9457 problem+json redaction — stays on. Per-knob
+ *   options still win (`secureHeaders: { ... }` re-enables it on top of
+ *   the preset). The preset choice is logged once at boot under the
+ *   `security.preset.applied` event so operators can audit the posture
+ *   without reading code.
+ *
+ * Topology presets are intentionally a small, curated set — they are NOT
+ * a master "disable everything" knob. If you really need to disable the
+ * entire secure-by-default surface, use the explicit
+ * {@link AppOptions.secureDefaults} `false` escape hatch.
+ *
+ * @since 0.34.0
+ */
+export type SecurityPreset = "internal-service";
 /**
  * Configuration accepted by {@link App}'s constructor. Every field is
  * optional; sensible production defaults are applied.
@@ -21,6 +48,23 @@ export interface AppOptions {
     title?: string;
     version?: string;
     description?: string;
+    /**
+     * Topology-aware security posture preset. See {@link SecurityPreset}.
+     *
+     * - `"internal-service"` — for service-to-service deployments behind a
+     *   service mesh, sidecar, or private network. Turns off the
+     *   browser-/edge-only guards (auto `secureHeaders`, cross-origin write
+     *   guard, session+state-changing CSRF boot guard, unconfigured
+     *   `X-Forwarded-*` guard) while keeping every input-, parser-,
+     *   credential-, and SSRF-level guard on. The choice is logged once at
+     *   boot under the `security.preset.applied` event. Per-knob options
+     *   you pass alongside the preset still win.
+     *
+     * Omit (default) for browser-facing / public APIs.
+     *
+     * @since 0.34.0
+     */
+    preset?: SecurityPreset;
     /** Validate handler responses against declared response schemas. Default: true. */
     validateResponses?: boolean;
     /** Hard cap on request body size in bytes. Default: 1 MiB. */
@@ -480,6 +524,25 @@ export interface IntrospectedRoute {
  * implementation detail — userland code should never depend on it.
  */
 export declare const DALOY_RAW_BODY: unique symbol;
+/**
+ * Internal Symbol used by adapters to stash a pre-buffered request body on
+ * the `Request` instance. When set, {@link readBodyLimited} skips the
+ * `ReadableStream` reader loop and returns the cached bytes directly after
+ * re-checking them against the caller-supplied limit. Adapters MUST only
+ * attach bytes they have already validated against the configured
+ * {@link AppOptions.bodyLimitBytes}; the limit re-check in
+ * `readBodyLimited` is defense-in-depth, not the primary cap. Module-public
+ * so first-party adapters can opt in; not part of the userland API surface.
+ */
+export declare const DALOY_REQUEST_RAW_BODY: unique symbol;
+/**
+ * Internal Symbol set by handlers/serializers to attach a raw stream
+ * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node
+ * adapter pipes the stream straight to the socket, skipping the
+ * Web-stream reader bridge. Module-public so first-party adapters can
+ * opt in; userland code should not depend on it.
+ */
+export declare const DALOY_RAW_STREAM: unique symbol;
 /**
  * Contract-first HTTP application.
  *
@@ -535,6 +598,14 @@ export declare class App {
     /** Public registry: enables OpenAPI gen, typed-client gen, dead-route detection. */
     readonly routes: RouteDefinition<any, any, any, any>[];
     private router;
+    /**
+     * Memoized result of `isProduction()`. The inputs (`options.env`,
+     * `options.production`, `process.env.NODE_ENV`) cannot change between
+     * the moment a route is dispatched and the moment its error is rendered,
+     * so reading `process.env.NODE_ENV` on every error response is wasted
+     * work in the hot path. Computed lazily on first read.
+     */
+    private _productionCache;
     /** WebSocket route registry. Adapters look up handlers via `app.webSocketRoutes.find()`. */
     readonly webSocketRoutes: WebSocketRegistry;
     private prefix;
@@ -545,6 +616,13 @@ export declare class App {
     private routeSecurityMarkers;
     /** Decorator bag merged into ctx.state on every request. */
     private decorations;
+    /**
+     * Count of own keys on {@link decorations}. Tracked alongside the bag so the
+     * dispatch hot path can take a `count === 0` fast path and skip the
+     * `Object.assign` spread on the common case (no `app.decorate()` calls).
+     * Updated only when {@link decorate} mutates the bag.
+     */
+    private decorationsCount;
     private installedPlugins;
     private closeHooks;
     private closeHooksRun;
@@ -608,6 +686,41 @@ export declare class App {
      *    set deep in shared configuration.
      */
     private assertInsecureDefaultsAcknowledged;
+    /**
+     * Emit the one-time boot audit entry for an applied security preset.
+     * Called from the constructor with the *original* (pre-preset) options
+     * so the log captures which fields the preset filled in vs. which the
+     * caller set explicitly. Logged at `info` so the line shows up in
+     * standard production log shipping without being noisy.
+     *
+     * Operators can audit the live posture at any time through
+     * {@link App.getSecurityPosture}.
+     *
+     * @since 0.34.0
+     */
+    private logSecurityPresetIfApplied;
+    /**
+     * Structured snapshot of the live security posture. Returns the same
+     * data the constructor logs under the `security.preset.applied` audit
+     * event plus the resolved values of every secure-by-default knob, so
+     * operators can build a `/__security` introspection route or a CI
+     * audit without parsing the framework source.
+     *
+     * @since 0.34.0
+     */
+    getSecurityPosture(): {
+        preset: SecurityPreset | undefined;
+        secureDefaults: boolean;
+        secureHeaders: boolean;
+        corsCrossOriginGuard: boolean;
+        csrf: "off" | "on";
+        crashOnUnhandledRejection: boolean | "default";
+        trustProxy: true | false | "unconfigured";
+        bodyLimitBytes: number;
+        requestTimeoutMs: number;
+        stripServerHeaders: boolean;
+        production: boolean;
+    };
     /**
      * Install the secure-by-default global hooks. Currently:
      *  - {@link secureHeaders} as a group-level hook so every response carries