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

# Native Remote Control — GC↔RMM Integration Contract & Embedded Viewer — Implementation Plan

> Spec created: 2026-05-29
> Status: not started
> Architecture: broker model — RMM orchestrates the separate GC agent, against a versioned
> integration contract that GC owns. Two independent products, kept in-sync by contract + capability
> discovery (NOT by shared pipelines).
> Repos: **GC** = guru-connect (standalone product, in claudetools repo) · **RMM** = guru-rmm (submodule).

## End-to-end flow (target behavior)

**Unattended:** tech clicks Remote Control on `AgentDetail` → RMM checks GC capabilities, (1)
pre-creates a GC session bound to the endpoint's `device_id` and mints a short-lived viewer token,
(2) commands the endpoint's RMM agent to ensure the GC agent is installed (checksum-verified) and
connected in persistent mode → RMM **embeds GC's viewer** in the dashboard (scoped iframe) pointed
at that session, native `guruconnect://` as fallback.

**Attended:** same, but RMM mints a support code on GC, the GC agent shows a consent prompt, and the
session starts only after the end user accepts.

The contract surface (Tasks 1-3) is GC's; the broker + embed (Tasks 7-10) is RMM's.

---

## Task 0: Commit this spec

```
git add projects/msp-tools/guru-connect/specs/native-remote-control/
git commit -m "spec: add native-remote-control shape spec"
```
Do not start Task 1 until this commit exists.

---

## Task 1 (GC): Define & version the integration contract — KEYSTONE

Files touched: `CONTRACT.md` (new, GC repo root or `docs/`), `server/src/main.rs` (routes `:254` `/health`,
`:300` `/api/version`), `server/src/api/` (new `integration.rs`), `server/src/middleware/` (integration auth).

- Author a semver'd `CONTRACT.md` documenting the GC integration surface (auth model, endpoints,
  payloads, capability flags, viewer embed protocol, error envelope). This is the artifact both teams
  keep "front of mind" — GC must not break a published version without a major bump.
- Create the `/api/integration/v1/` route namespace.
- `GET /api/integration/capabilities` (model on the existing public `/api/version` at
  `releases.rs:76`) → `{ contract_version, features: { embedded_viewer, consent_prompt,
  per_machine_keys, programmatic_sessions } }`. RMM reads this to version-gate.
- Add **server-to-server integration auth**: a single integration credential
  (`CONNECT_INTEGRATION_KEY`, env/SOPS) required on all `/api/integration/v1/*` routes. Capabilities
  endpoint may be unauthenticated (like `/api/version`) so RMM can probe before configuring.
- Error envelope per `api/response-format` (`detail`/`error_code`/`status_code`).

## Task 2 (GC): Per-machine agent keys

Files touched: `server/migrations/0XX_agent_keys.sql` (new), `server/src/db/agent_keys.rs` (new),
`server/src/relay/mod.rs` (`validate_agent_api_key` `:187`), `server/src/api/integration.rs`.

- Idempotent migration: `connect_agent_keys` (`id`, `agent_id`, `key_hash`, `created_at`, `revoked_at`).
  Hashed keys only (model on RMM `enroll.rs` `generate_api_key`/`hash_api_key`).
- `POST /api/integration/v1/agents/:agent_id/keys` mints a per-machine key (plaintext once, store hash).
- `validate_agent_api_key()` accepts a valid DB per-machine key; shared `AGENT_API_KEY` env becomes a
  deprecated fallback. Support `revoked_at`.

## Task 3 (GC): Programmatic session pre-create + viewer token

Files touched: `server/src/api/integration.rs`, `server/src/session/mod.rs` (`register_agent` `:95`),
`server/src/db/sessions.rs` (`create_session` `:22`), `server/src/auth/jwt.rs`, `server/migrations/`.

- `POST /api/integration/v1/sessions` — body `{ agent_id, mode }`. Pre-creates a session row +
  in-memory slot keyed by `agent_id`, marked `is_managed`/`source="gururmm"`; returns `{ session_id }`.
  When the GC agent later registers with that `agent_id`, `register_agent()` binds it to the
  pre-created session instead of generating a new one.
