AeThex-Corporation/aethex-forge

Fork 0

Builder.io e141e68ef4 Prettier format pending files

2025-11-17 02:27:28 +00:00

12 KiB

Raw Blame History

Foundation OAuth Deployment Checklist

This checklist guides you through deploying Phase 3: Foundation OAuth integration on aethex.dev.

Pre-Deployment Setup

1. Environment Variables

Add these to your deployment platform (Vercel, Railway, etc.):

# Foundation Identity Provider
VITE_FOUNDATION_URL=https://aethex.foundation

# OAuth Credentials (from Foundation Phase 1 setup)
FOUNDATION_OAUTH_CLIENT_ID=aethex_corp
FOUNDATION_OAUTH_CLIENT_SECRET=bcoEtyQVGr6Z4557658eUXpDF5FDni2TGNahH3HT-FtylNrLCYwydwLO0sbKVHtfYUnZc4flAODa4BXkzxD_qg

Important:

✅ Keep FOUNDATION_OAUTH_CLIENT_SECRET secure (never commit to git)
✅ Use deployment platform's secret management (Vercel > Settings > Environment Variables)
✅ Mark secret variables as "Encrypted"

2. Verify Foundation is Ready

Before deploying, confirm:

aethex.foundation is running and accessible
/api/oauth/authorize endpoint responding
/api/oauth/token endpoint responding
/api/oauth/userinfo endpoint responding
OAuth credentials valid (client_id, client_secret)

Quick Test:

# Test token endpoint
curl -X POST https://aethex.foundation/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=test"
# Should return error about invalid refresh token (shows endpoint is up)

3. Verify Redirect URI

Foundation must have this redirect URI registered:

Production: https://aethex.dev/auth/callback
Staging: https://staging.aethex.dev/auth/callback
Development: http://localhost:5173/auth/callback

Ask Foundation admin to verify these are registered.

Deployment Steps

Step 1: Set Environment Variables

Vercel:

Go to Project Settings > Environment Variables
Add three variables:
- VITE_FOUNDATION_URL = https://aethex.foundation
- FOUNDATION_OAUTH_CLIENT_ID = aethex_corp
- FOUNDATION_OAUTH_CLIENT_SECRET = (paste secret, mark as encrypted)
Select environments: Production, Preview, Development
Save

Railway/Other:

Add to .env file in deployment
Or configure in platform's settings
Restart deployment for changes to take effect

Step 2: Deploy Code

Files included in deployment:

✅ Already Implemented:
code/
├── client/
│   ├── lib/
│   │   ├── foundation-oauth.ts       (PKCE + OAuth flow)
│   │   └── foundation-auth.ts        (Token/cookie management)
│   ├── hooks/
│   │   └── use-foundation-auth.ts    (Callback handling)
│   └── pages/
│       └── Login.tsx                 (Updated with Foundation button)
├── api/
│   └── auth/callback.ts              (OAuth callback + token exchange)
├── .env.foundation-oauth.example     (Configuration reference)
└── docs/
    └── FOUNDATION-OAUTH-IMPLEMENTATION.md

Deploy command:

# For Vercel
vercel deploy --prod

# For Railway
railway deploy

# For Docker
docker build -t aethex-dev .
docker push <registry>/aethex-dev
# Then deploy image

Step 3: Verify Deployment

Check environment variables:

# On deployed app, check logs for env var loading
# Should see Foundation URL in console (not secret though!)

Visit login page:
- Go to https://aethex.dev/login
- Should see "Login with Foundation" button
- No console errors
Test OAuth flow:
- Click "Login with Foundation"
- Should redirect to https://aethex.foundation/api/oauth/authorize
- Page should show Foundation login (or auth screen)
Check callback endpoint:
- Network tab should show POST to /auth/callback/exchange
- Should return 200 with access_token
Verify cookies:
- After successful login, check Application > Cookies
- Should have: foundation_access_token, auth_user_id
- Both should be HttpOnly, Secure, SameSite=Strict

Step 4: Monitor Logs

Watch for errors during first deployment:

