@blamejs/core 0.7.107 → 0.8.4

package/lib/flag.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * b.flag — feature-flag client per the OpenFeature specification
+ * (https://openfeature.dev/specification/).
+ *
+ *   var flag = b.flag.create({
+ *     provider: b.flag.providers.localFile({ path: "./flags.json" }),
+ *     defaultEvaluationContext: { environment: "production" },
+ *   });
+ *
+ *   var enabled = flag.getBoolean("new-checkout-flow", { targetingKey: req.user.id });
+ *   var sample  = flag.getString ("greeting-banner", { targetingKey: req.user.id }, "default-text");
+ *   var rate    = flag.getNumber ("upsell-rate",     { targetingKey: req.user.id }, 0);
+ *   var cfg     = flag.getObject ("checkout-config", { targetingKey: req.user.id }, {});
+ *
+ *   var details = flag.getDetails("new-checkout-flow", ctx);
+ *   //  → { value, variant, reason, metadata }
+ *
+ *   flag.middleware()  → request-time middleware that attaches a
+ *                         per-request `flag` accessor onto req.
+ *
+ * Per the validation-tier policy: create() throws on bad opts; the
+ * hot-path getValue / getBoolean / etc. NEVER throw — they return the
+ * operator-supplied default + emit `flag.evaluation.error` on the
+ * audit chain so the operator sees the problem without taking down
+ * the request.
+ */
+
+var validateOpts   = require("./validate-opts");
+var lazyRequire    = require("./lazy-require");
+var providersMod   = require("./flag-providers");
+var contextMod     = require("./flag-evaluation-context");
+var targeting      = require("./flag-targeting");
+var cacheMod       = require("./flag-cache");
+var { defineClass } = require("./framework-error");
+var FlagError = defineClass("FlagError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+function _validateHooks(rawHooks) {
+  var out = { before: [], after: [], error: [], finally: [] };
+  if (rawHooks == null) return out;
+  if (typeof rawHooks !== "object") {
+    throw new FlagError("flag/bad-hooks",
+      "create: hooks must be an object { before, after, error, finally }");
+  }
+  var stages = ["before", "after", "error", "finally"];
+  for (var i = 0; i < stages.length; i += 1) {
+    var stage = stages[i];
+    if (rawHooks[stage] == null) continue;
+    var arr = Array.isArray(rawHooks[stage]) ? rawHooks[stage] : [rawHooks[stage]];
+    for (var j = 0; j < arr.length; j += 1) {
+      if (typeof arr[j] !== "function") {
+        throw new FlagError("flag/bad-hooks",
+          "create: hooks." + stage + "[" + j + "] must be a function");
+      }
+    }
+    out[stage] = arr.slice();
+  }
+  return out;
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "provider", "providers", "defaultEvaluationContext",
+    "audit", "errorHandler", "hooks",
+  ], "flag.create");
+  var providers = [];
+  if (opts.provider) {
+    if (typeof opts.provider.evaluate !== "function") {
+      throw new FlagError("flag/bad-provider",
+        "create: provider must implement .evaluate(flagKey, ctx)");
+    }
+    providers.push(opts.provider);
+  }
+  if (Array.isArray(opts.providers)) {
+    for (var i = 0; i < opts.providers.length; i += 1) {
+      if (typeof opts.providers[i].evaluate !== "function") {
+        throw new FlagError("flag/bad-provider",
+          "create: providers[" + i + "] must implement .evaluate()");
+      }
+      providers.push(opts.providers[i]);
+    }
+  }
+  if (providers.length === 0) {
+    throw new FlagError("flag/no-provider",
+      "create: at least one provider is required - pass `provider` or `providers`");
+  }
+  var defaultCtx = contextMod.create(opts.defaultEvaluationContext || {});
+  var auditOn    = opts.audit !== false;
+  var errorHandler = (typeof opts.errorHandler === "function")
+    ? opts.errorHandler : null;
+  var hooks = _validateHooks(opts.hooks);
+
+  function _emitErrorAudit(flagKey, err, ctx) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "flag.evaluation.error",
+        outcome:  "failure",
+        actor:    { targetingKey: ctx && ctx.targetingKey || null },
+        metadata: {
+          flagKey: flagKey,
+          message: err && err.message || String(err),
+          code:    err && err.code || "flag/unknown",
+        },
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function _runHook(stage, info) {
+    var arr = hooks[stage];
+    if (!arr || arr.length === 0) return;
+    for (var i = 0; i < arr.length; i += 1) {
+      try { arr[i](info); } catch (_e) { /* drop-silent — hooks are observability, not blocking */ }
+    }
+  }
+
+  function _evaluate(flagKey, ctx) {
+    var mergedCtx = contextMod.merge(defaultCtx, ctx || {});
+    var startMs = Date.now();
+    _runHook("before", { flagKey: flagKey, ctx: mergedCtx });
+    for (var i = 0; i < providers.length; i += 1) {
+      try {
+        var result = providers[i].evaluate(flagKey, mergedCtx);
+        if (result && result.reason !== "flag_not_found") {
+          if (auditOn) {
+            try {
+              audit().safeEmit({
+                action:   "flag.evaluated",
+                outcome:  "success",
+                actor:    { targetingKey: mergedCtx.targetingKey || null },
+                metadata: {
+                  flagKey:  flagKey,
+                  variant:  result.variant,
+                  reason:   result.reason,
+                  provider: providers[i].kind || null,
+                },
+              });
+            } catch (_e) { /* drop-silent */ }
+          }
+          _runHook("after", { flagKey: flagKey, ctx: mergedCtx, result: result, elapsedMs: Date.now() - startMs });
+          _runHook("finally", { flagKey: flagKey, ctx: mergedCtx, result: result });
+          return result;
+        }
+      } catch (err) {
+        _emitErrorAudit(flagKey, err, mergedCtx);
+        _runHook("error", { flagKey: flagKey, ctx: mergedCtx, err: err });
+        if (errorHandler) {
+          try { errorHandler({ flagKey: flagKey, err: err, ctx: mergedCtx }); }
+          catch (_e2) { /* drop-silent */ }
+        }
+      }
+    }
+    var notFound = {
+      value:    undefined,
+      variant:  null,
+      reason:   "flag_not_found",
+      metadata: { flagKey: flagKey, providers: providers.map(function (p) { return p.kind; }) },
+    };
+    _runHook("after", { flagKey: flagKey, ctx: mergedCtx, result: notFound, elapsedMs: Date.now() - startMs });
+    _runHook("finally", { flagKey: flagKey, ctx: mergedCtx, result: notFound });
+    return notFound;
+  }
+
+  function _coerceBoolean(v) {
+    if (v === true || v === false) return v;
+    if (v === "true")  return true;
+    if (v === "false") return false;
+    if (v === 1) return true;
+    if (v === 0) return false;
+    return null;
+  }
+
+  return {
+    getValue: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (r.value === undefined) return defaultValue;
+      return r.value;
+    },
+    getDetails: function (flagKey, ctx) {
+      return _evaluate(flagKey, ctx);
+    },
+    getBoolean: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (r.value === undefined) return defaultValue === true;
+      var coerced = _coerceBoolean(r.value);
+      return coerced != null ? coerced : (defaultValue === true);
+    },
+    getString: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (typeof r.value === "string") return r.value;
+      return (typeof defaultValue === "string") ? defaultValue : "";
+    },
+    getNumber: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (typeof r.value === "number" && isFinite(r.value)) return r.value;
+      return (typeof defaultValue === "number") ? defaultValue : 0;
+    },
+    getObject: function (flagKey, ctx, defaultValue) {
+      var r = _evaluate(flagKey, ctx);
+      if (r.value && typeof r.value === "object") return r.value;
+      return defaultValue == null ? {} : defaultValue;
+    },
+    list: function () {
+      var keys = Object.create(null);
+      for (var i = 0; i < providers.length; i += 1) {
+        if (typeof providers[i].list === "function") {
+          var arr = providers[i].list();
+          for (var j = 0; j < arr.length; j += 1) keys[arr[j]] = true;
+        }
+      }
+      return Object.keys(keys);
+    },
+    providers: providers.slice(),
+    defaultEvaluationContext: defaultCtx,
+    getValues: function (flagKeys, ctx) {
+      var out = {};
+      if (!Array.isArray(flagKeys)) return out;
+      for (var i = 0; i < flagKeys.length; i += 1) {
+        var k = flagKeys[i];
+        if (typeof k !== "string") continue;
+        var r = _evaluate(k, ctx);
+        out[k] = r.value;
+      }
+      return out;
+    },
+    getDetailsAll: function (flagKeys, ctx) {
+      var out = {};
+      if (!Array.isArray(flagKeys)) return out;
+      for (var i = 0; i < flagKeys.length; i += 1) {
+        var k = flagKeys[i];
+        if (typeof k !== "string") continue;
+        out[k] = _evaluate(k, ctx);
+      }
+      return out;
+    },
+    addProvider: function (next) {
+      if (!next || typeof next.evaluate !== "function") {
+        throw new FlagError("flag/bad-provider",
+          "addProvider: provider must implement .evaluate()");
+      }
+      providers.push(next);
+      return providers.length;
+    },
+    removeProvider: function (target) {
+      var before = providers.length;
+      for (var i = providers.length - 1; i >= 0; i -= 1) {
+        if (providers[i] === target) providers.splice(i, 1);
+      }
+      return before - providers.length;
+    },
+    middleware: function (mwOpts) {
+      mwOpts = mwOpts || {};
+      validateOpts(mwOpts, ["userKey"], "flag.middleware");
+      var self = this;
+      return function flagMiddleware(req, res, next) {
+        var reqCtx = contextMod.fromRequest(req, {
+          userKey: mwOpts.userKey,
+        });
+        req.flag = {
+          getBoolean: function (k, def)         { return self.getBoolean(k, reqCtx, def); },
+          getString:  function (k, def)         { return self.getString (k, reqCtx, def); },
+          getNumber:  function (k, def)         { return self.getNumber (k, reqCtx, def); },
+          getObject:  function (k, def)         { return self.getObject (k, reqCtx, def); },
+          getValue:   function (k, def)         { return self.getValue  (k, reqCtx, def); },
+          getDetails: function (k)              { return self.getDetails(k, reqCtx); },
+          ctx:        reqCtx,
+        };
+        return next();
+      };
+    },
+  };
+}
+
+module.exports = {
+  create:           create,
+  providers:        providersMod,
+  context:          contextMod,
+  targeting:        targeting,
+  cache:            cacheMod.cache,
+  FlagError:        FlagError,
+};

