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

package/migrations/meta/_journal.json

@@ -134,6 +134,13 @@
       "when": 1792106401545,
       "tag": "0018_agent_events_page",
       "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1792404850653,
+      "tag": "0019_oauth_token_rotated_at",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-shared": "0.31.0",
-    "@bevel-software/platform-mcp-core": "0.31.0"
+    "@bevel-software/platform-mcp-core": "0.32.0",
+    "@bevel-software/platform-shared": "0.32.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/core/create-core-services.ts

@@ -127,6 +127,7 @@ import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import { StarterPackService } from '../modules/onboarding/starter-pack.service.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
 import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
+import { ChangeRequestHooks, type IChangeRequestHooks } from '../modules/workflow/change-request-hooks.js';
 import { PendingCommitsService } from '../modules/workflow/pending-commits.service.js';
 import {
   PendingCommitsWorker,
@@ -324,6 +325,12 @@ export interface CoreServices {
   reviewWorkflowService: ReviewWorkflowService;
   fileLockService: FileLockService;
   workflowService: WorkflowService;
+  /**
+   * The seam for "a change request was opened": a deployment registers here
+   * how the reviewers are told (the cloud's mail, say), and the open's answer
+   * says whether somebody did. Core registers nothing.
+   */
+  changeRequestHooks: IChangeRequestHooks;
   /** Remote sync (`POST /api/sync`): a git host or pipeline makes the clones catch up. */
   kbSyncService: KbSyncService;
   eventBus: WorkflowEventBus;
@@ -950,6 +957,10 @@ export async function createCoreServices(
   // id-repair keeps the id namespace collision-free. Subscribers are registered
   // below, once the reacting services exist.
   const fileChangeNotifier = new FileChangeNotifier();
+  // Who tells the reviewers of an opened change request: the composition root
+  // of a distribution registers its listener here, after this returns (see
+  // `ChangeRequestHooks`).
+  const changeRequestHooks = new ChangeRequestHooks();
   const workflowService = new WorkflowService(
     db,
     gitService,
@@ -967,6 +978,11 @@ export async function createCoreServices(
     // the agent-access gate consult, so a deployment's registrations against
     // it reach every hook point.
     workflowHooks,
+    // Exposed as `changeRequestHooks`, the same instance, for the same reason.
+    changeRequestHooks,
+    // The opened event names the approvers as accounts; auth answers which
+    // of the addresses the access model names have one.
+    authService,
   );
   // The leftover-branch cleanup asks the Deployment page at every round, so
   // switching it off there applies without a restart.
@@ -1668,6 +1684,7 @@ export async function createCoreServices(
     reviewWorkflowService,
     fileLockService,
     workflowService,
+    changeRequestHooks,
     kbSyncService,
     eventBus,
     fileChangeNotifier,

package/src/index.ts

@@ -151,3 +151,10 @@ export {
   type AgentReadHook,
   type PreWriteHook,
 } from './modules/workflow/workflow-hooks.js';
+export {
+  ChangeRequestHooks,
+  type ChangeRequestOpenedEvent,
+  type ChangeRequestOpenedHook,
+  type ChangeRequestPerson,
+  type IChangeRequestHooks,
+} from './modules/workflow/change-request-hooks.js';

package/src/modules/access-model/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The access model's public entry: what another module imports of it.
+ *
+ * The module is the grammar of `access.md` (how principals, roles, groups
+ * and verbs are spelled), the errors a refused access is reported with, and
+ * the gate a change is read through. A consumer outside the module imports
+ * from here, not from the files; the files are the module's own layout and
+ * free to move. The `access` module's own files predate this entry and still
+ * import the files directly — they move here as they are touched.
+ */
+export * from './access-grammar.js';
+export * from './access-errors.js';
+export type { ChangeReadVerdict, ChangeTargetKind, IChangeReadGate } from './change-gate.js';

package/src/modules/auth/__tests__/account-deactivation.test.ts

@@ -25,10 +25,17 @@ import { RECOVERY_BOT_EMAIL } from '../../workflow/recovery-bot.js';
  * shows up as `db:`.
  */
 function makeFakeDb(queue: unknown[]) {
-  const captured: { values: Record<string, unknown>[]; set: Record<string, unknown>[]; order: string[] } = {
+  const captured: {
+    values: Record<string, unknown>[];
+    set: Record<string, unknown>[];
+    order: string[];
+    /** Every `where` predicate, rendered to the SQL it would send. */
+    where: { sql: string; params: unknown[] }[];
+  } = {
     values: [],
     set: [],
     order: [],
+    where: [],
   };
   const dialect = new PgDialect();
   function nextChain(): unknown {
@@ -42,7 +49,10 @@ function makeFakeDb(queue: unknown[]) {
     Object.assign(chain, {
       values: passthrough((a) => captured.values.push(a)),
       set: passthrough((a) => captured.set.push(a)),
-      where: passthrough(),
+      where: passthrough((a) => {
+        const { sql, params } = dialect.sqlToQuery(a as unknown as SQL);
+        captured.where.push({ sql, params });
+      }),
       limit: passthrough(),
       from: passthrough(),
       orderBy: passthrough(),
@@ -124,6 +134,32 @@ describe('signing in with a switched-off account', () => {
   });
 });
 
+describe('the accounts a change request\'s approvers resolve to', () => {
+  it('are read in one indexed query through the email blind index, live accounts only, keyed by canonical address', async () => {
+    const { db, captured } = makeFakeDb([[{ id: 'user-1', email: 'Alice@Example.com', name: 'Alice' }]]);
+    const svc = new AuthService(db, makeConfig());
+    const found = await svc.findActiveAccountsByEmail(['ALICE@example.com', 'alice@example.com', 'bob@example.com']);
+    // One read, by the blind index, with the addresses canonicalised and
+    // deduplicated, and a switched-off account excluded in the query itself.
+    expect((db as unknown as { select: ReturnType<typeof vi.fn> }).select).toHaveBeenCalledTimes(1);
+    expect(captured.where).toHaveLength(1);
+    expect(captured.where[0]!.sql).toMatch(/"users"."email_bidx" in \(\$1, \$2\) and "users"."deactivated_at" is null/);
+    // The blind-index column hashes each address with the handle's key as
+    // the query is sent; what was asked for is the canonical plain address.
+    expect(captured.where[0]!.params.map((p) => (p as { plain: string }).plain)).toEqual(['alice@example.com', 'bob@example.com']);
+    // Keyed by the canonical address, whatever spelling the row holds.
+    expect([...found.keys()]).toEqual(['alice@example.com']);
+    expect(found.get('alice@example.com')).toEqual({ id: 'user-1', email: 'Alice@Example.com', name: 'Alice' });
+  });
+
+  it('asks nothing for no addresses', async () => {
+    const { db } = makeFakeDb([]);
+    const svc = new AuthService(db, makeConfig());
+    expect(await svc.findActiveAccountsByEmail([])).toEqual(new Map());
+    expect((db as unknown as { select: ReturnType<typeof vi.fn> }).select).not.toHaveBeenCalled();
+  });
+});
+
 describe('a session that outlives a deactivation', () => {
   it('stops being accepted once the account is switched off', async () => {
     const { db } = makeFakeDb([[ROW], [{ deactivatedAt: new Date() }]]);

package/src/modules/auth/account-hooks.ts

@@ -1,5 +1,6 @@
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
+import { ListenerSeam, type NotifyingListener } from '../../shared/listener-seam.js';
 
 const log = logger('accounts');
 
@@ -24,13 +25,10 @@ export interface AccountInvitedEvent {
 
 /**
  * A listener answers how it reached the person — a non-empty channel name,
- * `'email'` say — or null when it did not (nothing configured, the send
- * failed). It is awaited: the admin's answer says who was notified,
- * truthfully, so a listener bounds its own wait. A throw is logged and
- * counts as null; it never fails the invite. An empty name is no channel and
- * counts as null too.
+ * `'email'` say — or null when it did not; the rule is {@link NotifyingListener}'s:
+ * awaited, a throw logged and counted as null, never failing the invite.
  */
-export type AccountInvitedHook = (event: AccountInvitedEvent) => Promise<string | null>;
+export type AccountInvitedHook = NotifyingListener<AccountInvitedEvent>;
 
 /**
  * Core's seam for "an account was invited": a deployment (the cloud with its
@@ -46,24 +44,18 @@ export interface IAccountHooks {
 }
 
 export class AccountHooks implements IAccountHooks {
-  private readonly invited: AccountInvitedHook[] = [];
+  // The account exists whether or not the person was told: the admin's
+  // answer says they were not, and the admin sends the link themselves.
+  private readonly invited = new ListenerSeam<AccountInvitedEvent>(
+    log,
+    'an account-invited listener failed; the person was not notified by it:',
+  );
 
   onAccountInvited(hook: AccountInvitedHook): void {
-    this.invited.push(hook);
+    this.invited.add(hook);
   }
 
-  async runAccountInvited(event: AccountInvitedEvent): Promise<string[]> {
-    const notified: string[] = [];
-    for (const hook of this.invited) {
-      try {
-        const channel = await hook(event);
-        if (channel !== null && channel !== '') notified.push(channel);
-      } catch (err) {
-        // The account exists whether or not the person was told: the admin's
-        // answer says they were not, and the admin sends the link themselves.
-        log.error('an account-invited listener failed; the person was not notified by it:', { err });
-      }
-    }
-    return notified;
+  runAccountInvited(event: AccountInvitedEvent): Promise<string[]> {
+    return this.invited.run(event);
   }
 }

package/src/modules/auth/auth.service.ts

@@ -1,9 +1,9 @@
 import jwt from 'jsonwebtoken';
-import { and, eq, getTableColumns, isNotNull, isNull, sql } from 'drizzle-orm';
+import { and, eq, getTableColumns, inArray, isNotNull, isNull, sql } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { users } from '../database/schema.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
+import { canonicalEmail } from '../../shared/email-identity.js';
 import {
   AccountAdmissionRefusedError,
   AccountChangeRefusedError,
@@ -863,26 +863,27 @@ export class AuthService implements IAccountSwitchGuard {
   }
 
   /**
-   * Resolve a set of `authorId` hashes back to the app users that produced
-   * them. Used by the PR list to display the human who triggered each PR
-   * instead of the shared GitHub service account.
+   * The live accounts behind a set of addresses — the approvers of a change
+   * request just opened, which the workflow module hands to the deployment's
+   * notification listeners as people with accounts (`ApproverAccounts`).
    *
-   * Loads all users and hashes them in-process rather than indexing on a
-   * stored hash column — the user table is small (one row per team member)
-   * and refreshes are infrequent (PR list polls at 60s), so the cost is
-   * negligible and we avoid carrying a denormalised hash column.
+   * One indexed read through the email's blind index, never a scan of every
+   * account: this is asked on every change request opened, and a deployment
+   * is as large as it is. Switched-off accounts are left out — a person who
+   * cannot act on a request is not told of it — so a caller that needs them
+   * asks another way. Keyed by the canonical address asked for.
    */
-  async findUsersByEmailHash(
-    hashes: Set<string>,
+  async findActiveAccountsByEmail(
+    emails: readonly string[],
   ): Promise<Map<string, { id: string; email: string; name: string }>> {
     const result = new Map<string, { id: string; email: string; name: string }>();
-    if (hashes.size === 0) return result;
-    const rows = await this.db.select().from(users);
-    for (const row of rows) {
-      const h = hashEmail(row.email);
-      if (!hashes.has(h)) continue;
-      result.set(h, { id: row.id, email: row.email, name: row.name });
-    }
+    const canonical = [...new Set(emails.map((e) => canonicalEmail(e)).filter(Boolean))];
+    if (canonical.length === 0) return result;
+    const rows = await this.db
+      .select({ id: users.id, email: users.email, name: users.name })
+      .from(users)
+      .where(and(inArray(users.emailBidx, canonical), isNull(users.deactivatedAt)));
+    for (const row of rows) result.set(canonicalEmail(row.email), { id: row.id, email: row.email, name: row.name });
     return result;
   }
 

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

@@ -550,7 +550,10 @@ export const agentConnections = pgTable('agent_connections', {
  * `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.
+ * retires the old row (`rotated_at`) and inserts a new one. A retired row's
+ * access token still verifies until its own expiry, unless the row is then
+ * revoked: by a revoke, a sign-out, or its refresh token's one allowed replay
+ * within the reuse grace, which revokes it in the statement that admits it.
  *
  * `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
@@ -569,6 +572,18 @@ export const oauthTokens = pgTable('oauth_tokens', {
   expiresAt: timestamp('expires_at').notNull(),
   refreshExpiresAt: timestamp('refresh_expires_at'),
   revokedAt: timestamp('revoked_at'),
+  /**
+   * When a refresh of this row's refresh token minted its successor. Set by
+   * rotation and never by a revoke, so the two are told apart: a rotated
+   * row's access token still verifies until its own expiry, and its refresh
+   * token is honoured once more within the reuse grace (see
+   * `exchangeRefreshToken`), a replay that revokes the row — access token
+   * included — in the statement that admits it; a revoked row does neither.
+   * Null on a row whose refresh token has not been used, and on rows from
+   * before the column existed, which rotation then marks as it does any
+   * other.
+   */
+  rotatedAt: timestamp('rotated_at'),
   lastUsedAt: timestamp('last_used_at'),
   createdAt: timestamp('created_at').defaultNow().notNull(),
 }, (t) => ({

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);
+});