@blamejs/core 0.7.107 → 0.8.4

package/lib/auth/step-up.js

@@ -0,0 +1,445 @@
+"use strict";
+/**
+ * RFC 9470 — OAuth 2.0 Step-Up Authentication Challenge.
+ *
+ * Step-up flows let a resource server demand a stronger or fresher
+ * authentication ceremony before serving a particular request. The
+ * challenge shape is fixed by RFC 9470:
+ *
+ *   HTTP/1.1 401 Unauthorized
+ *   WWW-Authenticate: Bearer error="insufficient_user_authentication",
+ *     error_description="A higher level of authentication is required",
+ *     acr_values="urn:mace:incommon:iap:silver",
+ *     max_age="300"
+ *
+ * The corresponding error code, `insufficient_user_authentication`, is
+ * registered in the OAuth Extensions Error Registry; clients MUST
+ * recognise it and re-trigger the auth-flow with `acr_values` and/or
+ * `max_age` propagated to the IdP.
+ *
+ * Public surface (b.auth.stepUp.*):
+ *
+ *   .evaluate({ claims, requirement, now? })
+ *     → { ok: true } | { ok: false, error, requirement }
+ *
+ *   .buildChallenge({ requirement, realm?, error?, errorDescription? })
+ *     → "Bearer error=\"insufficient_user_authentication\", ..."
+ *
+ *   .acr.register({ value, rank })          (delegates to acr-vocabulary)
+ *   .acr.meets(presented, required)
+ *
+ *   .grant.create({ subject, scope, acr, amr, evidence?, ttlSec? })
+ *     → { token, expiresAt, jti }
+ *   .grant.verify(token, { audience?, scope? })
+ *     → claims object
+ *
+ *   .parseAuthorizationDetails(value)        (RFC 9396 helper)
+ *
+ * Requirement object shape:
+ *   {
+ *     acr:           "urn:..."           (optional; one acr to require)
+ *     acrValues:     [ "...", "..." ]    (optional; ANY satisfies)
+ *     maxAge:        300                 (optional, seconds — RFC 9470)
+ *     requiredAmr:   [ "hwk", "pop" ]    (optional; AMR must include all)
+ *     phishingResistant: true            (optional; AMR must include any
+ *                                         phishing-resistant method)
+ *     authorizationDetails: [ {...} ]    (optional; RFC 9396 fine-grained)
+ *   }
+ *
+ * Per the validation-tier policy: configuration entry-points (.buildChallenge,
+ * .grant.create, .acr.register) THROW on bad input — operator catches the
+ * typo at boot. The hot-path (.evaluate) never throws — it returns the
+ * structured failure so the middleware can emit a 401.
+ *
+ * Audit emissions on every state transition:
+ *   - auth.stepUp.required        (challenge emitted)
+ *   - auth.stepUp.satisfied       (request passed evaluation)
+ *   - auth.stepUp.denied          (request failed)
+ *   - auth.stepUp.grant.issued    (elevation grant minted)
+ *   - auth.stepUp.grant.consumed  (elevation grant used)
+ *   - auth.stepUp.grant.revoked   (elevation grant revoked)
+ */
+
+var lazyRequire    = require("../lazy-require");
+var validateOpts   = require("../validate-opts");
+var safeJson       = require("../safe-json");
+var C              = require("../constants");
+var { AuthError }  = require("../framework-error");
+
+var acr            = require("./acr-vocabulary");
+var authTime       = require("./auth-time-tracker");
+var elevation      = lazyRequire(function () { return require("./elevation-grant"); });
+var audit          = lazyRequire(function () { return require("../audit"); });
+
+var INSUFFICIENT_USER_AUTHENTICATION = "insufficient_user_authentication";
+var DEFAULT_REALM                    = "api";
+
+function _readPresentedClaims(claims) {
+  return authTime.readClaims(claims);
+}
+
+// Quote a value for inclusion in a WWW-Authenticate parameter per RFC
+// 7235 §2.2 and RFC 9470 §3 (uses `quoted-string` for all values).
+function _quote(value) {
+  if (typeof value !== "string") value = String(value);
+  // Reject CTLs and quote-injecting characters.
+  for (var i = 0; i < value.length; i += 1) {
+    var code = value.charCodeAt(i);
+    if (code < 32 || code === 127) {                                    // allow:raw-byte-literal — ASCII control codepoints
+      throw new AuthError("auth-stepUp/bad-challenge",
+        "challenge value contains control character at index " + i);
+    }
+    if (value.charAt(i) === '"' || value.charAt(i) === "\\") {
+      throw new AuthError("auth-stepUp/bad-challenge",
+        "challenge value contains illegal character " +
+        JSON.stringify(value.charAt(i)) + " at index " + i);
+    }
+  }
+  return '"' + value + '"';
+}
+
+function _validateRequirement(requirement, label) {
+  if (!requirement || typeof requirement !== "object") {
+    throw new AuthError("auth-stepUp/bad-requirement",
+      label + ": requirement must be an object — got " +
+      JSON.stringify(requirement));
+  }
+  validateOpts(requirement, [
+    "acr", "acrValues", "maxAge", "requiredAmr", "phishingResistant",
+    "authorizationDetails",
+  ], label);
+  if (requirement.acr != null) {
+    validateOpts.requireNonEmptyString(requirement.acr,
+      label + ": acr", AuthError, "auth-stepUp/bad-acr");
+  }
+  if (requirement.acrValues != null) {
+    if (!Array.isArray(requirement.acrValues) || requirement.acrValues.length === 0) {
+      throw new AuthError("auth-stepUp/bad-acr",
+        label + ": acrValues must be a non-empty string array");
+    }
+    for (var i = 0; i < requirement.acrValues.length; i += 1) {
+      validateOpts.requireNonEmptyString(requirement.acrValues[i],
+        label + ": acrValues[" + i + "]", AuthError, "auth-stepUp/bad-acr");
+    }
+  }
+  if (requirement.maxAge != null) {
+    if (typeof requirement.maxAge !== "number" || !isFinite(requirement.maxAge) ||
+        requirement.maxAge < 0) {
+      throw new AuthError("auth-stepUp/bad-max-age",
+        label + ": maxAge must be a finite number >= 0 — got " +
+        JSON.stringify(requirement.maxAge));
+    }
+  }
+  if (requirement.requiredAmr != null) {
+    if (!Array.isArray(requirement.requiredAmr)) {
+      throw new AuthError("auth-stepUp/bad-amr",
+        label + ": requiredAmr must be a string array");
+    }
+    for (var j = 0; j < requirement.requiredAmr.length; j += 1) {
+      validateOpts.requireNonEmptyString(requirement.requiredAmr[j],
+        label + ": requiredAmr[" + j + "]", AuthError, "auth-stepUp/bad-amr");
+    }
+  }
+  if (requirement.phishingResistant != null &&
+      typeof requirement.phishingResistant !== "boolean") {
+    throw new AuthError("auth-stepUp/bad-requirement",
+      label + ": phishingResistant must be boolean — got " +
+      JSON.stringify(requirement.phishingResistant));
+  }
+}
+
+function evaluate(opts) {
+  opts = opts || {};
+  var claims      = opts.claims;
+  var requirement = opts.requirement;
+  if (!requirement || typeof requirement !== "object") {
+    return { ok: false, error: "no_requirement", reason: "evaluate: requirement object missing" };
+  }
+  // Hot-path drop-silent: do not throw on typo — return structured
+  // failure. But surface unregistered-acr because that's an operator-
+  // side typo that should bubble up.
+  try { _validateRequirement(requirement, "auth.stepUp.evaluate"); }
+  catch (err) { return { ok: false, error: "bad_requirement", reason: err.message }; }
+
+  var presented = _readPresentedClaims(claims);
+  var now       = (typeof opts.now === "number") ? opts.now : Math.floor(Date.now() / C.TIME.seconds(1));
+
+  // 1. ACR check (single)
+  if (typeof requirement.acr === "string") {
+    if (!acr.isRegistered(requirement.acr)) {
+      return {
+        ok: false, error: "unknown_acr",
+        reason: "evaluate: required acr is not registered: " + requirement.acr,
+        requirement: requirement,
+      };
+    }
+    if (!acr.meets(presented.acr, requirement.acr)) {
+      return {
+        ok: false, error: INSUFFICIENT_USER_AUTHENTICATION,
+        reason:  "presented acr " + JSON.stringify(presented.acr) +
+                 " does not meet required " + JSON.stringify(requirement.acr),
+        requirement: requirement, presented: presented,
+      };
+    }
+  }
+  // 2. ACR-values list (any one suffices)
+  if (Array.isArray(requirement.acrValues) && requirement.acrValues.length > 0) {
+    if (!acr.meetsAny(presented.acr, requirement.acrValues)) {
+      return {
+        ok: false, error: INSUFFICIENT_USER_AUTHENTICATION,
+        reason: "presented acr " + JSON.stringify(presented.acr) +
+                " does not meet any of " + JSON.stringify(requirement.acrValues),
+        requirement: requirement, presented: presented,
+      };
+    }
+  }
+  // 3. max_age freshness
+  if (typeof requirement.maxAge === "number") {
+    if (!authTime.freshEnough(claims, requirement.maxAge, now)) {
+      return {
+        ok: false, error: INSUFFICIENT_USER_AUTHENTICATION,
+        reason: "auth_time stale or missing — required max_age=" +
+                requirement.maxAge + "s, age=" + authTime.ageSec(claims, now),
+        requirement: requirement, presented: presented,
+      };
+    }
+  }
+  // 4. AMR — required methods
+  if (Array.isArray(requirement.requiredAmr) && requirement.requiredAmr.length > 0) {
+    if (!acr.amrSatisfiesRequiredList(presented.amr, requirement.requiredAmr)) {
+      return {
+        ok: false, error: INSUFFICIENT_USER_AUTHENTICATION,
+        reason: "presented amr " + JSON.stringify(presented.amr) +
+                " does not include all required " + JSON.stringify(requirement.requiredAmr),
+        requirement: requirement, presented: presented,
+      };
+    }
+  }
+  // 5. AMR — phishing resistance
+  if (requirement.phishingResistant === true) {
+    if (!acr.amrIncludesPhishingResistant(presented.amr)) {
+      return {
+        ok: false, error: INSUFFICIENT_USER_AUTHENTICATION,
+        reason: "presented amr " + JSON.stringify(presented.amr) +
+                " does not include any phishing-resistant method",
+        requirement: requirement, presented: presented,
+      };
+    }
+  }
+  return { ok: true, presented: presented };
+}
+
+function buildChallenge(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "requirement", "realm", "error", "errorDescription", "scope",
+  ], "auth.stepUp.buildChallenge");
+  _validateRequirement(opts.requirement, "auth.stepUp.buildChallenge");
+  var realm   = (typeof opts.realm === "string" && opts.realm.length > 0) ? opts.realm : DEFAULT_REALM;
+  var errCode = (typeof opts.error === "string" && opts.error.length > 0)
+    ? opts.error : INSUFFICIENT_USER_AUTHENTICATION;
+  var errDesc = (typeof opts.errorDescription === "string" && opts.errorDescription.length > 0)
+    ? opts.errorDescription : "A higher level of authentication is required";
+
+  var parts = [];
+  parts.push('realm=' + _quote(realm));
+  parts.push('error=' + _quote(errCode));
+  parts.push('error_description=' + _quote(errDesc));
+  if (typeof opts.scope === "string" && opts.scope.length > 0) {
+    parts.push('scope=' + _quote(opts.scope));
+  }
+
+  var req = opts.requirement;
+  // Per RFC 9470 §3: emit acr_values as space-separated string per RFC 6749.
+  if (typeof req.acr === "string" && req.acr.length > 0) {
+    parts.push('acr_values=' + _quote(req.acr));
+  } else if (Array.isArray(req.acrValues) && req.acrValues.length > 0) {
+    parts.push('acr_values=' + _quote(req.acrValues.join(" ")));
+  }
+  if (typeof req.maxAge === "number") {
+    parts.push('max_age=' + _quote(String(req.maxAge)));
+  }
+  if (Array.isArray(req.requiredAmr) && req.requiredAmr.length > 0) {
+    parts.push('amr_values=' + _quote(req.requiredAmr.join(" ")));
+  }
+  if (Array.isArray(req.authorizationDetails) && req.authorizationDetails.length > 0) {
+    parts.push('authorization_details=' + _quote(JSON.stringify(req.authorizationDetails)));
+  }
+  return "Bearer " + parts.join(", ");
+}
+
+// RFC 9396 helper — parse the JSON-array authorization_details parameter.
+// Throws on malformed payload at config time (operator typo at boot).
+// Hot-path callers wrap this in try/catch.
+function parseAuthorizationDetails(value) {
+  if (typeof value !== "string") {
+    throw new AuthError("auth-stepUp/bad-rar",
+      "parseAuthorizationDetails: value must be a JSON string — got " +
+      typeof value);
+  }
+  var parsed;
+  try { parsed = safeJson.parse(value, { maxBytes: C.BYTES.kib(64) }); }
+  catch (e) {
+    throw new AuthError("auth-stepUp/bad-rar",
+      "parseAuthorizationDetails: invalid JSON — " + e.message);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new AuthError("auth-stepUp/bad-rar",
+      "parseAuthorizationDetails: value must be a JSON array — got " +
+      typeof parsed);
+  }
+  for (var i = 0; i < parsed.length; i += 1) {
+    var entry = parsed[i];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new AuthError("auth-stepUp/bad-rar",
+        "parseAuthorizationDetails[" + i + "]: must be an object");
+    }
+    if (typeof entry.type !== "string" || entry.type.length === 0) {
+      throw new AuthError("auth-stepUp/bad-rar",
+        "parseAuthorizationDetails[" + i + "]: missing required 'type' field");
+    }
+  }
+  return parsed;
+}
+
+function emitAuditRequired(label, requirement, presented, req) {
+  try {
+    audit().safeEmit({
+      action:  "auth.stepup.required",
+      outcome: "denied",
+      actor:   { route: req && (req.url || req.pathname) || null,
+                 userId: req && req.user && req.user.id || null },
+      metadata: {
+        label:        label || "stepUp",
+        requirement:  _summarizeRequirement(requirement),
+        presented:    _summarizePresented(presented),
+      },
+    });
+  } catch (_e) { /* drop-silent */ }
+}
+
+function emitAuditSatisfied(label, requirement, presented, req) {
+  try {
+    audit().safeEmit({
+      action:  "auth.stepup.satisfied",
+      outcome: "success",
+      actor:   { route: req && (req.url || req.pathname) || null,
+                 userId: req && req.user && req.user.id || null },
+      metadata: {
+        label:        label || "stepUp",
+        requirement:  _summarizeRequirement(requirement),
+        presented:    _summarizePresented(presented),
+      },
+    });
+  } catch (_e) { /* drop-silent */ }
+}
+
+function _summarizeRequirement(req) {
+  if (!req || typeof req !== "object") return null;
+  return {
+    acr:               req.acr || null,
+    acrValues:         Array.isArray(req.acrValues) ? req.acrValues.slice() : null,
+    maxAge:            (typeof req.maxAge === "number") ? req.maxAge : null,
+    requiredAmr:       Array.isArray(req.requiredAmr) ? req.requiredAmr.slice() : null,
+    phishingResistant: req.phishingResistant === true ? true : false,
+  };
+}
+
+function _summarizePresented(presented) {
+  if (!presented || typeof presented !== "object") return null;
+  return {
+    acr:       presented.acr || null,
+    amr:       Array.isArray(presented.amr) ? presented.amr.slice() : null,
+    auth_time: presented.auth_time || null,
+  };
+}
+
+// ---- Bearer-challenge parser (RFC 7235 §2.1, RFC 9470 §3) ----
+//
+// Operator-side helper to inspect what an upstream RS challenged with.
+// Returns null when the header doesn't carry a Bearer challenge or
+// doesn't carry the insufficient_user_authentication error.
+
+function parseChallenge(headerValue) {
+  if (typeof headerValue !== "string") return null;
+  // Tolerate "Bearer " prefix in any case; reject anything else.
+  var idx = headerValue.toLowerCase().indexOf("bearer");
+  if (idx === -1) return null;
+  var rest = headerValue.slice(idx + "bearer".length).trim();
+  if (rest.length === 0) return null;
+  var out = { error: null, scope: null, acrValues: null, maxAge: null, raw: {} };
+  // Split on commas at top level, but respect quoted strings.
+  var tokens = _splitWwwAuth(rest);
+  for (var i = 0; i < tokens.length; i += 1) {
+    var token = tokens[i].trim();
+    var eq = token.indexOf("=");
+    if (eq === -1) continue;
+    var key = token.slice(0, eq).trim().toLowerCase();
+    var val = token.slice(eq + 1).trim();
+    if (val.length >= 2 && val.charAt(0) === '"' && val.charAt(val.length - 1) === '"') {
+      val = val.slice(1, val.length - 1);
+    }
+    out.raw[key] = val;
+    if (key === "error")              out.error     = val;
+    else if (key === "scope")         out.scope     = val;
+    else if (key === "acr_values")    out.acrValues = val.split(/\s+/);
+    else if (key === "max_age")       out.maxAge    = parseInt(val, 10);
+  }
+  return out;
+}
+
+function _splitWwwAuth(raw) {
+  var tokens = [];
+  var cursor = 0;
+  var inQuoted = false;
+  var current = "";
+  while (cursor < raw.length) {
+    var ch = raw.charAt(cursor);
+    if (inQuoted) {
+      current += ch;
+      if (ch === "\\" && cursor + 1 < raw.length) {
+        current += raw.charAt(cursor + 1);
+        cursor += 2;
+        continue;
+      }
+      if (ch === '"') inQuoted = false;
+      cursor += 1;
+      continue;
+    }
+    if (ch === '"') { inQuoted = true; current += ch; cursor += 1; continue; }
+    if (ch === ",") {
+      tokens.push(current);
+      current = "";
+      cursor += 1;
+      continue;
+    }
+    current += ch;
+    cursor += 1;
+  }
+  if (current.length > 0) tokens.push(current);
+  return tokens;
+}
+
+var policy        = lazyRequire(function () { return require("./step-up-policy"); });
+
+module.exports = {
+  evaluate:                  evaluate,
+  buildChallenge:            buildChallenge,
+  parseChallenge:            parseChallenge,
+  parseAuthorizationDetails: parseAuthorizationDetails,
+  acr:                       acr,
+  authTime:                  authTime,
+  get policy()               { return policy(); },
+  grant:                     {
+    create:           function (opts) { return elevation().create(opts); },
+    verify:           function (token, opts) { return elevation().verify(token, opts); },
+    revoke:           function (jti, opts) { return elevation().revoke(jti, opts); },
+    isRevoked:        function (jti) { return elevation().isRevoked(jti); },
+    list:             function () { return elevation().list(); },
+    setSigningKey:    function (key) { return elevation().setSigningKey(key); },
+    _resetForTests:   function () { return elevation()._resetForTests(); },
+  },
+  emitAuditRequired:   emitAuditRequired,
+  emitAuditSatisfied:  emitAuditSatisfied,
+  INSUFFICIENT_USER_AUTHENTICATION: INSUFFICIENT_USER_AUTHENTICATION,
+};

