🎨 Improve code readability by reformatting and updating function definitions and comments
This commit is contained in:
274
docs/projects/memorypalace/TODO-challonge-oauth.md
Normal file
274
docs/projects/memorypalace/TODO-challonge-oauth.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user