@blamejs/core 0.12.35 → 0.12.37

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- 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.
+
+- v0.12.36 (2026-05-24) — **`b.cose.encrypt0` / `b.cose.decrypt0` — COSE_Encrypt0 single-recipient AEAD (RFC 9052 §5.2).** Completes the COSE family with encryption alongside the v0.12.33 signing: COSE_Encrypt0 is the single-recipient AEAD container where the recipient already holds the symmetric key (direct mode). The default algorithm is ChaCha20/Poly1305 (COSE alg 24) — AES-GCM stays opt-in, since hard-rule #2 forbids AES-GCM as a default. The Enc_structure (`["Encrypt0", protected, external_aad]`) is bound as the AEAD associated data so the algorithm + any external context are authenticated, and the authentication tag is appended to the ciphertext per COSE. Composes the in-tree `b.cbor` codec and `node:crypto` AEAD. **Added:** *`b.cose.encrypt0(plaintext, opts)` / `b.cose.decrypt0(coseEncrypt0, opts)`* — `encrypt0` produces a tagged COSE_Encrypt0 with `alg` in the protected header and a random 12-byte IV in the unprotected header (label 5); `alg` is `"ChaCha20-Poly1305"` (default), `"A256GCM"`, or `"A128GCM"`, with the key length enforced (32 / 16 bytes). `decrypt0` reads the algorithm from the protected header (must be in the required `opts.algorithms` allowlist), reconstructs the Enc_structure as the AEAD AAD, and returns `{ plaintext, alg, protectedHeaders, unprotectedHeaders }`; a wrong key, tampered ciphertext, or `external_aad` mismatch fails AEAD authentication and is refused with `cose/decrypt-failed`. `external_aad` binds request context into the tag.
+
 - v0.12.35 (2026-05-24) — **`b.eat` — Entity Attestation Token (RFC 9711) over `b.cwt`.** An EAT is the token a Relying Party asks a device or software entity to produce to prove what it is and what state it is in — a freshness nonce, a Universal Entity ID, OEM / hardware identifiers, debug status, software measurements, and nested submodule attestations. `b.eat` is the RFC 9711 profile over the v0.12.34 `b.cwt`: it maps the EAT claim names to their IANA CWT claim-key integer labels and adds the attestation-specific verification on top of the CWT signature + time checks. The central control is the verifier-nonce binding: when the Relying Party supplies a fresh `expectedNonce`, the token's `eat_nonce` (claim 10) must match it (constant-time compare) — without it a captured attestation replays forever. `verify` also enforces a debug-status policy (`requireDebugDisabled` refuses an `enabled` or absent `dbgstat`) and pins the `eat_profile`. RFC 9711 is a finalized standard; signing follows `b.cwt` / `b.cose` (ES256/384/512 + EdDSA interoperable today, ML-DSA-87 PQC-forward). **Added:** *`b.eat.sign(claims, opts)` / `b.eat.verify(eat, opts)`* — `sign` maps EAT claim names (`nonce`, `ueid`, `oemid`, `hwmodel`, `dbgstat`, `eat_profile`, `swname`/`swversion`, `measurements`, `submods`, …) to their RFC 9711 integer labels and accepts the `dbgstat` enum by name (`disabled-since-boot` → 2); standard CWT claims (`iss` / `exp` / …) pass through. `verify` returns `{ claims, raw, alg, protectedHeaders }` with the labels mapped back to friendly names and `dbgstat` decoded to its enum name. Attestation enforcement: `expectedNonce` requires a matching `eat_nonce` (refused `eat/nonce-mismatch`, missing `eat/nonce-missing` — `eat_nonce` may be a single byte string or an array for multiple verifiers), `requireDebugDisabled` refuses a non-disabled `dbgstat` (`eat/debug-not-disabled`), and `expectedProfile` pins `eat_profile`. The signature, algorithm allowlist, and `exp`/`nbf` checks delegate to `b.cwt` / `b.cose`. · *`b.cwt.sign` accepts a `Map`* — `b.cwt.sign` now takes either a plain object (string keys, standard claims mapped by name) or a `Map`, which preserves integer claim keys verbatim — profiles like `b.eat` resolve their claim names to integer labels and pass them through without the keys being stringified. The plain-object path is unchanged.
 
 - v0.12.34 (2026-05-24) — **`b.cwt` — CBOR Web Token (RFC 8392) sign / verify over `b.cose`.** A CWT is the CBOR-native counterpart to JWT — a signed claims set for constrained / IoT, FIDO attestation, and verifiable-credential contexts. `b.cwt` composes the v0.12.33 `b.cose` (COSE_Sign1 signature + mandatory algorithm allowlist) and v0.12.32 `b.cbor` (deterministic claims encoding) and layers the standard-claim handling on top: `sign` takes a friendly claims object, maps the standard claims to their RFC 8392 §3.1.1 integer labels (iss=1, sub=2, aud=3, exp=4, nbf=5, iat=6, cti=7), and signs; `verify` checks the COSE signature, decodes the claims, and enforces the time + identity claims — a passed `exp` (with clock-skew tolerance), a future `nbf`, and an `iss` / `aud` mismatch against the expected values are each refused. Signing algorithms follow `b.cose`: classical ES256/384/512 + EdDSA (final COSE ids, interoperable today) and ML-DSA-87 (PQC-forward). RFC 8392 is a finalized standard, so CWTs produced here interoperate with other COSE/CWT implementations. **Added:** *`b.cwt.sign(claims, opts)` / `b.cwt.verify(cwt, opts)`* — `sign` maps standard claim names to integer labels and keeps custom claims verbatim; `exp` / `nbf` / `iat` must be non-negative integer NumericDates. `opts.tagged` wraps the COSE_Sign1 in the CWT CBOR tag 61 (RFC 8392 §6); `verify` accepts tagged or bare input. `verify` returns `{ claims, raw, alg, protectedHeaders }` — `claims` is the friendly object (labels mapped back to names), `raw` the integer-keyed Map. Standard-claim enforcement: `exp` past `now + clockSkewSec` (default 60s) is refused with `cwt/expired`, `nbf` beyond `now - skew` with `cwt/not-yet-valid`, and `expectedIssuer` / `expectedAudience` mismatches with `cwt/issuer-mismatch` / `cwt/audience-mismatch` (aud may be a single value or an array). `opts.now` overrides the clock for testing. The signature itself is verified by `b.cose.verify`, so a tampered token fails there.

