feat(rust): add authenticated node sidecar bridge

[giodl73-repo]

Summary

Adds one authenticated, bounded sidecar contract for running openclaw-node-host
out of process while leaving product policy, native capability ownership, process
launch, and transport selection with the embedding application.

This consolidates the reviewed fork evidence from
#193,
#194, and
#195 into the third OpenClaw
review surface:

• authenticated, versioned, directional, replay-resistant HMAC framing;
• exact supervisor/runtime offer-accept negotiation with intersection-only
  features and limits;
• permanent channel retirement and key zeroization after terminal validation
  failures;
• immutable post-handshake configuration and manifest acknowledgement;
• bounded admission, invocation, cancellation, result, and status messages;
• an adapter from the authenticated sidecar into the existing CommandRuntime
  and NodeLifecycle surfaces; and
• three language-neutral, byte-exact fixture corpora independently reproduced
  by the Windows C# adopter; plus
• a separate OS child-process proof that exchanges authenticated frames over
  real loopback TCP in both directions and exits cleanly.

Position in the series

1. #116050 — shared
   openclaw-gateway-client, initial openclaw-node-host, and Linux Tauri
   convergence.
2. #116450 — signing/token
   delivery, lifecycle/reconnect, duplex invocation, admission, Gateway
   authority, connection manifests, and shared TypeScript/Rust conformance.
3. This PR — the authenticated out-of-process sidecar boundary and typed
   ordinary-command runtime bridge.
4. Windows adopter #1068
   — independently consumes these contracts through the existing
   NodeCapabilityDispatcher while retaining C# as the production default.

GitHub requires this cross-fork PR to target main; it is logically stacked on
the exact #116450 head bfd5c4d14e2730d8e9b2a76a9ad45e52288a3732.
After #116050 and #116450 land, their shared ancestry drops out and only this
logical sidecar slice remains.

Ownership boundary

RFC #54 proposes that OpenClaw own the reusable protocol, Gateway authority
semantics, node runtime, and conformance corpora. Under that boundary, the
embedding product remains responsible for:

• verifying and launching the exact runtime artifact;
• creating the local-only transport and protected bootstrap channel;
• product approval policy, native capability handlers, and audit export;
• process/crash supervision, health integration, resource policy, rollout,
  rollback, packaging, and deployment; and
• choosing whether the sidecar is selectable at all.

The reported peer identity is authenticated by the fresh session key but is not
artifact-verification proof. The bridge cannot broaden the authenticated
configuration or introduce commands outside the exact manifest. The reserved
system.* namespace remains unavailable to this generic runtime until OpenClaw
defines an explicit authorization contract.

Deliberate exclusions

This PR does not choose a product IPC or launcher, deliver production
credentials, select the Rust runtime by default, implement product approval UX,
MCP/skills, or native handlers, provide an audit sink, or claim production
sidecar readiness. Its child-process TCP harness proves the generic
process/transport contract only.

Full ordered duplex sidecar input/progress/heartbeat transport, verified
process/bootstrap, Gateway pairing/token proof, crash/resource proof, packaging,
rollout, and rollback remain adoption gates.

Validation

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo test --workspace --all-targets --all-features — 124 tests passed
• cargo doc --workspace --no-deps
• oxfmt 0.60.0 --check on the protocol document and all three JSON corpora
• git diff --check
• sequential correctness, architecture/API, and security reviews — all
  findings resolved; final exact-head passes clean

The cumulative OpenClaw sidecar head is
71c1c8cb23c5647dc07fd4ee1f8663068c92a482. Review fixes cover terminal
retirement, bounded serialization, session-specific frame minima, portable
feature/version negotiation, role and delivery binding, immutable configuration,
portable JSON numbers, complete-message budgeting, and bounded stable adapter
errors.

Real behavior proof

Behavior or issue addressed:
The reusable Rust node runtime had no authenticated local process boundary that
an independent product could implement without importing product policy or
creating a second native execution path.

Real environment tested:
Ubuntu 24.04/WSL2 at commit
71c1c8cb23c5647dc07fd4ee1f8663068c92a482, Tokio loopback TCP, a separately
launched OS child, RustCrypto HMAC-SHA-256, OS randomness, and the checked-in
language-neutral protocol, handshake, and runtime corpora. The independent
Windows adopter at 711fe095028a025fa0649c9b8e20f480644a6967 reproduces the
same corpora in C#. This is process/transport contract proof, not a packaged or
product-supervised Rust runtime.

Exact steps or command run after this patch:

