@zgeoff/atc 2.8.1 → 2.9.0

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

@@ -0,0 +1,137 @@
+import { match } from 'ts-pattern';
+import { DaemonError } from '../protocol/daemon-error';
+import type { GrantScope } from '../shared/grant-scope';
+import { isRecord } from '../shared/report';
+import { buildToolList } from './build-tool-list';
+import { MCP_TOOLS } from './mcp-tools';
+import { pickProtocolVersion } from './pick-protocol-version';
+import { runTool } from './run-tool';
+import type { FleetCaller, ToolContext } from './types';
+
+interface RPCDeps {
+  readonly caller: FleetCaller;
+  readonly build: string;
+  readonly toolContext: ToolContext;
+
+  // The scopes the caller holds; absent means every tool is allowed.
+  readonly scopes?: readonly GrantScope[];
+}
+
+type RPCOutcome =
+  | { readonly kind: 'reply'; readonly body: Readonly<Record<string, unknown>> }
+  | { readonly kind: 'accepted' }
+  | { readonly kind: 'invalid' }
+  | { readonly kind: 'forbidden'; readonly scope: GrantScope };
+
+export async function answerRPCRequest(message: unknown, deps: RPCDeps): Promise<RPCOutcome> {
+  if (!isRecord(message) || typeof message['method'] !== 'string') {
+    return { kind: 'invalid' };
+  }
+
+  const method = message['method'];
+  const id = message['id'];
+
+  // Notifications carry no id and get no response.
+  if (id === undefined || id === null) {
+    return { kind: 'accepted' };
+  }
+
+  if (typeof id !== 'string' && typeof id !== 'number') {
+    return { kind: 'invalid' };
+  }
+
+  const params = isRecord(message['params']) ? message['params'] : {};
+  const missingScope = method === 'tools/call' ? findMissingScope(params, deps.scopes) : null;
+
+  if (missingScope !== null) {
+    return { kind: 'forbidden', scope: missingScope };
+  }
+
+  const outcome = await match(method)
+    .with('initialize', () => ({
+      kind: 'reply' as const,
+      body: buildRPCResult(id, {
+        protocolVersion: pickProtocolVersion(params['protocolVersion']),
+        capabilities: { tools: {} },
+        serverInfo: { name: 'atc', version: deps.build },
+      }),
+    }))
+    .with('ping', () => ({ kind: 'reply' as const, body: buildRPCResult(id, {}) }))
+    .with('tools/list', () => ({
+      kind: 'reply' as const,
+      body: buildRPCResult(id, { tools: buildToolList() }),
+    }))
+    .with('tools/call', async () => {
+      const result = await answerToolCall(deps, params);
+
+      return { kind: 'reply' as const, body: buildRPCResult(id, result) };
+    })
+    .otherwise(() => ({
+      kind: 'reply' as const,
+      body: buildRPCError(id, -32_601, `unknown method '${method}'`),
+    }));
+
+  return outcome;
+}
+
+const STRICTEST_SCOPE: GrantScope = 'kill';
+
+// The scope a tool call needs and the caller lacks. A tool with no listed
+// scope fails closed: it needs the strictest scope, and only a caller holding
+// that one gets the unknown name back as a tool error.
+function findMissingScope(
+  params: Readonly<Record<string, unknown>>,
+  scopes: readonly GrantScope[] | undefined,
+): GrantScope | null {
+  if (scopes === undefined) {
+    return null;
+  }
+
+  const tool = MCP_TOOLS.find((candidate) => candidate.name === params['name']);
+  const needed = tool === undefined ? STRICTEST_SCOPE : tool.scope;
+
+  return scopes.includes(needed) ? null : needed;
+}
+
+async function answerToolCall(
+  deps: RPCDeps,
+  params: Readonly<Record<string, unknown>>,
+): Promise<Readonly<Record<string, unknown>>> {
+  const name = typeof params['name'] === 'string' ? params['name'] : '';
+  const args = isRecord(params['arguments']) ? params['arguments'] : {};
+
+  try {
+    const text = await runTool(deps.caller, name, args, deps.toolContext);
+
+    return { content: [{ type: 'text', text }] };
+  } catch (error) {
+    return { content: [{ type: 'text', text: formatToolError(error) }], isError: true };
+  }
+}
+
+function formatToolError(error: unknown): string {
+  if (error instanceof DaemonError) {
+    return `${error.code}: ${error.message}`;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function buildRPCResult(
+  id: string | number,
+  result: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function buildRPCError(
+  id: string | number,
+  code: number,
+  message: string,
+): Readonly<Record<string, unknown>> {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}

package/src/mcp/approval-state.ts

@@ -0,0 +1,155 @@
+import { mintApprovalCode } from './mint-approval-code';
+import { normalizeApprovalCode } from './normalize-approval-code';
+
+interface ApprovalRequest {
+  // The signed authorization query the login page carries: one per request.
+  readonly key: string;
+  readonly clientID: string;
+  readonly clientName: string;
+  readonly redirectURI: string;
+}
+
+/**
+ * An authorization request waiting for the operator to type its approval code.
+ */
+export interface PendingApproval extends ApprovalRequest {
+  readonly approvalCode: string;
+  attempts: number;
+  readonly expiresAt: number;
+}
+
+// At most this many approvals wait at once across every client, and each
+// client holds at most this many. Across every client, at most this many
+// approvals start per minute, which bounds how fast approval lines print.
+const MAX_PENDING = 16;
+const MAX_PENDING_PER_CLIENT = 3;
+const MAX_STARTS_PER_MINUTE = 10;
+const MAX_ATTEMPTS = 5;
+const MINUTE_MS = 60_000;
+
+/**
+ * The approvals waiting for the operator, held in memory by the HTTP process.
+ * A client's new approval past its limit drops that client's oldest, and a
+ * full set of waiting approvals makes room by dropping the oldest overall, so
+ * no client can hold the operator's approvals hostage and a refused start
+ * lasts at most a minute. Once the operator types a code, the owner session
+ * it signed in holds the binding of the one request it approved until that
+ * request's consent is answered or the binding expires.
+ */
+export class ApprovalState {
+  private readonly pendingMs: number;
+
+  private readonly now: () => number;
+
+  private readonly pending = new Map<string, PendingApproval>();
+
+  // Owner session id to the binding of the request its approval code approved.
+  private readonly approved = new Map<string, { binding: string; expiresAt: number }>();
+
+  // Approval start times within the last minute, oldest first.
+  private startedAt: readonly number[] = [];
+
+  constructor(pendingMs: number, now: () => number) {
+    this.pendingMs = pendingMs;
+    this.now = now;
+  }
+
+  // Returns null when the last minute already holds its share of starts.
+  createPending(request: ApprovalRequest): PendingApproval | null {
+    const now = this.now();
+
+    this.removeExpired(now);
+
+    this.startedAt = this.startedAt.filter((at) => now - at < MINUTE_MS);
+
+    if (this.startedAt.length >= MAX_STARTS_PER_MINUTE) {
+      return null;
+    }
+
+    const own = [...this.pending].filter(([, approval]) => approval.clientID === request.clientID);
+    const [ownOldest] = own;
+
+    if (own.length >= MAX_PENDING_PER_CLIENT && ownOldest !== undefined) {
+      this.pending.delete(ownOldest[0]);
+    }
+
+    const oldest = this.pending.keys().next();
+
+    if (this.pending.size >= MAX_PENDING && oldest.done !== true) {
+      this.pending.delete(oldest.value);
+    }
+
+    const approval: PendingApproval = {
+      ...request,
+      approvalCode: mintApprovalCode(),
+      attempts: 0,
+      expiresAt: now + this.pendingMs,
+    };
+
+    this.pending.set(approval.key, approval);
+
+    this.startedAt = [...this.startedAt, now];
+
+    return approval;
+  }
+
+  findPending(key: string): PendingApproval | null {
+    this.removeExpired(this.now());
+
+    return this.pending.get(key) ?? null;
+  }
+
+  // A wrong code counts against the approval; the last allowed miss drops it.
+  verifyApprovalCode(key: string, typed: string): 'ok' | 'wrong' | 'locked' {
+    const approval = this.findPending(key);
+
+    if (approval === null) {
+      return 'locked';
+    }
+
+    if (normalizeApprovalCode(typed) === approval.approvalCode) {
+      this.pending.delete(key);
+
+      return 'ok';
+    }
+
+    approval.attempts += 1;
+
+    if (approval.attempts >= MAX_ATTEMPTS) {
+      this.pending.delete(key);
+
+      return 'locked';
+    }
+
+    return 'wrong';
+  }
+
+  recordApproved(sessionID: string, binding: string): void {
+    this.approved.set(sessionID, { binding, expiresAt: this.now() + this.pendingMs });
+  }
+
+  // The binding an owner session approved, or null once it expired or went.
+  findApproved(sessionID: string): string | null {
+    this.removeExpired(this.now());
+
+    return this.approved.get(sessionID)?.binding ?? null;
+  }
+
+  removeApproved(sessionID: string): void {
+    this.approved.delete(sessionID);
+  }
+
+  private removeExpired(now: number): void {
+    for (const [key, approval] of this.pending) {
+      if (approval.expiresAt <= now) {
+        this.pending.delete(key);
+      }
+    }
+
+    for (const [sessionID, approved] of this.approved) {
+      if (approved.expiresAt <= now) {
+        this.approved.delete(sessionID);
+      }
+    }
+  }
+}

package/src/mcp/build-consent-binding.ts

@@ -0,0 +1,13 @@
+/**
+ * The parts of an authorization request that stay the same from its login
+ * page to its consent page: the client, where it returns, its state, and its
+ * PKCE challenge. better-auth signs each page's query afresh, so the binding
+ * between an approval code and the consent it allows is built from these.
+ */
+export function buildConsentBinding(oauthQuery: string): string {
+  const params = new URLSearchParams(oauthQuery);
+
+  return JSON.stringify(
+    ['client_id', 'redirect_uri', 'state', 'code_challenge'].map((name) => params.get(name) ?? ''),
+  );
+}

package/src/mcp/build-owner-plugin.ts

@@ -0,0 +1,122 @@
+import { getOAuthProviderApi } from '@better-auth/oauth-provider';
+import type { BetterAuthPlugin } from 'better-auth';
+import { createAuthEndpoint } from 'better-auth/api';
+import { setSessionCookie } from 'better-auth/cookies';
+import { generateRandomString } from 'better-auth/crypto';
+import { z } from 'zod';
+import { GRANT_SCOPES } from '../shared/grant-scope';
+import { isAllowedRedirectURI } from './is-allowed-redirect-uri';
+
+// atc has one user: the operator who runs it. better-auth needs an email for
+// every user, so the owner gets one no mail ever reaches.
+const OWNER_EMAIL = 'owner@atc.invalid';
+const REDIRECT_URI = z.string().refine(isAllowedRedirectURI);
+
+/**
+ * The better-auth plugin that makes the operator the one user. Its endpoints
+ * are server-only: better-auth refuses them over HTTP, so only atc's own
+ * routes reach them, and only after checking what they guard.
+ *
+ * - `signInOwner` starts an owner session and sets its cookie. atc calls it
+ *   once the operator has typed the right approval code; with the signed
+ *   authorization query in the body, better-auth then resumes the
+ *   authorization.
+ * - `verifyMCPAccessToken` returns the introspection payload of an active
+ *   access token and rejects any other token.
+ * - `createFixedClient` registers a public client: no secret, PKCE required,
+ *   and every scope atc grants open to request.
+ */
+export function buildOwnerPlugin() {
+  return {
+    id: 'atc-owner',
+    endpoints: {
+      signInOwner: createAuthEndpoint(
+        '/atc/sign-in-owner',
+        {
+          method: 'POST',
+          body: z.object({ oauth_query: z.string().optional() }),
+          metadata: { SERVER_ONLY: true },
+        },
+        async (ctx) => {
+          const adapter = ctx.context.internalAdapter;
+
+          const existing = await adapter.findUserByEmail(OWNER_EMAIL);
+
+          const user =
+            existing === null
+              ? await adapter.createUser(
+                  { email: OWNER_EMAIL, name: 'owner', emailVerified: true },
+                  { method: 'admin' },
+                )
+              : existing.user;
+
+          const session = await adapter.createSession(user.id);
+
+          await setSessionCookie(ctx, { session, user });
+
+          return ctx.json({ signedIn: true });
+        },
+      ),
+      verifyMCPAccessToken: createAuthEndpoint(
+        '/atc/verify-access-token',
+        {
+          method: 'POST',
+          body: z.object({ token: z.string() }),
+          metadata: { SERVER_ONLY: true },
+        },
+        async (ctx) => {
+          const provider = ctx.context.getPlugin('oauth-provider');
+
+          if (provider === null) {
+            throw new Error('the oauth-provider plugin is not installed');
+          }
+
+          const payload = await getOAuthProviderApi(ctx, provider.options).requireActiveAccessToken(
+            ctx.body.token,
+          );
+
+          return ctx.json(payload);
+        },
+      ),
+      createFixedClient: createAuthEndpoint(
+        '/atc/create-fixed-client',
+        {
+          method: 'POST',
+          body: z.object({
+            name: z.string().min(1),
+            redirectURIs: z.array(REDIRECT_URI).min(1),
+          }),
+          metadata: { SERVER_ONLY: true },
+        },
+        async (ctx) => {
+          const clientID = generateRandomString(32, 'a-z', 'A-Z', '0-9');
+
+          const now = new Date();
+
+          await ctx.context.adapter.create({
+            model: 'oauthClient',
+            data: {
+              clientId: clientID,
+              name: ctx.body.name,
+              redirectUris: ctx.body.redirectURIs,
+              scopes: [...GRANT_SCOPES, 'offline_access'],
+              clientCredentialsScopes: [],
+              tokenEndpointAuthMethod: 'none',
+              grantTypes: ['authorization_code', 'refresh_token'],
+              responseTypes: ['code'],
+              applicationType: ctx.body.redirectURIs.every((uri) => uri.startsWith('https:'))
+                ? 'web'
+                : 'native',
+              requirePKCE: true,
+              disabled: false,
+              createdAt: now,
+              updatedAt: now,
+            },
+          });
+
+          return ctx.json({ clientID });
+        },
+      ),
+    },
+  } satisfies BetterAuthPlugin;
+}

package/src/mcp/build-page-response.ts

@@ -0,0 +1,29 @@
+import { toHTMLText } from './to-html-text';
+
+/**
+ * An HTML response from the authorization server, sent with headers that
+ * keep it out of frames and caches and confine where its form may post.
+ * `body` is either a full page or a plain message, which is escaped and
+ * wrapped in a minimal page.
+ */
+export function buildPageResponse(
+  status: number,
+  body: { readonly page: string } | { readonly message: string },
+  formTargets: readonly string[] = [],
+): Response {
+  const html =
+    'page' in body
+      ? body.page
+      : `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>atc</title></head><body><p>${toHTMLText(body.message)}</p></body></html>`;
+
+  return new Response(html, {
+    status,
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'content-security-policy': `default-src 'none'; style-src 'unsafe-inline'; form-action 'self'${formTargets.map((target) => ` ${target}`).join('')}; frame-ancestors 'none'; base-uri 'none'`,
+      'x-frame-options': 'DENY',
+      'cache-control': 'no-store',
+      'referrer-policy': 'same-origin',
+    },
+  });
+}

package/src/mcp/build-tool-list.ts

@@ -0,0 +1,21 @@
+import { MCP_TOOLS } from './mcp-tools';
+
+interface MCPTool {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly annotations: {
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint: boolean;
+    readonly openWorldHint: boolean;
+  };
+}
+
+export function buildToolList(): readonly MCPTool[] {
+  return MCP_TOOLS.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    annotations: tool.annotations,
+  }));
+}

