fix(whatsapp): reconcile post-pair gateway restart without operator.admin

[harjothkhara]

Summary

Fixes #6413 by restarting the running WhatsApp channel after a successful QR login without granting operator.admin to the pairing device.
The bounded restart uses gateway-token authentication only when the login targets the private gateway URL baked into NemoClaw's generated runtime environment.

The original implementation is by @harjothkhara.
The maintainer security follow-up preserves that credit with Co-authored-by: harjoth <harjoth.khara@gmail.com>.

Changes

• Reissues the bounded channels.start RPC after a successful token-less WhatsApp login.
• Bakes a separate readonly gateway URL trust anchor for token-bearing helpers instead of trusting caller-mutable OPENCLAW_GATEWAY_URL or NEMOCLAW_OPENCLAW_GATEWAY_URL values.
• Strips the gateway token from a login to any caller-selected URL and skips the follow-up reconcile.
• Adds the exact regression where a caller spoofs both mutable URL variables and verifies that no token reaches the login or reconcile.
• Uses command-scoped environment assignments so the generated runtime file preserves the fix(openclaw): restore local CLI pairing path #6291 no-ambient-export invariant.
• Preserves login exit status, forwards allowlisted --account values, and downgrades reconcile failures to recovery guidance.
• Documents the OpenClaw-only post-pair restart, trust boundary, custom-URL behavior, and status recovery flow.
• Synchronizes current main without rewriting the contributor's verified commit history.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — the existing QR, runtime-env, gateway-host, permission, and scope-replacement suites remain green.
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — the maintainer follow-up closes the mutable trust-anchor token-exfiltration path and adds an adversarial regression.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set — 73 passed and 3 skipped across the focused runtime, WhatsApp, gateway-host, permission, scope, and token-export coverage.
• Applicable broad gate passed — normal exact-head CI is pending after this push.
• 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) — passed with 0 errors and 2 existing repository warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

Validation performed

• Focused Vitest suites: 73 passed, 3 skipped
• npm run docs:sync-agent-variants
• npm run docs (0 errors; 2 existing warnings)
• npm run test-size:check
• npm run test:titles:check
• npx prek run shfmt --files scripts/nemoclaw-start.sh
• npx prek run shellcheck --files scripts/nemoclaw-start.sh
• npm run check:diff
• Commit and push hooks

AI-assisted: authored and reviewed with Claude Code; adversarially cross-reviewed with Codex.

---

Signed-off-by: harjoth harjoth.khara@gmail.com

Summary by CodeRabbit

• Bug Fixes
  • Improved WhatsApp experimental login to automatically reconcile/restart the WhatsApp channel after successful QR pairing when safe.
  • Added --account / --account=... forwarding to the gateway restart request, with account ID validation and clear guidance on invalid values.
  • Strengthened gateway-token protection: token is only used for the trusted private gateway URL (and stripped for untrusted targets); enhanced recovery guidance when restart/reconciliation can’t run or fails.
• Tests
  • Added end-to-end regression coverage for WhatsApp post-pair restart, parameter forwarding, and recovery/security scenarios.
  • Added a trusted gateway URL read-only alias test.
• Documentation
  • Expanded WhatsApp sandbox channel documentation with verification steps and expected restart/status behavior.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a trusted WhatsApp post-pair restart path to the login guard, with account forwarding, URL-based token gating, host guidance, updated docs, and regression tests covering restart, safety, and failure cases.

Changes

WhatsApp Post-Pair Restart

