fix(gateway): trusted-proxy auth rejected when bind=loopback by xinhuagu · Pull Request #20097 · openclaw/openclaw

xinhuagu · 2026-02-18T14:31:56Z

Problem

Gateway refuses to start with bind=loopback + auth.mode=trusted-proxy, throwing:

gateway auth mode=trusted-proxy makes no sense with bind=loopback

This blocks a valid deployment pattern: reverse proxy (cloudflared, nginx, Caddy) running on the same host, connecting to the gateway via loopback while adding authentication headers.

Users are forced to use bind=lan, unnecessarily exposing the gateway port to the local network.

Root Cause

Two hardcoded restrictions:

server-runtime-config.ts: throws on loopback + trusted-proxy
configure.gateway.ts: silently overrides bind from loopback to lan

Why This Is Safe

The trusted-proxy auth mode validates identity via HTTP headers (not IP origin) and checks req.socket.remoteAddress against gateway.trustedProxies. On loopback, the remote address is 127.0.0.1 — users configure trustedProxies: ["127.0.0.1"] to allow it. The existing trustedProxies.length === 0 check is preserved, so misconfiguration is still caught.

Fix

Remove the loopback restriction. Keep the trustedProxies-must-be-configured check.

Closes #20073

Greptile Summary

Removes two hardcoded restrictions that blocked trusted-proxy auth when bind=loopback: a hard error in server-runtime-config.ts and a silent bind override to "lan" in configure.gateway.ts. This unblocks a valid deployment pattern where a reverse proxy (e.g. cloudflared, nginx, Caddy) runs on the same host and connects to the gateway via loopback while adding authentication headers.

The existing safety check requiring trustedProxies to be non-empty is preserved, preventing misconfiguration.
On loopback, req.socket.remoteAddress is 127.0.0.1, so users must configure trustedProxies: ["127.0.0.1"] for the auth to work — this is validated at both config time and runtime.
Tests are updated to reflect the new behavior and a new test case covers loopback + trusted-proxy with empty trustedProxies.

Confidence Score: 5/5

This PR is safe to merge — it removes an unnecessary restriction while preserving all security validations.
The change is minimal and well-scoped: two restriction blocks removed, safety checks (trustedProxies must be configured) preserved. The auth flow in auth.ts validates remoteAddress against trustedProxies at request time, so security is not degraded. Tests are comprehensive and cover both the happy path and misconfiguration case. No other code paths depend on the removed restrictions.
No files require special attention

_{Last reviewed commit: 3cfb225}

greptile-apps

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

src/commands/configure.gateway.ts

greptile-apps · 2026-02-18T14:35:14Z

Additional Comments (1)

src/gateway/server-runtime-config.ts
Existing test will fail after this change

The test in src/gateway/server-runtime-config.test.ts (line 33) — "should reject loopback binding with trusted-proxy auth mode" — still expects this configuration to throw "gateway auth mode=trusted-proxy makes no sense with bind=loopback". Since the throw was removed, this test will now fail.

It should be updated to instead assert that loopback + trusted-proxy succeeds when trustedProxies is configured (and still rejects when trustedProxies is empty).

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/gateway/server-runtime-config.ts
Line: 105-111

Comment:
**Existing test will fail after this change**

The test in `src/gateway/server-runtime-config.test.ts` (line 33) — `"should reject loopback binding with trusted-proxy auth mode"` — still expects this configuration to throw `"gateway auth mode=trusted-proxy makes no sense with bind=loopback"`. Since the throw was removed, this test will now fail.

It should be updated to instead assert that loopback + trusted-proxy **succeeds** when `trustedProxies` is configured (and still rejects when `trustedProxies` is empty).

How can I resolve this? If you propose a fix, please make it concise.

xinhuagu · 2026-02-18T15:03:55Z

@greptileai review

xinhuagu · 2026-02-18T15:10:31Z

@greptileai review

xinhuagu · 2026-02-18T15:16:49Z

The test has been updated in the latest push — should reject loopback binding with trusted-proxy auth mode is now should allow loopback binding with trusted-proxy auth mode (asserts success). Also added a new test should reject loopback trusted-proxy without trustedProxies configured to cover the empty-trustedProxies case. CI is green ✅

xinhuagu · 2026-02-18T15:44:45Z

@greptileai review

…inhuagu

…inhuagu

mbelinky · 2026-02-20T17:51:40Z

Merged via squash.

Prepared head SHA: 8de62f1
Merge commit: 9c52497

Thanks @xinhuagu!

@mbelinky