foxhunt/AGENT_H1_QUICK_REFERENCE.md

# Agent H1: TLS Configuration - Quick Reference

**Status**: ✅ **CONFIGURATION COMPLETE** (Code initialization pending)

---

## 🚀 Quick Start

### Enable TLS in Development

**Edit `.env`**:
```bash
TLS_ENABLED=true  # Change from false to true
```

**Restart Services**:
```bash
docker-compose down
docker-compose up -d
```

⚠️ **WARNING**: Services will start but **TLS is NOT enforced** (code changes required in Wave H2-H3).

---

## 📁 Files Changed

1. **docker-compose.yml** - Added TLS configuration to 5 services:
   - Trading Service (port 50052)
   - Backtesting Service (port 50053)
   - ML Training Service (port 50054)
   - Trading Agent Service (port 50055)
   - API Gateway (port 50051)

2. **.env** - Added TLS environment variables

---

## 🔑 TLS Environment Variables

### Server-Side TLS (All Services)
```bash
TLS_ENABLED=false                     # Set to true to enable TLS
TLS_PROTOCOL_VERSION=TLS13            # Force TLS 1.3
TLS_REQUIRE_CLIENT_CERT=true          # Enforce mTLS
TLS_CERT_PATH=./certs/server-cert.pem
TLS_KEY_PATH=./certs/server-key.pem
TLS_CA_PATH=./certs/ca/ca-cert.pem
```

### Client-Side TLS (API Gateway)
```bash
TLS_CLIENT_CERT_PATH=./certs/client-cert.pem
TLS_CLIENT_KEY_PATH=./certs/client-key.pem

# For Backtesting Service connections
BACKTESTING_TLS_CA_CERT=/tmp/foxhunt/certs/ca/ca-cert.pem
BACKTESTING_TLS_CLIENT_CERT=/tmp/foxhunt/certs/client-cert.pem
BACKTESTING_TLS_CLIENT_KEY=/tmp/foxhunt/certs/client-key.pem

# For ML Training Service connections
ML_TRAINING_TLS_CA_CERT=/tmp/foxhunt/certs/ca/ca-cert.pem
ML_TRAINING_TLS_CLIENT_CERT=/tmp/foxhunt/certs/client-cert.pem
ML_TRAINING_TLS_CLIENT_KEY=/tmp/foxhunt/certs/client-key.pem
```

### mTLS Validation
```bash
MTLS_ENABLE_REVOCATION_CHECK=false    # Enable in production
MTLS_CRL_URL=                         # Certificate Revocation List URL
```

---

## 📊 Service Implementation Status

| Service | TLS Config | Code Init | Status |
|---------|-----------|-----------|--------|
| API Gateway | ✅ | ❌ | Config ready, code pending (Wave H2) |
| Trading Service | ✅ | ❌ | Config ready, no TLS infrastructure |
| Backtesting Service | ✅ | ❌ | Config + infra ready, not initialized |
| ML Training Service | ✅ | ❌ | Config + infra ready, not initialized |
| Trading Agent Service | ✅ | ❌ | Config ready, no TLS infrastructure |

**Overall Progress**: 20% (Configuration complete, 80% code implementation pending)

---

## 🔒 Certificate Files

**Location**: `/home/jgrusewski/Work/foxhunt/certs/`

```
certs/
├── ca/
│   ├── ca-cert.pem          ✅ CA certificate
│   ├── ca-key.pem           ✅ CA private key
│   └── ca-cert.srl          ✅ CA serial number
├── server-cert.pem          ✅ Server certificate
├── server-key.pem           ✅ Server private key
├── client-cert.pem          ✅ Client certificate
└── client-key.pem           ✅ Client private key
```

**Status**: ✅ All certificates present and valid (dev certificates)

---

## ⚠️ Known Limitations

### TLS NOT Enforced (Services Ignore TLS_ENABLED)

**Reason**: Services don't initialize TLS configuration in their `main.rs` files.

**Services Affected**:
1. ❌ API Gateway - No server-side TLS initialization
2. ❌ Trading Service - No TLS infrastructure
3. ❌ Backtesting Service - TLS config exists, not used
4. ❌ ML Training Service - TLS config exists, not used
5. ❌ Trading Agent Service - No TLS infrastructure

**Current Behavior**: Even with `TLS_ENABLED=true`, services start without TLS validation.

**Security Impact**: 🟡 **MEDIUM** (plaintext gRPC traffic until code fixes applied)