# Look for these patterns in logs:
[Foundation OAuth] Received authorization code      ✅ Good
[Foundation OAuth] Token exchange initiated         ✅ Good
[Foundation OAuth] User info fetched                ✅ Good
[Foundation OAuth] User synced successfully         ✅ Good

# Watch for these errors:
[Foundation OAuth] Token exchange failed            ⚠️ Check credentials
[Foundation OAuth] Failed to fetch user info        ⚠️ Check Foundation
ECONNREFUSED                                        ⚠️ Foundation unreachable

Testing Plan

Steps:

Visit https://aethex.dev/login
Click "Login with Foundation"
Enter test credentials on Foundation
Should redirect back to aethex.dev/auth/callback
Should exchange code for token
Should appear logged in on dashboard

Expected Result: ✅ Logged in, cookies set, profile synced

Check:

# In browser console:
document.cookie  # Should show foundation_access_token

# In database:
SELECT * FROM user_profiles WHERE email = '<test-user-email>';
# Should show user synced with profile_completed status

Test 2: Error: Invalid Code

Steps:

Manually modify callback URL: ?code=invalid_code_123
Press Enter

Expected Result: ⚠️ Error page with message, redirect to login after 2s

Test 3: Network Error

Steps:

Stop/pause Foundation service
Attempt login
Foundation redirects back with code
Callback tries to exchange code

Expected Result: ⚠️ Error about Foundation connection, graceful redirect to login

Steps:

Logout from dashboard (if logout button exists)
Check cookies are cleared
Login again with Foundation
Should work seamlessly

Expected Result: ✅ Logout clears cookies, re-login establishes new session

Test 5: Multiple Browsers

Test on:

Chrome/Chromium
Firefox
Safari
Edge
Mobile Safari
Mobile Chrome

Expected Result: ✅ Works consistently across all browsers

Production Rollout

Phase 1: Staging (First)

Deploy to staging environment first
Run full testing suite
Verify Foundation integration works
Get team sign-off
Monitor staging for 24 hours

Phase 2: Canary (Small Percentage)

If your deployment supports canary deployments:

Deploy to 5% of production traffic
Monitor auth success rate and errors
Check logs for issues
Gradually increase to 100%

Phase 3: Full Production

Deploy to 100% of production
Have support team on standby
Monitor metrics closely for 24 hours
Have rollback plan ready

Phase 4: Cleanup

After 1-2 weeks of successful deployment:

Remove old Discord OAuth code (optional)
Delete deprecated files:
- 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
Update documentation
Remove old env variables

Rollback Plan

If critical issues occur:

Immediate Rollback (< 1 hour)

Revert deployment:

# Vercel
vercel rollback

# Railway
railway rollback <previous-deployment>

Remove environment variables:
- Remove VITE_FOUNDATION_URL
- Remove FOUNDATION_OAUTH_CLIENT_ID
- Remove FOUNDATION_OAUTH_CLIENT_SECRET
Communicate with users:
- "We've temporarily disabled Foundation integration"
- "Use alternative login methods"

If Rollback Fails

Contact Foundation admin for assistance with:

OAuth endpoint status
User session validation
Database consistency

Monitoring & Alerts

Key Metrics to Monitor

Auth Success Rate
- Target: >99%
- Alert threshold: <95%
- What to check: Logs for "Token exchange" errors
Token Exchange Time
- Target: <500ms
- Alert threshold: >2000ms
- What to check: Network latency to Foundation
Foundation Connectivity
- Monitor: Foundation endpoint availability
- Alert on: Connection failures to /api/oauth/token
- Fallback: Maintenance page if Foundation down
Error Rate by Type
- invalid_code - Usually code expired, user retries
- state_mismatch - CSRF validation failed, investigate
- token_exchange_failed - Foundation issue, escalate
- user_sync_failed - Database issue, check Supabase

Sample Metrics Query

// In application logs/dashboard:
const metrics = {
  total_login_attempts: 1000,
  successful_logins: 990, // 99%
  failed_token_exchange: 5,
  failed_user_sync: 2,
  failed_state_validation: 3,
  avg_token_exchange_time_ms: 234,
};

Support & Troubleshooting

Common Issues During Deployment

