@blamejs/core 0.12.38 → 0.12.39

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.39 (2026-05-24) — **`b.vc` — W3C Verifiable Credentials 2.0 (issue / verify, JOSE + COSE securing).** Issue and verify W3C Verifiable Credentials (VC Data Model 2.0, a W3C Recommendation) secured per Securing Verifiable Credentials using JOSE and COSE (VC-JOSE-COSE, also a W3C Recommendation, May 2025). A verifiable credential is a tamper-evident, signed set of claims an issuer makes about a subject — a diploma, a membership, a license, an age assertion. Two securing mechanisms are supported, both signing the credential itself (no JWT/CWT claims wrapper): JOSE produces a compact JWS with the vc+jwt media type, signed with ES256/384/512 or EdDSA; COSE produces a COSE_Sign1 (application/vc+cose) over b.cose, which also accepts ML-DSA-87 for PQC-forward deployments. b.vc.verify auto-detects the form from the input, requires an algorithm allowlist, always refuses the JOSE none algorithm, re-checks the VCDM 2.0 structural rules, and enforces the validFrom / validUntil window. This is the W3C credential model, distinct from the IETF SD-JWT VC already at b.auth.sdJwtVc. Composes b.cose; no new runtime dependency. **Added:** *`b.vc.issue(credential, opts)` / `b.vc.verify(secured, opts)`* — `issue` validates the credential against the VCDM 2.0 structural rules (the `credentials/v2` context first, a `VerifiableCredential` type, an issuer, a credential subject) and signs it: `securing: "jose"` returns a compact JWS string (`typ` header `vc+jwt`), `securing: "cose"` returns COSE_Sign1 bytes (`typ` header `application/vc+cose`, content type `application/vc`) via `b.cose`. The credential is the exact signed payload — no JWT/CWT claims are injected. `verify` auto-detects the securing form from the input (compact-JWS string vs. COSE_Sign1 bytes), verifies the signature against the mandatory `opts.algorithms` allowlist (the JOSE `none` algorithm is always refused), re-checks the structural rules, enforces the `validFrom` / `validUntil` window against `opts.at` (default now; must be a valid Date), and optionally matches `opts.expectedIssuer` against the credential issuer id. Returns `{ credential, securing, alg, issuer }`.
+
 - v0.12.38 (2026-05-24) — **`b.tsa` — RFC 3161 trusted timestamping client (build / parse / verify).** A timestamp authority binds a hash of your data to a trusted time, producing a token that proves the data existed at that instant — timestamp a release artifact, an audit-log checkpoint, a b.scitt signed statement, or a contract. b.tsa is the requester/verifier side of RFC 3161: buildRequest produces the DER TimeStampReq (the message imprint plus an optional nonce and a cert request), parseResponse reads the TimeStampResp (PKIStatus, failure-info bits, and the token), and verifyToken checks a token against your data and returns the asserted time. Verification is done in full per §2.4.2 / §2.3: the token is a CMS SignedData (b.cms) whose eContentType must be id-ct-TSTInfo; the message imprint must equal the hash of your data (constant-time); a sent nonce must round-trip; the signer certificate's extendedKeyUsage must be a critical, sole id-kp-timeStamping; and the CMS signature over the signed attributes must verify after the messageDigest attribute is matched to the recomputed eContent digest. An optional trust-anchor set verifies the certificate chain and validity at the asserted time. The HTTP transport to the TSA is the operator's to make. Composes b.cms and the in-tree ASN.1 DER codec; no new runtime dependency. **Added:** *`b.tsa.buildRequest(data, opts?)` / `b.tsa.parseResponse(der)` / `b.tsa.verifyToken(token, opts)`* — `buildRequest` returns `{ der, nonce, hashAlg, messageImprint }`; the imprint hash defaults to SHA-512 and may be SHA-256/384/512 or SHA3-256/512, a random 64-bit nonce and a certificate request are included by default, and a pre-hashed input is accepted with `hashed: true`. `parseResponse` returns `{ granted, status, statusString, failInfo, token }`, decoding the PKIFailureInfo bits for a non-granted response rather than throwing. `verifyToken` enforces the imprint match (`opts.data` or `opts.hash`), the nonce round-trip, the critical/sole `id-kp-timeStamping` EKU, and the CMS signature, returning `{ genTime, policy, serialHex, accuracy, hashAlg, signerCertPem }`; pass `opts.trustAnchorsPem` to also verify the certificate chain and validity at the asserted time. Timestamp tokens are third-party artifacts, so verification accepts the classical RSA (PKCS#1 v1.5 and PSS) and ECDSA-over-SHA-2 signatures that public TSAs emit — the same consume-what-exists posture as `b.cose` verification, not a framework signing default.
 
 - v0.12.37 (2026-05-24) — **`b.scitt.signStatement` / `b.scitt.verifyStatement` — SCITT signed statements over COSE (RFC 9052 + RFC 9597).** A SCITT signed statement is a signed, attributable claim about an artifact — a signed SBOM, a build attestation, a release approval. It is a COSE_Sign1 (b.cose) whose integrity-protected CWT_Claims header (label 15, RFC 9597) binds the issuer (who makes the statement) and the subject (the artifact it is about); the artifact, or a hash/reference to it, is the payload. signStatement places iss/sub in the protected header and declares the payload media type; verifyStatement checks the COSE signature (the algorithm allowlist is mandatory) and refuses any statement that lacks the iss/sub binding, with optional expected-issuer/subject matching. Signing uses the same algorithms as b.cose — classical ES256/384/512 + EdDSA (final COSE ids, interoperable today) plus ML-DSA-87 (PQC-forward). This is the issuer side of SCITT, buildable today on finalized RFCs; the transparency receipt (an inclusion proof from a transparency service, the COSE Receipts draft) is not yet shipped — a statement produced here is the input a transparency service registers, and the receipt format is the part still in flux. It opts in when COSE Receipts publishes. **Added:** *`b.scitt.signStatement(payload, opts)` / `b.scitt.verifyStatement(statement, opts)`* — `signStatement` produces a COSE_Sign1 whose protected CWT_Claims header (label 15) carries `iss` (`opts.issuer`) and `sub` (`opts.subject`), with the payload media type declared via `opts.contentType` and extra CWT claims allowed by integer label (iss/sub cannot be overridden through `opts.claims`). `verifyStatement` verifies the signature through `b.cose.verify` (passing `opts.algorithms` as the mandatory allowlist), then requires a CWT_Claims header with both `iss` and `sub` — a bare COSE_Sign1 with no such binding is refused with `scitt/missing-cwt-claims` — and enforces `expectedIssuer` / `expectedSubject` when given. Returns `{ payload, issuer, subject, cwtClaims, alg, protectedHeaders, unprotectedHeaders }`. Because the identity binding lives in the integrity-protected header it is covered by the signature and cannot be substituted without detection. **Changed:** *`b.cose.sign` accepts `protectedHeaders` and a media-type-string `contentType`* — `opts.protectedHeaders` (a numeric-keyed object or Map) adds extra integrity-protected header parameters — the CWT_Claims map (label 15) is the SCITT case. Label 1 (alg) is reserved and managed via `opts.alg`; setting it through `protectedHeaders` is refused with `cose/reserved-header`. `opts.contentType` now accepts a media-type string (RFC 9052 §3.1 tstr form, e.g. `"application/spdx+json"`) in addition to a CoAP Content-Format uint; a string was previously dropped.

package/README.md

@@ -131,6 +131,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`
 - **Document parsers** — `b.parsers` (XML / TOML / YAML / .env); `b.config` (schema-validated env)
 - **File-type detection** — `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.)
 ### Content-safety gates

