@blamejs/pki 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -4,6 +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.5.2 — 2026-08-13
+
+pki.cms.verify gains a trust seam: name the roots you accept, and the verdict says whether the signer chained to one.
+
+### Added
+
+- pki.cms.verify(input, opts) accepts opts.trustAnchors -- the roots the caller accepts, as certificate DER or anchor tuples -- and returns trusted alongside valid, with a per-signer trusted on each entry of signers. The signer certificate is chained through the same path engine pki.path.validate uses, with the SignedData's own certificates offered as intermediates and never as anchors. Every signer must chain for the message to be trusted, the same rule the per-signer signature check already followed: reporting the whole as trusted because one signer anchored would let an unanchored signer ride out on another's chain. opts.time picks the instant the chain is judged at. Without anchors there is nothing to chain to and trusted is false -- a definite answer rather than a missing one, and the same shape pki.cmp.verify returns. Anchors that cannot be read are a caller's configuration mistake and throw, rather than being absorbed into trusted: false, which would report a verdict about the message for a check that never ran.
+- pki.smime.verify forwards opts.trustAnchors and opts.time to the CMS verification beneath it and surfaces trusted in its own verdict. It documents itself as that verdict plus the MIME surface, so the seam had to reach it: building the options from scratch and passing only certs would leave a caller naming anchors with no way to have them applied. It asks for the emailProtection key purpose when anchoring, at both ends of the chain: requiredEku constrains the signer certificate, because a certificate restricted to serverAuth chains to its root perfectly well and is still the wrong key to have signed a message (RFC 8551 sec. 4.4.4), and checkPurpose selects the anchor's own trust metadata, because a root distributed with NSS trust bits can be marked untrusted for email while remaining a good TLS root -- and those bits, along with distrustAfter, are consulted only when a purpose is named. Asking one without the other checks one end of the chain and not the other. Pass requiredEku or checkPurpose to ask for something else.
+- pki.webauthn accepts RSASSA-PSS credential keys at all three strengths: PS384 (-38) and PS512 (-39) join PS256, in registration and in assertion verification. They were previously refused at parse time on keys that are perfectly well-formed -- the same bytes accepted under -37 -- so a relying party holding credential rows written by another implementation had some it simply could not check, and could not tell which without scanning its own table. An algorithm this verifier does not implement now reports webauthn/unsupported-algorithm rather than webauthn/bad-cose-key: the key is not malformed, and only one of those two facts tells an operator that re-registering the credential cannot help.
+- pki.webauthn.parseCoseKey(bytes) decodes a stored credential public key on its own, and pki.webauthn.verifyAssertion accepts credentialPublicKey as either that parsed object or its COSE bytes. The registration-to-login round trip had a gap in the middle: verify returns the key as an object, but the durable form is bytes -- the object carries Buffers, so a JSON round trip through a datastore returns {"type":"Buffer","data":[...]} rather than what went in, and existing credential rows already hold COSE bytes whoever wrote them. The only routes into the decoder parsed a containing structure, so recovering a stored key meant fabricating an authenticatorData that never existed. A registration verdict now also carries credentialPublicKeyBytes, the form to persist.
+
+### Changed
+
+- A signer certificate whose keyUsage forbids signing is not trusted, however well it chains. RFC 5280 sec. 4.2.1.3 makes the extension binding when present, so a leaf asserting keyEncipherment alone must not verify a signature -- and path validation checks the CA's keyCertSign, not the target's own usage. The verb that knows a signature was made asks the question, the same format-local gate pki.cmp.verify applies, reading the value through the one strict decoder so a malformed keyUsage fails the gate rather than a hand-rolled bit test authorizing it. contentCommitment counts alongside digitalSignature. The signature is still reported sound; what changes is whether the certificate was permitted to have made it.
+- pki.cms.verify and pki.tsp.verify refuse an unrecognized option instead of ignoring it. This is what kept the missing trust seam silent -- a caller writing trustAnchors before it existed, or trustAnchor now, got a verdict that looked anchored and was not. It matters most between these two verbs, because they spell the anchor option differently: pki.tsp.verify takes trustAnchor, singular, an anchor tuple, while pki.cms.verify and pki.cmp.verify take trustAnchors, plural, accepting certificate DER. Carrying the plural spelling to pki.tsp.verify previously meant no anchoring and no error -- an unchained TSA certificate under valid: true. The refusal names the difference.
+
+### Security
+
+- Build and analysis pins move up: github/codeql-action to v4.37.6 across all six references, ossf/scorecard-action to v2.4.4, actions/setup-python to v7.0.0, the ClusterFuzzLite base-builder-javascript image to its current digest, and eslint to 10.8.1. Nothing here reaches the published tarball -- the package still declares no runtime dependencies -- and every action stays pinned by commit SHA with its version in a trailing comment.
+
 ## v0.5.1 — 2026-08-12
 
 Four verify and export paths stop answering a question other than the one they were asked: the key you supply governs, and a private key exports as one.

package/README.md

