foxhunt/services/trading_service/tests/common/README.md

JWT Authentication Helpers for E2E Tests

This module provides reusable JWT authentication utilities for integration and end-to-end tests across the Foxhunt trading system.

Overview

The auth_helpers module centralizes JWT token generation and authenticated client creation to ensure consistency across test suites. It provides:

• ✅ Valid JWT token generation matching API Gateway validation
• ✅ Authentication interceptor for gRPC clients
• ✅ Support for both MFA-enabled and MFA-disabled scenarios
• ✅ Configurable user roles and permissions
• ✅ Environment-based JWT secret management

Quick Start

Basic Usage

use common::auth_helpers::{create_default_test_jwt, create_auth_interceptor, TestAuthConfig};
use tonic::transport::Channel;

#[tokio::test]
async fn test_authenticated_request() -> Result<()> {
    // 1. Create JWT token
    let token = create_default_test_jwt()?;
    
    // 2. Create interceptor with authentication
    let interceptor = create_auth_interceptor(TestAuthConfig::trader())?;
    
    // 3. Connect to API Gateway
    let channel = Channel::from_static("http://localhost:50051")
        .connect()
        .await?;
    
    // 4. Create authenticated client
    let mut client = TradingServiceClient::with_interceptor(channel, interceptor);
    
    // 5. Make authenticated request
    let response = client.get_account_info(Request::new(GetAccountInfoRequest {})).await?;
    
    Ok(())
}

Core Functions

create_default_test_jwt() -> Result<String>

Generates a JWT token with default trader configuration.

Example:

let token = create_default_test_jwt()?;
// Use token in Authorization header: Bearer <token>

create_test_jwt(config: TestAuthConfig) -> Result<String>

Generates a JWT token with custom configuration.

Example:

let config = TestAuthConfig::admin()
    .with_user_id("admin_user_123")
    .with_expiry(Duration::minutes(30));
    
let token = create_test_jwt(config)?;

create_auth_interceptor(config: TestAuthConfig) -> Result<impl Fn(...) + Clone>

Creates an authentication interceptor that injects JWT token and user context into all requests.

Example:

let interceptor = create_auth_interceptor(TestAuthConfig::trader())?;
let channel = Channel::from_static("http://localhost:50051").connect().await?;
let mut client = TradingServiceClient::with_interceptor(channel, interceptor);

Configuration Options

TestAuthConfig Presets

Trader (Default)

let config = TestAuthConfig::trader();
// - user_id: "test_trader_001"
// - roles: ["trader"]
// - permissions: ["api.access", "trading.submit", "trading.view", "trading.cancel"]
// - MFA: disabled

Admin

let config = TestAuthConfig::admin();
// - user_id: "test_admin_001"
// - roles: ["admin"]
// - permissions: ["api.access", "trading.*", "admin.*"]
// - MFA: enabled and verified

Viewer (Read-only)

let config = TestAuthConfig::viewer();
// - user_id: "test_viewer_001"
// - roles: ["viewer"]
// - permissions: ["api.access", "trading.view"]
// - MFA: disabled

Builder Pattern

Customize any configuration:

let config = TestAuthConfig::trader()
    .with_user_id("custom_user_123")
    .with_roles(vec!["custom_role".to_string()])
    .with_permissions(vec!["custom.permission".to_string()])
    .with_expiry(Duration::minutes(30))
    .with_mfa_enabled();

Advanced Usage

Testing MFA Scenarios

MFA Enabled and Verified

let config = TestAuthConfig::trader().with_mfa_enabled();
let token = create_test_jwt(config)?;
// Token indicates MFA is verified

MFA Enabled but Not Verified (for testing MFA flows)

let config = TestAuthConfig::trader().with_mfa_unverified();
let token = create_test_jwt(config)?;
// Token indicates MFA needs verification

Testing Token Validation

Expired Token

let expired_token = create_expired_test_jwt()?;
// This token will fail API Gateway validation due to expiry

Invalid Issuer

let invalid_token = create_invalid_issuer_jwt()?;
// This token will fail API Gateway validation due to wrong issuer

Multiple Authenticated Clients

#[tokio::test]
async fn test_multiple_users() -> Result<()> {
    // Create trader client
    let trader_interceptor = create_auth_interceptor(TestAuthConfig::trader())?;
    let channel1 = Channel::from_static("http://localhost:50051").connect().await?;
    let mut trader_client = TradingServiceClient::with_interceptor(channel1, trader_interceptor);
    
    // Create admin client
    let admin_interceptor = create_auth_interceptor(TestAuthConfig::admin())?;
    let channel2 = Channel::from_static("http://localhost:50051").connect().await?;
    let mut admin_client = TradingServiceClient::with_interceptor(channel2, admin_interceptor);
    
    // Use both clients in test
    trader_client.submit_order(...).await?;
    admin_client.cancel_all_orders(...).await?;
    
    Ok(())
}

Environment Variables

The auth helpers respect the following environment variables:

JWT_SECRET

Override the default test JWT secret. Useful for CI/CD environments.

Default: m5G2uUIX1DzSYYny8hXkF93udN5s3Tq5oFWSrGtCqyTaUeYwslf/9sh6UxF5KM5AF0PwlbRWmXHAvbCF73V+Dw==

