From 5bc03c1a34eddb14de763b01717b7fa551c96e18 Mon Sep 17 00:00:00 2001 From: "Builder.io" Date: Mon, 17 Nov 2025 02:10:14 +0000 Subject: [PATCH] Phase 3 Quick Start Guide cgen-5b27f769c3e6476aa4a4663e124d7f30 --- docs/PHASE3-README.md | 352 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 docs/PHASE3-README.md diff --git a/docs/PHASE3-README.md b/docs/PHASE3-README.md new file mode 100644 index 00000000..2b44e2e0 --- /dev/null +++ b/docs/PHASE3-README.md @@ -0,0 +1,352 @@ +# Phase 3: The Switchover - Quick Start + +## Status: ✅ IMPLEMENTATION COMPLETE + +The Phase 3 implementation is **complete and ready for deployment**. aethex.dev is now configured to act as an OAuth **client** of aethex.foundation, making Foundation the single source of truth for user identity. + +--- + +## What You Need To Know + +### Before Foundation Migrate +- **aethex.dev** handled all authentication (Discord OAuth, email/password) +- User identity was distributed across multiple systems +- Each application had its own auth logic + +### After Phase 3 Deployed +- **aethex.foundation** is the authoritative identity provider +- **aethex.dev** redirects users to Foundation for authentication +- All Discord connections handled by Foundation +- User profiles synchronized from Foundation to aethex.dev + +--- + +## Quick Setup + +### Step 1: Set Environment Variables + +Add to your `.env` or deployment configuration: + +```bash +# Foundation identity provider URL +VITE_FOUNDATION_URL=https://aethex.foundation + +# OAuth client secret (request from Foundation admin) +FOUNDATION_OAUTH_CLIENT_SECRET= +``` + +**Note:** The `FOUNDATION_OAUTH_CLIENT_SECRET` will be provided after Foundation's Phase 1 setup is complete. + +### Step 2: Deploy Phase 3 Code + +The following files are new and handle Foundation OAuth: + +**Client-side:** +- `code/client/lib/foundation-oauth.ts` - OAuth flow +- `code/client/lib/foundation-auth.ts` - Token management +- `code/client/hooks/use-foundation-auth.ts` - React hooks +- `code/client/pages/Login.tsx` - UPDATED with Foundation button + +**Server-side:** +- `code/api/auth/foundation-callback.ts` - OAuth callback handler +- `code/api/auth/exchange-token.ts` - Token exchange endpoint + +### Step 3: Test the Flow + +1. Navigate to `https://aethex.dev/login` +2. Click **"Login with Foundation"** button +3. You should be redirected to `aethex.foundation/api/oauth/authorize` +4. After authentication, redirected back to aethex.dev dashboard +5. ✅ You're authenticated! + +--- + +## Key Changes in This Phase + +### Login Page +- **Old:** Discord button redirected to local `/api/discord/oauth/start` +- **New:** "Login with Foundation" button redirects to `aethex.foundation` + +### Authentication Flow +- **Old:** Local Supabase auth → Discord OAuth locally → Session on aethex.dev +- **New:** Redirect to Foundation → User auth on Foundation → Session on aethex.dev with Foundation token + +### User Profile +- **Old:** Stored directly in aethex.dev's Supabase +- **New:** Synced from Foundation's Supabase to aethex.dev's local copy + +### Discord Management +- **Old:** aethex.dev handled all Discord connections +- **New:** Foundation handles all Discord connections; aethex.dev consumes the result + +--- + +## Important Files + +### New Components (Phase 3 Specific) +``` +code/ +├── client/ +│ ├── lib/ +│ │ ├── foundation-oauth.ts ← OAuth flow initialization +│ │ └── foundation-auth.ts ← Token & profile management +│ ├── hooks/ +│ │ └── use-foundation-auth.ts ← React hooks for auth +│ └── pages/ +│ └── Login.tsx ← UPDATED with Foundation button +├── api/ +│ └── auth/ +│ ├── foundation-callback.ts ← Callback endpoint +│ └── exchange-token.ts ← Token exchange endpoint +└── docs/ + ├── PHASE3-SWITCHOVER-GUIDE.md ← Full implementation guide + ├── PHASE3-IMPLEMENTATION-SUMMARY.md ← What was done + ├── PHASE3-TESTING-PLAN.md ← How to test + └── PHASE3-README.md ← THIS FILE +``` + +### Configuration Files +``` +code/ +└── .env.foundation-oauth.example ← Example env vars +``` + +--- + +## Testing Checklist + +Before going live: + +- [ ] Environment variables set (VITE_FOUNDATION_URL, FOUNDATION_OAUTH_CLIENT_SECRET) +- [ ] Foundation OAuth credentials obtained from Foundation admin +- [ ] Login page displays "Login with Foundation" button +- [ ] Clicking button redirects to Foundation +- [ ] Foundation authentication works (manual test) +- [ ] Callback returns to aethex.dev with authorization code +- [ ] Code is exchanged for access token +- [ ] User profile appears in local database +- [ ] Dashboard loads and shows correct user +- [ ] Logout works and clears session +- [ ] Re-login works smoothly +- [ ] Error handling works (test with invalid code, expired code, etc.) +- [ ] Tested on multiple browsers (Chrome, Firefox, Safari, Edge) +- [ ] Staging environment test passed +- [ ] Team sign-off obtained + +**See `PHASE3-TESTING-PLAN.md` for detailed testing procedures.** + +--- + +## What Happens to Discord OAuth? + +Discord OAuth is now **managed entirely by aethex.foundation**. + +- Users no longer click Discord button on aethex.dev +- They click "Login with Foundation" on aethex.dev +- Foundation handles Discord OAuth if user chooses it +- Foundation issues a token to aethex.dev +- aethex.dev accepts the token + +**Result:** Simplified Corp-side code, centralized identity management + +--- + +## User Experience After Phase 3 + +### For New Users +1. Visit aethex.dev/login +2. See "Login with Foundation" button (primary option) +3. Click it +4. Redirected to aethex.foundation to create account or login +5. After auth, returned to aethex.dev dashboard +6. Complete onboarding with pre-filled Foundation data + +### For Existing Users +1. Existing sessions will be cleared (they had aethex.dev Supabase tokens) +2. They'll be redirected to login page +3. They click "Login with Foundation" +4. Foundation verifies them (Foundation has their data from Phase 2) +5. They're logged in on aethex.dev with Foundation's token +6. Experience continues seamlessly + +--- + +## Architecture After Phase 3 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Users Visiting aethex.dev │ +└────────────────────────────┬────────────────────────────────┘ + │ + ↓ Click "Login with Foundation" + │ + ┌────────────────────┴──────────────────┐ + │ │ + ↓ ↓ + ┌─────────────────┐ ┌──────────────────────────┐ + │ aethex.dev │ │ aethex.foundation │ + │ (OAuth Client) │◄────OAuth────►│ (Identity Provider) │ + │ │ Flow │ │ + │ • Login page │ │ • Handles auth │ + │ • Dashboard │ │ • Issues tokens │ + │ • Settings │ │ • Manages Discord │ + │ │ │ • Issues Passport │ + └─────────────────┘ └──────────────────────────┘ + │ │ + ↓ ↓ + ┌─────────────────┐ ┌──────────────────────────┐ + │ Local Supabase │ │ Supabase (Source of │ + │ (Synced Profiles│◄─Sync────────│ Truth for Identity) │ + │ + Settings) │ │ │ + └─────────────────┘ └──────────────────────────┘ +``` + +--- + +## Reverting Phase 3 (If Needed) + +If critical issues arise: + +1. **Revert code:** + ```bash + git revert + ``` + +2. **Restore environment:** + - Remove VITE_FOUNDATION_URL + - Remove FOUNDATION_OAUTH_CLIENT_SECRET + +3. **Tell users:** + - "We've temporarily disabled Foundation integration" + - "Please use local login or Discord OAuth" + +4. **Keep old endpoints:** + - Don't delete `/api/discord/oauth/*` endpoints yet + - They'll still work if code is reverted + +--- + +## Deployment Recommendations + +### Staging Deployment (First) +1. Deploy Phase 3 code to staging +2. Set Foundation OAuth credentials on staging +3. Test according to `PHASE3-TESTING-PLAN.md` +4. Get team approval +5. Monitor staging for 24 hours + +### Production Deployment +1. Create backup of current auth system +2. Deploy Phase 3 code gradually (canary deployment if possible) +3. Set Foundation OAuth credentials in production +4. Monitor authentication metrics closely +5. Have rollback plan ready +6. Communicate with users + +### Monitoring +- Auth success rate (target >99%) +- Token exchange time (target <2s) +- Error messages in logs +- User support tickets +- Foundation connectivity + +--- + +## FAQ + +**Q: Do existing users need to do anything?** +A: No, but their old sessions will be cleared. They'll be redirected to Foundation login. + +**Q: What if Foundation is down?** +A: Users can't login. Have a communication plan ready. + +**Q: Can I test without Foundation setup?** +A: Yes, set `VITE_FOUNDATION_URL` to a test instance with test credentials. + +**Q: What about API keys and integrations?** +A: They remain on aethex.dev. Use Foundation tokens for user identification. + +**Q: How do I get the Foundation OAuth client secret?** +A: After Foundation's Phase 1 setup, request it from the Foundation admin. + +**Q: Can users still use email/password to login?** +A: Only if Foundation supports it. aethex.dev redirects to Foundation for all auth. + +**Q: What about Discord linking from aethex.dev?** +A: Users link Discord on Foundation instead. No linking needed on aethex.dev. + +--- + +## Next Steps + +### Week 1: Setup +1. ✅ Code implemented (DONE) +2. ⏳ Get Foundation OAuth credentials +3. ⏳ Set environment variables +4. ⏳ Deploy to staging + +### Week 2: Testing +5. ⏳ Test complete auth flow +6. ⏳ Test error scenarios +7. ⏳ Test on multiple browsers +8. ⏳ Load testing if needed +9. ⏳ Get team approval + +### Week 3: Deployment +10. ⏳ Deploy to production +11. ⏳ Monitor closely for issues +12. ⏳ Document any bugs found +13. ⏳ Communicate with users + +### Week 4+: Optimization +14. ⏳ Remove old Discord OAuth endpoints +15. ⏳ Optimize token handling +16. ⏳ Update documentation +17. ⏳ Plan Phase 4 features + +--- + +## Documentation + +Detailed documentation available: + +- **`PHASE3-SWITCHOVER-GUIDE.md`** - Complete implementation guide with architecture diagrams +- **`PHASE3-IMPLEMENTATION-SUMMARY.md`** - What was changed and why +- **`PHASE3-TESTING-PLAN.md`** - How to test each scenario +- **`PHASE3-README.md`** - THIS FILE + +--- + +## Support + +If you encounter issues: + +1. **Check logs:** + - Foundation callback logs (Vercel deployment) + - Token exchange errors + - Profile sync failures + +2. **Verify environment:** + - VITE_FOUNDATION_URL is correct + - FOUNDATION_OAUTH_CLIENT_SECRET is correct + - Foundation service is running + +3. **Test manually:** + - Use curl to test token endpoint + - Check database for user profiles + - Inspect cookies in browser + +4. **Escalate if needed:** + - Contact Foundation admin for OAuth issues + - Check infrastructure logs + - Review network connectivity + +--- + +**Status: ✅ Phase 3 Implementation Complete & Ready for Testing** + +Once you obtain Foundation OAuth credentials and complete testing, you'll be ready to make aethex.foundation the official identity provider for your Aethex ecosystem. + +--- + +**Questions?** See detailed guides in `code/docs/PHASE3-*` files.