@blamejs/core 0.13.0 → 0.13.1

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.1 (2026-05-26) — **`b.worm` — write-once-read-many retention.** Store records that cannot be altered or deleted before a retention period elapses — the immutable-storage discipline regulators require (SEC 17a-4(f), CFTC 1.31, FINRA 4511). b.worm.create(opts) returns a WORM store that enforces, on every mutating call, that a record is not overwritten or deleted while it is within its retainUntil window or under a legal hold. Two modes mirror cloud Object-Lock: compliance (the default — no one, including the operator, can delete before expiry) and governance (a privileged caller may override with an audited reason). Retention can only be extended, never shortened; every record carries a SHA3-512 digest that get verifies, so tampering with the underlying bytes is detected on read; every allow/refuse decision is audited. Storage is pluggable via a synchronous store adapter, so the policy layer sits over a sealed DB table, a filesystem, or any non-S3 backend — the store-agnostic, application-level companion to b.objectStore's S3 Object Lock, with content-integrity verification that native Object Lock does not provide. **Added:** *`b.worm.create` — write-once-read-many retention* — Returns a store with `put` / `get` / `delete` / `extendRetention` / `placeLegalHold` / `releaseLegalHold` / `list`. `put` is write-once (an overwrite of a retained or held record is refused); `delete` is gated by the retention window, legal holds, and the mode (`compliance` refuses any early delete; `governance` allows a privileged override with a required, audited reason); `extendRetention` is extend-only; `get` verifies the stored SHA3-512 digest and throws `worm/tampered` on a mismatch. Storage is a pluggable synchronous adapter (`get` / `set` / `delete` / `has` / `keys`), defaulting to in-memory for tests. Use it for SEC 17a-4 / CFTC / FINRA immutable records on backends without native Object Lock; `b.objectStore` remains the path for S3 Object Lock.
+
 - v0.13.0 (2026-05-26) — **`b.crypto.oprf` — RFC 9497 Oblivious PRFs.** Compute F(serverKey, input) without the server learning the input and without the client learning the key — the Oblivious PRF primitive behind password hardening (the server peppers a password it never sees), private set intersection, and Privacy Pass. b.crypto.oprf.suite(name) returns an RFC 9497 ciphersuite — ristretto255-sha512, p256-sha256, p384-sha384, or p521-sha512 — each exposing the base oprf mode and the verifiable voprf mode (a DLEQ proof lets the client confirm the server used the key committed in its public key). The client blinds its input, the server blind-evaluates with its secret key, and the client finalizes by un-blinding and hashing; because un-blinding cancels the blind, the output depends only on key and input. Validated byte-for-byte against the RFC 9497 Appendix-A test vectors. Group and hash-to-curve operations come from the newly vendored @noble/curves (Paul Miller, MIT) — the same maintainer as the framework's existing vendored @noble/post-quantum and @noble/ciphers, with no added npm runtime dependency. **Added:** *`b.crypto.oprf` — RFC 9497 OPRF / VOPRF* — `suite(name)` returns `{ name, oprf, voprf }` for one of the four RFC 9497 ciphersuites (ristretto255-SHA512 / P-256-SHA256 / P-384-SHA384 / P-521-SHA512). The `oprf` (base) mode provides `deriveKeyPair` / `generateKeyPair` / `blind` / `blindEvaluate` / `finalize` / `evaluate`; `voprf` (verifiable) adds a DLEQ proof so the client can prove the server used the committed key. Use it for password hardening, private set intersection, and OPRF-based tokens. Verified against the RFC 9497 Appendix-A vectors. The partially-oblivious `poprf` mode is not yet exposed (the vendored `@noble/curves` does not implement it) and will follow upstream. · *Vendored `@noble/curves`* — `@noble/curves` 2.2.0 (Paul Miller, MIT) is vendored under `lib/vendor/` (no npm runtime dependency), supplying the ristretto255 / NIST-curve group and hash-to-curve operations behind `b.crypto.oprf`. It joins the existing vendored `@noble/post-quantum` and `@noble/ciphers` from the same maintainer; tracked in the SBOM and the vendor-currency gate.
 
 ## v0.12.x

