@blamejs/pki 0.4.15 → 0.5.0

package/lib/smime.js

@@ -495,7 +495,7 @@ function _base64Body(der) {
  * @primitive  pki.smime.sign
  * @signature  pki.smime.sign(content, signers, opts?) -> Promise<Buffer>
  * @since      0.2.25
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8551, RFC 5652
  * @related    pki.smime.verify, pki.cms.sign
  *
@@ -521,6 +521,10 @@ function _base64Body(der) {
  * @opts protectHeaders enable RFC 9788 header protection (`hp="clear"`) -- inline `opts.headers` on the signed payload + the outer display headers.
  * @opts headers     the Non-Structural fields to protect + display: an object `{ Name: value }` or an array `[{ name, value }]` (Subject / From / To / Date / ...); used with `protectHeaders`.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: signerKeyPkcs8 });
  *   var msg = await pki.smime.sign(Buffer.from("hello"), [{ cert: signerCertDer, key: signerKeyPkcs8 }]);
  */
 async function sign(content, signers, opts) {
@@ -565,7 +569,7 @@ function _capped(msg) {
  * @primitive  pki.smime.verify
  * @signature  pki.smime.verify(message, opts?) -> Promise<{ valid, signers, form, content, micalg, protectedHeaders, headerProtection }>
  * @since      0.2.25
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8551, RFC 5652, RFC 9788
  * @related    pki.smime.sign, pki.cms.verify, pki.path.validate
  *
@@ -595,6 +599,11 @@ function _capped(msg) {
  * @opts strictMicalg reject a `multipart/signed` whose `micalg` disagrees with the SignerInfo digest.
  * @opts legacyHeaderProtection  opt in to detecting a LEGACY RFC 8551 header-protected message (RFC 9788 sec. 4.10): a Cryptographic Payload that is a bare `message/rfc822` wrap with no `hp=` parameter. When set, a precisely-identified legacy message surfaces the inner message's headers under `headerProtection.legacy = { headers, mode, fromMismatch, confidential }` -- `headers` an ordered `[{ name, value }]` array (retaining legally-repeated fields such as `Received`), the mode inferred from the envelope (`clear` here) -- NOT under `protectedHeaders`, and `present` stays `false`. Consuming `headerProtection.legacy.headers` is an explicit choice: a legacy message is structurally indistinguishable from an ordinary forwarded `message/rfc822`, so this is a heuristic (RFC 9788 sec. 4.10.2: "not based on any strong end-to-end guarantees") -- cross-check `legacy.fromMismatch`. Anything not precisely identified (a nested crypto layer, an `hp=` on the inner message, a non-`message/rfc822` payload, a duplicate of a singleton field, or a duplicate Content-Type) reports `legacy: null`. Off by default. The signed-and-encrypted form (RFC 9788 Appendix C.3.17) is a documented gap (`legacy: null` at `decrypt`; surfaces as `clear` only via the caller's re-`verify` step) -- the non-recursive layered API exposes no single seam holding both the inner signature verdict and the outer header section.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = await pki.x509.sign({ subject: "Signer", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: key });
+ *   var smimeMessageBytes = await pki.smime.sign(Buffer.from("hello"), [{ cert: cert, key: key }]);
  *   var res = await pki.smime.verify(smimeMessageBytes);
  *   if (res.valid) { res.content; res.signers[0].sid; }
  */
@@ -680,7 +689,7 @@ function _cmsEncryptOpts(opts) {
  * @primitive  pki.smime.encrypt
  * @signature  pki.smime.encrypt(content, recipients, opts?) -> Promise<Buffer>
  * @since      0.2.26
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8551, RFC 5652, RFC 5083
  * @related    pki.smime.decrypt, pki.cms.encrypt
  *
@@ -709,6 +718,11 @@ function _cmsEncryptOpts(opts) {
  * @opts keyIdentifier              forwarded: `"issuerAndSerial"` (default) or `"subjectKeyIdentifier"`.
  * @opts ukm                        forwarded: user keying material for kari / kemri recipients.
  * @example
+ *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };
+ *   var pair = await pki.key.generate(rsa);
+ *   var recipientCertDer = await pki.x509.sign({ subject: "Recipient", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var enc = await pki.smime.encrypt(Buffer.from("secret"), [{ cert: recipientCertDer }]);
  */
 async function encrypt(content, recipients, opts) {
@@ -735,7 +749,7 @@ async function encrypt(content, recipients, opts) {
  * @primitive  pki.smime.decrypt
  * @signature  pki.smime.decrypt(message, keyMaterial, opts?) -> Promise<{ content, smimeType, authenticated, recipientType, recipientIndex, contentEncryptionAlgorithm, protectedHeaders, headerProtection }>
  * @since      0.2.26
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8551, RFC 5652, RFC 5083, RFC 9788
  * @related    pki.smime.encrypt, pki.cms.decrypt, pki.smime.verify
  *
@@ -763,9 +777,15 @@ async function encrypt(content, recipients, opts) {
  * @opts strictSmimeType reject a header `smime-type` that disagrees with the CMS body (`smime/smime-type-mismatch`).
  * @opts legacyHeaderProtection  opt in to detecting a LEGACY RFC 8551 header-protected message (RFC 9788 sec. 4.10): an encrypted Cryptographic Payload that is a bare `message/rfc822` wrap with no `hp=` parameter. When set, a precisely-identified legacy message surfaces the inner headers under `headerProtection.legacy = { headers, mode: "cipher", fromMismatch, confidential }` -- `headers` an ordered `[{ name, value }]` array (retaining repeated fields), the `confidential` set derived from the actual visible outer Header Section -- NOT under `protectedHeaders`, and `present` stays `false`, since a legacy message is structurally indistinguishable from a forwarded `message/rfc822` (a heuristic; cross-check `legacy.fromMismatch`). Anything not precisely identified reports `legacy: null`. Off by default.
  * @example
+ *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };
+ *   var pair = await pki.key.generate(rsa);
+ *   var recipientKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var recipientCertDer = await pki.x509.sign({ subject: "Recipient", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") }, { key: recipientKeyPkcs8 });
+ *   var smimeMessageBytes = await pki.smime.encrypt(Buffer.from("secret"), [{ cert: recipientCertDer }]);
  *   var res = await pki.smime.decrypt(smimeMessageBytes, { key: recipientKeyPkcs8, cert: recipientCertDer });
  *   res.content;        // the recovered inner MIME entity
- *   res.authenticated;  // false for an enveloped-only (CBC) message -- no integrity
+ *   res.authenticated;  // true here (an AEAD content cipher); false for an enveloped-only CBC message, which carries no integrity
  */
 async function decrypt(message, keyMaterial, opts) {
   opts = opts || {};
@@ -795,7 +815,7 @@ async function decrypt(message, keyMaterial, opts) {
  * @primitive  pki.smime.compress
  * @signature  pki.smime.compress(content, opts?) -> Promise<Buffer>
  * @since      0.2.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8551, RFC 3274
  * @related    pki.smime.decompress, pki.cms.compress
  *
@@ -827,7 +847,7 @@ async function compress(content, opts) {
  * @primitive  pki.smime.decompress
  * @signature  pki.smime.decompress(message, opts?) -> Promise<{ content, contentType, contentTypeName, compressionAlgorithm }>
  * @since      0.2.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8551, RFC 3274
  * @related    pki.smime.compress, pki.cms.decompress, pki.smime.verify, pki.smime.decrypt
  *
@@ -842,6 +862,7 @@ async function compress(content, opts) {
  *
  * @opts maxOutputBytes forwarded to cms.decompress: lower the decompressed-output cap (a DoS bound; downward only).
  * @example
+ *   var compressedSmimeBytes = await pki.smime.compress(Buffer.from("compress me"));
  *   var res = await pki.smime.decompress(compressedSmimeBytes);
  *   res.content;   // the recovered inner MIME entity
  */

package/lib/tls-cert-compress.js

@@ -141,7 +141,7 @@ function _resolveAllowed(opts) {
  * @primitive  pki.tls.decompressCertificate
  * @signature  pki.tls.decompressCertificate(bytes, opts?) -> { algorithm, algorithmName, uncompressedLength, certificateMessage, certificate }
  * @since      0.4.3
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8879, RFC 8446
  * @related    pki.tls.compressCertificate, pki.tls.parseCertificateMessage, pki.schema.x509.parse
  *
@@ -179,6 +179,10 @@ function _resolveAllowed(opts) {
  * @example
  *   // The Certificate message this codec carries: an empty request context, then one
  *   // entry -- the certificate DER followed by its (here empty) extensions vector.
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var certDer = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var u24 = function (n) { var b = Buffer.alloc(3); b.writeUIntBE(n, 0, 3); return b; };
  *   var entry = Buffer.concat([u24(certDer.length), certDer, Buffer.from([0, 0])]);
  *   var message = Buffer.concat([Buffer.from([0]), u24(entry.length), entry]);
@@ -252,7 +256,7 @@ function decompressCertificate(bytes, opts) {
  * @primitive  pki.tls.parseCertificateMessage
  * @signature  pki.tls.parseCertificateMessage(bytes, opts?) -> { certificateRequestContext, entries }
  * @since      0.4.3
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8446, RFC 7250
  * @related    pki.tls.decompressCertificate, pki.schema.x509.parse
  *
@@ -277,6 +281,10 @@ function decompressCertificate(bytes, opts) {
  *   certificateType - "X509" (default) or "RawPublicKey" (RFC 7250).
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var certDer = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var u24 = function (n) { var b = Buffer.alloc(3); b.writeUIntBE(n, 0, 3); return b; };
  *   var entry = Buffer.concat([u24(certDer.length), certDer, Buffer.from([0, 0])]);
  *   var message = Buffer.concat([Buffer.from([0]), u24(entry.length), entry]);
@@ -307,7 +315,7 @@ function parseCertificateMessage(bytes, opts) {
  * @primitive  pki.tls.compressCertificate
  * @signature  pki.tls.compressCertificate(certificateMessage, opts?) -> Buffer
  * @since      0.4.3
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8879
  * @related    pki.tls.decompressCertificate
  *
@@ -330,6 +338,10 @@ function parseCertificateMessage(bytes, opts) {
  *   level     - the codec's compression level, passed through unchanged where it applies.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var certDer = await pki.x509.sign({ subject: "example.com", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var u24 = function (n) { var b = Buffer.alloc(3); b.writeUIntBE(n, 0, 3); return b; };
  *   var entry = Buffer.concat([u24(certDer.length), certDer, Buffer.from([0, 0])]);
  *   var message = Buffer.concat([Buffer.from([0]), u24(entry.length), entry]);

package/lib/trust.js

@@ -353,7 +353,7 @@ function _dedupAnchors(anchors) {
  * @primitive  pki.trust.parseCertdata
  * @signature  pki.trust.parseCertdata(text) -> { anchors }
  * @since      0.2.0
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5280 (NSS certdata.txt object stream)
  * @defends    trust-metadata-misattribution (CWE-345), trust-store-parser-DoS (CWE-770)
  * @related    pki.trust.parseCcadbCsv, pki.trust.anchor, pki.path.validate
@@ -378,6 +378,11 @@ function _dedupAnchors(anchors) {
  * @example
  *   // Real input is the NSS certdata.txt read from disk; a one-root stream is
  *   // synthesized here from a DER certificate to show the object shape.
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "Example Root", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign"] } },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var cert = pki.schema.x509.parse(der);
  *   var oct = function (buf) { return Array.prototype.map.call(buf, function (b) { return "\\" + ("000" + b.toString(8)).slice(-3); }).join(""); };
  *   var blk = function (n, v) { return n + " MULTILINE_OCTAL\n" + oct(v) + "\nEND\n"; };
@@ -573,7 +578,7 @@ function _pemCell(cell) {
  * @primitive  pki.trust.parseCcadbCsv
  * @signature  pki.trust.parseCcadbCsv(text) -> { anchors }
  * @since      0.2.0
- * @status     experimental
+ * @status     stable
  * @spec       RFC 4180, RFC 5280 (CCADB certificate-records CSV)
  * @defends    trust-metadata-misattribution (CWE-345), trust-store-parser-DoS (CWE-770)
  * @related    pki.trust.parseCertdata, pki.trust.anchor, pki.path.validate
@@ -592,6 +597,11 @@ function _pemCell(cell) {
  * encoding, through the same strict time reader.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemText = await pki.x509.sign({ subject: "Example Root", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign", "cRLSign"] } },
+ *     { key: await pki.key.export(pair.privateKey) }, { pem: true });
  *   var csv = "Common Name or Certificate Name,Trust Bits," +
  *             "Distrust for TLS After Date,Distrust for S/MIME After Date,PEM Info\n" +
  *             'Example Root,"Websites; Email",2027.06.01,,"' + pemText + '"';
@@ -651,7 +661,7 @@ function parseCcadbCsv(text) {
  * @primitive  pki.trust.anchor
  * @signature  pki.trust.anchor(entry, opts?) -> trustAnchor
  * @since      0.2.0
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5280 sec. 6.1.1 (NSS trust-bit semantics)
  * @related    pki.trust.parseCertdata, pki.trust.parseCcadbCsv, pki.path.validate
  *
@@ -669,12 +679,25 @@ function parseCcadbCsv(text) {
  *   purpose: string   // "serverAuth" | "emailProtection" | "codeSigning" -- fail-fast purpose check
  *
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example Root", subjectPublicKey: await pki.key.export(ca.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["keyCertSign", "cRLSign"], subjectKeyIdentifier: true } },
+ *     { key: caKey });
+ *   var pemText = pki.schema.x509.pemEncode(caDer, "CERTIFICATE");
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "leaf.example", subjectPublicKey: await pki.key.export(leaf.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { keyUsage: ["digitalSignature"], extendedKeyUsage: ["serverAuth"], authorityKeyIdentifier: true } },
+ *     { cert: caDer, key: caKey });
  *   var csv = "Common Name or Certificate Name,Trust Bits," +
  *             "Distrust for TLS After Date,Distrust for S/MIME After Date,PEM Info\n" +
  *             'Example Root,Websites,,,"' + pemText + '"';
  *   var entry = pki.trust.parseCcadbCsv(csv).anchors[0];
  *   var anchor = pki.trust.anchor(entry, { purpose: "serverAuth" });
- *   await pki.path.validate([pki.schema.x509.parse(der)], { time: new Date(), trustAnchor: anchor, checkPurpose: "serverAuth" });
+ *   await pki.path.validate([pki.schema.x509.parse(der)],
+ *     { time: new Date("2026-06-01T00:00:00Z"), trustAnchor: anchor, checkPurpose: "serverAuth" });
  */
 function anchor(entry, opts) {
   if (!entry || typeof entry !== "object" || !Buffer.isBuffer(entry.publicKey) ||

package/lib/tsp-sign.js

@@ -76,7 +76,7 @@ function _signingCertV2(certDer, hashName) {
  * @primitive  pki.tsp.sign
  * @signature  pki.tsp.sign(messageImprint, tsa, opts) -> Promise<Buffer|string>
  * @since      0.2.15
- * @status     experimental
+ * @status     stable
  * @spec       RFC 3161
  * @related    pki.schema.tsp.parseToken, pki.cms.sign
  *
@@ -96,6 +96,14 @@ function _signingCertV2(certDer, hashName) {
  * @opts  certHashAlgorithm  The ESSCertIDv2 hash algorithm name. Default `sha256`.
  * @opts  sid / pem     Passed through to `pki.cms.sign` (signer identifier, PEM output).
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Example TSA", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     // RFC 3161 sec. 2.3: a TSA certificate's extendedKeyUsage MUST be critical
+ *     extensions: { keyUsage: ["digitalSignature"], extendedKeyUsage: ["timeStamping"], extendedKeyUsageCritical: true } },
+ *     { key: signerKeyPkcs8 });
+ *   var sha256Digest = Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello")));
  *   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
@@ -200,7 +208,7 @@ function _assertImprint(mi) {
  * @primitive  pki.tsp.request
  * @signature  pki.tsp.request(messageImprint, opts) -> Buffer|string
  * @since      0.2.19
- * @status     experimental
+ * @status     stable
  * @spec       RFC 3161
  * @related    pki.tsp.parseRequest, pki.tsp.sign
  *
@@ -215,6 +223,7 @@ function _assertImprint(mi) {
  * @opts  extensions  An array of encoded Extension DER buffers ([0] IMPLICIT Extensions).
  * @opts  pem         Return a PEM "TIMESTAMP REQUEST" string instead of DER (boolean).
  * @example
+ *   var sha256Digest = Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello")));
  *   var req = pki.tsp.request({ hashAlgorithm: "sha256", hashedMessage: sha256Digest }, { nonce: 0x0102030405060708n, certReq: true });
  */
 function request(messageImprint, opts) {
@@ -242,7 +251,7 @@ function request(messageImprint, opts) {
  * @primitive  pki.tsp.parseRequest
  * @signature  pki.tsp.parseRequest(input) -> timeStampReq
  * @since      0.2.19
- * @status     experimental
+ * @status     stable
  * @spec       RFC 3161
  * @related    pki.tsp.request, pki.schema.tsp.parseRequest
  *
@@ -251,6 +260,8 @@ function request(messageImprint, opts) {
  * nonceHex, certReq, extensions }`; a malformed structure throws a typed `TspError`.
  *
  * @example
+ *   var der = pki.tsp.request({ hashAlgorithm: "sha256", hashedMessage: Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello"))) },
+ *     { certReq: true });
  *   var req = pki.tsp.parseRequest(der);
  *   req.certReq;   // -> boolean
  */
@@ -260,7 +271,7 @@ function parseRequest(input) { return schemaTsp.parseRequest(input); }
  * @primitive  pki.tsp.response
  * @signature  pki.tsp.response(token, opts) -> Buffer|string
  * @since      0.2.19
- * @status     experimental
+ * @status     stable
  * @spec       RFC 3161
  * @related    pki.tsp.parseResponse, pki.tsp.sign
  *
@@ -275,6 +286,14 @@ function parseRequest(input) { return schemaTsp.parseRequest(input); }
  * @opts  statusString  Human-readable PKIFreeText (string or array of strings).
  * @opts  pem           Return a PEM "TIMESTAMP RESPONSE" string instead of DER (boolean).
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = await pki.x509.sign({ subject: "Example TSA", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { keyUsage: ["digitalSignature"], extendedKeyUsage: ["timeStamping"], extendedKeyUsageCritical: true } },
+ *     { key: key });
+ *   var token = await pki.tsp.sign({ hashAlgorithm: "sha256", hashedMessage: Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello"))) },
+ *     { cert: cert, key: key }, { policy: "1.3.6.1.4.1.1", serialNumber: 1 });
  *   var resp = pki.tsp.response(token, {});                                  // granted
  *   var rej  = pki.tsp.response(null, { status: 2, failInfo: ["badAlg"] });  // rejection
  */
@@ -308,7 +327,7 @@ function response(token, opts) {
  * @primitive  pki.tsp.parseResponse
  * @signature  pki.tsp.parseResponse(input) -> timeStampResp
  * @since      0.2.19
- * @status     experimental
+ * @status     stable
  * @spec       RFC 3161
  * @related    pki.tsp.response, pki.schema.tsp.parse
  *
@@ -317,6 +336,15 @@ function response(token, opts) {
  * status-to-token coupling enforced; a granted response's token is decoded via `parseToken`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = await pki.x509.sign({ subject: "Example TSA", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { keyUsage: ["digitalSignature"], extendedKeyUsage: ["timeStamping"], extendedKeyUsageCritical: true } },
+ *     { key: key });
+ *   var token = await pki.tsp.sign({ hashAlgorithm: "sha256", hashedMessage: Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello"))) },
+ *     { cert: cert, key: key }, { policy: "1.3.6.1.4.1.1", serialNumber: 1 });
+ *   var der = pki.tsp.response(token, {});
  *   var resp = pki.tsp.parseResponse(der);
  *   resp.timeStampToken.tstInfo.genTime;   // -> Date (on a granted response)
  */
@@ -534,7 +562,7 @@ function _buildTsaChains(leaf, pool) {
  * @primitive  pki.tsp.verify
  * @signature  pki.tsp.verify(token, data, opts) -> Promise<result>
  * @since      0.2.19
- * @status     experimental
+ * @status     stable
  * @spec       RFC 3161, RFC 5816
  * @related    pki.tsp.sign, pki.cms.verify, pki.path.validate
  *
@@ -563,6 +591,13 @@ function _buildTsaChains(leaf, pool) {
  *                      token can still verify and chain.
  * @opts  revocationChecker  Passed through to `pki.path.validate`.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = await pki.x509.sign({ subject: "Example TSA", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { keyUsage: ["digitalSignature"], extendedKeyUsage: ["timeStamping"], extendedKeyUsageCritical: true } },
+ *     { key: signerKeyPkcs8 });
+ *   var sha256Digest = Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello")));
  *   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 });
  *   var res = await pki.tsp.verify(token, Buffer.from("hello"), {});

package/lib/vendor/README.md

@@ -1,41 +1,41 @@
 # Vendored dependencies
 
-`@blamejs/pki` ships with **zero npm runtime dependencies**, and it currently
-vendors **nothing** — this directory holds only the manifest.
+`@blamejs/pki` ships with zero npm runtime dependencies and currently vendors
+nothing. This directory holds only the manifest.
 
 ## Native-first crypto
 
 The toolkit's cryptography runs entirely on Node's built-in `node:crypto`. The
 engine floor (Node `>=24.19`) links OpenSSL 3.5, which provides:
 
-- the full classical set — RSA (PKCS#1 v1.5, PSS, OAEP), ECDSA, EdDSA
-  (Ed25519/Ed448), ECDH (incl. X25519/X448), AES (GCM/CBC/CTR/KW), HMAC, HKDF,
-  PBKDF2, and the SHA-1/2/3 family; and
-- the FIPS post-quantum set — **ML-KEM** (FIPS 203), **ML-DSA** (FIPS 204), and
+- the full classical set: RSA (PKCS#1 v1.5, PSS, OAEP), ECDSA, EdDSA
+  (Ed25519/Ed448), ECDH including X25519 and X448, AES (GCM/CBC/CTR/KW), HMAC,
+  HKDF, PBKDF2, and the SHA-1/2/3 family; and
+- the FIPS post-quantum set: **ML-KEM** (FIPS 203), **ML-DSA** (FIPS 204), and
   **SLH-DSA** (FIPS 205).
 
-A platform built-in ships **zero bytes**, has **nothing to hash-pin or keep
-current**, and is **OpenSSL/NSS-interoperable by construction** — which is what
-the toolkit's interoperability gate needs. So there is no reason to vendor a
-crypto library when the runtime already provides the primitive.
+A platform built-in ships zero bytes, has nothing to hash-pin or keep current,
+and is OpenSSL- and NSS-interoperable by construction, which is what the
+toolkit's interoperability gate needs. There is no reason to vendor a crypto
+library when the runtime already provides the primitive.
 
-## When something IS vendored
+## When something is vendored
 
-A package is added here **only** when a specific operation is confirmed missing
-from the engine floor (for example, a pure-JS fallback for a post-quantum
-operation whose JS binding is absent on a supported Node version, or a
-cross-check reference used only in tests). When that happens:
+A package is added here only when a specific operation is confirmed missing from
+the engine floor: for example a pure-JS fallback for a post-quantum operation
+whose JS binding is absent on a supported Node version, or a cross-check
+reference used only in tests. When that happens:
 
 - `MANIFEST.json` records the package's version, SPDX license, upstream author,
   source URL, exported surface, bundler invocation, CPE, and pinned SHA-256, so
   any tampering is detectable and `scripts/check-vendor-currency.js` can gate
   version drift.
 - The top-level `NOTICE` gains the component's attribution.
-- The reason and the re-open condition are recorded alongside the entry — a
-  vendored dependency is a deliberate, justified exception to native-first, not
-  a default.
+- The reason and the re-open condition are recorded alongside the entry. A
+  vendored dependency is a deliberate, justified exception to native-first
+  rather than a default.
 
 Bundles, when present, are produced with
 `esbuild --format=cjs --minify --platform=node` against the pinned upstream
-version; refreshing one recomputes its SHA-256 and updates the bytes and the
+version. Refreshing one recomputes its SHA-256 and updates the bytes and the
 matching `hashes.server` entry in the same change.