# 🌐 File Protocol Testing Guide

## Overview

This guide explains how to use the test client (`test-client.html`) when opened directly from your filesystem (`file://` protocol) instead of through a web server.

---

## 🔑 The Authentication Challenge

When you open `test-client.html` directly from your filesystem:
- The file runs with `file://` protocol (e.g., `file:///C:/Users/you/TurboTrades/test-client.html`)
- Cookies set by `http://localhost:3000` are **not accessible** from `file://`
- You must use **Bearer token authentication** instead of cookies

---

## ✅ How to Authenticate

### Step 1: Login via Steam

1. **Open your browser and navigate to:**
   ```
   http://localhost:3000/auth/steam
   ```

2. **Complete Steam OAuth login**
   - You'll be redirected to Steam
   - Authorize the application
   - You'll be redirected back

3. **Get your access token**
   - After successful login, navigate to:
   ```
   http://localhost:3000/auth/decode-token
   ```
   - Copy the entire `accessToken` value from the JSON response

**Alternative: Extract from Browser Console**
```javascript
// Open browser console (F12) on http://localhost:3000
document.cookie.split('; ').find(row => row.startsWith('accessToken=')).split('=')[1]
```

---

### Step 2: Use Token in Test Client

1. **Open the test client:**
   ```
   Double-click: test-client.html
   ```

2. **Paste your token:**
   - Find the "Access Token (optional)" field in the Connection section
   - Paste your full JWT token (starts with `eyJhbGciOiJIUzI1NiIs...`)

3. **Verify authentication:**
   - Click **"🔄 Check Auth Status"** button in the Authentication Status section
   - You should see: ✅ Authenticated with your username and Steam ID

---

## 🧪 What Works Now

With your token pasted, you can use all authenticated features:

### ✅ WebSocket Connection
```
- Connect with token in URL parameter
- Receive authenticated welcome message
- Server identifies you by Steam ID
```

### ✅ Marketplace APIs
```
- Create Listing (POST /marketplace/listings)
- Update Price (PATCH /marketplace/listings/:id/price)
- Get Listings (GET /marketplace/listings) - with user-specific data
```

### ✅ User APIs
```
- Set Trade URL (PUT /user/trade-url)
- Update Email (PATCH /user/email)
- Get Profile (GET /user/profile)
- Get Balance (GET /user/balance)
- Get Stats (GET /user/stats)
```

---

## 🔍 How It Works

### API Request Flow

1. **Test client reads token from input field:**
   ```javascript
   const token = document.getElementById("token").value;
   ```

2. **Adds Authorization header to requests:**
   ```javascript
   headers: {
     "Authorization": `Bearer ${token}`,
     "Content-Type": "application/json"
   }
   ```

3. **Server validates token:**
   ```javascript
   // Server checks Authorization header first
   const authHeader = request.headers.authorization;
   if (authHeader && authHeader.startsWith("Bearer ")) {
     token = authHeader.substring(7);
   }
   // Falls back to cookies if no header
   if (!token && request.cookies.accessToken) {
     token = request.cookies.accessToken;
   }
   ```

4. **Request succeeds with user context**

---

## 🎯 Quick Start Example

### Example: Create a Listing

1. **Login and get token** (see Step 1 above)
   ```
   Your token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOi...
   ```

2. **Open test-client.html**

3. **Paste token in "Access Token" field**

4. **Click "Check Auth Status"**
   - Should show: ✅ Authenticated as [Your Name]

5. **Set your Trade URL** (if not set):
   - Get from: Steam → Inventory → Trade Offers → "Who can send me trade offers?"
   - Format: `https://steamcommunity.com/tradeoffer/new/?partner=XXXXX&token=XXXXX`
   - Click "Set Trade URL"

6. **Create a listing:**
   - Item Name: "AK-47 | Redline"
   - Game: CS2
   - Price: 45.99
   - Click "Create Listing (Requires Auth)"

7. **Success!** ✅
   - You'll get a success message
   - WebSocket will broadcast the new listing to all connected clients

---

## 🐛 Troubleshooting

### "No access token provided" Error

**Problem:** Token not being sent with request

**Solutions:**
1. Check token is pasted in "Access Token" field
2. Click "Check Auth Status" to verify
3. Token must be the full JWT (starts with `eyJhbGci...`)
4. Token expires after 15 minutes - get a new one

---

### "Invalid access token" Error

**Problem:** Token is expired or malformed

**Solutions:**
1. Login again to get a fresh token
2. Copy the entire token (no spaces or line breaks)
3. Check token hasn't expired (15 minute lifespan)

---

### "Trade URL must be set" Error

**Problem:** Trying to create listing without trade URL

**Solutions:**
1. Set your trade URL first using the "Set Trade URL" section
2. Get your trade URL from Steam:
   - Steam → Inventory → Trade Offers
   - "Who can send me trade offers?"
   - Copy the URL

---

### Authentication Status Shows "Not Authenticated"

**Problem:** Token not recognized or not present

**Solutions:**
1. Make sure you pasted the token in the "Access Token" field
2. Click "Check Auth Status" button
3. If still failing, get a new token (it may have expired)
4. Check browser console for specific error messages

---

## 📊 Token Information

### Your Current Token

