@bevel-software/platform-core-backend 0.30.0 → 0.32.0

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

@@ -0,0 +1,279 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createHash, randomBytes } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { InvalidGrantError, 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 { closeDb, createDb, type Database } from '../../database/connection.js';
+import { agentConnections, oauthClients, oauthTokens, users } from '../../database/core-schema.js';
+import { coreMigrationsDir } from '../../../assets.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
+
+/**
+ * The provider mints its tokens from `randomBytes`. One case below needs a
+ * mint to FAIL after the consume, with the database as the one saying no:
+ * while `forced` is set, every random draw is this buffer, so the minted
+ * access token's hash is one a seeded row already holds and the insert hits
+ * the unique index. Null the rest of the time, when the real generator runs.
+ */
+const { forcedRandom } = vi.hoisted(() => ({ forcedRandom: { bytes: null as Buffer | null } }));
+vi.mock('node:crypto', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:crypto')>();
+  return { ...actual, randomBytes: (size: number) => forcedRandom.bytes ?? actual.randomBytes(size) };
+});
+
+/**
+ * Refresh-token rotation as the DATABASE ends up holding it — on a real
+ * Postgres, through the provider's public surface alone (a sign-in's pair
+ * seeded as the token endpoint leaves one, then `exchangeRefreshToken`,
+ * `verifyAccessToken` and `revokeToken`), with the clock moved by hand.
+ *
+ * The fake-database suite beside this pins which statements run and what
+ * their predicates say; this one pins what those statements DO to a row over
+ * time: a retired pair's access token verifying for the rest of its hour and
+ * not after, the one replay a retired refresh token gets, a revoke ending a
+ * retired pair at once, and the prune keeping a retired row for exactly as
+ * long as it can still authenticate. Skipped without `TEST_DATABASE_URL`, as
+ * every `*.pg.test.ts` is; CI provides one.
+ */
+
+const PREFIX = 'bevel-mcp_';
+const sha256 = (s: string) => createHash('sha256').update(s).digest('hex');
+const T0 = new Date('2026-10-19T10:00:00Z');
+const HOUR = 60 * 60_000;
+
+describe.skipIf(!PG_ADMIN_URL)('refresh-token rotation, on a real Postgres', () => {
+  let db: Database;
+  let provider: BevelOAuthProvider;
+
+  beforeAll(async () => {
+    // A handle that holds a personal-data key, as the application's does:
+    // the seeded person's email and name are encrypted columns.
+    db = createDb(await scratchDatabaseUrl('hexis_oauth'), { piiKey: randomBytes(32).toString('base64') });
+    await migrate(db, { migrationsFolder: coreMigrationsDir() });
+    provider = new BevelOAuthProvider({
+      db,
+      crypto: null,
+      stateSecret: 'test-state-secret',
+      publicFrontendUrl: 'https://app.example.com',
+      tokenPrefix: PREFIX,
+    });
+  }, PG_TEST_TIMEOUT);
+
+  afterAll(async () => {
+    await closeDb(db);
+    await dropScratchDatabases();
+  }, PG_TEST_TIMEOUT);
+
+  beforeEach(() => {
+    // Only the clock is faked: the driver's own timers keep running.
+    vi.useFakeTimers({ toFake: ['Date'] });
+    vi.setSystemTime(T0);
+    vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  /** Move the clock `n` minutes on. */
+  const minutes = (n: number) => vi.setSystemTime(new Date(Date.now() + n * 60_000));
+
+  /**
+   * The mint refused by the unique index on `access_token_hash`, and by
+   * nothing else: Drizzle's wrapper around the insert, with Postgres's
+   * unique-violation code (23505) as the cause.
+   */
+  async function expectRefusedByUniqueIndex(call: Promise<unknown>): Promise<void> {
+    const err = await call.then(
+      () => {
+        throw new Error('the mint was not refused');
+      },
+      (e: unknown) => e as Error & { cause?: { code?: string } },
+    );
+    expect(err.message).toMatch(/Failed query: insert into "oauth_tokens"/);
+    expect(err.cause?.code).toBe('23505');
+  }
+
+  /** The row a refresh token's hash resolves to, or undefined once pruned. */
+  const rowOf = async (refreshToken: string) =>
+    (await db.select().from(oauthTokens).where(eq(oauthTokens.refreshTokenHash, sha256(refreshToken))))[0];
+
+  /**
+   * A person, a registered client, the agent connection their sign-in made,
+   * and the pair that sign-in minted — one of each per case, named by `tag`.
+   */
+  async function seed(tag: string) {
+    const [user] = await db
+      .insert(users)
+      .values({ email: `${tag}@example.com`, emailBidx: `${tag}@example.com`, name: tag })
+      .returning({ id: users.id });
+    const clientId = `client-${tag}`;
+    await db.insert(oauthClients).values({ clientId, redirectUris: ['https://agent.example.com/callback'] });
+    const [connection] = await db
+      .insert(agentConnections)
+      .values({ userId: user!.id, clientId, clientName: 'Claude', agentKey: 'claude' })
+      .returning({ id: agentConnections.id });
+    const access = `${PREFIX}a-${tag}`;
+    const refresh = `${PREFIX}r_${tag}`;
+    await db.insert(oauthTokens).values({
+      accessTokenHash: sha256(access),
+      refreshTokenHash: sha256(refresh),
+      clientId,
+      userId: user!.id,
+      connectionId: connection!.id,
+      scope: 'mcp',
+      expiresAt: new Date(Date.now() + HOUR),
+      refreshExpiresAt: new Date(Date.now() + 30 * 24 * HOUR),
+    });
+    const client: OAuthClientInformationFull = {
+      client_id: clientId,
+      redirect_uris: ['https://agent.example.com/callback'],
+      token_endpoint_auth_method: 'none',
+    };
+    return { client, access, refresh };
+  }
+
+  it("a retired pair's access token verifies for the rest of its hour, and not after", async () => {
+    const { client, access, refresh } = await seed('hour');
+    await expect(provider.verifyAccessToken(access)).resolves.toMatchObject({ clientId: client.client_id });
+
+    const next = await provider.exchangeRefreshToken(client, refresh);
+    const retired = await rowOf(refresh);
+    expect(retired?.rotatedAt).toBeInstanceOf(Date);
+    expect(retired?.revokedAt).toBeNull();
+    // Retired, not revoked: the old access token is still served…
+    await expect(provider.verifyAccessToken(access)).resolves.toMatchObject({ clientId: client.client_id });
+    minutes(59);
+    await expect(provider.verifyAccessToken(access)).resolves.toMatchObject({ clientId: client.client_id });
+    // …until its own expiry, like any access token.
+    minutes(2);
+    await expect(provider.verifyAccessToken(access)).rejects.toBeInstanceOf(InvalidTokenError);
+    // The pair the rotation minted carries on: its refresh token is good for 30 days.
+    await expect(provider.exchangeRefreshToken(client, next.refresh_token!)).resolves.toMatchObject({ token_type: 'Bearer' });
+  }, PG_TEST_TIMEOUT);
+
+  it('a retired refresh token is honoured once more within the grace — which ends the retired pair — and refused after that, or later', async () => {
+    const { client, access, refresh } = await seed('replay');
+    const winner = await provider.exchangeRefreshToken(client, refresh);
+    // The loser of a double refresh, a moment later: a fresh pair of its own.
+    const loser = await provider.exchangeRefreshToken(client, refresh);
+    expect(loser.refresh_token).not.toBe(winner.refresh_token);
+    // The replay revoked the retired row, access token included.
+    expect((await rowOf(refresh))?.revokedAt).toBeInstanceOf(Date);
+    await expect(provider.verifyAccessToken(access)).rejects.toBeInstanceOf(InvalidTokenError);
+    // Once: a third presentation is refused.
+    await expect(provider.exchangeRefreshToken(client, refresh)).rejects.toBeInstanceOf(InvalidGrantError);
+    // Both pairs are live and refresh on their own.
+    const winnerNext = await provider.exchangeRefreshToken(client, winner.refresh_token!);
+    await expect(provider.exchangeRefreshToken(client, loser.refresh_token!)).resolves.toMatchObject({ token_type: 'Bearer' });
+    // Past the grace, a retired token is not honoured again at all.
+    minutes(2);
+    await expect(provider.exchangeRefreshToken(client, winner.refresh_token!)).rejects.toBeInstanceOf(InvalidGrantError);
+    await expect(provider.exchangeRefreshToken(client, winnerNext.refresh_token!)).resolves.toMatchObject({ token_type: 'Bearer' });
+  }, PG_TEST_TIMEOUT);
+
+  it('three refreshes of one token at the same instant: exactly two pairs, the third refused — the row lock decides', async () => {
+    // What a client refreshing from several places at once actually sends.
+    // All three read the token fresh; the row lock serialises their retires,
+    // so one wins and the other two find it rotated under them; of those,
+    // the replay statement admits exactly one, and the last finds the row
+    // revoked. Nothing here is mocked: the database's own locking is the
+    // mechanism, and this is the one place it is exercised.
+    const { client, refresh } = await seed('race');
+    const outcomes = await Promise.allSettled([
+      provider.exchangeRefreshToken(client, refresh),
+      provider.exchangeRefreshToken(client, refresh),
+      provider.exchangeRefreshToken(client, refresh),
+    ]);
+    const fulfilled = outcomes.filter((o): o is PromiseFulfilledResult<Awaited<ReturnType<typeof provider.exchangeRefreshToken>>> => o.status === 'fulfilled');
+    const rejected = outcomes.filter((o): o is PromiseRejectedResult => o.status === 'rejected');
+    expect(fulfilled).toHaveLength(2);
+    expect(rejected).toHaveLength(1);
+    expect(rejected[0]!.reason).toBeInstanceOf(InvalidGrantError);
+    // Two distinct pairs, both live.
+    const [a, b] = fulfilled.map((o) => o.value.refresh_token!);
+    expect(a).not.toBe(b);
+    await expect(provider.exchangeRefreshToken(client, a)).resolves.toMatchObject({ token_type: 'Bearer' });
+    await expect(provider.exchangeRefreshToken(client, b)).resolves.toMatchObject({ token_type: 'Bearer' });
+    // The original is spent for good: retired by the winner, revoked by the replay.
+    const row = await rowOf(refresh);
+    expect(row?.rotatedAt).toBeInstanceOf(Date);
+    expect(row?.revokedAt).toBeInstanceOf(Date);
+    await expect(provider.exchangeRefreshToken(client, refresh)).rejects.toBeInstanceOf(InvalidGrantError);
+  }, PG_TEST_TIMEOUT);
+
+  it('a mint that fails after the consume rolls the consume back: the token is exactly as it was, and still refreshes', async () => {
+    // The consume and the mint are one transaction, and this is what that
+    // buys: the database refuses the insert (the minted access token's hash
+    // is one a seeded row already holds), the retire — then, on a second
+    // try, the replay — is rolled back with it, and the token that was
+    // presented is untouched rather than spent for nothing.
+    const { client, refresh } = await seed('rollback');
+    const collider = Buffer.alloc(32, 7);
+    const { client: other } = await seed('collider');
+    await db
+      .insert(oauthTokens)
+      .values({
+        accessTokenHash: sha256(PREFIX + collider.toString('base64url')),
+        refreshTokenHash: sha256(`${PREFIX}r_collider-pair`),
+        clientId: other.client_id,
+        userId: (await db.select({ id: users.id }).from(users).limit(1))[0]!.id,
+        scope: 'mcp',
+        expiresAt: new Date(Date.now() + HOUR),
+      });
+
+    // A fresh token: the retire is rolled back with the failed mint.
+    forcedRandom.bytes = collider;
+    try {
+      await expectRefusedByUniqueIndex(provider.exchangeRefreshToken(client, refresh));
+    } finally {
+      forcedRandom.bytes = null;
+    }
+    const untouched = await rowOf(refresh);
+    expect(untouched?.rotatedAt).toBeNull();
+    expect(untouched?.revokedAt).toBeNull();
+    const winner = await provider.exchangeRefreshToken(client, refresh);
+
+    // A retired token within the grace: the replay is rolled back with the failed mint too.
+    forcedRandom.bytes = collider;
+    try {
+      await expectRefusedByUniqueIndex(provider.exchangeRefreshToken(client, refresh));
+    } finally {
+      forcedRandom.bytes = null;
+    }
+    const stillRetired = await rowOf(refresh);
+    expect(stillRetired?.rotatedAt).toBeInstanceOf(Date);
+    expect(stillRetired?.revokedAt).toBeNull();
+    // Its one replay is still owed.
+    const loser = await provider.exchangeRefreshToken(client, refresh);
+    expect(loser.refresh_token).not.toBe(winner.refresh_token);
+  }, PG_TEST_TIMEOUT);
+
+  it("a revoke ends a retired pair's access token at once, hour or no hour", async () => {
+    const { client, access, refresh } = await seed('revoke');
+    await provider.exchangeRefreshToken(client, refresh);
+    await expect(provider.verifyAccessToken(access)).resolves.toMatchObject({ clientId: client.client_id });
+    await provider.revokeToken(client, { token: access, token_type_hint: 'access_token' });
+    await expect(provider.verifyAccessToken(access)).rejects.toBeInstanceOf(InvalidTokenError);
+    await expect(provider.exchangeRefreshToken(client, refresh)).rejects.toBeInstanceOf(InvalidGrantError);
+  }, PG_TEST_TIMEOUT);
+
+  it('the prune keeps a retired row for its hour and the grace, then removes it', async () => {
+    const { client, refresh } = await seed('prune');
+    const next = await provider.exchangeRefreshToken(client, refresh);
+    // The mint prunes, and the row it just retired is kept: it can still verify and be replayed.
+    expect(await rowOf(refresh)).toBeDefined();
+    minutes(30);
+    const later = await provider.exchangeRefreshToken(client, next.refresh_token!);
+    expect(await rowOf(refresh)).toBeDefined();
+    // 62 minutes after its rotation it can do neither, and the next mint's prune drops it.
+    minutes(32);
+    await provider.exchangeRefreshToken(client, later.refresh_token!);
+    expect(await rowOf(refresh)).toBeUndefined();
+    // The row retired 32 minutes ago is still there.
+    expect(await rowOf(next.refresh_token!)).toBeDefined();
+  }, PG_TEST_TIMEOUT);
+});

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

@@ -60,6 +60,10 @@ function makeFakeDb(queue: any[]) {
     // The mint-time prune of expired token rows; nothing here queues for it.
     delete: vi.fn(() => nextChain()),
   } as unknown as Database;
+  // A transaction is the same fake, so the queue is consumed in statement
+  // order whether or not a statement ran inside one; what ran inside one is
+  // pinned by the call count.
+  (db as unknown as { transaction: unknown }).transaction = vi.fn(async (fn: (tx: Database) => Promise<unknown>) => fn(db));
 
   return { db, captured };
 }
@@ -288,28 +292,39 @@ describe('BevelOAuthProvider', () => {
     ).rejects.toBeInstanceOf(InvalidGrantError);
   });
 
