fix(mitm): crash-safe system-state teardown + socket timeouts (ProxyBridge-inspired hardening)

[diegosouzapw]

Summary

Closes 4 high-impact correctness/security/resilience gaps in the MITM + Traffic-Inspector subsystem, surfaced by a comparative analysis against the ProxyBridge transparent-proxy reference design. ProxyBridge treats symmetric, crash-proof teardown of every system mutation as a first-class invariant (library destructor + crash signal handler + standalone --cleanup); OmniRoute did not. This ports that invariant to OmniRoute's application-layer model and hardens the proxy runtime.

• Gap 8 — stopMitm() DNS leak (fix). stopMitm() removed only the Antigravity default hosts, leaving every agent + custom-host /etc/hosts spoof line behind on a clean stop. Those accumulate and keep hijacking resolution machine-wide after MITM is "off". Added collectManagedHosts() (full agent registry + all custom hosts) and removal in stopMitm().
• Gap 7 — crash-safe cleanup (feat). No teardown ran on crash/SIGKILL. Added buildRepairPlan()/repairMitm() (idempotent: managed DNS + CA uninstall + best-effort system-proxy revert), POST /api/tools/agent-bridge/repair (the analogue of ProxyBridge's --cleanup), an orphanedStateDetected flag on getMitmStatus(), and best-effort parent SIGINT/SIGTERM handlers.
• Gap 9 — root CA never removed (security). uninstallCert() was fully implemented but had zero production call sites — the MITM root CA stayed trusted machine-wide forever. Wired it via a new DELETE /api/tools/agent-bridge/cert handler (idempotent, Zod-validated) and repairMitm(). Keep-installed policy documented inline.
• Gap 10 — no socket idle timeouts (resilience). Hung/half-open tunnels pinned sockets until OS TCP keepalive (hours), risking fd exhaustion. Added a shared socketTimeouts helper (60s default, mirroring ProxyBridge's relay poll) applied to requestTimeout/headersTimeout/keepAliveTimeout, per-connection idle reaping, and both sockets of every rawTcpForward tunnel — in both server.cjs and the Inspector HTTP-proxy listener.

Test Plan

• node --test — 274 MITM/inspector/agent-bridge/dns tests pass (zero regression), incl. new TDD tests:
  • mitm-manager-cleanup-symmetry.test.ts (Gap 8)
  • mitm-manager-repair.test.ts + agent-bridge-repair-route-validation.test.ts (Gap 7)
  • mitm-cert-removal-wiring.test.ts (Gap 9)
  • mitm-server-timeouts.test.ts (Gap 10)
• typecheck:core clean
• eslint clean on all touched files
• check-file-size.mjs OK (manager.ts 650 < 800 cap)
• node --check server.cjs OK; server.cjs contract tests (C1/C2/R4) still green
• CI full suite (runs on PR)

Notes

• Stub (manager.stub.ts) updated for Docker graceful degradation (repair = no-op, status flag).
• All routes covered by the existing /api/tools/agent-bridge/ LOCAL_ONLY prefix in routeGuard.ts (Hard Rules feat(npm): add npm package publishing with CLI entry point #15/fix(ci): explicit .npmrc auth for npm publish #17).
• Follow-ups (not in this PR): Remove-CA button + trust badge in the AgentBridge UI (needs an i18n key across 42 locales via the release autotranslate flow); Gap 13 (body-size cap) deferred — naive truncation would break multimodal LLM uploads, correct fix is streaming.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request introduces a DELETE endpoint for untrusting the MITM root CA, a POST endpoint for repairing orphaned MITM system state, and socket idle timeouts to prevent file descriptor leaks, along with corresponding unit tests. Feedback highlights a critical issue where the parent process could hang on SIGINT/SIGTERM signals, and warns that raw socket idle timeouts on connection events will prematurely terminate active connections (such as long-running LLM requests). Additionally, the reviewer noted that the newly defined Zod schemas should be moved to the shared schemas file to comply with the repository style guide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

In Node.js, registering a signal listener for SIGINT or SIGTERM suspends the default termination behavior of the process. Because onSignal terminates the child process and logs a warning but does not call process.exit() or re-raise the signal, the parent process will hang and refuse to exit when receiving these signals (unless another handler explicitly exits).

To fix this, you should re-send the signal to the parent process using process.kill(process.pid, signal) at the end of the handler. Since the listener was registered with once, it has already been removed, so re-sending the signal will trigger the default termination behavior and allow the process to exit cleanly with the correct status.

  const onSignal = (signal: string) => {
    try {
      if (serverProcess && !serverProcess.killed) serverProcess.kill("SIGTERM");
    } catch {
      // ignore
    }
    log.warn(
      { signal },
      "MITM parent received signal — child terminated; run Repair if DNS/CA/proxy were applied."
    );
    process.kill(process.pid, signal);
  };
  process.once("SIGINT", () => onSignal("SIGINT"));
  process.once("SIGTERM", () => onSignal("SIGTERM"));

[gemini-code-assist]

Setting a raw socket idle timeout on the HTTPS server's connection event will unconditionally destroy the socket after 60 seconds of inactivity, even during active HTTP requests. This is particularly problematic for LLM clients using reasoning models (such as DeepSeek-R1 or OpenAI o1/o3), which can have "thinking" times exceeding 60 seconds before they start streaming the first token. During this thinking phase, no data is transmitted, so the socket is considered idle and will be prematurely destroyed.

Since the server already configures robust HTTP-level timeouts (requestTimeout, headersTimeout, and keepAliveTimeout on lines 616-618), the raw socket timeout on connection is redundant and should be removed to prevent breaking long-running requests.

  // HTTP-level timeouts (requestTimeout, headersTimeout, keepAliveTimeout) are already configured on the server.

[gemini-code-assist]

Similar to the HTTPS server, setting a raw socket idle timeout on the HTTP proxy server's connection event will unconditionally destroy the socket after 60 seconds of inactivity, even during active HTTP requests. This will prematurely abort slow requests or requests to slow upstream APIs (such as LLM reasoning models with long thinking times).

Since the proxy server already configures HTTP-level timeouts (requestTimeout, headersTimeout, and keepAliveTimeout on lines 244-246), the raw socket timeout on connection is redundant and should be removed.

[gemini-code-assist]

According to the Repository Style Guide (Rule 8), all input validation schemas must be defined in or imported from src/shared/validation/schemas.ts. Defining RepairBodySchema locally in the route file violates this rule.

Please move RepairBodySchema to src/shared/validation/schemas.ts and import it here.

import { RepairBodySchema } from "@/shared/validation/schemas";

References

1. Always validate inputs with Zod schemas from src/shared/validation/schemas.ts ^(link)

[gemini-code-assist]

According to the Repository Style Guide (Rule 8), all input validation schemas must be defined in or imported from src/shared/validation/schemas.ts. CertTrustBodySchema is currently defined locally in this file (at line 17), which violates this rule.

Please move CertTrustBodySchema to src/shared/validation/schemas.ts and import it here.

References

1. Always validate inputs with Zod schemas from src/shared/validation/schemas.ts ^(link)