@blamejs/pki 0.3.13 → 0.3.14

package/CHANGELOG.md

@@ -4,7 +4,16 @@ 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.3.13 — 2026-07-24
+## v0.3.14 — 2026-07-24
+
+CMS AuthenticatedData is produced and verified (RFC 5652 sec. 9).
+
+### Added
+
+- pki.cms.authenticate(content, recipients, opts) produces a CMS AuthenticatedData (RFC 5652 sec. 9): cleartext content authenticated by an HMAC-SHA-256/384/512 MAC, with the fresh MAC key wrapped for each recipient through the same RecipientInfo model pki.cms.encrypt uses (key-transport RSAES-OAEP, key-agreement ECDH/X25519/X448, ML-KEM ori, password pwri, key-wrap kekri). By default it MACs the authenticated attributes (content-type + message-digest of the content) re-tagged to the EXPLICIT SET OF (sec. 9.2); opts.authenticatedAttributes false MACs the content octets directly (id-data only). opts.macAlgorithm selects the HMAC hash and opts.digestAlgorithm the message-digest hash. Returns a DER Buffer or, with opts.pem, a PEM string. RFC 5652 sec. 9, RFC 2104, RFC 4231.
+- pki.cms.decrypt verifies a CMS AuthenticatedData. It recovers the MAC key through the matching RecipientInfo, recomputes the HMAC over the exact RFC 5652 section 9.2 preimage, and -- when authenticated attributes are present -- independently recomputes digest(content) and confirms it equals the message-digest attribute (section 9.3, do not trust the originator's digest), before releasing the content with authenticated true and macAlgorithm / digestAlgorithm in place of contentEncryptionAlgorithm. Every secret-dependent failure -- a wrong recipient key, a forged or tampered MAC, a message-digest mismatch -- collapses to the one uniform cms/decrypt-failed verdict, so a MAC failure is indistinguishable from a key-unwrap failure and leaks no unwrap-success bit. A weak or unknown macAlgorithm (HMAC-SHA-1) is refused with a distinct cms/unsupported-algorithm before any key step.
+
+## v0.3.13 — 2026-07-23
 
 CMS gains countersignatures and unsigned attributes (RFC 5652 sec. 11.4).
 

package/README.md

@@ -230,7 +230,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, 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 and legacy-PBE (PKCS#12 Appendix C) bag decryption are not yet built. 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, 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 or legacy-PBE store is refused, a post-MAC 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. **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`, `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. **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. 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

@@ -44,7 +44,8 @@ async function decrypt(input, keyMaterial, opts) {
   var parsed = _parse(input);
   var ct = parsed.contentTypeName;
   if (ct === "encryptedData") return _decryptEncryptedData(parsed, keyMaterial, opts);
-  if (ct !== "envelopedData" && ct !== "authEnvelopedData") throw _err("cms/bad-input", "input is not an EnvelopedData / AuthEnvelopedData / EncryptedData (got " + ct + ")");
+  if (ct === "authData") return _verifyAuthenticatedData(parsed, keyMaterial, opts);
+  if (ct !== "envelopedData" && ct !== "authEnvelopedData") throw _err("cms/bad-input", "input is not an EnvelopedData / AuthEnvelopedData / EncryptedData / AuthenticatedData (got " + ct + ")");
 
   var recips = parsed.recipientInfos || [];
   var candidates = _selectCandidates(recips, keyMaterial, opts);   // stage 1 (typed, distinct)
@@ -365,8 +366,12 @@ async function _decryptPbes2(parsed, eci, km, opts) {
 // ---- shared helpers (mirror cms-encrypt's builders) ------------------------
 async function _aesKwUnwrap(kek, wrapped) {
   var kekKey = await subtle.importKey("raw", kek, { name: "AES-KW" }, false, ["unwrapKey"]);
-  var cekKey = await subtle.unwrapKey("raw", wrapped, kekKey, { name: "AES-KW" }, { name: "AES-CBC" }, true, ["decrypt"]);
-  return Buffer.from(await subtle.exportKey("raw", cekKey));
+  // Import the unwrapped key as HMAC, not AES-CBC: this function EXPORTS to raw bytes, so the CryptoKey
+  // type is transient and the exported bytes are identical for an AES CEK -- but HMAC accepts any wrap
+  // 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));
 }
 function _eccSharedInfo(wrapName, ukm, kekBytes) {
   var kids = [b.sequence([b.oid(O(wrapName))])];
@@ -475,10 +480,96 @@ function _mlkemName(o) { return MLKEM[o]; }
 function _explicitSetOf(implicitBytes) {
   // The AAD is the authAttrs re-encoded under the EXPLICIT SET OF tag (RFC 5083 sec. 2.2). The
   // parser surfaces authAttrsBytes as the transmitted [1] IMPLICIT form; retag 0xA1 -> 0x31.
+  // AuthenticatedData authAttrs are transmitted [2] IMPLICIT (0xA2); the same out[0]=0x31 handles it.
   var out = Buffer.from(implicitBytes);
   out[0] = 0x31;
   return out;
 }
+
+// ---- AuthenticatedData verification (RFC 5652 sec. 9.3) ---------------------
+// The macAlgorithm OID name -> WebCrypto HMAC hash, and the digestAlgorithm name -> hash (data-driven).
+var MAC_HASH = { hmacWithSHA256: "SHA-256", hmacWithSHA384: "SHA-384", hmacWithSHA512: "SHA-512" };
+var DIGEST_WC = { sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
+// The minimum conveyed MAC-key length (128-bit security floor). A ktri/pwri recipient can wrap a
+// key of any length (unlike AES-KW's 16-octet minimum), so a hostile message could convey a tiny or
+// empty MAC key that weakens the HMAC (or makes subtle.importKey throw); reject it fail-closed.
+var MAC_KEY_MIN_OCTETS = 16;
+function _isDerNull(p) { return Buffer.isBuffer(p) && p.length === 2 && p[0] === 0x05 && p[1] === 0x00; }
+
+// Verify a CMS AuthenticatedData (RFC 5652 sec. 9): recover the MAC key through the SAME RecipientInfo
+// unwrap decrypt uses, recompute the HMAC over the sec. 9.2 preimage (the re-tagged [2] authAttrs SET
+// OF when present, else the eContent value octets), constant-time-compare to the transmitted mac, and
+// -- when authAttrs are present -- INDEPENDENTLY confirm message-digest == digest(content) (sec. 9.3
+// do-not-trust-originator). The content is returned ONLY after every check passes. Every
+// secret-dependent failure collapses to the uniform cms/decrypt-failed (no unwrap-success oracle).
+async function _verifyAuthenticatedData(parsed, km, opts) {
+  var macAlg = parsed.macAlgorithm;
+  var hash = MAC_HASH[macAlg.name];
+  if (!hash) throw _err("cms/unsupported-algorithm", "unsupported macAlgorithm " + JSON.stringify(macAlg.name || macAlg.oid) + " (HMAC-SHA-256/384/512 only)");
+  if (macAlg.parameters != null && !_isDerNull(macAlg.parameters)) throw _err("cms/unsupported-algorithm", "the macAlgorithm parameters must be absent or DER NULL (RFC 3370)");
+  var content = parsed.encapContentInfo.eContent;
+  if (content == null) throw _err("cms/bad-input", "a detached AuthenticatedData (absent eContent) is not supported");
+
+  // Determine the sec. 9.2 preimage + (present mode) the message-digest claim, both structural.
+  var preimage, mdCheck = null;
+  if (parsed.authAttrsBytes) {
+    var dHash = DIGEST_WC[parsed.digestAlgorithm && parsed.digestAlgorithm.name];
+    if (!dHash) throw _err("cms/unsupported-algorithm", "unsupported digestAlgorithm " + JSON.stringify(parsed.digestAlgorithm && parsed.digestAlgorithm.name));
+    preimage = _explicitSetOf(parsed.authAttrsBytes);
+    // The parser already enforced content-type == eContentType (cms/content-type-mismatch) and the
+    // single-valued message-digest attribute; read the claimed digest from the parsed authAttrs (which
+    // decrypt re-parses from the same bytes the MAC covers).
+    var mdAttr = (parsed.authAttrs || []).filter(function (a) { return a.type === O("messageDigest"); })[0];
+    mdCheck = { hash: dHash, declared: asn1.read.octetString(asn1.decode(mdAttr.values[0])) };
+  } else {
+    preimage = Buffer.from(content);
+  }
+
+  var candidates = _selectCandidates(parsed.recipientInfos || [], km, opts);
+  for (var ci = 0; ci < candidates.length; ci++) {
+    try {
+      _assertSupported(candidates[ci].ri, km);
+      var macKey = await _acquireCek(candidates[ci].ri, km, opts);   // recover the MAC key (uniform failure)
+      // RFC 3218 implicit rejection: _ktriCek returns null on an RSA v1.5 unwrap fault, and a hostile
+      // ktri/pwri could convey a below-floor (128-bit) key; in EITHER case substitute a fresh random
+      // key so the MAC verify still RUNS and fails uniformly -- never a fast-path that distinguishes an
+      // invalid/short unwrap from a MAC mismatch (Bleichenbacher / weak-key oracle freedom).
+      if (macKey == null || macKey.length < MAC_KEY_MIN_OCTETS) macKey = nodeCrypto.randomBytes(MAC_KEY_MIN_OCTETS);
+      var key = await subtle.importKey("raw", macKey, { name: "HMAC", hash: hash }, false, ["verify"]);
+      if (!(await subtle.verify({ name: "HMAC" }, key, Buffer.from(parsed.mac), preimage))) throw _fail();
+      if (mdCheck) {
+        var actual = Buffer.from(await subtle.digest(mdCheck.hash, content));
+        if (!actual.equals(mdCheck.declared)) throw _fail();   // sec. 9.3: recompute, never trust the originator's digest
+      }
+      return {
+        content: Buffer.from(content),
+        contentType: parsed.encapContentInfo.eContentType, contentTypeName: oid.name(parsed.encapContentInfo.eContentType) || parsed.encapContentInfo.eContentType,
+        recipientType: candidates[ci].ri.type, recipientIndex: candidates[ci].index,
+        macAlgorithm: macAlg.name || macAlg.oid,
+        digestAlgorithm: parsed.digestAlgorithm ? (parsed.digestAlgorithm.name || parsed.digestAlgorithm.oid) : null,
+        authenticated: true,
+      };
+    } catch (e) {
+      if (candidates.length === 1) throw e;   // one candidate: preserve its exact (distinct or uniform) verdict
+    }
+  }
+  throw _fail();   // every ambiguous candidate failed -> uniform
+}
+// Coverage residual in _verifyAuthenticatedData -- defensive branches reachable only via a hand-built
+// malformed message (the producer never emits them) or unreachable behind an upstream guarantee:
+//   * the macAlgorithm-parameters-not-NULL reject and the unsupported-digestAlgorithm reject fire only
+//     on a hand-crafted message (this producer emits absent params + SHA-2); the behavioral guard is
+//     the frozen cms/unsupported-algorithm code, not a round-trip.
+//   * the detached (absent eContent) reject is the deferred-with-condition path (this producer always
+//     attaches the content); re-open when a detached AuthenticatedData caller appears.
+//   * `parsed.authAttrs || []` / `parsed.recipientInfos || []` -- the parser always surfaces these as
+//     arrays (or rejects), so the `|| []` fallbacks never fire.
+//   * `oid.name(eContentType) || eContentType` fires only for an unregistered content type; `macAlg.name
+//     || macAlg.oid` and `digestAlgorithm.name || .oid` never reach the `.oid` fallback because the
+//     algorithm name was already validated against MAC_HASH / DIGEST_WC above.
+//   * the `macKey == null` half of the random-key substitution fires only for a hand-crafted RSA v1.5
+//     ktri (this producer emits OAEP); its behaviour is identical to the tested below-floor path (a
+//     random key -> the MAC verify fails uniformly), so the < 16 vector covers the substitution.
 function _normKeyDer(key) {
   if (Buffer.isBuffer(key)) return key;
   if (key instanceof Uint8Array) return Buffer.from(key);

package/lib/cms-encrypt.js

@@ -458,4 +458,98 @@ function _tlvHeaderLen(der) {
   return 2 + (lenByte & 0x7f);
 }
 
-module.exports = { encrypt: encrypt };
+// ---- pki.cms.authenticate (RFC 5652 sec. 9 AuthenticatedData) ---------------
+// AuthenticatedData carries CLEARTEXT content plus a MAC (no content encryption). A single fresh HMAC
+// key is minted, wrapped for every recipient with the EXACT RecipientInfo model EnvelopedData uses for
+// the CEK, and the MAC (HMAC-SHA-2) covers either the re-tagged [2] authAttrs SET OF (default) or the
+// eContent value octets directly. Homes here (not a new module) so the recipient-wrap helpers are
+// module-local; the verify half folds into pki.cms.decrypt.
+
+// The macAlgorithm registry: an OID name + the WebCrypto/node hashes (data-driven, not a switch).
+var MAC_ALGS = {
+  "hmac-sha256": { oid: "hmacWithSHA256", wc: "SHA-256", node: "sha256" },
+  "hmac-sha384": { oid: "hmacWithSHA384", wc: "SHA-384", node: "sha384" },
+  "hmac-sha512": { oid: "hmacWithSHA512", wc: "SHA-512", node: "sha512" },
+};
+// The fresh MAC key length: 32 octets is AES-KW-compatible (16/24/32), so it wraps through every
+// recipient arm (kari/kekri/kemri import the wrapped key as AES-CBC) with no codec change, and a
+// 32-octet conveyed key is a valid HMAC key for SHA-256/384/512 (RFC 2104).
+var MAC_KEY_OCTETS = 32;
+// The message-digest hashes the AuthenticatedData verify path (cms-decrypt DIGEST_WC) can consume --
+// the producer never emits a digestAlgorithm its own verifier cannot recompute (the no-orphan rule).
+var SUPPORTED_DIGEST = { sha256: 1, sha384: 1, sha512: 1 };
+
+async function authenticate(content, recipients, opts) {
+  opts = opts || {};
+  var contentBytes = guard.bytes.view(content, CmsError, "cms/bad-input", "content");
+  var macName = opts.macAlgorithm || "hmac-sha256";
+  var mac = MAC_ALGS[macName];
+  if (!mac) throw _err("cms/bad-input", "unsupported macAlgorithm " + JSON.stringify(macName) + " (hmac-sha256/384/512)");
+  if (!Array.isArray(recipients) || !recipients.length) throw _err("cms/bad-input", "at least one recipient is required (RFC 5652 sec. 9.1)");
+  var contentType = opts.contentType || "data";
+  var withAttrs = opts.authenticatedAttributes !== false;
+  // RFC 5652 sec. 9.1: authAttrs MUST be present when the eContentType is not id-data.
+  if (contentType !== "data" && !withAttrs) throw _err("cms/bad-input", "AuthenticatedData with a non-data contentType requires authenticated attributes (RFC 5652 sec. 9.1)");
+
+  var macKey = nodeCrypto.randomBytes(MAC_KEY_OCTETS);
+  var recips = [];
+  for (var i = 0; i < recipients.length; i++) recips.push(await _buildRecipient(macKey, recipients[i], opts));
+  var riNodes = recips.map(_taggedRecipient);
+
+  var digestName = opts.digestAlgorithm || mac.node;
+  var digestAlgTagged = null, authAttrsDer = null, preimage;
+  if (withAttrs) {
+    if (!SUPPORTED_DIGEST[digestName]) throw _err("cms/bad-input", "unsupported digestAlgorithm " + JSON.stringify(digestName) + " (sha256/384/512)");
+    // sec. 9.2: content-type (== eContentType) + message-digest (== digest(content)) attributes,
+    // SET-OF-sorted, MACed under the EXPLICIT SET OF tag (0x31) but transmitted [2] IMPLICIT (0xA2).
+    var mdDigest = nodeCrypto.createHash(digestName).update(contentBytes).digest();
+    var pairs = [
+      b.sequence([b.oid(O("contentType")), b.setOf([b.oid(O(contentType))])]),
+      b.sequence([b.oid(O("messageDigest")), b.setOf([b.octetString(mdDigest)])]),
+    ];
+    if (opts.authAttrs && opts.authAttrs.length) pairs = pairs.concat(opts.authAttrs);
+    // Every authAttr (auto-built or caller-supplied) MUST be a well-formed Attribute SEQUENCE
+    // { type OBJECT IDENTIFIER, values SET OF } and each type appears at most once (RFC 5652) -- so a
+    // malformed or duplicate caller attribute is rejected BEFORE it is MACed and emitted, never left to
+    // fail an operator's parser downstream.
+    var seenTypes = {};
+    pairs.forEach(function (p) {
+      var node;
+      try { node = asn1.decode(p); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute is not well-formed DER", e); }
+      if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children || node.children.length !== 2 ||
+        node.children[1].tagClass !== "universal" || node.children[1].tagNumber !== asn1.TAGS.SET ||
+        !node.children[1].children || node.children[1].children.length < 1) {
+        throw _err("cms/bad-input", "an authenticated attribute must be an Attribute SEQUENCE { type, non-empty SET OF value } (RFC 5652)");
+      }
+      var t;
+      try { t = asn1.read.oid(node.children[0]); } catch (e) { throw _err("cms/bad-input", "an authenticated attribute type is not an OBJECT IDENTIFIER", e); }
+      if (seenTypes[t]) throw _err("cms/bad-input", "authenticated attributes must not repeat an attribute type (RFC 5652): " + t);
+      seenTypes[t] = 1;
+    });
+    var setOf = b.setOf(pairs);
+    preimage = setOf;                                                            // MAC over the 0x31 SET OF
+    authAttrsDer = b.contextConstructed(2, setOf.subarray(_tlvHeaderLen(setOf)));   // [2] IMPLICIT on the wire
+    digestAlgTagged = b.contextConstructed(1, b.oid(O(digestName)));             // [1] IMPLICIT DigestAlgorithmIdentifier
+  } else {
+    preimage = contentBytes;                                                    // MAC over the eContent value octets
+  }
+
+  var hmacKey = await subtle.importKey("raw", macKey, { name: "HMAC", hash: mac.wc }, false, ["sign"]);
+  var macValue = Buffer.from(await subtle.sign({ name: "HMAC" }, hmacKey, preimage));
+
+  var eci = b.sequence([b.oid(O(contentType)), b.explicit(0, b.octetString(contentBytes))]);
+  var kids = [b.integer(0n), b.setOf(riNodes), _algId(mac.oid)];
+  if (digestAlgTagged) kids.push(digestAlgTagged);
+  kids.push(eci);
+  if (authAttrsDer) kids.push(authAttrsDer);
+  kids.push(b.octetString(macValue));
+  var ci = b.sequence([b.oid(O("authData")), b.explicit(0, b.sequence(kids))]);
+  // Self-verify: the emitted AuthenticatedData MUST re-parse clean through the strict parser, so a
+  // caller-supplied authenticated attribute with a recognized type but extra RFC 5652 constraints (a
+  // misplaced type, a signing-time whose value is not a Time) is rejected HERE at build time rather
+  // than by the recipient's parser after the fact.
+  try { schemaCms.parse(ci); } catch (e) { throw (e instanceof CmsError) ? e : _err("cms/bad-input", "the supplied authenticated attributes produced an invalid AuthenticatedData", e); }
+  return opts.pem ? schemaCms.pemEncode(ci, "CMS") : ci;
+}
+
+module.exports = { encrypt: encrypt, authenticate: authenticate };

package/lib/cms-verify.js

@@ -770,25 +770,66 @@ var countersign = cmsSign.countersign;
  */
 var encrypt = cmsEncrypt.encrypt;
 
+/**
+ * @primitive pki.cms.authenticate
+ * @signature pki.cms.authenticate(content, recipients, opts?) -> Promise<Buffer | string>
+ * @since 0.3.14
+ * @status experimental
+ * @spec RFC 5652, RFC 2104, RFC 4231, RFC 3370
+ * @related pki.cms.decrypt, pki.schema.cms.parse
+ *
+ * Produce a CMS AuthenticatedData (RFC 5652 sec. 9): CLEARTEXT content plus a MAC (HMAC-SHA-2) --
+ * authenticated but NOT encrypted, the authenticated-only sibling of AuthEnvelopedData. A single
+ * fresh MAC key is minted and wrapped for every recipient with the SAME RecipientInfo model
+ * `pki.cms.encrypt` uses for a content-encryption key, so `recipients` is the identical array of
+ * descriptors: `{ cert }` (RSA -> ktri RSAES-OAEP, EC/X25519/X448 -> kari, ML-KEM -> ori/KEMRI),
+ * `{ password }` (pwri), or `{ kek, kekId }` (kekri). By default the MAC covers the authenticated
+ * attributes (a content-type and a message-digest = digest of the content) re-tagged to the EXPLICIT
+ * SET OF (RFC 5652 sec. 9.2); with `authenticatedAttributes: false` (id-data content only) it covers
+ * the content octets directly. `pki.cms.decrypt` recovers the MAC key, recomputes the MAC, and --
+ * with authenticated attributes -- independently confirms the message-digest before releasing the
+ * content, returning `authenticated: true`. Malformed input throws a typed `CmsError`.
+ *
+ * @opts macAlgorithm `"hmac-sha256"` (default) / `"hmac-sha384"` / `"hmac-sha512"`.
+ * @opts digestAlgorithm The authenticated-attributes message-digest hash (defaults to the MAC hash).
+ * @opts authenticatedAttributes Include the content-type + message-digest authenticated attributes
+ *                          (the default, and required for a non-`data` content type); false MACs the
+ *                          content directly.
+ * @opts authAttrs Extra authenticated attributes appended to the content-type + message-digest pair.
+ * @opts contentType The encapsulated content type (an OID name). Default `data`.
+ * @opts keyIdentifier `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
+ * @opts pem Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
+ * @example
+ *   var r = pki.cms; // authenticate a message to an RSA recipient, then verify via decrypt
+ *   var auth = await r.authenticate(Buffer.from("hi"), [{ cert: recipientCertDer }]);
+ *   var out = await r.decrypt(auth, { key: recipientKeyPkcs8, cert: recipientCertDer });
+ *   out.authenticated;   // true
+ */
+var authenticate = cmsEncrypt.authenticate;
+
 /**
  * @primitive pki.cms.decrypt
  * @signature pki.cms.decrypt(input, keyMaterial, opts?) -> Promise<{ content, contentType, contentTypeName, recipientType, recipientIndex, contentEncryptionAlgorithm, authenticated }>
  * @since 0.2.23
  * @status experimental
- * @spec RFC 5652, RFC 5083, RFC 5084, RFC 3560, RFC 5753, RFC 8418, RFC 9629, RFC 9936, RFC 3211, RFC 8018, RFC 3218
- * @related pki.cms.encrypt, pki.schema.cms.parse
+ * @spec RFC 5652, RFC 5083, RFC 5084, RFC 3560, RFC 5753, RFC 8418, RFC 9629, RFC 9936, RFC 3211, RFC 8018, RFC 3218, RFC 2104
+ * @related pki.cms.encrypt, pki.cms.authenticate, pki.schema.cms.parse
  *
- * Decrypt a CMS EnvelopedData / AuthEnvelopedData / EncryptedData (DER Buffer or PEM). It selects
- * the recipient the key material targets, acquires the content-encryption key through the matching
- * arm (ktri OAEP or PKCS#1 v1.5 decrypt-only; kari ECDH / X25519 / X448; kekri; pwri; ori/ML-KEM),
- * and decrypts + authenticates the content. `keyMaterial` is `{ key, cert }` (the recipient
- * private key + its certificate, which drives recipient matching), `{ password }`, `{ kek, kekId? }`,
- * or `{ cek }` (EncryptedData raw-key mode). Fail-closed and oracle-free: every secret-dependent
- * failure -- a bad key-wrap, a padding fault, a GCM tag mismatch, a PWRI check-byte mismatch --
- * collapses to the SINGLE uniform `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL oracle
- * freedom), and the PKCS#1 v1.5 arm applies the RFC 3218 implicit-rejection countermeasure so its
- * failure is indistinguishable. `authenticated` is true only for AuthEnvelopedData; a CBC
- * EnvelopedData surfaces `authenticated: false` (the EFAIL caveat in the verdict itself).
+ * Decrypt a CMS EnvelopedData / AuthEnvelopedData / EncryptedData, or verify a CMS AuthenticatedData
+ * (DER Buffer or PEM). It selects the recipient the key material targets, acquires the
+ * content-encryption or MAC key through the matching arm (ktri OAEP or PKCS#1 v1.5 decrypt-only; kari
+ * ECDH / X25519 / X448; kekri; pwri; ori/ML-KEM), and decrypts (or MAC-verifies) the content.
+ * `keyMaterial` is `{ key, cert }` (the recipient private key + its certificate, which drives recipient
+ * matching), `{ password }`, `{ kek, kekId? }`, or `{ cek }` (EncryptedData raw-key mode). Fail-closed
+ * and oracle-free: every secret-dependent failure -- a bad key-wrap, a padding fault, a GCM tag
+ * mismatch, a PWRI check-byte mismatch, an AuthenticatedData MAC/message-digest mismatch -- collapses
+ * to the SINGLE uniform `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL oracle freedom, and no
+ * unwrap-success bit for the MAC path), and the PKCS#1 v1.5 arm applies the RFC 3218 implicit-rejection
+ * countermeasure so its failure is indistinguishable. For an AuthenticatedData the MAC (HMAC-SHA-2)
+ * and, when authenticated attributes are present, the message-digest are verified before the content
+ * is released, and the result carries `macAlgorithm` / `digestAlgorithm` in place of
+ * `contentEncryptionAlgorithm`. `authenticated` is true for AuthEnvelopedData and AuthenticatedData; a
+ * CBC EnvelopedData surfaces `authenticated: false` (the EFAIL caveat in the verdict itself).
  *
  * @opts recipientIndex Explicitly select the recipient by index (overrides key-material matching).
  * @opts maxIterations  Lower the PBKDF2 iteration cap (a DoS bound; downward only).
@@ -845,4 +886,4 @@ var compress = cmsCompress.compress;
  */
 var decompress = cmsCompress.decompress;
 
-module.exports = { verify: verify, sign: sign, countersign: countersign, encrypt: encrypt, decrypt: decrypt, compress: compress, decompress: decompress };
+module.exports = { verify: verify, sign: sign, countersign: countersign, encrypt: encrypt, authenticate: authenticate, decrypt: decrypt, compress: compress, decompress: decompress };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.13",
+  "version": "0.3.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:ddc37e54-2fea-49ec-a673-31366e0c6424",
+  "serialNumber": "urn:uuid:7db025af-2d42-4d80-9d99-9e6ec17cd13f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-24T03:47:36.459Z",
+    "timestamp": "2026-07-24T06:23:40.600Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.13",
+      "bom-ref": "@blamejs/pki@0.3.14",
       "type": "application",
       "name": "pki",
-      "version": "0.3.13",
+      "version": "0.3.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.3.13",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.14",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.13",
+      "ref": "@blamejs/pki@0.3.14",
       "dependsOn": []
     }
   ]