Edit Event

Auth decision: Adopt PKCE flow for all OAuth providers

Content

Title*

Summary

Raw Content*

## Auth Architecture Decision — PKCE Flow

### Decision
Adopt PKCE (Proof Key for Code Exchange) as the standard OAuth flow for VCTRL.

### Context
The cookie-blocking bug revealed that our current implicit OAuth flow was fragile in strict browser environments. PKCE is the modern, recommended approach for SPAs and apps with redirects.

### What is PKCE?
PKCE adds a code verifier/challenge pair to the OAuth flow:
1. App generates a random `code_verifier`
2. App sends `code_challenge` (SHA-256 hash of verifier) with the auth request
3. After redirect, app sends `code_verifier` to exchange for token
4. Server verifies the verifier matches the challenge

This eliminates the need to store sensitive state in cookies that can be blocked.

### Supabase Support
- Supabase Auth supports PKCE natively
- Enable via: `flowType: 'pkce'` in createClient options
- Works with GitHub, Google, GitLab OAuth

### Implementation
```typescript
// lib/supabase/client.ts
const supabase = createBrowserClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  {
    auth: {
      flowType: 'pkce',
    },
  }
)
```

### Impact
- Fixes: Cookie-blocking bug
- Fixes: Cancel/retry auth state bug (PKCE verifier stored in sessionStorage, cleared on new attempt)
- Improves: Security posture (eliminates token in URL fragment)
- Improves: Future-proofing (PKCE is the OAuth 2.1 standard)

### Applies To
- GitHub OAuth (current)
- Google OAuth (planned)
- GitLab OAuth (V3)

### Status
Implemented in branch `feat/pkce-auth`. Merge after testing.

Classification

Category*

Event Type*

Severity*

Status*

Event Date*