@blamejs/pki 0.2.24 → 0.2.25

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.2.25 — 2026-07-16
+
+S/MIME signed-message assembly and verification arrive as pki.smime: sign and verify RFC 8551 multipart/signed and application/pkcs7-mime messages over the CMS layer, bidirectionally interoperable with OpenSSL.
+
+### Added
+
+- pki.smime.sign(content, signers, opts) assembles a signed RFC 8551 S/MIME message. opts.form selects multipart/signed (default, clear-signed: the canonical entity in the first part and a detached CMS SignedData over its canonical form as an application/pkcs7-signature second part, with protocol="application/pkcs7-signature" and a matching micalg) or pkcs7-mime (opaque: one application/pkcs7-mime; smime-type=signed-data entity whose base64 body is an attached CMS SignedData). content is wrapped as a text/plain entity by default or taken verbatim with opts.entity. Any pki.cms.sign signer (RSA / RSASSA-PSS / ECDSA / EdDSA / ML-DSA / SLH-DSA) carries through. Fail-closed with typed SmimeError.
+- pki.smime.verify(message, opts) unwraps and verifies a signed S/MIME message in both forms, recomputing the detached signature over the first part's RFC 8551 sec. 3.1.1 canonical form (the same canonicalizer the signer used, so a line-ending-mangling transport still verifies and a tampered part fails). It returns pki.cms.verify's { valid, signers } verdict plus the form, the recovered content, and the micalg; a micalg disagreeing with the actual digest is advisory unless opts.strictMicalg. Chaining a signer to a trust anchor is the caller's pki.path.validate step. Bidirectionally interoperable with openssl smime and openssl cms.
+
 ## v0.2.24 — 2026-07-16
 
 SCT-list encoding and log signing join pki.ct: encodeSctList builds an RFC 6962 SignedCertificateTimestampList byte-for-byte, and signSct performs a Certificate Transparency log's signing step, completing the parse/verify/encode/sign symmetry.

package/README.md

