Problem

When gateway.auth.mode is "trusted-proxy", the gateway WebSocket auth handler rejects all non-proxy connections (loopback, untrusted source) without checking password credentials. This breaks local clients — subagents, browser extensions, and CLI — that connect directly and cannot go through the reverse proxy.

PR #63280 (b1724f8b5f) auto-generates a browser control password for trusted-proxy mode and persists it to gateway.auth.password. However, the credential resolution path (call.ts, credential-planner.ts, credentials.ts) still blocks password reading for trusted-proxy mode, and the gateway auth dispatcher (auth.ts) still early-returns on trusted-proxy failure without attempting password verification.

Result: callGateway() never reads the password from config, and even if it did, the server would never check it. Subagent spawns, browser extension connections, and local CLI calls all fail with unauthorized.

This is reported in #17761, #26007, and #43300.

Root Cause

Two commits introduced conflicting assumptions:

The server-side authorizeGatewayConnectCore treats auth modes as mutually exclusive: trusted-proxy early-returns on failure, never falling back to password.

Solution

Make trusted-proxy + password work as complementary channels serving different client types, rather than mutually exclusive modes:

• From trusted proxy IP → proxy header auth only (existing behavior, unchanged)
• From loopback / non-proxy → password auth (new fallback path)

Changes

1. src/gateway/auth.ts — authorizeGatewayConnectCore

After the trusted-proxy path fails (untrusted source, loopback, missing header), attempt password verification if both the client and config provide one. The proxy path is tried first and remains preferred; password is only a second channel for local clients.

// Trusted-proxy path failed — attempt password fallback for local clients
if (auth.password && connectAuth?.password) {
  if (safeEqualSecret(connectAuth.password, auth.password)) {
    limiter?.reset(ip, rateLimitScope);
    return { ok: true, method: "password" };
  }
  limiter?.recordFailure(ip, rateLimitScope);
  return { ok: false, reason: "password_mismatch" };
}

2. src/gateway/call.ts — localAuthModeAllowsGatewaySecretInputPath

Allow password (but not token) secret input resolution for trusted-proxy mode. Token remains mutually exclusive with trusted-proxy; password does not.

if (authMode === "trusted-proxy") {
  return !isTokenGatewaySecretInputPath(path);
}

3. src/gateway/credential-planner.ts — passwordCanWin

Add authMode === "trusted-proxy" to the passwordCanWin condition so the credential planner considers password a viable credential.

4. src/gateway/credentials.ts — localPasswordCanWin

Add params.plan.authMode === "trusted-proxy" to the localPasswordCanWin condition so local password resolution is allowed.

Security Properties Preserved

Test Coverage

• 7 new tests in auth.test.ts: password accepted from loopback, password accepted from untrusted source, wrong password rejected, no client password rejected, no gateway password rejected, trusted-proxy identity still preferred over password
• 2 updated tests in call.test.ts: split it.each(["none", "trusted-proxy"]) into separate cases — none still ignores password, trusted-proxy now resolves it
• 1 updated test in credentials.test.ts: trusted-proxy with unresolved password ref now throws instead of silently returning undefined

All 168 tests across auth.test.ts, call.test.ts, credentials.test.ts, and connection-auth.test.ts pass.

Closes #17761, #26007, #43300.