guru-connect/specs/native-remote-control/shape.md

Native Remote Control — GC↔RMM Integration Contract & Embedded Viewer — Shape & Constraints

What this is

guru-connect (GC) is a standalone product — a ScreenConnect/Splashtop-style remote-support tool that must work fully on its own, with its own release pipeline, cadence, and development cycle, independent of GuruRMM (RMM).

This feature establishes and maintains the integration contract that lets RMM embed GC as an integrated session viewer — a technician launches a live remote-control session on a managed endpoint from inside the RMM dashboard, and the GC session viewer renders inside RMM's UI — while GC and RMM remain separately developed products. The deliverable is therefore not a one-off broker wiring; it is a durable, versioned boundary (owned by GC) plus the broker that consumes it. "Keep integration front of mind" = GC treats this contract as a first-class, supported surface that it does not break as it evolves on its own cadence.

What this is NOT (out of scope)

• File transfer — no drag/drop or browse-and-copy during a session (deferred).
• Session recording — no session-to-video capture for audit/compliance (deferred).
• Non-Windows agents — macOS/Linux remote-control endpoints are out of scope; the GC agent is Windows-only today. Windows-first. (Multi-monitor IS in scope.)
• Not coupling the two products. This must NOT merge GC into the RMM agent, share build pipelines, or make either product unbuildable/unreleasable without the other. GC must still ship and run standalone with zero RMM dependency.
• Not a replacement for RMM's generic admin tunnel scaffold (terminal/file/registry channels) — that is a separate text-channel feature; this is video remote control.

In scope

• A versioned GC integration contract (/api/integration/v1/...) owned and documented by GC, with a capability/version discovery endpoint so RMM can detect what a given GC build supports and degrade gracefully. This is the keystone of the feature.
• Embedded session viewer — RMM hosts GC's web viewer inside its dashboard (scoped iframe / panel), not only the native guruconnect:// launch.
• Unattended remote control of managed endpoints (primary RMM use case).
• Attended remote control with an end-user consent prompt.
• Multi-monitor (display switching) — GC already reports display_count.
• Short-lived, per-session viewer credentials (no long-lived viewer tokens).

Hard constraints

• GC stays standalone. Independent pipeline/cadence preserved. The integration contract is additive to GC and must not introduce any RMM build/runtime dependency into GC.
• Stability via versioning, not lockstep. Because the two products release on different cadences, the contract is semver'd and exposes GET /api/integration/capabilities. RMM version-gates features off that response; GC never breaks a published contract version without a major bump.
• No external apps / no supply-chain exposure. Remote control runs entirely on our Rust stack. The RMM agent obtains the GC agent binary only from GC's own release channel and verifies a SHA-256 checksum before launch (reuse GC's releases.checksum_sha256). No third-party downloads.
• Embedding must not weaken security. The viewer is framable only by an explicit RMM-origin allowlist via scoped frame-ancestors / X-Frame-Options on the viewer route(s); the global frame-ancestors 'none' (security_headers.rs:30) stays for every other route.
• No hardcoded secrets. Integration key, per-machine agent keys, viewer tokens come from env/SOPS, never source. No endpoint URLs in TOML/config files — env vars only.
• Single static binary, no runtime deps; Windows 7 SP1+ target preserved for the GC agent.

Key decisions

• GC owns the integration contract. It lives in the GC repo (this spec + a versioned CONTRACT.md / OpenAPI doc), is exposed under /api/integration/v1/, and is GC's responsibility to keep stable. RMM is purely a consumer.
• Decouple cadences with capability discovery. GET /api/integration/capabilities returns the contract version + a feature map (e.g. embedded_viewer, consent_prompt, per_machine_keys). RMM reads it at integration time and only offers what the connected GC build supports. This is how "in-sync" is achieved without lockstep releases.
• Broker model (RMM orchestrates the separate GC agent). Reuses GC's existing engine as-is; aligns naturally with two independent products. Endpoints both agents stay separate binaries.
• Stable cross-product identity = RMM device_id. The RMM agent launches the GC agent passing RMM's device_id as the GC agent_id, so the broker's pre-created session deterministically matches the endpoint (agent/src/device_id.rs survives reinstalls).
• Embedded viewer over native-only. GC exposes an embed-mode viewer.html (scoped framing + postMessage lifecycle events for the RMM host); the native guruconnect:// handler remains a fallback. This is what makes GC a true "integrated session viewer."
• Per-machine agent keys replace the shared AGENT_API_KEY (relay/mod.rs:187 flags this as future work); programmatic session pre-create + short-lived viewer token are added because GC has neither today; consent for attended mode is new (ConsentRequest/ConsentResponse).

Priority

P2 — important, near-term. The contract/capability layer (Tasks 1) is the part to get right first, because it is the long-lived surface both products depend on.

Roadmap reference

projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md:635-675 — "Remote Access" (supersedes the "Remote desktop (RDP/VNC proxy) - P3" line with our own stack). docs/UI_GAPS.md:155-186. GC side: this spec + the new CONTRACT.md become GC's integration-surface roadmap entry.