@zgeoff/atc 2.8.1 → 2.9.0

package/src/mcp/render-consent-page.ts

@@ -0,0 +1,65 @@
+import type { GrantScope } from '../shared/grant-scope';
+import { toHTMLText } from './to-html-text';
+
+interface ConsentPageView {
+  // The signed authorization query the page posts back.
+  readonly oauthQuery: string;
+  readonly clientName: string;
+  readonly redirectURI: string;
+  readonly scopes: readonly GrantScope[];
+}
+
+const SCOPE_LABELS: Readonly<Record<GrantScope, string>> = {
+  read: 'Read sessions, transcripts, and events',
+  message:
+    'Send instructions to your agents, which can run commands on this machine; also rename, pin, and acknowledge sessions',
+  spawn: 'Spawn sessions and type into them',
+  kill: 'Kill sessions',
+};
+
+// Only reading starts granted; every scope that lets the client act starts
+// withheld.
+const GRANTED_BY_DEFAULT: ReadonlySet<GrantScope> = new Set<GrantScope>(['read']);
+
+/**
+ * The page where the operator picks what a client may do: one checkbox per
+ * scope it requested, with only `read` ticked to start. Every dynamic value is
+ * escaped.
+ */
+export function renderConsentPage(view: ConsentPageView): string {
+  const scopeRows = view.scopes
+    .map((scope) => {
+      const checked = GRANTED_BY_DEFAULT.has(scope) ? ' checked' : '';
+
+      return `<label><input type="checkbox" name="scope" value="${scope}"${checked}> ${toHTMLText(SCOPE_LABELS[scope])}</label>`;
+    })
+    .join('\n');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Choose what to allow</title>
+<style>
+body { font-family: system-ui, sans-serif; max-width: 32rem; margin: 3rem auto; padding: 0 1rem; line-height: 1.5; }
+label { display: block; margin: 0.25rem 0; }
+code { word-break: break-all; }
+button { font: inherit; margin-right: 0.5rem; }
+</style>
+</head>
+<body>
+<h1>Choose what to allow</h1>
+<p><strong>${toHTMLText(view.clientName)}</strong> returns to <code>${toHTMLText(view.redirectURI)}</code> with the access you allow here.</p>
+<form method="post" action="/consent">
+<input type="hidden" name="oauth_query" value="${toHTMLText(view.oauthQuery)}">
+<fieldset>
+<legend>Allow it to</legend>
+${scopeRows}
+</fieldset>
+<p><button type="submit" name="decision" value="approve">Allow</button><button type="submit" name="decision" value="deny">Deny</button></p>
+</form>
+</body>
+</html>
+`;
+}

package/src/mcp/render-login-page.ts

@@ -0,0 +1,47 @@
+import { toHTMLText } from './to-html-text';
+
+interface LoginPageView {
+  // The signed authorization query the page posts back.
+  readonly oauthQuery: string;
+  readonly clientName: string;
+  readonly redirectURI: string;
+  readonly error: string | null;
+}
+
+/**
+ * The page where the operator proves they run atc: the client's name, the
+ * full redirect URI, and a field for the approval code atc printed in its
+ * terminal. Every dynamic value is escaped.
+ */
+export function renderLoginPage(view: LoginPageView): string {
+  const error = view.error === null ? '' : `<p class="error">${toHTMLText(view.error)}</p>`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Approve access to atc</title>
+<style>
+body { font-family: system-ui, sans-serif; max-width: 32rem; margin: 3rem auto; padding: 0 1rem; line-height: 1.5; }
+input[name="code"] { font: inherit; font-family: ui-monospace, monospace; letter-spacing: 0.1em; padding: 0.25rem; }
+.error { color: #b00020; }
+code { word-break: break-all; }
+button { font: inherit; }
+</style>
+</head>
+<body>
+<h1>Approve access to atc</h1>
+<p><strong>${toHTMLText(view.clientName)}</strong> wants access to your atc sessions.</p>
+<p>After approval it returns to <code>${toHTMLText(view.redirectURI)}</code>.</p>
+<p>Type the approval code that <code>atc mcp --http</code> printed in its terminal.</p>
+${error}
+<form method="post" action="/login">
+<input type="hidden" name="oauth_query" value="${toHTMLText(view.oauthQuery)}">
+<label>Approval code <input name="code" autocomplete="off" autofocus required></label>
+<button type="submit">Continue</button>
+</form>
+</body>
+</html>
+`;
+}

