@blamejs/pki 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.
+
+### Added
+
+- pki inspect <cert> renders a certificate as an openssl x509 -text style report (composes pki.inspect.certificate).
+- pki lint <cert> [--profile <name>] [--severity <floor>] [--json] lints a certificate against the RFC 5280 and CABF TLS profiles, exiting non-zero when an error or fatal finding is present (composes pki.lint.certificate).
+- pki convert <file> --to der|pem [--label <label>] transcodes between DER and PEM with auto-detected input encoding and byte-exact round-tripping.
+- pki verify <cert>... --anchor <cert> [--time <ISO>] validates an ordered certification path against a trust anchor per RFC 5280 section 6.1 (composes pki.path.validate), exiting non-zero and naming the failing check on rejection.
+
 ## v0.2.10 — 2026-07-13
 
 Certificate linting arrives as pki.lint -- graded, advisory conformance findings against the RFC 5280 profile and a representative CA/Browser Forum TLS Baseline Requirements subset.

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` |
@@ -232,7 +232,7 @@ is callable today; nothing below is a stub.
 | `pki.lint` | Certificate linting — the zlint / pkilint of JavaScript. `certificate(pem \| der \| parsed, opts)` walks a parsed certificate and emits graded, advisory findings — each with a stable id, a severity (`fatal` > `error` > `warn` > `notice`), a source, a spec-clause citation, and a message — against the RFC 5280 profile plus a representative CA/Browser Forum TLS BR subset (serial sign/size, validity ordering + the the SC081v3 reducing validity schedule, keyCertSign coherence, unknown critical extensions, empty-subject SAN, SKI/AKI presence, SAN required + CN-in-SAN, dNSName syntax, serverAuth EKU, weak keys). Unlike every other entry the DATA path never throws: hostile bytes return a `fatal` `lint/unparseable` finding (with the strict parser's code) so a whole directory lints without a try/catch; only config-time misuse throws a typed `LintError`. `certificate`, `rules`, `profiles` |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
 | `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError` / `WebauthnError` / `LintError`, each carrying a stable `code` in `domain/reason` form |
-| `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
+| `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>`, `pki inspect <cert>`, `pki lint <cert>`, `pki convert <file> --to der\|pem`, `pki verify <cert>... --anchor <cert>` |
 
 ### CLI
 
@@ -241,8 +241,18 @@ pki version                              # @blamejs/pki v0.1.0
 pki oid 1.2.840.113549.1.1.11           # sha256WithRSAEncryption
 pki oid sha256                           # 2.16.840.1.101.3.4.2.1
 pki parse cert.pem                       # structured JSON summary of a certificate
