Phase 3 Quick Start Guide
cgen-5b27f769c3e6476aa4a4663e124d7f30
This commit is contained in:
Builder.io
parent
fc12a98a5c
commit
5bc03c1a34
1 changed files with 352 additions and 0 deletions
352
docs/PHASE3-README.md
Normal file
352
docs/PHASE3-README.md
Normal file
|
|
@ -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=<secret-provided-by-foundation>
|
||||
```
|
||||
|
||||
**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 <Phase3-commit-hash>
|
||||
```
|
||||
|
||||
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.
|
||||
Loading…
Reference in a new issue