fix(gateway): classify loopback shared-secret clients as local for pairing

[SARAMALI15792]

Summary

• Problem: Internal tools (node-host cron scheduler, TUI, gateway-client backend) connecting from loopback with valid shared-secret auth are classified as remote by resolvePairingLocality(), causing close(1008, "pairing required") on scope-upgrade with no recovery path.
• Why it matters: Users cannot use internal tools that require scope upgrades — the gateway silently kills the connection and no approval UI exists for scope-upgrade.
• What changed: Added new PairingLocalityKind variant "shared_secret_loopback_local" with gate function isSharedSecretLoopbackLocalEquivalent in handshake-auth-helpers.ts. Any loopback-origin connection with valid shared-secret (token/password), no proxy headers, and no browser origin header now classifies as local for pairing purposes.
• What did NOT change (scope boundary): No changes to message-handler.ts, error messages, pending persistence, Control UI, or silent-pairing policy. shouldAllowSilentLocalPairing already uses locality !== "remote" — the new kind passes automatically.

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 Internal tool (cron) misidentified as remote client, causing unresolvable 'pairing required' on scope-upgrade #69397
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: resolvePairingLocality() only recognized three local shapes: direct_local, browser_container_local (Control UI), and cli_container_local (CLI clients). Internal tools using NODE_HOST, GATEWAY_CLIENT, or TUI client IDs fell through to "remote" despite connecting from loopback with valid shared-secret auth.
• Missing detection / guardrail: No catch-all gate for loopback + shared-secret clients beyond CLI and Control UI.
• Contributing context: The gate functions were designed when only CLI and Control UI needed loopback classification. As internal tools (cron scheduler, TUI) were added, they inherited the remote fallback.

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: src/gateway/server/ws-connection/handshake-auth-helpers.test.ts
• Scenario the test should lock in: NODE_HOST client + loopback + token auth → "shared_secret_loopback_local" (not "remote")
• Why this is the smallest reliable guardrail: The gate function is pure logic with no I/O — unit tests cover all decision paths exhaustively.
• Existing test that already covers this: None existed. Added 4 new tests + updated 1 existing test.

User-visible / Behavior Changes

• Internal tools (node-host cron, TUI, gateway-client backend) connecting from loopback with valid token/password auth will now silently auto-approve scope-upgrade, role-upgrade, and not-paired pairing requests instead of being disconnected with 1008 "pairing required".

Diagram (if applicable)

Before:
[node-host loopback+token] -> resolvePairingLocality -> "remote" -> close(1008, "pairing required")

After:
[node-host loopback+token] -> resolvePairingLocality -> "shared_secret_loopback_local" -> silent pairing approved

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 — locality only affects the approval path, not authentication. Connections must still pass sharedAuthOk before locality is evaluated.

Repro + Verification

Environment

• OS: Windows 11
• Runtime/container: Node.js via pnpm
• Model/provider: N/A (gateway infrastructure)
• Integration/channel: N/A

Steps

1. Start gateway with token auth configured
2. Connect node-host runner from loopback (127.0.0.1) with valid token
3. Trigger scope-upgrade on the connection

Expected

• Connection silently auto-approves scope-upgrade (same as CLI clients)

Actual

• Before fix: Connection closed with 1008 "pairing required"
• After fix: Scope-upgrade silently approved

Evidence

• Failing test/log before + passing after
• 19/19 unit tests pass including:
  • classifies non-CLI loopback + shared-secret clients as shared_secret_loopback_local
  • keeps non-CLI loopback clients remote without shared-secret auth (5 negative cases)
  • allows silent scope-upgrade for shared_secret_loopback_local
  • prefers cli_container_local over shared_secret_loopback_local for CLI clients

Human Verification (required)

• Verified scenarios: All 19 unit tests pass (vitest verbose). Type safety confirmed via successful test compilation. Spec compliance review + code quality review both approved.
• Edge cases checked: Non-loopback remote (192.168.1.10 → remote), proxy headers (→ remote), browser origin (→ remote), device-token auth (→ remote), sharedAuthOk=false (→ remote), CLI precedence preserved.
• What you did not verify: Full pnpm check / pnpm build (OOM on local machine — CI will validate). E2E with live gateway connection.

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

Risks and Mitigations

• Risk: Broadening locality classification could silently upgrade scopes for clients that previously failed.
  • Mitigation: Gate requires all 5 conditions simultaneously: sharedAuthOk + shared-secret auth method (token/password) + no proxy headers + no browser origin + loopback address + private/loopback host. Remote attackers cannot satisfy these conditions. The existing reason allowlist (not-paired, scope-upgrade, role-upgrade only — not metadata) is preserved unchanged.

[greptile-apps]

Greptile Summary

This PR adds a new "shared_secret_loopback_local" PairingLocalityKind and a corresponding gate function isSharedSecretLoopbackLocalEquivalent so that non-CLI internal tools (NODE_HOST, TUI, GATEWAY_CLIENT) connecting from loopback with valid token/password auth are no longer classified as "remote" and disconnected with 1008 "pairing required". The new gate is a clean, pure-logic extension evaluated after the existing CLI and Control UI gates, and shouldAllowSilentLocalPairing already handles it correctly via locality !== "remote" without any changes needed there.

