@blamejs/core 0.12.36 → 0.12.38

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.38 (2026-05-24) — **`b.tsa` — RFC 3161 trusted timestamping client (build / parse / verify).** A timestamp authority binds a hash of your data to a trusted time, producing a token that proves the data existed at that instant — timestamp a release artifact, an audit-log checkpoint, a b.scitt signed statement, or a contract. b.tsa is the requester/verifier side of RFC 3161: buildRequest produces the DER TimeStampReq (the message imprint plus an optional nonce and a cert request), parseResponse reads the TimeStampResp (PKIStatus, failure-info bits, and the token), and verifyToken checks a token against your data and returns the asserted time. Verification is done in full per §2.4.2 / §2.3: the token is a CMS SignedData (b.cms) whose eContentType must be id-ct-TSTInfo; the message imprint must equal the hash of your data (constant-time); a sent nonce must round-trip; the signer certificate's extendedKeyUsage must be a critical, sole id-kp-timeStamping; and the CMS signature over the signed attributes must verify after the messageDigest attribute is matched to the recomputed eContent digest. An optional trust-anchor set verifies the certificate chain and validity at the asserted time. The HTTP transport to the TSA is the operator's to make. Composes b.cms and the in-tree ASN.1 DER codec; no new runtime dependency. **Added:** *`b.tsa.buildRequest(data, opts?)` / `b.tsa.parseResponse(der)` / `b.tsa.verifyToken(token, opts)`* — `buildRequest` returns `{ der, nonce, hashAlg, messageImprint }`; the imprint hash defaults to SHA-512 and may be SHA-256/384/512 or SHA3-256/512, a random 64-bit nonce and a certificate request are included by default, and a pre-hashed input is accepted with `hashed: true`. `parseResponse` returns `{ granted, status, statusString, failInfo, token }`, decoding the PKIFailureInfo bits for a non-granted response rather than throwing. `verifyToken` enforces the imprint match (`opts.data` or `opts.hash`), the nonce round-trip, the critical/sole `id-kp-timeStamping` EKU, and the CMS signature, returning `{ genTime, policy, serialHex, accuracy, hashAlg, signerCertPem }`; pass `opts.trustAnchorsPem` to also verify the certificate chain and validity at the asserted time. Timestamp tokens are third-party artifacts, so verification accepts the classical RSA (PKCS#1 v1.5 and PSS) and ECDSA-over-SHA-2 signatures that public TSAs emit — the same consume-what-exists posture as `b.cose` verification, not a framework signing default.
+
+- 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.

package/README.md

@@ -129,6 +129,8 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **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
+- **Trusted timestamping** — `b.tsa` RFC 3161 timestamp client: `buildRequest` a TimeStampReq, `parseResponse`, and `verifyToken` against your data — the message imprint, sent nonce, critical/sole `id-kp-timeStamping` EKU, and CMS signature are all checked, with optional certificate-chain verification. Timestamp a release artifact, audit checkpoint, or signed statement against any RFC 3161 TSA. Composes `b.cms` + the in-tree ASN.1 DER codec
 - **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,8 @@ module.exports = {
   cose:             require("./lib/cose"),
   cwt:              require("./lib/cwt"),
   eat:              require("./lib/eat"),
+  scitt:            require("./lib/scitt"),
+  tsa:              require("./lib/tsa"),
   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();

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/lib/tsa.js

@@ -0,0 +1,688 @@
+"use strict";
+/**
+ * @module b.tsa
+ * @nav    Crypto
+ * @title  Timestamping (RFC 3161)
+ *
+ * @intro
+ *   An RFC 3161 Time-Stamp Protocol client — the requester / verifier
+ *   side, not a TSA. A timestamp authority binds a hash of your data to
+ *   a trusted time, producing a timestamp token that proves the data
+ *   existed at that instant: timestamp a release artifact, an audit-log
+ *   checkpoint, a <code>b.scitt</code> signed statement, a contract.
+ *
+ *   <code>b.tsa.buildRequest(data, opts)</code> produces the DER
+ *   TimeStampReq (a message imprint = the hash of your data, plus an
+ *   optional nonce and a request for the TSA's certificate);
+ *   <code>b.tsa.parseResponse(der)</code> reads the TimeStampResp,
+ *   surfacing the PKIStatus (and any failure-info bits) and the token;
+ *   <code>b.tsa.verifyToken(token, opts)</code> verifies the token
+ *   against your data and returns the asserted time. The transport (an
+ *   HTTP POST of <code>application/timestamp-query</code> to the TSA's
+ *   URL) is the operator's to make — the framework builds the request
+ *   and verifies the response.
+ *
+ *   <strong>Verification</strong> (RFC 3161 §2.4.2 / §2.3) is the
+ *   security-bearing part and is done in full: the token is a CMS
+ *   SignedData (<code>b.cms</code>) whose eContentType must be
+ *   <code>id-ct-TSTInfo</code>; the message imprint inside the TSTInfo
+ *   must equal the hash of your data (constant-time compare); a sent
+ *   nonce must round-trip; the signer's certificate must carry the
+ *   <code>id-kp-timeStamping</code> extended key usage, marked critical
+ *   and as the <em>only</em> EKU; and the CMS signature over the signed
+ *   attributes must verify (the <code>messageDigest</code> attribute is
+ *   checked against the recomputed eContent digest first). An optional
+ *   trust-anchor set verifies the certificate chain and validity at the
+ *   asserted time.
+ *
+ *   <strong>Algorithms.</strong> Timestamp tokens are third-party
+ *   artifacts: public TSAs sign with classical RSA (PKCS#1 v1.5 or PSS)
+ *   or ECDSA over SHA-2, so verification accepts those — the same
+ *   consume-what-exists stance as <code>b.cose</code> verification. This
+ *   is not a signing default (the framework is not the TSA); it is
+ *   verification of externally-produced tokens. The message-imprint
+ *   hash you request defaults to SHA-512 and may be any of SHA-256 /
+ *   384 / 512 or SHA3-256 / 512 the TSA supports.
+ *
+ * @card
+ *   RFC 3161 timestamp client — build a TimeStampReq, parse the
+ *   response, and verify a timestamp token in full (imprint match,
+ *   nonce, id-kp-timeStamping EKU critical+sole, CMS signature, optional
+ *   chain). Composes b.cms + the in-tree ASN.1 DER codec.
+ */
+
+var nodeCrypto = require("node:crypto");
+var bCrypto = require("./crypto");
+var asn1 = require("./asn1-der");
+var cms = require("./cms-codec");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var TsaError = defineClass("TsaError", { alwaysPermanent: true });
+
+// id-ct-TSTInfo (RFC 3161 §2.4.2) — the eContentType of a timestamp token.
+var OID_TST_INFO = "1.2.840.113549.1.9.16.1.4";
+// id-kp-timeStamping (RFC 3161 §2.3) — the required, critical, sole EKU.
+var OID_KP_TIMESTAMPING = "1.3.6.1.5.5.7.3.8";
+var OID_EXT_EKU = "2.5.29.37";                       // certificate extendedKeyUsage extension
+var OID_MESSAGE_DIGEST = "1.2.840.113549.1.9.4";     // RFC 5652 messageDigest signed attribute
+var OID_CONTENT_TYPE = "1.2.840.113549.1.9.3";       // RFC 5652 contentType signed attribute
+
+// Message-imprint hash algorithms: name to { oid, nodeHash }.
+var IMPRINT_HASHES = {
+  "SHA-256":  { oid: "2.16.840.1.101.3.4.2.1",  nodeHash: "sha256" },
+  "SHA-384":  { oid: "2.16.840.1.101.3.4.2.2",  nodeHash: "sha384" },
+  "SHA-512":  { oid: "2.16.840.1.101.3.4.2.3",  nodeHash: "sha512" },
+  "SHA3-256": { oid: "2.16.840.1.101.3.4.2.8",  nodeHash: "sha3-256" },
+  "SHA3-512": { oid: "2.16.840.1.101.3.4.2.10", nodeHash: "sha3-512" },
+};
+var OID_TO_IMPRINT_HASH = {};
+Object.keys(IMPRINT_HASHES).forEach(function (n) { OID_TO_IMPRINT_HASH[IMPRINT_HASHES[n].oid] = n; });
+
+// Signer signature algorithms a real TSA emits to node verify parameters.
+// scheme "rsa" = PKCS#1 v1.5, "pss" = RSASSA-PSS, "ecdsa" = ECDSA(DER).
+var SIG_ALGS = {
+  // Bare rsaEncryption — RFC 8933 / common CMS producers (incl. OpenSSL
+  // ts) put this in SignerInfo.signatureAlgorithm and take the hash from
+  // the separate digestAlgorithm field.
+  "1.2.840.113549.1.1.1":  { hash: null,     scheme: "rsa" },   // rsaEncryption (hash from digestAlg)
+  "1.2.840.113549.1.1.11": { hash: "sha256", scheme: "rsa" },   // sha256WithRSAEncryption
+  "1.2.840.113549.1.1.12": { hash: "sha384", scheme: "rsa" },   // sha384WithRSAEncryption
+  "1.2.840.113549.1.1.13": { hash: "sha512", scheme: "rsa" },   // sha512WithRSAEncryption
+  "1.2.840.113549.1.1.10": { hash: null,     scheme: "pss" },   // RSASSA-PSS (hash from signerInfo digestAlg)
+  // Bare id-ecPublicKey appears in some producers' SignerInfo too.
+  "1.2.840.10045.2.1":     { hash: null,     scheme: "ecdsa" }, // id-ecPublicKey (hash from digestAlg)
+  "1.2.840.10045.4.3.2":   { hash: "sha256", scheme: "ecdsa" }, // ecdsa-with-SHA256
+  "1.2.840.10045.4.3.3":   { hash: "sha384", scheme: "ecdsa" }, // ecdsa-with-SHA384
+  "1.2.840.10045.4.3.4":   { hash: "sha512", scheme: "ecdsa" }, // ecdsa-with-SHA512
+};
+var DIGEST_OID_TO_NODE = {
+  "2.16.840.1.101.3.4.2.1":  "sha256",
+  "2.16.840.1.101.3.4.2.2":  "sha384",
+  "2.16.840.1.101.3.4.2.3":  "sha512",
+  "2.16.840.1.101.3.4.2.8":  "sha3-256",
+  "2.16.840.1.101.3.4.2.10": "sha3-512",
+};
+
+function _bytes(x, what) {
+  if (Buffer.isBuffer(x)) return x;
+  if (x instanceof Uint8Array) return Buffer.from(x);
+  if (typeof x === "string") return Buffer.from(x, "utf8");
+  throw new TsaError("tsa/bad-bytes", "tsa: " + what + " must be Buffer / Uint8Array / string");
+}
+
+function _normHex(h) {
+  return String(h).replace(/[^0-9a-fA-F]/g, "").replace(/^0+(?=.)/, "").toUpperCase();
+}
+
+// Resolve the message imprint: hash the data, or use a pre-computed hash.
+function _imprint(data, opts, fnName) {
+  var hashName = opts.hashAlg || "SHA-512";
+  var h = IMPRINT_HASHES[hashName];
+  if (!h) {
+    throw new TsaError("tsa/bad-hash-alg",
+      fnName + ": hashAlg must be one of " + Object.keys(IMPRINT_HASHES).join(" / "));
+  }
+  var digest;
+  if (opts.hashed) {
+    digest = _bytes(data, "hash");
+    var expectLen = nodeCrypto.createHash(h.nodeHash).update(Buffer.alloc(0)).digest().length;
+    if (digest.length !== expectLen) {
+      throw new TsaError("tsa/bad-hash-length",
+        fnName + ": pre-hashed input is " + digest.length + " bytes, expected " +
+        expectLen + " for " + hashName);
+    }
+  } else {
+    digest = nodeCrypto.createHash(h.nodeHash).update(_bytes(data, "data")).digest();
+  }
+  return { hashName: hashName, hashOid: h.oid, digest: digest };
+}
+
+/**
+ * @primitive b.tsa.buildRequest
+ * @signature b.tsa.buildRequest(data, opts?)
+ * @since     0.12.38
+ * @status    experimental
+ * @compliance soc2
+ * @related   b.tsa.parseResponse, b.tsa.verifyToken
+ *
+ * Build a DER-encoded RFC 3161 TimeStampReq for <code>data</code>. POST
+ * the returned bytes to the TSA as <code>application/timestamp-query</code>;
+ * keep the returned <code>nonce</code> to pass to
+ * <code>verifyToken</code>. By default a random 64-bit nonce is included
+ * and the TSA is asked to return its certificate.
+ *
+ * @opts
+ *   {
+ *     hashAlg:    string,   // "SHA-512" (default) | "SHA-256" | "SHA-384" | "SHA3-256" | "SHA3-512"
+ *     hashed:     boolean,  // true means `data` is already the digest (must match hashAlg length)
+ *     reqPolicy:  string,   // request a specific TSA policy OID (dotted)
+ *     nonce:      Buffer,   // explicit nonce bytes, or false to omit (default: random 8 bytes)
+ *     certReq:    boolean,  // ask the TSA to include its cert (default true)
+ *   }
+ *
+ * @example
+ *   var req = b.tsa.buildRequest(releaseTarball, { hashAlg: "SHA-512" });
+ *   // POST req.der to the TSA; keep req.nonce for verifyToken
+ *   // → { der, nonce, hashAlg, messageImprint }
+ */
+function buildRequest(data, opts) {
+  opts = opts || {};
+  validateOpts.requireObject(opts, "tsa.buildRequest", TsaError);
+  validateOpts(opts, ["hashAlg", "hashed", "reqPolicy", "nonce", "certReq"], "tsa.buildRequest");
+  var imp = _imprint(data, opts, "tsa.buildRequest");
+
+  var algId = asn1.writeSequence([asn1.writeOid(imp.hashOid), asn1.writeNull()]);
+  var messageImprint = asn1.writeSequence([algId, asn1.writeOctetString(imp.digest)]);
+
+  var children = [asn1.writeInteger(Buffer.from([1])), messageImprint];          // version 1
+  if (typeof opts.reqPolicy === "string") children.push(asn1.writeOid(opts.reqPolicy));
+
+  var nonce = null;
+  if (opts.nonce !== false) {
+    nonce = Buffer.isBuffer(opts.nonce) ? opts.nonce : nodeCrypto.randomBytes(8);  // allow:raw-byte-literal — RFC 3161 nonce: 64-bit random
+    children.push(asn1.writeInteger(nonce));
+  }
+  // certReq DEFAULT FALSE — only encode when true (the default we want).
+  var certReq = opts.certReq !== false;
+  if (certReq) children.push(asn1.writeBoolean(true));
+
+  return {
+    der:            asn1.writeSequence(children),
+    nonce:          nonce,
+    hashAlg:        imp.hashName,
+    messageImprint: imp.digest,
+  };
+}
+
+/**
+ * @primitive b.tsa.parseResponse
+ * @signature b.tsa.parseResponse(der)
+ * @since     0.12.38
+ * @status    experimental
+ * @compliance soc2
+ * @related   b.tsa.buildRequest, b.tsa.verifyToken
+ *
+ * Parse a DER RFC 3161 TimeStampResp. Returns the PKIStatus and, when
+ * the request was granted, the timestamp token (the DER ContentInfo to
+ * pass to <code>verifyToken</code>). A non-granted status surfaces the
+ * status integer, any free-text, and the decoded failure-info flags
+ * rather than throwing — the caller decides how to react.
+ *
+ * @example
+ *   var resp = b.tsa.parseResponse(httpBodyBytes);
+ *   if (resp.granted) { var out = b.tsa.verifyToken(resp.token, { data: tarball, nonce: req.nonce }); }
+ *   // → { granted: true, status: 0, token, statusString: null, failInfo: [] }
+ */
+function parseResponse(der) {
+  var buf = _bytes(der, "der");
+  var root;
+  try { root = asn1.readNode(buf, 0); } catch (e) {
+    throw new TsaError("tsa/malformed", "tsa.parseResponse: not DER: " + ((e && e.message) || e));
+  }
+  if (root.tag !== asn1.TAG.SEQUENCE || root.tagClass !== asn1.TAG_CLASS.UNIVERSAL) {
+    throw new TsaError("tsa/malformed", "tsa.parseResponse: TimeStampResp must be a SEQUENCE");
+  }
+  var children = asn1.readSequence(root.value);
+  if (children.length < 1 || children[0].tag !== asn1.TAG.SEQUENCE) {
+    throw new TsaError("tsa/malformed", "tsa.parseResponse: missing PKIStatusInfo");
+  }
+  var statusInfo = asn1.readSequence(children[0].value);
+  if (statusInfo.length < 1 || statusInfo[0].tag !== asn1.TAG.INTEGER) {
+    throw new TsaError("tsa/malformed", "tsa.parseResponse: PKIStatusInfo missing status INTEGER");
+  }
+  var status = asn1.readUnsignedInt(statusInfo[0]);
+  if (typeof status !== "number") {
+    throw new TsaError("tsa/malformed", "tsa.parseResponse: status integer out of range");
+  }
+
+  var statusString = null;
+  var failInfo = [];
+  for (var i = 1; i < statusInfo.length; i += 1) {
+    var n = statusInfo[i];
+    if (n.tag === asn1.TAG.SEQUENCE && statusString === null) {
+      var texts = asn1.readSequence(n.value).map(function (t) { return t.value.toString("utf8"); });
+      statusString = texts.join("; ");
+    } else if (n.tag === asn1.TAG.BIT_STRING) {
+      failInfo = _decodeFailInfo(n);
+    }
+  }
+
+  // granted(0) / grantedWithMods(1) carry a token; 2..5 are failures.
+  var granted = status === 0 || status === 1;
+  var token = null;
+  if (granted) {
+    var tokNode = children[1];
+    if (!tokNode) {
+      throw new TsaError("tsa/no-token",
+        "tsa.parseResponse: status granted but no timeStampToken present");
+    }
+    token = tokNode.raw;
+  }
+  return { granted: granted, status: status, statusString: statusString, failInfo: failInfo, token: token };
+}
+
+// PKIFailureInfo bit names (RFC 3161 §2.4.2 / RFC 2510).
+var FAIL_INFO_BITS = {                                                                 // allow:raw-byte-literal — RFC 3161 PKIFailureInfo bit positions
+  0: "badAlg", 2: "badRequest", 5: "badDataFormat", 14: "timeNotAvailable",
+  15: "unacceptedPolicy", 16: "unacceptedExtension", 17: "addInfoNotAvailable", 25: "systemFailure",
+};
+function _decodeFailInfo(bitStringNode) {
+  var out = [];
+  var v = bitStringNode.value;
+  if (v.length <= 1) return out;                      // first byte = unused-bit count
+  var bits = v.slice(1);
+  for (var byteIdx = 0; byteIdx < bits.length; byteIdx += 1) {
+    for (var b = 0; b < 8; b += 1) {                    // allow:raw-byte-literal — 8 bits per byte
+      if (bits[byteIdx] & (0x80 >> b)) {
+        var pos = byteIdx * 8 + b;                      // allow:raw-byte-literal — 8 bits per byte
+        out.push(FAIL_INFO_BITS[pos] || ("bit" + pos));
+      }
+    }
+  }
+  return out;
+}
+
+// Parse GeneralizedTime "YYYYMMDDHHMMSS[.fff]Z" to Date (UTC).
+function _parseGeneralizedTime(node) {
+  var s = node.value.toString("ascii");
+  var m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\.\d+)?Z$/.exec(s);
+  if (!m) {
+    throw new TsaError("tsa/bad-gentime", "tsa: genTime is not a 'Z'-terminated GeneralizedTime: " + s);
+  }
+  // Fractional seconds (rare in timestamps) → milliseconds from the
+  // first three fractional digits, zero-padded; no float arithmetic.
+  var frac = m[7] ? m[7].slice(1) : "";
+  var ms = frac ? parseInt((frac + "000").slice(0, 3), 10) : 0;
+  var t = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6], ms);
+  return new Date(t);
+}
+
+// TSTInfo (RFC 3161 §2.4.2) to fields. messageImprint stays raw so
+// verifyToken can compare hash-alg OID + hashed bytes.
+function _parseTstInfo(eContent) {
+  var root = asn1.readNode(eContent, 0);
+  if (root.tag !== asn1.TAG.SEQUENCE) {
+    throw new TsaError("tsa/malformed", "tsa: TSTInfo must be a SEQUENCE");
+  }
+  var c = asn1.readSequence(root.value);
+  if (c.length < 5) throw new TsaError("tsa/malformed", "tsa: TSTInfo too short");
+  var idx = 0;
+  idx += 1;                                           // version
+  var policy = asn1.readOid(c[idx]); idx += 1;
+  var miNode = c[idx]; idx += 1;
+  var serialNode = c[idx]; idx += 1;
+  var genTime = _parseGeneralizedTime(c[idx]); idx += 1;
+
+  // Parse messageImprint { hashAlgorithm AlgId, hashedMessage OCTET STRING }.
+  var mi = asn1.readSequence(miNode.value);
+  var miAlg = asn1.readSequence(mi[0].value);
+  var miHashOid = asn1.readOid(miAlg[0]);
+  var miHash = asn1.readOctetString(mi[1]);
+
+  var accuracy = null;
+  var nonce = null;
+  for (; idx < c.length; idx += 1) {
+    var n = c[idx];
+    if (n.tagClass === asn1.TAG_CLASS.UNIVERSAL && n.tag === asn1.TAG.SEQUENCE && accuracy === null) {
+      accuracy = _parseAccuracy(n);
+    } else if (n.tagClass === asn1.TAG_CLASS.UNIVERSAL && n.tag === asn1.TAG.INTEGER) {
+      nonce = n.value;                                // raw INTEGER bytes
+    }
+    // ordering BOOLEAN, [0] tsa, [1] extensions are read but not surfaced in v1.
+  }
+
+  var serialHex = Buffer.isBuffer(serialNode.value) ? serialNode.value.toString("hex") : null;
+  return {
+    policy:       policy,
+    genTime:      genTime,
+    accuracy:     accuracy,
+    nonce:        nonce,
+    serialHex:    serialHex,
+    imprintHashOid: miHashOid,
+    imprintHash:  miHash,
+  };
+}
+
+function _parseAccuracy(node) {
+  var c = asn1.readSequence(node.value);
+  var out = { seconds: 0, millis: 0, micros: 0 };
+  for (var i = 0; i < c.length; i += 1) {
+    var n = c[i];
+    if (n.tagClass === asn1.TAG_CLASS.UNIVERSAL && n.tag === asn1.TAG.INTEGER) {
+      out.seconds = asn1.readUnsignedInt(n);
+    } else if (n.tagClass === asn1.TAG_CLASS.CONTEXT_SPECIFIC && n.tag === 0) {
+      out.millis = _ctxInt(n);
+    } else if (n.tagClass === asn1.TAG_CLASS.CONTEXT_SPECIFIC && n.tag === 1) {
+      out.micros = _ctxInt(n);
+    }
+  }
+  return out;
+}
+function _ctxInt(node) {
+  // [n] IMPLICIT INTEGER — value bytes are the integer content directly.
+  var v = node.value, n = 0;
+  for (var i = 0; i < v.length; i += 1) n = (n * 256) + v[i];  // allow:raw-byte-literal — base-256 integer accumulation
+  return n;
+}
+
+// Walk a certificate's extensions for one OID to { critical, valueBytes } or null.
+function _certExtension(certDer, wantOid) {
+  var cert = asn1.readNode(certDer, 0);
+  var top = asn1.readSequence(cert.value);            // [ tbs, sigAlg, sigValue ]
+  var tbs = asn1.readSequence(top[0].value);
+  // Find the [3] EXPLICIT extensions wrapper.
+  var extsWrapper = asn1.findChild(tbs, function (n) {
+    return n.tagClass === asn1.TAG_CLASS.CONTEXT_SPECIFIC && n.tag === 3;
+  });
+  if (!extsWrapper) return null;
+  var extsSeq = asn1.unwrapExplicit(extsWrapper, 3);
+  var exts = asn1.readSequence(extsSeq.value);
+  for (var i = 0; i < exts.length; i += 1) {
+    var ec = asn1.readSequence(exts[i].value);
+    var oid = asn1.readOid(ec[0]);
+    if (oid !== wantOid) continue;
+    var critical = false;
+    var valueNode = null;
+    for (var j = 1; j < ec.length; j += 1) {
+      if (ec[j].tag === asn1.TAG.BOOLEAN) critical = ec[j].value[0] !== 0;
+      else if (ec[j].tag === asn1.TAG.OCTET_STRING) valueNode = ec[j];
+    }
+    if (!valueNode) return null;
+    return { critical: critical, valueBytes: asn1.readOctetString(valueNode) };
+  }
+  return null;
+}
+
+// RFC 3161 §2.3: the signing cert's EKU MUST contain id-kp-timeStamping,
+// MUST be critical, and MUST be the only key purpose.
+function _checkTimestampingEku(certDer) {
+  var ext = _certExtension(certDer, OID_EXT_EKU);
+  if (!ext) {
+    throw new TsaError("tsa/bad-eku",
+      "tsa.verifyToken: signer certificate has no extendedKeyUsage (RFC 3161 §2.3 requires id-kp-timeStamping)");
+  }
+  if (!ext.critical) {
+    throw new TsaError("tsa/bad-eku",
+      "tsa.verifyToken: extendedKeyUsage is not marked critical (RFC 3161 §2.3)");
+  }
+  var purposes = asn1.readSequence(asn1.readNode(ext.valueBytes, 0).value).map(asn1.readOid);
+  if (purposes.length !== 1 || purposes[0] !== OID_KP_TIMESTAMPING) {
+    throw new TsaError("tsa/bad-eku",
+      "tsa.verifyToken: extendedKeyUsage must be exactly { id-kp-timeStamping } (got " +
+      purposes.join(", ") + ")");
+  }
+}
+
+// Pick the signing cert from the token: prefer the one whose serial
+// matches the SignerInfo sid (IssuerAndSerialNumber); else fall through
+// to all certs (the EKU + signature checks remain authoritative).
+function _candidateSigners(sidRaw, certs) {
+  var wantSerial = null;
+  try {
+    var sid = asn1.readNode(sidRaw, 0);
+    if (sid.tag === asn1.TAG.SEQUENCE && sid.tagClass === asn1.TAG_CLASS.UNIVERSAL) {
+      var parts = asn1.readSequence(sid.value);       // IssuerAndSerialNumber { issuer, serial }
+      var serialNode = parts[parts.length - 1];
+      if (serialNode && serialNode.tag === asn1.TAG.INTEGER) {
+        wantSerial = _normHex(serialNode.value.toString("hex"));
+      }
+    }
+  } catch (_e) { wantSerial = null; }
+  if (wantSerial === null) return certs.slice();
+  var matched = certs.filter(function (d) {
+    try { return _normHex(new nodeCrypto.X509Certificate(d).serialNumber) === wantSerial; }
+    catch (_e) { return false; }
+  });
+  return matched.length ? matched : certs.slice();
+}
+
+function _verifyCmsSignature(si, eContent, signerCertDer) {
+  var alg = SIG_ALGS[si.sigAlgOid];
+  if (!alg) {
+    throw new TsaError("tsa/bad-sig-alg",
+      "tsa.verifyToken: signer signature algorithm " + si.sigAlgOid +
+      " is not a supported RSA / ECDSA timestamp algorithm");
+  }
+  if (!si.signedAttrsRaw) {
+    throw new TsaError("tsa/no-signed-attrs",
+      "tsa.verifyToken: SignerInfo has no signed attributes (RFC 3161 tokens always sign attributes)");
+  }
+  var digestNode = DIGEST_OID_TO_NODE[si.digestAlgOid];
+  if (!digestNode) {
+    throw new TsaError("tsa/bad-digest",
+      "tsa.verifyToken: SignerInfo digest algorithm " + si.digestAlgOid + " unsupported");
+  }
+  // The eContent digest must equal the messageDigest signed attribute,
+  // and the contentType attribute must be id-ct-TSTInfo.
+  var attrs = _parseSignedAttrs(si.signedAttrsRaw);
+  if (!attrs.messageDigest) {
+    throw new TsaError("tsa/no-message-digest", "tsa.verifyToken: signed attrs missing messageDigest");
+  }
+  var actual = nodeCrypto.createHash(digestNode).update(eContent).digest();
+  if (!bCrypto.timingSafeEqual(actual, attrs.messageDigest)) {
+    throw new TsaError("tsa/message-digest-mismatch",
+      "tsa.verifyToken: recomputed eContent digest does not match the messageDigest attribute");
+  }
+  if (attrs.contentType && attrs.contentType !== OID_TST_INFO) {
+    throw new TsaError("tsa/bad-content-type-attr",
+      "tsa.verifyToken: signed contentType attribute is " + attrs.contentType + ", expected id-ct-TSTInfo");
+  }
+
+  var pubKey = new nodeCrypto.X509Certificate(signerCertDer).publicKey;
+  // For algorithm ids that don't name the hash (bare rsaEncryption /
+  // id-ecPublicKey / RSASSA-PSS), the hash comes from the digestAlgorithm.
+  var hashName = alg.hash || digestNode;
+  var keyParam = pubKey;
+  if (alg.scheme === "pss") {
+    keyParam = { key: pubKey, padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING,
+      saltLength: nodeCrypto.constants.RSA_PSS_SALTLEN_AUTO };
+  }
+  var ok;
+  try { ok = nodeCrypto.verify(hashName, si.signedAttrsRaw, keyParam, si.signature); }
+  catch (e) {
+    throw new TsaError("tsa/verify-threw",
+      "tsa.verifyToken: signature verification threw: " + ((e && e.message) || e));
+  }
+  if (!ok) {
+    throw new TsaError("tsa/bad-signature",
+      "tsa.verifyToken: CMS signature over the signed attributes did not verify");
+  }
+}
+
+// Parse the universal-SET signedAttrs bytes for contentType + messageDigest.
+function _parseSignedAttrs(signedAttrsRaw) {
+  var set = asn1.readNode(signedAttrsRaw, 0);
+  var attrs = asn1.readSequence(set.value);
+  var out = { contentType: null, messageDigest: null };
+  for (var i = 0; i < attrs.length; i += 1) {
+    var a = asn1.readSequence(attrs[i].value);        // Attribute { type OID, values SET }
+    var type = asn1.readOid(a[0]);
+    var valueSet = asn1.readSequence(a[1].value);
+    if (!valueSet.length) continue;
+    if (type === OID_MESSAGE_DIGEST) out.messageDigest = asn1.readOctetString(valueSet[0]);
+    else if (type === OID_CONTENT_TYPE) out.contentType = asn1.readOid(valueSet[0]);
+  }
+  return out;
+}
+
+// Optional: verify the signer chains to a trust anchor and is valid at `at`.
+function _verifyChain(signerCertDer, tokenCerts, trustAnchorsPem, at) {
+  var anchors = trustAnchorsPem.map(function (p) { return new nodeCrypto.X509Certificate(p); });
+  var pool = tokenCerts.map(function (d) { return new nodeCrypto.X509Certificate(d); });
+  var current = new nodeCrypto.X509Certificate(signerCertDer);
+  var seen = 0;
+  var atTime = at.getTime();
+  while (seen <= pool.length + 1) {
+    _assertValidAt(current, atTime);
+    // Anchor reached?
+    for (var a = 0; a < anchors.length; a += 1) {
+      if (_issued(anchors[a], current)) { _assertValidAt(anchors[a], atTime); return; }
+      if (current.fingerprint256 === anchors[a].fingerprint256) return;
+    }
+    // Walk up through the token's intermediates.
+    var parent = null;
+    for (var p = 0; p < pool.length; p += 1) {
+      if (pool[p].fingerprint256 !== current.fingerprint256 && _issued(pool[p], current)) {
+        parent = pool[p]; break;
+      }
+    }
+    if (!parent) {
+      throw new TsaError("tsa/untrusted-chain",
+        "tsa.verifyToken: signer certificate does not chain to any supplied trust anchor");
+    }
+    current = parent;
+    seen += 1;
+  }
+  throw new TsaError("tsa/chain-loop", "tsa.verifyToken: certificate chain did not terminate");
+}
+function _issued(issuer, subject) {
+  try { return subject.checkIssued(issuer) && subject.verify(issuer.publicKey); }
+  catch (_e) { return false; }
+}
+function _assertValidAt(cert, atMs) {
+  if (atMs < cert.validFromDate.getTime() || atMs > cert.validToDate.getTime()) {
+    throw new TsaError("tsa/cert-expired",
+      "tsa.verifyToken: certificate '" + cert.subject + "' is not valid at the asserted time");
+  }
+}
+
+/**
+ * @primitive b.tsa.verifyToken
+ * @signature b.tsa.verifyToken(token, opts)
+ * @since     0.12.38
+ * @status    experimental
+ * @compliance soc2
+ * @related   b.tsa.buildRequest, b.cms.parseSignedData
+ *
+ * Verify an RFC 3161 timestamp token against your data and return the
+ * asserted time. Performs the full §2.4.2 / §2.3 check: eContentType is
+ * <code>id-ct-TSTInfo</code>, the message imprint equals the hash of
+ * <code>opts.data</code> (or <code>opts.hash</code>), a sent nonce
+ * round-trips, the signer cert's extendedKeyUsage is a critical, sole
+ * <code>id-kp-timeStamping</code>, and the CMS signature verifies. Pass
+ * <code>opts.trustAnchorsPem</code> to also verify the certificate
+ * chain and validity at the asserted time.
+ *
+ * @opts
+ *   {
+ *     data:            Buffer,    // the timestamped data (hashed with hashAlg)
+ *     hash:            Buffer,    // OR a pre-computed digest (with hashAlg)
+ *     hashAlg:         string,    // default "SHA-512" — must match the imprint
+ *     nonce:           Buffer,    // require the token nonce to match (from buildRequest)
+ *     trustAnchorsPem: string|string[], // PEM root(s) — enables chain + validity verification
+ *     at:              Date,      // validity instant for chain check (default: genTime); must be a valid Date
+ *   }
+ *
+ * @example
+ *   var out = b.tsa.verifyToken(resp.token, { data: tarball, hashAlg: "SHA-512", nonce: req.nonce });
+ *   // → { genTime, policy, serialHex, accuracy, hashAlg, signerCertPem }
+ */
+function verifyToken(token, opts) {
+  validateOpts.requireObject(opts, "tsa.verifyToken", TsaError);
+  validateOpts(opts, ["data", "hash", "hashAlg", "nonce", "trustAnchorsPem", "at"], "tsa.verifyToken");
+  if (opts.data == null && opts.hash == null) {
+    throw new TsaError("tsa/no-data", "tsa.verifyToken: pass opts.data or opts.hash to bind the token");
+  }
+  var imp = _imprint(opts.hash != null ? opts.hash : opts.data,
+    { hashAlg: opts.hashAlg, hashed: opts.hash != null }, "tsa.verifyToken");
+
+  var sd;
+  try { sd = cms.parseSignedData(_bytes(token, "token")); }
+  catch (e) {
+    throw new TsaError("tsa/not-cms", "tsa.verifyToken: token is not CMS SignedData: " + ((e && e.message) || e));
+  }
+  if (sd.encapContent.eContentType !== OID_TST_INFO) {
+    throw new TsaError("tsa/not-tst",
+      "tsa.verifyToken: eContentType is " + sd.encapContent.eContentType + ", expected id-ct-TSTInfo");
+  }
+  if (!sd.encapContent.eContent) {
+    throw new TsaError("tsa/detached", "tsa.verifyToken: timestamp token has no embedded TSTInfo (detached not allowed)");
+  }
+  if (!sd.signerInfos.length) {
+    throw new TsaError("tsa/no-signer", "tsa.verifyToken: token has no SignerInfo");
+  }
+  if (!sd.certificates.length) {
+    throw new TsaError("tsa/no-cert",
+      "tsa.verifyToken: token carries no certificate — request one with certReq (the default)");
+  }
+
+  var tst = _parseTstInfo(sd.encapContent.eContent);
+
+  // (3) message imprint must match the data.
+  if (OID_TO_IMPRINT_HASH[tst.imprintHashOid] !== imp.hashName) {
+    throw new TsaError("tsa/imprint-alg-mismatch",
+      "tsa.verifyToken: token imprint hash (" + tst.imprintHashOid + ") differs from " + imp.hashName);
+  }
+  if (!bCrypto.timingSafeEqual(tst.imprintHash, imp.digest)) {
+    throw new TsaError("tsa/imprint-mismatch",
+      "tsa.verifyToken: token message imprint does not match the supplied data");
+  }
+
+  // (4) nonce round-trip.
+  if (opts.nonce != null) {
+    var want = _bytes(opts.nonce, "nonce");
+    var got = tst.nonce == null ? Buffer.alloc(0) : Buffer.from(tst.nonce);
+    // Compare as unsigned integers (ignore a DER sign-pad byte difference).
+    if (_normHex(want.toString("hex")) !== _normHex(got.toString("hex"))) {
+      throw new TsaError("tsa/nonce-mismatch", "tsa.verifyToken: token nonce does not match the request nonce");
+    }
+  }
+
+  // (5)+(6) signer cert + EKU + CMS signature.
+  var si = sd.signerInfos[0];
+  var candidates = _candidateSigners(si.sid, sd.certificates);
+  var signerCertDer = null;
+  var lastErr = null;
+  for (var i = 0; i < candidates.length; i += 1) {
+    try {
+      _checkTimestampingEku(candidates[i]);
+      _verifyCmsSignature(si, sd.encapContent.eContent, candidates[i]);
+      signerCertDer = candidates[i];
+      break;
+    } catch (e) { lastErr = e; }
+  }
+  if (!signerCertDer) {
+    throw lastErr || new TsaError("tsa/no-valid-signer",
+      "tsa.verifyToken: no certificate in the token both carries the timestamping EKU and verifies the signature");
+  }
+
+  // (7) optional chain + validity. Accept a single PEM string or an
+  // array — never silently skip chain verification when the caller
+  // supplied an anchor in an unexpected shape (a fail-open).
+  if (opts.trustAnchorsPem !== undefined && opts.trustAnchorsPem !== null) {
+    var anchors = typeof opts.trustAnchorsPem === "string" ? [opts.trustAnchorsPem] : opts.trustAnchorsPem;
+    if (!Array.isArray(anchors) || anchors.length === 0 ||
+        !anchors.every(function (a) { return typeof a === "string" && a.length > 0; })) {
+      throw new TsaError("tsa/bad-trust-anchors",
+        "tsa.verifyToken: trustAnchorsPem must be a non-empty PEM string or array of PEM strings");
+    }
+    // A supplied opts.at must be a valid Date — an Invalid Date would
+    // make every validity-window comparison NaN (silently disabling it).
+    var at = tst.genTime;
+    if (opts.at !== undefined && opts.at !== null) {
+      if (!(opts.at instanceof Date) || !isFinite(opts.at.getTime())) {
+        throw new TsaError("tsa/bad-at", "tsa.verifyToken: opts.at must be a valid Date");
+      }
+      at = opts.at;
+    }
+    _verifyChain(signerCertDer, sd.certificates, anchors, at);
+  }
+
+  return {
+    genTime:       tst.genTime,
+    policy:        tst.policy,
+    serialHex:     tst.serialHex,
+    accuracy:      tst.accuracy,
+    hashAlg:       imp.hashName,
+    signerCertPem: new nodeCrypto.X509Certificate(signerCertDer).toString(),
+  };
+}
+
+module.exports = {
+  buildRequest:   buildRequest,
+  parseResponse:  parseResponse,
+  verifyToken:    verifyToken,
+  IMPRINT_HASHES: IMPRINT_HASHES,
+  TsaError:       TsaError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.36",
+  "version": "0.12.38",
   "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:0d92b39a-5bed-4091-9927-a887660568ee",
+  "serialNumber": "urn:uuid:5183e917-7caf-48d3-b87d-5efa87791e85",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-25T00:19:35.328Z",
+    "timestamp": "2026-05-25T02:32:18.883Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.36",
+      "bom-ref": "@blamejs/core@0.12.38",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.36",
+      "version": "0.12.38",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.36",
+      "purl": "pkg:npm/%40blamejs/core@0.12.38",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.36",
+      "ref": "@blamejs/core@0.12.38",
       "dependsOn": []
     }
   ]