@boxxy/auth-oauth 0.0.1 → 0.2.2

package/src/auth/format-security-event.ts

@@ -0,0 +1,72 @@
+// Copied from atc: packages/mcp/src/auth/format-security-event.ts at commit 4fe647cf.
+
+import { PUBLIC_DOOR_PATHS } from '../http/public-door-paths.ts';
+import { normalizeClientName } from './normalize-client-name.ts';
+import type { SecurityEvent } from './types.ts';
+
+export interface SuppressedSecurityEvent {
+  readonly kind: 'suppressed';
+  readonly reason: SecurityEvent['kind'];
+  readonly count: number;
+}
+
+// The paths an event may hold as its route.
+const ROUTES: ReadonlySet<string> = new Set(
+  Object.values(PUBLIC_DOOR_PATHS).flatMap((group) => Object.values(group)),
+);
+
+export function formatSecurityEvent(
+  event: SecurityEvent | SuppressedSecurityEvent,
+  at: number,
+): string {
+  const head = { version: 1, ts: new Date(at).toISOString(), kind: event.kind };
+
+  if (event.kind === 'suppressed') {
+    return JSON.stringify({ ...head, reason: event.reason, count: event.count });
+  }
+
+  const requester = event.requester;
+
+  const fields = {
+    ...head,
+    outcome: event.outcome,
+    ...('reason' in event && event.reason !== undefined ? { reason: event.reason } : {}),
+    ...(event.kind === 'owner_auth'
+      ? { method: event.path === PUBLIC_DOOR_PATHS.browser.enroll ? 'enrollment_token' : 'passkey' }
+      : {}),
+    route: ROUTES.has(event.path) ? event.path : 'other',
+    ...(event.client === undefined
+      ? {}
+      : {
+          client: {
+            id: toEventText(event.client.id, 64),
+            name: toEventText(event.client.name, 100),
+          },
+        }),
+    ...(event.redirectHost === undefined
+      ? {}
+      : { redirectHost: toEventText(event.redirectHost, 255) }),
+    ...(event.correlationID === undefined ? {} : { correlationID: event.correlationID }),
+    ...(requester.socketAddress === null
+      ? {}
+      : { peer: { address: toEventText(requester.socketAddress, 45), provenance: 'socket' } }),
+    ...(requester.connectingIP === null
+      ? {}
+      : {
+          forwarded: {
+            address: toEventText(requester.connectingIP.address, 45),
+            header: 'cf-connecting-ip',
+            provenance: requester.connectingIP.provenance,
+          },
+        }),
+    ...(requester.userAgent === null
+      ? {}
+      : { userAgent: { summary: toEventText(requester.userAgent, 60), provenance: 'client' } }),
+  };
+
+  return JSON.stringify(fields);
+}
+
+function toEventText(value: string, maxLength: number): string {
+  return normalizeClientName(value, '', maxLength);
+}

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

@@ -0,0 +1,19 @@
+// Copied from atc: packages/mcp/src/auth/is-allowed-redirect-uri.ts at commit 4fe647cf.
+
+import { isLoopbackHost } from '../http/is-loopback-host.ts';
+
+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/auth/load-web-authn.ts

@@ -0,0 +1,19 @@
+// Copied from atc: packages/mcp/src/auth/load-web-authn.ts at commit 4fe647cf.
+
+import type {
+  verifyAuthenticationResponse,
+  verifyRegistrationResponse,
+} from '@simplewebauthn/server';
+
+export interface WebAuthn {
+  readonly verifyAuthenticationResponse: typeof verifyAuthenticationResponse;
+  readonly verifyRegistrationResponse: typeof verifyRegistrationResponse;
+}
+
+export async function loadWebAuthn(): Promise<WebAuthn> {
+  // the library imports this polyfill itself, but a compiled binary's bundle runs
+  // its certificate code before that import, so the polyfill loads first.
+  await import('reflect-metadata');
+
+  return import('@simplewebauthn/server');
+}

package/src/auth/mcp-auth-database.ts

@@ -0,0 +1,10 @@
+// Copied from atc: packages/mcp/src/auth/mcp-auth-database.ts at commit 4fe647cf.
+
+import type { Dialect } from 'kysely';
+
+export interface MCPAuthDatabase {
+  readonly dialect: Dialect;
+
+  // releases the file, once Kysely is done with it.
+  readonly close: () => void;
+}

