@blamejs/pki 0.3.12 → 0.3.14

package/CHANGELOG.md

@@ -4,7 +4,26 @@ 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.12 — 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).
+
+### Added
+
+- pki.cms.countersign(cms, signers, opts) adds RFC 5652 section 11.4 countersignatures to a CMS SignedData. Each countersigner is the same { cert, key, digestAlgorithm?, pss? } descriptor pki.cms.sign takes (RSA, RSASSA-PSS, ECDSA, EdDSA, ML-DSA, SLH-DSA, or composite ML-DSA), and its signature covers the countersigned SignerInfo's signature octets under the section 11.4 preimage -- message-digest bound to those octets, content-type omitted. opts.signerIndex selects which primary signer(s) to countersign (an index, an array, or 'all'), opts.countersignatureOf countersigns an existing countersignature (a nested countersignature), opts.signedAttributes false signs the target signature directly, and the countersigner certificate is embedded by default. The countersigned SignedData's original bytes are preserved so the primary signature verifies unchanged, and multiple countersignatures on one signer land as multiple values of the one id-countersignature attribute. Returns a DER Buffer or, with opts.pem, a PEM string. RFC 5652 sec. 11.4.
+- pki.cms.verify surfaces countersignatures and unsigned attributes per signer. Each res.signers[i] carries countersignatures -- an array of per-countersignature verdicts { ok, sid, cert, digestAlgorithm, ... }, each verified over the exact RFC 5652 section 11.4 preimage, nested for a countersignature of a countersignature -- and unsignedAttrs, the decoded unsigned attributes with their type names. Both are unauthenticated by definition (an unsigned attribute is outside the signature) and never change signers[i].ok or res.valid; a present-but-invalid countersignature is surfaced ok:false, never silently dropped.
+- pki.cms.sign gains an unsignedAttributes option: an array of { type, values } unsigned attributes placed in each SignerInfo, outside the signature. It is the vehicle for attaching an RFC 3161 timestamp token (id-aa-timeStampToken) or another unsigned attribute at signing time. content-type, message-digest, and signing-time are rejected as unsigned attributes (RFC 5652 sec. 11), as is a duplicate attribute type.
+
+## v0.3.12 — 2026-07-23
 
 pki.pkcs12.open reads and decrypts a password-integrity PKCS#12 store (RFC 7292, RFC 9579).
 

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`. **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`, `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-sign.js

@@ -23,6 +23,7 @@ var frameworkError = require("./framework-error");
 var signScheme = require("./sign-scheme");
 var guard = require("./guard-all");
 var pkiBuild = require("./pki-build");
+var cms = require("./schema-cms");
 var CmsError = frameworkError.CmsError;
 var b = asn1.build;
 function _err(code, message, cause) { return new CmsError(code, message, cause); }
@@ -57,6 +58,73 @@ function _skiValue(cert) {
 }
 
 
+// The SignerInfo SignerIdentifier + its coupled CMSVersion (RFC 5652 sec. 5.3): a [0] IMPLICIT
+// subjectKeyIdentifier => version 3, else an IssuerAndSerialNumber => version 1. Shared by the
+// top-level signer and the sec. 11.4 countersignature (a countersignature IS a SignerInfo).
+function _buildSid(cert, useSki) {
+  var sid = useSki
+    ? b.contextPrimitive(0, _skiValue(cert))                                       // [0] IMPLICIT SubjectKeyIdentifier
+    : b.sequence([b.raw(pkiBuild.tbsNameField(cert, "issuer")), b.integer(cert.serialNumber)]);   // IssuerAndSerialNumber
+  return { sid: sid, version: useSki ? 3 : 1 };
+}
+
+// Assemble a SignedAttributes SET from resolved attribute pairs (each { type: <dotted OID>, values:
+// [<build node or DER Buffer>] }), returning { setOf, wire }: `setOf` is the canonical DER SET OF
+// (tag 0x31, build.set SET-OF-sorts) the signature covers (RFC 5652 sec. 5.4); `wire` is the same
+// bytes with the on-wire [0] IMPLICIT tag (0xA0). Each attribute type appears AT MOST ONCE (sec.
+// 5.3) -- a duplicate throws. Shared by the top-level signer (content-type + message-digest +
+// signing-time + caller attrs) and the countersignature builder (message-digest over the target
+// signature octets + signing-time, content-type OMITTED per sec. 11.4).
+function _buildSignedAttrs(pairs) {
+  var seenTypes = {};
+  var attrs = pairs.map(function (p) {
+    if (seenTypes[p.type]) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
+    seenTypes[p.type] = 1;
+    return b.sequence([b.oid(p.type), b.set(p.values)]);
+  });
+  var setOf = b.set(attrs);   // SET OF (tag 0x31) -- the exact bytes the signature covers (sec. 5.4)
+  var wire = Buffer.from(setOf); wire[0] = 0xA0;   // the on-wire [0] IMPLICIT tag
+  return { setOf: setOf, wire: wire };
+}
+
+// Resolve caller-supplied additional signed attributes ({ type: OID name or dotted, values: [DER] })
+// into the pair shape _buildSignedAttrs consumes; each MUST carry >= 1 value (Attribute values is
+// SET SIZE (1..MAX)).
+function _resolveAttrPairs(list, what) {
+  return (list || []).map(function (a) {
+    var vals = (a.values || []).map(function (v) { return _toBuf(v, what); });
+    if (!vals.length) throw _err("cms/bad-input", "a signed attribute must carry at least one value (RFC 5652 -- Attribute values is SET SIZE (1..MAX))");
+    return { type: /^\d+(\.\d+)+$/.test(a.type) ? a.type : O(a.type), values: vals };
+  });
+}
+
+// content-type / message-digest / signing-time are content-binding SIGNED attributes and MUST NOT
+// appear as unsigned attributes (RFC 5652 sec. 11.1/11.2/11.3 -- the parser's ATTR_FORBIDDEN_IN).
+var UNSIGNED_FORBIDDEN = {};
+UNSIGNED_FORBIDDEN[O("contentType")] = "content-type";
+UNSIGNED_FORBIDDEN[O("messageDigest")] = "message-digest";
+UNSIGNED_FORBIDDEN[O("signingTime")] = "signing-time";
+
+// Build the [1] IMPLICIT unsignedAttrs SET OF (on-wire tag 0xA1) from opts.unsignedAttributes
+// (each { type, values: [DER] } -- a countersignature, an RFC 3161 timestamp token), or null when
+// absent/empty. Unsigned attributes are OUTSIDE the signature; a placement-forbidden type or a
+// duplicate type (RFC 5652 sec. 11 / sec. 5.3) is a config-time cms/bad-input.
+function _buildUnsignedAttrs(list) {
+  if (list == null) return null;
+  if (!Array.isArray(list)) throw _err("cms/bad-input", "opts.unsignedAttributes must be an array of { type, values }");
+  if (!list.length) return null;
+  var pairs = _resolveAttrPairs(list, "an unsigned attribute value");
+  var seen = {};
+  pairs.forEach(function (p) {
+    if (UNSIGNED_FORBIDDEN[p.type]) throw _err("cms/bad-input", "the " + UNSIGNED_FORBIDDEN[p.type] + " attribute must not appear as an unsigned attribute (RFC 5652 sec. 11)");
+    if (seen[p.type]) throw _err("cms/bad-input", "unsignedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + p.type);
+    seen[p.type] = 1;
+  });
+  var setOf = b.set(pairs.map(function (p) { return b.sequence([b.oid(p.type), b.set(p.values)]); }));
+  var wire = Buffer.from(setOf); wire[0] = 0xA1;   // SET OF -> [1] IMPLICIT UnsignedAttributes
+  return wire;
+}
+
 // Build one SignerInfo (RFC 5652 sec. 5.3) and sign it. Resolves the SignerInfo (as a build
 // node) plus its digestAlgorithm AlgorithmIdentifier and the signer certificate DER (for the
 // SignedData digestAlgorithms + certificates sets).
@@ -65,44 +133,28 @@ function _buildSignerInfo(signer, content, eContentType, opts) {
   var certDer = _normCertDer(so.cert);
   var cert = x509.parse(certDer);
   var scheme = signScheme.resolveSignScheme(cert, so, opts.signedAttributes === false, _signE);
-  var useSki = opts.sid === "ski";
-  var sid = useSki
-    ? b.contextPrimitive(0, _skiValue(cert))                                       // [0] IMPLICIT SubjectKeyIdentifier
-    : b.sequence([b.raw(pkiBuild.tbsNameField(cert, "issuer")), b.integer(cert.serialNumber)]);   // IssuerAndSerialNumber
-  var version = useSki ? 3 : 1;
+  var sidv = _buildSid(cert, opts.sid === "ski");
+  var sid = sidv.sid, version = sidv.version;
 
   return Promise.resolve().then(function () {
     if (opts.signedAttributes === false) return content;   // sign the content directly (no signed attributes)
     // Signed attributes (RFC 5652 sec. 5.3): content-type == eContentType, message-digest ==
-    // digest(content), and (by default) signing-time. build.set canonical-DER SET-OF-sorts them.
-    // Each attribute type appears AT MOST ONCE across the whole set (RFC 5652 sec. 5.3);
-    // `seenTypes` catches a caller-supplied attribute that duplicates a built-in or another.
-    var seenTypes = {};
-    function _pushAttr(typeOid, values) {
-      if (seenTypes[typeOid]) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + typeOid);
-      seenTypes[typeOid] = 1;
-      attrs.push(b.sequence([b.oid(typeOid), b.set(values)]));
-    }
-    var attrs = [];
-    _pushAttr(O("contentType"), [b.oid(eContentType)]);
-    _pushAttr(O("messageDigest"), [b.octetString(_digest(scheme.digest, content))]);
-    if (opts.signingTime !== false) _pushAttr(O("signingTime"), [_timeValue(opts.signingTime)]);
-    // Caller-supplied signed attributes (e.g. an RFC 3161 signing-certificate attribute): each
-    // { type: <OID name or dotted string>, values: [<DER value Buffer>] }. build.set sorts them in.
-    (opts.additionalSignedAttributes || []).forEach(function (a) {
-      var vals = (a.values || []).map(function (v) { return _toBuf(v, "a signed attribute value"); });
-      if (!vals.length) throw _err("cms/bad-input", "a signed attribute must carry at least one value (RFC 5652 -- Attribute values is SET SIZE (1..MAX))");
-      _pushAttr(/^\d+(\.\d+)+$/.test(a.type) ? a.type : O(a.type), vals);
-    });
-    var setOf = b.set(attrs);   // SET OF (tag 0x31) -- the exact bytes the signature covers (sec. 5.4)
-    var wire = Buffer.from(setOf); wire[0] = 0xA0;   // the on-wire [0] IMPLICIT tag
-    return { setOf: setOf, wire: wire };
+    // digest(content), and (by default) signing-time, plus any caller-supplied attribute.
+    var pairs = [
+      { type: O("contentType"), values: [b.oid(eContentType)] },
+      { type: O("messageDigest"), values: [b.octetString(_digest(scheme.digest, content))] },
+    ];
+    if (opts.signingTime !== false) pairs.push({ type: O("signingTime"), values: [_timeValue(opts.signingTime)] });
+    pairs = pairs.concat(_resolveAttrPairs(opts.additionalSignedAttributes, "a signed attribute value"));
+    return _buildSignedAttrs(pairs);
   }).then(function (toSign) {
     var signedBytes = toSign.setOf ? toSign.setOf : toSign;   // SET-OF form for signing (sec. 5.4)
     return signScheme.signOverTbs(scheme, so.key, signedBytes, _signE).then(function (sig) {
       var fields = [b.integer(BigInt(version)), sid, scheme.digestAlgId];
       if (toSign.wire) fields.push(toSign.wire);              // [0] IMPLICIT signedAttrs
       fields.push(scheme.sigAlgId, b.octetString(sig));
+      var ua = _buildUnsignedAttrs(opts.unsignedAttributes);
+      if (ua) fields.push(ua);                                 // [1] IMPLICIT unsignedAttrs
       return { si: b.sequence(fields), digestAlgId: scheme.digestAlgId, version: version, certDer: certDer };
     });
   });
@@ -191,6 +243,179 @@ function _toBuf(v, what) {
   throw _err("cms/bad-input", what + " must be a Buffer");
 }
 
+// ---- pki.cms.countersign (RFC 5652 sec. 11.4) ------------------------------
+// A countersignature is a SignerInfo (Countersignature ::= SignerInfo) over the CONTENTS of the
+// countersigned SignerInfo's signature OCTET STRING -- NOT the eContent -- attached as the
+// id-countersignature unsigned attribute. It reuses the whole build+sign flow (resolveSignScheme /
+// _buildSid / _buildSignedAttrs / signOverTbs); only the preimage (the target signature octets) and
+// the content-type OMISSION are the deltas, and the orchestrator splices the [1] unsignedAttrs into
+// an existing SignedData while preserving the targeted SignerInfo's signed bytes BYTE-FOR-BYTE.
+
+// Resolve opts.signerIndex (a number, an array of numbers, or "all"; default 0) to primary indices.
+function _resolveSignerIndices(spec, n) {
+  if (spec == null) { if (n < 1) throw _err("cms/bad-input", "the SignedData carries no SignerInfo to countersign"); return [0]; }
+  if (spec === "all") { var all = []; for (var i = 0; i < n; i++) all.push(i); return all; }
+  var arr = Array.isArray(spec) ? spec : [spec];
+  if (!arr.length) throw _err("cms/bad-input", "signerIndex must select at least one signer");
+  arr.forEach(function (i) { if (typeof i !== "number" || !Number.isInteger(i) || i < 0 || i >= n) throw _err("cms/bad-input", "signerIndex out of range: " + i); });
+  return arr;
+}
+
+// Build one countersignature value (RFC 5652 sec. 11.4) over `targetSigOctets`: message-digest bound
+// to digest(targetSigOctets) under the countersignature's own digestAlgorithm, content-type OMITTED,
+// signed through the SAME per-algorithm scheme machinery as a top-level signer.
+function _buildCountersignature(targetSigOctets, countersigner, opts) {
+  var so = countersigner || {};
+  var certDer = _normCertDer(so.cert);
+  var cert = x509.parse(certDer);
+  var scheme = signScheme.resolveSignScheme(cert, so, opts.signedAttributes === false, _signE);
+  var sidv = _buildSid(cert, opts.sid === "ski");
+  return Promise.resolve().then(function () {
+    if (opts.signedAttributes === false) return null;   // sign the target signature octets directly
+    var pairs = [{ type: O("messageDigest"), values: [b.octetString(_digest(scheme.digest, targetSigOctets))] }];
+    if (opts.signingTime !== false) pairs.push({ type: O("signingTime"), values: [_timeValue(opts.signingTime)] });
+    var extra = _resolveAttrPairs(opts.additionalSignedAttributes, "a countersignature signed attribute value");
+    extra.forEach(function (p) { if (p.type === O("contentType")) throw _err("cms/bad-input", "a countersignature must not carry a content-type attribute (RFC 5652 sec. 11.4)"); });
+    return _buildSignedAttrs(pairs.concat(extra));
+  }).then(function (attrs) {
+    return signScheme.signOverTbs(scheme, so.key, attrs ? attrs.setOf : targetSigOctets, _signE).then(function (sig) {
+      var fields = [b.integer(BigInt(sidv.version)), sidv.sid, scheme.digestAlgId];
+      if (attrs) fields.push(attrs.wire);          // [0] IMPLICIT signedAttrs
+      fields.push(scheme.sigAlgId, b.octetString(sig));
+      return { value: b.sequence(fields), certDer: certDer };
+    });
+  });
+}
+
+// Build the [1] IMPLICIT unsignedAttrs bytes for a SignerInfo, merging `newCsValues` into the ONE
+// id-countersignature attribute (RFC 5652 sec. 11: single instance per type, MULTIPLE values), and
+// keeping every OTHER unsigned attribute and every EXISTING countersignature value verbatim.
+function _mergeCountersig(uaNode, newCsValues) {
+  var CS = O("countersignature");
+  var others = [], csValues = [];
+  if (uaNode) uaNode.children.forEach(function (attr) {
+    if (asn1.read.oid(attr.children[0]) === CS) attr.children[1].children.forEach(function (v) { csValues.push(v.bytes); });
+    else others.push(attr.bytes);
+  });
+  newCsValues.forEach(function (v) { csValues.push(v); });
+  var csAttr = b.sequence([b.oid(CS), b.set(csValues)]);
+  var setOf = b.set(others.concat([csAttr]));
+  var wire = Buffer.from(setOf); wire[0] = 0xA1;   // SET OF -> [1] IMPLICIT UnsignedAttributes
+  return wire;
+}
+
+// Append countersignature values to a SignerInfo node, preserving version / sid / digestAlgorithm /
+// signedAttrs / signatureAlgorithm / signature BYTE-FOR-BYTE (the signed preimage), only adding the
+// [1] unsignedAttrs. Returns the new SignerInfo bytes.
+function _appendCountersigs(siNode, newCsValues) {
+  var kids = siNode.children;
+  var last = kids[kids.length - 1];
+  var hasUa = last.tagClass === "context" && last.tagNumber === 1;
+  var base = (hasUa ? kids.slice(0, kids.length - 1) : kids).map(function (k) { return k.bytes; });
+  base.push(_mergeCountersig(hasUa ? last : null, newCsValues));
+  return b.sequence(base);
+}
+
+// Splice countersignature values into the j-th countersignature VALUE of a SignerInfo node (nested
+// countersignature, RFC 5652 sec. 11.4). Returns the new SignerInfo bytes.
+function _spliceNested(siNode, j, newCsValues) {
+  var kids = siNode.children;
+  var last = kids[kids.length - 1];
+  var CS = O("countersignature");
+  if (!last || last.tagClass !== "context" || last.tagNumber !== 1) throw _err("cms/bad-input", "the target signer carries no countersignature to countersign");
+  var found = false;
+  var attrs = last.children.map(function (attr) {
+    if (asn1.read.oid(attr.children[0]) !== CS) return attr.bytes;
+    var values = attr.children[1].children;
+    if (j < 0 || j >= values.length) throw _err("cms/bad-input", "countersignatureOf out of range: " + j);
+    found = true;
+    return b.sequence([b.oid(CS), b.set(values.map(function (v, vi) { return vi === j ? _appendCountersigs(v, newCsValues) : v.bytes; }))]);
+  });
+  if (!found) throw _err("cms/bad-input", "the target signer carries no countersignature to countersign");
+  var setOf = b.set(attrs); var wire = Buffer.from(setOf); wire[0] = 0xA1;
+  var base = kids.slice(0, kids.length - 1).map(function (k) { return k.bytes; });
+  base.push(wire);
+  return b.sequence(base);
+}
+
+// The signature-value octets of a SignerInfo node: the last universal OCTET STRING, i.e. the last
+// child unless a [1] IMPLICIT unsignedAttrs (a prior countersignature) follows it.
+function _signatureOctets(siNode) {
+  var kids = siNode.children;
+  var last = kids[kids.length - 1];
+  var sigNode = (last.tagClass === "context" && last.tagNumber === 1) ? kids[kids.length - 2] : last;
+  return asn1.read.octetString(sigNode);
+}
+
+// The sec. 11.4 preimage for a target: the primary SignerInfo's signature octets, or (nested) the
+// j-th countersignature value's signature octets.
+function _targetPreimage(siNode, opts) {
+  if (opts.countersignatureOf == null) return _signatureOctets(siNode);
+  var last = siNode.children[siNode.children.length - 1];
+  var CS = O("countersignature");
+  if (!last || last.tagClass !== "context" || last.tagNumber !== 1) throw _err("cms/bad-input", "the target signer carries no countersignature to countersign");
+  var attr = last.children.filter(function (a) { return asn1.read.oid(a.children[0]) === CS; })[0];
+  if (!attr) throw _err("cms/bad-input", "the target signer carries no countersignature to countersign");
+  var values = attr.children[1].children;
+  var j = opts.countersignatureOf;
+  if (typeof j !== "number" || !Number.isInteger(j) || j < 0 || j >= values.length) throw _err("cms/bad-input", "countersignatureOf out of range: " + j);
+  return _signatureOctets(values[j]);
+}
+
+// pki.cms.countersign -- documented by the @primitive block in cms-verify.js (the @module pki.cms home).
+function countersign(cmsInput, signers, opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.countersign options must be an object");
+  var list = Array.isArray(signers) ? signers : [signers];
+  if (!list.length) throw _err("cms/bad-input", "pki.cms.countersign requires at least one countersigner");
+  if (opts.signingTime != null && opts.signingTime !== false) guard.time.assertValid(opts.signingTime, _err, "cms/bad-input", "signingTime");
+  var der = pkix.coerceToDer(cmsInput, { pemLabel: null, PemError: frameworkError.PemError, ErrorClass: CmsError, prefix: "cms" });
+  // cms.parse throws a typed cms/* error on a malformed input (mirroring verify's own parse call); a
+  // structurally-valid but non-SignedData CMS (an EnvelopedData) parses without a signerInfos array.
+  var parsed = cms.parse(der);
+  if (!Array.isArray(parsed.signerInfos)) throw _err("cms/bad-input", "pki.cms.countersign input is not a CMS SignedData");
+  var targets = _resolveSignerIndices(opts.signerIndex, parsed.signerInfos.length);
+  var root = asn1.decode(der);
+  var sd = root.children[1].children[0];
+  var sdKids = sd.children;
+  var siSet = sdKids[sdKids.length - 1];
+
+  // Build every countersignature value (target x countersigner), then splice into the node tree.
+  var jobs = [];
+  targets.forEach(function (t) {
+    var preimage = _targetPreimage(siSet.children[t], opts);
+    list.forEach(function (cs) { jobs.push({ t: t, p: _buildCountersignature(preimage, cs, opts) }); });
+  });
+  return Promise.all(jobs.map(function (j) { return j.p; })).then(function (built) {
+    var byTarget = {}, certDers = [];
+    built.forEach(function (res, i) { (byTarget[jobs[i].t] = byTarget[jobs[i].t] || []).push(res.value); certDers.push(res.certDer); });
+
+    var newSiSet = b.set(siSet.children.map(function (siNode, idx) {
+      if (!byTarget[idx]) return siNode.bytes;
+      return opts.countersignatureOf == null ? _appendCountersigs(siNode, byTarget[idx]) : _spliceNested(siNode, opts.countersignatureOf, byTarget[idx]);
+    }));
+
+    // Rebuild SignedData: version, digestAlgorithms (UNCHANGED -- a countersignature digest is not a
+    // SignedData digestAlgorithm), encapContentInfo, certificates [0]?, crls [1]?, the new signerInfos.
+    var certsNode = null, crlsNode = null;
+    for (var i = 3; i < sdKids.length - 1; i++) {
+      if (sdKids[i].tagClass === "context" && sdKids[i].tagNumber === 0) certsNode = sdKids[i];
+      else if (sdKids[i].tagClass === "context" && sdKids[i].tagNumber === 1) crlsNode = sdKids[i];
+    }
+    var existing = [];
+    if (certsNode) certsNode.children.forEach(function (c) { existing.push(c.bytes); });
+    if (opts.certificates !== false) certDers.forEach(function (d) { existing.push(d); });
+    var allCerts = _dedupe(existing).sort(Buffer.compare);   // X.690 sec. 11.6
+
+    var newSdFields = [sdKids[0].bytes, sdKids[1].bytes, sdKids[2].bytes];   // version, digestAlgs, encap (raw)
+    if (allCerts.length) newSdFields.push(b.contextConstructed(0, Buffer.concat(allCerts)));
+    if (crlsNode) newSdFields.push(crlsNode.bytes);
+    newSdFields.push(newSiSet);
+    var newCi = b.sequence([root.children[0].bytes, b.explicit(0, b.sequence(newSdFields))]);
+    return opts.pem ? pkix.pemEncode(newCi, "CMS", frameworkError.PemError) : newCi;
+  });
+}
+
 // Coverage residual -- three defensive branches are unreachable through the shipped path:
 //   * `_skiValue`'s `cert.extensions || []` fallback -- x509.parse always surfaces `extensions`
 //     as an array (empty when absent), so the `|| []` never fires.
@@ -199,4 +424,13 @@ function _toBuf(v, what) {
 //   * `_assertKeyMatchesScheme`'s `!ka.hash` guard -- an `imp.hash` is set only for an RSA
 //     scheme, which requires `ka.name` to already equal the RSA name (else the earlier name
 //     check throws); an RSA CryptoKey always carries a `hash`, so `!ka.hash` never fires.
-module.exports = { sign: sign };
+// Countersign-side residuals also unreachable through the shipped path:
+//   * `_resolveSignerIndices`'s `n < 1` throw -- a parsed SignedData always carries at least one
+//     SignerInfo, so the default index [0] is always in range.
+//   * `_spliceNested`'s no-countersignature / index-out-of-range / not-found throws -- the same node
+//     is validated by `_targetPreimage` FIRST (it computes the nested preimage before the build), so
+//     by the time `_spliceNested` re-walks it those conditions cannot hold; the checks are
+//     belt-and-suspenders against a future caller reordering the two.
+//   * the `crls [1]` preservation branches in `countersign` -- pki.cms.sign never emits a crls field,
+//     so a store this producer countersigns never carries one to preserve.
+module.exports = { sign: sign, countersign: countersign };

package/lib/cms-verify.js

@@ -51,6 +51,7 @@ function _err(code, message, cause) { return new CmsError(code, message, cause);
 
 var OID_MESSAGE_DIGEST = oid.byName("messageDigest");
 var OID_CONTENT_TYPE = oid.byName("contentType");
+var OID_COUNTERSIGNATURE = oid.byName("countersignature");
 
 // A digest-algorithm name -> the WebCrypto hash.
 var DIGEST_HASH = { sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
@@ -309,12 +310,16 @@ function _decodeSignedAttrs(setOfBytes) {
 
 // Verify one SignerInfo. Returns { ok, sid, cert, ... } -- a resolved false is a verdict; a
 // structural failure carries a code.
-function _verifyOne(si, content, eContentType, parsedCerts) {
+// `csTarget`, when set (a Buffer), makes this a COUNTERSIGNATURE verify (RFC 5652 sec. 11.4): the
+// preimage is the countersigned signature octets, not the sec. 5.4 content preimage, and no
+// content-type attribute is required or checked (_computeCountersigBytes). content/eContentType are
+// unused in that mode.
+function _verifyOne(si, content, eContentType, parsedCerts, csTarget) {
   // A composite ML-DSA SignerInfo (draft-ietf-lamps-cms-composite-sigs) is keyed by its composite
   // OID, not a SIG_SCHEME name; intercept it before the classical dispatch (its verify has no
   // single external signature hash, so it never routes through the SIG_SCHEME/sigHash gate below).
   var composite = compositeSig.COMPOSITE_ALGS[si.signatureAlgorithm.oid];
-  if (composite) return _verifyComposite(si, composite, content, eContentType, parsedCerts);
+  if (composite) return _verifyComposite(si, composite, content, eContentType, parsedCerts, csTarget);
   var scheme = SIG_SCHEME[si.signatureAlgorithm.name];
   if (!scheme) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported signature algorithm " + JSON.stringify(si.signatureAlgorithm.name) });
   var digestHash = DIGEST_HASH[si.digestAlgorithm.name];
@@ -362,12 +367,43 @@ function _verifyOne(si, content, eContentType, parsedCerts) {
   if (!signers.length) return Promise.resolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
   var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
 
-  return _computeSignedBytes(si, content, eContentType).then(function (signedBytes) {
+  return (csTarget != null ? _computeCountersigBytes(si, csTarget) : _computeSignedBytes(si, content, eContentType)).then(function (signedBytes) {
     if (signedBytes && signedBytes.mismatch) return { ok: false, code: signedBytes.mismatch.code, sid: si.sid, cert: signers[0].der, message: signedBytes.mismatch.message };
     return _verifyAgainstCandidates(scheme, sigHash, sigBytes, signedBytes, si.sid, signers, pss ? pss.saltLength : 0, scheme.sameKeyOid ? oid.byName(si.signatureAlgorithm.name) : null);
   });
 }
 
+// The exact bytes a countersignature covers (RFC 5652 sec. 11.4): the countersigned SignerInfo's
+// signature value octets (`csTarget`). With signed attributes present, the message-digest attribute
+// MUST equal digest(csTarget) under the countersignature's own digestAlgorithm and the signature
+// covers the re-tagged SignedAttributes ([0] -> universal SET OF) -- the identical transform the
+// top-level signer uses, minus the content-type attribute (which sec. 11.4 FORBIDS). Resolves the
+// signed bytes, or { mismatch } when the message-digest disagrees.
+function _computeCountersigBytes(si, csTarget) {
+  return Promise.resolve().then(function () {
+    if (!si.signedAttrsBytes) return csTarget;   // no signed attributes: sign over the target signature octets directly
+    var reTagged = Buffer.from(si.signedAttrsBytes);
+    reTagged[0] = 0x31;   // [0] IMPLICIT -> universal SET OF
+    var attrs;
+    try {
+      attrs = _decodeSignedAttrs(reTagged);
+    } catch (e) { if (e instanceof CmsError) throw e; throw _err("cms/bad-signed-attrs", "the countersignature signedAttrs is not a valid SET OF Attribute", e); }
+    // sec. 11.4: a content-type attribute MUST NOT appear (the parser already rejects it at parse, but
+    // verify never relies on the parse alone -- a parsed-object input could carry one).
+    if (attrs.filter(function (a) { return a.type === OID_CONTENT_TYPE; }).length) throw _err("cms/misplaced-attr", "a countersignature must not carry a content-type attribute (RFC 5652 sec. 11.4)");
+    var mdAttr = attrs.filter(function (a) { return a.type === OID_MESSAGE_DIGEST; })[0];
+    if (!mdAttr || mdAttr.values.length !== 1) throw _err("cms/bad-signed-attrs", "a countersignature's signedAttrs must carry exactly one message-digest attribute (RFC 5652 sec. 11.4)");
+    var declared;
+    try {
+      declared = asn1.read.octetString(mdAttr.values[0]);
+    } catch (e) { throw _err("cms/bad-signed-attrs", "the message-digest attribute value is not an OCTET STRING", e); }
+    return _computeDigest(si.digestAlgorithm.name, csTarget).then(function (d) {
+      if (!d.equals(declared)) return { mismatch: { code: "cms/message-digest-mismatch", message: "the countersignature message-digest does not match the countersigned signature" } };
+      return reTagged;
+    });
+  });
+}
+
 // The exact bytes the signature covers (RFC 5652 sec. 5.4), shared by the classical and composite
 // verify paths so both bind the message-digest / content-type checks to the VERIFIED preimage (not
 // the caller-mutable parsed si.signedAttrs). Resolves the signed bytes, or { mismatch } when a
@@ -418,7 +454,7 @@ function _computeSignedBytes(si, content, eContentType) {
 // pre-hash. It reuses the sec. 5.4 preimage + message-digest binding UNCHANGED, then dispatches
 // compositeVerify per candidate certificate (BOTH components must verify -- never an AND->OR
 // downgrade).
-function _verifyComposite(si, comp, content, eContentType, parsedCerts) {
+function _verifyComposite(si, comp, content, eContentType, parsedCerts, csTarget) {
   if (si.signatureAlgorithm.parameters !== null && si.signatureAlgorithm.parameters !== undefined) {
     return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "the composite signatureAlgorithm parameters must be absent (draft-ietf-lamps-cms-composite-sigs sec. 3.4)" });
   }
@@ -447,7 +483,7 @@ function _verifyComposite(si, comp, content, eContentType, parsedCerts) {
   var signers = _findSignerCerts(si.sid, parsedCerts);
   if (!signers.length) return Promise.resolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
   var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
-  return _computeSignedBytes(si, content, eContentType).then(function (signedBytes) {
+  return (csTarget != null ? _computeCountersigBytes(si, csTarget) : _computeSignedBytes(si, content, eContentType)).then(function (signedBytes) {
     if (signedBytes && signedBytes.mismatch) return { ok: false, code: signedBytes.mismatch.code, sid: si.sid, cert: signers[0].der, message: signedBytes.mismatch.message };
     return _verifyCompositeAgainstCandidates(comp, sigBytes, signedBytes, si.sid, signers, si.signatureAlgorithm.oid);
   });
@@ -480,6 +516,49 @@ function _verifyCompositeAgainstCandidates(comp, sigBytes, signedBytes, sid, can
   return attempt(0);
 }
 
+// The decoded unsigned attributes of a SignerInfo, surfaced UNAUTHENTICATED (they are outside the
+// signature) with each OID resolved to a name -- so a caller can read an attached RFC 3161 timestamp
+// token or inspect a countersignature attribute. NEVER counted toward a signer's ok / res.valid.
+function _surfaceUnsignedAttrs(si) {
+  return (si.unsignedAttrs || []).map(function (a) {
+    return { type: a.type, typeName: oid.name(a.type) || null, values: a.values };
+  });
+}
+
+// Verify every countersignature attached to `si` (RFC 5652 sec. 11.4): each id-countersignature
+// value is a SignerInfo over `si`'s signature octets. Returns per-countersignature verdicts; a
+// countersignature's OWN countersignatures verify over ITS signature octets (recursive). A
+// present-but-invalid countersignature is surfaced ok:false -- never silently dropped. The recursion
+// terminates because it only walks the FINITE parsed structure: each nested countersignature value
+// is a sub-encoding of its parent, and the strict decoder already bounds total nesting by
+// C.LIMITS.DER_MAX_DEPTH at parse (CWE-834/770), so a hostile deep chain fails closed before verify.
+function _verifyCountersignatures(si, parsedCerts) {
+  // si.signature is always a Buffer from the strict parser (and from walkCountersignature on the
+  // recursive path), so _toBuf is a pass-through here -- the SignerInfo is already well-formed.
+  var targetSig = _toBuf(si.signature, "the countersigned signature");
+  var values = [];
+  (si.unsignedAttrs || []).forEach(function (a) {
+    if (a.type !== OID_COUNTERSIGNATURE) return;
+    a.values.forEach(function (v) { values.push(v && v.bytes ? v.bytes : v); });
+  });
+  return Promise.all(values.map(function (vDer) { return _verifyOneCountersig(vDer, targetSig, parsedCerts); }));
+}
+
+function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
+  var csSi;
+  try { csSi = cms.walkCountersignature(asn1.decode(Buffer.isBuffer(vDer) ? vDer : Buffer.from(vDer))); }
+  catch (e) { return Promise.resolve({ ok: false, code: (e instanceof CmsError ? e.code : "cms/bad-countersignature"), message: e && e.message }); }
+  return _verifyOne(csSi, targetSig, null, parsedCerts, targetSig).then(function (verdict) {
+    return _verifyCountersignatures(csSi, parsedCerts).then(function (nested) {
+      var node = { ok: verdict.ok, sid: verdict.sid, cert: verdict.cert, digestAlgorithm: csSi.digestAlgorithm.name };
+      if (verdict.code) node.code = verdict.code;
+      node.unsignedAttrs = _surfaceUnsignedAttrs(csSi);
+      node.countersignatures = nested;
+      return node;
+    });
+  });
+}
+
 /**
  * @primitive  pki.cms.verify
  * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, signers }>
@@ -533,8 +612,17 @@ function verify(input, opts) {
   (parsed.certificates || []).forEach(function (c) { _addCert(parsedCerts, c && c.bytes ? c.bytes : c); });
   (opts.certs || []).forEach(function (c) { _addCert(parsedCerts, c); });
   var eContentType = parsed.encapContentInfo.eContentType;
-  return Promise.all(parsed.signerInfos.map(function (si) { return _verifyOne(si, content, eContentType, parsedCerts); }))
-    .then(function (signers) { return { valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }), signers: signers }; });
+  return Promise.all(parsed.signerInfos.map(function (si) {
+    // res.valid reflects only the PRIMARY signerInfos; a countersignature / unsigned attribute is
+    // outside the signature and NEVER flips the top-level verdict. Both are surfaced per signer.
+    return _verifyOne(si, content, eContentType, parsedCerts).then(function (verdict) {
+      return _verifyCountersignatures(si, parsedCerts).then(function (countersignatures) {
+        verdict.countersignatures = countersignatures;
+        verdict.unsignedAttrs = _surfaceUnsignedAttrs(si);
+        return verdict;
+      });
+    });
+  })).then(function (signers) { return { valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }), signers: signers }; });
 }
 // Parse a candidate cert DER and index its SKI; a cert that will not parse is skipped (it
 // simply cannot be a signer match, and a malformed embedded cert must not fail the verify).
@@ -595,12 +683,61 @@ function _addCert(out, der) {
  * @opts  sid               `"issuerAndSerial"` (default) or `"ski"` (subjectKeyIdentifier).
  * @opts  certificates      Embed the signer certificates in the output. Default true.
  * @opts  pem               Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
+ * @opts  unsignedAttributes  Unsigned attributes for every SignerInfo, each `{ type, values }`
+ *                          (`type` an OID name or dotted string, `values` an array of DER value
+ *                          `Buffer`s). Placed in the SignerInfo `[1]` unsignedAttrs -- OUTSIDE the
+ *                          signature, so they carry no cryptographic assurance and a verifier never
+ *                          reports them authenticated. The vehicle for an RFC 3161 timestamp token
+ *                          (`timeStampToken`); content-type / message-digest / signing-time are
+ *                          rejected here (RFC 5652 sec. 11). Use `pki.cms.countersign` for a
+ *                          countersignature specifically.
  * @example
  *   var p7 = await pki.cms.sign(Buffer.from("hello"), { cert: signerCertDer, key: signerKeyPkcs8 });
  *   var res = await pki.cms.verify(p7);   // res.valid === true
  */
 var sign = cmsSign.sign;
 
+/**
+ * @primitive  pki.cms.countersign
+ * @signature  pki.cms.countersign(cms, signers, opts?) -> Promise<Buffer|string>
+ * @since      0.3.13
+ * @status     experimental
+ * @spec       RFC 5652
+ * @related    pki.cms.sign, pki.cms.verify, pki.schema.cms.parse
+ *
+ * Add one or more countersignatures to an existing CMS SignedData (RFC 5652 sec. 11.4). A
+ * countersignature is itself a `SignerInfo` whose signature covers the CONTENTS of the countersigned
+ * SignerInfo's signature value (NOT the content), attached as the `id-countersignature` unsigned
+ * attribute -- the construction Authenticode timestamps and signature-attestation workflows rest on.
+ * `cms` is the SignedData (a DER `Buffer` or a PEM `CMS` string -- the wire bytes are preserved, so
+ * the countersigned primary still verifies byte-for-byte). Each `signers[i]` is the same descriptor
+ * `pki.cms.sign` takes -- `{ cert, key, digestAlgorithm?, pss? }`, any RSA / RSASSA-PSS / ECDSA /
+ * EdDSA / ML-DSA / SLH-DSA / composite key -- and countersigns over the target signature octets;
+ * `pki.cms.verify` returns each countersignature verdict under `signers[i].countersignatures`. A
+ * countersignature never carries a content-type attribute (sec. 11.4); multiple countersignatures on
+ * one signer are multiple values of the one id-countersignature attribute.
+ *
+ * @opts  signerIndex           Which primary SignerInfo(s) to countersign: an index (default 0), an
+ *                              array of indices, or `"all"`.
+ * @opts  countersignatureOf    Countersign the Nth existing countersignature of the target signer
+ *                              instead of the primary signature (a nested countersignature).
+ * @opts  signedAttributes      Include signed attributes (message-digest + signing-time; NEVER a
+ *                              content-type). Default true; false signs the target signature octets
+ *                              directly.
+ * @opts  signingTime           A `Date` for the countersignature's signing-time, or false to omit it.
+ * @opts  additionalSignedAttributes  Extra signed attributes on the countersignature (a content-type
+ *                              is rejected, RFC 5652 sec. 11.4).
+ * @opts  sid                   `"issuerAndSerial"` (default) or `"ski"`.
+ * @opts  certificates          Embed the countersigner certificate(s) in the SignedData. Default true.
+ * @opts  pem                   Return a PEM string instead of a DER Buffer.
+ * @example
+ *   var p7 = await pki.cms.sign(Buffer.from("hi"), { cert: signerCertDer, key: signerKeyPkcs8 });
+ *   var cs = await pki.cms.countersign(p7, { cert: signerCertDer, key: signerKeyPkcs8 });
+ *   var res = await pki.cms.verify(cs);
+ *   res.signers[0].countersignatures[0].ok;   // true
+ */
+var countersign = cmsSign.countersign;
+
 /**
  * @primitive pki.cms.encrypt
  * @signature pki.cms.encrypt(content, recipients, opts?) -> Promise<Buffer | string>
@@ -633,25 +770,66 @@ var sign = cmsSign.sign;
  */
 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).
@@ -708,4 +886,4 @@ var compress = cmsCompress.compress;
  */
 var decompress = cmsCompress.decompress;
 
-module.exports = { verify: verify, sign: sign, 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/lib/schema-cms.js

@@ -1204,6 +1204,12 @@ function walkEnvelopedData(node) { return schema.walk(ENVELOPED_DATA, node, NS).
 // walkEnvelopedData: the node is the bare structure, typed cms/* on rejection.
 function walkSignedData(node) { return schema.walk(SIGNED_DATA, node, NS).result; }
 function walkEncryptedData(node) { return schema.walk(ENCRYPTED_DATA, node, NS).result; }
+// Validate + surface one countersignature value (RFC 5652 sec. 11.4, Countersignature ::=
+// SignerInfo) into the same parsed shape parse() gives a top-level SignerInfo -- so pki.cms.verify
+// can verify a countersignature through the ONE SignerInfo definition (its sec. 11.4 rules
+// enforced: message-digest present, content-type FORBIDDEN via mode "countersig"). The node is the
+// bare id-countersignature value; a malformed / content-type-carrying value throws a typed cms/*.
+function walkCountersignature(node) { return schema.walk(COUNTERSIGNATURE_SIGNER_INFO, node, NS).result; }
 
 // assertAttachedCiphertext(eci, E, code, label): reject an EnvelopedData /
 // EncryptedData encryptedContentInfo whose encryptedContent (the payload itself)
@@ -1227,6 +1233,7 @@ module.exports = {
   walkEnvelopedData: walkEnvelopedData,
   walkSignedData: walkSignedData,
   walkEncryptedData: walkEncryptedData,
+  walkCountersignature: walkCountersignature,
   assertAttachedCiphertext: assertAttachedCiphertext,
   // The structure's own algorithm tables, exported (like the walk* helpers) as the single source
   // of truth the crypto layer (cms-encrypt / cms-decrypt) shares -- so the wrap<->KEK-length, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.12",
+  "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:a2281c9c-5058-4827-83e2-53a8a4561863",
+  "serialNumber": "urn:uuid:7db025af-2d42-4d80-9d99-9e6ec17cd13f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-24T02:15:58.035Z",
+    "timestamp": "2026-07-24T06:23:40.600Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.12",
+      "bom-ref": "@blamejs/pki@0.3.14",
       "type": "application",
       "name": "pki",
-      "version": "0.3.12",
+      "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.12",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.14",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.12",
+      "ref": "@blamejs/pki@0.3.14",
       "dependsOn": []
     }
   ]