@blamejs/core 0.9.14 → 0.9.15

package/lib/vault/rotate.js

@@ -48,18 +48,18 @@
  * sampler skips them.
  */
 
-var fs = require("fs");
-var path = require("path");
+var nodeFs = require("fs");
+var nodePath = require("path");
 var { DatabaseSync } = require("node:sqlite");
 var atomicFile = require("../atomic-file");
 var safeSql = require("../safe-sql");
 var C = require("../constants");
 var cryptoField = require("../crypto-field");
-var cryptoLib = require("../crypto");
+var bCrypto = require("../crypto");
 var dbSchema = require("../db-schema");
 var lazyRequire = require("../lazy-require");
 var { boot } = require("../log");
-var nb = require("../numeric-bounds");
+var numericBounds = require("../numeric-bounds");
 var safeJson = require("../safe-json");
 var validateOpts = require("../validate-opts");
 var vaultWrap = lazyRequire(function () { return require("./wrap"); });
@@ -109,7 +109,7 @@ function _knownColumnsFor(schema, infraColumns) {
 
 function validateSchemaMatch(db, opts) {
   opts = opts || {};
-  nb.requirePositiveFiniteIntIfPresent(opts.driftSampleLimit,
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.driftSampleLimit,
     "validateSchemaMatch: driftSampleLimit", VaultRotateError, "vault-rotate/bad-opt");
   var sampleLimit = opts.driftSampleLimit !== undefined
     ? opts.driftSampleLimit : DEFAULT_DRIFT_SAMPLE_LIMIT;
@@ -254,7 +254,7 @@ function verify(opts) {
   var keys       = opts.keys;
   var db         = opts.db;
   var oldKeys    = opts.oldKeys || null;
-  nb.requirePositiveFiniteIntIfPresent(opts.sampleMin,
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.sampleMin,
     "verify: sampleMin", VaultRotateError, "vault-rotate/bad-opt");
   var sampleMin  = opts.sampleMin !== undefined
     ? opts.sampleMin : DEFAULT_VERIFY_SAMPLE_MIN;
@@ -263,7 +263,7 @@ function verify(opts) {
        opts.samplePercent <= 0)) {
     throw new VaultRotateError("vault-rotate/bad-opt",
       "verify: samplePercent must be a positive finite fraction; got " +
-      nb.shape(opts.samplePercent));
+      numericBounds.shape(opts.samplePercent));
   }
   var samplePct  = opts.samplePercent !== undefined
     ? opts.samplePercent : DEFAULT_VERIFY_SAMPLE_FRAC;
@@ -311,7 +311,7 @@ function verify(opts) {
         if (typeof v !== "string" || v.indexOf(VAULT_PREFIX) !== 0) continue;
         var payload = v.substring(VAULT_PREFIX.length);
 
-        try { cryptoLib.decrypt(payload, keys); }
+        try { bCrypto.decrypt(payload, keys); }
         catch (e) {
           rowFailed = true;
           failures.push({
@@ -324,7 +324,7 @@ function verify(opts) {
 
         if (oldKeys && !foundOldFail) {
           try {
-            cryptoLib.decrypt(payload, oldKeys);
+            bCrypto.decrypt(payload, oldKeys);
             regressions.push({
               table:  table,
               column: col,
@@ -391,8 +391,8 @@ function _emit(cb, ev) {
 // the original write fd around.
 function _fsyncFileByPath(p) {
   try {
-    var fd = fs.openSync(p, "r+");
-    try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    var fd = nodeFs.openSync(p, "r+");
+    try { nodeFs.fsyncSync(fd); } finally { nodeFs.closeSync(fd); }
   } catch (_e) { /* best-effort across platforms */ }
 }
 
@@ -400,8 +400,8 @@ function _reSealValue(sealedValue, oldKeys, newKeys) {
   if (typeof sealedValue !== "string") return sealedValue;
   if (sealedValue.indexOf(C.VAULT_PREFIX) !== 0) return sealedValue;
   var payload = sealedValue.substring(VAULT_PREFIX_LEN);
-  var plain = cryptoLib.decrypt(payload, oldKeys);
-  return C.VAULT_PREFIX + cryptoLib.encrypt(plain, newKeys);
+  var plain = bCrypto.decrypt(payload, oldKeys);
+  return C.VAULT_PREFIX + bCrypto.encrypt(plain, newKeys);
 }
 
 // Walk a JSON-decoded value, re-sealing every vault-prefixed string.
@@ -530,12 +530,12 @@ async function rotate(opts) {
     throw new VaultRotateError("vault-rotate/no-keys",
       "rotate: opts.oldKeys and opts.newKeys are required");
   }
-  if (typeof opts.dataDir !== "string" || !fs.existsSync(opts.dataDir)) {
+  if (typeof opts.dataDir !== "string" || !nodeFs.existsSync(opts.dataDir)) {
     throw new VaultRotateError("vault-rotate/no-datadir",
       "rotate: opts.dataDir is required and must exist");
   }
   validateOpts.requireNonEmptyString(opts.stagingDir, "rotate: opts.stagingDir", VaultRotateError, "vault-rotate/no-staging");
-  if (fs.existsSync(opts.stagingDir)) {
+  if (nodeFs.existsSync(opts.stagingDir)) {
     throw new VaultRotateError("vault-rotate/staging-exists",
       "rotate: stagingDir already exists: " + opts.stagingDir);
   }
@@ -571,30 +571,30 @@ async function rotate(opts) {
   _emit(progress, { phase: "copy_verbatim" });
   for (var vf = 0; vf < paths.verbatimFiles.length; vf++) {
     var entry = paths.verbatimFiles[vf];
-    var src = path.join(dataDir, entry.relativePath);
-    if (!fs.existsSync(src)) {
+    var src = nodePath.join(dataDir, entry.relativePath);
+    if (!nodeFs.existsSync(src)) {
       if (entry.required) {
         throw new VaultRotateError("vault-rotate/missing-verbatim",
           "rotate: required verbatim file missing: " + entry.relativePath);
       }
       continue;
     }
-    var dest = path.join(stagingDir, entry.relativePath);
-    atomicFile.ensureDir(path.dirname(dest));
-    fs.copyFileSync(src, dest);
+    var dest = nodePath.join(stagingDir, entry.relativePath);
+    atomicFile.ensureDir(nodePath.dirname(dest));
+    nodeFs.copyFileSync(src, dest);
   }
   for (var vd = 0; vd < paths.verbatimDirs.length; vd++) {
     var dent = paths.verbatimDirs[vd];
-    var sdir = path.join(dataDir, dent.relativePath);
-    if (!fs.existsSync(sdir)) {
+    var sdir = nodePath.join(dataDir, dent.relativePath);
+    if (!nodeFs.existsSync(sdir)) {
       if (dent.required) {
         throw new VaultRotateError("vault-rotate/missing-verbatim-dir",
           "rotate: required verbatim dir missing: " + dent.relativePath);
       }
       continue;
     }
-    if (fs.existsSync(sdir)) {
-      atomicFile.copyDirRecursive(sdir, path.join(stagingDir, dent.relativePath));
+    if (nodeFs.existsSync(sdir)) {
+      atomicFile.copyDirRecursive(sdir, nodePath.join(stagingDir, dent.relativePath));
     }
   }
 
@@ -603,59 +603,59 @@ async function rotate(opts) {
   var keysJson = JSON.stringify(newKeys, null, 2);
   if (mode === "wrapped") {
     var sealed = await vaultWrap().wrap(keysJson, opts.newPassphrase);
-    fs.writeFileSync(path.join(stagingDir, paths.vaultKeySealed), sealed, { mode: 0o600 });
+    nodeFs.writeFileSync(nodePath.join(stagingDir, paths.vaultKeySealed), sealed, { mode: 0o600 });
   } else {
-    fs.writeFileSync(path.join(stagingDir, paths.vaultKeyPlain), keysJson, { mode: 0o600 });
+    nodeFs.writeFileSync(nodePath.join(stagingDir, paths.vaultKeyPlain), keysJson, { mode: 0o600 });
   }
 
   // 3. re-seal db.key.enc + any operator-supplied additionalSealed files
   _emit(progress, { phase: "reseal_files" });
-  var dbKeySealedPath = path.join(dataDir, paths.dbKeySealed);
+  var dbKeySealedPath = nodePath.join(dataDir, paths.dbKeySealed);
   var dbKey = null;
-  if (fs.existsSync(dbKeySealedPath)) {
-    var sealedKey = fs.readFileSync(dbKeySealedPath, "utf8").trim();
+  if (nodeFs.existsSync(dbKeySealedPath)) {
+    var sealedKey = nodeFs.readFileSync(dbKeySealedPath, "utf8").trim();
     if (sealedKey.indexOf(C.VAULT_PREFIX) !== 0) {
       throw new VaultRotateError("vault-rotate/bad-dbkey",
         "rotate: db.key.enc does not start with the vault prefix");
     }
-    var dbKeyB64 = cryptoLib.decrypt(sealedKey.substring(VAULT_PREFIX_LEN), oldKeys);
+    var dbKeyB64 = bCrypto.decrypt(sealedKey.substring(VAULT_PREFIX_LEN), oldKeys);
     dbKey = Buffer.from(dbKeyB64, "base64");
-    var resealedKey = C.VAULT_PREFIX + cryptoLib.encrypt(dbKeyB64, newKeys);
-    fs.writeFileSync(path.join(stagingDir, paths.dbKeySealed), resealedKey, { mode: 0o600 });
+    var resealedKey = C.VAULT_PREFIX + bCrypto.encrypt(dbKeyB64, newKeys);
+    nodeFs.writeFileSync(nodePath.join(stagingDir, paths.dbKeySealed), resealedKey, { mode: 0o600 });
   }
   for (var as = 0; as < paths.additionalSealed.length; as++) {
     var ase = paths.additionalSealed[as];
-    var asSrc = path.join(dataDir, ase.relativePath);
-    if (!fs.existsSync(asSrc)) {
+    var asSrc = nodePath.join(dataDir, ase.relativePath);
+    if (!nodeFs.existsSync(asSrc)) {
       if (ase.required) {
         throw new VaultRotateError("vault-rotate/missing-sealed",
           "rotate: required sealed file missing: " + ase.relativePath);
       }
       continue;
     }
-    var current = fs.readFileSync(asSrc, "utf8").trim();
+    var current = nodeFs.readFileSync(asSrc, "utf8").trim();
     if (current.indexOf(C.VAULT_PREFIX) !== 0) {
       throw new VaultRotateError("vault-rotate/bad-sealed",
         "rotate: sealed file does not start with the vault prefix: " + ase.relativePath);
     }
-    var asDestDir = path.join(stagingDir, path.dirname(ase.relativePath));
-    if (!fs.existsSync(asDestDir)) atomicFile.ensureDir(asDestDir);
-    fs.writeFileSync(path.join(stagingDir, ase.relativePath),
+    var asDestDir = nodePath.join(stagingDir, nodePath.dirname(ase.relativePath));
+    if (!nodeFs.existsSync(asDestDir)) atomicFile.ensureDir(asDestDir);
+    nodeFs.writeFileSync(nodePath.join(stagingDir, ase.relativePath),
       _reSealValue(current, oldKeys, newKeys), { mode: 0o600 });
   }
 
   // 4. decrypt + rotate + re-encrypt db.enc
   _emit(progress, { phase: "rotate_db" });
-  var encDbPath = path.join(dataDir, paths.encryptedDb);
+  var encDbPath = nodePath.join(dataDir, paths.encryptedDb);
   var tablesProcessed = 0;
   var totalRowsProcessed = 0;
   var verifyResult = null;
 
-  if (fs.existsSync(encDbPath) && dbKey) {
-    var packed = fs.readFileSync(encDbPath);
-    var plainBytes = cryptoLib.decryptPacked(packed, dbKey);
-    var tmpDbPath = path.join(stagingDir, "_blamejs_rotate.tmp.db");
-    fs.writeFileSync(tmpDbPath, plainBytes, { mode: 0o600 });
+  if (nodeFs.existsSync(encDbPath) && dbKey) {
+    var packed = nodeFs.readFileSync(encDbPath);
+    var plainBytes = bCrypto.decryptPacked(packed, dbKey);
+    var tmpDbPath = nodePath.join(stagingDir, "_blamejs_rotate.tmp.db");
+    nodeFs.writeFileSync(tmpDbPath, plainBytes, { mode: 0o600 });
 
     var db = new DatabaseSync(tmpDbPath);
     try {
@@ -708,32 +708,32 @@ async function rotate(opts) {
     // 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 }); }
+    try { nodeFs.unlinkSync(tmpDbPath + "-wal"); }
+    catch (e) { rotateLog.debug("cleanup-failed", { op: "nodeFs.unlinkSync", path: tmpDbPath + "-wal", error: e.message }); }
+    try { nodeFs.unlinkSync(tmpDbPath + "-shm"); }
+    catch (e) { rotateLog.debug("cleanup-failed", { op: "nodeFs.unlinkSync", path: tmpDbPath + "-shm", error: e.message }); }
 
-    var rotatedBytes = fs.readFileSync(tmpDbPath);
-    fs.writeFileSync(path.join(stagingDir, paths.encryptedDb),
-      cryptoLib.encryptPacked(rotatedBytes, dbKey));
-    fs.unlinkSync(tmpDbPath);
+    var rotatedBytes = nodeFs.readFileSync(tmpDbPath);
+    nodeFs.writeFileSync(nodePath.join(stagingDir, paths.encryptedDb),
+      bCrypto.encryptPacked(rotatedBytes, dbKey));
+    nodeFs.unlinkSync(tmpDbPath);
 
     // Round-trip verify on the staged DB
     _emit(progress, { phase: "verify" });
-    var verifyTmp = path.join(stagingDir, "_blamejs_verify.tmp.db");
-    fs.writeFileSync(verifyTmp,
-      cryptoLib.decryptPacked(fs.readFileSync(path.join(stagingDir, paths.encryptedDb)), dbKey));
+    var verifyTmp = nodePath.join(stagingDir, "_blamejs_verify.tmp.db");
+    nodeFs.writeFileSync(verifyTmp,
+      bCrypto.decryptPacked(nodeFs.readFileSync(nodePath.join(stagingDir, paths.encryptedDb)), dbKey));
     var vdb = new DatabaseSync(verifyTmp);
     try {
       verifyResult = verify({ keys: newKeys, db: vdb, oldKeys: oldKeys });
     } finally {
       vdb.close();
-      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 }); }
+      try { nodeFs.unlinkSync(verifyTmp); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "nodeFs.unlinkSync", path: verifyTmp, error: e.message }); }
+      try { nodeFs.unlinkSync(verifyTmp + "-wal"); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "nodeFs.unlinkSync", path: verifyTmp + "-wal", error: e.message }); }
+      try { nodeFs.unlinkSync(verifyTmp + "-shm"); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "nodeFs.unlinkSync", path: verifyTmp + "-shm", error: e.message }); }
     }
     if (!verifyResult.ok) {
       throw new VaultRotateError("vault-rotate/verify-failed",
@@ -747,10 +747,10 @@ async function rotate(opts) {
   // 5. fsync staging for durability before caller does the swap
   _emit(progress, { phase: "fsync" });
   function fsyncTree(dir) {
-    var entries = fs.readdirSync(dir);
+    var entries = nodeFs.readdirSync(dir);
     for (var i = 0; i < entries.length; i++) {
-      var p = path.join(dir, entries[i]);
-      var st = fs.statSync(p);
+      var p = nodePath.join(dir, entries[i]);
+      var st = nodeFs.statSync(p);
       if (st.isFile()) _fsyncFileByPath(p);
       else if (st.isDirectory()) fsyncTree(p);
     }

package/lib/vault/seal-pem-file.js

@@ -19,7 +19,7 @@
  *     source:       "/etc/letsencrypt/live/example.com/privkey.pem",
  *     destination:  "/var/lib/blamejs/server.key.sealed",
  *     audit:        true,                 // default
- *     pollInterval: b.constants.TIME.seconds(2),  // fs.watchFile cadence
+ *     pollInterval: b.constants.TIME.seconds(2),  // nodeFs.watchFile cadence
  *     onResealed:   function (info) { ... }, // { srcPath, destPath, bytes,
  *                                                resealedAt, generation }
  *     onError:      function (err)  { ... }, // sealing failed
@@ -42,10 +42,10 @@
  * (rename did not happen). The recovery routine re-runs the seal from
  * source — idempotent because the source PEM is the source of truth.
  *
- * fs.watchFile semantics:
+ * nodeFs.watchFile semantics:
  *
- * Node's fs.watchFile is a polling stat() loop with the configured
- * pollInterval. It fires on mtime / size change. fs.watch (the
+ * Node's nodeFs.watchFile is a polling stat() loop with the configured
+ * pollInterval. It fires on mtime / size change. nodeFs.watch (the
  * inotify / kqueue backend) is more efficient but inconsistent across
  * platforms — single rename events surface as multiple change events
  * on Linux (events fire on the directory entry, the file, and the
@@ -54,8 +54,8 @@
  * pollInterval) is acceptable for renewal cadences measured in days.
  */
 
-var fs = require("fs");
-var path = require("path");
+var nodeFs = require("fs");
+var nodePath = require("path");
 var atomicFile = require("../atomic-file");
 var C = require("../constants");
 var lazyRequire = require("../lazy-require");
@@ -76,7 +76,7 @@ var SealPemFileError = defineClass("SealPemFileError", { alwaysPermanent: true }
 // 2-second worst-case re-seal latency — negligible against the
 // renewal cadence. Operators with sub-second-sensitive use cases
 // override via opts.pollInterval.
-// H6 #6 — fs.watchFile default cadence reduced from 2s to 500ms so a
+// H6 #6 — nodeFs.watchFile default cadence reduced from 2s to 500ms so a
 // fast renewal-then-revert (mtime bump then second bump within ~2s)
 // doesn't sneak past the watcher. Operators with extremely-quiet
 // renewal cycles can override via opts.pollInterval; the cost of
@@ -126,7 +126,7 @@ var DEFAULT_MAX_SOURCE_BYTES = C.BYTES.mib(1);
  *     source:         string,    // plaintext PEM path (required)
  *     destination:    string,    // sealed-output path (required, must differ from source)
  *     audit:          boolean,   // emit b.audit events on every reseal (default true)
- *     pollInterval:   number,    // fs.watchFile cadence in ms (default 500)
+ *     pollInterval:   number,    // nodeFs.watchFile cadence in ms (default 500)
  *     onResealed:     function,  // (info) => void — { srcPath, destPath, bytes, resealedAt, generation }
  *     onError:        function,  // (err)  => void — sealing failed
  *     maxSourceBytes: number,    // refuse source larger than this (default 1 MiB)
@@ -219,7 +219,7 @@ function sealPemFile(opts) {
     // marker create and marker remove, the marker remains on disk
     // and _recoverIfNeeded() detects it on the next start().
     var markerPath = destination + ".rewriting";
-    var destDir    = path.dirname(destination);
+    var destDir    = nodePath.dirname(destination);
     atomicFile.ensureDir(destDir);
     // H6 #4 — assert parent-dir mode. If the directory is world-
     // writable, an attacker can swap the destination file or the
@@ -229,7 +229,7 @@ function sealPemFile(opts) {
     // skip the check there.
     if (process.platform !== "win32") {
       try {
-        var dirStat = fs.statSync(destDir);
+        var dirStat = nodeFs.statSync(destDir);
         if ((dirStat.mode & 0o022) !== 0) {                                       // allow:raw-byte-literal — POSIX mode mask
           throw new SealPemFileError("seal-pem-file/parent-dir-writable",
             "destination parent dir '" + destDir + "' is group/other-writable " +
@@ -242,23 +242,23 @@ function sealPemFile(opts) {
       }
     }
     var sealed = vault().seal(plaintextBytes);
-    fs.writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });   // allow:raw-byte-literal — POSIX file mode
+    nodeFs.writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });   // allow:raw-byte-literal — POSIX file mode
     try {
       atomicFile.writeSync(destination, sealed, { fileMode: 0o600 });    // allow:raw-byte-literal — POSIX file mode
     } catch (e) {
-      try { fs.unlinkSync(markerPath); } catch (_e) { /* best-effort */ }
+      try { nodeFs.unlinkSync(markerPath); } catch (_e) { /* best-effort */ }
       throw e;
     }
-    try { fs.unlinkSync(markerPath); } catch (_e) { /* marker cleanup best-effort */ }
+    try { nodeFs.unlinkSync(markerPath); } catch (_e) { /* marker cleanup best-effort */ }
     // H6 #5 — fsync the destination directory so the rename + marker
     // unlink survive a power loss. Crash + backup-snapshot edge case:
     // without dir-fsync, a journaled fs may have the new file inode
     // but not the directory entry update by the time the snapshot
     // reads.
     try {
-      var dirFd = fs.openSync(destDir, "r");
-      try { fs.fsyncSync(dirFd); }
-      finally { fs.closeSync(dirFd); }
+      var dirFd = nodeFs.openSync(destDir, "r");
+      try { nodeFs.fsyncSync(dirFd); }
+      finally { nodeFs.closeSync(dirFd); }
     } catch (_e) { /* dir fsync best-effort — Windows / non-POSIX may refuse */ }
   }
 
@@ -267,14 +267,14 @@ function sealPemFile(opts) {
     resealing = true;
     var plaintext = null;
     try {
-      // H6 #1 — bounded read. fs.readFileSync without a size cap on a
+      // H6 #1 — bounded read. nodeFs.readFileSync without a size cap on a
       // file the operator's renewal process writes is an OOM vector.
-      // H6 #3 — symlink TOCTOU defense. Open the file via fs.openSync
+      // H6 #3 — symlink TOCTOU defense. Open the file via nodeFs.openSync
       // with O_NOFOLLOW where possible; lstat first to verify the
       // source isn't a symlink we don't expect, then read via fd so
       // a swap-after-stat doesn't change which bytes we read.
       try {
-        var lstat = fs.lstatSync(source);
+        var lstat = nodeFs.lstatSync(source);
         if (lstat.isSymbolicLink()) {
           throw new SealPemFileError("seal-pem-file/symlink-refused",
             "source is a symlink (refused; follow + re-stat opens TOCTOU)");
@@ -283,9 +283,9 @@ function sealPemFile(opts) {
           throw new SealPemFileError("seal-pem-file/source-too-large",
             "source size " + lstat.size + " exceeds maxSourceBytes " + maxSourceBytes);
         }
-        var fd = fs.openSync(source, "r");
+        var fd = nodeFs.openSync(source, "r");
         try {
-          var fstat = fs.fstatSync(fd);
+          var fstat = nodeFs.fstatSync(fd);
           // H6 #3 — confirm the fd points at the same inode lstat saw.
           if (fstat.ino !== lstat.ino || fstat.size > maxSourceBytes) {
             throw new SealPemFileError("seal-pem-file/toctou-detected",
@@ -294,7 +294,7 @@ function sealPemFile(opts) {
           plaintext = Buffer.alloc(fstat.size);
           var read = 0;
           while (read < fstat.size) {
-            var n = fs.readSync(fd, plaintext, read, fstat.size - read, null);
+            var n = nodeFs.readSync(fd, plaintext, read, fstat.size - read, null);
             if (n === 0) break;
             read += n;
           }
@@ -303,7 +303,7 @@ function sealPemFile(opts) {
               "short read: " + read + " of " + fstat.size + " bytes");
           }
         } finally {
-          try { fs.closeSync(fd); } catch (_e) { /* close best-effort */ }
+          try { nodeFs.closeSync(fd); } catch (_e) { /* close best-effort */ }
         }
       }
       catch (e) {
@@ -390,7 +390,7 @@ function sealPemFile(opts) {
   // reseal was interrupted. Re-seal from source idempotently.
   function _recoverIfNeeded() {
     var markerPath = destination + ".rewriting";
-    if (fs.existsSync(markerPath)) {
+    if (nodeFs.existsSync(markerPath)) {
       log.info("vault.sealPemFile: recovery — marker '" + markerPath +
         "' present from prior crashed reseal; re-sealing from source");
       _emitAudit("recovery_started", "success", {
@@ -414,7 +414,7 @@ function sealPemFile(opts) {
         _resealNow();
       }
     };
-    fs.watchFile(source, { persistent: false, interval: pollInterval }, listener);
+    nodeFs.watchFile(source, { persistent: false, interval: pollInterval }, listener);
     watching = true;
     _emitAudit("watch_started", "success", {
       source:       source,
@@ -425,7 +425,7 @@ function sealPemFile(opts) {
 
   function stop() {
     if (!watching) return;
-    fs.unwatchFile(source, listener);
+    nodeFs.unwatchFile(source, listener);
     listener = null;
     watching = false;
     _emitAudit("watch_stopped", "success", {

package/lib/watcher.js

@@ -3,7 +3,7 @@
  * b.watcher — recursive filesystem-watch primitive with cross-platform
  * event normalization.
  *
- * Wraps `fs.watch(root, { recursive: true })` and turns the per-platform
+ * Wraps `nodeFs.watch(root, { recursive: true })` and turns the per-platform
  * event soup (Linux inotify "rename" + "change", macOS FSEvents
  * coalesced "rename", Windows ReadDirectoryChangesW pure "rename" /
  * "change") into a single shape:
@@ -15,7 +15,7 @@
  * `type` is one of "file" or "dir". The watcher is build-tool-shaped:
  * use it to drive incremental rebuilds, hot-reload-on-change,
  * config-file watching, or content-store cache busts. It is NOT a
- * security primitive — fs.watch is best-effort across kernels and the
+ * security primitive — nodeFs.watch is best-effort across kernels and the
  * caller must not rely on it for audit-grade change detection.
  *
  * Cross-platform notes baked in:
@@ -45,8 +45,8 @@
  *   watcher.WatcherError
  */
 
-var fs   = require("fs");
-var path = require("path");
+var nodeFs   = require("fs");
+var nodePath = require("path");
 var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 var { WatcherError } = require("./framework-error");
@@ -56,7 +56,7 @@ var observability = lazyRequire(function () { return require("./observability");
 
 var DEFAULT_DEBOUNCE_MS = 100;
 // Polling-mode defaults. The polling backend exists for environments
-// where fs.watch's native events don't reach userspace — most commonly
+// where nodeFs.watch's native events don't reach userspace — most commonly
 // Docker Desktop bind-mounts on Windows / macOS hosts (where the
 // inotify events from the Linux container's mount don't propagate
 // through the gRPC-FUSE / VirtioFS bridge to the host fs), or NFS /
@@ -166,8 +166,8 @@ function _compileIgnore(patterns) {
     }
   }
   return function (relPath) {
-    var base = path.basename(relPath);
-    var normalized = relPath.split(path.sep).join("/");
+    var base = nodePath.basename(relPath);
+    var normalized = relPath.split(nodePath.sep).join("/");
     for (var j = 0; j < compiled.length; j += 1) {
       var c = compiled[j];
       if (c.kind === "exact" && (c.value === relPath || c.value === normalized)) return true;
@@ -212,7 +212,7 @@ function _validateOpts(opts) {
 function create(opts) {
   _validateOpts(opts);
 
-  var root        = path.resolve(opts.root);
+  var root        = nodePath.resolve(opts.root);
   var debounceMs  = (opts.debounceMs !== undefined) ? opts.debounceMs : DEFAULT_DEBOUNCE_MS;
   var maxPending  = (opts.maxPending !== undefined) ? opts.maxPending : DEFAULT_MAX_PENDING;
   var mode        = opts.mode || "fs";
@@ -226,7 +226,7 @@ function create(opts) {
 
   // Pre-flight: root must exist and be a directory.
   var rootStat;
-  try { rootStat = fs.statSync(root); }
+  try { rootStat = nodeFs.statSync(root); }
   catch (e) {
     throw new WatcherError("watcher/root-missing",
       "watcher.create: root '" + root + "' is not accessible: " + ((e && e.message) || String(e)));
@@ -260,10 +260,10 @@ function create(opts) {
   function _normalizeAndDispatch(relPath) {
     if (stopped) return;
     if (isIgnored(relPath)) return;
-    var fullPath = path.join(root, relPath);
+    var fullPath = nodePath.join(root, relPath);
     // lstat (NOT stat) — refuses to follow symlinks out of root.
     var lst;
-    try { lst = fs.lstatSync(fullPath); }
+    try { lst = nodeFs.lstatSync(fullPath); }
     catch (e) {
       if (e && e.code === "ENOENT") {
         // Path is gone — delete event. Type unknown by the time we
@@ -335,9 +335,9 @@ function create(opts) {
     var stack = [""];
     while (stack.length > 0) {
       var relDir = stack.pop();
-      var absDir = relDir === "" ? root : path.join(root, relDir);
+      var absDir = relDir === "" ? root : nodePath.join(root, relDir);
       var entries;
-      try { entries = fs.readdirSync(absDir, { withFileTypes: true }); }
+      try { entries = nodeFs.readdirSync(absDir, { withFileTypes: true }); }
       catch (_e) {
         // Root vanished mid-walk OR an inner dir got deleted between
         // the parent listing and the descent. Skip — the next tick's
@@ -348,8 +348,8 @@ function create(opts) {
         var entry = entries[i];
         var relPath = relDir === "" ? entry.name : (relDir + "/" + entry.name);
         // Normalize to forward-slash so glob ignore-matching is
-        // consistent with the fs.watch path the operator's hooks see.
-        relPath = relPath.split(path.sep).join("/");
+        // consistent with the nodeFs.watch path the operator's hooks see.
+        relPath = relPath.split(nodePath.sep).join("/");
         if (isIgnored(relPath)) continue;
         if (entry.isSymbolicLink()) continue;            // never follow symlinks
         fileCount += 1;
@@ -358,9 +358,9 @@ function create(opts) {
             "watcher.poll: tree exceeds pollMaxFiles=" + pollMaxFiles +
             " — narrow `ignore` patterns OR raise pollMaxFiles, OR switch to mode: \"fs\"");
         }
-        var absPath = path.join(absDir, entry.name);
+        var absPath = nodePath.join(absDir, entry.name);
         var st;
-        try { st = fs.statSync(absPath); }
+        try { st = nodeFs.statSync(absPath); }
         catch (_e) { continue; }                          // race — entry vanished
         if (entry.isDirectory()) {
           snapshot.set(relPath, { type: "dir", size: 0, mtimeMs: st.mtimeMs });
@@ -382,13 +382,13 @@ function create(opts) {
     if (pollSnapshot === null) {
       // First tick — establish the baseline without firing events.
       // Operators get add events on file CREATION after start, not on
-      // pre-existing files (matches fs.watch semantics).
+      // pre-existing files (matches nodeFs.watch semantics).
       pollSnapshot = next;
       return;
     }
     // Diff: anything in `next` not in `pollSnapshot`, OR with size /
     // mtimeMs different, fires onChange via the same _enqueue path the
-    // fs.watch backend uses (so debounce + ignore + lstat dispatch
+    // nodeFs.watch backend uses (so debounce + ignore + lstat dispatch
     // stay uniform). Anything in `pollSnapshot` missing from `next`
     // fires onDelete (via _normalizeAndDispatch's ENOENT branch).
     next.forEach(function (info, relPath) {
@@ -416,12 +416,12 @@ function create(opts) {
     if (typeof pollTimer.unref === "function") pollTimer.unref();
   } else {
     try {
-      watcherHandle = fs.watch(root, { recursive: true, persistent: true }, function (eventType, filename) {
+      watcherHandle = nodeFs.watch(root, { recursive: true, persistent: true }, function (eventType, filename) {
         if (stopped) return;
         if (!filename) return;
         var rel = filename;
-        if (path.isAbsolute(rel) && rel.indexOf(root) === 0) {
-          rel = path.relative(root, rel);
+        if (nodePath.isAbsolute(rel) && rel.indexOf(root) === 0) {
+          rel = nodePath.relative(root, rel);
         }
         if (rel === "" || rel === ".") return;
         _enqueue(rel);
@@ -434,7 +434,7 @@ function create(opts) {
           ((e && e.message) || String(e)) + " — pass mode: \"poll\" to fall back to interval polling");
       }
       throw new WatcherError("watcher/start-failed",
-        "watcher.create: fs.watch failed: " + ((e && e.message) || String(e)));
+        "watcher.create: nodeFs.watch failed: " + ((e && e.message) || String(e)));
     }
   }