feat: revoke existing grants on re-authorization by default

[mattzcarey]

Summary

Two related grant-security improvements, shipped as one body of work:

1. Revoke existing grants on re-authorization — When a user goes through the OAuth flow again for the same client, all previous grants (and their tokens) for that user+client are now revoked after the new grant is stored. This fixes infinite re-auth loops caused by stale props in old grants (issue No provision to restart the authorization flow if the oauth server to the worker oauth client does not provide refresh tokens #34).

2. Revoke tokens on authorization code reuse (RFC 6749 §10.5) — When an authorization code that has already been exchanged is presented again, the provider now revokes the grant and all tokens from the original exchange. This prevents authorization code replay attacks. (Originally PR Revoke tokens on authorization code reuse #157 by @rc4, squashed into this PR.)

Breaking behavior change

completeAuthorization() now defaults revokeExistingGrants to true. Previously, re-authorizing the same user+client created an additional grant, leaving old tokens valid. Now, old grants are revoked by default. This is an edge case but it could be hit by some MCP clients.

If your application relies on multiple concurrent grants per user+client, set revokeExistingGrants: false to preserve the old behavior:

await oauthProvider.completeAuthorization({
  request: authRequest,
  userId: user.id,
  metadata: { ... },
  scope: ['read', 'write'],
  props: { ... },
  revokeExistingGrants: false,
});

MCP servers should not need to preserve this so setting the default to true here but allowing opt out for developers who need it.

Changes

src/oauth-provider.ts

• Added revokeExistingGrants?: boolean option to CompleteAuthorizationOptions (defaults to true)
• Before creating the new grant, collects all existing grant IDs for the same userId + clientId (with cursor-based pagination for >1000 grants)
• After the new grant is stored, revokes old grants in parallel via Promise.all
• Revocation is best-effort (wrapped in try/catch) — if it fails, the new grant is already stored and the authorization response still succeeds
• Both implicit flow and authorization code flow paths are covered
• Added auth code reuse detection: when authCodeId is absent on a grant, calls revokeGrant() (best-effort) and returns invalid_grant

__tests__/reauth-grant-revocation.test.ts (new, 5 tests)

• Demonstrates stale props persist when revokeExistingGrants: false (the bug)
• Demonstrates the infinite re-auth loop scenario with tokenExchangeCallback throwing invalid_grant
• Old access tokens return 401 after re-authorization (fix works)
• Old refresh tokens return 400 after re-authorization (fix works)
• Other clients' grants are unaffected

__tests__/oauth-provider.test.ts (1 new test)

• Auth code reuse: second exchange returns invalid_grant, all tokens and the grant are revoked

.changeset/fix-revoke-existing-grants.md

• Minor version bump (default behavior change)

RFC / spec alignment

• RFC 6749 §10.5: Authorization code reuse detection and token revocation — now implemented
• Grant Management for OAuth 2.0 (OpenID FAPI draft): Defines a replace action that does exactly what revokeExistingGrants does
• Most production OAuth servers (Auth0, Okta) revoke old refresh tokens on re-authorization as standard practice
• Neither OAuth 2.0 (RFC 6749), OAuth 2.1, nor the MCP spec mandate or prohibit revoking old grants on re-authorization — this is a defensible server-side policy choice

Test plan

• 222 tests pass (216 existing + 5 re-auth + 1 auth code reuse, no regressions)
• Formatting passes (prettier --check)
• E2E validation with MCP Inspector + real agents SDK MCP server

Fixes #34 | Includes #157

[changeset-bot]

🦋 Changeset detected

Latest commit: 19bbf24

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/workers-oauth-provider	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/workers-oauth-provider/@cloudflare/workers-oauth-provider@144

commit: 19bbf24

[mattzcarey]

gonna release this as a minor but the last one was massive so waiting a couple of days to test this better.