@blamejs/blamejs-shop 0.0.129 → 0.1.1

package/lib/vendor/blamejs/lib/cose.js

@@ -53,6 +53,7 @@
 
 var nodeCrypto = require("node:crypto");
 var cbor = require("./cbor");
+var bCrypto = require("./crypto");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -143,6 +144,7 @@ function _toBeSigned(protectedBstr, externalAad, payload) {
  *     externalAad?:        Buffer,    // default empty — bound into the signature
  *     unprotectedHeaders?: object,    // extra unprotected map entries (numeric keys)
  *     protectedHeaders?:   object,    // extra INTEGRITY-PROTECTED map entries (numeric keys); label 1 (alg) is reserved
+ *     detached?:           boolean,   // emit a nil payload (RFC 9052 §4.1) — signature still covers it; caller transmits the payload separately
  *   }
  *
  * @example
@@ -152,7 +154,7 @@ function _toBeSigned(protectedBstr, externalAad, payload) {
  */
 async function sign(payload, opts) {
   validateOpts.requireObject(opts, "cose.sign", CoseError);
-  validateOpts(opts, ["alg", "privateKey", "kid", "contentType", "externalAad", "unprotectedHeaders", "protectedHeaders"], "cose.sign");
+  validateOpts(opts, ["alg", "privateKey", "kid", "contentType", "externalAad", "unprotectedHeaders", "protectedHeaders", "detached"], "cose.sign");
   if (SIGNABLE.indexOf(opts.alg) === -1) {
     throw new CoseError("cose/unsignable-alg",
       "cose.sign: alg must be one of " + SIGNABLE.join(" / ") +
@@ -213,7 +215,10 @@ async function sign(payload, opts) {
     ? nodeCrypto.sign(null, toBeSigned, key)
     : nodeCrypto.sign(params.nodeAlg, toBeSigned, { key: key, dsaEncoding: params.dsaEncoding });
 
-  var sign1 = [protectedBstr, unprot, payloadBytes, signature];
+  // Detached payload (RFC 9052 §4.1): the COSE_Sign1 carries nil in the
+  // payload slot; the signature still covers the payload (above), and the
+  // caller transmits / re-supplies it out of band as externalPayload.
+  var sign1 = [protectedBstr, unprot, opts.detached ? null : payloadBytes, signature];
   return cbor.encode(new cbor.Tag(COSE_SIGN1_TAG, sign1));
 }
 
@@ -237,6 +242,7 @@ async function sign(payload, opts) {
  *     publicKey?:   object,    // the verification key (KeyObject / PEM)
  *     keyResolver?: function,  // (protectedHeaders, unprotectedHeaders) → key
  *     externalAad?: Buffer,    // must match what was signed
+ *     externalPayload?: Buffer, // required when the COSE_Sign1 payload is detached (nil); bound into the Sig_structure
  *     maxBytes?:    number,    // forwarded to b.cbor.decode
  *     maxDepth?:    number,
  *   }
@@ -247,7 +253,7 @@ async function sign(payload, opts) {
  */
 async function verify(coseSign1, opts) {
   validateOpts.requireObject(opts, "cose.verify", CoseError);
-  validateOpts(opts, ["algorithms", "publicKey", "keyResolver", "externalAad", "maxBytes", "maxDepth"], "cose.verify");
+  validateOpts(opts, ["algorithms", "publicKey", "keyResolver", "externalAad", "externalPayload", "maxBytes", "maxDepth"], "cose.verify");
   if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
     throw new CoseError("cose/algorithms-required",
       "cose.verify: opts.algorithms is required (no defaults — name the accepted algorithms)");
@@ -278,14 +284,23 @@ async function verify(coseSign1, opts) {
   if (!Buffer.isBuffer(protectedBstr) || !Buffer.isBuffer(signature)) {
     throw new CoseError("cose/malformed", "cose.verify: protected header and signature must be byte strings");
   }
+  // Detached payload (RFC 9052 §4.1): a nil payload slot means the caller
+  // must supply the payload out of band via opts.externalPayload, which
+  // is then bound into the Sig_structure. Supplying externalPayload for
+  // an attached (non-nil) token is ambiguous and refused.
   if (payload === null || payload === undefined) {
-    throw new CoseError("cose/detached-unsupported",
-      "cose.verify: detached payload (nil) is not supported in v1 — attached payload only");
-  }
-  // COSE_Sign1 payload is a bstr (RFC 9052 §4.2) — refuse a non-byte
-  // payload rather than return a value that violates the documented
-  // { payload: Buffer } shape.
-  if (!Buffer.isBuffer(payload)) {
+    if (opts.externalPayload == null) {
+      throw new CoseError("cose/detached-no-payload",
+        "cose.verify: COSE_Sign1 has a detached (nil) payload — pass opts.externalPayload to verify it");
+    }
+    payload = _bstr(opts.externalPayload);
+  } else if (opts.externalPayload != null) {
+    throw new CoseError("cose/payload-ambiguous",
+      "cose.verify: opts.externalPayload was supplied but the COSE_Sign1 carries an attached payload");
+  } else if (!Buffer.isBuffer(payload)) {
+    // COSE_Sign1 payload is a bstr (RFC 9052 §4.2) — refuse a non-byte
+    // payload rather than return a value that violates the documented
+    // { payload: Buffer } shape.
     throw new CoseError("cose/malformed", "cose.verify: payload must be a byte string (bstr)");
   }
   // The unprotected header is a CBOR map — refuse a non-map rather
@@ -534,12 +549,271 @@ function decrypt0(coseEncrypt0, opts) {
   return { plaintext: pt, alg: algName, protectedHeaders: protMap, unprotectedHeaders: unprotected };
 }
 
+// ---- COSE_Mac0 (RFC 9052 §6.2) — single shared-key MAC ----
+
+var COSE_MAC0_TAG = 17;                                                       // allow:raw-byte-literal — RFC 9052 COSE_Mac0 CBOR tag
+// HMAC algorithms (RFC 9053 §3.1). Only the full-length tags are offered —
+// the truncated HMAC 256/64 (id 4) is omitted. HMAC is symmetric, so its
+// post-quantum strength is fine; these are the COSE-standard MAC algs.
+var HMAC_NAME_TO_ID = { "HMAC-256/256": 5, "HMAC-384/384": 6, "HMAC-512/512": 7 };   // allow:raw-byte-literal — COSE HMAC algorithm ids (RFC 9053)
+var HMAC_ID_TO_NAME = {};
+Object.keys(HMAC_NAME_TO_ID).forEach(function (k) { HMAC_ID_TO_NAME[HMAC_NAME_TO_ID[k]] = k; });
+function _hmacHash(algId) {
+  switch (algId) {
+    case 5: return "sha256";
+    case 6: return "sha384";
+    case 7: return "sha512";
+    default: throw new CoseError("cose/unknown-alg", "cose: unrecognized HMAC COSE alg id " + algId);
+  }
+}
+
+// MAC_structure (§6.3) = [ "MAC0", body_protected (bstr), external_aad (bstr), payload (bstr) ].
+function _macStructure(protectedBstr, externalAad, payload) {
+  return cbor.encode(["MAC0", protectedBstr, externalAad, payload]);
+}
+
+/**
+ * @primitive b.cose.mac0
+ * @signature b.cose.mac0(payload, opts)
+ * @since     0.12.47
+ * @status    stable
+ * @related   b.cose.macVerify0, b.cose.sign
+ *
+ * Produce a tagged COSE_Mac0 (RFC 9052 §6.2) — a single shared-key MAC
+ * over <code>payload</code>. The MAC is HMAC-SHA-256 / 384 / 512 (the
+ * COSE-standard MAC algorithms; HMAC is symmetric, so post-quantum
+ * strength is preserved). Use when both parties hold a shared key (e.g.
+ * an ECDH-derived key) and a non-repudiable signature is not wanted.
+ * <code>detached: true</code> emits a nil payload, verified later with
+ * <code>opts.externalPayload</code>.
+ *
+ * @opts
+ *   {
+ *     alg:        string,   // "HMAC-256/256" | "HMAC-384/384" | "HMAC-512/512"
+ *     key:        Buffer,   // shared symmetric key
+ *     externalAad?: Buffer, // bound into the MAC
+ *     detached?:  boolean,  // emit a nil payload (caller re-supplies it on verify)
+ *     unprotectedHeaders?: object,
+ *   }
+ *
+ * @example
+ *   var mac = b.cose.mac0(Buffer.from("data"), { alg: "HMAC-256/256", key: sharedKey });
+ */
+function mac0(payload, opts) {
+  validateOpts.requireObject(opts, "cose.mac0", CoseError);
+  validateOpts(opts, ["alg", "key", "externalAad", "detached", "unprotectedHeaders"], "cose.mac0");
+  if (!(opts.alg in HMAC_NAME_TO_ID)) {
+    throw new CoseError("cose/unsignable-alg", "cose.mac0: alg must be one of " + Object.keys(HMAC_NAME_TO_ID).join(" / "));
+  }
+  var key = _bstr(opts.key);
+  var algId = HMAC_NAME_TO_ID[opts.alg];
+  var protMap = new Map();
+  protMap.set(HDR_ALG, algId);
+  var protectedBstr = cbor.encode(protMap);
+
+  var unprot = new Map();
+  if (opts.unprotectedHeaders && typeof opts.unprotectedHeaders === "object") {
+    var uk = Object.keys(opts.unprotectedHeaders);
+    for (var i = 0; i < uk.length; i++) unprot.set(Number(uk[i]), opts.unprotectedHeaders[uk[i]]);
+  }
+
+  var payloadBytes = _bstr(payload);
+  var externalAad = opts.externalAad == null ? Buffer.alloc(0) : _bstr(opts.externalAad);
+  var tag = nodeCrypto.createHmac(_hmacHash(algId), key).update(_macStructure(protectedBstr, externalAad, payloadBytes)).digest();
+
+  var mac0arr = [protectedBstr, unprot, opts.detached ? null : payloadBytes, tag];
+  return cbor.encode(new cbor.Tag(COSE_MAC0_TAG, mac0arr));
+}
+
+/**
+ * @primitive b.cose.macVerify0
+ * @signature b.cose.macVerify0(coseMac0, opts)
+ * @since     0.12.47
+ * @status    stable
+ * @related   b.cose.mac0
+ *
+ * Verify a COSE_Mac0 (RFC 9052 §6.2) and return its payload. The HMAC
+ * tag is recomputed over the MAC_structure and compared in constant
+ * time; the <code>alg</code> from the protected header must be in
+ * <code>opts.algorithms</code>. A detached (nil) payload is supplied via
+ * <code>opts.externalPayload</code>.
+ *
+ * @opts
+ *   {
+ *     algorithms:  string[],  // required — accepted HMAC alg names (allowlist)
+ *     key:         Buffer,    // the shared symmetric key
+ *     externalAad?: Buffer,
+ *     externalPayload?: Buffer, // required for a detached payload
+ *     maxBytes?:   number,
+ *     maxDepth?:   number,
+ *   }
+ *
+ * @example
+ *   var out = b.cose.macVerify0(mac, { algorithms: ["HMAC-256/256"], key: sharedKey });
+ *   // → { payload: <Buffer>, alg: "HMAC-256/256", protectedHeaders: Map, unprotectedHeaders: Map }
+ */
+function macVerify0(coseMac0, opts) {
+  validateOpts.requireObject(opts, "cose.macVerify0", CoseError);
+  validateOpts(opts, ["algorithms", "key", "externalAad", "externalPayload", "maxBytes", "maxDepth"], "cose.macVerify0");
+  if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
+    throw new CoseError("cose/algorithms-required", "cose.macVerify0: opts.algorithms is required");
+  }
+  for (var ai = 0; ai < opts.algorithms.length; ai++) {
+    if (!(opts.algorithms[ai] in HMAC_NAME_TO_ID)) {
+      throw new CoseError("cose/unknown-alg", "cose.macVerify0: unknown algorithm '" + opts.algorithms[ai] + "'");
+    }
+  }
+  if (opts.key == null) throw new CoseError("cose/no-key", "cose.macVerify0: opts.key is required");
+  var key = _bstr(opts.key);
+
+  var decoded = cbor.decode(_bstr(coseMac0), { allowedTags: [COSE_MAC0_TAG], maxBytes: opts.maxBytes, maxDepth: opts.maxDepth });
+  var arr = (decoded instanceof cbor.Tag && decoded.tag === COSE_MAC0_TAG) ? decoded.value : decoded;
+  if (!Array.isArray(arr) || arr.length !== 4) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: not a COSE_Mac0 (expected a 4-element array)");
+  }
+  var protectedBstr = arr[0];
+  var unprotected = arr[1];
+  var payload = arr[2];
+  var tag = arr[3];
+  if (!Buffer.isBuffer(protectedBstr) || !Buffer.isBuffer(tag)) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: protected header and tag must be byte strings");
+  }
+  if (!(unprotected instanceof Map)) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: unprotected header must be a CBOR map");
+  }
+  if (payload === null || payload === undefined) {
+    if (opts.externalPayload == null) {
+      throw new CoseError("cose/detached-no-payload", "cose.macVerify0: detached (nil) payload — pass opts.externalPayload");
+    }
+    payload = _bstr(opts.externalPayload);
+  } else if (opts.externalPayload != null) {
+    throw new CoseError("cose/payload-ambiguous", "cose.macVerify0: externalPayload supplied but the COSE_Mac0 carries an attached payload");
+  } else if (!Buffer.isBuffer(payload)) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: payload must be a byte string (bstr)");
+  }
+
+  var protMap = protectedBstr.length === 0 ? new Map()
+    : cbor.decode(protectedBstr, { maxBytes: opts.maxBytes, maxDepth: opts.maxDepth });
+  if (!(protMap instanceof Map)) {
+    throw new CoseError("cose/malformed", "cose.macVerify0: protected header is not a CBOR map");
+  }
+  // crit-bypass defense (RFC 9052 §3.1) — same as b.cose.verify: every
+  // label a crit array names must be one this verifier understands AND
+  // be present in the protected header.
+  if (protMap.has(HDR_CRIT)) {
+    var crit = protMap.get(HDR_CRIT);
+    if (!Array.isArray(crit)) {
+      throw new CoseError("cose/bad-crit", "cose.macVerify0: crit (label 2) must be an array");
+    }
+    for (var ci = 0; ci < crit.length; ci++) {
+      if (UNDERSTOOD_LABELS.indexOf(crit[ci]) === -1) {
+        throw new CoseError("cose/crit-unknown",
+          "cose.macVerify0: crit lists header label " + crit[ci] + " which is not understood (RFC 9052 §3.1)");
+      }
+      if (!protMap.has(crit[ci])) {
+        throw new CoseError("cose/crit-absent",
+          "cose.macVerify0: crit lists label " + crit[ci] + " not present in the protected header");
+      }
+    }
+  }
+  var algId = protMap.get(HDR_ALG);
+  var algName = HMAC_ID_TO_NAME[algId];
+  if (algName === undefined) {
+    throw new CoseError("cose/unknown-alg", "cose.macVerify0: unrecognized protected MAC alg id " + algId);
+  }
+  if (opts.algorithms.indexOf(algName) === -1) {
+    throw new CoseError("cose/alg-not-allowed", "cose.macVerify0: alg '" + algName + "' is not in the allowlist");
+  }
+
+  var externalAad = opts.externalAad == null ? Buffer.alloc(0) : _bstr(opts.externalAad);
+  var expected = nodeCrypto.createHmac(_hmacHash(algId), key).update(_macStructure(protectedBstr, externalAad, payload)).digest();
+  if (!bCrypto.timingSafeEqual(expected, tag)) {
+    throw new CoseError("cose/bad-tag", "cose.macVerify0: MAC tag verification failed");
+  }
+  return { payload: payload, alg: algName, protectedHeaders: protMap, unprotectedHeaders: unprotected };
+}
+
+// ---- COSE_Key (RFC 9052 §7 / RFC 9053 §7) → KeyObject ----
+
+// COSE_Key EC2 curve identifiers (RFC 9053 §7.1) → JWK crv names. Only
+// the curves b.cose.verify has an algorithm for are accepted: P-256
+// (ES256), P-384 (ES384), P-521 (ES512). secp256k1 is intentionally
+// absent — there is no ES256K path here, so importing one would let a
+// secp256k1 key be verified under ES256, breaking the COSE alg/curve
+// binding (RFC 9053). Re-add with an explicit ES256K algorithm.
+var COSE_EC2_CRV = { 1: "P-256", 2: "P-384", 3: "P-521" };
+var COSE_KTY_OKP = 1;
+var COSE_KTY_EC2 = 2;
+var COSE_OKP_ED25519 = 6;                                                    // allow:raw-byte-literal — COSE OKP Ed25519 crv id (RFC 9053)
+
+function _coseKeyBytes(v, what) {
+  if (Buffer.isBuffer(v)) return v;
+  if (v instanceof Uint8Array) return Buffer.from(v);
+  throw new CoseError("cose/bad-cose-key", "cose.importKey: COSE_Key " + what + " must be a byte string");
+}
+
+/**
+ * @primitive b.cose.importKey
+ * @signature b.cose.importKey(coseKey)
+ * @since     0.12.45
+ * @status    stable
+ * @related   b.cose.verify, b.cbor.decode
+ *
+ * Import a COSE_Key (RFC 9052 §7) — a CBOR map keyed by integer labels —
+ * as a <code>node:crypto</code> public KeyObject for
+ * <code>b.cose.verify</code>. Accepts the EC2 (<code>kty</code> 2:
+ * P-256 / P-384 / P-521) and OKP (<code>kty</code> 1: Ed25519) key
+ * types — the curves <code>b.cose.verify</code> has an algorithm for;
+ * the curve is allowlisted, so an unexpected key type (including
+ * secp256k1, which has no ES256K path here) is refused rather than
+ * imported. The verification key embedded in an mdoc MSO or a COSE_Key
+ * header is consumed this way.
+ *
+ * @example
+ *   var key = b.cose.importKey(coseKeyMap);            // → public KeyObject
+ *   var out = await b.cose.verify(sign1, { algorithms: ["ES256"], publicKey: key });
+ */
+function importKey(coseKey) {
+  if (!(coseKey instanceof Map)) {
+    if (coseKey && typeof coseKey === "object" && !Array.isArray(coseKey)) {
+      var m = new Map();
+      Object.keys(coseKey).forEach(function (k) { m.set(Number(k), coseKey[k]); });
+      coseKey = m;
+    } else {
+      throw new CoseError("cose/bad-cose-key", "cose.importKey: expected a COSE_Key map");
+    }
+  }
+  var kty = coseKey.get(1);
+  var x = _coseKeyBytes(coseKey.get(-2), "x");
+  var jwk;
+  if (kty === COSE_KTY_OKP) {
+    if (coseKey.get(-1) !== COSE_OKP_ED25519) {
+      throw new CoseError("cose/unsupported-key", "cose.importKey: only OKP curve Ed25519 is supported");
+    }
+    jwk = { kty: "OKP", crv: "Ed25519", x: x.toString("base64url") };
+  } else if (kty === COSE_KTY_EC2) {
+    var crvName = COSE_EC2_CRV[coseKey.get(-1)];
+    if (!crvName) throw new CoseError("cose/unsupported-key", "cose.importKey: unsupported EC2 curve id " + coseKey.get(-1));
+    var y = _coseKeyBytes(coseKey.get(-3), "y");
+    jwk = { kty: "EC", crv: crvName, x: x.toString("base64url"), y: y.toString("base64url") };
+  } else {
+    throw new CoseError("cose/unsupported-key", "cose.importKey: kty must be OKP (1) or EC2 (2), got " + kty);
+  }
+  try { return nodeCrypto.createPublicKey({ key: jwk, format: "jwk" }); }
+  catch (e) { throw new CoseError("cose/bad-cose-key", "cose.importKey: could not import COSE_Key: " + ((e && e.message) || e)); }
+}
+
 module.exports = {
   sign:        sign,
   verify:      verify,
   encrypt0:    encrypt0,
   decrypt0:    decrypt0,
+  mac0:        mac0,
+  macVerify0:  macVerify0,
+  importKey:   importKey,
   ALGORITHMS:  ALG_NAME_TO_ID,
+  MAC_ALGORITHMS: HMAC_NAME_TO_ID,
+  COSE_MAC0_TAG: COSE_MAC0_TAG,
   AEAD_ALGORITHMS: AEAD_NAME_TO_ID,
   COSE_SIGN1_TAG: COSE_SIGN1_TAG,
   COSE_ENCRYPT0_TAG: COSE_ENCRYPT0_TAG,

package/lib/vendor/blamejs/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,