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

# 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:

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

# 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)

# 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

# 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

# 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

#!/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)

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:

# 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"

# Install PyJWT
pip3 install pyjwt

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

Error: "python3 not found"

# 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:

# 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:

# 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
• PyJWT Documentation: https://pyjwt.readthedocs.io/
• API Gateway RBAC: services/api_gateway/src/auth/README.md