@blamejs/core 0.12.46 → 0.12.47

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.47 (2026-05-25) — **`b.cose.mac0` / `b.cose.macVerify0` — COSE_Mac0 (RFC 9052 §6.2).** Completes the COSE message-type set (COSE_Sign1 / COSE_Encrypt0 / COSE_Mac0) with single shared-key MACs. b.cose.mac0 produces a tagged COSE_Mac0 over a payload using HMAC-SHA-256/384/512 (the COSE-standard MAC algorithms; HMAC is symmetric, so its post-quantum strength is preserved). b.cose.macVerify0 recomputes the tag over the MAC_structure and compares it in constant time, with a mandatory algorithm allowlist. Use when both parties hold a shared key — e.g. an ECDH-derived key — and a non-repudiable signature is not wanted; detached payloads are supported (the proximity mdoc device-MAC variant and MACed CWTs are the consumers). Composes b.cbor + the framework's constant-time compare; no new runtime dependency. **Added:** *`b.cose.mac0(payload, opts)` / `b.cose.macVerify0(coseMac0, opts)`* — `mac0` emits a tagged COSE_Mac0 (tag 17) with `alg` (`HMAC-256/256` | `HMAC-384/384` | `HMAC-512/512`) in the protected header and the HMAC tag computed over the MAC_structure `["MAC0", protected, external_aad, payload]`; `detached: true` emits a nil payload. `macVerify0` reads the algorithm from the protected header (must be in the required `opts.algorithms` allowlist), recomputes the tag, and compares it constant-time — a wrong key, tampered tag, or `external_aad` mismatch is refused with `cose/bad-tag`; a detached payload is supplied via `opts.externalPayload`. `external_aad` binds context into the tag.
+
 - 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.

package/README.md

@@ -127,7 +127,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **JSON / SQL / schema** — `b.safeJson` (with `maxKeys` cap defending CVE-2026-21717 V8 HashDoS), `b.safeBuffer`, `b.safeSql`, `b.safeSchema`
 - **URL + path** — `b.safeUrl` (IDN mixed-script / homograph refuse); `b.safeJsonPath` (refuses filter `?(...)`, deep-scan `$..`, script-shape `(@.x)` for safe Postgres JSONB ops)
 - **Binary codec** — `b.cbor` bounded deterministic CBOR (RFC 8949 §4.2): depth/size caps, indefinite-length + reserved-info + tag + duplicate-key refusal, `requireDeterministic` canonical-form check; the in-tree substrate under COSE / CWT / SCITT / WebAuthn attestation
-- **COSE signing + encryption** — `b.cose` COSE_Sign1 sign/verify (attached or detached payload) + COSE_Encrypt0 + `importKey` (COSE_Key → KeyObject) (RFC 9052) over `b.cbor`: classical ES256/384/512 + EdDSA (final COSE ids, interoperable today) plus ML-DSA-87 (PQC-forward, draft id); bounded + alg-allowlisted + crit-bypass-checked verification; single-recipient AEAD (ChaCha20/Poly1305 default, AES-GCM opt-in) with Enc_structure-bound AAD; the signed-statement substrate under SCITT / CWT / mdoc / C2PA
+- **COSE messages** — `b.cose` the full RFC 9052 message-type set over `b.cbor`: COSE_Sign1 sign/verify (attached or detached payload), COSE_Encrypt0 single-recipient AEAD, COSE_Mac0 shared-key HMAC (mac0/macVerify0), plus `importKey` (COSE_Key → KeyObject). Signatures use classical ES256/384/512 + EdDSA (final COSE ids, interoperable today) plus ML-DSA-87 (PQC-forward, draft id); bounded + alg-allowlisted + crit-bypass-checked verification; AEAD ChaCha20/Poly1305 default (AES-GCM opt-in); the signed-statement substrate under SCITT / CWT / mdoc / C2PA
 - **CBOR Web Token** — `b.cwt` CWT sign/verify (RFC 8392) over `b.cose`: standard-claim mapping (iss/sub/aud/exp/nbf/iat/cti) + `exp`/`nbf` clock-skew enforcement + `iss`/`aud` matching; the CBOR-native JWT for constrained / IoT / FIDO / verifiable-credential contexts
 - **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

package/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");
 
@@ -548,6 +549,190 @@ 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
@@ -623,8 +808,12 @@ module.exports = {
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.46",
+  "version": "0.12.47",
   "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:059bfa5a-606e-407b-a262-1ee1d810affc",
+  "serialNumber": "urn:uuid:4b602bbd-c8e6-4e4a-8b26-b0c570144b86",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T10:03:10.245Z",
+    "timestamp": "2026-05-25T11:11:40.479Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.46",
+      "bom-ref": "@blamejs/core@0.12.47",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.46",
+      "version": "0.12.47",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.46",
+      "purl": "pkg:npm/%40blamejs/core@0.12.47",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.46",
+      "ref": "@blamejs/core@0.12.47",
       "dependsOn": []
     }
   ]