@blamejs/pki 0.2.12 → 0.2.14

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.14 — 2026-07-13
+
+CMS SignedData signature verification arrives as pki.cms.verify -- verifying a signed message (S/MIME, timestamps, code signing) over the exact RFC 5652 preimage, for attached and detached content, one or many signers, across RSA, RSASSA-PSS, ECDSA, and EdDSA.
+
+### Added
+
+- pki.cms.verify(input, opts) verifies a CMS SignedData signature (RFC 5652 section 5) for attached and detached content, single and multiple signers, across RSA, RSASSA-PSS, ECDSA, and EdDSA. It accepts a PEM string, a DER Buffer, or a parsed pki.schema.cms object; opts.content supplies the external content for a detached signature and opts.certs supplies additional signer certificates. Each signer is located by its issuerAndSerialNumber or subjectKeyIdentifier and its signature checked over the exact RFC 5652 section 5.4 preimage -- the message-digest attribute bound to the content digest and the signature verified over the SignedAttributes re-encoding when signed attributes are present, otherwise over the content directly. Returns { valid, signers } with a per-signer verdict and the matched certificate; a false verdict or a structural fault is a fail-closed cms/* outcome.
+
+## 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.

package/README.md

@@ -221,7 +221,8 @@ 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` | 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.cms` | RFC 5652 §5 CMS SignedData signature verification — `verify(input, opts)` parses a SignedData over the strict `pki.schema.cms` codec, locates each SignerInfo's signer certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature over the exact §5.4 preimage: when signed attributes are present it confirms the message-digest attribute equals the content digest and verifies over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced by a universal SET OF), otherwise directly over the content. Attached and detached content, single and multiple signers, RSA / RSASSA-PSS / ECDSA / EdDSA. Returns a per-signer verdict with the matched signer certificate; it does not chain that certificate to a trust anchor — that is the caller's step through `pki.path.validate`. Fail-closed with typed `cms/*` errors — `verify` |
+| `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` |
@@ -336,7 +337,8 @@ modules reached by explicit call rather than DER routing: `pki.path` (RFC 5280
 path validation), `pki.trust` (trust anchors), `pki.ct` (Certificate Transparency
 SCTs), `pki.hpke` (RFC 9180), `pki.shbs` (HSS/LMS stateful hash signatures),
 `pki.merkle` (RFC 9162 transparency proofs), `pki.sigstore` (offline npm-provenance
-verification), `pki.webauthn` (WebAuthn / passkey attestation verification), and the
+verification), `pki.webauthn` (WebAuthn / passkey attestation verification),
+`pki.cms` (RFC 5652 SignedData signature verification), and the
 `jose` / `acme` / `est` enrollment surfaces. Each composes
 the shared structure, foundation, and crypto layers directly. Alongside the schema
 engine, the fail-closed **guard family** (`guard-*`) centralizes each CVE-class

package/index.js

@@ -36,6 +36,7 @@ var webcrypto = require("./lib/webcrypto");
 var schema    = require("./lib/schema-all");
 var path      = require("./lib/path-validate");
 var ct        = require("./lib/ct");
+var cms       = require("./lib/cms-verify");
 var merkle    = require("./lib/merkle");
 var shbs      = require("./lib/shbs");
 var hpke      = require("./lib/hpke");
@@ -73,6 +74,7 @@ module.exports = {
   // SCT-list extension a certificate / OCSP response carries; the signature is
   // surfaced raw for external verification (pki.ct.reconstructSignedData).
   ct:        ct,
+  cms:       cms,
   // `merkle` is the RFC 6962 / RFC 9162 Merkle-tree proof-verification core --
   // pki.merkle.leafHash / nodeHash / emptyRootHash build the domain-separated
   // (0x00 leaf / 0x01 node) SHA-256 tree hashes; pki.merkle.verifyInclusion and

package/lib/cms-verify.js

@@ -0,0 +1,404 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module pki.cms
+ * @nav        Verification
+ * @title      CMS
+ * @intro Verify a CMS SignedData signature (RFC 5652 sec. 5) -- the structure S/MIME signed
+ *   mail, RFC 3161 timestamp tokens, and code-signing all rest on. `verify(cms, opts)` parses
+ *   the SignedData (over the strict `pki.schema.cms` codec), locates each SignerInfo's signer
+ *   certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature
+ *   over the exact bytes RFC 5652 sec. 5.4 defines: when signed attributes are present it
+ *   confirms the message-digest attribute equals the digest of the content and verifies the
+ *   signature over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced
+ *   by a universal SET OF); otherwise it verifies directly over the content. Attached and
+ *   detached content, single and multiple signers, and RSA / RSASSA-PSS / ECDSA / EdDSA are
+ *   covered. It reports a per-signer verdict; it does NOT chain the signer certificate to a
+ *   trust anchor -- that is the caller's step through `pki.path.validate`.
+ * @spec RFC 5652
+ * @card Verify a CMS SignedData signature (S/MIME, timestamps, code signing).
+ */
+
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var x509 = require("./schema-x509");
+var cms = require("./schema-cms");
+var webcrypto = require("./webcrypto");
+var subtle = webcrypto.webcrypto.subtle;
+var edwardsPoint = require("./edwards-point");
+var validator = require("./validator-all");
+var guard = require("./guard-all");
+var frameworkError = require("./framework-error");
+
+var CmsError = frameworkError.CmsError;
+function _err(code, message, cause) { return new CmsError(code, message, cause); }
+
+var OID_MESSAGE_DIGEST = oid.byName("messageDigest");
+var OID_CONTENT_TYPE = oid.byName("contentType");
+
+// A digest-algorithm name -> the WebCrypto hash.
+var DIGEST_HASH = { sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
+// A signatureAlgorithm name -> its verify scheme. A combined OID (sha256WithRSAEncryption,
+// ecdsaWithSHA256) carries its own hash; a bare key OID (rsaEncryption, ecPublicKey) takes the
+// hash from the SignerInfo digestAlgorithm.
+// `params` pins the AlgorithmIdentifier parameters shape RFC 5754 requires: "null" for the
+// RSASSA-PKCS1-v1_5 family (RFC 4055), "absent" for ECDSA (RFC 5758) and EdDSA (RFC 8410).
+// RSASSA-PSS omits it -- its parameters ARE the RSASSA-PSS-params, resolved by _resolvePss.
+var SIG_SCHEME = {
+  rsaEncryption: { kind: "rsa", params: "null" },
+  rsassaPss: { kind: "rsapss" },
+  ecPublicKey: { kind: "ec", params: "absent" },
+  Ed25519: { kind: "eddsa", name: "Ed25519", params: "absent" },
+  Ed448: { kind: "eddsa", name: "Ed448", params: "absent" },
+  sha1WithRSAEncryption: { kind: "rsa", hash: "SHA-1", params: "null" },
+  sha256WithRSAEncryption: { kind: "rsa", hash: "SHA-256", params: "null" },
+  sha384WithRSAEncryption: { kind: "rsa", hash: "SHA-384", params: "null" },
+  sha512WithRSAEncryption: { kind: "rsa", hash: "SHA-512", params: "null" },
+  ecdsaWithSHA1: { kind: "ec", hash: "SHA-1", params: "absent" },
+  ecdsaWithSHA256: { kind: "ec", hash: "SHA-256", params: "absent" },
+  ecdsaWithSHA384: { kind: "ec", hash: "SHA-384", params: "absent" },
+  ecdsaWithSHA512: { kind: "ec", hash: "SHA-512", params: "absent" },
+};
+// The signatureAlgorithm parameters match the algorithm's fixed shape (RFC 5754). A DER NULL
+// is exactly `05 00`; "absent" is the parameters field omitted entirely.
+function _isDerNull(p) { return Buffer.isBuffer(p) && p.length === 2 && p[0] === 0x05 && p[1] === 0x00; }
+function _algParamsOk(shape, p) { return shape === "null" ? _isDerNull(p) : (p === null || p === undefined); }
+// An EC named-curve OID (in the signer cert SPKI) -> the WebCrypto curve + r/s coordinate width.
+var EC_CURVE = {};
+EC_CURVE[oid.byName("prime256v1")] = { curve: "P-256", coordLen: 32 };
+EC_CURVE[oid.byName("secp384r1")] = { curve: "P-384", coordLen: 48 };
+EC_CURVE[oid.byName("secp521r1")] = { curve: "P-521", coordLen: 66 };
+
+function _toBuf(v, what) {
+  if (Buffer.isBuffer(v)) return v;
+  if (v instanceof Uint8Array) return Buffer.from(v);
+  throw _err("cms/bad-input", what + " must be a Buffer");
+}
+
+// Every certificate a SignerInfo's signer identifier matches, among the SignedData's embedded
+// certificates plus any the caller supplies. issuerAndSerialNumber matches on the canonical
+// DN + serial; subjectKeyIdentifier matches the cert's SKI extension. ALL matches are returned
+// (in candidate order) so a colliding certificate placed before the real signer cannot hide it.
+function _findSignerCerts(sid, parsedCerts) {
+  var out = [];
+  for (var i = 0; i < parsedCerts.length; i++) {
+    var c = parsedCerts[i];
+    if (sid.subjectKeyIdentifier != null) {
+      if (c.ski && c.ski.equals(_toBuf(sid.subjectKeyIdentifier, "sid.subjectKeyIdentifier"))) out.push(c);
+    } else if (sid.issuer && sid.serialNumberHex != null) {
+      if (c.cert.serialNumberHex === sid.serialNumberHex && guard.name.dnEqual(c.cert.issuer, sid.issuer, CmsError, "cms/bad-name")) out.push(c);
+    }
+  }
+  return out;
+}
+
+// Verify `sigBytes` over `signedBytes` against EACH matching candidate certificate in turn; the
+// signer is valid iff one candidate verifies. A candidate whose key is structurally unusable (a
+// low-order EdDSA point, an unsupported curve) or whose signature simply does not verify falls
+// through to the next -- so a colliding certificate cannot make a valid signature read invalid.
+// When no candidate verifies, a plain false is a code-less verdict; the last structural fault's
+// code is surfaced if one occurred (so the diagnostic is not lost).
+function _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, sid, candidates, pssSalt) {
+  var lastErr = null;
+  function attempt(idx) {
+    if (idx >= candidates.length) {
+      return lastErr ? { ok: false, code: lastErr.code, sid: sid, cert: candidates[0].der, message: lastErr.message }
+        : { ok: false, sid: sid, cert: candidates[0].der };
+    }
+    var c = candidates[idx];
+    return Promise.resolve()
+      .then(function () { return _verifySignature(scheme, sigHash, sigBytes, c.cert.subjectPublicKeyInfo.bytes, signedBytes, _certCurveOid(c.cert), pssSalt); })
+      .then(function (ok) { return ok === true ? { ok: true, sid: sid, cert: c.der } : attempt(idx + 1); },
+        function (e) { lastErr = (e instanceof CmsError) ? e : _err("cms/verify-error", "the SignerInfo signature could not be evaluated", e); return attempt(idx + 1); });
+  }
+  return attempt(0);
+}
+
+// The cert's subjectKeyIdentifier extension value (the raw key id), or null.
+function _certSki(cert) {
+  var ext = (cert.extensions || []).filter(function (e) { return e.oid === oid.byName("subjectKeyIdentifier"); })[0];
+  if (!ext) return null;
+  try {
+    return asn1.read.octetString(asn1.decode(ext.value));
+  } catch (_e) { return null; }
+}
+
+// RSASSA-PSS-params resolution (RFC 4055). A SHA-2 hashAlgorithm name -> its WebCrypto hash
+// and the salt length WebCrypto verifies (the hash-length salt of the supported profile).
+var OID_MGF1 = oid.byName("mgf1");
+var PSS_HASH = {};
+PSS_HASH[oid.byName("sha256")] = "SHA-256";
+PSS_HASH[oid.byName("sha384")] = "SHA-384";
+PSS_HASH[oid.byName("sha512")] = "SHA-512";
+
+// A hash AlgorithmIdentifier { OID, parameters? } whose parameters, when present, MUST be a
+// DER NULL with empty content (RFC 4055 sec. 2.1 / RFC 5754). Returns the hash OID, or null
+// on any malformed shape.
+function _hashAlgOid(seq) {
+  if (!seq || seq.tagClass !== "universal" || seq.tagNumber !== asn1.TAGS.SEQUENCE || !seq.children || seq.children.length < 1 || seq.children.length > 2) return null;
+  var o;
+  try {
+    o = asn1.read.oid(seq.children[0]);
+  } catch (_e) { return null; }
+  if (seq.children.length === 2) {
+    var p = seq.children[1];
+    if (p.tagClass !== "universal" || p.tagNumber !== asn1.TAGS.NULL) return null;
+    try {
+      asn1.read.nullValue(p);
+    } catch (_e2) { return null; }
+  }
+  return o;
+}
+
+// Resolve RSASSA-PSS-params (RFC 4055) to { hash, saltLength }, or null if the parameters
+// deviate from the supported profile: an explicit SHA-2 hashAlgorithm, MGF1 keyed to the SAME
+// hash, saltLength equal to the hash length, and trailerField 1. The SHA-1 DEFAULTs are
+// rejected (params must be explicit), matching the certification-path validator, so a
+// non-conformant PSS AlgorithmIdentifier is a fail-closed verdict -- never verified under
+// WebCrypto's own defaults (a signatureAlgorithm bypass otherwise).
+function _resolvePss(paramsBytes) {
+  if (!paramsBytes) return null;
+  var n;
+  try {
+    n = asn1.decode(paramsBytes);
+  } catch (_e) { return null; }
+  if (n.tagClass !== "universal" || n.tagNumber !== asn1.TAGS.SEQUENCE || !n.children) return null;
+  var hash = null, saltLen = null, mgfNode = null, trailer = 1n, last = -1;
+  for (var i = 0; i < n.children.length; i++) {
+    var f = n.children[i];
+    // Each field is an EXPLICIT context [0..3] wrapper carrying exactly one value, at most
+    // once and in ascending order; anything else is malformed.
+    if (f.tagClass !== "context" || f.tagNumber > 3 || f.tagNumber <= last || !f.children || f.children.length !== 1) return null;
+    last = f.tagNumber;
+    try {
+      if (f.tagNumber === 0) { hash = PSS_HASH[_hashAlgOid(f.children[0])]; if (!hash) return null; }
+      else if (f.tagNumber === 1) { mgfNode = f.children[0]; }
+      else if (f.tagNumber === 2) { saltLen = asn1.read.integer(f.children[0]); }
+      else { trailer = asn1.read.integer(f.children[0]); }
+    } catch (_e3) { return null; }
+  }
+  if (hash === null || mgfNode === null) return null;   // both MUST be explicit (SHA-1 default rejected)
+  if (mgfNode.tagClass !== "universal" || mgfNode.tagNumber !== asn1.TAGS.SEQUENCE || !mgfNode.children || mgfNode.children.length !== 2) return null;
+  var mgfOid;
+  try {
+    mgfOid = asn1.read.oid(mgfNode.children[0]);
+  } catch (_e4) { return null; }
+  if (mgfOid !== OID_MGF1 || PSS_HASH[_hashAlgOid(mgfNode.children[1])] !== hash) return null;
+  if (trailer !== 1n) return null;
+  // saltLength: an absent field is the RFC 4055 DEFAULT of 20; a declared value is honored and
+  // passed through to WebCrypto (RSASSA-PSS is not pinned to hash-length salt). It is bounded to
+  // a non-negative int -- a negative value maps to OpenSSL's RSA_PSS_SALTLEN_DIGEST/AUTO/MAX
+  // magic, and AUTO accepts any salt length, defeating the salt-length binding.
+  var saltLength = saltLen === null ? 20 : guard.range.uint31(saltLen, _err, "cms/unsupported-algorithm", "RSASSA-PSS saltLength");
+  return { hash: hash, saltLength: saltLength };
+}
+
+// Verify the signature over `signedBytes` with the signer certificate's public key under the
+// resolved scheme + hash. Resolves true/false (a false verdict is a verdict); a structural
+// fault throws a typed CmsError.
+function _verifySignature(scheme, hashName, sigBytes, spki, signedBytes, curveOid, pssSalt) {
+  if (scheme.kind === "rsa") {
+    return subtle.importKey("spki", spki, { name: "RSASSA-PKCS1-v1_5", hash: hashName }, false, ["verify"])
+      .then(function (k) { return subtle.verify({ name: "RSASSA-PKCS1-v1_5" }, k, sigBytes, signedBytes); });
+  }
+  if (scheme.kind === "rsapss") {
+    return subtle.importKey("spki", spki, { name: "RSA-PSS", hash: hashName }, false, ["verify"])
+      .then(function (k) { return subtle.verify({ name: "RSA-PSS", saltLength: pssSalt }, k, sigBytes, signedBytes); });
+  }
+  if (scheme.kind === "ec") {
+    var ec = EC_CURVE[curveOid];
+    if (!ec) throw _err("cms/unsupported-algorithm", "the signer key is on an unsupported EC curve");
+    var raw = validator.sig.ecdsaSigToRaw(sigBytes, ec.coordLen, CmsError, "cms/bad-signature");
+    return subtle.importKey("spki", spki, { name: "ECDSA", namedCurve: ec.curve }, false, ["verify"])
+      .then(function (k) { return subtle.verify({ name: "ECDSA", hash: hashName }, k, raw, signedBytes); });
+  }
+  // EdDSA -- the WebCrypto name follows the signing key's SPKI OID (Ed25519 / Ed448). node/
+  // OpenSSL imports any Ed25519/Ed448 SPKI without validating the point, and a low-order (e.g.
+  // all-zeroes) key verifies a forged signature -- so reject a non-full-order point first.
+  _requireValidEdPoint(spki, scheme.name);
+  return subtle.importKey("spki", spki, { name: scheme.name }, false, ["verify"])
+    .then(function (k) { return subtle.verify({ name: scheme.name }, k, sigBytes, signedBytes); });
+}
+
+// The raw Edwards point an OKP SPKI carries (its BIT STRING body, past the unused-bits octet)
+// MUST be a valid, canonical, full-order point -- reject an off-curve or low-order key before
+// it verifies a signature (WebCrypto import does not check it). Curve from the WebCrypto name.
+function _requireValidEdPoint(spkiBytes, name) {
+  var content;
+  try {
+    content = asn1.decode(spkiBytes).children[1].content;
+  } catch (e) { throw _err("cms/bad-signature", "the EdDSA public key is not a well-formed SPKI", e); }
+  var point = content && content.length ? content.subarray(1) : Buffer.alloc(0);
+  if (!edwardsPoint.validate(point, name === "Ed25519" ? 6 : 7)) {
+    throw _err("cms/bad-signature", "the EdDSA public key is not a valid, full-order Edwards point");
+  }
+}
+
+// The EC named-curve OID carried in a signer cert's SubjectPublicKeyInfo, or null (non-EC).
+function _certCurveOid(cert) {
+  var p = cert.subjectPublicKeyInfo.algorithm.parameters;
+  if (cert.subjectPublicKeyInfo.algorithm.oid !== oid.byName("ecPublicKey") || !Buffer.isBuffer(p)) return null;
+  try {
+    return asn1.read.oid(asn1.decode(p));
+  } catch (_e) { return null; }
+}
+
+// Decode the SignedAttributes SET OF Attribute from the exact bytes the signature covers
+// (the re-tagged signedAttrsBytes), returning [{ type, values: [valueNode] }]. Binding the
+// content-type / message-digest checks to THESE decoded attributes -- not the caller-mutable
+// parsed si.signedAttrs -- means a parsed-object input cannot desync the checked attributes
+// from the verified preimage (RFC 5652 sec. 5.4).
+function _decodeSignedAttrs(setOfBytes) {
+  var set = asn1.decode(setOfBytes);
+  if (set.tagClass !== "universal" || set.tagNumber !== asn1.TAGS.SET || !set.children) throw _err("cms/bad-signed-attrs", "signedAttrs is not a SET OF Attribute");
+  return set.children.map(function (attr) {
+    if (attr.tagClass !== "universal" || attr.tagNumber !== asn1.TAGS.SEQUENCE || !attr.children || attr.children.length !== 2) throw _err("cms/bad-signed-attrs", "a signed Attribute is not a SEQUENCE { type, values }");
+    var valuesSet = attr.children[1];
+    if (valuesSet.tagClass !== "universal" || valuesSet.tagNumber !== asn1.TAGS.SET || !valuesSet.children) throw _err("cms/bad-signed-attrs", "a signed Attribute values field is not a SET OF");
+    return { type: asn1.read.oid(attr.children[0]), values: valuesSet.children };
+  });
+}
+
+// Verify one SignerInfo. Returns { ok, sid, cert, ... } -- a resolved false is a verdict; a
+// structural failure carries a code.
+function _verifyOne(si, content, eContentType, parsedCerts) {
+  var scheme = SIG_SCHEME[si.signatureAlgorithm.name];
+  if (!scheme) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported signature algorithm " + JSON.stringify(si.signatureAlgorithm.name) });
+  var digestHash = DIGEST_HASH[si.digestAlgorithm.name];
+  // RSASSA-PSS takes its signature hash and salt length from the RSASSA-PSS-params, not the
+  // digestAlgorithm; a non-conformant parameter set is a fail-closed unsupported verdict.
+  var pss = scheme.kind === "rsapss" ? _resolvePss(si.signatureAlgorithm.parameters) : null;
+  if (scheme.kind === "rsapss" && !pss) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported or non-conformant RSASSA-PSS parameters (RFC 4055)" });
+  // signatureAlgorithm is outside the signed preimage, so a forbidden/missing parameters field
+  // (a present parameter on ECDSA/EdDSA, a non-NULL or absent one on RSA) must fail closed --
+  // otherwise it is a parser differential a caller trusting the verdict inherits (RFC 5754).
+  if (scheme.params && !_algParamsOk(scheme.params, si.signatureAlgorithm.parameters)) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the " + si.signatureAlgorithm.name + " signature algorithm parameters must be " + (scheme.params === "null" ? "DER NULL (RFC 4055)" : "absent (RFC 5758/8410)") });
+  // The digestAlgorithm parameters, when present, MUST be a DER NULL (RFC 5754 sec. 2 accepts
+  // absent OR NULL; a present non-NULL is malformed and, being outside the signed preimage,
+  // must fail closed like the signatureAlgorithm parameters above).
+  var dp = si.digestAlgorithm.parameters;
+  if (dp !== null && dp !== undefined && !_isDerNull(dp)) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the " + si.digestAlgorithm.name + " digest algorithm parameters must be absent or DER NULL (RFC 5754 sec. 2)" });
+  var sigHash = pss ? pss.hash : (scheme.hash || digestHash);
+  // The signature hash is required for every non-EdDSA scheme (EdDSA hashes internally);
+  // the content digest is required whenever signed attributes are present, for every scheme
+  // (the message-digest attribute is computed under digestAlgorithm). Either gap is a
+  // fail-closed unsupported-algorithm verdict, never a foreign-domain throw from the digest.
+  if ((scheme.kind !== "eddsa" && !sigHash) || (si.signedAttrsBytes && !digestHash)) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported digest algorithm " + JSON.stringify(si.digestAlgorithm.name) });
+  var signers = _findSignerCerts(si.sid, parsedCerts);
+  if (!signers.length) return Promise.resolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
+  var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
+
+  return Promise.resolve().then(function () {
+    if (!si.signedAttrsBytes) return content;   // no signed attributes: sign over the content directly
+    // With signed attributes: decode them from the EXACT bytes the signature covers -- the
+    // SignedAttributes SET OF, the on-wire [0] IMPLICIT tag replaced by a universal SET OF
+    // (RFC 5652 sec. 5.4) -- so the content-type / message-digest checks bind the same bytes
+    // that are verified. Reading the caller-mutable parsed si.signedAttrs instead would let a
+    // parsed-object input desync the checked attributes from the verified preimage.
+    var reTagged = Buffer.from(si.signedAttrsBytes);
+    reTagged[0] = 0x31;   // [0] IMPLICIT -> universal SET OF
+    var attrs;
+    try {
+      attrs = _decodeSignedAttrs(reTagged);
+    } catch (e) { if (e instanceof CmsError) throw e; throw _err("cms/bad-signed-attrs", "signedAttrs is not a valid SET OF Attribute", e); }
+    // The content-type attribute MUST be present, single-valued, and equal the eContentType
+    // (RFC 5652 sec. 5.3).
+    var ctAttr = attrs.filter(function (a) { return a.type === OID_CONTENT_TYPE; });
+    if (ctAttr.length !== 1 || ctAttr[0].values.length !== 1) throw _err("cms/bad-signed-attrs", "signedAttrs must carry exactly one content-type attribute (RFC 5652 sec. 5.3)");
+    var ctOid;
+    try {
+      ctOid = asn1.read.oid(ctAttr[0].values[0]);
+    } catch (e) { throw _err("cms/bad-signed-attrs", "the content-type attribute value is not an OBJECT IDENTIFIER", e); }
+    if (ctOid !== eContentType) return { mismatch: { code: "cms/content-type-mismatch", message: "the content-type signed attribute does not match the SignedData eContentType (RFC 5652 sec. 5.3)" } };
+    // The message-digest attribute MUST be present, single-valued, and equal the digest of the
+    // content (RFC 5652 sec. 5.4).
+    var mdAttr = attrs.filter(function (a) { return a.type === OID_MESSAGE_DIGEST; })[0];
+    if (!mdAttr || mdAttr.values.length !== 1) throw _err("cms/bad-signed-attrs", "signedAttrs must carry exactly one message-digest attribute (RFC 5652 sec. 5.4)");
+    var declared;
+    try {
+      declared = asn1.read.octetString(mdAttr.values[0]);
+    } catch (e) { throw _err("cms/bad-signed-attrs", "the message-digest attribute value is not an OCTET STRING", e); }
+    return subtle.digest(digestHash, content).then(function (d) {
+      if (!Buffer.from(d).equals(declared)) return { mismatch: { code: "cms/message-digest-mismatch", message: "the message-digest attribute does not match the content digest" } };
+      return reTagged;
+    });
+  }).then(function (signedBytes) {
+    if (signedBytes && signedBytes.mismatch) return { ok: false, code: signedBytes.mismatch.code, sid: si.sid, cert: signers[0].der, message: signedBytes.mismatch.message };
+    return _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, si.sid, signers, pss ? pss.saltLength : 0);
+  });
+}
+
+/**
+ * @primitive  pki.cms.verify
+ * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, signers }>
+ * @since      0.2.14
+ * @status     experimental
+ * @spec       RFC 5652
+ * @defends    cms-signature-forgery (CWE-347)
+ * @related    pki.schema.cms.parse, pki.path.validate
+ *
+ * Verify a CMS SignedData signature (RFC 5652 sec. 5). `input` is a PEM string, a DER
+ * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, signers }` where each
+ * `signers[i]` is `{ ok, sid, cert }` (`cert` the matched signer certificate DER) or carries
+ * a `code` on a structural failure; `valid` is true when there is at least one signer and
+ * every signer verified.
+ *
+ * @opts  content  The detached content (a `Buffer`) when the SignedData carries no
+ *                 encapsulated eContent. Required for a detached signature.
+ * @opts  certs    Extra signer certificates (an array of DER `Buffer`s) to match against, in
+ *                 addition to the certificates embedded in the SignedData.
+ * @example
+ *   var res = await pki.cms.verify(p7sDer, { content: detachedBytes });
+ *   res.valid;                         // boolean
+ *   res.signers[0].ok;                 // per-signer verdict
+ */
+function verify(input, opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.verify options must be an object");
+  var parsed = (input && typeof input === "object" && !Buffer.isBuffer(input) && Array.isArray(input.signerInfos)) ? input : cms.parse(input);
+  if (!Array.isArray(parsed.signerInfos)) throw _err("cms/bad-input", "input is not a CMS SignedData");
+  var content = parsed.encapContentInfo.eContent;
+  if (content == null) {
+    if (opts.content == null) throw _err("cms/detached-content-required", "this SignedData is detached; opts.content (the external content) is required");
+    content = _toBuf(opts.content, "opts.content");
+  }
+  // Pre-parse every candidate certificate (embedded + caller-supplied) once.
+  var parsedCerts = [];
+  (parsed.certificates || []).forEach(function (c) { _addCert(parsedCerts, c && c.bytes ? c.bytes : c); });
+  (opts.certs || []).forEach(function (c) { _addCert(parsedCerts, c); });
+  var eContentType = parsed.encapContentInfo.eContentType;
+  return Promise.all(parsed.signerInfos.map(function (si) { return _verifyOne(si, content, eContentType, parsedCerts); }))
+    .then(function (signers) { return { valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }), signers: signers }; });
+}
+// Parse a candidate cert DER and index its SKI; a cert that will not parse is skipped (it
+// simply cannot be a signer match, and a malformed embedded cert must not fail the verify).
+function _addCert(out, der) {
+  var buf;
+  try {
+    buf = _toBuf(der, "a certificate");
+  } catch (_e) { return; }
+  var cert;
+  try {
+    cert = x509.parse(buf);
+  } catch (_e2) { return; }
+  out.push({ cert: cert, der: buf, ski: _certSki(cert) });
+}
+
+// Coverage residual -- these defensive branches are unreachable through the shipped path
+// because an upstream contract already narrows the shape:
+//   * `cert.extensions || []` -- x509.parse always surfaces `extensions` as an array (empty
+//     when absent), so the `|| []` fallback never fires.
+//   * `_requireValidEdPoint`'s SPKI-decode catch and its empty-content `Buffer.alloc(0)`
+//     fallback -- a signer certificate accepted by x509.parse always carries a well-formed,
+//     non-empty SubjectPublicKeyInfo BIT STRING, so the decode never throws and the content is
+//     never empty here.
+//   * `_decodeSignedAttrs`'s `tagNumber !== SET` / `!children` guard -- the caller forces the
+//     leading byte to a universal SET OF before decoding, so `asn1.decode` yields a SET whose
+//     `children` is always an array; the guard is belt-and-suspenders against a future caller.
+//   * `if (!Array.isArray(parsed.signerInfos))` -- the object-input branch is only taken when
+//     `signerInfos` is already an array, and cms.parse yields a SignedData whose `signerInfos`
+//     is always an array (or it throws), so this belt-and-suspenders throw never fires.
+//   * `c && c.bytes ? c.bytes : c` -- schema-cms surfaces every embedded certificate as an
+//     object carrying a `bytes` Buffer, so the raw-value fallback never fires.
+module.exports = { verify: verify };

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.12",
+  "version": "0.2.14",
   "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:f99392dd-064e-4cea-b273-77302f5d396d",
+  "serialNumber": "urn:uuid:7f3139fc-e726-4373-afdf-0e304562ee70",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-13T18:39:01.236Z",
+    "timestamp": "2026-07-13T21:48:02.712Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.12",
+      "bom-ref": "@blamejs/pki@0.2.14",
       "type": "application",
       "name": "pki",
-      "version": "0.2.12",
+      "version": "0.2.14",
       "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.12",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.14",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.12",
+      "ref": "@blamejs/pki@0.2.14",
       "dependsOn": []
     }
   ]