Layer / File(s)	Summary
Trusted gateway URL anchor scripts/nemoclaw-start.sh	Writes a readonly trusted private gateway URL value into the runtime shell environment.
Gateway token reader and post-pair reconcile function scripts/nemoclaw-start.sh	Reads gateway.auth.token from config and calls channels.start after WhatsApp pairing with accountId validation and fallback guidance on missing token, invalid account, or RPC failure.
Account argument parsing in login wrapper scripts/nemoclaw-start.sh	Initializes login account parsing state and captures --account and --account=* values during channels login.
Trusted gateway URL classification and token gating scripts/nemoclaw-start.sh	Compares the selected gateway URL against the trusted anchor, strips OPENCLAW_GATEWAY_TOKEN for untrusted targets, and runs WhatsApp login with temporary errexit suppression and conditional env injection.
Post-login success branching and guidance scripts/nemoclaw-start.sh, docs/manage-sandboxes/messaging-channels.mdx	Branches after successful WhatsApp login to print no-auto-restart guidance for untrusted targets, skip duplicate reconciliation when token auth already happened, otherwise call the post-pair restart helper, restore set -e, and update the WhatsApp pairing documentation with the new host-side guidance.
Guard extraction and simulated login harness test/repro-6413-whatsapp-postpair-start.test.ts	Adds the reproduction test scaffolding, typed wrapper options/results, a temp bash harness with fake openclaw behavior, and a helper for isolating gateway call log lines.
Regression cases for restart and token safety test/repro-6413-whatsapp-postpair-start.test.ts, test/nemoclaw-start-gateway-ws-host.test.ts	Exercises post-pair restart success, account forwarding and validation, untrusted URL token protection, ambient token stripping, spoofed alias handling, trusted-URL behavior, set -e exit handling, missing-token guidance, restart-failure recovery, and the exported trusted URL in the generated env script.

Estimated code review effort: 4 (Complex) | ~60 minutes

Suggested labels: bug-fix, area: sandbox

Suggested reviewers: brandonpelfrey, ericksoa

🚥 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 summarizes the main fix: WhatsApp post-pair gateway reconciliation without operator.admin.
Linked Issues check	✅ Passed	The PR implements a bounded post-pair restart path with trusted-token gating and recovery guidance, matching #6413 and the security boundary.
Out of Scope Changes check	✅ Passed	The added tests and documentation directly support the WhatsApp restart fix and do not introduce unrelated scope.
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.}

[apurvvkumaria]

I pushed signed commits f207d4a20 and 9a83e4929 after synchronizing current main. The security follow-up preserves @harjothkhara's original implementation and credit through Co-authored-by: harjoth <harjoth.khara@gmail.com>.

The key correction is that token-bearing decisions no longer trust either caller-mutable URL variable. The generated runtime environment now bakes a separate readonly URL anchor, and the regression spoofs both OPENCLAW_GATEWAY_URL and NEMOCLAW_OPENCLAW_GATEWAY_URL while proving the token reaches neither login nor reconcile. I also replaced ambient exports with command-scoped assignments, clearing the branch-specific #6291 guard failure.

Validation completed:

• focused runtime/WhatsApp/security tests: 73 passed, 3 skipped
• shfmt, ShellCheck, Biome, test-size and title checks: passed
• docs variant sync and build: passed (0 errors; 2 existing warnings)
• full scoped pre-commit/pre-push verification: passed
• both maintainer commits are GitHub Verified

@coderabbitai review

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
cd /tmp
gh pr view 6496 --repo NVIDIA/NemoClaw --json title,body,commits,files -q '.' | head -c 3000
echo "---DIFF---"
gh pr diff 6496 --repo NVIDIA/NemoClaw > pr.diff
wc -l pr.diff
sed -n '1,400p' pr.diff

Length of output: 25622

---

🏁 Script executed:

#!/bin/bash
cd /tmp
grep -n "nemoclaw-configure-guard" pr.diff scripts/nemoclaw-start.sh 2>/dev/null | head -50
echo "---"
find . -maxdepth 2 -iname "nemoclaw-start.sh"

Length of output: 540

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail
rm -rf /tmp/repo
git clone --quiet https://github.com/NVIDIA/NemoClaw.git /tmp/repo
cd /tmp/repo
gh pr checkout 6496 --repo NVIDIA/NemoClaw
grep -n "nemoclaw-configure-guard" scripts/nemoclaw-start.sh | head -20

Length of output: 699

---

🏁 Script executed:

#!/bin/bash
cd /tmp/repo
sed -n '3240,3300p' scripts/nemoclaw-start.sh

Length of output: 3683

---

🏁 Script executed:

#!/bin/bash
cd /tmp/repo
sed -n '1,400p' test/repro-6413-whatsapp-postpair-start.test.ts | sed -n '100,400p'

Length of output: 12008

---