package/src/mcp/revoke-grant.ts

@@ -0,0 +1,28 @@
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './types';
+
+/**
+ * Revokes a grant: its access and refresh tokens go, along with the
+ * consent its client holds, so the client must go through approval again.
+ * Returns false for an unknown grant id.
+ */
+export function revokeGrant(db: Kysely<MCPAuthSchema>, grantID: string): Promise<boolean> {
+  return db.transaction().execute(async (trx) => {
+    const grant = await trx
+      .selectFrom('oauthRefreshToken')
+      .select('clientId')
+      .where('authorizationCodeId', '=', grantID)
+      .executeTakeFirst();
+
+    if (grant === undefined) {
+      return false;
+    }
+
+    await trx.deleteFrom('oauthAccessToken').where('authorizationCodeId', '=', grantID).execute();
+    await trx.deleteFrom('oauthRefreshToken').where('authorizationCodeId', '=', grantID).execute();
+    await trx.deleteFrom('oauthConsent').where('clientId', '=', grant.clientId).execute();
+    await trx.deleteFrom('atc_grant_use').where('grant_id', '=', grantID).execute();
+
+    return true;
+  });
+}

package/src/mcp/run-tool.ts

@@ -0,0 +1,143 @@
+import { match } from 'ts-pattern';
+import { DaemonError } from '../protocol/daemon-error';
+import type { FleetCaller, ToolContext } from './types';
+
+export function runTool(
+  caller: FleetCaller,
+  name: string,
+  args: Readonly<Record<string, unknown>>,
+  ctx: ToolContext,
+): Promise<string> {
+  return match(name)
+    .with('atc_session_list', async () => {
+      const ok = await caller.sendRequest('session.list');
+
+      return JSON.stringify(ok['sessions'], null, 2);
+    })
+    .with('atc_session_spawn', async () => {
+      const rawAgent = args['agent'];
+      const nested = args['detached'] !== true && ctx.callerSessionID !== null;
+
+      const params = {
+        cwd: args['cwd'],
+        ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
+        ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
+        ...(rawAgent === undefined ? {} : { agent: rawAgent }),
+        cols: 100,
+        rows: 30,
+      };
+
+      const ok =
+        nested && ctx.callerSessionID !== null
+          ? await sendNestedSpawn(caller, params, ctx.callerSessionID)
+          : await caller.sendRequest('session.spawn', params);
+
+      return JSON.stringify(ok['session'], null, 2);
+    })
+    .with('atc_session_input', async () => {
+      await caller.sendRequest('session.input', {
+        session: args['session'],
+        d: `${typeof args['text'] === 'string' ? args['text'] : ''}\n`,
+      });
+
+      return 'sent';
+    })
+    .with('atc_session_screen', async () => {
+      const ok = await caller.sendRequest('session.screen', { session: args['session'] });
+
+      return typeof ok['text'] === 'string' ? ok['text'] : JSON.stringify(ok);
+    })
+    .with('atc_session_update', async () => {
+      await caller.sendRequest('session.update', {
+        session: args['session'],
+        ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
+        ...(typeof args['pinned'] === 'boolean' ? { pinned: args['pinned'] } : {}),
+      });
+
+      return 'updated';
+    })
+    .with('atc_session_kill', async () => {
+      await caller.sendRequest('session.kill', { session: args['session'] });
+
+      return 'killed';
+    })
+    .with('atc_session_ack', async () => {
+      await caller.sendRequest('session.ack', { session: args['session'] });
+
+      return 'acked';
+    })
+    .with('atc_resume_command', async () => {
+      const ok = await caller.sendRequest('session.resumeCommand', { session: args['session'] });
+
+      return typeof ok['command'] === 'string' ? ok['command'] : JSON.stringify(ok);
+    })
+    .with('atc_dirs_list', async () => {
+      const ok = await caller.sendRequest('dirs.list');
+
+      return JSON.stringify(ok['dirs'], null, 2);
+    })
+    .with('atc_session_get', async () => {
+      const ok = await caller.sendRequest('session.get', { session: args['session'] });
+
+      return JSON.stringify(ok, null, 2);
+    })
+    .with('atc_session_read', async () => {
+      const ok = await caller.sendRequest('session.read', {
+        session: args['session'],
+        ...(typeof args['cursor'] === 'string' ? { cursor: args['cursor'] } : {}),
+        ...(typeof args['limit'] === 'number' ? { limit: args['limit'] } : {}),
+      });
+
+      return JSON.stringify(ok, null, 2);
+    })
+    .with('atc_events_read', async () => {
+      const ok = await caller.sendRequest('events.read', {
+        ...(typeof args['cursor'] === 'string' ? { cursor: args['cursor'] } : {}),
+        ...(typeof args['limit'] === 'number' ? { limit: args['limit'] } : {}),
+        ...(typeof args['waitMs'] === 'number' ? { waitMs: args['waitMs'] } : {}),
+      });
+
+      return JSON.stringify(ok, null, 2);
+    })
+    .with('atc_session_message', async () => {
+      const given = args['from'];
+
+      const from =
+        ctx.sender.kind === 'default' && typeof given === 'string' && given !== ''
+          ? given
+          : ctx.sender.name;
+
+      const ok = await caller.sendRequest('session.message', {
+        session: args['session'],
+        text: args['text'],
+        from,
+      });
+
+      return JSON.stringify(ok, null, 2);
+    })
+    .with('atc_message_get', async () => {
+      const ok = await caller.sendRequest('message.get', { message: args['message'] });
+
+      return JSON.stringify(ok, null, 2);
+    })
+    .otherwise(() => Promise.reject(new Error(`unknown tool '${name}'`)));
+}
+
+// The inherited id can point at a session another daemon hosts, or one
+// this daemon no longer lists; the spawn then lands top-level instead of
+// failing the tool call.
+async function sendNestedSpawn(
+  caller: FleetCaller,
+  params: Readonly<Record<string, unknown>>,
+  parent: string,
+): Promise<Readonly<Record<string, unknown>>> {
+  try {
+    return await caller.sendRequest('session.spawn', { ...params, parent });
+  } catch (error) {
+    if (error instanceof DaemonError && error.code === 'no_such_session') {
+      return caller.sendRequest('session.spawn', params);
+    }
+
+    throw error;
+  }
+}