- `POST /api/integration/v1/sessions/:id/viewer-token` — short-lived (~5 min), session-scoped viewer JWT.
- Add `is_managed BOOLEAN` / `source TEXT` to `connect_sessions` (idempotent migration).
- For attended, the broker reuses the existing `POST /api/codes` (`main.rs:382`); expose/document it
  under the contract too.

## Task 4 (GC): Embedded session viewer

Files touched: `server/static/viewer.html`, `server/src/middleware/security_headers.rs:30,37-39`,
`server/src/main.rs` (per-route header layer for the viewer), `CONTRACT.md` (embed protocol).

- Add a **scoped framing allowlist** for the viewer route(s): `frame-ancestors <RMM dashboard origin>`
  (from env, e.g. `CONNECT_EMBED_ALLOWED_ORIGINS`) and matching/relaxed `X-Frame-Options` ONLY on the
  viewer path. Every other route keeps `frame-ancestors 'none'` (`:30`) — do not weaken globally.
- Add an **embed mode** to `viewer.html` (e.g. `?embed=1`): hide standalone chrome, accept the
  session_id + viewer token from the host, and emit `postMessage` lifecycle events
  (`viewer:connected`, `viewer:disconnected`, `viewer:error`, `viewer:resize`) for the RMM host to
  react to. Document this embed protocol in `CONTRACT.md`.

## Task 5 (GC): Consent messages + attended prompt

Files touched: `proto/guruconnect.proto` (after `AdminCommand` `:286`),
`agent/src/session/mod.rs`, `agent/src/consent/mod.rs` (new) + `agent/src/tray/mod.rs`,
`server/src/relay/mod.rs`, `server/src/session/mod.rs`.

- Add `ConsentRequest { session_id, technician_name, reason }` (server→agent) and
  `ConsentResponse { session_id, accepted }` (agent→server).
- GC agent: on `ConsentRequest` in attended mode, show a native consent dialog; Decline → session
  refused + event logged. Unattended skips consent (gated by session `mode`).
- Emit `connect_session_events` for consent shown/accepted/declined. Expose `consent_prompt` in the
  capabilities map (Task 1).

## Task 6 (GC): Session persistence / restart reconcile (robustness)

Files touched: `server/src/session/mod.rs` (`:81`), `server/src/db/sessions.rs`, `server/src/main.rs`.

- On startup, load active `connect_sessions` from DB into `SessionManager` so a relay restart does
  not orphan managed sessions; reap stale rows. This satisfies the "robust" requirement.

## Task 7 (RMM): GC integration client (capability-aware) + config

Files touched: `server/src/connect_client.rs` (new), `server/src/config` (env wiring).

- Client for the GC `/api/integration/v1` contract: base URL (`CONNECT_SERVER_URL`) + integration key
  (`CONNECT_INTEGRATION_KEY`), env/SOPS only.
- On startup / first use, call `GET /api/integration/capabilities`; **cache the contract version +
  feature map** and version-gate RMM behavior off it (e.g. only offer attended consent if
  `consent_prompt` is true). Log a `[WARNING]` if the GC contract version is newer/older than expected.
- Methods: `capabilities()`, `pre_create_session(device_id, mode)`, `mint_viewer_token(session_id)`,
  `mint_support_code(technician)`, `provision_agent_key(device_id)`.

## Task 8 (RMM): Broker endpoint

Files touched: `server/src/api/remote_control.rs` (new), `server/src/api/mod.rs` (`:162` register),
`server/src/db/` + `server/migrations/0XX_remote_control_sessions.sql` (new, or extend `tech_sessions`),
reuse command dispatch `server/src/api/commands.rs:87-157`.

