TurboTrades/TROUBLESHOOTING_AUTH.md

# Authentication Troubleshooting Guide

This guide will help you debug authentication issues with sessions and 2FA endpoints.

## Quick Diagnosis Steps

### Step 1: Check if you're actually logged in

1. Open your browser console (F12)
2. Run this command:
```javascript
console.log('Cookies:', document.cookie);
```

You should see `accessToken` and `refreshToken` in the output. If not, you're not actually logged in.

### Step 2: Check the debug endpoint

1. While logged in, navigate to: `http://localhost:5173/api/auth/debug-cookies`
2. Or in console run:
```javascript
fetch('/api/auth/debug-cookies', { credentials: 'include' })
  .then(r => r.json())
  .then(d => console.log(d));
```

This will show:
- All cookies the backend receives
- All relevant headers
- Cookie configuration settings

**Expected output:**
```json
{
  "success": true,
  "hasAccessToken": true,
  "hasRefreshToken": true,
  "cookies": {
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc..."
  }
}
```

**If `hasAccessToken` is `false`**, proceed to Step 3.

### Step 3: Inspect browser cookies

1. Open DevTools (F12)
2. Go to **Application** tab (Chrome) or **Storage** tab (Firefox)
3. Click on **Cookies** in the left sidebar
4. Select your domain (`http://localhost:5173`)

**Check these cookie properties:**

| Property | Expected Value (Development) | Problem if Different |
|----------|------------------------------|---------------------|
| **Domain** | `localhost` | If it's `127.0.0.1` or `0.0.0.0`, cookie won't be sent |
| **Path** | `/` | If different, cookie may not apply to `/api/*` routes |
| **SameSite** | `Lax` or `None` | If `Strict`, cookies may not be sent on redirects |
| **Secure** | ☐ (unchecked) | If checked, cookies won't work on http://localhost |
| **HttpOnly** | ☑ (checked) | This is correct - JavaScript can't access it |

### Step 4: Check Network requests

1. Open DevTools → **Network** tab
2. Try to access sessions: Click "Active Sessions" or refresh your profile
3. Find the request to `/api/user/sessions`
4. Click on it and check the **Headers** tab

**In Request Headers, look for:**
```
Cookie: accessToken=eyJhbGc...; refreshToken=eyJhbGc...
```

**If the Cookie header is missing or doesn't include `accessToken`:**
- The browser is not sending the cookies
- This is usually due to incorrect cookie attributes (see Step 3)

## Common Issues & Solutions

### Issue 1: Cookies have wrong domain

**Symptoms:**
- Cookies exist in DevTools but aren't sent with requests
- `debug-cookies` shows `hasAccessToken: false`

**Solution:**
1. Check your backend `.env` file or `config/index.js`
2. Ensure `COOKIE_DOMAIN=localhost` (NOT `127.0.0.1` or `0.0.0.0`)
3. Restart the backend server
4. Log out and log back in via Steam

**Backend config check:**
```bash
# In backend directory
cat .env | grep COOKIE_DOMAIN
# Should show: COOKIE_DOMAIN=localhost
```

### Issue 2: Cookies are Secure but you're on HTTP

**Symptoms:**
- After Steam login, you're redirected back but cookies don't persist
- Chrome console shows warnings about Secure cookies on insecure origin

**Solution:**
1. Set `COOKIE_SECURE=false` in your `.env` or `config/index.js`
2. Restart backend
3. Clear all cookies for `localhost`
4. Log in again

### Issue 3: SameSite=Strict blocking cookies

**Symptoms:**
- Cookies set but not sent after Steam redirect
- Works on direct page load but not after navigation

**Solution:**
1. Set `COOKIE_SAME_SITE=lax` in your backend config
2. Restart backend
3. Log out and log in again

### Issue 4: CORS misconfiguration

**Symptoms:**
- Network errors in console
- 401 Unauthorized even though cookies exist

**Solution:**
1. Check backend `config/index.js`:
   ```javascript
   cors: {
     origin: "http://localhost:5173",  // Must match frontend URL exactly
     credentials: true,
   }
   ```
2. Ensure Vite dev server is running on `http://localhost:5173`
3. Restart backend

### Issue 5: Axios not sending credentials

**Symptoms:**
- Cookies exist but requests don't include them
- Works in Postman/curl but not in browser

**Solution:**
Check `frontend/src/utils/axios.js`:
```javascript
const axiosInstance = axios.create({
  baseURL: '/api',
  withCredentials: true,  // This is CRITICAL
  // ...
})
```

Also ensure individual requests include it:
```javascript
axios.get('/api/user/sessions', { 
  withCredentials: true  // Add this if missing
})
```

## Backend Debugging

### View authentication debug logs

The backend now has verbose debug logging. When you try to access `/api/user/sessions`, you'll see:

