From a263bdf7d6a430e0ecc6d1906cd578b7068fb632 Mon Sep 17 00:00:00 2001 From: "Builder.io" Date: Mon, 17 Nov 2025 02:26:14 +0000 Subject: [PATCH] Foundation OAuth Deployment Checklist cgen-a635f6693b0f45e793bf17c1f94113db --- docs/DEPLOYMENT-CHECKLIST.md | 469 +++++++++++++++++++++++++++++++++++ 1 file changed, 469 insertions(+) create mode 100644 docs/DEPLOYMENT-CHECKLIST.md diff --git a/docs/DEPLOYMENT-CHECKLIST.md b/docs/DEPLOYMENT-CHECKLIST.md new file mode 100644 index 00000000..e521695c --- /dev/null +++ b/docs/DEPLOYMENT-CHECKLIST.md @@ -0,0 +1,469 @@ +# 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.): + +```bash +# 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:** +```bash +# 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:** +1. Go to Project Settings > Environment Variables +2. Add three variables: + - `VITE_FOUNDATION_URL` = `https://aethex.foundation` + - `FOUNDATION_OAUTH_CLIENT_ID` = `aethex_corp` + - `FOUNDATION_OAUTH_CLIENT_SECRET` = (paste secret, mark as encrypted) +3. Select environments: Production, Preview, Development +4. 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:** +```bash +# For Vercel +vercel deploy --prod + +# For Railway +railway deploy + +# For Docker +docker build -t aethex-dev . +docker push /aethex-dev +# Then deploy image +``` + +### Step 3: Verify Deployment + +1. **Check environment variables:** + ```bash + # On deployed app, check logs for env var loading + # Should see Foundation URL in console (not secret though!) + ``` + +2. **Visit login page:** + - Go to https://aethex.dev/login + - Should see "Login with Foundation" button + - No console errors + +3. **Test OAuth flow:** + - Click "Login with Foundation" + - Should redirect to https://aethex.foundation/api/oauth/authorize + - Page should show Foundation login (or auth screen) + +4. **Check callback endpoint:** + - Network tab should show POST to `/auth/callback/exchange` + - Should return 200 with access_token + +5. **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: + +```bash +# 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 + +### Test 1: Happy Path (Successful Login) + +**Steps:** +1. Visit https://aethex.dev/login +2. Click "Login with Foundation" +3. Enter test credentials on Foundation +4. Should redirect back to aethex.dev/auth/callback +5. Should exchange code for token +6. Should appear logged in on dashboard + +**Expected Result:** ✅ Logged in, cookies set, profile synced + +**Check:** +```bash +# In browser console: +document.cookie # Should show foundation_access_token + +# In database: +SELECT * FROM user_profiles WHERE email = ''; +# Should show user synced with profile_completed status +``` + +### Test 2: Error: Invalid Code + +**Steps:** +1. Manually modify callback URL: `?code=invalid_code_123` +2. Press Enter + +**Expected Result:** ⚠️ Error page with message, redirect to login after 2s + +### Test 3: Network Error + +**Steps:** +1. Stop/pause Foundation service +2. Attempt login +3. Foundation redirects back with code +4. Callback tries to exchange code + +**Expected Result:** ⚠️ Error about Foundation connection, graceful redirect to login + +### Test 4: Logout and Re-login + +**Steps:** +1. Logout from dashboard (if logout button exists) +2. Check cookies are cleared +3. Login again with Foundation +4. 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) + +1. Deploy to staging environment first +2. Run full testing suite +3. Verify Foundation integration works +4. Get team sign-off +5. Monitor staging for 24 hours + +### Phase 2: Canary (Small Percentage) + +If your deployment supports canary deployments: + +1. Deploy to 5% of production traffic +2. Monitor auth success rate and errors +3. Check logs for issues +4. Gradually increase to 100% + +### Phase 3: Full Production + +1. Deploy to 100% of production +2. Have support team on standby +3. Monitor metrics closely for 24 hours +4. Have rollback plan ready + +### Phase 4: Cleanup + +After 1-2 weeks of successful deployment: + +1. Remove old Discord OAuth code (optional) +2. 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` + +3. Update documentation +4. Remove old env variables + +--- + +## Rollback Plan + +If critical issues occur: + +### Immediate Rollback (< 1 hour) + +1. **Revert deployment:** + ```bash + # Vercel + vercel rollback + + # Railway + railway rollback + ``` + +2. **Remove environment variables:** + - Remove VITE_FOUNDATION_URL + - Remove FOUNDATION_OAUTH_CLIENT_ID + - Remove FOUNDATION_OAUTH_CLIENT_SECRET + +3. **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 + +1. **Auth Success Rate** + - Target: >99% + - Alert threshold: <95% + - What to check: Logs for "Token exchange" errors + +2. **Token Exchange Time** + - Target: <500ms + - Alert threshold: >2000ms + - What to check: Network latency to Foundation + +3. **Foundation Connectivity** + - Monitor: Foundation endpoint availability + - Alert on: Connection failures to /api/oauth/token + - Fallback: Maintenance page if Foundation down + +4. **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 + +```javascript +// 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 + +```bash +# 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 + +1. **Check logs:** + - Deployment platform logs (Vercel Dashboard, Railway Dashboard) + - Application logs (if available) + - Browser console (F12) + - Network tab (check requests/responses) + +2. **Verify configuration:** + - Environment variables set correctly + - Foundation endpoints accessible + - Redirect URI registered + +3. **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:** + +1. Login page shows "Login with Foundation" button +2. Users can login and are redirected to Foundation +3. After Foundation auth, users redirected back to dashboard +4. User profiles sync to local database +5. Cookies are set correctly (HttpOnly, Secure) +6. Auth success rate >99% for 24+ hours +7. No critical errors in logs +8. Support team has no blocking issues +9. Users report smooth login experience +10. 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