package/lib/break-glass.js

@@ -693,6 +693,45 @@ async function grant(opts) {
       "grant: no authenticated actor on request (req.user.id / req.apiKey.id required)", true);
   }
 
+  // Scope-gate enforcement — when the policy declares requireScope,
+  // the actor must carry the named scope (or matching wildcard via
+  // b.permissions.match) before the framework will mint a grant.
+  // Without this, every TOTP-passing actor could glass-unseal PHI
+  // even when the operator explicitly declared `requireScope:
+  // "phi:admin"`.
+  if (policy.requireScope) {
+    var actorScopes = (opts.req && opts.req.user && Array.isArray(opts.req.user.scopes))
+      ? opts.req.user.scopes
+      : ((opts.req && opts.req.apiKey && Array.isArray(opts.req.apiKey.scopes))
+        ? opts.req.apiKey.scopes
+        : []);
+    var scopeOk = false;
+    for (var sci = 0; sci < actorScopes.length; sci += 1) {
+      if (actorScopes[sci] === policy.requireScope) { scopeOk = true; break; }
+      // Wildcard support: "phi:*" matches "phi:admin" and "phi:read".
+      if (typeof actorScopes[sci] === "string" &&
+          actorScopes[sci].length > 0 &&
+          actorScopes[sci].charAt(actorScopes[sci].length - 1) === "*") {
+        var prefix = actorScopes[sci].slice(0, -1);
+        if (typeof policy.requireScope === "string" &&
+            policy.requireScope.indexOf(prefix) === 0) {
+          scopeOk = true; break;
+        }
+      }
+    }
+    if (!scopeOk) {
+      audit.safeEmit({
+        action:   "breakglass.grant.requested",
+        outcome:  "denied",
+        actor:    actor,
+        reason:   "missing-scope",
+        metadata: { table: table, requireScope: policy.requireScope },
+      });
+      throw new BreakGlassError("breakglass/missing-scope",
+        "grant: actor does not carry required scope '" + policy.requireScope + "'", true);
+    }
+  }
+
   // Factor verification + lockout
   var factorType = opts.factor && opts.factor.type;
   if (!factorType || policy.factors.indexOf(factorType) === -1) {
@@ -897,6 +936,20 @@ async function unsealRow(grantHandle, table, rowId, opts) {
       grantRow.maxRowsPerGrant + " allowed rows", true);
   }
 
