@blamejs/pki 0.4.14 → 0.5.0

package/lib/ct.js

@@ -173,6 +173,19 @@ function _parseSct(r, sctLen) {
  * `TypeError`.
  *
  * @example
+ *   // a certificate with an embedded SCT list, as a log would return it
+ *   var log = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var kp = await pki.key.generate("Ed25519");
+ *   var leaf = await pki.x509.sign({ subject: "example.org", subjectPublicKey: await pki.key.export(kp.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(kp.privateKey) });
+ *   var sct = await pki.ct.signSct({ entryType: 0, leafCert: leaf }, await pki.key.export(log.privateKey));
+ *   var sctExt = pki.asn1.build.sequence([pki.asn1.build.oid(pki.oid.byName("signedCertificateTimestampList")),
+ *     pki.asn1.build.octetString(pki.ct.encodeSctList([sct]))]);
+ *   var pem = await pki.x509.sign({ subject: "example.org", subjectPublicKey: await pki.key.export(kp.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: [sctExt] }, { key: await pki.key.export(kp.privateKey) }, { pem: true });
+ *
  *   var cert = pki.schema.x509.parse(pem);
  *   var sctOid = pki.oid.byName("signedCertificateTimestampList");
  *   var ext = (cert.extensions || []).find(function (e) { return e.oid === sctOid; });
@@ -252,6 +265,13 @@ function _u24Bytes(n) {
  * extensions exceed their RFC 6962 3.2 wire ranges (uint64 / opaque<0..2^16-1>).
  *
  * @example
+ *   var log = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var kp = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.org", subjectPublicKey: await pki.key.export(kp.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(kp.privateKey) });
+ *   var sctExtValue = pki.ct.encodeSctList([
+ *     await pki.ct.signSct({ entryType: 0, leafCert: der }, await pki.key.export(log.privateKey))]);
  *   var sct = pki.ct.parseSctList(sctExtValue).scts[0];
  *   var preimage = pki.ct.reconstructSignedData({ entryType: 0, leafCert: der }, sct);
  *   // hash `preimage` + verify against the log's public key at the verify layer
@@ -367,9 +387,17 @@ function _spkiAlg(spki) {
  * entry/SCT, an unusable log key, or an unsupported hash/signature algorithm.
  *
  * @example
+ *   var log = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var kp = await pki.key.generate("Ed25519");
+ *   var certDer = await pki.x509.sign({ subject: "example.org", subjectPublicKey: await pki.key.export(kp.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(kp.privateKey) });
+ *   var sctExtValue = pki.ct.encodeSctList([
+ *     await pki.ct.signSct({ entryType: 0, leafCert: certDer }, await pki.key.export(log.privateKey))]);
  *   var sct = pki.ct.parseSctList(sctExtValue).scts[0];
  *   // Resolve the CT log's DER SubjectPublicKeyInfo from a trusted log list, keyed by log id.
  *   var logKeysByLogId = {};                       // { sct.logIdHex: <SPKI Buffer>, ... }
+ *   logKeysByLogId[sct.logIdHex] = await pki.key.export(log.publicKey);
  *   var logKey = logKeysByLogId[sct.logIdHex];
  *   var ok = await pki.ct.verifySct({ entryType: 0, leafCert: certDer }, sct, logKey);
  */
@@ -480,6 +508,13 @@ function _encodeSctBody(sct) {
  * `ct/bad-input`, `ct/too-large`, `ct/too-many-scts`) on malformed input.
  *
  * @example
+ *   var log = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var kp = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.org", subjectPublicKey: await pki.key.export(kp.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(kp.privateKey) });
+ *   var sctExtValue = pki.ct.encodeSctList([
+ *     await pki.ct.signSct({ entryType: 0, leafCert: der }, await pki.key.export(log.privateKey))]);
  *   var list = pki.ct.parseSctList(sctExtValue);
  *   var reEncoded = pki.ct.encodeSctList(list.all);   // byte-identical to sctExtValue
  */
@@ -549,6 +584,12 @@ function _logKeyMaterial(logKey) {
  * @opts extensions  raw `CtExtensions` bytes (opaque<0..2^16-1>). Default empty.
  * @opts logId       assert the derived LogID equals this 32-byte value (fail closed on mismatch).
  * @example
+ *   var log = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var signerKeyPkcs8 = await pki.key.export(log.privateKey);
+ *   var kp = await pki.key.generate("Ed25519");
+ *   var der = await pki.x509.sign({ subject: "example.org", subjectPublicKey: await pki.key.export(kp.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(kp.privateKey) });
  *   var sct = await pki.ct.signSct({ entryType: 0, leafCert: der }, signerKeyPkcs8);
  *   var ext = pki.ct.encodeSctList([sct]);
  */
@@ -688,6 +729,14 @@ function _logsAgree(a, b) {
  * leniently, never a throw). Every malformed / oversized / mis-bound input is a typed `CtError`.
  *
  * @example
+ *   // the v3 log-list JSON shape, as published by a CT log-list operator
+ *   var log = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var logSpki = await pki.key.export(log.publicKey);
+ *   var logId = Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", logSpki));
+ *   var logListJsonBytes = Buffer.from(JSON.stringify({ operators: [{ name: "Example Operator", logs: [{
+ *     description: "Example Log", log_id: logId.toString("base64"), key: logSpki.toString("base64"),
+ *     url: "https://ct.example/log/", mmd: 86400,
+ *     state: { usable: { timestamp: "2026-01-01T00:00:00Z" } } }] }] }), "utf8");
  *   var logList = pki.ct.parseLogList(logListJsonBytes);
  *   logList.logs[0].trusted;   // was the first log trusted (usable/qualified/readonly)?
  */
@@ -770,6 +819,20 @@ function _resolveNotAfter(entry, opts) {
  *
  * @opts certNotAfter A `Date` -- the covered certificate's notAfter for the temporal-interval gate (required for a precert entry).
  * @example
+ *   var log = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var logSpki = await pki.key.export(log.publicKey);
+ *   var kp = await pki.key.generate("Ed25519");
+ *   var leafCert = await pki.x509.sign({ subject: "example.org", subjectPublicKey: await pki.key.export(kp.publicKey),
+ *     notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z") },
+ *     { key: await pki.key.export(kp.privateKey) });
+ *   var sctEntry = { entryType: 0, leafCert: leafCert };
+ *   var embeddedSct = pki.ct.parseSctList(pki.ct.encodeSctList([
+ *     await pki.ct.signSct(sctEntry, await pki.key.export(log.privateKey))])).scts[0];
+ *   var logId = Buffer.from(await pki.webcrypto.subtle.digest("SHA-256", logSpki));
+ *   var logList = pki.ct.parseLogList(Buffer.from(JSON.stringify({ operators: [{ name: "Example Operator", logs: [{
+ *     description: "Example Log", log_id: logId.toString("base64"), key: logSpki.toString("base64"),
+ *     url: "https://ct.example/log/", mmd: 86400,
+ *     state: { usable: { timestamp: "2026-01-01T00:00:00Z" } } }] }] }), "utf8"));
  *   var ok = await pki.ct.verifySctWithLogList(sctEntry, embeddedSct, logList);
  */
 async function verifySctWithLogList(entry, sct, logList, opts) {
@@ -818,6 +881,15 @@ async function verifySctWithLogList(entry, sct, logList, opts) {
  * evaluation failure is `ct/verify-error`. Offline: the caller fetches and pins; the toolkit only verifies.
  *
  * @example
+ *   var b = pki.asn1.build;
+ *   var signer = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var googleSignerSpki = await pki.key.export(signer.publicKey);
+ *   var logListJsonBytes = Buffer.from(JSON.stringify({ operators: [] }), "utf8");
+ *   // the published signature is DER SEQUENCE(r, s); WebCrypto emits the raw r||s pair
+ *   var raw = Buffer.from(await pki.webcrypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" },
+ *     signer.privateKey, logListJsonBytes));
+ *   var logListSig = b.sequence([b.integer(BigInt("0x" + raw.subarray(0, raw.length / 2).toString("hex"))),
+ *                                b.integer(BigInt("0x" + raw.subarray(raw.length / 2).toString("hex")))]);
  *   var ok = await pki.ct.verifyLogListSignature(logListJsonBytes, logListSig, googleSignerSpki);
  */
 async function verifyLogListSignature(json, signature, publicKey) {