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.