AeThex-OS/temp-forge-extract/aethex-forge-main/docs/PHASE3-README.md

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:

# 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:

   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.