@blamejs/core 0.18.43 → 0.18.45

package/lib/guard-oauth.js

@@ -466,9 +466,7 @@ function _detectIssues(flow, opts) {
 // sanitize AFTER resolve -> detect -> throwOnRefusalSeverity. OAuth flows
 // can't be repaired: any critical/high finding refuses upstream, so the
 // transform passes the already-validated bundle through unchanged.
-function _sanitizeTransform(input) {
-  return input;
-}
+var _sanitizeTransform = gateContract.identitySanitize;
 
 /**
  * @primitive  b.guardOauth.gate

package/lib/guard-pdf.js

@@ -136,6 +136,11 @@ var PROFILES = Object.freeze({
 
 var DEFAULTS = gateContract.strictDefaults(PROFILES);
 
+// The options that are genuinely CAPS, where zero is not a setting — named once
+// so this guard's hand-bound gate holds a caller to the same rules the
+// generated validate() does. See guard-image for the full reasoning.
+var INT_OPTS = ["maxBytes", "maxPageCount"];
+
 var COMPLIANCE_POSTURES = gateContract.compliancePostures(PROFILES, { base: 512 });
 
 function _hasPdfMagic(buf) {
@@ -436,6 +441,9 @@ function gate(opts) {
     defaults:           DEFAULTS,
     errorClass:         GuardPdfError,
     errCodePrefix:      "pdf",
+    // Own resolver, own cap declaration — see guard-image.gate.
+    intOpts:            INT_OPTS,
+    nonNegativeOpts:    gateContract.capKeysOf(DEFAULTS),
   });
   return gateContract.buildGuardGate(
     opts.name || "guardPdf:" + (opts.profile || "default"),

package/lib/guard-regex.js

@@ -2658,9 +2658,7 @@ function _detectNestedExtglob(input, opts, issues) {
 // sanitize AFTER resolve -> detect -> throwOnRefusalSeverity. Regex patterns
 // cannot be safely repaired, so the transform is a pass-through: a non-string
 // or any critical/high finding refuses upstream, clean input returns verbatim.
-function _sanitizeTransform(input) {
-  return input;
-}
+var _sanitizeTransform = gateContract.identitySanitize;
 
 /**
  * @primitive  b.guardRegex.gate
@@ -2711,7 +2709,10 @@ function gate(opts) {
     opts.name || "guardRegex:" + (opts.profile || "default"),
     opts,
     async function (ctx) {
-      var pattern = ctx && (ctx.identifier || ctx.pattern);
+      // The shared reader, not an `||` chain: the chain collapses a field
+      // present as "" into the next one and ultimately into undefined, so an
+      // empty pattern served while validate("") refused it.
+      var pattern = gateContract.ctxValueFrom(ctx, ["identifier", "pattern"]);
       if (pattern === undefined || pattern === null) {
         return { ok: true, action: "serve" };
       }

package/lib/guard-smtp-command.js

@@ -473,8 +473,10 @@ function gate(opts) {
   _resolveProfile(opts);
   var name = opts.name || "guardSmtpCommand:" + (opts.profile || opts.posture || "default");
   return gateContract.buildGuardGate(name, opts, async function (ctx) {
-    var line = ctx && (ctx.identifier || ctx.commandLine || "");
-    if (!line) return { ok: true, action: "serve" };
+    // The shared reader, not an `||` chain — see guard-regex.gate. An empty
+    // command line is a value the validator refuses, not an absent field.
+    var line = gateContract.ctxValueFrom(ctx, ["identifier", "commandLine"]);
+    if (line === undefined || line === null) return { ok: true, action: "serve" };
     try {
       validate(line, opts);
       return { ok: true, action: "serve" };

package/lib/guard-sql.js

@@ -522,6 +522,12 @@ var DEFAULTS = gateContract.strictDefaults(PROFILES, {
   gdprRedact:   false,
 });
 
+// The options that are genuinely CAPS, where zero is not a setting — named once
+// so this guard's hand-bound resolver holds a caller to the same rules the
+// generated validate() does. maxRuntimeMs is deliberately absent: zero there
+// means no runtime budget. See guard-image for the full reasoning.
+var INT_OPTS = ["maxBytes"];
+
 // All four postures map to the strict floor — a regulated deployment
 // gets the tightest raw-SQL gate regardless of which framework it cites.
 // gdpr additionally redacts the fragment body in the audit trail
@@ -542,6 +548,9 @@ function _resolveOpts(opts) {
     defaults:           DEFAULTS,
     errorClass:         GuardSqlError,
     errCodePrefix:      "sql",
+    // Own resolver, own cap declaration — see guard-image.gate.
+    intOpts:            INT_OPTS,
+    nonNegativeOpts:    gateContract.capKeysOf(DEFAULTS),
   });
 }
 
@@ -1565,6 +1574,7 @@ module.exports = gateContract.defineGuard({
   integrationFixtures: INTEGRATION_FIXTURES,
   validate:    validate,
   sanitize:    sanitize,
+  intOpts:     INT_OPTS,
   gate:        gate,
   extra: {
     MIME_TYPES:    Object.freeze(["application/sql"]),

package/lib/guard-svg.js

@@ -1016,7 +1016,8 @@ var _guard = module.exports = gateContract.defineGuard({
   extensions:  [".svg", ".svgz"],
   integrationFixtures: INTEGRATION_FIXTURES,
   detect:      _detectIssues,
-  intOpts:     ["maxBytes", "maxElementCount", "maxUseDepth"],
+  intOpts:     ["maxBytes", "maxElementCount", "maxUseDepth",
+                "maxAttrValueBytes", "maxAttrsPerTag"],
   sanitize:    sanitize,
   gate:        gate,
   extra: {

package/lib/guard-text.js

@@ -114,6 +114,12 @@ var DEFAULTS = gateContract.strictDefaults(PROFILES, {
 
 var COMPLIANCE_POSTURES = gateContract.compliancePostures(PROFILES, { base: 256 });
 
+// The options that are genuinely CAPS, where zero is not a setting — named once
+// so this guard's hand-bound resolver holds a caller to the same rules the
+// generated validate() does. maxRuntimeMs is deliberately absent: zero there
+// means no runtime budget. See guard-image for the full reasoning.
+var INT_OPTS = ["maxBytes"];
+
 // ---- Internal helpers ----
 
 function _resolveOpts(opts) {
@@ -123,6 +129,9 @@ function _resolveOpts(opts) {
     defaults:           DEFAULTS,
     errorClass:         GuardTextError,
     errCodePrefix:      "text",
+    // Own resolver, own cap declaration — see guard-image.gate.
+    intOpts:            INT_OPTS,
+    nonNegativeOpts:    gateContract.capKeysOf(DEFAULTS),
   });
 }
 
@@ -573,5 +582,6 @@ module.exports = gateContract.defineGuard({
   integrationFixtures: INTEGRATION_FIXTURES,
   validate:    validate,
   sanitize:    sanitize,
+  intOpts:     INT_OPTS,
   gate:        gate,
 });

package/lib/guard-yaml.js

@@ -259,6 +259,12 @@ var DEFAULTS = gateContract.strictDefaults(PROFILES, {
 
 var COMPLIANCE_POSTURES = gateContract.compliancePostures(PROFILES, { base: 256 });
 
+// The options that are genuinely CAPS, where zero is not a setting — named once
+// so this guard's hand-bound parse() and gate() hold a caller to the same rules
+// the generated validate() does. See guard-image for the full reasoning.
+var INT_OPTS = ["maxBytes", "maxDepth", "maxAnchors", "maxAliasDepth",
+                "maxDocuments", "maxNodes", "maxScalarLength"];
+
 // Document separators — a `---` at the start of a line, followed by
 // whitespace. A line starts at index 0 or after an LF, and those are separate
 // facts: a document that opens with a blank line has its first separator at
@@ -642,6 +648,9 @@ function parse(input, opts) {
     defaults:           DEFAULTS,
     errorClass:         GuardYamlError,
     errCodePrefix:      "yaml",
+    // Own resolver, own cap declaration — see guard-image.gate.
+    intOpts:            INT_OPTS,
+    nonNegativeOpts:    gateContract.capKeysOf(DEFAULTS),
   });
   if (typeof input !== "string") {
     throw _err("yaml.bad-input", "parse requires string input");
@@ -788,6 +797,9 @@ function gate(opts) {
     defaults:           DEFAULTS,
     errorClass:         GuardYamlError,
     errCodePrefix:      "yaml",
+    // Own resolver, own cap declaration — see guard-image.gate.
+    intOpts:            INT_OPTS,
+    nonNegativeOpts:    gateContract.capKeysOf(DEFAULTS),
   });
   return gateContract.buildContentGate({
     name:     opts.name || "guardYaml:" + (opts.profile || "default"),
@@ -809,8 +821,7 @@ module.exports = gateContract.defineGuard({
   extensions:  [".yml", ".yaml"],
   integrationFixtures: INTEGRATION_FIXTURES,
   detect:      _detectIssues,
-  intOpts:     ["maxBytes", "maxDepth", "maxAnchors", "maxAliasDepth",
-                "maxDocuments", "maxNodes", "maxScalarLength"],
+  intOpts:     INT_OPTS,
   gate:              gate,
   dispositionFor:    _gateDispositionFor,
   sanitizeTransform: _sanitizeTransform,

package/lib/mail-auth.js

@@ -1184,9 +1184,10 @@ async function _fetchDmarcRecord(domain, dnsLookup) {
 // eight queries however long it is. That is a denial-of-service guard on the
 // RECEIVER, not a nicety — the sender picks the domain.
 // RFC 1035 §2.3.4 — the wire form of a name is at most 253 octets, and a single
-// label at most 63.
+// label at most 63. The per-label bound is enforced by canonicalDomain, so only
+// the qname total is measured here: `_dmarc.` is PREPENDED after
+// canonicalization and can push a name that was inside 253 past it.
 var DMARC_MAX_QNAME_OCTETS = 253;
-var DNS_MAX_LABEL_OCTETS = 63;
 var DMARC_TREE_WALK_MAX_LABELS = 8;
 var DMARC_TREE_WALK_LABEL_FLOOR = 7;
 
@@ -1224,18 +1225,15 @@ function _dmarcAuthorDomainLabels(domain) {
   // both sides end up in one canonical form.
   var d = publicSuffix.canonicalDomain(String(domain));
   if (!d) return null;
-  // RFC 1035 §2.3.4 bounds a LABEL at 1..63 octets as well as the whole name at
-  // 253, and `canonicalDomain` enforces only the second — it is the framework's
-  // definition of a domain NAME, and a label cap is a DNS wire rule rather than
-  // a naming one. Checking it here keeps the answer the same whichever resolver
-  // is wired in: the default one refuses an over-long label as `dns/bad-host`
-  // and the evaluation temperrors, while an operator's own `dnsLookup` would
-  // answer for it and let a policy apply to a name that cannot exist.
-  var labels = d.split(".");
-  for (var i = 0; i < labels.length; i += 1) {
-    if (labels[i].length === 0 || labels[i].length > DNS_MAX_LABEL_OCTETS) return null;
-  }
-  return labels;
+  // Both RFC 1035 §2.3.4 bounds — 63 octets per label and 253 for the whole
+  // name — are enforced by `canonicalDomain` itself, so an over-long or empty
+  // label has already returned "" above. This function used to re-check the
+  // label bound because canonicalDomain enforced only the total; the comment
+  // here argued a label cap was a DNS wire rule rather than a naming one, which
+  // did not survive the observation that the 253 cap is equally a wire rule and
+  // was enforced there anyway. Fixing it at the definition means every caller
+  // gets it, not just this one.
+  return d.split(".");
 }
 
 // The ordered list of names the walk queries, starting with the domain itself.

package/lib/middleware/index.js

@@ -26,6 +26,7 @@ var flagContext = require("./flag-context");
 var assetlinks = require("./assetlinks");
 var attachUser = require("./attach-user");
 var bearerAuth = require("./bearer-auth");
+var sharedSecretHeader = require("./shared-secret-header");
 var bodyParser = require("./body-parser");
 var clearSiteData = require("./clear-site-data");
 var botDisclose = require("./bot-disclose");
@@ -84,6 +85,7 @@ module.exports = {
   rateLimit:        rateLimit.create,
   attachUser:       attachUser.create,
   bearerAuth:       bearerAuth.create,
+  sharedSecretHeader: sharedSecretHeader.create,
   requireAal:       requireAal.create,
   requireAuth:      requireAuth.create,
   requireContentType: requireContentType.create,
@@ -149,6 +151,7 @@ module.exports = {
     rateLimit:        rateLimit,
     attachUser:       attachUser,
     bearerAuth:       bearerAuth,
+    sharedSecretHeader: sharedSecretHeader,
     requireAal:       requireAal,
     requireAuth:      requireAuth,
     requireContentType: requireContentType,

package/lib/middleware/shared-secret-header.js

@@ -0,0 +1,334 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * shared-secret-header middleware — a named header carrying a shared secret,
+ * compared in constant time.
+ *
+ * This is the third common way a request authenticates itself. The other two
+ * already have primitives: `Authorization: Bearer` is `b.middleware.bearerAuth`,
+ * and a signed webhook is `b.webhookHmac` / `b.webhook.verify`. A named custom
+ * header holding a fixed secret is what internal service-to-service calls,
+ * cron triggers and platform bridges use, and hand-rolling it puts four
+ * conditions in one expression that have to be in the right order:
+ *
+ *   - the LENGTH check comes first, because `b.crypto.timingSafeEqual` throws
+ *     on a length mismatch rather than returning false. A compare that runs
+ *     first turns a wrong-length header into a 500.
+ *   - an UNCONFIGURED secret refuses. A deployment that forgot the environment
+ *     variable is otherwise wide open, and looks configured.
+ *   - the compare does not short-circuit, which is the whole reason
+ *     timingSafeEqual is there and the thing a `===` "optimisation" removes.
+ *   - an AVAILABILITY failure is not an authentication failure. A secret
+ *     resolver that throws still denies — fail closed — but answers 503, so an
+ *     operator sees a dependency outage rather than a flood of bad
+ *     credentials, and a caller holding the right secret is not told it is
+ *     wrong.
+ *
+ * Every refusal is byte-identical, so the gate cannot be used as an oracle for
+ * which condition failed.
+ */
+
+var C = require("../constants");
+var codepointClass = require("../codepoint-class");
+var bCrypto = require("../crypto");
+var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
+var safeBuffer = require("../safe-buffer");
+var validateOpts = require("../validate-opts");
+var denyResponse = require("./deny-response").denyResponse;
+var { AuthError } = require("../framework-error");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+var observability = lazyRequire(function () { return require("../observability"); });
+
+var _err = AuthError.factory;
+
+// RFC 9110 §5.6.2 tchar: "!#$%&'*+-.^_`|~", DIGIT, ALPHA. Everything else is a
+// delimiter or a control and cannot appear in a field name. Index of the first
+// offending character, or -1.
+var _TCHAR_SPECIALS = "!#$%&'*+-.^_`|~";
+// How many times `lowerName` appears on the wire. node's IncomingMessage JOINS
+// duplicate custom headers into one comma-separated string rather than exposing
+// an array (only a documented few, like set-cookie, become arrays), so an
+// Array.isArray() check never fires for a custom header — and `rawHeaders` is
+// the only place the duplication is still visible.
+//
+// Returns -1 when the request does not expose rawHeaders at all (a non-node
+// request object, or a framework that rebuilds the request), so the caller can
+// tell "no duplicates" from "cannot tell" instead of reading the second as the
+// first.
+function _rawHeaderCount(req, lowerName) {
+  var raw = req && req.rawHeaders;
+  if (!Array.isArray(raw)) return -1;
+  var n = 0;
+  for (var i = 0; i + 1 < raw.length; i += 2) {
+    if (String(raw[i]).toLowerCase() === lowerName) n += 1;
+  }
+  return n;
+}
+
+function _firstNonTokenChar(s) {
+  for (var i = 0; i < s.length; i += 1) {
+    var cc = s.charCodeAt(i);
+    if (codepointClass.isAsciiAlnum(cc)) continue;
+    if (_TCHAR_SPECIALS.indexOf(s.charAt(i)) !== -1) continue;
+    return i;
+  }
+  return -1;
+}
+
+/**
+ * @primitive b.middleware.sharedSecretHeader
+ * @signature b.middleware.sharedSecretHeader(req, res, next)
+ * @since     0.18.44
+ * @status    stable
+ * @related   b.middleware.bearerAuth, b.webhookHmac, b.crypto.timingSafeEqual
+ *
+ * Require a named header to carry a shared secret, compared in constant time.
+ * The shape internal service-to-service calls, cron triggers and platform
+ * bridges use, alongside `bearerAuth` for `Authorization: Bearer` and
+ * `b.webhookHmac` for a signed webhook. Constructed via
+ * `b.middleware.sharedSecretHeader(opts)`; the resulting middleware has the
+ * `(req, res, next)` shape shown above.
+ *
+ * `secret` is either the value itself or a function returning it — the
+ * resolver form covers a secrets manager or a rotating value, and may be
+ * async. Whichever form, an absent or empty secret REFUSES every request. That
+ * is the documented default rather than a flag, because the alternative is a
+ * deployment that forgot its environment variable, accepts everything, and
+ * looks configured.
+ *
+ * A resolver that THROWS is treated differently from one that returns nothing.
+ * Returning nothing means unconfigured, which is an authentication failure —
+ * 401. Throwing means the secret could not be fetched, which is not: the
+ * caller may well hold the right value and the framework cannot tell. That
+ * still denies, but with 503, so the log shows a dependency outage instead of
+ * credential failures and a monitor does not page the wrong team.
+ *
+ * A resolver that returns something which is not a secret — a `Buffer` from a
+ * secrets-manager SDK, a number, a parsed JSON envelope — takes the same 503,
+ * for the same reason: no usable secret was obtained. Reporting that as 401
+ * would tell the operator their callers are wrong and bury a bug in their own
+ * resolver under a wall of credential failures.
+ *
+ * `headerName` must be an RFC 9110 §5.1 token, and a name carrying a space, a
+ * colon or any other delimiter is refused at construction. Such a name can
+ * never match an incoming header, so the gate would refuse every request
+ * forever — and those refusals are indistinguishable from a caller presenting
+ * the wrong secret, which is the worst place for a typo to surface.
+ *
+ * Every refusal — absent header, wrong length, wrong value, repeated header,
+ * unconfigured secret — produces the same status and body, so the gate is not
+ * an oracle for which of them it was.
+ *
+ * The repeated-header refusal reads `req.rawHeaders`, because Node joins
+ * duplicate custom headers into one comma-separated string rather than an
+ * array: without it, a secret equal to the joined value would authenticate a
+ * request in which no single header carried it. That reaches as far as this
+ * process can see. A reverse proxy that MERGES duplicates before Node receives
+ * them leaves one header on the wire and nothing to detect — if the deployment
+ * relies on this refusal, configure the proxy to reject duplicate occurrences
+ * of the header rather than fold them.
+ *
+ * @opts
+ *   headerName:     string,     // required — an RFC 9110 token, e.g. "x-internal-secret"
+ *   secret:         string | function,   // value, or () => value (may be async)
+ *   audit:          boolean,    // default true — emit auth.shared_secret.* rows
+ *   errorMessage:   string,     // default "Unauthorized"
+ *   onDeny:         function,   // custom refusal writer
+ *   problemDetails: boolean,    // RFC 9457 application/problem+json refusals
+ *
+ * @example
+ *   router.use("/internal", b.middleware.sharedSecretHeader({
+ *     headerName: "x-internal-secret",
+ *     secret:     process.env.INTERNAL_SECRET,
+ *   }));
+ *   // → a request without the exact secret never reaches the route
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "headerName", "secret", "audit", "errorMessage", "onDeny", "problemDetails",
+  ], "middleware.sharedSecretHeader");
+
+  var headerName = opts.headerName;
+  if (typeof headerName !== "string" || headerName.length === 0) {
+    throw _err("auth-shared-secret/bad-header-name",
+      "middleware.sharedSecretHeader: opts.headerName must be a non-empty string");
+  }
+  // A field name is an RFC 9110 §5.1 token. A name carrying a space, a colon or
+  // any other delimiter can never match an incoming header, so the gate would
+  // refuse every request forever — and those 401s are indistinguishable from a
+  // caller presenting the wrong secret. That is a configuration typo, so it
+  // belongs at boot where the operator sees it, not at request time where it
+  // looks like an attack.
+  if (_firstNonTokenChar(headerName) !== -1) {
+    throw _err("auth-shared-secret/bad-header-name",
+      "middleware.sharedSecretHeader: opts.headerName must be an RFC 9110 token " +
+      "(no spaces, colons or delimiters); got " + JSON.stringify(headerName));
+  }
+  // Node lowercases incoming header names; normalise once at construction so
+  // an operator can configure it in any case.
+  var headerKey = headerName.toLowerCase();
+
+  // A secret that is neither a string nor a resolver is a configuration
+  // mistake, and belongs at boot rather than as a per-request surprise. An
+  // ABSENT secret is deliberately NOT refused here: that is the deployment
+  // that forgot its environment variable, and it must fail closed at request
+  // time rather than stop the process from starting, so the operator sees
+  // 401s and an audit trail rather than a boot loop.
+  if (opts.secret !== undefined && opts.secret !== null &&
+      typeof opts.secret !== "string" && typeof opts.secret !== "function") {
+    throw _err("auth-shared-secret/bad-secret",
+      "middleware.sharedSecretHeader: opts.secret must be a string or a function " +
+      "returning one; got " + typeof opts.secret);
+  }
+
+  var auditOn = opts.audit !== false;
+  var errorMessage = typeof opts.errorMessage === "string" ? opts.errorMessage : "Unauthorized";
+  var onDeny = typeof opts.onDeny === "function" ? opts.onDeny : null;
+  var problemMode = opts.problemDetails === true;
+
+  function _emit(req, action, reason) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   action,
+        outcome:  "denied",
+        reason:   reason,
+        actor:    requestHelpers.extractActorContext(req),
+        metadata: { header: headerKey, method: req.method, path: requestHelpers.resolveRoute(req) },
+      });
+    } catch (_e) { /* drop-silent — an audit failure must not decide the request */ }
+  }
+
+  // One refusal writer for every deny path. The status varies (401 vs 503)
+  // because those are different facts about the world, but the BODY does not:
+  // a caller must not be able to tell an absent header from a wrong value.
+  function _refuse(req, res, status, reason) {
+    if (res.writableEnded) return;
+    denyResponse(req, res, {
+      onDeny:        onDeny,
+      problem:       problemMode,
+      status:        status,
+      info:          { status: status, reason: reason },
+      problemCode:   "shared-secret-" + reason,
+      problemTitle:  status === C.HTTP.STATUS.SERVICE_UNAVAILABLE ? "Service Unavailable" : "Unauthorized",
+      problemDetail: errorMessage,
+      contentType:   "text/plain; charset=utf-8",
+      body:          errorMessage,
+    });
+  }
+
+  return async function sharedSecretHeader(req, res, next) {
+    var headers = req.headers || {};
+    var presented = headers[headerKey];
+
+    // A repeated header is refused, whichever way the runtime represents it.
+    // node JOINS duplicate custom headers into one comma-separated string
+    // rather than an array, so checking Array.isArray alone would never fire
+    // on a real request — and a secret that happened to equal the joined value
+    // ("alpha, beta" against header lines `alpha` and `beta`) would
+    // authenticate a request in which NO single header carried the secret.
+    // Verified against node directly: two lines arrive as "alpha, beta" with
+    // both occurrences visible only in rawHeaders.
+    //
+    // Refused before the secret is resolved: the request is malformed whatever
+    // the configuration is, and there is no reason to call an operator's
+    // resolver for it.
+    if (Array.isArray(presented) || _rawHeaderCount(req, headerKey) > 1) {
+      _emit(req, "auth.shared_secret.failure", "header-repeated");
+      return _refuse(req, res, C.HTTP.STATUS.UNAUTHORIZED, "unauthorized");
+    }
+
+    // Absence is decided BEFORE the secret is resolved. `opts.secret` may be a
+    // resolver backed by a secrets manager, and awaiting it first let an
+    // unauthenticated client drive that dependency once per request — traffic
+    // and latency it never had to earn, and an outage it could amplify — while
+    // presenting no credential at all.
+    //
+    // The verdict is unchanged; only its cost is. During a resolver outage a
+    // request with no header now answers 401 rather than 503, which is the more
+    // accurate of the two: the caller brought no credential, so the
+    // dependency's health is not what decided it.
+    if (typeof presented !== "string" || presented.length === 0) {
+      _emit(req, "auth.shared_secret.failure", "header-absent");
+      return _refuse(req, res, C.HTTP.STATUS.UNAUTHORIZED, "unauthorized");
+    }
+
+    var want;
+    if (typeof opts.secret === "function") {
+      try {
+        want = await opts.secret(req);
+      } catch (e) {
+        // The secret could not be FETCHED. Not an auth failure — the caller
+        // may hold the right value and there is no way to know. Deny, but say
+        // so honestly.
+        //
+        // Contained, including the lazy module load: a broken metrics registry
+        // must not throw past this point, because the throw would escape the
+        // handler and the router would answer 500. Telemetry does not get to
+        // decide the response — least of all on the path whose whole purpose
+        // is to fail closed with an honest 503.
+        try {
+          observability().safeEvent("auth.shared_secret.unavailable", 1, { header: headerKey });
+        } catch (_o) { /* drop-silent — see above */ }
+        _emit(req, "auth.shared_secret.unavailable", "secret-resolver-failed: " + ((e && e.message) || String(e)));
+        return _refuse(req, res, C.HTTP.STATUS.SERVICE_UNAVAILABLE, "unavailable");
+      }
+    } else {
+      want = opts.secret;
+    }
+
+    // A resolver that hands back something that is NOT a secret — a Buffer
+    // from a secrets-manager SDK, a number, a parsed JSON envelope — is a bug
+    // in the resolver, not a deployment that forgot to configure one. Both
+    // deny, but reporting this as 401 tells the operator their CALLERS are
+    // wrong and buries the real cause under a wall of credential failures. It
+    // is the same fact as a resolver that threw: no usable secret was
+    // obtained, so it takes the same 503.
+    if (want !== undefined && want !== null && typeof want !== "string") {
+      try {
+        observability().safeEvent("auth.shared_secret.unavailable", 1, { header: headerKey });
+      } catch (_o) { /* drop-silent — telemetry never decides the response */ }
+      _emit(req, "auth.shared_secret.unavailable",
+        "secret-resolver-returned-" + (Buffer.isBuffer(want) ? "buffer" : typeof want));
+      return _refuse(req, res, C.HTTP.STATUS.SERVICE_UNAVAILABLE, "unavailable");
+    }
+
+    // Unconfigured refuses. FIRST, before anything about the request, so a
+    // deployment missing its secret cannot be talked into accepting by any
+    // header at all.
+    if (typeof want !== "string" || want.length === 0) {
+      _emit(req, "auth.shared_secret.failure", "secret-not-configured");
+      return _refuse(req, res, C.HTTP.STATUS.UNAUTHORIZED, "unauthorized");
+    }
+
+
+    var got = safeBuffer.toBuffer(presented, { encoding: "utf8" });
+    var expected = safeBuffer.toBuffer(want, { encoding: "utf8" });
+    // Length BEFORE the compare: timingSafeEqual throws on a length mismatch
+    // rather than returning false, so a compare-first ordering turns a
+    // wrong-length header into a 500. The length of a secret is not itself a
+    // secret, so answering early here leaks nothing the header size did not.
+    if (got.length !== expected.length || !bCrypto.timingSafeEqual(got, expected)) {
+      _emit(req, "auth.shared_secret.failure", "mismatch");
+      return _refuse(req, res, C.HTTP.STATUS.UNAUTHORIZED, "unauthorized");
+    }
+
+    if (auditOn) {
+      try {
+        audit().safeEmit({
+          action:   "auth.shared_secret.success",
+          outcome:  "success",
+          actor:    requestHelpers.extractActorContext(req),
+          metadata: { header: headerKey, method: req.method, path: requestHelpers.resolveRoute(req) },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    return next();
+  };
+}
+
+module.exports = { create: create };