PR #55448: fix(gateway): resolve env-backed SecretRef in restart drift-check (#55029)

• Repository: openclaw/openclaw
• Author: MoerAI
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/55448

Description (problem / solution / changelog)

Summary

openclaw gateway restart fails to verify token drift when gateway.auth.token is configured as a SecretRef with env provider, even though the referenced env var is available in the shell.

Root Cause

resolveGatewayTokenForDriftCheck called the drift credential resolver in a way that treated all unresolved SecretRef as unavailable, ignoring the env input entirely. The error message "gateway.auth.token SecretRef is configured but unavailable in this command path" was always emitted for env-backed tokens.

Changes

• src/cli/daemon-cli/gateway-token-drift.ts: Added safe sync fallback for env-sourced SecretRef — when the credential resolver throws GatewaySecretRefUnavailableError, we parse the configured token ref, verify it's env-sourced, honor provider allowlist, and read from current command env
• src/gateway/credentials.ts: Threaded optional env parameter into drift credentials API for consistent caller env usage
• src/cli/daemon-cli/gateway-token-drift.test.ts: Updated regression test to verify env-backed SecretRef now resolves from caller env

Test

• pnpm test -- src/cli/daemon-cli/gateway-token-drift.test.ts passed
• pnpm test -- src/cli/daemon-cli/lifecycle-core.test.ts passed
• pnpm test -- src/gateway/credentials.test.ts passed
• LSP diagnostics clean on all changed files

Closes #55029

Changed files

• src/cli/daemon-cli/gateway-token-drift.test.ts (modified, +19/-19)
• src/cli/daemon-cli/gateway-token-drift.ts (modified, +47/-3)
• src/gateway/credentials.ts (modified, +2/-1)

PR #58141: Secrets: hard-fail unsupported SecretRef policy and fix gateway restart token drift

• Repository: openclaw/openclaw
• Author: joshavant
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/58141

Description (problem / solution / changelog)

Summary

• Problem: Gateway service restart drift checks produced false-positive token drift/unavailable warnings when gateway.auth.token used SecretRef, and unsupported runtime-mutable SecretRef surfaces were not consistently hard-failed early.
• Why it matters: operators saw noisy or misleading drift warnings, and invalid SecretRef policy combinations could survive until later runtime paths.
• What changed: implemented service-env-aware SecretRef drift resolution in restart checks, added explicit unsupported SecretRef policy validation for mutable config/auth surfaces, and enforced OAuth + SecretRef hard-fail in auth-profile runtime resolution paths.
• What did NOT change (scope boundary): this PR does not implement/install-path fixes for gateway install --force file/plist SecretRef handling.

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 #55029
• Closes #57211
• Related #53742
• Related #57261
• Related #55448
• Related #57411
• This PR fixes a bug or regression

C2 Cluster Coverage Matrix

Fully addressed:

• #55029 (restart drift-check cannot verify env-backed SecretRef token)
  • Addressed by service-env-aware token SecretRef resolution in restart drift check.
• #57211 (restart false-positive token drift warning for SecretRef token)
  • Addressed by active-mode-aware token resolution and warning suppression when resolved values match.
• #55448 (open PR in same area)
  • Addressed/superseded by this PR’s restart drift-check fix path and tests.
• #57411 (open PR in same area)
  • Addressed/superseded by this PR’s restart false-positive warning fix path and tests.

Partially addressed:

• #53742
  • Addressed: restart/doctor drift-loop symptom caused by SecretRef drift-check resolution behavior.
  • Not addressed: gateway install --force plaintext projection concern in LaunchAgent plist handling.
• #57261
  • Addressed: drift-check SecretRef resolution behavior during restart evaluation.
  • Not addressed: install-path failure behavior for file-backed gateway.auth.token SecretRef.

Additional post-review blocker fix:

• Parent-path bypass in config set policy hard-fail (setting parent objects like hooks/channels.discord with nested unsupported SecretRef values).
  • Addressed by commit 6316fd3584: removed requested-path gating and now runs unsupported SecretRef policy validation unconditionally on post-mutation config before write.
  • Regression coverage: src/cli/config-cli.test.ts
    • fails early when parent-object writes include unsupported SecretRef objects
    • does not duplicate policy errors in --dry-run --json mode for parent-object writes

Root Cause / Regression History (if applicable)

• Root cause: drift-check token resolution used config-only/empty-env paths that did not mirror actual service runtime env inputs for SecretRef-backed tokens.
• Missing detection / guardrail: no restart-focused tests covered merged service command env + SecretRef token resolution and no early policy gate for unsupported mutable SecretRef paths.
• Prior context (git blame, prior PR, issue, or refactor if known): open bug threads #55029/#57211 and open PRs #55448/#57411 identified the restart drift check path.
• Why this regressed now: SecretRef support expansion outpaced drift-check parity and policy hard-fail coverage for runtime-mutable surfaces.
• If unknown, what was ruled out: N/A.

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/cli/daemon-cli/gateway-token-drift.test.ts
  • src/cli/daemon-cli/lifecycle-core.test.ts
  • src/config/validation.policy.test.ts
  • src/secrets/runtime-auth-profiles-oauth-policy.test.ts
  • src/secrets/runtime.integration.test.ts
