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:
   ```javascript
   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:
   ```javascript
   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:
```javascript
// 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)
```javascript
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

```json
{
  "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:
```javascript
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](https://challonge.apidog.io/getting-started-1726706m0)
- [Authorization Guide](https://challonge.apidog.io/authorization-1726705m0)
- [Developer Portal](https://connect.challonge.com/)
- [OAuth 2.0 RFC](https://datatracker.ietf.org/doc/html/rfc6749)

## 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