From 04f557873faecba4a85622edf5e01752d768aa0c Mon Sep 17 00:00:00 2001 From: "Builder.io" Date: Mon, 10 Nov 2025 01:15:34 +0000 Subject: [PATCH] Discord OAuth Setup Verification - Critical Checklist cgen-840f342dc85442d3a29d19405dc7a707 --- docs/DISCORD-OAUTH-SETUP-VERIFICATION.md | 270 +++++++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 docs/DISCORD-OAUTH-SETUP-VERIFICATION.md diff --git a/docs/DISCORD-OAUTH-SETUP-VERIFICATION.md b/docs/DISCORD-OAUTH-SETUP-VERIFICATION.md new file mode 100644 index 00000000..68258b7a --- /dev/null +++ b/docs/DISCORD-OAUTH-SETUP-VERIFICATION.md @@ -0,0 +1,270 @@ +# Discord OAuth Setup Verification Checklist + +## 🔴 CRITICAL: OAuth Redirect URI Registration + +This is the most common cause of session loss during Discord linking. + +### Step 1: Open Discord Developer Portal + +1. Go to: https://discord.com/developers/applications +2. Find and click: **AeThex** application +3. Left sidebar, click: **OAuth2** +4. Find the section: **REDIRECT URLS** or **REDIRECTS** + +### Step 2: Verify Redirect URI is Registered + +You must have this exact URL registered: + +``` +https://aethex.dev/api/discord/oauth/callback +``` + +**If you're using a different domain** (like localhost for testing): +``` +http://localhost:5173/api/discord/oauth/callback +``` + +### Step 3: Add Missing Redirect URI (If Needed) + +If the URL is NOT listed: + +1. Click: **Add Redirect** button +2. Paste the correct URL: + ``` + https://aethex.dev/api/discord/oauth/callback + ``` +3. Click: **Save Changes** +4. **Wait** - changes may take 1-2 minutes to propagate + +⚠️ **IMPORTANT:** The redirect URI must match EXACTLY: +- Correct: `https://aethex.dev/api/discord/oauth/callback` +- Wrong: `https://aethex.dev/api/discord/callback` (missing `/oauth`) +- Wrong: `aethex.dev/api/discord/oauth/callback` (missing `https://`) +- Wrong: `https://aethex.dev/api/discord/oauth/callback/` (trailing slash) + +--- + +## 🟢 TESTING THE DISCORD LINKING FLOWS + +After verifying the redirect URI, test both flows: + +### Test Flow 1: Discord `/verify` Command + +1. In Discord, type: `/verify` +2. Click the link button or copy the code +3. Browser opens: `https://aethex.dev/discord-verify?code=XXXXXX` +4. Page auto-submits and links your account +5. You should see: ✅ Success message +6. **Redirects to:** `/dashboard?tab=connections` (FIXED) +7. You should see Discord in your connections list + +**If it redirects to `/profile/settings` instead:** +- This has been FIXED in the code update + +**If it shows an error:** +- Check the error message in the browser console +- Note: Session may be lost if redirect URI not registered + +--- + +### Test Flow 2: Dashboard "Link Discord" Button + +This is the flow that had session loss issues. + +1. Go to: `/dashboard?tab=connections` +2. Click: **Link Discord** button +3. You'll be redirected to Discord OAuth +4. Click: **Authorize** on Discord +5. Discord redirects back to your app +6. **EXPECTED:** You should be redirected to `/dashboard?tab=connections` +7. **EXPECTED:** You should still be logged in +8. **EXPECTED:** Discord should appear in your connections + +**If you're redirected to `/login` instead:** +- Session was lost during OAuth callback +- **Cause:** Redirect URI not registered in Discord Dev Portal +- **Solution:** Follow Step 1-3 above to add the redirect URI +- **Then:** Try the flow again + +**If you see an error about session being lost:** +- This means the backend detected missing session cookies +- Check the browser console for error details +- The error message now tells you to verify Discord Dev Portal settings + +--- + +## 🔵 ENVIRONMENT VARIABLES CHECKLIST + +Verify these are set correctly: + +### Frontend (code/.env or deployment platform) + +- [ ] `VITE_API_BASE` is set to your API domain + ``` + VITE_API_BASE=https://aethex.dev + ``` + (Or your actual deployment domain) + +- [ ] `VITE_SUPABASE_URL` is correct + ``` + VITE_SUPABASE_URL=https://kmdeisowhtsalsekkzqd.supabase.co + ``` + +- [ ] `VITE_SUPABASE_ANON_KEY` is set + +### Backend/Server (environment variables) + +- [ ] `DISCORD_CLIENT_ID` is set + ``` + DISCORD_CLIENT_ID=578971245454950421 + ``` + +- [ ] `DISCORD_CLIENT_SECRET` is set (production) + ``` + DISCORD_CLIENT_SECRET=JKlilGzcTWgfmt2wEqiHO8wpCel5VEji + ``` + ⚠️ **NOTE:** This is sensitive - only set in production, not in code + +- [ ] `VITE_SUPABASE_URL` is set on backend + ``` + VITE_SUPABASE_URL=https://kmdeisowhtsalsekkzqd.supabase.co + ``` + +- [ ] `SUPABASE_SERVICE_ROLE` is set + ``` + SUPABASE_SERVICE_ROLE=eyJhbGciOiJIUzI1NiIs... + ``` + ⚠️ **CRITICAL:** Never commit this to git + +--- + +## 🟡 COMMON ISSUES & SOLUTIONS + +### Issue 1: "Session Lost" Error After Discord OAuth + +**Cause:** Redirect URI not registered in Discord Dev Portal + +**Solution:** +1. Open Discord Developer Portal +2. Go to OAuth2 → Redirects +3. Verify `https://aethex.dev/api/discord/oauth/callback` is listed +4. If not listed, add it and save +5. Try the linking flow again (may need to clear browser cache first) + +--- + +### Issue 2: Discord Link Disappears After Page Reload + +**Cause:** Linking succeeded but auth state not refreshed + +**Solution:** +1. Verify the `discord_links` table in Supabase has the record + - Go to: https://app.supabase.com/project/kmdeisowhtsalsekkzqd + - Find table: `discord_links` + - Check if your discord_id and user_id are recorded +2. If record exists but not showing in UI: + - Reload the page or go to `/dashboard` + - The UI should refresh and show Discord connection +3. If record doesn't exist: + - The linking failed silently + - Check browser console for errors + - Try the `/verify` flow instead + +--- + +### Issue 3: Wrong Redirect Page After `/verify` Command + +**Old Problem:** Redirected to `/profile/settings` + +**Solution:** ✅ FIXED in code +- The code now redirects to `/dashboard?tab=connections` +- If you're still seeing `/profile/settings`: + - Clear browser cache (Ctrl+Shift+Delete) + - Deploy the latest code changes + +--- + +### Issue 4: "Already Linked" Error in `/verify` Command + +**Cause:** Discord account already linked to an AeThex account + +**Solutions:** +- Option A: Use a different Discord account +- Option B: Contact admin to unlink the Discord account from the other AeThex account +- Option C: If it's your old account, use `\unlink` command to disconnect it, then `/verify` again + +--- + +## 🟣 DEBUGGING STEPS + +If something isn't working, follow these steps: + +### Step 1: Check Browser Console + +1. Open Discord or your app +2. Press F12 (DevTools) +3. Go to Console tab +4. Look for messages starting with `[Discord OAuth]` or `[Discord Activity]` +5. Take a screenshot of any error messages + +### Step 2: Check Network Tab + +1. In DevTools, go to Network tab +2. Perform the Discord linking flow +3. Look for a request to `/api/discord/oauth/callback?code=...` +4. Click on it and check: + - **Request Headers** → `Cookie` (should have `sb-access-token`) + - **Response Headers** → `Set-Cookie` (should have new tokens) + - **Status** → Should be `302` (redirect) + +### Step 3: Check Supabase + +1. Go to: https://app.supabase.com/project/kmdeisowhtsalsekkzqd +2. Find table: `discord_links` +3. Look for your discord_id (check if record exists) +4. If record exists but UI doesn't show it: + - Reload the page + - Or manually call `refreshAuthState()` +5. If record doesn't exist: + - Linking never succeeded + - Check the Network tab request/response above + +### Step 4: Check Discord Dev Portal + +1. Go to: https://discord.com/developers/applications/578971245454950421 +2. Click: OAuth2 +3. Scroll to: REDIRECT URLS +4. Verify: `https://aethex.dev/api/discord/oauth/callback` is listed +5. If missing: + - Add it + - Save + - Wait 1-2 minutes + - Try linking again + +--- + +## ✅ Verification Checklist + +When everything is working correctly, you should see: + +- [ ] Discord `/verify` command generates a code +- [ ] Clicking the link shows verification page +- [ ] Code auto-submits and succeeds +- [ ] Redirects to `/dashboard?tab=connections` (not `/profile/settings`) +- [ ] Discord appears in connections list +- [ ] Clicking "Link Discord" button on dashboard works +- [ ] User redirected to `/dashboard?tab=connections` after Discord OAuth +- [ ] User remains logged in after Discord OAuth +- [ ] Discord appears in connections list immediately +- [ ] Page reload doesn't lose Discord connection +- [ ] Running `/verify` again shows "Already Linked" message + +When all items are checked, your Discord linking is fully functional! 🎉 + +--- + +## Related Documentation + +- [DISCORD-LINKING-FLOW-ANALYSIS.md](./DISCORD-LINKING-FLOW-ANALYSIS.md) - Flow diagrams and architecture +- [DISCORD-ACTIVITY-SETUP.md](./DISCORD-ACTIVITY-SETUP.md) - Discord Activity/slash commands setup +- [DISCORD-ADMIN-COMMANDS-REGISTRATION.md](./DISCORD-ADMIN-COMMANDS-REGISTRATION.md) - Bot command registration