@blamejs/core 0.17.11 → 0.17.13

package/lib/redact.js

@@ -1055,8 +1055,62 @@ function installForPosture(posture, primitives) {
   });
 }
 
+var TEXT_REDACT_MARKER = "[redacted]";
+
+/**
+ * @primitive b.redact.redactText
+ * @signature b.redact.redactText(str)
+ * @since     0.17.13
+ * @status    stable
+ * @related   b.redact.redact
+ *
+ * Scrub credentials EMBEDDED in a free-text string in place, keeping the
+ * surrounding prose — for log messages and other operator-facing text where a
+ * secret may be interpolated mid-sentence. Unlike `redact` (structured,
+ * whole-value, anchored), this uses word-boundary fragment replacement so
+ * "login failed: <jwt> for bob" keeps everything but the jwt. Detects PEM
+ * blocks, JWTs, AWS access keys, URL-userinfo passwords, bearer tokens,
+ * `key=secret` assignments, SSN/EIN, and Luhn-valid PANs. The high-entropy
+ * api-key-shape detector is deliberately excluded (on free text it eats
+ * ordinary IDs / hashes / base64). Drop-safe: never throws (it runs on the
+ * hot-path log-emit sink); on any error it returns a fully-masked marker rather
+ * than the raw input. Every quantifier is length-capped (ReDoS backstop).
+ *
+ * @example
+ *   b.redact.redactText("token=AKIAIOSFODNN7EXAMPLE ok");  // → "token=[redacted] ok"
+ */
+function redactText(str) {
+  if (typeof str !== "string" || str.length === 0) return str;
+  try {
+    return str
+      // PEM / OpenSSH private-key blocks (multi-line).
+      .replace(/-----BEGIN [A-Z0-9 ]{1,40}-----[\s\S]{0,8192}?-----END [A-Z0-9 ]{1,40}-----/g, TEXT_REDACT_MARKER)
+      // JWT — three base64url segments, word-boundary anchored for embedding.
+      .replace(/\beyJ[A-Za-z0-9_-]{1,4096}\.[A-Za-z0-9_-]{1,8192}\.[A-Za-z0-9_-]{1,4096}\b/g, TEXT_REDACT_MARKER)
+      // AWS access-key IDs.
+      .replace(/\b(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASCA)[A-Z0-9]{16}\b/g, TEXT_REDACT_MARKER)
+      // Credentials in a URL userinfo: scheme://user:secret@host.
+      .replace(/([a-z][a-z0-9+.-]{0,32}:\/\/[^\s:@/]{1,256}:)[^\s@/]{1,256}(@)/gi, "$1" + TEXT_REDACT_MARKER + "$2")
+      // Bearer tokens.
+      .replace(/\b([Bb]earer\s{1,4})[A-Za-z0-9._~+/-]{8,4096}=*/g, "$1" + TEXT_REDACT_MARKER)
+      // key=secret / password: secret style assignments.
+      .replace(/\b((?:api[_-]?key|access[_-]?token|secret|password|passwd|pwd|token)\s{0,4}[=:]\s{0,4})[^\s&;"']{6,4096}/gi, "$1" + TEXT_REDACT_MARKER)
+      // SSN / EIN.
+      .replace(/\b\d{3}-\d{2}-\d{4}\b/g, TEXT_REDACT_MARKER)
+      .replace(/\b\d{2}-\d{7}\b/g, TEXT_REDACT_MARKER)
+      // Credit-card / PAN — Luhn-validated so ordinary long digit runs survive.
+      .replace(/\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{1,7}\b/g, function (m) {
+        var inner = m.replace(/[\s-]/g, "");
+        return (inner.length >= 13 && inner.length <= 19 && _luhnCheck(inner)) ? TEXT_REDACT_MARKER : m;
+      });
+  } catch (_e) {
+    return TEXT_REDACT_MARKER;
+  }
+}
+
 module.exports = {
   redact:                redact,
+  redactText:            redactText,
   registerFieldRule:     registerFieldRule,
   registerValueDetector: registerValueDetector,
   classifyDefaults:      classifyDefaults,

package/lib/safe-object.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     b.safeObject
+ * @nav        Validation
+ * @title      Safe object access
+ * @order      100
+ *
+ * @intro
+ *   Prototype-pollution-safe own-property access. Interpolators, template
+ *   engines, and structured readers that look up a key by name on an
+ *   attacker-influenced object must treat an inherited / prototype-chain key
+ *   (`__proto__`, `constructor`, `toString`) as ABSENT — never read it into
+ *   rendered output. This composes that guard into one primitive so every
+ *   consumer routes through the same hardened read instead of hand-rolling
+ *   `Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined` (which a
+ *   `__proto__` accessor property can still defeat).
+ *
+ * @card
+ *   Prototype-pollution-safe own-property get/set — the single guard every
+ *   interpolator composes.
+ */
+
+/**
+ * @primitive  b.safeObject.ownProp
+ * @signature  b.safeObject.ownProp(obj, key)
+ * @since      0.17.13
+ * @status     stable
+ * @related    b.safeObject.ownSet
+ *
+ * Returns the value of `obj`'s OWN property `key`, or `undefined` when `key`
+ * is not an own property (inherited / prototype-chain keys read as absent).
+ * Uses `Object.getOwnPropertyDescriptor` rather than `hasOwnProperty` + index
+ * read, so a `__proto__`-injected accessor property cannot run on read. A
+ * defined-but-`undefined` own value returns `undefined` (callers treat that as
+ * absent, matching the prior guarded reads).
+ *
+ * @example
+ *   b.safeObject.ownProp({ a: 1 }, "a");          // → 1
+ *   b.safeObject.ownProp({}, "toString");         // → undefined  (inherited)
+ *   b.safeObject.ownProp({}, "__proto__");        // → undefined
+ */
+function ownProp(obj, key) {
+  if (obj === null || obj === undefined) return undefined;
+  var d = Object.getOwnPropertyDescriptor(obj, key);
+  return d ? d.value : undefined;
+}
+
+/**
+ * @primitive  b.safeObject.ownSet
+ * @signature  b.safeObject.ownSet(obj, key, value)
+ * @since      0.17.13
+ * @status     stable
+ * @related    b.safeObject.ownProp
+ *
+ * Sets `obj[key] = value` as a plain own data property via
+ * `Object.defineProperty`, so a `__proto__` / `constructor` / accessor key on
+ * the prototype chain cannot intercept the write or pollute the prototype.
+ * Returns `obj`.
+ *
+ * @example
+ *   var o = {};
+ *   b.safeObject.ownSet(o, "__proto__", { polluted: 1 });
+ *   ({}).polluted;   // → undefined  (Object.prototype not touched)
+ */
+function ownSet(obj, key, value) {
+  Object.defineProperty(obj, key, {
+    value:        value,
+    writable:     true,
+    enumerable:   true,
+    configurable: true,
+  });
+  return obj;
+}
+
+module.exports = {
+  ownProp: ownProp,
+  ownSet:  ownSet,
+};

package/lib/self-update-standalone-verifier.js

@@ -88,6 +88,17 @@
 var nodeCrypto = require("node:crypto");
 var nodeFs     = require("node:fs");
 
+// _svErr — throw shape for this module. A plain Error (zero-dep — no framework
+// error class) carrying a machine-readable `.kind` so a framework caller
+// (b.selfUpdate.verify) can map the failure to its own typed error class
+// without parsing English message text. Operators consuming the module
+// standalone still get the human-readable `.message` unchanged.
+function _svErr(kind, message) {
+  var e = new Error(message);
+  e.kind = kind;
+  return e;
+}
+
 // _streamHashAndVerify — read the asset in 64 KiB chunks, feed each
 // chunk into sha256, sha3-512, AND the signature verifier in parallel.
 // Single pass over the file; no in-memory copy. node:crypto's
@@ -103,18 +114,18 @@ function _detectAlg(pubkeyPem) {
   try {
     key = nodeCrypto.createPublicKey(pubkeyPem);
   } catch (e) {
-    throw new Error("standalone-verifier: pubkey PEM did not parse: " +
+    throw _svErr("bad-pubkey", "standalone-verifier: pubkey PEM did not parse: " +
                     (e && e.message ? e.message : String(e)));
   }
   var t = key.asymmetricKeyType;
   if (t === "ec") {
     var curve = key.asymmetricKeyDetails && key.asymmetricKeyDetails.namedCurve;
     if (curve === "P-384" || curve === "secp384r1") return { alg: "ecdsa-p384", key: key };
-    throw new Error("standalone-verifier: unsupported EC curve '" + curve + "' (need P-384)");
+    throw _svErr("unsupported-key", "standalone-verifier: unsupported EC curve '" + curve + "' (need P-384)");
   }
   if (t === "ed25519") return { alg: "ed25519", key: key };
   if (t === "ml-dsa-87" || t === "ml-dsa") return { alg: "ml-dsa-87", key: key };
-  throw new Error("standalone-verifier: unrecognized pubkey type '" + t + "' " +
+  throw _svErr("unsupported-key", "standalone-verifier: unrecognized pubkey type '" + t + "' " +
                   "(need ecdsa-p384, ed25519, or ml-dsa-87)");
 }
 
@@ -163,7 +174,7 @@ function _looksLikeDerEcdsa(sig) {
 
 /**
  * @primitive b.selfUpdate.standaloneVerifier.verify
- * @signature b.selfUpdate.standaloneVerifier.verify(assetPath, signaturePath, pubkeyPem)
+ * @signature b.selfUpdate.standaloneVerifier.verify(assetPath, signaturePath, pubkeyPem, opts?)
  * @since     0.9.13
  * @status    stable
  * @related   b.selfUpdate.verify
@@ -175,12 +186,21 @@ function _looksLikeDerEcdsa(sig) {
  * Streams the asset in 64 KiB chunks through SHA-256 + SHA-3-512 + the
  * signature verifier in parallel — single allocation peak (one buffer
  * sized to fstat(asset).size for Ed25519 / ML-DSA-87, ECDSA P-384 needs
- * no buffer because createVerify is incremental).
+ * no buffer because createVerify is incremental). The signature commits
+ * to a SHA3-512 digest and the ECDSA encoding is dispatched by structure
+ * (DER SEQUENCE vs raw IEEE-P1363), so both encodings of a SHA3-512-signed
+ * P-384 sidecar verify.
  *
- * Returns `{ ok, sha3_512, sha256, alg }` on success; throws on
- * unrecognized pubkey shape, missing files, or signature mismatch.
- * `alg` is one of `"ecdsa-p384"`, `"ed25519"`, `"ml-dsa-87"` (auto-
- * detected from the pubkey PEM).
+ * Returns `{ ok, sha3_512, sha256, alg, bytes, digests }` on success;
+ * throws on unrecognized pubkey shape, missing files, or signature
+ * mismatch. `alg` is one of `"ecdsa-p384"`, `"ed25519"`, `"ml-dsa-87"`
+ * (auto-detected from the pubkey PEM). `bytes` is the verified asset byte
+ * count; `digests` maps each requested `opts.extraDigests` name to its
+ * hex digest (computed in the same single pass).
+ *
+ * @opts
+ *   maxAssetBytes: number,   // asset-size ceiling (default 2 GiB); refuse a larger asset before hashing
+ *   extraDigests:  array,    // additional node:crypto digest names to compute in the same stream
  *
  * @example
  *   var verifier = require("./standalone-verifier");
@@ -193,15 +213,26 @@ function _looksLikeDerEcdsa(sig) {
  *   if (!result.ok) process.exit(1);
  *   process.stdout.write("verified " + result.alg + " sha3-512=" + result.sha3_512 + "\n");
  */
-function verify(assetPath, signaturePath, pubkeyPem) {
+function verify(assetPath, signaturePath, pubkeyPem, opts) {
+  opts = opts || {};
+  // Asset-size ceiling — override the default via opts.maxAssetBytes (the
+  // framework caller passes its own maxBytes). A self-update bundle (SEA) is
+  // intentionally large, so the default ceiling is generous (2 GiB), but it
+  // stops a signaturePath/assetPath pointed at an unbounded file from OOM-ing.
+  var maxAssetBytes = (typeof opts.maxAssetBytes === "number" && isFinite(opts.maxAssetBytes) &&
+                       opts.maxAssetBytes > 0)
+    ? opts.maxAssetBytes
+    : (2 * 1024 * 1024 * 1024);   // allow:raw-byte-literal — zero-dep module, 2 GiB asset ceiling
+  var extraDigests = Array.isArray(opts.extraDigests) ? opts.extraDigests : [];
+
   if (typeof assetPath !== "string" || assetPath.length === 0) {
-    throw new Error("standalone-verifier.verify: assetPath must be a non-empty string");
+    throw _svErr("bad-input", "standalone-verifier.verify: assetPath must be a non-empty string");
   }
   if (typeof signaturePath !== "string" || signaturePath.length === 0) {
-    throw new Error("standalone-verifier.verify: signaturePath must be a non-empty string");
+    throw _svErr("bad-input", "standalone-verifier.verify: signaturePath must be a non-empty string");
   }
   if (typeof pubkeyPem !== "string" || pubkeyPem.indexOf("-----BEGIN ") !== 0) {
-    throw new Error("standalone-verifier.verify: pubkeyPem must be a PEM-encoded public key string");
+    throw _svErr("bad-input", "standalone-verifier.verify: pubkeyPem must be a PEM-encoded public key string");
   }
 
   // Open both files BEFORE parsing the pubkey so we own stable fds
@@ -212,7 +243,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
   try {
     assetFd = nodeFs.openSync(assetPath, "r");
   } catch (e) {
-    throw new Error("standalone-verifier.verify: asset not found at " + assetPath +
+    throw _svErr("asset-not-found", "standalone-verifier.verify: asset not found at " + assetPath +
                     " — " + (e && e.message ? e.message : String(e)));
   }
   var sigFd;
@@ -220,7 +251,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
     sigFd = nodeFs.openSync(signaturePath, "r");
   } catch (e) {
     nodeFs.closeSync(assetFd);
-    throw new Error("standalone-verifier.verify: signature not found at " + signaturePath +
+    throw _svErr("sig-not-found", "standalone-verifier.verify: signature not found at " + signaturePath +
                     " — " + (e && e.message ? e.message : String(e)));
   }
   var signature;
@@ -231,7 +262,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
     // from OOM-ing if signaturePath is pointed at a giant file. Zero-dep by
     // contract — inline literal, cannot import C.BYTES.
     if (sigStat.size > 64 * 1024) {   // allow:raw-byte-literal — zero-dep module
-      throw new Error("standalone-verifier.verify: signature file implausibly large (" +
+      throw _svErr("sig-too-large", "standalone-verifier.verify: signature file implausibly large (" +
                       sigStat.size + " bytes)");
     }
     signature = Buffer.allocUnsafe(sigStat.size);
@@ -241,7 +272,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
   }
   if (signature.length === 0) {
     nodeFs.closeSync(assetFd);
-    throw new Error("standalone-verifier.verify: signature file is empty");
+    throw _svErr("sig-empty", "standalone-verifier.verify: signature file is empty");
   }
 
   var detected;
@@ -249,7 +280,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
     detected = _detectAlg(pubkeyPem);
   } catch (e) {
     nodeFs.closeSync(assetFd);
-    throw e;
+    throw e;   // carries _detectAlg's .kind (bad-pubkey / unsupported-key)
   }
   var alg = detected.alg;
   var key = detected.key;
@@ -273,15 +304,24 @@ function verify(assetPath, signaturePath, pubkeyPem) {
   // time.
   var assetStat = nodeFs.fstatSync(assetFd);
   // Bound the asset alloc before Buffer.allocUnsafe(assetStat.size): a self-update
-  // bundle (SEA) is intentionally large, so the ceiling is generous (2 GiB), but
-  // it stops a signaturePath/assetPath pointed at an unbounded file from OOM-ing
-  // the verifier before any byte is hashed. Zero-dep by contract — inline literal.
-  if (assetStat.size > 2 * 1024 * 1024 * 1024) {   // allow:raw-byte-literal — zero-dep module, 2 GiB asset ceiling
-    throw new Error("standalone-verifier.verify: asset implausibly large (" +
-                    assetStat.size + " bytes) — exceeds the 2 GiB self-update ceiling");
+  // bundle (SEA) is intentionally large, so the ceiling is generous (2 GiB by
+  // default, or opts.maxAssetBytes), but it stops a signaturePath/assetPath
+  // pointed at an unbounded file from OOM-ing the verifier before any byte is
+  // hashed.
+  if (assetStat.size > maxAssetBytes) {
+    nodeFs.closeSync(assetFd);
+    throw _svErr("asset-too-large", "standalone-verifier.verify: asset implausibly large (" +
+                    assetStat.size + " bytes) — exceeds the " + maxAssetBytes + "-byte asset ceiling");
   }
   var sha256 = nodeCrypto.createHash("sha256");
   var sha3   = nodeCrypto.createHash("sha3-512");
+  // Additional operator-requested digests, computed in the same single pass so
+  // a framework caller can report an audit digest (sha-512 / shake256 / …)
+  // without a second read of the asset.
+  var extraHashers = [];
+  for (var xd = 0; xd < extraDigests.length; xd += 1) {
+    extraHashers.push({ name: extraDigests[xd], hash: nodeCrypto.createHash(extraDigests[xd]) });
+  }
   var verifier = (alg === "ecdsa-p384") ? nodeCrypto.createVerify("sha3-512") : null;
   var fullBuf  = null;
   var fullOff  = 0;
@@ -305,6 +345,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
       var slice = chunk.subarray(0, n);
       sha256.update(slice);
       sha3.update(slice);
+      for (var xh = 0; xh < extraHashers.length; xh += 1) extraHashers[xh].hash.update(slice);
       if (verifier) verifier.update(slice);
       if (fullBuf) {
         slice.copy(fullBuf, fullOff);
@@ -319,7 +360,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
   // beyond what the clamp let through. Both cases mean the hashers
   // and verifier saw a different byte set than the on-disk file.
   if (fullOff !== assetStat.size) {
-    throw new Error("standalone-verifier.verify: asset '" + assetPath +
+    throw _svErr("size-race", "standalone-verifier.verify: asset '" + assetPath +
                     "' changed size during read (expected " + assetStat.size +
                     " bytes per fstat, read " + fullOff +
                     " bytes) — refusing to return a hash that may not match the on-disk file");
@@ -327,6 +368,10 @@ function verify(assetPath, signaturePath, pubkeyPem) {
 
   var sha256Hex = sha256.digest("hex");
   var sha3Hex   = sha3.digest("hex");
+  var digests   = {};
+  for (var dh = 0; dh < extraHashers.length; dh += 1) {
+    digests[extraHashers[dh].name] = extraHashers[dh].hash.digest("hex");
+  }
 
   var ok = false;
   if (alg === "ecdsa-p384") {
@@ -351,7 +396,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
     } else {
       // assetFd was already closed by the read loop's `finally`; this is a
       // pure fail-closed refusal, same as the `if (!ok)` path below.
-      throw new Error("standalone-verifier.verify: ecdsa-p384 signature is neither a " +
+      throw _svErr("bad-sig-encoding", "standalone-verifier.verify: ecdsa-p384 signature is neither a " +
                       "well-formed DER SEQUENCE nor a raw " + (coordLen * 2) +
                       "-byte IEEE-P1363 pair (length " + signature.length +
                       ") — refusing to guess the encoding");
@@ -366,7 +411,7 @@ function verify(assetPath, signaturePath, pubkeyPem) {
   }
 
   if (!ok) {
-    throw new Error("standalone-verifier.verify: " + alg + " signature INVALID for " +
+    throw _svErr("verify-failed", "standalone-verifier.verify: " + alg + " signature INVALID for " +
                     assetPath + " (sha3-512=" + sha3Hex.slice(0, 16) + "...). " +   // 16-char hex prefix for forensic display, not bytes
                     "Either the asset was tampered with after signing, the signature " +
                     "doesn't match this asset, or the pubkey doesn't match the signing key.");
@@ -377,6 +422,8 @@ function verify(assetPath, signaturePath, pubkeyPem) {
     sha3_512: sha3Hex,
     sha256:   sha256Hex,
     alg:      alg,
+    bytes:    fullOff,
+    digests:  digests,
   };
 }