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

package/src/modules/marketplace/github-facade/github-facade.service.ts

@@ -1,20 +1,26 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
-import type { MintedExternalApiKey } from '../../tool-auth/external-api-key.interface.js';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('github-facade');
+import type { KeyKindSpec, MintedExternalApiKey } from '../../tool-auth/external-api-key.interface.js';
 import { signAuthRequest, type McpAuthRequestState } from '../../mcp/oauth/oauth-state.js';
 import type { GitHubFacadeCredentialsService } from './github-facade-credentials.service.js';
 import type { GitHubFacadeCodeStore } from './github-facade-codes.store.js';
+import { printable } from '../../../shared/printable.js';
 
 /**
- * The KIND stored on a connection key minted through the facade, and the
- * plaintext prefix that kind is minted with. `gho_` is what a GitHub OAuth
- * token looks like — the shape a consumer expecting a GitHub Enterprise host
- * accepts; the key is otherwise an ordinary connection key — hashed at rest,
- * revocable from the person's external-agent page, accepted by every surface
- * a connection key is. The kind, not the label, is what tells such a key
- * apart: a label is the person's to edit.
+ * The KIND stored on a connection key minted through the facade, and how
+ * that kind is spelled. `gho_` plus forty letters and digits is what a
+ * GitHub OAuth token looks like — the shape a consumer expecting a GitHub
+ * Enterprise host accepts, and may well check; the key is otherwise an
+ * ordinary connection key — hashed at rest, revocable from the person's
+ * external-agent page, accepted by every surface a connection key is. The
+ * kind, not the label, is what tells such a key apart: a label is the
+ * person's to edit.
  */
 export const GITHUB_LINK_KEY_KIND = 'github-link';
 export const GITHUB_LINK_KEY_PREFIX = 'gho_';
