TLS Intercept for CONNECT-based L7 Filtering and Credential Injection

[lukehinds]

Problem

The proxy has three modes with fundamentally different visibility:

Mode	TLS	L7 Visibility	Credential Injection	SDK Cooperation Required
Reverse proxy (/openai/...)	Proxy terminates TLS to upstream	Full	Yes	Yes (*_BASE_URL env vars)
CONNECT tunnel	End-to-end (proxy is blind)	None	No	No
External proxy passthrough	End-to-end (chained through enterprise proxy)	None	No	No

The reverse proxy gives full L7 control but requires SDK cooperation via base URL env vars. Both CONNECT modes (direct tunnel and external proxy passthrough) work universally but are opaque byte streams. SDKs and tools that don't honour *_BASE_URL go through CONNECT, bypassing credential injection and endpoint filtering entirely. The external proxy path additionally delegates allow/deny decisions to the enterprise proxy, but nono has no visibility into the traffic itself.

Solution

Selectively terminate TLS on CONNECT requests using an ephemeral, per-session CA. Only intercept connections to hosts that match a configured route with endpoint_rules or credential_key. All other CONNECT traffic remains a transparent tunnel.

Agent --> TLS(ephemeral CA) --> nono-proxy --> TLS(real cert) --> upstream
                                   |
                        L7 inspection + credential injection

Design Constraints

1. Selective interception only -- Only CONNECT requests to hosts matching a route with endpoint_rules or credential_key get TLS-terminated. Everything else stays as a transparent tunnel (current behaviour unchanged).

2. Hard fail on cert pinning -- If TLS interception fails (pinned cert, custom TLS config in the agent), the proxy returns a 502 with a clear diagnostic. It does NOT fall back to a transparent tunnel, because the route requires credential injection or filtering to function correctly.

3. Shared L7 processing with reverse proxy -- The intercepted CONNECT path reuses the same request-forwarding logic as the reverse proxy (credential injection, endpoint rules, audit logging, upstream TLS). See L7 Processing below.

Ephemeral CA Lifecycle

The CA exists only for the lifetime of a single proxy session. No long-lived key material.

Generation

• CA key pair (ECDSA P-256) generated at proxy startup using rcgen
• Self-signed CA certificate with:
  • CA:TRUE basic constraint
  • Short validity (24 hours -- covers the session, limits blast radius if cert file leaks)
  • Subject: CN=nono-session-ca
  • No CRL or OCSP (ephemeral, not worth the complexity)

Storage

Material	Location	Permissions
CA private key	Memory only (Zeroizing<Vec<u8>>)	Never written to disk
CA certificate	Tempfile in nono data dir	0o400 (owner-read only)

Cleanup

• ProxyHandle::shutdown() zeroizes the in-memory key and deletes the CA cert tempfile
• Drop impl as a safety net if shutdown isn't called explicitly
• Process exit / signal handler ensures cleanup on SIGTERM/SIGINT

Leaf Certificate Minting

On each intercepted CONNECT request, the proxy mints a leaf certificate for the requested hostname.

Certificate Properties

• Subject Alternative Name: the CONNECT target hostname
• Signed by the ephemeral session CA
• Short validity (1 hour)
• ECDSA P-256 key (fast generation, small wire size)

Caching

• In-memory HashMap<String, CertifiedKey> keyed by hostname
• No LRU eviction needed -- typical agent workloads hit a handful of distinct hosts
• Cache is naturally bounded by session lifetime
• Cache is zeroized on shutdown alongside the CA key

Trust Injection

The ephemeral CA cert file path is injected into the child process environment before sandbox application:

Env Var	Runtime Coverage
SSL_CERT_FILE	OpenSSL-based (Python requests, httpx, Ruby, many CLI tools)
REQUESTS_CA_BUNDLE	Python requests specifically
NODE_EXTRA_CA_CERTS	Node.js
CURL_CA_BUNDLE	curl

These are additive (agent can still reach non-intercepted hosts with system roots). The env vars point to a PEM file containing both the ephemeral CA cert and the system roots, so non-intercepted TLS connections continue to work.

External Proxy Composition

