@blamejs/core 0.18.43 → 0.18.44

package/lib/gate-contract.js

@@ -2528,7 +2528,197 @@ function resolveProfileAndPosture(opts, cfg) {
     }
     overlay = Object.assign({}, overlay, cfg.compliancePostures[posture]);
   }
-  return Object.assign({}, cfg.defaults || {}, overlay, opts);
+  // An explicitly-undefined property means the caller did not set it, not that
+  // the default should be removed. `{ maxBytes: parsedEnvValue }` with the
+  // variable unset is the ordinary way to write it, and a plain Object.assign
+  // copies that undefined straight over the profile's value - after which the
+  // cap is gone and every `measured > undefined` comparison is false. Dropping
+  // undefined here restores the merge everyone already assumes: last one to
+  // actually SET a key wins.
+  var resolved = Object.assign({}, cfg.defaults || {}, overlay, _defined(opts));
+  // The numeric caps are checked HERE, at the one point every entry point
+  // passes through, rather than in the generated validate() alone. A guard's
+  // hand-written entry points - guardMarkdown.render, guardEmail.sanitize,
+  // guardHtml's three - resolve their own opts and then read maxBytes/maxLines
+  // straight out of the result. When the check lived only in validate(), those
+  // paths took `{ maxBytes: "8mb" }` at face value: every `bytes > maxBytes`
+  // comparison against a string is false, so the malformed value did not fall
+  // back to the default, it DISABLED the cap on untrusted input. Checking at
+  // the resolver makes the bypass unreachable by construction, so a guard
+  // cannot grow a new entry point that silently opts out of its own limits.
+  //
+  // Two lists, because they answer two different questions.
+  //
+  // `intOpts` is what the guard AUTHOR declared to be a cap. Zero is not a
+  // setting there — `maxBytes: 0` would refuse every input — so those stay
+  // strictly positive, and the guards that already refuse it keep doing so.
+  //
+  // `nonNegativeOpts` is DERIVED from the defaults, and derivation cannot tell
+  // a cap from a tolerance. `maxRuntimeMs: 0` means "no runtime budget" and
+  // `nbfFutureSlackMs: 0` means "allow no clock slack": ordinary settings that
+  // requiring a positive integer took away. What derivation CAN say is that
+  // the value must still be a non-negative integer, and that is the whole
+  // fail-open class — a string, an Infinity, a NaN, a fraction or a negative
+  // makes every `measured > cap` comparison false and removes the bound.
+  //
+  // An earlier version kept a hand-written list of the options where zero is a
+  // value. That list was the same kind of thing that drifted in the first
+  // place, and it had already missed two.
+  //
+  // This is also why the general resolver must not infer on its own: a consumer
+  // whose defaults hold `{ retries: 3 }` is entitled to `retries: 0`, and only
+  // the caller knows which of its options are limits.
+  if (Array.isArray(cfg.intOpts) && cfg.intOpts.length > 0) {
+    numericBounds.requireAllPositiveFiniteIntIfPresent(resolved, cfg.intOpts,
+      prefix + ".resolveOpts", ErrorClass, prefix + ".bad-opt");
+  }
+  if (Array.isArray(cfg.nonNegativeOpts)) {
+    cfg.nonNegativeOpts.forEach(function (k) {
+      if (resolved[k] === undefined) return;
+      if (Array.isArray(cfg.intOpts) && cfg.intOpts.indexOf(k) !== -1) return;
+      numericBounds.requireNonNegativeFiniteIntIfPresent(resolved[k],
+        prefix + ".resolveOpts " + k, ErrorClass, prefix + ".bad-opt");
+    });
+  }
+  // Options whose value must come from a fixed vocabulary. Checked here, with
+  // the caps, because this is the one point every entry point passes through -
+  // a check on the request path would let a typo through gate construction and
+  // surface it as failing requests instead of a boot error. Read leniently, a
+  // misspelled policy takes whichever branch is not the strict one, so this
+  // fails closed by refusing the value rather than guessing at it.
+  if (cfg.enumOpts && typeof cfg.enumOpts === "object") {
+    Object.keys(cfg.enumOpts).forEach(function (k) {
+      var allowed = cfg.enumOpts[k];
+      var v = resolved[k];
+      if (v === undefined || !Array.isArray(allowed)) return;
+      if (typeof v !== "string" || allowed.indexOf(v) === -1) {
+        throw ErrorClass.factory(prefix + ".bad-opt",
+          prefix + ": " + k + " must be one of " + allowed.join(", ") +
+          "; got " + JSON.stringify(v));
+      }
+    });
+  }
+  return resolved;
+}
+
+
+// The own enumerable properties of `o` that were actually given a value. A key
+// present with the value `undefined` is treated as absent, so it cannot erase
+// a default it was never meant to touch.
+function _defined(o) {
+  if (!o || typeof o !== "object") return o;
+  var out = {};
+  Object.keys(o).forEach(function (k) {
+    if (o[k] !== undefined) out[k] = o[k];
+  });
+  return out;
+}
+
+/**
+ * @primitive  b.gateContract.capKeysOf
+ * @signature  b.gateContract.capKeysOf(defaults, declared?)
+ * @since      0.18.44
+ * @status     stable
+ * @related    b.gateContract.resolveProfileAndPosture, b.gateContract.defineGuard
+ *
+ * The guard option names that must stay non-negative integers: every default
+ * whose value is a positive finite integer, plus any name passed in `declared`.
+ *
+ * Pass the result as `nonNegativeOpts` when binding `resolveProfileAndPosture`
+ * by hand, so the resolver refuses a value given as a string, `Infinity`, a
+ * `NaN`, a fraction or a negative number. Those do not fall back to the
+ * default — every `measured > cap` comparison against them is false, which
+ * removes the limit on untrusted input. A guard built by `defineGuard` gets
+ * this applied for it.
+ *
+ * NON-NEGATIVE rather than positive, because derivation cannot tell a cap from
+ * a tolerance: `maxRuntimeMs: 0` means "no runtime budget" and
+ * `nbfFutureSlackMs: 0` means "allow no clock slack". Declare the options that
+ * are genuinely caps as `intOpts` instead, where zero is refused.
+ *
+ * Derived rather than hand-listed on purpose: a written-out list drifts from
+ * the defaults it mirrors, which is how `maxRuntimeMs` came to be unchecked
+ * across the whole guard family.
+ *
+ * @example
+ *   var DEFAULTS = { maxBytes: 1024, mode: "enforce", ratio: 0.5 };
+ *   b.gateContract.capKeysOf(DEFAULTS);
+ *   // -> ["maxBytes"]
+ */
+function capKeysOf(defaults, declared) {
+  return _capKeys(defaults, declared);
+}
+
+/**
+ * @primitive  b.gateContract.identitySanitize
+ * @signature  b.gateContract.identitySanitize(input)
+ * @since      0.18.44
+ * @status     stable
+ * @related    b.gateContract.defineGuard, b.gateContract.severityDisposition
+ *
+ * The sanitize transform for a guard that refuses rather than repairs.
+ *
+ * Some inputs cannot be safely rewritten: forging a JWT `alg`, editing an OAuth
+ * `state`, rewriting a caller's regular expression or dropping cookies would
+ * disarm the very evidence the guard is inspecting. A guard like that has no
+ * repair to perform, so its transform returns the value unchanged — reached
+ * only when nothing high or critical refused it upstream.
+ *
+ * @example
+ *   module.exports = b.gateContract.defineGuard({
+ *     name: "auth",
+ *     sanitizeTransform: b.gateContract.identitySanitize,
+ *   });
+ */
+function identitySanitize(input) {
+  return input;
+}
+
+/**
+ * @primitive  b.gateContract.ctxValueFrom
+ * @signature  b.gateContract.ctxValueFrom(ctx, fields)
+ * @since      0.18.44
+ * @status     stable
+ * @related    b.gateContract.defineGuard, b.gateContract.buildGuardGate
+ *
+ * Read a gate context the way a generated gate does: the first field carrying
+ * a value, or `undefined` when the context carries none of them.
+ *
+ * The distinction is the point. A field that is ABSENT means there is nothing
+ * for this guard to look at; a field PRESENT as an empty string is a value, and
+ * one most validators refuse. An `ctx.a || ctx.b || ""` chain collapses both
+ * into `""`, so a gate written that way serves an empty identifier its own
+ * `validate` rejects. Use this in a hand-written gate and short-circuit only on
+ * `undefined`.
+ *
+ * @example
+ *   var name = b.gateContract.ctxValueFrom(ctx, ["filename", "name"]);
+ *   if (name === undefined) return { ok: true, action: "serve" };
+ */
+function ctxValueFrom(ctx, fields) {
+  return _ctxValueForKind(null, ctx, fields);
+}
+
+// The cap keys of a GUARD: every default that is a positive finite integer,
+// plus anything the spec names outright. These are the caps, budgets and depth
+// bounds an operator may raise or lower but must not replace with a shape that
+// silently compares false against everything. Only defineGuard calls this -
+// the general resolver must not infer the same thing about an arbitrary
+// consumer's options.
+function _capKeys(defaults, declared) {
+  var out = [];
+  if (defaults && typeof defaults === "object") {
+    Object.keys(defaults).forEach(function (k) {
+      var v = defaults[k];
+      if (typeof v === "number" && Number.isInteger(v) && v > 0 && Number.isFinite(v)) {
+        out.push(k);
+      }
+    });
+  }
+  if (Array.isArray(declared)) {
+    declared.forEach(function (k) { if (out.indexOf(k) === -1) out.push(k); });
+  }
+  return out;
 }
 
 // _warnUnmappedPosture — emit a one-time, grep-able audit warning that a
