@blamejs/pki 0.5.7 → 0.5.9

package/lib/smime.js

@@ -13,7 +13,7 @@
  *   layer. `sign` wraps a MIME entity as a signed S/MIME message and `verify`
  *   unwraps and verifies one, in both forms: `multipart/signed` (clear-signed --
  *   the content stays readable, a detached CMS signature rides alongside) and
- *   `application/pkcs7-mime` (opaque -- the whole entity is a base64 CMS
+ *   `application/pkcs7-mime` (opaque, where the whole entity is a base64 CMS
  *   SignedData). `encrypt` envelopes a MIME entity as an opaque
  *   `application/pkcs7-mime` message and `decrypt` opens one -- `authEnveloped-data`
  *   (AES-GCM, confidentiality AND integrity, the default) or `enveloped-data`
@@ -28,7 +28,7 @@
  * @card
  *   Assemble, verify, and encrypt RFC 8551 S/MIME messages (signed:
  *   multipart/signed + application/pkcs7-mime; encrypted: enveloped-data +
- *   authEnveloped-data) over any CMS signer / recipient -- fail-closed,
+ *   authEnveloped-data) over any CMS signer / recipient, fail-closed,
  *   algorithm-agnostic.
  */
 
@@ -36,6 +36,9 @@ var frameworkError = require("./framework-error.js");
 var mime = require("./mime.js");
 var cms = require("./cms-verify.js");
 var schemaCms = require("./schema-cms.js");
+var schemaX509 = require("./schema-x509.js");
+var pkix = require("./schema-pkix.js");
+var oid = require("./oid.js");
 var guard = require("./guard-all.js");
 var C = require("./constants.js");
 var nodeCrypto = require("crypto");
@@ -46,14 +49,14 @@ function _err(code, msg, cause) { return new SmimeError(code, msg, cause); }
 
 // ---- the option surface each verb accepts -----------------------------------
 //
-// A misspelled option is the one input that reads as an omission rather than as a value: nothing is
+// A misspelled option is the one input that reads as an omission, never as a value: nothing is
 // out of range, nothing fails to parse, and the caller who asked for something stricter silently
 // gets the looser default. `protectHeaders` misspelled sends the headers a caller meant to protect
 // as ordinary display copies; `strictMicalg` misspelled accepts the mismatch it was set to reject;
 // `entity` misspelled wraps a caller's complete MIME entity inside another one.
 //
-// The tables are per VERB, not per module, because the surfaces genuinely differ -- `form` means
-// something on sign and nothing on encrypt -- and a merged table would accept each verb's options at
+// The tables are per verb, not per module, because the surfaces genuinely differ (`form` means
+// something on sign and nothing on encrypt) and a merged table would accept each verb's options at
 // every other one, which is the same silence in a wider form. Each is the keys that verb's body and
 // the helpers it hands `opts` to actually read: the value goes through _entityBytes, _cmsSignOpts or
 // _cmsEncryptOpts as readily as it is read here, so a table built from the verb's own lines alone
