fix(tunnel): register tunnel origin in gateway allowedOrigins on start

[TonyLuo-NV]

Summary

nemoclaw tunnel start starts cloudflared and prints the public *.trycloudflare.com URL, but never registers that origin in gateway.controlUi.allowedOrigins, so every Web UI WebSocket arriving through the tunnel is rejected with "origin not allowed". This PR auto-registers the tunnel's exact origin in the in-sandbox gateway config and restarts the gateway so the Web UI works through the tunnel with no manual configuration.

Related Issue

Fixes #6212

Changes

• New src/lib/tunnel/allowed-origins.ts:
  • tunnelUrlToOrigin / isTryCloudflareOrigin / computeTunnelAllowedOrigins — pure origin-list logic: converts the captured tunnel URL to an exact origin (never a wildcard), prunes stale *.trycloudflare.com origins so the list stays bounded across quick-tunnel restarts, and preserves all other origins (loopback, NEMOCLAW_CORS_ORIGIN, custom domains).
  • registerTunnelOrigin — reads the in-sandbox OpenClaw config via the existing sandbox/config.ts primitives (readSandboxConfig/writeSandboxConfig/recomputeSandboxConfigHash), applies the updated list, and restarts the gateway. Best-effort (a failure warns and never breaks tunnel start), idempotent (no write or restart when the list is unchanged), and skipped for non-OpenClaw agents.
• src/lib/tunnel/services.ts — startAll calls registerTunnelOrigin after the tunnel URL is captured, guarded by the existing SAFE_NAME_RE sandbox-name validation, with a clear warning when no sandbox name is available.
• Tests: 20 unit tests in src/lib/tunnel/allowed-origins.test.ts (origin conversion, prune/preserve, idempotency, agent gating, failure swallowing, sibling-key preservation) and 4 startAll integration tests in src/lib/tunnel/services.test.ts using the existing fake-cloudflared pattern.
• Docs: docs/reference/commands.mdx — documents the automatic origin registration under tunnel start (OpenClaw-only block; agent variants verified in sync).

Design notes:

• Exact origin instead of a *.trycloudflare.com wildcard: a wildcard would accept any trycloudflare tenant's origin (CSWSH exposure); only the URL the user just created is registered.
• Deviation from the internal design doc: the gateway reload uses the managed restartSandboxGateway (mutation-locked, health-probed, hash-verified) rather than a raw kill -HUP 1 container reap — less disruptive and safer.
• Issue nemoclaw start should auto-patch allowedOrigins for the tunnel URL it just created. #1422 was closed by the stale bot, not by a fix; the recovery infrastructure it references was never merged, so this is a first-time gap in the tunnel-start flow rather than a regression.

Type of Change

• Code change with doc updates

Quality Gates

• Tests added or updated for changed behavior
• Docs updated for user-facing behavior changes
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — internal 9-category security review passed (injection, CORS/CSWSH widening, secrets, SSRF, path traversal, parsing, privilege escalation, DoS, supply chain); requesting maintainer review as the merge gate.

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes — pre-commit vitest hook hung under coverage (known flake); Biome check run manually on all changed TS files, typecheck:cli clean
• Targeted tests pass for changed behavior (npx vitest run src/lib/tunnel/ test/cli/tunnel-command.test.ts — 5 files, 88+ tests pass)
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — 0 errors; 2 pre-existing environment warnings (Fern auth + theme contrast), none introduced by this change

Remaining manual verification: end-to-end run on a root-mode sandbox (immutable/hashed config) to confirm the write + hash recompute + gateway restart sequence on real hardware — the reporter's DGX Station environment. All logic is unit/integration tested and reuses the shipped config set write path.

🤖 Generated with Claude Code

Signed-off-by: Tony Luo xialuo@nvidia.com

Summary by CodeRabbit

• New Features
  • Public tunnel startup now automatically registers the tunnel origin with the sandbox gateway when possible (OpenClaw-only).
  • Allowed origins updates now preserve existing non-trycloudflare entries while removing stale quick-tunnel origins.
• Bug Fixes
  • Registration is skipped for unsafe/missing sandbox names and fails gracefully with warnings; tunnel startup output remains resilient.
• Documentation
  • Updated tunnel command reference with clearer behavior around origin injection, pruning, and gateway restarts.
• Tests
  • Added coverage for tunnel origin parsing, allowlist computation, and registration wiring.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3914ea27-ab51-43bc-ac0a-6ca7288f197b

📥 Commits

Reviewing files that changed from the base of the PR and between 7520f2e and 4bf018b.

📒 Files selected for processing (1)

• docs/reference/commands.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/reference/commands.mdx

---

📝 Walkthrough

Walkthrough

Adds tunnel-origin computation and best-effort registration into gateway allowedOrigins after tunnel URL discovery, with OpenClaw-only gating, config reloads when the allowlist changes, tests, and CLI documentation.

Changes

Tunnel origin registration

