Revoke tokens if authorization code presented a second time

[jspahrsummers]

Follow-up from #151.

[felixweinberger]

@pcarleton - we've done a bunch of OAuth 2.1 work since this was opened. Is this still relevant or can it be closed?

[mcp-claude]

confirmed on v1.x (bf1e022b). main branch has no server-side OAuth handler (architecture changed), so this only affects v1.x.

when an authorization code is replayed after it has already been exchanged, token.ts correctly returns 400 but does not revoke the access tokens issued from the first exchange. per OAuth 2.1 §4.1.3, the server MUST deny the request and SHOULD revoke all tokens previously issued for that code.

workaround: none at the framework level. custom providers can mitigate by tracking code→token mappings internally, but the token.ts handler never calls any revocation path on reuse.

the fix requires:

1. add an optional revokeTokensForAuthorizationCode(client, code): Promise<void> to OAuthServerProvider in src/server/auth/provider.ts
2. in src/server/auth/handlers/token.ts, after the code-exchange call fails, call provider.revokeTokensForAuthorizationCode?.(client, code) before rethrowing
3. implement the method in src/examples/server/demoInMemoryOAuthProvider.ts

repro script

// repro.ts — run with: npx tsx repro.ts
import { randomUUID } from 'node:crypto';
import { generateChallenge as generateCodeChallenge } from './node_modules/pkce-challenge/dist/index.node.js';
import type { AuthorizationParams, OAuthServerProvider } from './src/server/auth/provider.js';
import type { OAuthRegisteredClientsStore } from './src/server/auth/clients.js';
import type { OAuthClientInformationFull, OAuthTokenRevocationRequest, OAuthTokens } from './src/shared/auth.js';
import type { AuthInfo } from './src/server/auth/types.js';

class MinimalClientsStore implements OAuthRegisteredClientsStore {
  private clients = new Map<string, OAuthClientInformationFull>();
  async getClient(id: string) { return this.clients.get(id); }
  async registerClient(c: OAuthClientInformationFull) { this.clients.set(c.client_id, c); return c; }
}

class MinimalAuthProvider implements OAuthServerProvider {
  clientsStore = new MinimalClientsStore();
  private codes = new Map<string, { params: AuthorizationParams; client: OAuthClientInformationFull }>();
  private tokens = new Map<string, AuthInfo>();

  async authorize() {}

  async challengeForAuthorizationCode(_client: OAuthClientInformationFull, code: string): Promise<string> {
    const entry = this.codes.get(code);
    if (!entry) throw new Error('Invalid authorization code');
    return entry.params.codeChallenge;
  }

  async exchangeAuthorizationCode(client: OAuthClientInformationFull, code: string): Promise<OAuthTokens> {
    const entry = this.codes.get(code);
    if (!entry) throw new Error('Invalid or already-used authorization code');
    this.codes.delete(code);
    const token = randomUUID();
    this.tokens.set(token, { token, clientId: client.client_id, scopes: entry.params.scopes ?? [],
      expiresAt: Math.floor(Date.now() / 1000) + 3600, resource: entry.params.resource, type: 'access' });
    return { access_token: token, token_type: 'bearer', expires_in: 3600 };
  }

  async exchangeRefreshToken(): Promise<OAuthTokens> { throw new Error('not implemented'); }
  async verifyAccessToken(token: string): Promise<AuthInfo> {
    const info = this.tokens.get(token);
    if (!info) throw new Error('Invalid token');
    return info;
  }

  issueCode(client: OAuthClientInformationFull, params: AuthorizationParams): string {
    const code = randomUUID();
    this.codes.set(code, { client, params });
    return code;
  }
  isTokenValid(token: string): boolean { return this.tokens.has(token); }
}

async function main() {
  const provider = new MinimalAuthProvider();
  const client: OAuthClientInformationFull = {
    client_id: 'client-1', client_name: 'Test', redirect_uris: ['http://localhost/callback'],
    response_types: ['code'], grant_types: ['authorization_code'], token_endpoint_auth_method: 'none',
  };
  const codeVerifier = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
  const codeChallenge = await generateCodeChallenge(codeVerifier);
  const code = provider.issueCode(client, { codeChallenge, redirectUri: 'http://localhost/callback', scopes: ['read'] });

  const attackerTokens = await provider.exchangeAuthorizationCode(client, code, codeVerifier);
  const attackerToken = attackerTokens.access_token;
  console.log(`attacker token valid: ${provider.isTokenValid(attackerToken)}`); // true

  try { await provider.exchangeAuthorizationCode(client, code, codeVerifier); } catch {}
  // token SHOULD have been revoked, but:
  console.log(`attacker token still valid after reuse: ${provider.isTokenValid(attackerToken)}`); // true (BUG)
  process.exit(provider.isTokenValid(attackerToken) ? 1 : 0);
}
main();

