@blamejs/pki 0.4.15 → 0.5.1

package/lib/sigstore.js

@@ -117,6 +117,8 @@ function _b64(s, label) {
  * bundle object (structure only -- no cryptographic verification).
  *
  * @example
+ *   // requires: `bundle` -- a Sigstore bundle as cosign or npm provenance emits it
+ *   // (the JSON object, a JSON string, or its raw bytes)
  *   var b = pki.sigstore.parseBundle(bundle);
  *   b.mediaType; // "application/vnd.dev.sigstore.bundle.v0.3+json"
  */
@@ -514,14 +516,54 @@ function _fulcioExtValue(ext, leafArc) {
   return asn1.read.string(asn1.decode(ext.value));
 }
 
+// The fields an identity policy may constrain. Named once so the check, the refusal of an
+// unknown key, and the report of what ran cannot drift apart.
+var IDENTITY_FIELDS = ["san", "issuer", "sourceRepositoryURI"];
+// The guard tests membership with hasOwnProperty, so the permitted set is a lookup object --
+// an array would treat "0"/"1" as the known keys and reject every real field name.
+var IDENTITY_KEYS = { san: 1, issuer: 1, sourceRepositoryURI: 1 };
+
+// Returns WHICH fields were actually compared. A bundle verifies its own signature and log
+// inclusion whoever signed it -- Fulcio issues to anyone who completes an OIDC flow -- so
+// `verified: true` without an identity policy says the artifact was signed and logged, not that
+// a trusted party signed it. The caller cannot tell those apart from a bare boolean.
 function _checkIdentity(id, policy) {
-  if (!policy) return;
+  var ran = { san: false, issuer: false, sourceRepositoryURI: false };
+  if (policy === undefined || policy === null) return ran;
+  if (typeof policy !== "object" || Array.isArray(policy)) {
+    throw _err("sigstore/bad-input", "opts.identity must be an object naming the identity fields to pin (" + IDENTITY_FIELDS.join(", ") + ")");
+  }
+  // An unknown key is refused, not ignored: cosign spells this `certificateIdentity`, and a
+  // swallowed spelling checks nothing under a name the operator believes pins the signer.
+  // The guard rejects through a (code, message) FACTORY. Handing it the error CLASS raises
+  // "class constructor cannot be invoked without new" -- a raw, untyped throw escaping a public
+  // verb, on the branch a valid-input test never takes.
+  guard.identifier.assertKnownKeys(policy, IDENTITY_KEYS, _err, "sigstore/bad-input", "opts.identity has an unknown key ");
+  // A policy that constrains NOTHING is a configuration mistake, and the most dangerous input on
+  // this surface: every guard below is falsy, so it accepts every signer while reading as though
+  // an identity policy is in force. Refused at the boundary rather than answered.
+  var asked = IDENTITY_FIELDS.filter(function (f) { return policy[f] !== undefined; });
+  if (!asked.length) {
+    throw _err("sigstore/bad-input", "opts.identity constrains nothing -- name at least one of " + IDENTITY_FIELDS.join(", ") + ", or omit it to state that the signer is not being checked");
+  }
+  // A named field must carry a value that can actually be compared. The comparisons below are
+  // truthiness-guarded, so an empty string or a null would be skipped while the field had been
+  // named -- reporting a signer check that never ran, which is the exact confusion this report
+  // exists to remove. Deciding "asked" and deciding "compared" must be the SAME test, so a value
+  // that cannot be compared is refused here rather than quietly becoming "not asked".
+  asked.forEach(function (f) {
+    if (typeof policy[f] !== "string" || policy[f] === "") {
+      throw _err("sigstore/bad-input", "opts.identity." + f + " must be a non-empty string -- a value that cannot be compared would leave the signer unchecked under a policy that names it");
+    }
+    ran[f] = true;
+  });
   var sanValue = id.san && id.san.value;
   if (policy.san && sanValue !== policy.san) throw _err("sigstore/identity-mismatch", "the certificate SAN " + JSON.stringify(sanValue) + " does not match the expected identity");
   // The OIDC issuer is carried by the current Issuer V2 (.1.8) or, on older certs,
   // only by the deprecated raw-string issuer (.1.1); match against either.
   if (policy.issuer && policy.issuer !== id.extensions.issuer && policy.issuer !== id.extensions.issuerLegacy) throw _err("sigstore/identity-mismatch", "the certificate OIDC issuer does not match the expected issuer");
   if (policy.sourceRepositoryURI && id.extensions.sourceRepositoryURI !== policy.sourceRepositoryURI) throw _err("sigstore/identity-mismatch", "the certificate source-repository URI does not match");
+  return ran;
 }
 
 // ---- in-toto Statement leg ---------------------------------------------------
@@ -559,18 +601,29 @@ function _statement(payload, payloadType, expectedPredicate) {
  * the log entry bound to this exact signature; and the in-toto SLSA statement.
  * Any leg failing throws a typed `sigstore/*` error. On success returns
  * `{ verified: true, payload, statement, subjects, predicateType, predicate,
- * identity, integratedTime }` -- `payload` is the RAW verified envelope bytes
- * (never a re-serialization), and the caller confirms a `subjects[].digest`
- * matches the published artifact.
+ * identity, identityChecked, integratedTime }` -- `payload` is the RAW verified
+ * envelope bytes (never a re-serialization), and the caller confirms a
+ * `subjects[].digest` matches the published artifact.
+ *
+ * `verified: true` says the artifact was signed and logged -- not that a party you
+ * trust signed it. Fulcio issues a certificate to anyone who completes an OIDC
+ * flow, so WHO signed is decided only by `opts.identity`, and `identityChecked`
+ * reports which of its fields were compared (`{ san, issuer, sourceRepositoryURI }`,
+ * each a boolean). An `identity` naming none of them is refused rather than
+ * satisfied, since it would accept every signer while reading as a policy; so is an
+ * unrecognized field name, which would otherwise pin nothing under a spelling the
+ * operator believes constrains the signer.
  *
  * @opts
  *   fulcioRoots:   Array,      // the Fulcio CA anchors: a DER Buffer or { der, validFor } each
  *   rekorKeys:     Array,      // [{ keyId, spki, validFor? }] the Rekor log public keys
- *   identity:      object,     // optional policy: { san, issuer, sourceRepositoryURI }
+ *   identity:      object,     // optional policy: { san, issuer, sourceRepositoryURI }; at least one required when present
  *   predicateType: string,     // optional: require this in-toto predicateType (e.g. the SLSA URI)
  *   time:          Date,       // optional check-date override (default: the Rekor integratedTime)
  *
  * @example
+ *   // requires: `bundle` from cosign / npm provenance, and `sigstoreTrust` built from
+ *   // the public-good trusted_root.json (the Fulcio + Rekor material it pins)
  *   var out = await pki.sigstore.verifyBundle(bundle, sigstoreTrust);
  *   out.verified;            // true
  *   out.subjects[0].digest;  // { sha512: "..." } -- confirm against your tarball
@@ -612,7 +665,7 @@ async function verifyBundle(bundle, opts) {
   var checkTime = (opts.time instanceof Date) ? opts.time.getTime() : C.TIME.seconds(integratedTime);
   await _verifyChain(leaf, _chainDers(vm), fulcioRoots, checkTime);
   var identity = _identity(leaf);
-  _checkIdentity(identity, opts.identity);
+  var identityChecked = _checkIdentity(identity, opts.identity);
 
   // Leg 4 -- the in-toto SLSA statement + subject binding (with an optional
   // caller-pinned predicateType).
@@ -626,6 +679,9 @@ async function verifyBundle(bundle, opts) {
     predicateType: st.predicateType,
     predicate: st.predicate,
     identity: identity,
+    // Which identity fields were actually compared. `verified` says the artifact was signed and
+    // logged; only these say a signer the caller named was the one who signed it.
+    identityChecked: identityChecked,
     integratedTime: integratedTime,
   };
 }

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.