Layer / File(s)	Summary
Origin parsing and computation helpers src/lib/tunnel/allowed-origins.ts	Adds tunnelUrlToOrigin, isTryCloudflareOrigin, and computeTunnelAllowedOrigins for normalizing and computing the allowed-origins list.
registerTunnelOrigin dependency wiring and config mutation src/lib/tunnel/allowed-origins.ts	Defines RegisterTunnelOriginDeps, resolveDeps, config read/write helpers, and registerTunnelOrigin, which mutates gateway.controlUi.allowedOrigins, recomputes the config hash, and reloads the gateway when changed.
Wire registerTunnelOrigin into startAll src/lib/tunnel/services.ts	Imports registerTunnelOrigin, derives and validates the tunnel-origin sandbox name, and calls registration after tunnelUrl is discovered in startAll, warning on failure or missing sandbox name.
Tests and documentation src/lib/tunnel/allowed-origins.test.ts, src/lib/tunnel/services.test.ts, docs/reference/commands.mdx	Adds unit tests, integration tests for startAll wiring, and documentation describing tunnel-origin registration and gateway restart behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• NVIDIA/NemoClaw#3657: Both PRs modify src/lib/tunnel/services.ts’s tunnel public-URL discovery flow.
• NVIDIA/NemoClaw#4134: Both PRs modify the tunnel startup flow in src/lib/tunnel/services.ts around discovering the public tunnelUrl.

Suggested labels: bug-fix, area: cli, area: docs

Suggested reviewers: ericksoa, cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: registering tunnel origins in gateway allowedOrigins when starting the tunnel.
Linked Issues check	✅ Passed	The PR fulfills #6212 by auto-registering the generated trycloudflare origin, making the Control UI reachable through the tunnel.
Out of Scope Changes check	✅ Passed	The docs, tests, and validation helpers all support the tunnel-origin registration work and do not appear unrelated.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (2)

src/lib/tunnel/allowed-origins.ts (1)

161-168: 🩺 Stability & Availability | 🔵 Trivial | 💤 Low value

Minor contract gap: resolveDeps runs outside the try/catch.

The doc comment states any failure is swallowed so a working tunnel start is never turned into a hard error, but resolveDeps (Line 164) executes before the try (Line 168). If it throws (e.g., a module resolution failure via the require above), the error escapes this function despite the "best-effort" contract. Moving it inside the try makes the contract hold locally without relying on the caller's wrapper.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/tunnel/allowed-origins.ts` around lines 161 - 168, The best-effort
contract in the tunnel origin handling is broken because `resolveDeps` is called
before the `try` in `allowed-origins.ts`, so a resolution failure can still
escape and fail startup. Move the `resolveDeps(deps)` call, along with the
`info` and `warn` extraction, inside the existing `try` block in the
`tunnelUrlToOrigin`/allowed-origins flow so any module resolution error is
swallowed locally as intended.

src/lib/tunnel/services.ts (1)

679-696: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the sandbox-name selection into a helper
resolveDefaultSandboxName already centralizes the env precedence for start/stop, but this tunnel-origin path still repeats the same safe-name filtering inline. A small helper for the tunnel-origin sandbox name would keep the precedence and validation rules in one place without dragging in the registry fallback. The outer try/catch only adds protection for dependency-loading failures before registerTunnelOrigin’s own best-effort handling.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/tunnel/services.ts` around lines 679 - 696, The tunnel-origin path in
services.ts is duplicating sandbox-name selection and validation inline instead
of using a helper. Extract that logic into a small helper near
resolveDefaultSandboxName that applies the same env precedence and
SAFE_NAME_RE/“..” checks for tunnel-origin use, but does not include the
registry fallback. Then update the tunnelUrl block to call the helper and keep
the outer try/catch around registerTunnelOrigin for dependency-loading failures
only.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/tunnel/allowed-origins.ts`:
- Around line 161-168: The best-effort contract in the tunnel origin handling is
broken because `resolveDeps` is called before the `try` in `allowed-origins.ts`,
so a resolution failure can still escape and fail startup. Move the
`resolveDeps(deps)` call, along with the `info` and `warn` extraction, inside
the existing `try` block in the `tunnelUrlToOrigin`/allowed-origins flow so any
module resolution error is swallowed locally as intended.

In `@src/lib/tunnel/services.ts`:
- Around line 679-696: The tunnel-origin path in services.ts is duplicating
sandbox-name selection and validation inline instead of using a helper. Extract
that logic into a small helper near resolveDefaultSandboxName that applies the
same env precedence and SAFE_NAME_RE/“..” checks for tunnel-origin use, but does
not include the registry fallback. Then update the tunnelUrl block to call the
helper and keep the outer try/catch around registerTunnelOrigin for
dependency-loading failures only.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 14175b3f-83fe-47d7-9228-0b7da3c158b3

📥 Commits

Reviewing files that changed from the base of the PR and between a4cd77d and d3cc7ad.

📒 Files selected for processing (5)

• docs/reference/commands.mdx
• src/lib/tunnel/allowed-origins.test.ts
• src/lib/tunnel/allowed-origins.ts
• src/lib/tunnel/services.test.ts
• src/lib/tunnel/services.ts