dubs-server 1.0.0

package/documentation/JWT_TESTING_GUIDE.md

@@ -0,0 +1,404 @@
+# 🧪 JWT Authentication Testing Guide
+
+## ⚠️ Critical Fixes Applied
+
+I found and fixed **3 critical bugs** that were preventing JWT authentication from working:
+
+### Bug #1: Session Not Created on Wallet Connection
+**Problem:** When existing users connected their wallet, the code checked if they existed in the database and marked them as "authenticated", but **never actually called the login endpoint** to create a JWT session.
+
+**Fix:** Updated `AuthContext` to:
+1. First check if there's a valid JWT session (via `validateSession()`)
+2. If no valid session, prompt user to sign in (which creates JWT session)
+
+### Bug #2: Cookie SameSite Policy
+**Problem:** `sameSite: 'strict'` blocks cookies between different ports in development (localhost:3000 → localhost:3001).
+
+**Fix:** Changed to `sameSite: 'lax'` in development, `'strict'` in production.
+
+### Bug #3: Error Handling in Logout
+**Problem:** Logout would throw errors if there was no session.
+
+**Fix:** Added proper error handling to ignore 401 errors on logout.
+
+---
+
+## 🚀 How to Test the Fix
+
+### Step 1: Restart Both Servers
+
+```bash
+# Terminal 1 - Backend
+cd dubs-server
+npm start
+
+# Terminal 2 - Frontend
+cd dubs-jackpot
+npm run dev
+```
+
+**Important:** You MUST restart both servers for changes to take effect!
+
+### Step 2: Clear Browser State
+
+1. Open DevTools (F12)
+2. Go to Application → Storage
+3. Click "Clear site data"
+4. Refresh the page
+
+This removes any old cookies or state.
+
+### Step 3: Test New User Registration
+
+1. Navigate to `http://localhost:3000/v2`
+2. Click **"Connect Wallet"**
+3. Select your wallet and connect
+4. You should see the **"Sign Message"** modal
+5. Click **"Sign Message"** in the modal
+6. Sign the message in your wallet
+7. You should see the **"Complete Your Profile"** registration modal
+8. Fill in:
+   - Username (required)
+   - Email (required)
+   - Avatar URL (optional)
+   - Referral Code (optional)
+9. Click **"Create Account"**
+
+**Expected Result:**
+- ✅ User registered
+- ✅ JWT token created
+- ✅ Cookie set in browser
+- ✅ User marked as authenticated
+
+### Step 4: Verify JWT Cookie
+
+1. Open DevTools → Application → Cookies → `http://localhost:3000`
+2. Look for cookie named `auth_token`
+3. Verify properties:
+   - ✅ `HttpOnly`: Yes
+   - ✅ `Secure`: No (dev mode)
+   - ✅ `SameSite`: Lax (dev mode)
+   - ✅ `Path`: /
+   - ✅ `Expires`: 7 days from now
+
+**Screenshot where to find:**
+```
+DevTools > Application (tab)
+  > Storage (left sidebar)
+    > Cookies
+      > http://localhost:3000
+        > auth_token (should appear here)
+```
+
+### Step 5: Test Authenticated API Call
+
+Open browser console and run:
+
+```javascript
+fetch('http://localhost:3001/auth/validate-session', {
+  credentials: 'include'
+})
+  .then(r => r.json())
+  .then(data => console.log('Session validation:', data))
+  .catch(err => console.error('Error:', err));
+```
+
+**Expected Result:**
+```json
+{
+  "success": true,
+  "valid": true,
+  "user": {
+    "id": 1,
+    "wallet_address": "your_wallet_address",
+    "username": "your_username",
+    "email": "your_email",
+    "onboarding_complete": false
+  }
+}
+```
+
+### Step 6: Complete Onboarding
+
+1. Click through the onboarding modal
+2. Click **"Start Playing"** or similar button
+
+**Expected Result:**
+- ✅ `onboarding_complete` set to `true`
+- ✅ User marked as fully authenticated
+
+### Step 7: Test Logout
+
+1. Open the user menu (hamburger icon / profile icon)
+2. Click **"Disconnect Wallet"**
+
+**Expected Result:**
+- ✅ Logout API call succeeds (200 OK)
+- ✅ Cookie cleared from browser
+- ✅ User disconnected
+- ✅ Auth state reset
+
+### Step 8: Test Existing User Login
+
+1. Connect wallet again (same wallet as before)
+2. You should see **"Sign Message"** modal (to create new session)
+3. Sign the message
+4. **NO registration form** should appear
+5. You should be automatically logged in
+
+**Expected Result:**
+- ✅ User detected as existing
+- ✅ Login endpoint called (not register)
+- ✅ JWT token created
+- ✅ Cookie set
+- ✅ User authenticated immediately
+
+---
+
+## 🔍 Debugging Checklist
+
+### If Registration Fails
+
+**Check Backend Logs:**
+```bash
+# Should see:
+[Auth] Nonce generated successfully
+[Auth] Signature verified successfully, nonce marked as used
+[Auth] User registered and session created: <wallet_address>
+```
+
+**Check Network Tab (DevTools):**
+- `POST /auth/nonce/<wallet>` → 200 OK
+- `POST /auth/verify-signature` → 200 OK, `{ valid: true }`
+- `POST /auth/register` → 200 OK, sets cookie
+
+### If Cookie Not Set
+
+**Check Response Headers (Network Tab → /auth/register):**
+```
+Set-Cookie: auth_token=eyJhbGc...; Path=/; HttpOnly; SameSite=Lax
+```
+
+**Common Issues:**
+1. ❌ CORS not configured → Add `withCredentials: true` to axios
+2. ❌ Cookie blocked → Check `sameSite` is `lax` in dev
+3. ❌ Wrong domain → Verify cookie domain matches frontend
+4. ❌ Browser privacy settings → Disable "Block third-party cookies"
+
+### If 401 Unauthorized on Protected Endpoints
+
+**Check:**
+1. Cookie exists in Application → Cookies
+2. Cookie is being sent (Network tab → Request Headers → `Cookie: auth_token=...`)
+3. Token hasn't expired (check `expires_at` in database)
+4. Session exists in database:
+   ```sql
+   SELECT * FROM user_sessions WHERE expires_at > NOW();
+   ```
+
+### If Login Doesn't Work
+
+**Check Console Logs:**
+```
+[Auth] Checking for existing session...
+[Auth] No valid session, checking if user exists...
+[Auth] User exists but needs to sign in
+[Auth] Existing user detected, logging in...
+[Auth] User logged in successfully: <wallet>
+```
+
+**Check Network Tab:**
+- `GET /auth/validate-session` → 401 (expected if no session)
+- `GET /auth/user/<wallet>` → 200 OK (user exists)
+- `POST /auth/login` → 200 OK, sets cookie
+
+---
+
+## 🧪 Database Verification
+
+### Check User Created
+```sql
+SELECT wallet_address, username, email, onboarding_complete, created_at
+FROM users
+ORDER BY created_at DESC
+LIMIT 5;
+```
+
+### Check Session Created
+```sql
+SELECT 
+  s.id,
+  s.wallet_address,
+  u.username,
+  s.expires_at,
+  s.created_at,
+  s.last_activity
+FROM user_sessions s
+JOIN users u ON s.user_id = u.id
+WHERE s.expires_at > NOW()
+ORDER BY s.created_at DESC;
+```
+
+### Check Nonces
+```sql
+SELECT wallet_address, nonce, expires_at, used, created_at
+FROM auth_nonces
+ORDER BY created_at DESC
+LIMIT 5;
+```
+
+---
+
+## 🎯 Success Criteria
+
+You know authentication is working when:
+
+- ✅ New users can register
+- ✅ JWT cookie appears in browser
+- ✅ Registration sets `auth_token` cookie
+- ✅ Login sets `auth_token` cookie
+- ✅ `/auth/validate-session` returns 200 OK with user data
+- ✅ Protected endpoints accept authenticated requests
+- ✅ Logout clears cookie and session
+- ✅ Existing users can sign in again
+- ✅ Sessions persist across page refreshes
+- ✅ Multiple tabs share same session
+
+---
+
+## 🐛 Common Errors & Fixes
+
+### Error: "JWT_SECRET not set"
+**Fix:** Add to `.env`:
+```bash
+JWT_SECRET=$(node -e "console.log(require('crypto').randomBytes(64).toString('hex'))")
+```
+
+### Error: "Database connection error"
+**Fix:** 
+1. Check PostgreSQL is running: `psql --version`
+2. Verify DATABASE_URL in `.env`
+3. Test connection: `psql $DATABASE_URL -c "SELECT 1"`
+
+### Error: "Cookie not being sent"
+**Fix:**
+1. Verify `withCredentials: true` in api.ts ✅ (already set)
+2. Verify `credentials: true` in CORS ✅ (already set)
+3. Check cookie `sameSite` is `lax` ✅ (fixed)
+4. Restart both servers
+
+### Error: "401 Unauthorized" after registration
+**Fix:** 
+- Check session was created in database
+- Verify cookie was set (DevTools → Application → Cookies)
+- Check backend logs for errors
+
+### Error: "Logout fails with 401"
+**Fix:** ✅ Already handled - logout now ignores 401 errors
+
+---
+
+## 📱 Testing on Different Browsers
+
+Test on multiple browsers to verify cookie behavior:
+
+- ✅ Chrome (strict cookie policies)
+- ✅ Firefox (different cookie handling)
+- ✅ Safari (very strict, might block)
+- ✅ Brave (aggressive blocking, might fail)
+
+**Note:** Some privacy-focused browsers block cross-origin cookies by default.
+
+---
+
+## 🔐 Security Verification
+
+### Check Cookie Security
+```javascript
+// In browser console
+document.cookie
+// Should return empty (httpOnly prevents access)
+```
+
+### Check Token in Database
+```sql
+SELECT token_hash FROM user_sessions LIMIT 1;
+-- Should be a SHA256 hash, NOT the raw JWT
+```
+
+### Verify HTTPS in Production
+```bash
+# In production .env
+NODE_ENV=production
+
+# Cookie should have Secure flag
+# Check in DevTools → Application → Cookies → Secure: Yes
+```
+
+---
+
+## 📊 Expected Network Flow
+
+### New User Registration:
+```
+1. GET  /auth/nonce/<wallet>              → 200 OK
+2. POST /auth/verify-signature            → 200 OK
+3. POST /auth/register                    → 200 OK + Set-Cookie
+4. GET  /auth/validate-session            → 200 OK (with cookie)
+```
+
+### Existing User Login:
+```
+1. GET  /auth/nonce/<wallet>              → 200 OK  
+2. POST /auth/login                       → 200 OK + Set-Cookie
+3. GET  /auth/validate-session            → 200 OK (with cookie)
+```
+
+### Logout:
+```
+1. POST /auth/logout                      → 200 OK + Clear cookie
+2. GET  /auth/validate-session            → 401 Unauthorized
+```
+
+---
+
+## ✅ Final Checklist
+
+Before moving to production:
+
+- [ ] JWT_SECRET is strong and unique (64+ chars)
+- [ ] NODE_ENV=production in prod .env
+- [ ] Database has SSL enabled
+- [ ] CORS origins restricted to your domains
+- [ ] Cookie Secure flag enabled (HTTPS)
+- [ ] Session cleanup cron job running
+- [ ] Monitoring/logging set up
+- [ ] Rate limiting configured
+- [ ] Database backups enabled
+
+---
+
+## 🆘 Still Having Issues?
+
+1. **Check all console logs** (frontend + backend)
+2. **Check Network tab** for all API calls
+3. **Check Database** for users/sessions
+4. **Verify environment variables** are loaded
+5. **Restart both servers** completely
+6. **Clear browser data** and try again
+
+If still stuck:
+- Review `JWT_QUICK_SETUP.md`
+- Review `documentation/JWT_AUTHENTICATION.md`
+- Check server logs for specific error messages
+
+---
+
+**Remember:** The key changes were:
+1. ✅ Session validation on wallet connect
+2. ✅ Cookie SameSite set to 'lax' in dev
+3. ✅ Proper error handling in logout
+
+**These fixes make the authentication flow work correctly!**
+
+