-  it('exchangeRefreshToken rotates (revokes old row, mints new pair) and only narrows scope', async () => {
+  it('exchangeRefreshToken rotates (retires the old row, mints a new pair) and only narrows scope', async () => {
     const oldRow = {
       clientId: 'client-1', userId: 'user-1', connectionId: 'conn-1', scope: 'mcp extra', resource: null,
       refreshExpiresAt: new Date(Date.now() + 60_000),
     };
     const { provider, captured, db } = makeProvider([
-      [oldRow] /* revoke.returning */,
+      [oldRow] /* the row behind the hash, for this client */,
       [{ id: 'conn-1' }] /* the token's connection, still live */,
-      [] /* the (throttled) use stamp's first-use claim: stamped before */,
-      undefined, undefined, /* prunes */
+      undefined, undefined, /* prunes — on the pool, before the transaction */
+      [oldRow] /* retire.returning — inside the transaction with the mint */,
       undefined /* token insert */,
+      [] /* the (throttled) use stamp's first-use claim, after the commit: stamped before */,
       undefined /* the ordinary use stamp */,
     ]);
     const tokens = await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old', ['mcp']);
+    // The consume and the mint landed in one transaction.
+    expect((db as unknown as { transaction: ReturnType<typeof vi.fn> }).transaction).toHaveBeenCalledTimes(1);
     expect(tokens.scope).toBe('mcp');
+    // Read by hash AND client first, judged, and only then consumed.
+    expect(render(captured.where[0]).sql).toMatch(/"oauth_tokens"."refresh_token_hash" = .* and "oauth_tokens"."client_id" = /);
+    // The old row is RETIRED, not revoked: its access token keeps working for
+    // its own hour, so a runner still holding it is not cut off by a refresh
+    // another runner made. Only a fresh row is retired — one already rotated
+    // or revoked is the replay path's business.
+    expect(Object.keys(captured.set[0])).toEqual(['rotatedAt']);
+    expect(render(captured.where[4]).sql).toMatch(/"oauth_tokens"."revoked_at" is null and "oauth_tokens"."rotated_at" is null/);
     // 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((db as any).select).toHaveBeenCalledTimes(2);
     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: the
@@ -317,16 +332,170 @@ describe('BevelOAuthProvider', () => {
     await new Promise((r) => setTimeout(r, 0));
     expect(captured.updateTargets).toEqual([oauthTokens, agentConnections, agentConnections]);
     expect(Object.keys(captured.set[1])).toEqual(['lastUsedAt']);
+    // The refresh's prune — on the pool, before the transaction opened —
+    // keeps a retired row for its access hour plus the reuse grace (it can
+    // still verify and be replayed until then) and removes it after: the
+    // third term of the delete, cut off 61 minutes ago.
+    const prune = captured.where.map(render).find((w) => /"oauth_tokens"."rotated_at" < /.test(w.sql));
+    expect(prune, 'the refresh prunes retired rows').toBeDefined();
+    // Third statement: after the read and the liveness check, before the retire.
+    expect(render(captured.where[2]).sql).toMatch(/"oauth_tokens"."rotated_at" < /);
+    // The dialect renders a Date parameter as its ISO string.
+    const rotatedCutoff = new Date(prune!.params.at(-1) as string | Date);
+    expect(Date.now() - rotatedCutoff.getTime()).toBeGreaterThanOrEqual(61 * 60_000);
+    expect(Date.now() - rotatedCutoff.getTime()).toBeLessThan(61 * 60_000 + 5_000);
+
+    // Widening is refused — invalid_scope to the client, in the log like
+    // every other refusal, and BEFORE anything is consumed: the same token
+    // still refreshes with the scope it was granted.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      const widening = makeProvider([[oldRow]]);
+      await expect(
+        widening.provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old', ['mcp', 'admin']),
+      ).rejects.toBeInstanceOf(InvalidScopeError);
+      expect(warn).toHaveBeenCalledWith(expect.stringMatching(/refresh refused: requested scope exceeds the originally granted scope/), expect.anything());
+      expect(widening.captured.updateTargets).toEqual([]);
+    } finally {
+      warn.mockRestore();
+    }
+  });
 
-    // Widening is refused.
-    await expect(
-      makeProvider([[oldRow]]).provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old', ['mcp', 'admin']),
-    ).rejects.toBeInstanceOf(InvalidScopeError);
+  it('exchangeRefreshToken honours the loser of a rotation race once: read fresh, retired under it, replayed', async () => {
+    // Two refreshes of one fresh token at the same instant. Both read it
+    // fresh; one retire lands, the other matches nothing — and is then the
+    // loser of a double refresh, replayable within the grace like any other.
+    const oldRow = {
+      clientId: 'client-1', userId: 'user-1', connectionId: 'conn-1', scope: 'mcp', resource: null,
+      refreshExpiresAt: new Date(Date.now() + 60_000), revokedAt: null, rotatedAt: null,
+    };
+    const info = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const { provider, captured } = makeProvider([
+      [oldRow] /* read fresh */,
+      [{ id: 'conn-1' }] /* its connection, live */,
+      undefined, undefined, /* prunes — before the transaction */
+      [] /* the retire matches nothing: rotated under this request */,
+      [{ ...oldRow, rotatedAt: new Date() }] /* the replay consumes it */,
+      undefined /* token insert */,
+      [] /* first-use claim, after the commit */,
+      undefined /* the ordinary use stamp */,
+    ]);
+    try {
+      const tokens = await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old');
+      expect(tokens.refresh_token).toMatch(/^bevel-mcp_r_/);
+      expect(captured.values).toHaveLength(1);
+      expect(Object.keys(captured.set[0])).toEqual(['rotatedAt']);
+      expect(Object.keys(captured.set[1])).toEqual(['revokedAt']);
+      expect(info).toHaveBeenCalledWith(expect.stringMatching(/refresh replayed 0 s after its rotation/), expect.anything());
+    } finally {
+      info.mockRestore();
+    }
+  });
 
-    // Unknown/already-rotated refresh token.
-    await expect(
-      makeProvider([[]]).provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_gone'),
-    ).rejects.toBeInstanceOf(InvalidGrantError);
+  it('a retired pair\'s access token verifies until its own expiry, and dies with a revoke like any other', async () => {
+    // Rotation sets `rotated_at` and leaves `revoked_at` null, and the
+    // verification predicate asks about `revoked_at` and `expires_at` only:
+    // so a runner still holding the old pair is served for the rest of its
+    // hour. The same predicate is what a revoke, a sign-out or a connection
+    // revoke then falsify, since all of those set `revoked_at` (or the
+    // connection's), none of which this change touched.
+    const row = {
+      id: 't-1', clientId: 'client-1', connectionId: 'conn-1', scope: 'mcp', resource: null,
+      expiresAt: new Date(Date.now() + 30 * 60_000), userId: 'user-1', userEmail: 'u@x.io',
+    };
+    const { provider, captured } = makeProvider([[row], undefined /* touch */, [] /* claim lost */, undefined /* stamp */]);
+    const info = await provider.verifyAccessToken('bevel-mcp_live');
+    expect(info.clientId).toBe('client-1');
+    const verify = render(captured.where[0]).sql;
+    expect(verify).toMatch(/"oauth_tokens"."revoked_at" is null/);
+    expect(verify).toMatch(/"oauth_tokens"."expires_at" > /);
+    expect(verify).toMatch(/"agent_connections"."revoked_at" is null/);
+    expect(verify).not.toMatch(/rotated_at/);
+  });
+
+  /** A row the rotation did not match, as the replay path then reads it. */
+  const rotatedRow = (ago: number) => ({
+    clientId: 'client-1', userId: 'user-1', connectionId: 'conn-1', scope: 'mcp', resource: null,
+    refreshExpiresAt: new Date(Date.now() + 60_000),
+    revokedAt: null,
+    rotatedAt: new Date(Date.now() - ago),
+  });
+
+  it('exchangeRefreshToken honours a refresh token rotated within the reuse grace once more — the loser of a double refresh gets a pair too', async () => {
+    // Claude's hosted apps refresh proactively and reactively, and a
+    // scheduled task refreshes beside the chat that shares its connector:
+    // the same token arrives twice. The second arrival, 10 s after the first
+    // rotated it, is answered with a fresh pair on the same connection rather
+    // than the invalid_grant a client reads as "re-authorize".
+    const info = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const { provider, captured } = makeProvider([
+      [rotatedRow(10_000)] /* the row behind the hash: retired 10 s ago */,
+      [{ id: 'conn-1' }] /* its connection, live */,
+      undefined, undefined, /* prunes — before the transaction */
+      [rotatedRow(10_000)] /* the replay consumes it — inside the transaction with the mint */,
+      undefined /* token insert */,
+      [] /* first-use claim, after the commit */,
+      undefined /* the ordinary use stamp */,
+    ]);
+    try {
+      const tokens = await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old');
+      expect(tokens.refresh_token).toMatch(/^bevel-mcp_r_/);
+      expect(captured.values).toHaveLength(1);
+      expect(captured.values[0]).toMatchObject({ connectionId: 'conn-1', userId: 'user-1' });
+      // Honoured ONCE: the replay revokes the retired row in the statement
+      // that admits it — by hash AND client, unrevoked, rotated within the
+      // grace — so a third presentation finds nothing, and another client's
+      // token is never honoured. Never retired again: no `rotatedAt` write.
+      expect(Object.keys(captured.set[0])).toEqual(['revokedAt']);
+      expect(captured.set.flatMap((s) => Object.keys(s))).not.toContain('rotatedAt');
+      expect(render(captured.where[4]).sql).toMatch(
+        /"oauth_tokens"."refresh_token_hash" = .* and "oauth_tokens"."client_id" = .* and "oauth_tokens"."revoked_at" is null and "oauth_tokens"."rotated_at" > /,
+      );
+      // Said once the pair is minted, not before the checks that could still refuse.
+      expect(info).toHaveBeenCalledWith(expect.stringMatching(/refresh replayed 10 s after its rotation, within the reuse grace; a fresh pair is minted/), expect.anything());
+    } finally {
+      info.mockRestore();
+    }
+  });
+
+  it.each([
+    ['unknown to this client', [[]], /refresh refused: unknown refresh token for this client/],
+    ['revoked', [[{ ...rotatedRow(10_000), rotatedAt: null, revokedAt: new Date() }]], /refresh refused: refresh token revoked/],
+    ['rotated past the grace', [[rotatedRow(120_000)]], /refresh refused: refresh token rotated 120 s ago, past the 60 s reuse grace/],
+    ['already replayed once', [[{ ...rotatedRow(10_000), revokedAt: new Date() }]], /refresh refused: refresh token rotated 10 s ago and already replayed once, or revoked since/],
+    [
+      'rotated and replayed by concurrent requests between the read and the consume',
+      [[{ ...rotatedRow(0), rotatedAt: null }], [{ id: 'conn-1' }], undefined, undefined, /* prunes */ [] /* retire misses */, [] /* replay misses too */],
+      /refresh refused: refresh token rotated or revoked by a concurrent request/,
+    ],
+  ])('exchangeRefreshToken refuses a refresh token that is %s, mints nothing, and says why in the log', async (_what, queue, said) => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      const { provider, captured } = makeProvider([...queue]);
+      await expect(provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old')).rejects.toBeInstanceOf(InvalidGrantError);
+      expect(captured.values).toHaveLength(0);
+      // The reason is in the log, never the token.
+      expect(warn).toHaveBeenCalledWith(expect.stringMatching(said), expect.anything());
+      expect(JSON.stringify(warn.mock.calls)).not.toContain('bevel-mcp_r_old');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('exchangeRefreshToken logs the two refusals that come after a token was accepted: expired, and its agent revoked', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    try {
+      const expired = { ...rotatedRow(0), rotatedAt: null, refreshExpiresAt: new Date(Date.now() - 1_000) };
+      await expect(makeProvider([[expired]]).provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old')).rejects.toBeInstanceOf(InvalidGrantError);
+      expect(warn).toHaveBeenLastCalledWith(expect.stringMatching(/refresh refused: refresh token expired/), expect.anything());
+
+      const live = { ...rotatedRow(0), rotatedAt: null };
+      await expect(makeProvider([[live], [] /* its connection: revoked or gone */]).provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old')).rejects.toBeInstanceOf(InvalidGrantError);
+      expect(warn).toHaveBeenLastCalledWith(expect.stringMatching(/refresh refused: access for this agent was revoked/), expect.anything());
+      expect(JSON.stringify(warn.mock.calls)).not.toContain('bevel-mcp_r_old');
+    } finally {
+      warn.mockRestore();
+    }
   });
 
   it('exchangeRefreshToken refuses a token whose agent connection was revoked, minting nothing', async () => {
@@ -350,11 +519,13 @@ describe('BevelOAuthProvider', () => {
       refreshExpiresAt: new Date(Date.now() + 60_000),
     };
     const { provider, captured } = makeProvider([
-      [oldRow],
-      undefined, undefined, /* prunes */
+      [oldRow] /* the row behind the hash: no connection to check */,
+      // Placed under a connection BEFORE the transaction, as a first mint would place it.
       [{ clientName: 'Claude' }],
       [] /* no live connection */,
       [{ id: 'conn-new' }] /* connection insert.returning */,
+      undefined, undefined, /* prunes — before the transaction */
+      [oldRow] /* retire.returning */,
       undefined /* token insert */,
     ]);
     await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old');
@@ -458,6 +629,10 @@ describe('BevelOAuthProvider', () => {
     ]);
     await provider.revokeToken(CLIENT, { token: 'bevel-mcp_r_old', token_type_hint: 'refresh_token' });
     expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+    // "Live" excludes a retired row: its successor is the live token, and a
+    // sign-out must not keep the connection open on a refresh token nobody
+    // can use any more.
+    expect(render(captured.where[1]).sql).toMatch(/"oauth_tokens"."revoked_at" is null and "oauth_tokens"."rotated_at" is null/);
     expect(captured.set[1]).toMatchObject({ revokedBy: 'owner' });
     expect(captured.set[1].revokedAt).toBeInstanceOf(Date);
     expect(render(captured.where[2])).toMatchObject({ params: ['conn-1'] });

package/src/modules/mcp/__tests__/mcp-routes-harness.ts

@@ -2,6 +2,7 @@ import type { Server as HttpServer } from 'node:http';
 import type { RequestHandler } from 'express';
 import express from 'express';
 import { createMcpRoutes } from '../mcp.routes.js';
+import type { McpCallerKind } from '../mcp-auth.middleware.js';
 
 /**
  * The shared mount for every `createMcpRoutes` suite.
@@ -19,7 +20,8 @@ import { createMcpRoutes } from '../mcp.routes.js';
  */
 
 /**
- * Auth stand-in binding the user named by `x-test-user`, defaulting to user-A.
+ * Auth stand-in binding the user named by `x-test-user`, defaulting to user-A,
+ * and the credential kind named by `x-test-kind`, when one is.
  *
  * The header lets a suite act as a second user (the cross-user checks need
  * one); suites that never send it see the single fixed user their assertions
@@ -27,6 +29,10 @@ import { createMcpRoutes } from '../mcp.routes.js';
  */
 export const fakeAuth: RequestHandler = (req, _res, next) => {
   req.userId = (req.headers['x-test-user'] as string | undefined) ?? 'user-A';
+  // The credential kind the real middleware would have recognised, when a
+  // suite needs one (the page header is a session's alone).
+  const kind = req.headers['x-test-kind'] as McpCallerKind | undefined;
+  if (kind) req.mcpCallerKind = kind;
   next();
 };