@blamejs/pki 0.4.14 → 0.5.0

package/index.js

@@ -39,6 +39,7 @@ var ct        = require("./lib/ct");
 var tls       = require("./lib/tls-cert-compress");
 var cms       = require("./lib/cms-verify");
 var smime     = require("./lib/smime");
+var cmc       = require("./lib/cmc-verify");
 var tsp       = require("./lib/tsp-sign");
 var ocsp      = require("./lib/ocsp");
 var x509      = require("./lib/x509-sign");
@@ -93,6 +94,9 @@ module.exports = {
   tls:       tls,
   cms:       cms,
   smime:     smime,
+  // `cmc` interprets an RFC 5272 Full PKI Response into one terminal verdict;
+  // `pki.schema.cmc` is the decoder underneath it.
+  cmc:       cmc,
   tsp:       tsp,
   ocsp:      ocsp,
   // `x509` is the certificate-issuance producing side -- pki.x509.sign builds and

package/lib/acme.js

@@ -416,6 +416,10 @@ function validateProblem(obj) {
  * `acme/*` fault; returns the object.
  *
  * @example
+ *   var orderObj = { status: "pending", expires: "2026-02-01T00:00:00Z",
+ *     identifiers: [{ type: "dns", value: "example.org" }],
+ *     authorizations: ["https://ca.example/authz/1"],
+ *     finalize: "https://ca.example/order/1/finalize" };
  *   pki.acme.validate("order", orderObj).status;   // -> "pending"
  */
 function validate(kind, obj) {
@@ -442,6 +446,10 @@ function validate(kind, obj) {
  * are proven mutually exclusive; a DER structure identifies as `"unknown"`.
  *
  * @example
+ *   var orderObj = { status: "pending", expires: "2026-02-01T00:00:00Z",
+ *     identifiers: [{ type: "dns", value: "example.org" }],
+ *     authorizations: ["https://ca.example/authz/1"],
+ *     finalize: "https://ca.example/order/1/finalize" };
  *   pki.acme.identify(orderObj);   // -> "order"
  */
 function identify(obj) {
@@ -484,6 +492,9 @@ async function _sha256(bytes) { return Buffer.from(await subtle.digest("SHA-256"
  * digest, so changing the account key changes the key authorization.
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var accountJwk = await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey);
+ *   var token = "example-challenge-token-not-a-secret";   // the real one comes from the CA
  *   await pki.acme.keyAuthorization(token, accountJwk);   // -> "<token>.<thumbprint>"
  */
 async function keyAuthorization(token, accountJwk) {
@@ -505,6 +516,9 @@ async function keyAuthorization(token, accountJwk) {
  * authorization, no trailing newline). Validation reaches TCP port 80 over HTTP.
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var accountJwk = await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey);
+ *   var token = "example-challenge-token-not-a-secret";
  *   var c = await pki.acme.http01(token, accountJwk);
  *   c.path;   // -> "/.well-known/acme-challenge/<token>"
  */
@@ -526,6 +540,9 @@ async function http01(token, accountJwk) {
  * order) and the `value` `base64url(SHA-256(keyAuthorization))`.
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var accountJwk = await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey);
+ *   var token = "example-challenge-token-not-a-secret";
  *   var r = await pki.acme.dns01(token, accountJwk, "example.org");
  *   r.name;   // -> "_acme-challenge.example.org"
  */
@@ -559,6 +576,9 @@ var _extCtx = { E: function (c, m, cause) { return new AcmeError(c, m, cause); }
  * SHA-256(keyAuthorization) }`. Placed in the validation certificate.
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var accountJwk = await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey);
+ *   var token = "example-challenge-token-not-a-secret";
  *   var extDer = await pki.acme.tlsAlpn01Extension(token, accountJwk);
  */
 async function tlsAlpn01Extension(token, accountJwk) {
@@ -593,6 +613,19 @@ function _readAcmeIdentifier(extnValue) {
  * for an `ip` identifier (RFC 8738 sec. 6). Any deviation throws `acme/bad-tlsalpn`.
  *
  * @example
+ *   var b = pki.asn1.build;
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var accountJwk = await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey);
+ *   var token = "example-challenge-token-not-a-secret";
+ *   // the validation certificate carries exactly two extensions: the critical
+ *   // acmeIdentifier, and a single-entry SAN naming the identifier being validated
+ *   var acmeExt = await pki.acme.tlsAlpn01Extension(token, accountJwk);
+ *   var sanExt = b.sequence([b.oid("2.5.29.17"),
+ *     b.octetString(b.sequence([b.contextPrimitive(2, Buffer.from("example.org", "ascii"))]))]);
+ *   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"),
+ *     extensions: [acmeExt, sanExt] }, { key: await pki.key.export(kp.privateKey) });
  *   await pki.acme.verifyTlsAlpn01(certDer, token, accountJwk, { type: "dns", value: "example.org" });
  */
 async function verifyTlsAlpn01(certDer, token, accountJwk, identifier) {
@@ -755,6 +788,10 @@ var _HMAC_HASH = { HS256: "SHA-256", HS384: "SHA-384", HS512: "SHA-512" };
  * (alg default `HS256`). The result is embedded as newAccount's `externalAccountBinding`.
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var accountJwk = await pki.webcrypto.subtle.exportKey("jwk", ec.publicKey);
+ *   var macKey = Buffer.alloc(32, 7);          // the HMAC key the CA issued out of band
+ *   var url = "https://ca.example/acme/new-acct";
  *   var eab = await pki.acme.externalAccountBinding({ macKey, kid: "abc123", url, accountJwk });
  */
 async function externalAccountBinding(o) {
@@ -991,6 +1028,10 @@ async function finalize(o) {
  * (payload default `{}`; pass a custom object for a future challenge type).
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var key = ec.privateKey;
+ *   var nonce = "oFvnlFP1wIhRlYS2jTaXbA";                 // from the CA's Replay-Nonce header
+ *   var kid = "https://ca.example/acct/1", challUrl = "https://ca.example/chall/1";
  *   await pki.acme.challengeResponse({ key, alg: "ES256", nonce, url: challUrl, kid });
  */
 function challengeResponse(o) {
@@ -1013,6 +1054,10 @@ function challengeResponse(o) {
  * the only client-settable status. `opts` = `{ key, alg, nonce, url, kid }`.
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var key = ec.privateKey;
+ *   var nonce = "oFvnlFP1wIhRlYS2jTaXbA";
+ *   var kid = "https://ca.example/acct/1", authzUrl = "https://ca.example/authz/1";
  *   await pki.acme.deactivate({ key, alg: "ES256", nonce, url: authzUrl, kid });
  */
 function deactivate(o) {
@@ -1035,6 +1080,14 @@ function deactivate(o) {
  * url, certificate (DER Buffer), reason?, kid? | jwk? }`.
  *
  * @example
+ *   var ec = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var key = ec.privateKey;
+ *   var nonce = "oFvnlFP1wIhRlYS2jTaXbA";
+ *   var kid = "https://ca.example/acct/1", url = "https://ca.example/acme/revoke-cert";
+ *   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) });
  *   await pki.acme.revokeCert({ key, alg: "ES256", nonce, url, kid, certificate: certDer, reason: 1 });
  */
 function revokeCert(o) {
@@ -1071,6 +1124,14 @@ function revokeCert(o) {
  * private), newJwk (new public JWK), newAlg, nonce, url }`.
  *
  * @example
+ *   var subtle = pki.webcrypto.subtle;
+ *   var oldPair = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var newPair = await pki.key.generate({ name: "ECDSA", namedCurve: "P-256" });
+ *   var oldKey = oldPair.privateKey, newKey = newPair.privateKey;
+ *   var oldJwk = await subtle.exportKey("jwk", oldPair.publicKey);
+ *   var newJwk = await subtle.exportKey("jwk", newPair.publicKey);
+ *   var nonce = "oFvnlFP1wIhRlYS2jTaXbA";
+ *   var kid = "https://ca.example/acct/1", url = "https://ca.example/acme/key-change";
  *   await pki.acme.keyChange({ key: oldKey, alg: "ES256", kid, account: kid, oldKey: oldJwk, newKey, newJwk, newAlg: "ES256", nonce, url });
  */
 async function keyChange(o) {
@@ -1106,6 +1167,16 @@ async function keyChange(o) {
  * `acme/bad-certid` if the certificate lacks an AKI keyIdentifier.
  *
  * @example
+ *   // the certificate must carry an authorityKeyIdentifier -- ARI keys off it
+ *   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 kp = await pki.key.generate("Ed25519");
+ *   var certDer = await pki.x509.sign({ subject: "example.org", subjectPublicKey: await pki.key.export(kp.publicKey),
+ *     serialNumber: 0x87654321n, notBefore: new Date("2026-01-01T00:00:00Z"), notAfter: new Date("2036-01-01T00:00:00Z"),
+ *     extensions: { authorityKeyIdentifier: true } }, { cert: caDer, key: caKey });
  *   pki.acme.ariCertId(certDer);   // -> "<b64u-aki>.<b64u-serial>"
  */
 function ariCertId(certDer) {
@@ -1132,7 +1203,8 @@ function ariCertId(certDer) {
  * non-alphabet rejected); anything but exactly two parts throws `acme/bad-certid`.
  *
  * @example
- *   pki.acme.parseAriCertId("<b64u-aki>.<b64u-serial>").serial;   // -> Buffer
+ *   // the two halves are base64url(authorityKeyIdentifier) and base64url(serialNumber)
+ *   pki.acme.parseAriCertId("aYhfK4oaay8.AIdlQyE").serial;   // -> Buffer 00 87 65 43 21
  */
 function parseAriCertId(certId) {
   if (!_isString(certId)) throw E("acme/bad-certid", "an ARI certID must be a string");

package/lib/asn1-der.js

@@ -156,6 +156,7 @@ function _asBuffer(input, who) {
  *                             // constructed OCTET STRINGs (BER content regions)
  *
  * @example
+ *   var der = pki.asn1.build.sequence([pki.asn1.build.integer(1n)]);
  *   var node = pki.asn1.decode(der);
  *   node.tagNumber === pki.asn1.TAGS.SEQUENCE;
  */
@@ -553,6 +554,7 @@ function readNullImplicit(node, tag) {
  * the minimal base-128 sub-identifier encoding DER requires.
  *
  * @example
+ *   var node = pki.asn1.decode(pki.asn1.build.oid("2.5.4.3"));
  *   pki.asn1.read.oid(node); // -> "2.5.4.3"
  */
 function readOid(node) {

package/lib/attrcert-sign.js

@@ -440,6 +440,10 @@ function _buildExtensions(extSpec, aaSpki) {
  *   - `pss` (boolean) -- sign an RSA key with RSASSA-PSS rather than PKCS#1 v1.5.
  *   - `digestAlgorithm` (string) -- override the message digest where the algorithm permits a choice.
  * @example
+ *   var pair = await pki.key.generate("Ed25519");
+ *   var signerKeyPkcs8 = await pki.key.export(pair.privateKey);
+ *   var signerCertDer = 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: signerKeyPkcs8 });
  *   var ac = 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"),

package/lib/cbor-det.js

@@ -232,7 +232,7 @@ function _decodeItem(buf, start, limit, depth, maxD, rules, state) {
  * @primitive  pki.cbor.decode
  * @signature  pki.cbor.decode(bytes, opts?) -> node
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 4.2 (core deterministic encoding)
  *
  * Decode one Deterministically Encoded CBOR item into a navigable node tree.
@@ -290,7 +290,7 @@ function _tagInner(node, tagNum, who) {
  * @primitive  pki.cbor.read.uint
  * @signature  pki.cbor.read.uint(node) -> 0n
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 0)
  *
  * The unsigned integer value of a major-type-0 node, as a BigInt (uniform
@@ -298,6 +298,7 @@ function _tagInner(node, tagNum, who) {
  * `cbor/unexpected-major` on any other major type.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("00", "hex"));
  *   pki.cbor.read.uint(node); // -> 0n
  */
 function readUint(node) {
@@ -309,13 +310,14 @@ function readUint(node) {
  * @primitive  pki.cbor.read.nint
  * @signature  pki.cbor.read.nint(node) -> -1n
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 1)
  *
  * The negative integer value of a major-type-1 node, as a BigInt
  * (value = -1 - argument). Throws `cbor/unexpected-major` otherwise.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("20", "hex"));
  *   pki.cbor.read.nint(node); // -> -1n
  */
 function readNint(node) {
@@ -327,13 +329,14 @@ function readNint(node) {
  * @primitive  pki.cbor.read.int
  * @signature  pki.cbor.read.int(node) -> -1n
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major types 0 and 1)
  *
  * The signed integer value of a major-type-0 or -1 node, as a BigInt. Throws
  * `cbor/unexpected-major` on any other major type.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("20", "hex"));
  *   pki.cbor.read.int(node); // -> -1n
  */
 function readInt(node) {
@@ -346,13 +349,14 @@ function readInt(node) {
  * @primitive  pki.cbor.read.byteString
  * @signature  pki.cbor.read.byteString(node) -> Buffer
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 2)
  *
  * The zero-copy `Buffer` content of a major-type-2 byte string. Throws
  * `cbor/unexpected-major` otherwise.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("4401020304", "hex"));
  *   pki.cbor.read.byteString(node); // -> <Buffer 01 02 03 04>
  */
 function readByteString(node) {
@@ -364,13 +368,14 @@ function readByteString(node) {
  * @primitive  pki.cbor.read.textString
  * @signature  pki.cbor.read.textString(node) -> "text"
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 3)
  *
  * The string value of a major-type-3 text string (already validated as
  * well-formed UTF-8 at decode). Throws `cbor/unexpected-major` otherwise.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("6161", "hex"));
  *   pki.cbor.read.textString(node); // -> "a"
  */
 function readTextString(node) {
@@ -382,13 +387,14 @@ function readTextString(node) {
  * @primitive  pki.cbor.read.array
  * @signature  pki.cbor.read.array(node) -> [node, ...]
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 4)
  *
  * The element nodes of a major-type-4 array. Throws `cbor/unexpected-major`
  * otherwise.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("83010203", "hex"));
  *   pki.cbor.read.array(node); // -> [node, node, node]
  */
 function readArray(node) {
@@ -400,7 +406,7 @@ function readArray(node) {
  * @primitive  pki.cbor.read.map
  * @signature  pki.cbor.read.map(node) -> [[keyNode, valueNode], ...]
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 5)
  *
  * The ordered key/value node pairs of a major-type-5 map (ordering and
@@ -408,6 +414,7 @@ function readArray(node) {
  * otherwise.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("a1616101", "hex")); // {"a": 1}
  *   pki.cbor.read.map(node); // -> [[keyNode, valueNode]]
  */
 function readMap(node) {
@@ -419,7 +426,7 @@ function readMap(node) {
  * @primitive  pki.cbor.read.mapGet
  * @signature  pki.cbor.read.mapGet(node, key) -> valueNode | null
  * @since      0.2.20
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 5)
  *
  * The value node of the map entry whose key equals `key` -- a text string
@@ -436,6 +443,8 @@ function readMap(node) {
  * a TypeError for a key that is neither a text string nor an integer.
  *
  * @example
+ *   // a WebAuthn-shaped map: {3: -7, "fmt": "packed"} in deterministic key order
+ *   var node = pki.cbor.decode(Buffer.from("a2032663666d74667061636b6564", "hex"));
  *   pki.cbor.read.mapGet(node, "fmt"); // -> valueNode | null
  *   pki.cbor.read.mapGet(node, 3);     // a COSE alg label -> valueNode | null
  */
@@ -465,7 +474,7 @@ function readMapGet(node, key) {
  * @primitive  pki.cbor.read.boolean
  * @signature  pki.cbor.read.boolean(node) -> false
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.3 (simple values 20 / 21)
  *
  * The boolean value of a simple-value node (false=20, true=21). Throws
@@ -473,6 +482,7 @@ function readMapGet(node, key) {
  * other simple value.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("f5", "hex"));
  *   pki.cbor.read.boolean(node); // -> true
  */
 function readBoolean(node) {
@@ -486,13 +496,14 @@ function readBoolean(node) {
  * @primitive  pki.cbor.read.nullValue
  * @signature  pki.cbor.read.nullValue(node) -> null
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.3 (simple value 22)
  *
  * `null` for a simple-value-22 node. Throws `cbor/unexpected-major` on a
  * non-simple node, `cbor/bad-simple` on any other simple value.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("f6", "hex"));
  *   pki.cbor.read.nullValue(node); // -> null
  */
 function readNull(node) {
@@ -505,13 +516,14 @@ function readNull(node) {
  * @primitive  pki.cbor.read.undefinedValue
  * @signature  pki.cbor.read.undefinedValue(node) -> undefined
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.3 (simple value 23)
  *
  * `undefined` for a simple-value-23 node. Throws `cbor/unexpected-major` on a
  * non-simple node, `cbor/bad-simple` on any other simple value.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("f7", "hex"));
  *   pki.cbor.read.undefinedValue(node); // -> undefined
  */
 function readUndefined(node) {
@@ -524,7 +536,7 @@ function readUndefined(node) {
  * @primitive  pki.cbor.read.float
  * @signature  pki.cbor.read.float(node) -> 1.5
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.1 (major type 7 floats)
  *
  * The JS number (double) of a half / single / double float node (the
@@ -533,6 +545,7 @@ function readUndefined(node) {
  * simple value that is not a float.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("f93e00", "hex")); // half-precision 1.5
  *   pki.cbor.read.float(node); // -> 1.5
  */
 function readFloat(node) {
@@ -547,7 +560,7 @@ function readFloat(node) {
  * @primitive  pki.cbor.read.biguint
  * @signature  pki.cbor.read.biguint(node) -> 18446744073709551616n
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.4.3 (tag 2 unsigned bignum)
  *
  * The BigInt value of a tag-2 unsigned bignum (a big-endian magnitude byte
@@ -557,6 +570,7 @@ function readFloat(node) {
  * (`cbor/bad-tag-content`); a wrong / absent tag throws `cbor/unexpected-tag`.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("c249010000000000000000", "hex"));
  *   pki.cbor.read.biguint(node); // -> 18446744073709551616n
  */
 function readBiguint(node) {
@@ -575,7 +589,7 @@ function readBiguint(node) {
  * @primitive  pki.cbor.read.time
  * @signature  pki.cbor.read.time(node) -> Date
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 8949 sec. 3.4.2 (tag 1 epoch date/time)
  *
  * The `Date` of a tag-1 epoch time (seconds since 1970-01-01T00:00Z, integer).
@@ -583,6 +597,7 @@ function readBiguint(node) {
  * when tag 1 does not wrap an integer, `cbor/bad-time` on an out-of-range value.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("c11a514b67b0", "hex")); // tag 1, epoch seconds
  *   pki.cbor.read.time(node); // -> Date 2013-03-21T20:04:00.000Z
  */
 function readTime(node) {
@@ -606,7 +621,7 @@ function readTime(node) {
  * @primitive  pki.cbor.read.oid
  * @signature  pki.cbor.read.oid(node) -> "2.5.4.3"
  * @since      0.1.27
- * @status     experimental
+ * @status     stable
  * @spec       RFC 9090 (tag 111 CBOR OID)
  *
  * The dotted OID string of a tag-111 CBOR OID (a byte string carrying the BER
@@ -616,6 +631,7 @@ function readTime(node) {
  * `cbor/bad-tag-content` when tag 111 does not wrap a byte string.
  *
  * @example
+ *   var node = pki.cbor.decode(Buffer.from("d86f43550403", "hex")); // tag 111 (RFC 9090)
  *   pki.cbor.read.oid(node); // -> "2.5.4.3"
  */
 function readOid(node) {