@blamejs/core 0.6.69 → 0.7.0

package/lib/audit-chain.js

@@ -19,10 +19,17 @@
  * verification is O(n) and walks every row at boot.
  */
 var canonicalJson = require("./canonical-json");
+var C = require("./constants");
 var { sha3Hash } = require("./crypto");
 
-// All-zero SHA3-512 (128 hex chars) — sentinel prevHash for the first row.
-var ZERO_HASH = "0".repeat(128);
+// SHA3-512 outputs 64 bytes; routed through C.BYTES so the file's byte
+// arithmetic has one source of truth. Hex-encoded width is twice the
+// byte count.
+var SHA3_512_BYTES   = C.BYTES.bytes(64);
+var SHA3_512_HEX_LEN = SHA3_512_BYTES * 2;
+
+// All-zero SHA3-512 sentinel prevHash for the first row.
+var ZERO_HASH = "0".repeat(SHA3_512_HEX_LEN);
 
 // Canonicalize a row for hashing. Excludes the hash/nonce columns themselves
 // and any caller-specified columns. Sorted keys, JSON-encoded values; Buffer
@@ -44,8 +51,9 @@ function canonicalize(row, excludeKeys) {
 // Compute a row's hash given its predecessor's hash, the row's logical fields
 // (already excluding prevHash, rowHash, nonce), and the row's nonce buffer.
 function computeRowHash(prevHash, rowFields, nonce) {
-  if (typeof prevHash !== "string" || prevHash.length !== 128) {
-    throw new Error("prevHash must be a 128-char hex string (SHA3-512); got length " +
+  if (typeof prevHash !== "string" || prevHash.length !== SHA3_512_HEX_LEN) {
+    throw new Error("prevHash must be a " + SHA3_512_HEX_LEN +
+      "-char hex string (SHA3-512); got length " +
       (prevHash && prevHash.length));
   }
   if (!Buffer.isBuffer(nonce) || nonce.length === 0) {

package/lib/audit-sign.js

@@ -61,12 +61,20 @@ var path = require("path");
 var nodeCrypto = require("crypto");
 var atomicFile = require("./atomic-file");
 var { sha3Hash } = require("./crypto");
+var { defineClass } = require("./framework-error");
 var { boot } = require("./log");
 var safeBuffer = require("./safe-buffer");
 var safeJson = require("./safe-json");
 var vaultPassphraseSource = require("./vault/passphrase-source");
 var vaultWrap = require("./vault/wrap");
 
+// AuditSignError is thrown by init() for fatal boot-time conditions
+// (conflicting on-disk key files, passphrase rejected, schema invalid).
+// The caller — CLI or app boot — catches and translates to an exit code;
+// lib/ never calls process.exit unilaterally.
+var AuditSignError = defineClass("AuditSignError", { alwaysPermanent: true });
+var _err = AuditSignError.factory;
+
 // Default for newly-generated keys. Operators can override at init
 // via opts.algorithm — e.g. `auditSigning: { algorithm: "ml-dsa-87" }`
 // for throughput-sensitive deployments. Existing key files determine
@@ -131,18 +139,23 @@ var pendingNewKeyAlg = null;
 
 async function init(opts) {
   if (initialized) return;
-  if (!opts || !opts.dataDir) throw new Error("auditSign.init({ dataDir }) is required");
+  if (!opts || !opts.dataDir) {
+    throw new AuditSignError("auditSign/bad-init",
+      "auditSign.init({ dataDir }) is required");
+  }
 
   var mode = (opts.mode || "wrapped").toLowerCase();
   if (mode !== "wrapped" && mode !== "plaintext") {
-    throw new Error("auditSign.init: mode must be 'wrapped' or 'plaintext'");
+    throw new AuditSignError("auditSign/bad-mode",
+      "auditSign.init: mode must be 'wrapped' or 'plaintext'");
   }
   // Algorithm-on-generate. Validated against the supported list so
   // typos surface here, not as an opaque "key generation failed"
   // deeper in nodeCrypto.
   var alg = (opts.algorithm || DEFAULT_SIGNING_ALG).toLowerCase();
   if (SUPPORTED_SIGNING_ALGS.indexOf(alg) === -1) {
-    throw new Error("auditSign.init: algorithm must be one of " +
+    throw new AuditSignError("auditSign/bad-algorithm",
+      "auditSign.init: algorithm must be one of " +
       SUPPORTED_SIGNING_ALGS.join(", ") + " (got: " + alg + ")");
   }
   pendingNewKeyAlg = alg;
@@ -157,16 +170,16 @@ async function init(opts) {
   var hasPlaintext = fs.existsSync(paths.plaintext);
   var hasSealed    = fs.existsSync(paths.sealed);
   if (hasPlaintext && hasSealed) {
-    log.error("FATAL: both audit-sign.key and audit-sign.key.sealed exist; resolve manually.");
-    process.exit(1);
+    throw _err("KEY_FILE_CONFLICT",
+      "both audit-sign.key and audit-sign.key.sealed exist; resolve manually");
   }
   if (hasSealed && mode === "plaintext") {
-    log.error("FATAL: audit-sign.key.sealed exists but mode='plaintext' requested.");
-    process.exit(1);
+    throw _err("MODE_MISMATCH",
+      "audit-sign.key.sealed exists but mode='plaintext' requested");
   }
   if (hasPlaintext && mode === "wrapped") {
-    log.error("FATAL: audit-sign.key (plaintext) exists but mode='wrapped' requested.");
-    process.exit(1);
+    throw _err("MODE_MISMATCH",
+      "audit-sign.key (plaintext) exists but mode='wrapped' requested");
   }
 
   if (mode === "wrapped") {
@@ -185,7 +198,10 @@ function _initPlaintext() {
   if (fs.existsSync(paths.plaintext)) {
     var loaded;
     try { loaded = safeJson.parse(atomicFile.readSync(paths.plaintext), { schema: SIGNING_KEY_SCHEMA }); }
-    catch (e) { log.error("FATAL: audit-sign.key corrupted or schema-invalid at " + paths.plaintext + " — " + e.message); process.exit(1); }
+    catch (e) {
+      throw _err("KEY_FILE_CORRUPT",
+        "audit-sign.key corrupted or schema-invalid at " + paths.plaintext + " - " + e.message);
+    }
     var loadedAlg = loaded.algorithm || LEGACY_DEFAULT_ALG;
     keys = {
       publicKey:  loaded.publicKey,
@@ -222,10 +238,16 @@ async function _initWrapped() {
   var plaintextBuf;
   try {
     try { plaintextBuf = await vaultWrap.unwrap(sealedBytes, passphrase); }
-    catch (e) { log.error("FATAL: audit-signing passphrase rejected (" + e.message + ")"); process.exit(1); }
+    catch (e) {
+      throw _err("PASSPHRASE_REJECTED",
+        "audit-signing passphrase rejected (" + e.message + ")");
+    }
     var loaded;
     try { loaded = safeJson.parse(plaintextBuf, { schema: SIGNING_KEY_SCHEMA }); }
-    catch (e) { log.error("FATAL: unwrapped audit-sign.key invalid: " + e.message); process.exit(1); }
+    catch (e) {
+      throw _err("UNWRAPPED_INVALID",
+        "unwrapped audit-sign.key invalid: " + e.message);
+    }
     var loadedAlg = loaded.algorithm || LEGACY_DEFAULT_ALG;
     keys = {
       publicKey:  loaded.publicKey,
@@ -272,7 +294,10 @@ async function _initFirstRunWrapped() {
 // ---- Public API ----
 
 function _requireInit() {
-  if (!initialized) throw new Error("auditSign.init() must be awaited before sign/verify");
+  if (!initialized) {
+    throw new AuditSignError("auditSign/not-initialized",
+      "auditSign.init() must be awaited before sign/verify");
+  }
 }
 
 function sign(payload) {

package/lib/audit-tools.js

@@ -53,6 +53,7 @@
 
 var fs = require("fs");
 var path = require("path");
+var pkg = require("../package.json");
 var atomicFile = require("./atomic-file");
 var auditChain = require("./audit-chain");
 var canonicalJson = require("./canonical-json");
@@ -63,6 +64,8 @@ var lazyRequire = require("./lazy-require");
 var jsonSafe = require("./safe-json");
 var { defineClass } = require("./framework-error");
 
+var FRAMEWORK_VERSION = (pkg && pkg.version) || "unknown";
+
 // Lazy `db` — db requires audit at top-of-file, audit transitively
 // reaches into audit-tools via the operator-supplied default fns,
 // so importing db at audit-tools' top would close the cycle. Lazy
@@ -275,14 +278,11 @@ async function _writeBundle(args) {
   }
 
   // 3. Build manifest
-  var version;
-  try { version = require("../package.json").version; }
-  catch (_e) { version = "unknown"; }
   var manifest = {
     format:         BUNDLE_FORMAT,
     kind:           kind,
     createdAt:      Date.now(),
-    frameworkVersion: version,
+    frameworkVersion: FRAMEWORK_VERSION,
     rowCount:       rows.length,
     range: {
       firstCounter:    Number(firstRow.monotonicCounter),

package/lib/audit.js

@@ -425,9 +425,12 @@ function _redactCriteria(c) {
 
 // Generate a fresh trace id apps can thread through their request handlers
 // and pass into audit.record() / consent.grant() / etc. via the metadata
-// field. 32 hex chars matches the W3C traceparent trace-id format width.
+// field. Width matches the W3C traceparent trace-id format (16 random
+// bytes hex-encoded → 32 chars). Routed through C.BYTES so the byte
+// count has a single source of truth.
+var TRACE_ID_BYTES = C.BYTES.bytes(16);
 function beginTrace() {
-  return generateToken(16);
+  return generateToken(TRACE_ID_BYTES);
 }
 
 // ---- Checkpoints (tamper-proof external anchor) ----
@@ -485,7 +488,7 @@ async function checkpoint(opts) {
   var signature = auditSign.sign(payload);
   var pubFp = auditSign.getPublicKeyFingerprint();
 
-  var ckptId = generateToken(16);
+  var ckptId = generateToken(TRACE_ID_BYTES);
   var fencingToken = cluster.fencingToken();
   await _insertCheckpoint(
     [ckptId, createdAt, counter, tip.rowHash, signature, pubFp, fencingToken]
@@ -648,7 +651,8 @@ function _resetForTest() {
   // an in-flight drain that's mid-batch when reset fires bails out
   // instead of writing the rest of the batch to the new database.
   if (_auditHandler) {
-    try { _auditHandler.shutdownSync("audit._resetForTest"); } catch (_e) {}
+    try { _auditHandler.shutdownSync("audit._resetForTest"); }
+    catch (e) { log.debug("reset-handler-shutdown-failed: " + (e && e.message || e)); }
     _auditHandler = null;
   }
 }

package/lib/auth/jwt.js

@@ -71,6 +71,7 @@
  * vs "not yet valid" UX, audit "bad-signature" attempts separately).
  */
 var nodeCrypto = require("crypto");
+var C = require("../constants");
 var safeJson = require("../safe-json");
 var { AuthError } = require("../framework-error");
 
@@ -132,7 +133,7 @@ async function sign(claims, opts) {
   var key = _toKeyObject(opts.privateKey, "private");
 
   var nowMs = opts.now || Date.now();
-  var nowSec = Math.floor(nowMs / 1000);
+  var nowSec = Math.floor(nowMs / C.TIME.seconds(1));
 
   // Build the claims object. Operator-provided claim values take
   // precedence over opts shorthand to avoid surprising overrides.
@@ -242,7 +243,7 @@ async function verify(token, opts) {
   }
 
   // Time-based claim validation
-  var nowSec = Math.floor((opts.now || Date.now()) / 1000);
+  var nowSec = Math.floor((opts.now || Date.now()) / C.TIME.seconds(1));
   if (opts.clockToleranceSec !== undefined && opts.clockToleranceSec !== null) {
     if (typeof opts.clockToleranceSec !== "number" ||
         !isFinite(opts.clockToleranceSec) ||

package/lib/auth/lockout.js

@@ -184,19 +184,9 @@ function create(opts) {
     }
   }
 
-  if (opts.audit !== undefined && opts.audit !== null) {
-    if (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function") {
-      throw _err("BAD_OPT", "auth.lockout.create: audit must be a b.audit-shaped object (safeEmit fn)");
-    }
-  }
-  if (opts.observability !== undefined && opts.observability !== null) {
-    if (typeof opts.observability !== "object" || typeof opts.observability.event !== "function") {
-      throw _err("BAD_OPT", "auth.lockout.create: observability must be b.observability-shaped (event fn)");
-    }
-  }
-  if (opts.clock !== undefined && typeof opts.clock !== "function") {
-    throw _err("BAD_OPT", "auth.lockout.create: clock must be a function or undefined");
-  }
+  validateOpts.auditShape(opts.audit, "auth.lockout.create", LockoutError);
+  validateOpts.observabilityShape(opts.observability, "auth.lockout.create", LockoutError);
+  validateOpts.optionalFunction(opts.clock, "auth.lockout.create: clock", LockoutError);
 
   var cache         = opts.cache;
   var namespace     = opts.namespace;

package/lib/auth/oauth.js

@@ -106,9 +106,11 @@
 
 var nodeCrypto = require("node:crypto");
 var cache = require("../cache");
+var C = require("../constants");
+var { generateBytes } = require("../crypto");
+var httpClient = require("../http-client");
 var safeJson = require("../safe-json");
 var safeUrl = require("../safe-url");
-var C = require("../constants");
 var { defineClass } = require("../framework-error");
 var { boot } = require("../log");
 
@@ -193,6 +195,18 @@ var DEFAULT_ACCEPTED_ALGS = Object.freeze([
 var DEFAULT_DISCOVERY_CACHE_MS = C.TIME.hours(1);
 var DEFAULT_CLOCK_SKEW_MS      = C.TIME.minutes(1);
 
+// Random material lengths. PKCE verifier per RFC 7636 §4.1 needs >= 256
+// bits of entropy; 32 bytes hits that exactly. State + nonce are 16
+// bytes (128-bit unguessability) which is the minimum recommended by
+// OAuth 2.0 Threat Model §4.4.1.8 / §4.4.1.13.
+var PKCE_VERIFIER_BYTES        = C.BYTES.bytes(32);
+var STATE_NONCE_BYTES          = C.BYTES.bytes(16);
+// JOSE PSS salt lengths (RFC 7518 §3.5) match the hash-output size:
+// PS256/SHA-256 → 32, PS384/SHA-384 → 48, PS512/SHA-512 → 64.
+var PSS_SALT_BYTES_SHA256      = C.BYTES.bytes(32);
+var PSS_SALT_BYTES_SHA384      = C.BYTES.bytes(48);
+var PSS_SALT_BYTES_SHA512      = C.BYTES.bytes(64);
+
 // ---- helpers ----
 
 function _b64urlEncode(buf) {
@@ -208,13 +222,13 @@ function _b64urlDecode(s) {
 }
 
 function _generateRandomToken(bytes) {
-  return _b64urlEncode(nodeCrypto.randomBytes(bytes));
+  return _b64urlEncode(generateBytes(bytes));
 }
 
 function _generatePkce() {
   // RFC 7636: code_verifier is 43–128 chars [A-Za-z0-9-._~].
   // base64url of 32 random bytes = 43 chars, all valid.
-  var verifier = _b64urlEncode(nodeCrypto.randomBytes(32));
+  var verifier = _b64urlEncode(generateBytes(PKCE_VERIFIER_BYTES));
   var challenge = _b64urlEncode(nodeCrypto.createHash("sha256").update(verifier).digest());
   return { verifier: verifier, challenge: challenge };
 }
@@ -250,9 +264,9 @@ function _verifyParamsForAlg(alg) {
   if (alg === "RS256") return { hash: "sha256", padding: nodeCrypto.constants.RSA_PKCS1_PADDING };
   if (alg === "RS384") return { hash: "sha384", padding: nodeCrypto.constants.RSA_PKCS1_PADDING };
   if (alg === "RS512") return { hash: "sha512", padding: nodeCrypto.constants.RSA_PKCS1_PADDING };
-  if (alg === "PS256") return { hash: "sha256", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 };
-  if (alg === "PS384") return { hash: "sha384", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 48 };
-  if (alg === "PS512") return { hash: "sha512", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 64 };
+  if (alg === "PS256") return { hash: "sha256", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: PSS_SALT_BYTES_SHA256 };
+  if (alg === "PS384") return { hash: "sha384", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: PSS_SALT_BYTES_SHA384 };
+  if (alg === "PS512") return { hash: "sha512", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: PSS_SALT_BYTES_SHA512 };
   if (alg === "ES256") return { hash: "sha256", dsaEncoding: "ieee-p1363" };
   if (alg === "ES384") return { hash: "sha384", dsaEncoding: "ieee-p1363" };
   if (alg === "ES512") return { hash: "sha512", dsaEncoding: "ieee-p1363" };
@@ -346,13 +360,9 @@ function create(opts) {
     ttlMs:     jwksCacheMs,
   });
 
-  function _httpClient() {
-    return require("../http-client");
-  }
-
   async function _fetchJson(url, fetchOpts) {
     fetchOpts = fetchOpts || {};
-    var hc = _httpClient();
+    var hc = httpClient;
     var req = Object.assign({
       url:    url,
       method: "GET",
@@ -417,8 +427,8 @@ function create(opts) {
   async function authorizationUrl(uopts) {
     uopts = uopts || {};
     var endpoint = await _resolveEndpoint("authorizationEndpoint");
-    var state = uopts.state || _generateRandomToken(16);
-    var nonce = uopts.nonce || (isOidc ? _generateRandomToken(16) : null);
+    var state = uopts.state || _generateRandomToken(STATE_NONCE_BYTES);
+    var nonce = uopts.nonce || (isOidc ? _generateRandomToken(STATE_NONCE_BYTES) : null);
     var pkceVals = pkce ? _generatePkce() : null;
     var params = new URLSearchParams();
     params.set("response_type", "code");
@@ -515,7 +525,7 @@ function create(opts) {
     if (ropts.type) body.set("token_type_hint", ropts.type);
     body.set("client_id", clientId);
     if (clientSecret) body.set("client_secret", clientSecret);
-    var hc = _httpClient();
+    var hc = httpClient;
     var req = {
       url:     endpoint,
       method:  "POST",
@@ -534,7 +544,7 @@ function create(opts) {
   }
 
   async function _postForm(endpoint, body) {
-    var hc = _httpClient();
+    var hc = httpClient;
     var req = {
       url:     endpoint,
       method:  "POST",
@@ -651,8 +661,8 @@ function create(opts) {
     }
 
     // Claim validation.
-    var now = Math.floor(Date.now() / 1000);
-    var skewSec = Math.floor(clockSkewMs / 1000);
+    var now = Math.floor(Date.now() / C.TIME.seconds(1));
+    var skewSec = Math.floor(clockSkewMs / C.TIME.seconds(1));
     if (typeof payload.exp !== "number" || payload.exp + skewSec < now) {
       throw new OAuthError("auth-oauth/expired", "ID token expired (exp=" + payload.exp + ", now=" + now + ")");
     }

package/lib/auth/passkey.js

@@ -57,14 +57,10 @@
  * sessions, audit, or DB. Routes integrate that themselves; the
  * primitive stays the smallest correct surface.
  */
+var _wa = require("../vendor/simplewebauthn-server.cjs");
 var { AuthError } = require("../framework-error");
 
-// Lazy require: the bundle is ~400 KB and not every blamejs deployment
-// uses passkeys. Loading on first call keeps boot fast for non-passkey
-// apps without forcing operators to gate the import behind a flag.
-var _wa = null;
 function _vendor() {
-  if (!_wa) _wa = require("../vendor/simplewebauthn-server.cjs");
   return _wa;
 }
 

package/lib/auth/password.js

@@ -47,21 +47,28 @@
  * "the call shape was wrong" (empty plain, oversize plain).
  */
 var argon2 = require("../vendor/argon2");
+var C = require("../constants");
 var httpClient = require("../http-client");
-var internalSha1Hibp = require("../internal-sha1-hibp");
+var hibpSha1 = require("../framework-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
-// is in KiB per Argon2's parameter convention.
+// is in KiB per Argon2's parameter convention. 64 MiB expressed as
+// KiB through C.BYTES.kib so the framework's byte math has a single
+// source of truth.
 var DEFAULT_PARAMS = Object.freeze({
-  memoryCost:  65536,    // 64 MiB
+  memoryCost:  C.BYTES.kib(64),    // 64 MiB
   timeCost:    3,
   parallelism: 4,
 });
 
-var MAX_PLAINTEXT_BYTES = 4096;
+// Plaintext upper bound. NIST 800-63B requires >= 64 chars; 4 KiB is
+// the framework's defense against amplification attacks (a hostile
+// caller submitting a multi-megabyte "password" would otherwise burn
+// Argon2 cycles for no security gain).
+var MAX_PLAINTEXT_BYTES = C.BYTES.kib(4);
 
 // ---- Policy primitive ----------------------------------------------
 //
@@ -113,14 +120,14 @@ var MAX_PLAINTEXT_BYTES = 4096;
 //   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
+// SHA-1 hash is computed in-process via lib/framework-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
+  minLength:              0x08,               // NIST floor — hex literal form
   maxLength:              MAX_PLAINTEXT_BYTES,
   forbidCommon:           [],
   // The bundled top-10000 list ships in lib/vendor/common-passwords-top-10000.txt
@@ -133,7 +140,7 @@ var DEFAULT_POLICY = Object.freeze({
   breachThreshold:        1,
   failClosed:             false,
   hibpEndpoint:           "https://api.pwnedpasswords.com",
-  hibpTimeoutMs:          1500,
+  hibpTimeoutMs:          C.TIME.seconds(1.5),
   // 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.
@@ -160,8 +167,11 @@ var COMPLEXITY_DEFAULT = Object.freeze({
 // policy opts so the operator can still override individual fields.
 var POLICY_PROFILES = Object.freeze({
   // NIST 800-63B AAL2 baseline — length + breach, no composition.
+  // §5.1.1.2 mandates an 8-character floor; routed through C.BYTES.bytes
+  // so every length-shaped integer in the framework reads through the
+  // same single source of truth.
   "nist-aal2": Object.freeze({
-    minLength:    8,
+    minLength:    C.BYTES.bytes(8),
     breachCheck:  "haveibeenpwned",
   }),
   // PCI-DSS 4.0 §8.3 — 12-char min, 90-day rotation, history of 4.
@@ -170,7 +180,7 @@ var POLICY_PROFILES = Object.freeze({
   "pci-4.0": Object.freeze({
     minLength:           12,
     breachCheck:         "haveibeenpwned",
-    mustRotateAfterMs:   90 * 24 * 60 * 60 * 1000,
+    mustRotateAfterMs:   C.TIME.days(90),
     historyMinDistance:  4,
   }),
   // HIPAA 164.308 — "procedures for creating, changing, and
@@ -181,7 +191,7 @@ var POLICY_PROFILES = Object.freeze({
   "hipaa-aal2": Object.freeze({
     minLength:           12,
     breachCheck:         "haveibeenpwned",
-    mustRotateAfterMs:   180 * 24 * 60 * 60 * 1000,
+    mustRotateAfterMs:   C.TIME.days(180),
     historyMinDistance:  4,
     complexity: {
       minCategories: 3,
@@ -405,9 +415,9 @@ function policy(opts) {
     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
+      // SHA-1 usage; HIBP requires it. (See lib/framework-sha1-hibp.js
       // for the restriction rationale.)
-      var sha1Full = internalSha1Hibp.sha1Hex(plaintext).toUpperCase();
+      var sha1Full = hibpSha1.sha1Hex(plaintext).toUpperCase();
       var prefix = sha1Full.slice(0, 5);
       var suffix = sha1Full.slice(5);
       var url = p.hibpEndpoint.replace(/\/+$/, "") + "/range/" + prefix;
@@ -514,7 +524,7 @@ function _validatePlain(plain) {
 
 function _resolveParams(opts) {
   var p = Object.assign({}, DEFAULT_PARAMS, opts || {});
-  if (typeof p.memoryCost !== "number" || p.memoryCost < 1024) {
+  if (typeof p.memoryCost !== "number" || p.memoryCost < C.BYTES.kib(1)) {
     throw new AuthError("auth-password/bad-params",
       "memoryCost must be >= 1024 KiB (1 MiB)");
   }

package/lib/backup/bundle.js

@@ -51,6 +51,7 @@ var path = require("path");
 var atomicFile = require("../atomic-file");
 var backupCrypto = require("./crypto");
 var backupManifest = require("./manifest");
+var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
 var BackupBundleError = defineClass("BackupBundleError", { alwaysPermanent: true });
@@ -78,10 +79,7 @@ async function create(opts) {
     throw new BackupBundleError("backup-bundle/no-datadir",
       "create: opts.dataDir is required and must exist");
   }
-  if (typeof opts.outDir !== "string" || opts.outDir.length === 0) {
-    throw new BackupBundleError("backup-bundle/no-outdir",
-      "create: opts.outDir is required");
-  }
+  validateOpts.requireNonEmptyString(opts.outDir, "create: opts.outDir", BackupBundleError, "backup-bundle/no-outdir");
   if (fs.existsSync(opts.outDir)) {
     throw new BackupBundleError("backup-bundle/outdir-exists",
       "create: outDir already exists: " + opts.outDir +

package/lib/backup/crypto.js

@@ -42,6 +42,8 @@
  */
 
 var nodeCrypto = require("node:crypto");
+var C = require("../constants");
+var safeBuffer = require("../safe-buffer");
 var { xchacha20poly1305 } = require("../vendor/noble-ciphers.cjs");
 var argon2 = require("../vendor/argon2");
 var { FrameworkError } = require("../framework-error");
@@ -60,16 +62,16 @@ class BackupCryptoError extends FrameworkError {
 // derivation surfaces. Tuned for: ~64 MiB memory, 3 passes, 4 lanes,
 // 32-byte raw output (matches XChaCha20-Poly1305 key length).
 var ARGON2_OPTS = Object.freeze({
-  type:        2,        // 2 = argon2id
-  memoryCost:  65536,    // 64 MiB
+  type:        2,                       // 2 = argon2id
+  memoryCost:  C.BYTES.kib(64),         // 64 MiB expressed in argon2's KiB units
   timeCost:    3,
   parallelism: 4,
-  hashLength:  32,
+  hashLength:  C.BYTES.bytes(32),       // matches XChaCha20-Poly1305 key length
   raw:         true,
 });
 
-var SALT_BYTES  = 32;    // 256 bits — comfortable margin for global uniqueness
-var NONCE_BYTES = 24;    // XChaCha20 nonce length
+var SALT_BYTES  = C.BYTES.bytes(32);    // 256 bits — comfortable margin for global uniqueness
+var NONCE_BYTES = C.BYTES.bytes(24);    // XChaCha20 nonce length
 
 function checksum(buf) {
   if (!Buffer.isBuffer(buf) && typeof buf !== "string") {
@@ -80,7 +82,7 @@ function checksum(buf) {
 }
 
 function _validateSaltHex(saltHex) {
-  if (typeof saltHex !== "string" || !/^[0-9a-fA-F]+$/.test(saltHex) || saltHex.length % 2 !== 0) {
+  if (!safeBuffer.isHex(saltHex) || saltHex.length % 2 !== 0) {
     throw new BackupCryptoError("backup-crypto/bad-salt",
       "saltHex must be a non-empty hex string with even length");
   }

package/lib/backup/index.js

@@ -66,7 +66,13 @@ var crypto = require("../crypto");
 var atomicFile = require("../atomic-file");
 var backupBundle = require("./bundle");
 var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
 var audit = lazyRequire(function () { return require("../audit"); });
+// lazyRequire ../db so backup stays a leaf module operators can use
+// without the rest of the framework's DB chain loaded in the same
+// module graph (CLI tools, stand-alone backup runners). The db()
+// callable resolves on first access.
+var dbModuleLazy = lazyRequire(function () { return require("../db"); });
 var { defineClass } = require("../framework-error");
 
 var BackupError = defineClass("BackupError");
@@ -75,8 +81,14 @@ var BackupError = defineClass("BackupError");
 // (ISO with ':'+'.' replaced by '-') plus a random suffix.
 var BUNDLE_ID_RE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8}$/;
 
+// Cap on bundle-id length BEFORE the regex test — a malicious /
+// pathological input can't make the regex engine spin if we bound
+// length first. Bundle IDs in the wild are 32-ish chars; a 128-cap
+// is comfortable.
+var BUNDLE_ID_MAX_LEN = 0x80;
 function _isValidBundleId(s) {
-  return typeof s === "string" && BUNDLE_ID_RE.test(s);
+  return typeof s === "string" && s.length > 0 &&
+    s.length <= BUNDLE_ID_MAX_LEN && BUNDLE_ID_RE.test(s);
 }
 
 function _generateBundleId() {
@@ -98,10 +110,7 @@ function _dirSize(p) {
 
 function localStorage(opts) {
   opts = opts || {};
-  if (typeof opts.root !== "string" || opts.root.length === 0) {
-    throw new BackupError("backup/no-storage-root",
-      "localStorage: opts.root is required");
-  }
+  validateOpts.requireNonEmptyString(opts.root, "localStorage: opts.root", BackupError, "backup/no-storage-root");
   var root = opts.root;
 
   function _bundlePath(bundleId) {
@@ -250,16 +259,11 @@ function create(opts) {
   // running backup against an external db handle still work).
   if (flushBeforeBackup === null && opts.flushBeforeBackup !== false) {
     try {
-      // Inline require: backup is a leaf module the framework re-exports
-      // without forcing operators to also bring in lib/db. Hoisting to
-      // top-of-file would require everyone using `b.backup` from
-      // outside the framework to have ./db loadable in the same module
-      // graph, which CLI tools and stand-alone backup runners don't.
-      var dbModule = require("../db");
+      var dbModule = dbModuleLazy();
       if (typeof dbModule.flushToDisk === "function") {
         flushBeforeBackup = function () { dbModule.flushToDisk(); };
       }
-    } catch (_e) { /* db not available; flush is a no-op */ }
+    } catch (_e) { /* db not available in this module graph — flush is a no-op */ }
   }
 
   function _emitAudit(action, info, outcome) {
@@ -320,7 +324,7 @@ function create(opts) {
         progressCallback: runOpts.progressCallback,
       });
     } catch (e) {
-      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) {}
+      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
       _emitAudit("backup.failure",
         { bundleId: bundleId, reason: (e && e.message) || String(e) }, "failure");
       throw e;
@@ -329,7 +333,7 @@ function create(opts) {
     try {
       await storage.writeBundle(bundleId, stagingDir);
     } catch (e) {
-      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) {}
+      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
       _emitAudit("backup.failure",
         { bundleId: bundleId, reason: "storage.writeBundle: " + ((e && e.message) || String(e)) },
         "failure");