@blamejs/pki 0.4.12 → 0.4.13

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.4.13 — 2026-08-10
+
+A KEM shared secret and the key it derives are now wiped as soon as they stop being needed -- on the failing path as well as the succeeding one, which is the path an attacker chooses.
+
+### Added
+
+- A KEM shared secret and the key-encryption key derived from it are wiped as soon as they stop being needed, satisfying NIST SP 800-227 RS5 / sec. 4.2 and RFC 9629 sec. 7. The wipe runs in a finally, so a decryption that FAILS clears the same buffers a successful one does -- a wipe on the success path alone would preserve the secret in exactly the case an attacker can force. Only buffers this library allocated are cleared; a caller's key material, certificate, and the returned plaintext are never written to, and the plaintext remains usable after the wipe.
+- This is best-effort and is documented as such rather than overstated. The runtime copies a shared secret into places no code can reach -- the decapsulation result on its way out, and again when it is imported as key material -- and may relocate a buffer's backing store. Wiping the copies the library holds shortens the window in which a secret is readable; it does not mean a secret never persists in memory.
+- pki.oid.kemParams resolves an ML-KEM parameter set to its FIPS 203 Table 3 sizes, by dotted OID or by registered name.
+
+### Changed
+
+- The ML-KEM ciphertext-length check FIPS 203 sec. 7.3 requires of a decapsulating party is now performed by the crypto engine, so a caller reaching decapsulateBits directly is covered rather than only the CMS path that happens to call it today. It reports webcrypto/bad-kem-ciphertext, naming the parameter set and both lengths, where the failure was previously indistinguishable from any other decapsulation fault; a ciphertext whose length is valid for a DIFFERENT parameter set is refused as such rather than treated as merely short. The check is on length ONLY: a correct-length ciphertext that has been tampered with still resolves to a pseudo-random shared secret, because turning that into an error would give an attacker a decryption oracle. No engine detail reaches a CMS caller: a structurally valid message whose decryption fails for any secret-dependent reason still reports the single uniform cms/decrypt-failed verdict. A message whose ML-KEM ciphertext length does not match the parameter set the message itself declares is a separate case and always was -- including a length that would be valid for a different set -- because the strict parser rejects it up front and names it: the mismatch is a structural fault, decidable from the message alone, with nothing about it depending on a key.
+- The ML-KEM parameter sizes resolve from one registry instead of three separate tables in three modules. The encapsulation-key lengths were already duplicated verbatim in two of them, and each new consumer meant another copy that could drift; a parameter set is a property of the algorithm identifier, so it now lives beside the registry that resolves one. Behaviour is unchanged.
+
+### Fixed
+
+- The roadmap attributed two rules to NIST SP 800-227 that it does not state: implicit rejection and re-encapsulation are FIPS 203's, reached through SP 800-227's requirement to comply with the KEM's own standard, and SP 800-227 sec. 4.3 explicitly permits a shared secret to be used directly, truncated, or split into segments -- the unconditional key-derivation requirement comes from RFC 9629 sec. 5. The entry now states what each document requires.
+
 ## v0.4.12 — 2026-08-09
 
 A CMS message can no longer declare one content cipher and be opened with another: the declared algorithm's mode is now bound to the container that carries it, so an EnvelopedData naming an authenticated cipher is refused rather than opened, unauthenticated, under a result that reported it as authenticated.

package/README.md