---

## 🎯 Next Steps

### Wave H2: API Gateway TLS (2 hours)
**File**: `services/api_gateway/src/main.rs`

**Add**:
```rust
use api_gateway::auth::mtls::tls_config::ApiGatewayTlsConfig;

let tls_config = if std::env::var("TLS_ENABLED")
    .unwrap_or_else(|_| "false".to_string())
    .parse::<bool>()
    .unwrap_or(false)
{
    Some(ApiGatewayTlsConfig::from_files(
        &std::env::var("TLS_CERT_PATH")?,
        &std::env::var("TLS_KEY_PATH")?,
        &std::env::var("TLS_CA_PATH")?,
        true,  // require_client_cert
        false, // enable_revocation_check
        None,  // crl_url
    ).await?)
} else {
    None
};

let server_builder = if let Some(tls) = tls_config {
    tonic::transport::Server::builder()
        .tls_config(tls.to_server_tls_config())?
} else {
    tonic::transport::Server::builder()
};
```

### Wave H3: Backend Services TLS (4 hours)
**Files**:
- `services/backtesting_service/src/main.rs`
- `services/ml_training_service/src/main.rs`
- `services/trading_service/src/main.rs` (add `tls_config.rs` first)
- `services/trading_agent_service/src/main.rs` (add `tls_config.rs` first)

**Pattern**: Same as Wave H2 (load TLS config, apply to server builder)

### Wave H4: TLS Testing (2 hours)
**Tests**:
1. ✅ Services start with TLS_ENABLED=true
2. ✅ gRPC connections fail without client certificates
3. ✅ gRPC connections succeed with valid certificates
4. ✅ TLS 1.2 connections rejected
5. ✅ Invalid certificates rejected

---

## 🛠️ Troubleshooting

### Issue: Services fail to start with TLS_ENABLED=true
**Cause**: Code doesn't initialize TLS configuration
**Fix**: Wait for Wave H2-H3 implementation

### Issue: Certificate not found errors
**Check**:
```bash
ls -la /home/jgrusewski/Work/foxhunt/certs/
ls -la /home/jgrusewski/Work/foxhunt/certs/ca/
```
**Fix**: Regenerate certificates if missing

### Issue: docker-compose validation fails
**Check**:
```bash
docker-compose config --quiet
```
**Fix**: Ensure YAML syntax is valid

---

## 📈 Performance Impact

**TLS Overhead (Expected)**:
- Handshake: ~1-5ms (one-time per connection)
- Per-request: <100μs (acceptable for HFT)
- Total: <1% performance degradation

**Mitigation**:
- HTTP/2 connection reuse
- TLS session resumption
- Hardware acceleration (AES-NI)

---

## 🔐 Production Checklist

Before enabling TLS in production:

1. ⚠️ **Complete Wave H2-H3**: Implement TLS initialization
2. ⚠️ **Replace Dev Certificates**: Use CA-signed certificates
3. ⚠️ **Enable Revocation Check**: `MTLS_ENABLE_REVOCATION_CHECK=true`
4. ⚠️ **Configure CRL URL**: Set valid `MTLS_CRL_URL`
5. ⚠️ **Test Certificate Rotation**: Zero-downtime renewal
6. ⚠️ **Set Expiration Alerts**: Monitor 30 days before expiry
7. ⚠️ **Enable Audit Logging**: Track all TLS connections
8. ⚠️ **Performance Test**: Verify <100μs TLS overhead
9. ⚠️ **Test Failure Modes**: Invalid/expired/revoked certs
10. ⚠️ **Document Runbook**: TLS troubleshooting procedures

---

## 📞 Quick Commands

### Check TLS Configuration
```bash
grep "TLS_ENABLED" .env
grep "TLS_ENABLED" docker-compose.yml
```

### Validate Certificates
```bash
openssl x509 -in certs/server-cert.pem -text -noout
openssl x509 -in certs/ca/ca-cert.pem -text -noout
openssl verify -CAfile certs/ca/ca-cert.pem certs/server-cert.pem
```

### Test TLS Connection (After Wave H2-H3)
```bash
grpcurl -insecure localhost:50051 list  # Should fail if TLS enforced
grpcurl -cert certs/client-cert.pem -key certs/client-key.pem \
  -cacert certs/ca/ca-cert.pem localhost:50051 list  # Should succeed
```

---

**Last Updated**: 2025-10-18
**Next Wave**: H2 (API Gateway TLS Initialization)