@blamejs/core 0.6.12 → 0.6.20

package/lib/auth/password.js

@@ -47,6 +47,10 @@
  * "the call shape was wrong" (empty plain, oversize plain).
  */
 var argon2 = require("../vendor/argon2");
+var httpClient = require("../http-client");
+var internalSha1Hibp = require("../internal-sha1-hibp");
+var safeUrl = require("../safe-url");
+var timingSafeEqual = require("../crypto").timingSafeEqual;
 var { AuthError } = require("../framework-error");
 
 // Tuning targets ~250–500ms on commodity 2026 hardware. memoryCost
@@ -59,6 +63,444 @@ var DEFAULT_PARAMS = Object.freeze({
 
 var MAX_PLAINTEXT_BYTES = 4096;
 
+// ---- Policy primitive ----------------------------------------------
+//
+// Argon2id covers the OFFLINE attack model: even with the DB stolen,
+// each guess costs ~250ms of CPU + 64 MiB of RAM. It does NOT cover:
+//   - Online weak-credential attacks (operator phishes / reuses)
+//   - Periodic rotation requirements (PCI 8.3, NYDFS, some HIPAA)
+//   - History reuse (PCI 8.3 last-4 floor)
+//   - Operator-tunable composition rules (HIPAA / industry-specific
+//     where AAL2-equivalent posture is mandated)
+//
+// b.auth.password.policy(opts) returns:
+//   - check(plaintext, context?)         → presentation-time gate
+//   - shouldRotate(passwordSetAt)        → per-account rotation check
+//   - reuseProhibited(plaintext, history)→ history-reuse check
+//
+// Standards mapped:
+//   - NIST 800-63B §5.1.1.2: 8-char min floor, 64-char min max,
+//     breach check, NO MANDATORY composition. (Default posture.)
+//   - PCI-DSS 8.3.6 / 8.3.7: 12-char min, 90-day rotation, history
+//     of 4. (Operator opts in via { profile: "pci-8.3" }.)
+//   - HIPAA 164.308(a)(5)(ii)(D): "procedures for creating, changing,
+//     and safeguarding passwords" — addressed via composition opts.
+//   - GDPR Art. 32: storage shape (sealed via Argon2id); no
+//     additional policy requirement here.
+//   - NYDFS 23 NYCRR 500.12 / NIST AAL2: rotation + breach + length.
+//
+// The defaults follow NIST 800-63B (no mandatory composition,
+// length-and-breach over rules). Every other regime layers on
+// opt-in opts; the framework refuses to surprise an operator who
+// followed the defaults.
+//
+//   var policy = b.auth.password.policy({
+//     minLength:        12,
+//     breachCheck:      "haveibeenpwned",
+//     mustRotateAfterMs:    C.TIME.days(90),     // PCI 8.3.9
+//     historyMinDistance:   4,                    // PCI 8.3.7
+//     complexity: {
+//       minCategories:      0,                    // NIST: don't enforce. opt in for HIPAA-flavoured.
+//       categories:         ["lower", "upper", "digit", "special"],
+//       minRunRepeat:       3,                    // reject "aaaa…"
+//       minSequenceLength:  3,                    // reject "abcd"/"1234"
+//     },
+//     dictionary: ["companyName", "productName"],
+//   });
+//
+//   await policy.check(plain, { email, username, deny: [...], passwordSetAt });
+//   policy.shouldRotate(passwordSetAt);
+//   await policy.reuseProhibited(plain, [oldHash1, oldHash2, oldHash3]);
+//
+// breachCheck:"haveibeenpwned" uses the HIBP k-anonymity API; the
+// SHA-1 hash is computed in-process via lib/internal-sha1-hibp.js
+// (NOT exported on b.crypto — see comment in lib/crypto.js). Only
+// the first 5 hex chars cross the wire. Rate-limit and failure-mode
+// are operator's call: an HIBP outage returns
+// { ok: true, breachCheckSkipped: true } by default; failClosed:true
+// rejects.
+var DEFAULT_POLICY = Object.freeze({
+  minLength:              8,                  // NIST floor
+  maxLength:              MAX_PLAINTEXT_BYTES,
+  forbidCommon:           [],
+  // The bundled top-10000 list ships in lib/vendor/common-passwords-top-10000.txt
+  // (SecLists, CC-BY-3.0). Set false to skip — operators with a richer
+  // breach-list (HIBP downloads, NCSC 100k) layered via forbidCommon
+  // typically leave this on; it's additive.
+  useBundledCommon:       true,
+  denyContextSubstrings:  true,
+  breachCheck:            null,               // null | "haveibeenpwned"
+  breachThreshold:        1,
+  failClosed:             false,
+  hibpEndpoint:           "https://api.pwnedpasswords.com",
+  hibpTimeoutMs:          1500,
+  // Rotation policy (PCI 8.3.9 / NYDFS / industry-specific). null = no rotation.
+  mustRotateAfterMs:      null,
+  // History reuse (PCI 8.3.7 floor: last-4). 0 = disabled.
+  // Operator passes the actual stored hash list to reuseProhibited().
+  historyMinDistance:     0,
+  // Composition rules (NIST 800-63B explicitly says NOT to enforce
+  // these; HIPAA / older standards still ask for them. Default is OFF
+  // so the NIST-aligned posture is the default; operators opt in.)
+  complexity:             null,
+  // Dictionary terms forbidden as substrings (operator brand names,
+  // product names, etc.). Substring match, case-insensitive. Empty
+  // by default.
+  dictionary:             [],
+});
+
+var COMPLEXITY_DEFAULT = Object.freeze({
+  minCategories:     0,        // NIST default off; HIPAA-flavoured ops set 3 or 4
+  categories:        ["lower", "upper", "digit", "special"],
+  minRunRepeat:      0,        // reject N+ identical chars in a row; 0 = off
+  minSequenceLength: 0,        // reject N+ ascending or descending chars; 0 = off
+});
+
+// Predefined profiles operators can opt into. Each spreads onto the
+// policy opts so the operator can still override individual fields.
+var POLICY_PROFILES = Object.freeze({
+  // NIST 800-63B AAL2 baseline — length + breach, no composition.
+  "nist-aal2": Object.freeze({
+    minLength:    8,
+    breachCheck:  "haveibeenpwned",
+  }),
+  // PCI-DSS 4.0 §8.3 — 12-char min, 90-day rotation, history of 4.
+  // Composition is NOT required by PCI 4.0 (it dropped the older
+  // version's composition rule); breach check + length covers it.
+  "pci-4.0": Object.freeze({
+    minLength:           12,
+    breachCheck:         "haveibeenpwned",
+    mustRotateAfterMs:   90 * 24 * 60 * 60 * 1000,
+    historyMinDistance:  4,
+  }),
+  // HIPAA 164.308 — "procedures for creating, changing, and
+  // safeguarding". The standard is intentionally vague; the
+  // commonly-implemented profile pairs length + composition +
+  // rotation + lockout (lockout is b.auth.lockout, separate
+  // primitive).
+  "hipaa-aal2": Object.freeze({
+    minLength:           12,
+    breachCheck:         "haveibeenpwned",
+    mustRotateAfterMs:   180 * 24 * 60 * 60 * 1000,
+    historyMinDistance:  4,
+    complexity: {
+      minCategories: 3,
+      minRunRepeat:  3,
+      minSequenceLength: 3,
+    },
+  }),
+});
+
+// Top-10000 common-password set vendored from SecLists
+// (CC-BY-3.0 by Daniel Miessler). Loaded lazily on first policy.check
+// call — keeps boot fast for apps that never invoke the dictionary.
+// Operators wanting deeper enforcement supply opts.forbidCommon (set
+// of additional plaintexts) and/or opts.forbidCommonExtra (operator's
+// own breach list); both layer additively on top of the bundled set.
+var path = require("node:path");
+var fs   = require("node:fs");
+var _bundledCommonPasswords = null;
+function _loadBundledCommon() {
+  if (_bundledCommonPasswords) return _bundledCommonPasswords;
+  var p = path.join(__dirname, "..", "vendor", "common-passwords-top-10000.txt");
+  var text = fs.readFileSync(p, "utf8");
+  var set = new Set();
+  var lines = text.split(/\r?\n/);
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i].trim();
+    if (line.length > 0) set.add(line.toLowerCase());
+  }
+  _bundledCommonPasswords = set;
+  return _bundledCommonPasswords;
+}
+function _commonPasswordsSize() {
+  return _loadBundledCommon().size;
+}
+
+function _ok(extra) { return Object.assign({ ok: true }, extra || {}); }
+function _fail(code, message) {
+  return { ok: false, code: "policy/" + code, message: message };
+}
+
+// Argon2id verify with a known stored hash — used by reuseProhibited
+// to compare a candidate plaintext against history entries without
+// the operator having to wire verify() per row.
+async function _argon2Verify(stored, plaintext) {
+  if (typeof stored !== "string" || stored.indexOf("$argon2id$") !== 0) return false;
+  try { return await argon2.verify(stored, plaintext); }
+  catch (_e) { return false; }
+}
+
+function _hasCategory(plaintext, category) {
+  if (category === "lower")   return /[a-z]/.test(plaintext);
+  if (category === "upper")   return /[A-Z]/.test(plaintext);
+  if (category === "digit")   return /[0-9]/.test(plaintext);
+  if (category === "special") return /[^A-Za-z0-9]/.test(plaintext);
+  return false;
+}
+
+function _hasRunOfLength(plaintext, n) {
+  if (n < 2) return false;
+  for (var i = 0; i + n <= plaintext.length; i++) {
+    var c = plaintext.charCodeAt(i);
+    var allSame = true;
+    for (var j = 1; j < n; j++) {
+      if (plaintext.charCodeAt(i + j) !== c) { allSame = false; break; }
+    }
+    if (allSame) return true;
+  }
+  return false;
+}
+
+function _hasSequenceOfLength(plaintext, n) {
+  if (n < 3) return false;
+  for (var i = 0; i + n <= plaintext.length; i++) {
+    var ascending = true, descending = true;
+    for (var j = 1; j < n; j++) {
+      var diff = plaintext.charCodeAt(i + j) - plaintext.charCodeAt(i + j - 1);
+      if (diff !== 1)  ascending  = false;
+      if (diff !== -1) descending = false;
+    }
+    if (ascending || descending) return true;
+  }
+  return false;
+}
+
+function policy(opts) {
+  opts = opts || {};
+  // Apply named profile FIRST, then operator opts on top so the
+  // operator can override profile defaults per-field.
+  if (typeof opts.profile === "string" && opts.profile.length > 0) {
+    if (!POLICY_PROFILES[opts.profile]) {
+      throw new AuthError("auth-password/bad-policy",
+        "policy.profile must be one of " + Object.keys(POLICY_PROFILES).join("/") +
+        ", got " + JSON.stringify(opts.profile));
+    }
+    opts = Object.assign({}, POLICY_PROFILES[opts.profile], opts);
+    delete opts.profile;
+  }
+  var p = Object.assign({}, DEFAULT_POLICY, opts);
+  if (typeof p.minLength !== "number" || p.minLength < 1 || p.minLength > MAX_PLAINTEXT_BYTES) {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.minLength must be in [1, " + MAX_PLAINTEXT_BYTES + "]");
+  }
+  if (typeof p.maxLength !== "number" || p.maxLength < p.minLength || p.maxLength > MAX_PLAINTEXT_BYTES) {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.maxLength must be in [minLength, " + MAX_PLAINTEXT_BYTES + "]");
+  }
+  if (p.breachCheck !== null && p.breachCheck !== "haveibeenpwned") {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.breachCheck must be null or 'haveibeenpwned', got " + JSON.stringify(p.breachCheck));
+  }
+  if (p.hibpEndpoint) {
+    safeUrl.parse(p.hibpEndpoint, { allowedProtocols: safeUrl.ALLOW_HTTP_TLS, errorClass: AuthError });
+  }
+  if (p.mustRotateAfterMs !== null &&
+      (typeof p.mustRotateAfterMs !== "number" || !isFinite(p.mustRotateAfterMs) || p.mustRotateAfterMs <= 0)) {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.mustRotateAfterMs must be a positive finite number or null");
+  }
+  if (typeof p.historyMinDistance !== "number" || !isFinite(p.historyMinDistance) ||
+      p.historyMinDistance < 0 || Math.floor(p.historyMinDistance) !== p.historyMinDistance) {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.historyMinDistance must be a non-negative integer");
+  }
+  if (p.complexity !== null && typeof p.complexity !== "object") {
+    throw new AuthError("auth-password/bad-policy",
+      "policy.complexity must be null or an object");
+  }
+  var complexity = p.complexity ? Object.assign({}, COMPLEXITY_DEFAULT, p.complexity) : null;
+  if (complexity) {
+    if (typeof complexity.minCategories !== "number" || complexity.minCategories < 0 ||
+        complexity.minCategories > complexity.categories.length) {
+      throw new AuthError("auth-password/bad-policy",
+        "policy.complexity.minCategories must be in [0, " + complexity.categories.length + "]");
+    }
+    for (var ci = 0; ci < complexity.categories.length; ci++) {
+      if (["lower", "upper", "digit", "special"].indexOf(complexity.categories[ci]) === -1) {
+        throw new AuthError("auth-password/bad-policy",
+          "policy.complexity.categories[" + ci + "] must be lower / upper / digit / special, got " +
+          JSON.stringify(complexity.categories[ci]));
+      }
+    }
+  }
+  var forbidLower = (Array.isArray(p.forbidCommon) ? p.forbidCommon : [])
+    .map(function (s) { return String(s).toLowerCase(); });
+  var bundledSet = p.useBundledCommon === false ? null : _loadBundledCommon();
+  var dictionaryLower = (Array.isArray(p.dictionary) ? p.dictionary : [])
+    .filter(function (s) { return typeof s === "string" && s.length >= 3; })
+    .map(function (s) { return s.toLowerCase(); });
+
+  async function check(plaintext, context) {
+    if (typeof plaintext !== "string") {
+      return _fail("bad-input", "plaintext must be a string");
+    }
+    var byteLen = Buffer.byteLength(plaintext, "utf8");
+    if (byteLen < p.minLength) {
+      return _fail("too-short", "plaintext is shorter than " + p.minLength + " bytes");
+    }
+    if (byteLen > p.maxLength) {
+      return _fail("too-long", "plaintext exceeds " + p.maxLength + " bytes");
+    }
+    var lower = plaintext.toLowerCase();
+    if (bundledSet && bundledSet.has(lower)) {
+      return _fail("forbidden-common", "plaintext matches a known breached / common password (bundled top-10000)");
+    }
+    for (var i = 0; i < forbidLower.length; i++) {
+      if (lower === forbidLower[i]) {
+        return _fail("forbidden-common", "plaintext matches a known weak / common password");
+      }
+    }
+    for (var di2 = 0; di2 < dictionaryLower.length; di2++) {
+      if (lower.indexOf(dictionaryLower[di2]) !== -1) {
+        return _fail("forbidden-dictionary",
+          "plaintext contains a forbidden dictionary term");
+      }
+    }
+    if (p.denyContextSubstrings && context) {
+      var deny = [];
+      if (typeof context.email === "string" && context.email.length > 0) {
+        deny.push(context.email.toLowerCase());
+        var at = context.email.indexOf("@");
+        if (at > 0) deny.push(context.email.slice(0, at).toLowerCase());
+      }
+      if (typeof context.username === "string" && context.username.length > 0) {
+        deny.push(context.username.toLowerCase());
+      }
+      if (Array.isArray(context.deny)) {
+        for (var di = 0; di < context.deny.length; di++) {
+          if (typeof context.deny[di] === "string" && context.deny[di].length >= 3) {
+            deny.push(context.deny[di].toLowerCase());
+          }
+        }
+      }
+      for (var dj = 0; dj < deny.length; dj++) {
+        if (deny[dj].length >= 3 && lower.indexOf(deny[dj]) !== -1) {
+          return _fail("contains-context",
+            "plaintext contains a forbidden context substring (account identifier or operator-supplied deny string)");
+        }
+      }
+    }
+    if (complexity) {
+      if (complexity.minCategories > 0) {
+        var hits = 0;
+        for (var cc = 0; cc < complexity.categories.length; cc++) {
+          if (_hasCategory(plaintext, complexity.categories[cc])) hits++;
+        }
+        if (hits < complexity.minCategories) {
+          return _fail("complexity-categories",
+            "plaintext uses " + hits + " character categories; policy requires at least " +
+            complexity.minCategories + " of [" + complexity.categories.join(", ") + "]");
+        }
+      }
+      if (complexity.minRunRepeat >= 2 && _hasRunOfLength(plaintext, complexity.minRunRepeat)) {
+        return _fail("complexity-run",
+          "plaintext contains " + complexity.minRunRepeat + "+ identical consecutive characters");
+      }
+      if (complexity.minSequenceLength >= 3 && _hasSequenceOfLength(plaintext, complexity.minSequenceLength)) {
+        return _fail("complexity-sequence",
+          "plaintext contains a " + complexity.minSequenceLength + "+-char ascending or descending sequence");
+      }
+    }
+    if (p.breachCheck === "haveibeenpwned") {
+      // HIBP k-anonymity: send the first 5 hex chars of the SHA-1
+      // hash, scan the returned suffix list. The framework's only
+      // SHA-1 usage; HIBP requires it. (See lib/internal-sha1-hibp.js
+      // for the restriction rationale.)
+      var sha1Full = internalSha1Hibp.sha1Hex(plaintext).toUpperCase();
+      var prefix = sha1Full.slice(0, 5);
+      var suffix = sha1Full.slice(5);
+      var url = p.hibpEndpoint.replace(/\/+$/, "") + "/range/" + prefix;
+      var resp;
+      try {
+        resp = await httpClient.request({
+          method:        "GET",
+          url:           url,
+          headers:       { "User-Agent": "blamejs-password-policy/1" },
+          idleTimeoutMs: p.hibpTimeoutMs,
+          errorClass:    AuthError,
+        });
+      } catch (e) {
+        if (p.failClosed) {
+          return _fail("breach-check-failed",
+            "HIBP lookup failed and policy is fail-closed: " + ((e && e.message) || String(e)));
+        }
+        return _ok({ breachCheckSkipped: true,
+          breachCheckSkipReason: (e && e.message) || String(e) });
+      }
+      if (resp.statusCode !== 200 || !resp.body) {
+        if (p.failClosed) {
+          return _fail("breach-check-failed",
+            "HIBP returned status " + resp.statusCode + " with no body");
+        }
+        return _ok({ breachCheckSkipped: true,
+          breachCheckSkipReason: "hibp-status-" + resp.statusCode });
+      }
+      var bodyText = Buffer.isBuffer(resp.body) ? resp.body.toString("utf8") : String(resp.body);
+      var lines = bodyText.split(/\r?\n/);
+      for (var li = 0; li < lines.length; li++) {
+        var line = lines[li].trim();
+        if (line.length === 0) continue;
+        var colon = line.indexOf(":");
+        if (colon < 0) continue;
+        var hashSuffix = line.slice(0, colon).toUpperCase();
+        var count = parseInt(line.slice(colon + 1), 10);
+        if (timingSafeEqual(Buffer.from(hashSuffix, "utf8"), Buffer.from(suffix, "utf8")) &&
+            isFinite(count) && count >= p.breachThreshold) {
+          return _fail("breached",
+            "plaintext appears in HaveIBeenPwned with count " + count +
+            " (threshold " + p.breachThreshold + ")");
+        }
+      }
+      return _ok({ breachCheckCount: 0 });
+    }
+    return _ok();
+  }
+
+  function shouldRotate(passwordSetAt, now) {
+    if (p.mustRotateAfterMs === null) return false;
+    if (typeof passwordSetAt !== "number" || !isFinite(passwordSetAt)) {
+      throw new AuthError("auth-password/bad-input",
+        "shouldRotate: passwordSetAt must be a numeric ms-epoch timestamp");
+    }
+    var nowMs = typeof now === "number" ? now : Date.now();
+    return (nowMs - passwordSetAt) >= p.mustRotateAfterMs;
+  }
+
+  async function reuseProhibited(plaintext, history) {
+    if (typeof plaintext !== "string" || plaintext.length === 0) return false;
+    if (p.historyMinDistance <= 0) return false;
+    if (!Array.isArray(history) || history.length === 0) return false;
+    // Check the most-recent N entries (history-min-distance bound).
+    var checkCount = Math.min(history.length, p.historyMinDistance);
+    for (var i = 0; i < checkCount; i++) {
+      if (await _argon2Verify(history[i], plaintext)) return true;
+    }
+    return false;
+  }
+
+  return {
+    check:            check,
+    shouldRotate:     shouldRotate,
+    reuseProhibited:  reuseProhibited,
+    // Operator introspection — handy when an admin tool wants to
+    // surface "your policy requires X" to end users.
+    describe: function () {
+      return {
+        minLength:           p.minLength,
+        maxLength:           p.maxLength,
+        breachCheck:         p.breachCheck,
+        mustRotateAfterMs:   p.mustRotateAfterMs,
+        historyMinDistance:  p.historyMinDistance,
+        complexity:          complexity ? Object.assign({}, complexity) : null,
+        dictionaryCount:     dictionaryLower.length,
+        forbidCommonCount:   forbidLower.length,
+        bundledCommonCount:  bundledSet ? bundledSet.size : 0,
+      };
+    },
+  };
+}
+
 function _validatePlain(plain) {
   if (typeof plain !== "string" || plain.length === 0) {
     throw new AuthError("auth-password/invalid-plain",
@@ -132,8 +574,11 @@ function needsRehash(stored, opts) {
 }
 
 module.exports = {
-  hash:           hash,
-  verify:         verify,
-  needsRehash:    needsRehash,
-  DEFAULT_PARAMS: DEFAULT_PARAMS,
+  hash:             hash,
+  verify:           verify,
+  needsRehash:      needsRehash,
+  policy:           policy,
+  DEFAULT_PARAMS:   DEFAULT_PARAMS,
+  DEFAULT_POLICY:   DEFAULT_POLICY,
+  POLICY_PROFILES:  POLICY_PROFILES,
 };

package/lib/cache.js

@@ -93,6 +93,7 @@
 var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
+var numericChecks = require("./numeric-checks");
 var requestHelpers = require("./request-helpers");
 var safeAsync = require("./safe-async");
 var validateOpts = require("./validate-opts");
@@ -116,13 +117,8 @@ var DEFAULTS = Object.freeze({
 
 // ---- Config-time validation helpers (throw on bad input) ----
 
-function _isFiniteNonNegative(n) {
-  return typeof n === "number" && isFinite(n) && n >= 0;
-}
-
-function _isPositiveInt(n) {
-  return typeof n === "number" && isFinite(n) && n >= 1 && Math.floor(n) === n;
-}
+var _isFiniteNonNegative = numericChecks.isFiniteNonNegative;
+var _isPositiveInt       = numericChecks.isPositiveInt;
 
 // ttlMs accepts: any non-negative finite number OR Infinity. NaN, negative,
 // or non-number is rejected.