Summary

Fixes #17761.

Note: The device-pairing bypass for trusted-proxy connections (previously PR #17705) has been absorbed upstream via the connect-policy.ts refactoring (isTrustedProxyControlUiOperatorAuth, evaluateMissingDeviceIdentity, shouldSkipControlUiPairing). This PR is now based directly on main and focuses solely on the shared-secret auth fallback.

The gateway's authorizeGatewayConnect dispatcher treats trusted-proxy as a single-mode gate: when proxy auth fails (e.g. internal services connecting directly without the reverse proxy), the function early-returns before reaching the shared-secret (token/password) or Tailscale code paths. This breaks all internal consumers — node host, CLI RPC, ACP, TUI, agent tools, etc.

This PR adds an inline shared-secret fallback within the trusted-proxy block:

• When proxy auth fails and a token/password is configured, attempt shared-secret auth before returning failure
• Rate-limit fallback attempts using the existing AuthRateLimiter
• Preserve proxy auth priority (successful proxy auth still short-circuits)
• Fix allowTailscale default to not exclude trusted-proxy mode

Root Cause

When auth.mode === "trusted-proxy", the authorizeGatewayConnect function enters the trusted-proxy block and either succeeds or returns a failure reason. It never falls through to the shared-secret (token/password) block below. Internal services that connect directly (without the reverse proxy) always fail because they can't provide the proxy headers.

Changes

src/gateway/auth.ts:

1. Hoist limiter/ip/rateLimitScope above the trusted-proxy block so the fallback can reuse them:

+  const limiter = params.rateLimiter;
+  const ip =
+    params.clientIp ??
+    resolveRequestClientIp(req, trustedProxies, params.allowRealIpFallback === true) ??
+    req?.socket?.remoteAddress;
+  const rateLimitScope = params.rateLimitScope ?? AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET;
+
   if (auth.mode === "trusted-proxy") {

2. Add shared-secret fallback after proxy auth failure:

     if ("user" in result) {
       return { ok: true, method: "trusted-proxy", user: result.user };
     }
+
+    // Trusted-proxy auth failed — try shared-secret fallback for internal
+    // services (CLI, node host, ACP) that bypass the reverse proxy.
+    if (!auth.token && !auth.password) {
+      return { ok: false, reason: result.reason };
+    }
+
+    // Rate-limit fallback attempts
+    if (limiter) { ... }
+
+    // Try token fallback
+    if (connectAuth?.token && auth.token) {
+      if (safeEqualSecret(connectAuth.token, auth.token)) {
+        limiter?.reset(ip, rateLimitScope);
+        return { ok: true, method: "token" };
+      }
+      ...
+    }
+
+    // Try password fallback
+    if (connectAuth?.password && auth.password) { ... }
+
+    // Client didn't provide matching credentials — return original proxy failure
     return { ok: false, reason: result.reason };

3. Fix allowTailscale default to not exclude trusted-proxy mode:

-    authConfig.allowTailscale ??
-    (params.tailscaleMode === "serve" && mode !== "password" && mode !== "trusted-proxy");
+    authConfig.allowTailscale ?? (params.tailscaleMode === "serve" && mode !== "password");

src/gateway/auth.test.ts: 9 new unit tests for the fallback path (success, rejection, rate limiting, priority)

src/gateway/server.auth.e2e.test.ts: 3 new e2e tests for internal connections with token fallback + device identity

Connection flow (after fix)

Client connects to gateway (mode=trusted-proxy)
├─ From trusted proxy with user header? → Authenticated (trusted-proxy)
├─ Proxy auth failed, token/password configured?
│  ├─ Rate-limited? → Rejected (rate_limited)
│  ├─ Valid token? → Authenticated (token) → device-pairing works
│  ├─ Valid password? → Authenticated (password) → device-pairing works
│  └─ No match → Original proxy failure reason
└─ No fallback credentials configured → Original proxy failure reason

Related Issues

• [Bug]: Gateway auth dispatcher blocks all internal services when mode=trusted-proxy (no shared-secret fallback) #17761 — this bug report
• [Feature]: Allow disabling auth with LAN binding for reverse proxy setups #1560 — original trusted-proxy auth implementation
• [Bug]: Device token auth regression in v2026.2.14 - token priority flip in d8a2c80cd breaks non-localhost clients #17270 — device_token_mismatch errors in trusted-proxy setups
• [Bug]: openclaw status --deep crashes when gateway is unreachable #17106 — canSkipDevice/skipPairing gate logic
• feat(gateway): server-side token injection for reverse proxy deployments #10382 — auth mode configuration
• [Bug]: openclaw node run fails silently with "1008: pairing required" when connecting to a remote gateway #4833 — GatewayClient reconnect behavior
• [Bug]: Docker manual setup fails - CLI cannot reach gateway due to network configuration #5559 — rate limiting for auth

Test Plan

• 9 unit tests for shared-secret fallback (proxy success unchanged, token/password fallback, rejection, rate limiting, priority)
• 3 e2e tests for internal connections (token + device identity, token + no device, proxy priority)
• All existing 30 unit tests pass
• All existing 33 e2e tests pass
• oxlint — 0 errors
• oxfmt — clean
• tsgo — clean

Closes #17761
Related: #8529, #7384, #4833

Rebase History