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

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/oauth/bevel-oauth-provider.ts

@@ -32,9 +32,27 @@ import { signAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 // (`<tenant>-int_`).
 const TOKEN_BYTES = 32;
 
+/** A transaction's handle, for the statements a refresh must land together. */
+type Tx = Parameters<Parameters<Database['transaction']>[0]>[0];
+
 const ACCESS_TTL_MS = 60 * 60_000; // 1 hour
 const REFRESH_TTL_MS = 30 * 24 * 60 * 60_000; // 30 days, rotated on use
 const CODE_TTL_MS = 60_000; // exchanged within seconds of Finish
+/**
+ * How long a refresh token that was just rotated is honoured once more.
+ *
+ * Rotation makes a refresh token single-use, and a client that refreshes
+ * from two places at once — Claude's hosted apps refresh proactively before
+ * expiry AND reactively on a 401, and a scheduled task runs beside the chat
+ * that shares its connector — presents the same token twice. The second
+ * presentation used to be answered `invalid_grant`, which a client reads as
+ * "the credential is dead" and turns into a re-authorization prompt every
+ * day or two. Within this window the loser is answered as the winner was,
+ * with a fresh pair; past it, reuse is refused, which is what makes a stolen
+ * token's later replay fail. Sixty seconds is the window Okta allows at most
+ * and Auth0 recommends for exactly this case.
+ */
+const REFRESH_REUSE_GRACE_MS = 60_000;
 /**
  * How often, at most, one process stamps an agent connection's `last_used_at`.
  * The Audit log shows the instant relatively ("4 minutes ago"), so a minute's
@@ -261,34 +279,54 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     _resource?: URL,
   ): Promise<OAuthTokens> {
     const now = new Date();
-    // Rotation: atomically revoke the presented refresh token; the winner of
-    // a concurrent double-refresh gets the new pair, the loser a clean 400.
-    // `clientId` is IN the predicate so a caller presenting a valid refresh
-    // token under the WRONG client can't revoke (kill) another client's
-    // session — the update matches nothing and their token stays live.
-    const [row] = await this.deps.db
-      .update(oauthTokens)
-      .set({ revokedAt: now })
-      .where(
-        and(
-          eq(oauthTokens.refreshTokenHash, hashToken(refreshToken)),
-          eq(oauthTokens.clientId, client.client_id),
-          isNull(oauthTokens.revokedAt),
-        ),
-      )
-      .returning();
-    if (!row) {
-      throw new InvalidGrantError('Invalid or revoked refresh token');
+    const hash = hashToken(refreshToken);
+    const clientId = client.client_id;
+    // The row is READ first and judged whole, and consumed only once every
+    // check has passed: a refusal must leave a token the client could still
+    // use with a different request (a narrower scope) usable, and nothing
+    // may be minted or retired on a token that is expired, revoked, or
+    // bound to a revoked agent. Looked up by hash AND client, so a caller
+    // presenting a valid refresh token under the WRONG client learns
+    // nothing and changes nothing.
+    const [seen] = await this.deps.db
+      .select()
+      .from(oauthTokens)
+      .where(and(eq(oauthTokens.refreshTokenHash, hash), eq(oauthTokens.clientId, clientId)))
+      .limit(1);
+    if (!seen) return this.refuseRefresh('unknown refresh token for this client', 'Invalid or revoked refresh token', { clientId });
+    const rotatedAgoMs = seen.rotatedAt ? now.getTime() - seen.rotatedAt.getTime() : null;
+    const rotatedAgo = rotatedAgoMs === null ? null : `${Math.round(rotatedAgoMs / 1000)} s ago`;
+    if (seen.revokedAt) {
+      return this.refuseRefresh(
+        rotatedAgo ? `refresh token rotated ${rotatedAgo} and already replayed once, or revoked since` : 'refresh token revoked',
+        'Invalid or revoked refresh token',
+        seen,
+      );
+    }
+    if (rotatedAgoMs !== null && rotatedAgoMs > REFRESH_REUSE_GRACE_MS) {
+      return this.refuseRefresh(
+        `refresh token rotated ${rotatedAgo}, past the ${REFRESH_REUSE_GRACE_MS / 1000} s reuse grace`,
+        'Invalid or revoked refresh token',
+        seen,
+      );
     }
-    if (row.refreshExpiresAt && row.refreshExpiresAt <= now) {
-      throw new InvalidGrantError('Refresh token expired');
+    if (seen.refreshExpiresAt && seen.refreshExpiresAt <= now) {
+      return this.refuseRefresh('refresh token expired', 'Refresh token expired', seen);
     }
     // Scope may only narrow on refresh (RFC 6749 §6).
-    let scope = row.scope;
+    let scope = seen.scope;
     if (scopes?.length) {
-      const granted = new Set((row.scope ?? '').split(' ').filter(Boolean));
+      const granted = new Set((seen.scope ?? '').split(' ').filter(Boolean));
       if (!scopes.every((s) => granted.has(s))) {
-        throw new InvalidScopeError('Requested scope exceeds the originally granted scope');
+        // `invalid_scope` to the client (RFC 6749 §5.2), since the token
+        // itself is fine — and untouched, so the same token refreshes with
+        // the scope it was granted.
+        return this.refuseRefresh(
+          'requested scope exceeds the originally granted scope',
+          'Requested scope exceeds the originally granted scope',
+          seen,
+          (message) => new InvalidScopeError(message),
+        );
       }
       scope = scopes.join(' ');
     }
@@ -299,13 +337,115 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     // mint an unrevoked pair — the revoke undone by a millisecond. A token
     // from before connections existed has none to stay on and is placed
     // under one as a first mint would be.
-    if (row.connectionId) {
-      if (!(await this.isConnectionLive(row.connectionId))) {
-        throw new InvalidGrantError('Access for this agent was revoked');
+    if (seen.connectionId && !(await this.isConnectionLive(seen.connectionId))) {
+      return this.refuseRefresh('access for this agent was revoked', 'Access for this agent was revoked', seen);
+    }
+
+    // Consume, with the state the row was judged in as the predicate, so two
+    // refreshes racing on one row have exactly one winner. A fresh token is
+    // RETIRED (`rotatedAt`), not revoked: its pair's access token stays good
+    // until its own expiry, an hour at most, so a runner still holding it is
+    // not cut off mid-task by a refresh another runner made, while a revoke
+    // or a sign-out still ends it at once. A token already retired within
+    // the reuse grace — the loser of a double refresh, which is what a client
+    // refreshing from two places at once produces — is honoured ONCE more,
+    // and the replay revokes the row in the same statement that admits it,
+    // so a third presentation, or two replays racing, find nothing. That does
+    // end the retired pair's access token: the runner that replayed holds the
+    // fresh pair from here, and the rotation's winner holds its own.
+    //
+    // The consume and the mint are ONE transaction: a token is retired or
+    // replayed only in the same commit that hands its holder the new pair, so
+    // a mint that fails leaves the token exactly as it was — never spent with
+    // nothing to show for it, which for a replayed token would be the lockout
+    // this whole path exists to prevent. A token from before connections
+    // existed is placed under one first, outside the transaction, as a first
+    // mint would place it: finding or making a connection is idempotent.
+    const connectionId = seen.connectionId ?? (await this.ensureConnection(seen.userId, seen.clientId));
+    // The opportunistic prune too runs BEFORE the transaction opens, on the
+    // pool: inside it, this request would hold a transaction's client while
+    // waiting for a second one, and a burst of refreshes the size of the pool
+    // would have every one of them wait out the connect timeout.
+    await this.pruneTokenTables(now.getTime());
+    const { consumed, tokens, replayed } = await this.deps.db.transaction(async (tx) => {
+      let row = rotatedAgoMs === null ? await this.retireFresh(tx, hash, clientId, now) : undefined;
+      let replayed = rotatedAgoMs !== null;
+      if (!row) {
+        // Either a retired token within the grace, or a fresh one that lost
+        // its rotation to a concurrent refresh between the read above and the
+        // retire — which makes it the loser of a double refresh, and so
+        // replayable now.
+        row = await this.replayRetired(tx, hash, clientId, now);
+        replayed = true;
+      }
+      if (!row) {
+        return this.refuseRefresh('refresh token rotated or revoked by a concurrent request', 'Invalid or revoked refresh token', seen);
       }
-      this.noteConnectionUse(row.connectionId);
+      const tokens = await this.mintTokens(row.userId, row.clientId, scope, row.resource, connectionId, tx);
+      return { consumed: row, tokens, replayed };
+    });
+    if (replayed) {
+      log.info(
+        `refresh replayed ${Math.round((now.getTime() - consumed.rotatedAt!.getTime()) / 1000)} s after its rotation, within the reuse grace; a fresh pair is minted`,
+        { clientId, connectionId, userId: consumed.userId },
+      );
     }
-    return this.mintTokens(row.userId, row.clientId, scope, row.resource, row.connectionId ?? undefined);
+    this.noteConnectionUse(connectionId);
+    return tokens;
+  }
+
+  /** Retire a fresh refresh token: the one statement that wins a rotation. */
+  private async retireFresh(tx: Tx, hash: string, clientId: string, now: Date) {
+    const [row] = await tx
+      .update(oauthTokens)
+      .set({ rotatedAt: now })
+      .where(
+        and(
+          eq(oauthTokens.refreshTokenHash, hash),
+          eq(oauthTokens.clientId, clientId),
+          isNull(oauthTokens.revokedAt),
+          isNull(oauthTokens.rotatedAt),
+        ),
+      )
+      .returning();
+    return row;
+  }
+
+  /** Consume a retired refresh token's one replay: revoked in the statement that admits it, within the grace only. */
+  private async replayRetired(tx: Tx, hash: string, clientId: string, now: Date) {
+    const since = new Date(now.getTime() - REFRESH_REUSE_GRACE_MS);
+    const [row] = await tx
+      .update(oauthTokens)
+      .set({ revokedAt: now })
+      .where(
+        and(
+          eq(oauthTokens.refreshTokenHash, hash),
+          eq(oauthTokens.clientId, clientId),
+          isNull(oauthTokens.revokedAt),
+          gt(oauthTokens.rotatedAt, since),
+        ),
+      )
+      .returning();
+    return row;
+  }
+
+  /**
+   * The one place a refresh is refused: logged with its reason, never the
+   * token, then the client's error — `invalid_grant` unless the caller says
+   * otherwise (a widened scope is `invalid_scope`).
+   */
+  private refuseRefresh(
+    reason: string,
+    clientMessage: string,
+    row: { clientId: string; connectionId?: string | null; userId?: string },
+    error: (message: string) => Error = (message) => new InvalidGrantError(message),
+  ): never {
+    log.warn(`refresh refused: ${reason}`, {
+      clientId: row.clientId,
+      connectionId: row.connectionId ?? null,
+      userId: row.userId ?? null,
+    });
+    throw error(clientMessage);
   }
 
   async verifyAccessToken(token: string): Promise<AuthInfo> {
@@ -413,10 +553,15 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     // back to re-authorise into the same one.)
     const connectionId = revoked.find((r) => r.connectionId)?.connectionId;
     if (!connectionId) return;
+    // A rotated row is not a live token: its successor is the live one, and
+    // counting it would keep a connection open on a refresh token nobody can
+    // use any more.
     const [{ live }] = await this.deps.db
       .select({ live: count() })
       .from(oauthTokens)
-      .where(and(eq(oauthTokens.connectionId, connectionId), isNull(oauthTokens.revokedAt)));
+      .where(
+        and(eq(oauthTokens.connectionId, connectionId), isNull(oauthTokens.revokedAt), isNull(oauthTokens.rotatedAt)),
+      );
     if (Number(live) > 0) return;
     await this.deps.db
       .update(agentConnections)
@@ -428,6 +573,12 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    * @param connectionId The agent connection the pair belongs to, when the
    *   caller already holds one (a refresh: the consumed token's). Absent on a
    *   first mint, which finds or makes the live connection for (user, client).
+   * @param tx The transaction the insert belongs to, when the mint must land
+   *   with the statement that consumed the token it replaces (a refresh).
+   *   The prune is then the caller's, before the transaction opens: a
+   *   best-effort statement that fails inside a transaction would abort the
+   *   mint it is meant to spare, and one on the pool from inside it would
+   *   hold this request's client while waiting for another.
    */
   private async mintTokens(
     userId: string,
@@ -435,30 +586,17 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     scope: string | null,
     resource: string | null,
     connectionId?: string,
+    tx?: Tx,
   ): Promise<OAuthTokens> {
     const accessToken = this.deps.tokenPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const refreshToken = this.refreshPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const now = Date.now();
-    // Opportunistic pruning, piggybacked on mint (one per sign-in / refresh —
-    // no scheduler needed) so the oauth tables stay bounded: a token row whose
-    // refresh window has closed can never authenticate again (revoked-but-live
-    // rows are kept until then, so revocation stays observable), and an auth
-    // code past its 60s TTL can never be exchanged. Best-effort — a cleanup
-    // hiccup must not fail the token issuance itself.
-    try {
-      const cutoff = new Date(now);
-      await this.deps.db.delete(oauthTokens).where(
-        or(
-          lt(oauthTokens.refreshExpiresAt, cutoff),
-          and(isNull(oauthTokens.refreshExpiresAt), lt(oauthTokens.expiresAt, cutoff)),
-        ),
-      );
-      await this.deps.db.delete(oauthAuthCodes).where(lt(oauthAuthCodes.expiresAt, cutoff));
-    } catch (err) {
-      log.warn('token-table prune failed (non-fatal):', { err });
-    }
+    // A mint of its own (a sign-in) prunes here; a refresh pruned before its
+    // transaction opened.
+    if (!tx) await this.pruneTokenTables(now);
     const boundTo = connectionId ?? (await this.ensureConnection(userId, clientId));
-    await this.deps.db.insert(oauthTokens).values({
+    const sink: Tx | Database = tx ?? this.deps.db;
+    await sink.insert(oauthTokens).values({
       accessTokenHash: hashToken(accessToken),
       refreshTokenHash: hashToken(refreshToken),
       clientId,
@@ -478,6 +616,34 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     };
   }
 
+  /**
+   * Opportunistic pruning, piggybacked on every mint (one per sign-in /
+   * refresh — no scheduler needed) so the oauth tables stay bounded: a token
+   * row whose refresh window has closed can never authenticate again
+   * (revoked-but-live rows are kept until then, so revocation stays
+   * observable), a rotated row can authenticate for its access token's hour
+   * and be replayed for the reuse grace and past both is history only, and
+   * an auth code past its 60s TTL can never be exchanged. Best-effort, on the
+   * pool and never inside a transaction — a cleanup hiccup must not fail the
+   * token issuance itself.
+   */
+  private async pruneTokenTables(now: number): Promise<void> {
+    try {
+      const cutoff = new Date(now);
+      const rotatedCutoff = new Date(now - ACCESS_TTL_MS - REFRESH_REUSE_GRACE_MS);
+      await this.deps.db.delete(oauthTokens).where(
+        or(
+          lt(oauthTokens.refreshExpiresAt, cutoff),
+          and(isNull(oauthTokens.refreshExpiresAt), lt(oauthTokens.expiresAt, cutoff)),
+          lt(oauthTokens.rotatedAt, rotatedCutoff),
+        ),
+      );
+      await this.deps.db.delete(oauthAuthCodes).where(lt(oauthAuthCodes.expiresAt, cutoff));
+    } catch (err) {
+      log.warn('token-table prune failed (non-fatal):', { err });
+    }
+  }
+
   /**
    * The live `agent_connections` row for (user, client) — found, or made on
    * the first mint for the pair. A refresh finds the row the sign-in made, so

package/src/modules/workflow/__tests__/change-request-hooks.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ChangeRequestHooks, type ChangeRequestOpenedEvent } from '../change-request-hooks.js';
+
+const EVENT: ChangeRequestOpenedEvent = {
+  number: 12,
+  title: 'Tidy the glossary',
+  sourceBranch: 'ali/x',
+  targetBranch: 'main',
+  openedBy: { id: 'u-ali', email: 'ali@acme.test', name: 'Ali' },
+  approvers: [{ id: 'u-dana', email: 'dana@acme.test', name: 'Dana' }],
+  unresolvedApprovers: 0,
+  pushPending: false,
+};
+
+describe('ChangeRequestHooks: a change request was opened', () => {
+  it('notifies nobody when nothing is registered, and says so', async () => {
+    expect(await new ChangeRequestHooks().runChangeRequestOpened(EVENT)).toEqual([]);
+  });
+
+  it('runs every listener in registration order, with the event, and collects the channels that reached the approvers', async () => {
+    const hooks = new ChangeRequestHooks();
+    const seen: string[] = [];
+    hooks.onChangeRequestOpened(async (event) => {
+      seen.push(`mail:#${event.number}:${event.approvers.map((a) => a.email).join(',')}`);
+      return 'email';
+    });
+    hooks.onChangeRequestOpened(async () => {
+      seen.push('chat');
+      return null;
+    });
+    hooks.onChangeRequestOpened(async () => {
+      seen.push('sms');
+      return 'sms';
+    });
+    expect(await hooks.runChangeRequestOpened(EVENT)).toEqual(['email', 'sms']);
+    expect(seen).toEqual(['mail:#12:dana@acme.test', 'chat', 'sms']);
+  });
+
+  it('a listener that throws counts as not having notified, and stops nothing', async () => {
+    const hooks = new ChangeRequestHooks();
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      hooks.onChangeRequestOpened(async () => {
+        throw new Error('smtp down');
+      });
+      hooks.onChangeRequestOpened(async () => 'email');
+      expect(await hooks.runChangeRequestOpened(EVENT)).toEqual(['email']);
+      // Logged, so a failing mailer is diagnosable from the server's log.
+      expect(error).toHaveBeenCalledTimes(1);
+      expect(String(error.mock.calls[0]![0])).toContain('a change-request-opened listener failed');
+    } finally {
+      error.mockRestore();
+    }
+  });
+
+  it('an empty channel name is no channel: it counts as not having notified', async () => {
+    const hooks = new ChangeRequestHooks();
+    hooks.onChangeRequestOpened(async () => '');
+    hooks.onChangeRequestOpened(async () => 'email');
+    expect(await hooks.runChangeRequestOpened(EVENT)).toEqual(['email']);
+  });
+});