@zgeoff/atc 2.17.0 → 2.20.0

package/src/shared/collect-gateways.ts

@@ -1,13 +1,26 @@
 import { z } from 'zod';
 import type { AgentID } from './agent-id';
 import { buildOptionalStringArray } from './build-optional-string-array';
+import type { AuthProfile } from './collect-auth-profiles';
 import { isRecord } from './report';
+import { resolveAuthProfiles } from './resolve-auth-profiles';
+
+/**
+ * The auth profiles a gateway's sessions are bound to through impd's
+ * broker, and the variables each session gets in place of a credential,
+ * every value the fixed placeholder.
+ */
+export interface GatewayAuth {
+  readonly profiles: readonly string[];
+  readonly placeholderEnv: Readonly<Record<string, string>>;
+}
 
 /**
  * A Claude-compatible backend the Claude CLI is pointed at: its own agent id,
  * its own row in the spawn menu, and its own generated settings file. The
- * credential is never held here — a helper command supplies it at run time,
- * so it stays out of the file atc writes.
+ * credential is never held here: a helper command supplies it at run time,
+ * or, with `auth`, impd's credential broker adds it to each request on the
+ * host's side, so it stays out of the file atc writes.
  */
 export interface GatewayConfig {
   readonly id: AgentID;
@@ -19,6 +32,14 @@ export interface GatewayConfig {
   readonly apiKeyHelper?: string;
   readonly env: Readonly<Record<string, string>>;
   readonly settings?: Readonly<Record<string, unknown>>;
+  readonly auth?: GatewayAuth;
+}
+
+interface Gateways {
+  readonly gateways: GatewayConfig[];
+
+  // The problems that kept a gateway with `auth` out, one per problem.
+  readonly errors: string[];
 }
 
 // Ids the built-in adapters answer to; a gateway may not take one.
@@ -41,18 +62,22 @@ const GATEWAY_ENTRY_SCHEMA = z.object({
 /**
  * Reads the gateway map into menu order. An entry without a base URL, or
  * under an id another adapter already answers to, is left out rather than
- * registered half-formed: every gateway in the result can be spawned.
+ * registered half-formed: every gateway in the result can be spawned. A
+ * gateway with `auth` is checked against the auth profiles, and one that
+ * fails a check is left out with an error for each problem.
  */
 export function collectGateways(
   raw: unknown,
   claudeBin: string,
   claudeArgs: readonly string[],
-): GatewayConfig[] {
+  authProfiles: ReadonlyMap<string, AuthProfile> = new Map(),
+): Gateways {
   if (!isRecord(raw)) {
-    return [];
+    return { gateways: [], errors: [] };
   }
 
   const gateways: GatewayConfig[] = [];
+  const errors: string[] = [];
 
   for (const [id, entry] of Object.entries(raw)) {
     if (id === '' || BUILT_IN_IDS.has(id)) {
@@ -65,6 +90,19 @@ export function collectGateways(
       continue;
     }
 
+    let auth: GatewayAuth | undefined;
+
+    if (isRecord(entry) && entry['auth'] !== undefined) {
+      const checked = checkGatewayAuth(entry['auth'], parsed.data, authProfiles);
+
+      if (Array.isArray(checked)) {
+        errors.push(...checked.map((problem) => `gateways.${id}: ${problem}`));
+        continue;
+      }
+
+      auth = checked;
+    }
+
     const firstOfMark = (parsed.data.mark ?? id).codePointAt(0);
 
     gateways.push({
@@ -79,10 +117,189 @@ export function collectGateways(
       ...(parsed.data.apiKeyHelper === undefined ? {} : { apiKeyHelper: parsed.data.apiKeyHelper }),
       env: parsed.data.env,
       ...(parsed.data.settings === undefined ? {} : { settings: parsed.data.settings }),
+      ...(auth === undefined ? {} : { auth }),
     });
   }
 
-  return gateways;
+  return { gateways, errors };
+}
+
+interface GatewayEntry {
+  readonly baseURL?: string | undefined;
+  readonly apiKeyHelper?: string | undefined;
+  readonly env: Readonly<Record<string, string>>;
+  readonly settings?: Readonly<Record<string, unknown>> | undefined;
+}
+
+// The gateway's auth, or every problem that refuses it. The checks cover
+// each place a session's environment comes from: the gateway env, the
+// settings env, and the placeholders, and which of them would win.
+function checkGatewayAuth(
+  raw: unknown,
+  entry: GatewayEntry,
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): GatewayAuth | string[] {
+  const auth = parseGatewayAuth(raw);
+
+  if (typeof auth === 'string') {
+    return [auth];
+  }
+
+  const problems: string[] = [];
+
+  if (entry.apiKeyHelper !== undefined) {
+    problems.push(
+      'apiKeyHelper cannot be set together with auth, which supplies the credential through the broker',
+    );
+  }
+
+  if (entry.settings?.['apiKeyHelper'] !== undefined) {
+    problems.push(
+      'settings.apiKeyHelper cannot be set together with auth, which supplies the credential through the broker',
+    );
+  }
+
+  const settingsEnv = toEnvKeys(entry.settings?.['env']);
+
+  problems.push(
+    ...collectEnvProblems('env', Object.keys(entry.env)),
+    ...collectEnvProblems('settings.env', settingsEnv),
+    ...collectPlaceholderProblems(auth.placeholderEnv),
+  );
+
+  for (const key of Object.keys(auth.placeholderEnv)) {
+    for (const [source, keys] of [
+      ['env', Object.keys(entry.env)],
+      ['settings.env', settingsEnv],
+    ] as const) {
+      if (keys.includes(key)) {
+        problems.push(`placeholderEnv.${key} is also set in ${source}, which would override it`);
+      }
+    }
+  }
+
+  const resolution = resolveAuthProfiles(authProfiles, auth.profiles);
+
+  if ('problem' in resolution) {
+    problems.push(resolution.problem.message);
+  } else {
+    const hostProblem = findBaseURLProblem(entry.baseURL ?? '', resolution.resolved.hosts);
+
+    if (hostProblem !== null) {
+      problems.push(hostProblem);
+    }
+  }
+
+  return problems.length > 0 ? problems : auth;
+}
+
+// The value every placeholder variable holds; impd's broker swaps the real
+// credential in on the host's side.
+const PLACEHOLDER = 'imp-broker-placeholder';
+
+function parseGatewayAuth(raw: unknown): GatewayAuth | string {
+  const profiles = isRecord(raw) ? raw['profiles'] : undefined;
+
+  if (
+    !isRecord(raw) ||
+    !Array.isArray(profiles) ||
+    profiles.length === 0 ||
+    !profiles.every((name) => typeof name === 'string')
+  ) {
+    return 'auth must be an object with a non-empty profiles array';
+  }
+
+  const placeholderEnv = raw['placeholderEnv'] ?? {};
+
+  if (!isRecord(placeholderEnv) || Array.isArray(placeholderEnv)) {
+    return 'placeholderEnv must be an object of variable names';
+  }
+
+  const env: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(placeholderEnv)) {
+    if (value !== PLACEHOLDER) {
+      return `placeholderEnv.${key} must be ${PLACEHOLDER}`;
+    }
+
+    env[key] = value;
+  }
+
+  return { profiles: profiles.map(String), placeholderEnv: env };
+}
+
+// A settings env's variable names; anything but an object sets none.
+function toEnvKeys(value: unknown): string[] {
+  return isRecord(value) && !Array.isArray(value) ? Object.keys(value) : [];
+}
+
+// Variables Claude reads its endpoint and credential from. Only the
+// placeholders may set a credential variable, and the base URL comes from
+// `baseURL` alone, whose host is checked against the profiles.
+const CREDENTIAL_VARIABLES: ReadonlySet<string> = new Set([
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_API_KEY',
+]);
+
+const BASE_URL_VARIABLE = 'ANTHROPIC_BASE_URL';
+
+function collectEnvProblems(source: string, keys: readonly string[]): string[] {
+  return keys
+    .filter(
+      (key) => isBrokerVariable(key) || CREDENTIAL_VARIABLES.has(key) || key === BASE_URL_VARIABLE,
+    )
+    .map((key) => `${source} must not set ${key}`);
+}
+
+// Variables impd sets in a brokered exec to route requests through the
+// broker and trust its CA. impd lets a variable the caller sets win, so a
+// configured one would route around the broker or mask a failed CA install.
+const BROKER_VARIABLES: ReadonlySet<string> = new Set([
+  'HTTPS_PROXY',
+  'HTTP_PROXY',
+  'ALL_PROXY',
+  'NO_PROXY',
+  'NODE_USE_ENV_PROXY',
+  'SSL_CERT_FILE',
+  'SSL_CERT_DIR',
+  'NODE_EXTRA_CA_CERTS',
+  'GIT_SSL_CAINFO',
+  'REQUESTS_CA_BUNDLE',
+  'CURL_CA_BUNDLE',
+]);
+
+// Proxy and CA variables are read in either case by some clients.
+function isBrokerVariable(key: string): boolean {
+  return BROKER_VARIABLES.has(key.toUpperCase());
+}
+
+function collectPlaceholderProblems(env: Readonly<Record<string, string>>): string[] {
+  return Object.keys(env)
+    .filter((key) => isBrokerVariable(key) || key === BASE_URL_VARIABLE)
+    .map((key) => `placeholderEnv must not set ${key}`);
+}
+
+// The broker matches a request by the exact host it connects to on the
+// default https port, so the base URL must be https on that port, with a
+// host one of the selected profiles covers.
+function findBaseURLProblem(baseURL: string, hosts: readonly string[]): string | null {
+  let url: URL;
+
+  try {
+    url = new URL(baseURL);
+  } catch {
+    return 'baseURL must be an https URL with no port or user info';
+  }
+
+  if (url.protocol !== 'https:' || url.port !== '' || url.username !== '' || url.password !== '') {
+    return 'baseURL must be an https URL with no port or user info';
+  }
+
+  if (!hosts.includes(url.hostname)) {
+    return `baseURL host ${url.hostname} is not a host of the selected profiles (${hosts.join(', ')})`;
+  }
+
+  return null;
 }
 
 // Claude Code settings the sessions of this gateway are started with, on top of

package/src/shared/collect-workspaces-config.ts

@@ -2,15 +2,21 @@ import { DEFAULT_GIT_TRANSPORTS } from './default-git-transports';
 import { isRecord } from './report';
 
 /**
- * Where workspace sources come from: the GitHub owner whose repositories
- * the spawn picker lists by default, or null to list the gh account's own;
- * the ids of the sources the picker offers, in order, or null for the
- * default order; and the git transports the daemon fetches over.
+ * Where workspace sources come from and where their checkouts land: the
+ * GitHub owner whose repositories the spawn picker lists by default, or
+ * null to list the gh account's own; the ids of the sources the picker
+ * offers, in order, or null for the default order; the git transports the
+ * daemon fetches over; the root a checkout lands under on any target
+ * without its own, or null for the default; and each target's own root, by
+ * target id. A root is kept as written: whether it fits its target, such
+ * as `~` on a remote target, is checked where the target is known.
  */
 export interface WorkspacesConfig {
   readonly githubOwner: string | null;
   readonly sources: readonly string[] | null;
   readonly gitTransports: readonly string[] | InvalidGitTransports;
+  readonly root: string | null;
+  readonly targetRoots: ReadonlyMap<string, string>;
 }
 
 /**
@@ -34,17 +40,20 @@ const GITHUB_OWNER_PATTERN = /^[A-Za-z\d][A-Za-z\d-]{0,38}$/u;
 /**
  * Reads the `workspaces` section of config.json. An owner that is not a
  * GitHub login is dropped, so a typo lists the gh account's own
- * repositories instead of failing, and a source order that is not a list
- * of ids falls back to the default order. A transport list that is not a
+ * repositories instead of failing, a source order that is not a list of
+ * ids falls back to the default order, and a root that is not a non-empty
+ * string is dropped. A transport list that is not a
  * list of transports atc allows is a config error, and the list is then
  * invalid, never the default, so the daemon runs no git until it is fixed.
  * An empty list is valid and allows no transport.
  */
 export function collectWorkspacesConfig(raw: unknown): CollectedWorkspacesConfig {
-  const owner = isRecord(raw) ? raw['githubOwner'] : undefined;
-  const sources = isRecord(raw) ? raw['sources'] : undefined;
-  const rawTransports = isRecord(raw) ? raw['gitTransports'] : undefined;
-  const transports = collectGitTransports(rawTransports);
+  const section = isRecord(raw) ? raw : {};
+  const owner = section['githubOwner'];
+  const sources = section['sources'];
+  const root = section['root'];
+  const targets = isRecord(section['targets']) ? section['targets'] : {};
+  const transports = collectGitTransports(section['gitTransports']);
 
   return {
     workspaces: {
@@ -55,6 +64,12 @@ export function collectWorkspacesConfig(raw: unknown): CollectedWorkspacesConfig
           ? sources
           : null,
       gitTransports: transports.transports,
+      root: typeof root === 'string' && root !== '' ? root : null,
+      targetRoots: new Map(
+        Object.entries(targets).flatMap(([id, dir]) =>
+          typeof dir === 'string' && dir !== '' ? [[id, dir] as const] : [],
+        ),
+      ),
     },
     errors: transports.errors,
   };

package/src/shared/config.ts

@@ -3,6 +3,8 @@ import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { buildOptionalString } from './build-optional-string';
 import { buildOptionalStringArray } from './build-optional-string-array';
+import { collectAuthProfiles } from './collect-auth-profiles';
+import type { AuthProfile } from './collect-auth-profiles';
 import { collectDirRoots } from './collect-dir-roots';
 import { collectGateways } from './collect-gateways';
 import type { GatewayConfig } from './collect-gateways';
@@ -28,6 +30,14 @@ export interface Config {
   dirs: DirsConfig;
   workspaces: WorkspacesConfig;
   gateways: GatewayConfig[];
+
+  // The problems that kept a gateway with auth out of the gateways.
+  gatewayErrors: readonly string[];
+
+  // The credential references a gateway's auth selects from, by profile
+  // name, and the problems that kept a profile out.
+  authProfiles: ReadonlyMap<string, AuthProfile>;
+  authProfileErrors: readonly string[];
   hooks: HooksConfig;
   leader: LeaderKey;
 
@@ -70,8 +80,17 @@ const DEFAULTS: Config = {
   codexBin: 'codex',
   codexArgs: [],
   dirs: { roots: [] },
-  workspaces: { githubOwner: null, sources: null, gitTransports: DEFAULT_GIT_TRANSPORTS },
+  workspaces: {
+    githubOwner: null,
+    sources: null,
+    gitTransports: DEFAULT_GIT_TRANSPORTS,
+    root: null,
+    targetRoots: new Map(),
+  },
   gateways: [],
+  gatewayErrors: [],
+  authProfiles: new Map(),
+  authProfileErrors: [],
   hooks: {},
   leader: { code: 0, label: '^Space' },
   targets: [{ id: 'local', provider: 'local-pty', options: {} }],
@@ -112,6 +131,7 @@ const CONFIG_SCHEMA = z.object({
   dirs: z.unknown().optional(),
   workspaces: z.unknown().optional(),
   gateways: z.unknown().optional(),
+  authProfiles: z.unknown().optional(),
   hooks: z.unknown().optional(),
   leader: buildOptionalString(),
   targets: z.unknown().optional(),
@@ -200,21 +220,33 @@ function tryWriteDefaultConfig(file: string): void {
 /**
  * The config.json text a first run writes. It leaves out the targets and
  * principals, so the file holds the one implicit `local` target and no
- * principals until the user sets their own, and the errors a parse
- * reports, which belong to no file.
+ * principals until the user sets their own, no auth profiles, and the
+ * errors a parse reports, which belong to no file.
  */
 export function renderDefaultConfig(): string {
   const {
+    gatewayErrors: _gatewayErrors,
+    authProfiles: _authProfiles,
+    authProfileErrors: _authProfileErrors,
     targets: _targets,
     defaultTarget: _default,
     targetErrors: _errors,
     principals: _principals,
     principalErrors: _principalErrors,
     workspaceErrors: _workspaceErrors,
+    workspaces,
     ...written
   } = DEFAULTS;
 
-  return `${JSON.stringify(written, null, 2)}\n`;
+  // The target roots are a map in memory and an object of target ids in
+  // the file.
+  const { targetRoots, ...rest } = workspaces;
+
+  return `${JSON.stringify(
+    { ...written, workspaces: { ...rest, targets: Object.fromEntries(targetRoots) } },
+    null,
+    2,
+  )}\n`;
 }
 
 /**
@@ -251,7 +283,15 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
   const codexArgs = parsed.data.codexArgs ?? DEFAULTS.codexArgs;
   const dirs = { roots: collectDirRoots(parsed.data.dirs) };
   const workspaces = collectWorkspacesConfig(parsed.data.workspaces);
-  const gateways = collectGateways(parsed.data.gateways, claudeBin, claudeArgs);
+  const authProfiles = collectAuthProfiles(parsed.data.authProfiles);
+
+  const gateways = collectGateways(
+    parsed.data.gateways,
+    claudeBin,
+    claudeArgs,
+    authProfiles.profiles,
+  );
+
   const hooks = collectHooks(parsed.data.hooks);
   const targets = collectTargets(parsed.data.targets, parsed.data.defaultTarget);
   const principals = collectPrincipals(parsed.data.principals);
@@ -268,7 +308,10 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
     codexArgs,
     dirs,
     workspaces: workspaces.workspaces,
-    gateways,
+    gateways: gateways.gateways,
+    gatewayErrors: gateways.errors,
+    authProfiles: authProfiles.profiles,
+    authProfileErrors: authProfiles.errors,
     hooks,
     leader,
     targets: targets.targets,

package/src/shared/resolve-auth-profiles.ts

@@ -0,0 +1,186 @@
+import type { AuthProfile } from './collect-auth-profiles';
+
+/**
+ * How impd applies one secret to requests for one host.
+ */
+interface AuthRule {
+  readonly host: string;
+  readonly header: string;
+  readonly scheme: 'bearer';
+}
+
+/**
+ * One secret and the complete set of rules a selection needs impd to hold
+ * for it, one per host, sorted by host.
+ */
+export interface ResolvedAuthSecret {
+  readonly secret: string;
+  readonly kind: 'custom';
+  readonly rules: readonly AuthRule[];
+}
+
+/**
+ * A selection with its dependencies expanded: every profile it reaches,
+ * every host those profiles send a credential to, and the rules grouped by
+ * secret, each list sorted so two selections of the same profiles resolve
+ * the same.
+ */
+interface ResolvedAuthProfiles {
+  readonly profiles: readonly string[];
+  readonly hosts: readonly string[];
+  readonly secrets: readonly ResolvedAuthSecret[];
+}
+
+/**
+ * Why a selection cannot be bound:
+ *
+ * - `auth_profile_unknown`: it reaches a profile that is missing or that
+ *   the config refused.
+ * - `auth_dependency_cycle`: the dependencies loop back on themselves.
+ * - `auth_collision`: two profiles send different credentials or rules to
+ *   one host, which impd could not tell apart.
+ */
+export interface AuthProfileProblem {
+  readonly code: 'auth_profile_unknown' | 'auth_dependency_cycle' | 'auth_collision';
+  readonly message: string;
+}
+
+export type AuthProfileResolution =
+  | { readonly resolved: ResolvedAuthProfiles }
+  | { readonly problem: AuthProfileProblem };
+
+/**
+ * Expands the selected profiles through their dependencies, then checks
+ * the whole expanded set: each host must get exactly one rule, so a
+ * credential is never picked by order. Two profiles holding the identical
+ * secret and rule for a host merge into one rule.
+ */
+export function resolveAuthProfiles(
+  profiles: ReadonlyMap<string, AuthProfile>,
+  selected: readonly string[],
+): AuthProfileResolution {
+  let reached: ReadonlyMap<string, AuthProfile> = new Map();
+
+  for (const name of selected) {
+    const next = collectReached(profiles, name, null, [], reached);
+
+    if (isAuthProfileProblem(next)) {
+      return { problem: next };
+    }
+
+    reached = next;
+  }
+
+  const ordered = [...reached.values()].toSorted((a, b) => (a.name < b.name ? -1 : 1));
+
+  const byHost = new Map<string, AuthProfile>();
+
+  for (const profile of ordered) {
+    const other = byHost.get(profile.host);
+
+    if (other === undefined) {
+      byHost.set(profile.host, profile);
+    } else if (!hasSameRule(other, profile)) {
+      return {
+        problem: {
+          code: 'auth_collision',
+          message: `profiles ${other.name} and ${profile.name} both send a credential to ${profile.host}`,
+        },
+      };
+    }
+  }
+
+  return {
+    resolved: {
+      profiles: ordered.map((profile) => profile.name),
+      hosts: [...byHost.keys()].toSorted(),
+      secrets: buildSecrets([...byHost.values()]),
+    },
+  };
+}
+
+// Depth-first over the dependencies from one name: returns `reached` plus
+// every profile this name reaches, each added once its own dependencies are
+// done. A profile already reached is not walked again, so a shared
+// dependency costs one visit.
+// `path` holds the names on the way here, so a name already on it closes a
+// cycle.
+function collectReached(
+  profiles: ReadonlyMap<string, AuthProfile>,
+  name: string,
+  from: string | null,
+  path: readonly string[],
+  reached: ReadonlyMap<string, AuthProfile>,
+): ReadonlyMap<string, AuthProfile> | AuthProfileProblem {
+  if (path.includes(name)) {
+    return {
+      code: 'auth_dependency_cycle',
+      message: `profile dependencies form a cycle: ${[...path.slice(path.indexOf(name)), name].join(' -> ')}`,
+    };
+  }
+
+  if (reached.has(name)) {
+    return reached;
+  }
+
+  const profile = profiles.get(name);
+
+  if (profile === undefined) {
+    return {
+      code: 'auth_profile_unknown',
+      message:
+        from === null
+          ? `profile ${name} is selected, but authProfiles has no usable profile by that name`
+          : `profile ${from} depends on ${name}, but authProfiles has no usable profile by that name`,
+    };
+  }
+
+  let next = reached;
+
+  for (const dependency of profile.dependencies) {
+    const after = collectReached(profiles, dependency, name, [...path, name], next);
+
+    if (isAuthProfileProblem(after)) {
+      return after;
+    }
+
+    next = after;
+  }
+
+  return new Map([...next, [name, profile]]);
+}
+
+function isAuthProfileProblem(
+  value: ReadonlyMap<string, AuthProfile> | AuthProfileProblem,
+): value is AuthProfileProblem {
+  return 'code' in value;
+}
+
+function hasSameRule(left: AuthProfile, right: AuthProfile): boolean {
+  return (
+    left.secret === right.secret &&
+    left.header === right.header &&
+    left.scheme === right.scheme &&
+    left.kind === right.kind
+  );
+}
+
+// One entry per secret, sorted by secret, each with its rules sorted by host.
+function buildSecrets(profiles: readonly AuthProfile[]): ResolvedAuthSecret[] {
+  const rules = new Map<string, AuthRule[]>();
+
+  for (const profile of profiles) {
+    const list = rules.get(profile.secret) ?? [];
+
+    list.push({ host: profile.host, header: profile.header, scheme: profile.scheme });
+    rules.set(profile.secret, list);
+  }
+
+  return [...rules.entries()]
+    .toSorted(([a], [b]) => (a < b ? -1 : 1))
+    .map(([secret, list]) => ({
+      secret,
+      kind: 'custom',
+      rules: list.toSorted((a, b) => (a.host < b.host ? -1 : 1)),
+    }));
+}