@blamejs/core 0.8.42 → 0.8.49

package/lib/request-helpers.js

@@ -1,33 +1,34 @@
 "use strict";
 /**
- * request-helpers — small shared utilities for HTTP request middleware.
+ * @module b.requestHelpers
+ * @nav    HTTP
+ * @title  Request Helpers
  *
- * The framework's metrics + tracing requestMiddleware both label by
- * route TEMPLATE and capture the final response status. They had
- * identical implementations of:
+ * @intro
+ *   Defensive per-request shape readers — return sane defaults when
+ *   headers / route / params are missing or garbage. Every primitive
+ *   in this module sits in the framework's third validation tier:
+ *   request-shape readers RETURN DEFAULTS, never throw. They run on
+ *   every request, often inside middleware that has no recovery path;
+ *   a thrown error here would crash the very request that triggered
+ *   the read.
  *
- *   1. Reading req.routePattern with a URL-fallback
- *   2. Wrapping res.writeHead + reading res.statusCode at res.end
+ *   The contract is uniform: pass any shape (a real Node
+ *   IncomingMessage, a partially-constructed test fake, `undefined`,
+ *   a number, an attacker-supplied bag of strings) and get back a
+ *   sane default. `resolveRoute` falls back to "/", `clientIp` to
+ *   `null`, `requestProtocol` to "http", `parseListHeader` and
+ *   `parseQualityList` to `[]`, `safeHeadersDistinct` to a
+ *   null-prototype empty object, `extractBearer` to `null`. Operators
+ *   who want strict refusal layer their own check on the result.
  *
- * This module owns the two helpers so the duplication doesn't drift —
- * if either pattern changes (e.g. handle res.statusMessage), it changes
- * once.
+ *   The single exception is `parseListHeader({ strictToken: true })`,
+ *   which throws on RFC 9110 §5.6.2 token grammar violations because
+ *   it's used by config-time entry points (WebSocket subprotocol
+ *   negotiation etc.) where bad input MUST surface at boot.
  *
- * Public API:
- *
- *   resolveRoute(req)
- *     Returns req.routePattern when the router populated it,
- *     otherwise the URL with query string stripped.
- *
- *   captureResponseStatus(res, onEnd)
- *     Wraps res.writeHead + res.end. Calls onEnd(status) once when the
- *     response ends, with the final status pulled from writeHead's
- *     argument OR from res.statusCode (modern Node handlers set it
- *     directly without going through writeHead). Operators wrap their
- *     own pre-end logic by passing it as onEnd.
- *
- *     Returns the original (unwrapped) `res.end`. Useful for unit tests
- *     that need to assert against the original behavior.
+ * @card
+ *   Defensive per-request shape readers — return sane defaults when headers / route / params are missing or garbage.
  */
 
 // HTTP status codes used across the framework's HTTP-shaped surface.
@@ -64,19 +65,43 @@ var HTTP_STATUS = Object.freeze({
   GATEWAY_TIMEOUT:               0x1F8,
 });
 
