AeThex-OS/docs/OAUTH_QUICKSTART.md

OAuth Quick Start Guide

🚀 Get OAuth Working in 5 Minutes

Step 1: Register OAuth Apps (5 min per provider)

Discord

1. Go to https://discord.com/developers/applications
2. Click "New Application" → Name it "AeThex OS Dev"
3. Go to OAuth2 → Add redirect URI:

   http://localhost:5000/api/oauth/callback/discord
   

4. Copy Client ID and Client Secret to .env

Roblox

1. Go to https://create.roblox.com/dashboard/credentials
2. Create new OAuth 2.0 credential
3. Add redirect URI:

   http://localhost:5000/api/oauth/callback/roblox
   

4. Select scopes: openid, profile
5. Copy Client ID and Client Secret to .env

GitHub

1. Go to https://github.com/settings/developers
2. Click OAuth Apps → New OAuth App
3. Fill in:
   • Name: AeThex OS Dev
   • Homepage: http://localhost:5000
   • Callback URL: http://localhost:5000/api/oauth/callback/github
4. Copy Client ID and Client Secret to .env

Step 2: Verify Environment Variables

Your .env should have:

DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
ROBLOX_CLIENT_ID=your_roblox_client_id
ROBLOX_CLIENT_SECRET=your_roblox_client_secret
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

Step 3: Test the OAuth Flow

# Start server
npm run dev

# In browser:
# 1. Log in to AeThex OS
# 2. Open browser console
# 3. Run this code:
fetch('/api/oauth/link/discord', { 
  method: 'POST',
  credentials: 'include'
})
  .then(r => r.json())
  .then(data => {
    console.log('Auth URL:', data.authUrl);
    window.location.href = data.authUrl; // Redirects to Discord
  });

# 4. Authorize on Discord
# 5. You'll be redirected back to /settings?oauth=success&provider=discord

Step 4: Verify Database

-- Check if identity was created
SELECT * FROM aethex_subject_identities 
ORDER BY created_at DESC 
LIMIT 1;

---

🎯 Next Steps

Add Frontend UI

Create a button in Settings page:

// client/src/pages/settings.tsx
async function linkDiscord() {
  const res = await fetch('/api/oauth/link/discord', {
    method: 'POST',
    credentials: 'include'
  });
  const { authUrl } = await res.json();
  window.location.href = authUrl;
}

// Check for success on page load
useEffect(() => {
  const params = new URLSearchParams(window.location.search);
  if (params.get('oauth') === 'success') {
    toast.success(`${params.get('provider')} account linked!`);
  }
}, []);

For Production (aethex.app)

1. Create production OAuth apps with redirect URI:

   https://aethex.app/api/oauth/callback/{provider}
   

2. Add production credentials to production .env
3. Set NODE_ENV=production
4. Deploy!

---

⚠️ Security Reminders

Before Production:

1. ✅ Rotate ALL credentials (see docs/CREDENTIALS_ROTATION.md)
2. ✅ Use separate OAuth apps for dev/prod
3. ✅ Ensure .env is in .gitignore
4. ✅ Enable HTTPS in production
5. ✅ Replace in-memory state storage with Redis

---

📞 Need Help?

• Setup issues: See docs/OAUTH_SETUP.md
• Security questions: See docs/CREDENTIALS_ROTATION.md
• Implementation details: See docs/OAUTH_IMPLEMENTATION.md
• Testing OAuth: See "Testing Checklist" in implementation doc

---

Status: ✅ OAuth handler implemented and ready for testing
Build: ✅ Compiles successfully
Next: Register OAuth apps and test the flow!