@blamejs/core 0.14.26 → 0.14.27

package/lib/redis-client.js

@@ -28,7 +28,6 @@ var net = require("node:net");
 var nodeTls = require("node:tls");
 var nodeUrl = require("node:url");
 var C = require("./constants");
-var safeAsync = require("./safe-async");
 var validateOpts = require("./validate-opts");
 var ipUtils = require("./ip-utils");
 var { RedisError } = require("./framework-error");
@@ -215,11 +214,28 @@ function create(opts) {
   var connected = false;
   var connecting = false;
   var closing = false;
+  // Shared in-flight connect. Every _connect() call returns the SAME
+  // promise while a connect is in progress, so concurrent callers all
+  // observe the same resolve/reject instead of polling a flag. It is
+  // ALWAYS settled (resolve on ready, reject on socket-error / connect-
+  // timeout / AUTH-or-SELECT failure) and cleared the moment it settles
+  // so the next caller starts a fresh attempt — a connect that fails
+  // can never leave a never-settling promise behind for the next
+  // awaiter to wedge on.
+  var connectPromise = null;
   // Tracked + unref'd reconnect timer. Tracked so close() can cancel a
   // pending backoff (otherwise a reconnect scheduled before close fires
   // after it and opens a fresh socket); unref'd so a backoff window doesn't
   // by itself keep the event loop alive (the process-won't-exit class).
+  // Single-flight: a non-null reconnectTimer means a backoff is already
+  // pending — socket-error AND socket-close firing for the same failure
+  // must not stack two timers (which would burn the reconnect budget at
+  // 2x and open redundant sockets).
   var reconnectTimer = null;
+  // Set once the reconnect budget is exhausted. Makes the give-up path
+  // idempotent (drains pending+backlog exactly once) and stops a stray
+  // close/error after give-up from re-draining or racing a later success.
+  var gaveUp = false;
   var rxBuffer = Buffer.alloc(0);
   // FIFO of in-flight commands awaiting a response
   var pending = [];
@@ -239,18 +255,31 @@ function create(opts) {
 
   function _scheduleReconnect() {
     if (closing) return;
+    // Single-flight: a socket failure surfaces as both an `error` and a
+    // `close` event. Without this guard each one schedules its own timer,
+    // stacking two reconnects for one failure — the budget burns at 2x
+    // and two fresh sockets open. A pending backoff already covers the
+    // failure, so a second call is a no-op.
+    if (reconnectTimer !== null) return;
     if (maxReconnectAttempts >= 0 && reconnectAttempt >= maxReconnectAttempts) {
-      // Drain pending callbacks with a clear error
+      // Reconnect budget exhausted. Drain pending + backlog exactly once;
+      // a later stray close/error must not re-drain or race a future
+      // success path.
+      if (gaveUp) return;
+      gaveUp = true;
       var err = _err("RECONNECT_GAVE_UP",
         "redis: gave up after " + reconnectAttempt + " reconnect attempts");
       _drainPending(err);
       return;
     }
     reconnectAttempt++;
+    // Exponential backoff capped at 30s. Base 100ms is the first-retry
+    // delay (not a duration unit), so it stays a literal; the cap routes
+    // through C.TIME.
     var delay = Math.min(C.TIME.seconds(30), 100 * Math.pow(2, reconnectAttempt - 1));
     reconnectTimer = setTimeout(function () {
       reconnectTimer = null;
-      _connect().catch(function () { /* will reschedule */ });
+      _connect().catch(function () { /* failure reschedules via the teardown path */ });
     }, delay);
     if (typeof reconnectTimer.unref === "function") reconnectTimer.unref();
   }
@@ -261,7 +290,10 @@ function create(opts) {
     batch.forEach(function (p) { p.reject(err); });
     var bl = backlog.slice();
     backlog.length = 0;
-    bl.forEach(function (p) { p.reject(err); });
+    bl.forEach(function (p) {
+      if (p.timer) { clearTimeout(p.timer); p.timer = null; }
+      p.reject(err);
+    });
   }
 
   function _onData(chunk) {
@@ -312,39 +344,74 @@ function create(opts) {
     }
   }
 
-  function _onSocketError(err) {
-    var werr = _err("SOCKET", "redis socket error: " + ((err && err.message) || String(err)));
-    _drainPending(werr);
+  // Single teardown path for a lost socket. A failure surfaces as an
+  // `error` event AND a `close` event (and `error` then destroys the
+  // socket, which fires `close` again) — three callbacks for ONE lost
+  // connection. Routing all of them here, guarded by a "are we still
+  // attached to this socket" check, means pending is drained once and
+  // exactly one reconnect is scheduled (the single-flight guard in
+  // _scheduleReconnect absorbs the rest). `err` is the diagnostic to
+  // reject in-flight commands with.
+  function _teardownSocket(err) {
+    // Already torn down for this socket (the sibling event already ran).
+    if (!connected && socket === null) {
+      // Still let a stray event re-arm a reconnect if one isn't pending
+      // and we haven't been closed — but never re-drain pending.
+      if (!closing) _scheduleReconnect();
+      return;
+    }
     connected = false;
-    try { if (socket) socket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
+    var dead = socket;
     socket = null;
+    if (dead) {
+      try {
+        dead.removeListener("error", _onSocketError);
+        dead.removeListener("close", _onSocketClose);
+        dead.removeListener("data", _onData);
+        dead.destroy();
+      } catch (_e) { /* best-effort socket teardown */ }
+    }
+    _drainPending(err);
     if (!closing) _scheduleReconnect();
   }
 
+  function _onSocketError(err) {
+    _teardownSocket(_err("SOCKET",
+      "redis socket error: " + ((err && err.message) || String(err))));
+  }
+
   function _onSocketClose() {
-    connected = false;
-    if (!closing) {
-      var err = _err("SOCKET_CLOSED", "redis socket closed unexpectedly");
-      _drainPending(err);
-      socket = null;
-      _scheduleReconnect();
-    }
+    _teardownSocket(_err("SOCKET_CLOSED", "redis socket closed unexpectedly"));
   }
 
-  async function _connect() {
-    // A reconnect timer scheduled before close() can still fire afterward;
-    // refuse to re-open once closing so it doesn't leak a fresh socket.
-    if (closing) return;
-    if (connected) return;
-    if (connecting) {
-      // Wait until current connect attempt resolves
-      while (connecting) await safeAsync.sleep(20);
-      return;
-    }
+  // _connect() — public entry. Returns a promise that ALWAYS settles.
+  // Concurrent callers (and the reconnect timer) share the single
+  // in-flight connectPromise rather than each starting a parallel dial,
+  // and they all observe the same resolve/reject. A previous version
+  // polled a `connecting` flag in a `while (connecting) await sleep(20)`
+  // loop; if a failure path failed to clear that flag the waiter spun
+  // forever. The shared promise removes that wedge — the promise is
+  // cleared the instant it settles, so a failed connect can never leave
+  // a never-settling promise behind.
+  function _connect() {
+    if (closing) return Promise.resolve();
+    if (connected) return Promise.resolve();
+    if (connectPromise) return connectPromise;
+    connectPromise = _doConnect();
+    // Clear the shared promise once it settles (either way) so the next
+    // _connect() starts a fresh attempt instead of re-awaiting a stale
+    // settled promise.
+    var clear = function () { connectPromise = null; };
+    connectPromise.then(clear, clear);
+    return connectPromise;
+  }
+
+  async function _doConnect() {
     connecting = true;
     rxBuffer = Buffer.alloc(0);
+    var newSocket = null;
     try {
-      socket = await new Promise(function (resolve, reject) {
+      newSocket = await new Promise(function (resolve, reject) {
         var sock;
         var timer = setTimeout(function () {
           try { if (sock) sock.destroy(); } catch (_e) { /* best-effort socket teardown */ }
@@ -371,16 +438,19 @@ function create(opts) {
         }
         sock.once("error", onErr);
       });
+      socket = newSocket;
       socket.setNoDelay(true);
       socket.on("data", _onData);
       socket.on("error", _onSocketError);
       socket.on("close", _onSocketClose);
       connected = true;
-      reconnectAttempt = 0;
 
       // Auth + select db on (re)connect — without resetting the
       // backlog of commands queued during disconnect. Send these
       // BEFORE the backlog so the server is ready when backlog flushes.
+      // A failure here (wrong password, server SELECT rejection, socket
+      // dropped mid-AUTH) must not leave connected=true on a half-open
+      // socket — the catch below tears the socket down and rethrows.
       if (password) {
         var authArgs = username ? ["AUTH", username, password] : ["AUTH", password];
         await _sendNoQueue(authArgs);
@@ -389,15 +459,47 @@ function create(opts) {
         await _sendNoQueue(["SELECT", String(db)]);
       }
 
-      // Flush backlog
+      // Connect fully succeeded — only now reset the backoff counter +
+      // the give-up latch so a future disconnect gets a fresh budget.
+      reconnectAttempt = 0;
+      gaveUp = false;
+      connecting = false;
+
+      // Flush backlog. Clear each queued entry's not-connected timeout
+      // before it goes on the wire — the in-flight command timeout in
+      // _writeAndAwait now owns its lifetime.
       var bl = backlog.slice();
       backlog.length = 0;
-      bl.forEach(function (entry) { _writeAndAwait(entry.args, entry.resolve, entry.reject); });
+      bl.forEach(function (entry) {
+        if (entry.timer) { clearTimeout(entry.timer); entry.timer = null; }
+        _writeAndAwait(entry.args, entry.resolve, entry.reject);
+      });
     } catch (err) {
       connecting = false;
+      connected = false;
+      // Tear down a half-open socket (came up, then AUTH/SELECT failed)
+      // so we never leave connected=false with a live socket whose data/
+      // error/close handlers would fire against stale state. If the
+      // socket-error handler already ran it set socket=null.
+      var dead = socket || newSocket;
+      socket = null;
+      if (dead) {
+        try {
+          dead.removeListener("error", _onSocketError);
+          dead.removeListener("close", _onSocketClose);
+          dead.removeListener("data", _onData);
+          dead.destroy();
+        } catch (_e) { /* best-effort socket teardown */ }
+      }
+      // A failed dial (reset before ready) or an AUTH/SELECT failure must keep
+      // the reconnect loop alive. The post-ready error/close handlers that
+      // normally drive reconnect are not attached yet during the dial, so
+      // without scheduling here a connection lost mid-dial rejects the connect
+      // promise and the client never reconnects. Single-flight + budget-guarded
+      // by _scheduleReconnect; the caller still observes this attempt's rejection.
+      if (!closing) _scheduleReconnect();
       throw err;
     }
-    connecting = false;
   }
 
   // Internal helper that bypasses the connect-pending backlog (used
@@ -448,7 +550,28 @@ function create(opts) {
         return;
       }
       if (!connected) {
-        backlog.push({ args: args, resolve: resolve, reject: reject });
+        // Reconnect budget exhausted and no reconnect is in flight — a
+        // backlogged command here would never be flushed (nothing will
+        // reconnect to drain it) and would wedge the caller forever.
+        // Reject immediately instead.
+        if (gaveUp && reconnectTimer === null && !connecting) {
+          reject(_err("RECONNECT_GAVE_UP",
+            "redis: client disconnected and reconnect budget exhausted"));
+          return;
+        }
+        // Queued until the next successful connect flushes the backlog.
+        // Bound it with a timeout so a connect that never completes (the
+        // backend is down for the whole window) settles the caller with
+        // a clear error instead of leaving the await pending forever.
+        var entry = { args: args, resolve: resolve, reject: reject, timer: null };
+        entry.timer = setTimeout(function () {
+          var idx = backlog.indexOf(entry);
+          if (idx !== -1) backlog.splice(idx, 1);
+          reject(_err("COMMAND_TIMEOUT",
+            "redis " + args[0] + " timed out while queued (client not connected)"));
+        }, commandTimeoutMs);
+        if (typeof entry.timer.unref === "function") entry.timer.unref();
+        backlog.push(entry);
         return;
       }
       _writeAndAwait(args, resolve, reject);
@@ -469,6 +592,9 @@ function create(opts) {
   async function close() {
     closing = true;
     if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+    // Drop the shared connect promise so a re-create after close (or a
+    // late awaiter) doesn't re-await a stale in-flight attempt.
+    connectPromise = null;
     var err = _err("CLOSED", "redis client closed");
     _drainPending(err);
     if (socket) {
@@ -492,8 +618,11 @@ function create(opts) {
     _state:     function () {
       return {
         connected: connected, closing: closing,
+        connecting: connecting,
         pending:   pending.length, backlog: backlog.length,
         reconnect: reconnectAttempt,
+        reconnectPending: reconnectTimer !== null,
+        gaveUp:    gaveUp,
         host:      host, port: port, db: db, tls: useTls,
         connectTimeoutMs:     connectTimeoutMs,
         commandTimeoutMs:     commandTimeoutMs,

package/lib/router.js

@@ -42,6 +42,7 @@ var lazyRequire = require("./lazy-require");
 var safeAsync = require("./safe-async");
 var safeEnv = require("./parsers/safe-env");
 var safeUrl = require("./safe-url");
+var validateOpts = require("./validate-opts");
 var websocket = require("./websocket");
 var { boot } = require("./log");
 var { RouterError } = require("./framework-error");
@@ -301,6 +302,13 @@ class Router {
   constructor(opts) {
     opts = opts || {};
     this.routes = [];
+    // Registration-ordered middleware table. Each entry is
+    // `{ prefix, prefixSegments, fn }`: `prefix === null` is a global
+    // middleware (runs on every request); a non-null `prefix` is a
+    // path-scoped middleware that runs only when the request path
+    // matches the prefix on segment boundaries. Path-scoped and global
+    // entries interleave in registration order so a gate registered
+    // before a route still runs before it.
     this.middleware = [];
     // WebSocket routes are kept separate from HTTP routes — they're
     // matched on the upgrade / Extended CONNECT nodePath, not on a method
@@ -453,8 +461,23 @@ class Router {
     return conns.length;
   }
 
-  use(fn) {
-    this.middleware.push(fn);
+  // use(mw)                       — global middleware (runs on every request)
+  // use(mw1, mw2, ...)            — several global middlewares, in order
+  // use(prefix, mw1, mw2, ...)    — path-scoped: mw runs only when the
+  //                                 request path is at or beneath `prefix`
+  //                                 on segment boundaries ("/admin" covers
+  //                                 "/admin" + "/admin/x", not "/administrator")
+  // use([prefixA, prefixB], mw)   — scoped to any of several prefixes
+  //
+  // Bad input throws at config time (a non-string / non-array prefix, a
+  // prefix that doesn't begin with "/", a non-function middleware) so an
+  // operator wiring typo surfaces at boot instead of silently dropping a
+  // security gate or 500-ing every request.
+  use() {
+    var entries = _normalizeUseArgs(Array.prototype.slice.call(arguments));
+    for (var i = 0; i < entries.length; i++) {
+      this.middleware.push(entries[i]);
+    }
   }
 
   // Internal: split a route registration's args into { spec, handlers }.
@@ -687,8 +710,24 @@ class Router {
     }
     req.query = Object.fromEntries(queryEntries);
 
-    // Run middleware
-    for (var mw of this.middleware) {
+    // Run middleware in registration order. Global entries
+    // (prefixSegmentsList === null) run on every request; path-scoped
+    // entries run only when req.pathname is at or beneath one of the
+    // mount's prefixes (segment-boundary match). A skipped scoped
+    // middleware does NOT short-circuit the chain — the next entry
+    // still runs.
+    for (var entry of this.middleware) {
+      if (entry.prefixSegmentsList !== null) {
+        var matched = false;
+        for (var pli = 0; pli < entry.prefixSegmentsList.length; pli++) {
+          if (_pathMatchesPrefix(entry.prefixSegmentsList[pli], req.pathname)) {
+            matched = true;
+            break;
+          }
+        }
+        if (!matched) continue;
+      }
+      var mw = entry.fn;
       var next = false;
       try {
         await mw(req, res, () => (next = true));
@@ -1206,6 +1245,152 @@ class Router {
   }
 }
 
+// ---- Path-scoped `use()` helpers ----
+//
+// These back `Router.use(prefix, mw)`. They live after the class
+// (hoisted function declarations are visible to the methods regardless
+// of source order) so the class methods sit contiguous with the
+// route-matching helpers above.
+
+// Compile a `use(prefix, mw)` path prefix into the segment list the
+// matcher walks. A prefix is the literal-segment portion of a path
+// ("/admin", "/.well-known/jmap") — parameter segments (":id") are not
+// meaningful for a mounting prefix, so they're treated as literals.
+//
+// Normalization mirrors route-pattern handling: split on "/" and drop a
+// single trailing-slash artifact so "/admin" and "/admin/" mount the
+// same. The leading empty segment from the leading "/" is preserved so
+// the prefix anchors at the path root (a prefix that does not begin with
+// "/" is refused at the use() entry point).
+function _compilePrefix(prefix) {
+  var segments = prefix.split("/");
+  // A trailing "/" produces a final empty segment ("/admin/" → ["", "admin", ""]).
+  // Drop it so the trailing slash doesn't force an extra path segment.
+  if (segments.length > 1 && segments[segments.length - 1] === "") {
+    segments.pop();
+  }
+  return segments;
+}
+
+// True when `pathname` is at or beneath the mounting prefix, matching on
+// segment boundaries. "/admin" matches "/admin" and "/admin/x" but NOT
+// "/administrator" (Express-style segment semantics) — a substring
+// prefix that lands mid-segment is a no-match so a security gate scoped
+// to "/admin" never leaks onto a sibling path that merely shares a
+// textual prefix.
+function _pathMatchesPrefix(prefixSegments, pathname) {
+  var pathSegments = pathname.split("/");
+  if (pathSegments.length < prefixSegments.length) return false;
+  // Compare segment-for-segment. This is routing metadata (public URL
+  // path), not secret material, so an ordinary equality walk is correct
+  // — no constant-time comparison is warranted.
+  return prefixSegments.every(function (seg, i) {
+    return pathSegments[i] === seg;
+  });
+}
+
+// Classify the first `use()` argument:
+//   function          → global mount (prefixes stays null)
+//   string / string[] → path-scoped mount (one or more prefixes)
+//   anything else     → operator wiring typo, refused at config time
+// Returns the prefix array (or null for a global mount). Does not touch
+// the middleware functions — the caller validates those.
+function _usePrefixesFromFirstArg(first) {
+  if (typeof first === "function") return null;
+  if (typeof first !== "string" && !Array.isArray(first)) {
+    throw new RouterError("router/use-bad-first-arg",
+      "router.use: first argument must be a middleware function, a path " +
+      "prefix string, or an array of prefix strings (got " +
+      (first === null ? "null" : typeof first) + ")");
+  }
+  var prefixes = Array.isArray(first) ? first : [first];
+  if (prefixes.length === 0) {
+    throw new RouterError("router/use-empty-prefix-array",
+      "router.use: path-prefix array must contain at least one prefix string");
+  }
+  // Array-of-non-empty-strings shape (the index-pointing throw on a
+  // non-string / empty entry) is the shared validate-opts contract.
+  validateOpts.optionalNonEmptyStringArray(
+    prefixes, "router.use: path prefix", RouterError, "router/use-prefix-not-string");
+  // Prefix-specific grammar: anchor at "/" + bounded length.
+  for (var i = 0; i < prefixes.length; i++) {
+    var grammarErr = _prefixGrammarError(prefixes[i]);
+    if (grammarErr) throw grammarErr;
+  }
+  return prefixes;
+}
+
+// Return a RouterError describing why `prefix` is not a valid mounting
+// prefix, or null when it is valid. Split out so the per-prefix grammar
+// check is one branch, not an inline throw-block in the loop.
+function _prefixGrammarError(prefix) {
+  if (prefix.charAt(0) !== "/") {
+    return new RouterError("router/use-prefix-not-absolute",
+      "router.use: path prefix '" + prefix + "' must begin with '/'");
+  }
+  if (prefix.length > MAX_ROUTE_PATTERN_LEN) {
+    return new RouterError("router/use-prefix-too-long",
+      "router.use: path prefix exceeds " + MAX_ROUTE_PATTERN_LEN +
+      " chars (got " + prefix.length + ")");
+  }
+  return null;
+}
+
+// Index of the first non-function entry in `fns`, or -1 when all are
+// functions. Kept separate so the middleware-shape check is a scan, not
+// an inline throw inside the normalize flow.
+function _firstNonFunctionIndex(fns) {
+  for (var i = 0; i < fns.length; i++) {
+    if (typeof fns[i] !== "function") return i;
+  }
+  return -1;
+}
+
+// Validate + normalize the `use()` arguments into middleware-table
+// entries. Config-time entry-point tier: a non-string / non-array-of-
+// strings prefix or a non-function middleware is an operator wiring
+// typo and throws so it surfaces at boot, not as a silent dropped gate
+// or a request-time 500. Returns one entry per middleware function:
+//   { prefix: null,        prefixSegmentsList: null,        fn }  — global
+//   { prefix: "/admin",    prefixSegmentsList: [[...], ...], fn }  — scoped
+// A scoped entry matches when ANY of its prefixes match the request
+// path on segment boundaries; the fn runs at most once per request even
+// when two of its prefixes both match (nested prefixes), so a gate never
+// double-executes.
+function _normalizeUseArgs(args) {
+  if (args.length === 0) {
+    throw new RouterError("router/use-no-args",
+      "router.use: requires at least one middleware function");
+  }
+  var prefixes = _usePrefixesFromFirstArg(args[0]);
+  // Global mount uses every arg as a middleware; a scoped mount drops the
+  // leading prefix arg and uses the rest.
+  var fns = (prefixes === null) ? args : args.slice(1);
+  if (fns.length === 0) {
+    throw new RouterError("router/use-no-middleware",
+      "router.use: path-scoped mount requires at least one middleware " +
+      "function after the prefix");
+  }
+  var nonFn = _firstNonFunctionIndex(fns);
+  if (nonFn !== -1) {
+    throw new RouterError("router/use-middleware-not-function",
+      "router.use: middleware at position " + nonFn +
+      " must be a function (got " +
+      (fns[nonFn] === null ? "null" : typeof fns[nonFn]) + ")");
+  }
+  // Pre-compile each prefix to its segment list once at registration so
+  // dispatch only walks segments, never re-splits the prefix per request.
+  var segmentsList = (prefixes === null) ? null : prefixes.map(_compilePrefix);
+  var label = (prefixes === null) ? null
+            : (prefixes.length === 1 ? prefixes[0] : prefixes.slice());
+  // One entry per fn, preserving the order each middleware was passed —
+  // a path-scoped mount with two middlewares interleaves them in
+  // registration order just like two separate use() calls would.
+  return fns.map(function (fn) {
+    return { prefix: label, prefixSegmentsList: segmentsList, fn: fn };
+  });
+}
+
 /**
  * @primitive b.router.serveStatic
  * @signature b.router.serveStatic(dir)
@@ -1266,7 +1451,7 @@ function serveStatic(dir) {
  *
  * 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,
+ * / delete` for route registration, `use(...)` for middleware,
  * `ws(path, handler, opts?)` for WebSocket routes, `onNotFound(fn)`
  * and `onError(fn)` for fallthrough hooks, `inspectRoutes()` and
  * `openapi()` for introspection, `closeWebSockets({ timeoutMs })`
@@ -1274,6 +1459,21 @@ function serveStatic(dir) {
  * which boots an HTTP/2-capable TLS server (ALPN h2 + http/1.1) when
  * `tlsOptions` is provided, an HTTP/1.1 server otherwise.
  *
+ * `use` has two forms. `use(mw)` (and `use(mw1, mw2, ...)`) mounts
+ * global middleware that runs on every request. `use(prefix, mw1,
+ * mw2, ...)` mounts path-scoped middleware that runs only when the
+ * request path is at or beneath `prefix`, matched on segment
+ * boundaries — `"/admin"` covers `"/admin"` and `"/admin/x"` but not
+ * `"/administrator"`. The prefix may be an array of strings to scope a
+ * gate to several path roots at once. Global and scoped middleware
+ * interleave in registration order, so a gate registered before a
+ * route still runs before it. A non-string / non-array prefix, a
+ * prefix not beginning with `"/"`, or a non-function middleware throws
+ * at registration time rather than dropping the gate or 500-ing every
+ * request — scope a security middleware (`csrf`, `bearerAuth`,
+ * `requireAal`, `requireMtls`) to a path with confidence it runs
+ * exactly where mounted.
+ *
  * @opts
  *   tls0Rtt:                "refuse" | "replay-cache",  // RFC 8446 §8 anti-replay; default "refuse"
  *   allowedRedirectOrigins: string[],                    // exact-match HTTPS origins for cross-origin res.redirect()
@@ -1286,6 +1486,13 @@ function serveStatic(dir) {
  *   router.get("/users/:id", function (req, res) {
  *     res.json({ id: req.params.id });
  *   });
+ *
+ *   // Global middleware — runs on every request.
+ *   router.use(b.middleware.securityHeaders());
+ *
+ *   // Path-scoped middleware — the step-up gate runs only under /admin.
+ *   router.use("/admin", b.middleware.requireAal({ minimum: "AAL2" }));
+ *
  *   router.listen(3000);
  */
 function create(opts) {

package/lib/ssrf-guard.js

@@ -148,12 +148,27 @@ var IPV6_6TO4_PREFIX      = _ipv6ToBytes("2002::");
 // or attempted exfil to a sinkhole.
 var IPV6_DISCARD_PREFIX   = _ipv6ToBytes("100::");
 
-// ---- Cloud metadata addresses (string-equality, exact match) ----
+// ---- Cloud metadata addresses (matched on CANONICAL bytes, not string) ----
+// The documentation strings below are the human-readable canonical forms.
+// Matching is byte-canonical (see _isCloudMetadataAddr): an IPv6 address has
+// many textual representations (compressed `::`, fully-expanded
+// `fd00:ec2:0:0:0:0:0:254`, mixed-case) that all decode to the same 16 bytes.
+// A string-equality membership test matched only ONE spelling, so a hostile
+// (or merely DoH-decoded — network-dns.js emits the expanded form) answer of
+// `fd00:ec2:0:0:0:0:0:254` slipped past as "private" and rode the documented
+// `allowInternal:true` waiver straight into the IMDS credential endpoint.
 var CLOUD_METADATA_IPS = [
   "169.254.169.254",       // AWS, GCP, Azure, OpenStack, DO
   "169.254.170.2",         // AWS ECS task role
   "fd00:ec2::254",         // AWS IMDS over IPv6
 ];
+// Canonical byte forms of the metadata IPs — v4 as a 4-byte Buffer, v6 as a
+// 16-byte Buffer. Built once at load via the same parsers classify() uses,
+// so every textual representation that decodes to these bytes is caught.
+var CLOUD_METADATA_BYTES = CLOUD_METADATA_IPS.map(function (ip) {
+  var fam = net.isIP(ip);
+  return fam === 4 ? _ipv4ToBytes(ip) : _ipv6ToBytes(ip);
+});
 
 // ---- Helpers ----
 
@@ -180,6 +195,14 @@ function _ipv4ToInt(ip) {
           nums[3];
 }
 
+function _ipv4ToBytes(ip) {
+  // Canonical 4-byte form of an IPv4 address. Returns null on malformed
+  // input so a metadata-membership test never matches garbage.
+  var n = _ipv4ToInt(ip);
+  if (!Number.isFinite(n)) return null;
+  return Buffer.from([(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]);
+}
+
 function _ipv6ToBytes(ip) {
   // Node's net.isIPv6 returns 6 for valid IPv6; we then expand
   // shorthand via manual parsing. node:net doesn't export an
@@ -309,7 +332,10 @@ function classify(ip) {
   var family = net.isIP(ip);
   if (family === 0) return null;
 
-  if (CLOUD_METADATA_IPS.indexOf(ip) !== -1) return "cloud-metadata";
+  // Cloud-metadata IPs are matched on their canonical byte form so every
+  // textual spelling (compressed `::`, fully-expanded zero-runs, mixed
+  // case) is caught — a string-equality test matched one spelling only.
+  if (_isCloudMetadataAddr(ip, family)) return "cloud-metadata";
 
   if (family === 4) {
     var ipInt = _ipv4ToInt(ip);
@@ -349,6 +375,24 @@ function classify(ip) {
   return null;
 }
 
+// Canonical-bytes membership test for the cloud-metadata IP set. An IP
+// matches iff its parsed bytes equal one of CLOUD_METADATA_BYTES, regardless
+// of textual representation. This is the unconditional metadata gate — it
+// must NOT be string-based, because IPv6 has many spellings of the same
+// address (the DoH resolver in network-dns.js, for instance, emits the
+// fully-expanded `fd00:ec2:0:0:0:0:0:254` rather than the compressed form).
+function _isCloudMetadataAddr(ip, family) {
+  var fam = typeof family === "number" ? family : net.isIP(ip);
+  if (fam === 0) return false;
+  var bytes = fam === 4 ? _ipv4ToBytes(ip) : _ipv6ToBytes(ip);
+  if (!bytes) return false;
+  for (var i = 0; i < CLOUD_METADATA_BYTES.length; i++) {
+    var ref = CLOUD_METADATA_BYTES[i];
+    if (ref && ref.length === bytes.length && _bufEqual(bytes, ref)) return true;
+  }
+  return false;
+}
+
 function _bufEqual(a, b) {
   // Compares Buffer-like byte arrays for equality. The buffers here
   // are IP addresses, not secrets, so the comparison doesn't need
@@ -766,8 +810,11 @@ function checkUrlTextual(url, opts) {
   // If the textual hostname IS an IP literal AND matches a cloud-
   // metadata IP, refuse — even with `allowInternal: true` and a proxy.
   // Metadata IPs leak instance credentials (AWS IMDS, GCP, Azure) and
-  // are not a configuration knob.
-  if (net.isIP(host) && CLOUD_METADATA_IPS.indexOf(host) !== -1) {
+  // are not a configuration knob. Matched on canonical bytes so a
+  // non-canonical IPv6 spelling (compressed / expanded / mixed-case)
+  // can't slip the textual gate the way it slipped classify().
+  var hostFamily = net.isIP(host);
+  if (hostFamily !== 0 && _isCloudMetadataAddr(host, hostFamily)) {
     throw new ErrorClass(
       "URL '" + parsed.toString() + "' resolves to cloud-metadata IP " + host +
       " — refused unconditionally (not overridable via allowInternal + proxy)",