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

package/src/modules/audit/request-audit.ts

@@ -0,0 +1,141 @@
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import { logger } from '../../shared/logging.js';
+import type { AgentEventOutcome, AuditPrincipalRef, IAgentEventRecorder } from './audit.contract.js';
+import {
+  classifyToolCall,
+  skillReadPath,
+  type ClassifiedCall,
+  type ClassifierContext,
+  type SkillFolder,
+} from './event-classifier.js';
+
+const log = logger('audit');
+
+/**
+ * The Audit log's view of ONE MCP request: who is calling (the user and the
+ * key or agent connection the request arrived through), and how to name what
+ * they call. The MCP proxy creates one per request that has a principal and
+ * routes every call through it; a request with none (a browser JWT, an
+ * internal token minted before connections existed) gets no instance and
+ * records nothing.
+ *
+ * Holds nothing that outlives the request. The skill catalog it may need to
+ * tell a skill read from a file read is fetched at most once, and only when
+ * a platform read names a path.
+ */
+export class RequestAudit {
+  private skills: Promise<readonly SkillFolder[] | null> | undefined;
+
+  constructor(
+    private readonly recorder: IAgentEventRecorder,
+    private readonly userId: string,
+    private readonly principal: AuditPrincipalRef,
+    private readonly ctx: {
+      kbManualName: string;
+      /** Read at classification time — the surface (and its catalog names) is built lazily. */
+      catalogNames: () => ReadonlyMap<string, string>;
+      /** The caller's skill catalog, for telling a skill read from a file read. */
+      loadSkills: () => Promise<readonly SkillFolder[]>;
+    },
+  ) {}
+
+  /** Record one already-classified call. Never throws. */
+  emit(call: ClassifiedCall, outcome: AgentEventOutcome, durationMs: number | null): void {
+    try {
+      this.recorder.record({
+        userId: this.userId,
+        principal: this.principal,
+        kind: call.kind,
+        manual: call.manual,
+        name: call.name,
+        outcome,
+        durationMs,
+      });
+    } catch (err) {
+      log.warn('recording an agent event failed:', { err });
+    }
+  }
+
+  /** What a UTCP call is logged as — fetching the skill catalog first when the call might be a skill read. */
+  async classify(utcpName: string, args: Record<string, unknown>): Promise<ClassifiedCall> {
+    const ctx: ClassifierContext = { kbManualName: this.ctx.kbManualName, catalogNames: this.ctx.catalogNames() };
+    const wantsSkills = skillReadPath(utcpName, args, ctx.kbManualName) !== null;
+    const skills = wantsSkills ? await this.skillCatalog() : null;
+    return classifyToolCall(utcpName, args, ctx, skills);
+  }
+
+  /**
+   * Run a UTCP call and record it: `error` when it throws or `isError` says
+   * the result is one, `ok` otherwise. The result (or the throw) reaches the
+   * caller unchanged — recording is a side effect, never a filter.
+   *
+   * The call starts FIRST and is classified alongside: naming a read may cost
+   * a loopback fetch of the skill catalog, and that is the log's business,
+   * not the tool's — a tool result never waits on its own bookkeeping.
+   */
+  async call<T>(
+    utcpName: string,
+    args: Record<string, unknown>,
+    run: () => Promise<T>,
+    isError: (result: T) => boolean,
+  ): Promise<T> {
+    const started = performance.now();
+    const classified = this.classify(utcpName, args);
+    try {
+      const result = await run();
+      const duration = elapsed(started);
+      this.emit(await classified, isError(result) ? 'error' : 'ok', duration);
+      return result;
+    } catch (err) {
+      const duration = elapsed(started);
+      this.emit(await classified, 'error', duration);
+      throw err;
+    }
+  }
+
+  /** A call refused before it ran, because the caller's sign-in for its manual is missing. */
+  async denied(utcpName: string, args: Record<string, unknown>): Promise<void> {
+    this.emit(await this.classify(utcpName, args), 'denied', null);
+  }
+
+  /**
+   * Record every tool call made from INSIDE `call_tool_chain`: the chain
+   * bridges each in-isolate tool function to `client.callTool`, so wrapping
+   * that one entry point catches them all. Installed after the downstream
+   * routing wrapper so the timing covers the pool lease and any retry too.
+   * The direct MCP path (`callToolStreaming`) is deliberately NOT wrapped —
+   * the proxy's tool handler records those itself, with the result's
+   * `isError` in hand.
+   */
+  instrumentChainCalls(client: CodeModeUtcpClient): void {
+    const callTool = client.callTool.bind(client);
+    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) =>
+      this.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped);
+  }
+
+  private skillCatalog(): Promise<readonly SkillFolder[] | null> {
+    // A failed fetch is remembered as "no catalog" for the rest of the
+    // request: the read is then logged as a capability, and one hiccup does
+    // not cost a loopback round-trip per subsequent call.
+    this.skills ??= this.ctx.loadSkills().catch((err) => {
+      log.warn('skill catalog unavailable for audit classification:', { err });
+      return null;
+    });
+    return this.skills;
+  }
+}
+
+function elapsed(started: number): number {
+  return Math.max(0, Math.round(performance.now() - started));
+}
+
+/**
+ * A chain-internal result that is the tool saying it failed. A downstream
+ * MCP server answers a failed call with `{ isError: true, content }` as a
+ * VALUE (the UTCP mcp protocol hands it through rather than throwing), and
+ * the direct path records that as an error — so must the chain path, or the
+ * same failure would read `ok` inside a chain and `error` outside one.
+ */
+function isErrorShaped(result: unknown): boolean {
+  return typeof result === 'object' && result !== null && (result as { isError?: unknown }).isError === true;
+}

