@blamejs/blamejs-shop 0.0.127 → 0.0.128

package/lib/vendor/blamejs/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/vendor/blamejs/lib/cwt.js

@@ -0,0 +1,244 @@
+"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 or a Map");
+  }
+  validateOpts.requireObject(opts, "cwt.sign", CwtError);
+  validateOpts(opts, ["alg", "privateKey", "kid", "tagged", "externalAad"], "cwt.sign");
+
+  // Accept a plain object (string keys) OR a Map. A Map preserves
+  // INTEGER claim keys verbatim — profiles like b.eat pass their
+  // already-resolved integer labels through and must not have them
+  // stringified.
+  var source = (claims instanceof Map)
+    ? claims
+    : new Map(Object.keys(claims).map(function (k) { return [k, claims[k]]; }));
+
+  var map = new Map();
+  source.forEach(function (value, name) {
+    if (typeof name === "string" && 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((typeof name === "string" && 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,
+};