@blamejs/core 0.8.40 → 0.8.42

package/lib/resource-access-lock.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * b.resourceAccessLock — three-mode access-lock for arbitrary
+ * resources (data exports, scheduled jobs, file paths, queue
+ * partitions). Different from b.auth.accessLock — that one gates
+ * HTTP request flow; this one gates non-HTTP-shaped operator
+ * actions. Both share the open / read-only / locked vocabulary.
+ *
+ *   var exportLock = b.resourceAccessLock.create({
+ *     resource:     "data-export-jobs",
+ *     startMode:    "open",
+ *     audit:        b.audit,
+ *   });
+ *
+ *   if (!exportLock.permits("write")) {
+ *     throw new b.resourceAccessLock.ResourceAccessLockError(
+ *       "resource-access-lock/refused",
+ *       "data export refused: lock mode is " + exportLock.mode());
+ *   }
+ *   await runExportJob();
+ *
+ *   exportLock.set("locked", { actor: "alice", reason: "incident-42 freeze" });
+ *
+ * Mode semantics:
+ *   open       — every action permitted
+ *   read-only  — actions tagged "read" permitted; "write" refused
+ *   locked     — every action refused
+ *
+ * Audit shape:
+ *   resourceaccesslock.mode_changed — {resource, from, to, actor, reason}
+ *   resourceaccesslock.refused      — {resource, action, mode, actor}
+ */
+
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var ResourceAccessLockError = defineClass("ResourceAccessLockError",
+  { alwaysPermanent: true });
+
+var VALID_MODES = Object.freeze({ open: 1, "read-only": 1, locked: 1 });
+var READ_ACTIONS = Object.freeze({ read: 1, list: 1, get: 1, query: 1, "read-only": 1 });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["resource", "startMode", "audit"], "resourceAccessLock.create");
+  validateOpts.requireNonEmptyString(opts.resource, "resource",
+    ResourceAccessLockError, "resource-access-lock/no-resource");
+  var startMode = opts.startMode || "open";
+  if (!VALID_MODES[startMode]) {
+    throw new ResourceAccessLockError(
+      "resource-access-lock/bad-start-mode",
+      "startMode must be one of: " + Object.keys(VALID_MODES).join(" / "));
+  }
+  var auditOn = opts.audit !== false;
+  var resource = opts.resource;
+  var mode = startMode;
+
+  function _emit(action, outcome, meta) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action: action, outcome: outcome,
+        metadata: Object.assign({ resource: resource }, meta || {}),
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+
+  function permits(action) {
+    if (mode === "open") return true;
+    if (mode === "locked") return false;
+    return !!READ_ACTIONS[action];
+  }
+
+  function set(newMode, ctx) {
+    ctx = ctx || {};
+    if (!VALID_MODES[newMode]) {
+      throw new ResourceAccessLockError(
+        "resource-access-lock/bad-mode",
+        "set: mode must be one of: " + Object.keys(VALID_MODES).join(" / "));
+    }
+    var prev = mode;
+    mode = newMode;
+    _emit("resourceaccesslock.mode_changed", "success", {
+      from: prev, to: newMode,
+      actor: ctx.actor || null, reason: ctx.reason || null,
+    });
+  }
+
+  function assertPermits(action, ctx) {
+    if (permits(action)) return;
+    _emit("resourceaccesslock.refused", "failure", {
+      action: action, mode: mode,
+      actor: (ctx && ctx.actor) || null,
+    });
+    throw new ResourceAccessLockError(
+      "resource-access-lock/refused",
+      resource + " refuses '" + action + "': lock mode is '" + mode + "'");
+  }
+
+  return {
+    resource:      resource,
+    mode:          function () { return mode; },
+    set:           set,
+    permits:       permits,
+    assertPermits: assertPermits,
+  };
+}
+
+module.exports = {
+  create:                   create,
+  VALID_MODES:              Object.freeze(Object.keys(VALID_MODES)),
+  ResourceAccessLockError:  ResourceAccessLockError,
+};

package/lib/vault/index.js

@@ -66,12 +66,49 @@ var log = boot("vault");
 
 function resolvePaths(dataDir) {
   return {
-    dataDir:    dataDir,
-    plaintext:  path.join(dataDir, "vault.key"),
-    sealed:     path.join(dataDir, "vault.key.sealed"),
+    dataDir:           dataDir,
+    plaintext:         path.join(dataDir, "vault.key"),
+    sealed:            path.join(dataDir, "vault.key.sealed"),
+    derivedHashSalt:   path.join(dataDir, "vault.derived-hash-salt"),
   };
 }
 
