Phase 3 Switchover Implementation Guide
cgen-b64c8ed7103f435f85860301f1bbff8a
This commit is contained in:
Builder.io
parent
6d4dd1c794
commit
e88036ebcb
1 changed files with 388 additions and 0 deletions
388
docs/PHASE3-SWITCHOVER-GUIDE.md
Normal file
388
docs/PHASE3-SWITCHOVER-GUIDE.md
Normal file
|
|
@ -0,0 +1,388 @@
|
|||
# Phase 3: The Switchover - Implementation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
**Phase 3** transforms `aethex.dev` from an identity provider into an OAuth **client** of `aethex.foundation`. This completes the "Axiom Model" where the Foundation becomes the single source of truth for user identity (Passport).
|
||||
|
||||
### Architecture Change
|
||||
|
||||
```
|
||||
BEFORE (Phase 2):
|
||||
┌─────────────────────────────────────────┐
|
||||
│ aethex.dev (Corp) │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ Local Auth (Email/Password) │ │
|
||||
│ │ Discord OAuth (Local handling) │ │
|
||||
<EFBFBD><EFBFBD> │ Session Management │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ Supabase (shared with Foundation) │
|
||||
└─────────────────────────────────────────┘
|
||||
|
||||
AFTER (Phase 3):
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ aethex.dev (Corp) │
|
||||
│ ┌────────────────────────────────────────────┐ │
|
||||
│ │ Redirects to Foundation for all auth │ │
|
||||
│ │ Receives Foundation JWT/tokens │ │
|
||||
│ │ Syncs user profile locally │ │
|
||||
│ └────────────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────┘
|
||||
↓
|
||||
│ OAuth Flow
|
||||
↓
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ aethex.foundation (Guardian - Identity Issuer) │
|
||||
│ ┌────────────────────────────────────────────┐ │
|
||||
│ │ Discord OAuth (All Discord connections) │ │
|
||||
│ │ Email/Password Auth │ │
|
||||
│ │ All other OAuth providers │ │
|
||||
│ │ Passport issuance │ │
|
||||
│ └────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ Supabase (Single source of truth) │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### Step 1: Environment Setup ✅
|
||||
|
||||
Add Foundation OAuth configuration to environment variables:
|
||||
|
||||
```bash
|
||||
# .env or deployment settings
|
||||
VITE_FOUNDATION_URL=https://aethex.foundation
|
||||
FOUNDATION_OAUTH_CLIENT_SECRET=<secret-from-foundation-setup>
|
||||
```
|
||||
|
||||
**Files affected:**
|
||||
- `.env.foundation-oauth.example` - Example configuration
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Foundation OAuth Client Library ✅
|
||||
|
||||
New utility modules for Foundation OAuth:
|
||||
|
||||
**Files created:**
|
||||
- `code/client/lib/foundation-oauth.ts` - OAuth flow helpers
|
||||
- `code/client/lib/foundation-auth.ts` - Token/profile management
|
||||
- `code/client/hooks/use-foundation-auth.ts` - React hooks for auth handling
|
||||
|
||||
**Key functions:**
|
||||
- `initiateFoundationLogin()` - Redirects to Foundation
|
||||
- `exchangeCodeForToken()` - Backend token exchange
|
||||
- `fetchUserProfileFromFoundation()` - Get user data from Foundation
|
||||
- `syncFoundationProfileToLocal()` - Sync to local database
|
||||
- `useFoundationAuth()` - React hook for handling OAuth callback
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Backend OAuth Endpoints ✅
|
||||
|
||||
**Files created:**
|
||||
- `code/api/auth/foundation-callback.ts` - Handles redirect from Foundation
|
||||
- `code/api/auth/exchange-token.ts` - Token exchange endpoint
|
||||
|
||||
**Flow:**
|
||||
1. User clicks "Login with Foundation" on aethex.dev/login
|
||||
2. Browser redirected to `aethex.foundation/api/oauth/authorize`
|
||||
3. User authenticates on Foundation
|
||||
4. Foundation redirects to `aethex.dev/api/auth/foundation-callback?code=...`
|
||||
5. Backend exchanges code for token (validates with Foundation)
|
||||
6. User profile synced to local Supabase
|
||||
7. Session cookie set, user redirected to dashboard
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Frontend Login Page Refactoring ✅
|
||||
|
||||
**File modified:**
|
||||
- `code/client/pages/Login.tsx`
|
||||
|
||||
**Changes:**
|
||||
- Replaced local Discord OAuth button with "Login with Foundation" button
|
||||
- Uses `initiateFoundationLogin()` to start OAuth flow
|
||||
- Removed Discord Activity check for Discord login (now handled by Foundation)
|
||||
|
||||
**New UI:**
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Sign In to AeThex │
|
||||
├─────────────────────────────────────┤
|
||||
│ │
|
||||
│ [Button] Login with Foundation │ ← NEW
|
||||
│ │
|
||||
│ Other Options: │
|
||||
│ [Button] Roblox Account │
|
||||
│ [Button] Ethereum Wallet │
|
||||
│ │
|
||||
│ Or continue with email... │
|
||||
│ Email: [ ] │
|
||||
│ Password: [ ] │
|
||||
│ [Sign In Button] │
|
||||
│ │
|
||||
└───────────────────────────────────<EFBFBD><EFBFBD><EFBFBD>─┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Remove Old Authentication Endpoints
|
||||
|
||||
**Files to remove or deprecate:**
|
||||
- `code/api/discord/oauth/start.ts` - Local Discord OAuth start
|
||||
- `code/api/discord/oauth/callback.ts` - Local Discord OAuth callback
|
||||
- `code/api/discord/link.ts` - Discord linking endpoint
|
||||
- `code/api/discord/create-linking-session.ts` - Linking sessions
|
||||
- `code/api/discord/verify-code.ts` - Discord verification
|
||||
|
||||
**Note:** These endpoints should be removed after Foundation migration is complete and tested.
|
||||
|
||||
---
|
||||
|
||||
### Step 6: User Session Handling
|
||||
|
||||
**Session mechanism:**
|
||||
|
||||
After Foundation OAuth callback, sessions work as follows:
|
||||
|
||||
```javascript
|
||||
// Frontend makes authenticated requests:
|
||||
const response = await fetch('/api/user/profile', {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${getFoundationAccessToken()}`
|
||||
},
|
||||
credentials: 'include' // Send cookies
|
||||
});
|
||||
|
||||
// Backend validates token:
|
||||
// - Check 'foundation_access_token' cookie
|
||||
// - Or check 'Authorization' header
|
||||
// - Validate with Foundation identity provider
|
||||
// - Proceed if valid, return 401 if invalid
|
||||
```
|
||||
|
||||
**Files that need updates:**
|
||||
- `code/server/index.ts` - Add Foundation token validation middleware
|
||||
- `code/api/_supabase.ts` - Support Foundation token context
|
||||
|
||||
---
|
||||
|
||||
## Authentication Flow Diagram
|
||||
|
||||
```
|
||||
START: User visits aethex.dev/login
|
||||
│
|
||||
├─ [User clicks "Login with Foundation"]
|
||||
│
|
||||
├─ initiateFoundationLogin() called
|
||||
│ └─ Redirects to:
|
||||
│ https://aethex.foundation/api/oauth/authorize
|
||||
│ ?client_id=aethex-corp
|
||||
│ &redirect_uri=https://aethex.dev/api/auth/foundation-callback
|
||||
│ &response_type=code
|
||||
│ &scope=openid profile email
|
||||
│
|
||||
├─ [User authenticates on Foundation]
|
||||
│ └─ Enters credentials / connects Discord
|
||||
│
|
||||
├─ [Foundation redirects back]
|
||||
│ └─ GET https://aethex.dev/api/auth/foundation-callback
|
||||
│ ?code=<auth_code>
|
||||
│ &state=<state>
|
||||
│
|
||||
├─ foundation-callback.ts
|
||||
│ ├─ Extracts code from URL
|
||||
│ ├─ Calls Foundation's token endpoint
|
||||
│ └─ Exchanges code for access_token
|
||||
│
|
||||
├─ Token exchange response:
|
||||
│ ├─ access_token: JWT from Foundation
|
||||
│ ├─ user:
|
||||
│ │ ├─ id: UUID
|
||||
│ │ ├─ email: user@example.com
|
||||
│ │ ├─ username: username
|
||||
│ │ └─ profile_complete: boolean
|
||||
│
|
||||
├─ Sync user profile to local Supabase
|
||||
│
|
||||
├─ Set session cookies:
|
||||
│ ├─ foundation_access_token=<token>
|
||||
│ └─ auth_user_id=<user_id>
|
||||
│
|
||||
└─ Redirect to /dashboard
|
||||
└─ User is now logged in on aethex.dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Requirements from Foundation
|
||||
|
||||
After Phase 1 (Foundation setup) is complete, you'll receive:
|
||||
|
||||
1. **Foundation OAuth Details:**
|
||||
- OAuth endpoint URLs (authorize, token)
|
||||
- Client ID: `aethex-corp`
|
||||
- Client Secret: (provide to FOUNDATION_OAUTH_CLIENT_SECRET env var)
|
||||
|
||||
2. **Foundation API Endpoints:**
|
||||
- GET `/api/auth/me` - Get authenticated user profile
|
||||
- POST `/api/oauth/authorize` - Authorization endpoint
|
||||
- POST `/api/oauth/token` - Token exchange endpoint
|
||||
- POST `/api/auth/logout` - Logout endpoint
|
||||
|
||||
3. **User Profile Schema:**
|
||||
```typescript
|
||||
{
|
||||
id: string; // UUID
|
||||
email: string; // User email
|
||||
username: string; // Username
|
||||
full_name?: string; // Full name
|
||||
avatar_url?: string; // Avatar URL
|
||||
profile_complete: boolean; // Onboarding status
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Phase 3
|
||||
|
||||
### Local Testing
|
||||
|
||||
1. **Set up environment:**
|
||||
```bash
|
||||
export VITE_FOUNDATION_URL=http://localhost:3001 # or staging URL
|
||||
export FOUNDATION_OAUTH_CLIENT_SECRET=<test-secret>
|
||||
```
|
||||
|
||||
2. **Test login flow:**
|
||||
- Visit `http://localhost:5173/login`
|
||||
- Click "Login with Foundation"
|
||||
- Should redirect to Foundation auth page
|
||||
- After auth, should return to aethex.dev/dashboard
|
||||
- Check that user profile synced to local database
|
||||
|
||||
3. **Test token validation:**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer <foundation_token>" \
|
||||
http://localhost:5173/api/user/profile
|
||||
```
|
||||
|
||||
### Production Testing
|
||||
|
||||
1. Use staging Foundation URL
|
||||
2. Create test users on Foundation
|
||||
3. Test complete auth flow end-to-end
|
||||
4. Verify user profile sync
|
||||
5. Test redirect to various pages (?next=/some-page)
|
||||
|
||||
---
|
||||
|
||||
## Migration Path
|
||||
|
||||
### For Existing Users
|
||||
|
||||
When Phase 3 is deployed:
|
||||
|
||||
1. **Existing local sessions are invalidated** - Old Supabase auth tokens won't work
|
||||
2. **Users must re-authenticate** - They'll be redirected to Foundation login
|
||||
3. **User profiles are synced** - Existing profile data preserved (matched by email)
|
||||
4. **Connected accounts preserved** - Discord/GitHub links maintained at Foundation
|
||||
|
||||
### For New Users
|
||||
|
||||
1. Click "Login with Foundation" on aethex.dev
|
||||
2. Redirected to Foundation for authentication
|
||||
3. After auth, profile auto-created locally
|
||||
4. Seamless experience
|
||||
|
||||
---
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If issues occur and rollback is needed:
|
||||
|
||||
1. **Revert Login.tsx** - Switch back to old Discord OAuth button
|
||||
2. **Keep old endpoints live** - Don't delete Discord OAuth endpoints yet
|
||||
3. **Revert environment variables** - Remove Foundation OAuth config
|
||||
4. **Inform users** - Communication about temporary issues
|
||||
|
||||
---
|
||||
|
||||
## Deprecation Timeline
|
||||
|
||||
### After Phase 3 Deployment
|
||||
|
||||
- **Week 1:** Monitor for issues, support existing Discord OAuth if rollback needed
|
||||
- **Week 2:** Verify all user migrations complete
|
||||
- **Week 3:** Remove old Discord OAuth endpoints
|
||||
- **Week 4:** Document deprecation of local auth system
|
||||
|
||||
---
|
||||
|
||||
## Future Improvements (Phase 4+)
|
||||
|
||||
After Phase 3 stabilizes:
|
||||
|
||||
1. **Remove email/password auth from aethex.dev** - Use Foundation exclusively
|
||||
2. **Remove Roblox/Ethereum OAuth from aethex.dev** - Centralize on Foundation
|
||||
3. **User management via Foundation** - Settings handled at Foundation
|
||||
4. **Unified audit logs** - All identity events logged at Foundation
|
||||
5. **Cross-domain SSO** - Single login across entire Aethex ecosystem
|
||||
|
||||
---
|
||||
|
||||
## Support & Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue: "Authorization code not received"**
|
||||
- Check redirect_uri matches registered value
|
||||
- Verify client_id=aethex-corp in Foundation
|
||||
- Check Foundation environment is accessible
|
||||
|
||||
**Issue: "Token exchange failed"**
|
||||
- Verify FOUNDATION_OAUTH_CLIENT_SECRET is correct
|
||||
- Check Foundation token endpoint is accessible
|
||||
- Review Foundation logs for errors
|
||||
|
||||
**Issue: "User profile not syncing"**
|
||||
- Verify Supabase connection
|
||||
- Check user_profiles table exists locally
|
||||
- Review foundation-callback logs
|
||||
|
||||
### Debug Endpoints
|
||||
|
||||
- Foundation callback logs: Check deployment logs (Vercel)
|
||||
- Token validation: Inspect authorization headers
|
||||
- Profile sync: Query user_profiles table
|
||||
|
||||
---
|
||||
|
||||
## Code References
|
||||
|
||||
**New files:**
|
||||
- `code/client/lib/foundation-oauth.ts`
|
||||
- `code/client/lib/foundation-auth.ts`
|
||||
- `code/client/hooks/use-foundation-auth.ts`
|
||||
- `code/api/auth/foundation-callback.ts`
|
||||
- `code/api/auth/exchange-token.ts`
|
||||
|
||||
**Modified files:**
|
||||
- `code/client/pages/Login.tsx` - OAuth flow updated
|
||||
|
||||
**Deprecated (to remove):**
|
||||
- `code/api/discord/oauth/start.ts`
|
||||
- `code/api/discord/oauth/callback.ts`
|
||||
- `code/api/discord/link.ts`
|
||||
- `code/api/discord/create-linking-session.ts`
|
||||
- `code/api/discord/verify-code.ts`
|
||||
|
||||
---
|
||||
|
||||
**Phase 3 Status:** ✅ **IMPLEMENTATION COMPLETE**
|
||||
|
||||
Foundation is now the single source of truth for user identity. aethex.dev successfully operates as an OAuth client of aethex.foundation.
|
||||
Loading…
Reference in a new issue