@zgeoff/atc 2.23.0 → 2.25.0

package/src/daemon/verify-broker-authority.ts

@@ -15,8 +15,9 @@ export interface BrokerActivation {
 /**
  * The gate before atc grants or relies on a brokered credential. It reads
  * impd's features, then the token's identity, and writes nothing, so a
- * refusal leaves impd as it was. It rejects unless impd has both grantable
- * tokens and secret rebinds, the token may manage each imp and reaches no
+ * refusal leaves impd as it was. It rejects unless impd has grantable
+ * tokens, secret rebinds and exec requirements, so a start can refuse to
+ * run without a ready broker, the token may manage each imp and reaches no
  * imp outside the namespace whose imp names start with the prefix, and the
  * token may grant every bound secret.
  * Whether each secret's rules match the binding is a separate comparison.
@@ -28,11 +29,15 @@ export async function verifyBrokerAuthority(
 ): Promise<void> {
   const features = await port.readFeatures();
 
-  if (!features.grantableTokens || !features.secretRebind) {
+  if (!features.grantableTokens || !features.secretRebind || !features.execRequire) {
     throw new BrokerAuthorityError(
       'auth_impd_too_old',
-      'impd lacks grantable tokens or secret rebinds; it must be 0.27.0 or later',
-      { grantableTokens: features.grantableTokens, secretRebind: features.secretRebind },
+      'impd lacks grantable tokens, secret rebinds or exec requirements; it must be 0.30.0 or later',
+      {
+        grantableTokens: features.grantableTokens,
+        secretRebind: features.secretRebind,
+        execRequire: features.execRequire,
+      },
     );
   }
 

package/src/gateway.ts

@@ -0,0 +1,183 @@
+import { join } from 'node:path';
+import { defineCommand, runMain } from 'citty';
+import pkg from '../package.json';
+import { collectRedirectURIs } from './collect-redirect-uris';
+import { parseGatewayStateDir } from './parse-gateway-state-dir';
+import { parsePort } from './parse-port';
+
+// The flag every subcommand takes for the directory holding `gateway.db` and
+// `mcp-auth.db`.
+const STATE_DIR_ARG = {
+  'state-dir': {
+    type: 'string',
+    description: 'Directory for gateway.db and mcp-auth.db (default $ATC_GATEWAY_STATE_DIR)',
+  },
+} as const;
+
+// Every flag a subcommand declares, so a flag in any position, or one no
+// subcommand declares, is caught before a subcommand runs.
+const GATEWAY_FLAGS = {
+  values: new Set(['host', 'port', 'public-url', 'registry', 'redirect-uri', 'state-dir']),
+  switches: new Set(['help', 'h', 'version']),
+};
+
+// The state directory comes from the whole command line, since the argument
+// parser hands a subcommand only the arguments after its name.
+const parsedStateDir = parseGatewayStateDir(process.argv.slice(2), process.env, GATEWAY_FLAGS);
+
+if (!parsedStateDir.ok) {
+  console.error(`atc-gateway: ${parsedStateDir.message}`);
+  process.exit(1);
+}
+
+const stateDir = parsedStateDir.stateDir;
+const NO_STATE_DIR = 'atc-gateway: give --state-dir or set ATC_GATEWAY_STATE_DIR';
+
+// atc-gateway entry: serves the MCP tools over HTTP for the daemons a
+// registry lists, and manages the clients that may connect to it. It loads
+// nothing that starts a daemon or a session on this machine.
+const main = defineCommand({
+  meta: {
+    name: 'atc-gateway',
+    version: pkg.version,
+    description: 'Serve the atc MCP tools over HTTP for the daemons a registry lists',
+  },
+
+  // Declared at every level, so the argument parser reads `--state-dir <dir>`
+  // before a subcommand as a flag and its value, not as a subcommand name.
+  args: STATE_DIR_ARG,
+  subCommands: {
+    serve: () =>
+      defineCommand({
+        meta: { name: 'serve', description: 'Serve MCP over HTTP behind OAuth' },
+        args: {
+          host: { type: 'string', description: 'Address to bind (default 127.0.0.1)' },
+          port: { type: 'string', description: 'Port to listen on (default 8414)' },
+          'public-url': {
+            type: 'string',
+            required: true,
+            description: 'Origin clients reach the gateway at, such as https://mcp.example.com',
+          },
+          registry: { type: 'string', required: true, description: 'The registry JSON file' },
+          ...STATE_DIR_ARG,
+        },
+        async run(ctx) {
+          const port = ctx.args.port === undefined ? null : parsePort(ctx.args.port);
+
+          if (port !== null && !port.ok) {
+            console.error(`atc-gateway: ${port.message}`);
+            process.exit(1);
+          }
+
+          if (stateDir === null) {
+            console.error(NO_STATE_DIR);
+            process.exit(1);
+          }
+
+          const gateway = await import('./run-gateway');
+
+          await gateway.runGateway(`atc-gateway/${pkg.version}`, {
+            host: ctx.args.host ?? '127.0.0.1',
+            port: port === null ? 8414 : port.port,
+            publicURL: ctx.args['public-url'],
+            registryPath: ctx.args.registry,
+            stateDir,
+          });
+        },
+      }),
+    clients: () =>
+      defineCommand({
+        meta: {
+          name: 'clients',
+          description: 'List, add, or remove the clients that may connect to the gateway',
+        },
+        args: STATE_DIR_ARG,
+        default: 'list',
+        subCommands: {
+          list: () =>
+            defineCommand({
+              meta: { name: 'list', description: 'List the clients', hidden: true },
+              args: STATE_DIR_ARG,
+              async run() {
+                if (stateDir === null) {
+                  console.error(NO_STATE_DIR);
+                  process.exit(1);
+                }
+
+                const clients = await import('./clients');
+
+                await clients.runClients(
+                  { kind: 'list' },
+                  {
+                    dbPath: join(stateDir, 'mcp-auth.db'),
+                    command: 'atc-gateway clients',
+                  },
+                );
+              },
+            }),
+          add: () =>
+            defineCommand({
+              meta: { name: 'add', description: 'Add a client and print its client ID' },
+              args: {
+                name: { type: 'positional', required: true, description: 'The client name' },
+                'redirect-uri': {
+                  type: 'string',
+                  required: true,
+                  description: 'A redirect URI the client returns to; repeat for more',
+                },
+                ...STATE_DIR_ARG,
+              },
+              async run(ctx) {
+                if (stateDir === null) {
+                  console.error(NO_STATE_DIR);
+                  process.exit(1);
+                }
+
+                const clients = await import('./clients');
+
+                await clients.runClients(
+                  {
+                    kind: 'add',
+                    name: ctx.args.name,
+                    redirectURIs: collectRedirectURIs(ctx.rawArgs),
+                  },
+                  {
+                    dbPath: join(stateDir, 'mcp-auth.db'),
+                    command: 'atc-gateway clients',
+                  },
+                );
+              },
+            }),
+          remove: () =>
+            defineCommand({
+              meta: {
+                name: 'remove',
+                description: 'Remove a client and revoke every grant it holds',
+              },
+              args: {
+                id: { type: 'positional', required: true, description: 'The client ID' },
+                ...STATE_DIR_ARG,
+              },
+              async run(ctx) {
+                if (stateDir === null) {
+                  console.error(NO_STATE_DIR);
+                  process.exit(1);
+                }
+
+                const clients = await import('./clients');
+
+                await clients.runClients(
+                  { kind: 'remove', clientID: ctx.args.id },
+                  {
+                    dbPath: join(stateDir, 'mcp-auth.db'),
+                    command: 'atc-gateway clients',
+                  },
+                );
+              },
+            }),
+        },
+      }),
+  },
+});
+
+await runMain(main);

package/src/mcp/mcp-tools.ts

@@ -213,6 +213,7 @@ const AGENTS_OUTPUT: Readonly<Record<string, unknown>> = {
           label: { type: 'string' },
           kind: { type: 'string' },
           installed: { type: 'boolean' },
+          brokerAuth: { type: 'boolean' },
           capabilities: {
             type: 'object',
             properties: {
@@ -249,6 +250,7 @@ const AGENTS_OUTPUT: Readonly<Record<string, unknown>> = {
             type: 'object',
             additionalProperties: { type: 'boolean' },
           },
+          brokerAuth: { type: 'boolean' },
         },
         required: ['id', 'provider', 'identity', 'available', 'default', 'capabilities'],
       },

package/src/mcp/require-daemon-features.ts

@@ -23,6 +23,7 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'git.probe': 'git.probe',
   'transport.tcp': 'a TCP connection to the daemon',
   'idempotency.replayOnly': 'a resend that only replays a held idempotency key',
+  'session.auth': 'session.auth.revoke and session.auth.rebind',
 };
 
 /**

package/src/parse-gateway-state-dir.ts

@@ -0,0 +1,94 @@
+/**
+ * The flags `atc-gateway` accepts anywhere on its command line: those that
+ * take a value, and switches that take none. Names are written without
+ * their leading dashes.
+ */
+export interface GatewayFlags {
+  readonly values: ReadonlySet<string>;
+  readonly switches: ReadonlySet<string>;
+}
+
+type ParsedStateDir =
+  | { readonly ok: true; readonly stateDir: string | null }
+  | { readonly ok: false; readonly message: string };
+
+// A flag: one or two dashes, a name, and an optional `=<value>`. A lone `-`
+// is a positional.
+const FLAG_PATTERN = /^--?(?<name>[^=]+)(?:=(?<value>[\s\S]*))?$/;
+
+/**
+ * Finds the state directory in the whole `atc-gateway` command line, before,
+ * between, or after its subcommands, so no position can drop the flag.
+ * `--state-dir <dir>` and `--state-dir=<dir>` count; a value after `--` or
+ * held by another flag never does. Every `--state-dir` must give the same
+ * directory. The flag wins over `ATC_GATEWAY_STATE_DIR`, and with neither
+ * the result is null. A flag the gateway does not know, a switch given a
+ * value, and a flag whose value is missing or starts with `-` are refused,
+ * since reading them either way could pick the wrong directory.
+ */
+export function parseGatewayStateDir(
+  argv: readonly string[],
+  env: Readonly<Record<string, string | undefined>>,
+  flags: GatewayFlags,
+): ParsedStateDir {
+  const given: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i] ?? '';
+
+    if (token === '--') {
+      break;
+    }
+
+    const match = FLAG_PATTERN.exec(token);
+
+    if (match === null) {
+      continue;
+    }
+
+    const name = match.groups?.['name'] ?? '';
+    const inline = match.groups?.['value'];
+
+    if (flags.switches.has(name)) {
+      if (inline !== undefined) {
+        return { ok: false, message: `${token} takes no value` };
+      }
+
+      continue;
+    }
+
+    if (!flags.values.has(name)) {
+      return { ok: false, message: `unknown flag '${token}'` };
+    }
+
+    const value = inline ?? argv[i + 1];
+
+    if (inline === undefined) {
+      i++;
+    }
+
+    if (value === undefined || value === '' || (inline === undefined && value.startsWith('-'))) {
+      return { ok: false, message: `--${name} needs a value; write --${name}=<value>` };
+    }
+
+    if (name === 'state-dir') {
+      given.push(value);
+    }
+  }
+
+  const distinct = [...new Set(given)];
+
+  if (distinct.length > 1) {
+    return {
+      ok: false,
+      message: `--state-dir gives different directories: ${distinct.map((dir) => `'${dir}'`).join(', ')}`,
+    };
+  }
+
+  const fromEnv = env['ATC_GATEWAY_STATE_DIR'];
+
+  return {
+    ok: true,
+    stateDir: distinct[0] ?? (fromEnv === undefined || fromEnv === '' ? null : fromEnv),
+  };
+}