@@ -222,6 +222,7 @@ is callable today; nothing below is a stub.
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` / `encode` / `embeddedDer` plus the schema combinators |
 | `pki.path` | RFC 5280 §6 certification-path validation — `validate` runs the §6.1 state machine (signature chaining across RSA, ECDSA, EdDSA, ML-DSA, SLH-DSA and hybrid composite ML-DSA signatures — a composite is accepted only when **both** its post-quantum and traditional components verify; validity windows, name chaining, basic constraints and path length, key usage, name constraints, the certificate-policy tree) over an ordered path and a trust anchor, returning a structured verdict with per-check reason codes, and enforces a `pki.trust` anchor's per-purpose distrust-after dates and delegator purposes via `checkPurpose`; `crlChecker` supplies CRL-based revocation — including partitioned/sharded CRLs, whose §6.3.3 Distribution Point ↔ IDP correspondence lets a corresponding full-reason shard establish non-revocation — and `ocspChecker` supplies OCSP-based revocation (RFC 6960 — CertID binding, responder authorization, signature, currency) over the same pluggable hook. Pure and re-entrant, fail-closed — `validate`, `crlChecker`, `ocspChecker` |
 | `pki.cms` | RFC 5652 §5 CMS SignedData signing + signature verification — `sign(content, signers, opts)` produces a SignedData (attached or detached, one or many signers, RSA / RSASSA-PSS / ECDSA / EdDSA, the post-quantum ML-DSA-44/65/87 (RFC 9882) and SLH-DSA (all twelve FIPS 205 sets, RFC 9814), and composite ML-DSA (pairing ML-DSA with a traditional RSA / ECDSA / EdDSA — accepted only when **both** components verify — draft-ietf-lamps-cms-composite-sigs)); it builds the signed attributes (content-type, message-digest, signing-time) as canonical DER, signs the exact §5.4 preimage, and emits a DER `Buffer` or PEM. `verify(input, opts)` parses a SignedData over the strict `pki.schema.cms` codec, locates each SignerInfo's signer certificate by its issuerAndSerialNumber or subjectKeyIdentifier, and checks the signature over the exact §5.4 preimage: when signed attributes are present it confirms the message-digest attribute equals the content digest and verifies over the DER re-encoding of the SignedAttributes (the on-wire `[0]` tag replaced by a universal SET OF), otherwise directly over the content. It returns a per-signer verdict with the matched signer certificate; it does not chain that certificate to a trust anchor — that is the caller's step through `pki.path.validate`. **Content encryption** (RFC 5652/5083/5084/9629): `encrypt(content, recipients, opts)` produces an EnvelopedData, AuthEnvelopedData (AES-GCM, the authenticated default), or EncryptedData — recipients auto-dispatch off the certificate key to key-transport (RSAES-OAEP; v1.5 never emitted), key-agreement (ephemeral-static ECDH over P-256/384/521 with the X9.63 KDF, and X25519/X448 with HKDF), symmetric key-wrap, password (PBKDF2 + RFC 3211 PWRI-KEK), or the post-quantum ML-KEM KEMRecipientInfo (RFC 9629/9936) — one fresh content key wrapped for every recipient. `decrypt(input, keyMaterial, opts)` recovers the content through the matching arm and returns it with an `authenticated` flag; every secret-dependent failure collapses to one uniform `cms/decrypt-failed` verdict (Bleichenbacher / EFAIL / password-oracle freedom), and PKCS#1 v1.5 is decrypt-only under the RFC 3218 implicit-rejection countermeasure. Fail-closed with typed `cms/*` errors — `sign`, `verify`, `encrypt`, `decrypt` |
+| `pki.smime` | RFC 8551 S/MIME message assembly + verification over the CMS layer — `sign(content, signers, opts)` wraps a MIME entity as a signed S/MIME message in either form: `multipart/signed` (clear-signed — the content stays readable in any MUA, a detached CMS SignedData rides alongside as `application/pkcs7-signature` with a matching `micalg`) or `application/pkcs7-mime; smime-type=signed-data` (opaque — the whole entity is a base64 CMS SignedData). The signed bytes are the entity's RFC 8551 §3.1.1 canonical form (CRLF line endings); `verify(message, opts)` unwraps both forms and recomputes over the same canonicalizer, so a transport that re-wraps line endings still verifies and a tampered part fails. The crypto is entirely `pki.cms.sign` / `pki.cms.verify` — any RSA / RSASSA-PSS / ECDSA / EdDSA / ML-DSA / SLH-DSA signer carries through (algorithm-agnostic). Like `cms.verify`, it returns the per-signer cryptographic verdict plus the recovered content; chaining a signer to a trust anchor is the caller's `pki.path.validate` step. Bidirectionally interoperable with `openssl smime` / `openssl cms`. Fail-closed with typed `smime/*` errors — `sign`, `verify` |
 | `pki.tsp` | RFC 3161 Time-Stamp Protocol — `sign(messageImprint, tsa, opts)` produces a TimeStampToken: a CMS SignedData (over `pki.cms.sign`) whose content is a `TSTInfo` carrying the timestamped message imprint, the TSA policy, a serial number, and `genTime` (with optional accuracy / nonce / ordering), plus the RFC 3161 §2.4.2 signing-certificate attribute binding the token to the TSA certificate (SHA-2 imprints, any `pki.cms.sign` TSA key). `request` / `parseRequest` build and parse the TimeStampReq a client sends (imprint, requested policy, nonce, certReq), `response` / `parseResponse` the TimeStampResp a TSA returns — a granted status wrapping a token, or a rejection with PKIStatus and failure info, the §2.4.2 status↔token coupling enforced in both directions. `verify(token, data, opts)` verifies a token fail-closed: the CMS signature over the exact signed bytes, the message imprint recomputed from the data, the TSTInfo content type, the ESSCertID(V2) binding to the TSA certificate, the §2.3 critical timeStamping-only extendedKeyUsage, the request nonce when used, and — with a trust anchor supplied — full certification-path validation of the TSA certificate at the token's `genTime`, returning `{ valid, genTime, serialNumber, tstInfo, … }` — `sign`, `request`, `parseRequest`, `response`, `parseResponse`, `verify` |
 | `pki.ocsp` | RFC 6960 Online Certificate Status Protocol — the responder and relying-party surface. `buildRequest(query, opts)` builds an OCSPRequest for one or more `{ cert, issuer }` pairs (CertID hashed under SHA-1 by default per the RFC 5019 lightweight profile, or SHA-2; optional RFC 9654 nonce, optional requestor signature). `sign(responseData, responder, opts)` produces a signed BasicOCSPResponse over the exact `ResponseData` DER — the issuing CA directly or a delegated responder, any `pki.cms.sign` key including the post-quantum ML-DSA / SLH-DSA sets, with `good` / `revoked` (reason + time) / `unknown` per-certificate status, and `buildErrorResponse(status)` the unsigned §2.3 error (`tryLater` / `unauthorized` / …). `verify(response, opts)` verifies a response fail-closed against the same hardened gates `pki.path.ocspChecker` runs: the CertID binding, responder authorization (the issuing CA or a CA-issued delegate bearing id-kp-OCSPSigning **and** id-pkix-ocsp-nocheck, passing the full out-of-path certificate gates), the signature over `tbsResponseDataBytes`, currency (`thisUpdate`/`nextUpdate`), and the request-nonce echo — returning `{ status: "good" / "revoked" / "unknown", … }`, never a silent accept. Transport-free — `buildRequest`, `sign`, `buildErrorResponse`, `verify` |
 | `pki.ct` | RFC 6962 Certificate Transparency SCTs — `parseSctList` decodes the `SignedCertificateTimestampList` a certificate or OCSP response carries in the SCT extension (a TLS-presentation-language payload inside the §3.3 double DER wrap) into per-SCT log id, exact `timestamp` (BigInt), named signature algorithm, and raw signature; `reconstructSignedData` rebuilds the exact `digitally-signed` preimage; `verifySct` verifies an SCT signature against a log's public key by reconstructing the signed data, routing an ECDSA signature through the strict DER-conformance gate, and verifying through the crypto engine — resolving true or false, and throwing a typed error on a structural fault. The producing side: `encodeSctList` builds the extension value byte-for-byte (the exact inverse of `parseSctList`) and `signSct` performs a log's signing step (rebuilding the same signed-data preimage the verifier hashes and signing it with the log's ECDSA-P-256 / RSA key). Structure decoded, crypto fail-closed — `parseSctList`, `reconstructSignedData`, `verifySct`, `encodeSctList`, `signSct` |

package/index.js

@@ -37,6 +37,7 @@ var schema    = require("./lib/schema-all");
 var path      = require("./lib/path-validate");
 var ct        = require("./lib/ct");
 var cms       = require("./lib/cms-verify");
+var smime     = require("./lib/smime");
 var tsp       = require("./lib/tsp-sign");
 var ocsp      = require("./lib/ocsp");
 var merkle    = require("./lib/merkle");
@@ -77,6 +78,7 @@ module.exports = {
   // surfaced raw for external verification (pki.ct.reconstructSignedData).
   ct:        ct,
   cms:       cms,
+  smime:     smime,
   tsp:       tsp,
   ocsp:      ocsp,
   // `merkle` is the RFC 6962 / RFC 9162 Merkle-tree proof-verification core --

package/lib/cms-verify.js

@@ -516,6 +516,14 @@ function verify(input, opts) {
   if (content == null) {
     if (opts.content == null) throw _err("cms/detached-content-required", "this SignedData is detached; opts.content (the external content) is required");
     content = _toBuf(opts.content, "opts.content");
+  } else if (opts.content != null) {
+    // A caller supplied external content AND the SignedData is attached. A redundant COPY that equals
+    // the encapsulated content is fine; content that DIFFERS is a substitution trap -- silently
+    // preferring the embedded copy would let the caller believe it verified opts.content when the
+    // signature covers different embedded bytes. Fail closed on a mismatch.
+    if (Buffer.compare(_toBuf(opts.content, "opts.content"), Buffer.from(content)) !== 0) {
+      throw _err("cms/content-conflict", "opts.content disagrees with this SignedData's own encapsulated content (a detached signature must omit eContent)");
+    }
   }
   // Pre-parse every candidate certificate (embedded + caller-supplied) once.
   var parsedCerts = [];

package/lib/constants.js

@@ -233,6 +233,8 @@ var LIMITS = {
   // 10M clears the authoring default (600k) with generous headroom for high-security policies.
   PBKDF2_MAX_ITERATIONS: 10000000,
   PBKDF2_MAX_SALT: 1024,
+  // A MIME entity / S/MIME message size ceiling -- bounds the header + body decode before a copy.
+  MIME_MAX_BYTES: BYTES.mib(16),
   // ACME challenge token entropy floor (RFC 8555 sec. 8, errata 6950): >= 128
   // bits of base64url is >= 22 characters. A shorter token is refused before use.
   ACME_TOKEN_MIN_CHARS: 22,

package/lib/mime.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @internal
+ * lib/mime.js -- a minimal MIME entity framer + canonicalizer, the message-layer engine primitive
+ * under pki.smime (RFC 8551 S/MIME) and any future MIME-carrying feature. It parses an entity into
+ * its headers + body, canonicalizes a text entity to the RFC 8551 sec. 3.1.1 form (CRLF line endings),
+ * splits a multipart body on its boundary, and builds an entity/multipart back. There is NO crypto
+ * here -- the CMS layer signs/verifies the canonical bytes this module produces.
+ *
+ * The LOAD-BEARING rule is canonicalization: the detached signature over a multipart/signed first part
+ * is computed over that part's canonical MIME form, so the signer and verifier MUST share ONE
+ * canonicalizer -- this module. It carries the caller's typed ErrorClass `E` (constructed
+ * `new E(code, message)`), exactly as the byte-reader / guard family do, so every consumer keeps its
+ * own `domain/reason` fault code.
+ */
+
+var C = require("./constants.js");
+var guard = require("./guard-all.js");
+
+var CRLF = Buffer.from("\r\n");
+
+// A byte source -> a Buffer view, capped before any copy (CWE-770/400).
+function _buf(v, E, code, label) { return guard.bytes.view(v, E, code, label); }
+
+// Locate the header/body separator: the first empty line (a bare LF-LF or CRLF-CRLF, or a mix).
+// Returns { headerEnd, bodyStart } offsets, or null when there is no blank-line separator.
+function _splitPoint(bytes) {
+  for (var i = 0; i < bytes.length; i++) {
+    if (bytes[i] === 0x0a) {                                   // LF
+      if (i + 1 < bytes.length && bytes[i + 1] === 0x0a) return { headerEnd: i, bodyStart: i + 2 };           // LF LF
+      if (i + 2 < bytes.length && bytes[i + 1] === 0x0d && bytes[i + 2] === 0x0a) return { headerEnd: i, bodyStart: i + 3 };  // LF CRLF
+    }
+  }
+  return null;
+}
+
+// Split a header block into unfolded logical lines (RFC 5322 folding: a continuation line begins with
+// SP/HTAB and joins the previous). Returns the raw header strings (each "Name: value").
+function _unfoldHeaders(headerText) {
+  var lines = headerText.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  var out = [];
+  for (var i = 0; i < lines.length; i++) {
+    var ln = lines[i];
+    if (ln === "") continue;
+    if ((ln[0] === " " || ln[0] === "\t") && out.length) out[out.length - 1] += " " + ln.replace(/^[ \t]+/, "");
+    else out.push(ln);
+  }
+  return out;
+}
+
+// Parse a Content-Type / any structured header value into { value, type, params } -- the media type
+// (lowercased) plus its parameters (names lowercased, quotes stripped). Tolerant of extra whitespace.
+function _parseStructured(headerValue) {
+  var parts = _splitSemicolons(headerValue);   // always >= 1 element
+  var type = parts[0].trim().toLowerCase();
+  var params = {};
+  for (var i = 1; i < parts.length; i++) {
+    var eq = parts[i].indexOf("=");
+    if (eq < 0) continue;
+    var name = parts[i].slice(0, eq).trim().toLowerCase();
+    var val = parts[i].slice(eq + 1).trim();
+    if (val.length >= 2 && val[0] === '"' && val[val.length - 1] === '"') val = val.slice(1, -1);
+    params[name] = val;
+  }
+  return { value: headerValue.trim(), type: type, params: params };
+}
+
+// Split on ";" while respecting double-quoted spans (a boundary/protocol value may be quoted).
+function _splitSemicolons(s) {
+  var out = [], cur = "", inQ = false;
+  for (var i = 0; i < s.length; i++) {
+    var ch = s[i];
+    if (ch === '"') { inQ = !inQ; cur += ch; }
+    else if (ch === ";" && !inQ) { out.push(cur); cur = ""; }
+    else cur += ch;
+  }
+  out.push(cur);
+  return out;
+}
+
+// Parse a MIME entity (headers + body). `contentType` / `cte` are decoded; `header(name)` looks up a
+// header case-insensitively; `body` is the raw body Buffer. `headerBytes` / `bodyBytes` are the exact
+// slices (a signature over a first part must reference exact bytes, never a re-serialization).
+function parse(input, E, code) {
+  var bytes = _buf(input, E, code, "the MIME entity");
+  // Coverage residual: the DoS ceiling only fires on a >16 MiB message (a real cap, exercised by no
+  // unit vector -- driving it would allocate 16 MiB).
+  if (bytes.length > C.LIMITS.MIME_MAX_BYTES) throw new E(code, "MIME entity exceeds the size cap");
+  var sp = _splitPoint(bytes);
+  var headerBytes = sp ? bytes.subarray(0, sp.headerEnd) : bytes;
+  var bodyBytes = sp ? bytes.subarray(sp.bodyStart) : Buffer.alloc(0);
+  var headerText = guard.text.decode(headerBytes, C.LIMITS.MIME_MAX_BYTES, E, { charset: "latin1", tooLarge: code, badInput: code, label: "the MIME headers" });
+  var rawHeaders = _unfoldHeaders(headerText);
+  var headers = [];
+  for (var i = 0; i < rawHeaders.length; i++) {
+    var colon = rawHeaders[i].indexOf(":");
+    if (colon < 0) throw new E(code, "a MIME header line has no colon: " + JSON.stringify(rawHeaders[i].slice(0, 40)));
+    headers.push({ name: rawHeaders[i].slice(0, colon).trim(), lname: rawHeaders[i].slice(0, colon).trim().toLowerCase(), value: rawHeaders[i].slice(colon + 1).trim() });
+  }
+  function header(name) { var l = name.toLowerCase(); for (var j = 0; j < headers.length; j++) if (headers[j].lname === l) return headers[j].value; return null; }
+  var ctv = header("content-type");
+  var cte = (header("content-transfer-encoding") || "").trim().toLowerCase() || "7bit";
+  return {
+    headers: headers, header: header,
+    contentType: ctv != null ? _parseStructured(ctv) : { value: "text/plain", type: "text/plain", params: {} },
+    cte: cte,
+    headerBytes: headerBytes, bodyBytes: bodyBytes, body: bodyBytes, bytes: bytes,
+  };
+}
+
+// Normalize a text body's line endings to the RFC 8551 sec. 3.1.1 canonical CRLF pair (any bare CR or
+// LF becomes CRLF; an existing CRLF is preserved).
+function canonicalizeText(bodyBytes) {
+  var s = bodyBytes.toString("latin1").replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\n/g, "\r\n");
+  return Buffer.from(s, "latin1");
+}
+
+// The canonical MIME form of a part for signing (RFC 8551 sec. 3.1.1): line endings normalized to the
+// CRLF pair over the EXACT bytes -- never a header re-serialization, which would diverge from the
+// signer's digest (and would break a header-less clear-signed part, as OpenSSL's `smime -sign` emits).
+// The signer and verifier both call THIS, so their digests cannot diverge; a transport that mangles
+// CR/LF is repaired identically on both sides. (A binary clear-signed part must carry a base64
+// Content-Transfer-Encoding first -- line-ending canonicalization is defined for text, sec. 3.1.1.)
+function canonicalize(input, E, code) {
+  return canonicalizeText(_buf(input, E, code, "the MIME part"));
+}
+
+// Split a multipart body on its boundary into the exact bytes of each part (RFC 2046 sec. 5.1.1). A
+// part runs from after the "--boundary CRLF" delimiter to just before the "CRLF--boundary" that ends
+// it; the CRLF preceding a boundary is part of the delimiter, not the part (the S/MIME signing rule).
+function splitMultipart(bodyBytes, boundary, E, code) {
+  if (!boundary) throw new E(code, "a multipart entity is missing its boundary parameter");
+  var delim = Buffer.from("--" + boundary);
+  var body = bodyBytes;
+  var idx = _findDelim(body, delim, 0);
+  if (idx < 0) throw new E(code, "no boundary delimiter found in the multipart body");
+  // Advance past the opening delimiter line.
+  var pos = _afterLine(body, idx + delim.length, E, code);
+  var parts = [];
+  while (true) {
+    var next = _findDelim(body, delim, pos);
+    if (next < 0) throw new E(code, "an unterminated multipart body part (no closing boundary)");
+    // The part ends at the CRLF (or LF) that immediately precedes this boundary delimiter.
+    var partEnd = next;
+    if (partEnd >= 2 && body[partEnd - 2] === 0x0d && body[partEnd - 1] === 0x0a) partEnd -= 2;
+    else if (partEnd >= 1 && body[partEnd - 1] === 0x0a) partEnd -= 1;
+    parts.push(body.subarray(pos, partEnd));
+    // A closing delimiter is "--boundary--"; otherwise advance past this delimiter line to the next part.
+    var afterDelim = next + delim.length;
+    if (body[afterDelim] === 0x2d && body[afterDelim + 1] === 0x2d) break;   // "--"
+    pos = _afterLine(body, afterDelim, E, code);
+  }
+  return parts;
+}
+
+// The next LINE-ANCHORED "--boundary" delimiter at or after `from` (RFC 2046 sec. 5.1.1): it MUST begin
+// a line (at the body start, or immediately after an LF) AND its line MUST be a complete delimiter --
+// the token, then an optional "--" (close), then only transport-padding whitespace, then CRLF / LF /
+// end-of-buffer. So a "--boundary" substring mid-content, a "--boundaryextra" (a different token), a
+// "--boundary garbage" line, or one not at a line start is NOT matched -- an attacker cannot inject a
+// fake delimiter inside a part's content.
+function _findDelim(body, delim, from) {
+  for (var at = body.indexOf(delim, from); at >= 0; at = body.indexOf(delim, at + delim.length)) {
+    if ((at === 0 || body[at - 1] === 0x0a) && _delimLineOk(body, at + delim.length)) return at;
+  }
+  return -1;
+}
+// The suffix after the "--boundary" token is a valid delimiter line: an optional closing "--", then
+// zero or more LWSP (space / HTAB transport padding), then CRLF / LF / end-of-buffer. Anything else
+// (non-whitespace before the line end) means this is content, not a delimiter.
+function _delimLineOk(body, i) {
+  if (body[i] === 0x2d && body[i + 1] === 0x2d) i += 2;
+  while (body[i] === 0x20 || body[i] === 0x09) i++;
+  return i >= body.length || body[i] === 0x0d || body[i] === 0x0a;
+}
+
+// The offset just past the end of the current line (skipping to after the next LF).
+function _afterLine(buf, from, E, code) {
+  for (var i = from; i < buf.length; i++) if (buf[i] === 0x0a) return i + 1;
+  throw new E(code, "a multipart boundary line is not terminated");
+}
+
+module.exports = {
+  parse: parse,
+  canonicalize: canonicalize,
+  canonicalizeText: canonicalizeText,
+  splitMultipart: splitMultipart,
+  CRLF: CRLF,
+};

