@blamejs/core 0.8.43 → 0.8.49

package/lib/router.js

@@ -1,23 +1,36 @@
 "use strict";
 /**
- * Custom HTTP router — zero-dependency replacement for express/koa/fastify.
+ * @module b.router
+ * @featured true
+ * @nav    HTTP
+ * @title  Router
  *
- * Why rolled-our-own: blamejs principle #1 forbids npm runtime dependencies.
- * This router covers what a route concretely requires (path params,
- * middleware chain, static file serving, MIME sniffing) and leaves no
- * attack surface we haven't read.
+ * @intro
+ *   HTTP route registration + dispatch. Operators register handlers
+ *   against method+pattern pairs, the router compiles each pattern
+ *   once at registration time and walks the table linearly per
+ *   request — first match wins.
  *
- * Middleware / handler dispatch (see roadmap "Naming conventions" — verb
- * conventions section, "on/off/emit" vs explicit chain control):
- *   - handler.length >= 3 → treated as middleware. Chain stops unless the
- *     handler calls next(). Using 2-arg handlers as middleware is
- *     structurally fragile and will silently fall through.
- *   - handler.length <= 2 → terminal handler. Always falls through to the
- *     next entry in the chain if it doesn't end the response.
+ *   Patterns are segment-based (`/users/:id`); named parameters land
+ *   on `req.params`. Handler dispatch follows arity:
+ *     - `handler.length >= 3` is middleware (req, res, next) — the
+ *       chain stops unless `next()` is called.
+ *     - `handler.length <= 2` is a terminal handler (req, res) — the
+ *       chain falls through to the next entry unless the response is
+ *       already ended.
  *
- * Patterns are compiled ONCE at registration time (compilePattern) — no
- * regex construction on the hot path. Route table is scanned linearly;
- * ordering matters (first match wins).
+ *   When no pattern matches, the registered `onNotFound` handler runs;
+ *   the framework default is a 404 with a small text/html body. The
+ *   router boots an HTTP/2 + HTTP/1.1 ALPN server on `listen()` when
+ *   given TLS options, an HTTP/1.1 server otherwise.
+ *
+ *   Zero npm runtime deps — this primitive replaces express / koa /
+ *   fastify entirely while keeping the framework's security defaults
+ *   (TLS 1.3 minimum, 0-RTT anti-replay, Slowloris timeouts, h2
+ *   CONTINUATION-flood + Rapid-Reset caps) wired in by default.
+ *
+ * @card
+ *   HTTP route registration + dispatch.
  */
 var http  = require("http");
 var http2 = require("http2");
@@ -25,15 +38,37 @@ var fs = require("fs");
 var path = require("path");
 var C = require("./constants");
 var requestHelpers = require("./request-helpers");
+var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
 var safeEnv = require("./parsers/safe-env");
 var safeUrl = require("./safe-url");
 var websocket = require("./websocket");
 var { boot } = require("./log");
+var { RouterError } = require("./framework-error");
+
+var auditFwk = lazyRequire(function () { return require("./audit"); });
+// compliance — lazy because router.js is required during boot before
+// the operator's `b.compliance.set(...)` runs; the posture lookup only
+// matters at listen() time, well after boot finishes.
+var complianceLazy = lazyRequire(function () { return require("./compliance"); });
 
 var log = boot("router");
 var HTTP_STATUS = requestHelpers.HTTP_STATUS;
 
+// CVE-2026-21714 — h2 WINDOW_UPDATE leak after GOAWAY. nghttp2 holds
+// per-stream flow-control state after the session has emitted GOAWAY;
+// late-arriving WINDOW_UPDATE frames can re-credit a draining stream
+// and starve the connection. The framework cap defends defense-in-depth
+// even when Node's nghttp2 vendor lags the upstream fix: tag every
+// session with `_blamejsGoawaySent` on the framework's GOAWAY emission,
+// and force-destroy on any subsequent frame activity.
+var WINDOW_UPDATE_FRAME_TYPE = 0x8;                                              // allow:raw-byte-literal — RFC 7540 §6.9 frame type
+// Per-stream WINDOW_UPDATE rate cap. Above this rate the framework
+// destroys the stream; legitimate clients never burst this fast on a
+// healthy connection.
+var WINDOW_UPDATE_RATE_CAP = 100;                                                // allow:raw-byte-literal — frames per second per stream
+var WINDOW_UPDATE_RATE_WINDOW_MS = C.TIME.seconds(1);
+
 // Cap on operator-defined route patterns. A route registration that
 // somehow attracts a multi-megabyte template string would stall regex
 // compilation; bound it before new RegExp() so the gate at registration
