@blamejs/pki 0.3.23 → 0.3.25

package/lib/smime.js

@@ -228,32 +228,195 @@ function _declaresHp(content) {
   return false;
 }
 
+// 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 } }; }
+
+// 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.
+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
+// 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
+// message. A Set (not a plain object) so an attacker-chosen field name like "constructor" / "__proto__" cannot
+// match an inherited Object.prototype member and false-trip the singleton reject.
+var RFC5322_SINGLETON = new Set(["date", "from", "sender", "reply-to", "to", "cc", "bcc", "message-id", "in-reply-to", "references", "subject", "return-path"]);
+
+// 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
+// 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
+  // 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
+  var refouter = [];   // RFC 9788 sec. 4.2.1: the HP-Outer records (name + the value the field had in the outer section)
+  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)
+      // -> 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
+      // 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() });
+      return;
+    }
+    var val = _utf8Header(h.rawValue);                    // the exact authenticated field body (RFC 6532 UTF-8)
+    entries.push({ name: h.name, value: val, raw: h.rawValue });   // EVERY occurrence: `value` (UTF-8) for surfacing, `raw` (latin1) for the octet-exact confidentiality match
+    if (seen[h.lname]) { dup = h.name; if (RFC5322_SINGLETON.has(h.lname)) dupSingleton = h.name; }
+    seen[h.lname] = 1;
+    protectedHeaders[h.name] = val;                       // SURFACE (map, last-wins -- the ergonomic single-value view; `entries` keeps every occurrence + the octet-exact `raw`)
+    // innerFrom uses the byte-preserving value: a lossy UTF-8 decode maps distinct invalid 8-bit sequences (0x80
+    // vs 0x81) to the same replacement char, which would let an attacker alter the displayed From without
+    // tripping fromMismatch. Compare the raw octets instead.
+    if (h.lname === "from") innerFrom = h.value;
+  });
+  return { protectedHeaders: protectedHeaders, entries: entries, innerFrom: innerFrom, refouter: refouter, dup: dup, dupSingleton: dupSingleton };
+}
+
+// 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
+// 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
+// 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
+  // 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) {
+    var m = byName.get(r.name); if (!m) { m = new Map(); byName.set(r.name, m); }
+    m.set(r.value, (m.get(r.value) || 0) + 1);
+  });
+  var confidential = [], seen = Object.create(null);
+  entries.forEach(function (e) {
+    var m = byName.get(e.name.toLowerCase()), val = e.raw.trim(), n = (m && m.get(val)) || 0;
+    if (n > 0) { m.set(val, n - 1); return; }   // an outer occurrence accounts for (exposes) this one
+    if (!seen[e.name]) { seen[e.name] = 1; confidential.push(e.name); }
+  });
+  return confidential;
+}
+
+// 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.
+function _computeFromMismatch(innerFrom, outerEnt) {
+  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());
+}
+
+// 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.
+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).
+  return _isPkcs7(type, "mime") || type === "multipart/signed" || type === "multipart/encrypted";
+}
+
+// The legacy `refouter`: the actual visible outer Header Section (part A) as name+value records, so the sec.
+// 4.3.1 confidentiality comparison runs against the real outer values (a legacy message carries no HP-Outer).
+function _outerRefouter(outerEnt) {
+  var r = [];
+  outerEnt.headers.forEach(function (h) { if (!_isStructural(h.lname) && h.lname !== "hp-outer") r.push({ name: h.lname, value: h.rawValue.trim() }); });
+  return r;
+}
+
+// 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
+// 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 }
+// 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) {
+  if (!enabled) return _noneSurface();
+  var partC, partD;
+  try {
+    // C1 (outermost object is a Cryptographic Layer) holds by construction: _hpSurface only reaches here after a
+    // successful, AUTHENTICATED verify/decrypt. C2: the Cryptographic Payload must be a SINGLE message/rfc822 object.
+    partC = mime.parse(canon, SmimeError, "smime/bad-header-protection");
+    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.
+  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
+  // 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
+  // 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).
+  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
+  // 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
+  // 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 } } };
+}
+
 // Detect + surface RFC 9788 header protection on a recovered inner entity, FAIL-CLOSED. A payload that does