Confidence Score: 5/5

Safe to merge — the fix is correctly scoped, the gate requires prior sharedAuthOk authentication, and 19 unit tests cover all decision paths including negative cases.

The implementation is a minimal, well-understood extension to an existing pattern. The new gate function mirrors isCliContainerLocalEquivalent minus the CLI client ID check, all five security conditions are preserved, ordering in resolvePairingLocality is correct, and the tests cover the positive path, five negative cases, silent-pairing behavior, and CLI precedence. No P0/P1 findings.

No files require special attention.

_{Reviews (1): Last reviewed commit: "test(gateway): assert cli_container_loca..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 23b26be731

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Handle scope-upgrade for shared_secret_loopback_local

Returning "shared_secret_loopback_local" here does not actually unblock the scope-upgrade case this commit targets: in src/gateway/server/ws-connection/message-handler.ts:937-940, requestDevicePairing is still forced to silent: false whenever reason === "scope-upgrade", so these loopback shared-secret clients will still get pairing required and disconnect on scope upgrades. This means NODE_HOST/TUI scope-upgrade flows remain broken despite the new locality classification.

Useful? React with 👍 / 👎.

[SARAMALI15792]

P1: Handle scope-upgrade for shared_secret_loopback_local

Good catch on the scope-upgrade path — but this is pre-existing behavior that also affects cli_container_local clients, not a regression introduced by this PR.

At message-handler.ts:937-940:

silent: reason === "scope-upgrade" ? false : allowSilentLocalPairing || allowSilentBootstrapPairing

This hardcodes silent: false for all scope-upgrades regardless of locality — including CLI clients already classified as cli_container_local. The scope-upgrade silent bypass was never working for any local client type.

What this PR does fix for NODE_HOST/TUI/GATEWAY_CLIENT:

• not-paired — first-time pairing now silently auto-approves (previously got 1008 because shouldAllowSilentLocalPairing returned false for "remote" locality)
• role-upgrade — silently auto-approves (previously got 1008)
• scope-upgrade — pairing request is now correctly created as pending instead of the connection being closed before even reaching requestDevicePairing (because the remote locality caused the early-exit path)

The scope-upgrade silent override in message-handler.ts is a separate, pre-existing design decision that affects all local clients equally. Changing that is out of scope for this PR (noted in the design spec's Non-Goals). If maintainers want scope-upgrade to also silently auto-approve for local clients, that's a follow-up change to message-handler.ts.

[lovee-dev]

Makes sense — loopback + shared-secret should be treated as local regardless of how resolvePairingLocation classifies the connection origin. The bug would manifest as the TUI or node-host cron getting remote treatment and potentially hitting pairing rate limits meant for external clients. Does the fix also apply when the gateway is behind a reverse proxy and loopback traffic gets rewritten before reaching the handler?

[SARAMALI15792]

Does the fix also apply when the gateway is behind a reverse proxy and loopback traffic gets rewritten before reaching the handler?

Good question — no, by design. The gate function isSharedSecretLoopbackLocalEquivalent requires all five conditions simultaneously:

return (
  params.sharedAuthOk &&
  usesSharedSecretAuth &&
  !params.hasProxyHeaders &&           // ← Rejects if X-Forwarded-For present
  !params.hasBrowserOriginHeader &&
  isLoopbackAddress(params.remoteAddress) &&  // ← Requires 127.0.0.1/::1
  isPrivateOrLoopbackHost(resolveHostName(params.requestHost))
);

If a reverse proxy rewrites the connection:

• hasProxyHeaders becomes true (X-Forwarded-For, X-Real-IP detected)
• remoteAddress shows the proxy's IP, not 127.0.0.1
• Both conditions fail → gate returns false → locality stays "remote"

This is intentional security: proxy headers indicate the connection didn't originate directly from loopback. A remote attacker behind a proxy shouldn't get local-trust classification just by sending a valid token.

---

For legitimate internal tools behind a reverse proxy:

The correct setup is:

1. Configure the proxy to not add forwarding headers for loopback origins, OR
2. Have internal tools connect directly to the gateway's loopback interface (bypassing the proxy)

Docker-compose / container networking case:

If you have:

services:
  gateway:
    ports: ["18789:18789"]
  node-host:
    # connects via service name

And node-host connects to http://gateway:18789 (not http://127.0.0.1:18789):

• remoteAddress = container bridge IP (e.g., 172.17.0.3), not 127.0.0.1
• isLoopbackAddress(remoteAddress) returns false
• Gate rejects → locality stays "remote"

Solution: Have internal tools connect to http://127.0.0.1:18789 instead of the service name. This requires either:

1. network_mode: host for the internal tool container, OR
2. Publishing the gateway port and having the tool connect via the host's loopback interface

This matches existing behavior for cli_container_local — the CLI also needs loopback connection to get local classification. The gate checks the actual network path, not just "are these containers on the same host."

[steipete]

Landed after maintainer review and rebase.

• Gate: pnpm test src/gateway/server/ws-connection/handshake-auth-helpers.test.ts; pnpm check:changed; GitHub CI green
• Source SHA: 0dcc08c
• Merge SHA: 18269f0

Thanks @SARAMALI15792!