@blamejs/pki 0.4.14 → 0.5.0

package/lib/pkcs12-build.js

@@ -469,6 +469,10 @@ function _normalizeSpec(spec, opts) {
  *   - `recipientCerts` -- (public-key privacy convenience) `[certDer|PEM, ...]`; the convenience-form cert + key are placed in one recipient-enveloped safe (a plaintext keyBag). For the full form, set per-`safeContents` `recipients: [{ cert }, ...]` -- CERTIFICATE recipients only (RSA-OAEP / ECDH / X25519 / X448 / ML-KEM, dispatched off the cert key); a password or KEK recipient is not public-key privacy and is rejected -- with an optional `contentEncryptionAlgorithm` (`aes-128|192|256-cbc`, default 256; GCM/AEAD rejected). `encrypt` (password) and `recipients` (public-key) on the same safe is rejected; privacy is independent of integrity.
  *   - `pem` (boolean) -- return a PEM `PKCS12` string instead of DER.
  * @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 p12 = await pki.pkcs12.build({ safeContents: [{ bags: [
  *     { type: 'cert', cert: signerCertDer },
  *     { type: 'shroudedKey', key: signerKeyPkcs8, encrypt: { password: 'changeit' } } ] }] },
@@ -526,6 +530,10 @@ async function build(spec, opts) {
  * or public-key-integrity store, or an unsupported MAC algorithm (never a falsy verdict standing in for an error).
  *
  * @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 p12 = await pki.pkcs12.build({ key: signerKeyPkcs8, cert: signerCertDer }, { password: 'changeit' });
  *   var ok = await pki.pkcs12.verifyMac(p12, 'changeit');
  */
@@ -614,6 +622,10 @@ function _capWork(iterations, salt, opts, keyLength, hardCap) {
  *   - `keys` (string) -- `der` (default) or `crypto` (also `pki.key.import` each private key to a CryptoKey).
  *   - `importAlgorithm` -- forwarded to `pki.key.import` for the ambiguous RSA / EC arms when `keys: crypto`.
  * @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 p12 = await pki.pkcs12.build({ key: signerKeyPkcs8, cert: signerCertDer }, { password: 'changeit' });
  *   var store = await pki.pkcs12.open(p12, 'changeit');
  *   var keyDer = store.keys[0].pkcs8, certDer = store.certs[0].cert;

package/lib/schema-all.js

@@ -50,6 +50,15 @@ var attrcert = require("./schema-attrcert");
 // SEQUENCE) so it is deliberately absent from FORMATS / the detect-and-route
 // `parse`; it is reached only by explicit OID dispatch on a CMS attribute.
 var smime = require("./schema-smime");
+// cmc is likewise a COMPANION decoder, for the same reason arrived at from the
+// other direction: a CMC message's outer DER root IS a CMS ContentInfo, which
+// `cms.matches` already claims below. A `cmc` FORMATS row would either shadow CMS
+// or be shadowed by it, and there is no structurally disjoint root to detect --
+// the discriminator is the encapsulated content type, one layer in. So it is
+// reached by explicit call, or by dispatching on
+// `pki.schema.cms.parse(der).encapContentInfo.eContentType`, and exports no
+// `matches` for nobody to call.
+var cmc = require("./schema-cmc");
 var frameworkError = require("./framework-error");
 
 var SchemaError = frameworkError.SchemaError;
@@ -276,6 +285,10 @@ function all() { return FORMATS.map(function (f) { return f.name; }); }
  * errors of the matched format propagate unchanged.
  *
  * @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 parsed = pki.schema.parse(der);  // cert -> the pki.schema.x509 shape
  */
 function parse(input) {
@@ -294,7 +307,7 @@ function parse(input) {
  * @primitive  pki.schema.detectFormat
  * @signature  pki.schema.detectFormat(input) -> string | null
  * @since       0.3.8
- * @status      experimental
+ * @status      stable
  * @spec        RFC 5280
  * @related     pki.schema.parse, pki.schema.all
  *
@@ -307,6 +320,10 @@ function parse(input) {
  * same coercion / decode error `parse` throws.
  *
  * @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) });
  *   pki.schema.detectFormat(der);  // "x509" | "crl" | "csr" | "cms" | ... | null
  */
 function detectFormat(input) {
@@ -339,6 +356,7 @@ module.exports = {
   csrattrs: { parse: csrattrs.parse },
   attrcert: { parse: attrcert.parse, pemDecode: attrcert.pemDecode, pemEncode: attrcert.pemEncode },
   smime: { parseSigningCertificate: smime.parseSigningCertificate, parseSigningCertificateV2: smime.parseSigningCertificateV2, parseSmimeCapabilities: smime.parseSmimeCapabilities, decodeAttribute: smime.decodeAttribute },
+  cmc: { parse: cmc.parse, parsePkiData: cmc.parsePkiData, parsePkiResponse: cmc.parsePkiResponse },
   all: all,
   parse: parse,
   detectFormat: detectFormat,

package/lib/schema-attrcert.js

@@ -340,6 +340,15 @@ var ATTRIBUTE_CERTIFICATE = pkix.signedEnvelope(NS, ACINFO, {
  * and `Asn1Error` when the underlying DER is malformed.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var aaCert = await pki.x509.sign({ subject: "Attribute Authority", 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.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key });
  *   var ac = pki.schema.attrcert.parse(der);
  *   ac.attributes[0].name;   // "role"
  *   ac.validity.notAfterTime;// Date
@@ -383,6 +392,15 @@ function parseV1(input) {
  * `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 aaCert = await pki.x509.sign({ subject: "Attribute Authority", 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.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key }, { pem: true });
  *   var der = pki.schema.attrcert.pemDecode(pemText);
  */
 function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? null : (label || "ATTRIBUTE CERTIFICATE"), PemError); }
@@ -399,6 +417,15 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? n
  * same default `pemDecode` reads). Throws `PemError` on a malformed label.
  *
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var key = await pki.key.export(pair.privateKey);
+ *   var aaCert = await pki.x509.sign({ subject: "Attribute Authority", 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.attrcert.sign(
+ *     { holder: { entityName: { directoryName: "CN=Alice" } },
+ *       notBeforeTime: new Date("2026-01-01T00:00:00Z"), notAfterTime: new Date("2027-01-01T00:00:00Z"),
+ *       attributes: { role: { roleName: { uniformResourceIdentifier: "urn:role:admin" } } } },
+ *     { cert: aaCert, key: key });
  *   var pem = pki.schema.attrcert.pemEncode(der);
  */
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "ATTRIBUTE CERTIFICATE", PemError); }

package/lib/schema-c509.js

@@ -2327,6 +2327,12 @@ function _encodeC509Array(r) {
  *     only for the DER -> type-3 path; ignored when re-emitting a parse result.
  *
  * @example
+ *   // the type-3 (natively signed) encoding covers ECDSA-signed X.509 v3 certificates
+ *   var pair = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var signerCertDer = 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"),
+ *     extensions: { keyUsage: ["digitalSignature"] } },
+ *     { key: await pki.key.export(pair.privateKey) });
  *   var cbor = pki.schema.c509.encode(signerCertDer);   // a DER cert -> a compact type-3 C509
  *   pki.schema.c509.parse(cbor).certificateType;        // 3
  */