-// extractActorContext(req) — pull the 5 W's from a request for audit
-// chain emission. WHO/WHERE/HOW columns on _blamejs_audit_log are
-// populated from this shape:
-//
-//   { ip, userAgent, sessionId, requestId, method, route, userId }
-//
-// Every field is best-effort: missing or non-request inputs return
-// an object with whatever could be inferred plus null elsewhere.
-// Audit chain treats null as "unknown", so partial context is safe.
-//
-// Caller-supplied actor (existing actor.userId, actor.ip, etc.) is
-// merged on top of the request-derived fields — explicit operator
-// override always wins.
+/**
+ * @primitive b.requestHelpers.extractActorContext
+ * @signature b.requestHelpers.extractActorContext(req, override?)
+ * @since     0.4.29
+ * @related   b.requestHelpers.resolveActorWithOverride, b.requestHelpers.resolveRoute
+ *
+ * Pull the 5 W's from a request for audit chain emission. The
+ * WHO/WHERE/HOW columns on `_blamejs_audit_log` are populated from
+ * the returned shape `{ ip, userAgent, sessionId, requestId, method,
+ * route, userId }`. Every field is best-effort — missing or
+ * non-request inputs return an object with whatever could be
+ * inferred plus `null` elsewhere. The audit chain treats `null` as
+ * "unknown", so partial context is always safe.
+ *
+ * Caller-supplied `override` (own `userId`, `ip`, …) is merged on
+ * top of the request-derived fields — explicit operator override
+ * always wins.
+ *
+ * @example
+ *   var req = {
+ *     ip:      "203.0.113.4",
+ *     method:  "POST",
+ *     url:     "/api/orders?ref=abc",
+ *     headers: { "user-agent": "curl/8.7.1", "x-request-id": "req-9f2" },
+ *     user:    { id: "user-42" },
+ *   };
+ *   var actor = b.requestHelpers.extractActorContext(req);
+ *   // → {
+ *   //     ip: "203.0.113.4", userAgent: "curl/8.7.1",
+ *   //     sessionId: null, requestId: "req-9f2",
+ *   //     method: "POST", route: "/api/orders", userId: "user-42",
+ *   //   }
+ *
+ *   // Override beats request-derived fields:
+ *   var ovr = b.requestHelpers.extractActorContext(req, { userId: "svc-runner" });
+ *   ovr.userId;   // → "svc-runner"
+ */
 function extractActorContext(req, override) {
   var ctx = {
     ip:        null,
@@ -121,19 +146,42 @@ function extractActorContext(req, override) {
   return ctx;
 }
 
-// Convenience wrapper for primitives that accept an optional
-// `{ req, context }` shape and want to thread it into an audit-emit
-// `actor` field. Replaces the four near-identical `_actor()` helpers
-// that lived in api-key, cache, seeders, and notify before v0.4.29.
-//
-//   callerOpts:    operator-supplied `{ req?, context? }` (e.g. the
-//                  primitive's call-site opts bag)
-//   baseOverride:  optional seed values applied BEFORE callerOpts.context
-//                  so `context` wins. api-key seeds `{ userId }` here so
-//                  the resolved key's owner becomes the default actor
-//                  unless the operator passes their own context.userId.
-//
-// Returns the same shape as extractActorContext.
+/**
+ * @primitive b.requestHelpers.resolveActorWithOverride
+ * @signature b.requestHelpers.resolveActorWithOverride(callerOpts, baseOverride?)
+ * @since     0.4.29
+ * @related   b.requestHelpers.extractActorContext
+ *
+ * Convenience wrapper for primitives that accept an optional
+ * `{ req, context }` shape and want to thread it into an
+ * audit-emit `actor` field. Replaces the four near-identical
+ * `_actor()` helpers that lived in api-key, cache, seeders, and
+ * notify before v0.4.29.
+ *
+ * `callerOpts` is the operator-supplied `{ req?, context? }` bag
+ * (typically a primitive's call-site opts). `baseOverride` seeds
+ * default values applied BEFORE `callerOpts.context` is merged, so
+ * `context` always wins — `b.apiKey` seeds `{ userId }` here so the
+ * resolved key's owner becomes the default actor unless the
+ * operator passes their own `context.userId`. Returns the same
+ * shape as `b.requestHelpers.extractActorContext`.
+ *
+ * @example
+ *   var req = { ip: "198.51.100.7", method: "DELETE", url: "/v1/keys/abc" };
+ *   var actor = b.requestHelpers.resolveActorWithOverride(
+ *     { req: req, context: { userId: "ops-admin" } },
+ *     { userId: "key-owner-default" }
+ *   );
+ *   actor.userId;   // → "ops-admin"
+ *   actor.ip;       // → "198.51.100.7"
+ *   actor.method;   // → "DELETE"
+ *
+ *   // Falls back to the seed when caller passes no context:
+ *   var seeded = b.requestHelpers.resolveActorWithOverride(
+ *     { req: req }, { userId: "key-owner-default" }
+ *   );
+ *   seeded.userId;  // → "key-owner-default"
+ */
 function resolveActorWithOverride(callerOpts, baseOverride) {
   var override = baseOverride ? Object.assign({}, baseOverride) : {};
   if (callerOpts && callerOpts.context && typeof callerOpts.context === "object") {
@@ -148,22 +196,47 @@ function resolveActorWithOverride(callerOpts, baseOverride) {
 
 // ---- Proxy-trust primitives (v0.5.3) ----
 //
-// `X-Forwarded-For` and `X-Forwarded-Proto` are operator-trust headers —
-// behind a sanitizing reverse proxy they carry the apparent origin /
-// scheme; without one they're attacker-forgeable. Default is to NOT
-// trust them; operators behind a proxy set `trustProxy: true` (or a
-// hop count for multi-hop chains) per-middleware to opt in.
-//
-//   clientIp(req, { trustProxy }) →  string | null
-//
-//     trustProxy false (default):  socket.remoteAddress only
-//     trustProxy true:             leftmost x-forwarded-for hop, else socket
-//     trustProxy <integer N>:      Nth-from-rightmost xff hop (skip-N-trusted-hops)
-//
-// Middleware accepts `trustProxy` as an opt and threads it through;
-// the framework refuses to silently pick up forwarded headers without
-// the operator's explicit acknowledgement.
+// `X-Forwarded-For` and `X-Forwarded-Proto` are operator-trust
+// headers — behind a sanitizing reverse proxy they carry the
+// apparent origin / scheme; without one they're attacker-forgeable.
+// Default is to NOT trust them; operators behind a proxy opt in by
+// passing `trustProxy: true` (or a hop count for multi-hop chains).
 
+/**
+ * @primitive b.requestHelpers.clientIp
+ * @signature b.requestHelpers.clientIp(req, opts?)
+ * @since     0.5.3
+ * @related   b.requestHelpers.requestProtocol, b.requestHelpers.parseListHeader
+ *
+ * Resolve the originating client IP from a request. Default reads
+ * only `req.socket.remoteAddress` — `X-Forwarded-For` is ignored
+ * because without a sanitizing reverse proxy it's
+ * attacker-forgeable. Behind a trusted proxy, operators opt in via
+ * `trustProxy: true` (use the leftmost XFF hop) or
+ * `trustProxy: <N>` (skip N trusted hops from the right and return
+ * the Nth-from-rightmost). Returns `null` when no address can be
+ * read — never throws.
+ *
+ * @opts
+ *   trustProxy: boolean | number   // false (default) | true | hop count
+ *
+ * @example
+ *   var req = {
+ *     socket:  { remoteAddress: "10.0.0.1" },
+ *     headers: { "x-forwarded-for": "203.0.113.7, 10.0.0.5" },
+ *   };
+ *   b.requestHelpers.clientIp(req);
+ *   // → "10.0.0.1"   (forwarded headers ignored by default)
+ *
+ *   b.requestHelpers.clientIp(req, { trustProxy: true });
+ *   // → "203.0.113.7"   (leftmost XFF hop)
+ *
+ *   b.requestHelpers.clientIp(req, { trustProxy: 1 });
+ *   // → "10.0.0.5"   (1 trusted hop from the right)
+ *
+ *   b.requestHelpers.clientIp(undefined);
+ *   // → null
+ */
 function clientIp(req, opts) {
   if (!req) return null;
   var trust = opts && opts.trustProxy;
@@ -182,6 +255,38 @@ function clientIp(req, opts) {
   return null;
 }
 
+/**
+ * @primitive b.requestHelpers.requestProtocol
+ * @signature b.requestHelpers.requestProtocol(req, opts?)
+ * @since     0.5.3
+ * @related   b.requestHelpers.clientIp, b.safeRedirect
+ *
+ * Resolve the inbound transport scheme. Default returns `"https"`
+ * when `req.socket.encrypted` is set, otherwise `"http"`. Behind a
+ * trusted reverse proxy that terminates TLS, set `trustProxy: true`
+ * to read the leftmost `X-Forwarded-Proto` hop instead — without
+ * the explicit opt-in the framework refuses to pick up the
+ * attacker-forgeable header. Always returns a string; on bad input
+ * falls back to `"http"`.
+ *
+ * @opts
+ *   trustProxy: boolean   // false (default) | true
+ *
+ * @example
+ *   var req = { socket: { encrypted: true } };
+ *   b.requestHelpers.requestProtocol(req);
+ *   // → "https"
+ *
+ *   var behindProxy = {
+ *     socket:  { encrypted: false },
+ *     headers: { "x-forwarded-proto": "https, http" },
+ *   };
+ *   b.requestHelpers.requestProtocol(behindProxy, { trustProxy: true });
+ *   // → "https"
+ *
+ *   b.requestHelpers.requestProtocol(undefined);
+ *   // → "http"
+ */
 function requestProtocol(req, opts) {
   if (!req) return "http";
   var trust = opts && opts.trustProxy;
@@ -197,28 +302,53 @@ function requestProtocol(req, opts) {
   return "http";
 }
 
-// parseListHeader — split a comma-separated header / opt value into a
-// list of trimmed non-empty tokens. Replaces the
-// `String(x).split(",").map(s => s.trim()).filter(Boolean)` chain that
-// was duplicated across cors / compression / scheduler / webhook /
-// websocket / db-schema / cli before v0.5.17.
-//
-//   parseListHeader("a, b , ,c")           → ["a", "b", "c"]
-//   parseListHeader("Foo, Bar", { lowercase: true })
-//                                          → ["foo", "bar"]
-//   parseListHeader(undefined)             → []
-//   parseListHeader("")                    → []
-//
-// Tolerant read: non-string input returns [] — these are read from
-// request headers that the network might omit. Callers needing stricter
-// checks layer their own validation on the result.
 // RFC 9110 §5.6.2 token grammar — letters, digits, and the
 // punctuation set `!#$%&'*+-.^_`|~`. Used by header-list parsers
-// that consume protocol tokens (Connection, Sec-WebSocket-
-// Protocol, etc.). Operator handlers parsing comma-separated
-// human-supplied values (Origin lists, etc.) opt out by passing
-// `lax: true`.
+// that consume protocol tokens (Connection, Sec-WebSocket-Protocol,
+// etc.).
 var RFC_9110_TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+/**
+ * @primitive b.requestHelpers.parseListHeader
+ * @signature b.requestHelpers.parseListHeader(value, opts?)
+ * @since     0.5.17
+ * @related   b.requestHelpers.parseQualityList, b.requestHelpers.appendVary
+ *
+ * Split a comma-separated header / opt value into a list of trimmed
+ * non-empty tokens. Replaces the
+ * `String(x).split(",").map(s => s.trim()).filter(Boolean)` chain
+ * that was duplicated across cors / compression / scheduler /
+ * webhook / websocket / db-schema / cli before v0.5.17.
+ *
+ * Tolerant read: non-string input returns `[]` — these are read
+ * from request headers that the network might omit. Callers
+ * needing stricter checks layer their own validation on the
+ * result. The `strictToken` opt is the one exception — it throws
+ * on RFC 9110 §5.6.2 token-grammar violations, used by config-time
+ * entry points (WebSocket subprotocol negotiation etc.) where bad
+ * input MUST surface at boot.
+ *
+ * @opts
+ *   lowercase:   boolean   // lowercase every token before returning
+ *   strictToken: boolean   // throw on non-RFC 9110 token entries
+ *
+ * @example
+ *   b.requestHelpers.parseListHeader("a, b , ,c");
+ *   // → ["a", "b", "c"]
+ *
+ *   b.requestHelpers.parseListHeader("Foo, Bar", { lowercase: true });
+ *   // → ["foo", "bar"]
+ *
+ *   b.requestHelpers.parseListHeader(undefined);
+ *   // → []
+ *
+ *   try {
+ *     b.requestHelpers.parseListHeader("chat, bad token", { strictToken: true });
+ *   } catch (err) {
+ *     err.message;
+ *     // → "parseListHeader: 'bad token' is not a valid RFC 9110 token"
+ *   }
+ */
 function parseListHeader(value, opts) {
   if (value == null) return [];
   opts = opts || {};
@@ -241,10 +371,34 @@ function parseListHeader(value, opts) {
   return out;
 }
 
-// Append a token to a `Vary` response header without dropping prior
-// values (compression middleware sets `Vary: Accept-Encoding`, an
-// auth helper might set `Vary: Authorization`, etc.). Idempotent —
-// re-adding an existing token is a no-op.
+/**
+ * @primitive b.requestHelpers.appendVary
+ * @signature b.requestHelpers.appendVary(res, value)
+ * @since     0.5.17
+ * @related   b.requestHelpers.parseListHeader
+ *
+ * Append a token to a `Vary` response header without dropping
+ * prior values (compression middleware sets `Vary: Accept-
+ * Encoding`, an auth helper might set `Vary: Authorization`, etc.).
+ * Idempotent — re-adding an existing token (case-insensitive) is a
+ * no-op. Silently no-ops when `res` doesn't expose
+ * `getHeader`/`setHeader` so misuse during testing or in non-HTTP
+ * contexts never throws.
+ *
+ * @example
+ *   var headers = { Vary: "Accept-Encoding" };
+ *   var res = {
+ *     getHeader: function (n) { return headers[n]; },
+ *     setHeader: function (n, v) { headers[n] = v; },
+ *   };
+ *
+ *   b.requestHelpers.appendVary(res, "Authorization");
+ *   headers.Vary;   // → "Accept-Encoding, Authorization"
+ *
+ *   // Idempotent — re-adding is a no-op:
+ *   b.requestHelpers.appendVary(res, "accept-encoding");
+ *   headers.Vary;   // → "Accept-Encoding, Authorization"
+ */
 function appendVary(res, value) {
   if (!res || typeof res.getHeader !== "function" || typeof res.setHeader !== "function") return;
   var existing = res.getHeader("Vary");
@@ -256,6 +410,32 @@ function appendVary(res, value) {
   res.setHeader("Vary", tokens.join(", "));
 }
 
+/**
+ * @primitive b.requestHelpers.resolveRoute
+ * @signature b.requestHelpers.resolveRoute(req)
+ * @since     0.4.0
+ * @related   b.requestHelpers.extractActorContext, b.requestHelpers.captureResponseStatus
+ *
+ * Resolve the route pattern for a request. Prefers
+ * `req.routePattern` (set by `b.router` during dispatch — a
+ * low-cardinality template like `/users/:id` rather than the
+ * concrete URL), and falls back to `req.url` with the query
+ * string stripped. Returns `"/"` on missing or non-string input
+ * so audit-chain rows / metrics labels never carry `null`.
+ *
+ * @example
+ *   b.requestHelpers.resolveRoute({ routePattern: "/users/:id", url: "/users/42" });
+ *   // → "/users/:id"
+ *
+ *   b.requestHelpers.resolveRoute({ url: "/orders?ref=abc" });
+ *   // → "/orders"
+ *
+ *   b.requestHelpers.resolveRoute({});
+ *   // → "/"
+ *
+ *   b.requestHelpers.resolveRoute(undefined);
+ *   // → "/"
+ */
 function resolveRoute(req) {
   if (req && typeof req.routePattern === "string" && req.routePattern.length > 0) {
     return req.routePattern;
@@ -266,6 +446,40 @@ function resolveRoute(req) {
   return qIdx === -1 ? url : url.slice(0, qIdx);
 }
 
+/**
+ * @primitive b.requestHelpers.captureResponseStatus
+ * @signature b.requestHelpers.captureResponseStatus(res, onEnd)
+ * @since     0.4.0
+ * @related   b.requestHelpers.resolveRoute
+ *
+ * Wrap a response so observability / audit middleware can learn
+ * the final status code at end-of-stream. Patches `res.writeHead`
+ * and `res.end`; when `res.end()` fires, invokes `onEnd(status)`
+ * with the value passed to `writeHead` (preferred) or
+ * `res.statusCode` (fallback) or `200` (default). Errors thrown by
+ * the `onEnd` callback are swallowed — instrumentation must never
+ * break the response. Returns the original `end` function so
+ * callers that want to compose can keep a reference. Throws when
+ * either argument is missing — these are config-time wiring
+ * errors, surfaced loudly.
+ *
+ * @example
+ *   var headers = {};
+ *   var sent = null;
+ *   var res = {
+ *     statusCode: 200,
+ *     writeHead:  function (s) { this.statusCode = s; sent = "head"; },
+ *     end:        function () { sent = (sent || "end"); },
+ *   };
+ *
+ *   b.requestHelpers.captureResponseStatus(res, function (status) {
+ *     console.log("final status:", status);
+ *   });
+ *
+ *   res.writeHead(204);
+ *   res.end();
+ *   // → "final status: 204"
+ */
 function captureResponseStatus(res, onEnd) {
   if (!res || typeof onEnd !== "function") {
     throw new Error("captureResponseStatus: requires (res, onEnd)");
@@ -288,28 +502,46 @@ function captureResponseStatus(res, onEnd) {
   return origEnd;
 }
 
-// parseQualityList — RFC 9110 §12.5 Accept-* header parser.
-//
-// Returns `[{ value, q }]` sorted by q descending. Used by content
-// negotiation (`Accept-Encoding`, `Accept-Language`, `Accept`, etc.).
-// Each Accept-* middleware previously had its own copy of this loop;
-// extracting it here keeps the q-value semantics consistent
-// (q=0 = explicit exclusion; clamped to [0, 1]; missing q = 1).
-//
-//   parseQualityList("br;q=1.0, gzip;q=0.5, *;q=0")
-//     → [{ value: "br", q: 1 }, { value: "gzip", q: 0.5 }, { value: "*", q: 0 }]
-//
-// `value` is lowercased by default; pass `{ caseSensitive: true }` to
-// preserve case (BCP 47 language tags want case preservation since
-// `pt-BR` and `pt-br` resolve identically but operators may match by
-// canonical form themselves).
-//
-// Bad input (non-string, empty) returns []. RFC 9110 says an absent
-// Accept header means "accept anything"; callers handle that absence
-// at their own layer (compression's [{ encoding: "*", q: 1 }] default
-// vs i18n's "fall back to default locale" — different semantics).
 var Q_VALUE_RE = /(?:^|;|\s)q\s*=\s*([0-9]*\.?[0-9]+)/i;
 
+/**
+ * @primitive b.requestHelpers.parseQualityList
+ * @signature b.requestHelpers.parseQualityList(headerValue, opts?)
+ * @since     0.5.17
+ * @related   b.requestHelpers.parseListHeader
+ *
+ * RFC 9110 §12.5 `Accept-*` header parser. Returns
+ * `[{ value, q }]` sorted by q descending. Used by content
+ * negotiation (`Accept-Encoding`, `Accept-Language`, `Accept`, …).
+ * Each Accept-* middleware previously carried its own copy of this
+ * loop; centralizing it keeps the q-value semantics consistent —
+ * `q=0` is explicit exclusion, q is clamped to `[0, 1]`, missing q
+ * defaults to `1`. `value` is lowercased by default; pass
+ * `caseSensitive: true` to preserve case (BCP 47 language tags
+ * may need it). Bad input (non-string, empty) returns `[]` —
+ * absent Accept-* means "accept anything" but the right default
+ * differs by caller, so it's the caller's call to layer.
+ *
+ * @opts
+ *   caseSensitive: boolean   // preserve original case in `value`
+ *
+ * @example
+ *   b.requestHelpers.parseQualityList("br;q=1.0, gzip;q=0.5, *;q=0");
+ *   // → [
+ *   //     { value: "br",   q: 1   },
+ *   //     { value: "gzip", q: 0.5 },
+ *   //     { value: "*",    q: 0   },
+ *   //   ]
+ *
+ *   b.requestHelpers.parseQualityList("en-US,en;q=0.9", { caseSensitive: true });
+ *   // → [
+ *   //     { value: "en-US", q: 1   },
+ *   //     { value: "en",    q: 0.9 },
+ *   //   ]
+ *
+ *   b.requestHelpers.parseQualityList(undefined);
+ *   // → []
+ */
 function parseQualityList(headerValue, opts) {
   if (typeof headerValue !== "string" || headerValue.length === 0) return [];
   opts = opts || {};
@@ -339,19 +571,148 @@ function parseQualityList(headerValue, opts) {
   return out;
 }
 
-// safeHeadersDistinct(req) — defensive accessor for req.headersDistinct.
-//
-// Node CVE-2026-21710: req.headersDistinct is a getter; reading
-// __proto__ on the underlying header bag throws synchronously inside
-// the getter, so a request bearing a __proto__: header escapes any
-// handler-level try/catch (the throw happens at property-access time,
-// not later). This helper computes the same shape (lowercased header-
-// name → array of values) directly from req.rawHeaders, bypassing the
-// faulty getter entirely.
-//
-// Returns a null-prototype object so framework code can iterate its
-// keys without inheriting Object.prototype properties — the same shape
-// Node's headersDistinct produces, minus the throwing getter.
+/**
+ * @primitive b.requestHelpers.extractBearer
+ * @signature b.requestHelpers.extractBearer(req)
+ * @since     0.7.19
+ * @related   b.requestHelpers.safeHeadersDistinct, b.middleware.bearerAuth, b.guardJwt
+ *
+ * RFC 6750 §2.1 inbound bearer-token extractor. Reads the
+ * `Authorization` request header, validates the case-insensitive
+ * `Bearer ` scheme, and returns the trimmed token string. Returns
+ * `null` on any malformed shape — defensive by design, since this
+ * runs on every authenticated request and a throw here would crash
+ * the request itself. Callers that require a token throw their
+ * own authentication-shape error when `null` surfaces.
+ *
+ * Refusal cases (all return `null`): missing Authorization header,
+ * non-string value, multiple Authorization headers (CWE-345 trust
+ * mismatch), scheme other than `Bearer` (case-insensitive), missing
+ * space + token after the scheme, embedded CR / LF / NUL / Tab /
+ * other ASCII control bytes (CRLF-injection defense — the token
+ * transits log lines + audit metadata), embedded spaces inside the
+ * token. Token shape past the scheme word is NOT validated against
+ * the RFC 6750 b64token grammar here — `b.guardJwt` /
+ * `b.middleware.bearerAuth` own format-specific checks.
+ *
+ * The outbound counterpart is `b.authHeader.bearer(token)`, which
+ * constructs `Authorization: Bearer <token>` for outgoing requests.
+ *
+ * @example
+ *   var req = { headers: { authorization: "Bearer eyJhbGciOiJFUzI1NiJ9.payload.sig" } };
+ *   b.requestHelpers.extractBearer(req);
+ *   // → "eyJhbGciOiJFUzI1NiJ9.payload.sig"
+ *
+ *   // Case-insensitive scheme:
+ *   b.requestHelpers.extractBearer({ headers: { authorization: "bearer abc123" } });
+ *   // → "abc123"
+ *
+ *   // Refusals return null:
+ *   b.requestHelpers.extractBearer({ headers: { authorization: "Basic dXNlcjpwYXNz" } });
+ *   // → null
+ *
+ *   b.requestHelpers.extractBearer({ headers: { authorization: "Bearer abc, def" } });
+ *   // → null
+ *
+ *   b.requestHelpers.extractBearer({});
+ *   // → null
+ */
+function extractBearer(req) {
+  if (!req || typeof req !== "object") return null;
+  // Distinct-header scan first — multiple Authorization headers is a
+  // trust-mismatch shape (CWE-345); refuse rather than pick one. Node's
+  // h1 parser folds duplicate Authorization values with ", " joining
+  // by default, so the multi-value detection must look at rawHeaders
+  // (or headersDistinct via safeHeadersDistinct).
+  if (Array.isArray(req.rawHeaders)) {
+    var seen = 0;
+    for (var ri = 0; ri + 1 < req.rawHeaders.length; ri += 2) {
+      var name = req.rawHeaders[ri];
+      if (typeof name === "string" && name.toLowerCase() === "authorization") {
+        seen += 1;
+        if (seen > 1) return null;
+      }
+    }
+  }
+  var headers = req.headers;
+  if (!headers || typeof headers !== "object") return null;
+  var raw = headers["authorization"];
+  if (raw === undefined) raw = headers["Authorization"];
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  // A pre-folded duplicate (Node h1 default) shows up as a comma in the
+  // value — refuse, same trust-mismatch class. Bearer tokens themselves
+  // never contain commas (RFC 6750 b64token grammar).
+  if (raw.indexOf(",") !== -1) return null;
+  // Reject ASCII control characters BEFORE prefix-matching so a header
+  // like "Bearer\rinjected" never reaches consumers.
+  for (var ci = 0; ci < raw.length; ci += 1) {
+    var cc = raw.charCodeAt(ci);
+    if (cc === 0x00 || cc === 0x0A || cc === 0x0D || cc === 0x09 || cc < 0x20 || cc === 0x7F) {
+      return null;
+    }
+  }
+  // RFC 6750 §2.1 — auth-scheme is case-insensitive. The "Bearer "
+  // prefix + at least one token byte must be present; the literal
+  // 7-byte prefix length (6 letters + space) matches "Bearer " and
+  // its case variants.
+  if (raw.length < 8) return null;                                                  // allow:raw-byte-literal — RFC 6750 §2.1 "Bearer " prefix (7 chars) + ≥1 token byte, char count not bytes
+  if (raw.charAt(6) !== " ") return null;
+  var schemeLower = raw.slice(0, 6).toLowerCase();
+  if (schemeLower !== "bearer") return null;
+  var token = raw.slice(7);
+  // Trim whitespace per RFC 7230 OWS tolerance — but only the leading /
+  // trailing space; embedded whitespace in a Bearer token is not RFC
+  // 6750 b64token-shaped and is refused above (cc === 0x09 / 0x20 < cc
+  // already covers control + delete; spaces inside the token would
+  // pass the control check, so handle explicitly).
+  while (token.length > 0 && token.charAt(0) === " ") token = token.slice(1);
+  while (token.length > 0 && token.charAt(token.length - 1) === " ") {
+    token = token.slice(0, -1);
+  }
+  if (token.length === 0) return null;
+  // Refuse embedded spaces — a properly-formed bearer credential is
+  // a single token. Embedded space would slip a second value past
+  // operators that read the trailing portion as JWT / opaque-id.
+  if (token.indexOf(" ") !== -1) return null;
+  return token;
+}
+
+/**
+ * @primitive b.requestHelpers.safeHeadersDistinct
+ * @signature b.requestHelpers.safeHeadersDistinct(req)
+ * @since     0.7.0
+ * @related   b.requestHelpers.extractBearer
+ *
+ * Defensive replacement for `req.headersDistinct`. Node CVE
+ * 2026-21710: `headersDistinct` is implemented as a getter, and
+ * reading `__proto__` on the underlying header bag throws
+ * synchronously inside the getter. A request bearing a
+ * `__proto__:` header therefore escapes any handler-level
+ * try/catch — the throw happens at property-access time, not
+ * later. This helper computes the same shape (lowercased
+ * header-name to array of values) directly from `req.rawHeaders`,
+ * skipping `__proto__` / `constructor` / `prototype` keys, and
+ * returns a null-prototype object so iteration never inherits
+ * `Object.prototype` properties. Always returns an object — never
+ * throws.
+ *
+ * @example
+ *   var req = {
+ *     rawHeaders: [
+ *       "Set-Cookie", "a=1",
+ *       "Set-Cookie", "b=2",
+ *       "X-Trace",    "abc",
+ *       "__proto__",  "polluted",
+ *     ],
+ *   };
+ *   var headers = b.requestHelpers.safeHeadersDistinct(req);
+ *   headers["set-cookie"];   // → ["a=1", "b=2"]
+ *   headers["x-trace"];      // → ["abc"]
+ *   headers["__proto__"];    // → undefined   (prototype-pollution key dropped)
+ *
+ *   b.requestHelpers.safeHeadersDistinct(undefined);
+ *   // → {}   (null-prototype empty object)
+ */
 function safeHeadersDistinct(req) {
   var out = Object.create(null);
   if (!req || !Array.isArray(req.rawHeaders)) return out;
@@ -384,5 +745,8 @@ module.exports = {
   appendVary:                appendVary,
   // CVE-2026-21710 wrap — safe alternative to req.headersDistinct
   safeHeadersDistinct:       safeHeadersDistinct,
+  // RFC 6750 §2.1 inbound bearer-token extractor (returns null on
+  // missing / malformed input — symmetric to outbound b.authHeader.bearer)
+  extractBearer:             extractBearer,
   HTTP_STATUS:               HTTP_STATUS,
 };