diegosouzapw 1cb833acc4 docs(mitm): clarify CONNECT handler scope + guard activeConnections double-count (R4 #5) ...

The round-3 C1 fix added `server.on("connect", ...)` to satisfy plan 11 §4.6's
text. R4 architectural review confirmed the handler is essentially dead code
on port 443: `https.Server` runs the HTTP parser ABOVE TLS, so a
`server.on("connect")` handler only fires for CONNECT-tunneled-inside-TLS
(HTTPS-proxy-tunneled-in-TLS), not for the "no config required" AgentBridge
DNS-spoof flow where the IDE opens TLS directly to 127.0.0.1:443. Passthrough
for unmapped hosts is structurally handled elsewhere (DNS scoping for default
mode; httpProxyServer.ts:8080 for System-wide proxy mode). Genuine on-wire
bypass-without-decrypt at :443 under direct TLS would require SNI sniffing on
the raw 'connection' event — intentionally out of scope for this release.

This commit:
 - adds a block comment above the CONNECT handler explaining the real scope
   so future contributors don't assume it covers the primary AgentBridge flow
 - guards the `connection` listener with `socket.__mitmCounted` so the
   CONNECT "target" branch's `server.emit("connection", clientSocket)`
   re-entry doesn't double-increment `stats.activeConnections`
 - adds 2 source-grep regression tests asserting both the doc comment and
   the guard remain in place

C2 (x-omniroute-source/agent headers) was already correct and is unchanged.

2026-05-28 21:06:47 -03:00

11 KiB

Raw Blame History

View Raw