@blamejs/pki 0.2.14 → 0.2.15

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.15 — 2026-07-13
+
+CMS SignedData signing arrives as pki.cms.sign, and RFC 3161 timestamp token creation as pki.tsp.sign -- the producing sides of the CMS and timestamp verifiers, emitting exactly what pki.cms.verify and OpenSSL cms -verify accept.
+
+### Added
+
+- pki.cms.sign(content, signers, opts) produces a CMS SignedData (RFC 5652 section 5): attached or detached content, one or many signers, RSA (PKCS#1 v1.5 and, with opts.pss, RSASSA-PSS), ECDSA (P-256/384/521), Ed25519, and Ed448. Each signer is { cert, key } (a PEM/DER certificate and a WebCrypto CryptoKey or PKCS#8 key); the signed attributes (content-type, message-digest, signing-time, plus opts.additionalSignedAttributes) are canonical DER and the signature covers the exact section 5.4 preimage. opts selects detached content, the encapsulated content type, the signer identifier (issuerAndSerialNumber or subjectKeyIdentifier), certificate embedding, and DER or PEM output.
+- pki.tsp.sign(messageImprint, tsa, opts) creates an RFC 3161 TimeStampToken over a message imprint ({ hashAlgorithm, hashedMessage }): a CMS SignedData whose content is a TSTInfo carrying the imprint, the TSA policy, a serial number, and genTime, with optional accuracy, nonce, and ordering, and the RFC 3161 section 2.4.2 / RFC 5816 signing-certificate (ESSCertIDv2) attribute binding the token to the TSA certificate. It composes pki.cms.sign, so any supported TSA key algorithm works.
+
 ## v0.2.14 — 2026-07-13
 
 CMS SignedData signature verification arrives as pki.cms.verify -- verifying a signed message (S/MIME, timestamps, code signing) over the exact RFC 5652 preimage, for attached and detached content, one or many signers, across RSA, RSASSA-PSS, ECDSA, and EdDSA.

package/README.md

@@ -221,7 +221,8 @@ is callable today; nothing below is a stub.
 | `pki.schema.smime` | Decode S/MIME ESS signed-attribute values (RFC 5035 / RFC 8551) — `parseSigningCertificate` / `parseSigningCertificateV2` bind a signature to its signing certificate (cert hash, hash algorithm, issuer `GeneralNames` + serial), `parseSmimeCapabilities` decodes the ordered capability list, and `decodeAttribute` OID-dispatches a CMS attribute (enforcing the single-value rule, recognize-and-defer for unknown types). A companion decoder for CMS signed attributes, not an auto-routed format, fail-closed — `parseSigningCertificate`, `parseSigningCertificateV2`, `parseSmimeCapabilities`, `decodeAttribute` |
 | `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 signature verification — `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. Attached and detached content, single and multiple signers, RSA / RSASSA-PSS / ECDSA / EdDSA. 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`. Fail-closed with typed `cms/*` errors — `verify` |
+| `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); 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`. Fail-closed with typed `cms/*` errors — `sign`, `verify` |
+| `pki.tsp` | RFC 3161 timestamp token creation — `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. The producing side of `pki.schema.tsp.parseToken`; SHA-2 imprints, and any `pki.cms.sign` TSA key — `sign` |
 | `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.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` |
@@ -233,12 +234,12 @@ is callable today; nothing below is a stub.
 | `pki.lint` | Certificate linting — the zlint / pkilint of JavaScript. `certificate(pem \| der \| parsed, opts)` walks a parsed certificate and emits graded, advisory findings — each with a stable id, a severity (`fatal` > `error` > `warn` > `notice`), a source, a spec-clause citation, and a message — against the RFC 5280 profile plus a representative CA/Browser Forum TLS BR subset (serial sign/size, validity ordering + the the SC081v3 reducing validity schedule, keyCertSign coherence, unknown critical extensions, empty-subject SAN, SKI/AKI presence, SAN required + CN-in-SAN, dNSName syntax, serverAuth EKU, weak keys). Unlike every other entry the DATA path never throws: hostile bytes return a `fatal` `lint/unparseable` finding (with the strict parser's code) so a whole directory lints without a try/catch; only config-time misuse throws a typed `LintError`. `certificate`, `rules`, `profiles` |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
 | `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError` / `WebauthnError` / `LintError`, each carrying a stable `code` in `domain/reason` form |
-| `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>`, `pki inspect <cert>`, `pki lint <cert>`, `pki convert <file> --to der\|pem`, `pki verify <cert>... --anchor <cert>` |
+| `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>`, `pki inspect <cert>`, `pki lint <cert>`, `pki convert <file> --to der\|pem`, `pki verify <cert>... --anchor <cert>`, `pki sign <file> --cert <c> --key <k>` |
 
 ### CLI
 
 ```sh
-pki version                              # @blamejs/pki v0.1.0
+pki version                              # the installed @blamejs/pki version
 pki oid 1.2.840.113549.1.1.11           # sha256WithRSAEncryption
 pki oid sha256                           # 2.16.840.1.101.3.4.2.1
 pki parse cert.pem                       # structured JSON summary of a certificate
@@ -247,12 +248,15 @@ pki lint cert.pem                        # graded conformance findings; exit 1 o
 pki lint cert.pem --json --profile cabf-tls
 pki convert cert.pem --to der > cert.der # transcode between PEM and DER (round-trips)
 pki verify leaf.pem --anchor root.pem --time 2026-01-01T00:00:00Z   # RFC 5280 path validation
+pki sign msg.txt --cert signer.pem --key signer-key.pem --out msg.p7s   # CMS SignedData (pki.cms.sign)
+pki sign msg.txt --cert signer.pem --key signer-key.pem --detached --pem # detached, PEM to stdout
 ```
 
-`inspect`/`lint`/`convert`/`verify` are thin front-ends over `pki.inspect`, `pki.lint`, the
-per-format PEM codecs, and `pki.path.validate` — the CLI never does anything the library
-API can't. `lint` exits non-zero when any `error`/`fatal` finding is present; `verify` exits
-non-zero when the path does not validate.
+`inspect`/`lint`/`convert`/`verify`/`sign` are thin front-ends over `pki.inspect`, `pki.lint`, the
+per-format PEM codecs, `pki.path.validate`, and `pki.cms.sign` — the CLI never does anything the
+library API can't. `lint` exits non-zero when any `error`/`fatal` finding is present; `verify`
+exits non-zero when the path does not validate; `sign` reads a PKCS#8 DER/PEM private key and its
+certificate and writes a DER (or `--pem`) SignedData to `--out` or stdout.
 
 ### What's coming
 
@@ -338,7 +342,8 @@ path validation), `pki.trust` (trust anchors), `pki.ct` (Certificate Transparenc
 SCTs), `pki.hpke` (RFC 9180), `pki.shbs` (HSS/LMS stateful hash signatures),
 `pki.merkle` (RFC 9162 transparency proofs), `pki.sigstore` (offline npm-provenance
 verification), `pki.webauthn` (WebAuthn / passkey attestation verification),
-`pki.cms` (RFC 5652 SignedData signature verification), and the
+`pki.cms` (RFC 5652 SignedData signing + signature verification), `pki.tsp` (RFC 3161
+timestamp token creation), and the
 `jose` / `acme` / `est` enrollment surfaces. Each composes
 the shared structure, foundation, and crypto layers directly. Alongside the schema
 engine, the fail-closed **guard family** (`guard-*`) centralizes each CVE-class

package/bin/pki.js

@@ -15,11 +15,13 @@
  *              [--label LABEL]
  *   pki verify <cert>... --anchor <cert>  validate an ordered certification path (anchor->target)
  *              [--time ISO]
+ *   pki sign <file> --cert <c> --key <k>  produce a CMS SignedData over the file (pki.cms.sign)
+ *              [--detached] [--pss] [--digest D] [--pem] [--out F]
  *
  * The CLI is a thin operator convenience over the library surface: it validates its
  * arguments (entry-point tier — bad input exits non-zero with a message) and never does
- * anything the public API cannot. inspect / lint / convert / verify compose pki.inspect,
- * pki.lint, the per-format PEM codecs, and pki.path.validate respectively.
+ * anything the public API cannot. inspect / lint / convert / verify / sign compose pki.inspect,
+ * pki.lint, the per-format PEM codecs, pki.path.validate, and pki.cms.sign respectively.
  */
 
 var fs  = require("node:fs");
@@ -34,7 +36,7 @@ function fail(msg) {
 // rest are positionals in `_`. A value-taking flag whose value is absent or is itself another
 // flag is a usage error (never silently coerced to `true`, which would make e.g. `--time`
 // parse as `new Date(true)` = a real 1970 timestamp). No clustering, no `=value`.
-var VALUE_FLAGS = { to: 1, profile: 1, severity: 1, label: 1, anchor: 1, time: 1 };
+var VALUE_FLAGS = { to: 1, profile: 1, severity: 1, label: 1, anchor: 1, time: 1, cert: 1, key: 1, digest: 1, out: 1 };
 function parseArgs(argv) {
   var out = { _: [] };
   for (var i = 0; i < argv.length; i++) {
@@ -200,7 +202,28 @@ function cmdVerify(args) {
   }, function (e) { return fail(e.code + ": " + e.message); });
 }
 
-var USAGE = "usage: pki <version|oid|parse|inspect|lint|convert|verify> [args]\n";
+// pki sign <content-file> --cert <cert> --key <key> -- produce a CMS SignedData over the file
+// via pki.cms.sign. The signer key is a PKCS#8 DER or PEM private key; the certificate is DER or
+// PEM. Output is a DER Buffer (or a PEM block with --pem) to --out or stdout.
+function cmdSign(args) {
+  var contentFile = args._[0];
+  if (!contentFile || !args.cert || !args.key) {
+    return fail("usage: pki sign <content-file> --cert <cert> --key <key.pkcs8> [--detached] [--pss] [--digest sha256|sha384|sha512] [--pem] [--out <file>]");
+  }
+  var content = readFileBytes(contentFile);
+  var signer = { cert: _asPemOrDer(readFileBytes(args.cert)), key: _asPemOrDer(readFileBytes(args.key)) };
+  if (args.pss) signer.pss = true;
+  if (args.digest) signer.digestAlgorithm = args.digest;
+  return pki.cms.sign(content, signer, { detached: !!args.detached, pem: !!args.pem }).then(function (out) {
+    if (args.out) { try { fs.writeFileSync(args.out, out); } catch (e) { return fail("cannot write " + args.out + ": " + e.message); } }
+    else { process.stdout.write(out); }   // process.exitCode (0) lets Node flush a piped stdout
+  }, function (e) { return fail((e.code || "cms/sign-error") + ": " + e.message); });
+}
+// A PEM file (its first byte is '-') is passed to pki.cms.sign as a string; a DER file as its
+// Buffer. cms.sign accepts either for the certificate and needs a string for a PEM private key.
+function _asPemOrDer(buf) { return buf[0] === 0x2d ? buf.toString("latin1") : buf; }
+
+var USAGE = "usage: pki <version|oid|parse|inspect|lint|convert|verify|sign> [args]\n";
 
 function main(argv) {
   var cmd = argv[0];
@@ -212,6 +235,7 @@ function main(argv) {
     case "lint":    return cmdLint(parseArgs(argv.slice(1)));
     case "convert": return cmdConvert(parseArgs(argv.slice(1)));
     case "verify":  return cmdVerify(parseArgs(argv.slice(1)));
+    case "sign":    return cmdSign(parseArgs(argv.slice(1)));
     case undefined: case "help": case "--help": case "-h":
       process.stdout.write(USAGE);
       return;

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 tsp       = require("./lib/tsp-sign");
 var merkle    = require("./lib/merkle");
 var shbs      = require("./lib/shbs");
 var hpke      = require("./lib/hpke");
@@ -75,6 +76,7 @@ module.exports = {
   // surfaced raw for external verification (pki.ct.reconstructSignedData).
   ct:        ct,
   cms:       cms,
+  tsp:       tsp,
   // `merkle` is the RFC 6962 / RFC 9162 Merkle-tree proof-verification core --
   // pki.merkle.leafHash / nodeHash / emptyRootHash build the domain-separated
   // (0x00 leaf / 0x01 node) SHA-256 tree hashes; pki.merkle.verifyInclusion and

package/lib/cms-sign.js

@@ -0,0 +1,324 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+//
+// @internal -- the pki.cms.sign implementation. So the pki.cms namespace has ONE @module home,
+// the operator-facing @module pki.cms + the @primitive pki.cms.sign documentation block live in
+// cms-verify.js, which re-exports this sign function.
+//
+// CMS SignedData signing (RFC 5652 sec. 5), the producing side of pki.cms.verify: composes the
+// strict asn1 build layer (canonical DER, and build.set SET-OF-sorts the signed attributes for
+// free), the WebCrypto sign surface over node:crypto, and the shared validator.sig.rawToEcdsaDer
+// DER-ECDSA home -- emitting exactly the shapes cms.verify checks (NULL params for RSA, absent
+// for ECDSA/EdDSA, the RSASSA-PSS params SEQUENCE), with the sign->verify round-trip (and OpenSSL
+// cms -verify) as the guard.
+
+var nodeCrypto = require("crypto");
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var x509 = require("./schema-x509");
+var pkcs8 = require("./schema-pkcs8");
+var pkix = require("./schema-pkix");
+var webcrypto = require("./webcrypto");
+var subtle = webcrypto.webcrypto.subtle;
+var validator = require("./validator-all");
+var frameworkError = require("./framework-error");
+
+var CmsError = frameworkError.CmsError;
+var b = asn1.build;
+function _err(code, message, cause) { return new CmsError(code, message, cause); }
+function O(name) { return oid.byName(name); }
+
+// A digest-algorithm name -> the WebCrypto hash (sign path). SHAKE256 has no WebCrypto hash, so
+// the message digest is always computed with node:crypto (below), uniform across the family.
+var HASH = { sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
+var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512", shake256: "shake256" };
+var SHAKE_OUT = { shake256: 64 };   // RFC 8419 sec. 2.3 -- Ed448 uses SHAKE256 with 512-bit output
+var PSS_SALT = { "SHA-256": 32, "SHA-384": 48, "SHA-512": 64 };
+var ECDSA_ALG = { sha256: "ecdsaWithSHA256", sha384: "ecdsaWithSHA384", sha512: "ecdsaWithSHA512" };
+var HASH_NAME_BY_OID = {};
+HASH_NAME_BY_OID[O("sha256")] = "sha256";
+HASH_NAME_BY_OID[O("sha384")] = "sha384";
+HASH_NAME_BY_OID[O("sha512")] = "sha512";
+var EC_BY_CURVE_OID = {};
+EC_BY_CURVE_OID[O("prime256v1")] = { curve: "P-256", coordLen: 32 };
+EC_BY_CURVE_OID[O("secp384r1")] = { curve: "P-384", coordLen: 48 };
+EC_BY_CURVE_OID[O("secp521r1")] = { curve: "P-521", coordLen: 66 };
+
+var OID_DATA = O("data");
+var OID_SIGNED_DATA = O("signedData");
+var OID_SKI = O("subjectKeyIdentifier");
+
+// An AlgorithmIdentifier { OID } (absent parameters) or { OID, NULL }.
+function _algId(name, shape) { return shape === "null" ? b.sequence([b.oid(O(name)), b.nullValue()]) : b.sequence([b.oid(O(name))]); }
+// The RSASSA-PSS AlgorithmIdentifier with the params SEQUENCE cms.verify's _resolvePss accepts:
+// an explicit SHA-2 hashAlgorithm, MGF1 keyed to the same hash, the hash-length saltLength, and
+// the default trailerField (omitted). RFC 4055.
+function _pssAlgId(digestName) {
+  var hashAlg = b.sequence([b.oid(O(digestName)), b.nullValue()]);
+  var mgf = b.sequence([b.oid(O("mgf1")), hashAlg]);
+  var params = b.sequence([b.explicit(0, hashAlg), b.explicit(1, mgf), b.explicit(2, b.integer(BigInt(PSS_SALT[HASH[digestName]])))]);
+  return b.sequence([b.oid(O("rsassaPss")), params]);
+}
+
+// An id-RSASSA-PSS SubjectPublicKeyInfo MAY pin the permitted hash in its RSASSA-PSS-params
+// (RFC 4055 sec. 1.2 / sec. 3.1): a key generated for SHA-384 cannot sign under SHA-256. Read the
+// pinned digest name from the SPKI algorithm parameters so signing honors the key's restriction
+// instead of hard-coding SHA-256. Absent params (an unrestricted key) or an unrecognized hash
+// returns null -- the caller then falls back to its opts.digestAlgorithm or the SHA-256 default.
+function _pssHashFromSpki(cert) {
+  var params = cert.subjectPublicKeyInfo.algorithm.parameters;
+  if (params == null) return null;                              // an unrestricted id-RSASSA-PSS key
+  // params is the raw parameters TLV the strict codec already validated when it parsed the cert,
+  // so re-decoding a single valid TLV cannot throw. Read the pinned hash structurally, defaulting
+  // to null (caller falls back) whenever the shape is not the expected RSASSA-PSS-params.
+  var node = asn1.decode(params);
+  if (node.tagClass !== "universal" || node.tagNumber !== asn1.TAGS.SEQUENCE || !node.children) return null;
+  var hashField = node.children.filter(function (c) { return c.tagClass === "context" && c.tagNumber === 0; })[0];
+  if (!hashField || !hashField.children || !hashField.children[0] || !hashField.children[0].children) return null;
+  var oidNode = hashField.children[0].children[0];             // [0] EXPLICIT AlgorithmIdentifier { hash OID, ... }
+  if (!oidNode || oidNode.tagClass !== "universal" || oidNode.tagNumber !== asn1.TAGS.OBJECT_IDENTIFIER) return null;
+  var pinnedOid = asn1.read.oid(oidNode);
+  var name = HASH_NAME_BY_OID[pinnedOid];
+  // A recognized SHA-2 pin resolves to its name; an unsupported pinned hash (e.g. SHA-3) fails
+  // closed -- we cannot honor the key's restriction, so we never silently sign under a different
+  // digest the key forbids.
+  if (!name) throw _err("cms/unsupported-algorithm", "the id-RSASSA-PSS signer key pins an unsupported hash algorithm (" + pinnedOid + ")");
+  return name;
+}
+
+// The message digest of the content under the digest algorithm (SHA-2 or SHAKE256).
+function _digest(digestName, content) {
+  var h = SHAKE_OUT[digestName]
+    ? nodeCrypto.createHash(NODE_DIGEST[digestName], { outputLength: SHAKE_OUT[digestName] })
+    : nodeCrypto.createHash(NODE_DIGEST[digestName]);
+  return h.update(content).digest();
+}
+
+// Resolve the sign scheme from the signer certificate's public-key algorithm + per-signer opts:
+// the digest, the digestAlgorithm and signatureAlgorithm AlgorithmIdentifiers (with the exact
+// parameter shape cms.verify requires), and the WebCrypto import + sign algorithms.
+function _scheme(cert, so) {
+  var alg = cert.subjectPublicKeyInfo.algorithm;
+  var keyOid = alg.oid;
+  if (keyOid === O("rsaEncryption") || keyOid === O("rsassaPss")) {
+    var isPssKey = keyOid === O("rsassaPss");
+    // An id-RSASSA-PSS key MAY pin its permitted hash in the SPKI params (RFC 4055 sec. 1.2): honor
+    // that over the SHA-256 default so Node/OpenSSL does not reject the otherwise-valid signer with
+    // ERR_OSSL_DIGEST_NOT_ALLOWED. An explicit digestAlgorithm that contradicts the pin is rejected
+    // fail-closed rather than silently signed under a digest the key forbids.
+    var pinned = isPssKey ? _pssHashFromSpki(cert) : null;
+    if (pinned && so.digestAlgorithm && so.digestAlgorithm !== pinned) throw _err("cms/bad-input", "the signer key restricts the RSASSA-PSS digest to " + pinned + ", but digestAlgorithm " + JSON.stringify(so.digestAlgorithm) + " was requested");
+    var d = so.digestAlgorithm || pinned || "sha256";
+    if (!HASH[d]) throw _err("cms/unsupported-algorithm", "unsupported RSA digest algorithm " + JSON.stringify(d));
+    // A general rsaEncryption key signs PKCS#1 v1.5 by default, or RSASSA-PSS when opts.pss is set.
+    if (so.pss || isPssKey) return { digest: d, digestAlgId: _algId(d, "absent"), sigAlgId: _pssAlgId(d), imp: { name: "RSA-PSS", hash: HASH[d] }, sign: { name: "RSA-PSS", saltLength: PSS_SALT[HASH[d]] }, ecdsaDer: false };
+    return { digest: d, digestAlgId: _algId(d, "absent"), sigAlgId: _algId("rsaEncryption", "null"), imp: { name: "RSASSA-PKCS1-v1_5", hash: HASH[d] }, sign: { name: "RSASSA-PKCS1-v1_5" }, ecdsaDer: false };
+  }
+  if (keyOid === O("ecPublicKey")) {
+    var curveOid;
+    try { curveOid = asn1.read.oid(asn1.decode(alg.parameters)); }
+    catch (e) { throw _err("cms/unsupported-algorithm", "the signer EC key parameters are not a named-curve OID", e); }
+    var ec = EC_BY_CURVE_OID[curveOid];
+    if (!ec) throw _err("cms/unsupported-algorithm", "the signer key is on an unsupported EC curve");
+    var de = so.digestAlgorithm || "sha256";
+    if (!HASH[de]) throw _err("cms/unsupported-algorithm", "unsupported ECDSA digest algorithm " + JSON.stringify(de));
+    return { digest: de, digestAlgId: _algId(de, "absent"), sigAlgId: _algId(ECDSA_ALG[de], "absent"), imp: { name: "ECDSA", namedCurve: ec.curve }, sign: { name: "ECDSA", hash: HASH[de] }, ecdsaDer: true, coordLen: ec.coordLen };
+  }
+  if (keyOid === O("Ed25519") || keyOid === O("Ed448")) {
+    var name = keyOid === O("Ed25519") ? "Ed25519" : "Ed448";
+    var dd = so.digestAlgorithm || (name === "Ed25519" ? "sha512" : "shake256");
+    if (!NODE_DIGEST[dd]) throw _err("cms/unsupported-algorithm", "unsupported " + name + " digest algorithm " + JSON.stringify(dd));
+    return { digest: dd, digestAlgId: _algId(dd, "absent"), sigAlgId: _algId(name, "absent"), imp: { name: name }, sign: { name: name }, ecdsaDer: false };
+  }
+  throw _err("cms/unsupported-algorithm", "unsupported signer key algorithm " + keyOid);
+}
+
+// The raw issuer Name TLV from a parsed certificate (byte-identical to the cert, so the sid the
+// verifier canonically compares matches exactly). The issuer is the Name after the optional
+// version [0] and the serial + signature AlgorithmIdentifier in the tbsCertificate.
+function _issuerBytes(cert) {
+  var tbs = asn1.decode(cert.tbsBytes);
+  var hasVersion = tbs.children[0].tagClass === "context" && tbs.children[0].tagNumber === 0;
+  return tbs.children[hasVersion ? 3 : 2].bytes;
+}
+// The cert's subjectKeyIdentifier extension value (the raw key id), or throws.
+function _skiValue(cert) {
+  var ext = (cert.extensions || []).filter(function (e) { return e.oid === OID_SKI; })[0];
+  if (!ext) throw _err("cms/no-ski", "a subjectKeyIdentifier signer identifier requires the signer certificate to carry an SKI extension");
+  try { return asn1.read.octetString(asn1.decode(ext.value)); }
+  catch (e) { throw _err("cms/no-ski", "the signer certificate's subjectKeyIdentifier extension value is not an OCTET STRING", e); }
+}
+
+// A caller-supplied CryptoKey carries its OWN algorithm (name, and for RSA the baked-in hash,
+// for ECDSA the curve). A PKCS#8 key is imported under the resolved scheme, so it always agrees;
+// but a pre-imported CryptoKey whose algorithm disagrees with the certificate's scheme would
+// silently sign under a different hash than the digestAlgorithm advertises -- an inconsistent,
+// non-verifiable CMS. Reject the mismatch fail-closed.
+function _assertKeyMatchesScheme(key, imp) {
+  var ka = key.algorithm || {};
+  if (ka.name !== imp.name) throw _err("cms/bad-input", "the signer CryptoKey algorithm (" + ka.name + ") does not match the certificate's key algorithm (" + imp.name + ")");
+  if (imp.hash && (!ka.hash || ka.hash.name !== imp.hash)) throw _err("cms/bad-input", "the signer CryptoKey hash (" + (ka.hash && ka.hash.name) + ") does not match the signing digest (" + imp.hash + ")");
+  if (imp.namedCurve && ka.namedCurve !== imp.namedCurve) throw _err("cms/bad-input", "the signer CryptoKey curve (" + ka.namedCurve + ") does not match the certificate curve (" + imp.namedCurve + ")");
+}
+// Import the signer private key: a CryptoKey passed through, or a PKCS#8 DER Buffer / PEM string.
+function _importKey(key, imp) {
+  if (key && typeof key === "object" && !Buffer.isBuffer(key) && !(key instanceof Uint8Array) && key.type === "private") {
+    _assertKeyMatchesScheme(key, imp);
+    return Promise.resolve(key);
+  }
+  var der;
+  if (Buffer.isBuffer(key)) der = key;
+  else if (key instanceof Uint8Array) der = Buffer.from(key);
+  else if (typeof key === "string") { try { der = pkcs8.pemDecode(key); } catch (e) { throw _err("cms/bad-input", "the signer PEM private key could not be decoded", e); } }
+  else throw _err("cms/bad-input", "a signer key must be a CryptoKey, a PKCS#8 DER Buffer, or a PKCS#8 PEM string");
+  return subtle.importKey("pkcs8", der, imp, false, ["sign"]);
+}
+
+// Build one SignerInfo (RFC 5652 sec. 5.3) and sign it. Resolves the SignerInfo (as a build
+// node) plus its digestAlgorithm AlgorithmIdentifier and the signer certificate DER (for the
+// SignedData digestAlgorithms + certificates sets).
+function _buildSignerInfo(signer, content, eContentType, opts) {
+  var so = signer || {};
+  var certDer = _normCertDer(so.cert);
+  var cert = x509.parse(certDer);
+  var scheme = _scheme(cert, so);
+  var useSki = opts.sid === "ski";
+  var sid = useSki
+    ? b.contextPrimitive(0, _skiValue(cert))                                       // [0] IMPLICIT SubjectKeyIdentifier
+    : b.sequence([b.raw(_issuerBytes(cert)), b.integer(cert.serialNumber)]);        // IssuerAndSerialNumber
+  var version = useSki ? 3 : 1;
+
+  return _importKey(so.key, scheme.imp).then(function (priv) {
+    return Promise.resolve().then(function () {
+      if (opts.signedAttributes === false) return content;   // sign the content directly (no signed attributes)
+      // Signed attributes (RFC 5652 sec. 5.3): content-type == eContentType, message-digest ==
+      // digest(content), and (by default) signing-time. build.set canonical-DER SET-OF-sorts them.
+      // Each attribute type appears AT MOST ONCE across the whole set (RFC 5652 sec. 5.3);
+      // `seenTypes` catches a caller-supplied attribute that duplicates a built-in or another.
+      var seenTypes = {};
+      function _pushAttr(typeOid, values) {
+        if (seenTypes[typeOid]) throw _err("cms/bad-input", "signedAttrs must not repeat an attribute type (RFC 5652 sec. 5.3): " + typeOid);
+        seenTypes[typeOid] = 1;
+        attrs.push(b.sequence([b.oid(typeOid), b.set(values)]));
+      }
+      var attrs = [];
+      _pushAttr(O("contentType"), [b.oid(eContentType)]);
+      _pushAttr(O("messageDigest"), [b.octetString(_digest(scheme.digest, content))]);
+      if (opts.signingTime !== false) _pushAttr(O("signingTime"), [_timeValue(opts.signingTime)]);
+      // Caller-supplied signed attributes (e.g. an RFC 3161 signing-certificate attribute): each
+      // { type: <OID name or dotted string>, values: [<DER value Buffer>] }. build.set sorts them in.
+      (opts.additionalSignedAttributes || []).forEach(function (a) {
+        var vals = (a.values || []).map(function (v) { return _toBuf(v, "a signed attribute value"); });
+        if (!vals.length) throw _err("cms/bad-input", "a signed attribute must carry at least one value (RFC 5652 -- Attribute values is SET SIZE (1..MAX))");
+        _pushAttr(/^\d+(\.\d+)+$/.test(a.type) ? a.type : O(a.type), vals);
+      });
+      var setOf = b.set(attrs);   // SET OF (tag 0x31) -- the exact bytes the signature covers (sec. 5.4)
+      var wire = Buffer.from(setOf); wire[0] = 0xA0;   // the on-wire [0] IMPLICIT tag
+      return { setOf: setOf, wire: wire };
+    }).then(function (toSign) {
+      var signedBytes = toSign.setOf ? toSign.setOf : toSign;   // SET-OF form for signing (sec. 5.4)
+      return subtle.sign(scheme.sign, priv, signedBytes).then(function (sigRaw) {
+        var sig = Buffer.from(sigRaw);
+        if (scheme.ecdsaDer) sig = validator.sig.rawToEcdsaDer(sig, scheme.coordLen);
+        var fields = [b.integer(BigInt(version)), sid, scheme.digestAlgId];
+        if (toSign.wire) fields.push(toSign.wire);              // [0] IMPLICIT signedAttrs
+        fields.push(scheme.sigAlgId, b.octetString(sig));
+        return { si: b.sequence(fields), digestAlgId: scheme.digestAlgId, version: version, certDer: certDer };
+      });
+    });
+  });
+}
+
+// A signing-time Time value: UTCTime before 2050, GeneralizedTime from 2050 (RFC 5652 sec. 11.3 /
+// RFC 5280 sec. 4.1.2.5). A caller Date overrides; false omits the attribute (handled above).
+function _timeValue(when) {
+  var d = (when instanceof Date) ? when : new Date();
+  return d.getUTCFullYear() < 2050 ? b.utcTime(d) : b.generalizedTime(d);
+}
+
+// Normalize a signer certificate input to its raw DER (DER Buffer / PEM string / Uint8Array).
+// The same bytes drive scheme resolution and the certificates [0] embedding, so a parsed
+// certificate (which does not retain its full DER) is rejected -- pass DER or PEM.
+function _normCertDer(c) {
+  if (c == null) throw _err("cms/bad-input", "each signer requires a certificate (cert)");
+  if (c instanceof Uint8Array && !Buffer.isBuffer(c)) c = Buffer.from(c);   // a Uint8Array -> Buffer (below)
+  if (Buffer.isBuffer(c)) return c[0] === 0x30 ? c : _pemToDer(c.toString("latin1"));   // DER as-is, else PEM
+  if (typeof c === "string") return _pemToDer(c);
+  throw _err("cms/bad-input", "a signer certificate must be a DER Buffer or a PEM string");
+}
+function _pemToDer(text) {
+  var m = text.match(/-----BEGIN CERTIFICATE-----([\s\S]*?)-----END CERTIFICATE-----/);
+  if (!m) throw _err("cms/bad-input", "a signer certificate PEM is not a CERTIFICATE block");
+  return Buffer.from(m[1].replace(/[^A-Za-z0-9+/=]/g, ""), "base64");
+}
+
+// pki.cms.sign -- documented by the @primitive block in cms-verify.js (the @module pki.cms home).
+function sign(content, signers, opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("cms/bad-input", "pki.cms.sign options must be an object");
+  var contentBuf = _toBuf(content, "content");
+  var list = Array.isArray(signers) ? signers : [signers];
+  if (!list.length) throw _err("cms/bad-input", "pki.cms.sign requires at least one signer");
+  var eContentType = opts.eContentType ? O(opts.eContentType) : OID_DATA;
+  // RFC 5652 sec. 5.3: signed attributes MUST be present (carrying a content-type attribute)
+  // whenever the encapsulated content type is not id-data -- so signedAttributes:false is only
+  // valid for id-data content. Refusing it here keeps cms.sign from emitting a non-conformant
+  // SignedData (e.g. a timestamp token, id-ct-TSTInfo, with no signed attributes).
+  if (opts.signedAttributes === false && eContentType !== OID_DATA) {
+    throw _err("cms/bad-input", "signed attributes are required when eContentType is not id-data (RFC 5652 sec. 5.3)");
+  }
+  // A supplied signing-time MUST be a valid Date (or false to omit the attribute) -- never a
+  // silently-ignored non-Date or an Invalid Date that would encode a garbage Time.
+  if (opts.signingTime != null && opts.signingTime !== false && (!(opts.signingTime instanceof Date) || isNaN(opts.signingTime.getTime()))) {
+    throw _err("cms/bad-input", "signingTime must be a valid Date, or false to omit it");
+  }
+
+  return Promise.all(list.map(function (s) { return _buildSignerInfo(s, contentBuf, eContentType, opts); })).then(function (built) {
+    // digestAlgorithms: the distinct SignerInfo digestAlgorithm AlgorithmIdentifiers, deduped.
+    var seen = {}, digestAlgs = [];
+    built.forEach(function (x) { var k = x.digestAlgId.toString("hex"); if (!seen[k]) { seen[k] = 1; digestAlgs.push(x.digestAlgId); } });
+    // CMSVersion (RFC 5652 sec. 5.1): 3 if any SignerInfo is v3 (ski) or eContentType != id-data;
+    // otherwise 1 (v1 emits only X.509 certificates, so the v4/v5 attribute-certificate cases
+    // do not arise).
+    var v3 = built.some(function (x) { return x.version === 3; }) || eContentType !== OID_DATA;
+    var version = v3 ? 3 : 1;
+    // EncapsulatedContentInfo: eContentType + [0] EXPLICIT eContent (omitted when detached).
+    var encapFields = [b.oid(eContentType)];
+    if (!opts.detached) encapFields.push(b.explicit(0, b.octetString(contentBuf)));
+    var encap = b.sequence(encapFields);
+    // certificates [0] IMPLICIT SET OF (the signer certs), deduped + SET-OF-ordered, when embedded.
+    var sdFields = [b.integer(BigInt(version)), b.set(digestAlgs), encap];
+    if (opts.certificates !== false) {
+      var certDers = _dedupe(built.map(function (x) { return x.certDer; })).sort(Buffer.compare);   // X.690 sec. 11.6
+      sdFields.push(b.contextConstructed(0, Buffer.concat(certDers)));              // [0] IMPLICIT SET OF
+    }
+    sdFields.push(b.set(built.map(function (x) { return x.si; })));                 // signerInfos SET OF
+    var signedData = b.sequence(sdFields);
+    var contentInfo = b.sequence([b.oid(OID_SIGNED_DATA), b.explicit(0, signedData)]);   // ContentInfo
+    return opts.pem ? pkix.pemEncode(contentInfo, "CMS", frameworkError.PemError) : contentInfo;
+  });
+}
+
+// Dedupe certificate DERs (two signers may share a cert -- embed it once).
+function _dedupe(ders) {
+  var seen = {}, out = [];
+  ders.forEach(function (d) { var k = d.toString("hex"); if (!seen[k]) { seen[k] = 1; out.push(d); } });
+  return out;
+}
+
+function _toBuf(v, what) {
+  if (Buffer.isBuffer(v)) return v;
+  if (v instanceof Uint8Array) return Buffer.from(v);
+  throw _err("cms/bad-input", what + " must be a Buffer");
+}
+
+// Coverage residual -- three defensive branches are unreachable through the shipped path:
+//   * `_skiValue`'s `cert.extensions || []` fallback -- x509.parse always surfaces `extensions`
+//     as an array (empty when absent), so the `|| []` never fires.
+//   * `_assertKeyMatchesScheme`'s `key.algorithm || {}` -- a WebCrypto CryptoKey always carries
+//     an `algorithm`, so the `|| {}` fallback never fires.
+//   * `_assertKeyMatchesScheme`'s `!ka.hash` guard -- an `imp.hash` is set only for an RSA
+//     scheme, which requires `ka.name` to already equal the RSA name (else the earlier name
+//     check throws); an RSA CryptoKey always carries a `hash`, so `!ka.hash` never fires.
+module.exports = { sign: sign };

package/lib/cms-verify.js

@@ -20,6 +20,7 @@
  * @card Verify a CMS SignedData signature (S/MIME, timestamps, code signing).
  */
 
+var nodeCrypto = require("crypto");
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
 var x509 = require("./schema-x509");
@@ -27,6 +28,7 @@ var cms = require("./schema-cms");
 var webcrypto = require("./webcrypto");
 var subtle = webcrypto.webcrypto.subtle;
 var edwardsPoint = require("./edwards-point");
+var cmsSign = require("./cms-sign");
 var validator = require("./validator-all");
 var guard = require("./guard-all");
 var frameworkError = require("./framework-error");
@@ -39,6 +41,16 @@ var OID_CONTENT_TYPE = oid.byName("contentType");
 
 // A digest-algorithm name -> the WebCrypto hash.
 var DIGEST_HASH = { sha1: "SHA-1", sha256: "SHA-256", sha384: "SHA-384", sha512: "SHA-512" };
+// SHAKE256 (RFC 8419 sec. 2.3, the Ed448 message digest) has no WebCrypto hash, so it is computed
+// with node:crypto; its 512-bit (64-byte) output length is fixed by the profile.
+var SHAKE_OUT = { shake256: 64 };
+// Is `name` a message-digest algorithm this verifier supports (SHA-2 family or SHAKE256)?
+function _supportedDigest(name) { return !!(DIGEST_HASH[name] || SHAKE_OUT[name]); }
+// The digest of `content` under the named algorithm, resolved to a Buffer.
+function _computeDigest(name, content) {
+  if (SHAKE_OUT[name]) return Promise.resolve(nodeCrypto.createHash(name, { outputLength: SHAKE_OUT[name] }).update(content).digest());
+  return subtle.digest(DIGEST_HASH[name], content).then(function (d) { return Buffer.from(d); });
+}
 // A signatureAlgorithm name -> its verify scheme. A combined OID (sha256WithRSAEncryption,
 // ecdsaWithSHA256) carries its own hash; a bare key OID (rsaEncryption, ecPublicKey) takes the
 // hash from the SignerInfo digestAlgorithm.
@@ -284,7 +296,7 @@ function _verifyOne(si, content, eContentType, parsedCerts) {
   // the content digest is required whenever signed attributes are present, for every scheme
   // (the message-digest attribute is computed under digestAlgorithm). Either gap is a
   // fail-closed unsupported-algorithm verdict, never a foreign-domain throw from the digest.
-  if ((scheme.kind !== "eddsa" && !sigHash) || (si.signedAttrsBytes && !digestHash)) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported digest algorithm " + JSON.stringify(si.digestAlgorithm.name) });
+  if ((scheme.kind !== "eddsa" && !sigHash) || (si.signedAttrsBytes && !_supportedDigest(si.digestAlgorithm.name))) return Promise.resolve({ ok: false, code: "cms/unsupported-algorithm", sid: si.sid, message: "unsupported digest algorithm " + JSON.stringify(si.digestAlgorithm.name) });
   var signers = _findSignerCerts(si.sid, parsedCerts);
   if (!signers.length) return Promise.resolve({ ok: false, code: "cms/signer-cert-not-found", sid: si.sid, message: "no certificate matches this SignerInfo's signer identifier" });
   var sigBytes = _toBuf(si.signature, "the SignerInfo signature");
@@ -319,8 +331,8 @@ function _verifyOne(si, content, eContentType, parsedCerts) {
     try {
       declared = asn1.read.octetString(mdAttr.values[0]);
     } catch (e) { throw _err("cms/bad-signed-attrs", "the message-digest attribute value is not an OCTET STRING", e); }
-    return subtle.digest(digestHash, content).then(function (d) {
-      if (!Buffer.from(d).equals(declared)) return { mismatch: { code: "cms/message-digest-mismatch", message: "the message-digest attribute does not match the content digest" } };
+    return _computeDigest(si.digestAlgorithm.name, content).then(function (d) {
+      if (!d.equals(declared)) return { mismatch: { code: "cms/message-digest-mismatch", message: "the message-digest attribute does not match the content digest" } };
       return reTagged;
     });
   }).then(function (signedBytes) {
@@ -401,4 +413,37 @@ function _addCert(out, der) {
 //     is always an array (or it throws), so this belt-and-suspenders throw never fires.
 //   * `c && c.bytes ? c.bytes : c` -- schema-cms surfaces every embedded certificate as an
 //     object carrying a `bytes` Buffer, so the raw-value fallback never fires.
-module.exports = { verify: verify };
+/**
+ * @primitive  pki.cms.sign
+ * @signature  pki.cms.sign(content, signers, opts?) -> Promise<Buffer|string>
+ * @since      0.2.15
+ * @status     experimental
+ * @spec       RFC 5652
+ * @related    pki.cms.verify, pki.schema.cms.parse
+ *
+ * Produce a CMS SignedData (RFC 5652 sec. 5) over `content` (a `Buffer`) -- the structure
+ * S/MIME signed mail, RFC 3161 timestamp tokens, and code signing rest on, and exactly what
+ * `pki.cms.verify` consumes and OpenSSL `cms -verify` validates. Each `signers[i]` is
+ * `{ cert, key, digestAlgorithm?, pss? }`: `cert` the signer certificate (PEM or DER), `key`
+ * its private key (a WebCrypto `CryptoKey` or a PKCS#8 DER `Buffer` / PEM string). The
+ * signature covers the RFC 5652 sec. 5.4 preimage: with signed attributes (the default) the
+ * message-digest attribute is bound to the content digest and the signature is over the
+ * canonical DER SET OF SignedAttributes; otherwise over the content directly. RSA (PKCS#1 v1.5
+ * and, with `pss`, RSASSA-PSS), ECDSA (P-256/384/521), Ed25519, and Ed448 are covered.
+ *
+ * @opts  detached          Omit the encapsulated content (a detached signature; the verifier
+ *                          supplies the content). Default false.
+ * @opts  eContentType      The encapsulated content type (an OID name). Default `data`.
+ * @opts  signedAttributes  Include signed attributes (content-type, message-digest, signing-time);
+ *                          false signs the content directly. Default true.
+ * @opts  signingTime       A `Date` for the signing-time attribute, or false to omit it.
+ * @opts  sid               `"issuerAndSerial"` (default) or `"ski"` (subjectKeyIdentifier).
+ * @opts  certificates      Embed the signer certificates in the output. Default true.
+ * @opts  pem               Return a PEM string (`-----BEGIN CMS-----`) instead of a DER Buffer.
+ * @example
+ *   var p7 = await pki.cms.sign(Buffer.from("hello"), { cert: signerCertDer, key: signerKeyPkcs8 });
+ *   var res = await pki.cms.verify(p7);   // res.valid === true
+ */
+var sign = cmsSign.sign;
+
+module.exports = { verify: verify, sign: sign };

package/lib/tsp-sign.js

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.tsp
+ * @nav        Signing
+ * @title      Timestamps
+ * @intro Create an RFC 3161 timestamp token. A TimeStampToken IS a CMS SignedData whose
+ *   encapsulated content is a `TSTInfo` (the timestamped message imprint + trusted time), so
+ *   `sign(messageImprint, tsa, opts)` builds the `TSTInfo`, attaches the RFC 3161 sec. 2.4.2
+ *   signing-certificate attribute that binds the token to the TSA certificate, and signs it
+ *   through `pki.cms.sign`. It is the producing side of `pki.schema.tsp.parseToken`.
+ * @spec RFC 3161
+ * @card Create an RFC 3161 timestamp token (a CMS SignedData over a TSTInfo).
+ */
+
+var nodeCrypto = require("crypto");
+var asn1 = require("./asn1-der");
+var oid = require("./oid");
+var cmsSign = require("./cms-sign");
+var frameworkError = require("./framework-error");
+
+var TspError = frameworkError.TspError;
+var b = asn1.build;
+function _err(code, message, cause) { return new TspError(code, message, cause); }
+function O(name) { return oid.byName(name); }
+
+// Digest names whose imprint / certHash this producer supports (the SHA-2 family).
+var NODE_DIGEST = { sha256: "sha256", sha384: "sha384", sha512: "sha512" };
+// The message-imprint hash MUST be exactly the digest algorithm's output length (RFC 3161 sec.
+// 2.4.1 -- hashedMessage is "the hash of the datum to be time-stamped").
+var HASH_LEN = { sha256: 32, sha384: 48, sha512: 64 };
+
+// A hash AlgorithmIdentifier { OID, NULL } -- messageImprint and ESSCertIDv2 hash algorithms
+// carry an explicit NULL parameter (the form RFC 3161 / RFC 5035 producers emit).
+function _hashAlgId(name) {
+  if (!NODE_DIGEST[name]) throw _err("tsp/unsupported-algorithm", "unsupported hash algorithm " + JSON.stringify(name));
+  return b.sequence([b.oid(O(name)), b.nullValue()]);
+}
+// A policy identifier: an OID name or a dotted-decimal string.
+function _policy(p) {
+  if (typeof p !== "string") throw _err("tsp/bad-input", "the timestamp policy must be an OID name or dotted string");
+  return /^\d+(\.\d+)+$/.test(p) ? b.oid(p) : b.oid(O(p));
+}
+// The signer certificate DER (DER Buffer / PEM string / Uint8Array) -- for the ESSCertIDv2 hash.
+function _certDer(c) {
+  if (c == null) throw _err("tsp/bad-input", "the TSA signer requires a certificate (cert)");
+  if (c instanceof Uint8Array && !Buffer.isBuffer(c)) c = Buffer.from(c);          // a Uint8Array -> Buffer
+  if (Buffer.isBuffer(c)) { if (c[0] === 0x30) return c; c = c.toString("latin1"); }   // DER as-is, else decode as PEM
+  if (typeof c !== "string") throw _err("tsp/bad-input", "the TSA certificate must be a DER Buffer or a PEM string");
+  var m = c.match(/-----BEGIN CERTIFICATE-----([\s\S]*?)-----END CERTIFICATE-----/);
+  if (!m) throw _err("tsp/bad-input", "the TSA certificate PEM is not a CERTIFICATE block");
+  return Buffer.from(m[1].replace(/[^A-Za-z0-9+/=]/g, ""), "base64");
+}
+
+// The RFC 5035 SigningCertificateV2 signed-attribute value binding the token to the TSA cert:
+// SigningCertificateV2 ::= SEQUENCE { certs SEQUENCE OF ESSCertIDv2 }, ESSCertIDv2 ::= SEQUENCE {
+// hashAlgorithm DEFAULT sha256, certHash OCTET STRING, issuerSerial OPTIONAL }. The default
+// sha256 hashAlgorithm is omitted; certHash is the digest of the certificate.
+function _signingCertV2(certDer, hashName) {
+  var certHash = nodeCrypto.createHash(NODE_DIGEST[hashName]).update(certDer).digest();
+  var essCertId = hashName === "sha256"
+    ? b.sequence([b.octetString(certHash)])                       // hashAlgorithm DEFAULT sha256 omitted
+    : b.sequence([_hashAlgId(hashName), b.octetString(certHash)]);
+  return b.sequence([b.sequence([essCertId])]);
+}
+
+/**
+ * @primitive  pki.tsp.sign
+ * @signature  pki.tsp.sign(messageImprint, tsa, opts) -> Promise<Buffer|string>
+ * @since      0.2.15
+ * @status     experimental
+ * @spec       RFC 3161
+ * @related    pki.schema.tsp.parseToken, pki.cms.sign
+ *
+ * Create an RFC 3161 TimeStampToken over `messageImprint` (`{ hashAlgorithm, hashedMessage }`
+ * -- the hash of the data being timestamped, computed by the requester). `tsa` is the
+ * timestamp authority's `{ cert, key }` (as `pki.cms.sign` takes them). The token is a CMS
+ * SignedData whose content is a `TSTInfo` carrying the imprint, the TSA policy, a serial
+ * number, and `genTime`; the RFC 3161 sec. 2.4.2 signing-certificate attribute binding the
+ * token to the TSA certificate is attached automatically.
+ *
+ * @opts  policy        REQUIRED -- the TSA policy identifier (an OID name or dotted string).
+ * @opts  serialNumber  REQUIRED -- a unique token serial number (a number or BigInt).
+ * @opts  genTime       The trusted time (a `Date`). Default: now.
+ * @opts  nonce         The request nonce to echo (a number or BigInt), for replay protection.
+ * @opts  accuracy      `{ seconds?, millis?, micros? }` -- the genTime +/- accuracy.
+ * @opts  ordering      Whether tokens from this TSA are strictly ordered in time (boolean).
+ * @opts  certHashAlgorithm  The ESSCertIDv2 hash algorithm name. Default `sha256`.
+ * @opts  sid / pem     Passed through to `pki.cms.sign` (signer identifier, PEM output).
+ * @example
+ *   var imprint = { hashAlgorithm: "sha256", hashedMessage: sha256Digest };
+ *   var token = await pki.tsp.sign(imprint, { cert: signerCertDer, key: signerKeyPkcs8 }, { policy: "1.3.6.1.4.1.1", serialNumber: 1 });
+ *   (await pki.cms.verify(token)).valid;   // true
+ */
+function sign(messageImprint, tsa, opts) {
+  opts = opts || {};
+  if (typeof opts !== "object" || Buffer.isBuffer(opts)) throw _err("tsp/bad-input", "pki.tsp.sign options must be an object");
+  var mi = messageImprint || {};
+  if (!mi.hashAlgorithm || !NODE_DIGEST[mi.hashAlgorithm]) throw _err("tsp/unsupported-algorithm", "messageImprint.hashAlgorithm must be a supported hash name");
+  if (!Buffer.isBuffer(mi.hashedMessage) && !(mi.hashedMessage instanceof Uint8Array)) throw _err("tsp/bad-input", "messageImprint.hashedMessage must be a Buffer");
+  if (mi.hashedMessage.length !== HASH_LEN[mi.hashAlgorithm]) throw _err("tsp/bad-input", "messageImprint.hashedMessage length (" + mi.hashedMessage.length + ") does not match the " + mi.hashAlgorithm + " digest length (" + HASH_LEN[mi.hashAlgorithm] + ")");
+  if (!opts.policy) throw _err("tsp/bad-input", "a timestamp token requires a policy identifier (opts.policy)");
+  if (opts.serialNumber == null) throw _err("tsp/bad-input", "a timestamp token requires a serialNumber (opts.serialNumber)");
+
+  var certDer = _certDer(tsa && tsa.cert);
+  var certHashAlg = opts.certHashAlgorithm || "sha256";
+  if (!NODE_DIGEST[certHashAlg]) throw _err("tsp/unsupported-algorithm", "unsupported certHashAlgorithm " + JSON.stringify(certHashAlg));
+
+  // TSTInfo (RFC 3161 sec. 2.4.2): version(1), policy, messageImprint, serialNumber, genTime,
+  // then the OPTIONAL accuracy / ordering / nonce in ascending order.
+  var imprint = b.sequence([_hashAlgId(mi.hashAlgorithm), b.octetString(Buffer.from(mi.hashedMessage))]);
+  // genTime defaults to now; a supplied value MUST be a valid Date (never a silently-ignored
+  // non-Date or an Invalid Date that would encode a garbage GeneralizedTime).
+  if (opts.genTime != null && (!(opts.genTime instanceof Date) || isNaN(opts.genTime.getTime()))) {
+    throw _err("tsp/bad-input", "genTime must be a valid Date");
+  }
+  var genTime = opts.genTime instanceof Date ? opts.genTime : new Date();
+  var fields = [b.integer(1n), _policy(opts.policy), imprint, b.integer(BigInt(opts.serialNumber)), b.generalizedTime(genTime)];
+  if (opts.accuracy) fields.push(_accuracy(opts.accuracy));
+  if (opts.ordering === true) fields.push(b.boolean(true));
+  if (opts.nonce != null) fields.push(b.integer(BigInt(opts.nonce)));
+  var tstInfo = b.sequence(fields);
+
+  var signCert = { type: "signingCertificateV2", values: [_signingCertV2(certDer, certHashAlg)] };
+  var extra = [signCert].concat(opts.additionalSignedAttributes || []);
+  var signer = { cert: certDer, key: tsa && tsa.key, digestAlgorithm: opts.digestAlgorithm, pss: opts.pss };
+  return cmsSign.sign(tstInfo, signer, {
+    eContentType: "tSTInfo",
+    additionalSignedAttributes: extra,
+    sid: opts.sid,
+    pem: opts.pem,
+  });
+}
+
+// Accuracy ::= SEQUENCE { seconds INTEGER OPTIONAL, millis [0] INTEGER (1..999) OPTIONAL,
+// micros [1] INTEGER (1..999) OPTIONAL } (RFC 3161 sec. 2.4.2). seconds is a non-negative
+// integer; millis and micros MUST each be in 1..999 -- enforced before encoding.
+function _accuracy(a) {
+  var f = [];
+  if (a.seconds != null) {
+    var s = Number(a.seconds);
+    if (!Number.isInteger(s) || s < 0 || s > 0x7fffffff) throw _err("tsp/bad-input", "Accuracy seconds must be a non-negative integer");
+    f.push(b.integer(BigInt(s)));
+  }
+  if (a.millis != null) f.push(b.contextPrimitive(0, _subMilliBytes(a.millis, "millis")));
+  if (a.micros != null) f.push(b.contextPrimitive(1, _subMilliBytes(a.micros, "micros")));
+  return b.sequence(f);
+}
+// The content octets of an Accuracy millis/micros field: an INTEGER in 1..999 (RFC 3161 sec.
+// 2.4.2), without the universal INTEGER tag (the field is IMPLICIT [0]/[1]).
+function _subMilliBytes(n, label) {
+  var v = Number(n);
+  if (!Number.isInteger(v) || v < 1 || v > 999) throw _err("tsp/bad-input", "Accuracy " + label + " must be an integer in 1..999 (RFC 3161 sec. 2.4.2)");
+  return b.integer(BigInt(v)).subarray(2);               // strip the universal INTEGER tag+length
+}
+
+// Coverage residual -- `_hashAlgId`'s unsupported-hash throw is unreachable through the shipped
+// path: both callers (the messageImprint hash and the ESSCertIDv2 certHashAlgorithm) validate
+// the name against NODE_DIGEST before `_hashAlgId` runs, so the guard is belt-and-suspenders.
+module.exports = { sign: sign };

package/lib/validator-sig.js

@@ -54,4 +54,21 @@ function ecdsaSigToRaw(der, coordLen, E, code) {
   return Buffer.concat([coord(node.children[0], "r"), coord(node.children[1], "s")]);
 }
 
-module.exports = { ecdsaSigToRaw: ecdsaSigToRaw };
+// rawToEcdsaDer(raw, coordLen) -> the canonical DER ECDSA-Sig-Value SEQUENCE { r, s } for a raw
+// r||s signature (IEEE P1363, the WebCrypto sign() output). The inverse of ecdsaSigToRaw: a
+// signer composes this so the emitted ECDSA signature is canonical DER (minimally-encoded
+// INTEGERs via the build layer), never a hand-built SEQUENCE that could re-introduce a
+// non-minimal encoding. A config-time TypeError guards a mis-sized raw signature at entry.
+// @enforced-by behavioral -- a DER ECDSA-Sig-Value BUILD has no rename-proof code shape distinct
+// from generic sequence([integer,integer]); the round-trip vectors (build -> ecdsaSigToRaw
+// identity) and the cms.sign ECDSA KATs are the guard.
+function rawToEcdsaDer(raw, coordLen) {
+  if (!Buffer.isBuffer(raw) || typeof coordLen !== "number" || coordLen <= 0 || raw.length !== coordLen * 2) {
+    throw new TypeError("rawToEcdsaDer: raw signature must be a Buffer of exactly 2*coordLen bytes");
+  }
+  var r = BigInt("0x" + raw.subarray(0, coordLen).toString("hex"));
+  var s = BigInt("0x" + raw.subarray(coordLen).toString("hex"));
+  return asn1.build.sequence([asn1.build.integer(r), asn1.build.integer(s)]);
+}
+
+module.exports = { ecdsaSigToRaw: ecdsaSigToRaw, rawToEcdsaDer: rawToEcdsaDer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "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:7f3139fc-e726-4373-afdf-0e304562ee70",
+  "serialNumber": "urn:uuid:edfce9fb-f69d-4264-b69d-27177c001bc9",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-13T21:48:02.712Z",
+    "timestamp": "2026-07-14T00:56:05.894Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.2.14",
+      "bom-ref": "@blamejs/pki@0.2.15",
       "type": "application",
       "name": "pki",
-      "version": "0.2.14",
+      "version": "0.2.15",
       "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.14",
+      "purl": "pkg:npm/%40blamejs/pki@0.2.15",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.2.14",
+      "ref": "@blamejs/pki@0.2.15",
       "dependsOn": []
     }
   ]