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

Native Remote Control — Code References

Two repos. GC = guru-connect (D:\claudetools\projects\msp-tools\guru-connect, lives in the claudetools repo). RMM = GuruRMM (projects/msp-tools/guru-rmm, a git submodule tracking azcomputerguru/gururmm). Paths below are relative to each repo root.

Files that will be touched

guru-connect (GC)

• server/src/main.rs — route table; create_code :382, list_sessions :425, get_session :433, list_machines :467, /health :254, public /api/version :300. Add the /api/integration/v1/ namespace: GET .../capabilities, POST .../sessions, POST .../sessions/:id/viewer-token, POST .../agents/:agent_id/keys; register the server-to-server integration auth layer. Model the (unauthenticated) capabilities endpoint on the existing /api/version route.
• CONTRACT.md (new — GC repo root or docs/) — the semver'd integration contract doc both teams keep front of mind. Source of truth for the surface; tested in CI (Task 11).
• server/src/api/releases.rs:76 — GET /api/version handler (no auth, for agent polling). Pattern to model GET /api/integration/v1/capabilities on.
• server/static/viewer.html — the existing web viewer; gets an ?embed=1 mode (hide standalone chrome, accept host-provided session/token, emit postMessage lifecycle events for the RMM host).
• server/src/middleware/security_headers.rs:30 (frame-ancestors 'none') and :37-39 (X-Frame-Options) — the embedding blocker. Add a per-route scoped allowlist for the viewer path only (RMM origin from env); leave every other route at 'none'.
• server/src/session/mod.rs — in-memory SessionManager; register_agent() :95, join_session() :254. Change to allow a session to be pre-created/keyed by agent_id before the agent connects, then bound when the agent registers.
• server/src/db/sessions.rs — create_session() :22. Change/add to persist pre-created sessions and a is_managed/source marker; reconcile in-memory state on startup.
• server/src/db/support_codes.rs — create_support_code() :24, get_support_code() :43. Reused as-is for the attended path (broker calls POST /api/codes).
• server/src/relay/mod.rs — agent WS handler :55/:236; validate_agent_api_key() :187 (currently JWT-or-shared-AGENT_API_KEY, comment at :200 flags DB keys as future). Change to validate against the new per-machine key table.
• server/src/auth/jwt.rs — JWT signing/validation. Add a short-lived, session-scoped viewer token mint.
• server/migrations/ — add connect_agent_keys (per-machine keys) and session columns; follow the existing 001_initial_schema.sql / 003_auto_update.sql style. Idempotent (IF NOT EXISTS).
• proto/guruconnect.proto — SessionRequest :8, StartStream :261, AgentStatus :271, AdminCommand :286. Add ConsentRequest / ConsentResponse messages.
• agent/src/session/mod.rs — SessionState :71, persistent-vs-support logic. Change to register against a broker-assigned agent_id (= GuruRMM device_id).
• agent/src/transport/websocket.rs — connect() :32 (builds ?agent_id=&api_key=&support_code=). Pass the per-machine key.
• agent/src/tray/mod.rs + a new consent dialog — add the attended-mode consent prompt (handle ConsentRequest).
• agent/src/install.rs — register_protocol_handler() :131 (guruconnect://<session>?token=&server=). Reused for native-viewer launch URLs the broker returns.

GuruRMM (RMM)

• server/src/api/commands.rs:87-157 — POST /api/agents/{agent_id}/command dispatch (online → WS ServerMessage::Command; offline → queued). Reuse to push the "ensure + launch guru-connect" instruction to the endpoint agent.
• server/src/api/mod.rs:162 — route registration site. Add the new broker route.
• server/src/api/ — add remote_control.rs: POST /api/agents/:agent_id/remote-control (body selects unattended|attended); talks to the GC server API, returns a viewer launch URL.
• server/src/db/ + server/migrations/ — add a remote_control_sessions record (or reuse tech_sessions from 010_tunnel_sessions.sql) for audit (agent_id, tech_id, connect_session_id, mode, timestamps).
• agent/src/transport/websocket.rs — run_command() :1050, execute_command() :971. Add a RemoteControl/launch path (or a dedicated command_type) that, on Windows, ensures the guru-connect agent binary is present (download + SHA-256 verify) and launches it in the requested mode passing device_id as the GC agent_id.
• agent/src/device_id.rs:1-99 — source of the stable cross-product identity. Read-only.
• dashboard/src/pages/AgentDetail.tsx:1893-1931 — tab/header + action-button area. Add the "Remote Control" button (open viewer URL on success).
• dashboard/src/components/CommandTerminal.tsx:60-106 — the canonical button→api.post()→useQuery action pattern to copy.
• dashboard/src/api/client.ts:293-310 — commandsApi pattern. Add remoteControlApi.start(agentId, mode).

Similar existing implementations (patterns to follow)

• Per-agent action dispatch (RMM): server/src/api/commands.rs:87-157 + agent reception agent/src/transport/websocket.rs:570-573 → execute_command() :971 → run_command() :1050. The broker's "launch guru-connect" instruction follows this exact send-command path.
• Dashboard action button → poll (RMM): dashboard/src/components/CommandTerminal.tsx:82-105 (useMutation → commandsApi.send → useQuery poll). The Remote Control button mirrors this.
• Per-agent credential issuance (RMM): server/src/api/enroll.rs:38-139 — generate_api_key("agk_") :103, hash_api_key() :104, plaintext returned once :138. Model connect_agent_keys provisioning on this.
• Support-code minting (GC): server/src/main.rs:382 create_code + server/src/db/support_codes.rs:24. The attended path reuses this directly.
• Agent WS auth handshake (RMM): agent/src/transport/websocket.rs:100-197 — how api_key/device_id are presented; the per-machine GC key provisioning should align with this lifecycle.
• Half-built generic tunnel (RMM), for reference only: server server/src/api/tunnel.rs:1-232 (routes NOT registered), server/src/db/tunnel.rs:1-152, server/migrations/010_tunnel_sessions.sql, agent agent/src/tunnel/mod.rs:62-197, WS msgs server/src/ws/mod.rs:287-300. The tech_sessions/tunnel_audit schema is a usable model for the remote-control audit record.

Database schema

guru-connect (existing — server/migrations/)

• connect_machines (001_initial_schema.sql:8) — agent_id UNIQUE, hostname, is_persistent, status, plus agent_version/organization/site/tags from 003_auto_update.sql.
• connect_sessions (001_initial_schema.sql:27) — id, machine_id, is_support_session, support_code, status. Add is_managed / source marker for broker-initiated sessions.
• connect_support_codes (001_initial_schema.sql:59) — reused unchanged for attended.
• connect_session_events (001_initial_schema.sql:43) — audit; emit broker/consent events here.
• releases (003_auto_update.sql:9) — has checksum_sha256; reuse for the verify-before-launch supply-chain guard.
• New: connect_agent_keys — id, agent_id FK, key_hash, created_at, revoked_at. Idempotent migration, hashed keys only (mirror RMM enroll pattern).

GuruRMM (existing — server/migrations/)

• Agent identity: agent_id (UUID, assigned at WS auth), device_id (agent/src/device_id.rs), site_id, per-agent agk_ key (hashed) from server/src/api/enroll.rs.
• tech_sessions / tunnel_audit (010_tunnel_sessions.sql) — model for the new remote_control_sessions audit table (or extend tech_sessions with a mode).

Migration discipline for both Rust servers: idempotent IF NOT EXISTS, let the server binary apply migrations on startup, cargo sqlx prepare if any query!() macro changes. See gururmm/sqlx-migrations standard.