package/src/mcp/collect-clients.ts

@@ -0,0 +1,31 @@
+import type { Kysely } from 'kysely';
+import { collectJSONStrings } from './collect-json-strings';
+import type { MCPAuthSchema } from './types';
+
+/**
+ * A client added with `atc clients add`.
+ */
+export interface ClientView {
+  readonly clientID: string;
+  readonly name: string;
+  readonly redirectURIs: readonly string[];
+  readonly createdAt: string | null;
+}
+
+/**
+ * Every client the authorization server knows, oldest first.
+ */
+export async function collectClients(db: Kysely<MCPAuthSchema>): Promise<readonly ClientView[]> {
+  const rows = await db
+    .selectFrom('oauthClient')
+    .select(['clientId', 'name', 'redirectUris', 'createdAt'])
+    .orderBy('createdAt')
+    .execute();
+
+  return rows.map((row) => ({
+    clientID: row.clientId,
+    name: row.name ?? '',
+    redirectURIs: collectJSONStrings(row.redirectUris),
+    createdAt: row.createdAt,
+  }));
+}

package/src/mcp/collect-grants.ts

@@ -0,0 +1,55 @@
+import type { Kysely } from 'kysely';
+import { GRANT_SCOPES } from '../shared/grant-scope';
+import type { GrantScope } from '../shared/grant-scope';
+import { collectJSONStrings } from './collect-json-strings';
+import type { MCPAuthSchema } from './types';
+
+/**
+ * One authorization a client holds: every refresh token rotated from one
+ * authorization code, identified by that code's id.
+ */
+export interface GrantView {
+  readonly grantID: string;
+  readonly clientID: string;
+  readonly clientName: string;
+  readonly scopes: readonly GrantScope[];
+  readonly createdAt: string;
+  readonly lastUsedAt: string | null;
+}
+
+/**
+ * Every grant with a live refresh token, oldest first: one not revoked or
+ * rotated away and not yet expired.
+ */
+export async function collectGrants(db: Kysely<MCPAuthSchema>): Promise<readonly GrantView[]> {
+  const rows = await db
+    .selectFrom('oauthRefreshToken')
+    .leftJoin('oauthClient', 'oauthClient.clientId', 'oauthRefreshToken.clientId')
+    .leftJoin('atc_grant_use', 'atc_grant_use.grant_id', 'oauthRefreshToken.authorizationCodeId')
+    .select([
+      'oauthRefreshToken.authorizationCodeId',
+      'oauthRefreshToken.clientId',
+      'oauthRefreshToken.scopes',
+      'oauthRefreshToken.createdAt',
+      'oauthClient.name',
+      'atc_grant_use.last_used_at',
+    ])
+    .where('oauthRefreshToken.revoked', 'is', null)
+    .where('oauthRefreshToken.expiresAt', '>', new Date().toISOString())
+    .where('oauthRefreshToken.authorizationCodeId', 'is not', null)
+    .orderBy('oauthRefreshToken.createdAt')
+    .execute();
+
+  return rows.map((row) => {
+    const scopes = collectJSONStrings(row.scopes);
+
+    return {
+      grantID: row.authorizationCodeId ?? '',
+      clientID: row.clientId,
+      clientName: row.name ?? '',
+      scopes: GRANT_SCOPES.filter((scope) => scopes.includes(scope)),
+      createdAt: row.createdAt,
+      lastUsedAt: row.last_used_at,
+    };
+  });
+}