package/src/auth/mcp-auth-schema.ts

@@ -0,0 +1,56 @@
+// Copied from atc: packages/mcp/src/auth/mcp-auth-schema.ts at commit 4fe647cf.
+
+// only the columns boxxy reads and writes itself: better-auth owns the tables and
+// their migrations. Dates are ISO 8601 strings and string lists are JSON arrays.
+export interface MCPAuthSchema {
+  readonly oauthClient: {
+    readonly id: string;
+    readonly clientId: string;
+    readonly name: string | null;
+    readonly redirectUris: string;
+    readonly createdAt: string | null;
+  };
+  readonly oauthAccessToken: {
+    readonly id: string;
+    readonly token: string;
+    readonly clientId: string;
+    readonly sessionId: string | null;
+    readonly authorizationCodeId: string | null;
+  };
+  readonly oauthRefreshToken: {
+    readonly id: string;
+    readonly clientId: string;
+    readonly sessionId: string | null;
+    readonly authorizationCodeId: string | null;
+    readonly scopes: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly revoked: string | null;
+  };
+  readonly oauthConsent: { readonly id: string; readonly clientId: string };
+  readonly oauthResource: { readonly identifier: string };
+  readonly session: { readonly id: string; readonly expiresAt: string };
+
+  // When each grant last reached /mcp, keyed by the grant's authorization code id.
+  readonly boxxy_grant_use: { readonly grant_id: string; readonly last_used_at: string };
+
+  // The owner's passkeys: the credential id and its COSE public key, both
+  // base64url, the signature counter the authenticator last returned, and
+  // its transports as a JSON array.
+  readonly boxxy_passkey: {
+    readonly id: string;
+    readonly public_key: string;
+    readonly counter: number;
+    readonly transports: string;
+    readonly created_at: string;
+    readonly last_used_at: string | null;
+  };
+
+  // The hash of each enrollment token a host command minted and no passkey
+  // has used yet.
+  readonly boxxy_enrollment_token: {
+    readonly token_hash: string;
+    readonly created_at: string;
+    readonly expires_at: string;
+  };
+}

package/src/auth/normalize-client-name.ts

@@ -0,0 +1,22 @@
+// Copied from atc: packages/mcp/src/auth/normalize-client-name.ts at commit 4fe647cf.
+
+export function normalizeClientName(
+  raw: unknown,
+  fallback = 'unnamed client',
+  maxLength = 100,
+): string {
+  if (typeof raw !== 'string') {
+    return fallback;
+  }
+
+  const folded = raw
+    .replaceAll(/[\t\n\v\f\r]/gu, ' ')
+    .replaceAll(/[\p{Cc}\p{Cf}]/gu, '')
+    .replaceAll(/\s+/gu, ' ')
+    .trim();
+
+  // The cut counts code points, so it never splits a surrogate pair.
+  const cut = folded.replace(new RegExp(`^(?<kept>.{${maxLength}}).+$`, 'su'), '$<kept>').trim();
+
+  return cut === '' ? fallback : cut;
+}

package/src/auth/open-auth-database.ts

@@ -0,0 +1,22 @@
+// Adapted from atc: packages/mcp/src/testing/open-test-auth-database.ts at commit 4fe647cf.
+
+import { Database } from 'bun:sqlite';
+import { buildSQLiteDialect } from '@zgeoff/kysely-bun-sqlite';
+import type { MCPAuthDatabase } from './mcp-auth-database.ts';
+
+// A write waits for another process's lock, and the cascades from a client to its tokens need
+// foreign keys.
+export function openAuthDatabase(path: string): MCPAuthDatabase {
+  const sqlite = new Database(path, { create: true });
+
+  sqlite.run('PRAGMA journal_mode = WAL;');
+  sqlite.run('PRAGMA busy_timeout = 5000;');
+  sqlite.run('PRAGMA foreign_keys = ON;');
+
+  return {
+    dialect: buildSQLiteDialect(sqlite),
+    close: () => {
+      sqlite.close();
+    },
+  };
+}

