soth-mitm 0.3.2

# soth-mitm

Public Rust crate for the SOTH intercepting proxy contract.

## What You Get

- Stable handler decisions: `Allow` / `Block { status, body }`
- Deterministic request/response/stream contracts:
  - `RawRequest`
  - `RawResponse`
  - `StreamChunk`
  - `ConnectionMeta`
- Proxy lifecycle APIs:
  - `MitmProxyBuilder`
  - `MitmProxy`
  - `MitmProxyHandle` (`reload`, `current_config`, `metrics`, `shutdown`)
- TLS CA helpers:
  - `generate_ca`, `load_ca`, `load_ca_from_files`
  - trust install/uninstall/check helpers
- Runtime metrics snapshot API (`ProxyMetrics`)

## Scope Boundary

`soth-mitm` is transport/proxy core. Product-specific bundle logic or provider semantics are intentionally outside this crate.

## Minimal Integration Example

```rust
use bytes::Bytes;
use soth_mitm::{HandlerDecision, InterceptHandler, MitmConfig, MitmProxyBuilder, RawRequest};

struct ForwardOnly;

impl InterceptHandler for ForwardOnly {
    async fn on_request(&self, request: &RawRequest) -> HandlerDecision {
        if request.path.contains("/blocked") {
            return HandlerDecision::Block {
                status: 403,
                body: Bytes::from_static(b"blocked"),
            };
        }
        HandlerDecision::Allow
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut config = MitmConfig::default();
    config
        .interception
        .destinations
        .push("api.example.com:443".to_string());

    let _proxy = MitmProxyBuilder::new(config, ForwardOnly).build()?;
    Ok(())
}
```

Compilable example:

- `crates/soth-mitm/examples/soth_proxy_integration.rs`

## Key Types

- Config:
  - `MitmConfig`, `InterceptionScope`, `ProcessAttributionConfig`, `TlsConfig`
  - `UpstreamConfig`, `ConnectionPoolConfig`, `BodyConfig`, `HandlerConfig`
- Runtime metadata:
  - `ConnectionMeta`, `SocketFamily`, `ProcessInfo`, `TlsInfo`, `TlsVersion`
- Runtime streams:
  - `FrameKind::{SseData, NdjsonLine, GrpcMessage, WebSocketText, WebSocketBinary, WebSocketClose}`

> **Note:** All public config structs are marked `#[non_exhaustive]` — construct them
> via `Default::default()` and field assignment rather than struct literal syntax to
> remain forward-compatible.

## Feature Flags

| Flag | Default | Description |
|------|---------|-------------|
| `openssl-backend` | off | Enables OpenSSL-based CA material cross-validation when loading certificates from disk. On non-Windows platforms the OpenSSL crate is always present for downstream TLS fingerprinting, but this feature activates the CA validation code path. |
| `__internal` | off | Exposes internal sub-crate modules (`test_engine`, `test_policy`, etc.) for integration tests and benchmarks. **Not part of the stable API.** |

## Minimum Supported Rust Version

This crate requires **Rust 1.88** or later (`rust-version = "1.88"` in Cargo.toml).

## License

Licensed under the [Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/).
See [LICENSE](LICENSE) for the full text.

## Repository

- Main repo README: <https://github.com/soth-ai/soth-mitm/blob/main/README.md>
- Changelog: <https://github.com/soth-ai/soth-mitm/blob/main/crates/soth-mitm/CHANGELOG.md>
- Integration migration guide: <https://github.com/soth-ai/soth-mitm/blob/main/docs/migration/soth-proxy-integration.md>