@blamejs/pki 0.2.8 → 0.2.9

package/CHANGELOG.md

@@ -4,6 +4,15 @@ 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.9 — 2026-07-13
+
+Certification-path validation verifies composite ML-DSA signatures, accepting a certificate only when both its post-quantum and traditional components verify.
+
+### Added
+
+- pki.path.validate verifies composite ML-DSA certificate signatures (draft-ietf-lamps-pq-composite-sigs): a post-quantum ML-DSA paired with a traditional RSA / ECDSA / EdDSA, accepted only when BOTH components verify over the domain-separated message representative -- an all-components-must-verify rule (an OR would be a downgrade). The same combinator verifies a composite-signed CRL or OCSP response. Proven against the draft's official known-answer test vectors.
+- The 18 composite algorithm identifiers (1.3.6.1.5.5.7.6.37-54) are registered in the OID registry and their AlgorithmIdentifier parameters-absent requirement is enforced across every format that carries a signature algorithm.
+
 ## v0.2.8 — 2026-07-13
 
 pki.webcrypto rejects an AES key of invalid length at import instead of deferring the failure to first use.

package/README.md

@@ -220,7 +220,7 @@ is callable today; nothing below is a stub.
 | `pki.acme` | RFC 8555 / 8737 / 8738 / 9773 ACME message layer over `pki.jose` — resource-object validators (closed status enums, conditional-required fields, unknown fields ignored), the three §7.1.6 state machines, request builders (newAccount + EAB, newOrder + `replaces`, finalize with CSR identifier-set match and account-key-reuse rejection, challenge responses, deactivation, revokeCert in both key modes, the keyChange nested JWS, POST-as-GET), the http-01 / dns-01 / tls-alpn-01 challenge computations, the dns/ip identifier validators, and the ARI certID (serial sign-padding preserved). A message layer, not an HTTP client — transport-injectable, fail-closed — `validate`, `identify`, `assertTransition`, the builders, `keyAuthorization`, `http01`, `dns01`, `tlsAlpn01Extension`, `verifyTlsAlpn01`, `ariCertId` |
 | `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, 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.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.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` |

package/lib/oid.js

@@ -222,7 +222,19 @@ var FAMILIES = {
   // identifiers (RFC 9802 sec. 4). HSS/LMS additionally has the SMIME
   // id-alg-hss-lms-hashsig OID above (RFC 9708 / RFC 9802 share it).
   pkixAlg: { base: [1, 3, 6, 1, 5, 5, 7, 6], of: {
-    "id-alg-xmss-hashsig": 34, "id-alg-xmssmt-hashsig": 35 } },
+    "id-alg-xmss-hashsig": 34, "id-alg-xmssmt-hashsig": 35,
+    // Composite ML-DSA signature algorithms (draft-ietf-lamps-pq-composite-sigs
+    // sec. 6): a PQ ML-DSA paired with a traditional RSA / ECDSA / EdDSA so the
+    // certificate stays trustworthy if EITHER primitive is later broken.
+    "id-MLDSA44-RSA2048-PSS-SHA256": 37, "id-MLDSA44-RSA2048-PKCS15-SHA256": 38,
+    "id-MLDSA44-Ed25519-SHA512": 39, "id-MLDSA44-ECDSA-P256-SHA256": 40,
+    "id-MLDSA65-RSA3072-PSS-SHA512": 41, "id-MLDSA65-RSA3072-PKCS15-SHA512": 42,
+    "id-MLDSA65-RSA4096-PSS-SHA512": 43, "id-MLDSA65-RSA4096-PKCS15-SHA512": 44,
+    "id-MLDSA65-ECDSA-P256-SHA512": 45, "id-MLDSA65-ECDSA-P384-SHA512": 46,
+    "id-MLDSA65-ECDSA-brainpoolP256r1-SHA512": 47, "id-MLDSA65-Ed25519-SHA512": 48,
+    "id-MLDSA87-ECDSA-P384-SHA512": 49, "id-MLDSA87-ECDSA-brainpoolP384r1-SHA512": 50,
+    "id-MLDSA87-Ed448-SHAKE256": 51, "id-MLDSA87-RSA3072-PSS-SHA512": 52,
+    "id-MLDSA87-RSA4096-PSS-SHA512": 53, "id-MLDSA87-ECDSA-P521-SHA512": 54 } },
 
   // RSA-KEM key-transport algorithm (RFC 9690, obsoletes RFC 5990) on the ISO
   // 18033-2 arc -- the kem OID an RSA KEMRecipientInfo carries (distinct from the
