@zgeoff/atc 2.16.0 → 2.19.0

package/src/sources/github/find-github-alternate-url.ts

@@ -0,0 +1,20 @@
+const HTTPS_PATTERN = /^https:\/\/github\.com\/(?<owner>[\w.-]+)\/(?<repo>[\w.-]+?)(?:\.git)?\/?$/u;
+
+const SSH_PATTERN =
+  /^(?:ssh:\/\/)?git@github\.com[:/](?<owner>[\w.-]+)\/(?<repo>[\w.-]+?)(?:\.git)?$/u;
+
+/**
+ * The other URL form of a GitHub repository: the ssh form of an https URL,
+ * and the https form of an ssh URL. Null for a URL not on GitHub.
+ */
+export function findGitHubAlternateURL(url: string): string | null {
+  const ssh = SSH_PATTERN.exec(url)?.groups;
+
+  if (ssh !== undefined) {
+    return `https://github.com/${ssh['owner']}/${ssh['repo']}.git`;
+  }
+
+  const https = HTTPS_PATTERN.exec(url)?.groups;
+
+  return https === undefined ? null : `git@github.com:${https['owner']}/${https['repo']}.git`;
+}

package/src/sources/github/read-git-protocol.ts

@@ -0,0 +1,11 @@
+import { runGH } from './run-gh';
+
+/**
+ * The clone protocol the gh config on this host prefers: `ssh` when it says
+ * so, else `https`, which a gh that fails or takes too long also gives.
+ */
+export async function readGitProtocol(bin: string, timeoutMs: number): Promise<'https' | 'ssh'> {
+  const run = await runGH(bin, timeoutMs, ['config', 'get', 'git_protocol']);
+
+  return run.exitCode === 0 && run.stdout.trim() === 'ssh' ? 'ssh' : 'https';
+}

package/src/sources/github/run-gh.ts

@@ -0,0 +1,66 @@
+export interface GHRun {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly timedOut: boolean;
+}
+
+/**
+ * Runs gh with arguments and a time limit, killing its whole process group
+ * once the limit passes, so a wrapper or extension leaves no process
+ * behind. gh reads its own config and the host's environment for its
+ * token, and is kept from prompting, colouring, or checking for updates.
+ */
+export async function runGH(
+  bin: string,
+  timeoutMs: number,
+  args: readonly string[],
+): Promise<GHRun> {
+  const proc = Bun.spawn([bin, ...args], {
+    env: {
+      ...process.env,
+      GH_PROMPT_DISABLED: '1',
+      GH_NO_UPDATE_NOTIFIER: '1',
+      GH_SPINNER_DISABLED: '1',
+      NO_COLOR: '1',
+      LC_ALL: 'C',
+    },
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+
+    // gh leads its own process group, so stopping it stops what it
+    // started too.
+    detached: true,
+  });
+
+  const finished = Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  const limit = Promise.withResolvers<null>();
+
+  const timer = setTimeout(() => {
+    limit.resolve(null);
+  }, timeoutMs);
+
+  const settled = await Promise.race([finished, limit.promise]);
+
+  clearTimeout(timer);
+
+  if (settled === null) {
+    try {
+      process.kill(-proc.pid, 'SIGKILL');
+    } catch {
+      // The group already exited.
+    }
+
+    return { exitCode: -1, stdout: '', stderr: '', timedOut: true };
+  }
+
+  const [stdout, stderr, exitCode] = settled;
+
+  return { exitCode, stdout, stderr, timedOut: false };
+}

package/src/sources/types.ts