+// derivedHashSalt — per-deployment salt for crypto-field
+// derivedHashes (D-H1). Pre-v0.8.42 the deterministic
+// sha3(namespace + plaintext) shape allowed cross-deployment
+// rainbow + cross-table correlation; binding a 32-byte
+// per-deployment salt closes that class without breaking
+// indexed-lookup determinism inside one deployment. The salt
+// persists across vault rotations (different file from vault.key)
+// so existing derivedHash columns survive a passphrase change.
+function _readOrCreateDerivedHashSalt() {
+  if (!paths) {
+    throw new VaultError("vault/not-initialized",
+      "vault.derivedHashSalt() requires init()");
+  }
+  if (fs.existsSync(paths.derivedHashSalt)) {
+    var raw = atomicFile.readSync(paths.derivedHashSalt);
+    if (raw.length !== 32) {                                                       // allow:raw-byte-literal — 32-byte (256-bit) salt
+      throw new VaultError("vault/derived-hash-salt-corrupted",
+        "vault.derived-hash-salt must be exactly 32 bytes; got " + raw.length);
+    }
+    return raw;
+  }
+  var nodeCrypto = require("node:crypto");
+  var salt = nodeCrypto.randomBytes(32);                                           // allow:raw-byte-literal — 32-byte salt
+  atomicFile.writeSync(paths.derivedHashSalt, salt, { fileMode: 0o600 });
+  log("generated per-deployment derivedHash salt at " + paths.derivedHashSalt);
+  return salt;
+}
+
+var _cachedDerivedHashSalt = null;
+function getDerivedHashSalt() {
+  if (_cachedDerivedHashSalt === null) {
+    _cachedDerivedHashSalt = _readOrCreateDerivedHashSalt();
+  }
+  return _cachedDerivedHashSalt;
+}
+
 // ---- Init dispatch ----
 
 async function init(opts) {
@@ -294,10 +331,34 @@ var vaultAad = require("../vault-aad");
 
 var sealPemFileModule = require("./seal-pem-file");
 
+// _zeroizeAndReplace — best-effort secureZero of prior in-memory keys
+// before a swap. V8 strings can't be reliably overwritten (string
+// interning + GC managed), so the pre-swap pass converts each PEM
+// string to a Buffer, secureZeros the Buffer, and rebinds the
+// property to "ZEROED" before the new keys land. The string copy
+// inside V8 may still linger until GC; this just removes the
+// largest-window heap copy (the ones held by `keys`).
+function _zeroizeAndReplace(replacement) {
+  if (!keys) { keys = replacement; return; }
+  Object.keys(keys).forEach(function (k) {
+    var v = keys[k];
+    if (typeof v === "string" && v.length > 0) {
+      try {
+        var buf = Buffer.from(v, "utf8");
+        safeBuffer.secureZero(buf);
+      } catch (_e) { /* best-effort */ }
+      keys[k] = "ZEROED";
+    }
+  });
+  keys = replacement;
+}
+
 module.exports = {
   init:                  init,
   seal:                  seal,
   unseal:                unseal,
+  getDerivedHashSalt:    getDerivedHashSalt,
+  _zeroizeAndReplace:    _zeroizeAndReplace,
   aad:                   vaultAad,
   getKeysJson:           getKeysJson,
   getCurrentPassphrase:  getCurrentPassphrase,

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

@@ -76,7 +76,12 @@ 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.
-var DEFAULT_POLL_MS = C.TIME.seconds(2);
+// H6 #6 — fs.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
+// 500ms polling on an idle PEM file is ~2 stat() syscalls/sec.
+var DEFAULT_POLL_MS = 500;                                                         // allow:raw-time-literal — 500ms watchFile cadence (sub-second)
 
 // PEM files are tiny — 4 KiB for an ECDSA key, ~8 KiB for a 4096-bit
 // RSA key, ~64 KiB for a long cert chain. Cap at 1 MiB so an operator
@@ -148,7 +153,28 @@ 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";
-    atomicFile.ensureDir(path.dirname(destination));
+    var destDir    = path.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
+    // .rewriting marker between our writeFileSync and the atomic
+    // rename. Refuse on group-/other-writable parent dirs (POSIX
+    // mode bits 0o022). On Windows the stat mode is synthetic;
+    // skip the check there.
+    if (process.platform !== "win32") {
+      try {
+        var dirStat = fs.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 " +
+            "(mode " + (dirStat.mode & 0o777).toString(8) +                       // allow:raw-byte-literal — POSIX mode mask
+            ") — refuse to seal; chmod 0700 the dir");
+        }
+      } catch (e) {
+        if (e && e.code === "seal-pem-file/parent-dir-writable") throw e;
+        // stat itself failing is not fatal — the writeFileSync below will surface it.
+      }
+    }
     var sealed = vault().seal(plaintextBytes);
     fs.writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });   // allow:raw-byte-literal — POSIX file mode
     try {
@@ -158,6 +184,16 @@ function sealPemFile(opts) {
       throw e;
     }
     try { fs.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); }
+    } catch (_e) { /* dir fsync best-effort — Windows / non-POSIX may refuse */ }
   }
 
   function _resealNow(actor) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.40",
+  "version": "0.8.42",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:7c951f5a-156e-49be-91c0-8a5a420faf2c",
+  "serialNumber": "urn:uuid:6b316a2e-756a-4aa8-90a8-b6c414dbdc39",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T16:35:12.500Z",
+    "timestamp": "2026-05-07T17:47:29.804Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.40",
+      "bom-ref": "@blamejs/core@0.8.42",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.40",
+      "version": "0.8.42",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.40",
+      "purl": "pkg:npm/%40blamejs/core@0.8.42",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.40",
+      "ref": "@blamejs/core@0.8.42",
       "dependsOn": []
     }
   ]