@blamejs/core 0.12.33 → 0.12.34

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- 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.
+
 - v0.12.33 (2026-05-24) — **`b.cose` — COSE_Sign1 sign / verify (RFC 9052) over the in-tree CBOR codec.** COSE is the signed-statement substrate under SCITT, CWT, and C2PA — the CBOR-native counterpart to JWS. `b.cose` ships COSE_Sign1 signing and verification composing the v0.12.32 `b.cbor` codec for the deterministic Sig_structure encoding. It signs with the classical COSE algorithms that interoperate today — ES256 / ES384 / ES512 (ECDSA) and EdDSA (Ed25519), all with final IANA algorithm ids (RFC 9053) — and with ML-DSA-87 (FIPS 204) for PQC-forward deployments. Verification accepts the same set, so the framework both produces COSE other implementations read today and consumes third-party COSE. There is no classical default: the caller names the algorithm and supplies the key. **Added:** *`b.cose.sign(payload, opts)` / `b.cose.verify(coseSign1, opts)`* — `sign` produces a tagged COSE_Sign1 with `alg` in the integrity-protected header; `verify` returns `{ payload, alg, protectedHeaders, unprotectedHeaders }`. The Sig_structure (`["Signature1", protected, external_aad, payload]`) is deterministically CBOR-encoded; ECDSA signatures use the IEEE-P1363 fixed-width encoding COSE mandates (RFC 9053 §2.1), not ASN.1 DER. `external_aad` is bound into the signature. v1 is single-signer with an attached payload; detached payload, COSE_Sign (multi-signer), COSE_Mac0, and COSE_Encrypt are deferred-with-condition (operator demand). **Security:** *Bounded, alg-allowlisted, crit-checked verification* — `verify` decodes the COSE_Sign1 bytes AND the protected-header bstr through the bounded `b.cbor.decode` (depth + size caps, indefinite-length / tag / duplicate-key refusal). `opts.algorithms` is a required allowlist (no defaults — name the accepted algorithms). A `crit` header (label 2) listing a header label the verifier does not understand is refused (RFC 9052 §3.1 crit-bypass defense), as is a `crit` label absent from the protected header. The COSE algorithm switch refuses any unrecognized id at the default branch. · *ML-DSA-87 COSE algorithm id is a non-final draft* — ML-DSA-87 uses COSE algorithm id `-50`, a requested (non-final) IANA assignment from draft-ietf-cose-dilithium — an ML-DSA-87 COSE_Sign1 is not yet broadly interoperable and the id may change; it is pinned deliberately with the re-open condition being IANA finalization. SLH-DSA-SHAKE-256f has no registered COSE algorithm id at all and cannot be represented in COSE. The COSE_Sign1 mechanism and the classical algorithms are stable; ML-DSA-87 is the forward-looking opt-in.
 
 - v0.12.32 (2026-05-24) — **`b.cbor` — bounded, deterministic in-tree CBOR codec (RFC 8949).** CBOR is the binary serialization underneath COSE (RFC 9052), CWT, SCITT, and WebAuthn attestation — a foundational substrate the framework needs in-tree to build signed-statement primitives without a third-party parser. `b.cbor` is that codec, bounded by default like every parser the framework ships: a binary decoder is attack surface, so the defaults refuse the shapes a hostile encoder uses to exhaust memory or stack. The encoder emits Deterministically Encoded CBOR (RFC 8949 §4.2) — shortest-form heads, definite lengths, map keys sorted by encoded bytes, no indefinite-length items — so two semantically-equal values encode to byte-identical output, the property COSE signatures and SCITT receipts depend on. **Added:** *`b.cbor.encode(value, opts?)` / `b.cbor.decode(buffer, opts?)` / `b.cbor.Tag`* — `encode` produces deterministic CBOR from numbers (integers + float64), bigint (64-bit range), strings, `Buffer` / `Uint8Array`, arrays, `Map` or plain objects, `b.cbor.Tag`, and the simple values. `decode` returns the value with maps decoded to a `Map` (CBOR keys may be integers — COSE header labels are) and byte strings to `Buffer`. `b.cbor.Tag(tag, value)` carries a major-type-6 tagged item. `decode(buf, { requireDeterministic: true })` additionally asserts the input was itself canonically encoded (decode → re-encode → byte-compare), refusing a non-canonical re-encoding on a signature-verify path where it would be a malleability vector. **Security:** *Bounded-by-default decoder* — `maxDepth` (default 64, ceiling 256) caps nesting against stack exhaustion; `maxBytes` (default 16 MiB, ceiling 64 MiB) caps total input, and a declared string / array / map length exceeding the remaining bytes is refused before any allocation (no length-prefix memory bomb). Indefinite-length items (additional-info 31) are refused — a streaming-complexity / DoS vector forbidden by deterministic encoding. Reserved additional-info (28–30) is refused. Tags are refused unless allowlisted via `allowedTags` (a tag triggers semantic reprocessing — an un-vetted tag is a confused-deputy vector). Duplicate map keys (RFC 8949 §5.6) and trailing bytes after the data item are refused.