package/README.md

@@ -89,6 +89,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Workflow gates** — break-glass column gates with second-factor + audit (`b.breakGlass`); two-person-rule m-of-n approval with cooling-off lock + cancellation (`b.dualControl`)
 - **Financial / Open Banking** — FAPI 2.0 Final composite posture (PAR + PKCE-S256 + DPoP-or-mTLS + RFC 9207); runtime enforcement helpers `b.fapi2.assertCallback` (refuses missing iss + bare-param under message-signing) and `b.fapi2.assertAuthzRequest` (refuses non-JAR); CFPB §1033 / FDX 6.0 consumer-financial-data-sharing wrapper (`b.fdx`)
 - **Data-subject coordination** — cross-table export / rectify / erase / restrict / objection (`b.subject`, `b.subject.eraseHard`); subject-level legal-hold registry consulted by erase + retention paths (FRCP Rule 26/37(e), GDPR Art 17(3)(e), SEC Rule 17a-4, HIPAA §164.530(j)(2)) (`b.legalHold`)
+- **WORM retention** — write-once-read-many records over any backing store (`b.worm.create`): `compliance` / `governance` Object-Lock modes, extend-only `retainUntil`, legal holds, and a tamper-evident SHA3-512 digest verified on read — the store-agnostic application-level companion to `b.objectStore`'s S3 Object Lock, for sealed-DB / filesystem / non-S3 backends (SEC 17a-4(f), CFTC 1.31, FINRA 4511)
 - **Account safety** — adaptive bot-challenge staircase (`b.authBotChallenge`); session-to-device-posture binding with fail-closed verify (`b.sessionDeviceBinding`)
 - **Anonymous authorization** — Privacy Pass origin side (RFC 9577/9578 — `b.privacyPass`): issue a `WWW-Authenticate: PrivateToken` challenge and verify a presented Blind-RSA (type 0x0002) token against the issuer public key, with no issuer callback and no client identity
 - **Oblivious PRF** — RFC 9497 OPRF / VOPRF (`b.crypto.oprf.suite`): learn `F(serverKey, input)` without the server seeing the input — the primitive behind password hardening (pepper a password the server never sees), private set intersection, and Privacy Pass; `oprf` (base) + `voprf` (verifiable, DLEQ-proof) modes over ristretto255-SHA512 / P-256 / P-384 / P-521; validated against the RFC 9497 Appendix-A vectors

package/index.js

@@ -372,6 +372,7 @@ var fileUpload = require("./lib/file-upload");
 var dualControl = require("./lib/dual-control");
 var retention = require("./lib/retention");
 var legalHold = require("./lib/legal-hold");
+var worm = require("./lib/worm");
 var network = require("./lib/network");
 var cloudEvents = require("./lib/cloud-events");
 var dsr = require("./lib/dsr");
