memory-infrastructure-palace/docs/projects/memorypalace/TODO-challonge-oauth.md

OAuth Implementation TODO

This document outlines the steps needed to implement OAuth 2.0 authentication for the Challonge API v2.1.

Current Status

✅ Completed:

• API v2.1 service supports OAuth authentication (AuthType.OAUTH)
• UI toggle for OAuth is present in ChallongeTest.vue (disabled)
• Service client can accept Bearer tokens

🚧 Not Implemented:

• OAuth authorization flow
• Token storage and management
• Token refresh logic
• OAuth scope selection

OAuth Flow Options

Challonge supports three OAuth flows. Choose based on your use case:

1. Authorization Code Flow (Recommended for Web Apps)

Best for: Browser-based applications where users can authorize access

Steps to Implement:

1. Register application at https://connect.challonge.com

   • Get client_id and client_secret
   • Set redirect URI (e.g., http://localhost:5173/oauth/callback)

2. Create OAuth authorization URL:

   const authUrl = `https://api.challonge.com/oauth/authorize?` +
     `client_id=${CLIENT_ID}&` +
     `redirect_uri=${REDIRECT_URI}&` +
     `response_type=code&` +
     `scope=me+tournaments:read+tournaments:write+matches:read+matches:write+participants:read+participants:write`;
   

3. Redirect user to authorization URL

4. Handle callback with authorization code

5. Exchange code for access token:

   POST https://api.challonge.com/oauth/token
   Body: {
     client_id, client_secret, grant_type: "authorization_code",
     code, redirect_uri
   }
   

6. Store access_token and refresh_token

7. Use access_token with API requests

2. Device Authorization Grant Flow

Best for: Devices with no browser or limited input (TVs, consoles, IoT)

Steps:

1. Request device code
2. Show QR code or user code to user
3. Poll for access token while user authorizes on their phone/PC
4. Store and use access token

3. Client Credentials Flow

Best for: Server-side applications managing their own tournaments

Steps:

1. Use client_id and client_secret to get application-scoped token
2. Access all tournaments created via your app

Available OAuth Scopes

• me - Read user details
• tournaments:read - Read tournaments
• tournaments:write - Create/update/delete tournaments
• matches:read - Read matches
• matches:write - Update matches, report scores
• participants:read - Read participants
• participants:write - Add/update/remove participants
• attachments:read - Read match attachments
• attachments:write - Upload match attachments
• communities:manage - Access community resources
• application:organizer - Full access to user's resources for your app
• application:player - Read user's resources, register, report scores
• application:manage - Full access to all tournaments connected to your app

Implementation Checklist

Phase 1: OAuth Setup

• Register app at https://connect.challonge.com
• Store client_id in environment variables
• Store client_secret securely (backend only, never expose to frontend)
• Add OAuth callback route to Vue Router (/oauth/callback)
• Create OAuth configuration module

Phase 2: Authorization Flow

• Create OAuth composable (useChallongeOAuth.js)
• Implement authorization URL generation
• Create "Sign in with Challonge" button
• Handle OAuth redirect and code extraction
• Implement token exchange (requires backend proxy for client_secret)

Phase 3: Token Management

• Create secure token storage (localStorage for access token)
• Implement token refresh logic
• Check token expiration before requests
• Auto-refresh expired tokens
• Handle refresh token failure (re-authorize user)

Phase 4: API Key Manager Integration

• Update useChallongeApiKey composable to support OAuth tokens
• Add OAuth token storage alongside API keys
• Create OAuth setup wizard in API Key Manager
• Show token expiration date and refresh status
• Allow users to revoke OAuth access

Phase 5: UI Updates

• Enable OAuth toggle in ChallongeTest.vue
• Add OAuth status indicator (connected/disconnected)
• Show current OAuth scopes
• Add "Connect with OAuth" button
• Add "Disconnect OAuth" button
• Show which permissions are granted

Phase 6: Scope Management

• Create scope selection UI
• Allow users to request specific scopes
• Show which features require which scopes
• Handle insufficient permission errors gracefully

Phase 7: Testing

• Test authorization flow (desktop browser)
• Test authorization flow (mobile browser)
• Test token refresh
• Test expired token handling
• Test with different scope combinations
• Test OAuth + API v1 key fallback
• Test concurrent sessions (multiple tabs)

Security Considerations

Client Secret Protection

⚠️ CRITICAL: Never expose client_secret in frontend code!

Solution: Implement backend proxy for token exchange:

// Frontend requests token from your backend
POST /api/oauth/token
Body: { code, redirect_uri }

// Your backend exchanges code with Challonge
POST https://api.challonge.com/oauth/token
Body: { client_id, client_secret, code, ... }

Token Storage

• ✅ Access Token: Can store in localStorage (limited lifetime)
• ⚠️ Refresh Token: More sensitive, consider httpOnly cookies or secure backend storage
• ❌ Client Secret: Never in frontend

PKCE (Proof Key for Code Exchange)

Consider implementing PKCE for additional security:

• Generate code_verifier (random string)
• Create code_challenge (SHA256 hash of verifier)
• Send challenge with authorization request
• Send verifier with token request
• Prevents authorization code interception attacks

Backend Requirements

To properly implement OAuth, you need a backend proxy for:

1. Token Exchange (requires client_secret)
2. Token Refresh (requires client_secret)
3. Secure Storage (optional, for refresh tokens)

Minimal Backend Example (Node.js/Express)

app.post('/api/oauth/token', async (req, res) => {
  const { code, redirect_uri } = req.body;
  
  const response = await fetch('https://api.challonge.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: process.env.CHALLONGE_CLIENT_ID,
      client_secret: process.env.CHALLONGE_CLIENT_SECRET,
      grant_type: 'authorization_code',
      code,
      redirect_uri
    })
  });
  
  const tokens = await response.json();
  res.json(tokens);
});

Alternative: Serverless Functions

Can use:

• Netlify Functions
• Vercel Edge Functions
• Cloudflare Workers
• AWS Lambda

Token Response Format

{
  "access_token": "long-access-token-string",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "long-refresh-token-string",
  "scope": "me tournaments:read tournaments:write ...",
  "created_at": 1623246724
}

Note: expires_in is in seconds (604800 = 1 week)

Refresh Token Usage

When access token expires:

POST https://api.challonge.com/oauth/token
Body: {
  client_id,
  client_secret,
  grant_type: "refresh_token",
  refresh_token: "your-refresh-token"
}

Response includes new access_token and optionally a new refresh_token.

Migration Path

Users with API v1 keys can continue using them with v2.1 API:

1. API v1 keys work with Authorization-Type: v1 header
2. No migration required for existing users
3. OAuth is optional but recommended for:
   • Better security (scoped permissions)
   • Acting on behalf of other users
   • Building multi-user applications

Resources

• Challonge API Documentation
• Authorization Guide
• Developer Portal
• OAuth 2.0 RFC

Estimated Implementation Time

• Phase 1 (Setup): 1-2 hours
• Phase 2 (Auth Flow): 3-4 hours
• Phase 3 (Token Management): 2-3 hours
• Phase 4 (API Integration): 2-3 hours
• Phase 5-6 (UI): 3-4 hours
• Phase 7 (Testing): 2-3 hours

Total: ~15-20 hours for full OAuth implementation

Priority

📅 Medium Priority - API v1 keys work fine with v2.1 API. Implement OAuth when:

• Building features that require user-specific access
• Need to act on behalf of multiple users
• Want better security with scoped permissions
• Challonge announces v1 key deprecation

---

Status: Not started
Last Updated: 2026-01-28
Assigned To: Future development