@runuai/host 0.9.147 → 0.9.149

package/lib/secrets-proxy/container-steps.ts

@@ -0,0 +1,138 @@
+/**
+ * The root-side steps that put a running task behind the secrets proxy
+ * (ADR-153 §3 "Order"), run through the task environment's bounded exec:
+ * the CA bundle into its trust store, then the pinned names and the NAT
+ * chain. task-up runs the same scripts at a container start; these run them
+ * on a running task — after a runner restart, when the CA bundle changes, and
+ * when the task's proxied domains do.
+ *
+ * Every step is a reconciliation (safe to repeat), and every failure throws:
+ * the caller withholds the task's proxied keys until a step succeeds, since a
+ * placeholder whose domain is not pinned, or whose CA the task does not
+ * trust, would only fail later and less clearly.
+ */
+
+import type { TaskEnvironmentExecResult, TaskEnvironmentHandle } from "../task-environment/types";
+import { ROOT_SCRIPT_PATH, caInstallScript, hostsReconcileScript, redirectChainScript } from "./task-scripts";
+
+const STEP_TIMEOUT_MS = 60_000;
+const STEP_OUTPUT_BYTES = 64 * 1024;
+/** The shell itself starts clean, not only the script's children: the
+ *  inherited PATH and loader variables can name task-writable files. */
+const ROOT_STEP_ENV: Readonly<Record<string, string>> = Object.freeze({
+  PATH: ROOT_SCRIPT_PATH,
+  LD_PRELOAD: "",
+  LD_AUDIT: "",
+  LD_LIBRARY_PATH: "",
+});
+
+type Exec = Pick<TaskEnvironmentHandle<unknown>, "exec">;
+
+function checked(step: string, result: TaskEnvironmentExecResult): void {
+  if (result.exitCode === 0 && result.signal === null && !result.stdoutTruncated && !result.stderrTruncated) return;
+  const detail =
+    Buffer.from(result.stderr).toString("utf8").trim().slice(-512) ||
+    (result.signal === null ? `exit ${String(result.exitCode)}` : `signal ${result.signal}`);
+  throw new Error(`secrets proxy: ${step} failed in the task: ${detail}`);
+}
+
+/** Installs the bundle (`SecretsProxyRuntime.caBundlePem()`) as root. The
+ *  PEM travels on stdin; it is public, but argv stays short and fixed. */
+export async function installTaskTrust(environment: Exec, bundlePem: string): Promise<void> {
+  const result = await environment.exec({
+    argv: ["/bin/sh", "-c", caInstallScript()],
+    user: "root",
+    env: ROOT_STEP_ENV,
+    projectEnvProfile: "maintenance",
+    stdin: Buffer.from(bundlePem, "utf8"),
+    timeoutMs: STEP_TIMEOUT_MS,
+    maxOutputBytes: STEP_OUTPUT_BYTES,
+  });
+  checked("installing the proxy CA", result);
+}
+
+/** Where a task's NET_ADMIN comes from: each privileged exec (Docker); the
+ *  task VM itself, fixed when it was created (Apple); or the root that runs
+ *  the step (a machine's sidecar, root on the task's own machine). */
+export type TaskNetAdmin = "per-exec" | "from-creation" | "root";
+
+/**
+ * Pins `domains` to the task-local listener: the NAT chain that sends the pin
+ * address's :443 to `listenPort` (the task forwarder), and the /etc/hosts
+ * block that points the names there. The chain needs NET_ADMIN: on Docker
+ * the one privileged exec Uai makes; an Apple task's VM holds it from its
+ * creation, so there a root exec has it (and lacking it proves the VM never
+ * had it). Ordered so a failure part-way never leaves a name pointing at a
+ * pin with nothing behind it: when pinning, the chain goes first; when
+ * unpinning, the names go first. With no domains the block is removed and
+ * the chain emptied.
+ */
+export async function reconcileTaskPins(
+  environment: Exec,
+  options: {
+    domains: readonly string[];
+    listenPort: number;
+    netAdmin: TaskNetAdmin;
+    /** Redirect only this user's traffic (a machine, where the sidecar's own
+     *  upstream connections share the network); everyone's otherwise. */
+    uidOwner?: string;
+    /** Pin the names in this view of the hosts, built from `from`, rather
+     *  than in /etc/hosts itself (a machine, whose /etc/hosts the root
+     *  sidecar shares). The pins count only while `proven` says every task
+     *  process sees the view. */
+    hostsView?: { readonly path: string; readonly from: string; readonly proven: () => boolean };
+  },
+): Promise<void> {
+  const enabled = options.domains.length > 0;
+  // Both generated first: a domain that is not canonical and proxiable is
+  // refused before anything runs.
+  const hosts =
+    options.hostsView === undefined
+      ? hostsReconcileScript(options.domains)
+      : hostsReconcileScript(options.domains, options.hostsView.path, { sourcePath: options.hostsView.from });
+  const chain = redirectChainScript({
+    toPort: options.listenPort,
+    enabled,
+    netAdminFromCreation: options.netAdmin === "from-creation",
+    ...(options.uidOwner === undefined ? {} : { uidOwner: options.uidOwner }),
+  });
+  const hostsStep = async (): Promise<void> => {
+    const pinned = await environment.exec({
+      argv: ["/bin/sh", "-c", hosts],
+      user: "root",
+      env: ROOT_STEP_ENV,
+      projectEnvProfile: "maintenance",
+      timeoutMs: STEP_TIMEOUT_MS,
+      maxOutputBytes: STEP_OUTPUT_BYTES,
+    });
+    checked("pinning the proxied names", pinned);
+  };
+  const chainStep = async (): Promise<void> => {
+    const redirected = await environment.exec({
+      argv: ["/bin/sh", "-c", chain],
+      user: "root",
+      env: ROOT_STEP_ENV,
+      ...(options.netAdmin === "per-exec" ? { privileged: true as const } : {}),
+      projectEnvProfile: "maintenance",
+      timeoutMs: STEP_TIMEOUT_MS,
+      maxOutputBytes: STEP_OUTPUT_BYTES,
+    });
+    checked("redirecting the proxied names", redirected);
+  };
+  if (enabled) {
+    await chainStep();
+    await hostsStep();
+    // With a view, pins count only while every task process sees it: one
+    // a runner without the view started resolves the real names and goes
+    // around the proxy. Until then the step fails and the keys stay withheld.
+    if (options.hostsView !== undefined && !options.hostsView.proven()) {
+      throw new Error(
+        "secrets proxy: processes this task started before its hosts view may still run; " +
+          "its proxied keys stay withheld until its machine reboots",
+      );
+    }
+  } else {
+    await hostsStep();
+    await chainStep();
+  }
+}

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),
+  ]);
+}