memory-infrastructure-palace/docs/projects/Pokedex.Online/archive/auth-hub/implementation.md

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