This is a solid, well-tested security fix. The core correction addresses a real gap in the previous version: the earlier iteration used the caller-mutable NEMOCLAW_OPENCLAW_GATEWAY_URL alias to decide token trust, which meant a caller could spoof that variable and redirect the token-bearing reconcile to an attacker-controlled URL. This version fixes that by baking a separate _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL as readonly at generation time, so it can't be overridden after the runtime file is sourced.

A few things I verified by pulling the branch and diff:

• The readonly trust anchor is installed inside the generated runtime file (_NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL), guarded by a conditional assignment + builtin readonly, making repeated sourcing idempotent while failing closed if a conflicting value is already readonly.
• The openclaw() wrapper now branches on _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL (not the mutable alias) to decide whether the gateway token may be used for login or the post-pair reconcile, and strips OPENCLAW_GATEWAY_TOKEN for non-trusted targets.
• Login now runs with errexit saved/restored, so exit status and post-login handling are reliable even under a caller's set -e.
• --account / --account=<id> is parsed and allowlisted ([A-Za-z0-9._:-] under LC_ALL=C) before being embedded in the RPC JSON params, avoiding injection.
• The reconcile never fails the login itself — token-missing, invalid-account, and RPC-failure paths all downgrade to stderr guidance and return 0.
• The new test suite (test/repro-6413-whatsapp-postpair-start.test.ts) explicitly covers the adversarial case of spoofing both OPENCLAW_GATEWAY_URL and NEMOCLAW_OPENCLAW_GATEWAY_URL post-sourcing and asserts the token reaches neither the login subprocess nor the reconcile call, plus double-reconcile avoidance, account-id validation, and set -e preservation.

This looks like a meaningful hardening over the prior implementation while preserving the original author's design and intent. I'll trigger a full review pass to double check the diff end-to-end, including the docs and gateway-ws-host test changes.

---

✏️ Learnings added

Learnt from: apurvvkumaria
URL: https://github.com/NVIDIA/NemoClaw/pull/6496

Timestamp: 2026-07-08T21:52:22.408Z
Learning: In scripts/nemoclaw-start.sh, security-relevant trust decisions (e.g., whether the ambient OPENCLAW_GATEWAY_TOKEN may be sent to a gateway URL) must be based on `_NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL`, a `readonly` variable baked into the generated runtime file at sandbox-creation time. The caller-mutable compatibility alias `NEMOCLAW_OPENCLAW_GATEWAY_URL` (and the raw `OPENCLAW_GATEWAY_URL`) must never be used as the trust anchor for token-bearing decisions, since callers can override them after the runtime file is sourced.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

test/nemoclaw-start-gateway-ws-host.test.ts (1)

186-187: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prefer behavioral verification over literal source-text matching.

These assertions check the literal generated shell text rather than the actual runtime effect (that the variable is truly read-only and resolves to the expected value once sourced). Consider sourcing envFile and asserting the resulting env value plus that a reassignment attempt fails, consistent with behavioral testing over implementation-lock-in checks.

♻️ Example behavioral check

-      expect(envFile).toContain("_NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL='ws://10.200.0.2:18790'");
-      expect(envFile).toContain("builtin readonly _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL");
+      const check = spawnSync("bash", ["-c",
+        `source ${JSON.stringify(envFile)}; printf '%s\\n' "$_NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL"; ` +
+        `if _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL=x 2>/dev/null; then exit 1; fi`],
+        { encoding: "utf-8" });
+      expect(check.stdout.trim()).toBe("ws://10.200.0.2:18790");
+      expect(check.status).toBe(0);

Note this mirrors the file's existing assertion style for sibling variables, so this is a minor, deferable improvement rather than a blocking concern.

🤖 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 `@test/nemoclaw-start-gateway-ws-host.test.ts` around lines 186 - 187, The
current assertions in the test rely on matching the generated shell text instead
of verifying behavior, so update the test around the envFile checks to source
the file and assert the resulting _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL value
plus that reassignment is rejected. Reuse the existing sibling-variable testing
style in nemoclaw-start-gateway-ws-host.test.ts, and focus the change near the
envFile expectations for _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL.

Source: Path instructions

