@moondeck/station 0.0.0-stage → 1.0.0

package/lib/secrets-proxy/ca.ts

@@ -0,0 +1,470 @@
+/**
+ * The secrets proxy's certificate authority (ADR-153 §3 "The CA").
+ *
+ * One ECDSA P-256 CA per runner signs short-lived per-domain leaves that the
+ * proxy presents to a task on the domains it declares. Tasks trust this CA;
+ * the proxy's own upstream verification uses public roots, which can never
+ * include it.
+ *
+ * Two rules keep a bug here from turning into a leak:
+ *  - The CA private key is a KeyObject closed over by a signing callback. The
+ *    certificate builder hands it finished TBS bytes and embeds the signature
+ *    it gets back; it never receives key material.
+ *  - Every certificate is parsed back with node:crypto's X509Certificate and
+ *    checked straight after minting (CA-ness, SAN, EKU, issuer, signature,
+ *    key match, validity, serial). Any failure throws, and callers treat a
+ *    throw as "withhold": no handshake is ever answered with a certificate we
+ *    could not prove correct.
+ */
+
+import {
+  X509Certificate,
+  createHash,
+  createPrivateKey,
+  generateKeyPairSync,
+  randomBytes,
+  sign,
+  type KeyObject,
+} from "node:crypto";
+
+import * as der from "./der";
+import { canonicalHostname } from "./hostname";
+
+const OID = {
+  ecdsaWithSha256: "1.2.840.10045.4.3.2",
+  commonName: "2.5.4.3",
+  subjectKeyIdentifier: "2.5.29.14",
+  keyUsage: "2.5.29.15",
+  subjectAltName: "2.5.29.17",
+  basicConstraints: "2.5.29.19",
+  authorityKeyIdentifier: "2.5.29.35",
+  extKeyUsage: "2.5.29.37",
+  serverAuth: "1.3.6.1.5.5.7.3.1",
+} as const;
+
+/** KeyUsage named bits (RFC 5280 §4.2.1.3). */
+const KEY_USAGE = { digitalSignature: 0, keyCertSign: 5, cRLSign: 6 } as const;
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+/** Certificates start five minutes early so a task whose clock runs a little
+ *  behind the runner's (a VM after resume) still accepts a fresh leaf. */
+const BACKDATE_MS = 5 * MINUTE_MS;
+const MAX_CA_VALIDITY_DAYS = 3_650;
+/** The ADR's leaves live 24 h; this is only the ceiling a caller may ask for. */
+const MAX_LEAF_VALIDITY_HOURS = 7 * 24;
+const DEFAULT_LEAF_VALIDITY_HOURS = 24;
+/** Re-mint an hour before expiry, so a leaf is never served in its last
+ *  hour and a long-lived connection never straddles its notAfter — or a
+ *  quarter of the leaf's life when that is shorter (a short validity, or a
+ *  leaf capped by a CA near its own end), so a cached leaf always has a
+ *  usable window rather than being re-minted on every handshake. */
+const LEAF_RENEW_BEFORE_MS = HOUR_MS;
+const DEFAULT_LEAF_CACHE_ENTRIES = 256;
+
+/** Signs a finished TBSCertificate; the only door to a CA key. */
+export type SignTbs = (tbs: Buffer) => Buffer;
+
+export interface CertificateAuthority {
+  readonly certificatePem: string;
+  readonly certificate: X509Certificate;
+  /** The encoded subject Name, reused byte for byte as every leaf's issuer so
+   *  name matching never depends on a re-encoding. */
+  readonly subjectName: Buffer;
+  readonly keyIdentifier: Buffer;
+  readonly notBefore: number;
+  readonly notAfter: number;
+  readonly sign: SignTbs;
+}
+
+export interface LeafCertificate {
+  readonly hostname: string;
+  readonly certificatePem: string;
+  /** PKCS#8 PEM, because tls.createSecureContext does not accept a KeyObject. */
+  readonly privateKeyPem: string;
+  readonly certificate: X509Certificate;
+  readonly notBefore: number;
+  readonly notAfter: number;
+}
+
+interface CertificateFields {
+  serial: Buffer;
+  issuer: Buffer;
+  subject: Buffer;
+  notBefore: number;
+  notAfter: number;
+  publicKey: KeyObject;
+  extensions: readonly Buffer[];
+}
+
+function floorToSecond(ms: number): number {
+  return Math.floor(ms / 1_000) * 1_000;
+}
+
+/** 16 random octets with the top bit cleared: positive without a sign-guard
+ *  octet, under RFC 5280's 20-octet cap, and never zero. */
+function randomSerial(): Buffer {
+  for (;;) {
+    const serial = randomBytes(16);
+    serial[0] = (serial[0] ?? 0) & 0x7f;
+    if (serial.some((octet) => octet !== 0)) return serial;
+  }
+}
+
+/** X.520's ub-common-name: strict X.509 stacks refuse a longer CN. */
+const MAX_COMMON_NAME = 64;
+
+function distinguishedName(commonName: string): Buffer {
+  return der.sequence(
+    der.set(der.sequence(der.objectIdentifier(OID.commonName), der.utf8String(commonName))),
+  );
+}
+
+/** A leaf's subject: CN = hostname when it fits X.520's bound, otherwise an
+ *  empty Name — RFC 5280 §4.2.1.6 then requires a critical SAN, which is
+ *  where every client looks for the name anyway. */
+function leafSubject(hostname: string): { subject: Buffer; sanCritical: boolean } {
+  return hostname.length <= MAX_COMMON_NAME
+    ? { subject: distinguishedName(hostname), sanCritical: false }
+    : { subject: der.sequence(), sanCritical: true };
+}
+
+/** RFC 7093 §2 method 1: the leftmost 160 bits of SHA-256 over the
+ *  subjectPublicKey bits (the uncompressed EC point). */
+function subjectKeyIdentifier(publicKey: KeyObject): Buffer {
+  const jwk = publicKey.export({ format: "jwk" });
+  if (typeof jwk.x !== "string" || typeof jwk.y !== "string") {
+    throw new Error("expected an EC public key");
+  }
+  const point = Buffer.concat([
+    Buffer.from([0x04]),
+    Buffer.from(jwk.x, "base64url"),
+    Buffer.from(jwk.y, "base64url"),
+  ]);
+  return createHash("sha256").update(point).digest().subarray(0, 20);
+}
+
+/** DER omits `critical` when it is the DEFAULT FALSE. */
+function extension(oid: string, critical: boolean, value: Buffer): Buffer {
+  return der.sequence(
+    der.objectIdentifier(oid),
+    ...(critical ? [der.boolean(true)] : []),
+    der.octetString(value),
+  );
+}
+
+function buildCertificate(fields: CertificateFields, signTbs: SignTbs): Buffer {
+  // ecdsa-with-SHA256 takes no parameters, not even NULL (RFC 5758 §3.2).
+  const algorithm = der.sequence(der.objectIdentifier(OID.ecdsaWithSha256));
+  const tbs = der.sequence(
+    der.explicit(0, der.integer(2)), // v3
+    der.integer(fields.serial),
+    algorithm,
+    fields.issuer,
+    der.sequence(der.time(new Date(fields.notBefore)), der.time(new Date(fields.notAfter))),
+    fields.subject,
+    fields.publicKey.export({ type: "spki", format: "der" }),
+    der.explicit(3, der.sequence(...fields.extensions)),
+  );
+  return der.sequence(tbs, algorithm, der.bitString(signTbs(tbs)));
+}
+
+function validityOf(certificate: X509Certificate): { notBefore: number; notAfter: number } {
+  // validFromDate/validToDate only exist from Node 22.10; the string forms
+  // name the same instants on every supported runtime.
+  const from = certificate.validFromDate ?? new Date(certificate.validFrom);
+  const to = certificate.validToDate ?? new Date(certificate.validTo);
+  return { notBefore: from.getTime(), notAfter: to.getTime() };
+}
+
+function checkValidity(
+  failures: string[],
+  certificate: X509Certificate,
+  expected: { notBefore: number; notAfter: number },
+  maxSpanMs: number,
+): void {
+  const { notBefore, notAfter } = validityOf(certificate);
+  if (notBefore !== expected.notBefore || notAfter !== expected.notAfter) {
+    failures.push("validity is not the requested window");
+  }
+  if (!(notAfter > notBefore) || notAfter - notBefore > maxSpanMs) {
+    failures.push("validity is not bounded");
+  }
+}
+
+function checkSerial(failures: string[], certificate: X509Certificate): void {
+  const serial = certificate.serialNumber;
+  if (!/^[0-9A-Fa-f]+$/.test(serial) || BigInt(`0x${serial}`) <= 0n) {
+    failures.push("serial is not a positive integer");
+  }
+}
+
+function extendedKeyUsage(certificate: X509Certificate): readonly string[] {
+  // Node names the EKU list `keyUsage` (newer releases add `extKeyUsage`);
+  // it is undefined when the extension is absent.
+  const renamed = (certificate as { extKeyUsage?: string[] }).extKeyUsage;
+  return renamed ?? certificate.keyUsage ?? [];
+}
+
+function fail(what: string, failures: readonly string[]): void {
+  if (failures.length > 0) {
+    throw new Error(`${what} failed self-validation: ${failures.join("; ")}`);
+  }
+}
+
+/**
+ * Throws unless `certificate` is a self-signed CA certificate for
+ * `privateKey` over exactly the expected window. Exported for tests.
+ */
+export function validateCertificateAuthority(
+  certificate: X509Certificate,
+  expected: { privateKey: KeyObject; notBefore: number; notAfter: number },
+): void {
+  const failures: string[] = [];
+  // `ca` is X509_check_ca() == 1: basicConstraints CA:TRUE, and a keyUsage
+  // that (when present) allows keyCertSign.
+  if (certificate.ca !== true) failures.push("not a CA certificate");
+  // X509_check_issued: names and key ids chain, and the issuer's keyUsage
+  // allows certificate signing — here, of itself.
+  if (!certificate.checkIssued(certificate)) failures.push("not self-issued");
+  if (!certificate.verify(certificate.publicKey)) failures.push("self-signature does not verify");
+  if (!certificate.checkPrivateKey(expected.privateKey)) failures.push("private key does not match");
+  checkValidity(failures, certificate, expected, MAX_CA_VALIDITY_DAYS * DAY_MS + BACKDATE_MS);
+  checkSerial(failures, certificate);
+  fail("certificate authority", failures);
+}
+
+/**
+ * Throws unless `certificate` is a server leaf for exactly `hostname`, issued
+ * and signed by `authority`, matching `privateKey`, over exactly the expected
+ * window. Exported for tests.
+ */
+export function validateLeafCertificate(
+  certificate: X509Certificate,
+  expected: {
+    authority: CertificateAuthority;
+    hostname: string;
+    privateKey: KeyObject;
+    notBefore: number;
+    notAfter: number;
+  },
+): void {
+  const failures: string[] = [];
+  if (certificate.ca !== false) failures.push("leaf is a CA certificate");
+  if (certificate.subjectAltName !== `DNS:${expected.hostname}`) {
+    failures.push("subjectAltName is not exactly the hostname");
+  }
+  if (!extendedKeyUsage(certificate).includes(OID.serverAuth)) {
+    failures.push("extKeyUsage lacks serverAuth");
+  }
+  if (!certificate.checkIssued(expected.authority.certificate)) {
+    failures.push("not issued by the CA");
+  }
+  if (!certificate.verify(expected.authority.certificate.publicKey)) {
+    failures.push("signature does not verify against the CA");
+  }
+  if (!certificate.checkPrivateKey(expected.privateKey)) failures.push("private key does not match");
+  const matched = certificate.checkHost(expected.hostname, {
+    subject: "never",
+    wildcards: false,
+    partialWildcards: false,
+  });
+  if (matched !== expected.hostname) failures.push("hostname verification fails");
+  checkValidity(failures, certificate, expected, MAX_LEAF_VALIDITY_HOURS * HOUR_MS + BACKDATE_MS);
+  checkSerial(failures, certificate);
+  fail("leaf certificate", failures);
+}
+
+export function createCertificateAuthority(options: {
+  now: number;
+  commonName: string;
+  validityDays: number;
+  /** Receives the new key once, for a store to seal; nothing else sees it. */
+  onPrivateKey?: (privateKey: KeyObject) => unknown;
+}): CertificateAuthority {
+  const { now, commonName, validityDays } = options;
+  if (!Number.isFinite(now)) throw new RangeError("now must be a finite epoch-ms value");
+  // X.520 caps commonName at 64 characters.
+  if (typeof commonName !== "string" || commonName.length < 1 || commonName.length > 64) {
+    throw new RangeError("CA common name must be 1..64 characters");
+  }
+  if (!Number.isInteger(validityDays) || validityDays < 1 || validityDays > MAX_CA_VALIDITY_DAYS) {
+    throw new RangeError(`CA validity must be 1..${MAX_CA_VALIDITY_DAYS} days`);
+  }
+  const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const signTbs: SignTbs = (tbs) => sign("sha256", tbs, { key: privateKey, dsaEncoding: "der" });
+  const notBefore = floorToSecond(now - BACKDATE_MS);
+  const notAfter = floorToSecond(now + validityDays * DAY_MS);
+  const subjectName = distinguishedName(commonName);
+  const keyIdentifier = subjectKeyIdentifier(publicKey);
+  const certificate = new X509Certificate(
+    buildCertificate(
+      {
+        serial: randomSerial(),
+        issuer: subjectName,
+        subject: subjectName,
+        notBefore,
+        notAfter,
+        publicKey,
+        extensions: [
+          extension(OID.basicConstraints, true, der.sequence(der.boolean(true), der.integer(0))),
+          extension(
+            OID.keyUsage,
+            true,
+            der.namedBitString([KEY_USAGE.keyCertSign, KEY_USAGE.cRLSign]),
+          ),
+          extension(OID.subjectKeyIdentifier, false, der.octetString(keyIdentifier)),
+        ],
+      },
+      signTbs,
+    ),
+  );
+  validateCertificateAuthority(certificate, { privateKey, notBefore, notAfter });
+  options.onPrivateKey?.(privateKey);
+  return Object.freeze({
+    certificatePem: certificate.toString(),
+    certificate,
+    subjectName,
+    keyIdentifier,
+    notBefore,
+    notAfter,
+    sign: signTbs,
+  });
+}
+
+/**
+ * Rebuilds a CA handle from what a store kept: the certificate, its PKCS#8
+ * private key and the common name it was created with. Everything is
+ * re-validated exactly as at creation (CA-ness, self-signature, key match,
+ * bounded validity, serial), and the subject must be the one this code
+ * encodes for that name, because every leaf embeds it byte for byte as its
+ * issuer. Throws (withhold) on any mismatch.
+ */
+export function loadCertificateAuthority(stored: {
+  certificatePem: string;
+  privateKeyPem: string;
+  commonName: string;
+}): CertificateAuthority {
+  const certificate = new X509Certificate(stored.certificatePem);
+  const privateKey = createPrivateKey(stored.privateKeyPem);
+  const { notBefore, notAfter } = validityOf(certificate);
+  validateCertificateAuthority(certificate, { privateKey, notBefore, notAfter });
+  if (certificate.subject !== `CN=${stored.commonName}`) {
+    throw new Error("stored certificate authority does not carry its recorded name");
+  }
+  const signTbs: SignTbs = (tbs) => sign("sha256", tbs, { key: privateKey, dsaEncoding: "der" });
+  return Object.freeze({
+    certificatePem: certificate.toString(),
+    certificate,
+    subjectName: distinguishedName(stored.commonName),
+    keyIdentifier: subjectKeyIdentifier(certificate.publicKey),
+    notBefore,
+    notAfter,
+    sign: signTbs,
+  });
+}
+
+export function mintLeafCertificate(options: {
+  ca: CertificateAuthority;
+  hostname: string;
+  now: number;
+  validityHours?: number;
+}): LeafCertificate {
+  const { ca, hostname, now, validityHours = DEFAULT_LEAF_VALIDITY_HOURS } = options;
+  if (canonicalHostname(hostname) !== hostname) {
+    throw new Error("leaf hostname must be a canonical DNS name");
+  }
+  if (!Number.isFinite(now)) throw new RangeError("now must be a finite epoch-ms value");
+  if (!(validityHours > 0) || validityHours > MAX_LEAF_VALIDITY_HOURS) {
+    throw new RangeError(`leaf validity must be within (0, ${MAX_LEAF_VALIDITY_HOURS}] hours`);
+  }
+  const notBefore = floorToSecond(now - BACKDATE_MS);
+  // Past the CA's notAfter the chain fails anyway; a leaf never claims more.
+  const notAfter = Math.min(floorToSecond(now + validityHours * HOUR_MS), ca.notAfter);
+  if (now < ca.notBefore || notAfter <= now) {
+    throw new Error("certificate authority is outside its validity window");
+  }
+  const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const { subject, sanCritical } = leafSubject(hostname);
+  const certificate = new X509Certificate(
+    buildCertificate(
+      {
+        serial: randomSerial(),
+        issuer: ca.subjectName,
+        subject,
+        notBefore,
+        notAfter,
+        publicKey,
+        extensions: [
+          // CA:FALSE is the DEFAULT, so DER encodes it as an empty SEQUENCE.
+          extension(OID.basicConstraints, true, der.sequence()),
+          extension(OID.keyUsage, true, der.namedBitString([KEY_USAGE.digitalSignature])),
+          extension(OID.extKeyUsage, false, der.sequence(der.objectIdentifier(OID.serverAuth))),
+          extension(
+            OID.subjectAltName,
+            sanCritical,
+            der.sequence(der.implicit(2, der.ia5String(hostname))),
+          ),
+          extension(OID.subjectKeyIdentifier, false, der.octetString(subjectKeyIdentifier(publicKey))),
+          extension(
+            OID.authorityKeyIdentifier,
+            false,
+            der.sequence(der.implicit(0, der.octetString(ca.keyIdentifier))),
+          ),
+        ],
+      },
+      ca.sign,
+    ),
+  );
+  validateLeafCertificate(certificate, { authority: ca, hostname, privateKey, notBefore, notAfter });
+  return Object.freeze({
+    hostname,
+    certificatePem: certificate.toString(),
+    privateKeyPem: String(privateKey.export({ type: "pkcs8", format: "pem" })),
+    certificate,
+    notBefore,
+    notAfter,
+  });
+}
+
+/** The CA handle the proxy engine takes: leaves minted on demand, cached per
+ *  hostname, and re-minted an hour before they expire. */
+export interface LeafCertificateCache {
+  readonly authority: CertificateAuthority;
+  /** A valid leaf for a canonical hostname. Throws (withhold) when minting or
+   *  self-validation fails. */
+  leafFor(hostname: string): LeafCertificate;
+}
+
+export function createLeafCertificateCache(options: {
+  ca: CertificateAuthority;
+  now?: () => number;
+  validityHours?: number;
+  maxEntries?: number;
+}): LeafCertificateCache {
+  const { ca, now = Date.now, validityHours = DEFAULT_LEAF_VALIDITY_HOURS } = options;
+  const maxEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_LEAF_CACHE_ENTRIES));
+  const leaves = new Map<string, LeafCertificate>();
+  return {
+    authority: ca,
+    leafFor(hostname: string): LeafCertificate {
+      const at = now();
+      const cached = leaves.get(hostname);
+      if (cached !== undefined) {
+        const renewBefore = Math.min(LEAF_RENEW_BEFORE_MS, (cached.notAfter - cached.notBefore) / 4);
+        if (at >= cached.notBefore && at < cached.notAfter - renewBefore) return cached;
+      }
+      leaves.delete(hostname);
+      const leaf = mintLeafCertificate({ ca, hostname, now: at, validityHours });
+      // Only declared domains reach here (the SNI check runs first), so the
+      // cap is a backstop against a pathological declaration, not an LRU.
+      if (leaves.size >= maxEntries) {
+        const oldest = leaves.keys().next();
+        if (oldest.done !== true) leaves.delete(oldest.value);
+      }
+      leaves.set(hostname, leaf);
+      return leaf;
+    },
+  };
+}

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