Product OS : Proxy

Product OS : Proxy builds on the work of hudsucker, taking it to the next level with a man-in-the-middle proxy server that can tunnel traffic through a VPN utilising Product OS : VPN.

What is Product OS?

Product OS is a collection of packages that provide different tools and features that can work together to build products more easily for the Rust ecosystem.

Feature Flags

Product OS : Proxy uses feature flags to minimize dependencies and binary size:

• default: Enables decoder, rcgen_ca, rustls_client, and http2 (recommended for most use cases)
• decoder: HTTP content encoding/decoding support (gzip, brotli, deflate, zstd)
• http2: HTTP/2 protocol support
• rcgen_ca: Certificate authority using rcgen (recommended, pure Rust)
• rustls_client: TLS client using rustls (recommended, pure Rust)
• tor: Route traffic through Tor network
• vpn: Route traffic through VPN connections
• vendored_openssl: Use vendored OpenSSL build (for static linking)

Using Features

Enable specific features in your Cargo.toml:

[dependencies]
product-os-proxy = { version = "0.0.19", features = ["decoder", "http2", "tor"] }

Installation

[dependencies]
product-os-proxy = "0.0.19"

Pin the version to match the crate Cargo.toml when using path or git dependencies.

Documentation

Full API documentation is available at docs.rs/product-os-proxy.

Usage

Overview

Product OS : Proxy is a high-performance, feature-rich MITM (man-in-the-middle) proxy server built on the Rust async ecosystem. It builds upon the work of hudsucker, taking it to the next level with powerful traffic interception, modification, and tunneling capabilities through VPN or Tor networks.

Features

• 🔒 MITM Proxying: Intercept and modify HTTP/HTTPS traffic with custom middleware
• 🔌 WebSocket Support: Handle WebSocket connections with custom message processing
• 📜 TLS Certificate Authority: Automatic certificate generation for HTTPS interception
• 📦 Content Decoding: Support for gzip, brotli, deflate, and zstd compression (with decoder feature)
• 🌐 VPN Tunneling: Route proxy traffic through VPN connections (with vpn feature)
• 🧅 Tor Network: Route traffic through the Tor network (with tor feature)
• ⚡ HTTP/2 Support: Full HTTP/2 protocol support (with http2 feature)
• 🔧 Custom Middleware: Implement custom request/response handlers
• 🚀 High Performance: Built on Tokio async runtime with minimal overhead
• 🛡️ Type Safety: Leverages Rust's type system for safe concurrent operations

Quick Start

Basic Proxy

use product_os_proxy::{
    NetworkProxy, NetworkProxyCertificateAuthority, NetworkProxyCertificateAuthorityManaged,
    NetworkProxyCompression, NetworkProxyNetwork, NetworkProxyTunnel, Proxy, TunnelType,
};

#[tokio::main]
async fn main() -> Result<(), product_os_utilities::ProductOSError> {
    // Configure the proxy (use ..Default::default() for other fields)
    let config = NetworkProxy {
        enable: true,
        network: NetworkProxyNetwork {
            secure: true,
            host: "127.0.0.1".to_string(),
            port: 8080,
            listen_all_interfaces: false,
            allow_insecure: false,
            insecure_port: 0,
        },
        certificate_authority: Some(NetworkProxyCertificateAuthority {
            managed: Some(NetworkProxyCertificateAuthorityManaged {
                enabled: true,
                serve_cert_endpoint: true,
                ..Default::default()
            }),
            ..Default::default()
        }),
        compression: NetworkProxyCompression::None,
        custom_requester: false,
        enable_tunnel: false,
        tunnel_settings: NetworkProxyTunnel {
            tunnel_type: TunnelType::Vpn,
            ..Default::default()
        },
        ..Default::default()
    };

    // Create and start the proxy
    let mut proxy = Proxy::new(config);
    proxy.run().await?;

    // Proxy is now running in the background after startup has succeeded
    Ok(())
}

Custom Middleware

Implement custom middleware to inspect and modify traffic:

use product_os_proxy::{Proxy, ProxyMiddleware};
use product_os_server::{ProductOSMiddlewareAsync, BeforeResult, RequestData};
use product_os_http::{Request, Response};
use product_os_http_body::BodyBytes as Body;
use async_trait::async_trait;
use std::sync::Arc;

#[derive(Clone)]
struct LoggingMiddleware;

#[async_trait]
impl ProductOSMiddlewareAsync for LoggingMiddleware {
    async fn before(&self, request: Request<Body>) -> BeforeResult {
        println!("Request: {} {}", request.method(), request.uri());
        BeforeResult::Result(request)
    }

    async fn after(&self, response: Response<Body>, _request_data: RequestData) -> Response<Body> {
        println!("Response: {}", response.status());
        response
    }

    // ... implement other required methods (success, failure, error, etc.)
}

// Use the middleware
let middleware = ProxyMiddleware::new(Arc::new(LoggingMiddleware));
proxy.set_middleware(Some(middleware));

Certificate Authority Setup

Managed CA (recommended)

