foxhunt/tests/e2e_helpers/README.md

# E2E Testing Helpers

Helper scripts and utilities for end-to-end testing of the Foxhunt HFT Trading System.

## JWT Token Generator

**File**: `jwt_token_generator.sh`

Generates valid JWT tokens for testing API Gateway authentication. The token structure matches the production API Gateway implementation.

### Quick Start

```bash
# Generate default trader token
./jwt_token_generator.sh

# Generate admin token
./jwt_token_generator.sh admin_user admin "api.access,system.admin"

# Generate token with 10-minute expiration
./jwt_token_generator.sh test_user trader "api.access" 600

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

### Arguments

| Position | Name | Default | Description |
|----------|------|---------|-------------|
| 1 | user_id | `test_user_123` | User identifier |
| 2 | role | `trader` | User role (trader, admin, viewer) |
| 3 | permissions | `api.access` | Comma-separated permissions |
| 4 | ttl_seconds | `3600` | Token expiration in seconds |

### Environment Variables

- `JWT_SECRET` - JWT signing secret (default: test secret matching API Gateway)

**Production**: Set `JWT_SECRET` environment variable to match your deployment:
```bash
export JWT_SECRET="your-production-secret-key"
./jwt_token_generator.sh
```

### Token Structure

Generated tokens include the following claims (matching `services/api_gateway/tests/common/mod.rs`):

**Standard JWT Claims**:
- `sub` - Subject (user ID)
- `iat` - Issued at (Unix timestamp)
- `exp` - Expiration (Unix timestamp)
- `nbf` - Not before (Unix timestamp)
- `iss` - Issuer (`foxhunt-api-gateway`)
- `aud` - Audience (`foxhunt-services`)
- `jti` - JWT ID (UUID, for revocation support)

**Foxhunt-Specific Claims**:
- `roles` - User roles array (RBAC)
- `permissions` - Granular permissions array
- `token_type` - Token type (`access` or `refresh`)
- `session_id` - Session identifier (UUID)

### Common Use Cases

#### 1. Test API Gateway Authentication

```bash
# Generate token
TOKEN=$(./jwt_token_generator.sh)

# Test health endpoint (no auth required)
curl http://localhost:8080/health

# Test authenticated endpoint
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:50051/api/v1/orders
```

#### 2. Test Role-Based Access Control (RBAC)

```bash
# Trader role (limited permissions)
TRADER_TOKEN=$(./jwt_token_generator.sh trader_user trader "api.access")

# Admin role (full permissions)
ADMIN_TOKEN=$(./jwt_token_generator.sh admin_user admin "api.access,system.admin")

# Test trader permissions
curl -H "Authorization: Bearer $TRADER_TOKEN" \
     http://localhost:50051/api/v1/orders

# Test admin permissions
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
     http://localhost:50051/api/v1/config
```

#### 3. Test Token Expiration

```bash
# Short-lived token (30 seconds)
SHORT_TOKEN=$(./jwt_token_generator.sh test_user trader "api.access" 30)

# Use immediately (should succeed)
curl -H "Authorization: Bearer $SHORT_TOKEN" \
     http://localhost:50051/api/v1/orders

# Wait 31 seconds
sleep 31

# Use again (should fail with 401 Unauthorized)
curl -H "Authorization: Bearer $SHORT_TOKEN" \
     http://localhost:50051/api/v1/orders
```

#### 4. Load Testing with Multiple Users

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

# Use in load test
TOKEN=$(cat token_1.txt)
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:50051/api/v1/orders
```

#### 5. Integration Test Scripts

```bash
#!/bin/bash
# test_trading_flow.sh

# Generate authentication token
TOKEN=$(./jwt_token_generator.sh)

# Submit order
ORDER_RESPONSE=$(curl -s -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"symbol": "BTC/USD", "quantity": 1.0, "price": 50000.0}' \
    http://localhost:50051/api/v1/orders)

# Extract order ID
ORDER_ID=$(echo "$ORDER_RESPONSE" | jq -r '.order_id')

# Check order status
curl -H "Authorization: Bearer $TOKEN" \
     "http://localhost:50051/api/v1/orders/$ORDER_ID"
```

### Validation

The generated tokens are validated against the same structure used in Rust tests:

**Source**: `services/api_gateway/tests/common/mod.rs` (lines 28-62)

```rust
pub fn generate_test_token(
    user_id: &str,
    roles: Vec<String>,
    permissions: Vec<String>,
    ttl_seconds: u64,
) -> Result<(String, String)> {
    // ... (matches this script's implementation)
}
```

### Dependencies

**Required**:
- Python 3.x
- PyJWT library: `pip install pyjwt`

**Installation**:
```bash
# Ubuntu/Debian
sudo apt-get install python3 python3-pip
pip3 install pyjwt

# macOS
brew install python3
pip3 install pyjwt

# Verify installation
python3 -c "import jwt; print('PyJWT installed:', jwt.__version__)"
```

### Troubleshooting

#### Error: "PyJWT library not found"

```bash
# Install PyJWT
pip3 install pyjwt

# Or use system package manager
sudo apt-get install python3-jwt  # Debian/Ubuntu
```

#### Error: "python3 not found"

```bash
# Install Python 3
sudo apt-get install python3  # Debian/Ubuntu
brew install python3         # macOS
```

#### Token Validation Fails

Ensure JWT_SECRET matches your API Gateway configuration:

```bash
# Check API Gateway secret (default for development)
export JWT_SECRET="test-secret-must-be-at-least-64-characters-long-for-security-validation-ok-1234567890"

# Generate token with correct secret
TOKEN=$(./jwt_token_generator.sh)
```

#### Token Expired

Default expiration is 1 hour (3600 seconds). Generate fresh token:

```bash
# Generate new token
TOKEN=$(./jwt_token_generator.sh)

# Or increase TTL to 24 hours
TOKEN=$(./jwt_token_generator.sh test_user trader "api.access" 86400)
```

### Security Notes

- **Development Only**: The default JWT secret is for testing only
- **Production**: Always use a strong, randomly-generated secret
- **Storage**: Never commit tokens or secrets to version control
- **Expiration**: Use short-lived tokens (15-60 minutes) in production
- **Revocation**: Tokens include `jti` claim for server-side revocation

### Related Files

- **API Gateway Auth**: `services/api_gateway/src/auth/interceptor.rs`
- **JWT Service**: `services/api_gateway/src/auth/jwt/service.rs`
- **Test Utilities**: `services/api_gateway/tests/common/mod.rs`
- **E2E Tests**: `services/api_gateway/tests/e2e_tests.rs`

### References

- JWT Standard: [RFC 7519](https://tools.ietf.org/html/rfc7519)
- PyJWT Documentation: https://pyjwt.readthedocs.io/
- API Gateway RBAC: `services/api_gateway/src/auth/README.md`