package/lib/guard-all.js

@@ -116,8 +116,16 @@ var SHARED_POSTURES = Object.freeze(["hipaa", "pci-dss", "gdpr", "soc2"]);
 
 function _verifyParity() {
   var failures = [];
-  for (var i = 0; i < GUARDS.length; i += 1) {
-    var g = GUARDS[i];
+  // Walk both registries — content guards (with MIME_TYPES + EXTENSIONS)
+  // and standalone guards (filename / domain / uuid / cidr / time /
+  // mime / jwt / oauth / graphql / shell / regex / jsonpath / template /
+  // image / pdf / auth). Standalone guards skip the MIME/EXTENSION
+  // checks but every guard MUST declare the shared profile + posture
+  // vocabulary so b.guardAll.allGuards() returns a uniform surface.
+  var allGuards = GUARDS.concat(STANDALONE_GUARDS);
+  for (var i = 0; i < allGuards.length; i += 1) {
+    var g = allGuards[i];
+    var isContent = i < GUARDS.length;
     if (!g || typeof g !== "object") {
       failures.push("guard at index " + i + " is not an exported module object");
       continue;
@@ -126,11 +134,13 @@ function _verifyParity() {
       failures.push("guard at index " + i + ": missing NAME export");
       continue;
     }
-    if (!Array.isArray(g.MIME_TYPES) || g.MIME_TYPES.length === 0) {
-      failures.push(g.NAME + ": missing or empty MIME_TYPES export");
-    }
-    if (!Array.isArray(g.EXTENSIONS) || g.EXTENSIONS.length === 0) {
-      failures.push(g.NAME + ": missing or empty EXTENSIONS export");
+    if (isContent) {
+      if (!Array.isArray(g.MIME_TYPES) || g.MIME_TYPES.length === 0) {
+        failures.push(g.NAME + ": missing or empty MIME_TYPES export");
+      }
+      if (!Array.isArray(g.EXTENSIONS) || g.EXTENSIONS.length === 0) {
+        failures.push(g.NAME + ": missing or empty EXTENSIONS export");
+      }
     }
     if (typeof g.gate !== "function") {
       failures.push(g.NAME + ": missing gate(opts) function");
@@ -146,27 +156,34 @@ function _verifyParity() {
       }
     });
   }
-  // Detect duplicate NAMEs / MIME_TYPES / EXTENSIONS — would cause silent
-  // override in the aggregated gate map; surface at boot instead.
+  // Detect duplicate NAMEs across the full registry (both content +
+  // standalone) so a future guard with a NAME collision surfaces at
+  // boot instead of silently overriding _byName lookups. MIME / EXT
+  // collision detection stays scoped to content guards (standalone
+  // guards have no MIME/EXTENSIONS).
   var nameSeen = Object.create(null);
   var mimeSeen = Object.create(null);
   var extSeen  = Object.create(null);
-  for (var j = 0; j < GUARDS.length; j += 1) {
-    var gg = GUARDS[j];
+  for (var j = 0; j < allGuards.length; j += 1) {
+    var gg = allGuards[j];
     if (gg && gg.NAME) {
-      if (nameSeen[gg.NAME]) failures.push("duplicate NAME " + JSON.stringify(gg.NAME));
+      if (nameSeen[gg.NAME]) failures.push("duplicate NAME " + JSON.stringify(gg.NAME) +
+                                            " across the full guard registry");
       nameSeen[gg.NAME] = true;
     }
-    if (gg && Array.isArray(gg.MIME_TYPES)) {
-      gg.MIME_TYPES.forEach(function (m) {
+  }
+  for (var jc = 0; jc < GUARDS.length; jc += 1) {
+    var ggc = GUARDS[jc];
+    if (ggc && Array.isArray(ggc.MIME_TYPES)) {
+      ggc.MIME_TYPES.forEach(function (m) {
         var k = String(m).toLowerCase();
         if (mimeSeen[k]) failures.push("duplicate MIME_TYPE " + JSON.stringify(k) +
                                        " across multiple guards");
         mimeSeen[k] = true;
       });
     }
-    if (gg && Array.isArray(gg.EXTENSIONS)) {
-      gg.EXTENSIONS.forEach(function (e) {
+    if (ggc && Array.isArray(ggc.EXTENSIONS)) {
+      ggc.EXTENSIONS.forEach(function (e) {
         var k = String(e).toLowerCase();
         if (extSeen[k]) failures.push("duplicate EXTENSION " + JSON.stringify(k) +
                                       " across multiple guards");

package/lib/guard-csv.js

@@ -360,7 +360,20 @@ function _detectIssues(text, opts) {
   }
 
   if (opts.formulaInjectionPolicy !== "audit-only" && opts.formulaInjectionPolicy !== "allow") {
-    var formulaMatch = _firstMatch(text, FORMULA_SCAN_RE);
+    // Strip ZWSP / RTLO / LRM / RLM / BOM at cell-start before the
+    // formula scan. Without this, a cell beginning with U+200B (zero-
+    // width space), U+202E (RTLO), U+200E/F (LTR/RTL marks), or U+FEFF
+    // (BOM) followed by `=` slips past the start-anchor check (the `^`
+    // sits before the codepoint, not after) and the formula reaches
+    // the spreadsheet evaluator. Browsers + Excel + Sheets all strip
+    // these silently — operator users see "=SUM(...)" rendered, the
+    // file shipped a hidden bidi prefix that bypassed the scanner.
+    // U+200B-200F (ZWSP / ZWNJ / ZWJ / LRM / RLM) +
+    // U+202A-202E (LRE / RLE / PDF / LRO / RLO) +
+    // U+2066-2069 (LRI / RLI / FSI / PDI) +
+    // U+FEFF (BOM)                                                     // allow:dynamic-regex — explicit codepoints, no operator input
+    var stripped = text.replace(new RegExp("^[\\u200B-\\u200F\\u202A-\\u202E\\u2066-\\u2069\\uFEFF]+"), "");
+    var formulaMatch = _firstMatch(stripped, FORMULA_SCAN_RE);
     if (formulaMatch) {
       issues.push({
         kind: "formula-prefix-cell", severity: "critical",
@@ -368,7 +381,8 @@ function _detectIssues(text, opts) {
         location: formulaMatch.index,
         snippet: "cell beginning with formula trigger " +
                  JSON.stringify(formulaMatch.char.slice(-1)) +
-                 " at byte " + formulaMatch.index,
+                 " at byte " + formulaMatch.index +
+                 (stripped.length !== text.length ? " (after stripping leading bidi/zero-width prefix)" : ""),
       });
     }
   }

package/lib/guard-html.js

@@ -402,6 +402,30 @@ function escapeAttr(value) {
     .replace(/=/g, "=");
 }
 
+// HTML5 named entities that decode to ASCII codepoints — focused on
+// the entries browsers honor inside URL contexts (whitespace, control
+// chars, scheme-significant punctuation). The full WHATWG named-
+// character-reference table is ~2,231 entries; this is the
+// security-load-bearing subset documented in scheme-bypass writeups
+// (CVE-2026-30838 class). High-codepoint named entities (e.g. mathematical
+// symbols) don't affect URL scheme parsing, so they're omitted.
+var NAMED_ENTITY_ASCII = {
+  // Whitespace + control chars browsers strip inside URL schemes
+  Tab: "\t", NewLine: "\n",
+  // Scheme-significant punctuation
+  colon: ":", semi: ";", period: ".", sol: "/", bsol: "\\",
+  num: "#", excl: "!", quest: "?", lpar: "(", rpar: ")",
+  lsqb: "[", rsqb: "]", lcub: "{", rcub: "}",
+  // Quotes / brackets
+  quot: "\"", apos: "'", lt: "<", gt: ">",
+  // Misc ASCII
+  amp: "&", commat: "@", dollar: "$", percnt: "%",
+  ast: "*", plus: "+", lowbar: "_", hyphen: "-",
+  // Whitespace markers (codepoints in the ASCII / Latin-1 range that
+  // browsers treat as URL-strippable)
+  nbsp: " ",
+};
+
 // _normalizeUrl — peel off entity-encoded leading whitespace and
 // HTML/URL-encoded scheme prefix tricks, then return the lowercased
 // scheme. Returns "" if no scheme.
@@ -415,6 +439,17 @@ function _extractScheme(rawUrl) {
   s = s.replace(/&#(\d+);/g, function (_m, d) {
     return String.fromCharCode(parseInt(d, 10));
   });
+  // Decode HTML5 named entities that browsers honor inside URL
+  // contexts. Without this, payloads like `java&Tab;script:alert(1)`
+  // bypass the scheme allowlist (the literal `&Tab;` between `java`
+  // and `script:` doesn't match any denied scheme; the browser then
+  // decodes the entity, strips the tab, and executes javascript:).
+  s = s.replace(/&([A-Za-z][A-Za-z0-9]+);/g, function (m, name) {
+    if (Object.prototype.hasOwnProperty.call(NAMED_ENTITY_ASCII, name)) {
+      return NAMED_ENTITY_ASCII[name];
+    }
+    return m;
+  });
   // Strip embedded whitespace + control chars + zero-widths the
   // URL parser would tolerate.
   s = s.replace(C0_CTRL_RE_G, "").replace(ZW_RE_G, "");

package/lib/guard-svg.js

@@ -352,6 +352,20 @@ function _resolveOpts(opts) {
   });
 }
 
+// HTML5 named-entity ASCII subset — same shape as guard-html.
+// Browsers honor these inside URL contexts; without decoding them,
+// `java	script:` and friends bypass the scheme allowlist.
+var SVG_NAMED_ENTITY_ASCII = {
+  Tab: "\t", NewLine: "\n",
+  colon: ":", semi: ";", period: ".", sol: "/", bsol: "\\",
+  num: "#", excl: "!", quest: "?", lpar: "(", rpar: ")",
+  lsqb: "[", rsqb: "]", lcub: "{", rcub: "}",
+  quot: "\"", apos: "'", lt: "<", gt: ">",
+  amp: "&", commat: "@", dollar: "$", percnt: "%",
+  ast: "*", plus: "+", lowbar: "_", hyphen: "-",
+  nbsp: " ",
+};
+
 function _extractScheme(rawUrl) {
   var s = String(rawUrl || "").trim();
   s = s.replace(/&#x([0-9a-f]+);/gi, function (_m, h) {
@@ -360,6 +374,12 @@ function _extractScheme(rawUrl) {
   s = s.replace(/&#(\d+);/g, function (_m, d) {
     return String.fromCharCode(parseInt(d, 10));
   });
+  s = s.replace(/&([A-Za-z][A-Za-z0-9]+);/g, function (m, name) {
+    if (Object.prototype.hasOwnProperty.call(SVG_NAMED_ENTITY_ASCII, name)) {
+      return SVG_NAMED_ENTITY_ASCII[name];
+    }
+    return m;
+  });
   s = s.replace(C0_CTRL_RE_G, "").replace(ZW_RE_G, "");
   var m = s.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
   return m ? m[1].toLowerCase() : "";

package/lib/http-client.js

@@ -16,7 +16,7 @@
  *     body,               // Buffer | string | Readable | undefined
  *     timeoutMs,          // wall-clock cap (caller-chosen, no default)
  *     idleTimeoutMs,      // zero-progress idle cap (default 30s)
- *     responseMode,       // "buffer" (default) | "stream"
+ *     responseMode,       // "buffer" (default) | "stream" | "always-resolve"
  *     maxResponseBytes,   // for buffer mode (default 16 MiB control,
  *                         //   1 GiB GET — operators with > 1 GiB
  *                         //   stored objects must use stream mode)
@@ -618,6 +618,11 @@ function _requestWithRedirects(opts, hopsLeft) {
     var u0 = safeUrl.parse(opts.url, { allowedProtocols: safeUrl.ALLOW_HTTP_ALL });
     originalOrigin = u0.protocol + "//" + u0.host;
   } catch (_e) { /* request() will reject on next hop's parse */ }
+  // onRedirect: function ({ from, to, hop, headersStripped, statusCode }) — called
+  // BEFORE each follow. Operator can mutate the next-hop URL or abort
+  // the redirect by throwing. Async hooks are awaited.
+  var onRedirect = typeof opts.onRedirect === "function" ? opts.onRedirect : null;
+  var hopCount = 0;
 
   var current = Object.assign({}, opts, { _resolveOnRedirect: true });
   function _follow() {
@@ -628,6 +633,7 @@ function _requestWithRedirects(opts, hopsLeft) {
       var loc = res.headers && (res.headers.location || res.headers.Location);
       if (!loc) return { finalOpts: current, res: res };  // 3xx with no Location — operator handles
       hopsLeft -= 1;
+      hopCount += 1;
 
       // Resolve relative Location against the just-fetched URL (the URL
       // of the request that produced the redirect, which may itself be a
@@ -651,8 +657,10 @@ function _requestWithRedirects(opts, hopsLeft) {
         var nu = safeUrl.parse(nextUrl, { allowedProtocols: safeUrl.ALLOW_HTTP_ALL });
         nextOrigin = nu.protocol + "//" + nu.host;
       } catch (_e) { /* request() will reject when it tries to parse */ }
+      var headersStripped = false;
       if (originalOrigin && nextOrigin && nextOrigin !== originalOrigin) {
         nextHeaders = _stripCrossOriginAuth(nextHeaders);
+        headersStripped = true;
       }
 
       // 303 → always GET; body dropped. 301/302 → historical clients
@@ -667,14 +675,42 @@ function _requestWithRedirects(opts, hopsLeft) {
         nextBody = undefined;
       }
 
-      current = Object.assign({}, current, {
-        url:                 nextUrl,
-        method:              nextMethod,
-        body:                nextBody,
-        headers:             nextHeaders,
-        _resolveOnRedirect:  true,
-      });
-      return _follow();
+      function _continueFollow() {
+        current = Object.assign({}, current, {
+          url:                 nextUrl,
+          method:              nextMethod,
+          body:                nextBody,
+          headers:             nextHeaders,
+          _resolveOnRedirect:  true,
+        });
+        return _follow();
+      }
+
+      // Caller-supplied redirect hook fires here. The hook can throw
+      // (sync) or reject (async) to abort the follow with a custom
+      // error; otherwise we proceed to the next hop. We pre-bind the
+      // values the hook gets and pass them in a frozen object so a
+      // caller can't mutate the in-flight pipeline by side-effect.
+      if (onRedirect) {
+        var hookEvent = Object.freeze({
+          from:            current.url,
+          to:              nextUrl,
+          hop:             hopCount,
+          statusCode:      res.statusCode,
+          headersStripped: headersStripped,
+          method:          nextMethod,
+        });
+        try {
+          var hookResult = onRedirect(hookEvent);
+          if (hookResult && typeof hookResult.then === "function") {
+            return hookResult.then(function () { return _continueFollow(); });
+          }
+        } catch (e) {
+          return Promise.reject(_makeError(opts.errorClass, "REDIRECT_ABORTED",
+            "onRedirect hook refused redirect: " + ((e && e.message) || String(e)), true));
+        }
+      }
+      return _continueFollow();
     });
   }
   void originalUrl;
@@ -885,7 +921,7 @@ function _requestH1(transport, u, opts) {
       }
 
       if (responseMode === "stream") {
-        if (res.statusCode >= 400) {
+        if (res.statusCode >= 400 && responseMode !== "always-resolve") {
           res.resume();
           return _reject(_makeError(opts.errorClass, "HTTP_ERROR",
             "HTTP " + res.statusCode + " " + (res.statusMessage || ""),
@@ -936,6 +972,14 @@ function _requestH1(transport, u, opts) {
           // request() never sets _resolveOnRedirect — operator code that
           // didn't ask for redirect-following keeps seeing 3xx as errors.
           _resolve({ statusCode: res.statusCode, headers: res.headers, body: buf });
+        } else if (responseMode === "always-resolve") {
+          // Operator opted in to "give me the full response object
+          // regardless of status." Caller branches on statusCode in
+          // their own code path — useful for proxies / forwarders /
+          // health-checkers / probe libraries that want to surface
+          // the upstream response structurally instead of via an
+          // error message string.
+          _resolve({ statusCode: res.statusCode, headers: res.headers, body: buf });
         } else {
           var msg = "HTTP " + res.statusCode + ": " + buf.toString("utf8").slice(0, 500);
           _reject(_makeError(opts.errorClass, "HTTP_ERROR", msg,
@@ -1079,7 +1123,7 @@ function _requestH2(transport, u, opts) {
       }
 
       if (responseMode === "stream") {
-        if (statusCode >= 400) {
+        if (statusCode >= 400 && responseMode !== "always-resolve") {
           stream.resume();
           return _reject(_makeError(opts.errorClass, "HTTP_ERROR",
             "HTTP " + statusCode, _isPermanentStatus(statusCode), statusCode));
@@ -1110,6 +1154,8 @@ function _requestH2(transport, u, opts) {
         });
         if (statusCode >= 200 && statusCode < 300) {
           _resolve({ statusCode: statusCode, headers: responseHeaders, body: buf });
+        } else if (responseMode === "always-resolve") {
+          _resolve({ statusCode: statusCode, headers: responseHeaders, body: buf });
         } else {
           var msg = "HTTP " + statusCode + ": " + buf.toString("utf8").slice(0, 500);
           _reject(_makeError(opts.errorClass, "HTTP_ERROR", msg,