@blamejs/pki 0.4.15 → 0.5.0

package/lib/schema-cmp.js

@@ -881,6 +881,14 @@ var PKI_MESSAGE = schema.seq([
  * `crmf/*` code -- all `PkiError` subclasses.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = await pki.x509.sign({ subject: "client", 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 csrDer = await pki.csr.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey) }, { key: key });
+ *   var der = await pki.cmp.build(
+ *     { header: { sender: { directoryName: "CN=client" }, recipient: { directoryName: "CN=CA" } },
+ *       body: { p10cr: csrDer } }, { key: key, cert: cert });
  *   var m = pki.schema.cmp.parse(der);
  *   m.body.arm;             // "ir", "ip", "error", ...
  *   m.header.transactionID; // raw Buffer or null
@@ -903,6 +911,15 @@ var parse = pkix.makeParser({
  * messages that transit text channels.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = await pki.x509.sign({ subject: "client", 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 csrDer = await pki.csr.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey) }, { key: key });
+ *   var msg = await pki.cmp.build(
+ *     { header: { sender: { directoryName: "CN=client" }, recipient: { directoryName: "CN=CA" } },
+ *       body: { p10cr: csrDer } }, { key: key, cert: cert });
+ *   var pemText = pki.schema.cmp.pemEncode(msg);
  *   var der = pki.schema.cmp.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || "CMP", PemError); }
@@ -918,6 +935,14 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "CMP", Pe
  * Wrap DER bytes in a PEM envelope (default label `CMP`).
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var cert = await pki.x509.sign({ subject: "client", 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 csrDer = await pki.csr.sign({ subject: "client", subjectPublicKey: await pki.key.export(pair.publicKey) }, { key: key });
+ *   var der = await pki.cmp.build(
+ *     { header: { sender: { directoryName: "CN=client" }, recipient: { directoryName: "CN=CA" } },
+ *       body: { p10cr: csrDer } }, { key: key, cert: cert });
  *   var pem = pki.schema.cmp.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "CMP", PemError); }

package/lib/schema-cms.js

@@ -1140,8 +1140,14 @@ var CONTENT_INFO = schema.seq([
  * `asn1/*`.
  *
  * @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),
+ *     serialNumber: 0x0a1bn, notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: key });
+ *   var der = await pki.cms.sign(Buffer.from("hello"), { cert: cert, key: key });
  *   var cms = pki.schema.cms.parse(der);
- *   cms.signerInfos[0].sid.serialNumberHex;   // -> "0a1b..."
+ *   cms.signerInfos[0].sid.serialNumberHex;   // -> "0a1b"
  *   cms.encapContentInfo.eContent;            // -> Buffer | null (detached)
  */
 var parse = pkix.makeParser({ pemLabel: "CMS", PemError: PemError, ErrorClass: CmsError, prefix: "cms", what: "CMS ContentInfo", topSchema: CONTENT_INFO, ns: NS });
@@ -1158,6 +1164,11 @@ var parse = pkix.makeParser({ pemLabel: "CMS", PemError: PemError, ErrorClass: C
  * `PemError` on a missing / mismatched envelope or a non-base64 body.
  *
  * @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 pemText = await pki.cms.sign(Buffer.from("hello"), { cert: cert, key: key }, { pem: true });
  *   var der = pki.schema.cms.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || "CMS", PemError); }
@@ -1173,6 +1184,11 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "CMS", Pe
  * Wrap DER bytes in a PEM CMS envelope (default label `CMS`).
  *
  * @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 der = await pki.cms.sign(Buffer.from("hello"), { cert: cert, key: key });
  *   var pem = pki.schema.cms.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "CMS", PemError); }

package/lib/schema-crl.js

@@ -206,8 +206,16 @@ var CERTIFICATE_LIST = pkix.signedEnvelope(NS, TBS_CERTLIST, {
  * typed `CrlError` (`crl/*`) and a leaf-level codec fault surfaces as `asn1/*`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var caCert = await pki.x509.sign({ subject: "Issuing CA", 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: key });
+ *   var der = await pki.crl.sign({ thisUpdate: new Date("2026-01-01T00:00:00Z"), crlNumber: 1n,
+ *     revoked: [{ serialNumber: 0x0a3fn, revocationDate: new Date("2026-01-15T00:00:00Z") }] },
+ *     { cert: caCert, key: key });
  *   var crl = pki.schema.crl.parse(der);
- *   crl.revokedCertificates[0].serialNumberHex;  // -> "0a3f..."
+ *   crl.revokedCertificates[0].serialNumberHex;  // -> "0a3f"
  */
 var parse = pkix.makeParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorClass: CrlError, prefix: "crl", what: "CRL", topSchema: CERTIFICATE_LIST, ns: NS });
 