1. Reproduce the authenticated frame vector in supervisor and runtime roles.
2. Complete the exact offer/accept handshake and lower the live channel limit.
3. Exchange one immutable configuration and exact manifest acknowledgement.
4. Route an admitted ordinary invocation through product-owned admission and
   native dispatch, including denial, timeout, cancellation, and status paths.
5. Serialize and parse every message in all three shared fixture corpora.
6. Launch the same integration-test executable as a separate OS child; complete
   authenticated negotiation, configuration and exact manifest acknowledgement,
   admission, invocation, and result over real loopback TCP; and verify clean exit.
7. Run the complete Rust workspace and strict static/documentation gates.

Evidence after fix:
The Rust workspace passes 124 tests, including two focused process-boundary
tests and the complete configured ordinary-command transcript. The rebased
independent C# consumer in Windows #1068 passes 3,701 Shared
tests with 32 environment-dependent skips and 22 focused Connection tests; its
larger prior-head suites remain recorded in RFC #54.

Observed result after fix:
Both implementations agree byte-for-byte on framing, handshake, configuration,
admission, invocation, result, cancellation, and status. Authentication,
ordering, identity, replay, configuration substitution, command-manifest,
portable-number, cancellation, and output-bound violations fail closed before
native work or further transport use. No production runtime selection changes.

What was not tested:
No packaged Rust binary was launched through product-selected IPC; no protected
credential bootstrap, artifact verification, product supervisor, live Gateway
pairing/token session, system.* command, product audit sink, crash/restart
circuit breaker, resource measurement, packaging, rollout, or rollback was
exercised. Those remain explicit adopter gates rather than implied capabilities
of this PR.

[clawsweeper]

Codex review: found issues before merge. Reviewed August 12, 2026, 4:17 PM ET / 20:17 UTC.

ClawSweeper review

What this changes

This draft adds a Rust authenticated sidecar protocol and node-command runtime bridge, with Gateway schema and generated Android/Swift model updates.

Merge readiness

⛔ Blocked by patch quality or review findings - 9 items remain

Keep open for an explicit maintainer decision: this is a large, stacked proposal for a second core node runtime, not a bounded bug fix. The earlier nullable-params generator finding is addressed, but the dirty branch must be rebased and its generated native protocol clients refreshed before it can be reconsidered.

