# Unified OAuth Auth Hub Implementation Plan

## Overview
Consolidate Challonge OAuth, API keys, and client credentials into a generic `/auth` hub supporting multiple platforms (Challonge, Discord). Unify OAuth handling, add token refresh UI, and gate DeveloperTools via backend permissions.

## Implementation Scope

### Phase 1: Core Infrastructure (Foundation)
- [ ] Create `src/config/platforms.js` - Platform registry (Challonge configured + Discord scaffolded)
- [ ] Create `src/composables/useOAuth.js` - Unified OAuth handler for any provider
- [ ] Create `src/composables/useDiscordOAuth.js` - Discord-specific wrapper
- [ ] Update `src/router/index.js` - Add `/auth` route + legacy redirects
- [ ] Update `src/views/OAuthCallback.vue` - Provider-agnostic callback handling

### Phase 2: UI Migration (Views)
- [ ] Create `src/views/AuthenticationHub.vue` - Unified auth management interface
- [ ] Update `src/views/ChallongeTest.vue` - Remove auth sections, link to `/auth`
- [ ] Update `src/components/DeveloperTools.vue` - Gate with backend permissions

### Phase 3: Integration & Testing
- [ ] Update `.env` - Add Discord OAuth credentials
- [ ] Update Challonge composables to use unified OAuth (backward compatibility)
- [ ] Build and test frontend
- [ ] Deploy and verify in production

### Phase 4: Backend Support (if needed)
- [ ] Ensure `/api/oauth/token` endpoint handles `provider` parameter
- [ ] Ensure `/api/oauth/refresh` endpoint handles `provider` parameter
- [ ] Implement `/api/auth/discord/profile` endpoint
- [ ] Add `developer_tools.view` permission to user response
- [ ] Add `discord_username` to user profile

---

## File Changes Detail

### Phase 1: Core Infrastructure

#### 1. `src/config/platforms.js` (CREATE)
**Purpose:** Centralized platform configuration
**Size:** ~80 lines
**Key Content:** 
- Challonge config with OAuth, API key, client credentials
- Discord config with OAuth (identify scope only)
- Helper functions: `getPlatform()`, `getAllPlatforms()`

#### 2. `src/composables/useOAuth.js` (CREATE)
**Purpose:** Unified OAuth handler for multiple providers
**Size:** ~400 lines
**Key Content:**
- Multi-provider token storage with localStorage
- `initializeProvider()` - per-provider state setup
- `getAuthorizationUrl()` - with return_to support
- `login()` - initiate OAuth flow
- `exchangeCode()` - token exchange with provider parameter
- `refreshToken()` - auto-refresh with 5-min expiry buffer
- `getValidToken()` - returns valid token or refreshes
- `logout()` - clear tokens

#### 3. `src/composables/useDiscordOAuth.js` (CREATE)
**Purpose:** Discord-specific OAuth wrapper
**Size:** ~80 lines
**Key Content:**
- Thin wrapper around `useOAuth('discord')`
- `discordUsername`, `discordId` computed properties
- `fetchUserProfile()` - fetch from `/api/auth/discord/profile`
- `login()`, `logout()`, `refreshToken()`

#### 4. `src/router/index.js` (UPDATE)
**Purpose:** Add new routes and redirects
**Changes:**
- Import `AuthenticationHub` component
- Add route: `{ path: '/auth', name: 'AuthenticationHub', component: AuthenticationHub }`
- Add redirects: `/api-key-manager` → `/auth`, `/settings` → `/auth`

#### 5. `src/views/OAuthCallback.vue` (UPDATE)
**Purpose:** Make callback provider-agnostic
**Changes:**
- Extract `provider` from query or sessionStorage (default: 'challonge')
- Use `useOAuth(provider)` for code exchange
- Support `return_to` query parameter
- Redirect to `return_to || '/auth'` after success

### Phase 2: UI Migration

#### 6. `src/views/AuthenticationHub.vue` (CREATE)
**Purpose:** Unified authentication management interface
**Size:** ~800-1000 lines
**Key Content:**
- Tab/accordion interface for Challonge and Discord
- **Challonge section:**
  - API Key input + management
  - OAuth status with expiry + refresh button
  - Client Credentials input + management
- **Discord section:**
  - OAuth status with username display
  - Auto-refresh info
- Token expiry display and manual refresh buttons
- Success/error notifications
- Links to provider settings pages

#### 7. `src/views/ChallongeTest.vue` (UPDATE)
**Purpose:** Remove auth UI, keep tournament testing
**Changes:**
- Remove OAuth Authentication section (lines ~49-120)
- Remove API Key Configuration section
- Remove Client Credentials section
- Add info banner: "Configure Challonge authentication in Settings" with link to `/auth`
- Keep API Version selector, tournament list, testing UI

#### 8. `src/components/DeveloperTools.vue` (UPDATE)
**Purpose:** Gate with backend permissions
**Changes:**
- Replace `isAvailable` computed to check:
  - User must be authenticated
  - Check `user.permissions.includes('developer_tools.view')`
  - In dev mode: show for any authenticated user
  - In prod mode: require explicit permission

### Phase 3: Integration & Testing

#### 9. `.env` (UPDATE)
**Purpose:** Add Discord OAuth credentials
**Changes:**
```
VITE_DISCORD_CLIENT_ID=your_discord_app_id_here
VITE_DISCORD_REDIRECT_URI=http://localhost:5173/oauth/callback
```

#### 10. Test & Deploy
- Build frontend: `npm run build:frontend`
- Deploy containers: `docker compose -f docker-compose.production.yml up -d`
- Test `/auth` route loads
- Test OAuth callback with return_to
- Test token refresh UI
- Test DeveloperTools gating

---

## Backwards Compatibility Notes

- `useChallongeOAuth.js` can remain unchanged (still exports methods)
- `/api-key-manager` redirects to `/auth`
- OAuth callback still accepts no provider (defaults to Challonge)
- All existing API calls continue to work

---

## Testing Checklist

- [ ] `/auth` route loads AuthenticationHub
- [ ] Challonge OAuth flow works (code exchange → tokens stored)
- [ ] Challonge API key CRUD works
- [ ] Challonge client credentials CRUD works
- [ ] Token expiry display works
- [ ] Manual refresh button works
- [ ] Automatic 5-min expiry refresh works
- [ ] Discord OAuth flow works (redirects to Discord → code exchange)
- [ ] DeveloperTools only shows when authenticated with `developer_tools.view` permission
- [ ] `/api-key-manager` redirects to `/auth`
- [ ] `/oauth/callback` works without provider parameter
- [ ] `/oauth/callback?return_to=/challonge-test` redirects correctly
- [ ] ChallongeTest shows auth settings link
- [ ] All token storage persists across page reloads

---

## Implementation Order (Recommended)

1. **Start Phase 1** (infrastructure first)
   - Create `platforms.js`
   - Create `useOAuth.js`
   - Create `useDiscordOAuth.js`
   - Update router
   - Update OAuthCallback

2. **Test Phase 1**
   - Verify `/auth` route exists
   - Verify OAuth callback works
   - Verify token exchange works

3. **Start Phase 2** (UI)
   - Create AuthenticationHub
   - Update ChallongeTest
   - Update DeveloperTools

4. **Test Phase 2**
   - Build frontend
   - Test routes load
   - Test OAuth flows

5. **Phase 3** (final integration)
   - Update .env
   - Deploy
   - Test in production

---

## Notes for Pause/Resume

If stopping mid-implementation:
- Save the exact line numbers of any partial edits
- Mark completed todos in this file
- Note any environment variables or backend changes needed
- Keep this file up to date with actual progress