package/src/auth/open-mcp-auth.ts

@@ -0,0 +1,138 @@
+// Copied from atc: packages/mcp/src/auth/open-mcp-auth.ts at commit 4fe647cf.
+
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, openSync } from 'node:fs';
+import { mcp } from '@better-auth/mcp';
+import { oauthProvider } from '@better-auth/oauth-provider';
+import type { OAuthOptions, Scope } from '@better-auth/oauth-provider';
+import { grantScopes } from '@boxxy/contract';
+import { betterAuth } from 'better-auth';
+import type { BetterAuthPlugin } from 'better-auth';
+import { getMigrations } from 'better-auth/db/migration';
+import { Kysely, sql } from 'kysely';
+import { PUBLIC_DOOR_PATHS } from '../http/public-door-paths.ts';
+import { APPROVAL_WINDOW_SECONDS } from './approval-window-seconds.ts';
+import { createOwnerPlugin } from './create-owner-plugin.ts';
+import { deriveTokenHash } from './derive-token-hash.ts';
+import type { MCPAuthDatabase } from './mcp-auth-database.ts';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+interface MCPAuthOptions {
+  readonly dbPath: string;
+
+  // The public origin: the issuer, with `<origin>/mcp` the one resource tokens
+  // are bound to. Null opens the store to manage clients and grants only, with
+  // no resource served.
+  readonly origin: string | null;
+
+  // How long a rotated refresh token still answers with its successor; 0
+  // treats any reuse as replay.
+  readonly refreshReuseSeconds?: number;
+
+  // Opens the database file, which the entry wires to boxxy's SQLite opener.
+  readonly openDatabase: (path: string) => MCPAuthDatabase;
+}
+
+// The owner's session lives only to carry one approval from the code page
+// through consent to the code exchange, which every token detaches from.
+const OWNER_SESSION_SECONDS = 3 * APPROVAL_WINDOW_SECONDS;
+
+export async function openMCPAuth(options: MCPAuthOptions) {
+  // better-auth reads these when it builds its context; an empty endpoint
+  // turns its telemetry into a no-op.
+  process.env['BETTER_AUTH_TELEMETRY'] = '0';
+  process.env['BETTER_AUTH_TELEMETRY_ENDPOINT'] = '';
+
+  // The file holds token hashes and owner sessions, so only its owner may
+  // read it. SQLite gives the WAL and shared-memory files the main file's
+  // mode, so the mode is set before SQLite opens it.
+  closeSync(openSync(options.dbPath, 'a', 0o600));
+  chmodSync(options.dbPath, 0o600);
+
+  const database = options.openDatabase(options.dbPath);
+
+  const db = new Kysely<MCPAuthSchema>({ dialect: database.dialect });
+
+  const providerOptions: OAuthOptions<Scope[]> = {
+    loginPage: PUBLIC_DOOR_PATHS.browser.login,
+    consentPage: PUBLIC_DOOR_PATHS.browser.consent,
+    scopes: [...grantScopes, 'offline_access'],
+    disableJwtPlugin: true,
+    allowDynamicClientRegistration: false,
+    grantTypes: ['authorization_code', 'refresh_token'],
+
+    // boxxy serves one resource, so every client may request it.
+    enforcePerClientResources: false,
+    accessTokenExpiresIn: 3600,
+    codeExpiresIn: APPROVAL_WINDOW_SECONDS,
+    refreshTokenReuseInterval: options.refreshReuseSeconds ?? 0,
+    storeTokens: { hash: (token: string) => Promise.resolve(deriveTokenHash(token)) },
+  };
+
+  const provider =
+    options.origin === null
+      ? oauthProvider(providerOptions)
+      : mcp({ ...providerOptions, resource: `${options.origin}${PUBLIC_DOOR_PATHS.machine.mcp}` });
+
+  const baseURL = options.origin ?? 'http://127.0.0.1';
+
+  const auth = betterAuth({
+    baseURL,
+    basePath: '/',
+    secret: randomBytes(32).toString('base64url'),
+    database: { db, type: 'sqlite' },
+    telemetry: { enabled: false },
+    logger: { level: 'error' },
+    rateLimit: { enabled: false },
+
+    // Every open runs the migrations itself, so the startup schema check
+    // would only report the tables a fresh database has yet to get.
+    advanced: { database: { validateSchema: false } },
+    trustedOrigins: [baseURL],
+    session: { expiresIn: OWNER_SESSION_SECONDS, disableSessionRefresh: true },
+
+    // The provider's own endpoint types do not satisfy the plugin type under
+    // exactOptionalPropertyTypes, so boxxy reaches them over HTTP-shaped requests.
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- better-auth's plugin type fails its own type under exactOptionalPropertyTypes
+    plugins: [provider as BetterAuthPlugin, createOwnerPlugin()],
+  });
+
+  const migrations = await getMigrations(auth.options);
+
+  await migrations.runMigrations();
+
+  await sql`create table if not exists boxxy_grant_use (grant_id text primary key not null, last_used_at text not null)`.execute(
+    db,
+  );
+
+  await sql`create table if not exists boxxy_passkey (id text primary key not null, public_key text not null, counter integer not null, transports text not null, created_at text not null, last_used_at text)`.execute(
+    db,
+  );
+
+  await sql`create table if not exists boxxy_enrollment_token (token_hash text primary key not null, created_at text not null, expires_at text not null)`.execute(
+    db,
+  );
+
+  // A resource served under an earlier public URL stays a valid token target
+  // until its row goes.
+  if (options.origin !== null) {
+    await db
+      .deleteFrom('oauthResource')
+      .where('identifier', '!=', `${options.origin}${PUBLIC_DOOR_PATHS.machine.mcp}`)
+      .execute();
+  }
+
+  // better-auth starts its context when it is built, and that start queries
+  // the database, so a close before it settles destroys the driver under it.
+  await auth.$context;
+
+  return {
+    auth,
+    db,
+    async close(): Promise<void> {
+      await db.destroy();
+
+      database.close();
+    },
+  };
+}

