Support configurable trusted setup/control UI origins for remote access

[jamesachurchill]

Summary

ClawBox should provide a supported way to add operator-approved remote setup/control UI origins, such as VPN or MagicDNS hostnames, without hard-coding local hostnames in generated gateway config.

Problem

The setup/control UI needs a strict allowed-origin boundary, but real deployments may legitimately access the device through more than the default LAN names/IPs. Examples include VPN overlay DNS names, stable local DNS names, or deployment-specific HTTPS origins.

Without a supported configuration hook, operators are pushed toward local patches to generated or pre-start-managed allowed-origin lists. Those local patches are fragile across updates and can drift from upstream behavior.

Proposed shape

• Add a documented config key for extra trusted setup/control UI origins.
• Validate entries as full origins, not arbitrary strings.
• Merge configured extra origins with the existing default local/LAN origins.
• Keep defaults conservative; do not add broad wildcard origins.
• Surface invalid configured origins clearly during pre-start or setup status checks.

Acceptance criteria

• Operators can add a specific trusted origin through supported config.
• Invalid origins are rejected or reported clearly.
• Generated gateway/control UI config includes configured extra origins.
• The implementation does not require source patches for deployment-specific hostnames.
• Tests cover valid origin, invalid origin, and default behavior.

Security note

This should remain an explicit allowlist. The goal is to avoid brittle local patches, not to loosen cross-origin restrictions.

[jamesachurchill]

Review: configurable trusted setup/control UI origins

Endorse the direction. Repo review confirms the problem and surfaces two findings that should shape the implementation.

Findings

1. The clobber mechanism is the pre-start replace semantics — the config hook must land there [repo-grounded]

There are already two divergent writers of controlUi.allowedOrigins:

• setControlUiAllowedOrigins() (src/lib/openclaw-config.ts:537) merges — it explicitly preserves existing entries when a hostname rename occurs.
• scripts/gateway-pre-start.sh (~L226) replaces — it compares the on-disk list as a set against its computed list (hostname.local + localhost + 127.0.0.1 + hotspot IPs + enumerated LAN IPs) and overwrites on any difference.

So an operator-added origin survives a rename but is wiped on the next gateway start. Any implementation that doesn't merge the configured extra origins inside the pre-start Python pass will be silently defeated at next boot. This is the root cause of the "local patches to pre-start-managed lists" pressure named in the issue.

2. Tailscale/VPN IP origins are already implicitly allowed; the gap is DNS-name origins [repo-grounded]

The LAN-IP enumeration in pre-start skips only 127.* and 169.254.*, so every IPv4 on every interface — including tailscale0's CGNAT 100.x address, docker bridges, etc. — already becomes an http://<ip> allowed origin. Two implications:

• The user-facing gap is specifically hostname origins (MagicDNS *.ts.net, local DNS names) and https origins.
• The current enumeration is broader than the issue's "keep defaults conservative" goal — it implicitly allowlists any interface that appears. Worth a follow-up decision on whether to scope it (e.g., exclude CGNAT/docker ranges once explicit config exists), but that should not block this issue.

3. There is a second, independent allowlist in the Next proxy layer [repo-grounded]

src/lib/gateway-proxy.ts maintains its own ALLOWED_HOSTS env allowlist (default clawbox.local,10.42.0.1,10.43.0.1,localhost) plus system-mDNS and raw-IPv4 reflection. A remote DNS hostname fails isReflectableHost() and falls back to a CANONICAL_ORIGIN redirect. If extra origins only reach the gateway config, remote-hostname users get inconsistent redirect behavior from the proxy. The configured origins' hosts should feed both layers from one source of truth.

Recommended shape

• Config surface: follow the established hostname.env precedent (data/hostname.env, written 0600 by a setup-api route, parsed-not-sourced by pre-start). A data/extra-origins file, one origin per line, keeps the same trust and parsing model. [reviewer judgment]
• Validation (in the pre-start Python pass): accept only scheme://host[:port] with scheme ∈ {http, https}; reject wildcards, paths, query/fragment, userinfo, and empty hosts; lowercase-normalize before the set comparison so idempotency isn't broken by case differences.
• Failure mode: invalid entries should be skipped and logged (journal for the gateway unit), never fail the boot — fail-open on boot, fail-closed on the origin itself. Surfacing rejected entries via setup-api/setup/status (or gateway health) satisfies the "reported clearly" acceptance criterion.
• Proxy layer: derive extra hostnames for isReflectableHost() from the same file (read at module init like the existing config path handling), rather than asking operators to also maintain ALLOWED_HOSTS env in the service unit.
• Tests: src/tests/unit/gateway-pre-start-token.test.ts is the existing precedent for unit-testing the pre-start Python. Add: valid origin merged; invalid origin skipped + reported; file absent → current defaults exactly; idempotency (no config rewrite when merged set already matches).

Acceptance-criteria mapping

Criterion	Covered by
Add origin via supported config	data/extra-origins file + pre-start merge
Invalid origins rejected/reported	Python validation + journal + setup status
Generated config includes extras	Merge inside pre-start replace path (finding 1)
No source patches needed	Both gateway config and proxy layers read the file
Tests	Extend pre-start unit test suite

One scoping note: gateway.bind already accepts tailnet as a valid value in pre-start's normalization list, so upstream has tailnet awareness — worth checking whether upstream OpenClaw grows first-class extra-origin config that ClawBox could pass through instead of owning the merge logic long-term. [reviewer judgment]

[KrasimirKralev]

Triage: enhancement, legitimate remote-access need (VPN/Tailscale/MagicDNS hostnames). Note the constraint: gateway-pre-start.sh rewrites controlUi.allowedOrigins on every gateway start, so any operator-approved origins must live in a config the rewrite merges rather than replaces (e.g. an extraAllowedOrigins the pre-start script unions in). ALLOWED_HOSTS in .env covers the web-app side but not the gateway allowlist.

[KrasimirKralev]

Verified against the code — VALID. gateway-pre-start.sh computes allowedOrigins from a fixed set ({hostname}.local, localhost, AP IPs, live LAN IPs) and replaces the array on every gateway start whenever the sets differ — any operator-added origin is dropped on the next boot. There is no persistence hook: ALLOWED_HOSTS only affects web-app host reflection (gateway-proxy.ts), PORTAL_EMBED_ORIGINS is CSP frame-ancestors only, and even the union-preserving setControlUiAllowedOrigins() (used by the hostname-rename route) gets clobbered by the pre-start rewrite.

One nuance: Control-UI WebSocket remote access already works regardless — production-server.js rewrites the upgrade Origin to 127.0.0.1 for all proxied connections. So the gap is specifically a supported, validated, update-surviving extra-origins config.

Suggested fix shape: an extraAllowedOrigins list (config-store or openclaw.json key the pre-start script treats as union input, with origin-format validation), so operator entries survive every rewrite.