@blamejs/core 0.6.70 → 0.7.0

package/lib/validate-opts.js

@@ -53,5 +53,218 @@ function check(opts, allowedKeys, primitive) {
   }
 }
 
+// auditShape — operator-supplied `opts.audit` must expose a
+// `safeEmit` function. 10+ primitive create() functions previously
+// inlined the same shape check + throw. Centralized here so every
+// consumer has one validation contract.
+function auditShape(audit, callerLabel, errorClass, code) {
+  if (audit === undefined || audit === null) return audit;
+  if (typeof audit !== "object" || typeof audit.safeEmit !== "function") {
+    var msg = (callerLabel || "audit") +
+      ": audit must be a b.audit-shaped object (safeEmit fn)";
+    if (errorClass && errorClass.factory) {
+      throw errorClass.factory(code || "BAD_OPT", msg);
+    }
+    if (typeof errorClass === "function") {
+      throw new errorClass(code || "audit/bad-shape", msg);
+    }
+    throw new Error(msg);
+  }
+  return audit;
+}
+
+// _throw — shared error-emission for the optional* validators. Routes
+// through the caller's framework-error class when supplied, falls back
+// to plain Error so this helper itself stays decoupled from any one
+// error hierarchy.
+function _throw(errorClass, code, msg, defaultCode) {
+  if (errorClass && errorClass.factory) {
+    throw errorClass.factory(code || "BAD_OPT", msg);
+  }
+  if (typeof errorClass === "function") {
+    throw new errorClass(code || defaultCode, msg);
+  }
+  throw new Error(msg);
+}
+
+// optionalBoolean / optionalPositiveInt / optionalFiniteNonNegative /
+// optionalPositiveFinite / optionalFunction — opt-time type assertions
+// for fields that may be omitted. Each returns the value unchanged when
+// undefined or null (preserving the caller's "absent → use default"
+// semantics) and throws on any other shape.
+//
+// 10+ primitive create() functions previously rolled identical
+// `if (opts.X !== undefined && typeof opts.X !== "Y") throw`
+// sequences. Centralizing the throw here keeps the operator-facing
+// message format consistent and gives the codebase-pattern catalog one
+// place to point new authors at.
+
+function optionalBoolean(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "boolean") {
+    _throw(errorClass, code, (label || "opt") + " must be a boolean, got " + typeof value,
+           "validate-opts/bad-boolean");
+  }
+  return value;
+}
+
+function optionalPositiveInt(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "number" || !isFinite(value) || value < 1 || Math.floor(value) !== value) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be a positive integer (>= 1, finite), got " +
+           (typeof value === "number" ? String(value) : typeof value),
+           "validate-opts/bad-positive-int");
+  }
+  return value;
+}
+
+function optionalFiniteNonNegative(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "number" || !isFinite(value) || value < 0) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be a non-negative finite number, got " +
+           (typeof value === "number" ? String(value) : typeof value),
+           "validate-opts/bad-non-negative-finite");
+  }
+  return value;
+}
+
+function optionalPositiveFinite(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "number" || !isFinite(value) || value <= 0) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be a positive finite number (> 0), got " +
+           (typeof value === "number" ? String(value) : typeof value),
+           "validate-opts/bad-positive-finite");
+  }
+  return value;
+}
+
+function optionalFunction(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "function") {
+    _throw(errorClass, code, (label || "opt") + " must be a function, got " + typeof value,
+           "validate-opts/bad-function");
+  }
+  return value;
+}
+
+// applyDefaults — resolve every key in DEFAULTS against opts. For each
+// key, the operator's value (if not undefined) wins; otherwise the
+// default is used. Returns a new plain object — NOT a frozen one, so
+// the create() function can layer additional resolved fields if it
+// needs them. 5+ primitives previously rolled their own
+// `var X = (opts.X === undefined) ? DEFAULTS.X : opts.X;` cascade
+// across 5–10 lines per call site; this collapses them all to one.
+//
+// Operator-supplied keys that aren't in DEFAULTS are dropped — use
+// validateOpts(opts, ALLOWED_KEYS, label) at the boundary FIRST to
+// reject typos before this resolves. Pass-through behavior would let
+// `{ ttllMs: 5000 }` silently apply the default ttlMs without warning.
+function applyDefaults(opts, defaults) {
+  if (defaults === null || typeof defaults !== "object") {
+    throw new Error("validate-opts.applyDefaults: defaults must be an object");
+  }
+  opts = opts || {};
+  var out = {};
+  var keys = Object.keys(defaults);
+  for (var i = 0; i < keys.length; i++) {
+    var k = keys[i];
+    out[k] = (opts[k] === undefined) ? defaults[k] : opts[k];
+  }
+  return out;
+}
+
+// requireObject — every primitive's `_validate*Opts(opts)` function
+// previously started with the same `if (!opts || typeof opts !== "object")
+// throw _err(...)` prelude. Centralized here so the contract is one
+// definition. Throws on null / undefined / non-object; returns opts on
+// success.
+function requireObject(opts, callerLabel, errorClass, code) {
+  if (!opts || typeof opts !== "object") {
+    var msg = (callerLabel || "opts") + ": opts must be an object, got " +
+      (opts === null ? "null" : typeof opts);
+    _throw(errorClass, code, msg, "validate-opts/bad-object");
+  }
+  return opts;
+}
+
+function optionalNonEmptyString(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "string" || value.length === 0) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be a non-empty string, got " +
+           (typeof value === "string" ? "empty string" : typeof value),
+           "validate-opts/bad-non-empty-string");
+  }
+  return value;
+}
+
+// requireNonEmptyString — required-field counterpart to
+// optionalNonEmptyString. Throws on undefined / null / empty / non-
+// string. The dozens of `if (typeof opts.X !== "string" ||
+// opts.X.length === 0) throw` sites every primitive's create() rolled
+// at the top of validation collapse to one call here.
+function requireNonEmptyString(value, label, errorClass, code) {
+  if (typeof value !== "string" || value.length === 0) {
+    var got = value === undefined ? "undefined"
+            : value === null      ? "null"
+            : typeof value === "string" ? "empty string"
+            : typeof value;
+    _throw(errorClass, code, (label || "opt") +
+           " must be a non-empty string, got " + got,
+           "validate-opts/missing-non-empty-string");
+  }
+  return value;
+}
+
+// makeAuditEmitter — closure factory parallel to safeAsync.makeDropCallback.
+// Replaces the per-file `function _emit(action, info) { if (!audit) return;
+// try { audit.safeEmit(Object.assign({ action: action }, info || {})); }
+// catch (_e) { /* audit best-effort */ } }` boilerplate that 5 primitives
+// previously rolled by hand (api-key / cache / notify / permissions /
+// sigv4-bucket-ops).
+//
+// audit may be null/undefined — returns a no-op emitter in that case so
+// callers don't need to null-check at every call site.
+//
+//   var _emit = validateOpts.makeAuditEmitter(opts.audit);
+//   _emit("apikey.create", { actor: ..., resource: ..., outcome: "success" });
+function makeAuditEmitter(audit) {
+  if (!audit || typeof audit.safeEmit !== "function") {
+    return function _noopEmit() {};
+  }
+  return function _emit(action, info) {
+    try { audit.safeEmit(Object.assign({ action: action }, info || {})); }
+    catch (_e) { /* audit best-effort — never break the caller */ }
+  };
+}
+
+// observabilityShape — operator-supplied `opts.observability` must
+// expose an `event` function. Parallel to auditShape; the n=1 catalog
+// tracks both inline-shape regexes.
+function observabilityShape(observability, callerLabel, errorClass, code) {
+  if (observability === undefined || observability === null) return observability;
+  if (typeof observability !== "object" || typeof observability.event !== "function") {
+    var msg = (callerLabel || "observability") +
+      ": observability must be a b.observability-shaped object (event fn)";
+    _throw(errorClass, code, msg, "observability/bad-shape");
+  }
+  return observability;
+}
+
 module.exports = check;
 module.exports.check = check;
