@blamejs/pki 0.2.11 → 0.2.12

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.2.12 — 2026-07-13
+
+pki.ct.verifySct verifies a Signed Certificate Timestamp's signature against a Certificate Transparency log's public key.
+
+### Added
+
+- pki.ct.verifySct(entry, sct, logPublicKey) verifies a Signed Certificate Timestamp's signature against a CT log's public key (RFC 6962 section 3.2), composing pki.ct.reconstructSignedData, the shared ECDSA-Sig-Value conformance gate, and pki.webcrypto. Resolves true/false on the cryptographic verdict; throws a typed CtError on a structural fault.
+
 ## v0.2.11 — 2026-07-13
 
 The pki command-line tool gains inspect, lint, convert, and verify -- front-ends over the certificate inspector, the linter, the PEM codecs, and RFC 5280 path validation.

package/README.md

@@ -221,7 +221,7 @@ is callable today; nothing below is a stub.
 | `pki.schema.smime` | Decode S/MIME ESS signed-attribute values (RFC 5035 / RFC 8551) — `parseSigningCertificate` / `parseSigningCertificateV2` bind a signature to its signing certificate (cert hash, hash algorithm, issuer `GeneralNames` + serial), `parseSmimeCapabilities` decodes the ordered capability list, and `decodeAttribute` OID-dispatches a CMS attribute (enforcing the single-value rule, recognize-and-defer for unknown types). A companion decoder for CMS signed attributes, not an auto-routed format, fail-closed — `parseSigningCertificate`, `parseSigningCertificateV2`, `parseSmimeCapabilities`, `decodeAttribute` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` / `encode` / `embeddedDer` plus the schema combinators |
 | `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. Pure and re-entrant, fail-closed — `validate`, `crlChecker`, `ocspChecker` |
-| `pki.ct` | Parse RFC 6962 Certificate Transparency SCT lists — `parseSctList` decodes the `SignedCertificateTimestampList` a certificate or OCSP response carries in the SCT extension (a TLS-presentation-language payload inside the §3.3 double DER wrap) into per-SCT log id, exact `timestamp` (BigInt), named signature algorithm, and raw signature; `reconstructSignedData` rebuilds the exact `digitally-signed` preimage for external verification. Structure decoded, crypto surfaced raw, bounded decode, fail-closed — `parseSctList`, `reconstructSignedData` |
+| `pki.ct` | RFC 6962 Certificate Transparency SCTs — `parseSctList` decodes the `SignedCertificateTimestampList` a certificate or OCSP response carries in the SCT extension (a TLS-presentation-language payload inside the §3.3 double DER wrap) into per-SCT log id, exact `timestamp` (BigInt), named signature algorithm, and raw signature; `reconstructSignedData` rebuilds the exact `digitally-signed` preimage; `verifySct(entry, sct, logKey)` verifies the SCT signature against a log's public key — reconstructing the signed data, routing an ECDSA signature through the strict DER-conformance gate, and verifying through the crypto engine (resolves `true`/`false`, throws typed `ct/*` on a structural fault). Structure decoded, crypto fail-closed — `parseSctList`, `reconstructSignedData`, `verifySct` |
 | `pki.merkle` | RFC 6962 / RFC 9162 Merkle-tree proof verification — `leafHash` / `nodeHash` / `emptyRootHash` build the domain-separated (0x00 leaf / 0x01 node) SHA-256 tree hashes; `verifyInclusion` folds an audit proof back to a root and `verifyConsistency` reconstructs both the old and new root (the append-only guarantee), each constant-time-compared to a trusted checkpoint root. Fail-closed on bad geometry, sync hashing, transport-free — `leafHash`, `nodeHash`, `emptyRootHash`, `verifyInclusion`, `verifyConsistency` |
 | `pki.trust` | Mozilla / CCADB trust-store ingestion — `parseCertdata` reads the NSS `certdata.txt` object stream and `parseCcadbCsv` the CCADB CSV export into one identical constraint-carrying anchor shape: the per-purpose trust bits (only `CKT_NSS_TRUSTED_DELEGATOR` grants) and the per-purpose distrust-after dates the bare root list omits. Certificate and trust objects pair by byte-exact issuer + serial (never adjacency) and are cross-checked against the parsed DER, so metadata can never attach to the wrong root; `anchor()` hands an entry to `pki.path.validate({ trustAnchor, checkPurpose })`. Offline, fail-closed, bounded — `parseCertdata`, `parseCcadbCsv`, `anchor` |
 | `pki.shbs` | Stateful hash-based signature **verification** — HSS/LMS (RFC 8554), carried in X.509 by RFC 9802 and CMS by RFC 9708, profiled by NIST SP 800-208 (CNSA 2.0 firmware signing). `verify` checks an HSS signature (every level must pass) and `verifyLms` a single-tree LMS, over the raw public-key / signature blobs the parsers already surface. Pure public-input SHA-256 / SHAKE256 hashing, a data-driven typecode registry, bounds-before-slice reads; a malformed blob throws a typed `ShbsError`, a well-formed-but-wrong signature returns `false`. **Verify only by design** — stateful signing needs atomic one-time-key state that belongs in an HSM — `verify`, `verifyLms` |

