@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/modules/tool-auth/__tests__/connection-key-rejection.test.ts

@@ -0,0 +1,192 @@
+import type { Server as HttpServer } from 'node:http';
+import express, { type RequestHandler } from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { setLogger } from '../../../shared/logging.js';
+import type { ILogger, LogFields } from '../../../shared/logger.contract.js';
+import { createMcpAuthMiddleware } from '../../mcp/mcp-auth.middleware.js';
+import type { BevelOAuthProvider } from '../../mcp/oauth/bevel-oauth-provider.js';
+import { createAgentInstructionsRoutes } from '../../agent-instructions/agent-instructions.routes.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import { InternalTokenService } from '../internal-token.service.js';
+import { createManualAuthMiddleware, createToolAuthMiddleware } from '../tool-auth.middleware.js';
+import type { IExternalApiKeyService } from '../external-api-key.interface.js';
+
+/**
+ * A bearer shaped like a connection key that does not verify is answered with
+ * a plain sentence on EVERY key-authenticated endpoint the local server
+ * (hexis-mcp) calls — never with the `resource_metadata` challenge that
+ * invites an MCP client into a browser sign-in. A missing bearer and a bad
+ * OAuth token keep today's challenges, so sign-in still starts for those.
+ *
+ * The middlewares are the real ones; the handlers behind them (other than
+ * the agent instructions route) are stand-ins mounted at the paths the local
+ * server requests, with the same gate `create-core-server.ts` puts on each.
+ */
+const BAD_KEY = 'bevel_revokedKeyThatMustNeverBeEchoed';
+const RESOURCE_METADATA_URL = 'https://hexis.example/.well-known/oauth-protected-resource/api/mcp';
+const DISCOVERY_CHALLENGE = `Bearer realm="bevel-mcp", resource_metadata="${RESOURCE_METADATA_URL}"`;
+const KEY_CHALLENGE = 'Bearer error="invalid_token", error_description="Invalid or revoked connection key"';
+const KEY_BODY = { error: 'Invalid or revoked connection key. Mint a new one in External agent access.' };
+
+const externalApiKeys = {
+  looksLikeExternalApiKey: (t: string) => t.startsWith('bevel_'),
+  verifyAndLoadToken: async () => null,
+} as unknown as IExternalApiKeyService;
+
+const oauthProvider = {
+  looksLikeAccessToken: (t: string) => t.startsWith('bevel-mcp_'),
+  verifyAccessToken: async () => {
+    throw new InvalidTokenError('expired');
+  },
+} as unknown as BevelOAuthProvider;
+
+const authService = {
+  verifyToken: () => {
+    throw new Error('bad jwt');
+  },
+} as unknown as AuthService;
+
+/** Every line logged during a test, fields serialized, so a key anywhere in one is found. */
+let logged: string[] = [];
+let previousLogger: ILogger | undefined;
+function capturingLogger(bindings: LogFields = {}): ILogger {
+  const line = (level: string) => (message: string, fields?: LogFields) => {
+    logged.push(`${level} ${message} ${JSON.stringify({ ...bindings, ...fields }, (_k, v) => (v instanceof Error ? `${v.message} ${v.stack}` : v))}`);
+  };
+  return {
+    debug: line('debug'),
+    info: line('info'),
+    warn: line('warn'),
+    error: line('error'),
+    child: (more) => capturingLogger({ ...bindings, ...more }),
+  };
+}
+
+let server: HttpServer | undefined;
+beforeEach(() => {
+  logged = [];
+  previousLogger = setLogger(capturingLogger());
+});
+afterEach(async () => {
+  if (previousLogger) setLogger(previousLogger);
+  if (server) await new Promise<void>((r) => server!.close(() => r()));
+  server = undefined;
+});
+
+async function start(keys: IExternalApiKeyService = externalApiKeys): Promise<string> {
+  const internalTokens = new InternalTokenService({ secret: 'test-secret-32-bytes-long-enough!!' });
+  const mcpAuth = createMcpAuthMiddleware(authService, keys, oauthProvider, RESOURCE_METADATA_URL, internalTokens);
+  const toolAuth = createToolAuthMiddleware(keys, internalTokens);
+  const manualAuth = createManualAuthMiddleware(keys, internalTokens, authService);
+  const ok: RequestHandler = (_req, res) => {
+    res.json({ ok: true });
+  };
+  const app = express();
+  app.post('/api/mcp', mcpAuth, ok);
+  app.use('/api', createAgentInstructionsRoutes(manualAuth, async () => 'preamble'));
+  app.get('/api/agent/all-tools', manualAuth, ok);
+  app.post('/api/agent/tools/list_local_tools', toolAuth, ok);
+  app.post('/api/agent/local-tools/:slug/variables', manualAuth, ok);
+  app.get('/api/agent/plugins/:folder/archive', manualAuth, ok);
+  server = await new Promise<HttpServer>((res) => {
+    const s = app.listen(0, () => res(s));
+  });
+  return `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+}
+
+/** The key-authenticated requests hexis-mcp makes, as it makes them. */
+const KEY_ENDPOINTS: { name: string; method: 'GET' | 'POST'; path: string }[] = [
+  { name: 'MCP', method: 'POST', path: '/api/mcp' },
+  { name: 'agent instructions', method: 'GET', path: '/api/agent/instructions' },
+  { name: 'tool manual list', method: 'GET', path: '/api/agent/all-tools?remote=false' },
+  { name: 'local-only tool list', method: 'POST', path: '/api/agent/tools/list_local_tools' },
+  { name: 'local tool variables', method: 'POST', path: '/api/agent/local-tools/notion/variables' },
+  { name: 'plugin archive', method: 'GET', path: '/api/agent/plugins/GTM/archive' },
+];
+
+const call = (base: string, method: string, path: string, bearer?: string) =>
+  fetch(`${base}${path}`, {
+    method,
+    headers: {
+      ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}),
+      ...(method === 'POST' ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: method === 'POST' ? '{}' : undefined,
+  });
+
+describe('an invalid connection key is rejected plainly', () => {
+  for (const endpoint of KEY_ENDPOINTS) {
+    it(`${endpoint.name}: 401, invalid_token challenge without resource_metadata, the sentence, and no key anywhere`, async () => {
+      const base = await start();
+      const res = await call(base, endpoint.method, endpoint.path, BAD_KEY);
+      const text = await res.text();
+
+      expect(res.status).toBe(401);
+      expect(res.headers.get('www-authenticate')).toBe(KEY_CHALLENGE);
+      expect(JSON.parse(text)).toEqual(KEY_BODY);
+
+      const everyHeader = [...res.headers.entries()].map(([k, v]) => `${k}: ${v}`).join('\n');
+      expect(everyHeader).not.toContain('resource_metadata');
+      expect(everyHeader).not.toContain(BAD_KEY);
+      expect(text).not.toContain(BAD_KEY);
+      expect(logged.join('\n')).not.toContain(BAD_KEY);
+    });
+  }
+});
+
+describe('a key whose verification fails is a 500 that still logs no key', () => {
+  // The one branch that logs: the key store itself failed (a database error),
+  // so the caller's key may be fine and the answer is 500, not 401. What is
+  // logged is the store's error — never the bearer that was being checked.
+  const brokenStore = {
+    looksLikeExternalApiKey: (t: string) => t.startsWith('bevel_'),
+    verifyAndLoadToken: async () => {
+      throw new Error('connection pool exhausted');
+    },
+  } as unknown as IExternalApiKeyService;
+
+  for (const endpoint of KEY_ENDPOINTS) {
+    it(`${endpoint.name}: 500, the error logged, and no key anywhere`, async () => {
+      const base = await start(brokenStore);
+      const res = await call(base, endpoint.method, endpoint.path, BAD_KEY);
+      const text = await res.text();
+
+      expect(res.status).toBe(500);
+      expect(JSON.parse(text)).toEqual({ error: 'Authentication backend unavailable' });
+      expect(logged.join('\n')).toContain('connection pool exhausted');
+      expect(logged.join('\n')).not.toContain(BAD_KEY);
+      expect(text).not.toContain(BAD_KEY);
+    });
+  }
+});
+
+describe('the MCP endpoint keeps inviting sign-in where sign-in is the answer', () => {
+  it('no Authorization header: the resource_metadata discovery challenge, unchanged', async () => {
+    const base = await start();
+    const res = await call(base, 'POST', '/api/mcp');
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toBe(DISCOVERY_CHALLENGE);
+    expect(await res.json()).toEqual({ error: 'Missing or invalid Authorization header' });
+  });
+
+  it('an invalid or expired OAuth access token: the resource_metadata discovery challenge, unchanged', async () => {
+    const base = await start();
+    const res = await call(base, 'POST', '/api/mcp', 'bevel-mcp_expiredAccessToken');
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toBe(DISCOVERY_CHALLENGE);
+    expect(await res.json()).toEqual({ error: 'Invalid, expired, or revoked access token' });
+    expect(logged.join('\n')).not.toContain('bevel-mcp_expiredAccessToken');
+  });
+});
+
+describe('the REST agent surface keeps its challenge for everything but a key', () => {
+  it('no Authorization header: the bevel-tools realm challenge, unchanged', async () => {
+    const base = await start();
+    for (const endpoint of KEY_ENDPOINTS.filter((e) => e.name !== 'MCP')) {
+      const res = await call(base, endpoint.method, endpoint.path);
+      expect(res.status, endpoint.name).toBe(401);
+      expect(res.headers.get('www-authenticate'), endpoint.name).toBe('Bearer realm="bevel-tools"');
+    }
+  });
+});

package/src/modules/tool-auth/__tests__/connection-keys-admin.routes.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createConnectionKeysAdminRoutes } from '../connection-keys-admin.routes.js';
+import { TokenNotFoundError } from '../external-api-key.errors.js';
+import type { AdminExternalApiKeySummary } from '../external-api-key.interface.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+
+const TOK = '0f1e2d3c-4b5a-4697-8877-665544332211';
+const GHOST = '00000000-0000-4000-8000-000000000000';
+
+const ALICE_KEY: AdminExternalApiKeySummary = {
+  id: TOK,
+  label: 'CI pipeline',
+  kind: 'key',
+  createdAt: Date.UTC(2026, 0, 1),
+  lastUsedAt: Date.UTC(2026, 0, 2),
+  revokedAt: null,
+  user: { id: 'u-alice', email: 'alice@example.com', name: 'Alice' },
+};
+
+const keys = {
+  listForDeployment: vi.fn(async () => [ALICE_KEY]),
+  revokeAny: vi.fn<(id: string) => Promise<void>>(async () => {}),
+};
+
+function makeApp(opts: { admin: boolean }) {
+  const adminAccess: IAdminAccessService = {
+    isAdmin: vi.fn(async () => opts.admin),
+  };
+  const app = express();
+  app.use(express.json());
+  // Stand-in auth middleware: stamps the caller identity the way the real JWT
+  // middleware does.
+  app.use((req, _res, next) => {
+    req.userId = 'u-admin';
+    req.userEmail = 'admin@example.com';
+    next();
+  });
+  app.use('/api', createConnectionKeysAdminRoutes(keys, adminAccess));
+  return app;
+}
+
+let server: Server;
+afterEach(() => {
+  server?.close();
+  keys.listForDeployment.mockClear().mockResolvedValue([ALICE_KEY]);
+  keys.revokeAny.mockClear().mockResolvedValue(undefined);
+});
+
+async function listen(app: express.Express): Promise<string> {
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+describe('connection-keys admin routes', () => {
+  it('refuses non-admins on both endpoints without touching the service', async () => {
+    const base = await listen(makeApp({ admin: false }));
+    expect((await fetch(`${base}/api/admin/connection-keys`)).status).toBe(403);
+    expect(
+      (await fetch(`${base}/api/admin/connection-keys/${TOK}`, { method: 'DELETE' })).status,
+    ).toBe(403);
+    expect(keys.listForDeployment).not.toHaveBeenCalled();
+    expect(keys.revokeAny).not.toHaveBeenCalled();
+  });
+
+  it('lists every key with its owner for admins', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    const res = await fetch(`${base}/api/admin/connection-keys`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { keys: AdminExternalApiKeySummary[] };
+    expect(body.keys).toEqual([ALICE_KEY]);
+  });
+
+  it('revokes any key by id for admins (not scoped to the caller)', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    const res = await fetch(`${base}/api/admin/connection-keys/${TOK}`, { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: 'revoked' });
+    expect(keys.revokeAny).toHaveBeenCalledWith(TOK);
+  });
+
+  it('404s a malformed id without reaching the database (a uuid column would 500 on it)', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    for (const bad of ['not-a-uuid', '123', '0f1e2d3c-4b5a-4697-8877-66554433221']) {
+      const res = await fetch(`${base}/api/admin/connection-keys/${bad}`, { method: 'DELETE' });
+      expect(res.status).toBe(404);
+      expect(((await res.json()) as { error: string }).error).toBe('Token not found');
+    }
+    expect(keys.revokeAny).not.toHaveBeenCalled();
+  });
+
+  it('404s an unknown key and 500s with a generic body on other failures', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    keys.revokeAny.mockRejectedValueOnce(new TokenNotFoundError());
+    expect(
+      (await fetch(`${base}/api/admin/connection-keys/${GHOST}`, { method: 'DELETE' })).status,
+    ).toBe(404);
+
+    keys.revokeAny.mockRejectedValueOnce(new Error('relation "api_tokens" does not exist'));
+    const res = await fetch(`${base}/api/admin/connection-keys/${TOK}`, { method: 'DELETE' });
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe('Failed to revoke this key');
+    expect(JSON.stringify(body)).not.toContain('relation');
+
+    keys.listForDeployment.mockRejectedValueOnce(new Error('boom'));
+    const list = await fetch(`${base}/api/admin/connection-keys`);
+    expect(list.status).toBe(500);
+    expect(((await list.json()) as { error: string }).error).toBe('Failed to load connection keys');
+  });
+});

package/src/modules/tool-auth/__tests__/external-api-key.service.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import { createHash } from 'node:crypto';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
 import { ExternalApiKeyService } from '../external-api-key.service.js';
 import {
   InvalidTokenLabelError,
@@ -101,6 +103,15 @@ function makeRow(overrides: Partial<{
   };
 }
 
+/**
+ * Render a drizzle predicate to SQL text + params, so a test can assert on
+ * WHAT was asked of the database even though the fake never evaluates it.
+ */
+function renderSql(fragment: SQL): { sql: string; params: unknown[] } {
+  const q = new PgDialect().sqlToQuery(fragment);
+  return { sql: q.sql, params: q.params };
+}
+
 function sha256Hex(s: string): string {
   return createHash('sha256').update(s).digest('hex');
 }
@@ -137,7 +148,26 @@ describe('ExternalApiKeyService', () => {
         createdAt: row.createdAt.getTime(),
         lastUsedAt: null,
         revokedAt: null,
+        revokedBy: null,
+      });
+    });
+
+    it('mints a kind that asks for a GitHub-shaped token as prefix plus forty letters and digits', async () => {
+      const { db, calls } = makeFakeDb([[makeRow()]]);
+      const service = new ExternalApiKeyService(db, 'bevel_', {
+        'github-link': { prefix: 'gho_', shape: 'github-token' },
       });
+
+      const result = await service.mint('user-1', 'Claude', { kind: 'github-link' });
+
+      // GitHub's own tokens are alphanumeric after the prefix; a consumer
+      // that checks the shape must keep ours.
+      expect(result.plaintext).toMatch(/^gho_[A-Za-z0-9]{40}$/);
+      expect(service.looksLikeExternalApiKey(result.plaintext)).toBe(true);
+      expect(calls.values[0][0].tokenHash).toBe(sha256Hex(result.plaintext));
+      // The kind is STORED, not inferred back from the prefix: it is what
+      // classifies the key everywhere else.
+      expect(calls.values[0][0].kind).toBe('github-link');
     });
 
     it('trims the label before persisting', async () => {
@@ -272,6 +302,7 @@ describe('ExternalApiKeyService', () => {
         createdAt: rows[0].createdAt.getTime(),
         lastUsedAt: rows[0].lastUsedAt!.getTime(),
         revokedAt: null,
+        revokedBy: null,
       });
       expect(summaries[1].revokedAt).toBe(rows[1].revokedAt!.getTime());
       // sanity-check that ordering was requested (we can't introspect the
@@ -280,6 +311,98 @@ describe('ExternalApiKeyService', () => {
     });
   });
 
+  describe('listForDeployment', () => {
+    it('joins the owner onto every key and keeps the row order the DB returned', async () => {
+      const aliceKey = makeRow({ id: 'a', userId: 'u-alice', lastUsedAt: new Date('2026-03-02T00:00:00Z') });
+      const bobKey = makeRow({ id: 'b', userId: 'u-bob', revokedAt: new Date('2026-02-15T00:00:00Z') });
+      const rows = [
+        { key: aliceKey, userId: 'u-alice', email: 'alice@example.com', name: 'Alice' },
+        { key: bobKey, userId: 'u-bob', email: 'bob@example.com', name: 'Bob' },
+      ];
+      const { db, calls } = makeFakeDb([rows]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      const summaries = await service.listForDeployment();
+
+      expect(summaries).toEqual([
+        {
+          id: 'a',
+          label: aliceKey.label,
+          kind: aliceKey.kind,
+          createdAt: aliceKey.createdAt.getTime(),
+          lastUsedAt: aliceKey.lastUsedAt!.getTime(),
+          revokedAt: null,
+          revokedBy: null,
+          user: { id: 'u-alice', email: 'alice@example.com', name: 'Alice' },
+        },
+        {
+          id: 'b',
+          label: bobKey.label,
+          kind: bobKey.kind,
+          createdAt: bobKey.createdAt.getTime(),
+          lastUsedAt: null,
+          revokedAt: bobKey.revokedAt!.getTime(),
+          revokedBy: null,
+          user: { id: 'u-bob', email: 'bob@example.com', name: 'Bob' },
+        },
+      ]);
+      // One join to users, one ordering clause — the grouping order is the
+      // DB's job, not a re-sort here.
+      expect(calls.innerJoin).toHaveLength(1);
+      expect(calls.orderBy).toHaveLength(1);
+      // The hash never leaves the service, even for admins.
+      expect(JSON.stringify(summaries)).not.toContain('hash-1');
+    });
+  });
+
+  describe('revokeAny', () => {
+    it('revokes without an owner scope when the token was active', async () => {
+      const { db, calls } = makeFakeDb([[{ id: 'tok-1' }]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await service.revokeAny('tok-1');
+
+      expect(calls.set[0][0].revokedAt).toBeInstanceOf(Date);
+      // Recorded as the admin's doing, so the owner's page can say so.
+      expect(calls.set[0][0].revokedBy).toBe('admin');
+      expect((db as any).select).not.toHaveBeenCalled();
+      // The fake DB ignores predicates, so render the one the UPDATE was
+      // given: it must pin the id and the not-yet-revoked state, and must NOT
+      // carry a user_id — that scope is what makes this the admin path. The
+      // owner path (`revoke`) is checked for the opposite below.
+      const where = renderSql(calls.where[0][0]);
+      expect(where.sql).toContain('"id" = ');
+      expect(where.sql).toContain('"revoked_at" is null');
+      expect(where.sql).not.toContain('user_id');
+      expect(where.params).toEqual(['tok-1']);
+    });
+
+    it('owner-scoped revoke, by contrast, does carry the user_id predicate', async () => {
+      const { db, calls } = makeFakeDb([[{ id: 'tok-1' }]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await service.revoke('tok-1', 'user-1');
+
+      const where = renderSql(calls.where[0][0]);
+      expect(where.sql).toContain('"user_id" = ');
+      expect(where.params).toEqual(['tok-1', 'user-1']);
+    });
+
+    it('is idempotent on an already-revoked token', async () => {
+      const { db } = makeFakeDb([[], [{ id: 'tok-1' }]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await expect(service.revokeAny('tok-1')).resolves.toBeUndefined();
+    });
+
+    it('throws TokenNotFoundError when no such token exists on the deployment', async () => {
+      const { db } = makeFakeDb([[], []]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await expect(service.revokeAny('tok-x')).rejects.toBeInstanceOf(TokenNotFoundError);
+    });
+  });
+
   describe('revoke', () => {
     it('updates the row and returns silently when the token belongs to the user and was active', async () => {
       // First op: UPDATE returns 1 row.
@@ -290,6 +413,7 @@ describe('ExternalApiKeyService', () => {
 
       const setArgs = calls.set[0][0];
       expect(setArgs.revokedAt).toBeInstanceOf(Date);
+      expect(setArgs.revokedBy).toBe('owner');
       // No follow-up SELECT — the UPDATE found a row.
       expect((db as any).select).not.toHaveBeenCalled();
     });

package/src/modules/tool-auth/connection-key-rejection.ts

@@ -0,0 +1,25 @@
+import type { Response } from 'express';
+
+/**
+ * How every key-authenticated endpoint answers a bearer that LOOKS like a
+ * connection key but does not verify (unknown, revoked, mistyped).
+ *
+ * Deliberately no `resource_metadata`: that parameter (RFC 9728) invites an
+ * OAuth-capable client to discover our authorization server and start a
+ * browser sign-in, which is the wrong answer to someone who configured a key —
+ * signing in does not repair the key, and the invitation buries the one thing
+ * they need to hear. A missing bearer or a bad OAuth token keeps the discovery
+ * challenge; only this shape gets the plain sentence.
+ *
+ * The submitted key is never echoed, in the header, the body, or a log line.
+ */
+export const INVALID_CONNECTION_KEY_CHALLENGE =
+  'Bearer error="invalid_token", error_description="Invalid or revoked connection key"';
+
+export const INVALID_CONNECTION_KEY_MESSAGE =
+  'Invalid or revoked connection key. Mint a new one in External agent access.';
+
+export function rejectConnectionKey(res: Response): void {
+  res.setHeader('WWW-Authenticate', INVALID_CONNECTION_KEY_CHALLENGE);
+  res.status(401).json({ error: INVALID_CONNECTION_KEY_MESSAGE });
+}

package/src/modules/tool-auth/connection-keys-admin.routes.ts

@@ -0,0 +1,76 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('connection-keys');
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import { TokenNotFoundError } from './external-api-key.errors.js';
+import type { IExternalApiKeyService } from './external-api-key.interface.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+
+/** Shape of the `api_tokens.id` column (any uuid version; case-insensitive). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Admin overview of connection keys across the deployment (the core
+ * "Connection keys" admin page): every key on every account — owner, label,
+ * created, last used, whether it is still live — and a revoke that is not
+ * scoped to the caller. The per-user surface stays in mcp.routes.ts; this
+ * router exists so an admin can cut off a leaked or forgotten key without
+ * signing in as its owner. Gated per request by {@link IAdminAccessService}.
+ */
+export function createConnectionKeysAdminRoutes(
+  externalApiKeyService: Pick<IExternalApiKeyService, 'listForDeployment' | 'revokeAny'>,
+  adminAccess: IAdminAccessService,
+): express.Router {
+  const router = express.Router();
+
+  const requireAdmin: express.RequestHandler = async (req, res, next) => {
+    if (!(await adminAccess.isAdmin(req.userEmail))) {
+      res.status(403).json({ error: 'Admins only' });
+      return;
+    }
+    next();
+  };
+
+  // GET /api/admin/connection-keys — every key with its owner, ordered by
+  // owner email then newest-first. Never carries a plaintext or a hash.
+  router.get('/admin/connection-keys', requireAdmin, async (_req, res) => {
+    try {
+      res.json({ keys: await externalApiKeyService.listForDeployment() });
+    } catch (err) {
+      log.error('admin list failed:', { err });
+      res.status(500).json({ error: 'Failed to load connection keys' });
+    }
+  });
+
+  // DELETE /api/admin/connection-keys/:id — revoke (disconnect) a key
+  // belonging to ANY account. Idempotent on an already-revoked key; 404 when
+  // no such key exists. Revoked rows are kept so `last_used_at` stays
+  // auditable after a leak — there is deliberately no admin hard-delete.
+  router.delete('/admin/connection-keys/:id', requireAdmin, async (req, res) => {
+    const id = String(req.params.id);
+    // The id column is a uuid: anything else makes Postgres raise a cast
+    // error before the WHERE is even evaluated, which would surface as a 500.
+    // A malformed id names no key, so it is a not-found, same as an unknown one.
+    if (!UUID_RE.test(id)) {
+      res.status(404).json({ error: 'Token not found' });
+      return;
+    }
+    try {
+      await externalApiKeyService.revokeAny(id);
+      // Accountability record: WHO revoked WHICH key. Ids only — the key's
+      // label is the owner's free text and does not belong in logs.
+      log.info('revoke audit:', { action: 'admin-revoke-key', actorUserId: req.userId, tokenId: id });
+      res.json({ status: 'revoked' });
+    } catch (err) {
+      if (err instanceof TokenNotFoundError) {
+        res.status(404).json({ error: err.message });
+        return;
+      }
+      log.error('admin revoke failed:', { err });
+      res.status(500).json({ error: 'Failed to revoke this key' });
+    }
+  });
+
+  return router;
+}

package/src/modules/tool-auth/external-api-key.interface.ts

@@ -31,8 +31,17 @@ export interface ExternalApiKeySummary {
   createdAt: number;
   lastUsedAt: number | null;
   revokedAt: number | null;
+  /**
+   * Who ended it, once `revokedAt` is set: the owner themselves, or an admin
+   * from the deployment overview. Null while live (and on rows revoked
+   * before this was recorded, which read as the owner's doing).
+   */
+  revokedBy: RevokedBy | null;
 }
 
+/** Who revoked a key: its owner, or an admin acting across the deployment. */
+export type RevokedBy = 'owner' | 'admin';
+
 /**
  * Result of minting a new connection key. `plaintext` is shown to the user
  * once (with a "you won't see this again" warning); the stored DB row only
@@ -43,14 +52,42 @@ export interface MintedExternalApiKey {
   summary: ExternalApiKeySummary;
 }
 
+/**
+ * One row of the admin "Connection keys" overview: a key summary plus the
+ * account it belongs to. Deployment-wide, so unlike {@link ExternalApiKeySummary}
+ * the owner is not implied by the caller.
+ */
+export interface AdminExternalApiKeySummary extends ExternalApiKeySummary {
+  user: {
+    id: string;
+    email: string;
+    name: string;
+  };
+}
+
 /** The kind of a key a person creates by hand. */
 export const DEFAULT_KEY_KIND = 'key';
 
+/**
+ * How the plaintext of one kind of key is spelled: the prefix the outside
+ * world sees (and that routes the bearer back here), and the shape of the
+ * random part after it. `base64url` is the platform's own — 43 characters
+ * from a 32-byte draw. `github-token` is what a GitHub OAuth token looks
+ * like after its `gho_`: letters and digits only, 40 of them, so a consumer
+ * that validates the shape of a GitHub token (they are documented as
+ * alphanumeric) keeps it. Both hash the same way; the shape is only what a
+ * client is shown.
+ */
+export interface KeyKindSpec {
+  prefix: string;
+  shape?: 'base64url' | 'github-token';
+}
+
 /**
  * How a key is minted. `kind` names one of the kinds the service was built
- * with, each of which carries its own plaintext prefix (the tenant's for the
- * default kind, `gho_` for a Claude link); an unknown kind is refused, since
- * nothing would route its bearer back.
+ * with, each of which carries its own spelling (the tenant's prefix for the
+ * default kind, a GitHub-shaped token for a Claude link); an unknown kind is
+ * refused, since nothing would route its bearer back.
  */
 export interface MintOptions {
   kind?: string;
@@ -107,6 +144,22 @@ export interface IExternalApiKeyService {
    */
   revoke(id: string, userId: string): Promise<void>;
 
+  /**
+   * Every token on the deployment, active and revoked, with its owner —
+   * the admin overview. Ordered by owner email, then newest-first, so the
+   * caller can group per account without re-sorting.
+   */
+  listForDeployment(): Promise<AdminExternalApiKeySummary[]>;
+
+  /**
+   * Admin revoke: mark a token revoked WITHOUT scoping by owner, recording
+   * `revokedBy: 'admin'` so the owner's page can say it was taken rather than
+   * disconnected. Same idempotency as {@link revoke}; throws
+   * TokenNotFoundError when no such token exists. Only reachable through an
+   * admin-gated route — the per-user route must keep using {@link revoke}.
+   */
+  revokeAny(id: string): Promise<void>;
+
   /**
    * Permanently delete a token row, dropping its audit trail. Only permitted
    * on an already-revoked token — an active key must be disconnected first,