@blamejs/core 0.12.45 → 0.12.46

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.46 (2026-05-25) — **`b.mdoc.verifyDeviceAuth` — ISO 18013-5 mdoc device authentication.** Completes mdoc verification with the holder-binding half (ISO 18013-5 §9.1.3, signature variant). verifyIssuerSigned proves the data is issuer-signed; verifyDeviceAuth proves the presenter controls the device key the issuer bound into the MSO, so a captured issuer-signed document cannot be replayed by anyone else. The device's COSE_Sign1 (deviceSigned.deviceAuth.deviceSignature) is verified over the detached DeviceAuthentication structure ["DeviceAuthentication", SessionTranscript, DocType, DeviceNameSpacesBytes] using the device key from verifyIssuerSigned().deviceKey (now surfaced) and the operator-supplied SessionTranscript that binds the proof to this exact exchange (the presentation protocol — e.g. OpenID4VP — defines the transcript). Composes the v0.12.45 b.cose detached-payload verify + importKey. The MAC variant (deviceMac / COSE_Mac0, used in proximity flows with a reader ephemeral key) is deferred and refused with mdoc/device-mac-unsupported. No new runtime dependency. **Added:** *`b.mdoc.verifyDeviceAuth(opts)` + `deviceKey` on the verifyIssuerSigned result* — `verifyDeviceAuth({ deviceKey, deviceSigned, docType, sessionTranscript, algorithms })` imports the device key (a COSE_Key via `b.cose.importKey`, or a KeyObject), reconstructs the detached `DeviceAuthentication` payload, and verifies the `deviceSignature` COSE_Sign1 against the mandatory algorithm allowlist — a mismatched `sessionTranscript` or `docType` fails the signature. `verifyIssuerSigned` now returns `deviceKey` (the MSO `deviceKeyInfo.deviceKey`) so the two checks chain. The MAC variant (`deviceMac`) is refused with `mdoc/device-mac-unsupported` pending COSE_Mac0 + reader-key support.
+
 - v0.12.45 (2026-05-25) — **`b.cose` adds detached-payload sign/verify + `b.cose.importKey` (COSE_Key).** Two RFC 9052 / 9053 completions to the COSE substrate, both useable today and the prerequisites for mdoc device authentication and C2PA claim verification. Detached payloads (RFC 9052 §4.1): b.cose.sign with detached:true emits a COSE_Sign1 whose payload slot is nil — the signature still covers the payload, and the caller transmits it out of band; b.cose.verify takes the payload back as opts.externalPayload and binds it into the Sig_structure. A detached token verified without externalPayload is refused, and supplying externalPayload for an attached token is refused as ambiguous. COSE_Key import (RFC 9052 §7): b.cose.importKey turns a COSE_Key CBOR map into a node:crypto public KeyObject for b.cose.verify, accepting EC2 (P-256 / P-384 / P-521) and OKP (Ed25519) with the curve allowlisted so an unexpected key type is refused. No new runtime dependency. **Added:** *Detached COSE_Sign1 payloads + `b.cose.importKey(coseKey)`* — `b.cose.sign(payload, { detached: true })` emits a nil-payload COSE_Sign1 (the signature covers the payload regardless); `b.cose.verify(coseSign1, { externalPayload })` reconstructs the Sig_structure from the supplied payload, refusing a detached token with no `externalPayload` (`cose/detached-no-payload`) and refusing `externalPayload` on an attached token (`cose/payload-ambiguous`). `b.cose.importKey(coseKey)` maps a COSE_Key map (`kty` 2/EC2 with `crv` P-256/384/521, or `kty` 1/OKP with Ed25519) to a public KeyObject, allowlisting `kty`/`crv` and refusing anything else with `cose/unsupported-key` — the verification key embedded in an mdoc MSO or COSE_Key header is consumed this way.
 
 - v0.12.44 (2026-05-25) — **`b.did` adds the did:jwk method.** Completes b.did's method set with did:jwk alongside did:key and did:web. did:jwk encodes a public key as a base64url-encoded JWK directly in the identifier, so resolution is deterministic and offline — the same self-contained shape as did:key but in JWK form, which is what OpenID4VCI and the EU Digital Identity Wallet ecosystem commonly use. b.did.resolve("did:jwk:…") returns the verification key as a node:crypto KeyObject (kty/crv allowlisted — Ed25519 / P-256 / P-384 / secp256k1 — so an unexpected key type is refused, not blindly imported), and b.did.keyToDid(publicKey, { method: "jwk" }) produces a did:jwk from a key (the private member is stripped). No new runtime dependency. **Added:** *did:jwk in `b.did.resolve` / `b.did.keyToDid`* — `resolve` decodes the base64url JWK (bounded via `b.safeJson`), allowlists its `kty`/`crv`, and returns `{ didDocument, verificationMethods: [{ publicKey, … }] }` with the key as a KeyObject ready for `b.vc` / `b.mdoc` / `b.scitt`; `keyToDid(publicKey, { method: "jwk" })` encodes a public key as `did:jwk:<base64url-JWK>` (default remains `did:key`). Malformed base64url-JSON is refused with `did/bad-jwk` and an unsupported key type with `did/unsupported-key`.