package/src/protocol/daemon-features.ts

@@ -73,6 +73,10 @@ export const DAEMON_FEATURES = [
   // replays a key the daemon holds and refuses one it does not hold with
   // `idempotency_key_unknown`, running nothing.
   'idempotency.replayOnly',
+
+  // `session.auth.revoke` and `session.auth.rebind` exist, open to the
+  // daemon's owner only.
+  'session.auth',
 ] as const;
 
 export type DaemonFeature = (typeof DAEMON_FEATURES)[number];

package/src/protocol/protocol.ts

@@ -49,6 +49,22 @@ const ERROR_CODES = [
   'host_unavailable',
   'auth_not_configured',
   'auth_target_unsupported',
+  'auth_impd_too_old',
+  'auth_token_scope',
+  'auth_token_too_broad',
+  'auth_imp_out_of_scope',
+  'auth_secret_not_grantable',
+  'auth_secret_mismatch',
+  'auth_runtime_mismatch',
+  'auth_runtime_exists',
+  'auth_grant_missing',
+  'auth_grants_mismatch',
+  'auth_rebind_required',
+  'auth_blocked',
+  'auth_binding_mismatch',
+  'auth_binding_invalid',
+  'auth_revocation_pending',
+  'broker_not_ready',
   'host_leased',
   'confirmation_required',
   'confirm_token_invalid',

package/src/protocol/request-param-schemas.ts

@@ -204,6 +204,11 @@ export const REQUEST_PARAM_SCHEMAS = {
       .min(1, 'session.forget confirmToken must not be empty')
       .optional(),
   }),