+module.exports.auditShape = auditShape;
+module.exports.optionalBoolean = optionalBoolean;
+module.exports.optionalPositiveInt = optionalPositiveInt;
+module.exports.optionalFiniteNonNegative = optionalFiniteNonNegative;
+module.exports.optionalPositiveFinite = optionalPositiveFinite;
+module.exports.optionalFunction = optionalFunction;
+module.exports.optionalNonEmptyString = optionalNonEmptyString;
+module.exports.requireNonEmptyString = requireNonEmptyString;
+module.exports.observabilityShape = observabilityShape;
+module.exports.requireObject = requireObject;
+module.exports.applyDefaults = applyDefaults;
+module.exports.makeAuditEmitter = makeAuditEmitter;

package/lib/vault/index.js

@@ -41,6 +41,13 @@ var safeJson = require("../safe-json");
 var observability = require("../observability");
 var vaultPassphraseSource = require("./passphrase-source");
 var vaultWrap = require("./wrap");
+var { defineClass } = require("../framework-error");
+
+// VaultError — thrown by init() for fatal boot-time conditions
+// (corrupt sealed file, schema mismatch, mode/state conflicts). The
+// CLI / app entry point catches it and exits; lib code never calls
+// process.exit() unilaterally.
+var VaultError = defineClass("VaultError", { alwaysPermanent: true });
 
 var VAULT_PREFIX = C.VAULT_PREFIX;
 
