@crvouga/dev-fleet 0.5.0 → 0.7.0

package/src/github/credential.ts

@@ -0,0 +1,21 @@
+import type { FleetDefinition } from '../definition';
+import type { SecretsProvider } from '../secrets';
+import { githubPolicy } from './policy';
+
+/** Where a node's GitHub token comes from. Every source is read through the
+ * fleet's secrets provider, by the declared name `github-token`:
+ * - `shared`: one token for the whole fleet;
+ * - `per-node`: the node's own token (`github-token-<node>`), so revoking one
+ *   node's token leaves every other node signed in.
+ * gh on the node holds the token it was given; git and every other tool ask
+ * gh for it each time (`gh auth git-credential`), so a replaced token reaches
+ * them without restarting anything.
+ */
+export function githubCredential(
+  definition: FleetDefinition,
+  node: string,
+  secret: SecretsProvider
+): () => Promise<string | null> {
+  const perNode = githubPolicy(definition).credential === 'per-node';
+  return () => secret('github-token', perNode ? node : undefined);
+}

package/src/github/policy.ts

@@ -0,0 +1,141 @@
+import { record } from '../config';
+import { FleetUsageError } from '../errors';
+import type { FleetDefinition } from '../definition';
+
+/** How the fleet signs in to GitHub, from the optional `github` block of its
+ * fleet configuration. The fleet login itself is `worker.githubLogin`.
+ */
+export interface GithubPolicy {
+  /** `fleet`: the manager signs in as the fleet login, like every worker.
+   * `{ login }`: the manager keeps a person's own login, which is checked and
+   * never replaced.
+   */
+  manager: 'fleet' | { login: string };
+  /** `shared`: one token for every node (`github-token`). `per-node`: each
+   * node has its own (`github-token-<node>`), so one can be revoked alone.
+   */
+  credential: 'shared' | 'per-node';
+  /** Scopes the token must carry, such as `repo` and `workflow`. */
+  scopes: string[];
+  /** `owner/name` of repositories every node must be able to push to. */
+  repositories: string[];
+  /** Organisations whose single sign-on must have authorised the token. */
+  organizations: string[];
+  /** `owner/name` of a repository `fleet-github-verify` may branch, push to
+   * and open pull requests on, then clean up.
+   */
+  sandbox?: string;
+}
+
+export const DEFAULT_GITHUB: GithubPolicy = {
+  manager: 'fleet',
+  credential: 'shared',
+  scopes: [],
+  repositories: [],
+  organizations: [],
+};
+
+const LOGIN = /^[a-zA-Z0-9-]{1,39}$/;
+const REPOSITORY = /^[a-zA-Z0-9-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+const SCOPE = /^[a-z:_]{1,40}$/;
+const FIELDS = [
+  'manager',
+  'credential',
+  'scopes',
+  'repositories',
+  'organizations',
+  'sandbox',
+];
+
+function fail(): never {
+  throw new FleetUsageError(
+    'Invalid github block in fleet.json. "manager" is "fleet" or {"login": ...}, "credential" is "shared" or "per-node", "scopes", "repositories" (owner/name) and "organizations" are lists, "sandbox" is owner/name.'
+  );
+}
+
+function list(value: unknown, pattern: RegExp): string[] {
+  if (value === undefined) return [];
+  if (
+    !Array.isArray(value) ||
+    value.length > 64 ||
+    new Set(value).size !== value.length ||
+    !value.every((item) => typeof item === 'string' && pattern.test(item))
+  )
+    return fail();
+  return value as string[];
+}
+
+function managerLogin(value: unknown): GithubPolicy['manager'] {
+  if (value === undefined || value === 'fleet') return 'fleet';
+  if (
+    record(value) &&
+    Object.keys(value).length === 1 &&
+    typeof value['login'] === 'string' &&
+    LOGIN.test(value['login'])
+  )
+    return { login: value['login'] };
+  return fail();
+}
+
+function repository(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === 'string' && REPOSITORY.test(value) ? value : fail();
+}
+
+export function parseGithubPolicy(value: unknown): GithubPolicy {
+  if (
+    !record(value) ||
+    !Object.keys(value).every((key) => FIELDS.includes(key))
+  )
+    return fail();
+  const credential = value['credential'] ?? 'shared';
+  if (credential !== 'shared' && credential !== 'per-node') return fail();
+  const sandbox = repository(value['sandbox']);
+  return {
+    manager: managerLogin(value['manager']),
+    credential,
+    scopes: list(value['scopes'], SCOPE),
+    repositories: list(value['repositories'], REPOSITORY),
+    organizations: list(value['organizations'], LOGIN),
+    ...(sandbox === undefined ? {} : { sandbox }),
+  };
+}
+
+export type GithubRole = 'manager' | 'worker';
+
+/** What GitHub sign-in on one node is held to. */
+export interface GithubNode {
+  role: GithubRole;
+  /** The node's id: it names a per-node credential. */
+  node: string;
+  /** The login the node must be signed in as; null when the fleet declares
+   * none (no worker policy).
+   */
+  login: string | null;
+  /** Whether dev-fleet signs this node in from the stored credential, or only
+   * checks a person's own login.
+   */
+  managed: boolean;
+}
+
+export function githubPolicy(definition: FleetDefinition): GithubPolicy {
+  return definition.github ?? DEFAULT_GITHUB;
+}
+
+/** The manager when `node` is not a declared worker. */
+export function githubNode(
+  definition: FleetDefinition,
+  node?: string
+): GithubNode {
+  const policy = githubPolicy(definition);
+  const fleetLogin = definition.worker?.githubLogin ?? null;
+  if (node !== undefined && definition.workers.some((w) => w.id === node))
+    return { role: 'worker', node, login: fleetLogin, managed: true };
+  const personal = policy.manager !== 'fleet';
+  return {
+    role: 'manager',
+    node: definition.manager.id,
+    login: policy.manager === 'fleet' ? fleetLogin : policy.manager.login,
+    managed: !personal,
+  };
+}

package/src/github/sync.ts

@@ -0,0 +1,123 @@
+import type { CommandResult, Runner } from '../types';
+
+/** What GitHub sign-in on a node came to. Each failure names the system to
+ * fix: the store (`MISSING`), GitHub's verdict on the stored token
+ * (`REJECTED`), the fleet configuration or the store (`MISMATCH`), the network
+ * (`UNREACHABLE`).
+ */
+export type GithubCode =
+  | 'GITHUB_OK'
+  | 'GITHUB_TOKEN_MISSING'
+  | 'GITHUB_TOKEN_REJECTED'
+  | 'GITHUB_LOGIN_MISMATCH'
+  | 'GITHUB_UNREACHABLE'
+  | 'GITHUB_SIGN_IN_FAILED';
+
+export interface GithubSyncResult {
+  code: GithubCode;
+  /** The stored token replaced the one the node held. */
+  adopted: boolean;
+}
+
+/** Each GitHub request and the secret read is bounded by this; the unit that
+ * runs a sync allows every step its full time (ansible/ubuntu/tasks/github.yml).
+ */
+export const GITHUB_STEP_TIMEOUT_MS = 30_000;
+
+export interface GithubSyncInput {
+  run: Runner;
+  /** The stored credential of this node, through the fleet's secrets provider. */
+  token: () => Promise<string | null>;
+  /** The login the node must be signed in as. */
+  login: string;
+  /** False: measure only, change nothing (a check, or a person's own login). */
+  apply: boolean;
+}
+
+const TOKEN = /^[\x21-\x7e]{16,4096}$/;
+/** gh prints GitHub's status line on a refused request. */
+const REFUSED = /HTTP 401|Bad credentials/i;
+
+/** gh with no token in its environment: it uses only the login it stores. */
+const stored = { GH_TOKEN: undefined, GITHUB_TOKEN: undefined };
+
+async function whoami(run: Runner, token?: string): Promise<CommandResult> {
+  return run(['gh', 'api', 'user', '--jq', '.login'], {
+    timeoutMs: GITHUB_STEP_TIMEOUT_MS,
+    env: token ? { GH_TOKEN: token, GITHUB_TOKEN: undefined } : stored,
+  });
+}
+
+/** The token gh signs requests with on this node, held in memory only. */
+export async function activeToken(
+  run: Runner,
+  timeoutMs = GITHUB_STEP_TIMEOUT_MS
+): Promise<string | null> {
+  const result = await run(
+    ['gh', 'auth', 'token', '--hostname', 'github.com'],
+    { timeoutMs, env: stored }
+  );
+  const token = result.stdout.trim();
+  return result.ok && TOKEN.test(token) ? token : null;
+}
+
+function refused(result: CommandResult): GithubCode {
+  return REFUSED.test(result.stderr) || REFUSED.test(result.stdout)
+    ? 'GITHUB_TOKEN_REJECTED'
+    : 'GITHUB_UNREACHABLE';
+}
+
+/** Brings this node's GitHub sign-in to the stored credential, or with
+ * `apply: false` says what doing so would find. A token that differs from the
+ * one gh holds is adopted while the old one still works, so a rotation never
+ * waits for a revocation to break every node at once. A token is never in
+ * argv, a log or a result: gh receives it on standard input.
+ */
+export async function syncGithub(
+  input: GithubSyncInput
+): Promise<GithubSyncResult> {
+  const { run, login, apply } = input;
+  const current = await whoami(run);
+  const signedIn = current.ok && current.stdout.trim() === login;
+  const token = ((await input.token()) ?? '').trim();
+  if (!TOKEN.test(token))
+    return {
+      code: signedIn ? 'GITHUB_OK' : 'GITHUB_TOKEN_MISSING',
+      adopted: false,
+    };
+  if (signedIn && (await activeToken(run)) === token)
+    return { code: 'GITHUB_OK', adopted: false };
+  const owner = await whoami(run, token);
+  if (!owner.ok) {
+    // A stored token GitHub refuses is not adopted; the node keeps the one
+    // that still works, and the failure names the store.
+    return { code: refused(owner), adopted: false };
+  }
+  if (owner.stdout.trim() !== login)
+    return { code: 'GITHUB_LOGIN_MISMATCH', adopted: false };
+  // A measurement says what a sync would do: adopt the stored token.
+  if (!apply) return { code: 'GITHUB_OK', adopted: false };
+  const signIn = await run(
+    ['gh', 'auth', 'login', '--hostname', 'github.com', '--with-token'],
+    { input: token + '\n', env: stored, timeoutMs: GITHUB_STEP_TIMEOUT_MS }
+  );
+  if (!signIn.ok) return { code: 'GITHUB_SIGN_IN_FAILED', adopted: false };
+  return { code: 'GITHUB_OK', adopted: true };
+}
+
+/** Why a node is not signed in, for a check: measures, never signs in. When the
+ * node is signed in as the declared login nothing else is read.
+ */
+export async function githubSignInState(
+  input: Omit<GithubSyncInput, 'apply'>
+): Promise<GithubCode> {
+  const current = await whoami(input.run);
+  if (current.ok && current.stdout.trim() === input.login) return 'GITHUB_OK';
+  const token = ((await input.token()) ?? '').trim();
+  if (!TOKEN.test(token)) return 'GITHUB_TOKEN_MISSING';
+  const owner = await whoami(input.run, token);
+  if (!owner.ok) return refused(owner);
+  if (owner.stdout.trim() !== input.login) return 'GITHUB_LOGIN_MISMATCH';
+  // The stored token is good; the node has yet to adopt it.
+  return 'GITHUB_SIGN_IN_FAILED';
+}

package/src/github/workflow.ts

@@ -0,0 +1,223 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { Check, Runner } from '../types';
+
+/** The steps of the work an agent does on GitHub, in order. A failure names
+ * the first step that failed.
+ */
+export const WORKFLOW_STEPS = [
+  'clone',
+  'branch',
+  'commit',
+  'push',
+  'pull-request',
+  'read-checks',
+  'comment',
+] as const;
+export type WorkflowStep = (typeof WORKFLOW_STEPS)[number];
+
+export interface WorkflowInput {
+  run: Runner;
+  /** `owner/name` of the declared sandbox repository. */
+  sandbox: string;
+  /** The node that runs it: part of the branch name. */
+  node: string;
+  /** A unique suffix for the branch; time and randomness by default. */
+  unique?: string;
+  /** A private, empty directory for the clone; made and removed by default. */
+  directory?: string;
+}
+
+export interface WorkflowResult {
+  check: Check;
+  /** The step that failed, if one did. */
+  failed?: WorkflowStep;
+  /** The branch the run used, deleted again unless `leftBehind`. */
+  branch: string;
+  /** What clean-up could not remove: a branch or a pull request. */
+  leftBehind: string[];
+}
+
+const STEP_TIMEOUT_MS = 60_000;
+
+/** Runs the chain an agent depends on against the sandbox repository: clone,
+ * branch, commit with the configured identity, push, open a draft pull
+ * request, read its checks, comment; then always closes the pull request and
+ * deletes the branch, whatever failed. Every step is bounded.
+ */
+export async function verifyGithubWorkflow(
+  input: WorkflowInput
+): Promise<WorkflowResult> {
+  const { run, sandbox, node } = input;
+  const unique =
+    input.unique ??
+    `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const branch = `devfleet-verify/${node}-${unique}`;
+  const directory =
+    input.directory ?? (await mkdtemp(join(tmpdir(), 'devfleet-verify-')));
+  const clone = join(directory, 'sandbox');
+  const git = (args: string[]) =>
+    run(['git', '-C', clone, ...args], { timeoutMs: STEP_TIMEOUT_MS });
+  const gh = (args: string[]) =>
+    run(['gh', ...args], { timeoutMs: STEP_TIMEOUT_MS });
+  let failed: WorkflowStep | undefined;
+  let pushed = false;
+  let pullRequest: string | null = null;
+  const leftBehind: string[] = [];
+  const step = async (
+    name: WorkflowStep,
+    action: () => Promise<boolean>
+  ): Promise<boolean> => {
+    if (failed) return false;
+    if (await action()) return true;
+    failed = name;
+    return false;
+  };
+  try {
+    await step('clone', async () => {
+      const result = await run(
+        [
+          'git',
+          'clone',
+          '--depth',
+          '1',
+          `https://github.com/${sandbox}.git`,
+          clone,
+        ],
+        { timeoutMs: STEP_TIMEOUT_MS }
+      );
+      return result.ok;
+    });
+    await step('branch', async () => (await git(['switch', '-c', branch])).ok);
+    await step(
+      'commit',
+      async () =>
+        (
+          await git([
+            'commit',
+            '--allow-empty',
+            '--message',
+            `devfleet: verify the GitHub workflow from ${node}`,
+          ])
+        ).ok
+    );
+    await step('push', async () => {
+      pushed = (await git(['push', '--set-upstream', 'origin', branch])).ok;
+      return pushed;
+    });
+    await step('pull-request', async () => {
+      const created = await gh([
+        'pr',
+        'create',
+        '--repo',
+        sandbox,
+        '--head',
+        branch,
+        '--draft',
+        '--title',
+        `devfleet verify ${node}`,
+        '--body',
+        'Opened by devfleet fleet-github-verify; closed again by the same run.',
+      ]);
+      const url = created.stdout.trim().split('\n').pop() ?? '';
+      if (created.ok && /^https:\/\/\S+\/pull\/\d+$/.test(url))
+        pullRequest = url;
+      return pullRequest !== null;
+    });
+    await step(
+      'read-checks',
+      async () =>
+        (
+          await gh([
+            'pr',
+            'view',
+            pullRequest!,
+            '--repo',
+            sandbox,
+            '--json',
+            'statusCheckRollup',
+          ])
+        ).ok
+    );
+    await step(
+      'comment',
+      async () =>
+        (
+          await gh([
+            'pr',
+            'comment',
+            pullRequest!,
+            '--repo',
+            sandbox,
+            '--body',
+            'devfleet fleet-github-verify: comment step.',
+          ])
+        ).ok
+    );
+  } finally {
+    // Clean-up runs whatever failed, and is itself checked.
+    if (pullRequest !== null) {
+      const closed = await gh([
+        'pr',
+        'close',
+        pullRequest,
+        '--repo',
+        sandbox,
+        '--delete-branch',
+      ]);
+      if (!closed.ok) leftBehind.push(pullRequest, branch);
+    } else if (pushed) {
+      const deleted = await git(['push', 'origin', '--delete', branch]);
+      if (!deleted.ok) leftBehind.push(branch);
+    }
+    if (!input.directory) await rm(directory, { recursive: true, force: true });
+  }
+  return result(branch, failed, leftBehind);
+}
+
+function result(
+  branch: string,
+  failed: WorkflowStep | undefined,
+  leftBehind: string[]
+): WorkflowResult {
+  const check: Check =
+    failed === undefined && leftBehind.length === 0
+      ? {
+          id: 'github:workflow',
+          status: 'pass',
+          summary:
+            'Cloned the sandbox, pushed a branch, opened a draft pull request, read its checks and commented, then cleaned up.',
+        }
+      : {
+          id: 'github:workflow',
+          status: 'fail',
+          summary: failed
+            ? `GITHUB_WORKFLOW_FAILED: ${failed}`
+            : `GITHUB_WORKFLOW_CLEANUP_FAILED: ${leftBehind.join(', ')}`,
+          remedy: {
+            action: failed
+              ? remedyFor(failed)
+              : 'Close the pull request and delete the branch named on the sandbox repository.',
+          },
+        };
+  return { check, ...(failed ? { failed } : {}), branch, leftBehind };
+}
+
+function remedyFor(step: WorkflowStep): string {
+  return {
+    clone:
+      'This node cannot clone the sandbox over HTTPS: check github:git-credential and that the fleet login can read github.sandbox.',
+    branch:
+      'git could not create a branch in a fresh clone; check git on this node.',
+    commit:
+      'git could not commit: set user.name and user.email for the fleet login on this node.',
+    push: 'The token cannot push to the sandbox: check github:permissions (repo or contents: write).',
+    'pull-request':
+      'The token cannot open a pull request: it needs the pull requests permission on the sandbox.',
+    'read-checks':
+      'The token cannot read the checks of a pull request: it needs checks and statuses read access.',
+    comment:
+      'The token cannot comment on a pull request: it needs the pull requests (write) permission.',
+  }[step];
+}