@@ -0,0 +1,70 @@
+/**
+ * What a candidate or a typed input resolves to: a directory on the
+ * daemon's host, or a git repository URL that a probe pins to a commit
+ * before any spawn uses it.
+ */
+type SourcePick =
+  | { readonly kind: 'path'; readonly dir: string }
+  | { readonly kind: 'git'; readonly url: string };
+
+// The kind of pick every candidate of one source resolves to.
+export type SourceKind = SourcePick['kind'];
+
+// One entry a source lists for the spawn picker.
+interface SourceCandidate {
+  readonly label: string;
+  readonly detail?: string;
+  readonly pick: SourcePick;
+}
+
+// One listing: the candidates, and the scope they were listed under, or
+// null when the source lists without one.
+interface SourceListing {
+  readonly candidates: readonly SourceCandidate[];
+  readonly scope: string | null;
+}
+
+// What a listing asks for: a scope the source defines, such as one account,
+// and filter text for a source that filters on the daemon.
+interface SourceQuery {
+  readonly scope?: string;
+  readonly text?: string;
+}
+
+/**
+ * What a source reads typed input as: a scope to list, a pick, or nothing
+ * it recognizes.
+ */
+export type SourceInterpretation =
+  | { readonly kind: 'browse'; readonly scope: string }
+  | SourcePick
+  | { readonly kind: 'none' };
+
+/**
+ * The request a source serves: the execution target the spawn will use,
+ * and the daemon's spawn history as the requesting principal may read it.
+ */
+export interface SourceRequest {
+  readonly target: string;
+  readonly collectSpawnDirs: () => Promise<string[]>;
+}
+
+/**
+ * A discovery source for the spawn picker. It lists candidates and reads
+ * typed input, and every candidate resolves to a pick of its kind. A source
+ * runs on the daemon, the host that materializes the workspace, and gets
+ * the services it uses when it is built. A failure throws the error the
+ * source defines for it.
+ */
+export interface SourceProvider {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: SourceKind;
+  readonly list: (query: SourceQuery, request: SourceRequest) => Promise<SourceListing>;
+  readonly interpret: (input: string, request: SourceRequest) => Promise<SourceInterpretation>;
+
+  // The other URLs of the repository at a git URL the daemon's host could
+  // not read, for a source that knows its host's URL forms; none when it
+  // does not recognize the URL.
+  readonly findAlternateURLs?: (url: string) => readonly string[];
+}

package/src/workspace/check-git-transport.ts

@@ -0,0 +1,61 @@
+type TransportCheck =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly code: 'invalid_git_url'; readonly message: string };
+
+// `<transport>::<address>`, which runs git's remote helper for the
+// transport, such as `ext::` or `fd::`.
+const HELPER_PATTERN = /^(?<name>[A-Za-z][\w+.-]*)::/u;
+
+// `<scheme>://…`.
+const SCHEME_PATTERN = /^(?<name>[A-Za-z][\w+.-]*):\/\//u;
+
+// The scp-style `user@host:path` or `host:path`, which git reads as ssh.
+const SCP_PATTERN = /^(?:[^@/:\s]+@)?[^@/:\s]+:/u;
+
+// Schemes git treats as ssh.
+const SSH_SCHEMES: ReadonlySet<string> = new Set(['ssh', 'git+ssh', 'ssh+git']);
+
+/**
+ * Checks that a repository URL uses one of the allowed git transports,
+ * without running git. The scp-style form is ssh, a remote-helper URL is
+ * its helper's transport, and a path is the `file` transport. A URL that
+ * git could read as an option is refused whatever the transports.
+ */
+export function checkGitTransport(url: string, transports: readonly string[]): TransportCheck {
+  if (url.startsWith('-')) {
+    return { ok: false, code: 'invalid_git_url', message: 'a git URL must not start with -' };
+  }
+
+  const transport = findTransport(url);
+
+  if (transports.includes(transport)) {
+    return { ok: true };
+  }
+
+  const allowed =
+    transports.length === 0
+      ? 'workspaces.gitTransports allows no transports'
+      : `the daemon fetches over ${transports.join(' and ')}`;
+
+  return {
+    ok: false,
+    code: 'invalid_git_url',
+    message: `git transport '${transport}' is not allowed; ${allowed}`,
+  };
+}
+
+function findTransport(url: string): string {
+  const helper = HELPER_PATTERN.exec(url)?.groups?.['name'];
+
+  if (helper !== undefined) {
+    return helper.toLowerCase();
+  }
+
+  const scheme = SCHEME_PATTERN.exec(url)?.groups?.['name']?.toLowerCase();
+
+  if (scheme !== undefined) {
+    return SSH_SCHEMES.has(scheme) ? 'ssh' : scheme;
+  }
+
+  return SCP_PATTERN.test(url) ? 'ssh' : 'file';
+}