package/src/mcp/collect-json-strings.ts

@@ -0,0 +1,17 @@
+/**
+ * The strings in a column holding a JSON array, which is how the
+ * authorization server stores a list. Anything else holds none.
+ */
+export function collectJSONStrings(raw: string): readonly string[] {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+
+  return Array.isArray(parsed)
+    ? parsed.filter((item): item is string => typeof item === 'string')
+    : [];
+}

package/src/mcp/derive-token-hash.ts

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * The SHA-256 of a token, base64url encoded: the only form of a token the
+ * authorization server stores.
+ */
+export function deriveTokenHash(token: string): string {
+  return createHash('sha256').update(token).digest('base64url');
+}

package/src/mcp/find-client-name.ts

@@ -0,0 +1,19 @@
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './types';
+
+/**
+ * The name a client was added under, or null for an unknown client id or a
+ * client added without one.
+ */
+export async function findClientName(
+  db: Kysely<MCPAuthSchema>,
+  clientID: string,
+): Promise<string | null> {
+  const row = await db
+    .selectFrom('oauthClient')
+    .select('name')
+    .where('clientId', '=', clientID)
+    .executeTakeFirst();
+
+  return row?.name ?? null;
+}

package/src/mcp/find-owner-session-id.ts

@@ -0,0 +1,18 @@
+import type { HTTPServerContext } from './types';
+
+/**
+ * The id of the live owner session a request's cookie header carries, or
+ * null when it carries none, or one that is unsigned, expired, or deleted.
+ */
+export async function findOwnerSessionID(
+  ctx: HTTPServerContext,
+  cookie: string | null,
+): Promise<string | null> {
+  if (cookie === null || cookie === '') {
+    return null;
+  }
+
+  const found = await ctx.store.auth.api.getSession({ headers: new Headers({ cookie }) });
+
+  return found?.session.id ?? null;
+}