When an external (enterprise) proxy is configured (--upstream-proxy), the TLS intercept path must compose with it. The decision tree becomes a three-way branch:

CONNECT request arrives
  |
  +-- host matches route with L7/credential requirements?
  |     YES --> TLS intercept (terminate locally, inspect, then...)
  |               +-- external proxy configured AND host NOT in bypass_hosts?
  |               |     YES --> upstream leg: CONNECT through enterprise proxy, then TLS
  |               |     NO  --> upstream leg: direct TLS to upstream
  |               +-- forward_request() with credential injection + endpoint rules
  |
  +-- NO  --> transparent tunnel (no interception)
                +-- external proxy configured AND host NOT in bypass_hosts?
                |     YES --> chain CONNECT through enterprise proxy (current external.rs)
                |     NO  --> direct TCP relay (current connect.rs)

Upstream Connection Strategy

forward_request() needs an UpstreamStrategy parameter that abstracts how the upstream TLS connection is established:

enum UpstreamStrategy {
    /// Connect directly to upstream (resolved IPs from DNS check)
    Direct { resolved_addrs: Vec<SocketAddr> },
    /// Chain through an enterprise proxy via CONNECT
    ExternalProxy { proxy_addr: String, target_host: String, target_port: u16 },
}

For the ExternalProxy variant, the upstream leg:

1. TCP-connects to the enterprise proxy address
2. Sends CONNECT host:port HTTP/1.1 (with optional proxy auth)
3. Waits for 200 Connection Established
4. Performs TLS handshake to the real upstream over the tunnel
5. Forwards the HTTP request with injected credentials

This reuses the CONNECT-to-enterprise-proxy logic already in external.rs (connecting, sending CONNECT, reading 200), but wraps the resulting tunnel in a TLS connection to the upstream rather than relaying raw bytes.

Bypass Hosts

The existing BypassMatcher in external.rs determines whether a host should skip the enterprise proxy. When bypass matches, the intercept path connects directly to the upstream even if an external proxy is configured. This is consistent with current transparent-tunnel behaviour where bypass hosts go direct.

Extracting Shared Enterprise Proxy Helpers

external.rs currently has inline logic for connecting to the enterprise proxy and reading the CONNECT response. This should be extracted into reusable helpers that both the transparent external proxy path and the intercept upstream path can call:

// In external.rs or a shared module:
async fn connect_via_proxy(
    proxy_addr: &str,
    target_host: &str,
    target_port: u16,
    proxy_auth: Option<&str>,
) -> Result<TcpStream> {
    // 1. TCP connect to proxy
    // 2. Send CONNECT host:port
    // 3. Read and validate 200 response
    // 4. Return the tunnel stream
}

The transparent external proxy path calls this then relays bytes. The intercept path calls this then wraps the stream in a TLS connection for the upstream handshake.

L7 Processing

Shared Request Forwarding

The core L7 logic is extracted into a shared function used by both the reverse proxy and the intercept path:

reverse.rs  -->  parse prefix, lookup route, strip prefix  -->  forward_request(req, route, cred)
intercept   -->  lookup route by host:port                 -->  forward_request(req, route, cred)

The shared forward_request function handles:

• Credential injection via CredentialStore (header, url_path, query_param, basic_auth)
• Endpoint rule checking via CompiledEndpointRules
• Upstream TLS connection (using per-route TlsConnector from RouteStore)
• Audit logging
• Response streaming (SSE, chunked transfer)

Differences Between Callers

Concern	Reverse Proxy	Intercept
Route lookup	URL prefix (/openai/...)	Upstream hostname (api.openai.com:443) via RouteStore::is_route_upstream()
Path handling	Strip service prefix	Pass through as-is
Upstream connection	Proxy builds TLS connection	Upstream already resolved from CONNECT phase
Request shape	Relative path, no Host manipulation	Relative path (HTTP/1.1 over TLS), Host header present

Architecture

New Modules

crates/nono-proxy/src/
+-- tls_intercept/
    +-- mod.rs            # Module root, handle() entry point
    +-- ca.rs             # Ephemeral CA generation, storage, zeroization
    +-- cert_cache.rs     # Per-hostname leaf cert minting + HashMap cache
    +-- acceptor.rs       # TLS acceptor using minted certs for client-side termination

