@blamejs/pki 0.2.23 → 0.2.25

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.
+
+### Added
+
+- pki.ct.encodeSctList(scts) builds an RFC 6962 SCT-list extension value from an array of SCTs -- the exact inverse of pki.ct.parseSctList (byte-identical round-trip). A decoded v1 SCT is rebuilt from its fields in the RFC 6962 sec. 3.2 order; an opaque non-v1 entry re-emits its rawSct verbatim (forward compatibility). The list must be non-empty and stays within the parser's SCT_MAX_COUNT / SCT_MAX_BYTES caps. Fail-closed with a typed CtError.
+- pki.ct.signSct(entry, logKey, opts) performs a Certificate Transparency log's signing step (RFC 6962 sec. 3.2): it rebuilds the digitally-signed preimage via the same reconstructSignedData builder the verifier hashes, signs it with the log's private key (ECDSA NIST P-256 or RSA >= 2048, SHA-256 per sec. 2.1.4), and returns a fully-formed v1 SCT that pki.ct.verifySct accepts. The LogID is derived as SHA-256 of the log's SubjectPublicKeyInfo (sec. 3.4); a supplied opts.logId must match. Composes with encodeSctList to assemble a signed SCT-list extension.
+
 ## v0.2.23 — 2026-07-16
 
 CMS content encryption arrives as pki.cms.encrypt and pki.cms.decrypt: EnvelopedData, AuthEnvelopedData, and EncryptedData with every RFC 5652 recipient type -- RSA-OAEP, ephemeral-static ECDH, X25519/X448, symmetric key-wrap, password, and post-quantum ML-KEM (RFC 9629/9936) -- and a single, oracle-free decryption verdict.

package/README.md

