fix: use opaque state parameter in OAuth authorization flow (#41)

* fix: use opaque state parameter in OAuth authorization flow

Replace base64-encoded AuthRequest in the OAuth state parameter with
an opaque UUID token. The full AuthRequest is already stored in KV
via createOAuthState() — embedding it in the URL was redundant and
caused authorization URLs to exceed Cloudflare's size limits when
combined with CIMD client IDs or many scopes.

Security is unchanged: state is still validated via KV lookup +
SHA-256 session cookie binding + single-use deletion.

* test: assert opaque OAuth state token in e2e + unit coverage

Update OAuth tests for the opaque-state-token contract:
- cloudflare-auth.test.ts: getAuthorizationURL now takes stateToken and
  passes it through verbatim (no base64 AuthRequest).
- oauth-routes.test.ts full-flow: assert the state forwarded to Cloudflare
  is opaque, not a base64-encoded AuthRequest.
- oauth-routes.test.ts reject case: use a plain opaque token now that state
  is the KV lookup key directly.

* test: harden opaque OAuth state flow

* fix: accept in-flight legacy OAuth state

Author: mattzcarey

src/auth/cloudflare-auth.ts

@@ -1,7 +1,5 @@
 import { z } from 'zod'
 
-import type { AuthRequest } from '@cloudflare/workers-oauth-provider'
-
 import { OAuthError } from './workers-oauth-utils'
 
 /**
@@ -71,7 +69,7 @@ export async function generatePKCECodes(): Promise<PKCECodes> {
 export async function getAuthorizationURL(params: {
   client_id: string
   redirect_uri: string
-  state: AuthRequest
+  stateToken: string
   scopes: string[]
   codeChallenge: string
   oauthDomain: string
@@ -80,7 +78,7 @@ export async function getAuthorizationURL(params: {
     response_type: 'code',
     client_id: params.client_id,
     redirect_uri: params.redirect_uri,
-    state: btoa(JSON.stringify(params.state)),
+    state: params.stateToken,
     code_challenge: params.codeChallenge,
     code_challenge_method: 'S256',
     scope: params.scopes.join(' ')

src/auth/oauth-handler.ts

@@ -558,21 +558,15 @@ export async function handleTokenExchangeCallback(
  */
 async function redirectToCloudflare(
   requestUrl: string,
-  oauthReqInfo: AuthRequest,
   stateToken: string,
   codeChallenge: string,
   scopes: string[],
   additionalHeaders: Record<string, string> = {}
 ): Promise<Response> {
-  const stateWithToken: AuthRequest = {
-    ...oauthReqInfo,
-    state: stateToken
-  }
-
   const { authUrl } = await getAuthorizationURL({
     client_id: env.CLOUDFLARE_CLIENT_ID,
     redirect_uri: new URL('/oauth/callback', requestUrl).href,
-    state: stateWithToken,
+    stateToken,
     scopes,
     codeChallenge,
     oauthDomain: env.CLOUDFLARE_OAUTH_DOMAIN
@@ -617,16 +611,9 @@ export function createAuthHandlers() {
         const stateToken = await createOAuthState(oauthReqInfo, env.OAUTH_KV, codeVerifier)
         const { setCookie: sessionCookie } = await bindStateToSession(stateToken)
 
-        return redirectToCloudflare(
-          c.req.url,
-          oauthReqInfo,
-          stateToken,
-          codeChallenge,
-          defaultScopes,
-          {
-            'Set-Cookie': sessionCookie
-          }
-        )
+        return redirectToCloudflare(c.req.url, stateToken, codeChallenge, defaultScopes, {
+          'Set-Cookie': sessionCookie
+        })
       }
 
       // Client not approved - show consent dialog with scope selection
@@ -691,7 +678,6 @@ export function createAuthHandlers() {
 
       const redirectResponse = await redirectToCloudflare(
         c.req.url,
-        oauthReqInfo,
         stateToken,
         codeChallenge,
         scopesToRequest

src/auth/workers-oauth-utils.ts

@@ -10,6 +10,36 @@ const APPROVED_CLIENTS_COOKIE = '__Host-MCP_APPROVED_CLIENTS'
 const CSRF_COOKIE = '__Host-CSRF_TOKEN'
 const STATE_COOKIE = '__Host-CONSENTED_STATE'
 const ONE_YEAR_IN_SECONDS = 31536000
+const OAuthStateToken = z.uuid()
+const LegacyOAuthState = z.object({ state: OAuthStateToken }).passthrough()
+const MAX_LEGACY_OAUTH_STATE_LENGTH = 32_768
+
+function encodeBase64Utf8(value: string): string {
+  const bytes = new TextEncoder().encode(value)
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+}
+
+function decodeBase64Utf8(value: string): string {
+  const binary = atob(value)
+  return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)))
+}
+
+function parseOAuthStateToken(state: string): string | undefined {
+  const current = OAuthStateToken.safeParse(state)
+  if (current.success) return current.data
+
+  // TODO: Remove this legacy base64-JSON reader after all OAuth flows started
+  // before the opaque-state deployment have exceeded the 600-second KV TTL.
+  if (state.length > MAX_LEGACY_OAUTH_STATE_LENGTH) return undefined
+  try {
+    const legacy = LegacyOAuthState.safeParse(JSON.parse(atob(state)))
+    return legacy.success ? legacy.data.state : undefined
+  } catch {
+    return undefined
+  }
+}
 
 /**
  * OAuth error class for handling OAuth-specific errors
@@ -449,7 +479,7 @@ export function renderApprovalDialog(request: Request, options: ApprovalDialogOp
     requiredScopes = []
   } = options
 
-  const encodedState = btoa(JSON.stringify(state))
+  const encodedState = encodeBase64Utf8(JSON.stringify(state))
   const clientName = client?.clientName ? sanitizeHtml(client.clientName) : 'Unknown MCP Client'
   const requiredSet = new Set(requiredScopes)
   const categories = groupScopesByCategory(allScopes, requiredSet)
@@ -1469,7 +1499,7 @@ export async function parseRedirectApproval(
     throw new OAuthError('invalid_request', 'Missing state')
   }
 
-  const state = JSON.parse(atob(encodedState))
+  const state = JSON.parse(decodeBase64Utf8(encodedState))
   if (!state.oauthReqInfo || !state.oauthReqInfo.clientId) {
     throw new OAuthError('invalid_request', 'Invalid state data')
   }
@@ -1754,16 +1784,9 @@ export async function validateOAuthState(
     throw new OAuthError('invalid_request', 'Missing state parameter')
   }
 
-  // Decode state to extract embedded stateToken
-  let stateToken: string
-  try {
-    const decodedState = JSON.parse(atob(stateFromQuery))
-    stateToken = decodedState.state
-    if (!stateToken) {
-      throw new Error('State token not found')
-    }
-  } catch {
-    throw new OAuthError('invalid_request', 'Failed to decode state')
+  const stateToken = parseOAuthStateToken(stateFromQuery)
+  if (!stateToken) {
+    throw new OAuthError('invalid_request', 'Invalid state parameter')
   }
 
   // Validate state exists in KV

tests/auth/cloudflare-auth.test.ts

@@ -92,12 +92,12 @@ describe('generatePKCECodes', () => {
 })
 
 describe('getAuthorizationURL', () => {
-  it('builds the Cloudflare /oauth2/auth URL with S256 PKCE and encoded state', async () => {
-    const state = { clientId: 'mcp-client', redirectUri: 'https://app/cb' } as never
+  it('builds the Cloudflare /oauth2/auth URL with S256 PKCE and an opaque state token', async () => {
+    const stateToken = 'b9f1c0de-1234-4abc-9def-0123456789ab'
     const { authUrl } = await getAuthorizationURL({
       client_id: 'client-id',
       redirect_uri: 'https://mcp.example.com/oauth/callback',
-      state,
+      stateToken,
       scopes: ['user:read', 'account:read'],
       codeChallenge: 'challenge-123',
       oauthDomain: OAUTH_DOMAIN
@@ -111,8 +111,8 @@ describe('getAuthorizationURL', () => {
     expect(url.searchParams.get('code_challenge')).toBe('challenge-123')
     expect(url.searchParams.get('code_challenge_method')).toBe('S256')
     expect(url.searchParams.get('scope')).toBe('user:read account:read')
-    // State is base64-encoded JSON of the AuthRequest.
-    expect(JSON.parse(atob(url.searchParams.get('state')!))).toEqual(state)
+    // State is the opaque KV lookup token, passed through verbatim (RFC 6749 §10.12).
+    expect(url.searchParams.get('state')).toBe(stateToken)
   })
 })