@blamejs/core 0.12.42 → 0.12.43

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.43 (2026-05-25) — **`b.crypto.selfTest` — FIPS 140-3-style power-on self-test for the crypto stack.** A power-on self-test over the framework's cryptographic primitives — the integrity check a FIPS 140-3-validated module runs at start-up. The hash / XOF checks are known-answer tests against NIST FIPS 202 published vectors (SHA3-256 / SHA3-512 / SHAKE256), so they confirm the framework's hashing matches the standard rather than merely itself; the AEAD check round-trips XChaCha20-Poly1305 and confirms a tampered ciphertext is rejected; and the post-quantum checks run a pairwise-consistency + negative test for ML-KEM-1024, ML-DSA-87, and SLH-DSA-SHAKE-256f (a fresh keypair must encaps/decaps and sign/verify consistently and reject a tampered signature — FIPS 140-3 §10.3 pairwise consistency, since the runtime exposes no seed-injection API for a fixed-seed KAT). selfTest returns a structured report and, by default, throws on any failure so a broken crypto stack fails closed at boot rather than silently producing bad output. Operators in regulated deployments can run it at start-up as a self-integrity gate. **Added:** *`b.crypto.selfTest(opts?)`* — Runs eight checks — SHA3-512 / SHA3-256 / SHAKE256 known-answer tests (NIST FIPS 202), HMAC-SHA3-512 determinism, XChaCha20-Poly1305 round-trip + tamper-detect, and ML-KEM-1024 / ML-DSA-87 / SLH-DSA-SHAKE-256f pairwise-consistency + negative tests — and returns `{ ok, results: [{ name, ok, detail? }], failures, ranAt }`. Throws `crypto/self-test-failed` (with the report attached) on any failure unless `opts.throwOnFailure` is `false`. Exercises the framework's real primitive paths so a self-test failure means the shipped crypto is broken.
+
 - v0.12.42 (2026-05-24) — **`b.vc.present` / `b.vc.verifyPresentation` — W3C Verifiable Presentations.** Completes b.vc with the holder side: a Verifiable Presentation is a holder-signed envelope wrapping one or more credentials, proving the presenter controls the key the credentials were issued to. b.vc.present builds and signs a VerifiablePresentation (each credential enveloped per VC-JOSE-COSE) as a compact JWS (vp+jwt) or COSE_Sign1 (application/vp+cose), matching b.vc.issue's algorithms; an optional nonce / audience is embedded in the signed presentation for holder-binding and replay protection. b.vc.verifyPresentation verifies the holder signature (auto-detected jose/cose, mandatory algorithm allowlist, JOSE none refused), the VCDM structure, and the embedded nonce / audience / expectedHolder when given, and — with verifyCredentials: true — verifies each enveloped credential through b.vc.verify and returns them. The holder is typically a DID, resolved to a key via b.did. Composes b.cose; no new runtime dependency. **Added:** *`b.vc.present(opts)` / `b.vc.verifyPresentation(secured, opts)`* — `present` wraps `opts.credentials` (secured VCs — compact-JWS strings or COSE_Sign1 bytes, each enveloped as an `EnvelopedVerifiableCredential` data: URI) in a `VerifiablePresentation` signed by the holder, with optional `nonce` / `audience` embedded for binding. `verifyPresentation` verifies the holder signature against the mandatory `opts.algorithms` allowlist (JOSE `none` always refused), re-checks the VCDM structure, enforces `expectedHolder` / `nonce` / `audience` when supplied, and with `verifyCredentials: true` verifies each enveloped credential through `b.vc.verify` (using `opts.credentialOpts`), returning `{ presentation, holder, credentials, securing, alg }`. The enveloped-credential count is bounded. A `vp+jwt` presentation is refused by `b.vc.verify` and a `vc+jwt` credential is refused by `verifyPresentation` — the media-type binding keeps the two surfaces distinct.
 
 - v0.12.41 (2026-05-24) — **`b.did` — W3C DID resolution (did:key + did:web) feeding the credential verifiers.** Resolve W3C Decentralized Identifiers (DID Core 1.0) to verification keys — the link that lets a credential's issuer be named by a DID rather than a raw key. Resolve the issuer DID of a b.vc / b.mdoc / b.scitt credential to a node:crypto KeyObject and hand it to the verifier. did:key encodes the public key in the identifier (multicodec + base58btc), so resolution is deterministic and offline — Ed25519, P-256, P-384, and secp256k1 round-trip; did:web places the DID document at an HTTPS URL derived from the identifier, with the network fetch left to the operator (the framework parses the operator-fetched document and extracts its verification methods, as publicKeyMultibase or publicKeyJwk). b.did.keyToDid encodes a KeyObject as a did:key (an issuer naming itself), b.did.parse splits the identifier (and returns the did:web URL to fetch), and b.did.resolve returns the document and verification keys. DID Core 1.0 is a W3C Recommendation; the method specs (did:key W3C CCG report, did:web DID method registry — EUDI-mandated) are deployed-stable. Composes node:crypto; no new runtime dependency. **Added:** *`b.did.resolve(did, opts?)` / `b.did.keyToDid(publicKey)` / `b.did.parse(did)`* — `resolve` returns `{ didDocument, verificationMethods: [{ id, controller, type, publicKey }] }` with each `publicKey` a `node:crypto` KeyObject ready for `b.vc.verify` / `b.mdoc.verifyIssuerSigned` / `b.scitt.verifyStatement`. did:key resolves deterministically and offline (base58btc + multicodec → Ed25519 raw key or EC compressed point, rebuilt via SPKI); did:web requires the operator to pass the fetched DID document as `opts.document` (the URL to GET is on `b.did.parse(did).url`) and the document `id` must match the requested DID. A publicKeyJwk in a DID document is imported only after its `kty`/`crv` is allowlisted (Ed25519 / P-256 / P-384 / secp256k1) — an unexpected key type from an untrusted document is refused, not blindly imported. `keyToDid` encodes an Ed25519 / P-256 / P-384 / secp256k1 KeyObject as a did:key; `parse` derives the did:web HTTPS URL (`host[:port][:path]` → `https://host/path/did.json`, or `/.well-known/did.json`). Unknown methods, malformed base58, unsupported multicodec codes, and unsupported key types are each refused.