🤖 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 `@test/nemoclaw-start-gateway-ws-host.test.ts`:
- Around line 186-187: The current assertions in the test rely on matching the
generated shell text instead of verifying behavior, so update the test around
the envFile checks to source the file and assert the resulting
_NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL value plus that reassignment is rejected.
Reuse the existing sibling-variable testing style in
nemoclaw-start-gateway-ws-host.test.ts, and focus the change near the envFile
expectations for _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3fed4b2d-6a95-4f1c-afbf-b741567031fc

📥 Commits

Reviewing files that changed from the base of the PR and between c5423e8 and 9a83e49.

📒 Files selected for processing (4)

• docs/manage-sandboxes/messaging-channels.mdx
• scripts/nemoclaw-start.sh
• test/nemoclaw-start-gateway-ws-host.test.ts
• test/repro-6413-whatsapp-postpair-start.test.ts

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

• scripts/nemoclaw-start.sh
• test/repro-6413-whatsapp-postpair-start.test.ts

[apurvvkumaria]

Addressed CodeRabbit’s remaining behavioral-test suggestion in signed commit 8df9f738f: the test now sources the generated runtime environment, verifies _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL resolves to the trusted private gateway, and proves reassignment is rejected. The focused gateway-host suite passes 9/9; commit and pre-push hooks passed. Original author @harjothkhara remains credited as co-author.

[harjothkhara]

Thanks @apurvvkumaria. My version trusted NEMOCLAW_OPENCLAW_GATEWAY_URL, but a caller can just set that themselves, so switching to the readonly _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL is the right fix. LGTM.

[cv]

Exact-head security review at 8df9f738f found a fail-closed trust-anchor blocker in scripts/nemoclaw-start.sh:3273-3275.

The generated runtime file says a conflicting preexisting readonly _NEMOCLAW_TRUSTED_OPENCLAW_GATEWAY_URL fails closed, but Bash does the opposite here: the assignment prints readonly variable, sourcing continues, the final source status is 0, and the attacker-controlled value remains. The WhatsApp wrapper later treats that value as trusted at lines 3611-3615, so a matching caller-selected gateway URL can retain OPENCLAW_GATEWAY_TOKEN for the login and token-bearing reconcile.

Please make the generated runtime file explicitly verify that the trust anchor equals the baked URL and abort or disable every token-bearing helper when it does not. Add an adversarial regression that predefines a conflicting readonly anchor before sourcing and proves neither the login nor channels.start receives the token. The current tests only verify the normal generated readonly value and do not exercise this failure mode.

Secondary hardening: bound the allowlisted WhatsApp account ID length and test the boundary so an arbitrarily large caller value cannot inflate the JSON/RPC argv.

[cv]

Exact-head follow-up at b8c47c2ff: both requested security fixes are addressed. Conflicting readonly trust anchors now fail closed, clear the ambient token, and return before token-bearing helpers are installed; the adversarial regression proves no token reaches either OpenClaw call. Account IDs are character-validated and bounded to 128 before token read/JSON/RPC, with 128/129 boundary coverage. The focused security suite passes 26/26 and all 31 exact-head checks are green.

[cv]

Post-merge regression found while validating #6444: the trust-anchor code added here is emitted into /tmp/nemoclaw-proxy-env.sh, which sandbox commands source from /bin/sh -lc, but it invokes the Bash-only builtin readonly and builtin unset commands.

On the supported Ubuntu shell, sh -lc 'builtin readonly NEMOCLAW_TEST_ANCHOR=value' exits 127 with builtin: not found. In exact E2E run 29003632720, both onboard-resume and snapshot-commands then hit the fail-closed path and abort authenticated sandbox exec with:

NemoClaw rejected a conflicting gateway trust anchor, and the ambient gateway token could not be cleared.

Four other requested lifecycle jobs passed. The failures occur before #6444-specific lifecycle assertions, and scripts/nemoclaw-start.sh is not in that PR's diff.

This needs a POSIX-shell-compatible trust-anchor implementation that preserves the fail-closed anti-spoofing property, plus a regression that sources the generated runtime file through /bin/sh. Until then, fresh lifecycle evidence for #6444 is blocked.

[cv]

Follow-up #6560 now contains the narrow fix for the post-merge POSIX-shell regression reported above. It keeps the fail-closed trust-anchor/token behavior while making the generated runtime environment sourceable by both Bash and POSIX sh, with focused regression coverage.