package/src/mcp/is-allowed-redirect-uri.ts

@@ -0,0 +1,21 @@
+import { isLoopbackHost } from './is-loopback-host';
+
+/**
+ * Whether a client may register a redirect URI: https, or http on a loopback
+ * host, with no fragment and no credentials.
+ */
+export function isAllowedRedirectURI(raw: string): boolean {
+  let url: URL;
+
+  try {
+    url = new URL(raw);
+  } catch {
+    return false;
+  }
+
+  if (url.hash !== '' || url.username !== '' || url.password !== '') {
+    return false;
+  }
+
+  return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopbackHost(url.hostname));
+}

package/src/mcp/is-loopback-host.ts

@@ -0,0 +1,13 @@
+/**
+ * Whether a host name or address reaches only this machine: `localhost`, an
+ * IPv4 address in 127.0.0.0/8, or `::1` with or without the brackets a URL
+ * puts around it.
+ */
+export function isLoopbackHost(host: string): boolean {
+  return (
+    host === 'localhost' ||
+    host === '::1' ||
+    host === '[::1]' ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)
+  );
+}

package/src/mcp/is-supported-protocol-version.ts

@@ -0,0 +1,13 @@
+const SUPPORTED_PROTOCOL_VERSIONS: ReadonlySet<string> = new Set([
+  '2025-11-25',
+  '2025-06-18',
+  '2024-11-05',
+]);
+
+/**
+ * Whether atc's MCP server speaks a protocol version. It leaves out
+ * `2025-03-26`, which requires JSON-RPC batching that atc does not implement.
+ */
+export function isSupportedProtocolVersion(version: unknown): version is string {
+  return typeof version === 'string' && SUPPORTED_PROTOCOL_VERSIONS.has(version);
+}