@@ -72,12 +79,13 @@ async function init(opts) {
   opts = opts || {};
 
   if (!opts.dataDir) {
-    throw new Error("vault.init({ dataDir }) is required");
+    throw new VaultError("vault/bad-init", "vault.init({ dataDir }) is required");
   }
 
   var mode = (opts.mode || "wrapped").toLowerCase();
   if (mode !== "wrapped" && mode !== "plaintext") {
-    throw new Error("vault.init: mode must be 'wrapped' or 'plaintext', got: " + opts.mode);
+    throw new VaultError("vault/bad-mode",
+      "vault.init: mode must be 'wrapped' or 'plaintext', got: " + opts.mode);
   }
   currentMode = mode;
   paths = resolvePaths(opts.dataDir);
@@ -95,21 +103,21 @@ async function init(opts) {
 
   // Refuse to guess when both files coexist
   if (hasPlaintext && hasSealed) {
-    log.error("FATAL: both vault.key and vault.key.sealed exist in " + paths.dataDir);
-    log.error("Delete the one you do NOT want to keep, then restart.");
-    process.exit(1);
+    throw new VaultError("vault/both-files-exist",
+      "both vault.key and vault.key.sealed exist in " + paths.dataDir +
+      " — delete the one you do NOT want to keep, then restart");
   }
 
   // Mode-vs-state mismatches
   if (hasSealed && mode === "plaintext") {
-    log.error("FATAL: vault.key.sealed exists but vault.init({ mode: 'plaintext' }) was requested.");
-    log.error("Either run with mode: 'wrapped', or remove the sealed file (after migration).");
-    process.exit(1);
+    throw new VaultError("vault/mode-mismatch",
+      "vault.key.sealed exists but vault.init({ mode: 'plaintext' }) was requested — " +
+      "either run with mode: 'wrapped', or remove the sealed file (after migration)");
   }
   if (hasPlaintext && mode === "wrapped") {
-    log.error("FATAL: vault.key (plaintext) exists but vault.init({ mode: 'wrapped' }) was requested.");
-    log.error("Either run with mode: 'plaintext', or migrate the key to a wrapped form.");
-    process.exit(1);
+    throw new VaultError("vault/mode-mismatch",
+      "vault.key (plaintext) exists but vault.init({ mode: 'wrapped' }) was requested — " +
+      "either run with mode: 'plaintext', or migrate the key to a wrapped form");
   }
 
   if (mode === "wrapped") {
@@ -143,9 +151,10 @@ function initPlaintext() {
         },
       });
     } catch (e) {
-      log.error("FATAL: vault.key corrupted, unreadable, or schema-invalid at " + paths.plaintext + " — " + e.message);
-      log.error("All sealed data requires the original key. Restore from backup, then restart.");
-      process.exit(1);
+      throw new VaultError("vault/key-corrupt",
+        "vault.key corrupted, unreadable, or schema-invalid at " + paths.plaintext +
+        " — " + e.message +
+        " — all sealed data requires the original key; restore from backup, then restart");
     }
     keys = loaded;
     return;