package/README.md

@@ -127,6 +127,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **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
+- **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
 - **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

@@ -457,6 +457,7 @@ module.exports = {
   jose:             { jwe: { experimental: require("./lib/jose-jwe-experimental") } },
   cbor:             require("./lib/cbor"),
   cose:             require("./lib/cose"),
+  cwt:              require("./lib/cwt"),
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/cwt.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * @module b.cwt
+ * @nav    Crypto
+ * @title  CBOR Web Token (CWT)
+ *
+ * @intro
+ *   RFC 8392 CBOR Web Token — the CBOR-native counterpart to JWT, a
+ *   signed claims set for constrained / IoT, FIDO attestation, and
+ *   verifiable-credential contexts. A CWT is a COSE_Sign1
+ *   (<code>b.cose</code>) whose payload is a deterministically-encoded
+ *   CBOR claims map (<code>b.cbor</code>) — this module composes both
+ *   and layers the standard-claim handling on top.
+ *
+ *   <code>b.cwt.sign(claims, opts)</code> accepts a friendly claims
+ *   object; the standard claims are mapped to their RFC 8392 §3.1.1
+ *   integer labels (<code>iss</code>=1, <code>sub</code>=2,
+ *   <code>aud</code>=3, <code>exp</code>=4, <code>nbf</code>=5,
+ *   <code>iat</code>=6, <code>cti</code>=7) and any other key is kept
+ *   verbatim. <code>b.cwt.verify(cwt, opts)</code> verifies the COSE
+ *   signature (delegating the mandatory algorithm allowlist to
+ *   <code>b.cose.verify</code>), decodes the claims, and enforces the
+ *   time + identity claims: a passed <code>exp</code>, a future
+ *   <code>nbf</code>, an <code>iss</code> / <code>aud</code> mismatch
+ *   against the expected values are each refused.
+ *
+ *   Signing algorithms follow <code>b.cose</code>: the classical
+ *   ES256/384/512 + EdDSA (final COSE ids, interoperable today) and
+ *   ML-DSA-87 (PQC-forward). The optional CWT CBOR tag (61, RFC 8392
+ *   §6) wraps the COSE_Sign1 when <code>opts.tagged</code> is set;
+ *   <code>verify</code> accepts tagged and untagged input.
+ *
+ * @card
+ *   RFC 8392 CBOR Web Token — sign / verify a CBOR claims set as a
+ *   COSE_Sign1, with standard-claim mapping + exp / nbf / iss / aud
+ *   enforcement. Composes b.cose + b.cbor.
+ */
+
+var cose = require("./cose");
+var cbor = require("./cbor");
+var C = require("./constants");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var CwtError = defineClass("CwtError", { alwaysPermanent: true });
+
+// RFC 8392 §3.1.1 standard claim labels.
+var STD = { iss: 1, sub: 2, aud: 3, exp: 4, nbf: 5, iat: 6, cti: 7 };
+var STD_BY_LABEL = {};
+Object.keys(STD).forEach(function (k) { STD_BY_LABEL[STD[k]] = k; });
+
+var NUMERIC_DATE_CLAIMS = { exp: true, nbf: true, iat: true };
+
+// CWT CBOR tag (RFC 8392 §6) — 61, encoded as the 2-byte head 0xd8 0x3d.
+var CWT_TAG_PREFIX = Buffer.from([0xd8, 0x3d]);                                        // allow:raw-byte-literal — CBOR tag-61 head (0xd8=tag 1-byte arg, 0x3d=61)
+
+function _nowSec(opts) {
+  var ms = (opts && typeof opts.now === "number") ? opts.now : Date.now();
+  return Math.floor(ms / C.TIME.seconds(1));
+}
+
+// Read a leading CBOR tag head (major type 6) in any of its encodings;
+// returns { tag, len } or null if the buffer doesn't start with a tag.
+function _readTagHead(buf) {
+  if (buf.length < 1 || (buf[0] >> 5) !== 6) return null;                               // allow:raw-byte-literal — CBOR major-type 6 (tag) shift
+  var ai = buf[0] & 0x1f;
+  if (ai < 24) return { tag: ai, len: 1 };
+  if (ai === 24) return buf.length >= 2 ? { tag: buf[1], len: 2 } : null;               // allow:raw-byte-literal — CBOR additional-info threshold (RFC 8949 §3), not a size
+  if (ai === 25) return buf.length >= 3 ? { tag: buf.readUInt16BE(1), len: 3 } : null;
+  if (ai === 26) return buf.length >= 5 ? { tag: buf.readUInt32BE(1), len: 5 } : null;
+  if (ai === 27) return buf.length >= 9 ? { tag: Number(buf.readBigUInt64BE(1)), len: 9 } : null;
+  return null;                                                                          // reserved / indefinite — not a tag head we accept
+}
+
+/**
+ * @primitive b.cwt.sign
+ * @signature b.cwt.sign(claims, opts)
+ * @since     0.12.34
+ * @status    stable
+ * @related   b.cwt.verify, b.cose.sign
+ *
+ * Sign a claims set into a CWT (a COSE_Sign1 over the CBOR-encoded
+ * claims). Standard claims are mapped to their integer labels; custom
+ * claims (string or integer keys) are kept as given. <code>exp</code>
+ * / <code>nbf</code> / <code>iat</code> must be integer NumericDates
+ * (seconds since the epoch).
+ *
+ * @opts
+ *   {
+ *     alg:        string,   // COSE signing alg (ES256 / EdDSA / ML-DSA-87 / …)
+ *     privateKey: object,   // signing key (per b.cose.sign)
+ *     kid?:       string,   // COSE kid header
+ *     tagged?:    boolean,  // wrap in CWT CBOR tag 61 (default false)
+ *     externalAad?: Buffer, // bound into the COSE signature
+ *   }
+ *
+ * @example
+ *   var cwt = await b.cwt.sign(
+ *     { iss: "issuer.example", sub: "device-42", exp: Math.floor(Date.now()/1000) + 3600, scope: "telemetry" },
+ *     { alg: "ES256", privateKey: ecKey, kid: "k1" });
+ */
+async function sign(claims, opts) {
+  if (!claims || typeof claims !== "object" || Array.isArray(claims)) {
+    throw new CwtError("cwt/bad-claims", "cwt.sign: claims must be a plain object");
+  }
+  validateOpts.requireObject(opts, "cwt.sign", CwtError);
+  validateOpts(opts, ["alg", "privateKey", "kid", "tagged", "externalAad"], "cwt.sign");
+
+  var map = new Map();
+  var keys = Object.keys(claims);
+  for (var i = 0; i < keys.length; i++) {
+    var name = keys[i];
+    var value = claims[name];
+    if (NUMERIC_DATE_CLAIMS[name] &&
+        (typeof value !== "number" || !Number.isInteger(value) || value < 0)) {
+      throw new CwtError("cwt/bad-numeric-date",
+        "cwt.sign: claim '" + name + "' must be a non-negative integer NumericDate (seconds)");
+    }
+    map.set(Object.prototype.hasOwnProperty.call(STD, name) ? STD[name] : name, value);
+  }
+
+  var claimsCbor = cbor.encode(map);
+  var coseSign1 = await cose.sign(claimsCbor, {
+    alg: opts.alg, privateKey: opts.privateKey, kid: opts.kid, externalAad: opts.externalAad,
+  });
+  return opts.tagged === true ? Buffer.concat([CWT_TAG_PREFIX, coseSign1]) : coseSign1;
+}
+
+/**
+ * @primitive b.cwt.verify
+ * @signature b.cwt.verify(cwt, opts)
+ * @since     0.12.34
+ * @status    stable
+ * @related   b.cwt.sign, b.cose.verify
+ *
+ * Verify a CWT and return its claims. The COSE signature is checked
+ * via <code>b.cose.verify</code> (mandatory <code>algorithms</code>
+ * allowlist), then the standard time / identity claims are enforced:
+ * a passed <code>exp</code> (with <code>clockSkewSec</code> tolerance),
+ * a not-yet-valid <code>nbf</code>, and — when requested — an
+ * <code>iss</code> / <code>aud</code> mismatch are refused. Accepts a
+ * CWT-tag-61-wrapped or bare COSE_Sign1.
+ *
+ * @opts
+ *   {
+ *     algorithms:       string[],  // required — accepted COSE algs (allowlist)
+ *     publicKey?:       object,    // verification key (per b.cose.verify)
+ *     keyResolver?:     function,
+ *     expectedIssuer?:  string,    // require iss === this
+ *     expectedAudience?: string,   // require aud to include this
+ *     clockSkewSec?:    number,    // default 60
+ *     now?:             number,    // override clock (ms) for testing
+ *     externalAad?:     Buffer,
+ *   }
+ *
+ * @example
+ *   var out = await b.cwt.verify(cwt, { algorithms: ["ES256"], publicKey: pub, expectedIssuer: "issuer.example" });
+ *   // → { claims: { iss, sub, exp, scope }, raw: Map, protectedHeaders: Map }
+ */
+async function verify(cwt, opts) {
+  if (!Buffer.isBuffer(cwt) && !(cwt instanceof Uint8Array)) {
+    throw new CwtError("cwt/bad-input", "cwt.verify: cwt must be a Buffer / Uint8Array");
+  }
+  validateOpts.requireObject(opts, "cwt.verify", CwtError);
+  validateOpts(opts, [
+    "algorithms", "publicKey", "keyResolver", "expectedIssuer",
+    "expectedAudience", "clockSkewSec", "now", "externalAad",
+  ], "cwt.verify");
+
+  // Strip the optional CWT tag-61 wrapper to recover the COSE_Sign1.
+  // Read the tag head generically (1 / 2 / 3 / 5 / 9-byte argument
+  // forms) rather than matching only the minimal 0xd8 0x3d encoding —
+  // an external CBOR encoder may emit a non-minimal but valid tag 61.
+  var coseBytes = Buffer.from(cwt);
+  var head = _readTagHead(coseBytes);
+  if (head && head.tag === 61) coseBytes = coseBytes.subarray(head.len);                // allow:raw-byte-literal — CWT CBOR tag number (RFC 8392 §6)
+
+  var verified = await cose.verify(coseBytes, {
+    algorithms: opts.algorithms, publicKey: opts.publicKey,
+    keyResolver: opts.keyResolver, externalAad: opts.externalAad,
+  });
+
+  var raw = cbor.decode(verified.payload);
+  if (!(raw instanceof Map)) {
+    throw new CwtError("cwt/bad-claims", "cwt.verify: claims payload is not a CBOR map");
+  }
+
+  // Time claims (NumericDate, seconds). Skew tolerance both directions.
+  var skew = (typeof opts.clockSkewSec === "number" && opts.clockSkewSec >= 0) ? opts.clockSkewSec : 60;   // allow:numeric-opt-Infinity — clamped non-negative, else default / allow:raw-time-literal — clock-skew in seconds (NumericDate units), not a ms duration
+  var now = _nowSec(opts);
+  // A present exp / nbf MUST be a well-formed NumericDate — a non-numeric
+  // value would otherwise bypass the time check entirely (a token could
+  // carry exp: "whenever" and never expire). Refuse the malformed claim.
+  if (raw.has(STD.exp)) {
+    var exp = raw.get(STD.exp);
+    if (typeof exp !== "number" || !isFinite(exp)) {
+      throw new CwtError("cwt/malformed-claim", "cwt.verify: exp claim is present but not a numeric NumericDate");
+    }
+    if (now > exp + skew) {
+      throw new CwtError("cwt/expired", "cwt.verify: token expired (exp " + exp + " < now " + now + ")");
+    }
+  }
+  if (raw.has(STD.nbf)) {
+    var nbf = raw.get(STD.nbf);
+    if (typeof nbf !== "number" || !isFinite(nbf)) {
+      throw new CwtError("cwt/malformed-claim", "cwt.verify: nbf claim is present but not a numeric NumericDate");
+    }
+    if (now < nbf - skew) {
+      throw new CwtError("cwt/not-yet-valid", "cwt.verify: token not yet valid (nbf " + nbf + " > now " + now + ")");
+    }
+  }
+  if (opts.expectedIssuer != null) {
+    if (raw.get(STD.iss) !== opts.expectedIssuer) {
+      throw new CwtError("cwt/issuer-mismatch", "cwt.verify: iss does not match expectedIssuer");
+    }
+  }
+  if (opts.expectedAudience != null) {
+    var aud = raw.get(STD.aud);
+    var audOk = Array.isArray(aud) ? aud.indexOf(opts.expectedAudience) !== -1 : aud === opts.expectedAudience;
+    if (!audOk) {
+      throw new CwtError("cwt/audience-mismatch", "cwt.verify: aud does not include expectedAudience");
+    }
+  }
+
+  // Build a friendly claims object (standard labels → names).
+  var claims = {};
+  raw.forEach(function (v, k) {
+    claims[Object.prototype.hasOwnProperty.call(STD_BY_LABEL, k) ? STD_BY_LABEL[k] : k] = v;
+  });
+
+  return { claims: claims, raw: raw, alg: verified.alg, protectedHeaders: verified.protectedHeaders };
+}
+
+module.exports = {
+  sign:        sign,
+  verify:      verify,
+  CLAIM_LABELS: STD,
+  CwtError:    CwtError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.33",
+  "version": "0.12.34",
   "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:fc9aad21-216e-4059-88da-1a9dc8373559",
+  "serialNumber": "urn:uuid:619f056d-4027-4805-8bea-f39101edd638",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T21:32:33.865Z",
+    "timestamp": "2026-05-24T22:52:17.036Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.33",
+      "bom-ref": "@blamejs/core@0.12.34",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.33",
+      "version": "0.12.34",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.33",
+      "purl": "pkg:npm/%40blamejs/core@0.12.34",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.33",
+      "ref": "@blamejs/core@0.12.34",
       "dependsOn": []
     }
   ]