memory-infrastructure-palace/code/websites/pokedex.online/AUTH_HUB_PROGRESS.md

# Auth Hub Implementation - PROGRESS UPDATE

## Completed ✅

### Phase 1: Core Infrastructure (FOUNDATION COMPLETE)
- [x] **Created `src/config/platforms.js`** - Full platform registry with:
  - Challonge configuration (OAuth, API Key, Client Credentials)
  - Discord configuration (OAuth with identify scope)
  - Helper functions: getPlatform(), getAllPlatforms(), hasAuthMethod(), getAuthMethod()
  - Full JSDoc comments for all exports

- [x] **Created `src/composables/useOAuth.js`** - 400+ line unified OAuth handler:
  - Multi-provider token storage with localStorage persistence
  - Provider-specific state management (Map-based storage)
  - Authorization URL generation with return_to support
  - CSRF protection via state parameter validation
  - Code exchange with provider routing
  - Automatic token refresh with 5-minute expiry buffer
  - Token validation and cleanup
  - Comprehensive error handling and logging
  - Full JSDoc comments on all methods

- [x] **Created `src/composables/useDiscordOAuth.js`** - Thin wrapper for Discord:
  - Wrapper around useOAuth('discord')
  - Discord user profile management (username, ID, tag)
  - fetchUserProfile() method for backend integration
  - hasDevAccess() helper for permission checking
  - Full method documentation

## In Progress / Pending ⚠️

### Phase 1: Core Infrastructure (NEEDS FILE EDITING TOOLS)
- [ ] **Update `src/router/index.js`** - Need to:
  - Import AuthenticationHub component
  - Add route: { path: '/auth', name: 'AuthenticationHub', component: AuthenticationHub }
  - Add legacy redirects:
    - /api-key-manager → /auth
    - /settings → /auth
  - **STATUS:** File identified, changes drafted, awaiting file editor

- [ ] **Update `src/views/OAuthCallback.vue`** - Need to:
  - Extract provider from query/sessionStorage (default: 'challonge')
  - Support return_to query parameter
  - Use new useOAuth(provider) for code exchange
  - Redirect to return_to || '/auth' after success
  - Add better error handling for provider-specific errors
  - **STATUS:** Full replacement code drafted, awaiting file editor

### Phase 2: UI Migration (NOT STARTED)
- [ ] **Create `src/views/AuthenticationHub.vue`** - Will include:
  - Tab/accordion interface for Challonge and Discord
  - Challonge section: API Key input, OAuth status/refresh, Client Credentials
  - Discord section: OAuth status with username display
  - Token expiry display with manual refresh buttons
  - Success/error notifications
  - Links to provider settings
  - **STATUS:** Code drafted, awaiting file creation

- [ ] **Update `src/views/ChallongeTest.vue`** - Need to:
  - Remove OAuth Authentication section (lines ~49-120)
  - Remove API Key Configuration section  
  - Remove Client Credentials section
  - Add info banner linking to /auth
  - Keep tournament testing UI only
  - **STATUS:** Changes identified, awaiting file editor

- [ ] **Update `src/components/DeveloperTools.vue`** - Need to:
  - Replace isAvailable computed property
  - Check user.permissions.includes('developer_tools.view')
  - Keep dev-mode fallback for any authenticated user
  - **STATUS:** Changes identified, simple replacement, awaiting file editor

### Phase 3: Integration & Testing (NOT STARTED)
- [ ] **Update `.env`** - Add Discord OAuth credentials:
  - VITE_DISCORD_CLIENT_ID=your_discord_app_id_here
  - VITE_DISCORD_REDIRECT_URI=http://localhost:5173/oauth/callback
  - **STATUS:** Simple addition, awaiting file editor

- [ ] **Build and test Phase 1** - Verify:
  - /auth route loads (will error until AuthenticationHub created)
  - OAuth composables work
  - Token exchange works
  - **STATUS:** Blocked on Phase 1 completion

- [ ] **Build and test Phase 2** - Verify:
  - AuthenticationHub loads
  - All UI works
  - OAuth flows complete
  - DeveloperTools gating works
  - **STATUS:** Blocked on Phase 2 completion

- [ ] **Final deployment** - Deploy and verify in production

---

## Key Code Files Created

### 1. `src/config/platforms.js` (80 lines)
**Location:** `/Users/fragginwagon/Developer/MemoryPalace/code/websites/pokedex.online/src/config/platforms.js`
**Status:** ✅ CREATED AND READY

Platform registry with Challonge and Discord OAuth configurations. Includes helper functions for accessing platform configs and auth methods.

### 2. `src/composables/useOAuth.js` (400+ lines)
**Location:** `/Users/fragginwagon/Developer/MemoryPalace/code/websites/pokedex.online/src/composables/useOAuth.js`
**Status:** ✅ CREATED AND READY