export JWT_SECRET="your-custom-secret-for-testing"
cargo test

API_GATEWAY_ADDR

Override the default API Gateway address.

Default: http://localhost:50051

export API_GATEWAY_ADDR="http://api-gateway:50051"
cargo test

Helper Functions

get_test_user_id() -> String

Returns the default test user ID: "test_trader_001"

get_test_jwt_secret() -> String

Returns the JWT secret from environment or default test secret.

get_api_gateway_addr() -> String

Returns the API Gateway address from environment or default.

JWT Token Structure

Generated tokens match API Gateway validation requirements:

{
    "jti": "unique-jwt-id",           // Required for revocation tracking
    "sub": "test_trader_001",         // User ID
    "iat": 1234567890,                // Issued at (Unix timestamp)
    "exp": 1234571490,                // Expiry (Unix timestamp)
    "iss": "foxhunt-trading",         // Issuer (must match API Gateway)
    "aud": "trading-api",             // Audience (must match API Gateway)
    "roles": ["trader"],              // User roles
    "permissions": [                  // User permissions
        "api.access",
        "trading.submit",
        "trading.view"
    ],
    "token_type": "access",           // Token type
    "session_id": "session-uuid"      // Session ID
}

Integration with Existing Tests

Example: Trading Service E2E Test

mod common;

use common::auth_helpers::{create_auth_interceptor, TestAuthConfig};
use tonic::transport::Channel;

#[tokio::test]
async fn test_order_lifecycle() -> Result<()> {
    // Setup authenticated client
    let interceptor = create_auth_interceptor(TestAuthConfig::trader())?;
    let channel = Channel::from_static("http://localhost:50051")
        .connect()
        .await?;
    let mut client = TradingServiceClient::with_interceptor(channel, interceptor);
    
    // Submit order
    let order_request = SubmitOrderRequest {
        symbol: "AAPL".to_string(),
        side: OrderSide::Buy as i32,
        order_type: OrderType::Limit as i32,
        quantity: 100,
        price: Some(150.0),
    };
    
    let response = client.submit_order(Request::new(order_request)).await?;
    let order_id = response.into_inner().order_id;
    
    // Check order status
    let status_request = GetOrderStatusRequest { order_id };
    let status = client.get_order_status(Request::new(status_request)).await?;
    
    assert_eq!(status.into_inner().status, OrderStatus::Pending as i32);
    
    Ok(())
}

Example: Testing Authorization Failures

#[tokio::test]
async fn test_insufficient_permissions() -> Result<()> {
    // Create viewer client (read-only permissions)
    let interceptor = create_auth_interceptor(TestAuthConfig::viewer())?;
    let channel = Channel::from_static("http://localhost:50051").connect().await?;
    let mut client = TradingServiceClient::with_interceptor(channel, interceptor);
    
    // Attempt to submit order (should fail)
    let order_request = SubmitOrderRequest { /* ... */ };
    let result = client.submit_order(Request::new(order_request)).await;
    
    // Verify authorization failure
    assert!(result.is_err());
    assert!(matches!(
        result.unwrap_err().code(),
        tonic::Code::PermissionDenied
    ));
    
    Ok(())
}

Testing Checklist

When writing E2E tests with authentication:

• Use create_auth_interceptor() for authenticated clients
• Choose appropriate TestAuthConfig preset (trader/admin/viewer)
• Customize config with builder pattern if needed
• Test both successful and failed authorization scenarios
• Consider MFA scenarios if relevant
• Use environment variables for CI/CD flexibility
• Verify JWT token structure matches API Gateway requirements

Troubleshooting

"Invalid JWT token" errors

Cause: Token doesn't match API Gateway validation requirements.

Solution: Ensure:

• Issuer is "foxhunt-trading"
• Audience is "trading-api"
• Token is not expired
• JWT secret matches API Gateway configuration

"Failed to connect to API Gateway" errors

Cause: API Gateway is not running or address is incorrect.

Solution:

# Check API Gateway is running
docker-compose ps api_gateway

# Verify address is correct
echo $API_GATEWAY_ADDR  # Should be http://localhost:50051

# Restart API Gateway if needed
docker-compose restart api_gateway

"Permission denied" errors

Cause: User lacks required permissions for the operation.

Solution: Use appropriate config:

// For admin operations
let config = TestAuthConfig::admin();

// For custom permissions
let config = TestAuthConfig::trader()
    .with_permissions(vec!["admin.cancel_all".to_string()]);

Best Practices

1. Reuse configurations: Use presets (trader/admin/viewer) when possible
2. Explicit permissions: When testing authorization, explicitly set permissions to verify access control
3. Test both success and failure: Test with correct and insufficient permissions
4. Environment isolation: Use environment variables for CI/CD to avoid hardcoded credentials
5. Token uniqueness: Each token has unique JTI for revocation tracking
6. MFA testing: Test both MFA-enabled and MFA-disabled flows where applicable

See Also

• CLAUDE.md - System architecture and infrastructure
• API Gateway Authentication - JWT validation implementation
• MFA Module - Multi-factor authentication