@blamejs/pki 0.2.11 → 0.2.13

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.13 — 2026-07-13
+
+The certificate linter validates IP-literal common names with a strict in-house checker instead of node:net, so the toolkit pulls in no networking module.
+
+### Changed
+
+- pki.lint validates an IP-literal common name with a strict in-house IPv4/IPv6 checker (lib/ip-utils) instead of node:net, so the toolkit needs no networking module; the validator now also recognizes IPv4-mapped and dual-stack IPv6 literals.
+
+## 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` verifies an SCT signature against a log's public key by reconstructing the signed data, routing an ECDSA signature through the strict DER-conformance gate, and verifying through the crypto engine — resolving true or false, and throwing a typed error 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/lib/ip-utils.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. Textual IP-literal validation, shared so a
+// consumer (pki.lint's commonName-in-SAN check today; a future SAN iPAddress / name-
+// constraint surface) does not hand-roll a partial regex that misses a valid IPv6 form.
+//
+// The IPv4 grammar is strict per-octet 0-255 (RFC 791); the IPv6 parser follows RFC 4291
+// sec. 2.2 (8 groups of 1-4 hex, one "::" run compressing a contiguous zero run) plus the
+// RFC 4291 sec. 2.5.5.2 / RFC 5952 sec. 5 IPv4-mapped + dual-stack "::ffff:1.2.3.4" tail.
+// This mirrors the vetted validation in the sibling blamejs framework (lib/ip-utils.js);
+// this toolkit keeps its own copy rather than take a runtime dependency (Hard rule #1).
+
+// Strict RFC 791 dotted-quad: four 0-255 octets. Anchored + per-octet repeat-capped (no
+// ReDoS on unbounded input).
+var IPV4_RE = /^(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+function isIPv4(s) { return typeof s === "string" && IPV4_RE.test(s); }
+
+// Expand an IPv6 textual address to its 32-hex-character form, or null on any parse failure
+// (bad hex group, group count != 8, more than one "::", an over-length group). Accepts the
+// IPv4-mapped / dual-stack ".d.d.d.d" tail.
+var IPV6_TEXT_MAX_LEN = 45;   // 8 groups x4 hex + 7 colons + a dotted-quad tail headroom
+function expandIpv6Hex(ip) {
+  if (typeof ip !== "string" || ip.length > IPV6_TEXT_MAX_LEN || ip.indexOf(":") === -1) return null;
+  // RFC 4291 sec. 2.5.5.2 IPv4-mapped / dual-stack: fold a trailing dotted-quad into two
+  // 16-bit hex groups before the pure-hex parse.
+  var dual = ip.match(/^(.*):(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (dual) {
+    if (!isIPv4(dual[2])) return null;
+    var v4 = dual[2].split(".").map(Number);
+    ip = dual[1] + ":" + (((v4[0] << 8) | v4[1]).toString(16)) + ":" + (((v4[2] << 8) | v4[3]).toString(16));
+  }
+  var dbl = ip.split("::");
+  if (dbl.length > 2) return null;
+  var left = dbl[0] === "" ? [] : dbl[0].split(":");
+  var right = dbl.length === 2 ? (dbl[1] === "" ? [] : dbl[1].split(":")) : [];
+  if (dbl.length === 1 && left.length !== 8) return null;
+  var fill = 8 - left.length - right.length;
+  // A "::" run MUST compress at least one zero group (RFC 4291 sec. 2.2 / RFC 5952 sec.
+  // 4.2.2): a "::" with fill 0 is a full 8-group address that must not use compression.
+  if (dbl.length === 2 ? fill < 1 : fill !== 0) return null;
+  var groups = left, i;
+  for (i = 0; i < fill; i += 1) groups = groups.concat(["0"]);
+  groups = groups.concat(right);
+  if (groups.length !== 8) return null;
+  var hex = "";
+  for (i = 0; i < 8; i += 1) {
+    var g = groups[i];
+    if (g.length < 1 || g.length > 4 || !/^[0-9a-f]+$/i.test(g)) return null;
+    hex += g.toLowerCase().padStart(4, "0");
+  }
+  return hex;
+}
+
+// Is `s` a syntactically valid IPv4 or IPv6 textual literal?
+function isIpLiteral(s) { return isIPv4(s) || expandIpv6Hex(s) !== null; }
+
+module.exports = { isIPv4: isIPv4, expandIpv6Hex: expandIpv6Hex, isIpLiteral: isIpLiteral, IPV4_RE: IPV4_RE };

package/lib/lint.js

@@ -23,13 +23,13 @@
  * @card Lint a certificate against RFC 5280 + CABF TLS BR, in pure JS.
  */
 
-var net = require("net");
 var frameworkError = require("./framework-error");
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
 var pkix = require("./schema-pkix");
 var C = require("./constants");
+var ipUtils = require("./ip-utils");
 
 var MS_PER_DAY = C.TIME.days(1);
 
@@ -215,10 +215,11 @@ function _dnsNameProblem(s) {
   return null;
 }
 
-// A genuine IPv4 or IPv6 literal (validated by net.isIP, which rejects an out-of-range
-// dotted quad like 999.999.999.999 or a colon-bearing non-address like "api:443") -- a CN
-// validated against an iPAddress SAN rather than a dNSName.
-function _looksLikeIp(s) { return typeof s === "string" && net.isIP(s) !== 0; }
+// A genuine IPv4 or IPv6 literal -- a CN validated against an iPAddress SAN rather than a
+// dNSName. Routed through the shared strict validator (no node:net, so the toolkit needs no
+// networking module): a per-octet-bounded dotted quad, or a full RFC 4291 IPv6 form
+// (including the IPv4-mapped / dual-stack tail). Rejects 999.999.999.999 and "api:443".
+function _looksLikeIp(s) { return ipUtils.isIpLiteral(s); }
 
 function _sanDnsNames(ctx) {
   var d = ctx.decode("subjectAltName");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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:125643d3-4737-4dc7-ac9b-39283eea27e2",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-13T17:30:07.505Z",
+    "timestamp": "2026-07-13T19:15:38.903Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.11",
+      "bom-ref": "@blamejs/pki@0.2.13",
       "type": "application",
       "name": "pki",
-      "version": "0.2.11",
+      "version": "0.2.13",
       "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.13",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.11",
+      "ref": "@blamejs/pki@0.2.13",
       "dependsOn": []
     }
   ]