PR #59190: fix(auth): enhance trusted-proxy handling for non-loopback forwarded IPs

• Repository: openclaw/openclaw
• Author: Sandblaze05
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59190

Description (problem / solution / changelog)

Summary

• Problem: Trusted-proxy auth rejected all loopback sources, which broke same-host reverse proxy setups (for example Caddy or nginx on localhost) even when gateway.trustedProxies explicitly included loopback.
• Why it matters: Local authn/authz proxy deployments could no longer access Gateway, causing unauthorized failures with reason trusted_proxy_loopback_source.
• What changed: In trusted-proxy mode, loopback proxy sources are now allowed only when forwarded client IP resolves to a non-loopback address.
• What did NOT change (scope boundary): Direct loopback requests without valid forwarded client origin still fail closed; no token/password auth behavior changed.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #59167
• Related #54536
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: Trusted-proxy authorization added a blanket loopback-source rejection in src/gateway/auth.ts, so trusted identity headers from localhost proxies were always denied.
• Missing detection / guardrail: No positive test existed for same-host trusted proxy with non-loopback forwarded client origin.
• Prior context (git blame, prior PR, issue, or refactor if known): Regression introduced in the hardening change from #54536.
• Why this regressed now: The loopback block was unconditional, so explicit trustedProxies loopback configurations could not succeed.
• If unknown, what was ruled out: N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
• Unit test
• Seam / integration test
• End-to-end test
• Existing coverage already sufficient
• Target test or file: auth.test.ts
• Scenario the test should lock in: Accept same-host trusted-proxy auth when x-forwarded-for resolves to a non-loopback client IP, while still rejecting missing/loopback client chains.
• Why this is the smallest reliable guardrail: Logic is isolated in gateway auth path and can be validated deterministically in unit tests.
• Existing test that already covers this (if any): Existing tests already covered loopback rejection and fail-closed behavior.
• If no new test is added, why not: N/A (new test added)

User-visible / Behavior Changes

• Trusted-proxy mode on loopback now works for local reverse proxies if forwarded client origin is present and non-loopback.
• Requests still fail with trusted_proxy_loopback_source when forwarded client origin is missing or resolves to loopback.

Diagram (if applicable)

Before:
[localhost proxy request with identity headers] -> [loopback source check] -> [always reject]

After:
[localhost proxy request with identity headers]
-> [loopback source check]
-> [resolve forwarded client IP]
-> [non-loopback client IP: allow trusted-proxy auth]
-> [missing/loopback client IP: reject]

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Windows 11 dev environment; issue report target is Debian 13
• Runtime/container: local test runner
• Model/provider: N/A
• Integration/channel (if any): Gateway trusted-proxy auth
• Relevant config (redacted): trusted-proxy mode with trustedProxies including 127.0.0.1

Steps

1. Configure gateway auth mode trusted-proxy with trustedProxies including loopback.
2. Send request from loopback source with trusted identity headers and x-forwarded-for as non-loopback client IP.
3. Validate auth succeeds; verify loopback-only or missing forwarded client origin still fails.

Expected

• Same-host proxy auth succeeds when forwarded client origin is non-loopback.

Actual

• Previously all loopback trusted-proxy requests were rejected; now behavior matches expected with fail-closed safety preserved.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Scoped verification run:

• corepack pnpm test -- auth.test.ts -t "accepts same-host proxy identity headers when forwarded client IP is non-loopback|rejects trusted-proxy identity headers from loopback sources|fails closed when forwarded headers are present but the client chain resolves to loopback"
• Result: 3 passed, 0 failed

Human Verification (required)

• Verified scenarios: New same-host trusted-proxy success path with non-loopback x-forwarded-for; existing loopback fail-closed paths.
• Edge cases checked: Missing forwarded headers and loopback-only forwarded chain still rejected.
• What you did not verify: Full external reverse-proxy end-to-end (Caddy/Authelia) in this branch.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Proxies that do not send client-origin forwarding headers remain blocked on loopback.
• Mitigation: This is intentional fail-closed behavior; deployment guidance should require trusted proxy to set x-forwarded-for with real client IP.

https://github.com/openclaw/openclaw/issues/59167

Changed files

• src/gateway/auth.test.ts (modified, +28/-0)
• src/gateway/auth.ts (modified, +4/-1)