@zgeoff/atc 2.36.0 → 2.37.0

package/src/shared/check-gateway-auth.ts

@@ -0,0 +1,173 @@
+import type { AuthProfile } from './collect-auth-profiles';
+import { isBrokerVariable } from './is-broker-variable';
+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>>;
+}
+
+/**
+ * The fields of a gateway entry that its auth is checked against.
+ */
+interface GatewayAuthEntry {
+  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.
+export function checkGatewayAuth(
+  raw: unknown,
+  entry: GatewayAuthEntry,
+  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}`);
+}
+
+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;
+}

package/src/shared/collect-agents.ts

@@ -0,0 +1,326 @@
+import type { AgentID } from './agent-id';
+import { checkGatewayAuth } from './check-gateway-auth';
+import type { GatewayAuth } from './check-gateway-auth';
+import type { AuthProfile } from './collect-auth-profiles';
+import { collectClaudeAuth } from './collect-claude-auth';
+import { isSubscriptionOverrideVariable } from './is-subscription-override-variable';
+import { isRecord } from './report';
+
+/**
+ * The agent CLI an entry drives, which decides the adapter behind it.
+ */
+type AgentKind = 'claude' | 'codex' | 'grok';
+
+/**
+ * One agent atc offers: its id, how it appears in the spawn menu, the binary
+ * and arguments it starts with, and, for a Claude entry, the settings, the
+ * environment, and the backend and credential it runs against. A Claude entry
+ * with a `baseURL` is a gateway; without one it is stock Claude, whose
+ * `auth` holds profiles alone, for the subscription sign-in.
+ */
+export interface AgentEntry {
+  readonly id: AgentID;
+  readonly kind: AgentKind;
+  readonly label: string;
+  readonly mark: string;
+  readonly bin: string;
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string>>;
+  readonly settings?: Readonly<Record<string, unknown>>;
+  readonly baseURL?: string;
+  readonly apiKeyHelper?: string;
+  readonly auth?: GatewayAuth;
+}
+
+interface CollectedAgents {
+  readonly agents: AgentEntry[];
+
+  // One line per problem, each starting with the entry it refused.
+  readonly errors: string[];
+}
+
+/**
+ * Reads the `agents` map into registry order. An entry that is not an object,
+ * sets an unknown field or a field outside its kind, holds a wrong-typed
+ * value, or fails an auth check is left out with every problem that refused
+ * it, and the other entries load. A value that is not an object leaves the
+ * registry empty.
+ */
+export function collectAgents(
+  raw: unknown,
+  authProfiles: ReadonlyMap<string, AuthProfile> = new Map(),
+): CollectedAgents {
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return { agents: [], errors: ['agents must be an object of agent entries'] };
+  }
+
+  const agents: AgentEntry[] = [];
+  const errors: string[] = [];
+
+  for (const [id, entry] of Object.entries(raw)) {
+    const parsed = parseAgentEntry(id, entry, authProfiles);
+
+    if ('problems' in parsed) {
+      errors.push(...parsed.problems.map((problem) => `agents.${id}: ${problem}`));
+    } else {
+      agents.push(parsed.entry);
+    }
+  }
+
+  return { agents, errors };
+}
+
+const KINDS: readonly AgentKind[] = ['claude', 'codex', 'grok'];
+
+function isAgentKind(value: unknown): value is AgentKind {
+  return KINDS.some((kind) => kind === value);
+}
+
+// The fields every kind takes, and the ones only a Claude entry takes.
+const COMMON_FIELDS = new Set(['kind', 'label', 'mark', 'bin', 'args']);
+const CLAUDE_FIELDS = new Set(['settings', 'env', 'baseURL', 'apiKeyHelper', 'auth']);
+
+const DEFAULT_LABELS: Readonly<Record<AgentKind, string>> = {
+  claude: 'Claude',
+  codex: 'Codex',
+  grok: 'Grok',
+};
+
+type ParsedEntry = { readonly entry: AgentEntry } | { readonly problems: string[] };
+
+function parseAgentEntry(
+  id: string,
+  raw: unknown,
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): ParsedEntry {
+  if (id === '' || id === '__proto__') {
+    return { problems: ['the id cannot be used'] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return { problems: ['the entry must be an object'] };
+  }
+
+  const found = findKind(id, raw['kind']);
+
+  if ('problem' in found) {
+    return { problems: [found.problem] };
+  }
+
+  const problems = collectFieldProblems(raw, found.kind);
+
+  if (problems.length > 0) {
+    return { problems };
+  }
+
+  const entry = buildEntry(id, found.kind, raw);
+
+  if (found.kind !== 'claude') {
+    return { entry };
+  }
+
+  const claude = readClaudeAuth(entry, raw['auth'], authProfiles);
+
+  if ('problems' in claude) {
+    return claude;
+  }
+
+  return { entry: { ...entry, ...claude } };
+}
+
+// The entry's kind, or the problem that refuses it. An absent kind is the id
+// for one of the three ids that name a kind, and a problem for any other.
+function findKind(
+  id: string,
+  raw: unknown,
+): { readonly kind: AgentKind } | { readonly problem: string } {
+  const named = KINDS.find((kind) => kind === id);
+
+  if (raw === undefined) {
+    return named === undefined
+      ? { problem: 'kind is required for an id other than claude, codex, or grok' }
+      : { kind: named };
+  }
+
+  if (!isAgentKind(raw)) {
+    return { problem: 'kind must be claude, codex, or grok' };
+  }
+
+  if (named !== undefined && named !== raw) {
+    return { problem: `kind ${raw} contradicts the id ${id}` };
+  }
+
+  return { kind: raw };
+}
+
+function collectFieldProblems(raw: Readonly<Record<string, unknown>>, kind: AgentKind): string[] {
+  const problems: string[] = [];
+
+  for (const [name, value] of Object.entries(raw)) {
+    if (CLAUDE_FIELDS.has(name) && kind !== 'claude') {
+      problems.push(`${name} is not valid for kind ${kind}`);
+      continue;
+    }
+
+    if (!COMMON_FIELDS.has(name) && !CLAUDE_FIELDS.has(name)) {
+      problems.push(`unknown field ${name}`);
+      continue;
+    }
+
+    const problem = findFieldProblem(name, value);
+
+    if (problem !== null) {
+      problems.push(problem);
+    }
+  }
+
+  return problems;
+}
+
+// The problem with one field's value, or null. `kind` and `auth` are checked
+// elsewhere.
+function findFieldProblem(name: string, value: unknown): string | null {
+  switch (name) {
+    case 'label':
+    case 'mark':
+    case 'bin':
+    case 'baseURL':
+    case 'apiKeyHelper': {
+      return typeof value === 'string' && value !== ''
+        ? null
+        : `${name} must be a non-empty string`;
+    }
+    case 'args': {
+      return Array.isArray(value) && value.every((arg) => typeof arg === 'string')
+        ? null
+        : 'args must be an array of strings';
+    }
+    case 'env': {
+      return isStringRecord(value) ? null : 'env must be an object of strings';
+    }
+    case 'settings': {
+      return isRecord(value) && !Array.isArray(value) ? null : 'settings must be an object';
+    }
+    default: {
+      return null;
+    }
+  }
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    isRecord(value) &&
+    !Array.isArray(value) &&
+    Object.values(value).every((v) => typeof v === 'string')
+  );
+}
+
+// An entry with every default applied, from fields already checked.
+function buildEntry(
+  id: string,
+  kind: AgentKind,
+  raw: Readonly<Record<string, unknown>>,
+): AgentEntry {
+  const label = raw['label'];
+  const mark = raw['mark'];
+  const bin = raw['bin'];
+  const args = raw['args'];
+  const env = raw['env'];
+  const settings = raw['settings'];
+  const baseURL = raw['baseURL'];
+  const apiKeyHelper = raw['apiKeyHelper'];
+  const markSource = typeof mark === 'string' ? mark : id;
+
+  return {
+    id,
+    kind,
+    label: typeof label === 'string' ? label : buildDefaultLabel(id, kind),
+    mark: String.fromCodePoint(markSource.codePointAt(0) ?? 0),
+    bin: typeof bin === 'string' ? bin : kind,
+    args: Array.isArray(args) ? args.map(String) : [],
+    env: isStringRecord(env) ? env : {},
+    ...(isRecord(settings) ? { settings } : {}),
+    ...(typeof baseURL === 'string' ? { baseURL } : {}),
+    ...(typeof apiKeyHelper === 'string' ? { apiKeyHelper } : {}),
+  };
+}
+
+// The three ids that name a kind show that kind's name; any other id shows
+// itself.
+function buildDefaultLabel(id: string, kind: AgentKind): string {
+  return id === kind ? DEFAULT_LABELS[kind] : id;
+}
+
+// The `auth` a Claude entry holds, or every problem with it. With a base URL
+// the entry is a gateway and its auth is the gateway's. Without one it is
+// stock Claude, whose auth is profiles alone and whose environment may not
+// override or route around the subscription sign-in.
+function readClaudeAuth(
+  entry: AgentEntry,
+  raw: unknown,
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): { readonly auth?: GatewayAuth } | { readonly problems: string[] } {
+  if (entry.baseURL !== undefined) {
+    if (raw === undefined) {
+      return {};
+    }
+
+    const checked = checkGatewayAuth(
+      raw,
+      {
+        baseURL: entry.baseURL,
+        apiKeyHelper: entry.apiKeyHelper,
+        env: entry.env,
+        settings: entry.settings,
+      },
+      authProfiles,
+    );
+
+    return Array.isArray(checked) ? { problems: checked } : { auth: checked };
+  }
+
+  const problems =
+    entry.apiKeyHelper === undefined ? [] : ['apiKeyHelper is only valid together with baseURL'];
+
+  if (raw === undefined) {
+    return problems.length > 0 ? { problems } : {};
+  }
+
+  const collected = collectClaudeAuth(raw, authProfiles, 'auth');
+
+  problems.push(...collected.errors, ...collectSubscriptionProblems(entry));
+
+  if (problems.length > 0 || collected.auth === null) {
+    return { problems };
+  }
+
+  return { auth: { profiles: collected.auth.profiles, placeholderEnv: {} } };
+}
+
+// What a stock entry with `auth` sets that would override the subscription
+// sign-in or route the CLI around impd's broker.
+function collectSubscriptionProblems(entry: AgentEntry): string[] {
+  const settingsEnv = entry.settings?.['env'];
+
+  const settingsKeys =
+    isRecord(settingsEnv) && !Array.isArray(settingsEnv) ? Object.keys(settingsEnv) : [];
+
+  const problems = [
+    ...Object.keys(entry.env)
+      .filter((key) => isSubscriptionOverrideVariable(key))
+      .map((key) => `env must not set ${key}${OVERRIDE_REASON}`),
+    ...settingsKeys
+      .filter((key) => isSubscriptionOverrideVariable(key))
+      .map((key) => `settings.env must not set ${key}${OVERRIDE_REASON}`),
+  ];
+
+  if (entry.settings?.['apiKeyHelper'] !== undefined) {
+    problems.push(
+      'settings.apiKeyHelper must not be set, which would override the subscription sign-in',
+    );
+  }
+
+  return problems;
+}
+
+const OVERRIDE_REASON = ', which would override or route around the subscription sign-in';

package/src/shared/collect-claude-auth.ts

@@ -8,7 +8,7 @@ import { resolveAuthProfiles } from './resolve-auth-profiles';
  * token to the Anthropic API as a bearer authorization header, and the
  * rest bind beside it, such as a GitHub token.
  */
-export interface ClaudeAuth {
+interface ClaudeAuth {
   readonly profiles: readonly string[];
 }
 
@@ -18,7 +18,8 @@ interface CollectedClaudeAuth {
 }
 
 /**
- * Reads the `claudeAuth` entry against the auth profiles. An entry that
+ * Reads a Claude subscription auth entry against the auth profiles, `field`
+ * being the key it was set under in error text. An entry that
  * does not resolve, or whose profiles send no bearer authorization header
  * to the Anthropic API, is left out with every problem that refused it, so
  * stock Claude keeps the sign-in of the host it runs on rather than binding
@@ -27,6 +28,7 @@ interface CollectedClaudeAuth {
 export function collectClaudeAuth(
   raw: unknown,
   authProfiles: ReadonlyMap<string, AuthProfile>,
+  field = 'claudeAuth',
 ): CollectedClaudeAuth {
   if (raw === undefined) {
     return { auth: null, errors: [] };
@@ -42,7 +44,7 @@ export function collectClaudeAuth(
   ) {
     return {
       auth: null,
-      errors: ['claudeAuth must be an object with a non-empty profiles array'],
+      errors: [`${field} must be an object with a non-empty profiles array`],
     };
   }
 
@@ -52,7 +54,7 @@ export function collectClaudeAuth(
     return {
       auth: null,
       errors: [
-        `claudeAuth.${extra} cannot be set: atc fixes the endpoint and the placeholder of a Claude subscription session`,
+        `${field}.${extra} cannot be set: atc fixes the endpoint and the placeholder of a Claude subscription session`,
       ],
     };
   }
@@ -61,7 +63,7 @@ export function collectClaudeAuth(
   const resolution = resolveAuthProfiles(authProfiles, selected);
 
   if ('problem' in resolution) {
-    return { auth: null, errors: [`claudeAuth: ${resolution.problem.message}`] };
+    return { auth: null, errors: [`${field}: ${resolution.problem.message}`] };
   }
 
   const rule = resolution.resolved.secrets
@@ -72,7 +74,7 @@ export function collectClaudeAuth(
     return {
       auth: null,
       errors: [
-        `claudeAuth needs a profile that sets a bearer authorization header for ${ANTHROPIC_API_HOST}, where Claude Code sends its subscription token`,
+        `${field} needs a profile that sets a bearer authorization header for ${ANTHROPIC_API_HOST}, where Claude Code sends its subscription token`,
       ],
     };
   }