@@ -2810,14 +3000,34 @@ var _KIND_CTX_FIELDS = Object.freeze({
 
 // override (when given) replaces the per-KIND field table — lets a guard whose
 // gate is the standard chain but reads a custom ctx field take the default gate.
+// Returns the ctx value for this guard's kind, or `undefined` when the ctx
+// carries none of its fields at all.
+//
+// The distinction matters: an ABSENT field means there is nothing for this
+// guard to look at, while a field PRESENT as an empty string is a value, and
+// one most guards' validators refuse. Collapsing both to "" made the gate serve
+// `{ country: "" }` while validate("") reported it - the gate disagreeing with
+// the validator it is meant to enforce, across seventeen guards.
+//
+// A truthy field still wins, and still in declaration order, so a ctx carrying
+// a real value anywhere resolves exactly as before; the empty case only decides
+// between "" and undefined.
 function _ctxValueForKind(kind, ctx, override) {
   ctx = ctx || {};
   var fields = override || _KIND_CTX_FIELDS[kind];
   if (!fields) return extractBytesAsText(ctx);   // content (default)
+  var emptyPresent;
+  var sawEmpty = false;
   for (var i = 0; i < fields.length; i += 1) {
-    if (ctx[fields[i]]) return ctx[fields[i]];
+    var v = ctx[fields[i]];
+    if (v) return v;
+    if (!sawEmpty && v !== undefined && v !== null &&
+        Object.prototype.hasOwnProperty.call(ctx, fields[i])) {
+      emptyPresent = v;
+      sawEmpty = true;
+    }
   }
-  return "";
+  return sawEmpty ? emptyPresent : undefined;
 }
 
 /**
@@ -2946,6 +3156,19 @@ function defineGuard(spec) {
       defaults:           defaults,
       errorClass:         ErrorClass,
       errCodePrefix:      prefix,
+      // What the author declared IS a cap, so zero is refused there.
+      intOpts:            Array.isArray(spec.intOpts) ? spec.intOpts : null,
+      // Everything else derived from this guard's own defaults, held only to
+      // "still a non-negative integer". Deriving rather than hand-listing is
+      // what stops the drift that left maxRuntimeMs unchecked in all 27
+      // guards, guard-csv with no list at all, and guard-sql's and guard-svg's
+      // caps unnamed — while leaving `maxRuntimeMs: 0` and the clock-slack
+      // options the settings they have always been. Declared here so both
+      // bind on EVERY path that resolves opts, not just the generated
+      // validate() below.
+      nonNegativeOpts:    _capKeys(defaults, spec.intOpts),
+      // Options restricted to a fixed vocabulary, checked at the same funnel.
+      enumOpts:           spec.enumOpts || null,
     });
   };
   if (typeof spec.detect === "function") {
@@ -3104,17 +3327,26 @@ function defineGuard(spec) {
   // is idempotent over an already-resolved opts, so spec.validate's internal
   // resolution stays correct.
   function defaultGate(rawOpts) {
-    var opts = resolveProfileAndPosture(rawOpts || {}, {
-      profiles:           profiles,
-      compliancePostures: postures,
-      defaults:           defaults,
-      errorClass:         ErrorClass,
-      errCodePrefix:      prefix,
-    });
+    // Through the guard's own resolver, not a second copy of its binding. The
+    // copy that used to be here carried no cap or vocabulary list, so building
+    // a gate accepted a malformed limit or a misspelled policy that validate()
+    // would have refused - a misconfiguration surviving boot to fail later on
+    // requests, which is the opposite of what a config-time check is for.
+    var opts = _resolveGuardOpts(rawOpts || {});
     var perCtx = spec.defaultGateCheck || function (ctx) {
       var value = _ctxValueForKind(spec.kind, ctx, ctxFields);
-      if (!value) return { ok: true, action: "serve" };
-      var rv = spec.validate(value, opts);
+      // Only an ABSENT field short-circuits. A field present as an empty string
+      // is a value, and the validator decides what it is worth - which keeps the
+      // gate's verdict and validate()'s verdict the same answer.
+      if (value === undefined || value === null) return { ok: true, action: "serve" };
+      var rv;
+      try { rv = spec.validate(value, opts); }
+      catch (_e) {
+        // A validator that cannot even parse the value has not approved it.
+        // Letting the throw escape would crash the request this gate exists to
+        // decide, so it becomes the refusal it already means.
+        return { ok: false, action: "refuse" };
+      }
       return severityDisposition(rv.issues || []);
     };
     return buildGuardGate(
@@ -3128,6 +3360,11 @@ function defineGuard(spec) {
   var out = {
     NAME:                spec.name,
     KIND:                spec.kind,
+    // The options this guard DECLARES to be caps, where zero is refused. Every
+    // other numeric option is derived from the defaults and held only to
+    // "non-negative integer", because derivation cannot tell a cap from a
+    // tolerance. Exposed so the family tests can tell the two apart.
+    INT_OPTS:            Object.freeze(Array.isArray(spec.intOpts) ? spec.intOpts.slice() : []),
     validate:            spec.validate,
     resolveOpts:         _resolveGuardOpts,
     buildProfile:        buildProfileFn,
@@ -3472,6 +3709,12 @@ module.exports = {
   workerThreadGate:   workerThreadGate,
   buildProfile:       buildProfile,
   resolveProfileAndPosture: resolveProfileAndPosture,
+  // For a guard that binds its own resolver instead of going through
+  // defineGuard: the cap keys to declare, derived from its defaults so the
+  // list cannot drift away from them.
+  capKeysOf:                capKeysOf,
+  identitySanitize:         identitySanitize,
+  ctxValueFrom:             ctxValueFrom,
   runIssueValidator:  runIssueValidator,
   buildGuardGate:     buildGuardGate,
   severityDisposition: severityDisposition,

package/lib/guard-all.js

@@ -74,6 +74,7 @@ var STANDALONE_GUARDS = [
   require("./guard-domain"),
   require("./guard-uuid"),
   require("./guard-cidr"),
+  require("./guard-country"),
   require("./guard-time"),
   require("./guard-mime"),
   require("./guard-jwt"),

package/lib/guard-archive.js

@@ -183,8 +183,20 @@ 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. This guard
+// builds its own exports rather than going through defineGuard, so it names
+// them here. maxRuntimeMs is deliberately absent: zero there means no runtime
+// budget. See guard-image for the full reasoning.
+var INT_OPTS = ["maxEntries", "maxTotalBytes", "maxEntryBytes",
+                "maxCompressionRatio", "maxAggregateRatio"];
+
 // ---- Helpers ----
 
+// This guard builds its own exports rather than going through defineGuard, so
+// it binds its resolver here and declares its caps here too. The list is
+// DERIVED from DEFAULTS rather than written out, because a hand-kept list is
+// what drifted away from the defaults it was meant to mirror and left limits
+// unchecked across the family.
 function _resolveOpts(opts) {
   return gateContract.resolveProfileAndPosture(opts, {
     profiles:           PROFILES,
@@ -192,6 +204,8 @@ function _resolveOpts(opts) {
     defaults:           DEFAULTS,
     errorClass:         GuardArchiveError,
     errCodePrefix:      "archive",
+    intOpts:            INT_OPTS,
+    nonNegativeOpts:    gateContract.capKeysOf(DEFAULTS),
   });
 }
 

package/lib/guard-auth.js

@@ -316,9 +316,7 @@ function _detectIssues(bundle, opts) {
 // transform is identity — the bundle is returned unchanged when no high/critical
 // issue refused upstream. A non-object input refuses upstream via the high-
 // severity auth.bad-input issue _detectIssues raises.
-function _sanitizeTransform(input) {
-  return input;
-}
+var _sanitizeTransform = gateContract.identitySanitize;
 
 /**
  * @primitive  b.guardAuth.gate