@@ -222,9 +222,10 @@ 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. Structure decoded, crypto fail-closed — `parseSctList`, `reconstructSignedData`, `verifySct` |
+| `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` |
 | `pki.merkle` | RFC 6962 / RFC 9162 Merkle-tree proof verification — `leafHash` / `nodeHash` / `emptyRootHash` build the domain-separated (0x00 leaf / 0x01 node) SHA-256 tree hashes; `verifyInclusion` folds an audit proof back to a root and `verifyConsistency` reconstructs both the old and new root (the append-only guarantee), each constant-time-compared to a trusted checkpoint root. Fail-closed on bad geometry, sync hashing, transport-free — `leafHash`, `nodeHash`, `emptyRootHash`, `verifyInclusion`, `verifyConsistency` |
 | `pki.trust` | Mozilla / CCADB trust-store ingestion — `parseCertdata` reads the NSS `certdata.txt` object stream and `parseCcadbCsv` the CCADB CSV export into one identical constraint-carrying anchor shape: the per-purpose trust bits (only `CKT_NSS_TRUSTED_DELEGATOR` grants) and the per-purpose distrust-after dates the bare root list omits. Certificate and trust objects pair by byte-exact issuer + serial (never adjacency) and are cross-checked against the parsed DER, so metadata can never attach to the wrong root; `anchor()` hands an entry to `pki.path.validate({ trustAnchor, checkPurpose })`. Offline, fail-closed, bounded — `parseCertdata`, `parseCcadbCsv`, `anchor` |
 | `pki.shbs` | Stateful hash-based signature **verification** — HSS/LMS (RFC 8554), carried in X.509 by RFC 9802 and CMS by RFC 9708, profiled by NIST SP 800-208 (CNSA 2.0 firmware signing). `verify` checks an HSS signature (every level must pass) and `verifyLms` a single-tree LMS, over the raw public-key / signature blobs the parsers already surface. Pure public-input SHA-256 / SHAKE256 hashing, a data-driven typecode registry, bounds-before-slice reads; a malformed blob throws a typed `ShbsError`, a well-formed-but-wrong signature returns `false`. **Verify only by design** — stateful signing needs atomic one-time-key state that belongs in an HSM — `verify`, `verifyLms` |

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/byte-writer.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @internal
+ * lib/byte-writer.js -- a growable big-endian byte sink: the ENCODING-layer twin of
+ * lib/byte-reader.js, the shared producer under the toolkit's non-ASN.1 length-prefixed
+ * wire formats (the TLS-vector SCT list pki.ct emits; any future TLS-presentation
+ * producer). Every fixed-width integer is range-checked against its field width and
+ * every length-prefixed vector against its declared bound BEFORE a byte is committed,
+ * so an out-of-range value or an over-long body faults through the caller's typed
+ * ErrorClass rather than silently truncating mod 2^(8*width). It carries the CALLER's
+ * ErrorClass exactly as ByteReader / the guard family do, so every wire format keeps
+ * its own `domain/reason` fault code.
+ *
+ * This is an engine primitive, not a format: a new fixed-width or length-prefixed wire
+ * field is a method here (with its own range check), never a hand-rolled Buffer write
+ * in a format module.
+ */
+
+// A growable big-endian sink, faulting through the caller's ErrorClass `E`
+// (constructed `new E(code, message)`). `defaultCode` is the fault code used when a
+// write is not given its own.
+function ByteWriter(E, defaultCode) {
+  this.parts = [];
+  this.len = 0;
+  this.E = E;
+  this.defaultCode = defaultCode || "byte-writer/bad-value";
+}
+ByteWriter.prototype._push = function (buf) { this.parts.push(buf); this.len += buf.length; };
+// A non-negative integer that fills exactly `width` big-endian octets; the width MUST be 1..4 (a wider
+// or malformed width would break the max computation via 32-bit shift wrap-around and mis-size the
+// field), and a value outside [0, 2^(8*width)-1] (or a non-integer) faults rather than silently wrapping.
+ByteWriter.prototype._uint = function (v, width, code) {
+  if (!Number.isInteger(width) || width < 1 || width > 4) throw new this.E(code || this.defaultCode, "an integer width must be 1..4, got " + width);
+  var max = width === 4 ? 0xffffffff : (1 << (8 * width)) - 1;
+  if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 0 || v > max) {
+    throw new this.E(code || this.defaultCode, "a uint" + (8 * width) + " must be an integer in 0.." + max + ", got " + v);
+  }
+  var b = Buffer.alloc(width); b.writeUIntBE(v, 0, width); this._push(b);
+};
+ByteWriter.prototype.u8 = function (v, code) { this._uint(v, 1, code); return this; };
+ByteWriter.prototype.u16 = function (v, code) { this._uint(v, 2, code); return this; };
+ByteWriter.prototype.u24 = function (v, code) { this._uint(v, 3, code); return this; };
+ByteWriter.prototype.u32 = function (v, code) { this._uint(v, 4, code); return this; };
+// A uint64 from a BigInt or a safe-integer Number; refused if out of [0, 2^64-1].
+ByteWriter.prototype.u64 = function (v, code) {
+  var big;
+  if (typeof v === "bigint") big = v;
+  else if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0) big = BigInt(v);
+  else throw new this.E(code || this.defaultCode, "a uint64 must be a non-negative integer or BigInt, got " + v);
+  if (big < 0n || big > 0xffffffffffffffffn) throw new this.E(code || this.defaultCode, "a uint64 must be in 0..2^64-1");
+  var b = Buffer.alloc(8); b.writeBigUInt64BE(big); this._push(b);
+  return this;
+};
+// Append a raw opaque slice verbatim (a fixed-width field).
+ByteWriter.prototype.bytes = function (buf, code) {
+  if (!Buffer.isBuffer(buf)) throw new this.E(code || this.defaultCode, "bytes() requires a Buffer");
+  this._push(buf); return this;
+};
+// opaque<min..max> -- a `lenWidth`-byte big-endian length prefix (1..4) then `body`.
+// The body length is bounded [min, max] BEFORE the prefix is written, so an over-long
+// body cannot emit a prefix that disagrees with what follows.
+ByteWriter.prototype.vector = function (lenWidth, min, max, body, code) {
+  if (!Buffer.isBuffer(body)) throw new this.E(code || this.defaultCode, "vector() body must be a Buffer");
+  if (body.length < min) throw new this.E(code || this.defaultCode, "vector body " + body.length + " below minimum " + min);
+  if (max != null && body.length > max) throw new this.E(code || this.defaultCode, "vector body " + body.length + " above maximum " + max);
+  this._uint(body.length, lenWidth, code);
+  this._push(body);
+  return this;
+};
+ByteWriter.prototype.length = function () { return this.len; };
+ByteWriter.prototype.build = function () { return Buffer.concat(this.parts, this.len); };
+
+module.exports = ByteWriter;

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/ct.js