@@ -237,8 +237,8 @@ comment blocks, is at [pkijs.com](https://pkijs.com).
 | `pki.crl` | CRL issuance and verification (RFC 5280 §5). `sign(spec, issuer, opts)` builds and signs a `CertificateList` from a `spec` of `thisUpdate` and `nextUpdate`, an optional `crlNumber`, a `revoked` array (each entry a `serialNumber` and `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, with an `issuer` of `{ cert, key }` or `{ name, publicKey, key }`. The signature algorithm is resolved from the issuer key, so RSA (PKCS#1 v1.5 or 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. 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` | Key-material lifecycle (RFC 5958 / RFC 8018). `encrypt(privateKey, password, opts)` wraps a PKCS#8 private key (DER, PEM, or an extractable `CryptoKey`) into an `EncryptedPrivateKeyInfo` under PBES2 (PBKDF2 with AES-CBC-Pad), where `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, and scrypt are refused), the salt and iteration count are bounded before any derivation (`opts.maxIterations` lowers the cap), and a malformed parameter set or wrong-length IV is a distinct typed error. Because a MAC-less PBES2-CBC decrypt must not become 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)` and `import(input, opts)` move a private key as PKCS#8 or a public key as SubjectPublicKeyInfo. The key may come from the platform's WebCrypto or from a separately installed copy of this toolkit, and is exported through whichever holds its material; a non-extractable key, or one whose implementation keeps its material out of reach, is refused with that as the reason. Encoding is delegated to WebCrypto, so RSA carries an explicit NULL, EC a named curve, and Ed25519/Ed448/X25519/X448 omit parameters, and an ambiguous RSA or EC import requires `opts.algorithm`. `generate(algorithm, opts)` produces a key pair over RSA, ECDSA/ECDH, the Edwards and Montgomery curves, and the FIPS post-quantum ML-DSA and ML-KEM; `publicFromPrivate(privateKey)` derives the public key. Returns DER or PEM, with a typed `KeyError` on failure. Parsing stays at `pki.schema.pkcs8.parse` — `encrypt`, `decrypt`, `export`, `import`, `generate`, `publicFromPrivate` |
 | `pki.pkcs12` | PKCS#12 (.p12/.pfx) issuance and reading (RFC 7292 / RFC 9579). `build(spec, opts)` assembles a store from 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, or nested `safeContents` bags. Keys and certs are validated before wrapping, and `friendlyName` (BMPString) and `localKeyId` are single-value. Integrity is a classic Appendix B HMAC (the default, for maximum interoperability) or an RFC 9579 PBMAC1 (`opts.mac.algorithm`) over SHA-256/384/512, with 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 — which is what OpenSSL and NSS consume, so a file it emits opens in both, cross-checked bidirectionally. The MAC covers 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 classic or PBMAC1 MAC over `macedBytes` and constant-time-compares it, throwing on a MAC-less or public-key-integrity store. Public-key integrity (`opts.integrity.mode: "public-key"`) wraps the AuthenticatedSafe in a CMS SignedData instead of a MAC, signed by any `pki.cms.sign` signer and carrying no MacData (§4); privacy stays independent, so `password` still PBES2-encrypts the bags. Public-key privacy wraps a SafeContents as a CMS EnvelopedData (AES-CBC, `id-envelopedData`, never GCM) encrypted to recipient public keys through the `pki.cms.encrypt` recipient model, via per-safe `recipients` or the `opts.recipientCerts` convenience, restricted to certificate recipients (RSA-OAEP, ECDH, X25519, X448, ML-KEM) since a password or KEK recipient could not be reopened by `open`. All four integrity-by-privacy combinations are permitted (§3.1). `open(pfx, password, opts)` reads a store back: it verifies the MAC first, so a wrong password is the MAC verdict rather than a decrypt error, then PBES2-decrypts every privacy safe and shrouded key bag and returns `{ integrityMode, macVerified, signers, keys, certs, crls, secrets }` — keys as re-validated PKCS#8 DER, certs, CRLs and secrets as raw DER, all with `friendlyName` and `localKeyId`, nested safes recursively. A MAC-less store is refused unless `opts.allowUnauthenticated`. A public-key-integrity store is verified through its CMS SignedData signature first (`pkcs12/signature-invalid` on failure), with the signer surfaced in `signers` but never trust-chained, which remains the caller's `pki.path.validate` step. A legacy-PBE store's Appendix C 3DES and RC2 bags are decrypted, RC2 through an in-tree RFC 2268 cipher, so an `openssl pkcs12 -legacy` or NSS store opens; the legacy RC4 schemes are refused. An `id-envelopedData` safe is decrypted with `opts.recipientKey` after the integrity gate (`pkcs12/no-recipient-key` when absent), every recipient-side fault and every post-integrity decrypt failure collapsing to the uniform `pkcs12/decrypt-failed`, and `opts.keys: 'crypto'` imports each key to a `CryptoKey`. It reads what OpenSSL and NSS produce. Returns DER or a PEM `PKCS12`, with a typed `Pkcs12Error` on failure. Parsing stays at `pki.schema.pkcs12.parse` — `build`, `verifyMac`, `open` |
-| `pki.cms` | CMS signing, verification, encryption, and compression (RFC 5652). `sign(content, signers, opts)` produces a SignedData (§5), attached or detached, with one or many signers over 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, or EdDSA key (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. A signer may also be key-only — `{ key, spki, keyIdentifier }` with no certificate — which RFC 5272 §3.2 requires when a Full PKI Request is signed by the key of a certification request it carries: the signer identifier takes the subjectKeyIdentifier form carrying the identifier the request declares, the signature scheme resolves from the request's own public key, and no certificate is embedded. `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: with signed attributes 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), and otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate; chaining that certificate to a trust anchor is the caller's `pki.path.validate` step. `countersign(cms, signers, opts)` adds a countersignature (§11.4) — a `SignerInfo` over the countersigned SignerInfo's signature value, any signer algorithm, nestable, with 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 — including an RFC 3161 timestamp token, attachable via `sign`'s `unsignedAttributes` — under `signers[i].unsignedAttrs`, surfaced unauthenticated. `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData, with recipients auto-dispatched off the certificate key to key transport (RSAES-OAEP; v1.5 is 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 with RFC 3211 PWRI-KEK), or the post-quantum ML-KEM KEMRecipientInfo (RFC 9629/9936), wrapping one fresh content key 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, and password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. Every key-establishment secret the toolkit allocates is wiped once used, on the failing path as well as the succeeding one: the KEM shared secret and its derived key-encryption key, the raw ECDH / X25519 / X448 agreement secret, a password-derived key-encryption key, and the content-encryption key itself, cleared once the message is complete since all recipients share it. Caller-supplied key material is never written to (best-effort; NIST SP 800-227 §4.2, RFC 9629 §7). `authenticate(content, recipients, opts)` produces an `id-ct-authData` (§9): cleartext content plus an HMAC-SHA-256/384/512 MAC, authenticated but not encrypted, with the fresh MAC key wrapped for every recipient through the same RecipientInfo model. The MAC covers the authenticated attributes (content-type and 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`. `compress(content, opts)` and `decompress(input, opts)` produce and consume a CompressedData (RFC 3274; 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`. Compression is a size transform with no integrity or confidentiality (RFC 8551 §2.4.5). Fail-closed with typed `cms/*` errors — `sign`, `verify`, `countersign`, `encrypt`, `authenticate`, `decrypt`, `compress`, `decompress` |
-| `pki.smime` | S/MIME message assembly, verification, encryption, and compression over the CMS layer (RFC 8551). `sign(content, signers, opts)` wraps a MIME entity in either form: `multipart/signed`, where the content stays readable in any MUA and a detached CMS SignedData rides alongside as `application/pkcs7-signature` with a matching `micalg`, or `application/pkcs7-mime; smime-type=signed-data`, where the whole entity is a base64 CMS SignedData. The signed bytes are the entity's §3.1.1 canonical form with CRLF line endings, and `verify(message, opts)` unwraps both forms and recomputes over the same canonicalizer, so a transport that re-wraps line endings still verifies while 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, as `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 rather than the header, and decryption is fail-closed and oracle-free. The crypto is entirely `pki.cms.sign` / `verify` / `encrypt` / `decrypt`, so it is algorithm-agnostic: 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. As with `cms.verify`, `verify` returns the per-signer cryptographic verdict plus the recovered content, and chaining a signer to a trust anchor is the caller's `pki.path.validate` step. `compress(content, opts)` and `decompress(message, opts)` add the opaque `application/pkcs7-mime; smime-type=compressed-data; name=smime.p7z` frame (§3.6, RFC 3274), a size transform with no integrity or confidentiality (§2.4.5), bounded against a bomb; the recovered content, which may itself be signed or enveloped, is returned for the caller to re-verify. Header protection (RFC 9788): `sign` and `encrypt` take `opts.protectHeaders`, which inlines the caller's `opts.headers` on the Cryptographic Payload root (its Content-Type gaining `hp="clear"` when signed or `hp="cipher"` when encrypted) so the CMS signature or encryption covers them, defeating a transport that rewrites or reads Subject, From, and the rest. `verify` and `decrypt` surface the authenticated inner set as `protectedHeaders` plus `headerProtection { present, mode, fromMismatch, confidential, legacy }`, so a tampered outer header cannot alter it and `fromMismatch` flags an outer From that disagrees. Encryption applies a Header Confidentiality Policy: the default `hcp_baseline` obscures the outer Subject to `[...]` and removes Comments and Keywords, so the real values live only in the ciphertext, and `decrypt` recovers them. Every emitted header routes through a fail-closed injection guard that rejects a CR, LF, or NUL value and a non-ftext name, and a malformed or contradictory `hp` wrap fails closed as `smime/bad-header-protection` rather than silently downgrading. The CMS crypto is unchanged. Inbound legacy RFC 8551 header protection is recognized opt-in: `verify` and `decrypt` with `opts.legacyHeaderProtection` detect a legacy `message/rfc822`-wrapped payload by the RFC 9788 §4.10.1 four-condition identification and surface the inner headers under `headerProtection.legacy = { headers, mode, fromMismatch, confidential }`, where `headers` is an ordered `[{ name, value }]` array retaining legally repeated fields such as `Received`. Those never appear in `protectedHeaders` and never set `present: true`. Because a legacy message is structurally indistinguishable from an ordinary forwarded `message/rfc822`, this is an explicit heuristic (§4.10.2, "no strong end-to-end guarantees"): a caller keying trust off `present` or `protectedHeaders` is never misled, and only one that explicitly reads `headerProtection.legacy.headers` and cross-checks `legacy.fromMismatch` consumes it. It is off by default, and a nested crypto layer, an inner `hp=`, a non-`message/rfc822` payload, or a duplicate Content-Type reports `legacy: null`. Bidirectionally interoperable with `openssl smime` and `openssl cms`. Fail-closed with typed `smime/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
+| `pki.cms` | CMS signing, verification, encryption, and compression (RFC 5652). `sign(content, signers, opts)` produces a SignedData (§5), attached or detached, with one or many signers over 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, or EdDSA key (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. A signer may also be key-only — `{ key, spki, keyIdentifier }` with no certificate — which RFC 5272 §3.2 requires when a Full PKI Request is signed by the key of a certification request it carries: the signer identifier takes the subjectKeyIdentifier form carrying the identifier the request declares, the signature scheme resolves from the request's own public key, and no certificate is embedded. `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: with signed attributes 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), and otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate. `valid` and `trusted` are separate claims and neither implies the other: a SignedData carries its own certificates, so `valid` says the signature is sound under one of them and nothing about who signed, while `trusted` says every signer chained to a root named in `opts.trustAnchors`, validated through the same RFC 5280 path engine `pki.path.validate` uses. Without anchors there is nothing to chain to and `trusted` is `false`; anchors that cannot be read throw, rather than reading as untrusted. An unrecognized option is refused rather than ignored. `countersign(cms, signers, opts)` adds a countersignature (§11.4) — a `SignerInfo` over the countersigned SignerInfo's signature value, any signer algorithm, nestable, with 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 — including an RFC 3161 timestamp token, attachable via `sign`'s `unsignedAttributes` — under `signers[i].unsignedAttrs`, surfaced unauthenticated. `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData, with recipients auto-dispatched off the certificate key to key transport (RSAES-OAEP; v1.5 is 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 with RFC 3211 PWRI-KEK), or the post-quantum ML-KEM KEMRecipientInfo (RFC 9629/9936), wrapping one fresh content key 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, and password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. Every key-establishment secret the toolkit allocates is wiped once used, on the failing path as well as the succeeding one: the KEM shared secret and its derived key-encryption key, the raw ECDH / X25519 / X448 agreement secret, a password-derived key-encryption key, and the content-encryption key itself, cleared once the message is complete since all recipients share it. Caller-supplied key material is never written to (best-effort; NIST SP 800-227 §4.2, RFC 9629 §7). `authenticate(content, recipients, opts)` produces an `id-ct-authData` (§9): cleartext content plus an HMAC-SHA-256/384/512 MAC, authenticated but not encrypted, with the fresh MAC key wrapped for every recipient through the same RecipientInfo model. The MAC covers the authenticated attributes (content-type and 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`. `compress(content, opts)` and `decompress(input, opts)` produce and consume a CompressedData (RFC 3274; 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`. Compression is a size transform with no integrity or confidentiality (RFC 8551 §2.4.5). Fail-closed with typed `cms/*` errors — `sign`, `verify`, `countersign`, `encrypt`, `authenticate`, `decrypt`, `compress`, `decompress` |
+| `pki.smime` | S/MIME message assembly, verification, encryption, and compression over the CMS layer (RFC 8551). `sign(content, signers, opts)` wraps a MIME entity in either form: `multipart/signed`, where the content stays readable in any MUA and a detached CMS SignedData rides alongside as `application/pkcs7-signature` with a matching `micalg`, or `application/pkcs7-mime; smime-type=signed-data`, where the whole entity is a base64 CMS SignedData. The signed bytes are the entity's §3.1.1 canonical form with CRLF line endings, and `verify(message, opts)` unwraps both forms and recomputes over the same canonicalizer, so a transport that re-wraps line endings still verifies while 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, as `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 rather than the header, and decryption is fail-closed and oracle-free. The crypto is entirely `pki.cms.sign` / `verify` / `encrypt` / `decrypt`, so it is algorithm-agnostic: 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. As with `cms.verify`, `verify` returns the per-signer verdict plus the recovered content, and `valid` and `trusted` are separate claims: `valid` says the signature is sound under a certificate the message carried, `trusted` says every signer chained to a root named in `opts.trustAnchors`. Anchoring here is validated for email at both ends of the chain — the signer certificate must carry `emailProtection` (RFC 8551 §4.4.4) and the anchor's own trust metadata must permit that purpose, since a root can be distrusted for email while remaining a good TLS root. Override either with `requiredEku` / `checkPurpose`. `compress(content, opts)` and `decompress(message, opts)` add the opaque `application/pkcs7-mime; smime-type=compressed-data; name=smime.p7z` frame (§3.6, RFC 3274), a size transform with no integrity or confidentiality (§2.4.5), bounded against a bomb; the recovered content, which may itself be signed or enveloped, is returned for the caller to re-verify. Header protection (RFC 9788): `sign` and `encrypt` take `opts.protectHeaders`, which inlines the caller's `opts.headers` on the Cryptographic Payload root (its Content-Type gaining `hp="clear"` when signed or `hp="cipher"` when encrypted) so the CMS signature or encryption covers them, defeating a transport that rewrites or reads Subject, From, and the rest. `verify` and `decrypt` surface the authenticated inner set as `protectedHeaders` plus `headerProtection { present, mode, fromMismatch, confidential, legacy }`, so a tampered outer header cannot alter it and `fromMismatch` flags an outer From that disagrees. Encryption applies a Header Confidentiality Policy: the default `hcp_baseline` obscures the outer Subject to `[...]` and removes Comments and Keywords, so the real values live only in the ciphertext, and `decrypt` recovers them. Every emitted header routes through a fail-closed injection guard that rejects a CR, LF, or NUL value and a non-ftext name, and a malformed or contradictory `hp` wrap fails closed as `smime/bad-header-protection` rather than silently downgrading. The CMS crypto is unchanged. Inbound legacy RFC 8551 header protection is recognized opt-in: `verify` and `decrypt` with `opts.legacyHeaderProtection` detect a legacy `message/rfc822`-wrapped payload by the RFC 9788 §4.10.1 four-condition identification and surface the inner headers under `headerProtection.legacy = { headers, mode, fromMismatch, confidential }`, where `headers` is an ordered `[{ name, value }]` array retaining legally repeated fields such as `Received`. Those never appear in `protectedHeaders` and never set `present: true`. Because a legacy message is structurally indistinguishable from an ordinary forwarded `message/rfc822`, this is an explicit heuristic (§4.10.2, "no strong end-to-end guarantees"): a caller keying trust off `present` or `protectedHeaders` is never misled, and only one that explicitly reads `headerProtection.legacy.headers` and cross-checks `legacy.fromMismatch` consumes it. It is off by default, and a nested crypto layer, an inner `hp=`, a non-`message/rfc822` payload, or a duplicate Content-Type reports `legacy: null`. Bidirectionally interoperable with `openssl smime` and `openssl cms`. Fail-closed with typed `smime/*` errors — `sign`, `verify`, `encrypt`, `decrypt`, `compress`, `decompress` |
 | `pki.tsp` | Time-Stamp Protocol (RFC 3161). `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, and ordering, plus the §2.4.2 signing-certificate attribute binding the token to the TSA certificate (SHA-2 imprints, any `pki.cms.sign` TSA key). `request` and `parseRequest` build and parse the TimeStampReq a client sends (imprint, requested policy, nonce, certReq); `response` and `parseResponse` handle the TimeStampResp a TSA returns, either a granted status wrapping a token or a rejection with PKIStatus and failure info, with the §2.4.2 status-to-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`. It returns `{ valid, genTime, serialNumber, tstInfo, … }` — `sign`, `request`, `parseRequest`, `response`, `parseResponse`, `verify` |
 | `pki.ocsp` | Online Certificate Status Protocol (RFC 6960), both the responder and relying-party surface. `buildRequest(query, opts)` builds an OCSPRequest for one or more `{ cert, issuer }` pairs, with the CertID hashed under SHA-1 by default per the RFC 5019 lightweight profile or under SHA-2, plus an optional RFC 9654 nonce and an optional requestor signature. `sign(responseData, responder, opts)` produces a signed BasicOCSPResponse over the exact `ResponseData` DER, from the issuing CA directly or a delegated responder, under any `pki.cms.sign` key including the post-quantum ML-DSA and SLH-DSA sets, with `good`, `revoked` (reason and time), or `unknown` per-certificate status. `buildErrorResponse(status)` produces the unsigned §2.3 error (`tryLater`, `unauthorized`, and the rest). `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 and passing the full out-of-path certificate gates), the signature over `tbsResponseDataBytes`, currency against `thisUpdate` and `nextUpdate`, and the request-nonce echo. It returns `{ status: "good" / "revoked" / "unknown", … }` and never silently accepts. Transport-free — `buildRequest`, `sign`, `buildErrorResponse`, `verify` |
 | `pki.ct` | Certificate Transparency (RFC 6962). `parseSctList` decodes the `SignedCertificateTimestampList` a certificate or OCSP response carries, a TLS-presentation-language payload inside the §3.3 double DER wrap, into per-SCT log id, exact `timestamp` (BigInt), named signature algorithm, and raw signature. `reconstructSignedData` rebuilds the exact `digitally-signed` preimage, and `verifySct` verifies an SCT signature against a log's public key, routing an ECDSA signature through the strict DER-conformance gate and verifying through the crypto engine, resolving true or false and throwing a typed error on a structural fault. On the producing side, `encodeSctList` builds the extension value byte for byte as the exact inverse of `parseSctList`, and `signSct` performs a log's signing step. For trust, `parseLogList` ingests the CT log-list JSON into constraint-carrying trusted logs, recomputing each log's id as SHA-256 of its key and refusing a disagreeing id (a swapped key, §3.2) and decoding the state and temporal-interval constraints; `verifySctWithLogList` resolves the log key from an SCT's log id, enforces the state (usable, qualified, and readonly trusted; retired only before retirement; pending and rejected refused) and the temporal-interval window, then delegates the signature check to `verifySct`. `verifyLogListSignature(json, signature, publicKey)` verifies the detached `log_list.sig` over the raw log-list bytes against a caller-pinned signer key (RSASSA-PKCS1-v1.5/SHA-256 and an EC P-256 arm, with forgeable-key defenses failing closed), cross-checked against `openssl dgst`. `fetchLogList(opts)` turns that chain into a live client: it GETs the `log_list.json` and its detached `log_list.sig` over `pki.transport`, verifies the detached signature over the raw fetched bytes against a caller-pinned distributor key before parsing, so an unverified document is never parsed, read, cached, or surfaced, then ingests the same bytes through `parseLogList` and returns the trusted-log set plus the surfaced `version` and `timestamp`. There is no baked-in vendor URL or key, TLS trust is explicit with `rejectUnauthorized` always on, each response is size-capped before the trust chain, and the transport is injectable so the whole path is testable offline — `parseSctList`, `reconstructSignedData`, `verifySct`, `encodeSctList`, `signSct`, `parseLogList`, `verifySctWithLogList`, `verifyLogListSignature`, `fetchLogList` |

package/index.js

@@ -92,7 +92,11 @@ module.exports = {
   // certificate messages (zlib / brotli / zstd) and the RFC 8446 Certificate message
   // inside them, decoded to per-entry certificate DER. Structure only; no handshake.
   tls:       tls,
-  cms:       cms,
+  // Curated, the way pki.cmp is: cms-verify also exports `setEngine`, the seam path-validate injects
+  // its path builder through. That is plumbing between two internal modules, not an operator verb,
+  // and exporting the module wholesale would put it on the public surface.
+  cms:       { verify: cms.verify, sign: cms.sign, countersign: cms.countersign, encrypt: cms.encrypt,
+    authenticate: cms.authenticate, decrypt: cms.decrypt, compress: cms.compress, decompress: cms.decompress },
   smime:     smime,
   // `cmc` interprets an RFC 5272 Full PKI Response into one terminal verdict;
   // `pki.schema.cmc` is the decoder underneath it.

package/lib/cms-verify.js

@@ -44,6 +44,7 @@ var validator = require("./validator-all");
 var compositeSig = require("./composite-sig");
 var guard = require("./guard-all");
 var frameworkError = require("./framework-error");
+var pkix = require("./schema-pkix");
 
 var CmsError = frameworkError.CmsError;
 function _err(code, message, cause) { return new CmsError(code, message, cause); }
@@ -570,7 +571,7 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
 
 /**
  * @primitive  pki.cms.verify
- * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, signers }>
+ * @signature  pki.cms.verify(input, opts?) -> Promise<{ valid, trusted, signers }>
  * @since      0.2.14
  * @status     stable
  * @spec       RFC 5652
@@ -580,10 +581,27 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  * @related    pki.schema.cms.parse, pki.path.validate
  *
  * Verify a CMS SignedData signature (RFC 5652 sec. 5). `input` is a PEM string, a DER
- * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, signers }` where each
- * `signers[i]` is `{ ok, sid, cert }` (`cert` the matched signer certificate DER) or carries
+ * `Buffer`, or a parsed `pki.schema.cms` object. Returns `{ valid, trusted, signers }` where each
+ * `signers[i]` is `{ ok, sid, cert, trusted }` (`cert` the matched signer certificate DER) or carries
  * a `code` on a structural failure; `valid` is true when there is at least one signer and
- * every signer verified. RSA (PKCS#1 v1.5 and RSASSA-PSS), ECDSA, EdDSA, and the post-quantum
+ * every signer verified.
+ *
+ * `valid` and `trusted` are DIFFERENT claims and neither implies the other. A SignedData carries
+ * its own certificates, so `valid` establishes that the message is internally consistent -- the
+ * signature is sound under a certificate the message or `opts.certs` supplied. Anyone can mint a
+ * certificate, sign with it, and embed it, so that says nothing about WHO signed. `trusted` says
+ * every signer chained to a root named in `opts.trustAnchors`, validated through the same RFC 5280
+ * path engine `pki.path.validate` uses. Without anchors there is nothing to chain to and `trusted`
+ * is `false` -- a definite answer, not a missing one. Anchors that cannot be read are a
+ * configuration fault and throw, rather than being absorbed into `trusted: false`, which would
+ * report a verdict about the message for a check that never ran.
+ *
+ * Trust is decided from the certificate the SignerInfo selected -- the one reported as
+ * `signers[i].cert` -- never from another certificate that happens to share its key. A
+ * `subjectKeyIdentifier` names a key, and several certificates can hold it with different
+ * validity windows, key usage and policies; deciding from a sibling would let an expired or
+ * wrong-purpose signer certificate be reported trusted because a different certificate chained.
+ * Supply the certificate you want used. RSA (PKCS#1 v1.5 and RSASSA-PSS), ECDSA, EdDSA, and the post-quantum
  * ML-DSA (ML-DSA-44/65/87, RFC 9882) and SLH-DSA (the twelve FIPS 205 sets, RFC 9814) -- pure mode,
  * empty context -- signatures are recognized, as is composite ML-DSA
  * (draft-ietf-lamps-cms-composite-sigs), which pairs ML-DSA with a traditional RSA / ECDSA / EdDSA
@@ -593,6 +611,16 @@ function _verifyOneCountersig(vDer, targetSig, parsedCerts) {
  *                 encapsulated eContent. Required for a detached signature.
  * @opts  certs    Extra signer certificates (an array of DER `Buffer`s) to match against, in
  *                 addition to the certificates embedded in the SignedData.
+ * @opts  trustAnchors  The roots the caller accepts (DER `Buffer`s or anchor tuples). Supplying
+ *                 them is what makes `trusted` answerable; the SignedData's own certificates are
+ *                 offered as intermediates, never as anchors.
+ * @opts  time     The instant to validate the signer's chain at (default now). Only read when
+ *                 `trustAnchors` is supplied.
+ * @opts  requiredEku   Key purposes the SIGNER certificate must carry, as OID names or dotted OIDs.
+ * @opts  checkPurpose  The purpose the ANCHOR's own trust metadata must permit -- a separate
+ *                 question from `requiredEku`, since a root distributed with NSS trust bits can be
+ *                 marked untrusted for one purpose and good for another. Those bits and
+ *                 `distrustAfter` are consulted only when this names a purpose.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
  *   var key = await pki.key.export(pair.privateKey);
@@ -618,9 +646,18 @@ function _snapshotIfBytes(input, label) {
   return input;
 }
 
+// Every option pki.cms.verify reads. Adding one here is the only way to make it accepted, so a
+// capability cannot arrive with its option silently ignored at this boundary.
+var _VERIFY_OPTS = { certs: 1, content: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1 };
+
 function verify(input, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.verify options must be an object");
+  // An unrecognized option is refused, not swallowed. This is what kept the missing trust seam
+  // silent: a caller writing `trustAnchors` before it existed -- or `trustAnchor` now -- got a
+  // verdict that looked anchored and was not. The guard rejects through a (code, message) FACTORY
+  // and tests membership with hasOwnProperty, so the permitted set is a lookup object.
+  guard.identifier.assertKnownKeys(opts, _VERIFY_OPTS, _err, "cms/bad-input", "pki.cms.verify has an unknown option ");
   // Handed MUTABLE BYTES, parse a private copy. This function decodes synchronously
   // and checks signatures in a later promise turn, so without the copy every range
   // the parse surfaced -- the signed content above all -- stays a view into the
@@ -657,6 +694,12 @@ 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;
+  // The trust configuration is captured SYNCHRONOUSLY here, before any signature work yields. It is
+  // read a promise turn later, and everything in it stays caller-owned across that gap: the array
+  // can be re-pointed, an anchor's DER rewritten, the validation instant moved. Any of those would
+  // have the chain judged against a configuration the caller never asked for while the verdict
+  // reports the one they did. The same defence the input and the certificates already have.
+  var trustCfg = _snapshotTrust(opts);
   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.
@@ -667,7 +710,197 @@ function verify(input, opts) {
         return verdict;
       });
     });
-  })).then(function (signers) { return { valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }), signers: signers }; });
+  })).then(function (signers) {
+    var res = { valid: signers.length > 0 && signers.every(function (s) { return s.ok === true; }), signers: signers };
+    return _applyTrust(res, parsedCerts, trustCfg).then(function () { return res; });
+  });
+}
+
+// The full path build + validate, injected by path-validate the way it injects into crl-verify and
+// cmp-verify. It is a seam rather than a require because path-validate is the higher layer: taking
+// the dependency the other way round would be a cycle, and re-implementing a weaker chain walk here
+// is exactly how a second, divergent notion of trust gets into a toolkit.
+var _engine = null;
+function setEngine(engine) { _engine = engine; }
+
+// `valid` and `trusted` are DIFFERENT claims and neither implies the other. `valid` says every
+// signature is sound under a certificate the message or the caller supplied -- a message carries its
+// own certificates, so that establishes internal consistency and nothing about who signed. `trusted`
+// says the signer chained to a root the CALLER named. Without anchors there is no one to chain to,
+// so it is false: not null, because "nobody anchored this" is a definite answer, and the same one a
+// caller gets from pki.cmp.verify.
+// A private copy of the trust configuration, taken at the entry point. The array is copied so it
+// cannot be re-pointed or grown; each anchor's BYTES are copied because rewriting those in place is
+// the same substitution one level down; the instant is copied because a Date is mutable. An anchor
+// TUPLE is copied too, field by field: `{ name, publicKey, algorithm }` is an ordinary object whose
+// key bytes and name can be rewritten just as readily as a DER buffer's, and copying only the DER
+// form would leave the documented tuple form aliased across the same gap -- the window closed for
+// one spelling of an anchor and left open for the other. A PEM string needs no copy: it cannot be
+// rewritten. `requiredEku` is copied for the same reason as the array.
+var _ANCHOR_CLONE_DEPTH = 8;
+function _cloneAnchorValue(v, depth) {
+  if (Buffer.isBuffer(v) || ArrayBuffer.isView(v) || v instanceof ArrayBuffer) {
+    return _snapshotIfBytes(v, "opts.trustAnchors[]");
+  }
+  if (v === null || typeof v !== "object") return v;
+  // A Date BEFORE the generic object walk. It has no enumerable own properties, so copying it
+  // field by field yields `{}` -- an anchor's `distrustAfter: { emailProtection: <Date> }` would
+  // survive the snapshot as an empty object and be rejected as an invalid date, disabling the very
+  // policy it encodes. Copied by value, like the validation instant.
+  if (v instanceof Date) return new Date(v.getTime());
+  // A structure too deep to copy is REFUSED, not shared. Returning it by reference at the cap
+  // would leave part of the anchor caller-mutable across the chain walk while the rest was
+  // snapshotted -- a guarantee that holds for the shallow fields and quietly lapses for the deep
+  // ones, which is worse than not offering it. An anchor tuple is a handful of levels deep; a
+  // deeper one is a caller's mistake, and it fails closed at the entry point.
+  if (depth >= _ANCHOR_CLONE_DEPTH) {
+    throw _err("cms/bad-input", "an opts.trustAnchors entry nests deeper than " + _ANCHOR_CLONE_DEPTH +
+      " levels, so it cannot be copied before the chain is walked; pass the anchor as certificate DER or a { name, publicKey, algorithm } tuple");
+  }
+  if (Array.isArray(v)) return v.map(function (e) { return _cloneAnchorValue(e, depth + 1); });
+  var out = {}, k;
+  for (k in v) {
+    if (!Object.prototype.hasOwnProperty.call(v, k)) continue;
+    out[k] = _cloneAnchorValue(v[k], depth + 1);
+  }
+  return out;
+}
+function _snapshotTrust(opts) {
+  var raw = opts.trustAnchors;
+  var anchors = null;
+  if (raw != null) {
+    anchors = (Array.isArray(raw) ? raw : [raw]).map(function (a) {
+      return typeof a === "string" ? a : _cloneAnchorValue(a, 0);
+    });
+  }
+  return {
+    trustAnchors: anchors,
+    time: opts.time instanceof Date ? new Date(opts.time.getTime()) : opts.time,
+    requiredEku: Array.isArray(opts.requiredEku) ? opts.requiredEku.slice() : opts.requiredEku,
+    checkPurpose: opts.checkPurpose,
+  };
+}
+
+// A signer certificate whose keyUsage FORBIDS signing has not been permitted to sign, however well
+// it chains. RFC 5280 sec. 4.2.1.3: when the extension is present it is binding, and a leaf
+// asserting keyEncipherment alone must not verify a signature. Path validation checks the CA's
+// keyCertSign, not the target's own usage, so the format that knows a signature was made asks the
+// question -- the same format-local gate on top of path.validate that pki.cmp.verify applies.
+// contentCommitment (nonRepudiation) counts: RFC 5652 signatures are made under either bit.
+// The value is read through the ONE strict decoder, which enforces the X.690 sec. 11.2.2 minimal
+// NamedBitList form, so a malformed keyUsage fails the gate rather than a hand-rolled bit test
+// authorizing it.
+// The shared RFC 5280 sec. 4.2.1 extension-value decoders, the same set pki.cmp.verify reads its
+// signer keyUsage through -- one structurally-strict decoder rather than a second, weaker bit test.
+var _CERT_EXT_DECODERS = pkix.certExtensionDecoders(pkix.makeNS("cms", CmsError, oid)).byOid;
+
+function _keyUsagePermitsSigning(parsedCerts, der) {
+  var entry = parsedCerts.filter(function (c) { return c.der.equals(der); })[0];
+  if (!entry) return true;                    // not among the candidates: nothing to read
+  var kuOid = oid.byName("keyUsage");
+  var exts = entry.cert.extensions || [];
+  for (var i = 0; i < exts.length; i++) {
+    if (exts[i].oid !== kuOid) continue;
+    var ku;
+    try { ku = _CERT_EXT_DECODERS[kuOid](exts[i].value); }
+    catch (_e) { return false; }              // unreadable usage is not permission
+    return ku.digitalSignature === true || ku.contentCommitment === true || ku.nonRepudiation === true;
+  }
+  return true;                                // absent: unconstrained (sec. 4.2.1.3)
+}
+
+// `cfg` is verify's SNAPSHOT, never the caller's options object -- the parameter is named for that
+// so a future caller cannot hand it the live one without noticing.
+function _applyTrust(res, parsedCerts, cfg) {
+  res.trusted = false;
+  // Every signer carries the field too, whether or not anchors were supplied. A verdict whose
+  // per-signer shape depends on which options were passed makes a caller iterating `signers` write
+  // a different loop for each case -- and the absent field reads as "unknown" where the answer is
+  // a definite "nothing anchored this".
+  res.signers.forEach(function (s) { s.trusted = false; });
+  if (cfg.trustAnchors == null) return Promise.resolve();
+  if (!_engine) {
+    throw _err("cms/bad-input", "opts.trustAnchors requires the path validator; load pki.path before verifying (require the toolkit through its index)");
+  }
+  // Every signer, not merely one: a multi-signer message's signers are independent claims, and
+  // reporting the whole as trusted because one of them anchored would let an unanchored signer ride
+  // out on another's chain -- the same rule the per-signer `ok` already follows for signatures.
+  var pool = parsedCerts.map(function (c) { return c.der; });
+  var at = cfg.time !== undefined ? cfg.time : new Date();
+  var anchors = cfg.trustAnchors;
+  // The configuration is checked HERE, once, before any signer is looked at. Leaving it to the
+  // chain walk would make a caller's mistake depend on the message: a SignedData whose every signer
+  // failed to verify never reaches a build call, so unusable anchors would be accepted in silence
+  // and reported as `trusted: false` -- the config fault dressed as a verdict, which is exactly the
+  // conflation this seam exists to remove. An empty anchor list is refused for the same reason a
+  // policy that constrains nothing is: it cannot make anything trusted, so asking for it is a
+  // mistake rather than a request.
+  if (!anchors.length) {
+    throw _err("cms/bad-input", "opts.trustAnchors is empty -- name at least one root, or omit it to state that the signer is not being anchored");
+  }
+  // The INSTANT and the key purposes, before the anchors -- the anchor check reads the NORMALIZED
+  // purpose the resolver returns, so it has to run first.
+  if (cfg.time !== undefined) guard.time.assertValid(cfg.time, _err, "cms/bad-input", "opts.time");
+  // The resolver's RETURN is what the walk goes on to use: it normalizes a dotted purpose OID to
+  // its registered name, which is the key an anchor's per-purpose metadata is stored under.
+  // Preflighting with the caller's raw spelling would look up `distrustAfter["1.3.6.1.5.5.7.3.4"]`
+  // where the walk reads `distrustAfter.emailProtection` -- the same value checked under two
+  // different keys, so the early check would pass on metadata the walk then rejects.
+  var purposes = _engine.resolvePurposeOpts({ requiredEku: cfg.requiredEku, checkPurpose: cfg.checkPurpose });
+  // The WHOLE anchor, not only its identity: `toAnchor` settles the name / key / algorithm tuple,
+  // and the constraint metadata beside it -- the per-purpose distrustAfter dates -- is validated
+  // through the same definition the walk uses. Checking one and not the other is how this rule has
+  // repeatedly come back: each new part of the configuration has to join the preflight, not wait
+  // to be caught where it is consumed.
+  anchors.forEach(function (a) {
+    _engine.toAnchor(a);
+    if (purposes.checkPurpose != null) _engine.assertAnchorConstraints(a, purposes.checkPurpose);
+  });
+  // The INSTANT is checked here for the same reason the anchors are, and in the same place: a
+  // Everything above is the preflight: the anchor list, the instant, the key purposes, and each
+  // anchor's own constraint metadata -- all judged before a single signer is looked at, and all
+  // through the definitions the walk itself uses. A new option joins it here; validating one only
+  // where it is consumed is what made a caller's mistake depend on the message.
+  return res.signers.reduce(function (p, s) {
+    return p.then(function () {
+      if (s.ok !== true || !s.cert) { s.trusted = false; return null; }
+      var buildOpts = { trustAnchors: anchors, intermediates: pool, validate: true, time: at };
+      // A key purpose, when the caller names one. "Trusted" is not a property of a chain alone: a
+      // certificate restricted to serverAuth chains perfectly well and is still the wrong key to
+      // have signed an email. The verb that KNOWS the purpose supplies it -- pki.smime.verify asks
+      // for emailProtection -- rather than this layer guessing one for every CMS use.
+      if (cfg.requiredEku != null) buildOpts.requiredEku = cfg.requiredEku;
+      // The ANCHOR's own trust metadata, which is a separate question from the leaf's EKU. A root
+      // distributed with NSS trust bits can be marked untrusted for email while remaining a
+      // perfectly good TLS root, and `pki.path` consults those bits -- and distrustAfter -- only
+      // when a purpose is named. Requiring the leaf's EKU without naming the purpose checks one
+      // end of the chain and not the other, so a root explicitly distrusted for the very purpose
+      // being asked about would still answer "trusted".
+      if (cfg.checkPurpose != null) buildOpts.checkPurpose = cfg.checkPurpose;
+      // THE certificate this SignerInfo selected, and only that one -- the same certificate the
+      // verdict reports as `cert`. When a subjectKeyIdentifier is used, several certificates can
+      // hold the signing key, and it is tempting to let any of them answer: the embedded one may
+      // be self-signed while the caller supplied a CA-issued twin. Doing so would decide trust
+      // from a certificate the message did not present, carrying a different validity window, key
+      // usage and policy set -- so an expired or wrong-purpose signer certificate could be
+      // reported trusted through its sibling. `trusted` describes the certificate named in the
+      // same verdict; a caller who wants a particular one used supplies that one.
+      // Permitted to have signed, as well as chained. Checked BEFORE the chain walk because a
+      // certificate that forbids signing cannot become trusted by chaining, so there is nothing to
+      // learn from walking it.
+      if (!_keyUsagePermitsSigning(parsedCerts, s.cert)) { s.trusted = false; return null; }
+      return _engine.build(s.cert, buildOpts)
+        .then(function (r) { s.trusted = !!(r && r.valid); }, function (e) {
+          // A CONFIG fault -- unusable anchors, an invalid time -- is the caller's mistake and must
+          // not be absorbed into "untrusted", which would read as a verdict about the message. A
+          // chain that simply does not reach an anchor is not that: it is the answer.
+          if (e && e.code && /bad-input|bad-anchor|bad-time/.test(String(e.code))) throw e;
+          s.trusted = false;
+        });
+    });
+  }, Promise.resolve()).then(function () {
+    res.trusted = res.valid && res.signers.length > 0 && res.signers.every(function (s) { return s.trusted === true; });
+  });
 }
 // 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).
@@ -961,4 +1194,5 @@ var compress = cmsCompress.compress;
  */
 var decompress = cmsCompress.decompress;
 
-module.exports = { verify: verify, sign: sign, countersign: countersign, encrypt: encrypt, authenticate: authenticate, decrypt: decrypt, compress: compress, decompress: decompress };
+// `setEngine` is @internal -- the path-validate injection seam, never part of pki.cms.
+module.exports = { verify: verify, sign: sign, countersign: countersign, encrypt: encrypt, authenticate: authenticate, decrypt: decrypt, compress: compress, decompress: decompress, setEngine: setEngine };

package/lib/path-validate.js

@@ -41,6 +41,7 @@ var ocsp = require("./schema-ocsp");
 var ocspVerify = require("./ocsp-verify");
 var crlVerify = require("./crl-verify");
 var cmpVerify = require("./cmp-verify");
+var cmsVerify = require("./cms-verify");
 var cmpSession = require("./cmp-session");
 var guard = require("./guard-all");
 var constants = require("./constants");
@@ -1187,40 +1188,9 @@ async function validate(path, opts) {
   // opts.requiredEku -- the key purposes the TARGET certificate must be good
   // for, each a registered OID name or a dotted OID string. Resolved (and
   // typo-checked) here at the entry point.
-  var requiredEku = null;
-  if (opts.requiredEku !== undefined) {
-    if (!Array.isArray(opts.requiredEku) || opts.requiredEku.length === 0) {
-      throw E("path/bad-input", "validate: opts.requiredEku must be a non-empty array of key-purpose OID names or dotted OID strings");
-    }
-    requiredEku = opts.requiredEku.map(function (p) {
-      if (typeof p !== "string" || p.length === 0) throw E("path/bad-input", "validate: opts.requiredEku entries must be non-empty strings");
-      // A dotted-form attempt (leads with a digit) must be a canonical OID -- a
-      // loose regex accepted a leading-zero / out-of-bounds key that would never
-      // match the canonical EKU the target advertises; anything else is a name.
-      if (/^[0-9]/.test(p)) return guard.identifier.assertCanonicalOid(p, E, "path/bad-input", "validate: opts.requiredEku entry " + JSON.stringify(p));
-      var dotted = oid.byName(p);
-      if (typeof dotted !== "string") throw E("path/bad-input", "validate: opts.requiredEku entry " + JSON.stringify(p) + " is not a registered OID name");
-      return dotted;
-    });
-  }
-  // opts.checkPurpose -- the single key purpose the ANCHOR's NSS trust metadata
-  // (distrustAfter / purposes) is consulted for. Independent of requiredEku
-  // (which gates the leaf's own EKU extension): this selects the per-purpose
-  // key in the trust-anchor constraint contract. A purpose OID name (or a
-  // canonical dotted OID normalized to its name); a bad value throws here.
-  var checkPurpose = null;
-  if (opts.checkPurpose !== undefined) {
-    if (typeof opts.checkPurpose !== "string" || opts.checkPurpose.length === 0) {
-      throw E("path/bad-input", "validate: opts.checkPurpose must be a key-purpose OID name or dotted OID string");
-    }
-    if (/^[0-9]/.test(opts.checkPurpose)) {
-      var cpDotted = guard.identifier.assertCanonicalOid(opts.checkPurpose, E, "path/bad-input", "validate: opts.checkPurpose");
-      checkPurpose = oid.name(cpDotted) || cpDotted;   // normalize a dotted purpose OID to its name for the anchor map
-    } else {
-      if (typeof oid.byName(opts.checkPurpose) !== "string") throw E("path/bad-input", "validate: opts.checkPurpose " + JSON.stringify(opts.checkPurpose) + " is not a registered OID name");
-      checkPurpose = opts.checkPurpose;
-    }
-  }
+  var purposeOpts = resolvePurposeOpts(opts);
+  var requiredEku = purposeOpts.requiredEku;
+  var checkPurpose = purposeOpts.checkPurpose;
 
   var state = initialize(certs, opts, seeds);
   state._n = n;
@@ -1385,9 +1355,8 @@ async function validate(path, opts) {
       // NaN time) would make `notBefore > it` NaN-false and SILENTLY drop the distrust
       // restriction -- the NaN-Date fail-open. Validate a present date fail-closed
       // before the comparison; an absent (undefined/null) date is no restriction.
-      var distrustDate = (checkPurpose && ta.distrustAfter) ? ta.distrustAfter[checkPurpose] : null;
+      var distrustDate = assertAnchorConstraints(ta, checkPurpose);
       if (distrustDate != null) {
-        distrustDate = guard.time.assertValid(distrustDate, E, "path/bad-input", "trustAnchor.distrustAfter." + checkPurpose);
         // STRICTLY > : a leaf whose notBefore == the distrust date stays trusted
         // (Mozilla certverifier isDistrustedCertificateChain: endEntityNotBefore
         // <= distrustAfterTime -> not distrusted; the end-of-day ...235959Z
@@ -2211,6 +2180,16 @@ var ocspCore = ocspVerify.makeOcspVerify({
 cmpVerify.setEngine({ verifyWithSpki: _verifyWithSpki, build: build, validate: validate });
 // pki.cmp.session validates the ISSUED leaf certificate (its signature + chain) through the same engine.
 cmpSession.setEngine({ build: build, validate: validate, toAnchor: toAnchor, coerceCert: coerceCert });
+// pki.cms.verify chains a SignedData's signer certificate to the anchors the CALLER named, so its
+// `trusted` is decided by this one path engine rather than a second, weaker walk of its own.
+// `toAnchor` so cms.verify can validate the caller's anchors ONCE at entry, before any signer is
+// walked -- otherwise a message whose signers all failed would never reach a build call and a
+// malformed anchor would pass unnoticed.
+// `resolvePurposeOpts` so cms.verify can reject a malformed requiredEku / checkPurpose at ITS entry
+// point, through the SAME definition the walk uses -- a message whose signers all failed never
+// reaches a build call, and a caller's configuration must not be judged by the message's quality.
+cmsVerify.setEngine({ build: build, validate: validate, toAnchor: toAnchor,
+  resolvePurposeOpts: resolvePurposeOpts, assertAnchorConstraints: assertAnchorConstraints });
 
 /**
  * @primitive  pki.path.ocspChecker
@@ -2440,6 +2419,63 @@ function coerceCert(input) {
 // tuple. The algorithm is the SPKI KEY-algorithm OID (the sec. 6.1.4(f)
 // parameter-inheritance value), mirroring trust.js _mkAnchor -- NOT the
 // signature OID. The anchor is an input to validate, never one of the path certs.
+// The two key-purpose options, resolved and typo-checked. Extracted so a CALLER can validate them
+// at ITS entry point rather than only when a path is actually walked: a format verb that skips the
+// walk -- pki.cms.verify does when no signer verified -- would otherwise accept a malformed
+// purpose in silence, making configuration validity depend on the message. One definition, so the
+// answer cannot drift between the caller's early check and the walk's own.
+//
+// `requiredEku` gates the TARGET certificate's own EKU extension; `checkPurpose` selects which
+// per-purpose key the ANCHOR's NSS trust metadata (purposes / distrustAfter) is consulted under.
+// They are independent, and each is a registered OID name or a canonical dotted OID.
+// An anchor's CONSTRAINT metadata for one purpose, validated fail-closed and returned normalized.
+// A PRESENT-but-malformed distrustAfter (an Invalid Date: instanceof Date yet a NaN time) would
+// make `notBefore > it` NaN-false and SILENTLY drop the distrust restriction -- the NaN-Date
+// fail-open. Absent metadata is no restriction and returns null.
+//
+// Separate from resolvePurposeOpts because it validates the ANCHOR rather than the options, and
+// exposed for the same reason: a caller that may never reach the walk -- pki.cms.verify when no
+// signer verified -- has to be able to reject a malformed anchor at ITS entry point, through this
+// same definition, so configuration validity never depends on the message.
+function assertAnchorConstraints(ta, checkPurpose) {
+  var d = (checkPurpose && ta && ta.distrustAfter) ? ta.distrustAfter[checkPurpose] : null;
+  if (d == null) return null;
+  return guard.time.assertValid(d, E, "path/bad-input", "trustAnchor.distrustAfter." + checkPurpose);
+}
+
+function resolvePurposeOpts(opts) {
+  var requiredEku = null;
+  if (opts.requiredEku !== undefined) {
+    if (!Array.isArray(opts.requiredEku) || opts.requiredEku.length === 0) {
+      throw E("path/bad-input", "validate: opts.requiredEku must be a non-empty array of key-purpose OID names or dotted OID strings");
+    }
+    requiredEku = opts.requiredEku.map(function (p) {
+      if (typeof p !== "string" || p.length === 0) throw E("path/bad-input", "validate: opts.requiredEku entries must be non-empty strings");
+      // A dotted-form attempt (leads with a digit) must be a canonical OID -- a
+      // loose regex accepted a leading-zero / out-of-bounds key that would never
+      // match the canonical EKU the target advertises; anything else is a name.
+      if (/^[0-9]/.test(p)) return guard.identifier.assertCanonicalOid(p, E, "path/bad-input", "validate: opts.requiredEku entry " + JSON.stringify(p));
+      var dotted = oid.byName(p);
+      if (typeof dotted !== "string") throw E("path/bad-input", "validate: opts.requiredEku entry " + JSON.stringify(p) + " is not a registered OID name");
+      return dotted;
+    });
+  }
+  var checkPurpose = null;
+  if (opts.checkPurpose !== undefined) {
+    if (typeof opts.checkPurpose !== "string" || opts.checkPurpose.length === 0) {
+      throw E("path/bad-input", "validate: opts.checkPurpose must be a key-purpose OID name or dotted OID string");
+    }
+    if (/^[0-9]/.test(opts.checkPurpose)) {
+      var cpDotted = guard.identifier.assertCanonicalOid(opts.checkPurpose, E, "path/bad-input", "validate: opts.checkPurpose");
+      checkPurpose = oid.name(cpDotted) || cpDotted;   // normalize a dotted purpose OID to its name for the anchor map
+    } else {
+      if (typeof oid.byName(opts.checkPurpose) !== "string") throw E("path/bad-input", "validate: opts.checkPurpose " + JSON.stringify(opts.checkPurpose) + " is not a registered OID name");
+      checkPurpose = opts.checkPurpose;
+    }
+  }
+  return { requiredEku: requiredEku, checkPurpose: checkPurpose };
+}
+
 function toAnchor(entry) {
   if (entry && typeof entry === "object" && !Buffer.isBuffer(entry) && entry.name && entry.publicKey && entry.algorithm) {
     // A ready anchor tuple: validate the shape build + validate consume -- name.rdns

package/lib/smime.js

@@ -567,7 +567,7 @@ function _capped(msg) {
 
 /**
  * @primitive  pki.smime.verify
- * @signature  pki.smime.verify(message, opts?) -> Promise<{ valid, signers, form, content, micalg, protectedHeaders, headerProtection }>
+ * @signature  pki.smime.verify(message, opts?) -> Promise<{ valid, trusted, signers, form, content, micalg, protectedHeaders, headerProtection }>
  * @since      0.2.25
  * @status     stable
  * @spec       RFC 8551, RFC 5652, RFC 9788
@@ -577,9 +577,19 @@ function _capped(msg) {
  * `application/pkcs7-mime; smime-type=signed-data`. For `multipart/signed` the detached CMS signature
  * is recomputed over the first part's RFC 8551 sec. 3.1.1 canonical form (the SAME canonicalizer the
  * signer used); for `application/pkcs7-mime` the base64 body is the attached CMS SignedData. Returns
- * `pki.cms.verify`'s `{ valid, signers }` verdict PLUS `form`, the recovered `content` (the signed MIME
- * entity bytes), and the `micalg`. Like `cms.verify`, this returns the cryptographic verdict only --
- * chaining a signer certificate to a trust anchor is the caller's `pki.path.validate` step. A `micalg`
+ * `pki.cms.verify`'s `{ valid, trusted, signers }` verdict PLUS `form`, the recovered `content` (the
+ * signed MIME entity bytes), and the `micalg`.
+ *
+ * `valid` and `trusted` are separate claims, exactly as in `cms.verify`: a SignedData carries its own
+ * certificates, so `valid` says the signature is sound under one of them and nothing about who signed.
+ * Name the roots you accept in `opts.trustAnchors` and `trusted` says every signer chained to one --
+ * validated for EMAIL, at both ends of the chain. The signer certificate must carry the
+ * `emailProtection` key purpose (RFC 8551 sec. 4.4.4), because a certificate restricted to `serverAuth`
+ * chains to its root perfectly well and is still the wrong key to have signed a message; and the anchor's
+ * own trust metadata must permit that purpose, because a root distributed with NSS trust bits can be
+ * marked untrusted for email while remaining a good TLS root. Override either with `opts.requiredEku`
+ * and `opts.checkPurpose`. Supply no anchors and `trusted` is `false` -- there was nothing to chain to.
+ * A `micalg`
  * that disagrees with the actual digest is advisory unless `opts.strictMicalg` (then `smime/micalg-mismatch`).
  * If the message is header-protected (RFC 9788), `protectedHeaders` is the AUTHENTICATED inner header set (a
  * tampered outer header cannot alter it) and `headerProtection` is `{ present, mode, fromMismatch, confidential, legacy }`
@@ -596,6 +606,11 @@ function _capped(msg) {
  * `protectedHeaders` cannot mistake the opt-in heuristic for authenticated headers.
  *
  * @opts certs        extra signer certificates (DER `Buffer`s) to match, forwarded to `cms.verify`.
+ * @opts trustAnchors the roots you accept, forwarded to `cms.verify`; supplying them is what makes
+ *                    `trusted` answerable. Certificate DER or anchor tuples.
+ * @opts time         the instant the signer's chain is judged at (default now). Only read with `trustAnchors`.
+ * @opts requiredEku  key purposes the SIGNER certificate must carry. Defaults to `["emailProtection"]`.
+ * @opts checkPurpose the purpose the ANCHOR's own trust metadata must permit. Defaults to `"emailProtection"`.
  * @opts strictMicalg reject a `multipart/signed` whose `micalg` disagrees with the SignerInfo digest.
  * @opts legacyHeaderProtection  opt in to detecting a LEGACY RFC 8551 header-protected message (RFC 9788 sec. 4.10): a Cryptographic Payload that is a bare `message/rfc822` wrap with no `hp=` parameter. When set, a precisely-identified legacy message surfaces the inner message's headers under `headerProtection.legacy = { headers, mode, fromMismatch, confidential }` -- `headers` an ordered `[{ name, value }]` array (retaining legally-repeated fields such as `Received`), the mode inferred from the envelope (`clear` here) -- NOT under `protectedHeaders`, and `present` stays `false`. Consuming `headerProtection.legacy.headers` is an explicit choice: a legacy message is structurally indistinguishable from an ordinary forwarded `message/rfc822`, so this is a heuristic (RFC 9788 sec. 4.10.2: "not based on any strong end-to-end guarantees") -- cross-check `legacy.fromMismatch`. Anything not precisely identified (a nested crypto layer, an `hp=` on the inner message, a non-`message/rfc822` payload, a duplicate of a singleton field, or a duplicate Content-Type) reports `legacy: null`. Off by default. The signed-and-encrypted form (RFC 9788 Appendix C.3.17) is a documented gap (`legacy: null` at `decrypt`; surfaces as `clear` only via the caller's re-`verify` step) -- the non-recursive layered API exposes no single seam holding both the inner signature verdict and the outer header section.
  * @example
@@ -611,8 +626,28 @@ async function verify(message, opts) {
   opts = opts || {};
   var ent = mime.parse(message, SmimeError, "smime/bad-mime");
   var ct = ent.contentType;
+  // Forwarded, not re-decided here. This verb documents itself as pki.cms.verify's verdict plus the
+  // MIME surface, so the trust seam that verb offers has to reach it: building the options from
+  // scratch and passing only `certs` would leave a caller naming trust anchors with no way to have
+  // them applied, and a `trusted` that read false for want of ever being asked.
   var vOpts = {};
   if (opts.certs) vOpts.certs = opts.certs;
+  if (opts.trustAnchors != null) {
+    vOpts.trustAnchors = opts.trustAnchors;
+    // Trusted FOR THIS PURPOSE. A chain alone does not make a signer right for email: a
+    // certificate restricted to serverAuth chains to its root perfectly well and is still the
+    // wrong key to have signed a message. RFC 8551 sec. 4.4.4 names emailProtection as the purpose
+    // an S/MIME signer's certificate must carry, so this verb asks for it rather than accepting the
+    // purpose-neutral answer. A caller who means something else says so with `requiredEku`.
+    vOpts.requiredEku = opts.requiredEku != null ? opts.requiredEku : ["emailProtection"];
+    // Both ends of the chain. The EKU above constrains the LEAF; this selects the anchor's own
+    // trust metadata, which pki.path consults only when a purpose is named. A root distributed
+    // with NSS trust bits can be marked untrusted for email while remaining a good TLS root, so
+    // asking only the leaf would let a root explicitly distrusted for email still answer
+    // "trusted" for an email message.
+    vOpts.checkPurpose = opts.checkPurpose != null ? opts.checkPurpose : "emailProtection";
+  }
+  if (opts.time !== undefined) vOpts.time = opts.time;
   if (_isPkcs7(ct.type, "mime")) {
     if (ct.params["smime-type"] && ct.params["smime-type"] !== "signed-data") throw _err("smime/unsupported-type", "unsupported smime-type " + JSON.stringify(ct.params["smime-type"]) + " (only signed-data)");
     var p7m = _decodeCms(ent);
@@ -620,7 +655,7 @@ async function verify(message, opts) {
     var inner;
     try { inner = _toBuf(schemaCms.parse(p7m).encapContentInfo.eContent); }
     catch (e) { throw _err("smime/bad-mime", "the pkcs7-mime SignedData has no encapsulated content", e); }
-    return Object.assign({ valid: res.valid, signers: res.signers, form: "pkcs7-mime", content: inner, micalg: null }, _hpSurface(inner, ent, "clear", res.valid, opts.legacyHeaderProtection === true));
+    return Object.assign({ valid: res.valid, trusted: res.trusted, signers: res.signers, form: "pkcs7-mime", content: inner, micalg: null }, _hpSurface(inner, ent, "clear", res.valid, opts.legacyHeaderProtection === true));
   }
   if (ct.type === "multipart/signed") {
     if (ct.params.protocol && !_isPkcs7(ct.params.protocol, "signature")) throw _err("smime/bad-multipart", "multipart/signed protocol must be application/pkcs7-signature");
@@ -647,7 +682,7 @@ async function verify(message, opts) {
     if (opts.strictMicalg && micalg && _micalgSet(micalg) !== (_micalgOf(p7s) || "")) {
       throw _err("smime/micalg-mismatch", "the multipart/signed micalg " + JSON.stringify(micalg) + " disagrees with the SignerInfo digests");
     }
-    return Object.assign({ valid: res2.valid, signers: res2.signers, form: "multipart/signed", content: parts[0], micalg: micalg }, _hpSurface(parts[0], ent, "clear", res2.valid, opts.legacyHeaderProtection === true));
+    return Object.assign({ valid: res2.valid, trusted: res2.trusted, signers: res2.signers, form: "multipart/signed", content: parts[0], micalg: micalg }, _hpSurface(parts[0], ent, "clear", res2.valid, opts.legacyHeaderProtection === true));
   }
   throw _err("smime/unsupported-type", "not a signed S/MIME message (Content-Type " + JSON.stringify(ct.type) + ")");
 }

package/lib/tsp-sign.js

@@ -604,9 +604,19 @@ function _buildTsaChains(leaf, pool) {
  *   res.valid;     // boolean; pass opts.trustAnchor to also chain the TSA cert to a root
  *   res.genTime;   // Date, read from the verified eContent
  */
+// Every option pki.tsp.verify reads. Adding one here is the only way to make it accepted.
+var _VERIFY_OPTS = { certs: 1, trustAnchor: 1, nonce: 1, reqPolicy: 1, revocationChecker: 1 };
+
 async function verify(token, data, opts) {
   opts = opts || {};
   if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.verify options must be an object");
+  // An unrecognized option is refused rather than ignored. This verb spells its anchor option
+  // SINGULAR -- `trustAnchor`, an anchor tuple -- while pki.cms.verify and pki.cmp.verify spell it
+  // `trustAnchors` and take certificate DER. A caller carrying the plural spelling here would
+  // otherwise get no anchoring and no error: the TSA certificate unchained, `valid: true`, and
+  // nothing to notice it by. Naming the difference at the boundary is the only place it is cheap.
+  guard.identifier.assertKnownKeys(opts, _VERIFY_OPTS, _err, "tsp/bad-input",
+    "pki.tsp.verify has an unknown option (note the anchor option here is `trustAnchor`, singular, an anchor tuple -- not the `trustAnchors` certificate list pki.cms.verify takes) ");
   if (opts.certs != null && (!Array.isArray(opts.certs) || !opts.certs.every(function (c) { return Buffer.isBuffer(c) || c instanceof Uint8Array; }))) {
     throw _err("tsp/bad-input", "pki.tsp.verify opts.certs must be an array of DER certificate Buffers");   // a bad element is a caller error, never silently dropped
   }

package/lib/validator-cose.js

@@ -61,7 +61,12 @@ var ALG_PROFILE = {
   "-7": { kty: 2, crv: 1 }, "-35": { kty: 2, crv: 2 }, "-36": { kty: 2, crv: 3 },
   "-9": { kty: 2, crv: 1 }, "-51": { kty: 2, crv: 2 }, "-52": { kty: 2, crv: 3 },
   "-8": { kty: 1, crv: 6 }, "-19": { kty: 1, crv: 6 }, "-53": { kty: 1, crv: 7 },
-  "-257": { kty: 3 }, "-258": { kty: 3 }, "-259": { kty: 3 }, "-37": { kty: 3 }, "-65535": { kty: 3 },
+  // RSASSA-PSS at all three strengths. PS256 alone left PS384/PS512 refused at PARSE time on a key
+  // that is perfectly well-formed -- the same bytes accepted under -37 -- so the refusal blamed the
+  // key rather than the algorithm, and a relying party migrating credential rows written by another
+  // implementation could not tell which of its stored keys this verifier would decline, or why.
+  "-257": { kty: 3 }, "-258": { kty: 3 }, "-259": { kty: 3 },
+  "-37": { kty: 3 }, "-38": { kty: 3 }, "-39": { kty: 3 }, "-65535": { kty: 3 },
 };
 
 // credentialKey(node, E, code) -> the decoded + validated credential public key
@@ -72,7 +77,10 @@ var ALG_PROFILE = {
 // @enforced-by validator-shape-reinlined
 // @validator-shape kty\s*===\s*2n
 // @validator-shape EC2_CRV_LEN|ALG_PROFILE
-function credentialKey(node, E, code) {
+// `unsupportedCode` is OPTIONAL and names the code raised when the key is well-formed but its
+// algorithm is not one this verifier implements -- a different fact from a malformed key. Omit it
+// and that case keeps raising `code`, so an existing caller sees no change.
+function credentialKey(node, E, code, unsupportedCode) {
   function bad(msg, cause) { return new E(code, msg, cause); }
   if (!node || node.majorType !== 5) throw bad("a COSE_Key must be a CBOR map (RFC 9052 sec. 7)");
   // Every parameter read maps a wrong-type cbor/* fault to the caller's domain -- a
@@ -111,7 +119,12 @@ function credentialKey(node, E, code) {
   if (node.children.length !== expectedParams) throw bad("the COSE_Key carries parameters beyond the canonical set for its key type (WebAuthn sec. 6.5.1)");
   // PROFILE: the declared alg must match the key type (and, for EC2, the curve).
   var prof = ALG_PROFILE[String(key.alg)];
-  if (!prof) throw bad("unsupported credential key algorithm " + key.alg);
+  // An algorithm this verifier does not implement is NOT a malformed key. The key can be perfectly
+  // well-formed -- the same bytes may parse under a neighbouring algorithm id -- and a relying
+  // party migrating credential rows written elsewhere needs to tell "I cannot check this
+  // algorithm" from "these bytes are wrong", since only one of those is fixable by re-registering.
+  // Callers that do not distinguish the two pass one code and keep the previous behaviour.
+  if (!prof) throw new E(unsupportedCode || code, "unsupported credential key algorithm " + key.alg);
   if (prof.kty !== key.kty) throw bad("credential key algorithm " + key.alg + " is inconsistent with key type " + key.kty);
   if (prof.crv != null && prof.crv !== key.crv) throw bad("credential key algorithm " + key.alg + " requires a different curve");
   // ON-CURVE: import the SPKI so OpenSSL validates the EC point on its curve. An off-curve

package/lib/webauthn.js

@@ -73,7 +73,7 @@ function _isInteger(node) { return !!node && !node.constructed && node.tagClass
 // step rejects the attestation before the signature is evaluated. EdDSA (-8/-19/-53) is
 // absent by design: a TPM 2.0 AIK never signs with EdDSA, so such an attestation is
 // correctly refused.
-var COSE_ALG_HASH = { "-7": "sha256", "-9": "sha256", "-257": "sha256", "-37": "sha256", "-35": "sha384", "-51": "sha384", "-258": "sha384", "-36": "sha512", "-52": "sha512", "-259": "sha512", "-65535": "sha1" };
+var COSE_ALG_HASH = { "-7": "sha256", "-9": "sha256", "-257": "sha256", "-37": "sha256", "-35": "sha384", "-51": "sha384", "-258": "sha384", "-38": "sha384", "-36": "sha512", "-52": "sha512", "-259": "sha512", "-39": "sha512", "-65535": "sha1" };
 function _coseAlgHash(alg, E) {
   var h = COSE_ALG_HASH[String(alg)];
   if (!h) throw E("webauthn/unsupported-algorithm", "no hash mapping for COSE algorithm " + alg);
@@ -141,7 +141,54 @@ function _parseAuthData(buf, E) {
 // The complete COSE credential-key conformance rule set (kty/alg/crv/length/canonical/
 // profile/on-curve) lives in validator-cose, composed here so every credential key
 // routes through the one home -- never a per-format re-derivation of a partial subset.
-function _decodeCoseKey(node) { return validator.cose.credentialKey(node, WebauthnError, "webauthn/bad-cose-key"); }
+function _decodeCoseKey(node) {
+  return validator.cose.credentialKey(node, WebauthnError, "webauthn/bad-cose-key", "webauthn/unsupported-algorithm");
+}
+
+/**
+ * @primitive  pki.webauthn.parseCoseKey
+ * @signature  pki.webauthn.parseCoseKey(bytes) -> object
+ * @since      0.5.2
+ * @status     stable
+ * @spec       RFC 9052, W3C WebAuthn Level 3 sec. 6.5.1
+ * @related    pki.webauthn.verify, pki.webauthn.verifyAssertion
+ *
+ * Decode a bare COSE_Key -- the credential public key a relying party stored at
+ * registration -- back into the object `verifyAssertion` takes. `pki.webauthn.verify`
+ * returns that object, but the durable form is bytes: the object carries `Buffer`
+ * values, so a JSON round trip through a datastore yields
+ * `{"type":"Buffer","data":[...]}` rather than the object that went in, and existing
+ * credential stores already hold COSE bytes whoever wrote them. Without this the only
+ * routes into the decoder were `parseAttestationObject` and `parseAuthenticatorData`,
+ * both of which parse a CONTAINING structure -- so recovering a stored key meant
+ * fabricating an authenticatorData that never existed.
+ *
+ * The same validation the attestation path applies: the key type, the algorithm, the
+ * curve, and the coordinates are checked, and anything that is not a credential COSE
+ * key is refused with `webauthn/bad-cose-key`. `verifyAssertion` accepts either form
+ * for `credentialPublicKey`, so calling this first is a convenience rather than a step.
+ *
+ * @example
+ *   // requires: `attestationObject` / `clientDataHash` -- what a browser returns from a
+ *   // registration ceremony
+ *   var reg = await pki.webauthn.verify(attestationObject, clientDataHash, {});
+ *   var stored = reg.credentialPublicKeyBytes;   // the form a credential row holds
+ *   // ... at a login months later, read it back:
+ *   var key = pki.webauthn.parseCoseKey(stored);
+ *   key.alg;   // -> -7 for ES256
+ *   // verifyAssertion takes either form, so this parse is a convenience, not a step:
+ *   // pass `stored` straight as its credentialPublicKey.
+ */
+function parseCoseKey(bytes) {
+  var buf = _snapshotBytes(bytes, "the COSE key");
+  if (!Buffer.isBuffer(buf)) {
+    throw _err("webauthn/bad-input", "parseCoseKey takes the stored COSE key bytes (a Buffer, TypedArray or ArrayBuffer)");
+  }
+  var node;
+  try { node = cbor.decode(buf); }
+  catch (e) { throw _err("webauthn/bad-cose-key", "the stored credential key is not decodable CBOR", e); }
+  return _decodeCoseKey(node);
+}
 
 // ---- signature verification bridge ------------------------------------------
 
@@ -165,7 +212,11 @@ var COSE_ALG = {
   "-257": { imp: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, verify: { name: "RSASSA-PKCS1-v1_5" }, ecdsa: 0 },
   "-258": { imp: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-384" }, verify: { name: "RSASSA-PKCS1-v1_5" }, ecdsa: 0 },
   "-259": { imp: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-512" }, verify: { name: "RSASSA-PKCS1-v1_5" }, ecdsa: 0 },
+  // RSASSA-PSS. The salt length is the hash length, the profile WebCrypto verifies and the one
+  // RFC 8230 sec. 2 fixes for the COSE PS* identifiers -- 32 / 48 / 64 bytes for SHA-256/384/512.
   "-37":  { imp: { name: "RSA-PSS", hash: "SHA-256" }, verify: { name: "RSA-PSS", saltLength: 32 }, ecdsa: 0 },
+  "-38":  { imp: { name: "RSA-PSS", hash: "SHA-384" }, verify: { name: "RSA-PSS", saltLength: 48 }, ecdsa: 0 },
+  "-39":  { imp: { name: "RSA-PSS", hash: "SHA-512" }, verify: { name: "RSA-PSS", saltLength: 64 }, ecdsa: 0 },
   // RS1 (RSASSA-PKCS1-v1_5 / SHA-1): a legacy COSE algorithm real Windows Hello TPM
   // authenticators emit in their attestation statement. VERIFY-only support -- the
   // toolkit never signs with SHA-1; it must still evaluate the attestations that
@@ -1139,6 +1190,11 @@ function _result(fmt, attestationType, chain, att) {
     aaguid: att.authData.aaguid,
     credentialId: att.authData.credentialId,
     credentialPublicKey: att.authData.credentialPublicKey,
+    // The same key in the form that SURVIVES STORAGE. The decoded object carries Buffers, so a JSON
+    // round trip through a datastore returns {"type":"Buffer","data":[...]} rather than what went
+    // in; the COSE bytes are what a credential row actually holds. Returning only the object left
+    // the caller re-parsing the attestation object to recover bytes this call had already isolated.
+    credentialPublicKeyBytes: att.authData.credentialPublicKeyBytes,
     signCount: att.authData.signCount,
     flags: att.authData.flags,
   };
@@ -1176,7 +1232,7 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
 
 /**
  * @primitive pki.webauthn.verify
- * @signature pki.webauthn.verify(attestationObject, clientDataHash, opts) -> Promise<{ attestationVerified, fmt, attestationType, trustPath, anchoredTo, anchoredElements, aaguid, credentialId, credentialPublicKey, signCount, flags, bindingChecked }>
+ * @signature pki.webauthn.verify(attestationObject, clientDataHash, opts) -> Promise<{ attestationVerified, fmt, attestationType, trustPath, anchoredTo, anchoredElements, aaguid, credentialId, credentialPublicKey, credentialPublicKeyBytes, signCount, flags, bindingChecked }>
  * @since 0.2.5
  * @status stable
  * @spec W3C WebAuthn Level 3 sec. 8 / sec. 7.1
@@ -1201,7 +1257,12 @@ function _checkAndroidKeyDescription(cert, clientDataHash) {
  * them against the state only the relying party has.
  *
  * The verdict also carries what a relying party must STORE to run a later login:
- * `credentialId`, `credentialPublicKey` and the initial `signCount`.
+ * `credentialId`, `credentialPublicKey` and the initial `signCount`. The credential key
+ * comes back in both forms: the decoded object, and `credentialPublicKeyBytes`, which is
+ * what a credential row should hold -- the object carries `Buffer` values, so a JSON round
+ * trip through a datastore returns `{"type":"Buffer","data":[...]}` rather than the object
+ * that went in. `pki.webauthn.parseCoseKey` reads those bytes back, and
+ * `verifyAssertion` accepts either form.
  *
  * @intro This verifies the attestation STATEMENT -- the signature and the format's
  *   structural bindings (the x5c leaf key == credential key, the apple nonce, the tpm
@@ -1937,7 +1998,15 @@ function _snapshotAssertion(input) {
       out[f] = guard.bytes.snapshotSource(out[f], WebauthnError, "webauthn/bad-input", f);
     }
   });
-  if (_isPlainObject(out.credentialPublicKey)) {
+  // The BYTES form first. A Buffer satisfies the plain-object test below, so leaving it to that
+  // branch copies its numeric indices into a `{0:.., 1:..}` object that is no longer a key at all
+  // -- the stored credential silently becoming something the SPKI builder cannot read. It is
+  // snapshotted here for the same reason the other byte inputs are: it is read after a yield.
+  if (Buffer.isBuffer(out.credentialPublicKey) || ArrayBuffer.isView(out.credentialPublicKey) ||
+      out.credentialPublicKey instanceof ArrayBuffer) {
+    out.credentialPublicKey = guard.bytes.snapshotSource(out.credentialPublicKey, WebauthnError,
+      "webauthn/bad-input", "credentialPublicKey");
+  } else if (_isPlainObject(out.credentialPublicKey)) {
     var key = {}, kk;
     for (kk in out.credentialPublicKey) {
       if (!Object.prototype.hasOwnProperty.call(out.credentialPublicKey, kk)) continue;
@@ -2000,9 +2069,16 @@ function verifyAssertion(input) {
       }
       clientDataHash = Buffer.from(input.clientDataHash);
     }
+    // Either form a relying party can be holding. `verify` hands back the parsed object, but the
+    // durable form is BYTES: the object carries Buffers, so a JSON round trip through a datastore
+    // returns {"type":"Buffer","data":[...]} rather than what went in, and every existing credential
+    // store already holds the COSE bytes. Accepting only the object made a caller fabricate an
+    // authenticatorData that never existed just to reach their own key.
     var coseKey = input.credentialPublicKey;
-    if (!_isPlainObject(coseKey)) {
-      throw _err("webauthn/bad-input", "credentialPublicKey must be the stored COSE key object");
+    if (Buffer.isBuffer(coseKey) || ArrayBuffer.isView(coseKey) || coseKey instanceof ArrayBuffer) {
+      coseKey = parseCoseKey(coseKey);
+    } else if (!_isPlainObject(coseKey)) {
+      throw _err("webauthn/bad-input", "credentialPublicKey must be the stored COSE key -- the object pki.webauthn.verify returned, or its COSE bytes");
     }
     var bindingChecked = _applyBindings(authData, coseKey, input);
     // The counter's SHAPE is a config-time question and is answered here; whether it
@@ -2057,6 +2133,7 @@ module.exports = {
   parseAttestationObject: parseAttestationObject,
   parseAuthenticatorData: parseAuthenticatorData,
   parseClientData: parseClientData,
+  parseCoseKey: parseCoseKey,
   verify: verify,
   verifyAssertion: verifyAssertion,
   verifyMetadataBlob: mds.verifyMetadataBlob,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",
@@ -76,6 +76,6 @@
   "devDependencies": {
     "c8": "12.0.0",
     "esbuild": "0.28.1",
-    "eslint": "10.7.0"
+    "eslint": "10.8.1"
   }
 }

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:350d591c-d7d9-431c-8902-3859e2fdad78",
+  "serialNumber": "urn:uuid:36c2730b-a6b9-424c-9247-67c6cd2e2db1",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-12T22:09:02.062Z",
+    "timestamp": "2026-08-13T03:02:25.353Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.5.1",
+      "bom-ref": "@blamejs/pki@0.5.2",
       "type": "application",
       "name": "pki",
-      "version": "0.5.1",
+      "version": "0.5.2",
       "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.5.1",
+      "purl": "pkg:npm/%40blamejs/pki@0.5.2",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.5.1",
+      "ref": "@blamejs/pki@0.5.2",
       "dependsOn": []
     }
   ]