@@ -223,6 +231,13 @@ var parse = pkix.makeParser({ pemLabel: "X509 CRL", PemError: PemError, ErrorCla
  * `PemError` on a missing / mismatched envelope or a non-base64 body.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var caCert = await pki.x509.sign({ subject: "Issuing CA", 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: ["cRLSign"] } }, { key: key });
+ *   var pemText = await pki.crl.sign({ thisUpdate: new Date("2026-01-01T00:00:00Z"), crlNumber: 1n, revoked: [] },
+ *     { cert: caCert, key: key }, { pem: true });
  *   var der = pki.schema.crl.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || "X509 CRL", PemError); }
@@ -239,6 +254,13 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "X509 CRL
  * label `X509 CRL`, the RFC 7468 sec. 6 armor `pemDecode` expects back).
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var caCert = await pki.x509.sign({ subject: "Issuing CA", 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: ["cRLSign"] } }, { key: key });
+ *   var der = await pki.crl.sign({ thisUpdate: new Date("2026-01-01T00:00:00Z"), crlNumber: 1n, revoked: [] },
+ *     { cert: caCert, key: key });
  *   var pem = pki.schema.crl.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "X509 CRL", PemError); }

package/lib/schema-crmf.js

@@ -482,6 +482,10 @@ var CERT_REQ_MESSAGES = schema.seqOf(CERT_REQ_MSG, {
  * `Asn1Error` when the underlying DER is malformed.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.crmf.build(
+ *     { certReqId: 0, certTemplate: { subject: "req.example", publicKey: await pki.key.export(pair.publicKey) } },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var m = pki.schema.crmf.parse(der);
  *   m.messages[0].certReq.certTemplate.subject.dn;   // "CN=req.example"
  */
@@ -503,6 +507,11 @@ var parse = pkix.makeParser({
  * DER in practice). Throws `PemError` on a missing envelope or a non-base64 body.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var msg = await pki.crmf.build(
+ *     { certReqId: 0, certTemplate: { subject: "req.example", publicKey: await pki.key.export(pair.publicKey) } },
+ *     { key: await pki.key.export(pair.privateKey) });
+ *   var pemText = pki.schema.crmf.pemEncode(msg, "CERT REQUEST MESSAGES");
  *   var der = pki.schema.crmf.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || null, PemError); }
@@ -520,6 +529,10 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || null, Pem
  * `pemDecode`, which accepts any label). Omitting it throws `pem/bad-label`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.crmf.build(
+ *     { certReqId: 0, certTemplate: { subject: "req.example", publicKey: await pki.key.export(pair.publicKey) } },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var pem = pki.schema.crmf.pemEncode(der, "CERT REQUEST MESSAGES");
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }

package/lib/schema-csr.js

@@ -176,6 +176,11 @@ var CERTIFICATION_REQUEST = pkix.signedEnvelope(NS, CERTIFICATION_REQUEST_INFO,
  * certificate's extensions use).
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.csr.sign(
+ *     { subject: "req.example", subjectPublicKey: await pki.key.export(pair.publicKey),
+ *       extensionRequest: { subjectAltName: [{ dNSName: "req.example" }] } },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var csr = pki.schema.csr.parse(der);
  *   csr.subject.dn;             // -> "CN=req.example"
  *   csr.attributes[0].type;     // -> "1.2.840.113549.1.9.14"
@@ -195,6 +200,9 @@ var parse = pkix.makeParser({ pemLabel: "CERTIFICATE REQUEST", PemError: PemErro
  * body.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemText = await pki.csr.sign({ subject: "req.example", subjectPublicKey: await pki.key.export(pair.publicKey) },
+ *     { key: await pki.key.export(pair.privateKey) }, { pem: true });
  *   var der = pki.schema.csr.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || "CERTIFICATE REQUEST", PemError); }
@@ -210,6 +218,9 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "CERTIFIC
  * Wrap DER bytes in a PEM CSR envelope (default label `CERTIFICATE REQUEST`).
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.csr.sign({ subject: "req.example", subjectPublicKey: await pki.key.export(pair.publicKey) },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var pem = pki.schema.csr.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "CERTIFICATE REQUEST", PemError); }

package/lib/schema-csrattrs.js

@@ -335,6 +335,12 @@ var CSR_ATTRS = schema.seqOf(ATTR_OR_OID, {
  * (`csrattrs/*`) and a leaf-level codec fault surfaces as `asn1/*`.
  *
  * @example
+ *   // a CsrAttrs carrying one bare OID (challengePassword) and one Attribute
+ *   var b = pki.asn1.build;
+ *   var der = b.sequence([
+ *     b.oid("1.2.840.113549.1.9.7"),
+ *     b.sequence([b.oid("1.2.840.113549.1.1.1"), b.set([b.integer(2048n)])]),
+ *   ]);
  *   var a = pki.schema.csrattrs.parse(der);
  *   a.items[0].kind;   // -> "oid" | "attribute"
  */

package/lib/schema-engine.js

@@ -271,6 +271,9 @@ function implicitSeqOf(tag, item, opts) {
  *
  * @example
  *   var S = pki.schema.engine;
+ *   // `E` is an error FACTORY (called without `new`), so a domain can raise its own type
+ *   var MyError = function (code, msg) { var e = new Error(msg); e.code = code; return e; };
+ *   var der = pki.asn1.build.sequence([pki.asn1.build.oid("1.3.101.112")]);
  *   var ALGID = S.seq([S.field("algorithm", S.oidLeaf())],
  *     { assert: "sequence", arity: { min: 1 }, code: "app/bad-alg" });
  *   S.walk(ALGID, pki.asn1.decode(der), { prefix: "app", E: MyError, oid: pki.oid });
@@ -466,7 +469,7 @@ function _encFail(message) { throw new Error("schema.encode: " + message); }
  * @primitive  pki.schema.engine.encode
  * @signature  pki.schema.engine.encode(schema, value, ctx) -> Buffer
  * @since      0.1.17
- * @status     experimental
+ * @status     stable
  * @spec       X.690, X.680
  * @related    pki.schema.engine.walk
  *
@@ -589,7 +592,7 @@ function _encodeChoice(schema, value, ctx) {
  * @primitive  pki.schema.engine.embeddedDer
  * @signature  pki.schema.engine.embeddedDer(schema, bytes, ctx, opts?) -> value
  * @since      0.1.18
- * @status     experimental
+ * @status     stable
  * @spec       X.690
  * @defends    ASN.1-parser-DoS (CWE-400)
  * @related    pki.schema.engine.walk, pki.asn1.decode
@@ -613,6 +616,7 @@ function _encodeChoice(schema, value, ctx) {
  *
  * @example
  *   var S = pki.schema.engine;
+ *   var MyError = function (code, msg) { var e = new Error(msg); e.code = code; return e; };
  *   var INNER = S.seq([S.field("version", S.integerLeaf())], { code: "app/bad-inner" });
  *   var ns = { prefix: "app", E: MyError, oid: pki.oid };
  *   S.embeddedDer(INNER, pki.asn1.build.sequence([pki.asn1.build.integer(3n)]), ns,

package/lib/schema-ocsp.js

@@ -469,6 +469,16 @@ var OCSP_REQUEST = schema.seq([
  * `asn1/*`.
  *
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", 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"], subjectKeyIdentifier: true } }, { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = await pki.x509.sign({ subject: "leaf.example", subjectPublicKey: await pki.key.export(leaf.publicKey),
+ *     serialNumber: 0x1332n, notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { cert: caDer, key: caKey });
+ *   var der = await pki.ocsp.buildRequest({ cert: leafDer, issuer: caDer }, {});
  *   var req = pki.schema.ocsp.parseRequest(der);
  *   req.requestList[0].certID.serialNumberHex;   // -> "1332"
  */
@@ -492,6 +502,17 @@ var parseRequest = pkix.makeParser({ pemLabel: "OCSP REQUEST", PemError: PemErro
  * `ocsp/unsupported-response-type`.
  *
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", 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"], subjectKeyIdentifier: true } }, { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = 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") },
+ *     { cert: caDer, key: caKey });
+ *   var der = await pki.ocsp.sign({ responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
+ *     { cert: caDer, key: caKey });
  *   var res = pki.schema.ocsp.parseResponse(der);
  *   res.responseStatus.name;                       // -> "successful"
  *   res.basicResponse.responses[0].certStatus.type; // -> "good" | "revoked" | "unknown"
@@ -511,6 +532,16 @@ var parseResponse = pkix.makeParser({ pemLabel: "OCSP RESPONSE", PemError: PemEr
  * envelope or a non-base64 body.
  *
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", 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"], subjectKeyIdentifier: true } }, { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = 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") }, { cert: caDer, key: caKey });
+ *   var reqDer = await pki.ocsp.buildRequest({ cert: leafDer, issuer: caDer }, {});
+ *   var pemText = pki.schema.ocsp.pemEncode(reqDer, "OCSP REQUEST");
  *   var der = pki.schema.ocsp.pemDecode(pemText, "OCSP REQUEST");
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || "OCSP RESPONSE", PemError); }
@@ -528,6 +559,16 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "OCSP RES
  * `PemError` on a malformed label.
  *
  * @example
+ *   var ca = await pki.key.generate("Ed25519");
+ *   var caKey = await pki.key.export(ca.privateKey);
+ *   var caDer = await pki.x509.sign({ subject: "Example CA", 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"], subjectKeyIdentifier: true } }, { key: caKey });
+ *   var leaf = await pki.key.generate("Ed25519");
+ *   var leafDer = 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") }, { cert: caDer, key: caKey });
+ *   var der = await pki.ocsp.sign({ responderID: "byName", responses: [{ cert: leafDer, issuer: caDer, status: "good" }] },
+ *     { cert: caDer, key: caKey });
  *   var pem = pki.schema.ocsp.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "OCSP RESPONSE", PemError); }

package/lib/schema-pkcs12.js

@@ -515,6 +515,11 @@ function _buildBag(rec, state, ctx) {
  * (`pkcs8/*`) -- all `PkiError` subclasses.
  *
  * @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 der = await pki.pkcs12.build({ key: key, cert: cert }, { password: "changeit" });
  *   var store = pki.schema.pkcs12.parse(der);
  *   store.safeBags.map(function (b) { return b.type; });
  */
@@ -536,6 +541,12 @@ var parse = pkix.makeParser({
  * convenience for stores that transit text channels.
  *
  * @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 p12 = await pki.pkcs12.build({ key: key, cert: cert }, { password: "changeit" });
+ *   var pemText = pki.schema.pkcs12.pemEncode(p12);
  *   var der = pki.schema.pkcs12.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || "PKCS12", PemError); }
@@ -551,6 +562,11 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "PKCS12",
  * Wrap DER bytes in a PEM envelope (default label `PKCS12`).
  *
  * @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 der = await pki.pkcs12.build({ key: key, cert: cert }, { password: "changeit" });
  *   var pem = pki.schema.pkcs12.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "PKCS12", PemError); }

package/lib/schema-pkcs8.js

@@ -114,6 +114,8 @@ var ENCRYPTED_PRIVATE_KEY_INFO = schema.seq([
  * and a leaf-level codec fault surfaces as `asn1/*`.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.key.export(pair.privateKey);
  *   var key = pki.schema.pkcs8.parse(der);
  *   key.privateKeyAlgorithm.oid;   // -> "1.3.101.112" (Ed25519)
  *   key.privateKey;                // -> Buffer (the inner key encoding)
@@ -134,6 +136,8 @@ var parse = pkix.makeParser({ pemLabel: "PRIVATE KEY", PemError: PemError, Error
  * separate concern from structural validation.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.key.encrypt(await pki.key.export(pair.privateKey), "s3cr3t");
  *   var enc = pki.schema.pkcs8.parseEncrypted(der);
  *   enc.encryptionAlgorithm.oid;   // -> "1.2.840.113549.1.5.13" (PBES2)
  */
@@ -152,6 +156,8 @@ var parseEncrypted = pkix.makeParser({ pemLabel: "ENCRYPTED PRIVATE KEY", PemErr
  * body.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemText = await pki.key.export(pair.privateKey, { format: "pem" });
  *   var der = pki.schema.pkcs8.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label || "PRIVATE KEY", PemError); }
@@ -167,6 +173,8 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "PRIVATE
  * Wrap DER bytes in a PEM private-key envelope (default label `PRIVATE KEY`).
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = await pki.key.export(pair.privateKey);
  *   var pem = pki.schema.pkcs8.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "PRIVATE KEY", PemError); }

package/lib/schema-smime.js

@@ -237,7 +237,7 @@ var SMIME_CAPABILITIES = schema.seqOf(SMIME_CAPABILITY, {
  * @primitive  pki.schema.smime.parseSigningCertificate
  * @signature  pki.schema.smime.parseSigningCertificate(der) -> { certs, policies }
  * @since      0.1.22
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5035, RFC 2634
  * @related    pki.schema.smime.parseSigningCertificateV2, pki.schema.smime.decodeAttribute
  *
@@ -262,7 +262,7 @@ var parseSigningCertificate = pkix.makeParser({ pemLabel: null, PemError: PemErr
  * @primitive  pki.schema.smime.parseSigningCertificateV2
  * @signature  pki.schema.smime.parseSigningCertificateV2(der) -> { certs, policies }
  * @since      0.1.22
- * @status     experimental
+ * @status     stable
  * @spec       RFC 5035, RFC 5816
  * @related    pki.schema.smime.parseSigningCertificate, pki.schema.smime.decodeAttribute
  *
@@ -286,7 +286,7 @@ var parseSigningCertificateV2 = pkix.makeParser({ pemLabel: null, PemError: PemE
  * @primitive  pki.schema.smime.parseSmimeCapabilities
  * @signature  pki.schema.smime.parseSmimeCapabilities(der) -> { capabilities }
  * @since      0.1.22
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8551
  * @related    pki.schema.smime.decodeAttribute
  *
@@ -308,7 +308,7 @@ var parseSmimeCapabilities = pkix.makeParser({ pemLabel: null, PemError: PemErro
  * @primitive  pki.schema.smime.decodeAttribute
  * @signature  pki.schema.smime.decodeAttribute(attr) -> { kind, ... }
  * @since      0.1.22
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8551, RFC 5035
  * @related    pki.schema.smime.parseSigningCertificate, pki.schema.cms.parse
  *

package/lib/schema-tsp.js

@@ -313,7 +313,7 @@ var TIME_STAMP_REQ = schema.seq([
  * @primitive  pki.schema.tsp.parseRequest
  * @signature  pki.schema.tsp.parseRequest(input) -> timeStampReq
  * @since      0.2.19
- * @status     experimental
+ * @status     stable
  * @spec       RFC 3161
  * @related    pki.schema.tsp.parse, pki.tsp.request
  *
@@ -324,6 +324,8 @@ var TIME_STAMP_REQ = schema.seq([
  * is the raw digest. 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.schema.tsp.parseRequest(der);
  *   req.certReq;                        // -> boolean
  *   req.messageImprint.hashedMessage;   // -> Buffer (the raw digest)
@@ -346,6 +348,15 @@ var parseRequest = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorCl
  * `TspError` (`tsp/*`); a leaf-level codec fault surfaces as `asn1/*`.
  *
  * @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.schema.tsp.parseToken(token).eContent;   // the raw TSTInfo the TSA signed
  *   var tst = pki.schema.tsp.parseTstInfo(der);
  *   tst.genTime;                       // -> Date
  *   tst.messageImprint.hashedMessage;  // -> Buffer (the raw digest)
@@ -367,6 +378,15 @@ var parseTstInfo = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorCl
  * `PKIFailureInfo` named bits. A malformed structure throws a typed `TspError`.
  *
  * @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 res = pki.schema.tsp.parse(der);
  *   res.status;                              // -> 0 (granted)
  *   res.timeStampToken.tstInfo.genTime;      // -> Date (a granted token is decoded)
@@ -394,6 +414,14 @@ var parse = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: Ts
  * material.
  *
  * @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 tokenDer = 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 token = pki.schema.tsp.parseToken(tokenDer);
  *   token.tstInfo.genTime;   // -> Date
  *   token.signerInfo.sid;    // -> the TSA signer identifier
@@ -466,6 +494,8 @@ function parseToken(input) {
  * envelope or a non-base64 body.
  *
  * @example
+ *   var req = pki.tsp.request({ hashAlgorithm: "sha256", hashedMessage: Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello"))) }, {});
+ *   var pemText = pki.schema.tsp.pemEncode(req, "TSP REQUEST");
  *   var der = pki.schema.tsp.pemDecode(pemText);
  */
 // Decode a raw GeneralName TLV (the tsa field and the ESS issuerSerial issuer are surfaced raw) into
@@ -490,6 +520,7 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || null, Pem
  * `pemDecode`, which accepts any label). Omitting it throws `pem/bad-label`.
  *
  * @example
+ *   var der = pki.tsp.request({ hashAlgorithm: "sha256", hashedMessage: Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", Buffer.from("hello"))) }, {});
  *   var pem = pki.schema.tsp.pemEncode(der, "TSP RESPONSE");
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }

package/lib/schema-x509.js

@@ -55,6 +55,10 @@ var PemError = frameworkError.PemError;
  * missing / mismatched envelope or a non-base64 body.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemText = 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) }, { pem: true });
  *   var der = pki.schema.x509.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? null : (label || "CERTIFICATE"), PemError); }
@@ -70,6 +74,10 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? n
  * Wrap DER bytes in a PEM envelope with 64-column base64 lines.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = 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 pem = pki.schema.x509.pemEncode(der, "CERTIFICATE");
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label, PemError); }
@@ -213,10 +221,15 @@ var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
  * certificate and `Asn1Error` when the underlying DER is malformed.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var pemString = await pki.x509.sign({ subject: [{ commonName: "example.com" }, { organizationName: "Example" }],
+ *     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) }, { pem: true });
  *   var cert = pki.schema.x509.parse(pemString);
  *   cert.subject.dn;                 // "CN=example.com, O=Example"
  *   cert.validity.notAfter;          // Date
- *   cert.signatureAlgorithm.name;    // "sha256WithRSAEncryption"
+ *   cert.signatureAlgorithm.name;    // "Ed25519" (the algorithm the issuer signed with)
  */
 var parse = pkix.makeParser({ pemLabel: "CERTIFICATE", PemError: PemError, ErrorClass: CertificateError, prefix: "x509", what: "certificate", topSchema: CERTIFICATE, ns: NS });
 

package/lib/shbs.js

@@ -300,7 +300,7 @@ function _asBytes(x, label) { return guard.bytes.source(x, ShbsError, "shbs/bad-
  * @primitive pki.shbs.verify
  * @signature pki.shbs.verify(publicKey, message, signature) -> boolean
  * @since 0.2.1
- * @status experimental
+ * @status stable
  * @spec RFC 8554 sec. 6, RFC 9802, RFC 9708
  * @related pki.shbs.verifyLms
  *
@@ -315,6 +315,12 @@ function _asBytes(x, label) { return guard.bytes.source(x, ShbsError, "shbs/bad-
  * typed `ShbsError`. VERIFY ONLY -- this module never signs.
  *
  * @example
+ *   // throws: shbs/bad-public-key -- an Ed25519 key is not an HSS public key, and
+ *   // the verifier fails closed on the wrong key type rather than returning true
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var der = 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 cert = pki.schema.x509.parse(der);
  *   var ok = pki.shbs.verify(cert.subjectPublicKeyInfo.publicKey.bytes,
  *                            cert.tbsBytes, cert.signatureValue.bytes);
@@ -327,7 +333,7 @@ function verify(publicKey, message, signature) {
  * @primitive pki.shbs.verifyLms
  * @signature pki.shbs.verifyLms(publicKey, message, signature) -> boolean
  * @since 0.2.1
- * @status experimental
+ * @status stable
  * @spec RFC 8554 sec. 5
  * @related pki.shbs.verify
  *
@@ -337,8 +343,10 @@ function verify(publicKey, message, signature) {
  * a well-formed signature, a typed `ShbsError` for a malformed blob.
  *
  * @example
- *   // lmsPublicKey / lmsSignature are raw LMS blobs (an HSS level, or a bare
- *   // LMS-signed artifact). Shown here on arbitrary bytes, which fail closed.
+ *   // throws: shbs/unsupported-parameter-set -- lmsPublicKey / lmsSignature are raw
+ *   // LMS blobs (an HSS level, or a bare LMS-signed artifact); arbitrary bytes carry
+ *   // no recognized LMS typecode, so the verifier refuses them instead of returning
+ *   var bytes = Buffer.alloc(64);
  *   var ok = pki.shbs.verifyLms(bytes, bytes, bytes);
  */
 function verifyLms(publicKey, message, signature) {

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"
  */
@@ -571,6 +573,8 @@ function _statement(payload, payloadType, expectedPredicate) {
  *   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