- `POST /api/agents/:agent_id/remote-control` — body `{ mode }`. Authz via `authorize_agent_access`.
  Steps: resolve `device_id`+online → (via `connect_client`) ensure per-machine key, pre-create session,
  attended→support code → dispatch launch command to the RMM agent (Task 9) → mint viewer token →
  return `{ session_id, viewer_embed_url, viewer_native_url, mode, capabilities }`.
- Record a `remote_control_sessions` audit row (`agent_id`, `tech_id`, `connect_session_id`, `mode`,
  `started_at`), mirroring the `tunnel_audit` pattern.

## Task 9 (RMM agent): Ensure-and-launch GC agent

Files touched: `agent/src/transport/websocket.rs` (`run_command` `:1050`, `execute_command` `:971`),
`agent/src/remote_control/mod.rs` (new), `agent/src/config.rs`, `agent/src/service.rs` (AppState parity).

- New launch path (Windows, `#[cfg(windows)]`): ensure the GC agent binary present; if missing/outdated,
  download from the GC release channel and **verify SHA-256 before executing** (supply-chain guard).
  Launch passing RMM `device_id` as the GC `agent_id`, the per-machine key, relay URL, and (attended)
  the support code; unattended = persistent (no code).
- Non-Windows: working stub + `// TODO(platform): linux/macos — GC agent not available`
  (per `gururmm/platform-parity`). Mirror any new `AppState` field into `service.rs`.

## Task 10 (RMM dashboard): Remote Control button + embedded viewer

Files touched: `dashboard/src/pages/AgentDetail.tsx` (`:1893-1931`), `dashboard/src/api/client.ts`
(`:293-310` pattern), `dashboard/src/components/RemoteControlPanel.tsx` (new).

- `remoteControlApi.start(agentId, mode)` → `POST /api/agents/:agent_id/remote-control`.
- "Remote Control" button on `AgentDetail` (enabled only when online + GC capabilities allow); on
  success, render `RemoteControlPanel` embedding `viewer_embed_url` in a scoped iframe and wiring the
  `postMessage` lifecycle events (Task 4). Native `viewer_native_url` offered as a fallback link.
  ASCII markers in toasts/logs; no emojis.

## Task 11 (both): Contract tests in each pipeline

Files touched: GC `server/tests/integration_contract.rs` (new), RMM `server/tests/connect_contract.rs` (new).

- GC pipeline: a test asserting the `/api/integration/v1` surface + `capabilities` shape matches the
  documented `CONTRACT.md` version (catches accidental breaking changes before release).
- RMM pipeline: a test (against a recorded/mock capabilities response) asserting the client correctly
  version-gates and parses the contract. This is what keeps the independently-built products in-sync —
  each pipeline independently fails if it drifts from the contract.

## Task 12: Verification

End-to-end (Windows endpoint, both agents installed):

- **Capability discovery:** RMM logs the GC contract version + feature map on startup; disabling a GC
  feature flag hides the corresponding RMM affordance.
- **Embedded unattended:** Remote Control (unattended) on an online managed Windows endpoint → GC
  viewer renders **inside the RMM dashboard** (iframe), screen + mouse/keyboard work, multi-monitor
  switch works, no endpoint prompt. `postMessage` `viewer:connected` fires.
- **Attended:** end user sees the consent dialog (technician name); Accept → session; Decline → refused + logged.
- **Embedding security:** the GC viewer loads framed only from the RMM origin; any other origin is
  refused (`frame-ancestors`); all non-viewer GC routes still return `frame-ancestors 'none'`.
- **Supply-chain guard:** corrupt the staged GC binary → agent refuses to launch (checksum mismatch in logs).
- **Standalone unaffected:** GC still builds, runs, and serves a normal (non-embedded) support session
  with zero RMM present.
- **Robustness:** restart the GC relay mid-session → managed session reconciled from DB, not orphaned.
- **Audit:** `remote_control_sessions` (RMM) + `connect_session_events` (GC) show session, technician, mode, consent.
- **Contract tests:** both pipelines' contract tests pass; intentionally bumping the GC contract shape
  without updating `CONTRACT.md`/RMM fails the relevant pipeline test.