Modified Modules

connect.rs       # Branch: intercept (route match) vs tunnel (no match)
server.rs        # Initialize TLS intercept CA at proxy startup, cleanup on shutdown
reverse.rs       # Extract shared forward_request() function
external.rs      # Extract connect_via_proxy() helper for reuse by intercept upstream path
config.rs        # No changes needed (route config already has endpoint_rules, credential_key)

CONNECT Handler Branching

// In connect.rs, after host filter check passes:
if route_store.has_intercept_route(&host, port) {
    // Route has endpoint_rules or credential_key --> intercept TLS
    tls_intercept::handle(stream, &host, port, route_store, cred_store, &ca, audit_log).await
} else {
    // No L7 requirements --> transparent tunnel (current behaviour)
    relay_bidirectional(stream, upstream).await
}

Route Matching for Intercept

RouteStore already has is_route_upstream() which maps host:port to routes. A new method determines if a route requires interception:

impl RouteStore {
    /// Returns true if the host:port matches a route that needs L7 visibility
    /// (has endpoint_rules or an associated credential).
    fn has_intercept_route(&self, host: &str, port: u16) -> bool {
        // match against upstream_host_port, check if route has
        // non-empty endpoint_rules or credential_store has entry
    }
}

Dependencies

Existing (already in nono-proxy/Cargo.toml)

• rustls, tokio-rustls, rustls-pemfile -- TLS termination and upstream connections
• zeroize -- Key material cleanup

New

• rcgen -- CA and leaf certificate generation (well-maintained, used by rustls test infra)

Implementation Phases

Phase 1: Ephemeral CA Infrastructure

tls_intercept/ca.rs and cert_cache.rs. CA generation, leaf cert minting, zeroization. Unit-testable in isolation without network.

Phase 2: CONNECT Intercept Path

Branch in connect.rs. TLS acceptor using minted certs. Wire up to accept client TLS and read the inner HTTP request.

Phase 3: Shared L7 Forwarding

Extract forward_request() from reverse.rs. Wire both reverse proxy and intercept callers to it.

Phase 4: Trust Injection

Generate the combined CA cert + system roots PEM file. Set env vars in child environment. Test across Node.js, Python, curl, Go.

Phase 5: Audit and Diagnostics

Audit log entries distinguishing Connect (tunnel), ConnectIntercept (terminated), and Reverse modes. Diagnostic banner showing which routes are intercepted.

Security Considerations

• CA key never touches disk. The private key lives in Zeroizing<Vec<u8>> in memory. Only the public certificate is written to a tempfile.
• Per-session ephemeral CA. No persistent trust anchor that could be reused across sessions or by other processes.
• Cert file permissions. The CA cert tempfile is created with 0o400. The sandboxed child needs read access, so the file is created before sandbox application.
• Interception scope is minimal. Only routes with explicit L7 requirements trigger interception. The default is transparent tunnelling.
• Hard fail on interception failure. If TLS termination fails (cert pinning, HPKP, custom trust), the connection is refused with 502, not silently degraded to an uninspected tunnel.
• Zeroization on all exit paths. Drop impl on the CA struct ensures key material is zeroized even on panic or unexpected shutdown.
• External proxy composition preserves deny list. Cloud metadata endpoints are blocked before the intercept/tunnel decision, so they are denied regardless of whether an external proxy is configured. The enterprise proxy's own filtering is additive, not a replacement.
• Bypass hosts respected. When a host is in the external proxy's bypass_hosts list, the intercept path connects directly to the upstream, consistent with transparent-tunnel behaviour. This prevents routing internal traffic through the enterprise proxy unnecessarily.

[lukehinds]

@JimBugwadia , how well will this play with a k8s deployment? I am averse to MITM, so kept this as ephemeral and sanitized as I could.

[JimBugwadia]

@JimBugwadia , how well will this play with a k8s deployment? I am averse to MITM, so kept this as ephemeral and sanitized as I could.

I don't see any obvious issues, it should help simplify the credentials management (vs using a different method for the proxy).