# RustFS Trusted Proxies

The `rustfs-trusted-proxies` module provides secure and efficient management of trusted proxy servers within the RustFS
ecosystem. It is designed to handle multi-layer proxy architectures, ensuring accurate client IP identification while
maintaining a zero-trust security model.

## Modes

- **Simple default**: only trusts forwarding headers when the direct peer IP is
  internal.
- **Legacy full mode**: keeps the original proxy-chain validation, available
  via `legacy_*` helpers.

## Features

- **Multi-Layer Proxy Validation**: Supports `Strict`, `Lenient`, and `HopByHop` validation modes to accurately identify
  the real client IP address.
- **Zero-Trust Security**: Verifies every hop in the proxy chain against a configurable list of trusted networks.
- **Cloud Integration**: Automatic discovery of trusted IP ranges for major cloud providers including AWS, Azure, and
  GCP.
- **High Performance**: Utilizes the `moka` cache for fast lookup of validation results and `axum` for a
  high-performance web interface.
- **Observability**: Built-in support for Prometheus metrics and structured JSON logging via `tracing`.
- **RFC 7239 Support**: Full support for the modern `Forwarded` header alongside legacy `X-Forwarded-For` headers.

## Configuration

The module is configured primarily through environment variables:

| Variable                                      | Default             | Description                                             |
|-----------------------------------------------|---------------------|---------------------------------------------------------|
| `RUSTFS_TRUSTED_PROXY_ENABLED`                | `true`              | Enable the trusted proxy middleware                     |
| `RUSTFS_TRUSTED_PROXY_IMPLEMENTATION`         | `simple`            | Select `simple` or `legacy` implementation              |
| `RUSTFS_TRUSTED_PROXY_VALIDATION_MODE`        | `hop_by_hop`        | Validation strategy (`strict`, `lenient`, `hop_by_hop`) |
| `RUSTFS_TRUSTED_PROXY_NETWORKS`               | `127.0.0.1,::1`     | Comma-separated list of trusted CIDR ranges (loopback-only by default) |
| `RUSTFS_TRUSTED_PROXY_MAX_HOPS`               | `10`                | Maximum allowed proxy hops                              |
| `RUSTFS_TRUSTED_PROXY_CACHE_CAPACITY`         | `10000`             | Max entries in the validation cache                     |
| `RUSTFS_TRUSTED_PROXY_METRICS_ENABLED`        | `true`              | Enable Prometheus metrics collection                    |
| `RUSTFS_TRUSTED_PROXY_CLOUD_METADATA_ENABLED` | `false`             | Enable auto-discovery of cloud IP ranges                |

## Usage

### Initialization

Initialize the global trusted proxy system at the start of your application (e.g., in `main.rs`):

```rust
// Initialize trusted proxies system
rustfs_trusted_proxies::init();
```

### As a Middleware

Integrate the trusted proxy validation into your Axum application or HTTP service stack:

```rust
use rustfs_trusted_proxies;

let app = Router::new()
    .route("/", get(handler))
    // Add the trusted proxy layer if enabled
    .option_layer(if rustfs_trusted_proxies::is_enabled() {
        Some(rustfs_trusted_proxies::layer().clone())
    } else {
        None
    });
```

### Simple default mode

The default mode only trusts forwarding headers from internal IPs.

```bash
RUSTFS_TRUSTED_PROXY_IMPLEMENTATION=simple
```

### Legacy mode

The original implementation is still available:

```rust
rustfs_trusted_proxies::legacy_init();
let layer = rustfs_trusted_proxies::LegacyTrustedProxyLayer::enabled(config, None);
```

Or switch the global default path:

```bash
RUSTFS_TRUSTED_PROXY_IMPLEMENTATION=legacy
```

### Accessing Client Info

Retrieve the verified client information in your handlers or other middleware:

```rust
use rustfs_trusted_proxies::ClientInfo;

async fn handler(req: Request) -> impl IntoResponse {
    if let Some(client_info) = req.extensions().get::<ClientInfo>() {
        println!("Real Client IP: {}", client_info.real_ip);
        println!("Is Trusted: {}", client_info.is_from_trusted_proxy);
    }
}
```

## Development

### Pre-Commit Checklist

Before committing, ensure all checks pass:

```bash
make pre-commit
```

### Testing

Run the test suite:

```bash
cargo test --workspace --exclude e2e_test
```

## License

Licensed under the Apache License, Version 2.0.