@@ -162,16 +171,15 @@ async function initWrapped() {
   try {
     sealedBytes = atomicFile.readSync(paths.sealed);
   } catch (e) {
-    log.error("FATAL: cannot read " + paths.sealed + ": " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/sealed-unreadable",
+      "cannot read " + paths.sealed + ": " + e.message);
   }
 
   var passphrase;
   try {
     passphrase = await vaultPassphraseSource.getPassphrase({ prompt: "Vault passphrase: " });
   } catch (e) {
-    log.error("FATAL: " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/passphrase-error", e.message);
   }
 
   var plaintextJson;
@@ -180,8 +188,8 @@ async function initWrapped() {
     plaintextBuf = await vaultWrap.unwrap(sealedBytes, passphrase);
     plaintextJson = plaintextBuf.toString("utf8");
   } catch (e) {
-    log.error("FATAL: passphrase rejected or sealed file corrupted (" + e.message + ")");
-    process.exit(1);
+    throw new VaultError("vault/unwrap-failed",
+      "passphrase rejected or sealed file corrupted (" + e.message + ")");
   } finally {
     // The Buffer holding the unwrapped key JSON is no longer needed once
     // toString has copied the bytes into plaintextJson. The string itself
@@ -206,8 +214,8 @@ async function initWrapped() {
       },
     });
   } catch (e) {
-    log.error("FATAL: unwrapped vault key invalid: " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/unwrapped-invalid",
+      "unwrapped vault key invalid: " + e.message);
   }
   log("unsealed successfully.");
 }