package/src/workspace/check-repository-access.ts

@@ -0,0 +1,108 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { collectRemoteRefs } from './collect-remote-refs';
+import type { RemoteRef } from './collect-remote-refs';
+import type { GitCredential } from './create-git-askpass';
+import { findRemoteRef } from './find-remote-ref';
+import { resolveGitURL } from './resolve-git-url';
+
+interface AccessRequest {
+  readonly url: string;
+
+  // At most one: a branch or tag to resolve to its commit, or a full
+  // commit id taken as it is.
+  readonly ref?: string | undefined;
+  readonly sha?: string | undefined;
+  readonly credential?: GitCredential | undefined;
+
+  // How long the listing may take; 20 s when unset.
+  readonly timeoutMs?: number | undefined;
+
+  // The transports the URL may use and git may fetch over.
+  readonly transports: readonly string[];
+}
+
+interface RepositoryAccess {
+  readonly ok: true;
+
+  // The URL a workspace spawn from this source clones.
+  readonly url: string;
+  readonly head: string | null;
+  readonly refs: readonly RemoteRef[];
+
+  // The commit the requested ref or sha selects, and the branch it is on;
+  // null when the request holds neither.
+  readonly resolved: {
+    readonly sha: string;
+    readonly branch: string | null;
+  } | null;
+}
+
+interface AccessRefusal {
+  readonly ok: false;
+  readonly code:
+    | 'clone_failed'
+    | 'credential_in_url'
+    | 'credential_missing'
+    | 'invalid_git_url'
+    | 'ref_not_found';
+  readonly message: string;
+}
+
+/**
+ * Checks that the daemon's host can read a git workspace source the way a
+ * workspace spawn from it would, without cloning: the URL resolves exactly
+ * as the materializer resolves it, against the git config of a fresh empty
+ * directory, and one `git ls-remote` authenticates exactly as the clone
+ * does. A readable upstream answers with its branches, tags, and default
+ * branch, and with the commit the requested ref points at now. A full
+ * commit id is taken as it is: a listing holds refs, not objects, so only
+ * the clone can tell that the upstream lacks it.
+ */
+export async function checkRepositoryAccess(
+  request: AccessRequest,
+): Promise<AccessRefusal | RepositoryAccess> {
+  const cwd = await mkdtemp(join(tmpdir(), 'atc-repo-access-'));
+
+  try {
+    const resolved = await resolveGitURL(request.url, cwd, request.transports);
+
+    if (!resolved.ok) {
+      return resolved;
+    }
+
+    const listing = await collectRemoteRefs(
+      resolved.url,
+      request.credential,
+      request.transports,
+      request.timeoutMs,
+    );
+
+    if (!listing.ok) {
+      return listing;
+    }
+
+    const access = { ok: true, url: resolved.url, head: listing.head, refs: listing.refs } as const;
+
+    if (request.sha !== undefined) {
+      return { ...access, resolved: { sha: request.sha, branch: null } };
+    }
+
+    if (request.ref === undefined) {
+      return { ...access, resolved: null };
+    }
+
+    const match = findRemoteRef(listing.byName, request.ref);
+
+    if (match === null) {
+      const name = request.ref.replace(/^refs\/(?:heads|tags)\//u, '');
+
+      return { ok: false, code: 'ref_not_found', message: `origin has no branch or tag '${name}'` };
+    }
+
+    return { ...access, resolved: match };
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+}

package/src/workspace/collect-remote-refs.ts

@@ -0,0 +1,154 @@
+import { createGitAskpass } from './create-git-askpass';
+import type { GitCredential } from './create-git-askpass';
+import { runGit } from './run-git';
+
+export interface RemoteRef {
+  // The short name: `main`, `feat/x`, `v1.0`.
+  readonly name: string;
+  readonly kind: 'branch' | 'tag';
+
+  // The commit the ref points at; an annotated tag's is the commit it
+  // peels to.
+  readonly sha: string;
+}
+
+interface RemoteRefListing {
+  readonly ok: true;
+
+  // The branch the upstream's HEAD points at, or null when it reports none.
+  readonly head: string | null;
+  readonly refs: readonly RemoteRef[];
+
+  // Every listed ref by full name, each annotated tag's peeled `^{}` entry
+  // beside it, for resolving one ref the way a clone does.
+  readonly byName: ReadonlyMap<string, string>;
+}
+
+interface RemoteRefRefusal {
+  readonly ok: false;
+  readonly code: 'clone_failed' | 'credential_missing';
+  readonly message: string;
+}
+
+// How long a listing may take: a host that never answers holds a client
+// waiting on it no longer than this.
+const REMOTE_TIMEOUT_MS = 20_000;
+
+/**
+ * Lists an upstream's branches and tags and the branch its HEAD points at,
+ * through one `git ls-remote` that authenticates exactly as a clone of the
+ * same URL does: through the host's git config, or through a private
+ * askpass helper for an env credential. git never prompts. A listing git
+ * cannot read is refused as `clone_failed` with git's own message, and so
+ * is one that takes longer than the time limit, 20 s unless given. git
+ * fetches only over `transports`.
+ */
+export async function collectRemoteRefs(
+  url: string,
+  credential: GitCredential | undefined,
+  transports: readonly string[],
+  timeoutMs: number = REMOTE_TIMEOUT_MS,
+): Promise<RemoteRefListing | RemoteRefRefusal> {
+  const askpass = await createGitAskpass(credential);
+
+  if (!askpass.ok) {
+    return askpass;
+  }
+
+  let listed: Awaited<ReturnType<typeof runGit>>;
+
+  try {
+    const sshEnv = await buildSSHTimeoutEnv(timeoutMs);
+
+    listed = await runGit(
+      [
+        ...askpass.args,
+        ...buildHTTPTimeoutArgs(timeoutMs),
+        'ls-remote',
+        '--symref',
+        '--',
+        url,
+        'HEAD',
+        'refs/heads/*',
+        'refs/tags/*',
+      ],
+      { env: { ...askpass.env, ...sshEnv }, timeoutMs, transports },
+    );
+  } finally {
+    await askpass[Symbol.asyncDispose]();
+  }
+
+  if (listed.timedOut) {
+    return {
+      ok: false,
+      code: 'clone_failed',
+      message: `git ls-remote did not answer within ${timeoutMs / 1000} s`,
+    };
+  }
+
+  if (listed.exitCode !== 0) {
+    return { ok: false, code: 'clone_failed', message: listed.stderr.trim() };
+  }
+
+  return parseListing(listed.stdout);
+}
+
+// An ssh connection that takes longer than the limit is given up by ssh.
+// A host that chose its own ssh command keeps it.
+async function buildSSHTimeoutEnv(timeoutMs: number): Promise<Readonly<Record<string, string>>> {
+  if (process.env['GIT_SSH_COMMAND'] !== undefined || process.env['GIT_SSH'] !== undefined) {
+    return {};
+  }
+
+  const configured = await runGit(['config', '--get', 'core.sshCommand']);
+
+  if (configured.exitCode === 0 && configured.stdout.trim() !== '') {
+    return {};
+  }
+
+  const seconds = String(Math.max(1, Math.ceil(timeoutMs / 1000)));
+
+  return { GIT_SSH_COMMAND: `ssh -o ConnectTimeout=${seconds}` };
+}
+
+// An HTTP transfer that moves under a byte a second for the whole limit is
+// given up by git itself.
+function buildHTTPTimeoutArgs(timeoutMs: number): string[] {
+  const seconds = String(Math.max(1, Math.ceil(timeoutMs / 1000)));
+
+  return ['-c', 'http.lowSpeedLimit=1', '-c', `http.lowSpeedTime=${seconds}`];
+}
+
+const SYMREF_PREFIX = 'ref: refs/heads/';
+
+function parseListing(stdout: string): RemoteRefListing {
+  const byName = new Map<string, string>();
+
+  let head: string | null = null;
+
+  for (const line of stdout.split('\n')) {
+    const [left = '', name = ''] = line.split('\t');
+
+    if (name === 'HEAD' && left.startsWith(SYMREF_PREFIX)) {
+      head = left.slice(SYMREF_PREFIX.length);
+    } else if (name.startsWith('refs/heads/') || name.startsWith('refs/tags/')) {
+      byName.set(name, left);
+    }
+  }
+
+  const refs: RemoteRef[] = [];
+
+  for (const [name, sha] of byName) {
+    if (name.startsWith('refs/heads/')) {
+      refs.push({ name: name.slice('refs/heads/'.length), kind: 'branch', sha });
+    } else if (!name.endsWith('^{}')) {
+      refs.push({
+        name: name.slice('refs/tags/'.length),
+        kind: 'tag',
+        sha: byName.get(`${name}^{}`) ?? sha,
+      });
+    }
+  }
+
+  return { ok: true, head, refs, byName };
+}

package/src/workspace/create-git-askpass.ts

@@ -0,0 +1,84 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export interface GitCredential {
+  readonly kind: 'env';
+  readonly name: string;
+}
+
+interface GitAskpass {
+  readonly ok: true;
+
+  // What each network git command takes: the variables that point it at
+  // the helper, and the arguments that switch the host's credential
+  // helpers off.
+  readonly env: Readonly<Record<string, string>>;
+  readonly args: readonly string[];
+  [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+interface MissingCredential {
+  readonly ok: false;
+  readonly code: 'credential_missing';
+  readonly message: string;
+}
+
+const ASKPASS_SECRET_VAR = 'ATC_GIT_ASKPASS_SECRET';
+
+// Username prompts get a fixed name that GitHub and GitLab both accept
+// alongside a token; password prompts get the token.
+const ASKPASS_SCRIPT = `#!/bin/sh
+case "$1" in
+  Username*) printf '%s\\n' x-access-token ;;
+  *) printf '%s\\n' "$${ASKPASS_SECRET_VAR}" ;;
+esac
+`;
+
+/**
+ * Selects how network git commands authenticate. Without a credential they
+ * authenticate through the host's own git config, and the result adds
+ * nothing. An env credential is read from the named variable and handed to
+ * git only through a private askpass helper, never through the command line
+ * or the URL, with the host's credential helpers switched off so none of
+ * them stores the token. Disposing the result deletes the helper.
+ */
+export async function createGitAskpass(
+  credential: GitCredential | undefined,
+): Promise<GitAskpass | MissingCredential> {
+  if (credential === undefined) {
+    return { ok: true, env: {}, args: [], [Symbol.asyncDispose]: async () => {} };
+  }
+
+  const secret = process.env[credential.name];
+
+  if (secret === undefined || secret === '') {
+    return {
+      ok: false,
+      code: 'credential_missing',
+      message: 'the credential environment variable is unset or empty',
+    };
+  }
+
+  const dir = await mkdtemp(join(tmpdir(), 'atc-askpass-'));
+
+  const helper = join(dir, 'askpass');
+
+  // A helper that cannot be written leaves no directory behind.
+  try {
+    await writeFile(helper, ASKPASS_SCRIPT, { mode: 0o700 });
+  } catch (error) {
+    await rm(dir, { recursive: true, force: true });
+
+    throw error;
+  }
+
+  return {
+    ok: true,
+    env: { GIT_ASKPASS: helper, [ASKPASS_SECRET_VAR]: secret },
+    args: ['-c', 'credential.helper='],
+    [Symbol.asyncDispose]: async () => {
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}