package/src/modules/database/core-schema.ts

@@ -211,6 +211,16 @@ export const externalApiKeys = pgTable('api_tokens', {
    * reconnect a key that was taken from them.
    */
   revokedBy: text('revoked_by'),
+  /**
+   * When the owner deleted the key "for good" from their own pages. A
+   * DELETE in name only: the row stays, because the Audit log's events hang
+   * off it and a log its subject can erase is not one. Hidden from the
+   * owner's listings, shown to admins as deleted; gone for real only when
+   * the account is erased (the cascade) or its events have long been
+   * pruned. Always set on an already-revoked row — a live key is never
+   * deleted in one step.
+   */
+  deletedAt: timestamp('deleted_at'),
 }, (t) => ({
   byUser: index('api_tokens_by_user').on(t.userId),
 }));
@@ -446,12 +456,58 @@ export const oauthAuthCodes = pgTable('oauth_auth_codes', {
   byExpiry: index('oauth_auth_codes_by_expiry').on(t.expiresAt),
 }));
 
+/**
+ * "This person connected this agent" — the durable record behind the Audit
+ * log's agent rows. An OAuth grant cannot be that record: its token row is
+ * replaced on every refresh (hourly) and pruned once its refresh window
+ * closes, so nothing about it outlives a month. This row is made the first
+ * time a token is minted for a (user, client) pair, kept across every refresh
+ * (each new token row points at it), and REVOKED rather than deleted when the
+ * person or an admin cuts the agent off — its events stay readable under it.
+ *
+ * A connection is the AGENT, per person — not the OAuth client registration.
+ * Claude registers a fresh client on every re-authorisation (dynamic client
+ * registration mints a new id each time), so keying by registration gave one
+ * person five "Claude" rows for one agent. `agent_key` is what a connection is
+ * keyed by instead: the registered client name, folded (a name-less client
+ * falls back to its id), so every registration of "Claude" by one person
+ * lands on the same live row; `client_id` records the registration that
+ * first made it. `client_name` is that registration's name as shown.
+ *
+ * One LIVE connection per (user, agent): the partial unique index below. A
+ * reconnect after a revoke is a new row, so the old one's history and its
+ * "revoked by an admin" mark are never overwritten.
+ */
+export const agentConnections = pgTable('agent_connections', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  clientId: text('client_id').notNull().references(() => oauthClients.clientId),
+  clientName: text('client_name'),
+  /** The folded client name, or the client id when the registration carried none. */
+  agentKey: text('agent_key').notNull(),
+  connectedAt: timestamp('connected_at').defaultNow().notNull(),
+  lastUsedAt: timestamp('last_used_at'),
+  revokedAt: timestamp('revoked_at'),
+  /** `owner` | `admin` — who ended it; null while live. Same vocabulary as `api_tokens.revoked_by`. */
+  revokedBy: text('revoked_by'),
+}, (t) => ({
+  byUser: index('agent_connections_by_user').on(t.userId),
+  liveUnq: uniqueIndex('agent_connections_live_unq')
+    .on(t.userId, t.agentKey)
+    .where(sql`${t.revokedAt} is null`),
+}));
+
 /**
  * OAuth access/refresh token pairs minted by the token endpoint. Like
  * `api_tokens`: plaintext shown only in the token response, SHA-256 hashes
  * stored, revoked-not-deleted so `last_used_at` keeps its audit value and a
  * revoked token can't be re-issued. One row per pair; refresh rotation
  * revokes the old row and inserts a new one.
+ *
+ * `connection_id` names the {@link agentConnections} row the pair belongs to,
+ * so every call made with the token is attributed to that agent and revoking
+ * the agent can revoke exactly its tokens. Null only on rows minted before
+ * the column existed.
  */
 export const oauthTokens = pgTable('oauth_tokens', {
   id: uuid('id').defaultRandom().primaryKey(),
@@ -459,6 +515,7 @@ export const oauthTokens = pgTable('oauth_tokens', {
   refreshTokenHash: text('refresh_token_hash').unique(),
   clientId: text('client_id').notNull().references(() => oauthClients.clientId),
   userId: uuid('user_id').notNull().references(() => users.id),
+  connectionId: uuid('connection_id').references(() => agentConnections.id, { onDelete: 'cascade' }),
   scope: text('scope'),
   resource: text('resource'),
   expiresAt: timestamp('expires_at').notNull(),
@@ -469,6 +526,53 @@ export const oauthTokens = pgTable('oauth_tokens', {
 }, (t) => ({
   byUser: index('oauth_tokens_by_user').on(t.userId),
   byExpiry: index('oauth_tokens_by_expiry').on(t.expiresAt),
+  byConnection: index('oauth_tokens_by_connection').on(t.connectionId),
+}));
+
+/**
+ * The Audit log's events: one row per thing an external agent called through
+ * the platform — a hexis capability (the platform's own tools, `read_file`,
+ * `call_tool_chain`, …), a tool from a `.tool` manual or a connected MCP
+ * server, or a skill it read. Append-only; pruned past the deployment's
+ * retention window (the `auditRetentionDays` setting).
+ *
+ * Deliberately WITHOUT arguments or results: a call's inputs can carry
+ * secrets and personal data, and the log's question is "what was used, by
+ * which agent, when" — not "what was said".
+ *
+ * Exactly one principal per row (the CHECK): the connection key or the agent
+ * connection the call arrived through. Both cascade, so deleting a key for
+ * good, revoking-then-erasing a person, or dropping a connection takes its
+ * events along — the same contract the LLM-usage rows already keep.
+ */
+export const agentEvents = pgTable('agent_events', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  keyId: uuid('key_id').references(() => externalApiKeys.id, { onDelete: 'cascade' }),
+  connectionId: uuid('connection_id').references(() => agentConnections.id, { onDelete: 'cascade' }),
+  /** `capability` | `tool` | `skill`. */
+  kind: text('kind').notNull(),
+  /** The MCP server / `.tool` manual (catalog name) for a tool, the skill folder for a skill; null for a capability. */
+  manual: text('manual'),
+  /** The tool's bare name, or the skill's name. */
+  name: text('name').notNull(),
+  /** `ok` | `error` | `denied` (denied: the caller's sign-in for the tool was missing, so nothing ran). */
+  outcome: text('outcome').notNull(),
+  durationMs: integer('duration_ms'),
+  at: timestamp('at').defaultNow().notNull(),
+}, (t) => ({
+  // The two read paths: one principal's events, newest first.
+  byKey: index('agent_events_by_key').on(t.keyId, t.at),
+  byConnection: index('agent_events_by_connection').on(t.connectionId, t.at),
+  // The retention prune, and per-user counts.
+  byAt: index('agent_events_by_at').on(t.at),
+  byUser: index('agent_events_by_user').on(t.userId),
+  kindCheck: check('agent_events_kind', sql`${t.kind} IN ('capability', 'tool', 'skill')`),
+  outcomeCheck: check('agent_events_outcome', sql`${t.outcome} IN ('ok', 'error', 'denied')`),
+  principalCheck: check(
+    'agent_events_principal',
+    sql`(${t.keyId} IS NULL) <> (${t.connectionId} IS NULL)`,
+  ),
 }));
 
 export const sessionOntologyTouches = pgTable('session_ontology_touches', {

package/src/modules/diff/diff.service.ts

@@ -350,7 +350,12 @@ export class DiffService implements IDiffService {
     // reject, the ledger sync — so the git folder is refused for all of them
     // in one place, links into it included. FIRST, so a path into the folder
     // gets the one sanitized refusal rather than a containment error.
-    await assertNotGitInternals(workspaceDir, relativePath, fileAbs);
+    //
+    // The caller's SPELLING is what is judged, not `fileAbs`: `path.resolve`
+    // reads a backslash as an ordinary character and carries a leading climb
+    // out of the workspace, so a link reached either way resolved to nothing
+    // here and passed. The check reads every way the spelling could land.
+    await assertNotGitInternals(workspaceDir, relativePath);
     assertWithinDirectory(fileAbs, workspaceDir);
     assertWithinDirectory(backupAbs, backupDir);
     return { workspaceDir, backupDir, fileAbs, backupAbs };

package/src/modules/kb-fs/git-guarded-filesystem.ts

@@ -24,10 +24,23 @@ import { assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-
  * the floor under them, for whatever reaches the filesystem another way.
  */
 export class GitGuardedFilesystem extends LocalFilesystem {
-  /** Refuse `inputPath` when it names the git folder or resolves into it. */
+  /**
+   * Refuse `inputPath` when it names the git folder or resolves into it.
+   *
+   * The caller's SPELLING is judged first, every way it could land: this
+   * filesystem's own resolver reads a backslash as an ordinary character and
+   * carries a leading climb out of the workspace, so a link reached either way
+   * used to resolve to nothing and pass. Where this filesystem would actually
+   * put the path is then judged too, when that is somewhere else again.
+   */
   async assertNotGitInternals(inputPath: string): Promise<void> {
-    const absolutePath = this.resolveAbsolutePath(inputPath) ?? path.resolve(this.basePath, inputPath.replace(/^[\\/]+/, ''));
-    await assertNotGitInternals(this.basePath, inputPath, absolutePath);
+    // ONE call carrying both the spelling and the place this filesystem
+    // would put it. Both are still judged — a link this resolver cannot
+    // place (a backslash-spelled one, a leading climb) is caught by the
+    // spelling's own readings, a link it follows by the place — but the rule
+    // walks the root once and probes a place both name once, where two calls
+    // walked the root twice and probed that place twice.
+    await assertNotGitInternals(this.basePath, inputPath, this.resolveAbsolutePath(inputPath));
   }
 
   override async readFile(inputPath: string, options?: ReadOptions): Promise<string | Buffer> {

package/src/modules/mcp/__tests__/bevel-oauth-provider.test.ts

@@ -2,9 +2,12 @@ import { describe, expect, it, vi } from 'vitest';
 import { createHash } from 'node:crypto';
 import { InvalidGrantError, InvalidScopeError, InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type { OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth.js';
-import { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import { BevelOAuthProvider, agentKeyFor } from '../oauth/bevel-oauth-provider.js';
 import { signAuthRequest, verifyAuthRequest } from '../oauth/oauth-state.js';
 import type { Database } from '../../database/connection.js';
+import { agentConnections, oauthTokens } from '../../database/schema.js';
 
 const STATE_SECRET = 'test-state-secret';
 const PREFIX = 'bevel-mcp_';
@@ -12,9 +15,19 @@ const FRONTEND = 'https://app.example.com';
 
 /** Same fake drizzle chain as external-api-key.service.test.ts: every
  * chainable method returns the chain, the chain is thenable, and each
- * db.insert/select/update pops the next queued result. */
+ * db.insert/select/update pops the next queued result. What the provider
+ * WRITES and WHERE it writes it are captured too — `set`, `values`, the
+ * `update` target and every `where` predicate (rendered to SQL by
+ * {@link render}) — so a test can pin the row a statement lands on, not
+ * merely that a statement ran. */
 function makeFakeDb(queue: any[]) {
-  const captured: { values: any[]; set: any[] } = { values: [], set: [] };
+  const captured: {
+    values: any[];
+    set: any[];
+    where: SQL[];
+    updateTargets: unknown[];
+    onConflict: any[];
+  } = { values: [], set: [], where: [], updateTargets: [], onConflict: [] };
 
   function nextChain() {
     const result = queue.shift();
@@ -26,11 +39,13 @@ function makeFakeDb(queue: any[]) {
       });
     chain.values = passthrough((a) => captured.values.push(a[0]));
     chain.set = passthrough((a) => captured.set.push(a[0]));
-    chain.where = passthrough();
+    chain.where = passthrough((a) => captured.where.push(a[0]));
     chain.limit = passthrough();
     chain.innerJoin = passthrough();
+    chain.leftJoin = passthrough();
     chain.from = passthrough();
     chain.returning = passthrough();
+    chain.onConflictDoNothing = passthrough((a) => captured.onConflict.push(a[0]));
     chain.then = (onF: any, onR: any) => Promise.resolve(result).then(onF, onR);
     return chain;
   }
@@ -38,12 +53,23 @@ function makeFakeDb(queue: any[]) {
   const db = {
     insert: vi.fn(() => nextChain()),
     select: vi.fn(() => nextChain()),
-    update: vi.fn(() => nextChain()),
+    update: vi.fn((table: unknown) => {
+      captured.updateTargets.push(table);
+      return nextChain();
+    }),
+    // The mint-time prune of expired token rows; nothing here queues for it.
+    delete: vi.fn(() => nextChain()),
   } as unknown as Database;
 
   return { db, captured };
 }
 
+/** A captured predicate as the SQL it would send, with its parameters. */
+function render(fragment: SQL): { sql: string; params: unknown[] } {
+  const q = new PgDialect().sqlToQuery(fragment);
+  return { sql: q.sql, params: q.params };
+}
+
 function makeProvider(queue: any[] = []) {
   const { db, captured } = makeFakeDb(queue);
   const provider = new BevelOAuthProvider({
@@ -183,7 +209,15 @@ describe('BevelOAuthProvider', () => {
       clientId: 'client-1', userId: 'user-1', redirectUri: 'https://agent.example.com/callback',
       scope: 'mcp', resource: null,
     };
-    const { provider, captured } = makeProvider([[consumed] /* update.returning */, undefined /* insert */]);
+    const { provider, captured } = makeProvider([
+      [consumed] /* update.returning */,
+      undefined /* prune: expired tokens */,
+      undefined /* prune: expired codes */,
+      [{ clientName: 'Claude' }] /* the client's registration */,
+      [] /* no live agent connection yet for (user, "claude") */,
+      [{ id: 'conn-1' }] /* connection insert.returning */,
+      undefined /* token insert */,
+    ]);
 
     const tokens = await provider.exchangeAuthorizationCode(
       CLIENT, 'the-code', undefined, 'https://agent.example.com/callback',
@@ -194,15 +228,51 @@ describe('BevelOAuthProvider', () => {
     expect(tokens.refresh_token!.startsWith(`${PREFIX}r_`)).toBe(true);
     expect(tokens.expires_in).toBe(3600);
     expect(tokens.scope).toBe('mcp');
-    // The token row stores hashes of exactly what was returned.
-    expect(captured.values[0]).toMatchObject({
+    // A first mint for (user, agent) makes the durable agent connection,
+    // keyed by the client's folded name and snapshotting the name shown…
+    expect(captured.values[0]).toEqual({ userId: 'user-1', clientId: 'client-1', clientName: 'Claude', agentKey: 'claude' });
+    // …looked up by that key, so a later registration of "Claude" by this
+    // person lands on the same row instead of making a sixth one.
+    // (where[0] consumed the code, [1]/[2] are the prunes, [3] read the client.)
+    expect(render(captured.where[4])).toMatchObject({ params: ['user-1', 'claude'] });
+    expect(render(captured.where[4]).sql).toMatch(/"agent_connections"."agent_key" = \$2/);
+    // …and the token row stores hashes of exactly what was returned, bound to it.
+    expect(captured.values[1]).toMatchObject({
       accessTokenHash: sha256(tokens.access_token),
       refreshTokenHash: sha256(tokens.refresh_token!),
       clientId: 'client-1',
       userId: 'user-1',
+      connectionId: 'conn-1',
     });
   });
 
+  it('a mint that loses the race for the first connection re-reads the winner instead of failing', async () => {
+    const consumed = { clientId: 'client-1', userId: 'user-1', redirectUri: 'https://agent.example.com/callback', scope: null, resource: null };
+    const { provider, captured } = makeProvider([
+      [consumed],
+      undefined, undefined, /* prunes */
+      [{ clientName: 'Claude' }],
+      [] /* no live connection at first look */,
+      [] /* insert: ON CONFLICT DO NOTHING returned no row */,
+      [{ id: 'conn-winner' }] /* the re-read finds the other mint's row */,
+      undefined /* token insert */,
+    ]);
+    await provider.exchangeAuthorizationCode(CLIENT, 'the-code', undefined, 'https://agent.example.com/callback');
+    expect(captured.values[1]).toMatchObject({ connectionId: 'conn-winner' });
+    // The insert really did stand down on the conflict — on the live-agent
+    // index, not any other — rather than the fake merely answering "no row".
+    expect(captured.onConflict).toHaveLength(1);
+    expect(captured.onConflict[0].target).toEqual([agentConnections.userId, agentConnections.agentKey]);
+    expect(render(captured.onConflict[0].where).sql).toMatch(/"revoked_at" is null/);
+  });
+
+  it('keys a connection by the folded client name, so re-registrations of one agent share a row; a nameless client keys by its id', () => {
+    expect(agentKeyFor('Claude', 'c-1')).toBe('claude');
+    expect(agentKeyFor('  Claude Code ', 'c-2')).toBe('claude code');
+    expect(agentKeyFor(null, 'c-3')).toBe('c-3');
+    expect(agentKeyFor('   ', 'c-4')).toBe('c-4');
+  });
+
   it('exchangeAuthorizationCode rejects a spent/unknown code and a redirect_uri mismatch', async () => {
     await expect(
       makeProvider([[]]).provider.exchangeAuthorizationCode(CLIENT, 'spent'),
@@ -216,12 +286,30 @@ describe('BevelOAuthProvider', () => {
 
   it('exchangeRefreshToken rotates (revokes old row, mints new pair) and only narrows scope', async () => {
     const oldRow = {
-      clientId: 'client-1', userId: 'user-1', scope: 'mcp extra', resource: null,
+      clientId: 'client-1', userId: 'user-1', connectionId: 'conn-1', scope: 'mcp extra', resource: null,
       refreshExpiresAt: new Date(Date.now() + 60_000),
     };
-    const { provider } = makeProvider([[oldRow] /* revoke.returning */, undefined /* insert */]);
+    const { provider, captured, db } = makeProvider([
+      [oldRow] /* revoke.returning */,
+      [{ id: 'conn-1' }] /* the token's connection, still live */,
+      undefined /* the (throttled) use stamp */,
+      undefined, undefined, /* prunes */
+      undefined /* token insert */,
+    ]);
     const tokens = await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old', ['mcp']);
     expect(tokens.scope).toBe('mcp');
+    // A refresh STAYS on its token's connection: one connection spans every
+    // token the agent holds, nothing is looked up by (user, agent) and no
+    // second row is inserted for it.
+    expect(captured.values).toHaveLength(1);
+    expect(captured.values[0]).toMatchObject({ connectionId: 'conn-1' });
+    // The liveness check is a read of THAT connection, live rows only…
+    expect((db as any).select).toHaveBeenCalledTimes(1);
+    expect(render(captured.where[1])).toMatchObject({ params: ['conn-1'] });
+    expect(render(captured.where[1]).sql).toMatch(/"agent_connections"."revoked_at" is null/);
+    // …and the use is stamped separately, off the refresh's own path.
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+    expect(Object.keys(captured.set[1])).toEqual(['lastUsedAt']);
 
     // Widening is refused.
     await expect(
@@ -234,18 +322,100 @@ describe('BevelOAuthProvider', () => {
     ).rejects.toBeInstanceOf(InvalidGrantError);
   });
 
+  it('exchangeRefreshToken refuses a token whose agent connection was revoked, minting nothing', async () => {
+    // The race a revoke cannot otherwise win: the refresh consumed its old
+    // token a moment before the revoke landed. Looking the connection up
+    // afresh would find none live and make a new one; staying on the token's
+    // own connection finds it revoked and stops.
+    const oldRow = {
+      clientId: 'client-1', userId: 'user-1', connectionId: 'conn-1', scope: 'mcp', resource: null,
+      refreshExpiresAt: new Date(Date.now() + 60_000),
+    };
+    const { provider, captured } = makeProvider([[oldRow], [] /* connection revoked or gone */]);
+    await expect(provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old')).rejects.toBeInstanceOf(InvalidGrantError);
+    expect(captured.values).toHaveLength(0);
+    expect(captured.onConflict).toHaveLength(0);
+  });
+
+  it('exchangeRefreshToken places a token from before connections existed under one, as a first mint would', async () => {
+    const oldRow = {
+      clientId: 'client-1', userId: 'user-1', connectionId: null, scope: 'mcp', resource: null,
+      refreshExpiresAt: new Date(Date.now() + 60_000),
+    };
+    const { provider, captured } = makeProvider([
+      [oldRow],
+      undefined, undefined, /* prunes */
+      [{ clientName: 'Claude' }],
+      [] /* no live connection */,
+      [{ id: 'conn-new' }] /* connection insert.returning */,
+      undefined /* token insert */,
+    ]);
+    await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old');
+    expect(captured.values[0]).toEqual({ userId: 'user-1', clientId: 'client-1', clientName: 'Claude', agentKey: 'claude' });
+    expect(captured.values[1]).toMatchObject({ connectionId: 'conn-new' });
+  });
+
   it('verifyAccessToken resolves a live token to AuthInfo carrying the Bevel user', async () => {
     const row = {
-      id: 'tok-row-1', clientId: 'client-1', scope: 'mcp', resource: null,
+      id: 'tok-row-1', clientId: 'client-1', connectionId: 'conn-1', scope: 'mcp', resource: null,
       expiresAt: new Date(Date.now() + 60_000), userId: 'user-1', userEmail: 'alice@example.com',
     };
-    const { provider } = makeProvider([[row] /* select */, undefined /* lastUsedAt touch */]);
+    const { provider, captured } = makeProvider([
+      [row] /* select */,
+      undefined /* token lastUsedAt touch */,
+      undefined /* connection lastUsedAt touch */,
+      [row] /* a second verify a moment later */,
+      undefined /* its token touch — and NO second connection touch */,
+    ]);
 
     const info = await provider.verifyAccessToken('bevel-mcp_live');
 
     expect(info.clientId).toBe('client-1');
     expect(info.scopes).toEqual(['mcp']);
-    expect(info.extra).toMatchObject({ userId: 'user-1', userEmail: 'alice@example.com' });
+    // The agent connection rides along, for the auth middleware to bind.
+    expect(info.extra).toMatchObject({ userId: 'user-1', userEmail: 'alice@example.com', connectionId: 'conn-1' });
+    // The lookup admits a token only while its connection is unrevoked — or
+    // has none to be revoked (a token from before connections existed).
+    const lookup = render(captured.where[0]).sql;
+    expect(lookup).toMatch(/"oauth_tokens"."connection_id" is null or "agent_connections"."revoked_at" is null/);
+    // Both "last used" marks are touched: the token's row, and THIS token's
+    // agent connection.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+    expect(captured.set.map((s) => Object.keys(s))).toEqual([['lastUsedAt'], ['lastUsedAt']]);
+    expect(render(captured.where[1])).toMatchObject({ params: ['tok-row-1'] });
+    expect(render(captured.where[2])).toMatchObject({ params: ['conn-1'] });
+    expect(render(captured.where[2]).sql).toMatch(/"agent_connections"."id" = \$1/);
+    // The connection's stamp is throttled: a verify a moment later touches
+    // the token row again but not the connection — a minute has not passed.
+    await provider.verifyAccessToken('bevel-mcp_live');
+    await new Promise((r) => setTimeout(r, 0));
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections, oauthTokens]);
+  });
+
+  it('revokeToken (RFC 7009) ends the agent connection once no live token remains on it, as the owner\'s doing', async () => {
+    const { provider, captured } = makeProvider([
+      [{ connectionId: 'conn-1' }] /* the revoked pair's row */,
+      [{ live: 0 }] /* nothing else live on the connection */,
+      undefined /* connection close */,
+    ]);
+    await provider.revokeToken(CLIENT, { token: 'bevel-mcp_r_old', token_type_hint: 'refresh_token' });
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+    expect(captured.set[1]).toMatchObject({ revokedBy: 'owner' });
+    expect(captured.set[1].revokedAt).toBeInstanceOf(Date);
+    expect(render(captured.where[2])).toMatchObject({ params: ['conn-1'] });
+    expect(render(captured.where[2]).sql).toMatch(/"agent_connections"."revoked_at" is null/);
+
+    // Another live pair on the connection (the agent signed in twice): the
+    // connection stays.
+    const busy = makeProvider([[{ connectionId: 'conn-1' }], [{ live: 1 }]]);
+    await busy.provider.revokeToken(CLIENT, { token: 'bevel-mcp_r_other' });
+    expect(busy.captured.updateTargets).toEqual([oauthTokens]);
+
+    // An unknown or foreign token revokes nothing and touches no connection.
+    const unknown = makeProvider([[]]);
+    await unknown.provider.revokeToken(CLIENT, { token: 'bevel-mcp_r_gone' });
+    expect(unknown.captured.updateTargets).toEqual([oauthTokens]);
   });
 
   it('verifyAccessToken throws InvalidTokenError for unknown/revoked/expired tokens', async () => {