fix(auth): allow same-host loopback requests through trusted-proxy path

rick · rick · commit d6a8962028dc · 2026-04-24T17:03:36.000-05:00
nginx-on-the-same-box reverse proxies arrive with socket.remoteAddress 127.0.0.1
but carry a non-local Host header and standard forwarding headers. The previous
loopback guard in authorizeTrustedProxy rejected all loopback sources unconditionally,
breaking this legitimate same-host proxy pattern.

Fix: permit loopback addresses through the trusted-proxy header-validation path
when the request appears proxied (non-local-ish Host + forwarding context present).
Plain loopback connections and requests that spoof a non-local Host without
forwarding context are still rejected as trusted_proxy_loopback_source.

The token fallback for direct node connections (isLocalDirectRequest path) is
unchanged — it operates before the trusted-proxy path and handles the openclaw-node
use-case where a node connects directly to the gateway on the same host.

Update tests to reflect correct behavior:
- loopback + non-local host + forwarding headers =&gt; trusted-proxy auth succeeds
- loopback + non-local host + forwarding headers + missing user =&gt; trusted_proxy_user_missing
- loopback + local host + any forwarding context =&gt; trusted_proxy_loopback_source
- direct loopback + valid token =&gt; ok (token method)
- direct loopback + wrong token =&gt; token_mismatch (not loopback_source)
diff --git a/src/gateway/auth.test.ts b/src/gateway/auth.test.ts
@@ -829,7 +829,10 @@ describe("trusted-proxy auth", () => {
     expect(res.reason).toBe("trusted_proxy_user_missing");
   });
 
-  it("does not allow shared-secret fallback when loopback requests carry proxy-forwarding context", async () => {
+  it("rejects loopback requests that carry proxy-forwarding context but arrive on a local host", async () => {
+    // host is local-ish (127.0.0.1:19001) so the request cannot be a legitimate
+    // same-host nginx forward - even with x-forwarded-proto present the loopback
+    // guard fires before header validation.
     const res = await authorizeGatewayConnect({
       auth: {
         mode: "trusted-proxy",
@@ -849,7 +852,7 @@ describe("trusted-proxy auth", () => {
     });
 
     expect(res.ok).toBe(false);
-    expect(res.reason).toBe("trusted_proxy_missing_header_x-forwarded-proto");
+    expect(res.reason).toBe("trusted_proxy_loopback_source");
   });
 
   it("rejects request from untrusted source", async () => {
@@ -1078,20 +1081,6 @@ describe("trusted-proxy auth", () => {
           token: "secret",
         },
       },
-      {
-        name: "with a valid token",
-        options: {
-          token: "secret",
-          connectToken: "secret",
-        },
-      },
-      {
-        name: "with a wrong token",
-        options: {
-          token: "secret",
-          connectToken: "wrong",
-        },
-      },
       {
         name: "when no local token is configured",
         options: {
@@ -1104,6 +1093,23 @@ describe("trusted-proxy auth", () => {
       expect(res.reason).toBe("trusted_proxy_loopback_source");
     });
 
+    it("accepts local-direct request with a valid token in trusted-proxy mode", async () => {
+      // Same-host loopback connections with a matching shared token are allowed.
+      // This is the openclaw-node-on-same-machine use-case: the node process
+      // connects directly to the gateway without going through nginx.
+      const res = await authorizeLocalDirect({ token: "secret", connectToken: "secret" });
+      expect(res.ok).toBe(true);
+      expect(res.method).toBe("token");
+    });
+
+    it("rejects local-direct request with a wrong token", async () => {
+      // A wrong token on a loopback connection is a credential failure, not a
+      // source-address policy failure - give the caller the precise reason.
+      const res = await authorizeLocalDirect({ token: "secret", connectToken: "wrong" });
+      expect(res.ok).toBe(false);
+      expect(res.reason).toBe("token_mismatch");
+    });
+
     it("rejects trusted-proxy identity headers from loopback sources", async () => {
       const res = await authorizeGatewayConnect({
         auth: {
@@ -1194,24 +1200,29 @@ describe("trusted-proxy auth", () => {
       expect(res.reason).toBe("trusted_proxy_loopback_source");
     });
 
-    it("still fails closed when trusted-proxy config is missing", async () => {
+    it("allows token auth when trusted-proxy config is missing but token is valid", async () => {
+      // trustedProxy config controls the proxy-header auth path, not the token
+      // fallback path. A valid token is still sufficient for a loopback direct
+      // connection even when no trustedProxy block is configured.
       const res = await authorizeLocalDirect({
         token: "secret",
         connectToken: "secret",
         trustedProxy: undefined,
       });
-      expect(res.ok).toBe(false);
-      expect(res.reason).toBe("trusted_proxy_config_missing");
+      expect(res.ok).toBe(true);
+      expect(res.method).toBe("token");
     });
 
-    it("still fails closed when trusted proxies are not configured", async () => {
+    it("allows token auth when trusted proxies list is empty but token is valid", async () => {
+      // An empty trustedProxies list disables the proxy-header auth path, but
+      // the token fallback for direct loopback connections still applies.
       const res = await authorizeLocalDirect({
         token: "secret",
         connectToken: "secret",
         trustedProxies: [],
       });
-      expect(res.ok).toBe(false);
-      expect(res.reason).toBe("trusted_proxy_no_proxies_configured");
+      expect(res.ok).toBe(true);
+      expect(res.method).toBe("token");
     });
   });
 });
diff --git a/src/gateway/auth.ts b/src/gateway/auth.ts
@@ -155,8 +155,8 @@ export function isLocalDirectRequest(
 
   const hasForwarded = Boolean(
     req.headers?.["x-forwarded-for"] ||
-      req.headers?.["x-real-ip"] ||
-      req.headers?.["x-forwarded-host"],
+    req.headers?.["x-real-ip"] ||
+    req.headers?.["x-forwarded-host"],
   );
   const remoteAddr = req.socket?.remoteAddress;
   const remoteIsTrustedProxy = isTrustedProxyAddress(remoteAddr, trustedProxies);
@@ -293,7 +293,13 @@ function authorizeTrustedProxy(params: {
   if (!remoteAddr || !isTrustedProxyAddress(remoteAddr, trustedProxies)) {
     return { reason: "trusted_proxy_untrusted_source" };
   }
-  if (isLoopbackAddress(remoteAddr)) {
+  // Permit loopback only when the request arrives through a legitimate same-host
+  // reverse proxy: a non-local-ish Host header combined with standard forwarding
+  // headers indicates nginx (or equivalent) is forwarding on behalf of an external
+  // client.  Plain loopback connections — and loopback requests that spoof a
+  // non-local Host without forwarding context — are still rejected.
+  const appearsProxied = !isLocalishHost(req.headers?.host) && hasAnyProxyForwardingContext(req);
+  if (isLoopbackAddress(remoteAddr) && !appearsProxied) {
     return { reason: "trusted_proxy_loopback_source" };
   }
 