-// not declare hp surfaces protectedHeaders:null. 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.
-function _hpSurface(content, outerEnt, expectedMode, authenticated) {
-  var none = { protectedHeaders: null, headerProtection: { present: false, mode: null, fromMismatch: false, confidential: [] } };
+// 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.
+function _hpSurface(content, outerEnt, expectedMode, authenticated, legacyEnabled) {
   // 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
   // are never marked or exposed as protected (a caller must not treat protectedHeaders as a trust signal
   // unless integrity held).
-  if (!authenticated) return none;
+  if (!authenticated) return _noneSurface();
   // 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
   // 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);
-  if (!_declaresHp(canon)) return none;
+  // 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.
+  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.
-  var ctCount = 0;
-  inner.headers.forEach(function (h) { if (h.lname === "content-type") ctCount++; });
+  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
@@ -275,58 +438,14 @@ function _hpSurface(content, outerEnt, expectedMode, authenticated) {
   var hp = raw.toLowerCase();
   if (hp !== "clear" && hp !== "cipher") throw _err("smime/bad-header-protection", "the header-protected payload declares an invalid hp value " + JSON.stringify(raw) + " (only clear / cipher)");
   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) + ")");
-  // 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
-  // trimmed value that would diverge from the signed octets.
-  var protectedHeaders = Object.create(null), protectedRaw = Object.create(null), innerFrom = null, seen = Object.create(null), dup = null;
-  var refouter = [];   // RFC 9788 sec. 4.2.1: the HP-Outer records (name + the value the field had in the outer section)
-  inner.headers.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)
-      // -> 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
-      // 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() });
-      return;
-    }
-    if (seen[h.lname]) dup = h.name;
-    seen[h.lname] = 1;
-    protectedHeaders[h.name] = _utf8Header(h.rawValue);   // SURFACE the exact authenticated field body (RFC 6532 UTF-8)
-    protectedRaw[h.name] = h.rawValue;                    // ...but retain the BYTE-PRESERVING (latin1) body for the octet-exact confidentiality comparison
-    // ...and for the mismatch comparison: a lossy UTF-8 decode maps distinct invalid 8-bit sequences (0x80 vs
-    // 0x81) to the same replacement char, which would let an attacker alter the displayed From without
-    // tripping fromMismatch. Compare the raw octets instead.
-    if (h.lname === "from") innerFrom = h.value;
-  });
+  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.
-  if (dup) throw _err("smime/bad-header-protection", "a header-protected payload has a duplicate protected header field " + JSON.stringify(dup));
-  // RFC 9788 sec. 4.3.1: for an ENCRYPTED payload (hp="cipher"), a protected field is end-to-end confidential
-  // (encrypted-only) unless an HP-Outer record carries its EXACT name + value -- i.e. it was copied verbatim
-  // to the visible outer section. A field with no matching HP-Outer (removed, or obscured to a different outer
-  // value) was made confidential. This authenticated set lets a caller reply/forward without leaking it
-  // (sec. 6.1). Signed-only (clear) payloads carry no HP-Outer, so nothing is confidential.
-  var confidential = [];
-  if (hp === "cipher") {
-    Object.keys(protectedHeaders).forEach(function (name) {
-      var ln = name.toLowerCase(), val = protectedRaw[name].trim(), exposed = false;   // octet-exact (latin1), not lossy-decoded
-      for (var i = 0; i < refouter.length; i++) { if (refouter[i].name === ln && refouter[i].value === val) { exposed = true; break; } }
-      if (!exposed) confidential.push(name);
-    });
-  }
-  // Inspect EVERY outer From (outerEnt.header returns only the FIRST; an attacker may append a second, forged
-  // From that a MUA displays) -- a duplicate outer From, or any that disagrees with the protected From, is flagged.
-  var outerFroms = [];
-  outerEnt.headers.forEach(function (h) { if (h.lname === "from") outerFroms.push(h.value.trim()); });   // byte-preserving (latin1), compared octet-for-octet against the protected From
-  // A mismatch is ANYTHING but exactly one outer From equal to the protected one: a removed outer From (a
-  // transport/attacker strips it), a duplicate, or a differing value all flag tampering of the displayed sender.
-  var fromMismatch = innerFrom != null && (outerFroms.length !== 1 || outerFroms[0] !== innerFrom.trim());
-  return { protectedHeaders: protectedHeaders, headerProtection: { present: true, mode: hp, fromMismatch: fromMismatch, confidential: confidential } };
+  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.
+  var confidential = hp === "cipher" ? _computeConfidential(ex.entries, ex.refouter) : [];
+  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).
@@ -459,15 +578,22 @@ function _capped(msg) {
  * chaining a signer certificate to a trust anchor is the caller's `pki.path.validate` step. 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 }`
- * -- `fromMismatch` flags an outer From differing from the protected one; `confidential` lists the protected
- * fields the composer kept end-to-end confidential (per the authenticated HP-Outer records, RFC 9788 sec. 4.3;
- * only populated for an encrypted `hp="cipher"` payload). A non-protected message reports `protectedHeaders: null`.
- * A payload whose declared `hp` is malformed, invalid, or contradicts the envelope fails closed
- * (`smime/bad-header-protection`), never a silent downgrade.
+ * 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
+ * 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
+ * indistinguishable from an ordinary forwarded `message/rfc822`, so a caller keying trust off `present` /
+ * `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 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
  *   var res = await pki.smime.verify(smimeMessageBytes);
  *   if (res.valid) { res.content; res.signers[0].sid; }
@@ -485,7 +611,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));
+    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));
   }
   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");
@@ -512,7 +638,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));
+    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));
   }
   throw _err("smime/unsupported-type", "not a signed S/MIME message (Content-Type " + JSON.stringify(ct.type) + ")");
 }
@@ -624,14 +750,18 @@ async function encrypt(content, recipients, opts) {
  * 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
- * Header Confidentiality Policy hid) and `headerProtection` is `{ present, mode, fromMismatch, confidential }`,
- * where `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`).
+ * 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`).
  *
  * @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.
  * @example
  *   var res = await pki.smime.decrypt(smimeMessageBytes, { key: recipientKeyPkcs8, cert: recipientCertDer });
  *   res.content;        // the recovered inner MIME entity
@@ -658,7 +788,7 @@ async function decrypt(message, keyMaterial, opts) {
     content: res.content, smimeType: smimeType, authenticated: res.authenticated,
     recipientType: res.recipientType, recipientIndex: res.recipientIndex,
     contentEncryptionAlgorithm: res.contentEncryptionAlgorithm,
-  }, _hpSurface(res.content, ent, "cipher", res.authenticated));
+  }, _hpSurface(res.content, ent, "cipher", res.authenticated, opts.legacyHeaderProtection === true));
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:e6deeec3-0517-4316-9e40-caa107241321",
+  "serialNumber": "urn:uuid:5e29cae0-edec-47f9-be9b-305be03dd73c",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-26T18:13:45.078Z",
+    "timestamp": "2026-07-27T02:30:05.287Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.23",
+      "bom-ref": "@blamejs/pki@0.3.25",
       "type": "application",
       "name": "pki",
-      "version": "0.3.23",
+      "version": "0.3.25",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.3.23",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.25",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.23",
+      "ref": "@blamejs/pki@0.3.25",
       "dependsOn": []
     }
   ]