@@ -549,6 +561,17 @@ var _PARAMS_ABSENT = new Set();
   // Stateful hash-based signatures (RFC 9802 sec. 4 / RFC 9708): the parameters
   // field MUST be absent for HSS/LMS, XMSS, and XMSS^MT public keys and signatures.
   "id-alg-hss-lms-hashsig", "id-alg-xmss-hashsig", "id-alg-xmssmt-hashsig",
+  // Composite ML-DSA (draft-ietf-lamps-pq-composite-sigs sec. 5.3 + Figure 1:
+  // the parameters field MUST be absent for every composite AlgorithmIdentifier).
+  "id-MLDSA44-RSA2048-PSS-SHA256", "id-MLDSA44-RSA2048-PKCS15-SHA256",
+  "id-MLDSA44-Ed25519-SHA512", "id-MLDSA44-ECDSA-P256-SHA256",
+  "id-MLDSA65-RSA3072-PSS-SHA512", "id-MLDSA65-RSA3072-PKCS15-SHA512",
+  "id-MLDSA65-RSA4096-PSS-SHA512", "id-MLDSA65-RSA4096-PKCS15-SHA512",
+  "id-MLDSA65-ECDSA-P256-SHA512", "id-MLDSA65-ECDSA-P384-SHA512",
+  "id-MLDSA65-ECDSA-brainpoolP256r1-SHA512", "id-MLDSA65-Ed25519-SHA512",
+  "id-MLDSA87-ECDSA-P384-SHA512", "id-MLDSA87-ECDSA-brainpoolP384r1-SHA512",
+  "id-MLDSA87-Ed448-SHAKE256", "id-MLDSA87-RSA3072-PSS-SHA512",
+  "id-MLDSA87-RSA4096-PSS-SHA512", "id-MLDSA87-ECDSA-P521-SHA512",
 ].forEach(function (nm) {
   var d = byName(nm);
   // A seed-list typo must fail at module load -- admitting undefined would

package/lib/path-validate.js

@@ -258,6 +258,16 @@ function isDerNull(p) { return p && p.length === 2 && p[0] === 0x05 && p[1] ===
 
 function resolveDescriptor(sigAlg) {
   if (sigAlg.oid === OID_RSA_PSS) return resolveRsaPss(sigAlg.parameters);
+  var comp = COMPOSITE_ALGS[sigAlg.oid];
+  if (comp) {
+    // draft-ietf-lamps-pq-composite-sigs sec. 5.3: parameters MUST be absent.
+    if (sigAlg.parameters !== null && sigAlg.parameters !== undefined) {
+      throw E("path/unsupported-algorithm", "composite signature algorithm parameters must be absent (draft-ietf-lamps-pq-composite-sigs sec. 5.3)");
+    }
+    // The composite public-key algorithm OID equals the signature OID; enforce
+    // the RFC 9814-style key<->signature consistency structurally (sameKeyOid).
+    return { composite: comp, sameKeyOid: true };
+  }
   var d = SIG_ALGS[sigAlg.oid];
   if (!d) throw E("path/unsupported-algorithm", "no verify descriptor for signature algorithm " + (sigAlg.name || sigAlg.oid));
   // The signatureAlgorithm's parameters MUST match the algorithm's fixed shape:
@@ -316,6 +326,165 @@ function ecdsaDerToP1363(der, curve) {
   return Buffer.concat([pad(r), pad(s)]);
 }
 
+// ---- composite ML-DSA signatures (draft-ietf-lamps-pq-composite-sigs) -------
+// A composite signature pairs a post-quantum ML-DSA with a traditional RSA /
+// ECDSA / EdDSA. The public key is the raw concatenation mldsaPK || tradPK
+// (sec. 4.1) in the SPKI BIT STRING; the signature is mldsaSig || tradSig
+// (sec. 4.3) in the signatureValue BIT STRING. Both are surfaced RAW by the
+// x509 parser (no sub-walk). Verification (sec. 2): reconstruct
+//   M' = Prefix || Label || len(ctx) || ctx || PH(M),
+// verify the ML-DSA component over M' with ctx = the composite Label, verify the
+// traditional component over M' under its own hash, and accept IFF BOTH pass
+// (THREAT-MODEL: all components must verify -- never an AND-to-OR downgrade). The
+// ML-DSA component is the fixed-length FIRST half; the split point is its length.
+var COMPOSITE_PREFIX = Buffer.from("CompositeAlgorithmSignatures2025", "ascii");
+var MLDSA_COMPONENT = {
+  "ML-DSA-44": { pk: 1312, sig: 2420, oid: "id-ml-dsa-44" },
+  "ML-DSA-65": { pk: 1952, sig: 3309, oid: "id-ml-dsa-65" },
+  "ML-DSA-87": { pk: 2592, sig: 4627, oid: "id-ml-dsa-87" },
+};
+var EC_CURVE_OID = { "P-256": "prime256v1", "P-384": "secp384r1", "P-521": "secp521r1" };
+var COMPOSITE_ALGS = {};
+// _comp(name, mldsa, ph, label, trad). `trad` is exactly one component shape:
+//   { ec, hash } | { eddsa } | { rsaPss, hash, salt } | { rsaPkcs1, hash } |
+//   { unsupported } for the arms Node's WebCrypto surface cannot verify (brainpool
+//   curves; the SHAKE256/64 pre-hash) -- registered + params-guarded, deferred at
+//   verify to path/unsupported-algorithm rather than silently accepted.
+function _comp(name, mldsa, ph, label, trad) {
+  var sz = MLDSA_COMPONENT[mldsa];
+  COMPOSITE_ALGS[oid.byName(name)] = {
+    name: name, mldsa: mldsa, mldsaPk: sz.pk, mldsaSig: sz.sig, mldsaOid: sz.oid,
+    ph: ph, label: Buffer.from(label, "ascii"), trad: trad,
+  };
+}
+_comp("id-MLDSA44-RSA2048-PSS-SHA256", "ML-DSA-44", "SHA-256", "COMPSIG-MLDSA44-RSA2048-PSS-SHA256", { rsaPss: true, hash: "SHA-256", salt: 32, rsaBits: 2048 });
+_comp("id-MLDSA44-RSA2048-PKCS15-SHA256", "ML-DSA-44", "SHA-256", "COMPSIG-MLDSA44-RSA2048-PKCS15-SHA256", { rsaPkcs1: true, hash: "SHA-256", rsaBits: 2048 });
+_comp("id-MLDSA44-Ed25519-SHA512", "ML-DSA-44", "SHA-512", "COMPSIG-MLDSA44-Ed25519-SHA512", { eddsa: "Ed25519" });
+_comp("id-MLDSA44-ECDSA-P256-SHA256", "ML-DSA-44", "SHA-256", "COMPSIG-MLDSA44-ECDSA-P256-SHA256", { ec: "P-256", hash: "SHA-256" });
+_comp("id-MLDSA65-RSA3072-PSS-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-RSA3072-PSS-SHA512", { rsaPss: true, hash: "SHA-256", salt: 32, rsaBits: 3072 });
+_comp("id-MLDSA65-RSA3072-PKCS15-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-RSA3072-PKCS15-SHA512", { rsaPkcs1: true, hash: "SHA-256", rsaBits: 3072 });
+_comp("id-MLDSA65-RSA4096-PSS-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-RSA4096-PSS-SHA512", { rsaPss: true, hash: "SHA-384", salt: 48, rsaBits: 4096 });
+_comp("id-MLDSA65-RSA4096-PKCS15-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-RSA4096-PKCS15-SHA512", { rsaPkcs1: true, hash: "SHA-384", rsaBits: 4096 });
+_comp("id-MLDSA65-ECDSA-P256-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-ECDSA-P256-SHA512", { ec: "P-256", hash: "SHA-256" });
+_comp("id-MLDSA65-ECDSA-P384-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-ECDSA-P384-SHA512", { ec: "P-384", hash: "SHA-384" });
+_comp("id-MLDSA65-ECDSA-brainpoolP256r1-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-ECDSA-BP256-SHA512", { unsupported: "brainpoolP256r1 is not in the WebCrypto ECDSA curve set" });
+_comp("id-MLDSA65-Ed25519-SHA512", "ML-DSA-65", "SHA-512", "COMPSIG-MLDSA65-Ed25519-SHA512", { eddsa: "Ed25519" });
+_comp("id-MLDSA87-ECDSA-P384-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-ECDSA-P384-SHA512", { ec: "P-384", hash: "SHA-384" });
+_comp("id-MLDSA87-ECDSA-brainpoolP384r1-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-ECDSA-BP384-SHA512", { unsupported: "brainpoolP384r1 is not in the WebCrypto ECDSA curve set" });
+_comp("id-MLDSA87-Ed448-SHAKE256", "ML-DSA-87", "SHAKE256", "COMPSIG-MLDSA87-Ed448-SHAKE256", { unsupported: "the SHAKE256/64 pre-hash is not in the WebCrypto digest set" });
+_comp("id-MLDSA87-RSA3072-PSS-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-RSA3072-PSS-SHA512", { rsaPss: true, hash: "SHA-256", salt: 32, rsaBits: 3072 });
+_comp("id-MLDSA87-RSA4096-PSS-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-RSA4096-PSS-SHA512", { rsaPss: true, hash: "SHA-384", salt: 48, rsaBits: 4096 });
+_comp("id-MLDSA87-ECDSA-P521-SHA512", "ML-DSA-87", "SHA-512", "COMPSIG-MLDSA87-ECDSA-P521-SHA512", { ec: "P-521", hash: "SHA-512" });
+
+var _b = asn1.build;
+// Wrap a raw component public key in the SPKI its WebCrypto import expects, so
+// each half is verified through the SAME import + verify seam the classical path
+// uses (no second parallel verify path). tradPK for RSA is the RSAPublicKey DER;
+// for EC the uncompressed point; for EdDSA the raw public key.
+function _spkiFor(algNode, keyBytes) { return _b.sequence([algNode, _b.bitString(keyBytes, 0)]); }
+function _mldsaSpki(mldsaOid, raw) { return _spkiFor(_b.sequence([_b.oid(oid.byName(mldsaOid))]), raw); }
+function _ecSpki(curve, point) { return _spkiFor(_b.sequence([_b.oid(oid.byName("ecPublicKey")), _b.oid(oid.byName(EC_CURVE_OID[curve]))]), point); }
+function _edSpki(name, raw) { return _spkiFor(_b.sequence([_b.oid(oid.byName(name))]), raw); }
+function _rsaSpki(rsaPub) { return _spkiFor(_b.sequence([_b.oid(oid.byName("rsaEncryption")), _b.nullValue()]), rsaPub); }
+
+// The exact modulus bit length of an RSAPublicKey (SEQUENCE { modulus, exponent }).
+function _rsaModulusBits(rsaPubDer) {
+  return asn1.read.integer(asn1.decode(rsaPubDer).children[0]).toString(2).length;
+}
+
+function _verifyTradComponent(trad, tradPK, tradSig, mprime) {
+  if (trad.ec) {
+    // draft sec. 5.1: the EC point MUST be the uncompressed X9.62 form (leading 0x04).
+    // A compressed / hybrid point is a non-conforming composite component encoding.
+    if (tradPK.length < 1 || tradPK[0] !== 0x04) return Promise.resolve(false);
+    return subtle.importKey("spki", _ecSpki(trad.ec, tradPK), { name: "ECDSA" }, false, ["verify"]).then(function (k) {
+      // The traditional ECDSA signature is DER Ecdsa-Sig-Value; convert to P1363
+      // through the shared reader that also rejects r/s outside [1,n-1] (CVE-2022-21449).
+      var p1363 = ecdsaDerToP1363(tradSig, trad.ec);
+      return subtle.verify({ name: "ECDSA", hash: trad.hash }, k, p1363, mprime);
+    });
+  }
+  if (trad.eddsa) {
+    return subtle.importKey("spki", _edSpki(trad.eddsa, tradPK), { name: trad.eddsa }, false, ["verify"])
+      .then(function (k) { return subtle.verify({ name: trad.eddsa }, k, tradSig, mprime); });
+  }
+  if (trad.rsaPss || trad.rsaPkcs1) {
+    // The composite OID fixes the RSA modulus size: a downgraded or mismatched modulus
+    // under the declared OID (an id-MLDSA44-RSA2048-* whose component is really 1024-bit)
+    // is rejected BEFORE verify, so a weak RSA component cannot satisfy an arm that
+    // promises 2048/3072/4096 bits. A malformed RSAPublicKey rejects the same way.
+    var bits;
+    try { bits = _rsaModulusBits(tradPK); }
+    catch (_e) { return Promise.resolve(false); }
+    if (bits !== trad.rsaBits) return Promise.resolve(false);
+    if (trad.rsaPss) {
+      return subtle.importKey("spki", _rsaSpki(tradPK), { name: "RSA-PSS", hash: trad.hash }, false, ["verify"])
+        .then(function (k) { return subtle.verify({ name: "RSA-PSS", saltLength: trad.salt }, k, tradSig, mprime); });
+    }
+    return subtle.importKey("spki", _rsaSpki(tradPK), { name: "RSASSA-PKCS1-v1_5", hash: trad.hash }, false, ["verify"])
+      .then(function (k) { return subtle.verify({ name: "RSASSA-PKCS1-v1_5" }, k, tradSig, mprime); });
+  }
+  return Promise.resolve(false);
+}
+
+// Verify a composite signature: `spkiBytes` the issuer SPKI DER, `sigBytes` the
+// raw signatureValue (mldsaSig || tradSig), `message` the signed region (tbsBytes).
+function compositeVerify(spkiBytes, sigBytes, message, d) {
+  if (d.trad.unsupported) {
+    return Promise.resolve({ ok: false, code: "path/unsupported-algorithm",
+      error: E("path/unsupported-algorithm", "composite " + d.name + ": " + d.trad.unsupported) });
+  }
+  var rawKey;
+  try {
+    var bs = asn1.read.bitString(asn1.decode(spkiBytes).children[1]);
+    // The composite subjectPublicKey is an octet-aligned concatenation (no unused
+    // bits); a non-zero unused-bit count is malformed.
+    if (bs.unusedBits !== 0) throw E("path/bad-signature", "composite subjectPublicKey has unused bits");
+    rawKey = bs.bytes;
+  } catch (e) { return Promise.resolve({ ok: false, code: pathCode(e, "path/bad-signature"), error: e }); }
+  // The ML-DSA half is fixed-length and FIRST; the traditional half is the
+  // remainder. Both must be non-empty for a well-formed composite.
+  if (rawKey.length <= d.mldsaPk || sigBytes.length <= d.mldsaSig) {
+    return Promise.resolve({ ok: false, code: "path/bad-signature",
+      error: E("path/bad-signature", "composite key/signature shorter than the fixed ML-DSA component") });
+  }
+  var mldsaPK = rawKey.subarray(0, d.mldsaPk), tradPK = rawKey.subarray(d.mldsaPk);
+  var mldsaSig = sigBytes.subarray(0, d.mldsaSig), tradSig = sigBytes.subarray(d.mldsaSig);
+  return subtle.digest({ name: d.ph }, message).then(function (phBuf) {
+    // M' = Prefix || Label || len(ctx)=0 || ctx="" || PH(M). In X.509 path
+    // validation the application context is empty (a caller ctx is out of scope).
+    var mprime = Buffer.concat([COMPOSITE_PREFIX, d.label, Buffer.from([0]), Buffer.from(phBuf)]);
+    var mldsaP = subtle.importKey("spki", _mldsaSpki(d.mldsaOid, mldsaPK), { name: d.mldsa }, false, ["verify"])
+      .then(function (mk) { return subtle.verify({ name: d.mldsa, context: d.label }, mk, mldsaSig, mprime); });
+    var tradP = _verifyTradComponent(d.trad, tradPK, tradSig, mprime);
+    return Promise.all([mldsaP, tradP]).then(function (r) { return { ok: r[0] === true && r[1] === true }; });
+  }).catch(function (e) { return { ok: false, code: pathCode(e, "path/bad-signature"), error: e }; });
+}
+
+// draft-ietf-lamps-pq-composite-sigs sec. 5.2: a certificate whose SubjectPublicKeyInfo
+// carries a composite ML-DSA OID, IF it has a keyUsage extension, MUST assert at least
+// one signature bit (digitalSignature / nonRepudiation / keyCertSign / cRLSign) and MUST
+// NOT assert any encryption or key-establishment bit -- a composite ML-DSA key is a
+// signature-only key (ML-DSA cannot encrypt or agree, so a "dual usage" key is forbidden
+// even when the traditional component could encrypt). The caller invokes this only for a
+// composite-keyed certificate; an absent keyUsage places no restriction (RFC 5280 4.2.1.3).
+function compositeKeyUsageCheck(cert) {
+  var ku;
+  try { ku = decodeExt(cert, OID.keyUsage); }
+  catch (e) { return { ok: false, code: "path/composite-key-usage", error: e }; }
+  if (!ku) return { ok: true };
+  var v = ku.value;
+  if (v.keyEncipherment || v.dataEncipherment || v.keyAgreement || v.encipherOnly || v.decipherOnly) {
+    return { ok: false, code: "path/composite-key-usage",
+      error: E("path/composite-key-usage", "a composite ML-DSA key asserts a forbidden encryption/key-establishment keyUsage bit (draft-ietf-lamps-pq-composite-sigs sec. 5.2)") };
+  }
+  if (!(v.digitalSignature || v.nonRepudiation || v.keyCertSign || v.cRLSign)) {
+    return { ok: false, code: "path/composite-key-usage",
+      error: E("path/composite-key-usage", "a composite ML-DSA key's keyUsage asserts no signature bit (draft-ietf-lamps-pq-composite-sigs sec. 5.2)") };
+  }
+  return { ok: true };
+}
+
 // Verify cert.signatureValue over cert.tbsBytes with the working public key.
 function builtinVerify(state, cert) {
   var d;
@@ -326,6 +495,10 @@ function builtinVerify(state, cert) {
   // The signature is an octet-aligned BIT STRING (no unused bits) for every
   // supported algorithm; a non-zero unused-bit count is malformed.
   if (!guard.crypto.isOctetAligned(cert.signatureValue)) return Promise.resolve({ ok: false, code: "path/bad-signature" });
+  // A composite signature verifies its ML-DSA and traditional halves and accepts
+  // IFF both pass -- delegated to the composite combinator (which reuses this
+  // file's ECDSA range-check + the same import/verify seam).
+  if (d.composite) return compositeVerify(state.workingPublicKey, cert.signatureValue.bytes, cert.tbsBytes, d.composite);
   var key;
   return subtle.importKey("spki", state.workingPublicKey, d.imp, false, ["verify"]).then(function (k) {
     key = k;
@@ -1165,6 +1338,15 @@ async function validate(path, opts) {
     checks.push({ name: "signature", ok: sigRes.ok, code: sigRes.ok ? undefined : (sigRes.code || "path/bad-signature") });
     if (!sigRes.ok) failed = true;
 
+    // draft-ietf-lamps-pq-composite-sigs sec. 5.2: a composite-keyed certificate's
+    // keyUsage must be signature-only (no dual-usage). Runs for the target AND every
+    // intermediate whose own subject key is composite.
+    if (COMPOSITE_ALGS[cert.subjectPublicKeyInfo.algorithm.oid]) {
+      var cku = compositeKeyUsageCheck(cert);
+      checks.push({ name: "compositeKeyUsage", ok: cku.ok, code: cku.ok ? undefined : cku.code });
+      if (!cku.ok) failed = true;
+    }
+
     // 6.1.3(a)(2) validity window.
     var t = opts.time;
     var vOk = true, vCode;
@@ -1733,6 +1915,10 @@ function _verifyWithSpki(sigAlg, rawSig, spkiBytes, tbsBytes) {
     d = resolveDescriptor(sigAlg);
     assertKeyMatchesSigAlg(spkiBytes, sigAlg.oid, d);
   } catch (_e) { return Promise.resolve(false); }
+  // A composite-signed CRL / OCSP response verifies through the same combinator
+  // (both halves must pass) that the certificate path uses -- one composite verify,
+  // never a second parallel one.
+  if (d.composite) return compositeVerify(spkiBytes, rawSig, tbsBytes, d.composite).then(function (r) { return r.ok === true; });
   return subtle.importKey("spki", spkiBytes, d.imp, false, ["verify"]).then(function (key) {
     var sig = rawSig;
     if (d.ecdsa) sig = ecdsaDerToP1363(sig, key.algorithm.namedCurve);
@@ -1893,6 +2079,10 @@ async function ocspAuthorizeResponder(basicResponse, cert, issuer, issuerKeyBits
     // responder's own status opts in through a future checker; absent nocheck, fail
     // closed (unknown) rather than trust an unvalidated responder.
     if (!findExt(rc, OID_OCSP_NOCHECK)) continue;
+    // A composite-keyed delegate is an out-of-path signer cert and gets the same
+    // composite keyUsage gate the path certificates do (draft sec. 5.2): a dual-usage
+    // composite responder key (a forbidden encryption bit set) is not authorized.
+    if (COMPOSITE_ALGS[rc.subjectPublicKeyInfo.algorithm.oid] && !compositeKeyUsageCheck(rc).ok) continue;
     return ocspResponderSpki(rc, issuer);
   }
   return null;

package/lib/webcrypto.js

@@ -267,6 +267,16 @@ function _generateKeyPair(alg) {
 }
 
 function _hashObj(h) { if (!h) return undefined; return { name: (typeof h === "string" ? h : h.name) }; }
+// The node key argument for an ML-DSA sign/verify: the bare handle, or a
+// { key, context } when the caller supplies an ML-DSA context. FIPS 204 bounds the
+// context to 0..255 bytes; a longer one is a DataError at the API boundary, not a
+// raw ERR_OUT_OF_RANGE from node.
+function _mldsaKeyArg(alg, keyHandle, who) {
+  if (alg.context == null) return keyHandle;
+  var ctx = _toBuf(alg.context, who + " context");
+  if (ctx.length > 255) throw new WebCryptoError("webcrypto/data", who + ": an ML-DSA context must be at most 255 bytes (FIPS 204)");
+  return { key: keyHandle, context: ctx };
+}
 // publicExponent arrives as a W3C BigInteger octet string but node:crypto
 // takes a JS number, so the value is bounds-checked BEFORE the Number()
 // narrowing: an empty buffer has no integer value (BigInt("0x") is a raw
@@ -305,7 +315,13 @@ SubtleCrypto.prototype.sign = async function sign(algorithm, key, data) {
   if (name === "ECDSA") {
     return _toArrayBuffer(nodeCrypto.sign(_hashNode(alg.hash, "sign"), buf, { key: key._handle, dsaEncoding: "ieee-p1363" }));
   }
-  if (name === "ED25519" || name === "ED448" || ML_DSA_NODE[name] || SLH_DSA_NODE[name]) {
+  if (ML_DSA_NODE[name]) {
+    // ML-DSA (FIPS 204) accepts an optional context octet string; thread it through
+    // signing symmetrically with verify so a context signature round-trips (a
+    // signature made with a context verifies only under the SAME context).
+    return _toArrayBuffer(nodeCrypto.sign(null, buf, _mldsaKeyArg(alg, key._handle, "sign")));
+  }
+  if (name === "ED25519" || name === "ED448" || SLH_DSA_NODE[name]) {
     return _toArrayBuffer(nodeCrypto.sign(null, buf, key._handle));
   }
   if (name === "HMAC") {
@@ -336,7 +352,13 @@ SubtleCrypto.prototype.verify = async function verify(algorithm, key, signature,
   if (name === "ECDSA") {
     return nodeCrypto.verify(_hashNode(alg.hash, "verify"), buf, { key: key._handle, dsaEncoding: "ieee-p1363" }, sig);
   }
-  if (name === "ED25519" || name === "ED448" || ML_DSA_NODE[name] || SLH_DSA_NODE[name]) {
+  if (ML_DSA_NODE[name]) {
+    // ML-DSA (FIPS 204) accepts an optional context octet string (the composite
+    // signature construction passes the composite Domain as the ML-DSA context,
+    // draft-ietf-lamps-pq-composite-sigs sec. 2). A context mismatch fails.
+    return nodeCrypto.verify(null, buf, _mldsaKeyArg(alg, key._handle, "verify"), sig);
+  }
+  if (name === "ED25519" || name === "ED448" || SLH_DSA_NODE[name]) {
     return nodeCrypto.verify(null, buf, key._handle, sig);
   }
   if (name === "HMAC") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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:fb3ea0b4-6f7b-459d-b24d-19dcdee7f0a8",
+  "serialNumber": "urn:uuid:a09496c1-2301-420c-a786-1cb883b3f77c",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-13T08:58:47.895Z",
+    "timestamp": "2026-07-13T10:49:09.267Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.8",
+      "bom-ref": "@blamejs/pki@0.2.9",
       "type": "application",
       "name": "pki",
-      "version": "0.2.8",
+      "version": "0.2.9",
       "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.8",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.8",
+      "ref": "@blamejs/pki@0.2.9",
       "dependsOn": []
     }
   ]