• Scenario the test should lock in: restart drift check resolves SecretRef token using service env and avoids false drift warnings; unsupported mutable SecretRef policy fails early; OAuth + SecretRef profile combinations hard-fail in startup/reload/auth resolution.
• Why this is the smallest reliable guardrail: these tests hit the exact drift and policy seams without unrelated end-to-end harness overhead.
• Existing test that already covers this (if any): updated lifecycle/drift tests now cover merged-env restart behavior.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• openclaw gateway restart drift checks now resolve gateway.auth.token SecretRefs with merged service+process env inputs and reduce false-positive drift warnings.
• Drift checks skip config token resolution when gateway.auth.mode disables token auth (password, none, trusted-proxy).
• Unsupported runtime-mutable SecretRef assignments fail early with policy guidance in config validation/config-set paths.
• OAuth-mode auth-profile + SecretRef combinations now hard-fail in runtime/auth resolution paths.

Diagram (if applicable)

Before:
[gateway restart] -> [config token drift check with incomplete env] -> [SecretRef unavailable/false drift warning]

After:
[gateway restart] -> [drift check with merged service env + mode-aware token resolution] -> [accurate drift result]

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): Yes
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation:
  • Risk: stricter policy can reject previously accepted-but-invalid SecretRef configs.
  • Mitigation: deterministic error messages + docs updates clarify supported vs unsupported SecretRef surfaces.

Repro + Verification

Environment

• OS: macOS + Linux test fixtures
• Runtime/container: local Node/Bun test harness
• Model/provider: N/A
• Integration/channel (if any): gateway/daemon CLI and auth-profile runtime paths
• Relevant config (redacted): gateway.auth.token SecretRef via env/file provider, auth profile mode combinations

Steps

1. Configure gateway.auth.token as SecretRef and set service env token source.
2. Run restart/drift-check paths.
3. Attempt unsupported mutable SecretRef assignments and OAuth+SecretRef mode combinations.

Expected

• Accurate/noisy-free drift behavior in restart path for resolvable SecretRef token.
• Early hard-fail for unsupported policy combinations.

Actual

• Matches expected in scoped tests.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Scoped verification command (pass):

• pnpm test -- src/config/validation.policy.test.ts src/cli/config-cli.test.ts src/cli/daemon-cli/gateway-token-drift.test.ts src/cli/daemon-cli/lifecycle-core.test.ts src/agents/auth-profiles/oauth.test.ts src/secrets/runtime-auth-profiles-oauth-policy.test.ts src/secrets/runtime.integration.test.ts src/commands/doctor-gateway-services.test.ts src/secrets/target-registry.test.ts

Human Verification (required)

• Verified scenarios: restart drift-check SecretRef resolution, lifecycle drift warning behavior, unsupported mutable SecretRef validation, OAuth+SecretRef hard-fail behavior, docs/matrix sync.
• Edge cases checked: token mode disabled (password), unresolved active refs, reload keeps last-known-good snapshot.
• What you did not verify: full unrelated repo-wide suite (known unrelated skills/test lane failures remain out of this branch scope).

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/No): Yes (for valid supported configs)
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: stricter policy gating may break previously tolerated but philosophically invalid config shapes.
  • Mitigation: explicit policy errors point to canonical SecretRef surface docs; behavior is intentional hard-fail for unsupported mutable/OAuth combinations.
• Risk: restart drift behavior change could alter warning visibility for edge deployments.
  • Mitigation: added targeted tests for merged env and mode-gated token resolution.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/auth-credential-semantics.md (modified, +7/-0)
• docs/cli/config.md (modified, +7/-0)
• docs/cli/daemon.md (modified, +2/-0)
• docs/cli/gateway.md (modified, +2/-0)
• docs/gateway/authentication.md (modified, +1/-0)
• docs/gateway/configuration-reference.md (modified, +2/-1)
• docs/gateway/secrets.md (modified, +1/-0)
• docs/reference/secretref-credential-surface.md (modified, +7/-4)
• docs/reference/secretref-user-supplied-credentials-matrix.json (modified, +4/-2)
• src/agents/auth-profiles/oauth.test.ts (modified, +20/-0)
• src/agents/auth-profiles/oauth.ts (modified, +7/-0)
• src/agents/auth-profiles/policy.ts (added, +142/-0)
• src/cli/config-cli.test.ts (modified, +177/-0)
• src/cli/config-cli.ts (modified, +54/-6)
• src/cli/daemon-cli/gateway-token-drift.test.ts (modified, +78/-18)
• src/cli/daemon-cli/gateway-token-drift.ts (modified, +53/-5)
• src/cli/daemon-cli/lifecycle-core.test.ts (modified, +67/-1)
• src/cli/daemon-cli/lifecycle-core.ts (modified, +5/-1)
• src/config/validation.policy.test.ts (added, +129/-0)
• src/config/validation.ts (modified, +97/-1)
• src/secrets/credential-matrix.ts (modified, +2/-11)
• src/secrets/runtime-auth-collectors.ts (modified, +7/-0)
• src/secrets/runtime-auth-profiles-oauth-policy.test.ts (added, +74/-0)
• src/secrets/runtime.integration.test.ts (modified, +91/-0)
• src/secrets/unsupported-surface-policy.test.ts (added, +73/-0)
• src/secrets/unsupported-surface-policy.ts (added, +128/-0)