package/lib/ct.js

@@ -43,6 +43,10 @@ var constants = require("./constants.js");
 var frameworkError = require("./framework-error.js");
 var guard = require("./guard-all.js");
 var ByteReader = require("./byte-reader.js");
+var oid = require("./oid.js");
+var webcrypto = require("./webcrypto.js");
+var validator = require("./validator-all.js");
+var subtle = webcrypto.webcrypto.subtle;
 
 var CtError = frameworkError.CtError;
 var C = constants;
@@ -287,9 +291,128 @@ function reconstructSignedData(entry, sct) {
   return Buffer.concat(parts);
 }
 
+// RFC 6962 sec. 2.1.4 constrains an SCT to SHA-256 with either ECDSA (NIST P-256) or RSA;
+// the verifier enforces exactly that rather than accepting an off-profile hash / curve a
+// conformant log never uses. The SCT hash name -> the WebCrypto digest.
+var CT_HASH = { sha256: "SHA-256" };
+// The one EC named curve an SCT log key may use (P-256), keyed by the curve OID its SPKI
+// carries -> the WebCrypto curve name + the r/s coordinate width.
+var CT_EC_CURVE = {};
+CT_EC_CURVE[oid.byName("prime256v1")] = { curve: "P-256", coordLen: 32 };
+
+// Read the SubjectPublicKeyInfo algorithm OID (+ the EC curve OID) off a log key SPKI so
+// the verifier picks the WebCrypto import descriptor from the KEY, not just the SCT's
+// self-declared signature type. Fail-closed: a non-SPKI shape throws a typed ct/bad-input.
+function _spkiAlg(spki) {
+  var node;
+  try { node = asn1.decode(spki); } catch (e) { throw new CtError("ct/bad-input", "the CT log public key is not a well-formed SubjectPublicKeyInfo", e); }
+  var algId = node.children && node.children[0];
+  if (!algId || !algId.children || !algId.children.length) throw new CtError("ct/bad-input", "the CT log public key is not a SubjectPublicKeyInfo");
+  var out;
+  try { out = { algOid: asn1.read.oid(algId.children[0]) }; }
+  catch (e1) { throw new CtError("ct/bad-input", "the CT log key SPKI algorithm identifier is not an OID", e1); }
+  if (out.algOid === oid.byName("ecPublicKey")) {
+    if (!algId.children[1]) throw new CtError("ct/bad-input", "the EC log key SPKI is missing its named-curve parameters");
+    try { out.curveOid = asn1.read.oid(algId.children[1]); }
+    catch (e2) { throw new CtError("ct/bad-input", "the EC log key SPKI curve parameters are not a named-curve OID", e2); }
+  } else if (out.algOid === oid.byName("rsaEncryption")) {
+    // RFC 6962 sec. 2.1.4 requires an RSA log key of at least 2048 bits -- size it from the
+    // RSAPublicKey modulus in the subjectPublicKey BIT STRING.
+    var mod, exp;
+    try {
+      var rsaSeq = asn1.decode(asn1.read.bitString(node.children[1]).bytes);
+      mod = asn1.read.integer(rsaSeq.children[0]);
+      exp = asn1.read.integer(rsaSeq.children[1]);
+    } catch (e3) { throw new CtError("ct/bad-input", "the RSA log key SPKI is not a well-formed RSAPublicKey", e3); }
+    // A non-positive modulus is malformed -- fail closed rather than size its absolute value.
+    if (mod <= 0n) throw new CtError("ct/bad-input", "the RSA log key modulus is not a positive integer");
+    // A small or even public exponent makes RSASSA-PKCS1-v1_5 verification forgeable (with
+    // e=1 the signature is simply the encoded DigestInfo). Require an odd exponent >= 3 --
+    // critical when the log key is taken from an untrusted log list rather than a pinned key.
+    if (exp < 3n || (exp & 1n) === 0n) throw new CtError("ct/bad-input", "the RSA log key public exponent must be an odd integer >= 3");
+    out.rsaBits = mod.toString(2).length;
+  }
+  return out;
+}
+
+/**
+ * @primitive  pki.ct.verifySct
+ * @signature  pki.ct.verifySct(entry, sct, logPublicKey) -> Promise<boolean>
+ * @since      0.2.12
+ * @status     experimental
+ * @spec       RFC 6962
+ * @defends    sct-signature-forgery (CWE-347)
+ * @related    pki.ct.parseSctList, pki.ct.reconstructSignedData
+ *
+ * Verify a Signed Certificate Timestamp's signature against a Certificate Transparency
+ * log's public key (RFC 6962 sec. 3.2). `entry` is the log entry the SCT covers
+ * (`{ entryType: 0, leafCert }` or `{ entryType: 1, tbsCertificate, issuerKeyHash }`,
+ * as for `reconstructSignedData`), `sct` a decoded v1 SCT from `parseSctList().scts[]`,
+ * and `logPublicKey` the log's SubjectPublicKeyInfo (DER `Buffer`). Reconstructs the exact
+ * signed data, imports the log key, and verifies the SCT signature -- an ECDSA signature is
+ * routed through the strict DER ECDSA-Sig-Value conformance gate before conversion to the
+ * raw r||s WebCrypto expects, an RSA signature verifies directly.
+ *
+ * Resolves `true` on a valid signature and `false` on a cryptographic mismatch (a false
+ * verdict is a verdict). Throws a typed `CtError` on structural failure -- a malformed
+ * entry/SCT, an unusable log key, or an unsupported hash/signature algorithm.
+ *
+ * @example
+ *   var sct = pki.ct.parseSctList(sctExtValue).scts[0];
+ *   // Resolve the CT log's DER SubjectPublicKeyInfo from a trusted log list, keyed by log id.
+ *   var logKeysByLogId = {};                       // { sct.logIdHex: <SPKI Buffer>, ... }
+ *   var logKey = logKeysByLogId[sct.logIdHex];
+ *   var ok = await pki.ct.verifySct({ entryType: 0, leafCert: certDer }, sct, logKey);
+ */
+async function verifySct(entry, sct, logPublicKey) {
+  // reconstructSignedData validates the entry + SCT and rebuilds the exact preimage.
+  var message = reconstructSignedData(entry, sct);
+  var spki = _toBuffer(logPublicKey, "the CT log public key (SPKI)");
+  // RFC 6962 sec. 3.2: an SCT names its log by LogID = SHA-256(log SPKI). When the SCT
+  // carries a logId, it MUST match the key it is verified against, so an SCT is never
+  // accepted against a different log's key (a key-confusion the bare signature check misses).
+  if (sct.logId != null) {
+    var keyId = Buffer.from(await subtle.digest("SHA-256", spki));
+    if (!keyId.equals(_toBuffer(sct.logId, "sct.logId"))) {
+      throw new CtError("ct/log-id-mismatch", "the SCT logId does not match SHA-256 of the provided log key (RFC 6962 sec. 3.2)");
+    }
+  }
+  var sigInfo = sct.signatureAlgorithm || {};
+  var hashName = CT_HASH[sigInfo.hashName];
+  if (!hashName) throw new CtError("ct/unsupported-algorithm", "unsupported SCT hash algorithm " + JSON.stringify(sigInfo.hashName) + " (RFC 6962 sec. 2.1.4 mandates sha256)");
+  var alg = _spkiAlg(spki);
+  var imp, ver, sig = _toBuffer(sct.signature, "sct.signature");
+  if (sigInfo.signatureName === "ecdsa") {
+    if (alg.algOid !== oid.byName("ecPublicKey")) throw new CtError("ct/bad-input", "the SCT declares an ECDSA signature but the log key is not an EC key");
+    var ec = CT_EC_CURVE[alg.curveOid];
+    if (!ec) throw new CtError("ct/unsupported-algorithm", "unsupported SCT log EC curve (RFC 6962 sec. 2.1.4 mandates NIST P-256)");
+    imp = { name: "ECDSA", namedCurve: ec.curve };
+    ver = { name: "ECDSA", hash: hashName };
+    // The SCT signature is a DER ECDSA-Sig-Value; route it through the strict conformance
+    // gate (primitive, minimal, positive, bounded r/s) before converting to raw r||s.
+    sig = validator.sig.ecdsaSigToRaw(sig, ec.coordLen, CtError, "ct/bad-signature");
+  } else if (sigInfo.signatureName === "rsa") {
+    if (alg.algOid !== oid.byName("rsaEncryption")) throw new CtError("ct/bad-input", "the SCT declares an RSA signature but the log key is not an RSA key");
+    if (!(alg.rsaBits >= 2048)) throw new CtError("ct/unsupported-algorithm", "the SCT log RSA key is below the RFC 6962 sec. 2.1.4 minimum of 2048 bits");
+    imp = { name: "RSASSA-PKCS1-v1_5", hash: hashName };
+    ver = { name: "RSASSA-PKCS1-v1_5" };
+  } else {
+    throw new CtError("ct/unsupported-algorithm", "unsupported SCT signature algorithm " + JSON.stringify(sigInfo.signatureName) + " (RFC 6962 sec. 2.1.4 supports ecdsa/rsa)");
+  }
+  // A wrong signature resolves false from subtle.verify (a verdict); a structural failure
+  // -- an unimportable key, an algorithm/key mismatch -- is re-thrown fail-closed.
+  try {
+    var key = await subtle.importKey("spki", spki, imp, false, ["verify"]);
+    return await subtle.verify(ver, key, sig, message);
+  } catch (e) {
+    throw new CtError("ct/verify-error", "the SCT signature could not be evaluated", e);
+  }
+}
+
 module.exports = {
   parseSctList: parseSctList,
   reconstructSignedData: reconstructSignedData,
+  verifySct: verifySct,
   HASH_ALGORITHMS: HASH_ALGORITHMS,
   SIGNATURE_ALGORITHMS: SIGNATURE_ALGORITHMS,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "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:a5150e4c-cfd7-4241-8d30-2a5f74cea49e",
+  "serialNumber": "urn:uuid:f99392dd-064e-4cea-b273-77302f5d396d",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-13T17:30:07.505Z",
+    "timestamp": "2026-07-13T18:39:01.236Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.11",
+      "bom-ref": "@blamejs/pki@0.2.12",
       "type": "application",
       "name": "pki",
-      "version": "0.2.11",
+      "version": "0.2.12",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.2.11",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.12",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.11",
+      "ref": "@blamejs/pki@0.2.12",
       "dependsOn": []
     }
   ]