@@ -64,7 +67,7 @@ var SIGN_OPTS = {
 };
 var VERIFY_OPTS = {
   certs: 1, trustAnchors: 1, time: 1, requiredEku: 1, checkPurpose: 1, strictMicalg: 1,
-  legacyHeaderProtection: 1,
+  legacyHeaderProtection: 1, expectedSender: 1,
 };
 var ENCRYPT_OPTS = {
   entity: 1, contentType: 1, protectHeaders: 1, headers: 1, hcp: 1,
@@ -90,12 +93,12 @@ function _isPkcs7(type, kind) {
 
 // The RFC 8551 sec. 3.4.3.2 micalg name for a CMS digest (schema-cms surfaces "sha256" etc.).
 // RFC 8551 sec. 3.4.3.2 micalg names, extended with the SHAKE names FIPS 204/205 CMS signers digest
-// with (RFC 8702). An unknown digest passes through verbatim -- never regex-mangled (a blind
+// with (RFC 8702). An unknown digest passes through verbatim and is never regex-mangled (a blind
 // `sha`->`sha-` would corrupt "shake256" into "sha-ke256").
 var MICALG = { sha1: "sha-1", sha224: "sha-224", sha256: "sha-256", sha384: "sha-384", sha512: "sha-512", md5: "md5", shake128: "shake128", shake256: "shake256" };
 
 // The exact bytes to sign: the caller's content wrapped as a MIME entity (text/plain by default) in
-// its canonical form, OR -- when opts.entity is set -- the caller's own complete MIME entity, canonical.
+// its canonical form, or, when opts.entity is set, the caller's own complete MIME entity, canonical.
 function _entityBytes(content, opts) {
   var raw = guard.bytes.view(content, SmimeError, "smime/bad-input", "content");
   if (opts.entity) return mime.canonicalize(raw, SmimeError, "smime/bad-mime");
@@ -117,7 +120,7 @@ function _is7bit(buf) { for (var i = 0; i < buf.length; i++) if (buf[i] > 0x7f)
 // -Disposition / -ID / -Description / -Language / -Location / ...). These describe the specific MIME part --
 // the library sets them -- so they are never protected as Non-Structural fields (rejected at the producer) nor
 // surfaced in the authenticated protectedHeaders set on verify. The prefix rule is the RFC definition itself,
-// so it matches EVERY Content-* field (not just an enumerated subset) and is not a prototype-key lookup (a
+// so it matches every Content-* field (not just an enumerated subset) and is not a prototype-key lookup (a
 // field named "constructor" / "toString" is simply not Structural).
 function _isStructural(lname) {
   return lname === "mime-version" || lname.indexOf("content-") === 0;
@@ -131,7 +134,7 @@ function _hpHeaderList(headers) {
   if (Array.isArray(headers)) {
     headers.forEach(function (h) {
       if (!h || typeof h !== "object") throw _err("smime/bad-input", "each opts.headers entry must be { name, value }");
-      // Read name + value ONCE each -- an accessor / Proxy could return a different value on a second read, so
+      // Read name + value once each: an accessor / Proxy could return a different value on a second read, so
       // the snapshot (not the live property) is what both the signed inner header and the outer display copy use.
       var name = h.name, v = h.value;
       if (typeof name !== "string") throw _err("smime/bad-input", "each opts.headers entry must be { name, value }");
@@ -146,7 +149,7 @@ function _hpHeaderList(headers) {
   // describes the MIME structure -- the library sets it -- so a caller passing one would duplicate it on the
   // payload root. And a REPEATED field name is rejected here at the PRODUCER: a repeated protected field is an
   // unsupported shape (verify fails closed on the ambiguity), so the library never emits a message it cannot
-  // re-consume. Reject both rather than emit a malformed / self-inconsistent entity.
+  // re-consume. Reject both; never emit a malformed / self-inconsistent entity.
   var seen = Object.create(null);
   out.forEach(function (h) {
     var ln = h.name.toLowerCase();
@@ -163,7 +166,7 @@ function _hpHeaderList(headers) {
 // The Header Confidentiality Policy for an OUTER header of an encrypted-HP message. hcp_baseline (RFC 9788
 // sec. 3.2.1, the default) obscures Subject to "[...]" and REMOVES Comments / Keywords (null);
 // hcp_no_confidentiality leaves every field visible (opt-in only). This is the sec. 3.2.1 pseudocode
-// VERBATIM: Bcc is intentionally NOT stripped -- RFC 9788 sec. 11.4 explains that removing Bcc during
+// Verbatim: Bcc is intentionally not stripped. RFC 9788 sec. 11.4 explains that removing Bcc during
 // encryption can break deliverability to a Bcc'd recipient, so the choice is left to the caller (omit Bcc
 // from opts.headers to keep it out of the plaintext outer headers).
 function _applyHcp(name, value, hcp) {
@@ -175,7 +178,7 @@ function _applyHcp(name, value, hcp) {
 }
 
 // The outer display header list: for "clear" (signed) the fields are copied verbatim; for "cipher"
-// (encrypted) each passes through the HCP -- a null result removes the field (it lives only in the ciphertext).
+// (encrypted) each passes through the HCP, where a null result removes the field (it lives only in the ciphertext).
 function _outerHeaderList(list, mode, hcp) {
   var policy = hcp == null ? "hcp_baseline" : hcp;
   if (policy !== "hcp_baseline" && policy !== "hcp_no_confidentiality") throw _err("smime/bad-input", "unknown opts.hcp policy " + JSON.stringify(hcp) + " (only \"hcp_baseline\" or \"hcp_no_confidentiality\")");
@@ -193,13 +196,13 @@ function _outerHeaderList(list, mode, hcp) {
 
 // Build the inner Cryptographic Payload for a header-protected message: the caller's body wrapped with its
 // Content-Type (gaining ; hp="<mode>") + Content-Transfer-Encoding + the protected fields inlined, canonical.
-// hpList is the ONE normalized snapshot of opts.headers (see the caller) -- the SAME list feeds the signed/
+// hpList is the single normalized snapshot of opts.headers (see the caller), and that same list feeds the signed/
 // encrypted inner header set here and the outer display copy, so an accessor / Proxy cannot make them diverge.
 // outerList is the HCP-processed outer set (_outerHeaderList) -- for a cipher payload it also drives the
 // HP-Outer records embedded here.
 function _protectedInnerEntity(content, opts, mode, hpList, outerList) {
   // Header protection inlines the protected fields on the payload ROOT it builds, so a caller-supplied
-  // complete entity (opts.entity) is an unsupported combination -- reject it rather than silently bury the
+  // complete entity (opts.entity) is an unsupported combination: reject it, and never silently bury the
   // caller's entity (its own Content-Type + headers) beneath a new default text/plain wrapper.
   if (opts.entity) throw _err("smime/bad-input", "opts.entity is not supported with protectHeaders -- pass raw content + opts.contentType");
   var raw = guard.bytes.view(content, SmimeError, "smime/bad-input", "content");
@@ -212,7 +215,7 @@ function _protectedInnerEntity(content, opts, mode, hpList, outerList) {
   hpList.forEach(function (h) { fields.push(h); });
   // RFC 9788 sec. 2.2 / sec. 5.2.1 step 5.v: an ENCRYPTED header-protected payload documents inside the
   // ciphertext, as HP-Outer records, every Non-Structural field it deliberately left visible in the outer
-  // (unprotected) header section -- "HP-Outer: <name>: <outer-value>". A field the HCP removed has NO HP-Outer
+  // (unprotected) header section, as "HP-Outer: <name>: <outer-value>". A field the HCP removed has no HP-Outer
   // record; its absence authenticates that it was made confidential by removal. Signed-only (clear) payloads
   // carry no HP-Outer (sec. 2.2: "not relevant for signed-only messages").
   if (mode === "cipher") {
@@ -223,7 +226,7 @@ function _protectedInnerEntity(content, opts, mode, hpList, outerList) {
 
 // The outer header prefix (display copies + MIME-Version) that precedes the Cryptographic Envelope's
 // Content-Type in a header-protected message. Each field is guard-validated (no CR/LF/NUL injection). list is
-// the SAME HCP-processed outer set the inner entity's HP-Outer records were built from.
+// the same HCP-processed outer set the inner entity's HP-Outer records were built from.
 function _outerPrefix(list) {
   var s = "";
   for (var i = 0; i < list.length; i++) {
@@ -249,15 +252,15 @@ function _declaresHp(content) {
   var s = content.toString("latin1");
   var m = s.match(/\r\n\r\n/);
   var head = (m ? s.slice(0, m.index) : s).replace(/\r\n[ \t]+/g, " ");
-  // Detect hp by composing mime.paramCount -- the SAME comment- + quoted-string-aware tokenizer the parser
+  // Detect hp by composing mime.paramCount, the same comment- + quoted-string-aware tokenizer the parser
   // uses -- over each Content-Type field, so the probe never diverges from mime.parse: a leading-whitespace
   // or before-colon field name is matched (the parser trims it), while an hp= inside a MIME comment or a
-  // quoted value is NOT a parameter (so an ordinary Content-Type cannot opt a message into HP processing). A
+  // quoted value is not a parameter (so an ordinary Content-Type cannot opt a message into HP processing). A
   // real hp on ANY Content-Type line is detected; a duplicate Content-Type is rejected downstream.
   var cts = head.match(/^[ \t]*content-type[ \t]*:[^\r\n]*/gim);
   if (!cts) return false;
   for (var i = 0; i < cts.length; i++) {
-    // hasParam (not paramCount): a payload that names the hp attribute WITHOUT a value ("...; hp") still
+    // hasParam (not paramCount): a payload that names the hp attribute without a value ("...; hp") still
     // CLAIMS header protection -- detect it so _hpSurface fails closed on the malformed declaration rather
     // than silently downgrading it to unprotected.
     if (mime.hasParam(cts[i].replace(/^[ \t]*content-type[ \t]*:/i, ""), "hp")) return true;
@@ -267,17 +270,20 @@ function _declaresHp(content) {
 
 // A fresh not-protected surface (returned when no header protection is present or detection fails soft). A NEW
 // object each call -- the caller Object.assign()s it onto the verify/decrypt result, so it must not be shared.
-// `present` + `protectedHeaders` describe ONLY cryptographically-declared (hp=) protection; `legacy` is null
-// unless an opt-in legacy RFC8551HP inference succeeded (then it carries its own headers/mode/etc. -- see below).
-function _noneSurface() { return { protectedHeaders: null, headerProtection: { present: false, mode: null, fromMismatch: false, confidential: [], legacy: null } }; }
+// `present` + `protectedHeaders` describe only cryptographically-declared (hp=) protection; `legacy` is null
+// unless an opt-in legacy RFC8551HP inference succeeded (then it carries its own headers/mode/etc.; see below).
+// No header protection means no protected From to compare the outer one against, so the
+// mismatch question is unanswered rather than answered "no" -- null, matching every other
+// field here that reports an absent property.
+function _noneSurface() { return { protectedHeaders: null, headerProtection: { present: false, mode: null, fromMismatch: null, confidential: [], legacy: null } }; }
 
 // Count the Content-Type fields in a parsed header list. A structure with more than one is AMBIGUOUS: mime.parse
-// surfaces only the FIRST via contentType, so an hp= parameter or a Cryptographic-Layer media type on a LATER
-// field would be invisible to the classification -- both the standard HP path and the legacy path fail closed on it.
+// surfaces only the first via contentType, so an hp= parameter or a Cryptographic-Layer media type on a later
+// field would be invisible to the classification, and both the standard HP path and the legacy path fail closed on it.
 function _contentTypeCount(headers) { var n = 0; headers.forEach(function (h) { if (h.lname === "content-type") n++; }); return n; }
 
 // Header fields that must not sensibly repeat: the RFC 5322 sec. 3.6 max-1 originator/destination/identification
-// fields, plus Return-Path (the envelope sender -- RFC 5322 sec. 3.6 groups it under trace, but RFC 5321 sec. 4.4
+// fields, plus Return-Path (the envelope sender; RFC 5322 sec. 3.6 groups it under trace, but RFC 5321 sec. 4.4
 // restricts a delivered message to a single one). A duplicate of one of these is a malformed / ambiguous set (a
 // consumer could pick a different sender / subject); a duplicate of any OTHER field (Received and the other
 // trace fields, Resent-*, Comments, Keywords, and optional / X-* fields) is legitimately repeatable in a real
@@ -287,14 +293,14 @@ var RFC5322_SINGLETON = new Set(["date", "from", "sender", "reply-to", "to", "cc
 
 // Extract the Non-Structural protected fields from a recovered inner header list. Shared by the standard HP path
 // (over the Cryptographic Payload root) and the legacy path (over the message/rfc822 inner message, sec. 4.10).
-// Returns { protectedHeaders (UTF-8 map, last-wins -- the ergonomic single-value view surfaced by the standard
-// path), entries (an ORDERED array of every { name, value, raw } occurrence -- a real message repeats trace
+// Returns { protectedHeaders (UTF-8 map, last-wins, the ergonomic single-value view surfaced by the standard
+// path), entries (an ordered array of every { name, value, raw } occurrence, since a real message repeats trace
 // fields, and a last-wins collapse would drop all but one), innerFrom, refouter (HP-Outer records), dup (any
 // duplicate field name), dupSingleton (a duplicate of an RFC 5322 singleton field) }.
 function _extractProtected(headerList) {
   // mime.parse decodes the header block as latin1 (byte-preserving), so a protected value emitted as UTF-8
   // (RFC 6532, the guard permits it) is re-decoded latin1->UTF-8 here to round-trip intact. protectedHeaders
-  // surfaces the exact authenticated field body (rawValue: leading/trailing whitespace preserved), NOT a
+  // surfaces the exact authenticated field body (rawValue: leading/trailing whitespace preserved), and not a
   // trimmed value that would diverge from the signed octets.
   var protectedHeaders = Object.create(null), innerFrom = null, seen = Object.create(null), dup = null, dupSingleton = null;
   var entries = [];    // every Non-Structural { name, value } occurrence, in order -- retains legally-repeated fields
@@ -302,11 +308,11 @@ function _extractProtected(headerList) {
   headerList.forEach(function (h) {
     if (_isStructural(h.lname)) return;
     if (h.lname === "hp-outer") {
-      // RFC 9788 sec. 4.2.1 step 4.i: split the HP-Outer value on the FIRST colon into (name, outer-value)
+      // RFC 9788 sec. 4.2.1 step 4.i: split the HP-Outer value on the first colon into (name, outer-value)
       // -> refouter. The value is kept BYTE-PRESERVING (latin1), never UTF-8-decoded, because the sec. 4.3.1
       // confidentiality comparison must be octet-exact (a lossy decode maps distinct invalid octets 0x80/0x81
       // to one replacement char, which would mis-classify an obscured field as exposed and drop it from the
-      // confidential set). HP-Outer is NEVER surfaced as a protected header nor counted toward the duplicate
+      // confidential set). HP-Outer is never surfaced as a protected header nor counted toward the duplicate
       // check (sec. 2.2: it "can appear multiple times"). A valueless HP-Outer (no inner colon) is ignored.
       var ci = h.rawValue.indexOf(":");
       if (ci >= 0) refouter.push({ name: h.rawValue.slice(0, ci).trim().toLowerCase(), value: h.rawValue.slice(ci + 1).trim() });
@@ -326,17 +332,17 @@ function _extractProtected(headerList) {
 }
 
 // RFC 9788 sec. 4.3.1: a protected field occurrence is end-to-end confidential (encrypted-only) unless a
-// `refouter` record carries its EXACT name + value -- i.e. that value was copied verbatim to the visible outer
+// `refouter` record carries its EXACT name + value, meaning that value was copied verbatim to the visible outer
 // section. The match is per-OCCURRENCE and MULTISET (each outer record accounts for at most one inside
 // occurrence), so a legally-repeated field with one obscured value and one exposed value (Keywords: secret then
-// Keywords: public, outer exposing only "public") still reports the name confidential -- a last-wins collapse
+// Keywords: public, outer exposing only "public") still reports the name confidential, because a last-wins collapse
 // would drop the hidden "secret" and let a caller leak it. A field name is confidential if ANY of its
 // occurrences is unexposed. The comparison is octet-exact (latin1 raw), never lossy-decoded. For the standard
 // path `refouter` is the HP-Outer records; for the legacy path it is the actual outer Header Section (part A).
 function _computeConfidential(entries, refouter) {
   // Index the outer occurrences by (normalized name -> value -> available count) so the multiset comparison is
   // O(N + M), not a per-occurrence rescan of the outer array: matching N identical exposed occurrences would
-  // otherwise be N(N+1)/2 comparisons -- a DoS an attacker could drive toward the 16 MiB section cap. A two-level
+  // otherwise be N(N+1)/2 comparisons: a DoS an attacker could drive toward the 16 MiB section cap. A two-level
   // Map (never a plain object) so an attacker-chosen name/value like "__proto__" cannot confuse the lookup.
   var byName = new Map();
   refouter.forEach(function (r) {
@@ -352,18 +358,24 @@ function _computeConfidential(entries, refouter) {
   return confidential;
 }
 
-// Inspect EVERY outer From (outerEnt.header returns only the FIRST; an attacker may append a second, forged From
+// Inspect every outer From (outerEnt.header returns only the first; an attacker may append a second, forged From
 // that a MUA displays). A mismatch is ANYTHING but exactly one outer From equal to the protected one: a removed
 // outer From, a duplicate, or a differing value all flag tampering of the displayed sender.
+// null when there was nothing to compare, true/false only when a comparison ran. A bare
+// false cannot distinguish "the outer From agrees with the protected one" from "no inner
+// From was protected, so no comparison happened" -- and the second is the common case,
+// which is how `!fromMismatch` came to read as a passed check on a message where nothing
+// was checked at all.
 function _computeFromMismatch(innerFrom, outerEnt) {
+  if (innerFrom == null) return null;
   var outerFroms = [];
   outerEnt.headers.forEach(function (h) { if (h.lname === "from") outerFroms.push(h.value.trim()); });   // byte-preserving (latin1)
-  return innerFrom != null && (outerFroms.length !== 1 || outerFroms[0] !== innerFrom.trim());
+  return outerFroms.length !== 1 || outerFroms[0] !== innerFrom.trim();
 }
 
 // Is this (lowercased) media type a Cryptographic Layer (RFC 9788 sec. 4.10.1)? Conservative: any
 // application/pkcs7-mime (incl. an OpenSSL x-pkcs7-mime, or a compressed-data layer) plus multipart/signed and
-// multipart/encrypted. Mis-classifying part D as a layer only degrades legacy detection to none -- the safe direction.
+// multipart/encrypted. Mis-classifying part D as a layer only degrades legacy detection to none, the safe direction.
 function _isCryptoLayer(type) {
   // `type` is the already-lowercased media type from mime.parse's _parseStructured; _isPkcs7 guards the
   // null/undefined case internally, so no local `|| ""` fallback is needed (and no dead branch is introduced).
@@ -378,19 +390,19 @@ function _outerRefouter(outerEnt) {
   return r;
 }
 
-// RFC 9788 sec. 4.10 backward compatibility: identify + surface a LEGACY RFC8551HP message -- a Cryptographic
+// RFC 9788 sec. 4.10 backward compatibility: identify + surface a legacy RFC8551HP message, a Cryptographic
 // Envelope whose payload is a bare message/rfc822 object carrying the real headers, with NO hp= parameter. This
-// is DETECT-ONLY (sec. 4.10: "An MUA MUST NOT generate an RFC8551HP message ... MAY try to render") and OPT-IN
-// (`enabled`). Identification (sec. 4.10.1) is the four conjunctive conditions C1-C4; every failure -- an
+// is detect-only (sec. 4.10: "An MUA MUST NOT generate an RFC8551HP message ... MAY try to render") and opt-in
+// (`enabled`). Identification (sec. 4.10.1) is the four conjunctive conditions C1-C4; every failure (an
 // unparseable inner message, a non-message/rfc822 payload, a nested Cryptographic Layer, an hp= on part D, or an
 // ambiguous/empty protected set -- fails SOFT to none (never throws), because the message is not PRECISELY
 // identified. On identification (sec. 4.10.2) the inner message's (part D's) Non-Structural fields are surfaced,
 // the mode is inferred from the envelope (clear for signed, cipher for encrypted), and the confidential set is
 // derived from the actual outer section (part A). CRUCIAL: a legacy RFC8551HP message is structurally
 // INDISTINGUISHABLE from an ordinary signed/forwarded message/rfc822 (sec. 4.10.2: the inference is "not based
-// on any strong end-to-end guarantees"), so the inferred set is NEVER placed in `protectedHeaders` and NEVER
-// sets `present:true` -- those describe only cryptographically-declared hp= protection a caller may trust. The
-// inference is surfaced ONLY under `headerProtection.legacy` (its own { headers, mode, fromMismatch, confidential }
+// on any strong end-to-end guarantees"), so the inferred set is never placed in `protectedHeaders` and never
+// sets `present:true`; those describe only cryptographically-declared hp= protection a caller may trust. The
+// inference is surfaced only under `headerProtection.legacy` (its own { headers, mode, fromMismatch, confidential }
 // object), so a caller keying trust off `present` / `protectedHeaders` can never mistake an opted-in heuristic --
 // possibly a forwarded attachment -- for this message's authenticated headers; consuming it is an explicit choice.
 function _legacyHpSurface(canon, outerEnt, mode, enabled) {
@@ -403,73 +415,250 @@ function _legacyHpSurface(canon, outerEnt, mode, enabled) {
     if (partC.contentType.type !== "message/rfc822") return _noneSurface();
     partD = mime.parse(partC.body, SmimeError, "smime/bad-header-protection");
   } catch (_e) { return _noneSurface(); }   // an unparseable legacy candidate is not precisely identified -- fail soft
-  // The C2-C4 classification reads only the FIRST Content-Type of each part (mime.parse surfaces that one). A
-  // duplicate Content-Type on part C or part D is ambiguous -- a later field could carry hp= or a Cryptographic
-  // Layer media type the checks below would miss -- so fail soft, matching the standard path's duplicate reject.
+  // The C2-C4 classification reads only the first Content-Type of each part (mime.parse surfaces that one). A
+  // duplicate Content-Type on part C or part D is ambiguous, since a later field could carry hp= or a
+  // Cryptographic Layer media type the checks below would miss. Fail soft there, matching the standard path's
+  // duplicate reject.
   if (_contentTypeCount(partC.headers) > 1 || _contentTypeCount(partD.headers) > 1) return _noneSurface();
-  // C4: an hp= on part D means the message is NOT legacy (sec. 4.1: a consumer MUST ignore hp outside the payload
+  // C4: an hp= on part D means the message is not legacy (sec. 4.1: a consumer MUST ignore hp outside the payload
   // root). C3: part D must not itself be a Cryptographic Layer (a genuinely nested signed/encrypted message).
   if (mime.hasParam(partD.contentType.value, "hp")) return _noneSurface();
   if (_isCryptoLayer(partD.contentType.type)) return _noneSurface();
   var ex = _extractProtected(partD.headers);
-  // Only a duplicate SINGLETON field (RFC 5322 sec. 3.6) is the ambiguous case -- part D is an ordinary received
+  // Only a duplicate SINGLETON field (RFC 5322 sec. 3.6) is the ambiguous case. Part D is an ordinary received
   // message whose trace fields (Received, ...) and other repeatable fields legitimately recur, so a repeatable
-  // duplicate must NOT reject the inference (else legacy detection fails on essentially all delivered mail).
+  // duplicate must not reject the inference (else legacy detection fails on essentially all delivered mail).
   if (ex.dupSingleton) return _noneSurface();
   if (!ex.entries.length) return _noneSurface();   // no Non-Structural fields -- nothing to surface
   var confidential = mode === "cipher" ? _computeConfidential(ex.entries, _outerRefouter(outerEnt)) : [];
-  // present stays false + protectedHeaders stays null: the inferred set is surfaced ONLY under `legacy` so a
+  // present stays false + protectedHeaders stays null: the inferred set is surfaced only under `legacy` so a
   // caller cannot mistake an opt-in heuristic (indistinguishable from a forwarded message/rfc822) for authenticated
-  // headers. `headers` is the ORDERED [{ name, value }] list (every occurrence -- a real message repeats trace
+  // headers. `headers` is the ORDERED [{ name, value }] list (every occurrence; a real message repeats trace
   // fields); the internal `raw` per occurrence is dropped from the public shape.
   var headers = ex.entries.map(function (e) { return { name: e.name, value: e.value }; });
-  return { protectedHeaders: null, headerProtection: { present: false, mode: null, fromMismatch: false, confidential: [], legacy: { headers: headers, mode: mode, fromMismatch: _computeFromMismatch(ex.innerFrom, outerEnt), confidential: confidential } } };
+  // The OUTER fromMismatch stays unanswered here: a legacy wrap is an inference, never
+  // declared protection, so the top-level field must not report a comparison the message
+  // did not authenticate. The legacy block carries its own, clearly opt-in.
+  return { protectedHeaders: null, headerProtection: { present: false, mode: null, fromMismatch: null, confidential: [], legacy: { headers: headers, mode: mode, fromMismatch: _computeFromMismatch(ex.innerFrom, outerEnt), confidential: confidential } } };
 }
 
 // Detect + surface RFC 9788 header protection on a recovered inner entity, FAIL-CLOSED. A payload that does
-// not declare hp surfaces protectedHeaders:null -- UNLESS opts.legacyHeaderProtection is set and it is a legacy
+// not declare hp surfaces protectedHeaders:null, unless opts.legacyHeaderProtection is set and it is a legacy
 // RFC8551HP message/rfc822 wrap (sec. 4.10), which _legacyHpSurface then surfaces (opt-in, fail-soft). A payload
 // that DECLARES hp is validated: a malformed block, an invalid hp value, or an hp mode that CONTRADICTS the
 // cryptographic envelope (expectedMode "clear" for a signed message, "cipher" for a decrypted one) throws
 // smime/bad-header-protection -- never a silent downgrade. Otherwise the inline Non-Structural fields ARE the
 // authenticated set; a From that differs from the untrusted OUTER From is flagged fromMismatch.
+// The email identities a signer certificate actually asserts. RFC 8550 sec. 4.4.3 makes
+// subjectAltName the carrier: an ASCII local-part rides the rfc822Name CHOICE, and a
+// certificate MAY assert several addresses, so this collects every one rather than the
+// first. A non-ASCII local-part rides otherName / SmtpUTF8Mailbox (RFC 8398 sec. 3); those
+// are counted as PRESENT but not returned as comparable strings, so a certificate that
+// carries only internationalized identities reports "there is an identity here that this
+// comparison cannot read" instead of the indistinguishable "no identities".
+var SAN_OID = oid.byName("subjectAltName");
+var SMTP_UTF8_MAILBOX = oid.byName("smtpUtf8Mailbox");
+var EMAIL_ADDRESS_ATTR = oid.byName("emailAddress");
+var _extNs = pkix.makeNS("smime", SmimeError, oid);
+var _extDecoders = pkix.certExtensionDecoders(_extNs);
+var _extCtx = { E: function (c, m, cause) { return new SmimeError(c, m, cause); }, oid: oid };
+function _signerEmails(certDer) {
+  var out = { addresses: [], unreadable: 0 };
+  var parsed = null;
+  // A failure here is COUNTED, never absorbed: it raises `unreadable`, which drives the
+  // sender verdict to null (undecidable) rather than to a clean "no identities". Returning
+  // early on the error would make an unreadable certificate indistinguishable from one
+  // that genuinely asserts no address, and the caller would read "nothing to match" as a
+  // finished comparison instead of one that never happened.
+  try { parsed = schemaX509.parse(certDer); }
+  catch (parseFailed) { out.unreadable++; out.reason = parseFailed.code || "unparseable"; }
+  if (parsed === null) return out;
+  (parsed.extensions || []).forEach(function (e) {
+    if (e.oid !== SAN_OID) return;
+    var dec = null;
+    try { dec = _extDecoders.byOid[SAN_OID](e.value, _extCtx); }
+    catch (sanFailed) { out.unreadable++; out.reason = sanFailed.code || "bad-san"; }
+    if (dec === null) return;
+    (dec.names || []).forEach(function (n) {
+      if (n.tagNumber === 1) { out.addresses.push(String(n.value)); return; }   // rfc822Name
+      // An otherName only bears on the EMAIL question when it is an SmtpUTF8Mailbox
+      // (RFC 8398 sec. 3). A certificate may legitimately carry unrelated otherNames -- a
+      // Microsoft UPN is routine in enterprise issuance -- and counting those as an
+      // unreadable identity would drive a certificate whose rfc822Name matches perfectly
+      // to an undecidable verdict, making expectedSender unusable for that whole class.
+      if (n.tagNumber !== 0) return;
+      // The decoder builds otherName as value: { typeId, valueBytes } (schema-pkix's
+      // GeneralName rule), so the type-id lives one level in. Reading it off the node
+      // itself silently matched nothing, which made every SmtpUTF8Mailbox invisible and
+      // let a legacy subject value speak for a certificate whose SAN was authoritative.
+      // An otherName whose type-id cannot be read at all counts as unreadable: unknown
+      // shape is a reason to withhold a verdict, not to ignore the entry.
+      var typeId = n.value && typeof n.value === "object" ? n.value.typeId : undefined;
+      if (typeId === undefined) { out.unreadable++; return; }
+      if (String(typeId) === SMTP_UTF8_MAILBOX) out.unreadable++;
+    });
+  });
+  // RFC 8550 sec. 3: the address SHOULD live in subjectAltName, but a receiving agent
+  // "MUST recognize email addresses in the distinguished name field in the PKCS #9
+  // emailAddress attribute". Reading only the extension would leave every legacy
+  // certificate of that shape permanently undecidable, so the subject DN is consulted too.
+  // It is a fallback, not a peer: a SAN address is the conformant carrier.
+  // A fallback, not a peer: consulted ONLY when subjectAltName yielded no address. RFC 8550
+  // sec. 3 says the address SHOULD be in the extension and SHOULD NOT be in the subject, so
+  // where both exist the extension is authoritative. Merging them would let a stale or
+  // conflicting subject value satisfy expectedSender while the SAN names a different
+  // mailbox -- a positive binding drawn from the weaker of two disagreeing identities.
+  // "No SAN email identity" means none of EITHER kind. An SmtpUTF8Mailbox raises
+  // `unreadable` without adding a comparable address, so testing `addresses` alone would
+  // fall through to the subject for exactly the certificates whose SAN does carry an
+  // authoritative identity -- letting a stale subject value override an internationalized
+  // SAN this toolkit simply cannot read.
+  var sanCarriedIdentity = out.addresses.length > 0 || out.unreadable > 0;
+  var rdns = !sanCarriedIdentity && parsed.subject ? parsed.subject.rdns : null;
+  (rdns || []).forEach(function (rdn) {
+    (rdn || []).forEach(function (attr) {
+      if (!attr || attr.type !== EMAIL_ADDRESS_ATTR || typeof attr.value !== "string") return;
+      if (out.addresses.indexOf(attr.value) === -1) out.addresses.push(attr.value);
+    });
+  });
+  return out;
+}
+
+// What the signer's certificate says about who sent this, and whether anyone asked.
+//
+// `match` is THREE-valued and never collapses: true only when an identity in the signer's
+// certificate matches under RFC 5280 sec. 7.5; false when every identity was comparable and
+// none matched; null when the question was not asked, or was asked and could not be decided
+// (no readable identity, or an address needing an IDNA transform this toolkit will not do).
+// A boolean here would make "nobody checked" indistinguishable from "checked and agreed",
+// which is the defect this field exists to remove -- so a caller enforcing sender binding
+// tests `match === true`, and null fails that test exactly as false does.
+//
+// `expectedSender` is the authoritative input. The outer From is attacker-controlled on an
+// unprotected message, so comparing against it is reported as advisory (`source: "from"`)
+// and never presented as a verified binding.
+function _senderSurface(signers, outerEnt, expectedSender) {
+  var expected = null, source = null;
+  // Entry-tier: a mistyped option is a caller bug and throws, never a coercion. String()
+  // would accept any object with a toString, so `{ toString: () => "alice@example.com" }`
+  // would drive a sender binding the caller never actually stated -- the authoritative
+  // input to this comparison must be the string it claims to be.
+  if (expectedSender != null) {
+    if (typeof expectedSender !== "string") {
+      throw _err("smime/bad-input", "expectedSender must be a string email address, got " + typeof expectedSender);
+    }
+    expected = expectedSender; source = "expectedSender";
+  }
+  else {
+    var froms = [];
+    outerEnt.headers.forEach(function (h) { if (h.lname === "from") froms.push(h.value.trim()); });
+    // Exactly one From, or there is no unambiguous address to compare against.
+    if (froms.length === 1) { expected = _addrSpec(froms[0]); source = expected === null ? null : "from"; }
+  }
+  var identities = [], undecidable = false, sawIdentity = false;
+  (signers || []).forEach(function (s) {
+    // Only a signer whose signature actually verified may contribute an identity.
+    // cms.verify reports every matched signer, including ones that failed, as ok:false --
+    // harvesting their subjectAltName would let a tampered message report valid:false
+    // alongside sender.match:true, and this verb's own guidance is to enforce
+    // sender.match === true. A failed signer makes the answer undecidable, never a clean
+    // no-match.
+    // Only a signer whose signature actually verified may contribute an identity.
+    // cms.verify reports every matched signer, including ones that failed, as ok:false --
+    // harvesting their subjectAltName would let a tampered message report valid:false
+    // alongside sender.match:true, and this verb's own guidance is to enforce
+    // sender.match === true. A failed signer makes the answer undecidable, never a clean
+    // no-match.
+    // A verified signature is not enough: anyone can self-sign a certificate carrying the
+    // victim's address, and cms.verify reports that signer ok:true / trusted:false. Reading
+    // its subjectAltName would let an attacker-minted certificate produce a positive
+    // binding, which is the same defect one layer up from the ok:false case. Name your
+    // roots in opts.trustAnchors; with none supplied nothing is trusted, so the binding
+    // question stays unanswered rather than answered from an unvetted certificate.
+    if (!s || s.ok !== true || s.trusted !== true) { undecidable = true; return; }
+    var e = s.cert ? _signerEmails(s.cert) : null;
+    if (e === null) { undecidable = true; return; }   // no certificate to read at all
+    if (e.unreadable > 0) { undecidable = true; sawIdentity = true; }
+    e.addresses.forEach(function (a) { sawIdentity = true; if (identities.indexOf(a) === -1) identities.push(a); });
+  });
+  if (expected === null) return { checked: false, expected: null, source: null, identities: identities, match: null };
+  if (!sawIdentity) return { checked: true, expected: expected, source: source, identities: identities, match: null };
+  // No early return on the first match. A match is only the answer once nothing else has
+  // made the result undecidable: a failed co-signer, an unreadable certificate or an
+  // address this toolkit cannot canonicalize all mean the verdict is unsettled, and
+  // reporting true from inside the loop would let that be read as a clean binding.
+  // Undecidable always wins over a positive.
+  var sawMatch = false, sawNotComparable = false;
+  for (var i = 0; i < identities.length; i++) {
+    var v = guard.name.emailEqual(identities[i], expected);
+    if (v === "match") sawMatch = true;
+    else if (v === "not-comparable") sawNotComparable = true;
+  }
+  // The question is existential: does a verified signer's certificate assert this address?
+  // An exact match answers it, and a second identity that could not be compared does not
+  // un-answer it -- a certificate legitimately carrying several addresses would otherwise
+  // fail the binding because of one it was never asked about. Undecidability only decides
+  // the verdict when nothing matched.
+  var verdict;
+  if (sawMatch) verdict = true;
+  else if (undecidable || sawNotComparable) verdict = null;
+  else verdict = false;
+  return { checked: true, expected: expected, source: source, identities: identities, match: verdict };
+}
+
+// The addr-spec inside an RFC 5322 From. A display-name form ("Bob <bob@x>") yields the
+// angle-addr; a bare address yields itself. Anything else (a group, a second address, an
+// unclosed angle bracket) returns null so the caller reports "not compared" rather than
+// comparing against a fragment.
+function _addrSpec(v) {
+  var lt = v.indexOf("<"), gt = v.lastIndexOf(">");
+  if (lt === -1 && gt === -1) return v.indexOf(",") === -1 ? v.trim() : null;
+  if (lt === -1 || gt < lt) return null;
+  // Nothing but whitespace may follow the angle address. `Alice <alice@x>, mallory@y` is two
+  // mailboxes, and returning the first would report a single compared sender over a field
+  // that named more than one -- the ambiguity this function exists to refuse.
+  if (v.slice(gt + 1).trim().length) return null;
+  var inner = v.slice(lt + 1, gt).trim();
+  return inner.length && inner.indexOf(",") === -1 && inner.indexOf("<") === -1 ? inner : null;
+}
+
 function _hpSurface(content, outerEnt, expectedMode, authenticated, legacyEnabled) {
-  // Header protection is an AUTHENTICATED property: surface the inner headers as protected ONLY when the
+  // Header protection is an AUTHENTICATED property: surface the inner headers as protected only when the
   // cryptographic verdict succeeded (a valid signature, or an authenticated-encryption decrypt). An invalid
-  // signature or an unauthenticated (AES-CBC, no integrity) decrypt yields attacker-influenced bytes -- they
+  // signature or an unauthenticated (AES-CBC, no integrity) decrypt yields attacker-influenced bytes, and those
   // are never marked or exposed as protected (a caller must not treat protectedHeaders as a trust signal
   // unless integrity held).
   if (!authenticated) return _noneSurface();
-  // Detect + parse the CANONICAL entity -- the exact bytes the signature covers. A transport may rewrite a
+  // Detect + parse the CANONICAL entity: the exact bytes the signature covers. A transport may rewrite a
   // CRLF fold OR the header/body separator to bare CR/LF; canonicalize repairs them (so verification still
-  // succeeds), and BOTH the hp detection and the parse must run on the repaired bytes, or they diverge from
+  // succeeds), and both the hp detection and the parse must run on the repaired bytes, or they diverge from
   // the signed content -- stripping the signal, or false-rejecting a valid message as an unparseable block.
   // The returned `content` stays the raw recovered bytes; only this HP inspection uses the canonical copy.
   var canon = mime.canonicalizeText(content);
   // A payload that does not declare hp is either non-protected (protectedHeaders:null) or a legacy RFC8551HP
   // message/rfc822 wrap the caller opted into detecting (sec. 4.10). Both are mutually exclusive with the
-  // standard path below by construction: it runs ONLY when a real hp= is present on the payload root.
+  // standard path below by construction: it runs only when a real hp= is present on the payload root.
   if (!_declaresHp(canon)) return _legacyHpSurface(canon, outerEnt, expectedMode, legacyEnabled);
   var inner = mime.parse(canon, SmimeError, "smime/bad-header-protection");   // a malformed HP block fails closed
-  // A duplicate Content-Type makes the hp declaration ambiguous (a parser reads params from the FIRST field,
-  // but an hp= may sit on a later one) -- a malformed wrap that fails closed, never a silent downgrade.
+  // A duplicate Content-Type makes the hp declaration ambiguous (a parser reads params from the first field,
+  // but an hp= may sit on a later one), so the wrap is malformed and fails closed, never a silent downgrade.
   var ctCount = _contentTypeCount(inner.headers);
   if (ctCount > 1) throw _err("smime/bad-header-protection", "a header-protected payload must carry exactly one Content-Type field (found " + ctCount + ")");
-  // A duplicate hp attribute is ambiguous (mime.parse keeps the LAST value, but a recipient honoring the
-  // first would see a different mode) -- fail closed, like the duplicate Content-Type. Counted by attribute
+  // A duplicate hp attribute is ambiguous (mime.parse keeps the last value, but a recipient honoring the
+  // first would see a different mode); fail closed, like the duplicate Content-Type. Counted by attribute
   // name (bare OR valued) so a bare+valued pair ("hp; hp=x") is caught too, and quote-/comment-aware (an hp=
   // inside a quoted value or comment is not the hp parameter, so a message we emit is never self-rejected).
   if (mime.paramNameCount(inner.contentType.value, "hp") > 1) throw _err("smime/bad-header-protection", "a header-protected payload declares the hp parameter more than once");
-  // _declaresHp composes the SAME comment/quoted-string-aware tokenizer (mime.paramCount) mime.parse uses, so
+  // _declaresHp composes the same comment/quoted-string-aware tokenizer (mime.paramCount) mime.parse uses, so
   // reaching here means the single Content-Type carries a real hp parameter (a duplicate is rejected above) --
   // hp is defined. A malformed value fails CLOSED at the mode checks below, never a silent downgrade.
-  // The hp keyword values clear / cipher are an enumerated Content-Type parameter -- per RFC 2045 sec. 5.1 a
+  // The hp keyword values clear / cipher are an enumerated Content-Type parameter. Per RFC 2045 sec. 5.1 a
   // value of this kind is compared case-insensitively for its intended use, so a peer that emits hp="Clear"
   // or hp=CIPHER is still recognized. (We always EMIT lowercase; we ACCEPT any case. The value is inside the
-  // signed/encrypted payload, so normalizing it enables no attack -- the mode-contradiction check still runs.)
+  // signed/encrypted payload, so normalizing it enables no attack; the mode-contradiction check still runs.)
   // _declaresHp detected the hp attribute (hasParam); a bare "hp" with no value is a malformed HP declaration
-  // -- fail closed rather than silently downgrade (mime.parse skips a valueless parameter, so params.hp is
-  // undefined here only for that malformed case).
+  // and fails closed (mime.parse skips a valueless parameter, so params.hp is undefined here only for that
+  // malformed case).
   var raw = inner.contentType.params.hp;
   if (raw === undefined) throw _err("smime/bad-header-protection", "a header-protected payload declares a bare hp parameter with no value (expected hp=\"clear\" or hp=\"cipher\")");
   var hp = raw.toLowerCase();
@@ -477,7 +666,7 @@ function _hpSurface(content, outerEnt, expectedMode, authenticated, legacyEnable
   if (hp !== expectedMode) throw _err("smime/bad-header-protection", "the payload hp=" + JSON.stringify(hp) + " contradicts the cryptographic envelope (a " + (expectedMode === "cipher" ? "decrypted" : "signed") + " message requires hp=" + JSON.stringify(expectedMode) + ")");
   var ex = _extractProtected(inner.headers);
   // A duplicate protected field is ambiguous (the last-wins overwrite hides an earlier value a different
-  // parser might select) -- fail closed rather than surface an ambiguous authenticated set.
+  // parser might select), so the payload fails closed.
   if (ex.dup) throw _err("smime/bad-header-protection", "a header-protected payload has a duplicate protected header field " + JSON.stringify(ex.dup));
   // RFC 9788 sec. 4.3.1: for an ENCRYPTED payload (hp="cipher") the confidential set is the fields not copied
   // verbatim to the outer section via an HP-Outer record. Signed-only (clear) payloads carry no HP-Outer.
@@ -485,7 +674,7 @@ function _hpSurface(content, outerEnt, expectedMode, authenticated, legacyEnable
   return { protectedHeaders: ex.protectedHeaders, headerProtection: { present: true, mode: hp, fromMismatch: _computeFromMismatch(ex.innerFrom, outerEnt), confidential: confidential, legacy: null } };
 }
 
-// Map smime opts to cms.sign opts (the S/MIME layer is algorithm-agnostic -- it forwards any signer).
+// Map smime opts to cms.sign opts (the S/MIME layer is algorithm-agnostic and forwards any signer).
 function _cmsSignOpts(opts, detached) {
   var o = { detached: detached };
   if (opts.signingTime !== undefined) o.signingTime = opts.signingTime;
@@ -536,7 +725,7 @@ function _base64Body(der) {
  * @spec       RFC 8551, RFC 5652
  * @related    pki.smime.verify, pki.cms.sign
  *
- * Assemble a signed S/MIME message (RFC 8551). `content` is the payload -- a raw body wrapped as a
+ * Assemble a signed S/MIME message (RFC 8551). `content` is the payload: a raw body wrapped as a
  * `text/plain` entity by default, or the caller's own complete MIME entity when `opts.entity` is set;
  * `signers` is the `pki.cms.sign` signer array (any RSA / RSASSA-PSS / ECDSA / EdDSA / ML-DSA / SLH-DSA
  * signer -- the S/MIME layer is algorithm-agnostic). Two forms via `opts.form`:
@@ -545,17 +734,17 @@ function _base64Body(der) {
  *     canonical form in the second, with `protocol="application/pkcs7-signature"` + a matching `micalg`.
  *   - `"pkcs7-mime"` (opaque): one `application/pkcs7-mime; smime-type=signed-data` entity whose base64
  *     body is an ATTACHED CMS SignedData over the canonical entity.
- * The signed bytes are the entity's RFC 8551 sec. 3.1.1 canonical form (CRLF line endings); the SAME
+ * The signed bytes are the entity's RFC 8551 sec. 3.1.1 canonical form (CRLF line endings); the same
  * canonicalizer runs on verify. With `opts.protectHeaders`, the message is header-protected (RFC 9788): the
- * caller's `opts.headers` are inlined on the Cryptographic Payload root -- its Content-Type gains `hp="clear"`
- * -- so the signature covers them, and copied to the outer display headers; `verify` surfaces the
+ * caller's `opts.headers` are inlined on the Cryptographic Payload root (its Content-Type gains `hp="clear"`),
+ * so the signature covers them, and copied to the outer display headers; `verify` surfaces the
  * authenticated inner set. Returns the assembled message bytes. Fail-closed with `SmimeError`.
  *
  * @opts form        `"multipart"` (default) or `"pkcs7-mime"`.
  * @opts entity      treat `content` as a complete MIME entity (default: wrap it as text/plain).
  * @opts contentType the wrapped entity's Content-Type (default `text/plain; charset=utf-8`).
  * @opts signingTime a `Date` for the CMS signing-time attribute, or false to omit it.
- * @opts protectHeaders enable RFC 9788 header protection (`hp="clear"`) -- inline `opts.headers` on the signed payload + the outer display headers.
+ * @opts protectHeaders enable RFC 9788 header protection (`hp="clear"`), inlining `opts.headers` on the signed payload + the outer display headers.
  * @opts headers     the Non-Structural fields to protect + display: an object `{ Name: value }` or an array `[{ name, value }]` (Subject / From / To / Date / ...); used with `protectHeaders`.
  * @opts hcp         the Header Confidentiality Policy applied to the OUTER display copies: `"hcp_baseline"` (default) or `"hcp_no_confidentiality"`. A signed message's payload is not encrypted, so this governs presentation, not secrecy; used with `protectHeaders`.
  * @opts sid                       forwarded to cms.sign: the SignerIdentifier form, `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
@@ -609,7 +798,7 @@ function _capped(msg) {
 
 /**
  * @primitive  pki.smime.verify
- * @signature  pki.smime.verify(message, opts?) -> Promise<{ valid, trusted, signers, form, content, micalg, protectedHeaders, headerProtection }>
+ * @signature  pki.smime.verify(message, opts?) -> Promise<{ valid, trusted, signers, form, content, micalg, sender, protectedHeaders, headerProtection }>
  * @since      0.2.25
  * @status     stable
  * @spec       RFC 8551, RFC 5652, RFC 9788
@@ -617,7 +806,7 @@ function _capped(msg) {
  *
  * Unwrap and verify a signed S/MIME message (RFC 8551), both `multipart/signed` and
  * `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
+ * 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, trusted, signers }` verdict PLUS `form`, the recovered `content` (the
  * signed MIME entity bytes), and the `micalg`.
@@ -630,31 +819,54 @@ function _capped(msg) {
  * 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.
+ * and `opts.checkPurpose`. Supply no anchors and `trusted` is `false`, since 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 }`
- * -- `present` is `true` only for cryptographically-DECLARED (`hp=`) protection you may trust; `fromMismatch` flags
- * an outer From differing from the protected one; `confidential` lists the protected fields the composer kept
+ * -- `present` is `true` only for cryptographically-DECLARED (`hp=`) protection you may trust; `fromMismatch` is
+ * `true` when the outer From differs from the protected one, `false` when they agree, and `null` when there was
+ * no protected From to compare against, which is every message without header protection. Test it against
+ * `false` rather than for falsiness: `!fromMismatch` treats the unanswered case as a passed check, and that is
+ * the common case. For a binding that does not depend on the composer having protected headers, use `sender`
+ * with `opts.expectedSender`; `confidential` lists the protected fields the composer kept
  * end-to-end confidential (per the authenticated HP-Outer records, RFC 9788 sec. 4.3; only for an encrypted
  * `hp="cipher"` payload). A non-protected message reports `protectedHeaders: null`, `present: false`. A payload
  * whose declared `hp` is malformed, invalid, or contradicts the envelope fails closed (`smime/bad-header-protection`),
  * never a silent downgrade. `legacy` is `null` unless `opts.legacyHeaderProtection` detected a legacy RFC 8551
  * `message/rfc822` wrap (see that option), in which case it is its own `{ headers, mode, fromMismatch, confidential }`
  * object (`headers` an ordered `[{ name, value }]` array that retains legally-repeated fields like `Received`) -- a
- * legacy inference is NEVER placed in `protectedHeaders` and never sets `present: true`, because it is
+ * legacy inference is never placed in `protectedHeaders` and never sets `present: true`, because it is
  * indistinguishable from an ordinary forwarded `message/rfc822`, so a caller keying trust off `present` /
  * `protectedHeaders` cannot mistake the opt-in heuristic for authenticated headers.
  *
+ * `sender` answers who the message is from, which `valid` does not: a signature proves a key signed,
+ * never that the message came from the mailbox the reader sees. Name the address you expect in
+ * `opts.expectedSender` and `sender.match` is `true` only when the signer certificate asserts it,
+ * compared under RFC 5280 sec. 7.5: the local-part exactly, the host-part case-insensitively. The
+ * address is read from the `subjectAltName` `rfc822Name` entries (RFC 8550 sec. 4.4.3) and, where the
+ * extension carries none, from the subject DN's PKCS #9 `emailAddress` attribute, which RFC 8550 sec. 3
+ * requires a receiving agent to recognise. Where both are present the extension wins. Only a signer
+ * whose signature verified contributes an identity, so a tampered message cannot report a binding. `match` is THREE-valued and a caller enforcing sender binding tests
+ * `match === true` -- `false` means every identity was comparable and none matched, and `null` means the
+ * question was not answered (no `expectedSender` and no single outer `From`, a signer certificate
+ * asserting no readable email identity, or an internationalized address needing an IDNA transform this
+ * toolkit does not perform). `null` is not a pass. `sender.identities` lists what the certificate
+ * actually asserts, `sender.checked` whether a comparison ran, and `sender.source` which input it ran
+ * against -- `"from"` is ADVISORY, because on a message without header protection the outer From is
+ * attacker-controlled.
+ *
  * @opts certs        extra signer certificates (DER `Buffer`s) to match, forwarded to `cms.verify`.
+ * @opts expectedSender  the email address the signer's certificate must assert for `sender.match` to be
+ *                    `true`. Without it the outer `From` is used when there is exactly one, and reported
+ *                    as `source: "from"` -- advisory, never a verified binding.
  * @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.
+ * @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 }`, where `headers` is an ordered `[{ name, value }]` array (retaining legally-repeated fields such as `Received`) and the mode is inferred from the envelope (`clear` here). They are not placed 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), because the non-recursive layered API exposes no single seam holding both the inner signature verdict and the outer header section.
  * @example
  *   var pair = await pki.key.generate("Ed25519");
  *   var key = await pki.key.export(pair.privateKey);
@@ -698,7 +910,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, trusted: res.trusted, 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, sender: _senderSurface(res.signers, ent, opts.expectedSender) }, _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");
@@ -725,7 +937,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, trusted: res2.trusted, 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, sender: _senderSurface(res2.signers, ent, opts.expectedSender) }, _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) + ")");
 }
@@ -774,13 +986,13 @@ function _cmsEncryptOpts(opts) {
  * Envelope a MIME entity as an encrypted S/MIME message (RFC 8551 sec. 3.3 / sec. 3.4). `content` is the
  * payload -- a raw body wrapped as a `text/plain` entity by default, or the caller's own complete MIME
  * entity when `opts.entity` is set; `recipients` is the `pki.cms.encrypt` recipient array (any RSA-OAEP
- * ktri / EC or X25519/X448 kari / ML-KEM ori-KEM / password pwri / kek kekri -- the S/MIME layer is
+ * ktri / EC or X25519/X448 kari / ML-KEM ori-KEM / password pwri / kek kekri: the S/MIME layer is
  * recipient-agnostic; a single descriptor is accepted and normalized to a one-element array). Enveloping
- * has ONE form -- opaque `application/pkcs7-mime` with the whole entity base64-encoded. The `smime-type`
+ * has a single form, opaque `application/pkcs7-mime` with the whole entity base64-encoded. The `smime-type`
  * is derived from the produced CMS: AES-GCM (the default) yields an AuthEnvelopedData with
  * `smime-type=authEnveloped-data` (confidentiality AND integrity); a CBC choice yields an EnvelopedData
- * with `smime-type=enveloped-data` (confidentiality only -- no integrity, RFC 8551 sec. 3.3). With
- * `opts.protectHeaders`, the message is header-protected (RFC 9788): the REAL `opts.headers` are inlined
+ * with `smime-type=enveloped-data` (confidentiality only, no integrity, RFC 8551 sec. 3.3). With
+ * `opts.protectHeaders`, the message is header-protected (RFC 9788): the real `opts.headers` are inlined
  * inside the ciphertext (the payload Content-Type gains `hp="cipher"`), and only the Header-Confidentiality-
  * Policy-processed display copies appear outside -- the default `hcp_baseline` obscures Subject to `[...]`
  * and removes Comments / Keywords, so those values live only in the ciphertext; `decrypt` recovers the real
@@ -788,9 +1000,9 @@ function _cmsEncryptOpts(opts) {
  *
  * @opts entity                     treat `content` as a complete MIME entity (default: wrap it as text/plain).
  * @opts contentType                the wrapped entity's MIME Content-Type (default `text/plain; charset=utf-8`).
- * @opts protectHeaders             enable RFC 9788 header protection (`hp="cipher"`) -- inline `opts.headers` inside the ciphertext, emit HCP-processed outer copies, and embed the authenticated HP-Outer records (RFC 9788 sec. 2.2) documenting which fields were left visible outside.
+ * @opts protectHeaders             enable RFC 9788 header protection (`hp="cipher"`): inline `opts.headers` inside the ciphertext, emit HCP-processed outer copies, and embed the authenticated HP-Outer records (RFC 9788 sec. 2.2) documenting which fields were left visible outside.
  * @opts headers                    the Non-Structural fields to protect (object `{ Name: value }` or array `[{ name, value }]`); the real values, hidden by the HCP.
- * @opts hcp                        the Header Confidentiality Policy: `"hcp_baseline"` (default -- obscure Subject, remove Comments/Keywords) or `"hcp_no_confidentiality"` (leave all outer values visible). Per RFC 9788 sec. 3.2.1 / sec. 11.4, `hcp_baseline` deliberately does NOT strip `Bcc` (removing it can break deliverability to a Bcc'd recipient); to keep a blind recipient out of the plaintext outer headers, omit `Bcc` from `opts.headers`.
+ * @opts hcp                        the Header Confidentiality Policy: `"hcp_baseline"` (the default, obscuring Subject and removing Comments/Keywords) or `"hcp_no_confidentiality"` (leave all outer values visible). Per RFC 9788 sec. 3.2.1 / sec. 11.4, `hcp_baseline` deliberately does not strip `Bcc` (removing it can break deliverability to a Bcc'd recipient); to keep a blind recipient out of the plaintext outer headers, omit `Bcc` from `opts.headers`.
  * @opts contentEncryptionAlgorithm forwarded to cms.encrypt: `"aes-256-gcm"` (default) / `"aes-128-gcm"` / `"aes-256-cbc"` / `"aes-128-cbc"`.
  * @opts oaepHash                   forwarded: the RSAES-OAEP hash for ktri recipients.
  * @opts keyIdentifier              forwarded: `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
@@ -835,26 +1047,26 @@ async function encrypt(content, recipients, opts) {
  * Open an encrypted S/MIME message (RFC 8551 sec. 3.3 / sec. 3.4) -- an `application/pkcs7-mime` entity
  * whose base64 body is a CMS EnvelopedData or AuthEnvelopedData. `keyMaterial` is the `pki.cms.decrypt`
  * key material (`{ key, cert }`, `{ password }`, or `{ kek, kekId? }`). Returns the recovered inner MIME
- * entity as `content`, the `smimeType`, `authenticated` (true only for AuthEnvelopedData -- a CBC
+ * entity as `content`, the `smimeType`, `authenticated` (true only for AuthEnvelopedData; a CBC
  * `enveloped-data` message reports `false`, the RFC 8551 sec. 3.3 / EFAIL no-integrity caveat), and the
  * `recipientType` / `recipientIndex` / `contentEncryptionAlgorithm` from the CMS layer. Fail-closed and
  * oracle-free: every secret-dependent failure collapses to the uniform `cms/decrypt-failed` the CMS layer
  * emits (this layer only propagates it). A recovered `content` that is itself a signed S/MIME message is
  * returned as-is for the caller to feed back to `pki.smime.verify` (no auto-recursion). Accepts OpenSSL's
  * legacy `application/x-pkcs7-mime` and a missing `smime-type`. If the decrypted payload is header-protected
- * (RFC 9788, `hp="cipher"`), `protectedHeaders` is the recovered REAL inner header set (the values the outer
+ * (RFC 9788, `hp="cipher"`), `protectedHeaders` is the recovered real inner header set (the values the outer
  * Header Confidentiality Policy hid) and `headerProtection` is `{ present, mode, fromMismatch, confidential, legacy }`,
  * where `present` is `true` only for a declared `hp=` payload, and `confidential` names the fields the composer
  * kept end-to-end confidential (via the authenticated HP-Outer records, RFC 9788 sec. 4.3) -- so a caller can
  * reply/forward without leaking them (sec. 6.1); a payload whose `hp` is malformed or contradicts the envelope
  * fails closed (`smime/bad-header-protection`). `legacy` is `null` unless `opts.legacyHeaderProtection` detected a
- * legacy RFC 8551 `message/rfc822` wrap (its own `{ headers, mode, fromMismatch, confidential }` object -- `headers`
- * an ordered `[{ name, value }]` array -- never merged into `protectedHeaders` / `present`).
+ * legacy RFC 8551 `message/rfc822` wrap (its own `{ headers, mode, fromMismatch, confidential }` object, where `headers`
+ * is an ordered `[{ name, value }]` array; it is never merged into `protectedHeaders` / `present`).
  *
  * @opts recipientIndex  forwarded to cms.decrypt: explicitly select the recipient by index.
  * @opts maxIterations   forwarded to cms.decrypt: lower the PBKDF2 iteration cap (downward only).
  * @opts strictSmimeType reject a header `smime-type` that disagrees with the CMS body (`smime/smime-type-mismatch`).
- * @opts legacyHeaderProtection  opt in to detecting a LEGACY RFC 8551 header-protected message (RFC 9788 sec. 4.10): an encrypted Cryptographic Payload that is a bare `message/rfc822` wrap with no `hp=` parameter. When set, a precisely-identified legacy message surfaces the inner headers under `headerProtection.legacy = { headers, mode: "cipher", fromMismatch, confidential }` -- `headers` an ordered `[{ name, value }]` array (retaining repeated fields), the `confidential` set derived from the actual visible outer Header Section -- NOT under `protectedHeaders`, and `present` stays `false`, since a legacy message is structurally indistinguishable from a forwarded `message/rfc822` (a heuristic; cross-check `legacy.fromMismatch`). Anything not precisely identified reports `legacy: null`. Off by default.
+ * @opts legacyHeaderProtection  opt in to detecting a LEGACY RFC 8551 header-protected message (RFC 9788 sec. 4.10): an encrypted Cryptographic Payload that is a bare `message/rfc822` wrap with no `hp=` parameter. When set, a precisely-identified legacy message surfaces the inner headers under `headerProtection.legacy = { headers, mode: "cipher", fromMismatch, confidential }`, with `headers` an ordered `[{ name, value }]` array (retaining repeated fields) and the `confidential` set derived from the actual visible outer Header Section. They are not placed under `protectedHeaders`, and `present` stays `false`, since a legacy message is structurally indistinguishable from a forwarded `message/rfc822` (a heuristic; cross-check `legacy.fromMismatch`). Anything not precisely identified reports `legacy: null`. Off by default.
  * @example
  *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };
  *   var pair = await pki.key.generate(rsa);
@@ -904,7 +1116,7 @@ async function decrypt(message, keyMaterial, opts) {
  * entity when `opts.entity` is set. The entity is canonicalized (RFC 8551 sec. 3.1) and ZLIB-compressed
  * into a CMS `CompressedData` (`pki.cms.compress`), carried opaque in one `application/pkcs7-mime;
  * smime-type=compressed-data; name=smime.p7z` entity (base64). Compression is a size transform with NO
- * integrity, confidentiality, or authentication (RFC 8551 sec. 2.4.5) -- sign or encrypt the result if
+ * integrity, confidentiality, or authentication (RFC 8551 sec. 2.4.5). Sign or encrypt the result if
  * you need protection. Returns the assembled message bytes; fail-closed with `SmimeError`.
  *
  * @opts entity      treat `content` as a complete MIME entity (default: wrap it as text/plain).
@@ -936,7 +1148,7 @@ async function compress(content, opts) {
  * base64 body is a CMS `CompressedData`. Returns the recovered inner MIME entity as `content` plus the
  * inner `contentType` / `contentTypeName` and the `compressionAlgorithm`. The inflate is BOUNDED (a
  * decompression-bomb defense, `cms/decompress-too-large`; `opts.maxOutputBytes` tightens it downward).
- * The verdict carries NO `authenticated` / `valid` field -- CompressedData is not a security assertion
+ * The verdict carries NO `authenticated` / `valid` field, because CompressedData is not a security assertion
  * (RFC 8551 sec. 2.4.5). A recovered content that is itself a signed or enveloped S/MIME message is
  * returned as-is for the caller to feed back to `pki.smime.verify` / `pki.smime.decrypt` (no
  * auto-recursion). Accepts OpenSSL's legacy `application/x-pkcs7-mime` and a missing `smime-type`.