foxhunt/tests/e2e_helpers/USAGE_EXAMPLES.md

# JWT Token Generator - Usage Examples

Quick reference for common JWT token generation scenarios in E2E testing.

## Basic Usage

### Generate Default Token
```bash
./jwt_token_generator.sh
```
Output: Trader token with `api.access` permission, 1-hour expiration

### Use in Curl Request
```bash
TOKEN=$(./jwt_token_generator.sh)
curl -H "Authorization: Bearer $TOKEN" http://localhost:50051/api/v1/orders
```

## Role-Based Scenarios

### Trader (Default)
```bash
./jwt_token_generator.sh
# or
./jwt_token_generator.sh trader_user trader "api.access"
```

### Admin User
```bash
./jwt_token_generator.sh admin_user admin "api.access,system.admin,config.write"
```

### Viewer (Read-Only)
```bash
./jwt_token_generator.sh viewer_user viewer "api.read,data.read,metrics.view"
```

## Custom Expiration

### Short-Lived (60 seconds)
```bash
./jwt_token_generator.sh test_user trader "api.access" 60
```

### Long-Lived (24 hours)
```bash
./jwt_token_generator.sh test_user trader "api.access" 86400
```

### Very Short (10 seconds, for expiration testing)
```bash
./jwt_token_generator.sh test_user trader "api.access" 10
```

## Permission Combinations

### Trading Permissions
```bash
./jwt_token_generator.sh trader_user trader "api.access,orders.submit,orders.cancel,positions.view"
```

### Risk Management
```bash
./jwt_token_generator.sh risk_user risk_manager "api.access,risk.view,risk.limits,circuit.breaker"
```

### System Administration
```bash
./jwt_token_generator.sh admin_user admin "api.access,system.admin,config.write,config.reload,users.manage"
```

### Monitoring Only
```bash
./jwt_token_generator.sh monitor_user viewer "api.access,metrics.view,health.check,alerts.view"
```

## Integration Test Scripts

### Order Submission Test
```bash
#!/bin/bash
TOKEN=$(./jwt_token_generator.sh)

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC/USD", "quantity": 1.0, "side": "buy", "price": 50000.0}' \
  http://localhost:50051/api/v1/orders
```

### Position Query Test
```bash
#!/bin/bash
TOKEN=$(./jwt_token_generator.sh)

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:50051/api/v1/positions
```

### Config Management Test (Admin)
```bash
#!/bin/bash
ADMIN_TOKEN=$(./jwt_token_generator.sh admin_user admin "api.access,config.write")

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "max_order_size", "value": "100.0"}' \
  http://localhost:50051/api/v1/config
```

## Load Testing

### Generate Multiple User Tokens
```bash
#!/bin/bash
# Generate 100 unique user tokens
for i in {1..100}; do
    TOKEN=$(./jwt_token_generator.sh "user_$i" trader "api.access")
    echo "$TOKEN" > "tokens/token_$i.txt"
done
```

### Parallel Requests
```bash
#!/bin/bash
# Use different tokens for concurrent requests
for i in {1..10}; do
    TOKEN=$(cat "tokens/token_$i.txt")
    curl -H "Authorization: Bearer $TOKEN" \
      http://localhost:50051/api/v1/orders &
done
wait
```

## Token Expiration Testing

### Test Expired Token
```bash
#!/bin/bash
# Generate 5-second token
TOKEN=$(./jwt_token_generator.sh test_user trader "api.access" 5)

# Use immediately (should succeed)
curl -H "Authorization: Bearer $TOKEN" http://localhost:50051/api/v1/orders
echo "First request: OK"

# Wait for expiration
sleep 6

# Use again (should fail with 401)
curl -H "Authorization: Bearer $TOKEN" http://localhost:50051/api/v1/orders
echo "Second request: Should fail with 401"
```

### Test Token Refresh
```bash
#!/bin/bash
# Old token (about to expire)
OLD_TOKEN=$(./jwt_token_generator.sh user1 trader "api.access" 10)

# New token (fresh)
NEW_TOKEN=$(./jwt_token_generator.sh user1 trader "api.access" 3600)

# Use old token
curl -H "Authorization: Bearer $OLD_TOKEN" http://localhost:50051/api/v1/orders

# Wait for old token to expire
sleep 11

# Use new token (should work)
curl -H "Authorization: Bearer $NEW_TOKEN" http://localhost:50051/api/v1/orders
```

## Environment Variable Configuration

### Production Secret
```bash
export JWT_SECRET="your-production-secret-key-here-must-be-long-enough-for-security"
TOKEN=$(./jwt_token_generator.sh)
```

### Multiple Environments
```bash
# Development
JWT_SECRET="dev-secret-123" DEV_TOKEN=$(./jwt_token_generator.sh)

# Staging
JWT_SECRET="staging-secret-456" STAGING_TOKEN=$(./jwt_token_generator.sh)

# Production
JWT_SECRET="prod-secret-789" PROD_TOKEN=$(./jwt_token_generator.sh)
```

## Debugging

### Inspect Token Claims
```bash
TOKEN=$(./jwt_token_generator.sh)

# Decode token (requires python3 and pyjwt)
python3 <<EOF
import jwt
import json
token = "$TOKEN"
decoded = jwt.decode(token, options={"verify_signature": False})
print(json.dumps(decoded, indent=2))