package/src/auth/passkey-script.ts

@@ -0,0 +1,50 @@
+// Copied from atc: packages/mcp/src/auth/passkey-script.ts at commit 4fe647cf.
+
+import { createHash } from 'node:crypto';
+
+// runs the `create` or `get` ceremony a page's `boxxy-passkey` block holds and posts
+// the credential's JSON with the form; a prompt that ends without one leaves the
+// form unsent and the button ready again.
+const SOURCE = `(() => {
+  const data = document.getElementById('boxxy-passkey');
+  const form = document.getElementById('boxxy-passkey-form');
+  const button = document.getElementById('boxxy-passkey-start');
+  const status = document.getElementById('boxxy-passkey-status');
+  if (data === null || form === null || button === null || status === null) return;
+  const spec = JSON.parse(data.textContent);
+  const toBytes = (value) => {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+    return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+  };
+  const toText = (buffer) => {
+    let text = '';
+    for (const byte of new Uint8Array(buffer)) text += String.fromCharCode(byte);
+    return btoa(text).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');
+  };
+  const toDescriptors = (list) => (list || []).map((item) => ({ ...item, id: toBytes(item.id) }));
+  button.addEventListener('click', async () => {
+    button.disabled = true;
+    status.textContent = '';
+    try {
+      const options = spec.options;
+      const credential = spec.mode === 'create'
+        ? await navigator.credentials.create({ publicKey: { ...options, challenge: toBytes(options.challenge), user: { ...options.user, id: toBytes(options.user.id) }, excludeCredentials: toDescriptors(options.excludeCredentials) } })
+        : await navigator.credentials.get({ publicKey: { ...options, challenge: toBytes(options.challenge), allowCredentials: toDescriptors(options.allowCredentials) } });
+      const reply = credential.response;
+      const response = spec.mode === 'create'
+        ? { clientDataJSON: toText(reply.clientDataJSON), attestationObject: toText(reply.attestationObject), transports: typeof reply.getTransports === 'function' ? reply.getTransports() : [] }
+        : { clientDataJSON: toText(reply.clientDataJSON), authenticatorData: toText(reply.authenticatorData), signature: toText(reply.signature), userHandle: reply.userHandle ? toText(reply.userHandle) : undefined };
+      form.elements.namedItem('credential').value = JSON.stringify({ id: credential.id, rawId: toText(credential.rawId), type: credential.type, response, clientExtensionResults: credential.getClientExtensionResults(), authenticatorAttachment: credential.authenticatorAttachment || undefined });
+      form.submit();
+    } catch (error) {
+      status.textContent = 'The passkey prompt ended without a passkey (' + (error && error.name ? error.name : 'Error') + '). Try again.';
+      button.disabled = false;
+    }
+  });
+})();`;
+
+export const PASSKEY_SCRIPT = {
+  source: SOURCE,
+  policySource: `'sha256-${createHash('sha256').update(SOURCE).digest('base64')}'`,
+} as const;