command + output

$ npx tsx repro.ts
[1] Authorization code issued: 57f4390a-...
[2] Attacker exchanged code, got token: 971539df-...
    Token valid after first exchange: true
[3] Second code exchange error (expected): Invalid or already-used authorization code
[4] Attacker's token still valid after code reuse detected: true

BUG CONFIRMED: token issued for the (now-replayed) code was NOT revoked.

exit code 1

code path

src/server/auth/handlers/token.ts:88-116 — authorization_code branch:

• line 102: provider.challengeForAuthorizationCode(client, code) — succeeds on first call (code not yet consumed); throws on second call (code deleted by first exchangeAuthorizationCode)
• line 109: provider.exchangeAuthorizationCode(...) — deletes the code and mints tokens on first call; throws on second call because code is gone
• lines 143-151: the catch block returns a 400 error — no revocation call happens

OAuthServerProvider interface (src/server/auth/provider.ts:17-73) has revokeToken?(client, request) but no method to look up or bulk-revoke tokens by originating code. the handler cannot revoke without a new interface method.

suggested fix

// src/server/auth/provider.ts
     revokeToken?(client: OAuthClientInformationFull, request: OAuthTokenRevocationRequest): Promise<void>;
 
+    /**
+     * Revokes all tokens previously issued for the given authorization code.
+     *
+     * Called when authorization code reuse is detected (OAuth 2.1 §4.1.3): if a code is
+     * presented after it has already been exchanged, all tokens issued for that code must
+     * be revoked. If unimplemented, code-reuse revocation is not supported.
+     */
+    revokeTokensForAuthorizationCode?(client: OAuthClientInformationFull, authorizationCode: string): Promise<void>;
+
     /**
      * Whether to skip local PKCE validation.

// src/server/auth/handlers/token.ts
                     const skipLocalPkceValidation = provider.skipLocalPkceValidation;
 
-                    // Perform local PKCE validation unless explicitly skipped
-                    if (!skipLocalPkceValidation) {
-                        const codeChallenge = await provider.challengeForAuthorizationCode(client, code);
-                        if (!(await verifyChallenge(code_verifier, codeChallenge))) {
-                            throw new InvalidGrantError('code_verifier does not match the challenge');
+                    try {
+                        if (!skipLocalPkceValidation) {
+                            const codeChallenge = await provider.challengeForAuthorizationCode(client, code);
+                            if (!(await verifyChallenge(code_verifier, codeChallenge))) {
+                                throw new InvalidGrantError('code_verifier does not match the challenge');
+                            }
                         }
-                    }
-
-                    const tokens = await provider.exchangeAuthorizationCode(
-                        client, code,
-                        skipLocalPkceValidation ? code_verifier : undefined,
-                        redirect_uri,
-                        resource ? new URL(resource) : undefined
-                    );
-                    res.status(200).json(tokens);
+                        const tokens = await provider.exchangeAuthorizationCode(
+                            client, code,
+                            skipLocalPkceValidation ? code_verifier : undefined,
+                            redirect_uri,
+                            resource ? new URL(resource) : undefined
+                        );
+                        res.status(200).json(tokens);
+                    } catch (codeError) {
+                        // OAuth 2.1 §4.1.3: revoke any tokens previously issued for this code
+                        await provider.revokeTokensForAuthorizationCode?.(client, code);
+                        throw codeError;
+                    }
                     break;

// src/examples/server/demoInMemoryOAuthProvider.ts
     private tokens = new Map<string, AuthInfo>();
+    private codeToTokens = new Map<string, string[]>();
 
     ...
 
         this.tokens.set(token, tokenData);
+        this.codeToTokens.set(authorizationCode, [token]);
 
         return { access_token: token, ... };
     }
 
+    async revokeTokensForAuthorizationCode(_client: OAuthClientInformationFull, authorizationCode: string): Promise<void> {
+        const tokens = this.codeToTokens.get(authorizationCode);
+        if (tokens) {
+            for (const token of tokens) {
+                this.tokens.delete(token);
+            }
+            this.codeToTokens.delete(authorizationCode);
+        }
+    }

test to verify: asserts that when a code-exchange request fails (simulating code reuse), revokeTokensForAuthorizationCode is called on the provider with the client and the presented code.