```
Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2OTYxMzRlOTIwNzYxOTc3ZGNjMWQ2ZDIiLCJzdGVhbUlkIjoiNzY1NjExOTgwMjc2MDgwNzEiLCJ1c2VybmFtZSI6IuKchSBBc2hsZXkg44Ki44K344Ol44Oq44O8IiwiYXZhdGFyIjoiaHR0cHM6Ly9hdmF0YXJzLnN0ZWFtc3RhdGljLmNvbS9kNmI2MTY0NjQ2MjlkYjIxNjcwYTQ0NTY3OWFlZmVlYjE4ZmI0MDFmX2Z1bGwuanBnIiwic3RhZmZMZXZlbCI6MCwiaWF0IjoxNzY3OTk0MzkwLCJleHAiOjE3Njc5OTUyOTAsImF1ZCI6InR1cmJvdHJhZGVzLWFwaSIsImlzcyI6InR1cmJvdHJhZGVzIn0.9Xh-kDvWZbQERuXgRb-NEMw6il2h8SQyVQySdILcLo8

User ID: 696134e92076197...[truncated]
Steam ID: 76561198027608071
Username: ✅ Ashley アシュリー
Staff Level: 0
Issued At: 1767994390 (Unix timestamp)
Expires At: 1767995290 (Unix timestamp - 15 minutes from issue)
```

### Token Lifespan
- **Access Token:** 15 minutes
- **Refresh Token:** 7 days (stored in cookies, not available in file:// protocol)

### When Token Expires
1. Navigate to `http://localhost:3000/auth/steam` again
2. You'll be automatically logged in (Steam session still active)
3. Get new token from `/auth/decode-token`
4. Paste new token in test client

---

## 🎓 Advanced Tips

### Save Token Temporarily
```javascript
// In browser console on test client page
localStorage.setItem('authToken', 'YOUR_TOKEN_HERE');

// Load it later
const token = localStorage.getItem('authToken');
document.getElementById('token').value = token;
```

### Check Token Expiry
```javascript
// Decode JWT (client-side, no verification)
function parseJwt(token) {
  const base64Url = token.split('.')[1];
  const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
  const jsonPayload = decodeURIComponent(atob(base64).split('').map(c => {
    return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2);
  }).join(''));
  return JSON.parse(jsonPayload);
}

const decoded = parseJwt(YOUR_TOKEN);
const expiresAt = new Date(decoded.exp * 1000);
console.log('Token expires at:', expiresAt);
```

### Auto-Refresh Before Expiry
```javascript
// Set up auto-refresh 1 minute before expiry
const decoded = parseJwt(token);
const expiresIn = (decoded.exp * 1000) - Date.now();
const refreshTime = expiresIn - 60000; // 1 minute before

if (refreshTime > 0) {
  setTimeout(() => {
    alert('Token expiring soon! Please get a new token.');
  }, refreshTime);
}
```

---

## 🌐 Alternative: Use a Web Server

If you prefer cookie-based authentication:

### Option 1: Simple HTTP Server (Python)
```bash
cd TurboTrades
python -m http.server 8000
```
Then open: `http://localhost:8000/test-client.html`

### Option 2: Node.js HTTP Server
```bash
cd TurboTrades
npx http-server -p 8000
```
Then open: `http://localhost:8000/test-client.html`

### Option 3: VS Code Live Server
1. Install "Live Server" extension
2. Right-click `test-client.html`
3. Select "Open with Live Server"

**Note:** With a web server, cookies will work and you don't need to paste tokens!

---

## 📋 Testing Checklist

### With Token Authentication (file:// protocol)
- [ ] Login via Steam
- [ ] Get access token
- [ ] Paste token in test client
- [ ] Check auth status (should show ✅)
- [ ] Connect WebSocket with token
- [ ] Set trade URL
- [ ] Create listing
- [ ] Update listing price
- [ ] Get listings
- [ ] Verify WebSocket broadcasts received

---

## 🔐 Security Notes

### Token Security
- ✅ Token is sent via HTTPS in production
- ✅ Token expires after 15 minutes
- ✅ Token is JWT signed and verified server-side
- ⚠️ Don't share your token with others
- ⚠️ Don't commit tokens to version control

### File Protocol Limitations
- ❌ Cookies don't work across protocols
- ❌ Can't access localStorage from different origin
- ✅ Authorization header works perfectly
- ✅ CORS configured to allow file:// protocol

---

## 📚 Related Documentation

- **WEBSOCKET_AUTH.md** - WebSocket authentication details
- **TESTING_GUIDE.md** - Comprehensive testing guide
- **TEST_CLIENT_REFERENCE.md** - Quick reference for test client
- **NEW_FEATURES.md** - Latest features and enhancements

---

## 💡 Summary

**File Protocol Testing Flow:**
1. Login via `http://localhost:3000/auth/steam`
2. Get token from `/auth/decode-token`
3. Paste token in test client "Access Token" field
4. Click "Check Auth Status"
5. Use all authenticated features! 🎉

**Key Points:**
- Token authentication works from `file://` protocol
- Token lasts 15 minutes
- Server accepts `Authorization: Bearer <token>` header
- All API requests automatically include your token
- WebSocket can use token via query parameter

**You're all set! Happy testing! 🚀**