#21100: Security/Gateway: require explicit break-glass env for Control UI bypass flags
gateway
size: M
This PR reopens the gateway hardening change from the previously closed PR after branch-name cleanup.
Summary:
- Enforce explicit break-glass env for Control UI bypass flags.
- Add runtime/config tests and e2e coverage for the guard.
- Include current CI-compatible test typing fix required by `pnpm check`.
Replaces: #21059
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR adds a security hardening change that requires an explicit break-glass environment variable (`OPENCLAW_UNSAFE_ALLOW_CONTROL_UI_BYPASS=1`) to enable Control UI bypass flags (`gateway.controlUi.allowInsecureAuth` and `gateway.controlUi.dangerouslyDisableDeviceAuth`). The gateway will now fail at startup if these flags are set without the environment variable.
Key changes:
- Added startup validation in `src/gateway/server-runtime-config.ts:109-119` that enforces the break-glass requirement
- Updated config help text for both bypass flags to document the new requirement
- Added comprehensive test coverage in runtime config tests (2 new tests)
- Wrapped existing e2e tests that use bypass flags with `withEnvAsync` to set the required env var
- Included a typing fix for the CLI test suite (`runDaemonInstall` mock) to resolve `pnpm check` failures
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk - it adds a security hardening measure with comprehensive test coverage
- The change enforces a security guard that prevents accidental use of insecure Control UI bypass flags. The implementation is clean, follows existing patterns (`isTruthyEnvValue`), has thorough test coverage at both unit and e2e levels, and includes proper documentation updates. The typing fix is a straightforward addition of a missing mock declaration.
- No files require special attention
<sub>Last reviewed commit: 739736f</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#23364: Gateway: add risk-ack interlock for dangerous Control UI flags
by bmendonca3 · 2026-02-22
88.7%
#21120: Security/Gateway: guard dangerous HTTP /tools/invoke re-enables
by bmendonca3 · 2026-02-19
85.0%
#21326: Security/UI: harden Control UI gatewayUrl URL overrides
by bmendonca3 · 2026-02-19
81.6%
#23361: Gateway: reject scope assertions without identity binding
by bmendonca3 · 2026-02-22
81.1%
#20089: fix(gateway): preserve control-ui scopes when dangerouslyDisableDev...
by vashkartik · 2026-02-18
80.8%
#23355: Gateway: fail closed on untrusted proxy headers
by bmendonca3 · 2026-02-22
80.1%
#23465: Gateway: strengthen Control UI security headers
by bmendonca3 · 2026-02-22
79.5%
#21186: fix(gateway): strict loopback guard for Control UI (v2)
by dinakars777 · 2026-02-19
79.3%
#21119: Security/Browser: fail closed when control server has no auth
by bmendonca3 · 2026-02-19
79.2%
#23780: Gateway: fail closed on insecure state directory permissions
by bmendonca3 · 2026-02-22
79.2%