package/src/mcp/start-mcp-http-server.ts

@@ -0,0 +1,330 @@
+import { MAX_LINE } from '../protocol/protocol';
+import { isRecord } from '../shared/report';
+import { answerAuthorizeRequest } from './answer-authorize-request';
+import { answerConsentRequest } from './answer-consent-request';
+import { answerLoginRequest } from './answer-login-request';
+import { answerMCPRequest } from './answer-mcp-request';
+import { ApprovalState } from './approval-state';
+import { buildPageResponse } from './build-page-response';
+import { isLoopbackHost } from './is-loopback-host';
+import { normalizePublicURL } from './normalize-public-url';
+import { openMCPAuth } from './open-mcp-auth';
+import { pickErrorMessage } from './pick-error-message';
+import type { FleetCaller, HTTPServerContext } from './types';
+
+interface MCPHTTPServerOptions {
+  readonly caller: FleetCaller;
+  readonly build: string;
+
+  // The address to bind; 0 as the port binds a free one.
+  readonly host: string;
+  readonly port: number;
+
+  // The origin clients reach the server at; absent means the local address.
+  readonly publicURL: string | null;
+
+  // Further Host header values to accept, for a proxy that rewrites Host.
+  readonly allowedHosts: readonly string[];
+
+  // The authorization server's SQLite database.
+  readonly dbPath: string;
+  readonly printApproval: (line: string) => void;
+
+  // How long a rotated refresh token still answers with its successor.
+  readonly refreshReuseSeconds?: number;
+}
+
+/**
+ * A running MCP HTTP server.
+ */
+export interface MCPHTTPServer {
+  // The local address the server listens on.
+  readonly url: string;
+
+  // The public origin: the OAuth issuer.
+  readonly origin: string;
+  readonly stop: () => Promise<void>;
+}
+
+/**
+ * Serves atc's MCP tools over streamable HTTP at `/mcp`, with better-auth as
+ * the OAuth 2.1 authorization server in the same process. Only the routes a
+ * connector and the operator's browser need reach better-auth; every other
+ * path is a 404. A request whose Host header is not the server's own is
+ * refused, so a DNS rebinding page cannot reach it through a browser, and a
+ * browser form post from any other origin is refused too.
+ */
+export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise<MCPHTTPServer> {
+  // Normalized before binding, so an invalid public URL throws with no port
+  // left bound.
+  const publicOrigin = options.publicURL === null ? null : normalizePublicURL(options.publicURL);
+
+  // atc speaks plain HTTP, so a listener other machines can reach has to sit
+  // behind something that terminates TLS, and the public URL clients use is
+  // that https origin.
+  if (
+    !isLoopbackHost(options.host) &&
+    (publicOrigin === null || !publicOrigin.startsWith('https:'))
+  ) {
+    throw new Error(
+      `listening on '${options.host}' reaches beyond this machine, so it needs an https public URL served by a TLS-terminating proxy or tunnel`,
+    );
+  }
+
+  const holder: { ready: ServerState | null } = { ready: null };
+
+  const server = Bun.serve({
+    hostname: options.host,
+    port: options.port,
+
+    // A long poll holds a request open for up to 30 seconds without a byte.
+    idleTimeout: 60,
+    maxRequestBodySize: MAX_LINE,
+    fetch: async (request, bunServer) => {
+      const state = holder.ready;
+
+      if (state === null) {
+        return new Response(null, { status: 503 });
+      }
+
+      try {
+        const answered = await answerHTTPRequest(
+          state,
+          request,
+          bunServer.requestIP(request)?.address ?? null,
+        );
+
+        return answered;
+      } catch {
+        return new Response(null, { status: 503 });
+      }
+    },
+  });
+
+  const port = server.port ?? options.port;
+  const local = `http://127.0.0.1:${port}`;
+  const origin = publicOrigin ?? local;
+  let store: HTTPServerContext['store'];
+
+  try {
+    store = await openMCPAuth({
+      dbPath: options.dbPath,
+      origin,
+      ...(options.refreshReuseSeconds === undefined
+        ? {}
+        : { refreshReuseSeconds: options.refreshReuseSeconds }),
+    });
+  } catch (error) {
+    await server.stop(true);
+
+    throw error;
+  }
+
+  holder.ready = {
+    hosts: new Set([
+      new URL(origin).host,
+      `127.0.0.1:${port}`,
+      `localhost:${port}`,
+      ...options.allowedHosts,
+    ]),
+    origins: new Set([origin, local, `http://localhost:${port}`]),
+    ctx: {
+      caller: options.caller,
+      build: options.build,
+      origin,
+      resource: `${origin}/mcp`,
+      store,
+      approvals: new ApprovalState(600_000, () => Date.now()),
+      printApproval: options.printApproval,
+    },
+  };
+
+  return {
+    url: local,
+    origin,
+    stop: async () => {
+      await server.stop(true);
+      await store.close();
+    },
+  };
+}
+
+interface ServerState {
+  readonly hosts: ReadonlySet<string>;
+  readonly origins: ReadonlySet<string>;
+  readonly ctx: HTTPServerContext;
+}
+
+// The better-auth routes a connector calls directly.
+const PASSED_THROUGH: ReadonlySet<string> = new Set([
+  'GET /.well-known/oauth-protected-resource',
+  'GET /.well-known/oauth-protected-resource/mcp',
+  'POST /oauth2/revoke',
+]);
+
+// `socketAddress` is the peer the request arrived from: the requester, or the
+// proxy or tunnel in front of atc.
+async function answerHTTPRequest(
+  state: ServerState,
+  request: Request,
+  socketAddress: string | null,
+): Promise<Response> {
+  const host = request.headers.get('host');
+
+  if (host === null || !state.hosts.has(host)) {
+    return new Response(null, { status: 403 });
+  }
+
+  const ctx = state.ctx;
+
+  const url = new URL(request.url);
+
+  const route = `${request.method} ${url.pathname}`;
+  const requestOrigin = request.headers.get('origin');
+  const isForeignOrigin = requestOrigin !== null && !state.origins.has(requestOrigin);
+
+  if (PASSED_THROUGH.has(route)) {
+    return ctx.store.auth.handler(toPublicRequest(ctx, request, url));
+  }
+
+  if (route === 'GET /.well-known/oauth-authorization-server') {
+    return answerMetadataRequest(ctx, request, url);
+  }
+
+  if (route === 'GET /oauth2/authorize') {
+    return answerAuthorizeRequest(ctx, url, {
+      socketAddress,
+      connectingIP: request.headers.get('cf-connecting-ip'),
+      userAgent: request.headers.get('user-agent'),
+    });
+  }
+
+  if (route === 'POST /oauth2/token') {
+    return answerTokenRequest(ctx, request, url);
+  }
+
+  if (route === 'GET /error') {
+    return buildPageResponse(400, { message: pickErrorMessage(url.searchParams.get('error')) });
+  }
+
+  const isPage = url.pathname === '/login' || url.pathname === '/consent';
+
+  if (isPage && request.method === 'POST' && (requestOrigin === null || isForeignOrigin)) {
+    return buildPageResponse(403, { message: 'The form came from an unexpected origin.' });
+  }
+
+  if (isPage && (request.method === 'GET' || request.method === 'POST')) {
+    const body = request.method === 'POST' ? await request.text() : '';
+
+    return url.pathname === '/login'
+      ? answerLoginRequest(ctx, request.method, url, body)
+      : answerConsentRequest(ctx, {
+          method: request.method,
+          url,
+          cookie: request.headers.get('cookie'),
+          body,
+        });
+  }
+
+  if (url.pathname === '/mcp') {
+    if (isForeignOrigin) {
+      return new Response(null, { status: 403 });
+    }
+
+    if (request.method !== 'POST') {
+      return new Response(null, { status: 405, headers: { allow: 'POST' } });
+    }
+
+    return answerMCPRequest(ctx, {
+      authorization: request.headers.get('authorization'),
+      protocolVersion: request.headers.get('mcp-protocol-version'),
+      body: await request.text(),
+    });
+  }
+
+  return new Response(null, { status: 404 });
+}
+
+// better-auth builds every URL it returns from its base URL, so a request
+// that reached the local address is handed over as if it came to the public
+// origin.
+function toPublicRequest(ctx: HTTPServerContext, request: Request, url: URL): Request {
+  return new Request(`${ctx.origin}${url.pathname}${url.search}`, request);
+}
+
+// The metadata advertises only what atc's clients can use: public clients
+// with no client authentication, and no introspection endpoint.
+async function answerMetadataRequest(
+  ctx: HTTPServerContext,
+  request: Request,
+  url: URL,
+): Promise<Response> {
+  const response = await ctx.store.auth.handler(toPublicRequest(ctx, request, url));
+  const metadata: unknown = await response.json();
+
+  if (!isRecord(metadata)) {
+    return new Response(null, { status: 503 });
+  }
+
+  const advertised = Object.fromEntries(
+    Object.entries(metadata).filter(([key]) => !key.startsWith('introspection_')),
+  );
+
+  return Response.json({
+    ...advertised,
+    token_endpoint_auth_methods_supported: ['none'],
+    revocation_endpoint_auth_methods_supported: ['none'],
+  });
+}
+
+// A code exchange binds its tokens to the owner session that approved it;
+// once issued, every token is detached from its session, so a session's end
+// never ends the grant, and the session, whose one authorization is done, is
+// deleted.
+async function answerTokenRequest(
+  ctx: HTTPServerContext,
+  request: Request,
+  url: URL,
+): Promise<Response> {
+  const response = await ctx.store.auth.handler(toPublicRequest(ctx, request, url));
+
+  if (response.ok) {
+    const attached = await ctx.store.db
+      .selectFrom('oauthAccessToken')
+      .select('sessionId')
+      .where('sessionId', 'is not', null)
+      .union(
+        ctx.store.db
+          .selectFrom('oauthRefreshToken')
+          .select('sessionId')
+          .where('sessionId', 'is not', null),
+      )
+      .execute();
+
+    const sessionIDs = attached.flatMap((row) => (row.sessionId === null ? [] : [row.sessionId]));
+
+    await ctx.store.db
+      .updateTable('oauthAccessToken')
+      .set({ sessionId: null })
+      .where('sessionId', 'is not', null)
+      .execute();
+
+    await ctx.store.db
+      .updateTable('oauthRefreshToken')
+      .set({ sessionId: null })
+      .where('sessionId', 'is not', null)
+      .execute();
+
+    await ctx.store.db
+      .deleteFrom('session')
+      .where((eb) =>
+        eb.or([
+          eb('expiresAt', '<', new Date().toISOString()),
+          ...(sessionIDs.length === 0 ? [] : [eb('id', 'in', sessionIDs)]),
+        ]),
+      )
+      .execute();
+  }
+
+  return response;
+}

package/src/mcp/to-html-text.ts

@@ -0,0 +1,12 @@
+/**
+ * Escapes text for safe placement in HTML element content or a quoted
+ * attribute value.
+ */
+export function toHTMLText(text: string): string {
+  return text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}