feat: global egress proxy (HTTP(S)_PROXY across all daemon + CLI egress)

[roeikosh]

Description

Makes all daemon and CLI egress proxy-aware.

📌 Future hardening recommendations (DNS-pinned SSRF, pre-merge SAST, plugin SDK) are at the end of this description — jump to Future work: recommended follow-ups.

Why we built it (corporate-proxy / egress-locked networks). The deployments that hit this run inside a corporate network where direct outbound internet is blocked and the only sanctioned path off-box is the corp HTTP(S) proxy — the normal posture for regulated/enterprise environments, where all egress must traverse a single audited gateway. Comis previously had no way to honor it: Node's native fetch (undici) ignores HTTP_PROXY/HTTPS_PROXY (while curl honors them), so comis init reported "could not reach Telegram API" even though the token worked with curl, and the daemon couldn't function on the network at all. Routing everything through the corp proxy is also what lets the security team apply their existing egress controls (allow-listing, logging, DLP, TLS inspection) to the agent's traffic.

Security benefits

Making egress proxy-aware turns outbound traffic into a controlled, auditable surface:

• Single egress chokepoint. Every outbound connection (LLM providers, MCP, media, web search, all chat transports) is forced through the configured proxy, so the corporate gateway's allow-listing, logging, and DLP apply uniformly. This makes a zero-direct-egress posture viable — direct internet can be fully blocked and Comis still operates.
• SSRF blocklist on every proxied request. Before any proxy agent is constructed, the target host is checked against an internal/special-purpose IP blocklist (loopback, RFC 1918, CGNAT, IPv6 ULA/link-local, IPv4-mapped IPv6, and the 169.254.0.0/16 link-local range that covers the AWS/GCP/Azure 169.254.169.254 metadata endpoint). Closes the "agent tricked into fetching cloud metadata / internal services" path.
• Fail-closed boot. A misconfigured proxy makes the daemon fail closed at boot rather than silently falling back to direct egress. An unresolved ${SECRET} proxy URL fails with a SecretRef-naming error.
• Explicit, hardenable loopback policy. loopbackMode defaults to gateway-only (the daemon's own localhost:4766 gateway is always kept off the proxy); block mode rejects any loopback egress for hardened environments, while the SSRF gate still blocks private ranges in proxy mode.
• TLS inspection / internal CA support. proxy.tls.caFile threads a corporate/self-signed CA into the proxy tunnel (CONNECT) connection — works behind a TLS-inspecting proxy without disabling certificate validation.
• Credential hygiene. Proxy URLs (which may embed user:pass) are redacted everywhere via sanitizeProxyUrl; caFile is a path only (cert content never logged); the proxy.* config block is runtime-immutable.
• Diagnosable by failure class. Channel credential validators classify failures as network-vs-auth (classifyValidationError), so an egress/proxy failure says "check egress / proxy" instead of misleadingly telling the operator to re-check their token.

How it works

• Tier 1 — global dispatcher. The daemon installs a global undici dispatcher at boot (installGlobalProxyDispatcher) so every fetch-based egress (providers, MCP, media, web search) routes through the proxy. Loopback/gateway addresses are kept out via an effective NO_PROXY (with CIDR support); an SSRF blocklist interceptor rejects private/metadata destinations. comis init installs an env-only dispatcher so live credential/channel validation honors the proxy too.
• Tier 2 — per-transport wiring. Adapters that don't use undici get explicit agents: grammy/Telegram, Slack, Baileys/WhatsApp (HttpsProxyAgent), discord.js REST (ProxyAgent), IMAP/SMTP (native proxy:). IRC and the discord WS gateway are documented accepted gaps; signal-cli inherits the proxy env; LINE/Earendil are covered by the global dispatcher.
• Config: new proxy.* block (enabled, proxyUrl supporting ${SECRET}, tls.caFile, loopbackMode).
• Diagnostics: comis proxy validate (offline reachability + loopback canary + SSRF pre-check + honest uncovered-transports list); proxy posture surfaces on comis explain / comis fleet.
• Architecture: pure net primitives in @comis/core/net; undici-bound runtime pieces in @comis/infra — keeps the @comis/cli ↛ @comis/infra boundary (L12) intact.
• Docs: docs/security/network-proxy.md (coverage table + SSRF + loopback policy + caFile) plus env-var and CLI references.

Related Issue

Fixes the corporate-proxy connectivity bug (comis init "could not reach Telegram API" behind an egress-locked proxy). No tracked issue number.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Refactor

Checklist

• Tests pass (pnpm test)
• Linting passes (pnpm lint:security)
• Documentation updated (if applicable)
• No secrets or credentials committed
• Security implications considered

RED Test Proof

Test-first per commit. Representative RED before the production patch — matchesNoProxy CIDR matching (packages/core/src/net/proxy-env.test.ts), which fails on pre-patch code because no NO_PROXY CIDR matcher existed:

FAIL  packages/core/src/net/proxy-env.test.ts > matchesNoProxy > matches an IP inside a CIDR range
TypeError: matchesNoProxy is not a function
 ❯ packages/core/src/net/proxy-env.test.ts:160

AssertionError: expected false to be true   // 10.1.2.3 vs NO_PROXY=10.0.0.0/8
 ❯ packages/core/src/net/proxy-env.test.ts:165

SSRF gate RED (packages/core/src/net/ssrf.test.ts — isSsrfBlocked("169.254.169.254") expected true, returned false pre-patch) and the channel-validator network-vs-auth classification RED (classifyValidationError returning auth for a connection-refused error) follow the same pattern. The bwrap/*.linux test:coverage tier was not run on the dev box (host EDR) — exercised by CI.

Dependency security bumps (included)

This PR also clears pnpm audit --prod (the CI audit tier, which prior runs never reached). The advisories are pre-existing on main — comisai:main's latest CI audit is red on the same undici set — surfaced here because this is the first branch to run the full pipeline green up to that step. Bumped to patched releases (security-floor pnpm.overrides + matching exact pins):

Package	From → To	Advisory
undici	8.3.0 → 8.5.0	GHSA-p88m-4jfj-68fv (+14) — also the dep the egress proxy itself uses (added to @comis/cli)
hono	4.12.23 → 4.12.26	GHSA-wgpf-jwqj-8h8p
nodemailer	8.0.10 → 9.0.1 (major)	patched ≥9.0.1
protobufjs (transitive, @google/genai)	→ ≥8.6.0	override floor
form-data (transitive, @line/bot-sdk→axios)	→ ≥4.0.6	override floor

Verified: pnpm audit --prod → no known vulnerabilities; clean build; email adapter (112, nodemailer 9), gateway (547, hono), infra net (53), daemon proxy-boot (20) suites green; umbrella-bundling + package-runtime-deps guards green (pins stay exact + version-matched across the umbrella).

Additional Notes

CI guard fixes folded in alongside the feature: removed an @deprecated JSDoc alias (no-backward-compat), dropped dead @comis/channels re-exports consumed only internally (public-export-consumers), added https-proxy-agent@7.0.6 to the umbrella comisai package deps + lockfile (umbrella-bundling), kept daemon.ts under its line cap by extracting wiring/emit-config-posture.ts, restored infra branch coverage ≥92% by collapsing unreachable guards in proxy-agent.ts, and made installProxyAtBoot tolerate a missing config.proxy block.

Future work: recommended follow-ups

Not in this PR — scoped hardening surfaced while building the egress layer:

1. Guard direct (no-proxy) egress, then DNS-pin it. Today the SSRF interceptor is composed only inside installGlobalProxyDispatcher, after the zero-config no-op return — so with no proxy configured, direct fetch has no SSRF guard at all, and even on the proxied path the check is a synchronous host-string test that lets a hostname resolving to a private IP through (DNS-rebinding / TOCTOU gap). Two-step fix, ~2–3 days in packages/infra/src/net, reusing the existing isSsrfBlocked predicate:
   • (a) Install the SSRF-guarded dispatcher unconditionally (zero-config too), so direct egress is guarded regardless of proxy config.
   • (b) Add a DNS-pinning undici connector (buildConnector({ lookup })) that resolves the host, validates every returned address via isSsrfBlocked, fails closed, and pins the connection to the validated IP (no re-resolution). Must exempt the configured proxy/gateway hosts — a corp proxy is often on a private RFC-1918 IP — by reusing resolveLoopbackExemptHosts. This closes the DNS-rebinding gap that the current synchronous host-string check leaves open on the direct path.
2. Pre-merge static-analysis firewall. Add a before-commit gate — a fast linter (e.g. oxlint), a CVE/GHSA-tied semgrep/opengrep rulepack (PR-gated), and a pre-commit framework (shellcheck, actionlint, zizmor, detect-private-key); today comis has eslint-security + CodeQL + a pre-push pnpm validate only. Mostly config — high quality-per-effort.
3. Extract a published plugin-SDK boundary (largest effort). A versioned plugin SDK + declarative extensions would let third parties ship channels/tools without forking; comis channels are currently hardcoded workspace packages with no extension API.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	nodemailer@​8.0.10 ⏵ 9.0.1	+1	+16	+1
	hono@​4.12.23 ⏵ 4.12.26	+1	+21
	undici@​8.3.0 ⏵ 8.5.0		+31	+1

View full report

[anconina]

Code review

Found 2 issues:

1. The PR introduces internal design-doc traceability IDs (XPORT-NN, D-NN, SC#N, T-N-NN, WR-02, Wave-3) across production comments, test names, and — most importantly — operator-facing runtime strings: the exported UNCOVERED_TRANSPORTS[].reason strings that feed comis proxy validate --json embed (XPORT-06), (XPORT-02), XPORT-07. (CLAUDE.md says "Never add (AGENTS.md §2.12): process/traceability IDs (WR-01, Phase 193, …). Runtime strings — log messages, hints, tool/CLI output — carry ZERO of these".) This branch predates commit 82fc311e ("strip pre-release history for first public release"), which removed exactly this pattern repo-wide and encoded the rule in AGENTS.md §2.12 — a sweep before merge would reconcile it. Runtime strings:

comis/packages/cli/src/util/proxy-error-classify.ts

Lines 138 to 152 in ae19798

	reason:
	"IRC clients use raw TCP sockets — not an HTTP/HTTPS fetch path — so EnvHttpProxyAgent has no effect. irc-framework is SOCKS-only; HTTP CONNECT is not supported. Accepted gap: low-volume, operator-controllable channel. See docs/security/network-proxy.md (XPORT-06).",
	coveredInPhase: "accepted-gap",
	},
	{
	name: "Discord WS",
	reason:
	"The Discord gateway connection is a WebSocket upgrade initiated by the discord.js library, which does not use the undici global dispatcher. ws-agent wiring is a disproportionate change for the current phase. Accepted gap: operator-controllable. See docs/security/network-proxy.md (XPORT-02).",
	coveredInPhase: "accepted-gap",
	},
	{
	name: "signal-cli",
	reason:
	"signal-cli is a separate JVM process that inherits process.env (https_proxy / http_proxy / HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY). It is env-covered — the global dispatcher does not apply to it, but env var injection is sufficient. The daemon Stage-1 scrub deliberately excludes these keys (verified by daemon.test.ts XPORT-07). signal-client.ts itself uses fetch → global dispatcher for the HTTP/SSE API channel.",
	coveredInPhase: "env-covered",

Representative comment instances (also in immutable-keys.ts, emit-config-posture.ts, setup-channels-adapters.ts, signal-client.ts, and many test titles):

comis/packages/core/src/net/sanitize.ts

Lines 2 to 4 in ae19798

	/**
	* Proxy URL credential sanitizer — SEC-04 / D-08.
	*

comis/packages/daemon/src/daemon-proxy-boot-helpers.ts

Lines 269 to 274 in ae19798

	* logProxyPosture — emit exactly one module:"proxy" INFO line when the proxy
	* dispatcher is active (D-07 / SC#1). Call AFTER setupLogging() (~line 1375).
	*
	* Emits nothing when posture.configured is false (D-10 zero-config gate).
	* Only maskedUrl is logged — the raw proxy URL is never interpolated (T-3-03).
	*/

Rule:

comis/CLAUDE.md

Lines 19 to 21 in c3406c5

	## No Pre-History in Comments/Docs/Strings
	The public repo shows no build pre-history. Never add (AGENTS.md §2.12): process/traceability IDs (`WR-01`, `Phase 193`, `.planning/…`, `design §…`), Comis version pre-history (`v2.31`, "added in vX", migration framing), milestone codenames ("Glass Box"), or reference-project names (Hermes, OpenClaw/clawdbot, Deer-Flow). State the constraint, not its origin. **Runtime strings — log messages, `hint`s, tool/CLI output — carry ZERO of these; cleaning one is a behavior change, so update its asserting test in the same commit.** Keep third-party/standards versions, GitHub `#refs`, real code identifiers (`SEC-GW-003` codes, live-test scenario IDs, `architecture-allowlist` phase types), and license attributions in `NOTICE`.

2. The new top-level proxy config section is missing from the config catalog docs/reference/config-yaml.mdx, whose quick-reference still says "All 42 top-level configuration sections at a glance" — the PR adds the section to the schema but does not update the catalog (the new docs/security/network-proxy.md page documents usage, not the authoritative key/default reference). (CLAUDE.md says "Keep docs/**/*.mdx up to date in the same change that alters anything they describe — user-facing behavior, config keys/defaults, …")

Schema addition:

comis/packages/core/src/config/schema.ts

Lines 71 to 74 in ae19798

	gateway: GatewayConfigSchema.default(() => GatewayConfigSchema.parse({})),
	/** Outbound HTTP proxy configuration (env-first, zero-config default path) */
	proxy: ProxyConfigSchema.default(() => ProxyConfigSchema.parse({})),
	/** External integrations configuration */

Stale catalog claim:

comis/docs/reference/config-yaml.mdx

Lines 156 to 158 in c3406c5

	All 42 top-level configuration sections at a glance:

Rule:

comis/CLAUDE.md

Lines 11 to 13 in c3406c5

	## Docs-Current
	Keep `docs/**/*.mdx` up to date in the **same change** that alters anything they describe — user-facing behavior, config keys/defaults, CLI commands/flags, file paths and the `~/.comis` data-dir layout (`docs/operations/data-directory.mdx`), env vars (`docs/reference/environment-variables.mdx`), logging, and install/release steps. A patch that leaves the docs describing the old behavior is incomplete. Run `pnpm docs:check` (cheap, no build needed; also part of `validate`) to catch MDX errors. The docs sit **outside** the build/lint/coverage gates, so drift fails silently rather than breaking a gate: e.g. `COMIS_LOG_PATH`'s documented default was wrong (`~/.comis/logs/daemon.log`) for ages because nothing checked it. When you rename or move a path/flag/key, `grep -rn '<old-name>' docs/` and fix every hit.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}