fix(agent): exempt direct loopback callers from the IP whitelist

[Scra3]

What

The agent's IP whitelist evaluated x-forwarded-for ?? request.ip on all /forest routes. The embedded workflow-executor reaches /forest over a loopback socket with no real client IP, so once a customer enabled the whitelist the executor was rejected as 127.0.0.1 → 403 at its probe → the executor never started.

Fix

IpWhitelist.checkIp now exempts a trusted internal caller before the rule check: one reaching us directly over a loopback socket with no proxy hop (no x-forwarded-for).

• Keys on req.socket.remoteAddress (the true socket peer) — never request.ip / x-forwarded-for, which are spoofable once the host app sets app.proxy.
• Feature-agnostic: no coupling to any specific token/scope. A caller behind a same-host reverse proxy carries x-forwarded-for, so it is not exempted and its real IP is still checked normally.
• Safe: checkIp runs after koa-jwt, so an exempted request is already authenticated; a remote attacker can neither forge the socket peer nor pass koa-jwt without the authSecret.

Scope (deliberately narrow)

Fixes only the executor case. Whether the MCP channel should be subject to the IP whitelist is a deferred product decision (Slack thread, PRD-752). Consequences, documented (PRD-753), not changed here:

• Mounted MCP in-process + whitelist ON -> tool calls remain 403 (known limitation, not silently exempted).
• Standalone mcp-server + whitelist ON -> the mcp-server's IP must be whitelisted on the agent (pre-existing).

Tests

packages/agent/test/routes/security/ip-whitelist.test.ts — exemption for the 3 loopback socket forms with no proxy hop; not exempt for a non-loopback socket, nor for a loopback socket carrying x-forwarded-for (proxied user); anti-spoof (external socket + x-forwarded-for: 127.0.0.1 -> 403 on the header IP); non-regression (proxied user from a whitelisted IP passes the normal check).

Note

Exempt direct loopback callers from IP whitelist checks in agent

Requests originating from a loopback socket (127.0.0.1, ::1, ::ffff:127.0.0.1) with no x-forwarded-for header now bypass IP whitelist validation in IpWhitelist.checkIp. A Debug log line is emitted for each exempted request. Loopback sockets that carry an x-forwarded-for header are still subject to normal IP rule checks using the header value.

^{Macroscope summarized 5306eaa.}

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.01%.

Modified Files with Diff Coverage (1)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/routes/security/ip-whitelist.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.