+  // SELECT-before-increment — fetch the target row FIRST. If the row
+  // doesn't exist (operator typo, race with row-deletion, etc.), the
+  // grant should not be consumed. Without this ordering, a single
+  // typo against `maxRowsPerGrant: 1` (the default) exhausts the
+  // grant and forces the operator to re-do the step-up ceremony.
+  var rows = await clusterStorage.executeAll(
+    "SELECT * FROM " + '"' + table + '"' + " WHERE _id = ?",
+    [String(rowId)]
+  );
+  if (!rows || rows.length === 0) {
+    throw new BreakGlassError("breakglass/row-not-found",
+      "unsealRow: " + table + "[" + rowId + "] not found", true);
+  }
+
   // Increment rowsConsumed (atomic UPDATE with WHERE rowsConsumed < cap
   // so concurrent unseals can't both pass the runtime check above).
   var updateRes = await clusterStorage.execute(
@@ -925,20 +978,6 @@ async function unsealRow(grantHandle, table, rowId, opts) {
       "unsealRow: grant " + grantHandle.id + " was exhausted by a concurrent read", true);
   }
   void updateRes;
-
-  // Fetch + unseal the target row. Model A goes straight through
-  // cryptoField; Model B reads the row, lets cryptoField unseal the
-  // non-glass-locked columns, and then decryptCell handles the
-  // glass-locked columns separately (their ciphertext was written
-  // by encryptCell at app-write time, not by cryptoField.sealRow).
-  var rows = await clusterStorage.executeAll(
-    "SELECT * FROM " + '"' + table + '"' + " WHERE _id = ?",
-    [String(rowId)]
-  );
-  if (!rows || rows.length === 0) {
-    throw new BreakGlassError("breakglass/row-not-found",
-      "unsealRow: " + table + "[" + rowId + "] not found", true);
-  }
   var policy = await policyGet(table);
   var unsealedRow;
   if (policy && policy.cryptographic) {

package/lib/cache-redis.js

@@ -96,7 +96,7 @@ function create(cfg) {
 
   async function set(key, value, expiresAt, meta) {
     await _ensureConnected();
-    var json = JSON.stringify(value);
+    var json = safeJson.stringify(value);
 
     // Drop any prior tag membership for this key (tags may have changed
     // across sets). The reverse-tag set tells us which tag SETs need

package/lib/cache.js

@@ -491,7 +491,12 @@ function _clusterBackend(cfg) {
   }
 
   async function set(key, value, expiresAt, meta) {
-    var json = JSON.stringify(value);
+    // safeJson.stringify refuses Buffer / circular / Date round-trip
+    // ambiguity that vanilla JSON.stringify silently flattens. The
+    // failure mode without this is "cache returns a structurally-
+    // changed value, app code treats it as the original" — a subtle
+    // freshness bug that's hard to debug.
+    var json = safeJson.stringify(value);
     var storedExpires = (expiresAt === Infinity) ? Number.MAX_SAFE_INTEGER : expiresAt;
     var now = clock();
     var ck = _composedKey(key);

package/lib/cli.js

@@ -1370,9 +1370,9 @@ async function _runMtls(args, ctx) {
   if (vaultMode !== "wrapped" && vaultMode !== "plaintext") {
     return report.error("--vault-mode must be 'wrapped' or 'plaintext'", 2);
   }
-  var sealedMode = args.flags["sealed-mode"] || "auto";
-  if (["auto", "required", "disabled"].indexOf(sealedMode) === -1) {
-    return report.error("--sealed-mode must be 'auto', 'required', or 'disabled'", 2);
+  var sealedMode = args.flags["sealed-mode"] || "required";
+  if (["required", "disabled"].indexOf(sealedMode) === -1) {
+    return report.error("--sealed-mode must be 'required' or 'disabled'", 2);
   }
 
   var booted;

package/lib/cluster.js

@@ -69,7 +69,17 @@ var vault = lazyRequire(function () { return require("./vault"); });
 
 var DEFAULT_LEASE_TTL    = C.TIME.seconds(30);
 var DEFAULT_HEARTBEAT    = C.TIME.seconds(10);
-var MIN_LEASE_TTL        = C.TIME.seconds(5);
+// MIN_LEASE_TTL bumped from 5s → 10s. With 5s leases + 1s heartbeats,
+// a network glitch + GC pause can leave the old leader believing it
+// still holds the lease (4s remaining on its clock) while a new
+// leader has already acquired. Old-leader writes during that window
+// only land on framework state with a fencingToken WHERE clause
+// (audit-tip CHECK catches it); operator-supplied writes through
+// b.externalDb.transaction outside the audit chain DON'T carry the
+// clause and can be accepted by both leaders. 10s leaves more room
+// for the framework's audit-tip fencing to catch the split-brain
+// before consequential writes reach durable state.
+var MIN_LEASE_TTL        = C.TIME.seconds(10);
 var MIN_HEARTBEAT        = C.TIME.seconds(1);
 
 var initialized      = false;
@@ -476,7 +486,20 @@ async function _tryAcquire() {
 
 async function _heartbeat() {
   if (!initialized) return;
+  // ±20% per-tick jitter on followers — without it, N followers
+  // polling on a deterministic cadence all fire _tryAcquire at the
+  // same wall-clock instant on lease expiry, producing thundering-
+  // herd INSERT/UPDATE pressure on the leader-election row at
+  // exactly the worst time. Leader-renewal path doesn't jitter
+  // (a missed renewal hands the lease to a follower; the timing
+  // budget is in `leaseTtl - heartbeatMs`, not in the jitter
+  // window).
   if (!lease) {
+    var jitterMs = Math.floor(Math.random() * (heartbeatMs * 0.4));            // allow:math-random-noncrypto — heartbeat jitter, not security-bearing
+    if (jitterMs > 0) {
+      await safeAsync.sleep(jitterMs);
+    }
+    if (!initialized) return;
     // Not currently leader — try to acquire (lease may have expired
     // on the previous holder).
     await _tryAcquire();