@runuai/host 0.9.149 → 0.9.151

package/lib/credential-consumers/github.ts

@@ -0,0 +1,594 @@
+/**
+ * ADR-154 §6, §12 on the runner: a task owner's GitHub sign-in and SSH key,
+ * from the task's lease.
+ *
+ * - The registry installs each grant and credential change here; the token
+ *   and key live in memory for the task's run only. A credential the
+ *   manifest names but the lease could not read is held as unavailable, never
+ *   as absent: whoever asks for it fails and retries, and never falls back to
+ *   another transport as if the person had none.
+ * - Task-up's clone and fetches hold them (`holdTaskGitCredentials`) for
+ *   the exact assignment, only while the registry's gate is open on it;
+ *   nothing reads the runner's own store. A hold is the operation's only
+ *   access: a gate that closes, or a cleanup that takes either credential,
+ *   aborts it and waits for its release, so nothing uses them after.
+ * - Inside the task they are written only by streaming over an exec's stdin,
+ *   in a clean environment (`env -i`, absolute paths): the token into the
+ *   managed `gh` configuration (file-backed, never a keyring), the key where
+ *   ADR-029 puts it, each file through an intermediate renamed into place
+ *   without following anything the task put in the way. What git needs from
+ *   them (credential helper, transport, signing) is in files the global git
+ *   configuration includes, so the cleanup that deletes the credential's
+ *   files takes its configuration too. Every path, intermediates included,
+ *   is recorded in the cleanup inventory before anything is written to it.
+ * - Writes for one task run one at a time, and each exec is admitted at the
+ *   provider's last moment against the task's live state: the same
+ *   assignment, the same credential revision, not sealed. A cleanup seals
+ *   (or drops the credentials it names), then waits for every write under
+ *   way to end, so nothing it is about to delete can be written again after.
+ */
+
+import {
+  CredentialLeaseUnavailableError,
+  type CredentialCleanupRequest,
+  type CredentialInstallRequest,
+  type GithubLeasedValue,
+  type SshLeasedValue,
+  type TaskAssignment,
+  type TaskCredentialView,
+  type TaskStaticCredential,
+} from "../cloud-credential-leases";
+import { rememberCredentialCleanupPath } from "../credential-cleanup-inventory";
+import {
+  assertTaskRuntime,
+  runInTask as run,
+  STAGED_SUFFIX,
+  TASK_FILE_WRITE_HELPER,
+  withStaged,
+  writeTaskFileArgv as writeFileArgv,
+  type TaskWriteEnvironment as Environment,
+} from "./task-files";
+
+export { STAGED_SUFFIX, TASK_FILE_WRITE_HELPER };
+
+export interface LeasedGithub {
+  credentialId: string;
+  revision: string;
+  token: string;
+}
+
+export interface LeasedSshKey {
+  credentialId: string;
+  revision: string;
+  privateKey: string;
+  publicKey: string;
+}
+
+/** A manifest lane: not named, named but unreadable, or in hand. */
+type Slot<T extends { credentialId: string; revision: string }> =
+  | { kind: "absent" }
+  | { kind: "unavailable"; credentialId: string; revision: string }
+  | { kind: "present"; value: T };
+
+interface CredentialIdentity {
+  credentialId: string;
+  revision: string;
+}
+
+/** One host-side git operation's hold on the owner's credentials. */
+interface GitHold {
+  controller: AbortController;
+  /** The credentials it was given: what a cleanup must take it for. */
+  github: CredentialIdentity | null;
+  ssh: CredentialIdentity | null;
+  released: Promise<void>;
+  release(): void;
+}
+
+interface TaskPersonCredentials {
+  assignment: TaskAssignment;
+  /** What the registry's gate opened on (the exact committed view): the
+   *  only thing holds and writers read. Absent while closed. */
+  github: Slot<LeasedGithub>;
+  ssh: Slot<LeasedSshKey>;
+  /** What the last install proposed: never served until a gate opens on it. */
+  candidate: { github: Slot<LeasedGithub>; ssh: Slot<LeasedSshKey> };
+  /** The registry's gate for this run: nothing is held or written while
+   *  closed. */
+  open: boolean;
+  /** Host-side git operations holding the credentials now. */
+  holds: Set<GitHold>;
+  /** A full cleanup began: no write is admitted again for this run. */
+  sealed: boolean;
+  /** The writes for this task, one after another. */
+  queue: Promise<void>;
+  /** Writes admitted and not yet ended. */
+  writing: number;
+  drained: Array<() => void>;
+}
+
+const byTask = new Map<string, TaskPersonCredentials>();
+
+function slotOf<T extends GithubLeasedValue | SshLeasedValue, V extends { credentialId: string; revision: string }>(
+  credential: TaskStaticCredential<T> | null,
+  value: (material: Readonly<T>) => Omit<V, "credentialId" | "revision">,
+): Slot<V> {
+  if (!credential) return { kind: "absent" };
+  const identity = { credentialId: credential.manifest.credentialId, revision: credential.manifest.revision };
+  if (credential.availability !== "available" || !credential.material) return { kind: "unavailable", ...identity };
+  return { kind: "present", value: { ...identity, ...value(credential.material) } as V };
+}
+
+function slotsOf(view: TaskCredentialView): { github: Slot<LeasedGithub>; ssh: Slot<LeasedSshKey> } {
+  return {
+    github: slotOf<GithubLeasedValue, LeasedGithub>(view.github, (material) => ({ token: material.token })),
+    ssh: slotOf<SshLeasedValue, LeasedSshKey>(view.ssh, (material) => ({
+      privateKey: material.privateKey,
+      publicKey: material.publicKey,
+    })),
+  };
+}
+
+/** The same credential at the same revision, both readable. */
+function sameIdentity<T extends CredentialIdentity>(a: Slot<T>, b: Slot<T>): boolean {
+  return (
+    a.kind === "present" &&
+    b.kind === "present" &&
+    a.value.credentialId === b.value.credentialId &&
+    a.value.revision === b.value.revision
+  );
+}
+
+/**
+ * Install the owner's GitHub sign-in and SSH key from a grant or a change:
+ * a candidate, served by nothing until the registry opens its gate on it. A
+ * credential change of this run takes effect now on a credential already
+ * served that is otherwise the same (a newer version of it).
+ */
+export function installPersonCredentials(request: CredentialInstallRequest): void {
+  const candidate = slotsOf(request.next);
+  const current = byTask.get(request.assignment.taskId);
+  if (current && !current.sealed && sameAssignment(current.assignment, request.assignment)) {
+    // The same run: its queue and the writes under way kept, each admitted
+    // against what is served at its moment.
+    current.candidate = candidate;
+    if (request.reason === "credential-change" && current.open) {
+      if (sameIdentity(current.github, candidate.github)) current.github = candidate.github;
+      if (sameIdentity(current.ssh, candidate.ssh)) current.ssh = candidate.ssh;
+    }
+    return;
+  }
+  // A new run, or one after a full cleanup began: a fresh state, so nothing
+  // queued for the old one is ever admitted for it.
+  byTask.set(request.assignment.taskId, {
+    assignment: { ...request.assignment },
+    github: { kind: "absent" },
+    ssh: { kind: "absent" },
+    candidate,
+    open: false,
+    holds: new Set(),
+    sealed: false,
+    queue: Promise.resolve(),
+    writing: 0,
+    drained: [],
+  });
+}
+
+/**
+ * Drop what a cleanup names from memory, then wait for every write under way
+ * for this task to end: a full cleanup seals the task first, a selective one
+ * drops the credentials it names, so no exec is admitted for them again and
+ * the inventoried paths cannot be written after the coordinator deletes them.
+ */
+export async function cleanupPersonCredentials(request: CredentialCleanupRequest): Promise<void> {
+  const current = byTask.get(request.assignment.taskId);
+  if (!current || !sameAssignment(current.assignment, request.assignment)) return;
+  // The exact identity a cleanup names: its revision too, when it names one,
+  // so a stale revision's cleanup never takes a newer one of the same id.
+  const takes = (credentialClass: "github" | "ssh", identity: CredentialIdentity | null) =>
+    request.mode === "full" ||
+    (identity !== null &&
+      request.removed.some(
+        (removed) =>
+          removed.class === credentialClass &&
+          removed.credentialId === identity.credentialId &&
+          (removed.revision === null || removed.revision === identity.revision),
+      ));
+  const identityOf = (slot: Slot<CredentialIdentity>): CredentialIdentity | null =>
+    slot.kind === "present"
+      ? { credentialId: slot.value.credentialId, revision: slot.value.revision }
+      : slot.kind === "unavailable"
+        ? { credentialId: slot.credentialId, revision: slot.revision }
+        : null;
+  if (request.mode === "full") {
+    current.sealed = true;
+    current.open = false;
+    current.github = { kind: "absent" };
+    current.ssh = { kind: "absent" };
+    current.candidate = { github: { kind: "absent" }, ssh: { kind: "absent" } };
+  } else {
+    if (takes("github", identityOf(current.github))) current.github = { kind: "absent" };
+    if (takes("ssh", identityOf(current.ssh))) current.ssh = { kind: "absent" };
+    if (takes("github", identityOf(current.candidate.github))) current.candidate.github = { kind: "absent" };
+    if (takes("ssh", identityOf(current.candidate.ssh))) current.candidate.ssh = { kind: "absent" };
+  }
+  // Every operation holding what this takes stops now; with every one a gate
+  // close already stopped, whatever narrowed, each is waited for.
+  const taken = [...current.holds].filter(
+    (hold) => hold.controller.signal.aborted || takes("github", hold.github) || takes("ssh", hold.ssh),
+  );
+  for (const hold of taken) hold.controller.abort(new PersonCredentialWriteRefused());
+  await Promise.all([drain(current), ...taken.map((hold) => hold.released)]);
+  if (request.mode === "full" && byTask.get(request.assignment.taskId) === current) {
+    byTask.delete(request.assignment.taskId);
+  }
+}
+
+function drain(state: TaskPersonCredentials): Promise<void> {
+  if (state.writing === 0) return Promise.resolve();
+  return new Promise((resolve) => state.drained.push(resolve));
+}
+
+/** Process shutdown: every GitHub sign-in or SSH key write under way, for
+ *  any task, over: an exec it had admitted ends, the next one is refused. */
+export function drainPersonCredentialWrites(): Promise<void> {
+  return Promise.all([...byTask.values()].map(drain)).then(() => undefined);
+}
+
+/** The live state for this exact assignment, or a failure: never "none". */
+/** The live, open state for this exact assignment, or a failure: never
+ *  "none". Nothing is read, held or written while the gate is closed. */
+function liveState(assignment: TaskAssignment): TaskPersonCredentials {
+  const state = byTask.get(assignment.taskId);
+  if (!state || state.sealed || !sameAssignment(state.assignment, assignment)) {
+    throw new CredentialLeaseUnavailableError("the task's credentials are not installed for this run");
+  }
+  if (!state.open) throw new CredentialLeaseUnavailableError("the task's credentials are not open for this run");
+  return state;
+}
+
+/** The registry opened its gate on this exact committed view: serve exactly
+ *  its GitHub sign-in and SSH key. An older run's opening changes nothing. */
+export function openPersonCredentialGate(assignment: TaskAssignment, view: TaskCredentialView): void {
+  const state = byTask.get(assignment.taskId);
+  if (!state || state.sealed || !sameAssignment(state.assignment, assignment)) return;
+  const served = slotsOf(view);
+  state.github = served.github;
+  state.ssh = served.ssh;
+  state.open = true;
+}
+
+/** The registry closed its gate: nothing is served, held or written, and
+ *  every operation holding the credentials of this run or an older one
+ *  stops now. */
+export function closePersonCredentialGate(assignment: TaskAssignment): void {
+  const state = byTask.get(assignment.taskId);
+  if (!state || state.assignment.runEpoch > assignment.runEpoch) return;
+  state.open = false;
+  state.github = { kind: "absent" };
+  state.ssh = { kind: "absent" };
+  for (const hold of state.holds) hold.controller.abort(new PersonCredentialWriteRefused());
+}
+
+/** A host-side git operation's hold on the owner's GitHub sign-in and SSH
+ *  key (task-up's clone and fetches). */
+export interface TaskGitCredentialHold {
+  /** The exact run it was given for: providers refuse it for any other. */
+  assignment: Readonly<TaskAssignment>;
+  /** Null only when the manifest names no GitHub sign-in. */
+  github: LeasedGithub | null;
+  /** Null only when the manifest names no SSH key. */
+  ssh: LeasedSshKey | null;
+  /** Aborted when the gate closes or a cleanup takes either credential:
+   *  the operation stops using them at once, then releases. */
+  signal: AbortSignal;
+  /** The operation no longer uses them. Idempotent. */
+  release(): void;
+}
+
+/**
+ * Hold the owner's GitHub sign-in and SSH key for one host-side git
+ * operation of the exact assignment, while the registry's gate is open on
+ * it. Throws `CredentialLeaseUnavailableError` when the gate is closed, the
+ * run moved on, or the manifest names a credential the lease could not
+ * read: the caller retries or fails, and never clones another way as if
+ * there were none. A cleanup waits for the hold's release.
+ */
+export function holdTaskGitCredentials(assignment: TaskAssignment): TaskGitCredentialHold {
+  const state = liveState(assignment);
+  if (state.github.kind === "unavailable") throw new CredentialLeaseUnavailableError("the GitHub sign-in could not be read");
+  if (state.ssh.kind === "unavailable") throw new CredentialLeaseUnavailableError("the SSH key could not be read");
+  const github = state.github.kind === "present" ? state.github.value : null;
+  const ssh = state.ssh.kind === "present" ? state.ssh.value : null;
+  const controller = new AbortController();
+  let release!: () => void;
+  const released = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const hold: GitHold = {
+    controller,
+    github: github && { credentialId: github.credentialId, revision: github.revision },
+    ssh: ssh && { credentialId: ssh.credentialId, revision: ssh.revision },
+    released,
+    release: () => {
+      state.holds.delete(hold);
+      release();
+    },
+  };
+  state.holds.add(hold);
+  return { assignment: { ...assignment }, github, ssh, signal: controller.signal, release: hold.release };
+}
+
+/**
+ * The task owner's GitHub token for task-up's clone, for the exact
+ * assignment: null only when the manifest names no GitHub sign-in. Throws
+ * when it names one the lease could not read, or the run moved on: the
+ * caller retries or fails, and never clones another way as if there were
+ * none.
+ */
+export function leasedGithubToken(assignment: TaskAssignment): { accessToken: string; expiresAt: null } | null {
+  const slot = liveState(assignment).github;
+  if (slot.kind === "absent") return null;
+  if (slot.kind === "unavailable") throw new CredentialLeaseUnavailableError("the GitHub sign-in could not be read");
+  return { accessToken: slot.value.token, expiresAt: null };
+}
+
+/** The task owner's SSH key for the exact assignment: null only when the
+ *  manifest names none; throws when it names one the lease could not read. */
+export function leasedSshKey(assignment: TaskAssignment): LeasedSshKey | null {
+  const slot = liveState(assignment).ssh;
+  if (slot.kind === "absent") return null;
+  if (slot.kind === "unavailable") throw new CredentialLeaseUnavailableError("the SSH key could not be read");
+  return slot.value;
+}
+
+/** Tests only. */
+export function resetLeasedPersonCredentialsForTests(): void {
+  byTask.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Writing them into the task
+// ---------------------------------------------------------------------------
+
+export const TASK_GH_HOSTS_PATH = "/home/node/.config/gh/hosts.yml";
+/** The GitHub sign-in's git configuration: credential helper, HTTPS transport. */
+export const TASK_GH_GITCONFIG_PATH = "/home/node/.config/gh/uai.gitconfig";
+export const TASK_SSH_KEY_PATH = "/home/node/.ssh/id_ed25519";
+export const TASK_SSH_PUBLIC_KEY_PATH = "/home/node/.ssh/id_ed25519.pub";
+export const TASK_SSH_ALLOWED_SIGNERS_PATH = "/home/node/.ssh/allowed_signers";
+/** The key's signing configuration (ADR-029). */
+export const TASK_SSH_SIGNING_GITCONFIG_PATH = "/home/node/.ssh/uai-signing.gitconfig";
+/** SSH as git's transport to GitHub, while the task has no GitHub sign-in. */
+export const TASK_SSH_TRANSPORT_GITCONFIG_PATH = "/home/node/.ssh/uai-transport.gitconfig";
+/** The writer's step was refused: the run, the revision or the gate moved. */
+export class PersonCredentialWriteRefused extends Error {
+  constructor() {
+    super("the task's credentials changed or were cleaned up; the write was not made");
+    this.name = "PersonCredentialWriteRefused";
+  }
+}
+
+/**
+ * Queue one write for the task: it starts once the writes before it ended,
+ * counts as under way until it ends (a cleanup waits for it), and each of
+ * its execs is admitted only while `stillCurrent` holds for the task's live
+ * state at that moment.
+ */
+function enqueueWrite(
+  assignment: TaskAssignment,
+  write: (admit: () => void, current: () => TaskPersonCredentials) => Promise<boolean>,
+): Promise<boolean> {
+  let state: TaskPersonCredentials;
+  try {
+    state = liveState(assignment);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  state.writing += 1;
+  const settle = (): void => {
+    state.writing -= 1;
+    if (state.writing === 0) for (const resolve of state.drained.splice(0)) resolve();
+  };
+  const current = (): TaskPersonCredentials => {
+    const live = byTask.get(assignment.taskId);
+    // Every admission: this exact run's state, its gate open on the view it
+    // serves now.
+    if (live !== state || state.sealed || !state.open || !sameAssignment(state.assignment, assignment)) {
+      throw new PersonCredentialWriteRefused();
+    }
+    return state;
+  };
+  const result = state.queue.then(() => write(() => void current(), current));
+  state.queue = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  return result.finally(settle);
+}
+
+/**
+ * Have the global git configuration include `path`, once. Everything a
+ * credential needs from git lives in such a file, inventoried with the
+ * credential: the cleanup that deletes it takes the configuration with it,
+ * and git ignores an include whose file is gone.
+ */
+function includeOnce(path: string): string {
+  return (
+    `/usr/bin/git config --global --get-all --fixed-value include.path '${path}' >/dev/null || ` +
+    `/usr/bin/git config --global --add include.path '${path}'`
+  );
+}
+
+/** The GitHub sign-in's git configuration: `gh` is git's credential helper
+ *  for GitHub, and git reaches GitHub over HTTPS. */
+const GITHUB_GITCONFIG = [
+  '[credential "https://github.com"]',
+  "\thelper =",
+  "\thelper = !/usr/bin/gh auth git-credential",
+  '[credential "https://gist.github.com"]',
+  "\thelper =",
+  "\thelper = !/usr/bin/gh auth git-credential",
+  '[url "https://github.com/"]',
+  "\tinsteadOf = git@github.com:",
+  "\tinsteadOf = ssh://git@github.com/",
+  "",
+].join("\n");
+
+/** ADR-029: commits and tags signed with the key, verified with its signers file. */
+const SSH_SIGNING_GITCONFIG = [
+  "[gpg]",
+  "\tformat = ssh",
+  '[gpg "ssh"]',
+  `\tallowedSignersFile = ${TASK_SSH_ALLOWED_SIGNERS_PATH}`,
+  "[user]",
+  `\tsigningkey = ${TASK_SSH_PUBLIC_KEY_PATH}`,
+  "[commit]",
+  "\tgpgsign = true",
+  "[tag]",
+  "\tgpgsign = true",
+  "",
+].join("\n");
+
+/** SSH as git's transport to GitHub. */
+const SSH_TRANSPORT_GITCONFIG = [
+  '[url "git@github.com:"]',
+  "\tinsteadOf = https://github.com/",
+  "[core]",
+  "\tsshCommand = ssh -o StrictHostKeyChecking=accept-new",
+  "",
+].join("\n");
+
+/**
+ * `gh` logs in, as root, into a configuration directory of its own in
+ * memory (`/dev/shm`, root-only, removed on the way out), out of the task's
+ * reach: nothing the task does to its own tree while `gh` checks the token
+ * over the network can carry the token's write anywhere. The hosts file `gh`
+ * made is printed for the writer, which puts it in place through the
+ * no-follow helper.
+ */
+const GH_LOGIN_SCRIPT = [
+  "set -eu",
+  "umask 077",
+  "dir=$(/usr/bin/mktemp -d /dev/shm/uai-gh.XXXXXXXX)",
+  "trap '/bin/rm -rf \"$dir\"' EXIT",
+  'GH_CONFIG_DIR="$dir" /usr/bin/gh auth login --with-token --insecure-storage --hostname github.com --git-protocol https >/dev/null',
+  '/bin/cat "$dir/hosts.yml"',
+].join("\n");
+
+function inventory(environment: Environment, assignment: TaskAssignment, lane: "github" | "ssh", credentialId: string, paths: readonly string[]): void {
+  for (const path of paths) {
+    rememberCredentialCleanupPath({
+      taskId: assignment.taskId,
+      runEpoch: assignment.runEpoch,
+      runtime: environment.descriptor.locator,
+      lane,
+      path,
+      credentialId,
+    });
+  }
+}
+
+/**
+ * The owner's GitHub sign-in into the task: `gh` logs in with the token on
+ * stdin, file-backed (`--insecure-storage`: never a keyring the inventory
+ * does not name), in a directory of its own out of the task's reach, and
+ * its hosts file goes into the task through the no-follow helper. The
+ * GitHub git configuration goes in an included file: `gh` as git's
+ * credential helper, HTTPS as its transport, and SSH transport no longer
+ * selected. Every path is inventoried first. False when the lease names no
+ * GitHub sign-in; throws when it names one it could not read.
+ */
+export function writeTaskGithub(environment: Environment, assignment: TaskAssignment): Promise<boolean> {
+  assertTaskRuntime(environment, assignment.taskId);
+  return enqueueWrite(assignment, async (_admit, current) => {
+    const slot = current().github;
+    if (slot.kind === "absent") return false;
+    if (slot.kind === "unavailable") throw new CredentialLeaseUnavailableError("the GitHub sign-in could not be read");
+    const { credentialId, revision, token } = slot.value;
+    // Admitted only while this exact revision is still the task's.
+    const admit = (): void => {
+      const live = current().github;
+      if (live.kind !== "present" || live.value.revision !== revision) throw new PersonCredentialWriteRefused();
+    };
+    inventory(environment, assignment, "github", credentialId, withStaged(TASK_GH_HOSTS_PATH, TASK_GH_GITCONFIG_PATH));
+    const hosts = await run(environment, ["/bin/sh", "-c", GH_LOGIN_SCRIPT], `${token}\n`, "gh auth login", admit, "root");
+    if (hosts.length === 0) throw new Error("gh auth login failed in the task (no hosts file)");
+    await run(environment, writeFileArgv(TASK_GH_HOSTS_PATH, "600"), Buffer.from(hosts).toString("utf8"), "GitHub sign-in", admit);
+    await run(environment, writeFileArgv(TASK_GH_GITCONFIG_PATH, "644"), GITHUB_GITCONFIG, "GitHub git configuration", admit);
+    await run(
+      environment,
+      [
+        "/bin/sh",
+        "-c",
+        `set -eu\n/bin/rm -f -- '${TASK_SSH_TRANSPORT_GITCONFIG_PATH}'\n${includeOnce(TASK_GH_GITCONFIG_PATH)}`,
+      ],
+      null,
+      "git HTTPS transport setup",
+      admit,
+    );
+    return true;
+  });
+}
+
+/**
+ * The owner's SSH key into the task: the private half, owner-only, its
+ * public half and the signers file git verifies with, then the signing
+ * configuration in an included file (ADR-029). Without a GitHub sign-in in
+ * the task at that moment SSH is also git's transport to GitHub, in an
+ * included file of its own; with one, any such file goes. After the GitHub
+ * sign-in leaves a task that keeps its key, writing the key again selects
+ * SSH transport. Every path, intermediates included, is inventoried first.
+ * False when the lease names no SSH key; throws when it names one it could
+ * not read.
+ */
+export function writeTaskSshKey(environment: Environment, assignment: TaskAssignment): Promise<boolean> {
+  assertTaskRuntime(environment, assignment.taskId);
+  return enqueueWrite(assignment, async (_admit, current) => {
+    const slot = current().ssh;
+    if (slot.kind === "absent") return false;
+    if (slot.kind === "unavailable") throw new CredentialLeaseUnavailableError("the SSH key could not be read");
+    const { credentialId, revision, privateKey, publicKey } = slot.value;
+    const admit = (): void => {
+      const live = current().ssh;
+      if (live.kind !== "present" || live.value.revision !== revision) throw new PersonCredentialWriteRefused();
+    };
+    inventory(
+      environment,
+      assignment,
+      "ssh",
+      credentialId,
+      withStaged(
+        TASK_SSH_KEY_PATH,
+        TASK_SSH_PUBLIC_KEY_PATH,
+        TASK_SSH_ALLOWED_SIGNERS_PATH,
+        TASK_SSH_SIGNING_GITCONFIG_PATH,
+        TASK_SSH_TRANSPORT_GITCONFIG_PATH,
+      ),
+    );
+    const write = (path: string, mode: "600" | "644", content: string, what: string, admitted = admit) =>
+      run(environment, writeFileArgv(path, mode), content.endsWith("\n") ? content : `${content}\n`, what, admitted);
+    await write(TASK_SSH_KEY_PATH, "600", privateKey, `writing ${TASK_SSH_KEY_PATH}`);
+    await write(TASK_SSH_PUBLIC_KEY_PATH, "644", publicKey, `writing ${TASK_SSH_PUBLIC_KEY_PATH}`);
+    await write(TASK_SSH_ALLOWED_SIGNERS_PATH, "644", `* ${publicKey.trim()}`, `writing ${TASK_SSH_ALLOWED_SIGNERS_PATH}`);
+    await write(TASK_SSH_SIGNING_GITCONFIG_PATH, "644", SSH_SIGNING_GITCONFIG, "SSH signing configuration");
+    await run(environment, ["/bin/sh", "-c", includeOnce(TASK_SSH_SIGNING_GITCONFIG_PATH)], null, "SSH signing setup", admit);
+    // The transport follows the task's GitHub sign-in as it is now, not as
+    // it was when this write began.
+    if (current().github.kind === "absent") {
+      const sshTransport = (): void => {
+        admit();
+        if (current().github.kind !== "absent") throw new PersonCredentialWriteRefused();
+      };
+      await write(TASK_SSH_TRANSPORT_GITCONFIG_PATH, "644", SSH_TRANSPORT_GITCONFIG, "SSH transport configuration", sshTransport);
+      await run(environment, ["/bin/sh", "-c", includeOnce(TASK_SSH_TRANSPORT_GITCONFIG_PATH)], null, "SSH transport setup", sshTransport);
+    } else {
+      await run(environment, ["/bin/rm", "-f", "--", TASK_SSH_TRANSPORT_GITCONFIG_PATH], null, "SSH transport removal", admit);
+    }
+    return true;
+  });
+}
+
+function sameAssignment(a: TaskAssignment, b: TaskAssignment): boolean {
+  return a.taskId === b.taskId && a.runEpoch === b.runEpoch;
+}