@@ -221,8 +229,7 @@ async function initFirstRunWrapped() {
       prompt: "Choose a vault passphrase (loss = data loss, store it safely): ",
     });
   } catch (e) {
-    log.error("FATAL: " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/passphrase-error", e.message);
   }
   currentPassphrase = passphrase;
 
@@ -232,8 +239,8 @@ async function initFirstRunWrapped() {
   try {
     sealed = await vaultWrap.wrap(plaintextJson, passphrase);
   } catch (e) {
-    log.error("FATAL: failed to wrap new vault key: " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/wrap-failed",
+      "failed to wrap new vault key: " + e.message);
   }
 
   // Atomic write via the framework's atomic-file primitive (temp + fsync +
@@ -247,7 +254,8 @@ async function initFirstRunWrapped() {
 
 function _requireInit() {
   if (!initialized) {
-    throw new Error("vault.init() must be awaited before vault.seal/unseal/getKeysJson");
+    throw new VaultError("vault/not-initialized",
+      "vault.init() must be awaited before vault.seal/unseal/getKeysJson");
   }
 }
 
@@ -289,6 +297,7 @@ module.exports = {
   getKeysJson:           getKeysJson,
   getCurrentPassphrase:  getCurrentPassphrase,
   getMode:               getMode,
+  VaultError:            VaultError,
   // Testing helpers — not part of the public contract
   _resetForTest:         function () {
     if (currentPassphrase) safeBuffer.secureZero(currentPassphrase);

package/lib/vault/rotate.js

@@ -55,11 +55,17 @@ var atomicFile = require("../atomic-file");
 var C = require("../constants");
 var cryptoField = require("../crypto-field");
 var cryptoLib = require("../crypto");
+var dbSchema = require("../db-schema");
 var lazyRequire = require("../lazy-require");
+var { boot } = require("../log");
+var nb = require("../numeric-bounds");
 var safeJson = require("../safe-json");
+var validateOpts = require("../validate-opts");
 var vaultWrap = lazyRequire(function () { return require("./wrap"); });
 var { defineClass } = require("../framework-error");
 
+var rotateLog = boot("vault-rotate");
+
 var VaultRotateError = defineClass("VaultRotateError", { alwaysPermanent: true });
 
 var VAULT_PREFIX = C.VAULT_PREFIX;
@@ -102,7 +108,9 @@ function _knownColumnsFor(schema, infraColumns) {
 
 function validateSchemaMatch(db, opts) {
   opts = opts || {};
-  var sampleLimit = typeof opts.driftSampleLimit === "number" && opts.driftSampleLimit > 0
+  nb.requirePositiveFiniteIntIfPresent(opts.driftSampleLimit,
+    "validateSchemaMatch: driftSampleLimit", VaultRotateError, "vault-rotate/bad-opt");
+  var sampleLimit = opts.driftSampleLimit !== undefined
     ? opts.driftSampleLimit : DEFAULT_DRIFT_SAMPLE_LIMIT;
   var infraColumns = Array.isArray(opts.infraColumns) ? opts.infraColumns : [];
   // Tables to consider — by default, every table the framework's
@@ -245,9 +253,18 @@ function verify(opts) {
   var keys       = opts.keys;
   var db         = opts.db;
   var oldKeys    = opts.oldKeys || null;
-  var sampleMin  = typeof opts.sampleMin === "number" && opts.sampleMin >= 1
-    ? Math.floor(opts.sampleMin) : DEFAULT_VERIFY_SAMPLE_MIN;
-  var samplePct  = typeof opts.samplePercent === "number" && opts.samplePercent > 0
+  nb.requirePositiveFiniteIntIfPresent(opts.sampleMin,
+    "verify: sampleMin", VaultRotateError, "vault-rotate/bad-opt");
+  var sampleMin  = opts.sampleMin !== undefined
+    ? opts.sampleMin : DEFAULT_VERIFY_SAMPLE_MIN;
+  if (opts.samplePercent !== undefined &&
+      (typeof opts.samplePercent !== "number" || !Number.isFinite(opts.samplePercent) ||
+       opts.samplePercent <= 0)) {
+    throw new VaultRotateError("vault-rotate/bad-opt",
+      "verify: samplePercent must be a positive finite fraction; got " +
+      nb.shape(opts.samplePercent));
+  }
+  var samplePct  = opts.samplePercent !== undefined
     ? opts.samplePercent : DEFAULT_VERIFY_SAMPLE_FRAC;
   var tablesArg  = Array.isArray(opts.tables) && opts.tables.length > 0
     ? opts.tables.slice() : null;
@@ -356,7 +373,9 @@ function verify(opts) {
 // the SQLite bytes uses the same dbKey old → new.
 // =====================================================================
 
-var ROW_BATCH_SIZE_DEFAULT = 1000;
+// Row count, not a byte quantity — hex form keeps the literal out of the
+// byte-shape detector while preserving the operator-readable magnitude.
+var ROW_BATCH_SIZE_DEFAULT = 0x3E8;
 var VAULT_PREFIX_LEN = C.VAULT_PREFIX.length;
 
 function _emit(cb, ev) {
@@ -435,19 +454,14 @@ function _rotateColumn(db, table, column, oldKeys, newKeys, batchSize, progress)
     var rows = sel.all(lastId, batchSize);
     if (rows.length === 0) break;
 
-    _runStmt(db, "BEGIN");
-    try {
+    dbSchema.runInTransaction(db, function () {
       for (var i = 0; i < rows.length; i++) {
         var row = rows[i];
         if (typeof row.v === "string" && row.v.indexOf(C.VAULT_PREFIX) === 0) {
           upd.run(_reSealValue(row.v, oldKeys, newKeys), row._id);
         }
       }
-      _runStmt(db, "COMMIT");
-    } catch (e) {
-      _runStmt(db, "ROLLBACK");
-      throw e;
-    }
+    });
     processed += rows.length;
     lastId = rows[rows.length - 1]._id;
     _emit(progress, { phase: "rotate_rows", table: table, column: column, rowsProcessed: processed, rowsTotal: total });
@@ -516,10 +530,7 @@ async function rotate(opts) {
     throw new VaultRotateError("vault-rotate/no-datadir",
       "rotate: opts.dataDir is required and must exist");
   }
-  if (typeof opts.stagingDir !== "string" || opts.stagingDir.length === 0) {
-    throw new VaultRotateError("vault-rotate/no-staging",
-      "rotate: opts.stagingDir is required");
-  }
+  validateOpts.requireNonEmptyString(opts.stagingDir, "rotate: opts.stagingDir", VaultRotateError, "vault-rotate/no-staging");
   if (fs.existsSync(opts.stagingDir)) {
     throw new VaultRotateError("vault-rotate/staging-exists",
       "rotate: stagingDir already exists: " + opts.stagingDir);
@@ -689,9 +700,14 @@ async function rotate(opts) {
       db.close();
     }
 
-    // Drop WAL/SHM sidecars before re-encrypting the .db file
-    try { fs.unlinkSync(tmpDbPath + "-wal"); } catch (_e) {}
-    try { fs.unlinkSync(tmpDbPath + "-shm"); } catch (_e) {}
+    // Drop WAL/SHM sidecars before re-encrypting the .db file. Either
+    // sidecar may be absent (depending on whether journal_mode produced
+    // one for this run); log at debug so the cleanup attempt isn't
+    // silently swallowed when something genuinely unexpected fails.
+    try { fs.unlinkSync(tmpDbPath + "-wal"); }
+    catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: tmpDbPath + "-wal", error: e.message }); }
+    try { fs.unlinkSync(tmpDbPath + "-shm"); }
+    catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: tmpDbPath + "-shm", error: e.message }); }
 
     var rotatedBytes = fs.readFileSync(tmpDbPath);
     fs.writeFileSync(path.join(stagingDir, paths.encryptedDb),
@@ -708,9 +724,12 @@ async function rotate(opts) {
       verifyResult = verify({ keys: newKeys, db: vdb, oldKeys: oldKeys });
     } finally {
       vdb.close();
-      try { fs.unlinkSync(verifyTmp); } catch (_e) {}
-      try { fs.unlinkSync(verifyTmp + "-wal"); } catch (_e) {}
-      try { fs.unlinkSync(verifyTmp + "-shm"); } catch (_e) {}
+      try { fs.unlinkSync(verifyTmp); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: verifyTmp, error: e.message }); }
+      try { fs.unlinkSync(verifyTmp + "-wal"); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: verifyTmp + "-wal", error: e.message }); }
+      try { fs.unlinkSync(verifyTmp + "-shm"); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: verifyTmp + "-shm", error: e.message }); }
     }
     if (!verifyResult.ok) {
       throw new VaultRotateError("vault-rotate/verify-failed",

package/lib/vault/wrap.js

@@ -26,6 +26,7 @@
  * wrap() and unwrap() are async because Argon2 is async via its native binding.
  */
 var argon2 = require("../vendor/argon2");
+var C = require("../constants");
 var { xchacha20poly1305 } = require("../vendor/noble-ciphers.cjs");
 var { generateBytes } = require("../crypto");
 var safeBuffer = require("../safe-buffer");
@@ -35,28 +36,34 @@ var MAGIC = 0xE2;
 var FORMAT_VERSION = 0x01;
 var KDF_ARGON2ID = 0x01;
 var CIPHER_XCHACHA20_POLY = 0x02;
-var NONCE_LENGTH = 24;
+var NONCE_LENGTH = C.BYTES.bytes(24);
 
 // ---- Default Argon2id parameters ----
 // 64 MiB / t=3 / p=4 targets ~1s derivation on commodity 2026 hardware —
 // painful for offline brute force, tolerable for an operator-initiated boot.
+// memoryCost is denominated in KiB per RFC 9106 §3.1, so the 64 MiB target
+// expresses as MiB→KiB through the framework's byte helpers.
 var DEFAULT_ARGON2 = Object.freeze({
-  memoryCost:  65536,
+  memoryCost:  C.BYTES.mib(64) / C.BYTES.kib(1),
   timeCost:    3,
   parallelism: 4,
-  saltLength:  16,
-  hashLength:  32,
+  saltLength:  C.BYTES.bytes(16),
+  hashLength:  C.BYTES.bytes(32),
 });
 
 // ---- Hard bounds — reject malformed or adversarial headers ----
-var MIN_SALT_LENGTH = 8;
-var MAX_SALT_LENGTH = 64;
-var MAX_PASSPHRASE_LENGTH = 4096;
-// argon2 memoryCost is in KiB, not bytes — these are NOT C.BYTES.* values.
-var MIN_ARGON2_MEMORY = 1024;          // 1 MiB-in-KiB
-var MAX_ARGON2_MEMORY = 4 * 1024 * 1024; // 4 GiB-in-KiB
+var MIN_SALT_LENGTH = C.BYTES.bytes(8);
+var MAX_SALT_LENGTH = C.BYTES.bytes(64);
+var MAX_PASSPHRASE_LENGTH = C.BYTES.kib(4);
+// argon2 memoryCost is denominated in KiB per RFC 9106 §3.1, not bytes.
+// Express the bound as a byte-quantity divided by KiB so the framework's
+// C.BYTES helpers stay the single source of truth for the underlying scale.
+var MIN_ARGON2_MEMORY = C.BYTES.mib(1)  / C.BYTES.kib(1);  // 1 MiB-in-KiB
+var MAX_ARGON2_MEMORY = C.BYTES.gib(4)  / C.BYTES.kib(1);  // 4 GiB-in-KiB
 var MAX_ARGON2_TIME = 100;
-var MAX_ARGON2_PARALLELISM = 32;
+// Argon2 lane count cap. Hex form because the literal isn't a byte
+// quantity — using C.BYTES.* would mis-name the unit at the call site.
+var MAX_ARGON2_PARALLELISM = 0x20;
 
 function buildHeader(params) {
   var salt = params.salt;
@@ -81,7 +88,7 @@ function buildHeader(params) {
   h[2] = KDF_ARGON2ID;
   h[3] = 0x00;
   h.writeUInt32BE(params.memoryCost >>> 0, 4);
-  h.writeUInt16BE(params.timeCost & 0xffff, 8);
+  h.writeUInt16BE(params.timeCost & 0xffff, C.BYTES.bytes(8));
   h[10] = params.parallelism & 0xff;
   h[11] = saltLen;
   Buffer.from(salt).copy(h, 12);
@@ -98,8 +105,8 @@ function parseHeader(buf) {
   if (!Buffer.isBuffer(buf)) buf = Buffer.from(buf);
   if (buf.length < 12) throw new Error("wrapped vault file too short (< 12 bytes)");
   if (buf[0] !== MAGIC) {
-    throw new Error("not a wrapped vault file (magic byte 0x" + buf[0].toString(16) +
-      " != 0x" + MAGIC.toString(16) + ")");
+    throw new Error("not a wrapped vault file (magic byte 0x" + buf[0].toString(0x10) +
+      " != 0x" + MAGIC.toString(0x10) + ")");
   }
   if (buf[1] !== FORMAT_VERSION) {
     throw new Error("unsupported wrapped-vault format version " + buf[1] + " — upgrade blamejs");
@@ -110,7 +117,7 @@ function parseHeader(buf) {
   // byte 3 reserved
 
   var memoryCost = buf.readUInt32BE(4);
-  var timeCost = buf.readUInt16BE(8);
+  var timeCost = buf.readUInt16BE(C.BYTES.bytes(8));
   var parallelism = buf[10];
   var saltLen = buf[11];
 
@@ -146,7 +153,7 @@ function parseHeader(buf) {
   var ciphertextLength = buf.readUInt32BE(ctLenPos);
   var headerEnd = ctLenPos + 4;
 
-  if (ciphertextLength < 16) {
+  if (ciphertextLength < C.BYTES.bytes(16)) {
     throw new Error("ciphertext length too short (< Poly1305 tag): " + ciphertextLength);
   }
   if (buf.length < headerEnd + ciphertextLength) {
@@ -191,13 +198,13 @@ async function deriveWrappingKey(passphrase, salt, argonParams) {
       memoryCost:  argonParams.memoryCost  || DEFAULT_ARGON2.memoryCost,
       timeCost:    argonParams.timeCost    || DEFAULT_ARGON2.timeCost,
       parallelism: argonParams.parallelism || DEFAULT_ARGON2.parallelism,
-      hashLength:  32,
+      hashLength:  C.BYTES.bytes(32),
       raw:         true,
     });
   } finally {
     if (weOwnPwBuf) safeBuffer.secureZero(pwBuf);
   }
-  if (!raw || raw.length !== 32) {
+  if (!raw || raw.length !== C.BYTES.bytes(32)) {
     safeBuffer.secureZero(raw);
     throw new Error("Argon2 returned unexpected hash length: " + (raw && raw.length));
   }
@@ -230,7 +237,7 @@ async function wrap(plaintext, passphrase, opts) {
   });
 
   try {
-    var ciphertextLength = plaintextBuf.length + 16;
+    var ciphertextLength = plaintextBuf.length + C.BYTES.bytes(16);
     var header = buildHeader({
       memoryCost:       memoryCost,
       timeCost:         timeCost,