Gateway: fail closed unresolved local auth SecretRefs by joshavant · Pull Request #42672 · openclaw/openclaw

joshavant · 2026-03-11T02:09:06Z

Summary

This PR fixes a fail-open credential precedence bug in local gateway mode and aligns related docs. Thanks to tdjackey for reporting.

Before this change, when gateway.mode="local" and local auth (gateway.auth.token / gateway.auth.password) was explicitly configured as a SecretRef but unresolved, resolver paths could silently fall back to gateway.remote.* credentials.

After this change, unresolved active local auth SecretRefs fail closed instead of being masked by remote fallback credentials.

Root cause

In local mode credential resolution, local and remote values were merged before unresolved-local SecretRef checks were enforced. That allowed a truthy remote fallback to satisfy the resolved credential and bypass the local SecretRef failure path.

What changed

Credential resolution

src/gateway/credentials.ts
- Local-mode resolution now enforces unresolved active local SecretRef checks before any remote fallback can satisfy auth.
- This prevents gateway.remote.* from masking unresolved gateway.auth.* SecretRefs in local mode.

Regression tests

src/gateway/credentials.test.ts
- Added token/password fail-closed tests for unresolved local SecretRef + present remote fallback.
src/gateway/connection-auth.test.ts
- Added async + sync wrapper tests for the same fail-closed behavior.
src/gateway/call.test.ts
- Added command-path test proving unresolved local token SecretRef rejects even when remote token is resolvable.
src/node-host/runner.credentials.test.ts
- Existing local-mode node-host behavior remained green (does not inherit gateway.remote.* in local mode).

Docs alignment

Clarified fallback and fail-closed semantics in:
- docs/gateway/remote.md
- docs/gateway/configuration-reference.md
- docs/gateway/security/index.md
- docs/help/faq.md
- docs/cli/acp.md
- docs/channels/discord.md
Corrected node-host-specific precedence drift:
- docs/cli/node.md
- docs/nodes/index.md
- docs/cli/index.md
Minor clarity/format cleanup:
- docs/gateway/secrets.md

Validation

Targeted tests:
- OPENCLAW_TEST_PROFILE=low OPENCLAW_TEST_SERIAL_GATEWAY=1 pnpm test src/gateway/credentials.test.ts src/gateway/connection-auth.test.ts src/gateway/call.test.ts src/node-host/runner.credentials.test.ts
PoC-equivalent behavior was manually validated post-fix:
- local mode + unresolved gateway.auth.token SecretRef + configured gateway.remote.token now throws GatewaySecretRefUnavailableError for gateway.auth.token.

Notes

No CI workflow lanes were added.
Changes are scoped to auth resolution, tests, and docs.

greptile-apps · 2026-03-11T02:15:35Z

Greptile Summary

This PR adds regression test coverage and documentation alignment for the fail-closed unresolved local auth SecretRef behavior. When gateway.mode="local" and a local auth field (gateway.auth.token / gateway.auth.password) is configured as a SecretRef but cannot be resolved, credential resolution now throws GatewaySecretRefUnavailableError instead of silently falling through to gateway.remote.* credentials.

Key changes:

New unit tests in credentials.test.ts confirm resolveGatewayCredentialsFromConfig throws for both unresolved token and password local SecretRefs when a remote fallback is present
New tests in connection-auth.test.ts cover both the async (resolveGatewayConnectionAuth) and sync (resolveGatewayConnectionAuthFromConfig) wrappers under the same scenario
New integration test in call.test.ts verifies the full callGateway call path rejects with the correct error
Documentation across docs/gateway/, docs/cli/, docs/channels/, docs/help/, and docs/nodes/ is updated to reflect the fail-closed semantic and the node-host local-mode exception (node-host intentionally ignores gateway.remote.* in local mode)
Minor formatting fix in docs/gateway/secrets.md corrects nested list indentation

The implementation fix was already applied in the base branch; this PR provides test coverage and doc alignment. One test isolation issue exists in call.test.ts where an environment variable set in one test is not properly cleaned up.

Confidence Score: 3/5