@@ -710,6 +711,7 @@ module.exports = {
   dualControl:      dualControl,
   retention:        retention,
   legalHold:        legalHold,
+  worm:             worm,
   network:          network,
   cloudEvents:      cloudEvents,
   dsr:              dsr,

package/lib/worm.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * @module b.worm
+ * @nav    Compliance
+ * @title  WORM Retention
+ *
+ * @intro
+ *   Write-once-read-many records with retention-until immutability — the
+ *   storage discipline regulators require for records that must not be
+ *   altered or deleted before a retention period elapses (SEC 17a-4(f),
+ *   CFTC 1.31, FINRA 4511, and the "immutable storage" controls in many
+ *   sectoral postures). A WORM store enforces, on every mutating call, that
+ *   a stored record cannot be overwritten or deleted while it is within its
+ *   retention window or under a legal hold.
+ *
+ *   Two modes mirror the cloud Object-Lock model: in <code>compliance</code>
+ *   mode (the default) a record cannot be deleted before its
+ *   <code>retainUntil</code> time by anyone, including the operator; in
+ *   <code>governance</code> mode a privileged caller may override with an
+ *   explicit reason, which is audited. Retention can only be
+ *   <em>extended</em>, never shortened. Every record carries a SHA3-512
+ *   content digest, so <code>get</code> detects tampering of the underlying
+ *   bytes. Every allow/refuse decision is audited.
+ *
+ *   Storage is pluggable: <code>create</code> takes a synchronous
+ *   <code>store</code> adapter (<code>get</code> / <code>set</code> /
+ *   <code>delete</code> / <code>has</code> / <code>keys</code>) so the WORM
+ *   policy layer sits over an operator's durable backend (a sealed DB
+ *   table, an S3 Object-Lock bucket, a filesystem); the default in-memory
+ *   adapter is for tests and ephemeral use.
+ *
+ * @card
+ *   Write-once-read-many retention (`b.worm.create`) — SEC 17a-4 / CFTC-style
+ *   immutable records with compliance / governance Object-Lock modes,
+ *   extend-only retention, legal holds, and a tamper-evident SHA3-512 digest
+ *   over any pluggable store.
+ */
+
+var nodeCrypto = require("node:crypto");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var { timingSafeEqual } = require("./crypto");
+var { defineClass } = require("./framework-error");
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var WormError = defineClass("WormError", { alwaysPermanent: true });
+
+var MODES = { compliance: 1, governance: 1 };
+
+function _now(clock) { return typeof clock === "function" ? clock() : Date.now(); }
+function _toBytes(data) {
+  // Always return a fresh copy — the WORM record owns its bytes. If we kept
+  // the caller's Buffer, a later mutation of their reference would silently
+  // change stored bytes and break the digest, defeating immutability.
+  if (Buffer.isBuffer(data)) return Buffer.from(data);
+  if (data instanceof Uint8Array) return Buffer.from(data);
+  if (typeof data === "string") return Buffer.from(data, "utf8");
+  return Buffer.from(JSON.stringify(data), "utf8");   // structured value → canonical-ish JSON
+}
+function _digest(bytes) { return nodeCrypto.createHash("sha3-512").update(bytes).digest(); }
+
+// Default in-memory store adapter (tests / ephemeral). Operators pass a
+// durable adapter with the same five synchronous methods.
+function _memStore() {
+  var m = new Map();
+  return {
+    get: function (id) { return m.get(id); },
+    set: function (id, rec) { m.set(id, rec); },
+    delete: function (id) { m.delete(id); },
+    has: function (id) { return m.has(id); },
+    keys: function () { return Array.from(m.keys()); },
+  };
+}
+
+/**
+ * @primitive  b.worm.create
+ * @signature  b.worm.create(opts?)
+ * @since      0.13.0
+ * @status     stable
+ * @compliance sox-404, soc2
+ * @related    b.retention.create, b.legalHold, b.retention.complianceFloor
+ *
+ * Create a WORM store that enforces write-once-read-many retention over a
+ * backing store. The returned instance has <code>put</code>,
+ * <code>get</code>, <code>delete</code>, <code>extendRetention</code>,
+ * <code>placeLegalHold</code>, <code>releaseLegalHold</code>, and
+ * <code>list</code>. Throws <code>WormError</code> on policy violations.
+ *
+ * @opts
+ *   store:             object,   // adapter: get/set/delete/has/keys (default: in-memory)
+ *   mode:              string,   // "compliance" (default) | "governance"
+ *   defaultRetentionMs: number,  // applied when put() gives no retain time
+ *   clock:             function, // () => epoch ms (default Date.now; for tests)
+ *
+ * @example
+ *   var w = b.worm.create({ mode: "compliance" });
+ *   w.put("invoice-42", pdfBytes, { retentionMs: b.C.TIME.days(2555) }); // 7y
+ *   w.get("invoice-42").data;            // → pdfBytes (digest verified)
+ *   w.delete("invoice-42");              // throws worm/retained until 2033
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["store", "mode", "defaultRetentionMs", "clock"], "worm.create");
+  var mode = opts.mode || "compliance";
+  if (!MODES[mode]) throw new WormError("worm/bad-mode", "worm.create: mode must be 'compliance' or 'governance'");
+  var store = opts.store || _memStore();
+  ["get", "set", "delete", "has", "keys"].forEach(function (m) {
+    if (typeof store[m] !== "function") throw new WormError("worm/bad-store", "worm.create: store adapter must implement " + m + "()");
+  });
+  var clock = opts.clock;
+  var defaultRetentionMs = opts.defaultRetentionMs;
+  if (defaultRetentionMs != null && (typeof defaultRetentionMs !== "number" || !isFinite(defaultRetentionMs) || defaultRetentionMs < 0)) {
+    throw new WormError("worm/bad-opt", "worm.create: defaultRetentionMs must be a non-negative finite number");
+  }
+
+  function _emit(action, outcome, id, metadata) {
+    try {
+      audit().safeEmit({ action: "worm." + action, actor: { type: "system" }, outcome: outcome, metadata: Object.assign({ id: id, mode: mode }, metadata || {}) });
+    } catch (_e) { /* audit is drop-silent by design */ }
+  }
+
+  function _resolveRetainUntil(now, putOpts) {
+    if (putOpts.retainUntil != null) {
+      if (typeof putOpts.retainUntil !== "number" || !isFinite(putOpts.retainUntil)) throw new WormError("worm/bad-opt", "worm.put: retainUntil must be an epoch-ms number");
+      return putOpts.retainUntil;
+    }
+    var ms = putOpts.retentionMs != null ? putOpts.retentionMs : defaultRetentionMs;
+    if (ms == null) throw new WormError("worm/no-retention", "worm.put: a retention is required — pass retainUntil, retentionMs, or set defaultRetentionMs at create()");
+    if (typeof ms !== "number" || !isFinite(ms) || ms < 0) throw new WormError("worm/bad-opt", "worm.put: retentionMs must be a non-negative finite number");
+    return now + ms;
+  }
+
+  function put(id, data, putOpts) {
+    putOpts = putOpts || {};
+    if (typeof id !== "string" || id.length === 0) throw new WormError("worm/bad-id", "worm.put: id must be a non-empty string");
+    var now = _now(clock);
+    var existing = store.get(id);
+    if (existing) {
+      // Write-once: an existing record may not be overwritten while it is
+      // still retained or held — that is the whole guarantee.
+      if (existing.legalHolds.length > 0 || now < existing.retainUntil) {
+        _emit("put-refused", "denied", id, { reason: "write-once" });
+        throw new WormError("worm/already-exists", "worm.put: '" + id + "' exists and is still retained/held — WORM records are write-once");
+      }
+    }
+    var bytes = _toBytes(data);
+    var retainUntil = _resolveRetainUntil(now, putOpts);
+    var holds = [];
+    if (putOpts.legalHold != null) holds.push(String(putOpts.legalHold));
+    var rec = {
+      bytes: bytes,
+      digest: _digest(bytes),
+      createdAt: now,
+      retainUntil: retainUntil,
+      legalHolds: holds,
+      mode: mode,
+    };
+    store.set(id, rec);
+    _emit("put", "allowed", id, { retainUntil: retainUntil, bytes: bytes.length });
+    return { id: id, digest: rec.digest.toString("hex"), createdAt: now, retainUntil: retainUntil };
+  }
+
+  function _require(id) {
+    var rec = store.get(id);
+    if (!rec) throw new WormError("worm/not-found", "worm: no record '" + id + "'");
+    return rec;
+  }
+
+  function get(id) {
+    var rec = _require(id);
+    // Tamper-evidence: the stored digest must still match the stored bytes.
+    if (!timingSafeEqual(rec.digest, _digest(rec.bytes))) {
+      _emit("tamper-detected", "denied", id, {});
+      throw new WormError("worm/tampered", "worm.get: stored bytes for '" + id + "' do not match their digest");
+    }
+    // Hand back a copy so a consumer cannot mutate the stored bytes through
+    // the read API and corrupt the record behind the policy checks.
+    return { id: id, data: Buffer.from(rec.bytes), digest: rec.digest.toString("hex"), createdAt: rec.createdAt, retainUntil: rec.retainUntil, legalHolds: rec.legalHolds.slice(), mode: rec.mode };
+  }
+
+  function del(id, delOpts) {
+    delOpts = delOpts || {};
+    var rec = _require(id);
+    var now = _now(clock);
+    if (rec.legalHolds.length > 0) {
+      _emit("delete-refused", "denied", id, { reason: "legal-hold", holds: rec.legalHolds.length });
+      throw new WormError("worm/legal-hold", "worm.delete: '" + id + "' is under " + rec.legalHolds.length + " legal hold(s)");
+    }
+    if (now < rec.retainUntil) {
+      if (mode === "governance" && delOpts.override === true) {
+        if (typeof delOpts.reason !== "string" || delOpts.reason.length === 0) throw new WormError("worm/override-reason", "worm.delete: a governance override requires a non-empty reason");
+        store.delete(id);
+        _emit("delete-override", "allowed", id, { retainUntil: rec.retainUntil, reason: delOpts.reason });
+        return true;
+      }
+      _emit("delete-refused", "denied", id, { reason: "retained", retainUntil: rec.retainUntil });
+      throw new WormError("worm/retained", "worm.delete: '" + id + "' is retained until " + new Date(rec.retainUntil).toISOString() + (mode === "compliance" ? " (compliance mode — no override)" : " (pass { override: true, reason } in governance mode)"));
+    }
+    store.delete(id);
+    _emit("delete", "allowed", id, {});
+    return true;
+  }
+
+  function extendRetention(id, newRetainUntil) {
+    var rec = _require(id);
+    if (typeof newRetainUntil !== "number" || !isFinite(newRetainUntil)) throw new WormError("worm/bad-opt", "worm.extendRetention: newRetainUntil must be an epoch-ms number");
+    if (newRetainUntil < rec.retainUntil) {
+      _emit("extend-refused", "denied", id, { current: rec.retainUntil, requested: newRetainUntil });
+      throw new WormError("worm/retention-shorten", "worm.extendRetention: retention can only be extended, never shortened");
+    }
+    rec.retainUntil = newRetainUntil;
+    store.set(id, rec);
+    _emit("extend", "allowed", id, { retainUntil: newRetainUntil });
+    return newRetainUntil;
+  }
+
+  function placeLegalHold(id, holdId) {
+    var rec = _require(id);
+    if (typeof holdId !== "string" || holdId.length === 0) throw new WormError("worm/bad-opt", "worm.placeLegalHold: holdId must be a non-empty string");
+    if (rec.legalHolds.indexOf(holdId) === -1) { rec.legalHolds.push(holdId); store.set(id, rec); }
+    _emit("legal-hold-placed", "allowed", id, { holdId: holdId });
+    return rec.legalHolds.slice();
+  }
+
+  function releaseLegalHold(id, holdId) {
+    var rec = _require(id);
+    var i = rec.legalHolds.indexOf(String(holdId));
+    if (i !== -1) { rec.legalHolds.splice(i, 1); store.set(id, rec); }
+    _emit("legal-hold-released", "allowed", id, { holdId: holdId });
+    return rec.legalHolds.slice();
+  }
+
+  function list() { return store.keys(); }
+
+  return {
+    put: put, get: get, delete: del, extendRetention: extendRetention,
+    placeLegalHold: placeLegalHold, releaseLegalHold: releaseLegalHold,
+    list: list, mode: mode,
+  };
+}
+
+module.exports = {
+  create:    create,
+  MODES:     Object.keys(MODES),
+  WormError: WormError,
+};

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:d8196be4-b27f-4e74-86fc-32557c5f1ac1",
+  "serialNumber": "urn:uuid:867201c0-c1e7-42ae-8956-c09389ae0095",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-26T20:49:46.612Z",
+    "timestamp": "2026-05-26T22:27:34.169Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.0",
+      "bom-ref": "@blamejs/core@0.13.1",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.0",
+      "version": "0.13.1",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.0",
+      "purl": "pkg:npm/%40blamejs/core@0.13.1",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.0",
+      "ref": "@blamejs/core@0.13.1",
       "dependsOn": []
     }
   ]