package/README.md

@@ -133,7 +133,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **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, 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`
+- **Mobile credentials (mDL)** — `b.mdoc` ISO/IEC 18013-5 verification: `verifyIssuerSigned` checks the COSE_Sign1 IssuerAuth (issuer cert from the `x5chain` header), the MSO validity window, and every disclosed element's digest against the MSO `valueDigests` (selective-disclosure integrity), with optional issuer-chain verification; `verifyDeviceAuth` proves holder binding (§9.1.3 signature variant) — the device COSE_Sign1 over the `DeviceAuthentication` structure with the MSO device key + protocol `sessionTranscript`. 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` / `did:jwk` (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` or `did:jwk`; document/JWK keys are kty/crv-allowlisted before import
 - **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.)

package/lib/mdoc.js

@@ -251,17 +251,138 @@ async function verifyIssuerSigned(issuerSigned, opts) {
     _verifyChain(chain, anchors, at);
   }
 
+  // The device key (MSO deviceKeyInfo.deviceKey, a COSE_Key) binds the
+  // holder — surfaced for b.mdoc.verifyDeviceAuth.
+  var deviceKeyInfo = _mapGet(mso, "deviceKeyInfo");
+  var deviceKey = deviceKeyInfo ? _mapGet(deviceKeyInfo, "deviceKey") : undefined;
+
   return {
     docType:      docType,
     version:      _mapGet(mso, "version"),
     digestAlgorithm: digestAlgName,
     validityInfo: { validFrom: new Date(validFromMs), validUntil: new Date(validUntilMs) },
     namespaces:   out,
+    deviceKey:    deviceKey,
     signerCert:   signerCert.toString(),
     alg:          verified.alg,
   };
 }
 
+/**
+ * @primitive b.mdoc.verifyDeviceAuth
+ * @signature b.mdoc.verifyDeviceAuth(opts)
+ * @since     0.12.46
+ * @status    experimental
+ * @compliance gdpr, soc2
+ * @related   b.mdoc.verifyIssuerSigned, b.cose.verify
+ *
+ * Verify the device-authentication half of an ISO 18013-5 mdoc (§9.1.3,
+ * signature variant) — the proof that the holder controls the device key
+ * the issuer bound into the MSO, which stops a captured issuer-signed
+ * document from being replayed by anyone else. The device's COSE_Sign1
+ * (<code>deviceSigned.deviceAuth.deviceSignature</code>) is verified over
+ * the detached DeviceAuthentication structure
+ * (<code>["DeviceAuthentication", SessionTranscript, DocType,
+ * DeviceNameSpacesBytes]</code>) with the device key from the issuer-signed
+ * MSO (<code>verifyIssuerSigned(...).deviceKey</code>). The
+ * <code>sessionTranscript</code> binds the proof to this exact exchange
+ * and is supplied by the operator (the presentation protocol — e.g.
+ * OpenID4VP — defines it). The MAC variant (<code>deviceMac</code> /
+ * COSE_Mac0, used in proximity flows with a reader ephemeral key) is not
+ * yet supported and is refused with <code>mdoc/device-mac-unsupported</code>.
+ *
+ * @opts
+ *   {
+ *     deviceKey:         object,   // COSE_Key (from verifyIssuerSigned().deviceKey) or a KeyObject / PEM
+ *     deviceSigned:      object,   // the DeviceSigned structure (CBOR bytes or decoded)
+ *     docType:           string,   // the document type (must match the issuer-signed docType)
+ *     sessionTranscript: any,      // the SessionTranscript (CBOR bytes or decoded) bound by the protocol
+ *     algorithms:        string[], // required — accepted COSE alg names (ES256/384/512, EdDSA)
+ *     maxBytes:          number,   // forwarded to b.cbor.decode
+ *     maxDepth:          number,
+ *   }
+ *
+ * @example
+ *   var issuer = await b.mdoc.verifyIssuerSigned(issuerSignedBytes, { algorithms: ["ES256"] });
+ *   var dev = await b.mdoc.verifyDeviceAuth({ deviceKey: issuer.deviceKey, deviceSigned: deviceSignedBytes, docType: issuer.docType, sessionTranscript: transcript, algorithms: ["ES256"] });
+ *   // → { docType, alg, deviceNamespaces }
+ */
+async function verifyDeviceAuth(opts) {
+  validateOpts.requireObject(opts, "mdoc.verifyDeviceAuth", MdocError);
+  validateOpts(opts, ["deviceKey", "deviceSigned", "docType", "sessionTranscript", "algorithms", "maxBytes", "maxDepth"], "mdoc.verifyDeviceAuth");
+  if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
+    throw new MdocError("mdoc/algorithms-required", "mdoc.verifyDeviceAuth: opts.algorithms is required");
+  }
+  if (typeof opts.docType !== "string" || !opts.docType) {
+    throw new MdocError("mdoc/bad-input", "mdoc.verifyDeviceAuth: opts.docType is required");
+  }
+  if (opts.sessionTranscript === undefined || opts.sessionTranscript === null) {
+    throw new MdocError("mdoc/no-session-transcript", "mdoc.verifyDeviceAuth: opts.sessionTranscript is required (the protocol-bound transcript)");
+  }
+  var decodeOpts = { allowedTags: ALLOWED_TAGS, maxBytes: opts.maxBytes, maxDepth: opts.maxDepth };
+
+  // Device key → KeyObject. Accept a COSE_Key (Map/object) via importKey,
+  // or an already-loaded KeyObject / PEM.
+  var deviceKeyObj;
+  if (opts.deviceKey && typeof opts.deviceKey === "object" && typeof opts.deviceKey.asymmetricKeyType === "string") {
+    deviceKeyObj = opts.deviceKey;
+  } else if (opts.deviceKey instanceof Map || (opts.deviceKey && typeof opts.deviceKey === "object")) {
+    deviceKeyObj = cose.importKey(opts.deviceKey);
+  } else if (typeof opts.deviceKey === "string") {
+    deviceKeyObj = opts.deviceKey;   // PEM, resolved by b.cose
+  } else {
+    throw new MdocError("mdoc/no-device-key", "mdoc.verifyDeviceAuth: opts.deviceKey is required (a COSE_Key or KeyObject)");
+  }
+
+  var ds = (Buffer.isBuffer(opts.deviceSigned) || opts.deviceSigned instanceof Uint8Array)
+    ? cbor.decode(_bytes(opts.deviceSigned, "deviceSigned"), decodeOpts) : opts.deviceSigned;
+  var deviceNameSpaces = _mapGet(ds, "nameSpaces");
+  var deviceAuth = _mapGet(ds, "deviceAuth");
+  if (!deviceNameSpaces || !deviceAuth) {
+    throw new MdocError("mdoc/malformed", "mdoc.verifyDeviceAuth: deviceSigned must have nameSpaces + deviceAuth");
+  }
+  if (!(deviceNameSpaces instanceof cbor.Tag) || deviceNameSpaces.tag !== TAG_ENCODED_CBOR) {
+    throw new MdocError("mdoc/malformed", "mdoc.verifyDeviceAuth: deviceSigned.nameSpaces must be a Tag-24 DeviceNameSpacesBytes");
+  }
+  var deviceSignature = _mapGet(deviceAuth, "deviceSignature");
+  if (!deviceSignature) {
+    if (_mapGet(deviceAuth, "deviceMac") !== undefined) {
+      throw new MdocError("mdoc/device-mac-unsupported",
+        "mdoc.verifyDeviceAuth: the MAC variant (deviceMac / COSE_Mac0) is not supported — only deviceSignature");
+    }
+    throw new MdocError("mdoc/no-device-signature", "mdoc.verifyDeviceAuth: deviceAuth has no deviceSignature");
+  }
+
+  var st = (Buffer.isBuffer(opts.sessionTranscript) || opts.sessionTranscript instanceof Uint8Array)
+    ? cbor.decode(_bytes(opts.sessionTranscript, "sessionTranscript"), decodeOpts) : opts.sessionTranscript;
+
+  // DeviceAuthentication (ISO 18013-5 §9.1.3.4); the detached payload is
+  // its Tag-24-wrapped CBOR.
+  var deviceAuthentication = ["DeviceAuthentication", st, opts.docType, deviceNameSpaces];
+  var deviceAuthBytes = cbor.encode(new cbor.Tag(TAG_ENCODED_CBOR, cbor.encode(deviceAuthentication)));
+
+  var coseBytes = Array.isArray(deviceSignature) ? cbor.encode(deviceSignature) : _bytes(deviceSignature, "deviceSignature");
+  var out = await cose.verify(coseBytes, {
+    algorithms:      opts.algorithms,
+    keyResolver:     function () { return deviceKeyObj; },
+    externalPayload: deviceAuthBytes,
+    maxBytes:        opts.maxBytes,
+    maxDepth:        opts.maxDepth,
+  });
+
+  var deviceNamespaces = {};
+  try {
+    var dns = cbor.decode(deviceNameSpaces.value, decodeOpts);
+    if (dns instanceof Map) {
+      dns.forEach(function (items, ns) {
+        deviceNamespaces[ns] = items instanceof Map ? Object.fromEntries(items) : items;
+      });
+    }
+  } catch (_e) { /* device-released namespaces are optional + advisory */ }
+
+  return { docType: opts.docType, alg: out.alg, deviceNamespaces: deviceNamespaces };
+}
+
 // Verify the leaf (chain[0]) chains to a supplied anchor and every cert
 // is valid at `at`. Intermediates in the x5chain are consulted.
 function _verifyChain(chainDer, anchorsPem, at) {
@@ -300,6 +421,7 @@ function _assertValidAt(cert, atMs) {
 
 module.exports = {
   verifyIssuerSigned: verifyIssuerSigned,
+  verifyDeviceAuth:   verifyDeviceAuth,
   DIGEST_ALGS:        DIGEST_ALGS,
   MdocError:          MdocError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.45",
+  "version": "0.12.46",
   "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:f35a1ab6-b9b1-49fa-af2e-e468ce543070",
+  "serialNumber": "urn:uuid:059bfa5a-606e-407b-a262-1ee1d810affc",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T09:29:59.667Z",
+    "timestamp": "2026-05-25T10:03:10.245Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.45",
+      "bom-ref": "@blamejs/core@0.12.46",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.45",
+      "version": "0.12.46",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.45",
+      "purl": "pkg:npm/%40blamejs/core@0.12.46",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.45",
+      "ref": "@blamejs/core@0.12.46",
       "dependsOn": []
     }
   ]