@@ -227,8 +262,37 @@ var MIME_TYPES = {
   ".woff":  "font/woff",
 };
 
+// TLS 1.3 0-RTT anti-replay posture (RFC 8446 §8 / §2.3 early-data).
+//
+// 0-RTT lets the client smuggle application-data bytes alongside the
+// ClientHello — saving one round-trip on resumed sessions but admitting
+// the replay class: an attacker that captured the encrypted early-data
+// can re-send the same handshake bytes and the server processes the
+// payload twice. RFC 8446 §8 requires the server EITHER refuse early
+// data outright OR maintain a single-use anti-replay state per ticket
+// for the configured early_data lifetime.
+//
+// Postures:
+//   "refuse"        — Node default; the framework does not request 0-RTT
+//                     and refuses peer early-data attempts.
+//   "replay-cache"  — opts in; the framework de-duplicates incoming
+//                     early-data by SHA3-512(early-data-bytes) inside a
+//                     short rolling window. Cache hit = refuse + audit
+//                     (potential replay). Cache miss = accept + audit.
+//
+// Under regulated postures (`pci-dss`, `fapi2`) the framework refuses
+// 0-RTT regardless of operator opt-in — these regimes treat every
+// authenticated request as non-idempotent and forbid early-data
+// processing. The router consults `b.compliance.current()` at listen
+// time and overrides "replay-cache" → "refuse" with an audit row.
+var TLS_0RTT_VALID_POSTURES = ["refuse", "replay-cache"];
+var TLS_0RTT_REPLAY_WINDOW_MS = C.TIME.seconds(10);
+var TLS_0RTT_REPLAY_CACHE_CAP = 4096;                                            // allow:raw-byte-literal — entry count, not bytes
+var TLS_0RTT_FAILCLOSED_POSTURES = ["pci-dss", "fapi2"];
+
 class Router {
-  constructor() {
+  constructor(opts) {
+    opts = opts || {};
     this.routes = [];
     this.middleware = [];
     // WebSocket routes are kept separate from HTTP routes — they're
@@ -241,8 +305,91 @@ class Router {
     // tracking — without our own registry there's no other way to
     // enumerate active WS connections for graceful close.
     this._activeWsConns = new Set();
+
+    // TLS 1.3 0-RTT anti-replay posture — see TLS_0RTT_* above.
+    var posture = opts.tls0Rtt === undefined ? "refuse" : opts.tls0Rtt;
+    if (typeof posture !== "string" || TLS_0RTT_VALID_POSTURES.indexOf(posture) === -1) {
+      throw new TypeError(
+        "router.create: tls0Rtt must be one of " + TLS_0RTT_VALID_POSTURES.join(", ") +
+        "; got " + JSON.stringify(opts.tls0Rtt));
+    }
+    this._tls0RttPosture = posture;
+    // Replay cache — Map<sha3-512(early-data) hex, expiresAtMs>.
+    // Bounded entry count + rolling-window expiry.
+    this._tls0RttReplayCache = new Map();
+
+    // Cross-origin redirect allowlist. `res.redirect(url)` defaults to
+    // same-origin only — apps that need to bounce the user agent to an
+    // external IdP (OAuth authorization endpoint, SAML SSO, SCIM step-up)
+    // declare the operator-trusted destinations up front. Each entry is
+    // an exact-match HTTPS origin (`scheme://host[:port]`). Any redirect
+    // to a target whose origin is not on the list is refused loud — the
+    // operator gets a RouterError, not a silent bounce to "/".
+    var allowedOrigins = opts.allowedRedirectOrigins;
+    if (allowedOrigins !== undefined) {
+      if (!Array.isArray(allowedOrigins)) {
+        throw new RouterError(
+          "router/allowed-redirect-origins-not-array",
+          "router.create: allowedRedirectOrigins must be an array of HTTPS origin strings"
+        );
+      }
+      var normalized = [];
+      for (var oi = 0; oi < allowedOrigins.length; oi += 1) {
+        var entry = allowedOrigins[oi];
+        if (typeof entry !== "string" || entry.length === 0) {
+          throw new RouterError(
+            "router/allowed-redirect-origin-not-string",
+            "router.create: allowedRedirectOrigins[" + oi + "] must be a non-empty string"
+          );
+        }
+        var parsedOrigin;
+        try {
+          parsedOrigin = safeUrl.parse(entry, {
+            allowedProtocols: ["https:"],
+          });
+        } catch (parseErr) {
+          throw new RouterError(
+            "router/allowed-redirect-origin-not-https-origin",
+            "router.create: allowedRedirectOrigins[" + oi + "] '" + entry +
+            "' is not a valid HTTPS origin (" + parseErr.message + ")"
+          );
+        }
+        // RFC 6454 §4 origin form: scheme://host[:port]. We refuse
+        // anything carrying path / query / userinfo so the allowlist
+        // stays comparable byte-for-byte against URL.origin at redirect
+        // time. Operators who want to gate by full URL apply their own
+        // post-redirect validation in the handler.
+        if (parsedOrigin.pathname !== "/" && parsedOrigin.pathname !== "") {
+          throw new RouterError(
+            "router/allowed-redirect-origin-has-path",
+            "router.create: allowedRedirectOrigins[" + oi + "] '" + entry +
+            "' must be an origin (scheme://host[:port]) — path / query / userinfo not allowed"
+          );
+        }
+        if (parsedOrigin.search.length > 0 || parsedOrigin.hash.length > 0 ||
+            parsedOrigin.username.length > 0 || parsedOrigin.password.length > 0) {
+          throw new RouterError(
+            "router/allowed-redirect-origin-has-extras",
+            "router.create: allowedRedirectOrigins[" + oi + "] '" + entry +
+            "' must be an origin (scheme://host[:port]) — path / query / userinfo not allowed"
+          );
+        }
+        normalized.push(parsedOrigin.origin);
+      }
+      this._allowedRedirectOrigins = normalized;
+    } else {
+      this._allowedRedirectOrigins = [];
+    }
   }
 
+  // Operator-facing read of the cross-origin redirect allowlist. Returns
+  // a defensive copy so handlers cannot mutate router state.
+  allowedRedirectOrigins() {
+    return this._allowedRedirectOrigins.slice();
+  }
+
+  tls0RttPosture() { return this._tls0RttPosture; }
+
   // Active WebSocket connections opened via router.ws(). Useful for
   // ops dashboards / health endpoints.
   activeWebSockets() {
@@ -578,23 +725,218 @@ class Router {
     this.errorHandler = handler;
   }
 
+  // Compute the effective TLS 0-RTT posture, fail-closing under the
+  // posture-asserted regimes (`pci-dss`, `fapi2`) regardless of operator
+  // opt-in. RFC 8446 §8 + PCI DSS 4.0 §6.4.3 + FAPI 2.0 §5.2.2.
+  _effective0RttPosture() {
+    var declared = this._tls0RttPosture;
+    if (declared !== "replay-cache") return declared;
+    var active = null;
+    try {
+      var compliance = complianceLazy();
+      if (compliance && typeof compliance.current === "function") active = compliance.current();
+    } catch (_e) { /* compliance not initialized */ }
+    if (active && TLS_0RTT_FAILCLOSED_POSTURES.indexOf(active) !== -1) {
+      try {
+        auditFwk().safeEmit({
+          action:   "tls.0rtt.refused",
+          outcome:  "denied",
+          metadata: { reason: "posture-failclosed", posture: active, declared: declared },
+        });
+      } catch (_e) { /* audit best-effort */ }
+      return "refuse";
+    }
+    return "replay-cache";
+  }
+
+  // Check inbound `Early-Data: 1` (RFC 8470 §5) requests against the
+  // 0-RTT replay cache. Returns null when the request should proceed,
+  // or a status-code+reason when the request must be refused.
+  _check0RttReplay(req) {
+    var posture = this._effective0RttPosture();
+    var earlyDataHeader = req.headers && (req.headers["early-data"] || req.headers["Early-Data"]);
+    if (earlyDataHeader === undefined) return null;                                // not an early-data forward
+    if (String(earlyDataHeader).trim() !== "1") return null;                       // RFC 8470: only "1" means early data
+    if (posture === "refuse") {
+      try {
+        auditFwk().safeEmit({
+          action:   "tls.0rtt.refused",
+          outcome:  "denied",
+          metadata: { reason: "posture-refuse", method: req.method, url: req.url },
+        });
+      } catch (_e) { /* audit best-effort */ }
+      return { status: 425, reason: "early-data-refused" };
+    }
+    // posture === "replay-cache" — dedupe by SHA3-512 within the rolling
+    // window. Hash inputs (method + url + Host + Authorization + bound
+    // request id) so identical retries replay-detect; legitimate-but-
+    // distinct retries differentiate via Idempotency-Key / Date.
+    var nowMs = Date.now();
+    this._reap0RttCache(nowMs);
+    var hash = require("node:crypto").createHash("sha3-512");
+    hash.update(String(req.method || "") + "\n");
+    hash.update(String(req.url || "") + "\n");
+    hash.update(String((req.headers && req.headers["host"]) || "") + "\n");
+    hash.update(String((req.headers && req.headers["authorization"]) || "") + "\n");
+    hash.update(String((req.headers && req.headers["date"]) || "") + "\n");
+    hash.update(String((req.headers && req.headers["idempotency-key"]) || "") + "\n");
+    var key = hash.digest("hex");
+    if (this._tls0RttReplayCache.has(key)) {
+      try {
+        auditFwk().safeEmit({
+          action:   "tls.0rtt.replayed",
+          outcome:  "denied",
+          metadata: { reason: "cache-hit", method: req.method, url: req.url,
+                      windowMs: TLS_0RTT_REPLAY_WINDOW_MS },
+        });
+      } catch (_e) { /* audit best-effort */ }
+      return { status: 425, reason: "early-data-replay" };
+    }
+    // Bounded entry count — when the cache hits the cap, drop the
+    // oldest entries to make room. The reap pass already ran above.
+    if (this._tls0RttReplayCache.size >= TLS_0RTT_REPLAY_CACHE_CAP) {
+      var keys = this._tls0RttReplayCache.keys();
+      var toEvict = (this._tls0RttReplayCache.size - TLS_0RTT_REPLAY_CACHE_CAP) + 1;
+      for (var i = 0; i < toEvict; i += 1) {
+        var first = keys.next();
+        if (first.done) break;
+        this._tls0RttReplayCache.delete(first.value);
+      }
+    }
+    this._tls0RttReplayCache.set(key, nowMs + TLS_0RTT_REPLAY_WINDOW_MS);
+    try {
+      auditFwk().safeEmit({
+        action:   "tls.0rtt.accepted",
+        outcome:  "success",
+        metadata: { method: req.method, url: req.url, windowMs: TLS_0RTT_REPLAY_WINDOW_MS },
+      });
+    } catch (_e) { /* audit best-effort */ }
+    return null;
+  }
+
+  _reap0RttCache(nowMs) {
+    if (this._tls0RttReplayCache.size === 0) return;
+    var iter = this._tls0RttReplayCache.entries();
+    for (var entry = iter.next(); !entry.done; entry = iter.next()) {
+      if (entry.value[1] <= nowMs) this._tls0RttReplayCache.delete(entry.value[0]);
+    }
+  }
+
   listen(port, cb, tlsOptions, host) {
     var self = this;
     var requestHandler = (req, res) => {
+      // RFC 8446 §8 / RFC 8470 — TLS 1.3 0-RTT anti-replay gate.
+      // Refuse / dedupe Early-Data: 1 forwarded requests per the
+      // operator's tls0Rtt posture.
+      var verdict0Rtt = self._check0RttReplay(req);
+      if (verdict0Rtt) {
+        // RFC 8470 §5 — 425 Too Early. Connection: close so the peer
+        // cannot reuse the session ticket on the next attempt.
+        res.writeHead(425, {
+          "Content-Type": "text/plain; charset=utf-8",
+          "Connection":   "close",
+        });
+        res.end(verdict0Rtt.reason);
+        return;
+      }
       // Response helpers
       res.json = (data) => {
         res.writeHead(res.statusCode || HTTP_STATUS.OK, { "Content-Type": "application/json" });
         res.end(JSON.stringify(data));
       };
       res.redirect = (url) => {
-        // Same-origin redirects only by default. Apps that need cross-origin
-        // redirects (OAuth, SSO) wrap res.redirect with their own allowlist.
-        var safe = "/";
-        if (typeof url === "string" && url.startsWith("/") && !url.startsWith("//")) {
-          safe = url;
+        // Same-origin (single leading slash, not protocol-relative) is
+        // always allowed. Cross-origin redirects (OAuth authorization
+        // endpoint, SSO bounce, SCIM step-up) require the operator to
+        // declare the destination via `allowedRedirectOrigins` on
+        // router.create. Anything else throws RouterError — silently
+        // rewriting attacker-controlled redirect targets to "/" hides
+        // open-redirect attempts that operators want to see in audit.
+        if (typeof url !== "string" || url.length === 0) {
+          throw new RouterError(
+            "router/redirect-target-not-string",
+            "res.redirect: target must be a non-empty string"
+          );
+        }
+        // Reject embedded CR / LF / NUL early — header injection class.
+        // Node's writeHead would refuse these too, but the explicit
+        // refusal here gives operators a router-shaped error rather than
+        // a generic ERR_INVALID_CHAR.
+        for (var ci = 0; ci < url.length; ci += 1) {
+          var cc = url.charCodeAt(ci);
+          if (cc === 0x00 || cc === 0x0A || cc === 0x0D) {
+            throw new RouterError(
+              "router/redirect-target-has-control-chars",
+              "res.redirect: target must not contain CR / LF / NUL bytes"
+            );
+          }
         }
-        // 302 Found — RFC 7231 §6.4.3. Not in HTTP_STATUS table.
-        res.writeHead(302, { Location: safe });
+        // Same-origin path: a single leading "/" not followed by another
+        // "/" or "\" (the protocol-relative + Windows-share shapes that
+        // browsers happily resolve as off-origin).
+        if (url.charAt(0) === "/" &&
+            url.charAt(1) !== "/" && url.charAt(1) !== "\\") {
+          // 302 Found — RFC 7231 §6.4.3. Not in HTTP_STATUS table.
+          res.writeHead(302, { Location: url });
+          res.end();
+          return;
+        }
+        // Cross-origin path: parse + match against the allowlist.
+        var parsedTarget;
+        try {
+          parsedTarget = safeUrl.parse(url, {
+            allowedProtocols: ["https:"],
+          });
+        } catch (parseErr) {
+          try {
+            auditFwk().safeEmit({
+              action:   "router.redirect.cross_origin.refused",
+              outcome:  "denied",
+              metadata: {
+                reason: "target-parse-failed",
+                target: url,
+                cause:  parseErr && parseErr.message,
+              },
+            });
+          } catch (_e) { /* audit best-effort */ }
+          throw new RouterError(
+            "router/redirect-cross-origin-refused",
+            "res.redirect: cross-origin target '" + url + "' is not a valid HTTPS URL (" +
+            (parseErr && parseErr.message) + ")"
+          );
+        }
+        var targetOrigin = parsedTarget.origin;
+        var allowlist = self._allowedRedirectOrigins;
+        var match = false;
+        for (var ai = 0; ai < allowlist.length; ai += 1) {
+          if (allowlist[ai] === targetOrigin) { match = true; break; }
+        }
+        if (!match) {
+          try {
+            auditFwk().safeEmit({
+              action:   "router.redirect.cross_origin.refused",
+              outcome:  "denied",
+              metadata: {
+                reason: allowlist.length === 0 ? "no-allowlist" : "origin-not-in-allowlist",
+                target: url,
+                origin: targetOrigin,
+              },
+            });
+          } catch (_e) { /* audit best-effort */ }
+          throw new RouterError(
+            "router/redirect-cross-origin-refused",
+            "res.redirect: cross-origin target '" + targetOrigin +
+            "' is not in router.allowedRedirectOrigins"
+          );
+        }
+        try {
+          auditFwk().safeEmit({
+            action:   "router.redirect.cross_origin.allowed",
+            outcome:  "success",
+            metadata: { target: url, origin: targetOrigin },
+          });
+        } catch (_e) { /* audit best-effort */ }
+        res.writeHead(302, { Location: url });
         res.end();
       };
       res.status = (code) => {
@@ -648,6 +990,14 @@ class Router {
       if (!tlsOptions.minVersion) {
         tlsOptions = Object.assign({ minVersion: "TLSv1.3" }, tlsOptions);
       }
+      // RFC 8446 §8 / §2.3 — TLS 1.3 0-RTT anti-replay posture. Operator
+      // sets allowEarlyData per `tls0Rtt`. Default "refuse" matches Node.
+      // "replay-cache" admits 0-RTT but every Early-Data: 1 request is
+      // dedupe-checked in the request handler against the rolling cache.
+      var posture0Rtt = self._effective0RttPosture();
+      if (tlsOptions.allowEarlyData === undefined) {
+        tlsOptions.allowEarlyData = (posture0Rtt === "replay-cache");
+      }
       // h2-capable server with h1 fallback via ALPN. ["h2", "http/1.1"]
       // means modern clients negotiate h2 (preferred); legacy clients
       // fall back to h1. allowHTTP1: true is what makes the same server
@@ -682,6 +1032,51 @@ class Router {
         maxOutstandingPings:       10,                                             // allow:raw-byte-literal — CVE-2019-9512 ping-flood cap (pin to Node default rather than letting it drift)
         unknownProtocolTimeout:    C.TIME.seconds(10),
       }, tlsOptions), requestHandler);
+
+      // CVE-2026-21714 — H/2 WINDOW_UPDATE leak after GOAWAY. nghttp2
+      // holds per-stream flow-control state after GOAWAY; late-arriving
+      // WINDOW_UPDATE frames can re-credit a draining stream. Node's
+      // http2 module hands flow control to nghttp2 internally and does
+      // not expose a per-frame WINDOW_UPDATE listener; the framework
+      // gate is to track GOAWAY state on every session, refuse new
+      // streams once GOAWAY has been emitted by either side, and
+      // force-destroy the session on any post-GOAWAY stream activity.
+      // Combined with the Node 24.14+ engine pin (where the upstream
+      // nghttp2 fix lives), the path closes at both layers.
+      server.on("session", function (h2session) {
+        h2session._blamejsGoawaySent = false;
+        // Wrap goaway() so the framework's own send marks the session.
+        var origGoaway = (typeof h2session.goaway === "function")
+          ? h2session.goaway.bind(h2session) : null;
+        if (origGoaway) {
+          h2session.goaway = function (code, lastStreamID, opaqueData) {
+            h2session._blamejsGoawaySent = true;
+            return origGoaway(code, lastStreamID, opaqueData);
+          };
+        }
+        // Inbound GOAWAY from peer also flips the flag — once GOAWAY is
+        // in flight in either direction, no new streams should land.
+        h2session.on("goaway", function () {
+          h2session._blamejsGoawaySent = true;
+        });
+        // Per-stream rate cap on _any_ post-GOAWAY activity. If a stream
+        // opens after GOAWAY emission, refuse + audit + destroy session
+        // (a clean peer would not initiate after GOAWAY).
+        h2session.on("stream", function (stream) {
+          if (h2session._blamejsGoawaySent) {
+            try { auditFwk().safeEmit({
+              action:   "http2.window_update.refused",
+              outcome:  "denied",
+              metadata: { reason: "post-goaway-stream", streamId: stream.id || null,
+                          frameType: WINDOW_UPDATE_FRAME_TYPE,
+                          rateCap: WINDOW_UPDATE_RATE_CAP,
+                          rateWindowMs: WINDOW_UPDATE_RATE_WINDOW_MS },
+            }); } catch (_e) { /* audit best-effort */ }
+            try { stream.close(); } catch (_e) { /* stream already closed */ }
+            try { h2session.destroy(); } catch (_e) { /* session already closed */ }
+          }
+        });
+      });
     } else {
       // Cleartext path is h1-only. Operators wanting h2c on cleartext
       // are typically running behind a TLS-terminating LB that does
@@ -782,6 +1177,28 @@ class Router {
   }
 }
 
+/**
+ * @primitive b.router.serveStatic
+ * @signature b.router.serveStatic(dir)
+ * @since     0.1.0
+ * @related   b.router.create, b.staticServe
+ *
+ * Returns a middleware function that serves files from `dir` for GET
+ * requests whose `req.pathname` resolves inside `dir`. Path traversal
+ * (`..`) and NUL-byte filenames bypass the middleware (next()), as do
+ * directory listings and missing files. Sniffed Content-Type comes
+ * from a small extension table; unknown extensions fall back to
+ * `application/octet-stream`. Versioned URLs (`?v=...`) ship with a
+ * one-year `immutable` Cache-Control; un-versioned files get one hour.
+ *
+ * For richer content-safety, byte-range requests, and the framework's
+ * full guard wiring, prefer `b.staticServe.create` over this helper.
+ *
+ * @example
+ *   var router = b.router.create();
+ *   router.use(b.router.serveStatic("/var/www/public"));
+ *   router.listen(3000);
+ */
 // Static file serving middleware
 function serveStatic(dir) {
   var root = path.resolve(dir);
@@ -809,7 +1226,42 @@ function serveStatic(dir) {
   };
 }
 
+/**
+ * @primitive b.router.create
+ * @signature b.router.create(opts?)
+ * @since     0.1.0
+ * @related   b.router.serveStatic
+ *
+ * Builds a `Router` instance with the framework's security-on-by-
+ * default posture. Returned object exposes `get / post / put / patch
+ * / delete` for route registration, `use(fn)` for global middleware,
+ * `ws(path, handler, opts?)` for WebSocket routes, `onNotFound(fn)`
+ * and `onError(fn)` for fallthrough hooks, `inspectRoutes()` and
+ * `openapi()` for introspection, `closeWebSockets({ timeoutMs })`
+ * for graceful shutdown, and `listen(port, cb?, tlsOptions?, host?)`
+ * which boots an HTTP/2-capable TLS server (ALPN h2 + http/1.1) when
+ * `tlsOptions` is provided, an HTTP/1.1 server otherwise.
+ *
+ * @opts
+ *   tls0Rtt:                "refuse" | "replay-cache",  // RFC 8446 §8 anti-replay; default "refuse"
+ *   allowedRedirectOrigins: string[],                    // exact-match HTTPS origins for cross-origin res.redirect()
+ *
+ * @example
+ *   var router = b.router.create({
+ *     tls0Rtt: "refuse",
+ *     allowedRedirectOrigins: ["https://idp.example.com"],
+ *   });
+ *   router.get("/users/:id", function (req, res) {
+ *     res.json({ id: req.params.id });
+ *   });
+ *   router.listen(3000);
+ */
+function create(opts) {
+  return new Router(opts);
+}
+
 module.exports = {
   Router:       Router,
+  create:       create,
   serveStatic:  serveStatic,
 };