+pki inspect cert.pem                     # openssl x509 -text style report (pki.inspect)
+pki lint cert.pem                        # graded conformance findings; exit 1 on an error
+pki lint cert.pem --json --profile cabf-tls
+pki convert cert.pem --to der > cert.der # transcode between PEM and DER (round-trips)
+pki verify leaf.pem --anchor root.pem --time 2026-01-01T00:00:00Z   # RFC 5280 path validation
 ```
 
+`inspect`/`lint`/`convert`/`verify` are thin front-ends over `pki.inspect`, `pki.lint`, the
+per-format PEM codecs, and `pki.path.validate` — the CLI never does anything the library
+API can't. `lint` exits non-zero when any `error`/`fatal` finding is present; `verify` exits
+non-zero when the path does not validate.
+
 ### What's coming
 
 Certificate build/sign/verify, CMS AuthenticatedData /

package/bin/pki.js

@@ -5,14 +5,21 @@
 /**
  * pki — command-line front-end for @blamejs/pki.
  *
- *   pki version
- *   pki oid <dotted|name>          resolve an OID <-> name
- *   pki parse <cert.pem|cert.der>  parse an X.509 certificate and print
- *                                  its fields as JSON
+ *   pki version                          print the package version
+ *   pki oid <dotted|name>                resolve an OID <-> name
+ *   pki parse <cert>                      parse an X.509 certificate to JSON
+ *   pki inspect <cert>                    render a certificate as text (openssl x509 -text style)
+ *   pki lint <cert> [--profile P]         lint a certificate; exit non-zero on an error finding
+ *              [--severity S] [--json]
+ *   pki convert <file> --to der|pem       transcode a DER/PEM file between the two encodings
+ *              [--label LABEL]
+ *   pki verify <cert>... --anchor <cert>  validate an ordered certification path (anchor->target)
+ *              [--time ISO]
  *
- * The CLI is a thin operator convenience over the library surface; it
- * validates its arguments (entry-point tier — bad input exits non-zero
- * with a message) and never does anything the public API can't.
+ * The CLI is a thin operator convenience over the library surface: it validates its
+ * arguments (entry-point tier — bad input exits non-zero with a message) and never does
+ * anything the public API cannot. inspect / lint / convert / verify compose pki.inspect,
+ * pki.lint, the per-format PEM codecs, and pki.path.validate respectively.
  */
 
 var fs  = require("node:fs");
@@ -23,6 +30,65 @@ function fail(msg) {
   process.exit(1);
 }
 
+// Minimal flag parser: `--flag value` for value-taking flags, `--flag` for booleans, the
+// rest are positionals in `_`. A value-taking flag whose value is absent or is itself another
+// flag is a usage error (never silently coerced to `true`, which would make e.g. `--time`
+// parse as `new Date(true)` = a real 1970 timestamp). No clustering, no `=value`.
+var VALUE_FLAGS = { to: 1, profile: 1, severity: 1, label: 1, anchor: 1, time: 1 };
+function parseArgs(argv) {
+  var out = { _: [] };
+  for (var i = 0; i < argv.length; i++) {
+    var a = argv[i];
+    if (a.indexOf("--") === 0) {
+      var key = a.slice(2);
+      if (VALUE_FLAGS[key]) {
+        if (i + 1 >= argv.length || argv[i + 1].indexOf("--") === 0) fail("--" + key + " requires a value");
+        out[key] = argv[++i];
+      } else { out[key] = true; }
+    } else { out._.push(a); }
+  }
+  return out;
+}
+
+function readFileBytes(file) {
+  try { return fs.readFileSync(file); } catch (e) { return fail("cannot read " + file + ": " + e.message); }
+}
+
+// For the library entry points (parse / inspect / lint / verify) that accept EITHER a DER
+// Buffer or a PEM string and own the decode + error handling: hand a Buffer when the bytes
+// are a well-formed DER structure, otherwise the text so the library pemDecodes it (and
+// applies its own canonical-base64 policy). This defers ALL error handling to the library,
+// which is what preserves the linter's never-throw survey -- malformed bytes become a fatal
+// lint/unparseable finding rather than a CLI hard-fail. DER-first is unambiguous (a PEM file
+// is ASCII text and never decodes as one DER TLV).
+function readForLib(file) {
+  var bytes = readFileBytes(file);
+  try { pki.asn1.decode(bytes); return bytes; }
+  catch (_derErr) { return bytes.toString("latin1"); }   // not DER -- let the library pemDecode / report it
+}
+
+// For `convert`, which transcodes RAW bytes and bypasses the library parse: extract DER
+// explicitly (a well-formed DER file as-is, or a canonical PEM body), failing on anything
+// else. Returns { der, label } where `label` is the PEM armor when the input was PEM.
+function readDer(file) {
+  var bytes = readFileBytes(file);
+  try { pki.asn1.decode(bytes); return { der: bytes, label: null }; }
+  catch (_derErr) { /* not a single well-formed DER structure -- try PEM */ }
+  // Match the library's PEM grammar exactly (an uppercase A-Z0-9 label, and ONLY CR/LF/TAB/
+  // space ignored in the body -- not every JS whitespace), so convert is not a looser
+  // validation path than the codecs it composes.
+  var m = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/.exec(bytes.toString("latin1"));
+  if (!m) return fail(file + ": input is neither a well-formed DER structure nor a PEM block");
+  var b64 = m[2].replace(/[\r\n\t ]+/g, "");
+  // Enforce CANONICAL base64 (RFC 4648 sec. 3.5), matching the library's fail-closed PEM
+  // policy: Node's decoder silently drops invalid characters and tolerates non-canonical
+  // trailing pad bits. Gate alphabet/length, then require that re-encoding reproduces the body.
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64) || b64.length % 4 !== 0) return fail(file + ": malformed PEM base64");
+  var der = Buffer.from(b64, "base64");
+  if (der.toString("base64") !== b64) return fail(file + ": non-canonical PEM base64");
+  return { der: der, label: m[1] };
+}
+
 function cmdVersion() {
   process.stdout.write("@blamejs/pki v" + pki.version + "\n");
 }
@@ -41,10 +107,8 @@ function cmdOid(arg) {
 
 function cmdParse(file) {
   if (!file) fail("usage: pki parse <cert.pem|cert.der>");
-  var bytes;
-  try { bytes = fs.readFileSync(file); } catch (e) { return fail("cannot read " + file + ": " + e.message); }
   var cert;
-  try { cert = pki.schema.x509.parse(bytes); } catch (e) { return fail(e.code + ": " + e.message); }
+  try { cert = pki.schema.x509.parse(readForLib(file)); } catch (e) { return fail(e.code + ": " + e.message); }
   var view = {
     version:            cert.version,
     serialNumber:       cert.serialNumberHex,
@@ -59,19 +123,101 @@ function cmdParse(file) {
   process.stdout.write(JSON.stringify(view, null, 2) + "\n");
 }
 
+// pki inspect <cert> -- the human-readable certificate render (pki.inspect.certificate),
+// the pure-JS equivalent of `openssl x509 -text`.
+function cmdInspect(file) {
+  if (!file) fail("usage: pki inspect <cert.pem|cert.der>");
+  try { process.stdout.write(pki.inspect.certificate(readForLib(file))); }
+  catch (e) { return fail(e.code + ": " + e.message); }
+}
+
+function pad(s, n) { while (s.length < n) s += " "; return s; }
+
+// pki lint <cert> -- lint against pki.lint's profiles. Prints one line per finding and
+// exits non-zero when any error/fatal finding is present (0 when the worst is advisory).
+function cmdLint(args) {
+  var file = args._[0];
+  if (!file) fail("usage: pki lint <cert> [--profile <name>] [--severity <floor>] [--json]");
+  var report;
+  // Config-time misuse (unknown profile / bad severity) throws a typed LintError; the data
+  // path never throws (malformed bytes become a fatal lint/unparseable finding).
+  try { report = pki.lint.certificate(readForLib(file), { profile: args.profile, severity: args.severity }); }
+  catch (e) { return fail(e.code + ": " + e.message); }
+  if (args.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    report.findings.forEach(function (f) {
+      process.stdout.write(pad(f.severity.toUpperCase(), 7) + " " + f.id + " -- " + f.message + "\n");
+    });
+    process.stdout.write("\n" + (report.findings.length || "no") + " finding(s); worst: " + (report.worst || "pass") + "\n");
+  }
+  // Set the exit CODE and let Node drain — process.exit() can truncate a buffered stdout
+  // write to a pipe before it flushes.
+  process.exitCode = (report.counts.error || report.counts.fatal) ? 1 : 0;
+}
+
+// pki convert <file> --to der|pem -- transcode between DER and PEM. The input encoding is
+// auto-detected; the bytes must be well-formed DER (we never wrap/emit garbage).
+function cmdConvert(args) {
+  var file = args._[0], to = args.to;
+  if (!file) fail("usage: pki convert <file> --to der|pem [--label LABEL]");
+  if (to !== "der" && to !== "pem") fail("convert: --to must be 'der' or 'pem'");
+  var input = readDer(file);
+  try { pki.asn1.decode(input.der); } catch (e) { return fail("input is not well-formed DER: " + (e.code || e.message)); }
+  if (to === "der") { process.stdout.write(input.der); return; }
+  var label = args.label || input.label || "CERTIFICATE";
+  // The armor label must be re-readable by the library's PEM grammar (uppercase A-Z0-9 words,
+  // single spaces) -- reject a lowercase/invalid label rather than emit an unparseable file.
+  if (!/^[A-Z0-9]+( [A-Z0-9]+)*$/.test(label)) return fail("convert: --label must be an uppercase A-Z0-9 label with single spaces (RFC 7468)");
+  var b64 = input.der.toString("base64").replace(/(.{1,64})/g, "$1\n");
+  process.stdout.write("-----BEGIN " + label + "-----\n" + b64 + "-----END " + label + "-----\n");
+}
+
+// pki verify <cert>... --anchor <cert> -- validate an ordered certification path
+// (anchor->target) against a trust anchor via pki.path.validate (RFC 5280 sec. 6.1).
+function cmdVerify(args) {
+  var certFiles = args._, anchorFile = args.anchor;
+  if (!certFiles.length || !anchorFile) fail("usage: pki verify <cert>... --anchor <anchor-cert> [--time ISO]");
+  var certs, anchor;
+  try { certs = certFiles.map(function (f) { return pki.schema.x509.parse(readForLib(f)); }); }
+  catch (e) { return fail("cannot parse a path certificate: " + (e.code || e.message)); }
+  try { anchor = pki.schema.x509.parse(readForLib(anchorFile)); }
+  catch (e2) { return fail("cannot parse the anchor certificate: " + (e2.code || e2.message)); }
+  var time = args.time ? new Date(args.time) : new Date();
+  if (isNaN(time.getTime())) fail("verify: --time must be an ISO-8601 date");
+  var spki = anchor.subjectPublicKeyInfo;
+  return pki.path.validate(certs, {
+    time: time,
+    trustAnchor: { name: anchor.subject, publicKey: spki.bytes, algorithm: spki.algorithm.oid, parameters: spki.algorithm.parameters },
+  }).then(function (res) {
+    process.stdout.write(res.valid ? "valid\n" : "invalid\n");
+    if (!res.valid) {
+      (res.results || []).forEach(function (r, i) {
+        (r.checks || []).forEach(function (c) { if (c.ok === false) process.stdout.write("  cert[" + i + "] " + c.code + "\n"); });
+      });
+    }
+    process.exitCode = res.valid ? 0 : 1;   // let Node flush stdout before it exits
+  }, function (e) { return fail(e.code + ": " + e.message); });
+}
+
+var USAGE = "usage: pki <version|oid|parse|inspect|lint|convert|verify> [args]\n";
+
 function main(argv) {
   var cmd = argv[0];
   switch (cmd) {
     case "version": case "--version": case "-v": return cmdVersion();
     case "oid":     return cmdOid(argv[1]);
     case "parse":   return cmdParse(argv[1]);
+    case "inspect": return cmdInspect(argv[1]);
+    case "lint":    return cmdLint(parseArgs(argv.slice(1)));
+    case "convert": return cmdConvert(parseArgs(argv.slice(1)));
+    case "verify":  return cmdVerify(parseArgs(argv.slice(1)));
     case undefined: case "help": case "--help": case "-h":
-      process.stdout.write("usage: pki <version|oid|parse> [args]\n");
+      process.stdout.write(USAGE);
       return;
     default:
       return fail("unknown command: " + cmd);
   }
 }
 
-main(process.argv.slice(2));
-
+Promise.resolve(main(process.argv.slice(2))).catch(function (e) { fail(e && (e.stack || e.message) || String(e)); });

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.10",
+  "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:63ae20ee-b75f-4b87-9846-27c435f26822",
+  "serialNumber": "urn:uuid:f99392dd-064e-4cea-b273-77302f5d396d",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-13T16:00:51.631Z",
+    "timestamp": "2026-07-13T18:39:01.236Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.10",
+      "bom-ref": "@blamejs/pki@0.2.12",
       "type": "application",
       "name": "pki",
-      "version": "0.2.10",
+      "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.10",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.12",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.10",
+      "ref": "@blamejs/pki@0.2.12",
       "dependsOn": []
     }
   ]