@zgeoff/atc 2.8.1 → 2.9.0

package/src/daemon/start-headless-run.ts

@@ -6,6 +6,7 @@ import { isRecord } from '../shared/report';
 import type { SessionID } from '../shared/session-id';
 import { buildHeadlessEnv } from './build-headless-env';
 import { resolveHeadlessExecutable } from './resolve-headless-executable';
+import { truncateSummary } from './truncate-summary';
 
 const PERMISSION_MODES = [
   'default',
@@ -40,7 +41,7 @@ interface HeadlessRunHandle {
 /**
  * Runs one headless Agent SDK turn over a session, rendering its structured
  * messages as plain lines into the session's output pipe. The run ends in
- * done (with the result as the summary) or needs_you (errors, turn limits,
+ * done (with the turn's whole result) or needs_you (errors, turn limits,
  * anything a human must look at).
  */
 export function startHeadlessRun(
@@ -89,7 +90,7 @@ export function startHeadlessRun(
         }
 
         if (message.subtype === 'success') {
-          hooks.onDone(truncateSummary(message.result));
+          hooks.onDone(message.result);
           continue;
         }
 
@@ -170,9 +171,3 @@ export function renderSdkMessage(message: RenderableMessage): string | null {
 
   return null;
 }
-
-function truncateSummary(text: string): string {
-  const flat = text.replaceAll('\n', ' ');
-
-  return flat.length <= 200 ? flat : `${flat.slice(0, 199)}…`;
-}

package/src/daemon/start-headless-turn.ts

@@ -1,11 +1,15 @@
+import type { AdapterEvent } from '../agents/agent-adapter';
+import { truncateDetail } from '../agents/truncate-detail';
 import type { SessionID } from '../shared/session-id';
 import type { SessionRuntime } from './session-runtime';
 import type { SessionManager } from './sessions';
+import { truncateSummary } from './truncate-summary';
 
 /**
  * Starts one headless turn for a session: finds its adapter's headless
  * runner, wires the run's output and completion into the session manager,
- * and records the live handle on the session's runtime. Returns false
+ * passes the turn's start and end to the event trail the way a terminal
+ * turn's hooks do, and records the live handle on the session's runtime. Returns false
  * without starting anything when the session is unknown, its agent has no
  * headless runner, or a turn is already running.
  */
@@ -14,6 +18,7 @@ export function startHeadlessTurn(
   findRuntime: (sessionID: SessionID) => SessionRuntime | undefined,
   sessionID: SessionID,
   prompt: string,
+  recordTurnEvent: (sessionID: SessionID, ev: Readonly<AdapterEvent>) => void,
 ): boolean {
   const s = mgr.sessions.find((x) => x.id === sessionID);
   const runner = s === undefined ? null : (mgr.findAdapter(s.agent)?.headlessRunner ?? null);
@@ -25,6 +30,8 @@ export function startHeadlessTurn(
 
   mgr.updateSurfaceState(sessionID, 'running', 'headless turn running');
 
+  recordTurnEvent(sessionID, { kind: 'prompt-submitted', detail: truncateDetail(prompt) });
+
   const handle = runner(
     {
       cwd: s.cwd,
@@ -37,17 +44,22 @@ export function startHeadlessTurn(
       onOutput: (text) => {
         mgr.onOutput(s, text);
       },
-      onDone: (summary) => {
+      onDone: (result) => {
         runtime.headlessRun = null;
 
+        const summary = truncateSummary(result);
         const doneMsg = summary === '' ? 'headless turn done' : summary;
 
-        mgr.updateSurfaceState(sessionID, 'done', doneMsg);
+        mgr.updateSurfaceState(sessionID, 'done', doneMsg, result);
+
+        recordTurnEvent(sessionID, { kind: 'turn-done', detail: truncateDetail(result) });
       },
       onNeedsYou: (msg) => {
         runtime.headlessRun = null;
 
         mgr.updateSurfaceState(sessionID, 'needs_you', msg);
+
+        recordTurnEvent(sessionID, { kind: 'needs-input', message: msg, detail: msg });
       },
     },
   );

package/src/daemon/truncate-summary.ts

@@ -0,0 +1,9 @@
+/**
+ * Flattens text to one line and caps it at 200 characters, ellipsizing
+ * anything longer, for a session's one-line status.
+ */
+export function truncateSummary(text: string): string {
+  const flat = text.replaceAll('\n', ' ');
+
+  return flat.length <= 200 ? flat : `${flat.slice(0, 199)}…`;
+}

package/src/grants.ts

@@ -0,0 +1,51 @@
+import { mkdirSync } from 'node:fs';
+import { collectGrants } from './mcp/collect-grants';
+import { openMCPAuth } from './mcp/open-mcp-auth';
+import { revokeGrant } from './mcp/revoke-grant';
+import { mcpAuthDBFile, stateDir } from './shared/config';
+
+/**
+ * Runs `atc grants`: lists the grants clients of `atc mcp --http` hold, or
+ * revokes one. A revoked grant's tokens stop working at once, and its client
+ * has to go through approval again. It opens the authorization server's
+ * database directly, so it works whether or not the server is running.
+ */
+export async function runGrants(revoke: string | null): Promise<void> {
+  mkdirSync(stateDir, { recursive: true });
+
+  const store = await openMCPAuth({ dbPath: mcpAuthDBFile, origin: null });
+
+  try {
+    if (revoke !== null) {
+      const revoked = await revokeGrant(store.db, revoke);
+
+      if (!revoked) {
+        console.error(`atc grants: no grant has the ID '${revoke}'`);
+
+        process.exitCode = 1;
+
+        return;
+      }
+
+      console.log(`Revoked grant ${revoke}`);
+
+      return;
+    }
+
+    const grants = await collectGrants(store.db);
+
+    if (grants.length === 0) {
+      console.log('No grants.');
+
+      return;
+    }
+
+    for (const grant of grants) {
+      console.log(
+        `${grant.grantID}  ${grant.clientName}  ${grant.scopes.join(',')}  last used ${grant.lastUsedAt ?? 'never'}`,
+      );
+    }
+  } finally {
+    await store.close();
+  }
+}

package/src/mcp/answer-authorize-request.ts

@@ -0,0 +1,98 @@
+import { normalizeClientName } from '../shared/normalize-client-name';
+import { buildPageResponse } from './build-page-response';
+import { findClientName } from './find-client-name';
+import type { HTTPServerContext } from './types';
+
+// Where an authorization request came from, as the HTTP request shows it.
+interface Requester {
+  readonly socketAddress: string | null;
+  readonly connectingIP: string | null;
+  readonly userAgent: string | null;
+}
+
+/**
+ * Answers `GET /oauth2/authorize`. Before better-auth validates the request,
+ * atc sets three parameters of its own:
+ *
+ * - `prompt=login consent`, so every authorization asks for a fresh approval
+ *   code and shows the consent page, whatever session or consent a browser
+ *   kept from before.
+ * - `offline_access` in a requested scope, so every grant gets a refresh token.
+ * - `resource=<origin>/mcp` when the client gave none, so every token is bound
+ *   to the one resource atc serves.
+ *
+ * A request better-auth sends on to the login page gets a pending approval,
+ * and its code prints in atc's terminal with the client's name, the host it
+ * returns to, and who asked: the `CF-Connecting-IP` address when the request
+ * carries one, labelled as reported since anyone can send that header, else
+ * the socket's peer address, plus the start of the user agent.
+ */
+export async function answerAuthorizeRequest(
+  ctx: HTTPServerContext,
+  url: URL,
+  requester: Requester,
+): Promise<Response> {
+  const params = new URLSearchParams(url.searchParams);
+
+  params.set('prompt', 'login consent');
+
+  const scope = params.get('scope');
+
+  if (scope !== null) {
+    const scopes = scope.split(' ').filter((item) => item !== '');
+
+    params.set('scope', [...new Set([...scopes, 'offline_access'])].join(' '));
+  }
+
+  if (!params.has('resource')) {
+    params.set('resource', ctx.resource);
+  }
+
+  const response = await ctx.store.auth.handler(
+    new Request(`${ctx.origin}/oauth2/authorize?${params.toString()}`, {
+      headers: { accept: 'text/html' },
+    }),
+  );
+
+  const location = response.headers.get('location');
+  const target = location === null ? null : new URL(location, ctx.origin);
+
+  if (target === null || target.origin !== ctx.origin || target.pathname !== '/login') {
+    return response;
+  }
+
+  const clientID = target.searchParams.get('client_id') ?? '';
+  const redirectURI = target.searchParams.get('redirect_uri') ?? '';
+
+  const storedName = await findClientName(ctx.store.db, clientID);
+
+  const clientName = normalizeClientName(storedName);
+
+  const approval = ctx.approvals.createPending({
+    key: target.search.slice(1),
+    clientID,
+    clientName,
+    redirectURI,
+  });
+
+  if (approval === null) {
+    return buildPageResponse(429, {
+      message: 'Too many approvals started in the last minute. Wait a minute, then start again.',
+    });
+  }
+
+  const code = `${approval.approvalCode.slice(0, 4)}-${approval.approvalCode.slice(4)}`;
+
+  const from =
+    requester.connectingIP === null
+      ? normalizeClientName(requester.socketAddress, 'an unknown address', 45)
+      : `${normalizeClientName(requester.connectingIP, 'an empty address', 45)} (reported by CF-Connecting-IP)`;
+
+  const userAgent = normalizeClientName(requester.userAgent, 'none', 60);
+
+  ctx.printApproval(
+    `Approve ${clientName} (returns to ${new URL(redirectURI).host}) with code ${code}. Requested from ${from}, user agent "${userAgent}". The code expires in 10 minutes.`,
+  );
+
+  return response;
+}

package/src/mcp/answer-consent-request.ts

@@ -0,0 +1,166 @@
+import { GRANT_SCOPES } from '../shared/grant-scope';
+import { normalizeClientName } from '../shared/normalize-client-name';
+import { isRecord } from '../shared/report';
+import { buildConsentBinding } from './build-consent-binding';
+import { buildPageResponse } from './build-page-response';
+import { findClientName } from './find-client-name';
+import { findOwnerSessionID } from './find-owner-session-id';
+import { renderConsentPage } from './render-consent-page';
+import type { HTTPServerContext } from './types';
+import { verifyOAuthQuery } from './verify-oauth-query';
+
+interface ConsentRequest {
+  readonly method: 'GET' | 'POST';
+  readonly url: URL;
+  readonly cookie: string | null;
+  readonly body: string;
+}
+
+// How long an authorization code stays exchangeable.
+const CODE_MS = 600_000;
+
+/**
+ * Answers `GET /consent` and `POST /consent`. Both refuse a request unless
+ * its signed query is valid, its prompt no longer asks for a login, and its
+ * owner session is the one an approval code signed in for this same request.
+ * The page lists the scopes the client requested, with only `read` ticked to
+ * start. The form goes to better-auth's consent endpoint with the ticked
+ * scopes plus `offline_access`; better-auth refuses any scope the client did
+ * not request. Allowing nothing denies the request. Either way the browser
+ * returns to the client with its owner session cookie cleared.
+ *
+ * One login answers one consent: the answer ends the session's binding, so
+ * it can approve nothing else. An answer that issues no authorization code
+ * deletes the session outright. One that issues a code leaves the session
+ * only until the code expires, since the code exchange needs it, and the
+ * exchange deletes it.
+ */
+export async function answerConsentRequest(
+  ctx: HTTPServerContext,
+  request: ConsentRequest,
+): Promise<Response> {
+  const form = new URLSearchParams(request.body);
+
+  const oauthQuery =
+    request.method === 'GET' ? request.url.search.slice(1) : (form.get('oauth_query') ?? '');
+
+  const sessionID = await verifyConsentRequest(ctx, oauthQuery, request.cookie);
+
+  if (sessionID === null) {
+    return buildPageResponse(400, {
+      message: 'This approval expired or was already used. Start again from the client.',
+    });
+  }
+
+  if (request.method === 'GET') {
+    const params = new URLSearchParams(oauthQuery);
+
+    const redirectURI = params.get('redirect_uri') ?? '';
+    const requested = (params.get('scope') ?? '').split(' ');
+
+    const storedName = await findClientName(ctx.store.db, params.get('client_id') ?? '');
+
+    const page = renderConsentPage({
+      oauthQuery,
+      clientName: normalizeClientName(storedName),
+      redirectURI,
+      scopes: GRANT_SCOPES.filter((scope) => requested.includes(scope)),
+    });
+
+    // The form's answer redirects to the client, which the page's form-action
+    // policy has to allow.
+    const formTargets = URL.canParse(redirectURI) ? [new URL(redirectURI).origin] : [];
+
+    return buildPageResponse(200, { page }, formTargets);
+  }
+
+  ctx.approvals.removeApproved(sessionID);
+
+  const ticked = form.getAll('scope');
+  const scopes = GRANT_SCOPES.filter((scope) => ticked.includes(scope));
+  const accept = form.get('decision') === 'approve' && scopes.length > 0;
+
+  const choice = JSON.stringify({
+    accept,
+    ...(accept ? { scope: [...scopes, 'offline_access'].join(' ') } : {}),
+    oauth_query: oauthQuery,
+  });
+
+  const forwarded = new Request(`${ctx.origin}/oauth2/consent`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      accept: 'application/json',
+      origin: ctx.origin,
+      ...(request.cookie === null ? {} : { cookie: request.cookie }),
+    },
+    body: choice,
+  });
+
+  const consented = await ctx.store.auth.handler(forwarded);
+  const answer: unknown = await consented.json();
+
+  const next = isRecord(answer) ? (answer['url'] ?? answer['redirect_uri']) : undefined;
+
+  const issuedCode =
+    consented.ok && typeof next === 'string' && new URL(next).searchParams.has('code');
+
+  await (issuedCode
+    ? ctx.store.db
+        .updateTable('session')
+        .set({ expiresAt: new Date(Date.now() + CODE_MS).toISOString() })
+        .where('id', '=', sessionID)
+        .execute()
+    : ctx.store.db.deleteFrom('session').where('id', '=', sessionID).execute());
+
+  if (!consented.ok || typeof next !== 'string') {
+    return buildPageResponse(400, {
+      message: 'atc could not record this choice. Start again from the client.',
+    });
+  }
+
+  const authContext = await ctx.store.auth.$context;
+
+  const sessionCookie = authContext.authCookies.sessionToken;
+  const secure = sessionCookie.attributes.secure === true ? '; Secure' : '';
+
+  return new Response(null, {
+    status: 302,
+    headers: {
+      location: next,
+      'set-cookie': `${sessionCookie.name}=; Max-Age=0; Path=/; HttpOnly; SameSite=Lax${secure}`,
+    },
+  });
+}
+
+// The owner session id when the request may reach consent, else null. A
+// query still asking for a login is one better-auth signed for the login
+// page, which the approval code never carried past.
+async function verifyConsentRequest(
+  ctx: HTTPServerContext,
+  oauthQuery: string,
+  cookie: string | null,
+): Promise<string | null> {
+  const authContext = await ctx.store.auth.$context;
+
+  if (!(await verifyOAuthQuery(oauthQuery, authContext.secret))) {
+    return null;
+  }
+
+  const prompt = (new URLSearchParams(oauthQuery).get('prompt') ?? '').split(' ');
+
+  if (prompt.includes('login')) {
+    return null;
+  }
+
+  const sessionID = await findOwnerSessionID(ctx, cookie);
+
+  if (
+    sessionID === null ||
+    ctx.approvals.findApproved(sessionID) !== buildConsentBinding(oauthQuery)
+  ) {
+    return null;
+  }
+
+  return sessionID;
+}

package/src/mcp/answer-login-request.ts

@@ -0,0 +1,108 @@
+import { isRecord } from '../shared/report';
+import { buildConsentBinding } from './build-consent-binding';
+import { buildPageResponse } from './build-page-response';
+import { findOwnerSessionID } from './find-owner-session-id';
+import { renderLoginPage } from './render-login-page';
+import type { HTTPServerContext } from './types';
+
+/**
+ * Answers `GET /login` and `POST /login`, the approval code page better-auth
+ * sends a browser to. The page exists only for an authorization request that
+ * holds a pending approval. The right code signs the operator in, binds the
+ * new owner session to this one request, and better-auth carries the request
+ * on to the consent page. A wrong code shows the page again, and the fifth
+ * wrong code ends the request.
+ */
+export async function answerLoginRequest(
+  ctx: HTTPServerContext,
+  method: 'GET' | 'POST',
+  url: URL,
+  body: string,
+): Promise<Response> {
+  const form = new URLSearchParams(body);
+
+  const oauthQuery = method === 'GET' ? url.search.slice(1) : (form.get('oauth_query') ?? '');
+  const approval = ctx.approvals.findPending(oauthQuery);
+
+  if (approval === null) {
+    return buildPageResponse(400, {
+      message: 'This approval expired or was already used. Start again from the client.',
+    });
+  }
+
+  const view = {
+    oauthQuery,
+    clientName: approval.clientName,
+    redirectURI: approval.redirectURI,
+  };
+
+  if (method === 'GET') {
+    return buildPageResponse(200, { page: renderLoginPage({ ...view, error: null }) });
+  }
+
+  const verdict = ctx.approvals.verifyApprovalCode(oauthQuery, form.get('code') ?? '');
+
+  if (verdict === 'locked') {
+    return buildPageResponse(400, {
+      message: 'Too many wrong approval codes. Start again from the client.',
+    });
+  }
+
+  if (verdict === 'wrong') {
+    return buildPageResponse(400, {
+      page: renderLoginPage({
+        ...view,
+        error: 'That approval code is wrong. Check the terminal running atc mcp --http.',
+      }),
+    });
+  }
+
+  // Resuming the authorization reads the request better-auth was called with.
+  const apiHeaders = new Headers({
+    accept: 'application/json',
+    'content-type': 'application/json',
+  });
+
+  const signedIn = await ctx.store.auth.api.signInOwner({
+    body: { oauth_query: oauthQuery },
+    headers: apiHeaders,
+    request: new Request(`${ctx.origin}/atc/sign-in-owner`, {
+      method: 'POST',
+      headers: apiHeaders,
+    }),
+    asResponse: true,
+  });
+
+  const resumed: unknown = await signedIn.json();
+
+  const next = isRecord(resumed) ? resumed['url'] : undefined;
+
+  if (!signedIn.ok || typeof next !== 'string') {
+    return buildPageResponse(400, {
+      message: 'atc could not continue this approval. Start again from the client.',
+    });
+  }
+
+  const setCookies = signedIn.headers.getSetCookie();
+
+  const sessionID = await findOwnerSessionID(
+    ctx,
+    setCookies.map((line) => line.split(';')[0]).join('; '),
+  );
+
+  if (sessionID === null) {
+    return buildPageResponse(400, {
+      message: 'atc could not continue this approval. Start again from the client.',
+    });
+  }
+
+  ctx.approvals.recordApproved(sessionID, buildConsentBinding(oauthQuery));
+
+  const headers = new Headers({ location: new URL(next, ctx.origin).href });
+
+  for (const cookie of setCookies) {
+    headers.append('set-cookie', cookie);
+  }
+
+  return new Response(null, { status: 302, headers });
+}

package/src/mcp/answer-mcp-request.ts

@@ -0,0 +1,161 @@
+import { isAPIError } from 'better-auth/api';
+import { GRANT_SCOPES } from '../shared/grant-scope';
+import type { GrantScope } from '../shared/grant-scope';
+import { normalizeClientName } from '../shared/normalize-client-name';
+import { isRecord } from '../shared/report';
+import { answerRPCRequest } from './answer-rpc-request';
+import { deriveTokenHash } from './derive-token-hash';
+import { findClientName } from './find-client-name';
+import { isSupportedProtocolVersion } from './is-supported-protocol-version';
+import type { HTTPServerContext } from './types';
+
+interface MCPHTTPRequest {
+  readonly authorization: string | null;
+  readonly protocolVersion: string | null;
+  readonly body: string;
+}
+
+/**
+ * Answers `POST /mcp`: one JSON-RPC message from a client holding an access
+ * token. Every request checks its token against the authorization server's
+ * database, so a revoked grant loses access at once, and a token bound to any
+ * other resource is refused. A tool call outside the token's scopes is a 403
+ * that names the missing scope. A message the client sends is always from the
+ * client's own name.
+ */
+export async function answerMCPRequest(
+  ctx: HTTPServerContext,
+  request: MCPHTTPRequest,
+): Promise<Response> {
+  if (request.protocolVersion !== null && !isSupportedProtocolVersion(request.protocolVersion)) {
+    return new Response(null, { status: 400 });
+  }
+
+  const metadataURL = `${ctx.origin}/.well-known/oauth-protected-resource/mcp`;
+  const token = /^Bearer (?<token>\S+)$/i.exec(request.authorization ?? '')?.groups?.['token'];
+
+  if (token === undefined) {
+    return new Response(null, {
+      status: 401,
+      headers: { 'www-authenticate': `Bearer resource_metadata="${metadataURL}"` },
+    });
+  }
+
+  const access = await verifyAccessToken(ctx, token);
+
+  if (access === null) {
+    return new Response(null, {
+      status: 401,
+      headers: {
+        'www-authenticate': `Bearer error="invalid_token", resource_metadata="${metadataURL}"`,
+      },
+    });
+  }
+
+  let message: unknown;
+
+  try {
+    message = JSON.parse(request.body);
+  } catch {
+    return buildRPCError(400, null, -32_700, 'parse error');
+  }
+
+  if (Array.isArray(message)) {
+    return buildRPCError(400, null, -32_600, 'atc does not accept JSON-RPC batches');
+  }
+
+  const outcome = await answerRPCRequest(message, {
+    caller: ctx.caller,
+    build: ctx.build,
+    toolContext: { callerSessionID: null, sender: { kind: 'fixed', name: access.clientName } },
+    scopes: access.scopes,
+  });
+
+  if (outcome.kind === 'reply') {
+    return Response.json(outcome.body);
+  }
+
+  if (outcome.kind === 'accepted') {
+    return new Response(null, { status: 202 });
+  }
+
+  if (outcome.kind === 'forbidden') {
+    const id = isRecord(message) ? (message['id'] ?? null) : null;
+    const response = buildRPCError(403, id, -32_001, `this grant lacks the ${outcome.scope} scope`);
+
+    response.headers.set(
+      'www-authenticate',
+      `Bearer error="insufficient_scope", scope="${outcome.scope}", resource_metadata="${metadataURL}"`,
+    );
+
+    return response;
+  }
+
+  return buildRPCError(400, null, -32_600, 'invalid request');
+}
+
+interface VerifiedAccess {
+  readonly clientName: string;
+  readonly scopes: readonly GrantScope[];
+}
+
+// An inactive, unknown, or revoked token, or one bound to another resource,
+// verifies to null. Verifying stamps when the token's grant was last used.
+async function verifyAccessToken(
+  ctx: HTTPServerContext,
+  token: string,
+): Promise<VerifiedAccess | null> {
+  let payload: unknown;
+
+  try {
+    payload = await ctx.store.auth.api.verifyMCPAccessToken({ body: { token } });
+  } catch (error) {
+    if (isAPIError(error)) {
+      return null;
+    }
+
+    throw error;
+  }
+
+  if (!isRecord(payload) || ![payload['aud']].flat().includes(ctx.resource)) {
+    return null;
+  }
+
+  const granted = typeof payload['scope'] === 'string' ? payload['scope'].split(' ') : [];
+  const clientID = typeof payload['client_id'] === 'string' ? payload['client_id'] : '';
+
+  await upsertGrantUse(ctx, token);
+
+  const storedName = await findClientName(ctx.store.db, clientID);
+
+  return {
+    clientName: normalizeClientName(storedName, 'remote'),
+    scopes: GRANT_SCOPES.filter((scope) => granted.includes(scope)),
+  };
+}
+
+async function upsertGrantUse(ctx: HTTPServerContext, token: string): Promise<void> {
+  const row = await ctx.store.db
+    .selectFrom('oauthAccessToken')
+    .select('authorizationCodeId')
+    .where('token', '=', deriveTokenHash(token))
+    .executeTakeFirst();
+
+  const grantID = row?.authorizationCodeId ?? null;
+
+  if (grantID === null) {
+    return;
+  }
+
+  const now = new Date().toISOString();
+
+  await ctx.store.db
+    .insertInto('atc_grant_use')
+    .values({ grant_id: grantID, last_used_at: now })
+    .onConflict((conflict) => conflict.column('grant_id').doUpdateSet({ last_used_at: now }))
+    .execute();
+}
+
+function buildRPCError(status: number, id: unknown, code: number, message: string): Response {
+  return Response.json({ jsonrpc: '2.0', id, error: { code, message } }, { status });
+}