package/src/auth/read-client-name.ts

@@ -0,0 +1,17 @@
+// Copied from atc: packages/mcp/src/auth/read-client-name.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export async function readClientName(
+  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/auth/read-client-views.ts

@@ -0,0 +1,27 @@
+// Copied from atc: packages/mcp/src/auth/read-client-views.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import { parseJSONStrings } from '../utils/parse-json-strings.ts';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export interface ClientView {
+  readonly clientID: string;
+  readonly name: string;
+  readonly redirectURIs: readonly string[];
+  readonly createdAt: string | null;
+}
+
+export async function readClientViews(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: parseJSONStrings(row.redirectUris) ?? [],
+    createdAt: row.createdAt,
+  }));
+}

package/src/auth/read-enrollment-token.ts

@@ -0,0 +1,20 @@
+// Copied from atc: packages/mcp/src/auth/read-enrollment-token.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import { deriveTokenHash } from './derive-token-hash.ts';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export async function readEnrollmentToken(
+  db: Kysely<MCPAuthSchema>,
+  token: string,
+  now: number,
+): Promise<string | null> {
+  const row = await db
+    .selectFrom('boxxy_enrollment_token')
+    .select('token_hash')
+    .where('token_hash', '=', deriveTokenHash(token))
+    .where('expires_at', '>', new Date(now).toISOString())
+    .executeTakeFirst();
+
+  return row?.token_hash ?? null;
+}

package/src/auth/read-grant-views.ts

@@ -0,0 +1,53 @@
+// Copied from atc: packages/mcp/src/auth/read-grant-views.ts at commit 4fe647cf.
+
+import { grantScopes } from '@boxxy/contract';
+import type { GrantScope } from '@boxxy/contract';
+import type { Kysely } from 'kysely';
+import { parseJSONStrings } from '../utils/parse-json-strings.ts';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export interface GrantView {
+  readonly grantID: string;
+  readonly clientID: string;
+  readonly clientName: string;
+  readonly scopes: readonly GrantScope[];
+  readonly createdAt: string;
+  readonly lastUsedAt: string | null;
+}
+
+export async function readGrantViews(db: Kysely<MCPAuthSchema>): Promise<readonly GrantView[]> {
+  const rows = await db
+    .selectFrom('oauthRefreshToken')
+    .leftJoin('oauthClient', 'oauthClient.clientId', 'oauthRefreshToken.clientId')
+    .leftJoin(
+      'boxxy_grant_use',
+      'boxxy_grant_use.grant_id',
+      'oauthRefreshToken.authorizationCodeId',
+    )
+    .select([
+      'oauthRefreshToken.authorizationCodeId',
+      'oauthRefreshToken.clientId',
+      'oauthRefreshToken.scopes',
+      'oauthRefreshToken.createdAt',
+      'oauthClient.name',
+      'boxxy_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 = parseJSONStrings(row.scopes) ?? [];
+
+    return {
+      grantID: row.authorizationCodeId ?? '',
+      clientID: row.clientId,
+      clientName: row.name ?? '',
+      scopes: grantScopes.filter((scope) => scopes.includes(scope)),
+      createdAt: row.createdAt,
+      lastUsedAt: row.last_used_at,
+    };
+  });
+}

package/src/auth/read-owner-session-id.ts