"certificateAuthority": {
  "managed": {
    "enabled": true,
    "storagePath": "~/.product-os/proxy",
    "serveCertEndpoint": true
  },
  "trust": {
    "verifyOnStartup": true,
    "onMissingTrust": "guide",
    "allowAutoInstall": true,
    "activeHttpsProbe": true,
    "targets": ["system", "firefox", "chromium-profile"]
  }
}

Default storage: ~/.product-os/proxy/ (or $PRODUCT_OS_HOME/proxy/).

Generate and install trust via CLI:

cargo run --features cli --bin pos-proxy -- cert generate
cargo run --features cli --bin pos-proxy -- cert guide
cargo run --features cli --bin pos-proxy -- cert install --trust
cargo run --features cli --bin pos-proxy -- cert install --target firefox --trust
cargo run --features cli --bin pos-proxy -- cert install --target chromium-profile --trust
cargo run --features cli --bin pos-proxy -- cert install --target macos-user --trust   # macOS, no sudo
cargo run --features cli --bin pos-proxy -- cert status

Trust targets

Active HTTPS probe

When activeHttpsProbe is true, the proxy waits until its listen port accepts connections, then performs a CONNECT + TLS request to example.com:443 through itself using only the managed CA as trust anchor. This validates end-to-end MITM signing after store trust checks pass.

The probe runs after the proxy starts (not during preflight store checks). Use pos-proxy cert guide → “Run active HTTPS self-test” when the proxy is already running.

Interactive cert guide

pos-proxy cert guide launches a dialoguer menu (with --features cli):

1. Auto-install and trust
2. Manual steps
3. Export CA to Desktop
4. Re-check trust status
5. Run active HTTPS self-test through proxy
6. Skip

mkcert migration

Reuse an existing mkcert CA (already trusted via mkcert -install):

"certificateAuthority": {
  "files": {
    "certFile": "/path/to/mkcert/rootCA.pem",
    "keyFile": "/path/to/mkcert/rootCA-key.pem"
  }
}

Programmatic API

use product_os_proxy::Proxy;

let ca = Proxy::generate_certificate_authority(None); // in-memory CA
let managed = Proxy::load_or_create_managed_certificate_authority(None)?;

⚠️ Security Warning: Clients must be configured to trust the CA certificate, or certificate errors must be explicitly ignored. Never share your CA private key. Store it securely and use proper access controls.

Configuration boundary

NetworkProxy, NetworkProxyCertificateAuthority, and related MITM types are owned by product-os-proxy. Downstream crates (product-os-agents-browser, product-os-runner) depend on product-os-proxy for proxy configuration and CA material — they should not duplicate proxy config structs or path-resolution logic. Use load_certificate_authority and LoadedCa::to_managed_config() when you need a managed CA from loaded cert/key paths.

Architecture

The proxy operates as a MITM proxy with the following flow:

graph LR
    Client --> Proxy
    Proxy --> CA[Certificate Authority]
    CA --> TLS[TLS Handshake]
    TLS --> Middleware
    Middleware --> Tunnel[VPN/Tor Optional]
    Tunnel --> Server
    Server --> Tunnel
    Tunnel --> Middleware
    Middleware --> Client

1. Accept Connection: Client connects to proxy
2. HTTPS CONNECT: Intercept CONNECT requests for HTTPS traffic
3. Certificate Generation: Generate temporary certificates signed by CA
4. TLS Termination: Establish TLS connections with clients
5. Middleware Processing: Apply custom request/response transformations
6. Tunneling (optional): Route through VPN/Tor
7. Forward Request: Send request to destination server
8. Response Processing: Apply middleware transformations
9. Return Response: Send response back to client

Examples

See the examples/ directory for complete working examples:

• basic_proxy.rs - Minimal proxy setup
• custom_middleware.rs - Custom request/response handling

Run examples with:

cargo run --example basic_proxy --features="default"
cargo run --example custom_middleware --features="default"

Performance

Product OS : Proxy is designed for high performance:

• Async I/O: Built on Tokio for efficient async operations
• Zero-copy: Minimal data copying with Bytes and streaming
• Connection Pooling: Reuses connections to backend servers
• Certificate Caching: Caches generated certificates to reduce overhead
• Parallel Processing: Handles multiple connections concurrently

Security Considerations

When using MITM proxying, be aware of security implications:

1. Certificate Trust: Clients must trust your CA certificate
2. Private Key Security: Protect your CA private key
3. Traffic Inspection: Only inspect traffic you have authorization to intercept
4. Compliance: Ensure compliance with relevant regulations (GDPR, CCPA, etc.)
5. Logging: Be mindful of sensitive data in logs
6. Encryption: All traffic between client and proxy should be encrypted

Thread Safety

The Proxy struct is not Send or Sync by design, as it manages mutable state. However:

• Use it within a single async task
• The internal proxy implementation is thread-safe
• Handles multiple concurrent connections safely
• Middleware should implement Clone + Send + Sync

Minimum Supported Rust Version

This crate requires Rust 1.75 or later.

Contributing

Contributions are not currently available but will be available on a public repository soon.

License

This project is licensed under the GNU GPLv3.