@blamejs/pki 0.1.1

package/lib/asn1-der.js

@@ -0,0 +1,576 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.asn1
+ * @nav        Core
+ * @title      ASN.1 / DER
+ * @order      30
+ * @featured   true
+ * @slug       asn1
+ *
+ * @intro
+ *   A strict DER (Distinguished Encoding Rules) codec — the byte layer
+ *   every X.509 / PKCS / CMS structure is built on. The decoder is
+ *   fail-closed: it rejects the BER shapes DER forbids (indefinite
+ *   length, non-minimal length or integer encodings, trailing garbage,
+ *   constructed strings) and refuses input past a size or nesting cap
+ *   before it walks a single byte, so a hostile length prefix can't turn
+ *   into a decoder denial-of-service.
+ *
+ *   `decode(bytes)` returns a navigable node tree; the `read.*` helpers
+ *   turn a node into a JS value (BigInt, dotted OID, Date, string); the
+ *   `build.*` helpers construct canonical DER from JS values. Because DER
+ *   is canonical, each value the `build.*` helpers emit has exactly one
+ *   valid encoding — byte-identical to any other conformant DER encoder's
+ *   output — and decoding it reproduces the value it was built from.
+ *
+ * @card
+ *   Strict, fail-closed DER decode / encode with a navigable node tree
+ *   and typed readers + builders.
+ */
+
+var constants = require("./constants");
+var frameworkError = require("./framework-error");
+
+var Asn1Error = frameworkError.Asn1Error;
+var OidError = frameworkError.OidError;
+
+// ---- Tag constants (universal class) --------------------------------
+
+var TAGS = {
+  BOOLEAN:           0x01,
+  INTEGER:           0x02,
+  BIT_STRING:        0x03,
+  OCTET_STRING:      0x04,
+  NULL:              0x05,
+  OBJECT_IDENTIFIER: 0x06,
+  ENUMERATED:        0x0a,
+  UTF8_STRING:       0x0c,
+  SEQUENCE:          0x10,
+  SET:               0x11,
+  PRINTABLE_STRING:  0x13,
+  TELETEX_STRING:    0x14,
+  IA5_STRING:        0x16,
+  UTC_TIME:          0x17,
+  GENERALIZED_TIME:  0x18,
+  VISIBLE_STRING:    0x1a,
+  UNIVERSAL_STRING:  0x1c,
+  BMP_STRING:        0x1e,
+};
+
+var CLASS_UNIVERSAL   = 0x00;
+var CLASS_APPLICATION = 0x40;
+var CLASS_CONTEXT     = 0x80;
+var CLASS_PRIVATE     = 0xc0;
+var CONSTRUCTED_BIT   = 0x20;
+
+function _className(bits) {
+  switch (bits) {
+    case CLASS_UNIVERSAL:   return "universal";
+    case CLASS_APPLICATION: return "application";
+    case CLASS_CONTEXT:     return "context";
+    case CLASS_PRIVATE:     return "private";
+    default:                return "universal";
+  }
+}
+
+function _asBuffer(input, who) {
+  if (Buffer.isBuffer(input)) return input;
+  if (input instanceof Uint8Array) return Buffer.from(input);
+  throw new Asn1Error("asn1/not-buffer", who + ": expected a Buffer / Uint8Array");
+}
+
+// ---- Decoder --------------------------------------------------------
+
+/**
+ * @primitive  pki.asn1.decode
+ * @signature  pki.asn1.decode(bytes, opts?) -> node
+ * @since      0.1.0
+ * @status     stable
+ * @related    pki.asn1.encode
+ *
+ * Parse DER into a node tree. Each node is
+ * `{ tagClass, constructed, tagNumber, header, length, content, children,
+ * bytes }` — `content` is the primitive value slice, `children` the
+ * decoded sub-nodes of a constructed node, and `bytes` the full TLV slice
+ * (all zero-copy views over the input).
+ *
+ * Throws `Asn1Error` on any non-DER shape: indefinite length, a
+ * non-minimal length or a length that overruns the buffer, trailing bytes
+ * after the top-level value (unless `allowTrailing`), or exceeding the
+ * size / depth caps.
+ *
+ * @opts
+ *   maxBytes:       number,   // default: C.LIMITS.DER_MAX_BYTES (16 MiB)
+ *   maxDepth:       number,   // default: C.LIMITS.DER_MAX_DEPTH (64)
+ *   allowTrailing:  boolean,  // default: false — allow bytes after the top TLV
+ *
+ * @example
+ *   var node = pki.asn1.decode(der);
+ *   node.tagNumber === pki.asn1.TAGS.SEQUENCE;
+ */
+function decode(input, opts) {
+  opts = opts || {};
+  var buf = _asBuffer(input, "decode");
+  var maxBytes = typeof opts.maxBytes === "number" ? opts.maxBytes : constants.LIMITS.DER_MAX_BYTES;
+  var maxDepth = typeof opts.maxDepth === "number" ? opts.maxDepth : constants.LIMITS.DER_MAX_DEPTH;
+  if (buf.length > maxBytes) {
+    throw new Asn1Error("asn1/too-large", "input " + buf.length + " bytes exceeds cap " + maxBytes);
+  }
+  var r = _decodeTLV(buf, 0, buf.length, 0, maxDepth);
+  if (!opts.allowTrailing && r.end !== buf.length) {
+    throw new Asn1Error("asn1/trailing-bytes", (buf.length - r.end) + " trailing byte(s) after the top-level value");
+  }
+  return r.node;
+}
+
+function _decodeTLV(buf, start, limit, depth, maxDepth) {
+  if (depth > maxDepth) {
+    throw new Asn1Error("asn1/too-deep", "nesting exceeds depth cap " + maxDepth);
+  }
+  var p = start;
+  if (p >= limit) throw new Asn1Error("asn1/truncated", "expected an identifier octet");
+  var first = buf[p]; p += 1;
+  var tagClassBits = first & 0xc0;
+  var constructed = (first & CONSTRUCTED_BIT) !== 0;
+  var tagNumber = first & 0x1f;
+
+  if (tagNumber === 0x1f) {
+    // High-tag-number form: base-128, minimal (no leading 0x80).
+    tagNumber = 0;
+    var seen = 0;
+    for (;;) {
+      if (p >= limit) throw new Asn1Error("asn1/truncated", "truncated high-tag-number");
+      var tb = buf[p]; p += 1;
+      if (seen === 0 && tb === 0x80) {
+        throw new Asn1Error("asn1/non-minimal-tag", "leading 0x80 in high-tag-number form");
+      }
+      tagNumber = (tagNumber * 128) + (tb & 0x7f);
+      seen += 1;
+      if (seen > 4) throw new Asn1Error("asn1/tag-too-large", "high-tag-number too large");
+      if ((tb & 0x80) === 0) break;
+    }
+    if (tagNumber < 0x1f) {
+      throw new Asn1Error("asn1/non-minimal-tag", "high-tag-number form used for a low tag");
+    }
+  }
+
+  if (p >= limit) throw new Asn1Error("asn1/truncated", "expected a length octet");
+  var lenByte = buf[p]; p += 1;
+  var length;
+  if (lenByte < 0x80) {
+    length = lenByte;
+  } else if (lenByte === 0x80) {
+    throw new Asn1Error("asn1/indefinite-length", "indefinite length is not valid DER");
+  } else {
+    var numLenBytes = lenByte & 0x7f;
+    if (numLenBytes > 6) throw new Asn1Error("asn1/length-too-large", "length uses more than 6 octets");
+    if (p + numLenBytes > limit) throw new Asn1Error("asn1/truncated", "truncated long-form length");
+    if (buf[p] === 0x00) throw new Asn1Error("asn1/non-minimal-length", "leading zero in long-form length");
+    length = 0;
+    for (var i = 0; i < numLenBytes; i++) length = (length * 256) + buf[p + i];
+    p += numLenBytes;
+    if (length < 0x80) throw new Asn1Error("asn1/non-minimal-length", "long form used for a length < 128");
+  }
+
+  var contentStart = p;
+  var contentEnd = contentStart + length;
+  if (contentEnd > limit) throw new Asn1Error("asn1/truncated", "content length overruns the buffer");
+
+  var node = {
+    tagClass:     _className(tagClassBits),
+    constructed:  constructed,
+    tagNumber:    tagNumber,
+    length:       length,
+    header:       { start: start, end: contentStart },
+    contentStart: contentStart,
+    contentEnd:   contentEnd,
+    content:      null,
+    children:     null,
+    bytes:        buf.subarray(start, contentEnd),
+  };
+
+  if (constructed) {
+    node.children = [];
+    var cp = contentStart;
+    while (cp < contentEnd) {
+      var child = _decodeTLV(buf, cp, contentEnd, depth + 1, maxDepth);
+      node.children.push(child.node);
+      cp = child.end;
+    }
+  } else {
+    node.content = buf.subarray(contentStart, contentEnd);
+  }
+  return { node: node, end: contentEnd };
+}
+
+// ---- Node assertions ------------------------------------------------
+
+function _expectUniversal(node, tag, who) {
+  if (node.tagClass !== "universal" || node.tagNumber !== tag) {
+    throw new Asn1Error("asn1/unexpected-tag", who + ": expected universal tag " + tag +
+      ", got " + node.tagClass + "/" + node.tagNumber);
+  }
+}
+
+function _expectPrimitive(node, who) {
+  if (node.constructed) throw new Asn1Error("asn1/expected-primitive", who + ": expected a primitive encoding");
+}
+
+// ---- Typed readers --------------------------------------------------
+
+function readBoolean(node) {
+  _expectUniversal(node, TAGS.BOOLEAN, "readBoolean");
+  _expectPrimitive(node, "readBoolean");
+  if (node.content.length !== 1) throw new Asn1Error("asn1/bad-boolean", "BOOLEAN content must be 1 octet");
+  var v = node.content[0];
+  if (v === 0x00) return false;
+  if (v === 0xff) return true;
+  throw new Asn1Error("asn1/bad-boolean", "DER BOOLEAN must be 0x00 or 0xFF, got 0x" + v.toString(16));
+}
+
+function readInteger(node) {
+  if (node.tagClass === "universal" && node.tagNumber === TAGS.ENUMERATED) {
+    // ENUMERATED shares INTEGER's content encoding.
+  } else {
+    _expectUniversal(node, TAGS.INTEGER, "readInteger");
+  }
+  _expectPrimitive(node, "readInteger");
+  var c = node.content;
+  if (c.length === 0) throw new Asn1Error("asn1/bad-integer", "INTEGER must have at least 1 content octet");
+  if (c.length > 1) {
+    if (c[0] === 0x00 && (c[1] & 0x80) === 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal positive INTEGER");
+    if (c[0] === 0xff && (c[1] & 0x80) !== 0) throw new Asn1Error("asn1/non-minimal-integer", "non-minimal negative INTEGER");
+  }
+  var neg = (c[0] & 0x80) !== 0;
+  var v = 0n;
+  for (var i = 0; i < c.length; i++) v = (v << 8n) | BigInt(c[i]);
+  if (neg) v -= (1n << BigInt(8 * c.length));
+  return v;
+}
+
+function readBitString(node) {
+  _expectUniversal(node, TAGS.BIT_STRING, "readBitString");
+  _expectPrimitive(node, "readBitString");
+  var c = node.content;
+  if (c.length === 0) throw new Asn1Error("asn1/bad-bit-string", "BIT STRING must have >= 1 content octet");
+  var unusedBits = c[0];
+  if (unusedBits > 7) throw new Asn1Error("asn1/bad-bit-string", "unused-bit count " + unusedBits + " > 7");
+  if (unusedBits > 0 && c.length === 1) throw new Asn1Error("asn1/bad-bit-string", "unused bits declared over an empty body");
+  return { unusedBits: unusedBits, bytes: c.subarray(1) };
+}
+
+function readOctetString(node) {
+  _expectUniversal(node, TAGS.OCTET_STRING, "readOctetString");
+  _expectPrimitive(node, "readOctetString");
+  return node.content;
+}
+
+function readNull(node) {
+  _expectUniversal(node, TAGS.NULL, "readNull");
+  _expectPrimitive(node, "readNull");
+  if (node.content.length !== 0) throw new Asn1Error("asn1/bad-null", "NULL must have empty content");
+  return null;
+}
+
+/**
+ * @primitive  pki.asn1.readOid
+ * @signature  pki.asn1.read.oid(node) -> "1.2.840.113549.1.1.11"
+ * @since      0.1.0
+ * @status     stable
+ * @related    pki.oid.name
+ *
+ * Decode an OBJECT IDENTIFIER node to its dotted-decimal string, enforcing
+ * the minimal base-128 sub-identifier encoding DER requires.
+ *
+ * @example
+ *   pki.asn1.read.oid(node); // -> "2.5.4.3"
+ */
+function readOid(node) {
+  _expectUniversal(node, TAGS.OBJECT_IDENTIFIER, "readOid");
+  _expectPrimitive(node, "readOid");
+  return decodeOidContent(node.content);
+}
+
+function decodeOidContent(buf) {
+  if (buf.length === 0) throw new OidError("oid/empty", "OBJECT IDENTIFIER content is empty");
+  var arcs = [];
+  var value = 0n;
+  var started = false;
+  for (var i = 0; i < buf.length; i++) {
+    var b = buf[i];
+    if (!started && b === 0x80) throw new OidError("oid/non-minimal", "non-minimal sub-identifier (leading 0x80)");
+    value = (value << 7n) | BigInt(b & 0x7f);
+    started = true;
+    if ((b & 0x80) === 0) { arcs.push(value); value = 0n; started = false; }
+  }
+  if (started) throw new OidError("oid/truncated", "OBJECT IDENTIFIER ends mid sub-identifier");
+  var first = arcs[0];
+  var a1, a2;
+  if (first < 40n) { a1 = 0n; a2 = first; }
+  else if (first < 80n) { a1 = 1n; a2 = first - 40n; }
+  else { a1 = 2n; a2 = first - 80n; }
+  var out = [a1.toString(), a2.toString()];
+  for (var j = 1; j < arcs.length; j++) out.push(arcs[j].toString());
+  return out.join(".");
+}
+
+function _decodeText(buf, encoding) {
+  return buf.toString(encoding);
+}
+
+function readString(node) {
+  if (node.tagClass !== "universal") throw new Asn1Error("asn1/expected-string", "readString: not a universal string type");
+  _expectPrimitive(node, "readString");
+  switch (node.tagNumber) {
+    case TAGS.UTF8_STRING:      return _decodeText(node.content, "utf8");
+    case TAGS.PRINTABLE_STRING: return _decodeText(node.content, "latin1");
+    case TAGS.IA5_STRING:       return _decodeText(node.content, "latin1");
+    case TAGS.TELETEX_STRING:   return _decodeText(node.content, "latin1");
+    case TAGS.VISIBLE_STRING:   return _decodeText(node.content, "latin1");
+    case TAGS.BMP_STRING:       return _decodeUtf16be(node.content);
+    case TAGS.UNIVERSAL_STRING: return _decodeUtf32be(node.content);
+    default:
+      throw new Asn1Error("asn1/expected-string", "readString: tag " + node.tagNumber + " is not a known string type");
+  }
+}
+
+function _decodeUtf16be(buf) {
+  if (buf.length % 2 !== 0) throw new Asn1Error("asn1/bad-bmp-string", "BMPString length must be even");
+  var swapped = Buffer.from(buf);
+  swapped.swap16();
+  return swapped.toString("utf16le");
+}
+
+function _decodeUtf32be(buf) {
+  if (buf.length % 4 !== 0) throw new Asn1Error("asn1/bad-universal-string", "UniversalString length must be a multiple of 4");
+  var out = "";
+  for (var i = 0; i < buf.length; i += 4) {
+    var cp = (buf[i] * 0x1000000) + (buf[i + 1] << 16) + (buf[i + 2] << 8) + buf[i + 3];
+    out += String.fromCodePoint(cp);
+  }
+  return out;
+}
+
+var UTC_RE = /^(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})Z$/;
+var GEN_RE = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})Z$/;
+
+function readTime(node) {
+  if (node.tagClass !== "universal") throw new Asn1Error("asn1/expected-time", "readTime: not a universal time type");
+  _expectPrimitive(node, "readTime");
+  var s = node.content.toString("latin1");
+  var m, year;
+  if (node.tagNumber === TAGS.UTC_TIME) {
+    m = UTC_RE.exec(s);
+    if (!m) throw new Asn1Error("asn1/bad-utctime", "UTCTime must be YYMMDDHHMMSSZ, got " + JSON.stringify(s));
+    year = parseInt(m[1], 10);
+    // RFC 5280 §4.1.2.5.1 — YY < 50 => 20YY, else 19YY.
+    year += (year < 50) ? 2000 : 1900;
+  } else if (node.tagNumber === TAGS.GENERALIZED_TIME) {
+    m = GEN_RE.exec(s);
+    if (!m) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime must be YYYYMMDDHHMMSSZ, got " + JSON.stringify(s));
+    year = parseInt(m[1], 10);
+  } else {
+    throw new Asn1Error("asn1/expected-time", "readTime: tag " + node.tagNumber + " is not a time type");
+  }
+  var month = parseInt(m[node.tagNumber === TAGS.UTC_TIME ? 2 : 2], 10);
+  var day   = parseInt(m[3], 10);
+  var hour  = parseInt(m[4], 10);
+  var min   = parseInt(m[5], 10);
+  var sec   = parseInt(m[6], 10);
+  var t = Date.UTC(year, month - 1, day, hour, min, sec);
+  if (isNaN(t)) throw new Asn1Error("asn1/bad-time", "unparseable time " + JSON.stringify(s));
+  return new Date(t);
+}
+
+// ---- Encoder / builders ---------------------------------------------
+
+function encodeLength(n) {
+  if (typeof n !== "number" || !isFinite(n) || n < 0 || Math.floor(n) !== n) {
+    throw new Asn1Error("asn1/bad-length", "length must be a non-negative integer");
+  }
+  if (n < 0x80) return Buffer.from([n]);
+  var bytes = [];
+  var v = n;
+  while (v > 0) { bytes.unshift(v & 0xff); v = Math.floor(v / 256); }
+  if (bytes.length > 126) throw new Asn1Error("asn1/length-too-large", "length needs more than 126 octets");
+  return Buffer.concat([Buffer.from([0x80 | bytes.length]), Buffer.from(bytes)]);
+}
+
+function encodeIdentifier(classBits, constructed, tagNumber) {
+  var lead = classBits | (constructed ? CONSTRUCTED_BIT : 0);
+  if (tagNumber < 0x1f) return Buffer.from([lead | tagNumber]);
+  var body = [];
+  var v = tagNumber;
+  do { body.unshift(v & 0x7f); v = Math.floor(v / 128); } while (v > 0);
+  for (var i = 0; i < body.length - 1; i++) body[i] |= 0x80;
+  return Buffer.concat([Buffer.from([lead | 0x1f]), Buffer.from(body)]);
+}
+
+/**
+ * @primitive  pki.asn1.encode
+ * @signature  pki.asn1.encode(classBits, constructed, tagNumber, content) -> Buffer
+ * @since      0.1.0
+ * @status     stable
+ * @related    pki.asn1.decode
+ *
+ * Low-level TLV encoder — prepend the identifier + DER length to a content
+ * buffer. Most callers use the higher-level `build.*` helpers; this is the
+ * escape hatch for context-tagged and implicitly-tagged constructions.
+ *
+ * @example
+ *   pki.asn1.encode(0x00, false, pki.asn1.TAGS.NULL, Buffer.alloc(0));
+ */
+function encodeTLV(classBits, constructed, tagNumber, content) {
+  var body = Buffer.isBuffer(content) ? content : Buffer.from(content || []);
+  var id = encodeIdentifier(classBits, constructed, tagNumber);
+  return Buffer.concat([id, encodeLength(body.length), body]);
+}
+
+function _universal(tagNumber, constructed, content) {
+  return encodeTLV(CLASS_UNIVERSAL, constructed, tagNumber, content);
+}
+
+function intToDer(v) {
+  if (typeof v === "number") {
+    if (!Number.isSafeInteger(v)) throw new Asn1Error("asn1/bad-integer", "unsafe integer; pass a BigInt");
+    v = BigInt(v);
+  }
+  if (typeof v !== "bigint") throw new Asn1Error("asn1/bad-integer", "integer must be number or BigInt");
+  if (v === 0n) return Buffer.from([0]);
+  var bytes = [];
+  if (v > 0n) {
+    var t = v;
+    while (t > 0n) { bytes.unshift(Number(t & 0xffn)); t >>= 8n; }
+    if (bytes[0] & 0x80) bytes.unshift(0x00);
+  } else {
+    var len = 1;
+    while (v < -(1n << BigInt(8 * len - 1))) len += 1;
+    var tc = (1n << BigInt(8 * len)) + v;
+    for (var i = len - 1; i >= 0; i--) { bytes[i] = Number(tc & 0xffn); tc >>= 8n; }
+  }
+  return Buffer.from(bytes);
+}
+
+function encodeOidContent(dotted) {
+  if (typeof dotted !== "string" || dotted.length === 0) throw new OidError("oid/bad-input", "OID must be a dotted-decimal string");
+  var parts = dotted.split(".");
+  if (parts.length < 2) throw new OidError("oid/too-short", "OID needs at least two arcs");
+  var arcs = [];
+  for (var i = 0; i < parts.length; i++) {
+    if (!/^\d+$/.test(parts[i])) throw new OidError("oid/bad-arc", "arc " + JSON.stringify(parts[i]) + " is not a non-negative integer");
+    arcs.push(BigInt(parts[i]));
+  }
+  var a1 = arcs[0], a2 = arcs[1];
+  if (a1 > 2n) throw new OidError("oid/bad-arc", "first arc must be 0, 1, or 2");
+  if (a1 < 2n && a2 >= 40n) throw new OidError("oid/bad-arc", "second arc must be < 40 when the first arc is 0 or 1");
+  var subids = [a1 * 40n + a2].concat(arcs.slice(2));
+  var out = [];
+  for (var s = 0; s < subids.length; s++) {
+    var body = [];
+    var v = subids[s];
+    do { body.unshift(Number(v & 0x7fn)); v >>= 7n; } while (v > 0n);
+    for (var k = 0; k < body.length - 1; k++) body[k] |= 0x80;
+    for (var j = 0; j < body.length; j++) out.push(body[j]);
+  }
+  return Buffer.from(out);
+}
+
+var PRINTABLE_RE = /^[A-Za-z0-9 '()+,\-./:=?]*$/;
+
+function _fmtTwo(n) { return (n < 10 ? "0" : "") + n; }
+
+function _generalizedTimeString(date) {
+  return "" + date.getUTCFullYear() +
+    _fmtTwo(date.getUTCMonth() + 1) + _fmtTwo(date.getUTCDate()) +
+    _fmtTwo(date.getUTCHours()) + _fmtTwo(date.getUTCMinutes()) + _fmtTwo(date.getUTCSeconds()) + "Z";
+}
+
+function _utcTimeString(date) {
+  var yy = date.getUTCFullYear() % 100;
+  return _fmtTwo(yy) +
+    _fmtTwo(date.getUTCMonth() + 1) + _fmtTwo(date.getUTCDate()) +
+    _fmtTwo(date.getUTCHours()) + _fmtTwo(date.getUTCMinutes()) + _fmtTwo(date.getUTCSeconds()) + "Z";
+}
+
+/**
+ * @primitive  pki.asn1.build
+ * @signature  pki.asn1.build.sequence([ ...tlvBuffers ]) -> Buffer
+ * @since      0.1.0
+ * @status     stable
+ * @related    pki.asn1.encode
+ *
+ * Canonical-DER value builders. Each returns the full TLV Buffer for one
+ * value; `sequence` / `set` / `setOf` take arrays of already-built child
+ * TLVs. `setOf` sorts its members by their DER encoding as X.690 requires.
+ *
+ * @example
+ *   var rdn = pki.asn1.build.sequence([
+ *     pki.asn1.build.oid("2.5.4.3"),
+ *     pki.asn1.build.utf8("example.com"),
+ *   ]);
+ */
+var build = {
+  boolean:  function (v) { return _universal(TAGS.BOOLEAN, false, Buffer.from([v ? 0xff : 0x00])); },
+  integer:  function (v) { return _universal(TAGS.INTEGER, false, Buffer.isBuffer(v) ? v : intToDer(v)); },
+  enumerated: function (v) { return _universal(TAGS.ENUMERATED, false, Buffer.isBuffer(v) ? v : intToDer(v)); },
+  nullValue: function () { return _universal(TAGS.NULL, false, Buffer.alloc(0)); },
+  oid:      function (dotted) { return _universal(TAGS.OBJECT_IDENTIFIER, false, encodeOidContent(dotted)); },
+  octetString: function (buf) { return _universal(TAGS.OCTET_STRING, false, _asBuffer(buf, "build.octetString")); },
+  bitString: function (buf, unusedBits) {
+    var u = unusedBits || 0;
+    if (u < 0 || u > 7) throw new Asn1Error("asn1/bad-bit-string", "unusedBits must be 0..7");
+    return _universal(TAGS.BIT_STRING, false, Buffer.concat([Buffer.from([u]), _asBuffer(buf, "build.bitString")]));
+  },
+  utf8:     function (s) { return _universal(TAGS.UTF8_STRING, false, Buffer.from(String(s), "utf8")); },
+  ia5:      function (s) { return _universal(TAGS.IA5_STRING, false, Buffer.from(String(s), "latin1")); },
+  printable: function (s) {
+    s = String(s);
+    if (!PRINTABLE_RE.test(s)) throw new Asn1Error("asn1/bad-printable-string", "value has characters outside the PrintableString set");
+    return _universal(TAGS.PRINTABLE_STRING, false, Buffer.from(s, "latin1"));
+  },
+  utcTime:  function (date) { return _universal(TAGS.UTC_TIME, false, Buffer.from(_utcTimeString(date), "latin1")); },
+  generalizedTime: function (date) { return _universal(TAGS.GENERALIZED_TIME, false, Buffer.from(_generalizedTimeString(date), "latin1")); },
+  sequence: function (children) { return _universal(TAGS.SEQUENCE, true, Buffer.concat(_asBufferArray(children, "build.sequence"))); },
+  set:      function (children) { return _universal(TAGS.SET, true, Buffer.concat(_asBufferArray(children, "build.set"))); },
+  setOf:    function (children) {
+    var arr = _asBufferArray(children, "build.setOf").slice();
+    arr.sort(Buffer.compare);
+    return _universal(TAGS.SET, true, Buffer.concat(arr));
+  },
+  // Context-tagged constructions for [n] EXPLICIT / IMPLICIT tagging.
+  explicit: function (tagNumber, inner) { return encodeTLV(CLASS_CONTEXT, true, tagNumber, _asBuffer(inner, "build.explicit")); },
+  contextPrimitive:   function (tagNumber, content) { return encodeTLV(CLASS_CONTEXT, false, tagNumber, _asBuffer(content, "build.contextPrimitive")); },
+  contextConstructed: function (tagNumber, content) { return encodeTLV(CLASS_CONTEXT, true, tagNumber, _asBuffer(content, "build.contextConstructed")); },
+  raw:      function (buf) { return _asBuffer(buf, "build.raw"); },
+};
+
+function _asBufferArray(arr, who) {
+  if (!Array.isArray(arr)) throw new Asn1Error("asn1/bad-children", who + ": expected an array of TLV buffers");
+  return arr.map(function (b) { return _asBuffer(b, who); });
+}
+
+module.exports = {
+  TAGS:          TAGS,
+  decode:        decode,
+  // `encode` is the documented public name for the low-level TLV encoder;
+  // `encodeTLV` remains as the descriptive alias.
+  encode:        encodeTLV,
+  encodeTLV:     encodeTLV,
+  encodeLength:  encodeLength,
+  encodeIdentifier: encodeIdentifier,
+  decodeOidContent: decodeOidContent,
+  encodeOidContent: encodeOidContent,
+  build:         build,
+  read: {
+    boolean:      readBoolean,
+    integer:      readInteger,
+    bitString:    readBitString,
+    octetString:  readOctetString,
+    nullValue:    readNull,
+    oid:          readOid,
+    string:       readString,
+    time:         readTime,
+  },
+};

package/lib/constants.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.C
+ * @nav        Core
+ * @title      Constants
+ * @order      10
+ * @featured   true
+ * @slug       constants
+ *
+ * @intro
+ *   Version-stable constant namespace for the toolkit. Scale values are
+ *   FUNCTIONS, not pre-baked discrete numbers: `C.TIME.days(30)` reads
+ *   at the call site and computes at boot, so a caller never hand-writes
+ *   `30 * 24 * 60 * 60 * 1000` (a raw-literal the codebase gate refuses)
+ *   and a reviewer never has to decode it.
+ *
+ *   Every scale helper is config-time / entry-point validation: it THROWS
+ *   `ConstantsError` on a non-finite or negative argument, so an operator
+ *   catches the typo at boot rather than shipping a silently-wrong window.
+ *
+ * @card
+ *   Functional scale helpers (`C.TIME.*`, `C.BYTES.*`) plus the toolkit
+ *   version and shared codec limits.
+ */
+
+var frameworkError = require("./framework-error");
+
+var ConstantsError = frameworkError.ConstantsError;
+
+// _positive(n, who) — the shared guard every scale helper runs. Config-
+// time tier: a bad scale argument is an authoring bug, so it throws.
+function _positive(n, who) {
+  if (typeof n !== "number" || !isFinite(n) || n < 0) {
+    throw new ConstantsError(
+      "constants/bad-scale",
+      who + ": expected a finite number >= 0, got " + String(n)
+    );
+  }
+  return n;
+}
+
+var MS_PER_SECOND = 1000;
+var SECONDS_PER_MINUTE = 60;
+var MINUTES_PER_HOUR = 60;
+var HOURS_PER_DAY = 24;
+var DAYS_PER_WEEK = 7;
+
+/**
+ * @primitive  pki.C.TIME
+ * @signature  C.TIME.days(n) -> milliseconds
+ * @since      0.1.0
+ * @status     stable
+ *
+ * Duration helpers. Each returns an integer count of milliseconds so the
+ * value drops straight into `setTimeout`, a validity window, or an OCSP
+ * `nextUpdate` computation. Composing reads naturally:
+ * `C.TIME.days(365)` for a one-year certificate lifetime.
+ *
+ * @example
+ *   var oneYear = pki.C.TIME.days(365);
+ *   // -> 31536000000
+ */
+var TIME = {
+  ms:      function (n) { return Math.round(_positive(n, "C.TIME.ms")); },
+  seconds: function (n) { return Math.round(_positive(n, "C.TIME.seconds") * MS_PER_SECOND); },
+  minutes: function (n) { return Math.round(_positive(n, "C.TIME.minutes") * SECONDS_PER_MINUTE * MS_PER_SECOND); },
+  hours:   function (n) { return Math.round(_positive(n, "C.TIME.hours") * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND); },
+  days:    function (n) { return Math.round(_positive(n, "C.TIME.days") * HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND); },
+  weeks:   function (n) { return Math.round(_positive(n, "C.TIME.weeks") * DAYS_PER_WEEK * HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND); },
+};
+
+var BYTES_PER_KIB = 1024;
+
+/**
+ * @primitive  pki.C.BYTES
+ * @signature  C.BYTES.mib(n) -> bytes
+ * @since      0.1.0
+ * @status     stable
+ *
+ * Binary-magnitude size helpers. Each returns an integer byte count for
+ * codec limits (max DER input, max PEM block) so a size bound reads as
+ * `C.BYTES.mib(16)` instead of `16 * 1024 * 1024`.
+ *
+ * @example
+ *   var cap = pki.C.BYTES.mib(16);
+ *   // -> 16777216
+ */
+var BYTES = {
+  b:   function (n) { return Math.round(_positive(n, "C.BYTES.b")); },
+  kib: function (n) { return Math.round(_positive(n, "C.BYTES.kib") * BYTES_PER_KIB); },
+  mib: function (n) { return Math.round(_positive(n, "C.BYTES.mib") * BYTES_PER_KIB * BYTES_PER_KIB); },
+  gib: function (n) { return Math.round(_positive(n, "C.BYTES.gib") * BYTES_PER_KIB * BYTES_PER_KIB * BYTES_PER_KIB); },
+};
+
+// LIMITS — shared codec ceilings. A DER document larger than this, or
+// nested deeper than this, is refused before the parser walks it: an
+// unbounded length prefix or a pathologically-nested SEQUENCE is a
+// classic decoder-DoS, so the bound is a fail-closed default rather
+// than a tunable an operator must remember to set.
+var LIMITS = {
+  DER_MAX_BYTES: BYTES.mib(16),
+  DER_MAX_DEPTH: 64,
+  PEM_MAX_BYTES: BYTES.mib(16),
+};
+
+var VERSION = "0.1.0";
+
+module.exports = {
+  TIME:    TIME,
+  BYTES:   BYTES,
+  LIMITS:  LIMITS,
+  version: VERSION,
+};