@blamejs/core 0.12.41 → 0.12.43

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.12.40 (2026-05-24) — **`b.mdoc` — ISO 18013-5 mdoc / mDL issuer-data verification.** Verify the issuer-signed data of an ISO/IEC 18013-5 mdoc — the credential format behind mobile driving licences (mDL) and the ISO track of the EU Digital Identity Wallet. This is the relying-party side: confirm that the data elements a holder presents were signed by the issuer and have not been altered. An mdoc's IssuerSigned carries the disclosed data elements and an issuerAuth that is a COSE_Sign1 (b.cose) over a Mobile Security Object (MSO) holding a per-element digest. b.mdoc.verifyIssuerSigned verifies the COSE signature with the issuer certificate from the COSE x5chain header, parses the MSO, enforces its validityInfo window, and recomputes each disclosed element's digest (the full Tag-24 IssuerSignedItemBytes) to match it against the MSO constant-time — the integrity check that makes selective disclosure trustworthy. An absent or mismatched digest is refused. Signing algorithms follow b.cose verification (the classical ES256/384/512 + EdDSA that real mDL issuers use; the caller names the allowlist); opts.trustAnchorsPem additionally verifies the issuer certificate chain. This completes the credential trio alongside W3C VCDM (b.vc) and IETF SD-JWT VC (b.auth.sdJwtVc). Composes b.cose + b.cbor; no new runtime dependency. **Added:** *`b.mdoc.verifyIssuerSigned(issuerSigned, opts)`* — Takes the CBOR `IssuerSigned` map (the operator extracts it from the device response / QR) and returns `{ docType, version, digestAlgorithm, validityInfo, namespaces, signerCert, alg }`. Verifies the COSE_Sign1 `issuerAuth` against the mandatory `opts.algorithms` allowlist using the issuer certificate from its `x5chain` (label 33) header; parses the Tag-24 Mobile Security Object; enforces the MSO `validityInfo` window against `opts.at` (default now; must be a valid Date; malformed dates fail closed); and recomputes the digest of every disclosed `IssuerSignedItem` (over the full Tag-24 bytes, with the MSO `digestAlgorithm` — SHA-256/384/512) to match the MSO `valueDigests` constant-time — an absent or mismatched digest is refused with `mdoc/digest-mismatch`. `opts.expectedDocType` pins the document type; `opts.trustAnchorsPem` (a PEM string or array) additionally verifies the issuer certificate chain and validity at the asserted time. A malformed `x5chain` certificate is refused with a clean `mdoc/bad-cert`. The mdoc device-authentication half (the SessionTranscript-bound holder-binding proof) is a presentation-protocol concern and is not part of issuer-data verification.

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`)
@@ -131,7 +132,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Entity Attestation Token** — `b.eat` EAT sign/verify (RFC 9711) over `b.cwt`: device + software attestation claims (ueid / oemid / hwmodel / measurements / submods) with verifier-nonce freshness binding, `dbgstat` debug-status policy, and `eat_profile` pinning
 - **SCITT signed statements** — `b.scitt` sign/verify a signed, attributable claim about an artifact (signed SBOM, build attestation, release approval) over `b.cose`: the issuer + subject bind in the integrity-protected CWT_Claims header (RFC 9597); verification refuses any statement missing the iss/sub binding. The issuer side, on finalized RFCs; the transparency receipt (COSE Receipts draft) opts in on publication
 - **Trusted timestamping** — `b.tsa` RFC 3161 timestamp client: `buildRequest` a TimeStampReq, `parseResponse`, and `verifyToken` against your data — the message imprint, sent nonce, critical/sole `id-kp-timeStamping` EKU, and CMS signature are all checked, with optional certificate-chain verification. Timestamp a release artifact, audit checkpoint, or signed statement against any RFC 3161 TSA. Composes `b.cms` + the in-tree ASN.1 DER codec
-- **Verifiable Credentials** — `b.vc` W3C Verifiable Credentials Data Model 2.0 (VC-JOSE-COSE): `issue` / `verify` a signed credential as a compact JWS (`vc+jwt`, ES256/384/512 + EdDSA) or a COSE_Sign1 (`vc+cose`, + ML-DSA-87) over `b.cose`. VCDM structural + `validFrom`/`validUntil` checks; the JOSE `none` algorithm is always refused. The W3C model, distinct from the IETF SD-JWT VC at `b.auth.sdJwtVc`
+- **Verifiable Credentials** — `b.vc` W3C Verifiable Credentials Data Model 2.0 (VC-JOSE-COSE): `issue` / `verify` a signed credential, and `present` / `verifyPresentation` a holder-signed Verifiable Presentation wrapping credentials (with `nonce`/`audience` holder-binding) — as a compact JWS (`vc+jwt` / `vp+jwt`, ES256/384/512 + EdDSA) or a COSE_Sign1 (`vc+cose` / `vp+cose`, + ML-DSA-87) over `b.cose`. VCDM structural + `validFrom`/`validUntil` checks; the JOSE `none` algorithm is always refused. The W3C model, distinct from the IETF SD-JWT VC at `b.auth.sdJwtVc`
 - **Mobile credentials (mDL)** — `b.mdoc` ISO/IEC 18013-5 issuer-data verification: `verifyIssuerSigned` checks the COSE_Sign1 IssuerAuth (issuer cert from the `x5chain` header), the Mobile Security Object validity window, and every disclosed element's digest against the MSO `valueDigests` (the selective-disclosure integrity check), with optional issuer-chain verification. The ISO credential ecosystem alongside `b.vc` and `b.auth.sdJwtVc`. Composes `b.cose` + `b.cbor`
 - **Decentralized Identifiers** — `b.did` W3C DID resolution (DID Core 1.0): `resolve` a `did:key` (deterministic, offline — Ed25519 / P-256 / P-384 / secp256k1) or `did:web` (operator-fetched document) to `node:crypto` verification keys, so a credential's issuer DID resolves to the key that verifies it (`b.vc` / `b.mdoc` / `b.scitt`). `keyToDid` names a key as a `did:key`; document JWKs are kty/crv-allowlisted before import
 - **Document parsers** — `b.parsers` (XML / TOML / YAML / .env); `b.config` (schema-validated env)

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/lib/vc.js

@@ -51,6 +51,11 @@ var VCDM_V2_CONTEXT = "https://www.w3.org/ns/credentials/v2";
 var JOSE_TYP = "vc+jwt";
 var COSE_TYP = "application/vc+cose";
 var COSE_CONTENT_TYPE = "application/vc";
+var VP_JOSE_TYP = "vp+jwt";
+var VP_COSE_TYP = "application/vp+cose";
+var VP_COSE_CONTENT_TYPE = "application/vp";
+var MAX_PRESENTATION_CREDENTIALS = 64;                 // allow:raw-byte-literal — bounded count of enveloped VCs per presentation
+var ENVELOPED_VC_TYPE = "EnvelopedVerifiableCredential";
 var HDR_COSE_TYP = 16;                                 // allow:raw-byte-literal — COSE "typ" header label (RFC 9596)
 
 // JOSE signature algorithms (final RFC 7518 / 8037), mapped to node
@@ -165,36 +170,43 @@ async function issue(credential, opts) {
   _validateVcdm(credential, null);
   if (!opts.privateKey) throw new VcError("vc/no-key", "vc.issue: opts.privateKey is required");
 
+  return _sign(credential, opts, JOSE_TYP, COSE_TYP, COSE_CONTENT_TYPE, "vc.issue");
+}
+
+// Secure a JSON document (credential or presentation) as a compact JWS
+// (jose) or COSE_Sign1 (cose) with the given media-type headers. The
+// document is the exact signed payload — no claims wrapper.
+function _sign(doc, opts, joseTyp, coseTyp, coseContentType, fnName) {
   if (opts.securing === "cose") {
     var protectedHeaders = {};
-    protectedHeaders[HDR_COSE_TYP] = COSE_TYP;
-    return cose.sign(Buffer.from(JSON.stringify(credential), "utf8"), {
+    protectedHeaders[HDR_COSE_TYP] = coseTyp;
+    return cose.sign(Buffer.from(JSON.stringify(doc), "utf8"), {
       alg:              opts.alg,
       privateKey:       opts.privateKey,
       kid:              opts.kid,
-      contentType:      COSE_CONTENT_TYPE,
+      contentType:      coseContentType,
       protectedHeaders: protectedHeaders,
     });
   }
   if (opts.securing === "jose") {
     var params = JOSE_ALGS[opts.alg];
     if (!params) {
-      throw new VcError("vc/bad-alg", "vc.issue: JOSE securing requires alg ES256/384/512 or EdDSA (got " + opts.alg + ")");
+      throw new VcError("vc/bad-alg", fnName + ": JOSE securing requires alg ES256/384/512 or EdDSA (got " + opts.alg + ")");
     }
     var key = _toKey(opts.privateKey, "private");
-    var header = { alg: opts.alg, typ: JOSE_TYP };
+    var header = { alg: opts.alg, typ: joseTyp };
     if (typeof opts.kid === "string") header.kid = opts.kid;
     if (typeof opts.cty === "string") header.cty = opts.cty;
-    var signingInput = _b64urlJson(header) + "." + _b64urlJson(credential);
+    var signingInput = _b64urlJson(header) + "." + _b64urlJson(doc);
     var sig = params.nodeHash === null
       ? nodeCrypto.sign(null, Buffer.from(signingInput, "ascii"), key)
       : nodeCrypto.sign(params.nodeHash, Buffer.from(signingInput, "ascii"), { key: key, dsaEncoding: params.dsaEncoding });
     return signingInput + "." + sig.toString("base64url");
   }
-  throw new VcError("vc/bad-securing", "vc.issue: securing must be 'jose' or 'cose'");
+  throw new VcError("vc/bad-securing", fnName + ": securing must be 'jose' or 'cose'");
 }
 
-function _verifyJose(token, opts) {
+function _verifyJose(token, opts, expectedTyp) {
   var parts = token.split(".");
   if (parts.length !== 3) {
     throw new VcError("vc/malformed", "vc.verify: not a compact JWS (expected three dot-separated segments)");
@@ -202,8 +214,8 @@ function _verifyJose(token, opts) {
   var header;
   try { header = safeJson.parse(Buffer.from(parts[0], "base64url").toString("utf8")); }
   catch (_e) { throw new VcError("vc/malformed", "vc.verify: JWS header is not valid base64url-JSON"); }
-  if (!header || header.typ !== JOSE_TYP) {
-    throw new VcError("vc/bad-typ", "vc.verify: JWS typ must be '" + JOSE_TYP + "'");
+  if (!header || header.typ !== expectedTyp) {
+    throw new VcError("vc/bad-typ", "vc.verify: JWS typ must be '" + expectedTyp + "'");
   }
   // crit-bypass defense (RFC 7515 §4.1.11): a `crit` header marks
   // extensions the verifier MUST understand and process. This verifier
@@ -228,16 +240,16 @@ function _verifyJose(token, opts) {
     ? nodeCrypto.verify(null, Buffer.from(signingInput, "ascii"), pub, sig)
     : nodeCrypto.verify(params.nodeHash, Buffer.from(signingInput, "ascii"), { key: pub, dsaEncoding: params.dsaEncoding }, sig);
   if (!ok) throw new VcError("vc/bad-signature", "vc.verify: JWS signature did not verify");
-  var credential;
-  try { credential = safeJson.parse(Buffer.from(parts[1], "base64url").toString("utf8")); }
+  var payload;
+  try { payload = safeJson.parse(Buffer.from(parts[1], "base64url").toString("utf8")); }
   catch (_e) { throw new VcError("vc/malformed", "vc.verify: JWS payload is not valid base64url-JSON"); }
-  return { credential: credential, alg: header.alg };
+  return { payload: payload, alg: header.alg };
 }
 
-async function _verifyCose(bytes, opts) {
+async function _verifyCose(bytes, opts, expectedTyp) {
   var algorithms = opts.algorithms.filter(function (a) { return a in cose.ALGORITHMS; });
   if (!algorithms.length) {
-    throw new VcError("vc/no-cose-alg", "vc.verify: opts.algorithms has no COSE algorithm for a vc+cose credential");
+    throw new VcError("vc/no-cose-alg", "vc.verify: opts.algorithms has no COSE algorithm for a COSE-secured credential");
   }
   var out = await cose.verify(bytes, {
     algorithms:  algorithms,
@@ -245,13 +257,25 @@ async function _verifyCose(bytes, opts) {
     keyResolver: opts.keyResolver,
   });
   var typ = out.protectedHeaders.get(HDR_COSE_TYP);
-  if (typ !== undefined && typ !== COSE_TYP) {
-    throw new VcError("vc/bad-typ", "vc.verify: COSE typ header is '" + typ + "', expected '" + COSE_TYP + "'");
+  if (typ !== undefined && typ !== expectedTyp) {
+    throw new VcError("vc/bad-typ", "vc.verify: COSE typ header is '" + typ + "', expected '" + expectedTyp + "'");
   }
-  var credential;
-  try { credential = safeJson.parse(out.payload.toString("utf8")); }
+  var payload;
+  try { payload = safeJson.parse(out.payload.toString("utf8")); }
   catch (_e) { throw new VcError("vc/malformed", "vc.verify: COSE payload is not valid JSON"); }
-  return { credential: credential, alg: out.alg };
+  return { payload: payload, alg: out.alg };
+}
+
+// Verify a secured JSON document (the JOSE/COSE envelope) → { payload,
+// alg, securing }. Shared by credential + presentation verification.
+async function _verifySecured(secured, opts, joseTyp, coseTyp) {
+  if (typeof secured === "string") {
+    return Object.assign({ securing: "jose" }, _verifyJose(secured, opts, joseTyp));
+  }
+  if (Buffer.isBuffer(secured) || secured instanceof Uint8Array) {
+    return Object.assign({ securing: "cose" }, await _verifyCose(Buffer.from(secured), opts, coseTyp));
+  }
+  throw new VcError("vc/bad-input", "vc.verify: secured must be a compact-JWS string or COSE_Sign1 bytes");
 }
 
 /**
@@ -300,28 +324,202 @@ async function verify(secured, opts) {
     at = opts.at;
   }
 
-  var securing, result;
-  if (typeof secured === "string") {
-    securing = "jose";
-    result = _verifyJose(secured, opts);
-  } else if (Buffer.isBuffer(secured) || secured instanceof Uint8Array) {
-    securing = "cose";
-    result = await _verifyCose(Buffer.from(secured), opts);
-  } else {
-    throw new VcError("vc/bad-input", "vc.verify: secured must be a compact-JWS string or COSE_Sign1 bytes");
-  }
+  var result = await _verifySecured(secured, opts, JOSE_TYP, COSE_TYP);
 
-  _validateVcdm(result.credential, { temporal: true, at: at });
-  var issuer = _issuerId(result.credential);
+  _validateVcdm(result.payload, { temporal: true, at: at });
+  var issuer = _issuerId(result.payload);
   if (opts.expectedIssuer !== undefined && issuer !== opts.expectedIssuer) {
     throw new VcError("vc/issuer-mismatch", "vc.verify: credential issuer does not match expectedIssuer");
   }
-  return { credential: result.credential, securing: securing, alg: result.alg, issuer: issuer };
+  return { credential: result.payload, securing: result.securing, alg: result.alg, issuer: issuer };
+}
+
+// VCDM 2.0 presentation structural rules.
+function _validateVp(vp) {
+  if (!vp || typeof vp !== "object" || Array.isArray(vp)) {
+    throw new VcError("vc/bad-presentation", "vc: presentation must be a JSON object");
+  }
+  var ctx = vp["@context"];
+  if (!Array.isArray(ctx) || ctx[0] !== VCDM_V2_CONTEXT) {
+    throw new VcError("vc/bad-context", "vc: presentation @context must start with '" + VCDM_V2_CONTEXT + "'");
+  }
+  var types = Array.isArray(vp.type) ? vp.type : [vp.type];
+  if (types.indexOf("VerifiablePresentation") === -1) {
+    throw new VcError("vc/bad-type", "vc: type must include 'VerifiablePresentation'");
+  }
+  // verifiableCredential, when present, MUST be an array — a non-array
+  // value must fail closed rather than coerce to empty (which would let
+  // a holder bypass credential verification with a malformed container).
+  if (vp.verifiableCredential !== undefined && !Array.isArray(vp.verifiableCredential)) {
+    throw new VcError("vc/bad-presentation", "vc: verifiableCredential must be an array");
+  }
+}
+
+// An enveloped VC (VC-JOSE-COSE §enveloping): a data: URI whose media
+// type selects the securing and whose body is the secured credential.
+function _envelopeVc(securedVc) {
+  if (typeof securedVc === "string") {
+    return { "@context": [VCDM_V2_CONTEXT], type: ENVELOPED_VC_TYPE, id: "data:application/vc+jwt," + securedVc };
+  }
+  if (Buffer.isBuffer(securedVc) || securedVc instanceof Uint8Array) {
+    return { "@context": [VCDM_V2_CONTEXT], type: ENVELOPED_VC_TYPE,
+      id: "data:application/vc+cose;base64," + Buffer.from(securedVc).toString("base64") };
+  }
+  throw new VcError("vc/bad-credential", "vc.present: each credential must be a compact-JWS string or COSE_Sign1 bytes");
+}
+
+function _parseEnvelopedVc(entry) {
+  if (!entry || typeof entry !== "object" || entry.type !== ENVELOPED_VC_TYPE || typeof entry.id !== "string") {
+    throw new VcError("vc/bad-enveloped", "vc.verifyPresentation: verifiableCredential entries must be EnvelopedVerifiableCredential data: URIs");
+  }
+  var comma = entry.id.indexOf(",");
+  if (entry.id.indexOf("data:") !== 0 || comma === -1) {
+    throw new VcError("vc/bad-enveloped", "vc.verifyPresentation: enveloped credential id is not a data: URI");
+  }
+  var meta = entry.id.slice("data:".length, comma);
+  var body = entry.id.slice(comma + 1);
+  if (meta.indexOf("application/vc+cose") === 0) return Buffer.from(body, "base64");
+  if (meta.indexOf("application/vc+jwt") === 0) return body;
+  throw new VcError("vc/bad-enveloped", "vc.verifyPresentation: unsupported enveloped media type '" + meta + "'");
+}
+
+/**
+ * @primitive b.vc.present
+ * @signature b.vc.present(opts)
+ * @since     0.12.42
+ * @status    experimental
+ * @compliance gdpr, soc2
+ * @related   b.vc.verifyPresentation, b.vc.issue
+ *
+ * Build and sign a W3C Verifiable Presentation: a holder-signed envelope
+ * wrapping one or more secured credentials (each enveloped per
+ * VC-JOSE-COSE). <code>securing</code> and the algorithms match
+ * <code>b.vc.issue</code> (compact JWS <code>vp+jwt</code>, or COSE_Sign1
+ * <code>application/vp+cose</code>). Supply <code>nonce</code> /
+ * <code>audience</code> for holder-binding / replay protection — they
+ * are embedded in the signed presentation and checked at verification.
+ *
+ * @opts
+ *   {
+ *     credentials: array,    // secured VCs (compact-JWS strings or COSE_Sign1 bytes)
+ *     holder:      string,   // the presenter (a DID or other id)
+ *     securing:    string,   // "jose" | "cose"
+ *     alg:         string,   // JOSE: ES256/384/512 | EdDSA. COSE: + ML-DSA-87
+ *     privateKey:  object,   // the holder's key
+ *     kid:         string,   // optional key id
+ *     nonce:       string,   // optional verifier challenge (embedded + checked)
+ *     audience:    string,   // optional intended verifier (embedded + checked)
+ *   }
+ *
+ * @example
+ *   var vp = await b.vc.present({ credentials: [jws], holder: holderDid, securing: "jose", alg: "ES256", privateKey: holderKey, nonce: challenge });
+ */
+async function present(opts) {
+  validateOpts.requireObject(opts, "vc.present", VcError);
+  validateOpts(opts, ["credentials", "holder", "securing", "alg", "privateKey", "kid", "nonce", "audience"], "vc.present");
+  if (!Array.isArray(opts.credentials) || opts.credentials.length === 0) {
+    throw new VcError("vc/no-credentials", "vc.present: opts.credentials must be a non-empty array");
+  }
+  if (opts.credentials.length > MAX_PRESENTATION_CREDENTIALS) {
+    throw new VcError("vc/too-many-credentials", "vc.present: at most " + MAX_PRESENTATION_CREDENTIALS + " credentials per presentation");
+  }
+  if (typeof opts.holder !== "string" || !opts.holder) {
+    throw new VcError("vc/no-holder", "vc.present: opts.holder is required (the presenter id / DID)");
+  }
+  if (!opts.privateKey) throw new VcError("vc/no-key", "vc.present: opts.privateKey is required");
+
+  var vp = {
+    "@context": [VCDM_V2_CONTEXT],
+    type: ["VerifiablePresentation"],
+    holder: opts.holder,
+    verifiableCredential: opts.credentials.map(_envelopeVc),
+  };
+  if (typeof opts.nonce === "string") vp.nonce = opts.nonce;
+  if (typeof opts.audience === "string") vp.audience = opts.audience;
+
+  return _sign(vp, opts, VP_JOSE_TYP, VP_COSE_TYP, VP_COSE_CONTENT_TYPE, "vc.present");
+}
+
+/**
+ * @primitive b.vc.verifyPresentation
+ * @signature b.vc.verifyPresentation(secured, opts)
+ * @since     0.12.42
+ * @status    experimental
+ * @compliance gdpr, soc2
+ * @related   b.vc.present, b.vc.verify
+ *
+ * Verify a Verifiable Presentation: the holder signature (auto-detected
+ * jose / cose, mandatory algorithm allowlist, JOSE <code>none</code>
+ * refused), the VCDM structure, and the embedded <code>nonce</code> /
+ * <code>audience</code> / <code>expectedHolder</code> when given. With
+ * <code>verifyCredentials: true</code> each enveloped credential is
+ * verified through <code>b.vc.verify</code> (using
+ * <code>opts.credentialOpts</code>) and returned.
+ *
+ * @opts
+ *   {
+ *     algorithms:      string[],  // required — holder-signature alg allowlist
+ *     publicKey:       object,    // the holder verification key
+ *     keyResolver:     function,  // (header) → holder key
+ *     expectedHolder:  string,    // require presentation holder to match
+ *     nonce:           string,    // require embedded nonce to match
+ *     audience:        string,    // require embedded audience to match
+ *     verifyCredentials: boolean, // verify each enveloped VC via b.vc.verify
+ *     credentialOpts:  object,    // opts passed to b.vc.verify for each VC
+ *   }
+ *
+ * @example
+ *   var out = await b.vc.verifyPresentation(vp, {
+ *     algorithms: ["ES256"], publicKey: holderKey, nonce: challenge,
+ *     verifyCredentials: true, credentialOpts: { algorithms: ["ES256"], publicKey: issuerKey },
+ *   });
+ *   // → { presentation, holder, credentials: [verified VCs], securing, alg }
+ */
+async function verifyPresentation(secured, opts) {
+  validateOpts.requireObject(opts, "vc.verifyPresentation", VcError);
+  validateOpts(opts, ["algorithms", "publicKey", "keyResolver", "expectedHolder", "nonce", "audience", "verifyCredentials", "credentialOpts"], "vc.verifyPresentation");
+  if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
+    throw new VcError("vc/algorithms-required", "vc.verifyPresentation: opts.algorithms is required");
+  }
+  if (!opts.publicKey && typeof opts.keyResolver !== "function") {
+    throw new VcError("vc/no-key", "vc.verifyPresentation: pass publicKey or keyResolver");
+  }
+
+  var result = await _verifySecured(secured, opts, VP_JOSE_TYP, VP_COSE_TYP);
+  var vp = result.payload;
+  _validateVp(vp);
+
+  if (opts.expectedHolder !== undefined && vp.holder !== opts.expectedHolder) {
+    throw new VcError("vc/holder-mismatch", "vc.verifyPresentation: presentation holder does not match expectedHolder");
+  }
+  if (opts.nonce !== undefined && vp.nonce !== opts.nonce) {
+    throw new VcError("vc/nonce-mismatch", "vc.verifyPresentation: presentation nonce does not match");
+  }
+  if (opts.audience !== undefined && vp.audience !== opts.audience) {
+    throw new VcError("vc/audience-mismatch", "vc.verifyPresentation: presentation audience does not match");
+  }
+
+  var entries = vp.verifiableCredential || [];   // _validateVp guarantees array-or-absent
+  if (entries.length > MAX_PRESENTATION_CREDENTIALS) {
+    throw new VcError("vc/too-many-credentials", "vc.verifyPresentation: presentation carries more than " + MAX_PRESENTATION_CREDENTIALS + " credentials");
+  }
+  var credentials = [];
+  if (opts.verifyCredentials) {
+    var credOpts = opts.credentialOpts;
+    validateOpts.requireObject(credOpts, "vc.verifyPresentation.credentialOpts", VcError);
+    for (var i = 0; i < entries.length; i += 1) {
+      credentials.push(await verify(_parseEnvelopedVc(entries[i]), credOpts));
+    }
+  }
+
+  return { presentation: vp, holder: vp.holder, credentials: credentials, securing: result.securing, alg: result.alg };
 }
 
 module.exports = {
   issue:          issue,
   verify:         verify,
+  present:        present,
+  verifyPresentation: verifyPresentation,
   JOSE_ALGS:      JOSE_ALGS,
   VCDM_V2_CONTEXT: VCDM_V2_CONTEXT,
   VcError:        VcError,

package/package.json

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