docs(plans): add SNI-deferred MITM cert fix plan

Author: nnemirovsky

docs/plans/20260408-sni-defer-mitm-cert.md

@@ -0,0 +1,78 @@
+# Fix MITM cert generation for SNI-deferred connections
+
+## Overview
+
+When a SOCKS5 CONNECT arrives with a raw IP (no hostname) and the connection is SNI-deferred, the MITM proxy generates a TLS certificate for the raw IP address. This cert lacks IP SANs, causing `x509: cannot validate certificate for <IP> because it doesn't contain any IP SANs` errors on the upstream connection.
+
+The `sniAwareTLSConfig` callback in goproxy already handles this for normal connections by reading SNI from the TLS ClientHello and regenerating the cert with the hostname. But for SNI-deferred connections, the custom connect handler peeks the ClientHello bytes before they reach goproxy, and the MITM layer may not see the SNI.
+
+Observed in production: OpenClaw's Telegram client falls back to direct IP connections (`149.154.167.220`) when DNS-resolved IPs are unreachable. These IP-only connections get SNI-deferred, pass through the MITM, but the upstream TLS handshake fails because the MITM cert is for the IP.
+
+## Context
+
+- SNI deferral: `internal/proxy/server.go` (handleConnect, sniPolicyCheck)
+- SNI extraction: `internal/proxy/sni.go` (extractSNI, peekSNI)
+- MITM cert generation: `internal/proxy/inject.go` (sniAwareTLSConfig, GetConfigForClient)
+- DNS reverse cache: `internal/proxy/dns_reverse.go`
+
+## Development Approach
+
+- **Testing approach**: Regular (code first, then tests)
+- CRITICAL: every task MUST include new/updated tests
+- CRITICAL: all tests must pass before starting next task
+
+## Testing Strategy
+
+- Unit tests: `internal/proxy/sni_test.go` for SNI extraction
+- Integration tests: `internal/proxy/server_test.go` for SNI-deferred MITM connections
+- Verify on knuth with OpenClaw's Telegram fallback IP behavior
+
+## Implementation Steps
+
+### Task 1: Investigate SNI flow through custom connect handler to MITM
+
+**Files:**
+- Read: `internal/proxy/server.go` (handleConnect, sniPolicyCheck)
+- Read: `internal/proxy/inject.go` (sniAwareTLSConfig)
+
+- [ ] Trace the data flow: when sniPolicyCheck peeks ClientHello bytes and returns `io.MultiReader(buf, reader)`, verify that goproxy's TLS layer still receives the ClientHello (including SNI)
+- [ ] Check if `sniAwareTLSConfig.GetConfigForClient` is called and receives the SNI hostname
+- [ ] Identify whether the peeked bytes are consumed before goproxy reads them
+- [ ] Document the exact failure point
+- [ ] Run tests
+
+### Task 2: Fix cert generation for SNI-deferred IP connections
+
+**Files:**
+- Modify: `internal/proxy/server.go`
+- Modify: `internal/proxy/inject.go`
+- Test: `internal/proxy/server_test.go`
+
+- [ ] After SNI extraction in sniPolicyCheck, pass the recovered hostname to the MITM layer
+- [ ] Option A: update the CONNECT target in the goproxy context so the MITM uses hostname instead of IP
+- [ ] Option B: store the SNI hostname in the connection context and use it in sniAwareTLSConfig
+- [ ] Option C: replace the IP in the dial target with the SNI hostname before routing to the injector
+- [ ] Ensure the DNS reverse cache is populated (already done in sniPolicyCheck)
+- [ ] Write test: SNI-deferred IP connection produces cert with hostname SAN
+- [ ] Write test: SNI-deferred IP connection successfully MITMs upstream TLS
+- [ ] Run tests
+
+### Task 3: Verify acceptance criteria
+
+- [ ] Deploy to knuth, restart stack
+- [ ] Verify OpenClaw's Telegram fallback IP connections work through MITM
+- [ ] Verify no `IP SANs` errors in sluice logs
+- [ ] Verify credential injection works for IP-only Telegram connections
+- [ ] Run full test suite: `go test ./... -v -timeout 30s`
+
+### Task 4: [Final] Update documentation
+
+- [ ] Update CLAUDE.md SNI deferral section to note the cert generation fix
+- [ ] Move this plan to `docs/plans/completed/`
+
+## Post-Completion
+
+**Manual verification:**
+- Force OpenClaw to use IP-only Telegram connection (block DNS, let fallback kick in)
+- Verify MITM cert has correct hostname SAN
+- Check sluice logs for clean SNI -> ALLOW flow without cert errors