PR is safe to merge but contains a test isolation bug that could cause flaky tests in future runs.
Changes are tests and docs only (the implementation fix was already in the base branch). The tests are logically correct and cover the intended fail-closed scenarios. However, there is one actionable issue: src/gateway/call.test.ts has an env var isolation gap where LOCAL_REMOTE_FALLBACK_TOKEN is set but not cleaned up properly, which could leak state to subsequent tests in the same run. This doesn't block merge but should be fixed to prevent test flakiness.
src/gateway/call.test.ts — env var isolation in test at line 816

_{Last reviewed commit: 7275a0e}

src/gateway/call.test.ts

* Gateway: fail closed unresolved local auth SecretRefs * Docs: align node-host gateway auth precedence * CI: resolve rebase breakages in checks lanes * Tests: isolate LOCAL_REMOTE_FALLBACK_TOKEN env state * Gateway: remove stale remote.enabled auth-surface semantics * Changelog: note gateway SecretRef fail-closed fix

* Gateway: fail closed unresolved local auth SecretRefs * Docs: align node-host gateway auth precedence * CI: resolve rebase breakages in checks lanes * Tests: isolate LOCAL_REMOTE_FALLBACK_TOKEN env state * Gateway: remove stale remote.enabled auth-surface semantics * Changelog: note gateway SecretRef fail-closed fix (cherry picked from commit 0125ce1)

* Gateway: fail closed unresolved local auth SecretRefs * Docs: align node-host gateway auth precedence * CI: resolve rebase breakages in checks lanes * Tests: isolate LOCAL_REMOTE_FALLBACK_TOKEN env state * Gateway: remove stale remote.enabled auth-surface semantics * Changelog: note gateway SecretRef fail-closed fix

* Gateway: fail closed unresolved local auth SecretRefs * Docs: align node-host gateway auth precedence * CI: resolve rebase breakages in checks lanes * Tests: isolate LOCAL_REMOTE_FALLBACK_TOKEN env state * Gateway: remove stale remote.enabled auth-surface semantics * Changelog: note gateway SecretRef fail-closed fix (cherry picked from commit 0125ce1)

(cherry picked from commit 0125ce1)

@joshavant