package/README.md

@@ -126,9 +126,10 @@ 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** — `b.cose` COSE_Sign1 sign/verify (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; the signed-statement substrate under SCITT / CWT / C2PA
+- **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
 - **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
 - **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

@@ -459,6 +459,7 @@ module.exports = {
   cose:             require("./lib/cose"),
   cwt:              require("./lib/cwt"),
   eat:              require("./lib/eat"),
+  scitt:            require("./lib/scitt"),
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/cose.js

@@ -63,6 +63,7 @@ var HDR_ALG = 1;
 var HDR_CRIT = 2;                                                                      // header label: crit
 var HDR_CONTENT_TYPE = 3;                                                              // header label: content type
 var HDR_KID = 4;                                                                       // header label: kid
+var HDR_CWT_CLAIMS = 15;                                                               // allow:raw-byte-literal — RFC 9597 CWT Claims header label (carries SCITT iss/sub)
 
 // COSE algorithm identifiers. ML-DSA-87 is a NON-FINAL requested
 // assignment (draft-ietf-cose-dilithium) — pinned deliberately, re-open
@@ -83,7 +84,7 @@ var SIGNABLE = ["ML-DSA-87", "ES256", "ES384", "ES512", "EdDSA"];
 
 // Header labels this verifier understands — a `crit` entry naming any
 // other label is refused (RFC 9052 §3.1 crit-bypass defense).
-var UNDERSTOOD_LABELS = [HDR_ALG, HDR_CRIT, HDR_CONTENT_TYPE, HDR_KID];
+var UNDERSTOOD_LABELS = [HDR_ALG, HDR_CRIT, HDR_CONTENT_TYPE, HDR_KID, HDR_CWT_CLAIMS];
 
 function _toKeyObject(key, kind) {
   if (key && typeof key === "object" && typeof key.asymmetricKeyType === "string") return key;
@@ -138,9 +139,10 @@ function _toBeSigned(protectedBstr, externalAad, payload) {
  *     alg:                 string,    // "ES256" | "ES384" | "ES512" | "EdDSA" | "ML-DSA-87"
  *     privateKey:          object,    // matching KeyObject or PEM
  *     kid?:                string,    // → unprotected header label 4
- *     contentType?:        number,    // → protected header label 3
+ *     contentType?:        number|string, // → protected header label 3 (CoAP Content-Format uint or media-type string)
  *     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
  *   }
  *
  * @example
@@ -150,7 +152,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"], "cose.sign");
+  validateOpts(opts, ["alg", "privateKey", "kid", "contentType", "externalAad", "unprotectedHeaders", "protectedHeaders"], "cose.sign");
   if (SIGNABLE.indexOf(opts.alg) === -1) {
     throw new CoseError("cose/unsignable-alg",
       "cose.sign: alg must be one of " + SIGNABLE.join(" / ") +
@@ -165,7 +167,31 @@ async function sign(payload, opts) {
 
   var protMap = new Map();
   protMap.set(HDR_ALG, algId);
-  if (typeof opts.contentType === "number") protMap.set(HDR_CONTENT_TYPE, opts.contentType);
+  // Content type (RFC 9052 §3.1): a uint (CoAP Content-Format) or a
+  // media-type string (tstr) — a SCITT signed statement declares its
+  // payload media type as a string here.
+  if (typeof opts.contentType === "number" || typeof opts.contentType === "string") {
+    protMap.set(HDR_CONTENT_TYPE, opts.contentType);
+  }
+  // Extra integrity-protected headers (e.g. CWT_Claims label 15 for a
+  // SCITT signed statement). alg (label 1) is managed via opts.alg and
+  // cannot be overridden here — a caller that needs a different alg
+  // names it in opts.alg.
+  if (opts.protectedHeaders && typeof opts.protectedHeaders === "object") {
+    var pk = opts.protectedHeaders instanceof Map
+      ? Array.from(opts.protectedHeaders.keys())
+      : Object.keys(opts.protectedHeaders);
+    for (var pi = 0; pi < pk.length; pi++) {
+      var plabel = Number(pk[pi]);
+      if (plabel === HDR_ALG) {
+        throw new CoseError("cose/reserved-header",
+          "cose.sign: protectedHeaders must not set label 1 (alg) — pass opts.alg instead");
+      }
+      var pval = opts.protectedHeaders instanceof Map
+        ? opts.protectedHeaders.get(pk[pi]) : opts.protectedHeaders[pk[pi]];
+      protMap.set(plabel, pval);
+    }
+  }
   var protectedBstr = cbor.encode(protMap);
 
   var unprot = new Map();
@@ -330,10 +356,192 @@ async function verify(coseSign1, opts) {
   };
 }
 
+// ---- COSE_Encrypt0 (RFC 9052 §5.2) — single-recipient AEAD ----
+
+var COSE_ENCRYPT0_TAG = 16;                                                            // allow:raw-byte-literal — RFC 9052 COSE_Encrypt0 CBOR tag
+var HDR_IV = 5;                                                                        // RFC 9052 §3.1 unprotected header label: IV
+var AEAD_TAG_LEN = 16;                                                                 // allow:raw-byte-literal — AEAD authentication tag length (bytes)
+
+// AEAD algorithm: COSE id → node cipher + key / IV sizes. ChaCha20/
+// Poly1305 (24) is the default; AES-GCM is opt-in (project hard-rule
+// #2 forbids AES-GCM as a default).
+var AEAD_NAME_TO_ID = { "ChaCha20-Poly1305": 24, "A256GCM": 3, "A128GCM": 1 };         // allow:raw-byte-literal — COSE AEAD algorithm identifiers (RFC 9053), not sizes
+var AEAD_ID_TO_NAME = {};
+Object.keys(AEAD_NAME_TO_ID).forEach(function (k) { AEAD_ID_TO_NAME[AEAD_NAME_TO_ID[k]] = k; });
+
+function _aeadParams(algId) {
+  switch (algId) {
+    case 24: return { cipher: "chacha20-poly1305", keyLen: 32, ivLen: 12 };            // allow:raw-byte-literal — ChaCha20/Poly1305 key+IV sizes
+    case 3:  return { cipher: "aes-256-gcm",      keyLen: 32, ivLen: 12 };             // allow:raw-byte-literal — AES-256-GCM key+IV sizes
+    case 1:  return { cipher: "aes-128-gcm",      keyLen: 16, ivLen: 12 };             // allow:raw-byte-literal — AES-128-GCM key+IV sizes
+    default:
+      throw new CoseError("cose/unknown-alg", "cose: unrecognized AEAD COSE alg id " + algId);
+  }
+}
+
+// Enc_structure (§5.3) = [ "Encrypt0", body_protected (bstr), external_aad (bstr) ]
+// — deterministically CBOR-encoded, used as the AEAD associated data.
+function _encStructure(protectedBstr, externalAad) {
+  return cbor.encode(["Encrypt0", protectedBstr, externalAad]);
+}
+
+/**
+ * @primitive b.cose.encrypt0
+ * @signature b.cose.encrypt0(plaintext, opts)
+ * @since     0.12.36
+ * @status    stable
+ * @related   b.cose.decrypt0, b.cose.sign
+ *
+ * Encrypt bytes into a tagged COSE_Encrypt0 (RFC 9052 §5.2), a
+ * single-recipient AEAD container where the recipient already holds
+ * the symmetric key (direct mode). Default algorithm is
+ * <code>ChaCha20-Poly1305</code>; <code>A256GCM</code> / <code>A128GCM</code>
+ * are opt-in. The Enc_structure is bound as the AEAD associated data,
+ * and the authentication tag is appended to the ciphertext per COSE.
+ *
+ * @opts
+ *   {
+ *     alg:        string,   // "ChaCha20-Poly1305" (default) | "A256GCM" | "A128GCM"
+ *     key:        Buffer,   // symmetric key (32 bytes for ChaCha/A256GCM, 16 for A128GCM)
+ *     iv?:        Buffer,   // 12-byte IV (random if omitted)
+ *     externalAad?: Buffer, // bound into the AEAD tag
+ *     unprotectedHeaders?: object,
+ *   }
+ *
+ * @example
+ *   var enc = b.cose.encrypt0(Buffer.from("secret"), { alg: "ChaCha20-Poly1305", key: k });
+ */
+function encrypt0(plaintext, opts) {
+  validateOpts.requireObject(opts, "cose.encrypt0", CoseError);
+  validateOpts(opts, ["alg", "key", "iv", "externalAad", "unprotectedHeaders"], "cose.encrypt0");
+  var alg = opts.alg || "ChaCha20-Poly1305";
+  if (!(alg in AEAD_NAME_TO_ID)) {
+    throw new CoseError("cose/unknown-alg", "cose.encrypt0: alg must be one of " + Object.keys(AEAD_NAME_TO_ID).join(" / "));
+  }
+  var algId = AEAD_NAME_TO_ID[alg];
+  var p = _aeadParams(algId);
+  var key = _bstr(opts.key);
+  if (key.length !== p.keyLen) throw new CoseError("cose/bad-key", "cose.encrypt0: " + alg + " requires a " + p.keyLen + "-byte key");
+  var iv = opts.iv != null ? _bstr(opts.iv) : nodeCrypto.randomBytes(p.ivLen);
+  if (iv.length !== p.ivLen) throw new CoseError("cose/bad-iv", "cose.encrypt0: " + alg + " requires a " + p.ivLen + "-byte IV");
+
+  var protMap = new Map(); protMap.set(HDR_ALG, algId);
+  var protectedBstr = cbor.encode(protMap);
+  var aad = _encStructure(protectedBstr, opts.externalAad == null ? Buffer.alloc(0) : _bstr(opts.externalAad));
+
+  var cipher = nodeCrypto.createCipheriv(p.cipher, key, iv, { authTagLength: AEAD_TAG_LEN });
+  cipher.setAAD(aad);
+  var ct = Buffer.concat([cipher.update(_bstr(plaintext)), cipher.final()]);
+  var ciphertext = Buffer.concat([ct, cipher.getAuthTag()]);                            // COSE appends the auth tag to the ciphertext
+
+  var unprot = new Map(); unprot.set(HDR_IV, iv);
+  if (opts.unprotectedHeaders && typeof opts.unprotectedHeaders === "object") {
+    var uk = Object.keys(opts.unprotectedHeaders);
+    for (var i = 0; i < uk.length; i++) {
+      var label = Number(uk[i]);
+      // The IV (label 5) is managed via opts.iv and must match the IV
+      // the AEAD used — refuse an override that would emit a token whose
+      // stored IV disagrees with the one it was encrypted under.
+      if (label === HDR_IV) {
+        throw new CoseError("cose/reserved-header",
+          "cose.encrypt0: unprotectedHeaders must not set label 5 (IV) — pass opts.iv instead");
+      }
+      unprot.set(label, opts.unprotectedHeaders[uk[i]]);
+    }
+  }
+  return cbor.encode(new cbor.Tag(COSE_ENCRYPT0_TAG, [protectedBstr, unprot, ciphertext]));
+}
+
+/**
+ * @primitive b.cose.decrypt0
+ * @signature b.cose.decrypt0(coseEncrypt0, opts)
+ * @since     0.12.36
+ * @status    stable
+ * @related   b.cose.encrypt0
+ *
+ * Decrypt a COSE_Encrypt0 and return the plaintext. The algorithm is
+ * read from the protected header and must be in
+ * <code>opts.algorithms</code>; the Enc_structure is reconstructed as
+ * the AEAD associated data and authentication failure (wrong key /
+ * tampered ciphertext or AAD) is refused.
+ *
+ * @opts
+ *   {
+ *     key:        Buffer,    // symmetric key
+ *     algorithms: string[],  // required — accepted AEAD algs (allowlist)
+ *     externalAad?: Buffer,  // must match what was encrypted
+ *     maxBytes?:  number,
+ *     maxDepth?:  number,
+ *   }
+ *
+ * @example
+ *   var pt = b.cose.decrypt0(enc, { key: k, algorithms: ["ChaCha20-Poly1305"] }).plaintext;
+ */
+function decrypt0(coseEncrypt0, opts) {
+  validateOpts.requireObject(opts, "cose.decrypt0", CoseError);
+  validateOpts(opts, ["key", "algorithms", "externalAad", "maxBytes", "maxDepth"], "cose.decrypt0");
+  if (!Array.isArray(opts.algorithms) || opts.algorithms.length === 0) {
+    throw new CoseError("cose/algorithms-required", "cose.decrypt0: opts.algorithms is required (no defaults — name the accepted algorithms)");
+  }
+  var decoded = cbor.decode(_bstr(coseEncrypt0), { allowedTags: [COSE_ENCRYPT0_TAG], maxBytes: opts.maxBytes, maxDepth: opts.maxDepth });
+  var arr = (decoded instanceof cbor.Tag && decoded.tag === COSE_ENCRYPT0_TAG) ? decoded.value : decoded;
+  if (!Array.isArray(arr) || arr.length !== 3) {
+    throw new CoseError("cose/malformed", "cose.decrypt0: not a COSE_Encrypt0 (expected a 3-element array)");
+  }
+  var protectedBstr = arr[0], unprotected = arr[1], ciphertext = arr[2];
+  if (!Buffer.isBuffer(protectedBstr) || !Buffer.isBuffer(ciphertext)) {
+    throw new CoseError("cose/malformed", "cose.decrypt0: protected header and ciphertext must be byte strings");
+  }
+  if (!(unprotected instanceof Map)) {
+    throw new CoseError("cose/malformed", "cose.decrypt0: unprotected header must be a CBOR map");
+  }
+  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.decrypt0: protected header is not a CBOR map");
+  }
+  var algId = protMap.get(HDR_ALG);
+  var algName = AEAD_ID_TO_NAME[algId];
+  if (algName === undefined) {
+    throw new CoseError("cose/unknown-alg", "cose.decrypt0: unrecognized AEAD alg id " + algId);
+  }
+  if (opts.algorithms.indexOf(algName) === -1) {
+    throw new CoseError("cose/alg-not-allowed", "cose.decrypt0: alg '" + algName + "' is not in the allowlist");
+  }
+  var p = _aeadParams(algId);
+  var key = _bstr(opts.key);
+  if (key.length !== p.keyLen) throw new CoseError("cose/bad-key", "cose.decrypt0: " + algName + " requires a " + p.keyLen + "-byte key");
+  var iv = unprotected.get(HDR_IV);
+  if (!Buffer.isBuffer(iv) || iv.length !== p.ivLen) {
+    throw new CoseError("cose/bad-iv", "cose.decrypt0: missing or wrong-length IV (unprotected label 5)");
+  }
+  if (ciphertext.length < AEAD_TAG_LEN) {
+    throw new CoseError("cose/malformed", "cose.decrypt0: ciphertext shorter than the AEAD tag");
+  }
+  var tag = ciphertext.subarray(ciphertext.length - AEAD_TAG_LEN);
+  var ct = ciphertext.subarray(0, ciphertext.length - AEAD_TAG_LEN);
+  var aad = _encStructure(protectedBstr, opts.externalAad == null ? Buffer.alloc(0) : _bstr(opts.externalAad));
+
+  var decipher = nodeCrypto.createDecipheriv(p.cipher, key, iv, { authTagLength: AEAD_TAG_LEN });
+  decipher.setAAD(aad);
+  decipher.setAuthTag(tag);
+  var pt;
+  try {
+    pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+  } catch (_e) {
+    throw new CoseError("cose/decrypt-failed", "cose.decrypt0: AEAD authentication failed (wrong key, tampered ciphertext, or AAD mismatch)");
+  }
+  return { plaintext: pt, alg: algName, protectedHeaders: protMap, unprotectedHeaders: unprotected };
+}
+
 module.exports = {
   sign:        sign,
   verify:      verify,
+  encrypt0:    encrypt0,
+  decrypt0:    decrypt0,
   ALGORITHMS:  ALG_NAME_TO_ID,
+  AEAD_ALGORITHMS: AEAD_NAME_TO_ID,
   COSE_SIGN1_TAG: COSE_SIGN1_TAG,
+  COSE_ENCRYPT0_TAG: COSE_ENCRYPT0_TAG,
   CoseError:   CoseError,
 };

package/lib/scitt.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * @module b.scitt
+ * @nav    Crypto
+ * @title  SCITT signed statements
+ *
+ * @intro
+ *   A SCITT (Supply Chain Integrity, Transparency, and Trust) signed
+ *   statement is a <code>b.cose</code> COSE_Sign1 that makes a signed,
+ *   attributable claim <em>about an artifact</em> — a signed SBOM, a
+ *   build attestation, a release approval. The artifact (or a hash /
+ *   reference to it) is the payload; the issuer and the subject are
+ *   carried in the integrity-protected <strong>CWT_Claims</strong>
+ *   header (label 15, RFC 9597): <code>iss</code> (label 1) is who
+ *   makes the statement, <code>sub</code> (label 2) is the artifact the
+ *   statement is about. This module builds and verifies that envelope
+ *   over <code>b.cose</code> + <code>b.cbor</code>.
+ *
+ *   <code>b.scitt.signStatement(payload, opts)</code> produces the
+ *   COSE_Sign1, placing <code>iss</code> / <code>sub</code> (plus any
+ *   extra CWT claims) in the protected CWT_Claims header and declaring
+ *   the payload media type as the COSE content type.
+ *   <code>b.scitt.verifyStatement(statement, opts)</code> verifies the
+ *   signature (delegating the mandatory algorithm allowlist to
+ *   <code>b.cose.verify</code>), then enforces that a CWT_Claims header
+ *   with both <code>iss</code> and <code>sub</code> is present —
+ *   refusing a statement that omits the issuer/subject binding — and
+ *   optionally checks them against expected values.
+ *
+ *   The signing algorithms are exactly <code>b.cose</code>'s: the
+ *   classical ES256/384/512 + EdDSA (final COSE ids, interoperable
+ *   today) and ML-DSA-87 (PQC-forward, draft COSE id). Because the
+ *   identity binding lives in the protected header it is covered by the
+ *   signature and cannot be substituted without detection.
+ *
+ *   <strong>Scope.</strong> This is the <em>issuer half</em> of SCITT —
+ *   producing and verifying signed statements, which is buildable today
+ *   on finalized RFCs (RFC 9052 COSE, RFC 9597 CWT_Claims header, RFC
+ *   8392 iss/sub). The <em>transparency receipt</em> (an inclusion proof
+ *   from an append-only transparency service, COSE Receipts /
+ *   draft-ietf-cose-merkle-tree-proofs) and the transparency-service
+ *   registration protocol (draft-ietf-scitt-*) are deferred until those
+ *   drafts publish — a signed statement produced here is the input a
+ *   transparency service registers, and the receipt format is the part
+ *   still in flux. Re-open on COSE-Receipts publication.
+ *
+ * @card
+ *   SCITT signed statements (RFC 9052 COSE + RFC 9597 CWT_Claims) — a
+ *   signed, issuer/subject-bound claim about an artifact (SBOM /
+ *   attestation / approval). Composes b.cose; transparency receipts
+ *   deferred to the COSE-Receipts draft.
+ */
+
+var cose = require("./cose");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var ScittError = defineClass("ScittError", { alwaysPermanent: true });
+
+// CWT_Claims header label (RFC 9597) and the two SCITT-required claim
+// labels inside it (RFC 8392 §3.1.1): iss = who states, sub = about what.
+var HDR_CWT_CLAIMS = 15;
+var CLAIM_ISS = 1;
+var CLAIM_SUB = 2;
+
+function _requireNonEmptyString(v, name) {
+  if (typeof v !== "string" || v.length === 0) {
+    throw new ScittError("scitt/bad-" + name,
+      "scitt.signStatement: opts." + name + " is required and must be a non-empty string");
+  }
+}
+
+/**
+ * @primitive b.scitt.signStatement
+ * @signature b.scitt.signStatement(payload, opts)
+ * @since     0.12.37
+ * @status    experimental
+ * @compliance soc2, cra
+ * @related   b.scitt.verifyStatement, b.cose.sign
+ *
+ * Produce a SCITT signed statement: a COSE_Sign1 over
+ * <code>payload</code> (the artifact bytes, or a hash / reference to
+ * it) whose integrity-protected CWT_Claims header (label 15) binds the
+ * issuer (<code>iss</code>) and subject (<code>sub</code>). Declare the
+ * payload media type via <code>contentType</code> so a consumer knows
+ * how to interpret it.
+ *
+ * @opts
+ *   {
+ *     alg:          string,        // b.cose alg: "ES256" | … | "ML-DSA-87"
+ *     privateKey:   object,        // matching KeyObject or PEM
+ *     issuer:       string,        // → CWT_Claims iss (label 1) — who makes the statement
+ *     subject:      string,        // → CWT_Claims sub (label 2) — the artifact the statement is about
+ *     contentType?: number|string, // payload media type (e.g. "application/spdx+json")
+ *     claims?:      object,        // extra CWT claims by integer label, merged into CWT_Claims
+ *     kid?:         string,        // → unprotected header label 4
+ *     externalAad?: Buffer,        // bound into the signature
+ *   }
+ *
+ * @example
+ *   var stmt = await b.scitt.signStatement(sbomBytes, {
+ *     alg: "ES256", privateKey: issuerKey,
+ *     issuer: "https://builder.example", subject: "pkg:npm/widget@1.2.3",
+ *     contentType: "application/spdx+json",
+ *   });
+ */
+async function signStatement(payload, opts) {
+  validateOpts.requireObject(opts, "scitt.signStatement", ScittError);
+  validateOpts(opts,
+    ["alg", "privateKey", "issuer", "subject", "contentType", "claims", "kid", "externalAad"],
+    "scitt.signStatement");
+  _requireNonEmptyString(opts.issuer, "issuer");
+  _requireNonEmptyString(opts.subject, "subject");
+
+  var cwtClaims = new Map();
+  cwtClaims.set(CLAIM_ISS, opts.issuer);
+  cwtClaims.set(CLAIM_SUB, opts.subject);
+  // Extra CWT claims (e.g. iat = 6, a registration-policy claim) keyed
+  // by their integer label. iss / sub are managed via opts.issuer /
+  // opts.subject and cannot be overridden here.
+  if (opts.claims && typeof opts.claims === "object") {
+    var ck = opts.claims instanceof Map ? Array.from(opts.claims.keys()) : Object.keys(opts.claims);
+    for (var i = 0; i < ck.length; i++) {
+      var label = Number(ck[i]);
+      if (!Number.isInteger(label)) {
+        throw new ScittError("scitt/bad-claim-label",
+          "scitt.signStatement: claims keys must be integer CWT claim labels");
+      }
+      if (label === CLAIM_ISS || label === CLAIM_SUB) {
+        throw new ScittError("scitt/reserved-claim",
+          "scitt.signStatement: set iss / sub via opts.issuer / opts.subject, not opts.claims");
+      }
+      var val = opts.claims instanceof Map ? opts.claims.get(ck[i]) : opts.claims[ck[i]];
+      cwtClaims.set(label, val);
+    }
+  }
+
+  var protectedHeaders = {};
+  protectedHeaders[HDR_CWT_CLAIMS] = cwtClaims;
+
+  return cose.sign(payload, {
+    alg:              opts.alg,
+    privateKey:       opts.privateKey,
+    kid:              opts.kid,
+    contentType:      opts.contentType,
+    externalAad:      opts.externalAad,
+    protectedHeaders: protectedHeaders,
+  });
+}
+
+/**
+ * @primitive b.scitt.verifyStatement
+ * @signature b.scitt.verifyStatement(statement, opts)
+ * @since     0.12.37
+ * @status    experimental
+ * @compliance soc2, cra
+ * @related   b.scitt.signStatement, b.cose.verify
+ *
+ * Verify a SCITT signed statement and return its payload + identity
+ * binding. The COSE signature is checked through
+ * <code>b.cose.verify</code> (the algorithm allowlist is mandatory); a
+ * statement that does not carry a CWT_Claims header with both
+ * <code>iss</code> and <code>sub</code> is refused — that binding is
+ * what makes it a SCITT statement rather than a bare COSE_Sign1.
+ * <code>expectedIssuer</code> / <code>expectedSubject</code>, when
+ * given, must match.
+ *
+ * @opts
+ *   {
+ *     algorithms:       string[],  // required — accepted alg names (allowlist)
+ *     publicKey?:       object,    // verification key (KeyObject / PEM)
+ *     keyResolver?:     function,  // (protectedHeaders, unprotectedHeaders) → key
+ *     expectedIssuer?:  string,    // require iss === this
+ *     expectedSubject?: string,    // require sub === this
+ *     externalAad?:     Buffer,    // must match what was signed
+ *     maxBytes?:        number,    // forwarded to b.cose.verify → b.cbor.decode
+ *     maxDepth?:        number,
+ *   }
+ *
+ * @example
+ *   var out = await b.scitt.verifyStatement(stmt, {
+ *     algorithms: ["ES256"], publicKey: issuerPub,
+ *     expectedSubject: "pkg:npm/widget@1.2.3",
+ *   });
+ *   // → { payload: <Buffer>, issuer, subject, cwtClaims: Map, alg, protectedHeaders, unprotectedHeaders }
+ */
+async function verifyStatement(statement, opts) {
+  validateOpts.requireObject(opts, "scitt.verifyStatement", ScittError);
+  validateOpts(opts,
+    ["algorithms", "publicKey", "keyResolver", "expectedIssuer", "expectedSubject",
+     "externalAad", "maxBytes", "maxDepth"],
+    "scitt.verifyStatement");
+
+  var out = await cose.verify(statement, {
+    algorithms:  opts.algorithms,
+    publicKey:   opts.publicKey,
+    keyResolver: opts.keyResolver,
+    externalAad: opts.externalAad,
+    maxBytes:    opts.maxBytes,
+    maxDepth:    opts.maxDepth,
+  });
+
+  var cwtClaims = out.protectedHeaders.get(HDR_CWT_CLAIMS);
+  if (!(cwtClaims instanceof Map)) {
+    throw new ScittError("scitt/missing-cwt-claims",
+      "scitt.verifyStatement: no CWT_Claims header (label 15) — not a SCITT signed statement");
+  }
+  var issuer = cwtClaims.get(CLAIM_ISS);
+  var subject = cwtClaims.get(CLAIM_SUB);
+  if (issuer === undefined || issuer === null) {
+    throw new ScittError("scitt/missing-issuer",
+      "scitt.verifyStatement: CWT_Claims has no iss (label 1)");
+  }
+  if (subject === undefined || subject === null) {
+    throw new ScittError("scitt/missing-subject",
+      "scitt.verifyStatement: CWT_Claims has no sub (label 2)");
+  }
+  if (opts.expectedIssuer !== undefined && issuer !== opts.expectedIssuer) {
+    throw new ScittError("scitt/issuer-mismatch",
+      "scitt.verifyStatement: iss does not match expectedIssuer");
+  }
+  if (opts.expectedSubject !== undefined && subject !== opts.expectedSubject) {
+    throw new ScittError("scitt/subject-mismatch",
+      "scitt.verifyStatement: sub does not match expectedSubject");
+  }
+
+  return {
+    payload:            out.payload,
+    issuer:             issuer,
+    subject:            subject,
+    cwtClaims:          cwtClaims,
+    alg:                out.alg,
+    protectedHeaders:   out.protectedHeaders,
+    unprotectedHeaders: out.unprotectedHeaders,
+  };
+}
+
+module.exports = {
+  signStatement:   signStatement,
+  verifyStatement: verifyStatement,
+  CWT_CLAIMS_LABEL: HDR_CWT_CLAIMS,
+  ScittError:      ScittError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.35",
+  "version": "0.12.37",
   "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:05721aa1-7108-4263-bd58-e67b140f3790",
+  "serialNumber": "urn:uuid:06167082-579c-4ea8-9d7e-30209b1be393",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T23:29:47.165Z",
+    "timestamp": "2026-05-25T01:10:14.224Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.35",
+      "bom-ref": "@blamejs/core@0.12.37",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.35",
+      "version": "0.12.37",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.35",
+      "purl": "pkg:npm/%40blamejs/core@0.12.37",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.35",
+      "ref": "@blamejs/core@0.12.37",
       "dependsOn": []
     }
   ]