[Threat] Trusted-proxy mode creates a distinct Control UI trust boundary where proxy, origin, and WebSocket/pairing drift can yield unintended operator access

[jjdomain]

I’d like to propose a threat entry for failures around gateway.auth.mode = "trusted-proxy".

This is not a claim about one current unpatched vulnerability. I’m suggesting this should be documented as a threat family because trusted-proxy creates a distinct control-plane trust boundary with its own failure modes, and recent advisories suggest this boundary is important enough to name directly.

Why this feels different from generic sender spoofing

In trusted-proxy mode, OpenClaw delegates identity to the reverse proxy. In the current auth code, access depends on several linked assumptions: the request must come from a configured trusted proxy IP, required proxy headers may need to be present, the configured identity header must be populated, and optional allowUsers checks become the effective allowlist. The docs also say that when trusted-proxy checks pass, Control UI WebSocket sessions can connect without device pairing identity, so pairing is no longer the primary gate in that mode.

That makes this feel different from ordinary sender spoofing. The boundary here depends on multiple things staying aligned:

• only the proxy can reach the Gateway
• the proxy strips and rewrites identity headers correctly
• HTTP and WebSocket entry paths preserve equivalent auth guarantees
• browser-origin validation remains independent from proxy-header validation
• pairing and role/scope behavior do not accidentally widen access on one path

If those assumptions drift apart, the outcome can be more serious than a spoofed sender field. It can become unintended operator-class access to the Gateway control plane.

Attack scenario

1. A deployment runs behind a reverse proxy with gateway.auth.mode = "trusted-proxy".
2. The proxy forwards authenticated identity headers to the Gateway, including on WebSocket upgrade requests.
3. A browser-originated or adjacent client path reaches the Gateway through that trusted proxy path.
4. Origin validation, pairing behavior, or WebSocket scope binding behaves differently than the operator expects on that path.
5. The client reaches a Control UI or operator-class session it should not have received.

Affected parts

• Gateway auth / trusted-proxy
• Control UI WebSocket connect path
• browser-origin validation
• pairing behavior for Control UI-related sessions
• role/scope binding on WebSocket session establishment

Impact

Potential outcomes include:

• unintended Control UI access
• operator-class session establishment
• access to privileged gateway methods
• wider blast radius from proxy or deployment mistakes

I think this deserves its own threat entry because the recent advisory history in this area was not limited to one narrow bug class. It involved trusted-proxy assumptions, browser-origin validation, Control UI WebSocket behavior, and privileged session establishment.

Why I think the threat model should name this directly

The current threat-model summary lists token/password/Tailscale auth and device pairing inside the Gateway trust boundary, but it does not seem to call out trusted-proxy as its own first-class boundary even though the docs treat it as security-sensitive and the advisory history shows repeated boundary failures involving proxy auth, origin validation, pairing, and WebSocket/session handling. Naming the class would help future reviews catch new variants earlier.

Suggested mitigations

• Model trusted-proxy as its own first-class trust boundary in the threat model.
• Require equivalent auth and identity guarantees across HTTP and WebSocket entry points, including upgrade handling.
• Keep browser-origin validation independent from proxy-header validation.
• Treat any path that bypasses the proxy as an explicit anti-pattern in deployment guidance.
• Encourage non-empty allowUsers and meaningful requiredHeaders in examples and audits.

Severity

My guess is High when this threat manifests in a browser-reachable or control-path-reachable deployment, because the boundary being crossed is the Gateway control plane / operator trust boundary. But I’m leaving final scoring to maintainers.