@@ -232,7 +232,7 @@ is callable today; nothing below is a stub.
 | `pki.crl` | RFC 5280 §5 certificate revocation list issuance — `sign(spec, issuer, opts)` builds and signs a `CertificateList`: a `spec` of `thisUpdate` / `nextUpdate`, an optional `crlNumber`, a `revoked` array (each entry a `serialNumber` + `revocationDate` with an optional `reason` or `invalidityDate`), and an optional `extensions` object (authority key identifier, issuing distribution point, delta-CRL indicator, freshest CRL, authority information access) or an array of pre-encoded Extension DER; an `issuer` of `{ cert, key }` or `{ name, publicKey, key }`. The signature algorithm is resolved from the issuer key, so RSA (PKCS#1 v1.5 / PSS via `opts.pss`), ECDSA, EdDSA, ML-DSA, SLH-DSA, and the composite arms all sign without a per-algorithm branch. The version is derived from the extension set (v2 when any CRL or entry extension is present, else v1), the outer `signatureAlgorithm` matches `tbsCertList.signature`, an empty revocation list omits the field rather than emitting an empty SEQUENCE, `reasonCode` is an ENUMERATED and `invalidityDate` is always GeneralizedTime, per-extension criticality is fixed by the RFC, and the produced signature is verified under the issuer key before return. `verify(crl, issuer)` checks a CRL signature through the one path-validation signature engine (algorithm-confusion and EdDSA low-order gates included), and `isRevoked(crl, serialNumber)` looks a serial up in the revocation list. Returns DER, or a PEM `X509 CRL` with `opts.pem`; malformed input throws a typed `CrlError`. Parsing stays at `pki.schema.crl.parse` — `sign` / `verify` / `isRevoked` |
 | `pki.key` | RFC 5958 / RFC 8018 key-material lifecycle — `encrypt(privateKey, password, opts)` wraps a PKCS#8 private key (DER, PEM, or an extractable `CryptoKey`) into an `EncryptedPrivateKeyInfo` under PBES2 (PBKDF2 + AES-CBC-Pad): `opts` selects the `cipher` (`aes-256-cbc` default, `aes-192-cbc`, `aes-128-cbc`), the `prf` (`hmacWithSHA256` default, SHA-384/512, SHA-1), the `iterations` (default 600000), and the `salt`; the plaintext is validated as PKCS#8 before encryption, a default `prf` and `keyLength` are omitted so the parameters are byte-exact with OpenSSL, and the output is re-parsed before return. `decrypt(encrypted, password, opts)` recovers the inner `PrivateKeyInfo` (re-validated through `pki.schema.pkcs8.parse`) — only PBES2/PBKDF2/AES-CBC is accepted (PBES1, PBMAC1, scrypt refused), the salt and iteration count are bounded before any derivation (`opts.maxIterations` lowers the cap), a malformed parameter set or wrong-length IV is a distinct typed error, and — because a MAC-less PBES2-CBC decrypt must not be a padding oracle (RFC 8018 §8) — a wrong password and a valid-pad-but-not-a-key both surface the one uniform `key/decrypt-failed`. `export(key, opts)` / `import(input, opts)` move a private key as PKCS#8 or a public key as SubjectPublicKeyInfo -- the key may come from the platform's WebCrypto or from a separately-installed copy of this toolkit, and is exported through whichever holds its material (a non-extractable key, or one whose implementation keeps its material out of reach, is refused with that as the reason) -- delegating the encoding to WebCrypto so RSA carries an explicit NULL, EC a named curve, and Ed25519/Ed448/X25519/X448 omit parameters (an ambiguous RSA/EC import requires `opts.algorithm`). `generate(algorithm, opts)` produces a key pair over RSA, ECDSA/ECDH, the Edwards/Montgomery curves, and the FIPS post-quantum ML-DSA / ML-KEM, and `publicFromPrivate(privateKey)` derives the public key. Returns DER or PEM; fail-closed with typed `KeyError`. Parsing stays at `pki.schema.pkcs8.parse` — `encrypt` / `decrypt` / `export` / `import` / `generate` / `publicFromPrivate` |
 | `pki.pkcs12` | RFC 7292 / RFC 9579 PKCS#12 (.p12/.pfx) issuance — `build(spec, opts)` assembles a password-integrity store. `spec` is the OpenSSL-style `{ key, cert, ca?, friendlyName?, localKeyId? }` or the full `{ safeContents: [...] }`, where each element is a plaintext or PBES2-encrypted `SafeContents` of key / shroudedKey / cert / crl / secret / nested `safeContents` bags. Keys and certs are validated before wrapping; `friendlyName` (BMPString) and `localKeyId` attributes are single-value. The store is protected by a classic Appendix B HMAC (default, max interop) or an RFC 9579 PBMAC1 (`opts.mac.algorithm`), over SHA-256/384/512, with the shrouded keys and cert safes encrypted under RFC 8018 PBES2 (AES-128/192/256-CBC). Every password is encoded the PKCS#12 way — BMPString+NULL for the classic MAC, UTF-8 for the PBES2 bags and PBMAC1 (what OpenSSL and NSS consume) — so a file it emits opens in OpenSSL and NSS, cross-checked bidirectionally. The MAC is computed over the exact AuthenticatedSafe byte range, a DEFAULT-1 `MacData.iterations` is rejected up front, and the store is re-parsed before return. `verifyMac(pfx, password, opts)` recomputes a store's classic or PBMAC1 MAC over `macedBytes` and constant-time-compares it, throwing on a MAC-less or public-key-integrity store. **Public-key integrity** (`opts.integrity.mode: "public-key"`) wraps the AuthenticatedSafe in a CMS SignedData instead of a MAC — a signature from any `pki.cms.sign` signer (RSA / ECDSA / EdDSA / ML-DSA / SLH-DSA / composite), no MacData (RFC 7292 §4); privacy stays independent, so the `password` still PBES2-encrypts the bags. **Public-key privacy** — per-safe `recipients` (or the `opts.recipientCerts` convenience) wraps a SafeContents as a CMS EnvelopedData (AES-CBC, `id-envelopedData` — never GCM) encrypting it to recipient public keys through the shipped `pki.cms.encrypt` recipient model, restricted to certificate recipients (RSA-OAEP / ECDH / X25519 / X448 / ML-KEM — a password or KEK recipient, which `open` could not reopen, is rejected); all four integrity × privacy combinations are permitted (RFC 7292 §3.1). **Legacy-PBE read** — `open` decrypts the RFC 7292 Appendix C 3DES and RC2 bags an `openssl pkcs12 -legacy` / NSS store uses (RC2 via an in-tree RFC 2268 cipher), so an older store opens; the legacy RC4 schemes are refused. Returns DER or a PEM `PKCS12`; fail-closed with typed `Pkcs12Error`. `open(pfx, password, opts)` reads a store back: it verifies the MAC **first** (a wrong password is the MAC verdict, not a decrypt error), then PBES2-decrypts every privacy safe and shrouded key bag and returns `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` — keys as re-validated PKCS#8 DER, certs/CRLs/secrets as raw DER, all with `friendlyName`/`localKeyId`, nested safes recursively. A MAC-less store is refused unless `opts.allowUnauthenticated`; a **public-key-integrity store is verified through its CMS SignedData signature first** (`pkcs12/signature-invalid` on failure, the signer surfaced in `signers` but never trust-chained — the caller's `pki.path.validate` step); a legacy-PBE (App. C) store's 3DES / RC2 bags are decrypted (RC4 refused); an `id-envelopedData` (public-key privacy) safe is decrypted with `opts.recipientKey` after the integrity gate (`pkcs12/no-recipient-key` if absent, every recipient-side fault the uniform `pkcs12/decrypt-failed`); a post-integrity decrypt failure is the uniform `pkcs12/decrypt-failed`, and `opts.keys: 'crypto'` imports each key to a `CryptoKey`; it reads what OpenSSL and NSS produce. Parsing stays at `pki.schema.pkcs12.parse` — `build` / `verifyMac` / `open` |
-| `pki.cms` | RFC 5652 §5 CMS SignedData signing + signature verification — `sign(content, signers, opts)` produces a SignedData (attached or detached, one or many signers, RSA / RSASSA-PSS / ECDSA / EdDSA, the post-quantum ML-DSA-44/65/87 (RFC 9882) and SLH-DSA (all twelve FIPS 205 sets, RFC 9814), and composite ML-DSA (pairing ML-DSA with a traditional RSA / ECDSA / EdDSA — accepted only when **both** components verify — draft-ietf-lamps-cms-composite-sigs)); it builds the signed attributes (content-type, message-digest, signing-time) as canonical DER, signs the exact §5.4 preimage, and emits a DER `Buffer` or PEM. `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. It 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`. **Countersignatures** (RFC 5652 §11.4): `countersign(cms, signers, opts)` adds a countersignature — a `SignerInfo` over the countersigned SignerInfo's signature value, any signer algorithm, nestable, the primary bytes preserved so it still verifies — attached as the id-countersignature unsigned attribute; `verify` returns each countersignature's verdict under `signers[i].countersignatures` and every unsigned attribute (an RFC 3161 timestamp token attachable via `sign`'s `unsignedAttributes`) under `signers[i].unsignedAttrs`, surfaced unauthenticated. **Content encryption** (RFC 5652/5083/5084/9629): `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData — recipients auto-dispatch off the certificate key to key-transport (RSAES-OAEP; v1.5 never emitted), key-agreement (ephemeral-static ECDH over P-256/384/521 with the X9.63 KDF, and X25519/X448 with HKDF), symmetric key-wrap, password (PBKDF2 + RFC 3211 PWRI-KEK), or the post-quantum ML-KEM KEMRecipientInfo (RFC 9629/9936) — one fresh content key wrapped for every recipient. `decrypt(input, keyMaterial, opts)` recovers the content through the matching arm and returns it with an `authenticated` flag; every secret-dependent failure collapses to one uniform `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL / password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. **AuthenticatedData** (RFC 5652 §9): `authenticate(content, recipients, opts)` produces an `id-ct-authData` — cleartext content plus an HMAC-SHA-256/384/512 MAC (authenticated but not encrypted), the fresh MAC key wrapped for every recipient through the same RecipientInfo model as `encrypt`; the MAC covers the authenticated attributes (content-type + message-digest) re-tagged to the EXPLICIT SET OF (§9.2), or the content octets directly. `decrypt` recovers the MAC key, recomputes the MAC and independently the message-digest (§9.3), and releases the content only after both pass, with every secret-dependent failure collapsing to the uniform `cms/decrypt-failed`. **Compression** (RFC 3274): `compress(content, opts)` / `decompress(input, opts)` produce and consume a CompressedData (ZLIB, version 0, id-alg-zlibCompress); decompress bounds the uncompressed output at 16 MiB and stops before it is materialized, so a decompression bomb fails closed as `cms/decompress-too-large` — a size transform with no integrity/confidentiality (RFC 8551 §2.4.5). Fail-closed with typed `cms/*` errors — `sign`, `verify`, `countersign`, `encrypt`, `authenticate`, `decrypt`, `compress`, `decompress` |
+| `pki.cms` | RFC 5652 §5 CMS SignedData signing + signature verification — `sign(content, signers, opts)` produces a SignedData (attached or detached, one or many signers, RSA / RSASSA-PSS / ECDSA / EdDSA, the post-quantum ML-DSA-44/65/87 (RFC 9882) and SLH-DSA (all twelve FIPS 205 sets, RFC 9814), and composite ML-DSA (pairing ML-DSA with a traditional RSA / ECDSA / EdDSA — accepted only when **both** components verify — draft-ietf-lamps-cms-composite-sigs)); it builds the signed attributes (content-type, message-digest, signing-time) as canonical DER, signs the exact §5.4 preimage, and emits a DER `Buffer` or PEM. `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. It 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`. **Countersignatures** (RFC 5652 §11.4): `countersign(cms, signers, opts)` adds a countersignature — a `SignerInfo` over the countersigned SignerInfo's signature value, any signer algorithm, nestable, the primary bytes preserved so it still verifies — attached as the id-countersignature unsigned attribute; `verify` returns each countersignature's verdict under `signers[i].countersignatures` and every unsigned attribute (an RFC 3161 timestamp token attachable via `sign`'s `unsignedAttributes`) under `signers[i].unsignedAttrs`, surfaced unauthenticated. **Content encryption** (RFC 5652/5083/5084/9629): `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData — recipients auto-dispatch off the certificate key to key-transport (RSAES-OAEP; v1.5 never emitted), key-agreement (ephemeral-static ECDH over P-256/384/521 with the X9.63 KDF, and X25519/X448 with HKDF), symmetric key-wrap, password (PBKDF2 + RFC 3211 PWRI-KEK), or the post-quantum ML-KEM KEMRecipientInfo (RFC 9629/9936) — one fresh content key wrapped for every recipient. `decrypt(input, keyMaterial, opts)` recovers the content through the matching arm and returns it with an `authenticated` flag; every secret-dependent failure collapses to one uniform `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL / password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. A KEM shared secret and its derived key-encryption key are wiped once used, on the failing path as well as the succeeding one (best-effort; NIST SP 800-227, RFC 9629 sec. 7). **AuthenticatedData** (RFC 5652 §9): `authenticate(content, recipients, opts)` produces an `id-ct-authData` — cleartext content plus an HMAC-SHA-256/384/512 MAC (authenticated but not encrypted), the fresh MAC key wrapped for every recipient through the same RecipientInfo model as `encrypt`; the MAC covers the authenticated attributes (content-type + message-digest) re-tagged to the EXPLICIT SET OF (§9.2), or the content octets directly. `decrypt` recovers the MAC key, recomputes the MAC and independently the message-digest (§9.3), and releases the content only after both pass, with every secret-dependent failure collapsing to the uniform `cms/decrypt-failed`. **Compression** (RFC 3274): `compress(content, opts)` / `decompress(input, opts)` produce and consume a CompressedData (ZLIB, version 0, id-alg-zlibCompress); decompress bounds the uncompressed output at 16 MiB and stops before it is materialized, so a decompression bomb fails closed as `cms/decompress-too-large` — a size transform with no integrity/confidentiality (RFC 8551 §2.4.5). Fail-closed with typed `cms/*` errors — `sign`, `verify`, `countersign`, `encrypt`, `authenticate`, `decrypt`, `compress`, `decompress` |
 | `pki.smime` | RFC 8551 S/MIME message assembly, verification, encryption, and compression over the CMS layer — `sign(content, signers, opts)` wraps a MIME entity as a signed S/MIME message in either form: `multipart/signed` (clear-signed — the content stays readable in any MUA, a detached CMS SignedData rides alongside as `application/pkcs7-signature` with a matching `micalg`) or `application/pkcs7-mime; smime-type=signed-data` (opaque — the whole entity is a base64 CMS SignedData). The signed bytes are the entity's RFC 8551 §3.1.1 canonical form (CRLF line endings); `verify(message, opts)` unwraps both forms and recomputes over the same canonicalizer, so a transport that re-wraps line endings still verifies and a tampered part fails. `encrypt(content, recipients, opts)` envelopes a MIME entity as an opaque `application/pkcs7-mime` message and `decrypt(message, keyMaterial, opts)` opens one — `smime-type=authEnveloped-data` (AES-GCM, confidentiality and integrity, the default) or `smime-type=enveloped-data` (AES-CBC, confidentiality only, so `decrypt` reports `authenticated: false`, the §3.3 no-integrity caveat); the `smime-type` is derived from the CMS body, not the header, and decryption is fail-closed and oracle-free. The crypto is entirely `pki.cms.sign` / `verify` / `encrypt` / `decrypt` — any RSA / RSASSA-PSS / ECDSA / EdDSA / ML-DSA / SLH-DSA signer and any RSA-OAEP / ECDH / X25519 / X448 / AES-KW / PBKDF2 / ML-KEM recipient carries through (algorithm-agnostic). Like `cms.verify`, `verify` returns the per-signer cryptographic verdict plus the recovered content; chaining a signer to a trust anchor is the caller's `pki.path.validate` step. `compress(content, opts)` / `decompress(message, opts)` add the opaque `application/pkcs7-mime; smime-type=compressed-data; name=smime.p7z` frame (RFC 8551 §3.6, RFC 3274) — a size transform with no integrity/confidentiality (§2.4.5), decompress bounded against a bomb; the recovered content, which may itself be signed or enveloped, is returned for the caller to re-verify. **Header protection** (RFC 9788): `sign` / `encrypt` gain `opts.protectHeaders` — the caller's `opts.headers` are inlined on the Cryptographic Payload root (its Content-Type gains `hp="clear"` signed / `hp="cipher"` encrypted) so the CMS signature/encryption covers them, defeating a transport that rewrites or reads Subject/From/… `verify` / `decrypt` surface the AUTHENTICATED inner set as `protectedHeaders` + `headerProtection { present, mode, fromMismatch, confidential, legacy }` (a tampered outer header cannot alter it; `fromMismatch` flags an outer From that disagrees). Encryption applies a Header Confidentiality Policy — the default `hcp_baseline` obscures the outer Subject to `[...]` and removes Comments/Keywords, so the real values live only in the ciphertext; `decrypt` recovers them. Every emitted header routes through a fail-closed injection guard (a CR/LF/NUL value or a non-ftext name is rejected), and a malformed/contradictory `hp` wrap fails closed (`smime/bad-header-protection`), never a silent downgrade; the CMS crypto is unchanged. Inbound **legacy** RFC 8551 header protection is recognized opt-in: `verify` / `decrypt` with `opts.legacyHeaderProtection` detect a legacy `message/rfc822`-wrapped payload (the RFC 9788 §4.10.1 four-condition identification) and surface the inner message's headers under `headerProtection.legacy = { headers, mode, fromMismatch, confidential }` (`headers` an ordered `[{ name, value }]` array that retains legally-repeated fields like `Received`) — never in `protectedHeaders` and never setting `present: true`. Because a legacy message is structurally indistinguishable from an ordinary forwarded `message/rfc822`, this is an explicit heuristic (§4.10.2, "no strong end-to-end guarantees"): a caller keying trust off `present`/`protectedHeaders` is never misled, and only one that explicitly reads `headerProtection.legacy.headers` (cross-checking `legacy.fromMismatch`) consumes it. Off by default; a nested crypto layer, an inner `hp=`, a non-`message/rfc822` payload, or a duplicate Content-Type reports `legacy: null`. Bidirectionally interoperable with `openssl smime` / `openssl cms`. Fail-closed with typed `smime/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
 | `pki.tsp` | RFC 3161 Time-Stamp Protocol — `sign(messageImprint, tsa, opts)` produces a TimeStampToken: a CMS SignedData (over `pki.cms.sign`) whose content is a `TSTInfo` carrying the timestamped message imprint, the TSA policy, a serial number, and `genTime` (with optional accuracy / nonce / ordering), plus the RFC 3161 §2.4.2 signing-certificate attribute binding the token to the TSA certificate (SHA-2 imprints, any `pki.cms.sign` TSA key). `request` / `parseRequest` build and parse the TimeStampReq a client sends (imprint, requested policy, nonce, certReq), `response` / `parseResponse` the TimeStampResp a TSA returns — a granted status wrapping a token, or a rejection with PKIStatus and failure info, the §2.4.2 status↔token coupling enforced in both directions. `verify(token, data, opts)` verifies a token fail-closed: the CMS signature over the exact signed bytes, the message imprint recomputed from the data, the TSTInfo content type, the ESSCertID(V2) binding to the TSA certificate, the §2.3 critical timeStamping-only extendedKeyUsage, the request nonce when used, and — with a trust anchor supplied — full certification-path validation of the TSA certificate at the token's `genTime`, returning `{ valid, genTime, serialNumber, tstInfo, … }` — `sign`, `request`, `parseRequest`, `response`, `parseResponse`, `verify` |
 | `pki.ocsp` | RFC 6960 Online Certificate Status Protocol — the responder and relying-party surface. `buildRequest(query, opts)` builds an OCSPRequest for one or more `{ cert, issuer }` pairs (CertID hashed under SHA-1 by default per the RFC 5019 lightweight profile, or SHA-2; optional RFC 9654 nonce, optional requestor signature). `sign(responseData, responder, opts)` produces a signed BasicOCSPResponse over the exact `ResponseData` DER — the issuing CA directly or a delegated responder, any `pki.cms.sign` key including the post-quantum ML-DSA / SLH-DSA sets, with `good` / `revoked` (reason + time) / `unknown` per-certificate status, and `buildErrorResponse(status)` the unsigned §2.3 error (`tryLater` / `unauthorized` / …). `verify(response, opts)` verifies a response fail-closed against the same hardened gates `pki.path.ocspChecker` runs: the CertID binding, responder authorization (the issuing CA or a CA-issued delegate bearing id-kp-OCSPSigning **and** id-pkix-ocsp-nocheck, passing the full out-of-path certificate gates), the signature over `tbsResponseDataBytes`, currency (`thisUpdate`/`nextUpdate`), and the request-nonce echo — returning `{ status: "good" / "revoked" / "unknown", … }`, never a silent accept. Transport-free — `buildRequest`, `sign`, `buildErrorResponse`, `verify` |

package/lib/cms-decrypt.js

@@ -308,10 +308,29 @@ async function _kemriCek(ri, km) {
   var wrapAlg = k.wrap;
   if (WRAP_KEK_LENGTHS[wrapAlg.oid] !== kekBytes) throw _fail(); // M29 re-check on the consumer path
   var priv = await subtle.importKey("pkcs8", _normKeyDer(km.key), { name: wcName }, false, ["decapsulateBits"]);
-  var ss = Buffer.from(await subtle.decapsulateBits({ name: wcName }, priv, kemct));
-  var ssKey = await subtle.importKey("raw", ss, { name: "HKDF" }, false, ["deriveBits"]);
-  var kek = Buffer.from(await subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: Buffer.alloc(0), info: _kemOtherInfo(wrapAlg.name, kekBytes, k.ukm || null) }, ssKey, kekBytes * 8));
-  return await _aesKwUnwrap(kek, k.encryptedKey);
+  var ss = null, kek = null, ssAb = null, kekAb = null;
+  try {
+    // The engine hands back an ArrayBuffer it allocated, and the Buffer below is a copy of it. Both
+    // hold the secret, so both are wiped: clearing only the copy this function made would leave the
+    // engine's return value readable, which is the same omission one level up.
+    ssAb = await subtle.decapsulateBits({ name: wcName }, priv, kemct);
+    ss = Buffer.from(ssAb);
+    var ssKey = await subtle.importKey("raw", ss, { name: "HKDF" }, false, ["deriveBits"]);
+    kekAb = await subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: Buffer.alloc(0), info: _kemOtherInfo(wrapAlg.name, kekBytes, k.ukm || null) }, ssKey, kekBytes * 8);
+    kek = Buffer.from(kekAb);
+    return await _aesKwUnwrap(kek, k.encryptedKey);
+  } finally {
+    // NIST SP 800-227 RS5 / sec. 4.2 and RFC 9629 sec. 7: the shared secret and the KEK it derives
+    // are destroyed as soon as they stop being needed. In a `finally`, so an unwrap that FAILS --
+    // the common case under a wrong key or a tampered encryptedKey -- leaves nothing behind either;
+    // a wipe on the success path alone would keep the secret exactly when an attacker made it fail.
+    // Only buffers allocated here are wiped: km.key, the message bytes and the returned CEK are the
+    // caller's or the caller's to consume.
+    // A Uint8Array view aliases the ArrayBuffer's own bytes, so wiping the view wipes the buffer
+    // the engine returned -- no further copy is made in order to destroy one.
+    guard.secret.zeroizeAll([ss, kek, ssAb ? new Uint8Array(ssAb) : null, kekAb ? new Uint8Array(kekAb) : null],
+      CmsError, "cms/bad-input", "the KEM shared secret");
+  }
 }
 
 // The declared cipher MODE must match the container's authentication model: an AEAD cipher belongs in
@@ -410,7 +429,22 @@ async function _aesKwUnwrap(kek, wrapped) {
   // length, so an AuthenticatedData MAC key that is not 16/24/32 octets (e.g. a 64-octet HMAC-SHA-512
   // key from another implementation) is recovered instead of rejected before the MAC is even checked.
   var raw = await subtle.unwrapKey("raw", wrapped, kekKey, { name: "AES-KW" }, { name: "HMAC", hash: "SHA-256" }, true, ["sign"]);
-  return Buffer.from(await subtle.exportKey("raw", raw));
+  // exportKey allocates an ArrayBuffer holding the unwrapped key; the Buffer below is a copy of it,
+  // and the original would otherwise stay readable with nothing referencing it. That is a
+  // controllable allocation, not one of the runtime-internal copies the best-effort caveat covers.
+  // Only the intermediate is wiped -- the returned Buffer IS the key the caller must use to open
+  // the content, so wiping it here would destroy the result rather than protect it.
+  var rawAb = await subtle.exportKey("raw", raw);
+  try {
+    // An explicit COPY, not Buffer.from(arrayBuffer) -- that form returns a VIEW sharing the
+    // ArrayBuffer's memory, so wiping the intermediate below would zero the key being returned.
+    var view = new Uint8Array(rawAb);
+    var out = Buffer.alloc(view.length);
+    out.set(view);
+    return out;
+  } finally {
+    guard.secret.zeroize(new Uint8Array(rawAb), CmsError, "cms/bad-input", "the unwrapped content key");
+  }
 }
 function _eccSharedInfo(wrapName, ukm, kekBytes) {
   var kids = [b.sequence([b.oid(O(wrapName))])];

package/lib/cms-encrypt.js

@@ -275,15 +275,29 @@ async function _buildKemri(cek, cert, opts) {
   var pub = await subtle.importKey("spki", cert.subjectPublicKeyInfo.bytes, { name: wcName }, false, ["encapsulateBits"]);
   var kem = await subtle.encapsulateBits({ name: wcName }, pub);
   var ss = Buffer.from(kem.sharedKey), kemct = Buffer.from(kem.ciphertext);
-  var ssKey = await subtle.importKey("raw", ss, { name: "HKDF" }, false, ["deriveBits"]);
-  var kek = Buffer.from(await subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: Buffer.alloc(0), info: _kemOtherInfo(wrapName, kekBytes, ukm) }, ssKey, kekBytes * 8));
-  var encryptedKey = await _aesKwWrap(kek, cek);
-  var rid = _rid(cert, opts.keyIdentifier);
-  var kemriKids = [b.integer(0n), rid.node, _algId(oid.name(keyOid), "absent"), b.octetString(kemct), _algId("hkdfWithSha256", "absent"), b.integer(BigInt(kekBytes))];
-  if (ukm) kemriKids.push(b.explicit(0, b.octetString(ukm)));
-  kemriKids.push(_algId(wrapName, "absent"), b.octetString(encryptedKey));
-  var kemri = b.sequence(kemriKids);
-  return { tag: 4, node: b.sequence([b.oid(O("kem")), kemri]) };
+  var kek = null, kekAb = null;
+  try {
+    var ssKey = await subtle.importKey("raw", ss, { name: "HKDF" }, false, ["deriveBits"]);
+    kekAb = await subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: Buffer.alloc(0), info: _kemOtherInfo(wrapName, kekBytes, ukm) }, ssKey, kekBytes * 8);
+    kek = Buffer.from(kekAb);
+    var encryptedKey = await _aesKwWrap(kek, cek);
+    var rid = _rid(cert, opts.keyIdentifier);
+    var kemriKids = [b.integer(0n), rid.node, _algId(oid.name(keyOid), "absent"), b.octetString(kemct), _algId("hkdfWithSha256", "absent"), b.integer(BigInt(kekBytes))];
+    if (ukm) kemriKids.push(b.explicit(0, b.octetString(ukm)));
+    kemriKids.push(_algId(wrapName, "absent"), b.octetString(encryptedKey));
+    var kemri = b.sequence(kemriKids);
+    return { tag: 4, node: b.sequence([b.oid(O("kem")), kemri]) };
+  } finally {
+    // RFC 9629 sec. 7 asks the SENDER to discard the shared secret and KEK once the recipient entry
+    // is built -- and to use a fresh secret per recipient, so this runs per call rather than once at
+    // the end of a multi-recipient message. In a `finally`, so a wrap or encoding failure does not
+    // leave them behind. The CEK is the caller's and is wiped by no one here; kemct is public.
+    // kem.sharedKey is the ArrayBuffer the engine returned and ss is this function's copy of it;
+    // both hold the secret, so both are cleared. A Uint8Array view aliases the buffer's bytes, so
+    // wiping the view wipes the buffer itself. kem.ciphertext is public and stays.
+    guard.secret.zeroizeAll([ss, kek, kem.sharedKey ? new Uint8Array(kem.sharedKey) : null, kekAb ? new Uint8Array(kekAb) : null],
+      CmsError, "cms/bad-input", "the KEM shared secret");
+  }
 }
 
 // AES-KW wrap of the CEK under a raw KEK.

package/lib/guard-all.js

@@ -59,6 +59,7 @@ var json   = require("./guard-json");
 var identifier = require("./guard-identifier");
 var header = require("./guard-header");
 var compress = require("./guard-compress");
+var secret = require("./guard-secret");
 
 module.exports = {
   bytes:  bytes,
@@ -73,4 +74,5 @@ module.exports = {
   identifier: identifier,
   header: header,
   compress: compress,
+  secret: secret,
 };

package/lib/guard-secret.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- no operator-facing namespace. The documented surface is the KEM
+// key-establishment paths that compose this guard (pki.cms.encrypt / decrypt).
+//
+// guard-secret -- wipe a secret buffer the TOOLKIT ALLOCATED at the moment it
+// stops being needed. NIST SP 800-227 RS5 / sec. 4.2 requires that a KEM shared
+// secret and every intermediate value be destroyed as soon as they are no longer
+// needed; RFC 9629 sec. 7 says the same of the KEK a KEMRecipientInfo derives.
+//
+// The defended class is secret lifetime, not secret disclosure: a shared secret
+// or KEK left readable in the heap widens the window in which a later memory
+// disclosure -- a core dump, a swapped page, a same-process read primitive --
+// yields key material for traffic that was already decrypted.
+//
+// SCOPE, stated honestly because the docstring is the only place a reader learns
+// it: this is BEST EFFORT. The runtime copies buffers into places no JS can
+// reach (node's decapsulate return is copied on the way out; importKey("raw")
+// copies into a KeyObject), and V8 may relocate a backing store, leaving the
+// original bytes behind. Wiping the copies the toolkit holds shortens the
+// window. It does not support a claim that a secret never persists in memory,
+// and no operator-facing text may imply that it does.
+//
+// OWNERSHIP IS THE CONTRACT. Only a buffer the toolkit allocated may be wiped --
+// never a caller's opts.key / opts.cert / opts.kek / opts.password, and never the
+// input DER. Silently destroying a caller's own memory is a worse defect than
+// leaving a secret readable, and it is the failure mode a zeroization patch
+// reaches for first, so the call sites pass only their own intermediates.
+
+var bytes = require("./guard-bytes");
+
+// zeroize(value, ErrorClass, code, label) -> the same object, cleared.
+//   value      : a Buffer / TypedArray the TOOLKIT allocated, or null / undefined
+//                (absent is a no-op so a `finally` needs no branch around it).
+//   ErrorClass : the caller's typed error CONSTRUCTOR, declared with
+//                `{ withCause: true }`. The guard family carries two currencies --
+//                most guards take a (code, message) factory and call it without
+//                `new`, while guard-bytes / guard-header take the class and
+//                construct it. This module's ONLY throw is the delegated re-view
+//                below, so it must pass what guard-bytes expects: the class, and
+//                one that accepts a cause, because guard-bytes threads the raw
+//                detach fault through as one. A plain class fails to construct at
+//                the single moment the caller needs a real error.
+//   code       : the frozen domain/reason code a detached buffer rejects under.
+//   label      : field phrase for the message.
+//
+// A detached ArrayBuffer cannot be written, and reaching one here means a caller
+// handed over memory that was transferred away -- a real fault, not something to
+// swallow, so it routes through the shared re-view guard and throws typed.
+//
+// The `.fill(0)` shape lives ONLY in this module: a wipe re-inlined anywhere in
+// lib/ -- including a module not yet written -- is flagged, so the safe
+// implementation is also the tripwire that stops the next consumer from rolling
+// its own partial one.
+// @enforced-by guard-shape-reinlined
+// @guard-shape \.fill\s*\(\s*0\s*[,)]
+function zeroize(value, ErrorClass, code, label) {
+  if (value === null || value === undefined) return value;
+  // Re-view through the shared bytes guard: it is the single place that decides
+  // what counts as a writable BufferSource and rejects a detached one typed.
+  var view = bytes.view(value, ErrorClass, code, label);
+  view.fill(0);
+  return value;
+}
+
+// zeroizeAll(list, ErrorClass, code, label) -- wipe every present member, tolerating
+// holes so a `finally` can name intermediates that may not have been reached.
+//
+// @enforced-by behavioral -- this is a loop over zeroize, which carries the family's only
+// rename-proof shape (the `.fill(0)` above). It introduces no shape of its own, so a lexical
+// detector here would anchor on a renameable symbol and go silently green (drift rule sec. 3).
+// The behavioural guards are guard-secret.test.js (holes tolerated, every member cleared) and the
+// CMS vectors that assert the shared secret and KEK are wiped on BOTH the success and failure paths.
+function zeroizeAll(list, ErrorClass, code, label) {
+  if (!list) return list;
+  for (var i = 0; i < list.length; i++) zeroize(list[i], ErrorClass, code, label);
+  return list;
+}
+
+module.exports = { zeroize: zeroize, zeroizeAll: zeroizeAll };

package/lib/lint.js

@@ -628,8 +628,10 @@ var CABF_TLS_RULES = [
 
 // RFC 9935 -- ML-KEM public keys in X.509 certificates. The OID is the sole authority for the
 // parameter set; the SPKI BIT STRING is the raw ek, exactly 384k+32 octets for that OID.
+// Encapsulation-key lengths come from the shared ML-KEM parameter registry (FIPS 203 Table 3),
+// keyed by NAME because an SPKI surfaces its algorithm by name on this path.
 var ML_KEM_EK_LEN = {};
-["id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024"].forEach(function (n, i) { ML_KEM_EK_LEN[n] = [800, 1184, 1568][i]; });
+["id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024"].forEach(function (n) { ML_KEM_EK_LEN[n] = oid.kemParams(n).ek; });
 function _isMlKem(cert) {
   var spki = cert.subjectPublicKeyInfo;
   return !!(spki && spki.algorithm && ML_KEM_EK_LEN[spki.algorithm.name] !== undefined);

package/lib/oid.js

@@ -693,11 +693,46 @@ function paramsMustBeAbsent(dotted) {
   return _PARAMS_ABSENT.has(dotted);
 }
 
+// ---- ML-KEM parameter sets (FIPS 203 Table 3) --------------------------------
+//
+// ONE row per parameter set, resolvable by dotted OID or by registered name, because the
+// consumers hold different currencies: the CMS codec and the decrypt path key by OID, the
+// linter keys by the SPKI algorithm's name. Before this table the same FIPS 203 constants
+// lived in three modules -- schema-cms's ciphertext lengths, webcrypto's {ek, dk}, and
+// lint's encapsulation-key lengths -- so a fourth consumer (a composite KEM, an HPKE row,
+// HQC by analogy) meant a fourth copy, and the ek values were already duplicated verbatim
+// in two of them. A parameter set is a property OF the algorithm identifier, so it lives
+// beside the registry that resolves one rather than in whichever module needed it first.
+//
+//   ek : encapsulation-key octets      dk : decapsulation-key octets
+//   ct : ciphertext octets             ss : shared-secret octets
+// A null-prototype table: a plain object would answer kemParams("toString") with a function
+// inherited from Object.prototype, so the documented fail-closed contract would hold for every
+// input EXCEPT the handful every object already carries -- exactly the ones an untrusted
+// identifier might be.
+var KEM_PARAMS = Object.create(null);
+[["id-ml-kem-512", 800, 1632, 768, 32],
+  ["id-ml-kem-768", 1184, 2400, 1088, 32],
+  ["id-ml-kem-1024", 1568, 3168, 1568, 32]].forEach(function (r) {
+  // FROZEN, because these rows are reachable from the public surface AND one of them now governs a
+  // security check: the engine reads .ct to enforce the FIPS 203 sec. 7.3 ciphertext length. A shared
+  // mutable row would let any code in the process rewrite that bound once, for every later call --
+  // a parameter set is a fact about the algorithm, not a setting an application may retune.
+  var row = Object.freeze({ ek: r[1], dk: r[2], ct: r[3], ss: r[4] });
+  KEM_PARAMS[byName(r[0])] = row;   // by dotted OID
+  KEM_PARAMS[r[0]] = row;           // and by registered name -- the same frozen row
+});
+Object.freeze(KEM_PARAMS);
+// kemParams(oidOrName) -> the row, or undefined for anything that is not an ML-KEM
+// parameter set. Undefined is the caller's signal to fail closed; it never guesses a size.
+function kemParams(oidOrName) { return KEM_PARAMS[oidOrName]; }
+
 module.exports = {
   name:           name,
   byName:         byName,
   has:            has,
   paramsMustBeAbsent: paramsMustBeAbsent,
+  kemParams:      kemParams,
   register:       register,
   registerFamily: registerFamily,
   all:            all,

package/lib/schema-cms.js

@@ -106,10 +106,10 @@ WRAP_KEK_LENGTHS[oid.byName("aes256-wrap")] = 32;
 // ML-KEM OID -> the exact ciphertext (kemct) length in octets (FIPS 203). A
 // recognized ML-KEM kem carries a fixed-size ciphertext; any other length can
 // never decapsulate. (The params-absent rule rides the shared oid registry.)
+// Ciphertext lengths come from the shared ML-KEM parameter registry (FIPS 203 Table 3) rather
+// than a local copy, so this codec and the crypto engine cannot disagree about a parameter set.
 var KEM_CT_LENGTHS = {};
-KEM_CT_LENGTHS[oid.byName("id-ml-kem-512")] = 768;
-KEM_CT_LENGTHS[oid.byName("id-ml-kem-768")] = 1088;
-KEM_CT_LENGTHS[oid.byName("id-ml-kem-1024")] = 1568;
+["id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024"].forEach(function (n) { KEM_CT_LENGTHS[oid.byName(n)] = oid.kemParams(n).ct; });
 
 // Recognized AEAD content-encryption OIDs -> the AES-GCM/CCM parameter shape + the
 // legal ICVlen set (RFC 5084). An unrecognized content-encryption OID surfaces its

package/lib/webcrypto.js

@@ -608,8 +608,16 @@ async function _deriveBitsRaw(alg, key, length) {
   }
   if (name === "HKDF") {
     _requireDeriveLength(length, "HKDF");
-    var derived = nodeCrypto.hkdfSync(_hashNode(alg.hash, "HKDF"), _secretBytes(key), _toBuf(alg.salt, "HKDF salt"), _toBuf(alg.info || Buffer.alloc(0), "HKDF info"), length / 8);
-    return derived instanceof ArrayBuffer ? derived : _toArrayBuffer(Buffer.from(derived));
+    // _secretBytes EXPORTS the key material into a fresh Buffer this module owns -- for a KEM flow
+    // that Buffer is the shared secret itself. It is a controllable allocation, not one of the
+    // runtime-internal copies the best-effort caveat covers, so it is wiped once HKDF has consumed it.
+    var ikm = _secretBytes(key);
+    try {
+      var derived = nodeCrypto.hkdfSync(_hashNode(alg.hash, "HKDF"), ikm, _toBuf(alg.salt, "HKDF salt"), _toBuf(alg.info || Buffer.alloc(0), "HKDF info"), length / 8);
+      return derived instanceof ArrayBuffer ? derived : _toArrayBuffer(Buffer.from(derived));
+    } finally {
+      guard.secret.zeroize(ikm, WebCryptoError, "webcrypto/operation", "the HKDF input key material");
+    }
   }
   if (name === "PBKDF2") {
     _requireDeriveLength(length, "PBKDF2");
@@ -701,7 +709,18 @@ SubtleCrypto.prototype.encapsulateBits = async function encapsulateBits(algorith
   var r;
   try { r = nodeCrypto.encapsulate(encapsulationKey._handle); }
   catch (e) { throw new WebCryptoError("webcrypto/operation", "encapsulateBits: ML-KEM encapsulation failed", e); }
-  return { sharedKey: _toArrayBuffer(Buffer.from(r.sharedKey)), ciphertext: _toArrayBuffer(Buffer.from(r.ciphertext)) };
+  try {
+    // _toArrayBuffer copies via ArrayBuffer.slice, so the shared key is passed straight through --
+    // an intermediate Buffer.from would be another copy of the secret that nothing wipes. The
+    // ciphertext is public and needs no such care, but it is copied the same way for symmetry.
+    return { sharedKey: _toArrayBuffer(r.sharedKey), ciphertext: _toArrayBuffer(r.ciphertext) };
+  } finally {
+    // Encapsulation produces a shared secret exactly as decapsulation does, so it owes the same
+    // duty: the provider's buffer is wiped once the caller's copy exists (NIST SP 800-227 RS5 /
+    // sec. 4.2, RFC 9629 sec. 7). Wiping only the decapsulation side would make the guarantee a
+    // half-truth -- the sender holds the same secret the recipient does.
+    guard.secret.zeroize(r.sharedKey, WebCryptoError, "webcrypto/operation", "the KEM shared secret");
+  }
 };
 
 SubtleCrypto.prototype.decapsulateBits = async function decapsulateBits(algorithm, decapsulationKey, ciphertext) {
@@ -711,10 +730,39 @@ SubtleCrypto.prototype.decapsulateBits = async function decapsulateBits(algorith
   _requireAlgMatch(alg, decapsulationKey, "decapsulateBits");
   if (decapsulationKey.type !== "private") throw new WebCryptoError("webcrypto/invalid-access", "decapsulateBits requires a private (decapsulation) key, got " + JSON.stringify(decapsulationKey.type));
   var ct = _toBuf(ciphertext, "decapsulateBits ciphertext");
+  // FIPS 203 sec. 7.3 makes the ciphertext-length check the ONE per-execution input check a
+  // decapsulating party owes, so it belongs here, at the engine boundary, rather than only in the
+  // format module that happens to call this today: a direct caller -- or a future composite-KEM or
+  // HPKE consumer -- inherits nothing from a check that lives in cms-decrypt. A distinct code names
+  // the real reason, which "the operation failed" cannot.
+  //
+  // Length ONLY. A correct-length ciphertext that has been tampered with must still resolve to a
+  // pseudo-random shared secret (the Fujisaki-Okamoto implicit rejection of FIPS 203 sec. 6.3);
+  // turning that into a throw would hand an attacker a decryption oracle, and it is the property
+  // the CMS uniform verdict is built on.
+  // The registry is keyed by the registered OID name ("id-ml-kem-768"), which is the node
+  // algorithm name this module already maps ("ml-kem-768") under its id- prefix.
+  var kemRow = oid.kemParams("id-" + ML_KEM_NODE[alg.name]);
+  if (kemRow && ct.length !== kemRow.ct) {
+    throw new WebCryptoError("webcrypto/bad-kem-ciphertext",
+      "decapsulateBits: " + alg.name + " expects a " + kemRow.ct + "-octet ciphertext, got " + ct.length + " (FIPS 203 sec. 7.3)");
+  }
   var ss;
   try { ss = nodeCrypto.decapsulate(decapsulationKey._handle, ct); }
   catch (e) { throw new WebCryptoError("webcrypto/operation", "decapsulateBits: ML-KEM decapsulation failed (malformed or wrong-length ciphertext)", e); }
-  return _toArrayBuffer(Buffer.from(ss));
+  try {
+    // ss is already a Buffer, and _toArrayBuffer copies via ArrayBuffer.slice -- so it is passed
+    // straight through. An intermediate Buffer.from(ss) would be a THIRD copy of the secret that
+    // nothing wipes, which would give back most of what the wipe below is for.
+    return _toArrayBuffer(ss);
+  } finally {
+    // The shared secret is returned as a COPY, so the buffer the provider handed back would stay
+    // readable until collection -- and a caller wiping only what it receives would leave the
+    // original behind, which is the whole secret. Wiping here means the engine owns the lifetime of
+    // the buffer it allocated, and every caller (CMS today, a composite KEM or HPKE later) inherits
+    // it rather than each having to remember (NIST SP 800-227 RS5 / sec. 4.2).
+    guard.secret.zeroize(ss, WebCryptoError, "webcrypto/operation", "the KEM shared secret");
+  }
 };
 
 SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey, wrapAlgorithm) {
@@ -731,10 +779,16 @@ SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey
     if (bytes.length < 16 || bytes.length % 8 !== 0) {
       throw new WebCryptoError("webcrypto/operation", "wrapKey: AES-KW requires the serialized key be a multiple of 8 bytes (>= 16); got " + bytes.length + " -- format " + JSON.stringify(format) + " is not AES-KW-wrappable");
     }
+    // The mirror of unwrapKey below: in a KEM flow this export is the SENDER's copy of the same
+    // key-encryption key, so leaving it unwiped would keep a full copy of the KEK alive for the
+    // process lifetime and make the wipes the CMS layer performs pointless in the encrypt direction.
+    var wkBytes = null;
     try {
-      var c = nodeCrypto.createCipheriv("aes" + wrappingKey.algorithm.length + "-wrap", _secretBytes(wrappingKey), Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
+      wkBytes = _secretBytes(wrappingKey);
+      var c = nodeCrypto.createCipheriv("aes" + wrappingKey.algorithm.length + "-wrap", wkBytes, Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
       return _toArrayBuffer(Buffer.concat([c.update(bytes), c.final()]));
     } catch (e) { throw new WebCryptoError("webcrypto/operation", "wrapKey: AES-KW key wrap failed", e); }
+    finally { guard.secret.zeroize(wkBytes, WebCryptoError, "webcrypto/operation", "the AES-KW wrapping key"); }
   }
   // Delegate to a content-encryption algorithm (RSA-OAEP / AES-GCM).
   var wrapKeyClone = _cloneWithUsage(wrappingKey, "encrypt");
@@ -760,10 +814,19 @@ SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey,
     if (wrapped.length < 24 || wrapped.length % 8 !== 0) {
       throw new WebCryptoError("webcrypto/operation", "unwrapKey: AES-KW wrapped key must be a multiple of 8 bytes (>= 24); got " + wrapped.length);
     }
+    // The exported wrapping key is a Buffer this module owns; in a KEM flow it is the KEK derived
+    // from the shared secret, so it is wiped once the unwrap has consumed it -- on the failing path
+    // too, which is the one an attacker induces by tampering with the wrapped key.
+    // Declared outside so the finally can reach it, but EXPORTED INSIDE the try: a key whose handle
+    // cannot be exported must still surface the typed verdict this branch promises, not a raw node
+    // TypeError -- and a non-PkiError throw would also break the fuzz-harness contract.
+    var kwBytes = null;
     try {
-      var d = nodeCrypto.createDecipheriv("aes" + unwrappingKey.algorithm.length + "-wrap", _secretBytes(unwrappingKey), Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
+      kwBytes = _secretBytes(unwrappingKey);
+      var d = nodeCrypto.createDecipheriv("aes" + unwrappingKey.algorithm.length + "-wrap", kwBytes, Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
       bytes = Buffer.concat([d.update(wrapped), d.final()]);
     } catch (e) { throw new WebCryptoError("webcrypto/operation", "unwrapKey: AES-KW key unwrap failed (integrity or length)", e); }
+    finally { guard.secret.zeroize(kwBytes, WebCryptoError, "webcrypto/operation", "the AES-KW unwrapping key"); }
   } else {
     var unwrapKeyClone = _cloneWithUsage(unwrappingKey, "decrypt");
     bytes = Buffer.from(await this.decrypt(unwrapAlgorithm, unwrapKeyClone, wrappedKey));
@@ -783,7 +846,14 @@ SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey,
   } else {
     keyData = bytes;
   }
-  return this.importKey(format, keyData, unwrappedKeyAlgorithm, extractable, keyUsages);
+  try {
+    return await this.importKey(format, keyData, unwrappedKeyAlgorithm, extractable, keyUsages);
+  } finally {
+    // `bytes` is the UNWRAPPED key in plaintext -- a module-owned buffer, and the last plaintext
+    // copy this layer controls once importKey has taken its own. Clearing the caller-visible copy
+    // downstream while leaving this one live would make that wipe ceremonial.
+    guard.secret.zeroize(bytes, WebCryptoError, "webcrypto/operation", "the unwrapped key material");
+  }
 };
 
 function _cloneWithUsage(key, usage) {
@@ -819,10 +889,13 @@ function _nodeKey(fn, who) {
 // RFC 9935 sec. 6 ML-KEM-*-PrivateKey CHOICE: the inner sizes, keyed by the OID -- the OID is
 // the SOLE authority for the parameter set (never a length heuristic). ek = 384k+32, dk = the
 // FIPS 203 decapsulation key length.
+// {ek, dk} come from the shared ML-KEM parameter registry (FIPS 203 Table 3) -- the same rows the
+// CMS codec and the linter read, so a parameter set cannot mean one size here and another there.
 var ML_KEM_INNER = {};
-ML_KEM_INNER[oid.byName("id-ml-kem-512")] = { ek: 800, dk: 1632 };
-ML_KEM_INNER[oid.byName("id-ml-kem-768")] = { ek: 1184, dk: 2400 };
-ML_KEM_INNER[oid.byName("id-ml-kem-1024")] = { ek: 1568, dk: 3168 };
+["id-ml-kem-512", "id-ml-kem-768", "id-ml-kem-1024"].forEach(function (n) {
+  var row = oid.kemParams(n);
+  ML_KEM_INNER[oid.byName(n)] = { ek: row.ek, dk: row.dk };
+});
 
 function _isOctet(node, size) {
   return node && node.tagClass === "universal" && node.tagNumber === asn1.TAGS.OCTET_STRING &&
@@ -1028,9 +1101,16 @@ SubtleCrypto.prototype.exportKey = async function exportKey(format, key) {
   if (!key.extractable) throw new WebCryptoError("webcrypto/invalid-access", "key is not extractable");
   if (format === "jwk") return key._handle.export({ format: "jwk" });
   if (key.type === "secret") {
+    // export() allocates a fresh Buffer holding the secret key, and _toArrayBuffer copies it via
+    // ArrayBuffer.slice -- so the export Buffer is a controllable allocation nothing references once
+    // the copy exists. Wiped in a `finally` so the unsupported-format throw below clears it too.
     var raw = key._handle.export();
-    if (format === "raw") return _toArrayBuffer(raw);
-    throw new WebCryptoError("webcrypto/not-supported", "exportKey: secret keys support 'raw' / 'jwk' only");
+    try {
+      if (format === "raw") return _toArrayBuffer(raw);
+      throw new WebCryptoError("webcrypto/not-supported", "exportKey: secret keys support 'raw' / 'jwk' only");
+    } finally {
+      guard.secret.zeroize(raw, WebCryptoError, "webcrypto/operation", "the exported secret key");
+    }
   }
   if (format === "spki") return _toArrayBuffer(key._handle.export({ format: "der", type: "spki" }));
   if (format === "pkcs8") return _toArrayBuffer(key._handle.export({ format: "der", type: "pkcs8" }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.4.12",
+  "version": "0.4.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:14a71e45-54e7-49bd-8fe1-ac576a769036",
+  "serialNumber": "urn:uuid:47691d4d-f958-4718-adb0-5a945e2dd23e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-10T02:28:13.520Z",
+    "timestamp": "2026-08-10T06:22:53.264Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.4.12",
+      "bom-ref": "@blamejs/pki@0.4.13",
       "type": "application",
       "name": "pki",
-      "version": "0.4.12",
+      "version": "0.4.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.4.12",
+      "purl": "pkg:npm/%40blamejs/pki@0.4.13",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.4.12",
+      "ref": "@blamejs/pki@0.4.13",
       "dependsOn": []
     }
   ]