@@ -0,0 +1,16 @@
+// Copied from atc: packages/mcp/src/auth/read-owner-session-id.ts at commit 4fe647cf.
+
+import type { HTTPServerContext } from './types.ts';
+
+export async function readOwnerSessionID(
+  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/auth/record-refused-exchange.ts

@@ -0,0 +1,74 @@
+// Copied from atc: packages/mcp/src/auth/record-refused-exchange.ts at commit 4fe647cf.
+
+import { isRecord } from '../utils/is-record.ts';
+import { normalizeClientName } from './normalize-client-name.ts';
+import { readClientName } from './read-client-name.ts';
+import type { HTTPServerContext, Requester, TokenExchangeReason } from './types.ts';
+
+interface RefusedExchange {
+  // The refused request's body, read only for its client id.
+  readonly contentType: string | null;
+  readonly body: string;
+  readonly response: Response;
+  readonly path: string;
+  readonly requester: Requester;
+}
+
+// The event holds better-auth's error code from a fixed list, and the
+// client's id and name only for a client boxxy holds. It never holds the
+// code, the verifier, or a token the request carried.
+export async function recordRefusedExchange(
+  ctx: Pick<HTTPServerContext, 'store' | 'security'>,
+  exchange: RefusedExchange,
+): Promise<void> {
+  const code = await readErrorCode(exchange.response);
+
+  const reason = isTokenExchangeError(code) ? code : 'other';
+  const clientID = findClientID(exchange);
+  const storedName = clientID === null ? null : await readClientName(ctx.store.db, clientID);
+
+  ctx.security.record({
+    kind: 'token_exchange',
+    outcome: 'rejected',
+    reason,
+    path: exchange.path,
+    requester: exchange.requester,
+    ...(clientID === null || storedName === null
+      ? {}
+      : { client: { id: clientID, name: normalizeClientName(storedName) } }),
+  });
+}
+
+async function readErrorCode(response: Response): Promise<string | null> {
+  try {
+    const body: unknown = await response.clone().json();
+
+    return isRecord(body) && typeof body['error'] === 'string' ? body['error'] : null;
+  } catch {
+    return null;
+  }
+}
+
+// A fixed list keeps the reason a value a log rule can match, whatever text
+// a future better-auth puts in its error field.
+const TOKEN_EXCHANGE_ERRORS: ReadonlySet<string> = new Set([
+  'invalid_request',
+  'invalid_client',
+  'invalid_grant',
+  'unauthorized_client',
+  'unsupported_grant_type',
+  'invalid_scope',
+  'invalid_target',
+]);
+
+function isTokenExchangeError(code: string | null): code is TokenExchangeReason {
+  return code !== null && TOKEN_EXCHANGE_ERRORS.has(code);
+}
+
+function findClientID(exchange: RefusedExchange): string | null {
+  if (exchange.contentType?.startsWith('application/x-www-form-urlencoded') !== true) {
+    return null;
+  }
+
+  return new URLSearchParams(exchange.body).get('client_id');
+}

package/src/auth/remove-client.ts

@@ -0,0 +1,33 @@
+// Copied from atc: packages/mcp/src/auth/remove-client.ts at commit 4fe647cf.
+
+import type { Kysely } from 'kysely';
+import type { MCPAuthSchema } from './mcp-auth-schema.ts';
+
+export function removeClient(db: Kysely<MCPAuthSchema>, clientID: string): Promise<boolean> {
+  return db.transaction().execute(async (trx) => {
+    const grants = await trx
+      .selectFrom('oauthRefreshToken')
+      .select('authorizationCodeId')
+      .where('clientId', '=', clientID)
+      .execute();
+
+    const grantIDs = grants.flatMap((grant) =>
+      grant.authorizationCodeId === null ? [] : [grant.authorizationCodeId],
+    );
+
+    if (grantIDs.length > 0) {
+      await trx.deleteFrom('boxxy_grant_use').where('grant_id', 'in', grantIDs).execute();
+    }
+
+    await trx.deleteFrom('oauthAccessToken').where('clientId', '=', clientID).execute();
+    await trx.deleteFrom('oauthRefreshToken').where('clientId', '=', clientID).execute();
+    await trx.deleteFrom('oauthConsent').where('clientId', '=', clientID).execute();
+
+    const removed = await trx
+      .deleteFrom('oauthClient')
+      .where('clientId', '=', clientID)
+      .executeTakeFirst();
+
+    return removed.numDeletedRows > 0n;
+  });
+}