diff --git a/docs/DISCORD-OAUTH-VERIFICATION.md b/docs/DISCORD-OAUTH-VERIFICATION.md new file mode 100644 index 00000000..5d468e31 --- /dev/null +++ b/docs/DISCORD-OAUTH-VERIFICATION.md @@ -0,0 +1,225 @@ +# Discord OAuth Connection Verification & Testing + +## Current Status ✅ + +**Bot Token**: Updated with new token (as of latest deployment) +**Environment Variables**: All configured +**Endpoints**: Live and responding + +## What Should Work + +### ✅ 1. Login with Discord (New Scenario) +**Scenario**: User clicks "Continue with Discord" on `/login` with Discord email matching existing account + +**Steps**: +1. Go to `https://aethex.dev/login` +2. Click **"Continue with Discord"** button +3. Authorize on Discord +4. Should show success and redirect to `/dashboard` + +**Expected Result**: User logged in with Discord account linked + +--- + +### ✅ 2. Login with Discord (Email Mismatch) +**Scenario**: Discord email doesn't match any existing AeThex account + +**Steps**: +1. Go to `https://aethex.dev/login` +2. Click **"Continue with Discord"** button +3. Authorize with Discord account that has different email +4. Should show error: "Discord email not found" +5. Click back to login and sign in with your email instead + +**Expected Result**: User shown helpful error message, redirected to login + +--- + +### ✅ 3. Link Discord from Dashboard +**Scenario**: User already logged in, wants to link Discord + +**Steps**: +1. Sign in with email/password on `/login` +2. Go to `/dashboard?tab=connections` +3. Find Discord card +4. Click **"Link Discord"** button +5. Authorize Discord +6. Should see Discord as "Linked" in connections + +**Expected Result**: Discord account linked to existing user + +--- + +### ✅ 4. Discord Bot Commands +**Scenario**: User types Discord commands in a server where bot is present + +**Commands to Test**: +``` +/verify - Bot sends verification code +/set-realm gameforge - Bot confirms realm change + assigns role +/profile - Bot shows user profile card +/verify-role - Bot shows assigned roles +/unlink - Bot unlinks Discord account +``` + +**Expected Result**: All commands respond without errors + +--- + +## OAuth Flow Diagram + +``` +┌─────────────────────────────────────────────────────────┐ +│ Discord OAuth Login Flow │ +└─────────────────────────────────────────────────────────┘ + +1. User clicks "Continue with Discord" + ↓ +2. Frontend redirects to: + /api/discord/oauth/start + ↓ +3. Backend redirects to: + https://discord.com/api/oauth2/authorize? + client_id=578971245454950421 + &redirect_uri=https://aethex.dev/api/discord/oauth/callback + &response_type=code + &scope=identify%20email + &state=... + ↓ +4. User authorizes on Discord + ↓ +5. Discord redirects to: + /api/discord/oauth/callback?code=XXX&state=... + ↓ +6. Backend: + a) Exchanges code for Discord access token + b) Fetches Discord user profile (email, username, avatar) + c) Checks if Discord email matches existing account + d) If YES → Links to existing user + d) If NO → Shows error "Discord email not found" + e) Creates session cookies + f) Redirects to /dashboard + ↓ +7. ✅ User logged in with Discord linked +``` + +--- + +## Environment Variables (Current) + +``` +DISCORD_CLIENT_ID=578971245454950421 +DISCORD_CLIENT_SECRET= +DISCORD_BOT_TOKEN= +DISCORD_PUBLIC_KEY=d9771dd29e3a6f030cb313e33bb4b51384c7c36829bd551df714681dcf1e1eb0 +``` + +--- + +## Discord Developer Portal Checklist + +Make sure these are configured in Discord Developer Portal: + +- [ ] **General Information**: + - [ ] Application name: "AeThex" + - [ ] Client ID: `578971245454950421` + - [ ] Public Key: `d9771dd29e3a6f030cb313e33bb4b51384c7c36829bd551df714681dcf1e1eb0` + +- [ ] **OAuth2 > General**: + - [ ] Client Secret configured + - [ ] Redirect URIs includes: `https://aethex.dev/api/discord/oauth/callback` + +- [ ] **Bot**: + - [ ] Bot token set (new GmEHDt token) + - [ ] Intents enabled: `Message Content`, `Guilds` + - [ ] Permissions: `Administrator` or specific permissions + +- [ ] **Interactions Endpoint URL**: + - [ ] URL: `https://aethex.dev/api/discord/interactions` + - [ ] ✅ Verified by Discord + +--- + +## Testing Checklist + +### Basic Connectivity +- [ ] API endpoint responds: `curl https://aethex.dev/api/discord/oauth/start -I` +- [ ] Discord bot online (shows in server member list) +- [ ] Discord bot can execute commands (`/verify` works) + +### OAuth Login Tests +- [ ] **Test 1**: Login with Discord email matching existing account + - [ ] Click "Continue with Discord" + - [ ] Authorize + - [ ] Redirects to dashboard ✅ + +- [ ] **Test 2**: Login with Discord email NOT in system + - [ ] Click "Continue with Discord" + - [ ] Authorize + - [ ] Shows error message ✅ + - [ ] Can sign in with email instead ✅ + +### OAuth Linking Tests +- [ ] **Test 3**: Link Discord from Dashboard + - [ ] Sign in with email + - [ ] Go to Dashboard → Connections + - [ ] Click "Link Discord" + - [ ] Authorize + - [ ] Discord appears as linked ✅ + +- [ ] **Test 4**: Unlink and re-link Discord + - [ ] From connections tab, click "Unlink Discord" + - [ ] Confirm unlink + - [ ] Click "Link Discord" again + - [ ] Authorize + - [ ] Successfully re-linked ✅ + +### Bot Command Tests +- [ ] **Test 5**: `/verify` command generates code + - [ ] Type `/verify` in Discord + - [ ] Bot sends code with link + - [ ] Link works: `https://aethex.dev/discord-verify?code=...` ✅ + +- [ ] **Test 6**: `/set-realm` command works + - [ ] Type `/set-realm` + - [ ] Select an arm (gameforge, labs, etc) + - [ ] Bot confirms change ✅ + - [ ] Logs show role assignment ✅ + +- [ ] **Test 7**: `/profile` command shows user + - [ ] Type `/profile` + - [ ] Bot shows user profile card ✅ + +--- + +## Troubleshooting + +### "Redirect URI mismatch" error +- Problem: Discord OAuth callback failing +- Solution: Verify `https://aethex.dev/api/discord/oauth/callback` is registered in Discord Developer Portal + +### "Invalid token" error +- Problem: Bot token expired or revoked +- Solution: Get new token from Discord Developer Portal + +### Bot commands not working +- Problem: Commands not registered with Discord +- Solution: Run `/api/discord/admin-register-commands` endpoint with DISCORD_ADMIN_REGISTER_TOKEN + +### Session lost during linking +- Problem: User logged out after Discord OAuth redirect +- Solution: This should NOT happen anymore - we use database sessions instead of cookies + +--- + +## Success Indicators ✅ + +All flows working when you see: + +1. ✅ Discord button visible on login page +2. ✅ Can authorize on Discord and return to aethex.dev +3. ✅ Discord appears in Dashboard connections +4. ✅ Bot commands work in Discord +5. ✅ No session loss during OAuth redirects +6. ✅ Helpful error messages when things go wrong +