package/lib/smime.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.smime
+ * @nav        Messaging
+ * @title      S/MIME
+ * @order      175
+ * @slug       smime
+ *
+ * @intro
+ *   RFC 8551 S/MIME assembly + verification over the shipped CMS 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
+ *   SignedData). The crypto is entirely `pki.cms.sign` / `pki.cms.verify`; the
+ *   new work is the MIME frame and the RFC 8551 sec. 3.1.1 canonicalization the
+ *   detached signature is computed over -- signer and verifier share one
+ *   canonicalizer (`lib/mime.js`) so their digests cannot diverge. Like
+ *   `cms.verify`, `verify` returns the per-signer cryptographic verdict; chaining
+ *   a signer to a trust anchor is the caller's `pki.path.validate` step.
+ *
+ * @card
+ *   Assemble + verify RFC 8551 S/MIME signed messages (multipart/signed +
+ *   application/pkcs7-mime) over any CMS signer -- shared canonicalization,
+ *   fail-closed, algorithm-agnostic.
+ */
+
+var frameworkError = require("./framework-error.js");
+var mime = require("./mime.js");
+var cms = require("./cms-verify.js");
+var schemaCms = require("./schema-cms.js");
+var guard = require("./guard-all.js");
+var C = require("./constants.js");
+var nodeCrypto = require("crypto");
+
+var SmimeError = frameworkError.SmimeError;
+
+function _err(code, msg, cause) { return new SmimeError(code, msg, cause); }
+
+// RFC 8551 uses application/pkcs7-<kind>; OpenSSL's legacy `smime` command emits the PKCS#7
+// application/x-pkcs7-<kind>. Accept both on the RECEIVE side (we always EMIT the RFC 8551 form).
+function _isPkcs7(type, kind) {
+  var t = (type || "").toLowerCase();
+  return t === "application/pkcs7-" + kind || t === "application/x-pkcs7-" + 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
+// `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.
+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");
+  var ct = opts.contentType || "text/plain; charset=utf-8";
+  // Declare the honest Content-Transfer-Encoding: "7bit" requires every byte <= 127 (RFC 2045); a body
+  // with any 8-bit byte is "8bit". Declaring 7bit for 8-bit content is a false claim a transport could act on.
+  var cte = _is7bit(raw) ? "7bit" : "8bit";
+  var head = Buffer.from("Content-Type: " + ct + "\r\nContent-Transfer-Encoding: " + cte + "\r\n\r\n", "latin1");
+  return mime.canonicalize(Buffer.concat([head, raw]), SmimeError, "smime/bad-mime");
+}
+function _is7bit(buf) { for (var i = 0; i < buf.length; i++) if (buf[i] > 0x7f) return false; return true; }
+
+// Map smime opts to cms.sign opts (the S/MIME layer is algorithm-agnostic -- it forwards any signer).
+function _cmsSignOpts(opts, detached) {
+  var o = { detached: detached };
+  if (opts.signingTime !== undefined) o.signingTime = opts.signingTime;
+  if (opts.sid) o.sid = opts.sid;
+  if (opts.signedAttributes !== undefined) o.signedAttributes = opts.signedAttributes;
+  if (opts.additionalSignedAttributes) o.additionalSignedAttributes = opts.additionalSignedAttributes;
+  return o;
+}
+
+// Coverage residual: the defensive `|| default` fallbacks in the helpers below (a null media type, a
+// non-standard SignerInfo digest name -> a derived micalg, an absent micalg -> "sha-256"/null, a
+// non-Buffer cms.sign result) and the two catch arms (a CMS body that passed cms.verify yet fails a
+// second schema-cms.parse) are belt-and-braces around the primary path the round-trips exercise; the
+// producer never emits any of them.
+function _micName(name) { return name ? (MICALG[name] || name) : null; }
+// Normalize a micalg header value into the same sorted-distinct comma-joined form _micalgOf emits.
+function _micalgSet(value) {
+  var seen = [];
+  String(value).split(",").forEach(function (m) { var t = m.trim().toLowerCase(); if (t && seen.indexOf(t) < 0) seen.push(t); });
+  return seen.sort().join(",");
+}
+// The micalg for the SignedData -- RFC 8551 sec. 3.4.3.2: EVERY signer's message-digest algorithm,
+// distinct, sorted, comma-separated (a multi-signer message with mixed digests lists them all).
+function _micalgOf(p7Der) {
+  var parsed;
+  try { parsed = schemaCms.parse(guard.bytes.view(p7Der, SmimeError, "smime/bad-mime", "the CMS body")); }
+  catch (e) { throw _err("smime/bad-mime", "the CMS SignedData body could not be parsed", e); }
+  var out = [];
+  (parsed.signerInfos || []).forEach(function (si) {
+    var mic = _micName(si.digestAlgorithm && si.digestAlgorithm.name);
+    if (mic && out.indexOf(mic) < 0) out.push(mic);
+  });
+  return out.length ? out.sort().join(",") : null;
+}
+
+// A fresh multipart boundary that cannot collide with the content (random, dashed, unique per call).
+function _boundary() { return "----=_pki_smime_" + nodeCrypto.randomBytes(18).toString("hex"); }
+
+function _base64Body(der) {
+  return Buffer.from(der.toString("base64").replace(/(.{64})/g, "$1\r\n").replace(/\r\n$/, ""), "latin1");
+}
+
+/**
+ * @primitive  pki.smime.sign
+ * @signature  pki.smime.sign(content, signers, opts?) -> Promise<Buffer>
+ * @since      0.2.25
+ * @status     experimental
+ * @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
+ * `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`:
+ *   - `"multipart"` (default, clear-signed): a `multipart/signed` message carrying the canonical entity
+ *     verbatim in the first part and a DETACHED CMS SignedData (`application/pkcs7-signature`) over its
+ *     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
+ * canonicalizer runs on verify. 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.
+ * @example
+ *   var msg = await pki.smime.sign(Buffer.from("hello"), [{ cert: signerCertDer, key: signerKeyPkcs8 }]);
+ */
+async function sign(content, signers, opts) {
+  opts = opts || {};
+  var entity = _entityBytes(content, opts);
+  var form = opts.form || "multipart";
+  if (form === "pkcs7-mime") {
+    var p7m = await cms.sign(entity, signers, _cmsSignOpts(opts, false));
+    var head = Buffer.from("Content-Type: application/pkcs7-mime; smime-type=signed-data; name=smime.p7m\r\nContent-Transfer-Encoding: base64\r\nContent-Disposition: attachment; filename=smime.p7m\r\n\r\n", "latin1");
+    return _capped(Buffer.concat([head, _base64Body(_toBuf(p7m)), mime.CRLF]));
+  }
+  if (form !== "multipart") throw _err("smime/bad-input", "form must be \"multipart\" or \"pkcs7-mime\"");
+  var p7s = _toBuf(await cms.sign(entity, signers, _cmsSignOpts(opts, true)));
+  var micalg = _micalgOf(p7s) || "sha-256";
+  var boundary = _boundary();
+  var head2 = Buffer.from("Content-Type: multipart/signed; protocol=\"application/pkcs7-signature\"; micalg=" + micalg + "; boundary=\"" + boundary + "\"\r\n\r\n", "latin1");
+  var sigPart = Buffer.concat([
+    Buffer.from("Content-Type: application/pkcs7-signature; name=smime.p7s\r\nContent-Transfer-Encoding: base64\r\nContent-Disposition: attachment; filename=smime.p7s\r\n\r\n", "latin1"),
+    _base64Body(p7s),
+  ]);
+  var dl = Buffer.from("--" + boundary + "\r\n", "latin1"), close = Buffer.from("--" + boundary + "--\r\n", "latin1");
+  return _capped(Buffer.concat([head2, dl, entity, mime.CRLF, dl, sigPart, mime.CRLF, close]));
+}
+
+// A produced message MUST stay within the same size ceiling verify enforces on receive, so sign never
+// emits an S/MIME message our own verify would reject as too large (producer/consumer symmetry).
+// Coverage residual: the throw only fires on a >16 MiB assembled message -- a real cap, exercised by no
+// unit vector (driving it would sign 16 MiB).
+function _capped(msg) {
+  if (msg.length > C.LIMITS.MIME_MAX_BYTES) throw _err("smime/too-large", "the assembled S/MIME message (" + msg.length + " bytes) exceeds the " + C.LIMITS.MIME_MAX_BYTES + "-byte cap that verify enforces");
+  return msg;
+}
+
+/**
+ * @primitive  pki.smime.verify
+ * @signature  pki.smime.verify(message, opts?) -> Promise<{ valid, signers, form, content, micalg }>
+ * @since      0.2.25
+ * @status     experimental
+ * @spec       RFC 8551, RFC 5652
+ * @related    pki.smime.sign, pki.cms.verify, pki.path.validate
+ *
+ * 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
+ * signer used); for `application/pkcs7-mime` the base64 body is the attached CMS SignedData. Returns
+ * `pki.cms.verify`'s `{ valid, signers }` verdict PLUS `form`, the recovered `content` (the signed MIME
+ * entity bytes), and the `micalg`. Like `cms.verify`, this returns the cryptographic verdict only --
+ * chaining a signer certificate to a trust anchor is the caller's `pki.path.validate` step. A `micalg`
+ * that disagrees with the actual digest is advisory unless `opts.strictMicalg` (then `smime/micalg-mismatch`).
+ *
+ * @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.
+ * @example
+ *   var res = await pki.smime.verify(smimeMessageBytes);
+ *   if (res.valid) { res.content; res.signers[0].sid; }
+ */
+async function verify(message, opts) {
+  opts = opts || {};
+  var ent = mime.parse(message, SmimeError, "smime/bad-mime");
+  var ct = ent.contentType;
+  var vOpts = {};
+  if (opts.certs) vOpts.certs = opts.certs;
+  if (_isPkcs7(ct.type, "mime")) {
+    if (ct.params["smime-type"] && ct.params["smime-type"] !== "signed-data") throw _err("smime/unsupported-type", "unsupported smime-type " + JSON.stringify(ct.params["smime-type"]) + " (only signed-data)");
+    var p7m = _decodeCms(ent);
+    var res = await cms.verify(p7m, vOpts);
+    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 { valid: res.valid, signers: res.signers, form: "pkcs7-mime", content: inner, micalg: null };
+  }
+  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");
+    var parts = mime.splitMultipart(ent.body, ct.params.boundary, SmimeError, "smime/bad-multipart");
+    if (parts.length !== 2) throw _err("smime/bad-multipart", "multipart/signed must have exactly two body parts, got " + parts.length);
+    var sigEnt = mime.parse(parts[1], SmimeError, "smime/bad-mime");
+    if (!_isPkcs7(sigEnt.contentType.type, "signature")) throw _err("smime/bad-multipart", "the second part must be application/pkcs7-signature");
+    var p7s = _decodeCms(sigEnt);
+    // RFC 8551 sec. 3.4 / RFC 1847: the multipart/signed signature is DETACHED -- the SignedData carries
+    // NO encapsulated content, the first MIME part IS the signed unit. Reject an ATTACHED SignedData:
+    // otherwise cms.verify would verify over the embedded eContent and IGNORE the first part, so an
+    // attacker could pair any validly-signed attached blob with an arbitrary first part (a forgery).
+    var sd;
+    try { sd = schemaCms.parse(p7s); }
+    catch (e) { throw _err("smime/bad-mime", "the pkcs7-signature part is not a CMS SignedData", e); }
+    if (sd.encapContentInfo && sd.encapContentInfo.eContent != null) {
+      throw _err("smime/bad-multipart", "the pkcs7-signature part must carry a DETACHED SignedData (no encapsulated content) (RFC 8551 sec. 3.4)");
+    }
+    var canon = mime.canonicalize(parts[0], SmimeError, "smime/bad-mime");
+    var res2 = await cms.verify(p7s, Object.assign({}, vOpts, { content: canon }));
+    var micalg = ct.params.micalg || null;
+    // Compare micalg as an ORDER-INDEPENDENT set of digest names (RFC 8551 sec. 3.4.3.2 lists them
+    // comma-separated, in no required order, possibly with whitespace).
+    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 { valid: res2.valid, signers: res2.signers, form: "multipart/signed", content: parts[0], micalg: micalg };
+  }
+  throw _err("smime/unsupported-type", "not a signed S/MIME message (Content-Type " + JSON.stringify(ct.type) + ")");
+}
+
+// Decode a CMS body per its Content-Transfer-Encoding (base64 is the S/MIME norm; 7bit/8bit/binary pass through).
+function _decodeCms(ent) {
+  // guard.encoding.base64 is strict (no whitespace) and rejects via a (code,msg) FACTORY -- strip the
+  // MIME line-wrapping whitespace first, and pass _err (not the SmimeError class).
+  if (ent.cte === "base64") return guard.encoding.base64(ent.body.toString("latin1").replace(/[\r\n\t ]/g, ""), C.LIMITS.MIME_MAX_BYTES, _err, "smime/bad-mime", "the CMS body");
+  return ent.body;
+}
+
+function _toBuf(v) { return Buffer.isBuffer(v) ? v : Buffer.from(v); }
+
+module.exports = { sign: sign, verify: verify };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.24",
+  "version": "0.2.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:778bbc49-b521-4695-b1a1-915cda8b8012",
+  "serialNumber": "urn:uuid:40b168db-ab8a-4925-b224-648cd2ed3f10",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-16T09:47:36.237Z",
+    "timestamp": "2026-07-16T11:50:45.040Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.24",
+      "bom-ref": "@blamejs/pki@0.2.25",
       "type": "application",
       "name": "pki",
-      "version": "0.2.24",
+      "version": "0.2.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.2.24",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.25",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.24",
+      "ref": "@blamejs/pki@0.2.25",
       "dependsOn": []
     }
   ]