+
+  // Owner-only: withdraw the grants of the runtime auth binding on the
+  // session's host, or bind that host to its agent's current selection.
+  'session.auth.revoke': SESSION_DEFAULTED,
+  'session.auth.rebind': SESSION_DEFAULTED,
   'session.update': SESSION_DEFAULTED.extend({
     name: buildOptionalString(),
     pinned: buildOptionalBoolean(),

package/src/run-gateway.ts

@@ -0,0 +1,93 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DaemonClient } from './client/daemon-client';
+import { loadGatewayRegistry } from './federation/load-gateway-registry';
+import { openGatewayCaller } from './federation/open-gateway-caller';
+import { startMCPHTTPServer } from './mcp/start-mcp-http-server';
+import type { MCPHTTPServer } from './mcp/start-mcp-http-server';
+
+interface GatewayFlags {
+  readonly host: string;
+  readonly port: number;
+  readonly publicURL: string;
+  readonly registryPath: string;
+  readonly stateDir: string;
+}
+
+/**
+ * Runs `atc-gateway` in the foreground: serves the MCP tools over HTTP for
+ * the daemons the registry lists, routing every call to one of them over
+ * TCP, until SIGINT or SIGTERM. It never starts or reaches a local daemon.
+ * The keyed-request bindings (`gateway.db`) and the authorization server
+ * (`mcp-auth.db`) live in the state directory, the only place it writes. A
+ * registry that fails to load, or a server that fails to start, prints the
+ * reason and exits 1.
+ */
+export async function runGateway(build: string, flags: GatewayFlags): Promise<void> {
+  const loaded = loadGatewayRegistry(flags.registryPath, process.env);
+
+  if (!loaded.ok) {
+    for (const error of loaded.errors) {
+      console.error(`atc-gateway: ${error}`);
+    }
+
+    process.exit(1);
+  }
+
+  mkdirSync(flags.stateDir, { recursive: true });
+
+  const gateway = openGatewayCaller({
+    registry: loaded.registry,
+    build,
+    openChannel: (address) => DaemonClient.open({ hostname: address.host, port: address.port }),
+    gatewayDBPath: join(flags.stateDir, 'gateway.db'),
+  });
+
+  let server: MCPHTTPServer;
+
+  try {
+    server = await startMCPHTTPServer({
+      caller: gateway.caller,
+      build,
+      host: flags.host,
+      port: flags.port,
+      publicURL: flags.publicURL,
+      allowedHosts: [],
+      dbPath: join(flags.stateDir, 'mcp-auth.db'),
+      probes: true,
+
+      // The line carries a client's name, so control and format characters
+      // are dropped before it reaches the log.
+      printApproval: (line) => {
+        console.log(line.replaceAll(/[\p{Cc}\p{Cf}]/gu, ''));
+      },
+
+      // Request lines go to stderr, so stdout keeps the approval lines alone.
+      printRequest: (line) => {
+        console.error(line);
+      },
+    });
+  } catch (error) {
+    await gateway.stop();
+
+    console.error(`atc-gateway: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+
+  console.log(`atc-gateway: serving ${server.origin}/mcp, listening on ${server.listening}`);
+
+  const stopServing = async () => {
+    await server.stop();
+    await gateway.stop();
+
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => {
+    void stopServing();
+  });
+
+  process.on('SIGTERM', () => {
+    void stopServing();
+  });
+}

package/src/shared/collect-gateways.ts

@@ -2,6 +2,7 @@ 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 { isBrokerVariable } from './is-broker-variable';
 import { isRecord } from './report';
 import { resolveAuthProfiles } from './resolve-auth-profiles';
 
@@ -251,28 +252,6 @@ function collectEnvProblems(source: string, keys: readonly string[]): string[] {
     .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)

package/src/shared/is-broker-variable.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether a variable is one 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 caller's own value would route around the broker or mask
+ * a failed CA install. Some clients read proxy and CA variables in either
+ * case, so the check ignores case.
+ */
+export function isBrokerVariable(key: string): boolean {
+  return BROKER_VARIABLES.has(key.toUpperCase());
+}
+
+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',
+]);

package/src/store/state-store.ts

@@ -1054,6 +1054,17 @@ export class StateStore {
     return row === undefined ? null : toRuntimeAuthBinding(row);
   }
 
+  // Every host's binding, by host key.
+  async collectAuthBindings(): Promise<RuntimeAuthBinding[]> {
+    const rows = await this.db
+      .selectFrom('runtime_auth_binding')
+      .selectAll()
+      .orderBy('host_key')
+      .execute();
+
+    return rows.map((row) => toRuntimeAuthBinding(row));
+  }
+
   // Writes one secret's grant row for a host, or moves the existing one to
   // the given phase, revision and attempt.
   async upsertAuthGrant(grant: Omit<RuntimeAuthGrant, 'updatedAt'>, at: number): Promise<void> {