Unified OAuth handler supporting any provider. Handles:
- Multi-provider token storage with localStorage
- Authorization flow with CSRF protection
- Token exchange and refresh
- Automatic refresh before expiry
- Error handling and logging

### 3. `src/composables/useDiscordOAuth.js` (80 lines)
**Location:** `/Users/fragginwagon/Developer/MemoryPalace/code/websites/pokedex.online/src/composables/useDiscordOAuth.js`
**Status:** ✅ CREATED AND READY

Discord-specific OAuth wrapper providing:
- User profile management
- Username/ID access
- Permission checking helpers

---

## Files Needing Updates (Drafts Ready)

### 1. `src/router/index.js`
**Changes Required:**
```javascript
// Line 1-8: Update imports
// Change: import ApiKeyManager from '../views/ApiKeyManager.vue';
// To: import AuthenticationHub from '../views/AuthenticationHub.vue';

// Lines 28-35: Add new route after ChallongeTest route
{
  path: '/auth',
  name: 'AuthenticationHub',
  component: AuthenticationHub
},

// Lines 36-43: Change api-key-manager to redirect
// OLD: path: '/api-key-manager', name: 'ApiKeyManager', component: ApiKeyManager
// NEW: path: '/api-key-manager', redirect: '/auth'

// Lines 44+: Add settings redirect
{
  path: '/settings',
  redirect: '/auth'
}
```

### 2. `src/views/OAuthCallback.vue`
**Key Changes:**
- Extract provider from query/sessionStorage
- Use unified useOAuth(provider) instead of useChallongeOAuth()
- Support return_to query parameter
- Redirect to return_to || '/auth' instead of hardcoded '/challonge-test'

### 3. `src/components/DeveloperTools.vue`
**Changes Required (Line ~146):**
```javascript
// OLD:
const isAvailable = computed(() => {
  const isDev = process.env.NODE_ENV === 'development';
  const isAuthenticatedInProduction = process.env.NODE_ENV === 'production' && user.value;
  return isDev || isAuthenticatedInProduction;
});

// NEW:
const isAvailable = computed(() => {
  if (!user.value) return false;
  if (user.value.permissions?.includes('developer_tools.view')) {
    return true;
  }
  if (process.env.NODE_ENV === 'development') {
    return true;
  }
  return false;
});
```

### 4. `src/views/ChallongeTest.vue`
**Changes Required:**
- Remove OAuth Authentication section (lines ~49-120)
- Remove API Key Configuration section
- Remove Client Credentials section
- Add info banner with link to /auth
- Keep tournament testing UI

---

## Next Steps (When File Editors Available)

1. **Update router.js** - Add AuthenticationHub route and legacy redirects
2. **Create AuthenticationHub.vue** - Main UI hub for all auth methods
3. **Update OAuthCallback.vue** - Make provider-agnostic
4. **Update ChallongeTest.vue** - Remove auth sections
5. **Update DeveloperTools.vue** - Gate with permissions
6. **Update .env** - Add Discord OAuth variables
7. **Build and test** - npm run build:frontend && docker compose up -d
8. **Verify** - Test all OAuth flows and DeveloperTools gating

---

## Testing Checklist (Post-Implementation)

- [ ] `/auth` route loads AuthenticationHub
- [ ] Challonge OAuth flow works end-to-end
- [ ] Challonge API key management works
- [ ] Challonge client credentials management works
- [ ] Token expiry display works
- [ ] Manual refresh button works
- [ ] Auto-refresh (5-min before expiry) works
- [ ] Discord OAuth flow works
- [ ] DeveloperTools only shows with permission
- [ ] `/api-key-manager` redirects to `/auth`
- [ ] `/oauth/callback` works without provider param
- [ ] `/oauth/callback?return_to=/challonge-test` works
- [ ] ChallongeTest shows settings link
- [ ] Tokens persist across page reloads
- [ ] Token state changes update UI immediately

---

## Architecture Notes

### Token Storage Strategy
- Each provider has isolated token storage in localStorage
- Multiple OAuth providers can be authenticated simultaneously
- Tokens are auto-refreshed 5 minutes before expiry
- Storage keys from platform config prevent conflicts

### Security Features Implemented
- CSRF protection via state parameter validation
- Secure random state generation using crypto.getRandomValues()
- Token expiry calculation and auto-refresh
- Automatic token cleanup on logout
- Error isolation by provider

### Backwards Compatibility
- Old `/api-key-manager` redirects to `/auth`
- OAuth callback works without provider parameter (defaults to Challonge)
- Existing Challonge OAuth composable still works (can be refactored later)
- All existing API endpoints unchanged

---

## Resume Instructions

If work is paused:
1. Check this file for completed vs pending items
2. All "CREATED AND READY" files are in the codebase
3. All "Drafts Ready" files have code provided above
4. Next task: Update router.js when file editors available
5. Then create AuthenticationHub.vue (largest file, ~800-1000 lines)

---

**Last Updated:** Phase 1 infrastructure complete, awaiting file editor tool for Phase 1 router update