package/index.js

@@ -461,6 +461,7 @@ module.exports = {
   eat:              require("./lib/eat"),
   scitt:            require("./lib/scitt"),
   tsa:              require("./lib/tsa"),
+  vc:               require("./lib/vc"),
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/vc.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * @module b.vc
+ * @nav    Crypto
+ * @title  Verifiable Credentials (W3C VCDM 2.0)
+ *
+ * @intro
+ *   Issue and verify W3C Verifiable Credentials (VC Data Model 2.0, a
+ *   W3C Recommendation) secured per "Securing Verifiable Credentials
+ *   using JOSE and COSE" (VC-JOSE-COSE, also a W3C Recommendation). A
+ *   verifiable credential is a tamper-evident, cryptographically-signed
+ *   set of claims an issuer makes about a subject — a diploma, a
+ *   membership, a license, an age assertion.
+ *
+ *   Two securing mechanisms are supported, both putting the credential
+ *   itself (not a JWT/CWT claims wrapper) as the signed payload:
+ *   <strong>JOSE</strong> produces a compact JWS with the <code>vc+jwt</code>
+ *   media type (<code>typ</code> header <code>"vc+jwt"</code>), signed
+ *   with the classical ES256 / 384 / 512 or EdDSA JOSE algorithms;
+ *   <strong>COSE</strong> produces a COSE_Sign1 (<code>application/vc+cose</code>)
+ *   over <code>b.cose</code>, adding ML-DSA-87 (PQC-forward) to that set.
+ *   <code>b.vc.verify</code> auto-detects the form from the input (a
+ *   compact-JWS string vs. COSE_Sign1 bytes).
+ *
+ *   <code>b.vc.issue(credential, opts)</code> validates the credential
+ *   against the VCDM 2.0 structural rules (the <code>credentials/v2</code>
+ *   context first, a <code>VerifiableCredential</code> type, an issuer,
+ *   a credential subject) and signs it. <code>b.vc.verify(secured, opts)</code>
+ *   verifies the signature (the algorithm allowlist is mandatory; the
+ *   JOSE <code>none</code> algorithm is always refused), re-checks the
+ *   structural rules, and enforces the <code>validFrom</code> /
+ *   <code>validUntil</code> validity window. This is the W3C model and
+ *   is distinct from the IETF SD-JWT VC at <code>b.auth.sdJwtVc</code>.
+ *
+ * @card
+ *   W3C Verifiable Credentials 2.0 (VC-JOSE-COSE) — issue / verify a
+ *   signed credential as a compact JWS (vc+jwt) or a COSE_Sign1
+ *   (vc+cose), with VCDM structural + validity-window checks. Composes
+ *   b.cose; the JOSE alg `none` is always refused.
+ */
+
+var nodeCrypto = require("node:crypto");
+var cose = require("./cose");
+var safeJson = require("./safe-json");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var VcError = defineClass("VcError", { alwaysPermanent: true });
+
+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 HDR_COSE_TYP = 16;                                 // allow:raw-byte-literal — COSE "typ" header label (RFC 9596)
+
+// JOSE signature algorithms (final RFC 7518 / 8037), mapped to node
+// verify parameters. ECDSA uses the IEEE-P1363 fixed-width encoding JOSE
+// mandates (not ASN.1 DER). There is no signing default — the caller
+// names the algorithm, mirroring b.cose.
+var JOSE_ALGS = {
+  "ES256": { nodeHash: "sha256", dsaEncoding: "ieee-p1363" },
+  "ES384": { nodeHash: "sha384", dsaEncoding: "ieee-p1363" },
+  "ES512": { nodeHash: "sha512", dsaEncoding: "ieee-p1363" },
+  "EdDSA": { nodeHash: null },
+};
+
+function _b64urlJson(obj) {
+  return Buffer.from(JSON.stringify(obj), "utf8").toString("base64url");
+}
+function _toKey(key, kind) {
+  if (key && typeof key === "object" && typeof key.asymmetricKeyType === "string") return key;
+  try {
+    return kind === "private" ? nodeCrypto.createPrivateKey(key) : nodeCrypto.createPublicKey(key);
+  } catch (e) {
+    throw new VcError("vc/bad-key", "vc: could not load " + kind + " key: " + ((e && e.message) || e));
+  }
+}
+
+function _issuerId(cred) {
+  if (typeof cred.issuer === "string") return cred.issuer;
+  if (cred.issuer && typeof cred.issuer === "object" && typeof cred.issuer.id === "string") return cred.issuer.id;
+  return undefined;
+}
+
+// VCDM 2.0 structural rules; temporal checks only on verify.
+function _validateVcdm(cred, opts) {
+  if (!cred || typeof cred !== "object" || Array.isArray(cred)) {
+    throw new VcError("vc/bad-credential", "vc: credential must be a JSON object");
+  }
+  var ctx = cred["@context"];
+  if (!Array.isArray(ctx) || ctx[0] !== VCDM_V2_CONTEXT) {
+    throw new VcError("vc/bad-context",
+      "vc: @context must be an array whose first element is '" + VCDM_V2_CONTEXT + "'");
+  }
+  var types = Array.isArray(cred.type) ? cred.type : [cred.type];
+  if (types.indexOf("VerifiableCredential") === -1) {
+    throw new VcError("vc/bad-type", "vc: type must include 'VerifiableCredential'");
+  }
+  if (_issuerId(cred) === undefined) {
+    throw new VcError("vc/no-issuer", "vc: issuer is required (a URL string or an object with an id)");
+  }
+  if (cred.credentialSubject === undefined || cred.credentialSubject === null) {
+    throw new VcError("vc/no-subject", "vc: credentialSubject is required");
+  }
+  // validFrom / validUntil, when present, MUST be valid XSD dateTimes
+  // (VCDM 2.0 §4.9). A malformed value fails closed at both issue and
+  // verify rather than silently skipping the window check.
+  var vf = _parseValidityField(cred, "validFrom");
+  var vu = _parseValidityField(cred, "validUntil");
+  if (opts && opts.temporal) {
+    var nowMs = opts.at.getTime();
+    if (vf !== null && nowMs < vf) {
+      throw new VcError("vc/not-yet-valid", "vc.verify: credential validFrom (" + cred.validFrom + ") is in the future");
+    }
+    if (vu !== null && nowMs > vu) {
+      throw new VcError("vc/expired", "vc.verify: credential validUntil (" + cred.validUntil + ") has passed");
+    }
+  }
+}
+
+function _parseValidityField(cred, name) {
+  if (cred[name] === undefined) return null;
+  if (typeof cred[name] !== "string") {
+    throw new VcError("vc/bad-validity", "vc: " + name + " must be an XSD dateTime string");
+  }
+  var ms = Date.parse(cred[name]);
+  if (!isFinite(ms)) {
+    throw new VcError("vc/bad-validity", "vc: " + name + " is not a valid dateTime: " + cred[name]);
+  }
+  return ms;
+}
+
+/**
+ * @primitive b.vc.issue
+ * @signature b.vc.issue(credential, opts)
+ * @since     0.12.39
+ * @status    experimental
+ * @compliance gdpr, soc2
+ * @related   b.vc.verify, b.cose.sign
+ *
+ * Validate a credential against the VCDM 2.0 structural rules and secure
+ * it. <code>securing: "jose"</code> returns a compact JWS string (media
+ * type <code>vc+jwt</code>) signed with an ES256/384/512 or EdDSA key;
+ * <code>securing: "cose"</code> returns COSE_Sign1 bytes (media type
+ * <code>application/vc+cose</code>) over <code>b.cose</code>, which also
+ * accepts <code>"ML-DSA-87"</code>. The credential itself is the signed
+ * payload — no JWT/CWT claims wrapper is added.
+ *
+ * @opts
+ *   {
+ *     securing:   string,   // "jose" (compact JWS) | "cose" (COSE_Sign1)
+ *     alg:        string,   // JOSE: ES256/384/512 | EdDSA. COSE: + ML-DSA-87
+ *     privateKey: object,   // matching KeyObject or PEM
+ *     kid:        string,   // optional key id (header)
+ *     cty:        string,   // optional JOSE cty (e.g. "vc")
+ *   }
+ *
+ * @example
+ *   var jws = await b.vc.issue(credential, { securing: "jose", alg: "ES256", privateKey: key });
+ *   // → a compact JWS string with typ "vc+jwt"
+ */
+async function issue(credential, opts) {
+  validateOpts.requireObject(opts, "vc.issue", VcError);
+  validateOpts(opts, ["securing", "alg", "privateKey", "kid", "cty"], "vc.issue");
+  _validateVcdm(credential, null);
+  if (!opts.privateKey) throw new VcError("vc/no-key", "vc.issue: opts.privateKey is required");
+
+  if (opts.securing === "cose") {
+    var protectedHeaders = {};
+    protectedHeaders[HDR_COSE_TYP] = COSE_TYP;
+    return cose.sign(Buffer.from(JSON.stringify(credential), "utf8"), {
+      alg:              opts.alg,
+      privateKey:       opts.privateKey,
+      kid:              opts.kid,
+      contentType:      COSE_CONTENT_TYPE,
+      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 + ")");
+    }
+    var key = _toKey(opts.privateKey, "private");
+    var header = { alg: opts.alg, typ: JOSE_TYP };
+    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 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'");
+}
+
+function _verifyJose(token, opts) {
+  var parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new VcError("vc/malformed", "vc.verify: not a compact JWS (expected three dot-separated segments)");
+  }
+  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 + "'");
+  }
+  // crit-bypass defense (RFC 7515 §4.1.11): a `crit` header marks
+  // extensions the verifier MUST understand and process. This verifier
+  // implements no critical extensions, so any `crit` is refused rather
+  // than ignored — accepting it would mean honoring a credential under
+  // weaker semantics than the issuer marked mandatory.
+  if (header.crit !== undefined) {
+    throw new VcError("vc/crit-unsupported",
+      "vc.verify: JWS 'crit' header lists extensions this verifier does not support (RFC 7515 §4.1.11)");
+  }
+  if (header.alg === "none" || !JOSE_ALGS[header.alg]) {
+    throw new VcError("vc/bad-alg", "vc.verify: unsupported or unsecured JWS alg '" + header.alg + "'");
+  }
+  if (opts.algorithms.indexOf(header.alg) === -1) {
+    throw new VcError("vc/alg-not-allowed", "vc.verify: alg '" + header.alg + "' is not in the allowlist");
+  }
+  var params = JOSE_ALGS[header.alg];
+  var pub = opts.publicKey ? _toKey(opts.publicKey, "public") : _toKey(opts.keyResolver(header), "public");
+  var signingInput = parts[0] + "." + parts[1];
+  var sig = Buffer.from(parts[2], "base64url");
+  var ok = params.nodeHash === null
+    ? 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")); }
+  catch (_e) { throw new VcError("vc/malformed", "vc.verify: JWS payload is not valid base64url-JSON"); }
+  return { credential: credential, alg: header.alg };
+}
+
+async function _verifyCose(bytes, opts) {
+  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");
+  }
+  var out = await cose.verify(bytes, {
+    algorithms:  algorithms,
+    publicKey:   opts.publicKey,
+    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 + "'");
+  }
+  var credential;
+  try { credential = 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 };
+}
+
+/**
+ * @primitive b.vc.verify
+ * @signature b.vc.verify(secured, opts)
+ * @since     0.12.39
+ * @status    experimental
+ * @compliance gdpr, soc2
+ * @related   b.vc.issue, b.cose.verify
+ *
+ * Verify a secured verifiable credential and return the credential. The
+ * securing form is auto-detected (a compact-JWS string vs. COSE_Sign1
+ * bytes); the algorithm allowlist is mandatory and the JOSE
+ * <code>none</code> algorithm is always refused. After the signature,
+ * the VCDM 2.0 structural rules are re-checked and the
+ * <code>validFrom</code> / <code>validUntil</code> window is enforced
+ * against <code>opts.at</code> (default: now).
+ *
+ * @opts
+ *   {
+ *     algorithms:      string[],  // required — accepted alg names (allowlist)
+ *     publicKey:       object,    // verification key (KeyObject / PEM)
+ *     keyResolver:     function,  // (header) → key  (alternative to publicKey)
+ *     expectedIssuer:  string,    // require the credential issuer (id) to match
+ *     at:              Date,      // validity instant (default: now); must be a valid Date
+ *   }
+ *
+ * @example
+ *   var out = await b.vc.verify(jws, { algorithms: ["ES256"], publicKey: issuerPub, expectedIssuer: "did:example:123" });
+ *   // → { credential, securing: "jose", alg: "ES256", issuer: "did:example:123" }
+ */
+async function verify(secured, opts) {
+  validateOpts.requireObject(opts, "vc.verify", VcError);
+  validateOpts(opts, ["algorithms", "publicKey", "keyResolver", "expectedIssuer", "at"], "vc.verify");
+  if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
+    throw new VcError("vc/algorithms-required", "vc.verify: opts.algorithms is required (name the accepted algorithms)");
+  }
+  if (!opts.publicKey && typeof opts.keyResolver !== "function") {
+    throw new VcError("vc/no-key", "vc.verify: pass publicKey or keyResolver");
+  }
+  var at = new Date();
+  if (opts.at !== undefined && opts.at !== null) {
+    if (!(opts.at instanceof Date) || !isFinite(opts.at.getTime())) {
+      throw new VcError("vc/bad-at", "vc.verify: opts.at must be a valid Date");
+    }
+    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");
+  }
+
+  _validateVcdm(result.credential, { temporal: true, at: at });
+  var issuer = _issuerId(result.credential);
+  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 };
+}
+
+module.exports = {
+  issue:          issue,
+  verify:         verify,
+  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.38",
+  "version": "0.12.39",
   "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:5183e917-7caf-48d3-b87d-5efa87791e85",
+  "serialNumber": "urn:uuid:a7d5bcb5-4579-407d-b2ac-9baa683fb8f4",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T02:32:18.883Z",
+    "timestamp": "2026-05-25T03:32:36.788Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.38",
+      "bom-ref": "@blamejs/core@0.12.39",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.38",
+      "version": "0.12.39",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.38",
+      "purl": "pkg:npm/%40blamejs/core@0.12.39",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.38",
+      "ref": "@blamejs/core@0.12.39",
       "dependsOn": []
     }
   ]