@moondeck/station 0.0.1 → 1.0.0

package/lib/secrets-proxy/der.ts

@@ -0,0 +1,273 @@
+/**
+ * Minimal DER encoder (ADR-153 §3 "The CA") — exactly the X.690 subset an
+ * X.509 v3 certificate needs, so the runner mints its proxy certificates with
+ * Node built-ins and no new dependency.
+ *
+ * Every function returns one complete TLV. Nothing here ever sees key
+ * material: ca.ts hands the finished TBSCertificate to a signing callback and
+ * only embeds the signature it gets back. Inputs that DER cannot represent
+ * exactly throw instead of being silently adjusted, so a bad certificate can
+ * only fail to mint — never be minted subtly wrong.
+ */
+
+const CONTEXT_SPECIFIC = 0x80;
+const CONSTRUCTED = 0x20;
+/** Low-tag-number form only (X.690 §8.1.2.2); X.509 never needs more. */
+const MAX_TAG_NUMBER = 30;
+
+const TAG = {
+  boolean: 0x01,
+  integer: 0x02,
+  bitString: 0x03,
+  octetString: 0x04,
+  null: 0x05,
+  objectIdentifier: 0x06,
+  utf8String: 0x0c,
+  printableString: 0x13,
+  ia5String: 0x16,
+  utcTime: 0x17,
+  generalizedTime: 0x18,
+  sequence: 0x30,
+  set: 0x31,
+} as const;
+
+/** Definite length: short form below 128, long form (0x80 | n, then n
+ *  big-endian octets, no leading zero) above (X.690 §8.1.3, §10.1). */
+export function encodeLength(length: number): Buffer {
+  if (!Number.isSafeInteger(length) || length < 0) {
+    throw new RangeError("DER length must be a non-negative safe integer");
+  }
+  if (length < 0x80) return Buffer.from([length]);
+  const octets: number[] = [];
+  for (let rest = length; rest > 0; rest = Math.floor(rest / 256)) {
+    octets.unshift(rest % 256);
+  }
+  return Buffer.from([0x80 | octets.length, ...octets]);
+}
+
+function tlv(tag: number, content: Uint8Array): Buffer {
+  return Buffer.concat([Buffer.from([tag]), encodeLength(content.length), content]);
+}
+
+export function sequence(...items: readonly Buffer[]): Buffer {
+  return tlv(TAG.sequence, Buffer.concat(items));
+}
+
+/** X.690 §11.6: a DER SET OF orders its elements by their encodings, compared
+ *  as octet strings with the shorter one padded with trailing zero octets. */
+function compareEncodings(left: Buffer, right: Buffer): number {
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+export function set(...items: readonly Buffer[]): Buffer {
+  return tlv(TAG.set, Buffer.concat([...items].sort(compareEncodings)));
+}
+
+/**
+ * A non-negative INTEGER. A Buffer is read as an unsigned big-endian
+ * magnitude (a certificate serial); a number must be a safe integer. DER
+ * wants the minimal two's-complement form: redundant leading zero octets are
+ * dropped, and one is added back when the top bit would read as a sign.
+ */
+export function integer(value: Buffer | number): Buffer {
+  let magnitude: Buffer;
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new RangeError("DER INTEGER must be a non-negative safe integer");
+    }
+    const octets: number[] = [];
+    for (let rest = value; rest > 0; rest = Math.floor(rest / 256)) {
+      octets.unshift(rest % 256);
+    }
+    magnitude = Buffer.from(octets);
+  } else {
+    magnitude = value;
+  }
+  let start = 0;
+  while (start < magnitude.length - 1 && magnitude[start] === 0) start += 1;
+  let content = magnitude.length === 0 ? Buffer.from([0]) : magnitude.subarray(start);
+  if (((content[0] ?? 0) & 0x80) !== 0) {
+    content = Buffer.concat([Buffer.from([0]), content]);
+  }
+  return tlv(TAG.integer, content);
+}
+
+function base128(arc: bigint): number[] {
+  const octets = [Number(arc & 0x7fn)];
+  for (let rest = arc >> 7n; rest > 0n; rest >>= 7n) {
+    octets.unshift(Number(rest & 0x7fn) | 0x80);
+  }
+  return octets;
+}
+
+/** Dotted-decimal OID. Arcs are BigInt so a 2.25.<uuid> arc stays exact. */
+export function objectIdentifier(oid: string): Buffer {
+  if (!/^[0-2](?:\.(?:0|[1-9][0-9]*))+$/.test(oid)) {
+    throw new Error(`invalid object identifier: ${oid}`);
+  }
+  const [first, second, ...rest] = oid.split(".").map((arc) => BigInt(arc));
+  if (first === undefined || second === undefined) {
+    throw new Error(`invalid object identifier: ${oid}`);
+  }
+  if (first < 2n && second >= 40n) {
+    throw new Error(`invalid object identifier: ${oid}`);
+  }
+  const octets = [first * 40n + second, ...rest].flatMap(base128);
+  return tlv(TAG.objectIdentifier, Buffer.from(octets));
+}
+
+export function nullValue(): Buffer {
+  return Buffer.from([TAG.null, 0x00]);
+}
+
+/** DER encodes TRUE as 0xFF only (X.690 §11.1). */
+export function boolean(value: boolean): Buffer {
+  return Buffer.from([TAG.boolean, 0x01, value ? 0xff : 0x00]);
+}
+
+/** A BIT STRING whose final `unusedBits` bits are padding, which DER requires
+ *  to be zero (X.690 §11.2.1). */
+export function bitString(bytes: Buffer, unusedBits = 0): Buffer {
+  if (!Number.isInteger(unusedBits) || unusedBits < 0 || unusedBits > 7) {
+    throw new RangeError("BIT STRING unused bits must be 0..7");
+  }
+  if (bytes.length === 0 && unusedBits !== 0) {
+    throw new RangeError("an empty BIT STRING has no unused bits");
+  }
+  const last = bytes[bytes.length - 1] ?? 0;
+  if ((last & ((1 << unusedBits) - 1)) !== 0) {
+    throw new RangeError("DER requires the unused bits of a BIT STRING to be zero");
+  }
+  return tlv(TAG.bitString, Buffer.concat([Buffer.from([unusedBits]), bytes]));
+}
+
+/**
+ * A NamedBitList BIT STRING such as KeyUsage: bit 0 is the most significant
+ * bit of the first octet, and DER drops trailing zero bits (X.690 §11.2.2),
+ * so keyCertSign|cRLSign encodes as `03 02 01 06`, not `03 02 00 06`.
+ */
+export function namedBitString(bits: readonly number[]): Buffer {
+  if (bits.length === 0) return bitString(Buffer.alloc(0));
+  for (const bit of bits) {
+    if (!Number.isInteger(bit) || bit < 0 || bit > 255) {
+      throw new RangeError("named bits must be integers 0..255");
+    }
+  }
+  const highest = Math.max(...bits);
+  const bytes = Buffer.alloc((highest >> 3) + 1);
+  for (const bit of bits) {
+    bytes[bit >> 3] = (bytes[bit >> 3] ?? 0) | (0x80 >> (bit & 7));
+  }
+  return bitString(bytes, 7 - (highest & 7));
+}
+
+export function octetString(bytes: Buffer): Buffer {
+  return tlv(TAG.octetString, bytes);
+}
+
+export function utf8String(value: string): Buffer {
+  const bytes = Buffer.from(value, "utf8");
+  // Buffer.from silently turns a lone surrogate into U+FFFD; refuse instead.
+  if (bytes.toString("utf8") !== value) {
+    throw new Error("UTF8String must be well-formed Unicode");
+  }
+  return tlv(TAG.utf8String, bytes);
+}
+
+export function printableString(value: string): Buffer {
+  if (!/^[A-Za-z0-9 '()+,\-./:=?]*$/.test(value)) {
+    throw new Error("value is outside the PrintableString alphabet");
+  }
+  return tlv(TAG.printableString, Buffer.from(value, "ascii"));
+}
+
+export function ia5String(value: string): Buffer {
+  if (!/^[\x00-\x7f]*$/.test(value)) {
+    throw new Error("value is outside the IA5String alphabet");
+  }
+  return tlv(TAG.ia5String, Buffer.from(value, "ascii"));
+}
+
+function wholeSeconds(date: Date): void {
+  if (!Number.isFinite(date.getTime())) throw new RangeError("invalid date");
+  // X.509 times carry no fraction (RFC 5280 §4.1.2.5); refuse rather than
+  // truncate, so the caller's notBefore/notAfter is exactly what is signed.
+  if (date.getUTCMilliseconds() !== 0) {
+    throw new RangeError("certificate times must be whole seconds");
+  }
+}
+
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, "0");
+}
+
+function monthToSecond(date: Date): string {
+  return (
+    pad(date.getUTCMonth() + 1, 2) +
+    pad(date.getUTCDate(), 2) +
+    pad(date.getUTCHours(), 2) +
+    pad(date.getUTCMinutes(), 2) +
+    pad(date.getUTCSeconds(), 2)
+  );
+}
+
+/** YYMMDDHHMMSSZ — RFC 5280 reads YY ≥ 50 as 19YY, so only 1950–2049 fit. */
+export function utcTime(date: Date): Buffer {
+  wholeSeconds(date);
+  const year = date.getUTCFullYear();
+  if (year < 1950 || year > 2049) {
+    throw new RangeError("UTCTime covers 1950 through 2049 only");
+  }
+  return tlv(TAG.utcTime, Buffer.from(`${pad(year % 100, 2)}${monthToSecond(date)}Z`, "ascii"));
+}
+
+/** YYYYMMDDHHMMSSZ, no fractional seconds (RFC 5280 §4.1.2.5.2). */
+export function generalizedTime(date: Date): Buffer {
+  wholeSeconds(date);
+  const year = date.getUTCFullYear();
+  if (year < 0 || year > 9999) {
+    throw new RangeError("GeneralizedTime covers years 0000 through 9999");
+  }
+  return tlv(TAG.generalizedTime, Buffer.from(`${pad(year, 4)}${monthToSecond(date)}Z`, "ascii"));
+}
+
+/** RFC 5280 §4.1.2.5: UTCTime through 2049, GeneralizedTime from 2050 on. */
+export function time(date: Date): Buffer {
+  const year = date.getUTCFullYear();
+  return year >= 1950 && year <= 2049 ? utcTime(date) : generalizedTime(date);
+}
+
+function checkTagNumber(tagNumber: number): number {
+  if (!Number.isInteger(tagNumber) || tagNumber < 0 || tagNumber > MAX_TAG_NUMBER) {
+    throw new RangeError(`context tag number must be 0..${MAX_TAG_NUMBER}`);
+  }
+  return tagNumber;
+}
+
+/** `[n] EXPLICIT`: a constructed context-specific TLV wrapping the whole inner
+ *  TLV (e.g. the certificate version `A0 03 02 01 02`). */
+export function explicit(tagNumber: number, inner: Buffer): Buffer {
+  return tlv(CONTEXT_SPECIFIC | CONSTRUCTED | checkTagNumber(tagNumber), inner);
+}
+
+/**
+ * `[n] IMPLICIT`: the context-specific tag REPLACES the inner type's own tag,
+ * keeping its length and content octets and its constructed bit — e.g. a
+ * SAN dNSName is `[2] IMPLICIT IA5String`, `82 len name`. Takes the encoded
+ * inner TLV so callers reuse the typed encoders above.
+ */
+export function implicit(tagNumber: number, inner: Buffer): Buffer {
+  const identifier = inner[0];
+  if (identifier === undefined || inner.length < 2 || (identifier & 0x1f) === 0x1f) {
+    throw new Error("implicit tagging needs a complete low-tag-number TLV");
+  }
+  return Buffer.concat([
+    Buffer.from([CONTEXT_SPECIFIC | (identifier & CONSTRUCTED) | checkTagNumber(tagNumber)]),
+    inner.subarray(1),
+  ]);
+}