package/README.md

@@ -92,6 +92,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 ### Crypto
 
 - **At-rest envelope** — envelope-versioned PQC (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256); vault sealing (`b.crypto`, `b.vault`)
+- **Power-on self-test** — `b.crypto.selfTest()` runs FIPS 140-3-style integrity checks: NIST FIPS 202 known-answer tests (SHA3-256/512, SHAKE256), AEAD round-trip + tamper-detect, and ML-KEM-1024 / ML-DSA-87 / SLH-DSA-SHAKE-256f pairwise-consistency + negative tests; fails closed (throws) on any mismatch
 - **Field-level + crypto-shred** — `b.cryptoField.eraseRow`; per-column data residency tagging + per-row keys (`K_row = HKDF(K_table, rowId)`) so erasing the per-row key makes WAL / replica residuals undecryptable (`b.cryptoField.declareColumnResidency`, `b.cryptoField.declarePerRowKey`)
 - **AAD-bound sealed columns** — AEAD tag tied to `(table, rowId, column, schemaVersion)`; copy-paste between rows or schema-version replay surfaces as refused decrypt (`b.vault.aad`)
 - **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`)

package/lib/crypto.js

@@ -62,6 +62,9 @@ var audit       = lazyRequire(function () { return require("./audit"); });
 // loaded because safe-buffer.js itself imports b.crypto for
 // hex-compare helpers (circular).
 var safeBuffer  = lazyRequire(function () { return require("./safe-buffer"); });
+// pqc-software requires this module (b.crypto) — lazy-load to break the
+// cycle. Only the power-on self-test needs it here.
+var pqcSoftware = lazyRequire(function () { return require("./pqc-software"); });
 
 // Streaming-hash algorithm allowlist. Mirrors the framework's PQC-
 // first crypto policy: SHA3 / SHAKE family is the default surface;
@@ -1873,8 +1876,124 @@ var SUPPORTED_KEM_ALGORITHMS = Object.freeze([
 //   var fixtures = require("blamejs/lib/_test/crypto-fixtures");
 //   var blob = fixtures.mintLegacyEnvelope0xE1(plaintext, recipient);
 
+// ---- FIPS 140-3-style power-on self-test ----
+//
+// Known-answer tests (KATs) for the deterministic primitives — the
+// hash / XOF digests are NIST FIPS 202 published vectors, so this
+// confirms the framework's hashing matches the standard, not merely
+// itself. The PQC algorithms have no seed-injection API (node generates
+// the keypair randomness internally), so they get FIPS 140-3 §10.3
+// pairwise-consistency + negative tests (a fresh keypair must
+// sign->verify / encaps->decaps consistently, and a tampered signature
+// must be rejected) rather than a fixed-seed KAT.
+var KAT_SHA3_512_ABC = "b751850b1a57168a5693cd924b6b096e08f621827444f70d884f5d0240d2712e10e116e9192af3c91a7ec57647e3934057340b4cf408d5a56592f8274eec53f0";
+var KAT_SHA3_256_ABC = "3a985da74fe225b2045c172d6bd390bd855f086e3e9d525b46bfe24511431532";
+var KAT_SHAKE256_ABC_32 = "483366601360a8771c6863080cc4114d8db44530f8f1e1ee4f94ea37e78b5739";
+
+/**
+ * @primitive b.crypto.selfTest
+ * @signature b.crypto.selfTest(opts?)
+ * @since     0.12.43
+ * @status    stable
+ * @compliance soc2, hipaa, pci-dss
+ * @related   b.crypto.sha3Hash, b.crypto.encrypt
+ *
+ * Run a power-on self-test over the framework's cryptographic
+ * primitives — the integrity check FIPS 140-3 requires of a validated
+ * module. The hash / XOF checks are known-answer tests against NIST FIPS
+ * 202 vectors (SHA3-256 / SHA3-512 / SHAKE256); the AEAD check
+ * round-trips XChaCha20-Poly1305 and confirms a tampered ciphertext is
+ * rejected; the post-quantum checks run a pairwise-consistency +
+ * negative test for ML-KEM-1024, ML-DSA-87, and SLH-DSA-SHAKE-256f.
+ * Returns a structured report and, by default, throws on any failure so
+ * a broken crypto stack fails closed at boot rather than silently
+ * producing bad output.
+ *
+ * @opts
+ *   {
+ *     throwOnFailure?: boolean,  // default true — throw if any check fails
+ *   }
+ *
+ * @example
+ *   var report = b.crypto.selfTest();
+ *   // -> { ok: true, results: [ { name, ok }, ... ], failures: [], ranAt }
+ */
+function selfTest(opts) {
+  opts = opts || {};
+  var results = [];
+  function record(name, fn) {
+    try { fn(); results.push({ name: name, ok: true }); }
+    catch (e) { results.push({ name: name, ok: false, detail: (e && e.message) || String(e) }); }
+  }
+  function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+  record("SHA3-512 KAT (FIPS 202)", function () {
+    assert(sha3Hash("abc") === KAT_SHA3_512_ABC, "SHA3-512(\"abc\") does not match the FIPS 202 vector");
+  });
+  record("SHA3-256 KAT (FIPS 202)", function () {
+    assert(hash("abc", "sha3-256").toString("hex") === KAT_SHA3_256_ABC, "SHA3-256(\"abc\") does not match the FIPS 202 vector");
+  });
+  record("SHAKE256 KAT (FIPS 202)", function () {
+    assert(hash("abc", "shake256", C.BYTES.bytes(32)).toString("hex") === KAT_SHAKE256_ABC_32, "SHAKE256(\"abc\") does not match the FIPS 202 vector");
+  });
+  record("HMAC-SHA3-512 determinism", function () {
+    var k = Buffer.from("self-test-hmac-key", "utf8");
+    assert(timingSafeEqual(hmacSha3(k, "abc"), hmacSha3(k, "abc")), "HMAC-SHA3-512 is not deterministic");
+    assert(!timingSafeEqual(hmacSha3(k, "abc"), hmacSha3(k, "abd")), "HMAC-SHA3-512 collided on distinct inputs");
+  });
+  record("XChaCha20-Poly1305 round-trip + tamper-detect", function () {
+    var key = generateBytes(C.BYTES.bytes(32));
+    var pt = Buffer.from("blamejs crypto self-test plaintext", "utf8");
+    var packed = encryptPacked(pt, key);
+    assert(decryptPacked(packed, key).equals(pt), "AEAD round-trip did not recover the plaintext");
+    var bad = Buffer.from(packed); bad[bad.length - 1] ^= 0xff;
+    var rejected = false;
+    try { decryptPacked(bad, key); } catch (_e) { rejected = true; }
+    assert(rejected, "AEAD accepted a tampered ciphertext");
+  });
+
+  // Post-quantum pairwise-consistency + negative tests. PQC is an
+  // optional vendored dependency — a load failure surfaces as a failed
+  // check rather than a silent skip.
+  var pqc = pqcSoftware();
+  record("ML-KEM-1024 encaps/decaps pairwise consistency", function () {
+    var kp = pqc.ml_kem_1024.keygen();
+    var enc = pqc.ml_kem_1024.encapsulate(kp.publicKey);
+    var ss = pqc.ml_kem_1024.decapsulate(enc.cipherText, kp.secretKey);
+    assert(timingSafeEqual(Buffer.from(ss), Buffer.from(enc.sharedSecret)), "ML-KEM-1024 decapsulated secret does not match");
+  });
+  record("ML-DSA-87 sign/verify + negative", function () {
+    var kp = pqc.ml_dsa_87.keygen();
+    var msg = Buffer.from("blamejs ML-DSA self-test", "utf8");
+    var sig = pqc.ml_dsa_87.sign(msg, kp.secretKey);
+    assert(pqc.ml_dsa_87.verify(sig, msg, kp.publicKey), "ML-DSA-87 rejected a valid signature");
+    var bad = Buffer.from(sig); bad[0] ^= 0xff;
+    assert(!pqc.ml_dsa_87.verify(bad, msg, kp.publicKey), "ML-DSA-87 accepted a tampered signature");
+  });
+  record("SLH-DSA-SHAKE-256f sign/verify + negative", function () {
+    var kp = pqc.slh_dsa_shake_256f.keygen();
+    var msg = Buffer.from("blamejs SLH-DSA self-test", "utf8");
+    var sig = pqc.slh_dsa_shake_256f.sign(msg, kp.secretKey);
+    assert(pqc.slh_dsa_shake_256f.verify(sig, msg, kp.publicKey), "SLH-DSA-SHAKE-256f rejected a valid signature");
+    var bad = Buffer.from(sig); bad[0] ^= 0xff;
+    assert(!pqc.slh_dsa_shake_256f.verify(bad, msg, kp.publicKey), "SLH-DSA-SHAKE-256f accepted a tampered signature");
+  });
+
+  var failures = results.filter(function (r) { return !r.ok; });
+  var report = { ok: failures.length === 0, results: results, failures: failures, ranAt: new Date().toISOString() };
+  if (failures.length && opts.throwOnFailure !== false) {
+    var err = new Error("crypto.selfTest: " + failures.length + " self-test(s) failed: " +
+      failures.map(function (f) { return f.name; }).join("; "));
+    err.code = "crypto/self-test-failed";
+    err.report = report;
+    throw err;
+  }
+  return report;
+}
+
 module.exports = {
   sri:                          sri,
+  selfTest:                     selfTest,
   // Hashing
   sha3Hash:                    sha3Hash,
   hmacSha3:                    hmacSha3,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.42",
+  "version": "0.12.43",
   "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:313dd43c-bb3f-4c16-a801-2af63046b56f",
+  "serialNumber": "urn:uuid:2659855c-303c-4b3d-931b-a39839633612",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T06:48:54.423Z",
+    "timestamp": "2026-05-25T07:30:43.059Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.42",
+      "bom-ref": "@blamejs/core@0.12.43",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.42",
+      "version": "0.12.43",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.42",
+      "purl": "pkg:npm/%40blamejs/core@0.12.43",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.42",
+      "ref": "@blamejs/core@0.12.43",
       "dependsOn": []
     }
   ]