@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,358 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createHash } from 'node:crypto';
+import { ExternalApiKeyService } from '../external-api-key.service.js';
+import {
+  InvalidTokenLabelError,
+  TokenNotFoundError,
+  TokenStillActiveError,
+} from '../external-api-key.errors.js';
+import type { Database } from '../../database/connection.js';
+import { externalApiKeys } from '../../database/schema.js';
+
+/**
+ * Builds a fake drizzle chain. Every chainable method returns the same
+ * chain object, and the chain itself is thenable — so `await db.x().y().z()`
+ * resolves to whatever the test queued for this operation. Each call to
+ * `db.insert / .select / .update` pops the next result off `queue`.
+ *
+ * We use this instead of a real Postgres because the service is pure
+ * domain logic on top of drizzle; integration coverage of the migration
+ * shape lives with the route tests later.
+ */
+function makeFakeDb(queue: any[]) {
+  const calls: Record<string, any[][]> = {
+    insert: [],
+    select: [],
+    update: [],
+    delete: [],
+    values: [],
+    set: [],
+    where: [],
+    orderBy: [],
+    limit: [],
+    innerJoin: [],
+    from: [],
+    returning: [],
+  };
+
+  function nextChain() {
+    const result = queue.shift();
+    const chain: any = {};
+    const passthrough = (name: string) =>
+      vi.fn((...args: any[]) => {
+        calls[name].push(args);
+        return chain;
+      });
+    chain.values = passthrough('values');
+    chain.set = passthrough('set');
+    chain.where = passthrough('where');
+    chain.orderBy = passthrough('orderBy');
+    chain.limit = passthrough('limit');
+    chain.innerJoin = passthrough('innerJoin');
+    chain.from = passthrough('from');
+    chain.returning = passthrough('returning');
+    chain.then = (onF: any, onR: any) =>
+      Promise.resolve(result).then(onF, onR);
+    return chain;
+  }
+
+  const db = {
+    insert: vi.fn((...args: any[]) => {
+      calls.insert.push(args);
+      return nextChain();
+    }),
+    select: vi.fn((...args: any[]) => {
+      calls.select.push(args);
+      return nextChain();
+    }),
+    update: vi.fn((...args: any[]) => {
+      calls.update.push(args);
+      return nextChain();
+    }),
+    delete: vi.fn((...args: any[]) => {
+      calls.delete.push(args);
+      return nextChain();
+    }),
+    // Transactions run the callback against the same fake db, so queued
+    // results are consumed in order just like a non-transactional call.
+    transaction: vi.fn((fn: (tx: any) => Promise<unknown>) => fn(db)),
+  } as unknown as Database;
+
+  return { db, calls };
+}
+
+function makeRow(overrides: Partial<{
+  id: string;
+  userId: string;
+  tokenHash: string;
+  label: string;
+  createdAt: Date;
+  lastUsedAt: Date | null;
+  revokedAt: Date | null;
+}> = {}) {
+  return {
+    id: overrides.id ?? 'tok-1',
+    userId: overrides.userId ?? 'user-1',
+    tokenHash: overrides.tokenHash ?? 'hash-1',
+    label: overrides.label ?? 'My laptop',
+    createdAt: overrides.createdAt ?? new Date('2026-01-01T00:00:00Z'),
+    lastUsedAt: overrides.lastUsedAt ?? null,
+    revokedAt: overrides.revokedAt ?? null,
+  };
+}
+
+function sha256Hex(s: string): string {
+  return createHash('sha256').update(s).digest('hex');
+}
+
+// Flush queued microtasks so a fire-and-forget `.catch(...)` runs before
+// we assert. The service intentionally does not await its touchLastUsed
+// call, so the rejection handler runs in a later microtask.
+const flushMicrotasks = () => new Promise<void>((r) => setImmediate(r));
+
+describe('ExternalApiKeyService', () => {
+  describe('mint', () => {
+    it('generates a bevel_-prefixed token, persists its sha256 hash (never the plaintext), and returns both', async () => {
+      const row = makeRow({ id: 'tok-42', label: 'My laptop' });
+      const { db, calls } = makeFakeDb([[row]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      const result = await service.mint('user-1', 'My laptop');
+
+      expect(result.plaintext.startsWith('bevel_')).toBe(true);
+      // 32 random bytes base64url-encoded => 43 chars after the prefix.
+      expect(result.plaintext.length).toBe('bevel_'.length + 43);
+
+      const inserted = calls.values[0][0];
+      expect(inserted.userId).toBe('user-1');
+      expect(inserted.label).toBe('My laptop');
+      expect(inserted.tokenHash).toBe(sha256Hex(result.plaintext));
+      // The plaintext must never land in the DB row.
+      expect(inserted.tokenHash).not.toBe(result.plaintext);
+      expect(inserted).not.toHaveProperty('plaintext');
+
+      expect(result.summary).toEqual({
+        id: 'tok-42',
+        label: 'My laptop',
+        createdAt: row.createdAt.getTime(),
+        lastUsedAt: null,
+        revokedAt: null,
+      });
+    });
+
+    it('trims the label before persisting', async () => {
+      const { db, calls } = makeFakeDb([[makeRow()]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await service.mint('user-1', '   spacey   ');
+
+      expect(calls.values[0][0].label).toBe('spacey');
+    });
+
+    it('rejects empty/whitespace labels without touching the DB', async () => {
+      const { db } = makeFakeDb([]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await expect(service.mint('user-1', '')).rejects.toBeInstanceOf(
+        InvalidTokenLabelError,
+      );
+      await expect(service.mint('user-1', '   \n\t  ')).rejects.toBeInstanceOf(
+        InvalidTokenLabelError,
+      );
+      expect((db as any).insert).not.toHaveBeenCalled();
+    });
+
+    it('rejects oversized labels (>200 chars) without touching the DB', async () => {
+      const { db } = makeFakeDb([]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await expect(
+        service.mint('user-1', 'a'.repeat(201)),
+      ).rejects.toBeInstanceOf(InvalidTokenLabelError);
+      expect((db as any).insert).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('verifyAndLoadUser', () => {
+    it('returns the owning user when the token hash matches an un-revoked row', async () => {
+      const row = {
+        tokenId: 'tok-1',
+        userId: 'user-7',
+        email: 'alice@example.com',
+        name: 'Alice',
+        avatarUrl: null,
+      };
+      // Two queued ops: the SELECT for verify, then the UPDATE for the
+      // fire-and-forget last_used_at touch.
+      const { db } = makeFakeDb([[row], undefined]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      const user = await service.verifyAndLoadUser('bevel_abc123');
+
+      expect(user).toEqual({
+        id: 'user-7',
+        email: 'alice@example.com',
+        name: 'Alice',
+        avatarUrl: undefined,
+      });
+    });
+
+    it('returns null for tokens not carrying the `bevel_` prefix without hitting the DB', async () => {
+      const { db } = makeFakeDb([]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      expect(await service.verifyAndLoadUser('eyJhbGciOiJIUzI1NiJ9')).toBeNull();
+      expect(await service.verifyAndLoadUser('')).toBeNull();
+      expect(await service.verifyAndLoadUser(null as any)).toBeNull();
+      expect((db as any).select).not.toHaveBeenCalled();
+    });
+
+    it('returns null when no matching un-revoked row exists', async () => {
+      const { db } = makeFakeDb([[]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      expect(await service.verifyAndLoadUser('bevel_unknown')).toBeNull();
+    });
+
+    it('still resolves with the user even when the last_used_at update fails (fire-and-forget)', async () => {
+      const row = {
+        tokenId: 'tok-1',
+        userId: 'user-7',
+        email: 'alice@example.com',
+        name: 'Alice',
+        avatarUrl: null,
+      };
+      // Queue: SELECT returns the row; UPDATE rejects.
+      const queue: any[] = [[row]];
+      const { db } = makeFakeDb(queue);
+      // Replace the update chain with one that rejects on await, so the
+      // service's fire-and-forget `.catch` handler runs.
+      (db as any).update = vi.fn(() => {
+        const chain: any = {};
+        chain.set = vi.fn().mockReturnValue(chain);
+        chain.where = vi.fn().mockReturnValue(chain);
+        chain.then = (_onF: any, onR: any) =>
+          Promise.resolve().then(() => onR(new Error('connection lost')));
+        return chain;
+      });
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const service = new ExternalApiKeyService(db, 'bevel_');
+      const user = await service.verifyAndLoadUser('bevel_abc');
+
+      expect(user?.id).toBe('user-7');
+      await flushMicrotasks();
+      expect(warn).toHaveBeenCalled();
+      warn.mockRestore();
+    });
+  });
+
+  describe('listForUser', () => {
+    it('maps DB rows to summaries, newest-first via desc(createdAt)', async () => {
+      const rows = [
+        makeRow({
+          id: 'a',
+          createdAt: new Date('2026-03-01T00:00:00Z'),
+          lastUsedAt: new Date('2026-03-02T00:00:00Z'),
+        }),
+        makeRow({
+          id: 'b',
+          revokedAt: new Date('2026-02-15T00:00:00Z'),
+        }),
+      ];
+      const { db, calls } = makeFakeDb([rows]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      const summaries = await service.listForUser('user-1');
+
+      expect(summaries).toHaveLength(2);
+      expect(summaries[0]).toEqual({
+        id: 'a',
+        label: rows[0].label,
+        createdAt: rows[0].createdAt.getTime(),
+        lastUsedAt: rows[0].lastUsedAt!.getTime(),
+        revokedAt: null,
+      });
+      expect(summaries[1].revokedAt).toBe(rows[1].revokedAt!.getTime());
+      // sanity-check that ordering was requested (we can't introspect the
+      // SQL fragment here, but we can confirm the call shape).
+      expect(calls.orderBy).toHaveLength(1);
+    });
+  });
+
+  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.
+      const { db, calls } = makeFakeDb([[{ id: 'tok-1' }]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await service.revoke('tok-1', 'user-1');
+
+      const setArgs = calls.set[0][0];
+      expect(setArgs.revokedAt).toBeInstanceOf(Date);
+      // No follow-up SELECT — the UPDATE found a row.
+      expect((db as any).select).not.toHaveBeenCalled();
+    });
+
+    it('is idempotent on already-revoked tokens: returns silently without throwing', async () => {
+      // UPDATE matches 0 rows (because `isNull(revokedAt)` filtered it out),
+      // then SELECT confirms the row exists for this user → idempotent path.
+      const { db } = makeFakeDb([[], [{ id: 'tok-1' }]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await expect(service.revoke('tok-1', 'user-1')).resolves.toBeUndefined();
+    });
+
+    it('throws TokenNotFoundError when the token does not exist or belongs to another user', async () => {
+      // UPDATE matches 0 rows, follow-up SELECT also returns empty.
+      const { db } = makeFakeDb([[], []]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await expect(service.revoke('tok-x', 'user-1')).rejects.toBeInstanceOf(
+        TokenNotFoundError,
+      );
+    });
+  });
+
+  describe('remove', () => {
+    it('validates then deletes the key (dependents cascade at the DB layer)', async () => {
+      // Queue: SELECT finds a revoked row; then the key delete consumes one.
+      const { db } = makeFakeDb([
+        [{ revokedAt: new Date('2026-02-01T00:00:00Z') }],
+        undefined,
+      ]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await service.remove('tok-1', 'user-1');
+
+      // Validation SELECT first, then ONE delete of the key row. Dependent
+      // rows (e.g. llm_usage metering) are removed by ON DELETE CASCADE —
+      // this service must not know those tables exist.
+      expect((db as any).select).toHaveBeenCalledTimes(1);
+      expect((db as any).delete).toHaveBeenCalledTimes(1);
+      expect((db as any).delete).toHaveBeenCalledWith(externalApiKeys);
+    });
+
+    it('throws TokenStillActiveError when the token exists but was never disconnected', async () => {
+      // SELECT finds the row with a null revokedAt → still active; no delete.
+      const { db } = makeFakeDb([[{ revokedAt: null }]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await expect(service.remove('tok-1', 'user-1')).rejects.toBeInstanceOf(
+        TokenStillActiveError,
+      );
+      expect((db as any).delete).not.toHaveBeenCalled();
+    });
+
+    it('throws TokenNotFoundError when the token does not exist or belongs to another user', async () => {
+      // SELECT returns empty → not found; no delete.
+      const { db } = makeFakeDb([[]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+
+      await expect(service.remove('tok-x', 'user-1')).rejects.toBeInstanceOf(
+        TokenNotFoundError,
+      );
+      expect((db as any).delete).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/modules/tool-auth/__tests__/internal-token.service.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { InternalTokenService } from '../internal-token.service.js';
+import { createTokenVerifier } from '../tool-auth.middleware.js';
+import type { IExternalApiKeyService } from '../external-api-key.interface.js';
+
+const claim = { userId: 'user-A' };
+
+describe('InternalTokenService', () => {
+  it('mints a token that verifies back to the same claim', () => {
+    const svc = new InternalTokenService({ secret: 'test-secret' });
+    const token = svc.mint(claim);
+    expect(svc.looksLikeInternalToken(token)).toBe(true);
+    expect(svc.verify(token)).toEqual(claim);
+  });
+
+  it('round-trips the externalProxy flag (the MCP proxy loopback identity)', () => {
+    const svc = new InternalTokenService({ secret: 'test-secret' });
+    const token = svc.mint({ userId: 'user-A', externalProxy: true });
+    expect(svc.verify(token)).toEqual({ userId: 'user-A', externalProxy: true });
+  });
+
+  it('rejects a tampered token', () => {
+    const svc = new InternalTokenService({ secret: 'test-secret' });
+    const token = svc.mint(claim);
+    expect(svc.verify(token + 'x')).toBeNull();
+    expect(svc.verify(token.replace(/.$/, (c) => (c === 'a' ? 'b' : 'a')))).toBeNull();
+  });
+
+  it('rejects a token signed with a different secret', () => {
+    const a = new InternalTokenService({ secret: 'secret-a' });
+    const b = new InternalTokenService({ secret: 'secret-b' });
+    expect(b.verify(a.mint(claim))).toBeNull();
+  });
+
+  it('rejects an expired token', () => {
+    let now = 1_000_000;
+    const svc = new InternalTokenService({ secret: 's', ttlMs: 1000, now: () => now });
+    const token = svc.mint(claim);
+    now += 1500;
+    expect(svc.verify(token)).toBeNull();
+  });
+
+  it('rejects a connection-key-shaped bearer', () => {
+    const svc = new InternalTokenService({ secret: 's' });
+    expect(svc.verify('bevel_abc123')).toBeNull();
+    expect(svc.looksLikeInternalToken('bevel_abc123')).toBe(false);
+  });
+});
+
+describe('createTokenVerifier — internal-token source resolution', () => {
+  const noExternalKeys = {
+    looksLikeExternalApiKey: () => false,
+    verifyAndLoadToken: async () => null,
+  } as unknown as IExternalApiKeyService;
+
+  it('a plain per-run internal token resolves to source internal with its sessionId', async () => {
+    const svc = new InternalTokenService({ secret: 's' });
+    const verify = createTokenVerifier(noExternalKeys, svc);
+    const result = await verify(svc.mint({ userId: 'user-A', sessionId: 'run-1' }));
+    expect(result).toEqual({
+      ok: true,
+      auth: { source: 'internal', userId: 'user-A', sessionId: 'run-1', scope: 'write' },
+    });
+  });
+
+  it('an externalProxy token resolves to source EXTERNAL — the caller is an external agent', async () => {
+    // The MCP proxy mints this as the loopback identity of an OAuth/JWT MCP
+    // session. Resolving it internal used to deadlock those sessions: the
+    // external-only `start_session` refused them, and every session-gated
+    // tool demands the sessionId they then couldn't mint.
+    const svc = new InternalTokenService({ secret: 's' });
+    const verify = createTokenVerifier(noExternalKeys, svc);
+    const result = await verify(svc.mint({ userId: 'user-A', externalProxy: true }));
+    expect(result).toEqual({
+      ok: true,
+      auth: { source: 'external', userId: 'user-A', scope: 'write' },
+    });
+  });
+});

package/src/modules/tool-auth/__tests__/manual-auth.middleware.test.ts

@@ -0,0 +1,88 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { toolDef } from '../../tool-helpers/tool-def.js';
+import { createManualRoutes } from '../../tool-registry/manual.routes.js';
+import { InternalTokenService } from '../internal-token.service.js';
+import { createManualAuthMiddleware } from '../tool-auth.middleware.js';
+import type { IExternalApiKeyService } from '../external-api-key.interface.js';
+import type { AuthService } from '../../auth/auth.service.js';
+
+/**
+ * The manual endpoints (`/agent/utcp`, `/agent/internal/utcp`) accept a browser
+ * JWT in ADDITION to a connection key / internal token, so a logged-in user can
+ * browse the catalog with their session — but the internal catalog stays
+ * `requireInternalSource`-gated, and a JWT never reaches an execution route.
+ */
+const KEY = 'bevel_validkey';
+const JWT = 'browser-jwt';
+
+const fakeExternalApiKeys = {
+  looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
+  verifyAndLoadToken: async (t: string) =>
+    t === KEY ? { user: { id: 'u-key' }, tokenId: 'tok-1' } : null,
+} as unknown as IExternalApiKeyService;
+
+const fakeAuth = {
+  verifyToken: (t: string) => {
+    if (t === JWT) return { userId: 'u-jwt', email: 'jwt@x' };
+    throw new Error('bad jwt');
+  },
+} as unknown as AuthService;
+
+let server: HttpServer | undefined;
+afterEach(async () => {
+  if (server) await new Promise<void>((r) => server!.close(() => r()));
+  server = undefined;
+});
+
+async function start() {
+  const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+  const registry = new ToolRegistry();
+  registry.registerExternalTool(toolDef({ name: 'pub', description: 'd', path: '/api/agent/tools/pub', inputs: { type: 'object', properties: {} } }));
+  registry.registerInternalTool(toolDef({ name: 'sec', description: 'd', path: '/api/agent/tools/sec', inputs: { type: 'object', properties: {} } }));
+  const manualAuth = createManualAuthMiddleware(fakeExternalApiKeys, internalTokens, fakeAuth);
+  const app = express();
+  app.use('/api', createManualRoutes(registry, manualAuth));
+  server = await new Promise<HttpServer>((res) => {
+    const s = app.listen(0, () => res(s));
+  });
+  const port = (server.address() as { port: number }).port;
+  return { base: `http://127.0.0.1:${port}`, intToken: internalTokens.mint({ userId: 'u-int' }) };
+}
+
+const get = (base: string, path: string, bearer?: string) =>
+  fetch(`${base}${path}`, bearer ? { headers: { Authorization: `Bearer ${bearer}` } } : undefined);
+
+describe('createManualAuthMiddleware (read-only manual endpoints)', () => {
+  it('serves the external manual to a browser JWT', async () => {
+    const { base } = await start();
+    const r = await get(base, '/api/agent/utcp', JWT);
+    expect(r.status).toBe(200);
+    const m = (await r.json()) as { tools: { name: string }[] };
+    expect(m.tools.map((t) => t.name)).toContain('pub');
+  });
+
+  it('serves the external manual to a connection key', async () => {
+    const { base } = await start();
+    expect((await get(base, '/api/agent/utcp', KEY)).status).toBe(200);
+  });
+
+  it('401s a missing or unrecognised bearer', async () => {
+    const { base } = await start();
+    expect((await get(base, '/api/agent/utcp')).status).toBe(401);
+    expect((await get(base, '/api/agent/utcp', 'garbage')).status).toBe(401);
+  });
+
+  it('refuses the INTERNAL manual to a browser JWT (403) but allows an internal token', async () => {
+    const { base, intToken } = await start();
+    expect((await get(base, '/api/agent/internal/utcp', JWT)).status).toBe(403);
+    expect((await get(base, '/api/agent/internal/utcp', intToken)).status).toBe(200);
+  });
+
+  it('refuses the INTERNAL manual to a connection key (403)', async () => {
+    const { base } = await start();
+    expect((await get(base, '/api/agent/internal/utcp', KEY)).status).toBe(403);
+  });
+});

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

@@ -0,0 +1,25 @@
+/**
+ * Domain errors for the API token service. Distinct classes so callers can
+ * map each to an HTTP status and a user-facing message without string-matching.
+ */
+
+export class InvalidTokenLabelError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidTokenLabelError';
+  }
+}
+
+export class TokenNotFoundError extends Error {
+  constructor(message = 'Token not found') {
+    super(message);
+    this.name = 'TokenNotFoundError';
+  }
+}
+
+export class TokenStillActiveError extends Error {
+  constructor(message = 'Disconnect this key before deleting it') {
+    super(message);
+    this.name = 'TokenStillActiveError';
+  }
+}

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

@@ -0,0 +1,99 @@
+import type { AuthUser } from '@bevel-software/platform-shared';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      /**
+       * Connection-key id bound by whichever auth middleware resolved a
+       * `<tenant>_…` key (MCP auth, LLM-proxy auth) — consumers use it for
+       * per-key attribution/metering. Declared beside the key contract so
+       * every key-resolving surface shares one augmentation.
+       */
+      externalApiKeyId?: string;
+    }
+  }
+}
+
+/**
+ * Summary row shown in the user's "Connection keys" settings panel. Never
+ * carries the plaintext — that is returned exactly once from `mint`.
+ */
+export interface ExternalApiKeySummary {
+  id: string;
+  label: string;
+  createdAt: number;
+  lastUsedAt: number | null;
+  revokedAt: number | null;
+}
+
+/**
+ * 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
+ * carries the hash.
+ */
+export interface MintedExternalApiKey {
+  plaintext: string;
+  summary: ExternalApiKeySummary;
+}
+
+/**
+ * Contract for connection-key (API token) lifecycle. Used by the MCP auth
+ * middleware to resolve a Bearer token to a Bevel user, and by the settings
+ * UI to mint, list, and revoke keys.
+ *
+ * Verification is a hash lookup on a unique index, so it stays O(1) even
+ * with many tokens per user. Revoked tokens are kept (not deleted) so an
+ * operator can audit `last_used_at` after a leak.
+ */
+export interface IExternalApiKeyService {
+  /**
+   * True if a bearer string carries this tenant's external-API-key prefix
+   * (`<tenant>_…`). Lets auth middlewares route a key vs a JWT / internal token
+   * without a DB round-trip, using the tenant prefix the service was built with.
+   */
+  looksLikeExternalApiKey(token: string): boolean;
+
+  /**
+   * Generate a new token, persist its hash, and return the plaintext. The
+   * plaintext is **only** returned here — there is no read path that can
+   * surface it again.
+   */
+  mint(userId: string, label: string): Promise<MintedExternalApiKey>;
+
+  /**
+   * Resolve a plaintext token to the owning user. Returns null when the
+   * token is unknown, revoked, or malformed. Bumps `last_used_at`
+   * fire-and-forget — verification latency stays bounded by the hash
+   * lookup, not the update.
+   */
+  verifyAndLoadUser(plaintext: string): Promise<AuthUser | null>;
+
+  /**
+   * Like `verifyAndLoadUser`, but also returns the matching token's id. The
+   * LLM proxy needs the token id (not just the user) to meter per-key usage
+   * against the daily cap. Returns null on unknown/revoked/malformed tokens.
+   */
+  verifyAndLoadToken(
+    plaintext: string,
+  ): Promise<{ tokenId: string; user: AuthUser } | null>;
+
+  /** Active + revoked tokens for the user, newest-first. */
+  listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
+
+  /**
+   * Mark a token revoked. Idempotent — revoking an already-revoked token
+   * is a no-op (the row's `revokedAt` is not overwritten). Throws
+   * TokenNotFoundError if the token doesn't belong to the user.
+   */
+  revoke(id: string, userId: 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,
+   * so a live agent's access is never yanked by a single click. Throws
+   * TokenNotFoundError if the token doesn't belong to the user, and
+   * TokenStillActiveError if it hasn't been revoked yet.
+   */
+  remove(id: string, userId: string): Promise<void>;
+}