Priority: P3
Reviewed head: 71c1c8cb23c5647dc07fd4ee1f8663068c92a482
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The generic sidecar proof is useful, but the dirty generated-client conflict and unresolved architecture decision leave the patch unready.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (terminal): The PR body describes an after-fix OS-child loopback TCP exchange that exercises authenticated negotiation, configuration, invocation, and result recovery; it proves the generic transport boundary, not packaging or product supervision.
Patch quality	🦪 silver shellfish (2/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The PR body describes an after-fix OS-child loopback TCP exchange that exercises authenticated negotiation, configuration, invocation, and result recovery; it proves the generic transport boundary, not packaging or product supervision.
Evidence reviewed	7 items	Existing current-main runtime: Current docs define one paired Gateway node surface and state that macOS uses the matching CLI node-host runtime as its internal worker; current source prepares that transport-independent TypeScript runtime. Gateway ownership and session forwarding: Current main owns node dispatch and forwards sessionKey beside paramsJSON at the final Gateway-to-node event boundary. Current generated-client contract: Current schema exposes terminalPolicy and current Swift output retains it; the coordinator consumes that generated protocol type.
Findings	1 actionable finding	[P1] Rebase and regenerate the native protocol models
Security	Needs attention	Assign the bootstrap trust boundary: The protocol explicitly relies on a supervisor to verify the executable and deliver a protected fresh session key, but this PR has no adopting supervisor or product-owned implementation of that boundary.

How this fits together

Gateway sends authenticated node invocations to paired device runtimes and receives results, progress, and cancellation events. This PR adds a Rust runtime that can place a local authenticated sidecar between that Gateway-facing node session and product-owned command handlers.

flowchart LR
  Gateway[Gateway node invocation] --> Schema[Gateway protocol schema]
  Schema --> Native[Android and Swift models]
  Schema --> Rust[Rust node runtime]
  Rust --> Sidecar[Authenticated local sidecar]
  Sidecar --> Handler[Product-owned command handler]
  Handler --> Result[Gateway result and progress]

Loading

Decision needed

Question	Recommendation
Should OpenClaw adopt a core-owned Rust node runtime and authenticated sidecar as an incubating supported architecture, rather than keep the existing TypeScript node-host as the sole core runtime?	Pause for architecture sponsorship: Keep the stack draft until the RFC names the runtime owner, supported platforms, adoption path, bootstrap trust boundary, and compatibility commitment.

Why: This is a 12k-production-line parallel runtime stack with future product-owned packaging, artifact verification, bootstrap, and supervision obligations; code review cannot choose that ownership or support commitment.

Before merge

• Rebase and regenerate the native protocol models (P1) - This changed generated file is based on a schema snapshot that lacks current-main terminalPolicy and other native models. GitHub marks the branch dirty; rebase, preserve current protocol changes, and regenerate before merge so conflict resolution cannot discard existing client APIs.
• Resolve security concern: Assign the bootstrap trust boundary - The protocol explicitly relies on a supervisor to verify the executable and deliver a protected fresh session key, but this PR has no adopting supervisor or product-owned implementation of that boundary.
• Resolve merge risk (P1) - The dirty head predates current generated protocol clients; rebase resolution must retain current Swift/Android models and regenerate from the merged schema.
• Resolve merge risk (P1) - The sidecar introduces a new command-execution trust boundary whose artifact verification and protected bootstrap are intentionally left to a future embedding product.
• Resolve merge risk (P1) - The checkout could not materialize the complete three-way PR diff because required promised Git objects attempted an unavailable network fetch; an exact merge-resolution audit remains necessary.
• Complete next step (P2) - A product owner must choose the core runtime and bootstrap-security direction; rebase is necessary but does not settle that choice.
• Improve patch quality - Rebase onto current main and regenerate all native protocol artifacts without losing current schema models.
• Improve patch quality - Obtain maintainer sponsorship for the Rust runtime, bootstrap trust owner, and adoption plan.

Findings

• [P1] Rebase and regenerate the native protocol models — apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift:3798-3829
• [medium] Assign the bootstrap trust boundary — crates/openclaw-node-host/SIDECAR_PROTOCOL.md:12

Agent review details

Security

Needs attention: The framing is deliberately fail-closed, but the new sidecar cannot safely become product-selectable until its bootstrap and artifact-verification owner is approved.

PR surface

Source +30, Tests +488, Docs +204, Other +14143. Total +14865 across 42 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	3	32	2	+30
Tests	8	489	1	+488
Docs	1	204	0	+204
Config	0	0	0	0
Generated	0	0	0	0
Other	30	14626	483	+14143
Total	42	15351	486	+14865

Review metrics

Metric	Value	Why it matters
Production vs test LOC	runtime/tooling +12,120/-480; tests +1,709/-1; generated +6/-1; fixtures +338; lockfiles +1,178/-4; docs +204	The large new core runtime surface needs explicit architecture sponsorship and a clean restack rather than routine feature review.

Stored data model

Persistent data-model change detected: database schema: packages/gateway-protocol/src/schema/nodes.test.ts, database schema: test/fixtures/node-sidecar-handshake-v1.json, database schema: test/fixtures/node-sidecar-negotiation-v1.json, database schema: test/fixtures/node-sidecar-protocol-v1.json, database schema: test/fixtures/node-sidecar-runtime-v1.json, serialized state: crates/openclaw-gateway-client/src/session.rs, and 8 more. Confirm migration or upgrade compatibility proof before merge.

Merge-risk options

Maintainer options:

1. Rebase and regenerate native protocol models (recommended)
   Resolve the dirty merge against current main, preserve its protocol models, and run the canonical protocol generation checks before another functional review.
2. Pause the core runtime proposal
   Do not merge the sidecar until a maintainer sponsors its packaging, supervision, and bootstrap trust contract.

Technical review

Best possible solution:

Decide whether a core Rust runtime is an endorsed architecture, then land only a rebased, generated-client-clean slice atop merged prerequisites with a named in-tree adopter and bootstrap-trust owner.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this PR proposes a new runtime boundary, while its stated child-process test is evidence for the generic sidecar contract.

Is this the best way to solve the issue?

Unclear: the existing TypeScript node-host already owns the Gateway node boundary, and whether a parallel Rust core runtime is preferable requires maintainer direction.

Full review comments:

• [P1] Rebase and regenerate the native protocol models — apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift:3798-3829
  This changed generated file is based on a schema snapshot that lacks current-main terminalPolicy and other native models. GitHub marks the branch dirty; rebase, preserve current protocol changes, and regenerate before merge so conflict resolution cannot discard existing client APIs.
  Confidence: 0.97

Overall correctness: patch is incorrect
Overall confidence: 0.91

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against c631b1a45edb.

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body describes an after-fix OS-child loopback TCP exchange that exercises authenticated negotiation, configuration, invocation, and result recovery; it proves the generic transport boundary, not packaging or product supervision.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🐚 platinum hermit and patch quality is 🦪 silver shellfish.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.
• remove merge-risk: 🚨 availability: Current PR review merge-risk labels are merge-risk: 🚨 compatibility, merge-risk: 🚨 security-boundary.

Label justifications:

• P3: This is an optional architectural feature proposal rather than an active user-facing regression.
• merge-risk: 🚨 compatibility: The dirty branch’s generated Swift model omits current-main protocol fields, so an unsafe conflict resolution could break native client contracts.
• merge-risk: 🚨 security-boundary: The new authenticated sidecar delegates executable verification and protected bootstrap to a future product owner.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🐚 platinum hermit and patch quality is 🦪 silver shellfish.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR body describes an after-fix OS-child loopback TCP exchange that exercises authenticated negotiation, configuration, invocation, and result recovery; it proves the generic transport boundary, not packaging or product supervision.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body describes an after-fix OS-child loopback TCP exchange that exercises authenticated negotiation, configuration, invocation, and result recovery; it proves the generic transport boundary, not packaging or product supervision.

Evidence

Security concerns:

• [medium] Assign the bootstrap trust boundary — crates/openclaw-node-host/SIDECAR_PROTOCOL.md:12
  The protocol explicitly relies on a supervisor to verify the executable and deliver a protected fresh session key, but this PR has no adopting supervisor or product-owned implementation of that boundary.
  Confidence: 0.94

What I checked:

• Existing current-main runtime: Current docs define one paired Gateway node surface and state that macOS uses the matching CLI node-host runtime as its internal worker; current source prepares that transport-independent TypeScript runtime. Public docs: docs/nodes/index.md. (docs/nodes/index.md:10, c631b1a45edb)
• Gateway ownership and session forwarding: Current main owns node dispatch and forwards sessionKey beside paramsJSON at the final Gateway-to-node event boundary. (src/gateway/node-registry.ts:1163, 9b80654d48c0)
• Current generated-client contract: Current schema exposes terminalPolicy and current Swift output retains it; the coordinator consumes that generated protocol type. (packages/gateway-protocol/src/schema/gateway-suspend.ts:44, c631b1a45edb)
• Stale generated output at PR head: The PR-head Swift model has only requestId for GatewaySuspendPrepareParams, omitting terminalPolicy present on current main; GitHub reports this head as dirty, so a rebase and regeneration must preserve current protocol models. (apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift:1646, 71c1c8cb23c5)
• Prior generator finding resolved: The head generator special-cases the nullable paramsJSON field as String, and the generated Android model retains paramsJson: String?. (scripts/protocol-gen-kotlin.ts:241, 71c1c8cb23c5)
• Product-direction constraint: VISION.md calls TypeScript the primary orchestration implementation, treats PRs above roughly 5,000 changed lines as exceptional, and prioritizes lean core boundaries. (VISION.md:36, c631b1a45edb)

Likely related people:

• steipete: Authored the major current-main node-hosted plugin and node-host migration work relevant to the existing runtime boundary. (role: recent node-host feature owner; confidence: high; commits: 49b5b862acf3, 6c812539859a, 032defb17216; files: src/node-host/runtime.ts, docs/nodes/index.md)
• vincentkoc: Authored current-main work on node session attribution and N-1 Gateway/node compatibility. (role: recent protocol compatibility contributor; confidence: high; commits: 735f176b0121, 587def9c9d56; files: packages/gateway-protocol/src/schema/nodes.ts, src/gateway/node-registry.ts)
• Amp: Current generated protocol/client consolidation owns the main-only models the dirty branch must preserve. (role: recent generated-client contributor; confidence: medium; commits: 9b80654d48c0; files: apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift, apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (12 earlier review cycles; latest 8 shown)

• reviewed 2026-08-01T11:59:22.748Z sha 8d0a1b0 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-01T12:21:00.820Z sha 8d0a1b0 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-01T16:39:01.208Z sha 8d0a1b0 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-01T21:15:32.061Z sha 8d0a1b0 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-02T06:27:57.125Z sha 8d0a1b0 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-02T13:17:01.539Z sha 8d0a1b0 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-03T22:18:57.166Z sha 8d0a1b0 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-12T19:18:46.617Z sha 8ead00a :: found issues before merge. :: [P1] Preserve the generated paramsJSON string contract

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31637042413
• Updated: 2026-08-12T20:19:32.226Z