@blamejs/core 0.12.44 → 0.12.45

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- 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`.
 
 - 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.

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 + COSE_Encrypt0 (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 / C2PA
+- **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
 - **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

@@ -143,6 +143,7 @@ function _toBeSigned(protectedBstr, externalAad, payload) {
  *     externalAad?:        Buffer,    // default empty — bound into the signature
  *     unprotectedHeaders?: object,    // extra unprotected map entries (numeric keys)
  *     protectedHeaders?:   object,    // extra INTEGRITY-PROTECTED map entries (numeric keys); label 1 (alg) is reserved
+ *     detached?:           boolean,   // emit a nil payload (RFC 9052 §4.1) — signature still covers it; caller transmits the payload separately
  *   }
  *
  * @example
@@ -152,7 +153,7 @@ function _toBeSigned(protectedBstr, externalAad, payload) {
  */
 async function sign(payload, opts) {
   validateOpts.requireObject(opts, "cose.sign", CoseError);
-  validateOpts(opts, ["alg", "privateKey", "kid", "contentType", "externalAad", "unprotectedHeaders", "protectedHeaders"], "cose.sign");
+  validateOpts(opts, ["alg", "privateKey", "kid", "contentType", "externalAad", "unprotectedHeaders", "protectedHeaders", "detached"], "cose.sign");
   if (SIGNABLE.indexOf(opts.alg) === -1) {
     throw new CoseError("cose/unsignable-alg",
       "cose.sign: alg must be one of " + SIGNABLE.join(" / ") +
@@ -213,7 +214,10 @@ async function sign(payload, opts) {
     ? nodeCrypto.sign(null, toBeSigned, key)
     : nodeCrypto.sign(params.nodeAlg, toBeSigned, { key: key, dsaEncoding: params.dsaEncoding });
 
-  var sign1 = [protectedBstr, unprot, payloadBytes, signature];
+  // Detached payload (RFC 9052 §4.1): the COSE_Sign1 carries nil in the
+  // payload slot; the signature still covers the payload (above), and the
+  // caller transmits / re-supplies it out of band as externalPayload.
+  var sign1 = [protectedBstr, unprot, opts.detached ? null : payloadBytes, signature];
   return cbor.encode(new cbor.Tag(COSE_SIGN1_TAG, sign1));
 }
 
@@ -237,6 +241,7 @@ async function sign(payload, opts) {
  *     publicKey?:   object,    // the verification key (KeyObject / PEM)
  *     keyResolver?: function,  // (protectedHeaders, unprotectedHeaders) → key
  *     externalAad?: Buffer,    // must match what was signed
+ *     externalPayload?: Buffer, // required when the COSE_Sign1 payload is detached (nil); bound into the Sig_structure
  *     maxBytes?:    number,    // forwarded to b.cbor.decode
  *     maxDepth?:    number,
  *   }
@@ -247,7 +252,7 @@ async function sign(payload, opts) {
  */
 async function verify(coseSign1, opts) {
   validateOpts.requireObject(opts, "cose.verify", CoseError);
-  validateOpts(opts, ["algorithms", "publicKey", "keyResolver", "externalAad", "maxBytes", "maxDepth"], "cose.verify");
+  validateOpts(opts, ["algorithms", "publicKey", "keyResolver", "externalAad", "externalPayload", "maxBytes", "maxDepth"], "cose.verify");
   if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
     throw new CoseError("cose/algorithms-required",
       "cose.verify: opts.algorithms is required (no defaults — name the accepted algorithms)");
@@ -278,14 +283,23 @@ async function verify(coseSign1, opts) {
   if (!Buffer.isBuffer(protectedBstr) || !Buffer.isBuffer(signature)) {
     throw new CoseError("cose/malformed", "cose.verify: protected header and signature must be byte strings");
   }
+  // Detached payload (RFC 9052 §4.1): a nil payload slot means the caller
+  // must supply the payload out of band via opts.externalPayload, which
+  // is then bound into the Sig_structure. Supplying externalPayload for
+  // an attached (non-nil) token is ambiguous and refused.
   if (payload === null || payload === undefined) {
-    throw new CoseError("cose/detached-unsupported",
-      "cose.verify: detached payload (nil) is not supported in v1 — attached payload only");
-  }
-  // COSE_Sign1 payload is a bstr (RFC 9052 §4.2) — refuse a non-byte
-  // payload rather than return a value that violates the documented
-  // { payload: Buffer } shape.
-  if (!Buffer.isBuffer(payload)) {
+    if (opts.externalPayload == null) {
+      throw new CoseError("cose/detached-no-payload",
+        "cose.verify: COSE_Sign1 has a detached (nil) payload — pass opts.externalPayload to verify it");
+    }
+    payload = _bstr(opts.externalPayload);
+  } else if (opts.externalPayload != null) {
+    throw new CoseError("cose/payload-ambiguous",
+      "cose.verify: opts.externalPayload was supplied but the COSE_Sign1 carries an attached payload");
+  } else if (!Buffer.isBuffer(payload)) {
+    // COSE_Sign1 payload is a bstr (RFC 9052 §4.2) — refuse a non-byte
+    // payload rather than return a value that violates the documented
+    // { payload: Buffer } shape.
     throw new CoseError("cose/malformed", "cose.verify: payload must be a byte string (bstr)");
   }
   // The unprotected header is a CBOR map — refuse a non-map rather
@@ -534,11 +548,82 @@ function decrypt0(coseEncrypt0, opts) {
   return { plaintext: pt, alg: algName, protectedHeaders: protMap, unprotectedHeaders: unprotected };
 }
 
+// ---- COSE_Key (RFC 9052 §7 / RFC 9053 §7) → KeyObject ----
+
+// COSE_Key EC2 curve identifiers (RFC 9053 §7.1) → JWK crv names. Only
+// the curves b.cose.verify has an algorithm for are accepted: P-256
+// (ES256), P-384 (ES384), P-521 (ES512). secp256k1 is intentionally
+// absent — there is no ES256K path here, so importing one would let a
+// secp256k1 key be verified under ES256, breaking the COSE alg/curve
+// binding (RFC 9053). Re-add with an explicit ES256K algorithm.
+var COSE_EC2_CRV = { 1: "P-256", 2: "P-384", 3: "P-521" };
+var COSE_KTY_OKP = 1;
+var COSE_KTY_EC2 = 2;
+var COSE_OKP_ED25519 = 6;                                                    // allow:raw-byte-literal — COSE OKP Ed25519 crv id (RFC 9053)
+
+function _coseKeyBytes(v, what) {
+  if (Buffer.isBuffer(v)) return v;
+  if (v instanceof Uint8Array) return Buffer.from(v);
+  throw new CoseError("cose/bad-cose-key", "cose.importKey: COSE_Key " + what + " must be a byte string");
+}
+
+/**
+ * @primitive b.cose.importKey
+ * @signature b.cose.importKey(coseKey)
+ * @since     0.12.45
+ * @status    stable
+ * @related   b.cose.verify, b.cbor.decode
+ *
+ * Import a COSE_Key (RFC 9052 §7) — a CBOR map keyed by integer labels —
+ * as a <code>node:crypto</code> public KeyObject for
+ * <code>b.cose.verify</code>. Accepts the EC2 (<code>kty</code> 2:
+ * P-256 / P-384 / P-521) and OKP (<code>kty</code> 1: Ed25519) key
+ * types — the curves <code>b.cose.verify</code> has an algorithm for;
+ * the curve is allowlisted, so an unexpected key type (including
+ * secp256k1, which has no ES256K path here) is refused rather than
+ * imported. The verification key embedded in an mdoc MSO or a COSE_Key
+ * header is consumed this way.
+ *
+ * @example
+ *   var key = b.cose.importKey(coseKeyMap);            // → public KeyObject
+ *   var out = await b.cose.verify(sign1, { algorithms: ["ES256"], publicKey: key });
+ */
+function importKey(coseKey) {
+  if (!(coseKey instanceof Map)) {
+    if (coseKey && typeof coseKey === "object" && !Array.isArray(coseKey)) {
+      var m = new Map();
+      Object.keys(coseKey).forEach(function (k) { m.set(Number(k), coseKey[k]); });
+      coseKey = m;
+    } else {
+      throw new CoseError("cose/bad-cose-key", "cose.importKey: expected a COSE_Key map");
+    }
+  }
+  var kty = coseKey.get(1);
+  var x = _coseKeyBytes(coseKey.get(-2), "x");
+  var jwk;
+  if (kty === COSE_KTY_OKP) {
+    if (coseKey.get(-1) !== COSE_OKP_ED25519) {
+      throw new CoseError("cose/unsupported-key", "cose.importKey: only OKP curve Ed25519 is supported");
+    }
+    jwk = { kty: "OKP", crv: "Ed25519", x: x.toString("base64url") };
+  } else if (kty === COSE_KTY_EC2) {
+    var crvName = COSE_EC2_CRV[coseKey.get(-1)];
+    if (!crvName) throw new CoseError("cose/unsupported-key", "cose.importKey: unsupported EC2 curve id " + coseKey.get(-1));
+    var y = _coseKeyBytes(coseKey.get(-3), "y");
+    jwk = { kty: "EC", crv: crvName, x: x.toString("base64url"), y: y.toString("base64url") };
+  } else {
+    throw new CoseError("cose/unsupported-key", "cose.importKey: kty must be OKP (1) or EC2 (2), got " + kty);
+  }
+  try { return nodeCrypto.createPublicKey({ key: jwk, format: "jwk" }); }
+  catch (e) { throw new CoseError("cose/bad-cose-key", "cose.importKey: could not import COSE_Key: " + ((e && e.message) || e)); }
+}
+
 module.exports = {
   sign:        sign,
   verify:      verify,
   encrypt0:    encrypt0,
   decrypt0:    decrypt0,
+  importKey:   importKey,
   ALGORITHMS:  ALG_NAME_TO_ID,
   AEAD_ALGORITHMS: AEAD_NAME_TO_ID,
   COSE_SIGN1_TAG: COSE_SIGN1_TAG,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.44",
+  "version": "0.12.45",
   "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:645939ff-86bb-46c2-a5af-52ac1e920cb5",
+  "serialNumber": "urn:uuid:f35a1ab6-b9b1-49fa-af2e-e468ce543070",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T08:20:43.623Z",
+    "timestamp": "2026-05-25T09:29:59.667Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.44",
+      "bom-ref": "@blamejs/core@0.12.45",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.44",
+      "version": "0.12.45",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.44",
+      "purl": "pkg:npm/%40blamejs/core@0.12.45",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.44",
+      "ref": "@blamejs/core@0.12.45",
       "dependsOn": []
     }
   ]