Greptile Summary

This PR fixes a regression (introduced in #54536) where authorizeTrustedProxy unconditionally rejected requests from loopback remote addresses, breaking same-host reverse-proxy setups (e.g., Nginx or Caddy on 127.0.0.1) even when loopback was explicitly listed in trustedProxies.

What changed:

• src/gateway/auth.ts: The unconditional isLoopbackAddress → reject is replaced with a conditional check: if the remote address is loopback, the function calls resolveRequestClientIp to inspect the x-forwarded-for chain. Only if that chain is absent or resolves back to a loopback address is the request rejected with trusted_proxy_loopback_source. If the chain resolves to a non-loopback client IP the function continues normally into required-headers and user-header validation.
• src/gateway/auth.test.ts: A new test confirms the new success path (remoteAddr = 127.0.0.1, x-forwarded-for = 203.0.113.10 → auth succeeds with method: "trusted-proxy"). Existing fail-closed tests remain intact and still pass.

Logic correctness: The fix is sound. The outer isTrustedProxyAddress guard (line 349) ensures the loopback address was deliberately configured in trustedProxies before the loopback branch is reached, so trusting the forwarded headers from it is consistent with the operator's intent. The rest of the validation chain (required headers, userHeader, allowUsers) is unchanged and executes after the guard passes.

One test gap: The existing test "rejects same-host proxy request with missing required header" (line 935) does not include x-forwarded-for, so it still fails at the loopback check rather than the required-headers check. The required-headers enforcement on the newly opened code path (loopback source + non-loopback x-forwarded-for + user header present + required header absent) is not covered by any test.

Confidence Score: 5/5

• Safe to merge; the logic change is correct, fail-closed behavior is preserved, and the only finding is a minor test-coverage gap.
• No P0 or P1 issues found. The core logic change is correct by inspection and aligns with the documented intent. Fail-closed paths (missing forwarded IP, loopback-only chain) are still rejected. The single P2 comment concerns a missing test for required-headers enforcement on the new code path — not a runtime defect.
• src/gateway/auth.test.ts — the "rejects same-host proxy request with missing required header" test should be supplemented with a variant that includes a non-loopback x-forwarded-for to actually exercise required-headers enforcement after the loopback guard passes.

This is a comment left during a code review.
Path: src/gateway/auth.test.ts
Line: 935-955

Comment:
**Missing test for required-headers enforcement on the new loopback-bypass path**

The test named `"rejects same-host proxy request with missing required header"` doesn't actually exercise the new code path this PR adds. Because the request omits `x-forwarded-for`, the rejection happens at the loopback check (`trusted_proxy_loopback_source`), not at the required-headers check — so the comment `// missing x-forwarded-proto (requiredHeader)` describes the intent, but not what fires.

Now that a loopback proxy with a non-loopback `x-forwarded-for` is allowed through, there is no test confirming that `requiredHeaders` (`x-forwarded-proto` in this suite) is still enforced after the loopback guard passes. A minimal addition would be:

```typescript
it("rejects same-host proxy request with non-loopback client IP but missing required header", async () => {
  const res = await authorizeGatewayConnect({
    auth: {
      mode: "trusted-proxy",
      allowTailscale: false,
      trustedProxy: trustedProxyConfig,
    },
    connectAuth: null,
    trustedProxies: ["127.0.0.1"],
    req: {
      socket: { remoteAddress: "127.0.0.1" },
      headers: {
        host: "localhost",
        "x-forwarded-user": "nick@example.com",
        "x-forwarded-for": "203.0.113.10",
        // x-forwarded-proto intentionally absent
      },
    } as never,
  });
  expect(res.ok).toBe(false);
  expect(res.reason).toBe("trusted_proxy_missing_header_x-forwarded-proto");
});
```

Without this, the required-headers check is untested on the path that this PR opens up.

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

_{Reviews (1): Last reviewed commit: "fix(auth): enhance trusted-proxy handlin..." | Re-trigger Greptile}

Added unsafeAllowLoopbackProxies configuration flag to address a loopback spoofing vulnerability in trusted-proxy auth.

The issue: The previous loopback exception allowed any local process to forge x-forwarded-for and identity headers, enabling privilege elevation attacks on same-host reverse proxies (nginx/Caddy on localhost).

The solution:

• Default behavior remains secure: loopback connections are rejected
• Same-host proxy deployments can opt-in by setting gateway.auth.trustedProxy.unsafeAllowLoopbackProxies: true
• Configuration includes prominent security warnings and guidance toward safer alternatives (non-loopback address, token/password auth, Tailscale)

Trade-off: Operators with existing localhost reverse proxy setups can now enable this flag consciously, understanding the risk. The naming and documentation make the security implications explicit — this is a deliberate choice, not an implicit vulnerability.

Security + Contract Update

Summary

This PR hardens trusted-proxy auth for localhost reverse-proxy deployments while preserving existing observable failure semantics.

What changed

1. Loopback trusted-proxy requests are now gated by:

   • explicit loopback trust in gateway.trustedProxies
   • a resolvable non-loopback forwarded client IP
   • proxy authenticity material (trustedProxy.authHeader + trustedProxy.authValue) for loopback path

2. trustedProxy.authValue is marked sensitive in config schema/hints so redaction tooling treats it as a secret.

3. Config validation now enforces trustedProxy.authHeader/trustedProxy.authValue pairing at parse time (schema-level), with field-specific errors. Whitespace-only values are rejected.

Contract compatibility (important)

Loopback-source rejections continue to return the existing reason code:

• trusted_proxy_loopback_source

This preserves behavior for existing callers/consumers that rely on the previous loopback rejection contract, avoiding a reason-code migration in this PR.

Why this shape

• Addresses localhost spoofing risk in trusted-proxy mode.
• Keeps same-host reverse-proxy support.
• Avoids breaking downstream reason-code consumers.

Validation

• Focused gateway auth tests for loopback/proxy-auth flows pass.
• Config schema tests for trusted-proxy parse-time constraints pass.
• Generated schema baseline test passes.

"The issue: The previous loopback exception allowed any local process to forge x-forwarded-for and identity headers, enabling privilege elevation attacks on same-host reverse proxies (nginx/Caddy on localhost)."

How does being non-local stop this form of attack? If I move my proxy to a separate host, a rogue local process on that host could still forge x-forwarded-for and identity headers... You're not removing any attack surface, you're just moving the surface to another host.

In practice blocking loopback proxies will make users far less secure because it pushes users toward binding Gateway on a non-loopback interface so a same-machine proxy can reach it via the host’s LAN IP, which can be less secure than a loopback-only deployment if firewalling is not perfect. The net effect may be to trade a localhost trust issue for broader network exposure.

Literally when I asked my OpenClaw jow to fix my proxy setup, it told me I would need to change my network bind to bind to "lan" (IE: 0.0.0.0) and use my hosts LAN IP (192.168.x.x) in the proxy config.

That is exactly what people are going to start doing.

Thanks @Sandblaze05. #73266 landed the localhost trusted-proxy fix and closed #59167.

I am closing this PR as superseded because the landed version keeps the same-host reverse-proxy path behind an explicit gateway.auth.trustedProxy.allowLoopback opt-in, preserves requiredHeaders / allowUsers, and updates the security-audit/docs surface with that sharper contract.