+export const GITHUB_LINK_KEY_SPEC: KeyKindSpec = { prefix: GITHUB_LINK_KEY_PREFIX, shape: 'github-token' };
 
 /**
  * A product that talks to this deployment as if it were a GitHub Enterprise
@@ -62,11 +68,21 @@ export interface GitHubFacadeDeps {
   publicFrontendUrl: string;
 }
 
+/**
+ * A refusal the caller is answered with in GitHub's terms — and, for the
+ * server log only, WHY: `detail` names the check that failed (a client
+ * secret that is not the registered one, a code nobody issued) where the
+ * response deliberately says no more than GitHub would. A consumer's
+ * backend never shows its user what we answered; the log is the only place
+ * an operator can see which hop of the connect flow went wrong. It never
+ * carries a secret or a code.
+ */
 export class GitHubFacadeRequestError extends Error {
   constructor(
     readonly status: number,
     readonly code: string,
     message: string,
+    readonly detail: string = message,
   ) {
     super(message);
     this.name = 'GitHubFacadeRequestError';
@@ -103,10 +119,20 @@ export class GitHubFacade {
     const state = str(query.state);
     const creds = await this.deps.credentials.ensure();
     if (!clientId || !safeEqual(clientId, creds.clientId)) {
-      throw new GitHubFacadeRequestError(400, 'unknown_client', 'Unknown client_id.');
+      throw new GitHubFacadeRequestError(
+        400,
+        'unknown_client',
+        'Unknown client_id.',
+        clientId ? 'client_id is not the registered one (rotated since, or mistyped)' : 'no client_id in the request',
+      );
     }
     if (!this.consumerFor(redirectUri)) {
-      throw new GitHubFacadeRequestError(400, 'invalid_redirect', 'redirect_uri does not belong to a known consumer.');
+      throw new GitHubFacadeRequestError(
+        400,
+        'invalid_redirect',
+        'redirect_uri does not belong to a known consumer.',
+        `redirect_uri host is ${hostOf(redirectUri)}, not a consumer's`,
+      );
     }
     const signed = signAuthRequest(this.deps.stateSecret, {
       c: clientId,
@@ -169,27 +195,47 @@ export class GitHubFacade {
     const clientId = str(body.client_id);
     const clientSecret = str(body.client_secret);
     const code = str(body.code);
-    if (!clientId || !clientSecret || !safeEqual(clientId, creds.clientId) || !safeEqual(clientSecret, creds.clientSecret)) {
-      throw new GitHubFacadeRequestError(401, 'incorrect_client_credentials', 'The client_id and/or client_secret passed are incorrect.');
+    // One answer for every credential failure, as GitHub gives; the log
+    // alone says which half was wrong.
+    const credentialsWrong = (detail: string) =>
+      new GitHubFacadeRequestError(
+        401,
+        'incorrect_client_credentials',
+        'The client_id and/or client_secret passed are incorrect.',
+        detail,
+      );
+    if (!clientId || !safeEqual(clientId, creds.clientId)) {
+      throw credentialsWrong(clientId ? 'client_id is not the registered one (rotated since, or mistyped)' : 'no client_id in the request');
     }
-    const pending = code ? await this.deps.codes.peek(hashCode(code)) : null;
-    if (!pending || pending.clientId !== clientId) {
-      throw new GitHubFacadeRequestError(400, 'bad_verification_code', 'The code passed is incorrect or expired.');
+    if (!clientSecret || !safeEqual(clientSecret, creds.clientSecret)) {
+      throw credentialsWrong(clientSecret ? 'client_secret is not the registered one (rotated since, or mistyped)' : 'no client_secret in the request');
     }
+    const codeWrong = (detail: string) =>
+      new GitHubFacadeRequestError(400, 'bad_verification_code', 'The code passed is incorrect or expired.', detail);
+    if (!code) throw codeWrong('no code in the request');
+    const pending = await this.deps.codes.peek(hashCode(code));
+    if (!pending) throw codeWrong('no live code with that value: never issued, already spent, or older than 10 minutes');
+    if (pending.clientId !== clientId) throw codeWrong('the code was issued under a different client id');
     const redirectUri = str(body.redirect_uri);
     if (redirectUri && redirectUri !== pending.redirectUri) {
-      throw new GitHubFacadeRequestError(400, 'redirect_uri_mismatch', 'The redirect_uri does not match the authorization.');
+      throw new GitHubFacadeRequestError(
+        400,
+        'redirect_uri_mismatch',
+        'The redirect_uri does not match the authorization.',
+        `redirect_uri host is ${hostOf(redirectUri)}, the code was issued for ${hostOf(pending.redirectUri)}`,
+      );
     }
     const spent = await this.deps.codes.consume(pending.codeHash);
-    if (!spent) {
-      throw new GitHubFacadeRequestError(400, 'bad_verification_code', 'The code passed is incorrect or expired.');
-    }
+    if (!spent) throw codeWrong('the code was spent by a concurrent exchange');
     // The consumer is the one the code was issued for — the redirect the
     // person approved names it — so the key is labelled for that product.
     const consumer = this.consumerFor(spent.redirectUri);
     const minted = await this.deps.keys.mint(spent.userId, consumer?.keyLabel ?? 'GitHub-compatible link', {
       kind: GITHUB_LINK_KEY_KIND,
     });
+    log.info(
+      `${printable(consumer?.name ?? 'a consumer')} connected user ${printable(spent.userId)}: link key ${printable(minted.summary.id)} minted`,
+    );
     return { access_token: minted.plaintext, token_type: 'bearer', scope: '' };
   }
 
@@ -210,6 +256,21 @@ function hashCode(code: string): string {
   return createHash('sha256').update(code).digest('hex');
 }
 
+/**
+ * The host of a URL for a log line, or what was sent when it is not one.
+ * The caller chose the URL, so the host is rendered printable even though a
+ * parsed host is ASCII: the log's one-line rule holds by construction, not
+ * by an argument about URL parsing.
+ */
+function hostOf(url: string): string {
+  try {
+    const host = new URL(url).host;
+    return host ? printable(host) : '(empty)';
+  } catch {
+    return url ? '(not a URL)' : '(empty)';
+  }
+}
+
 function str(v: unknown): string {
   return typeof v === 'string' ? v : '';
 }

package/src/modules/marketplace/github-facade/index.ts

@@ -17,6 +17,7 @@ export {
   GitHubFacadeRequestError,
   GITHUB_LINK_KEY_KIND,
   GITHUB_LINK_KEY_PREFIX,
+  GITHUB_LINK_KEY_SPEC,
   CLAUDE_CONSUMER,
   type GitHubFacadeConsumer,
   type GitHubFacadeDeps,

package/src/modules/marketplace/marketplace-repo.service.ts

@@ -1,12 +1,10 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { execFile, spawn, type ChildProcess } from 'node:child_process';
-import { promisify } from 'node:util';
+import { spawn, type ChildProcess } from 'node:child_process';
 import { WorkspaceMutex } from '../kb-fs/mutex.js';
 import type { VirtualTree } from '../plugins/compile/compile-marketplace.js';
-
-const execFileAsync = promisify(execFile);
+import { type IGitRunner } from '../../shared/git.contract.js';
 
 /** What the repo service asks the compiler for — the one seam it has. */
 export interface MarketplaceCompiler {
@@ -59,6 +57,8 @@ export class MarketplaceRepoService {
     /** Absolute path of the bare repository (created on first use). */
     readonly repoDir: string,
     private readonly compiler: MarketplaceCompiler,
+    /** How git is run — see `shared/git.contract.ts`. */
+    private readonly gitRunner: IGitRunner,
     private readonly committer: { name: string; email: string } = {
       name: 'Hexis',
       email: 'hexis@localhost',
@@ -220,7 +220,14 @@ export class MarketplaceRepoService {
     try {
       const { stdout } = await this.git(['-C', this.repoDir, 'rev-parse', '--verify', '--quiet', this.refOf(namespace)]);
       return stdout.trim() || null;
-    } catch {
+    } catch (err) {
+      // "No such ref" is the answer this null stands for, and `rev-parse
+      // --verify --quiet` says it with exit code 1 and nothing else. Every
+      // other failure — a deadline, a repository git cannot open, a spawn that
+      // never ran — is not an answer about the ref, and read as one it would
+      // have `ensureCompiled` start a namespace's history over on top of the
+      // one it has.
+      if (exitCodeOf(err) !== 1) throw err;
       return null;
     }
   }
@@ -314,14 +321,22 @@ export class MarketplaceRepoService {
     await fs.writeFile(path.join(this.sidecarDir(), `${namespace}.json`), sourceCommit);
   }
 
+  /**
+   * Every command names the bare repository with `-C`, so the working
+   * directory only has to be somewhere that EXISTS: the process's own, as
+   * before. Not the repository — the first command ever run here is the `init`
+   * that creates it, and a spawn into a directory that is not there fails as
+   * `ENOENT` on git itself, which reads as git being missing. The plumbing
+   * that reads a scratch checkout passes its own `cwd`.
+   */
   private git(args: string[], opts: { cwd?: string; env?: NodeJS.ProcessEnv } = {}) {
-    return execFileAsync('git', args, { cwd: opts.cwd, env: opts.env ?? process.env, maxBuffer: 64 * 1024 * 1024 });
+    return this.gitRunner.run(opts.cwd ?? process.cwd(), args, { env: opts.env });
   }
 }
 
-/** The exit code an execFile failure carries, or null when the process never ran. */
+/** The exit code a git failure carries, or null when the process never ran. */
 function exitCodeOf(err: unknown): number | null {
-  const code = (err as { code?: unknown } | null)?.code;
+  const code = (err as { exitCode?: unknown } | null)?.exitCode;
   return typeof code === 'number' ? code : null;
 }
 

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 () => {