package/src/node-converge-linux.ts

@@ -66,7 +66,7 @@ export async function convergeLinux(
   checks.push(...(await t3AfterBaseline(root, { node, baseline, run })));
   checks.push(
     ...(await attempt('workstation:configuration', () =>
-      configureWorkstation(root, run)
+      configureWorkstation(root, run, node)
     ))
   );
   checks.push(
@@ -169,7 +169,7 @@ async function applyBaseline(
     },
     {
       name: 'ubuntu-baseline',
-      sources: [ubuntu],
+      sources: [ubuntu, resolve(root, 'ansible/github')],
       force,
       verify: () => baselineServicesActive(run),
     }
@@ -207,6 +207,7 @@ async function baselineServicesActive(run: Runner): Promise<boolean> {
     'is-active',
     '--quiet',
     'personal-worker-auth.timer',
+    'personal-worker-github.timer',
   ]);
   return user.ok;
 }

package/src/node-converge-shared.ts

@@ -1,6 +1,7 @@
 import { fingerprint, writeReceipt } from './fingerprint';
 import { configureWorkspace } from './configure';
 import { stableWorkspace } from './platform/t3-policy';
+import { convergeGithub } from './github/converge';
 import type { Check, Runner } from './types';
 
 /** Phase wrapper: one failure code per phase, durations measured, no exception text. */
@@ -30,11 +31,13 @@ export async function attempt(
 }
 
 /** The `devfleet` launcher (linked to the applied revision, never copied) and
- * this worker's own credential refresh. Identical on Linux and macOS.
+ * this worker's own credential refresh: its Vault session and, apart from it,
+ * its GitHub sign-in. Identical on Linux and macOS.
  */
 export async function configureWorkstation(
   root: string,
-  run: Runner
+  run: Runner,
+  node?: string
 ): Promise<Check[]> {
   const installed = await run(
     // The stable path of the applied revision: it survives pruning.
@@ -62,6 +65,7 @@ export async function configureWorkstation(
       summary:
         'The devfleet launcher is linked to the applied revision; authentication remains a separate gate.',
     },
+    await convergeGithub(root, run, node),
   ];
 }