* Gateway: fail closed unresolved local auth SecretRefs (openclaw#42672) (cherry picked from commit 0125ce1) * Infra: block GIT_EXEC_PATH in host env sanitizer (openclaw#43685) (cherry picked from commit 1dcef7b) * fix: preserve talk provider and speaking state (cherry picked from commit 2afd657) * fix(review): preserve talk directive overrides (cherry picked from commit 47e412b) * fix(review): address talk cleanup feedback (cherry picked from commit 4a0341e) * feat(ios): refresh home canvas toolbar (cherry picked from commit 6bcf89b) * Refactor: trim duplicate gateway/onboarding helpers and dead utils (openclaw#43871) (cherry picked from commit 7c889e7) * fix(gateway): harden token fallback/reconnect behavior and docs (openclaw#42507) * fix(gateway): harden token fallback and auth reconnect handling * docs(gateway): clarify auth retry and token-drift recovery * fix(gateway): tighten auth reconnect gating across clients * fix: harden gateway token retry (openclaw#42507) (thanks @joshavant) # Conflicts: # CHANGELOG.md # package.json # src/gateway/client.test.ts # src/gateway/client.ts # src/gateway/server.auth.compat-baseline.test.ts # src/gateway/server/ws-connection/message-handler.ts # ui/src/ui/gateway.node.test.ts * build: bump openclaw to 2026.3.11-beta.1 (cherry picked from commit b125c3b) * build: sync versions to 2026.3.11 (cherry picked from commit ce5dd74) * build(android): add play and third-party release flavors (cherry picked from commit ecec0d5) * build: upload Android native debug symbols (cherry picked from commit 1f9cc64) * build(android): add auto-bump signed aab release script (cherry picked from commit 3fb6292) * build(android): update Gradle tooling (cherry picked from commit 4c60956) * docs: update 2026.3.11 release examples (cherry picked from commit 9648570) * fix(ios): make pairing instructions generic (cherry picked from commit c2e41c5) * build(android): strip unused dnsjava resolver service before R8 (cherry picked from commit f1d9fcd) * build: shrink Android app release bundle (cherry picked from commit f251e7e) * fix: resolve type errors from cherry-pick conflicts - Replace OpenClawConfig → RemoteClawConfig in onboarding helpers and call tests - Add missing vi import and fetchTalkSpeak helper in talk-config test - Fix speechProviders → ttsProviders type alignment --------- Co-authored-by: Josh Avant <[email protected]> Co-authored-by: Vincent Koc <[email protected]> Co-authored-by: Ayaan Zaidi <[email protected]> Co-authored-by: Nimrod Gutman <[email protected]> Co-authored-by: Peter Steinberger <[email protected]> Co-authored-by: Ayaan Zaidi <[email protected]> Co-authored-by: Ayaan Zaidi <[email protected]> Co-authored-by: Nimrod Gutman <[email protected]>

openclaw-barnacle bot added docs Improvements or additions to documentation channel: discord Channel integration: discord gateway Gateway runtime size: S maintainer Maintainer-authored PR labels Mar 11, 2026

greptile-apps bot reviewed Mar 11, 2026

View reviewed changes

src/gateway/call.test.ts Show resolved Hide resolved

openclaw-barnacle bot added app: macos App: macos cli CLI command changes size: M and removed size: S labels Mar 11, 2026

joshavant added 4 commits March 10, 2026 21:22

Gateway: fail closed unresolved local auth SecretRefs

65e6384

Docs: align node-host gateway auth precedence

53b7fe6

CI: resolve rebase breakages in checks lanes

6c164e8

Tests: isolate LOCAL_REMOTE_FALLBACK_TOKEN env state

d66d189

joshavant force-pushed the fix/local-secretref-fail-closed branch from e7b9897 to d66d189 Compare March 11, 2026 02:26

joshavant added 3 commits March 10, 2026 21:32

Gateway: remove stale remote.enabled auth-surface semantics

1304770

Changelog: note gateway SecretRef fail-closed fix

38399b7

Merge branch 'main' into fix/local-secretref-fail-closed

431ea8e

joshavant merged commit 0125ce1 into main Mar 11, 2026
6 checks passed

joshavant deleted the fix/local-secretref-fail-closed branch March 11, 2026 02:41

openclaw-barnacle bot removed the cli CLI command changes label Mar 11, 2026

github-actions bot mentioned this pull request Mar 11, 2026

📡 Upstream Digest — 2026-03-11 04:02 UTC curtismercier/openclaw-mods#232

Open

github-actions bot mentioned this pull request Mar 12, 2026

上游更新: v2026.3.11 — 14 P0 + 32 P1 待合并 jiulingyun/openclaw-cn#499

Open

This was referenced Mar 22, 2026

Cherry-pick: Security vulnerability fixes (18 commits) remoteclaw/remoteclaw#1823

Closed

Cherry-pick: SecretRef hardening chain (5 commits) remoteclaw/remoteclaw#1827

Closed

alexey-pelykh mentioned this pull request Mar 23, 2026

Cherry-pick batch: Security vulnerability fixes (18 commits) remoteclaw/remoteclaw#1845

Merged

This was referenced Mar 23, 2026

Cherry-pick batch: SecretRef hardening chain (5 commits) remoteclaw/remoteclaw#1850

Merged

Cherry-pick: Native app updates (24 commits) remoteclaw/remoteclaw#1912

Closed

alexey-pelykh pushed a commit to remoteclaw/remoteclaw that referenced this pull request Mar 27, 2026

Gateway: fail closed unresolved local auth SecretRefs (openclaw#42672)

2302d1f

(cherry picked from commit 0125ce1)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Gateway: fail closed unresolved local auth SecretRefs#42672

Gateway: fail closed unresolved local auth SecretRefs#42672
joshavant merged 7 commits intomainfrom
fix/local-secretref-fail-closed

joshavant commented Mar 11, 2026 •

edited

Loading

Uh oh!

greptile-apps bot commented Mar 11, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

joshavant commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root cause

What changed

Credential resolution

Regression tests

Docs alignment

Validation

Notes

Uh oh!

greptile-apps bot commented Mar 11, 2026

Greptile Summary

Confidence Score: 3/5

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

joshavant commented Mar 11, 2026 •

edited

Loading