```
=== AUTH MIDDLEWARE DEBUG ===
URL: /user/sessions
Method: GET
Cookies present: [ 'accessToken', 'refreshToken' ]
Has accessToken cookie: true
Authorization header: Missing
Origin: http://localhost:5173
✓ Token found in cookies
✓ Token verified, userId: 65abc123...
✓ User authenticated: YourUsername
=== END AUTH DEBUG ===
```

**If you see "No token found":**
- The backend is not receiving cookies
- Check cookie domain/path/secure settings

**If you see "Token verified" but still get 401:**
- Check the user exists in the database
- Check for ban status

### Test with curl

If you have cookies working in the browser, test directly:

1. Copy cookie values from DevTools
2. Run:
```bash
curl -v http://localhost:3000/user/sessions \
  -H "Cookie: accessToken=YOUR_TOKEN_HERE; refreshToken=YOUR_REFRESH_HERE"
```

If curl works but browser doesn't:
- CORS issue
- Browser security policy blocking cookies
- Check browser console for security warnings

## Manual Cookie Fix

If all else fails, manually set correct cookie attributes:

1. Log in via Steam
2. After redirect, open DevTools console
3. Run this in backend terminal to check current cookies:
```bash
# Look at the Steam callback code in routes/auth.js
# Check the cookie settings being used
```

4. Modify `config/index.js`:
```javascript
cookie: {
  domain: 'localhost',           // NOT 127.0.0.1 or 0.0.0.0
  secure: false,                 // Must be false for http://
  sameSite: 'lax',              // Not 'strict'
  httpOnly: true,               // Keep this true
},
```

5. Restart backend: `npm run dev`
6. Clear all cookies: DevTools → Application → Cookies → Right-click localhost → Clear
7. Log in again

## Environment File Template

Create/update `TurboTrades/.env`:

```env
# Server
NODE_ENV=development
PORT=3000
HOST=0.0.0.0

# Database
MONGODB_URI=mongodb://localhost:27017/turbotrades

# JWT
JWT_ACCESS_SECRET=your-super-secret-access-key-change-this
JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-this
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# Steam
STEAM_API_KEY=your_steam_api_key_here
STEAM_REALM=http://localhost:3000
STEAM_RETURN_URL=http://localhost:3000/auth/steam/return

# Cookies - CRITICAL FOR DEVELOPMENT
COOKIE_DOMAIN=localhost
COOKIE_SECURE=false
COOKIE_SAME_SITE=lax

# CORS - Must match frontend URL exactly
CORS_ORIGIN=http://localhost:5173

# Session
SESSION_SECRET=your-session-secret-change-this
```

## Testing Checklist

Run through this checklist:

- [ ] Backend running on `http://localhost:3000`
- [ ] Frontend running on `http://localhost:5173`
- [ ] MongoDB running and connected
- [ ] Steam API key configured
- [ ] Can visit `http://localhost:5173` and see the site
- [ ] Can visit `http://localhost:3000/health` and get response
- [ ] Can click "Login with Steam" and complete OAuth
- [ ] After login, redirected back to frontend
- [ ] DevTools shows `accessToken` and `refreshToken` cookies for `localhost`
- [ ] Cookies have `Domain: localhost` (not `127.0.0.1`)
- [ ] Cookies have `Secure: false` (unchecked)
- [ ] Cookies have `SameSite: Lax`
- [ ] Profile page shows your username and avatar (means `/auth/me` worked)
- [ ] `/api/auth/debug-cookies` shows `hasAccessToken: true`
- [ ] Network tab shows `Cookie` header on `/api/user/sessions` request
- [ ] Backend console shows "✓ User authenticated" in debug logs

## Still Not Working?

If you've gone through all the above and it still doesn't work:

1. **Check browser console** for any JavaScript errors
2. **Check backend logs** (`backend.log` or terminal output)
3. **Try a different browser** (sometimes browser extensions interfere)
4. **Try incognito/private mode** (rules out extension interference)
5. **Check if MongoDB is running** and has the User document
6. **Verify the Steam login actually created/updated your user** in MongoDB

### MongoDB Check

```bash
# Connect to MongoDB
mongosh

# Switch to database
use turbotrades

# Find your user
db.users.findOne({ steamId: "YOUR_STEAM_ID" })

# Check if sessions exist
db.sessions.find({ steamId: "YOUR_STEAM_ID" })
```

## Getting Help

If you're still stuck, gather this information:

1. Output of `/api/auth/debug-cookies`
2. Screenshot of DevTools → Application → Cookies
3. Screenshot of DevTools → Network → `/api/user/sessions` request headers
4. Backend console output when you try to access sessions
5. Frontend console errors (if any)
6. Your `config/index.js` cookie settings (remove secrets)

Good luck! 🚀