@@ -38,11 +38,13 @@
  *   bounded TLS-struct decode, fail-closed.
  */
 
+var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der.js");
 var constants = require("./constants.js");
 var frameworkError = require("./framework-error.js");
 var guard = require("./guard-all.js");
 var ByteReader = require("./byte-reader.js");
+var ByteWriter = require("./byte-writer.js");
 var oid = require("./oid.js");
 var webcrypto = require("./webcrypto.js");
 var validator = require("./validator-all.js");
@@ -136,15 +138,15 @@ function _parseSct(r, sctLen) {
 
 /**
  * @primitive  pki.ct.parseSctList
- * @signature  pki.ct.parseSctList(extValue) -> { scts, unknownScts }
+ * @signature  pki.ct.parseSctList(extValue) -> { scts, unknownScts, all }
  * @since      0.1.20
  * @status     experimental
  * @spec       RFC 6962, RFC 5246, RFC 8446
- * @related    pki.ct.reconstructSignedData, pki.schema.x509.parse
+ * @related    pki.ct.reconstructSignedData, pki.ct.encodeSctList, pki.schema.x509.parse
  *
  * Parse the value of an RFC 6962 SCT-list extension (the raw `extnValue`
  * content an `x509.parse` / OCSP extension already surfaces) into
- * `{ scts, unknownScts }`. Each entry of `scts` is a fully decoded v1 SCT:
+ * `{ scts, unknownScts, all }`. Each entry of `scts` is a fully decoded v1 SCT:
  * `version` (0), `logId` (32-byte Buffer) + `logIdHex`, `timestamp` (BigInt,
  * exact) + `timestampMs` (Number or `null` above 2^53) + `timestampDate`,
  * `extensions` (raw Buffer), `hashAlg` / `sigAlg` (1-byte code points) + a named
@@ -152,7 +154,10 @@ function _parseSct(r, sctLen) {
  * SerializedSCT body). A SerializedSCT whose version this parser does not define
  * is preserved OPAQUE in `unknownScts` as `{ version, rawSct }` rather than
  * failing the list -- RFC 6962 sec. 3.3 frames each SerializedSCT with its own length
- * so unknown versions are skippable (forward compatibility).
+ * so unknown versions are skippable (forward compatibility). `all` lists every
+ * SerializedSCT (known and unknown) in the exact wire order, so
+ * `encodeSctList(all)` reproduces the list byte-identically even when the two
+ * kinds are interleaved.
  *
  * The extension value is a DER `OCTET STRING` wrapping the TLS-encoded list
  * (RFC 6962 sec. 3.3 double wrap); everything below that peel is TLS presentation
@@ -186,7 +191,7 @@ function parseSctList(extValue) {
   if (listLen < 1) {
     throw new CtError("ct/empty-list", "an SCT list must contain at least one SCT (RFC 6962 sec. 3.3)");
   }
-  var scts = [], unknownScts = [];
+  var scts = [], unknownScts = [], all = [];
   // The shared item counter bounds the TOTAL element count (known + preserved-
   // unknown) before it can drive unbounded per-element work (RFC 6962 sec. 3.3).
   var sctCount = guard.limits.counter(C.LIMITS.SCT_MAX_COUNT, _ctErr, "ct/too-many-scts", "SCT");
@@ -203,10 +208,12 @@ function parseSctList(extValue) {
     }
     sctCount.tick();
     var one = _parseSct(outer.subReader(sctLen, "ct/list-trailing-bytes"), sctLen);
-    if (one.unknown) unknownScts.push({ version: one.version, rawSct: one.rawSct });
-    else scts.push(one);
+    if (one.unknown) { var u = { version: one.version, rawSct: one.rawSct }; unknownScts.push(u); all.push(u); }
+    else { scts.push(one); all.push(one); }
   }
-  return { scts: scts, unknownScts: unknownScts };
+  // `all` preserves the exact wire order across known + unknown entries, so encodeSctList(all)
+  // reproduces the list byte-identically even when the two kinds were interleaved.
+  return { scts: scts, unknownScts: unknownScts, all: all };
 }
 
 function _u24Bytes(n) {
@@ -409,10 +416,188 @@ async function verifySct(entry, sct, logPublicKey) {
   }
 }
 
+// The TLS-vector WRITER bound to the ct/* fault domain -- the encode twin of TlsReader,
+// over the shared ByteWriter engine primitive (see lib/byte-writer.js).
+function TlsWriter() { return new ByteWriter(CtError, "ct/bad-input"); }
+
+// Encode one SerializedSCT body. A v1 SCT is rebuilt from its fields in the exact _parseSct
+// order (so it round-trips byte-identically); an opaque non-v1 entry re-emits its rawSct
+// verbatim (RFC 6962 sec. 3.3 forward-compat symmetry -- encode preserves what parse preserved).
+function _encodeSctBody(sct) {
+  if (!sct || typeof sct !== "object") throw new CtError("ct/bad-input", "each SCT must be an object");
+  if (sct.version !== 0) {
+    // The SerializedSCT version is a single byte (RFC 6962 sec. 3.2), so a declared version must be a
+    // 0..255 integer -- reject a non-byte value rather than masking it (a masked 263 would spoof v7).
+    if (typeof sct.version !== "number" || !Number.isInteger(sct.version) || sct.version < 0 || sct.version > 255) {
+      throw new CtError("ct/bad-input", "an SCT version must be a byte in 0..255 (RFC 6962 sec. 3.2)");
+    }
+    // An opaque entry re-emits its rawSct verbatim, but the SerializedSCT's on-wire version is
+    // rawSct[0] -- refuse a rawSct whose leading byte disagrees with the declared version, so encode
+    // never emits a list whose framing our own parser would reject or re-classify (RFC 6962 sec. 3.3).
+    var raw = _toBuffer(sct.rawSct, "sct.rawSct");
+    if (raw.length < 1 || raw[0] !== sct.version) {
+      throw new CtError("ct/bad-input", "an opaque SCT's rawSct[0] must equal its declared version (RFC 6962 sec. 3.3)");
+    }
+    return raw;
+  }
+  var w = new TlsWriter();
+  w.u8(0, "ct/bad-input");                                                            // Version -- v1(0)
+  var logId = _toBuffer(sct.logId, "sct.logId");
+  if (logId.length !== LOGID_BYTES) throw new CtError("ct/bad-input", "an SCT logId must be exactly " + LOGID_BYTES + " bytes (RFC 6962 sec. 3.2)");
+  w.bytes(logId);
+  w.u64(guard.range.uint64(sct.timestamp, _ctErr, "ct/bad-input", "sct.timestamp"), "ct/bad-input");   // uint64 timestamp
+  w.vector(2, 0, 0xffff, _toBuffer(sct.extensions, "sct.extensions"), "ct/bad-input");  // CtExtensions<0..2^16-1>
+  w.u8(sct.hashAlg, "ct/bad-input");                                                   // digitally-signed hash
+  w.u8(sct.sigAlg, "ct/bad-input");                                                    // digitally-signed signature
+  w.vector(2, 0, 0xffff, _toBuffer(sct.signature, "sct.signature"), "ct/bad-input");   // signature<0..2^16-1>
+  return w.build();
+}
+
+/**
+ * @primitive  pki.ct.encodeSctList
+ * @signature  pki.ct.encodeSctList(scts) -> Buffer
+ * @since      0.2.24
+ * @status     experimental
+ * @spec       RFC 6962, RFC 5246
+ * @related    pki.ct.parseSctList, pki.ct.signSct
+ *
+ * Build the value of an RFC 6962 SCT-list extension from an array of SCTs -- the exact
+ * inverse of `parseSctList`, such that `parseSctList(encodeSctList(list.all))` round-trips to
+ * identical bytes. Each element is either a decoded v1 SCT (the shape `parseSctList().scts[]`
+ * or `signSct` returns: `version` 0, 32-byte `logId`, `timestamp` BigInt, raw `extensions`,
+ * `hashAlg` / `sigAlg` code points, raw `signature`) -- rebuilt from its fields in the RFC
+ * 6962 sec. 3.2 field order -- or an opaque non-v1 entry (`{ version, rawSct }`) whose
+ * `rawSct` is re-emitted verbatim (forward compatibility, sec. 3.3). Pass `parseSctList().all`
+ * (not `.scts`) to preserve the exact wire order and every unknown-version entry.
+ *
+ * Returns the DER `OCTET STRING`-wrapped TLS `SignedCertificateTimestampList` (the same
+ * `extnValue` content `parseSctList` consumes). The list must be non-empty and stays within
+ * the parser's `SCT_MAX_COUNT` element cap and the RFC 6962 sec. 3.3 65535-byte list-body cap so
+ * encode cannot emit what parse would reject. Throws a typed `CtError` (`ct/empty-list`,
+ * `ct/bad-input`, `ct/too-large`, `ct/too-many-scts`) on malformed input.
+ *
+ * @example
+ *   var list = pki.ct.parseSctList(sctExtValue);
+ *   var reEncoded = pki.ct.encodeSctList(list.all);   // byte-identical to sctExtValue
+ */
+function encodeSctList(scts) {
+  if (!Array.isArray(scts)) throw new CtError("ct/bad-input", "encodeSctList expects an array of SCTs");
+  if (scts.length < 1) throw new CtError("ct/empty-list", "an SCT list must contain at least one SCT (RFC 6962 sec. 3.3)");
+  var sctCount = guard.limits.counter(C.LIMITS.SCT_MAX_COUNT, _ctErr, "ct/too-many-scts", "SCT");
+  var elements = [], total = 0;
+  for (var i = 0; i < scts.length; i++) {
+    sctCount.tick();
+    var ew = new TlsWriter();
+    ew.vector(2, 1, 0xffff, _encodeSctBody(scts[i]), "ct/bad-input");   // SerializedSCT<1..2^16-1>
+    var el = ew.build();
+    total += el.length;
+    // Enforce the sct_list<1..2^16-1> body cap INCREMENTALLY, so an over-long list fails at the first
+    // element that crosses the bound instead of accumulating the whole (potentially large) set first.
+    if (total > 0xffff) throw new CtError("ct/too-large", "the SCT list body exceeds the 65535-byte maximum (RFC 6962 sec. 3.3)");
+    elements.push(el);
+  }
+  var lw = new TlsWriter();
+  lw.vector(2, 1, 0xffff, Buffer.concat(elements, total), "ct/too-large");   // sct_list<1..2^16-1>
+  return asn1.build.octetString(lw.build());                                 // RFC 6962 sec. 3.3 DER OCTET STRING wrap
+}
+
+// A CT log private key -> its PKCS#8 DER (for WebCrypto sign) + the SPKI DER (for the LogID +
+// the sec. 2.1.4 algorithm profile). Accepts a PKCS#8 DER Buffer, a PEM string, a node
+// KeyObject, or a { key, format, type } input.
+function _logKeyMaterial(logKey) {
+  // Every key operation runs inside the guard: a duck-typed impostor (an object carrying an
+  // asymmetricKeyType but not a real KeyObject) fails at export/createPublicKey and surfaces the
+  // typed ct/bad-input, never a raw TypeError. The private-key check keeps its own CtError.
+  try {
+    var keyObj;
+    if (logKey && typeof logKey === "object" && logKey.asymmetricKeyType) keyObj = logKey;
+    else if (Buffer.isBuffer(logKey)) keyObj = nodeCrypto.createPrivateKey({ key: logKey, format: "der", type: "pkcs8" });
+    else keyObj = nodeCrypto.createPrivateKey(logKey);
+    if (keyObj.type !== "private") throw new CtError("ct/bad-input", "signSct requires the CT log PRIVATE key");
+    return { pkcs8: keyObj.export({ type: "pkcs8", format: "der" }), spki: nodeCrypto.createPublicKey(keyObj).export({ type: "spki", format: "der" }) };
+  } catch (e) {
+    if (e instanceof CtError) throw e;
+    throw new CtError("ct/bad-input", "the CT log private key could not be loaded", e);
+  }
+}
+
+/**
+ * @primitive  pki.ct.signSct
+ * @signature  pki.ct.signSct(entry, logKey, opts?) -> Promise<sct>
+ * @since      0.2.24
+ * @status     experimental
+ * @spec       RFC 6962
+ * @related    pki.ct.verifySct, pki.ct.reconstructSignedData, pki.ct.encodeSctList
+ *
+ * Perform a Certificate Transparency log's signing step (RFC 6962 sec. 3.2): rebuild the exact
+ * `digitally-signed` preimage over `entry` (via `reconstructSignedData`, the SAME builder the
+ * verifier hashes), sign it with the log's private key, and return a fully-formed v1 SCT that
+ * `verifySct` accepts against the log's public key. `entry` is the log entry the SCT covers
+ * (`{ entryType: 0, leafCert }` or `{ entryType: 1, tbsCertificate, issuerKeyHash }`, as for
+ * `reconstructSignedData`); `logKey` is the log's private key (PKCS#8 DER `Buffer`, PEM string,
+ * or a node `KeyObject`).
+ *
+ * The log-key profile is RFC 6962 sec. 2.1.4: ECDSA NIST P-256 (`sigAlg` 3) or RSA >= 2048
+ * (`sigAlg` 1), SHA-256 only -- an unsupported key fails closed `ct/unsupported-algorithm`. The
+ * `logId` is derived as SHA-256 of the log SPKI (sec. 3.4); a supplied `opts.logId` must match.
+ * The returned SCT is the parseSctList/verifySct shape and composes with `encodeSctList`.
+ *
+ * @opts timestamp   ms since the epoch (finite non-negative integer/BigInt). Default `Date.now()`.
+ * @opts extensions  raw `CtExtensions` bytes (opaque<0..2^16-1>). Default empty.
+ * @opts logId       assert the derived LogID equals this 32-byte value (fail closed on mismatch).
+ * @example
+ *   var sct = await pki.ct.signSct({ entryType: 0, leafCert: der }, signerKeyPkcs8);
+ *   var ext = pki.ct.encodeSctList([sct]);
+ */
+async function signSct(entry, logKey, opts) {
+  opts = opts || {};
+  var mat = _logKeyMaterial(logKey);
+  var alg = _spkiAlg(mat.spki);
+  var hashAlg = 4, sigAlg, imp, sign, ecdsaDer = false, coordLen;
+  if (alg.algOid === oid.byName("ecPublicKey")) {
+    var ec = CT_EC_CURVE[alg.curveOid];
+    if (!ec) throw new CtError("ct/unsupported-algorithm", "unsupported SCT log EC curve (RFC 6962 sec. 2.1.4 mandates NIST P-256)");
+    sigAlg = 3; imp = { name: "ECDSA", namedCurve: ec.curve }; sign = { name: "ECDSA", hash: "SHA-256" }; ecdsaDer = true; coordLen = ec.coordLen;
+  } else if (alg.algOid === oid.byName("rsaEncryption")) {
+    if (!(alg.rsaBits >= 2048)) throw new CtError("ct/unsupported-algorithm", "the SCT log RSA key is below the RFC 6962 sec. 2.1.4 minimum of 2048 bits");
+    sigAlg = 1; imp = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }; sign = { name: "RSASSA-PKCS1-v1_5" };
+  } else {
+    throw new CtError("ct/unsupported-algorithm", "unsupported SCT log key algorithm (RFC 6962 sec. 2.1.4 supports ecdsa P-256 / rsa)");
+  }
+  var timestamp;
+  if (opts.timestamp == null) timestamp = BigInt(Date.now());
+  else if (typeof opts.timestamp === "bigint") timestamp = opts.timestamp;
+  else if (typeof opts.timestamp === "number" && Number.isSafeInteger(opts.timestamp) && opts.timestamp >= 0) timestamp = BigInt(opts.timestamp);
+  else throw new CtError("ct/bad-input", "timestamp must be a finite non-negative integer or BigInt (RFC 6962 sec. 3.2)");
+  var extensions = opts.extensions == null ? Buffer.alloc(0) : _toBuffer(opts.extensions, "opts.extensions");
+  var logId = Buffer.from(await subtle.digest("SHA-256", mat.spki));
+  if (opts.logId != null && !_toBuffer(opts.logId, "opts.logId").equals(logId)) {
+    throw new CtError("ct/bad-input", "opts.logId does not match SHA-256 of the log key (RFC 6962 sec. 3.4)");
+  }
+  // Reuse the ONE preimage builder the verifier uses -- sign and verify cannot diverge.
+  var preimage = reconstructSignedData(entry, { version: 0, timestamp: timestamp, extensions: extensions });
+  var priv = await subtle.importKey("pkcs8", mat.pkcs8, imp, false, ["sign"]);
+  var sigRaw = Buffer.from(await subtle.sign(sign, priv, preimage));
+  var signature = ecdsaDer ? validator.sig.rawToEcdsaDer(sigRaw, coordLen) : sigRaw;
+  return {
+    version: 0,
+    logId: logId, logIdHex: logId.toString("hex"),
+    timestamp: timestamp,
+    extensions: extensions,
+    hashAlg: hashAlg, sigAlg: sigAlg,
+    // The `|| null` fallbacks mirror parseSctList's shape; unreachable here since signSct only ever
+    // emits the in-map sha256(4) + ecdsa(3)/rsa(1) code points (coverage residual).
+    signatureAlgorithm: { hash: hashAlg, hashName: HASH_ALGORITHMS[hashAlg] || null, signature: sigAlg, signatureName: SIGNATURE_ALGORITHMS[sigAlg] || null },
+    signature: signature,
+  };
+}
+
 module.exports = {
   parseSctList: parseSctList,
   reconstructSignedData: reconstructSignedData,
   verifySct: verifySct,
+  encodeSctList: encodeSctList,
+  signSct: signSct,
   HASH_ALGORITHMS: HASH_ALGORITHMS,
   SIGNATURE_ALGORITHMS: SIGNATURE_ALGORITHMS,
 };

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.23",
+  "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:218fb396-9c81-482d-be9e-f08c7add5683",
+  "serialNumber": "urn:uuid:40b168db-ab8a-4925-b224-648cd2ed3f10",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-16T08:33:14.109Z",
+    "timestamp": "2026-07-16T11:50:45.040Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.23",
+      "bom-ref": "@blamejs/pki@0.2.25",
       "type": "application",
       "name": "pki",
-      "version": "0.2.23",
+      "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.23",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.25",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.23",
+      "ref": "@blamejs/pki@0.2.25",
       "dependsOn": []
     }
   ]