Issue	Cause	Solution
"Client secret not found"	Missing env var	Add FOUNDATION_OAUTH_CLIENT_SECRET
"Redirect URI mismatch"	URI not registered on Foundation	Ask Foundation admin to register
"Token exchange failed 401"	Invalid credentials	Verify client_id and client_secret
"User sync failed"	Supabase error	Check user_profiles table schema
"Cookies not set"	SameSite policy blocking	Check cookie headers on response

Debug Commands

# Check environment variables (safely)
curl https://aethex.dev/api/health
# Should show that Foundation URL is configured (not the secret)

# Test Foundation connectivity
curl https://aethex.foundation/api/oauth/authorize?client_id=aethex_corp
# Should show authorization page (or redirect)

# Check database
psql -c "SELECT COUNT(*) FROM user_profiles;"
# Should show number of synced users

Getting Help

Check logs:
- Deployment platform logs (Vercel Dashboard, Railway Dashboard)
- Application logs (if available)
- Browser console (F12)
- Network tab (check requests/responses)
Verify configuration:
- Environment variables set correctly
- Foundation endpoints accessible
- Redirect URI registered
Escalate if needed:
- Contact Foundation admin for OAuth endpoint issues
- Contact Supabase for database sync issues
- Contact platform support for deployment issues

Post-Deployment

1. Verify Everything Works (Week 1)

Users can login via Foundation
User profiles sync correctly
No errors in logs
Auth success rate >99%
Response times acceptable
No support tickets about login

2. Communicate with Users (Week 1)

Send announcement: "Foundation is now your identity provider"
Explain: Existing sessions will be cleared
Remind: They'll need to login again via Foundation
Link: Documentation if they need help

3. Monitor Metrics (Week 2-3)

Track daily auth success rate
Monitor error rates
Check Foundation connectivity
Review support tickets

4. Final Cleanup (Week 3-4)

Remove old Discord OAuth code (if stable)
Archive deprecated files
Update documentation
Plan next features

Success Criteria

✅ Deployment is successful when:

Login page shows "Login with Foundation" button
Users can login and are redirected to Foundation
After Foundation auth, users redirected back to dashboard
User profiles sync to local database
Cookies are set correctly (HttpOnly, Secure)
Auth success rate >99% for 24+ hours
No critical errors in logs
Support team has no blocking issues
Users report smooth login experience
All team members approve

Deployment Checklist

Environment variables configured in deployment platform
Foundation OAuth credentials verified
Redirect URI registered on Foundation
Code deployed to staging
Staging tests pass
Production env vars set
Code deployed to production
Verify login page works
Test complete OAuth flow
Check database for user syncs
Verify cookies are set correctly
Monitor logs for errors
Monitor metrics for 24 hours
Team sign-off obtained
User communication sent
Support team briefed
Rollback plan documented
Post-deployment review scheduled

Ready to deploy? Follow this checklist step-by-step for a smooth Foundation OAuth integration!

Status: ✅ Deployment checklist complete and ready for use

12 KiB Raw Blame History

Foundation OAuth Deployment Checklist

Pre-Deployment Setup

1. Environment Variables

2. Verify Foundation is Ready

3. Verify Redirect URI

Deployment Steps

Step 1: Set Environment Variables

Step 2: Deploy Code

Step 3: Verify Deployment

Step 4: Monitor Logs

Testing Plan

Test 1: Happy Path (Successful Login)

Test 2: Error: Invalid Code

Test 3: Network Error

Test 4: Logout and Re-login

Test 5: Multiple Browsers

Production Rollout

Phase 1: Staging (First)

Phase 2: Canary (Small Percentage)

Phase 3: Full Production

Phase 4: Cleanup

Rollback Plan

Immediate Rollback (< 1 hour)

If Rollback Fails

Monitoring & Alerts

Key Metrics to Monitor

Sample Metrics Query

Support & Troubleshooting

Common Issues During Deployment

Debug Commands

Getting Help

Post-Deployment

1. Verify Everything Works (Week 1)

2. Communicate with Users (Week 1)

3. Monitor Metrics (Week 2-3)

4. Final Cleanup (Week 3-4)

Success Criteria

Deployment Checklist

12 KiB

Raw Blame History