guru-connect/docs/FEATURE_ROADMAP.md

GuruConnect — Feature Roadmap

Living roadmap for the GuruConnect product. Status markers: [ ] planned · [~] in consideration · [x] shipped. Priorities: P1 (blocking/MVP) · P2 (important) · P3 (nice-to-have). Specs live in docs/specs/SPEC-NNN-<slug>.md. Decisions in docs/ARCHITECTURE_DECISIONS.md.

GuruConnect is a standalone remote-support product (ScreenConnect/Splashtop-class) on our own Rust stack. It ships independently of GuruRMM and integrates with it via a versioned contract (see specs/native-remote-control/ and ADR-001).

Active direction: v2 reset — Phase 1 already landed (2026-05-30). Per SPEC-002, GuruConnect is being rebuilt above the salvaged Windows-internals cores. v2 Phase 1 (secure session core) is implemented in-place and deployed — secure-session-core Tasks 1–7 are committed (plan), and the 3 audit CRITICALs are closed and live in production (session-scoped viewer tokens + session-claim match, blacklist-on-WS, agent-plane rejects user JWTs via per-agent cak_ keys). The feature specs below (SPEC-003–009) are work-items inside the later v2 phases — see the mapping.

Remaining to formally exit Phase 1: secure-session-core Task 8 (end-to-end verification + /gc-audit --pass=security re-audit + the manual CRITICAL checks) and Code-Review sign-off on Tasks 3–5 (implemented without a local toolchain at the time; since built + deployed). Live HW-H.264 validation is also pending — raw+Zstd remains the shipping default. Sprint 0 (relay-auth CRITICAL hotfix) not needed — those fixes shipped in Tasks 2–3.

v2 phase mapping of current specs

Spec	v2 Phase	Note
SPEC-004 (identity / per-agent keys / session reaping / removal)	Phase 1 — secure session core	per-agent keys + session lifecycle are Phase 1's heart
SPEC-008 (structured errors + correlation IDs)	Phase 0/1 conventions	adopted as the cross-cutting error standard
SPEC-003 (machine inventory)	Phase 2 — dashboard/data	bake columns into the Phase-0 fresh schema
SPEC-005 (list view) · SPEC-006 (search) · SPEC-007 (installer)	Phase 2 — dashboard	built on the v2 dashboard + Phase-1 keys
SPEC-009 (documented API + tokens)	Phase 3 — integration contract	alongside /api/integration/v1/

Schema note: the v2 tenancy-ready schema + connect_agent_keys already exist (Task 1 / migration 004_v2_secure_session_core.sql). SPEC-004's per-agent-key identity binding is largely covered by Tasks 1–3; what remains of SPEC-004 (deterministic machine_uid, TTL session reaping, operator bulk removal) and SPEC-003's inventory columns are the additive Phase-2 migrations to fold onto that base.

---

Operational Tooling & Release Engineering

Bringing GC to parity with GuruRMM's release engineering. Full plan: SPEC-001.

• Code signing — Azure Trusted Signing in CI — P1 — sign the Windows agent .exe via jsign (TRUSTEDSIGNING) in Gitea Actions, reusing the shared ACG cert profile. (SPEC-001 §2)
• Automatic versioning — P1 — conventional-commit-driven version bump across agent/server/dashboard, embedded via build.rs. (SPEC-001 §3)
• Changelog generation & API — P2 — CHANGELOG.md + per-version changelogs from conventional commits, served at /api/changelog/.... (SPEC-001 §4)
• Feature-request workflow — P2 — /gc-feature-request skill producing docs/specs/SPEC-NNN-*.md and updating this roadmap. (SPEC-001 §1)
• Roadmap / ADR / spec tracking — P1 — this file + ARCHITECTURE_DECISIONS.md + docs/specs/. (SPEC-001 §5) — bootstrapped
• Coord-API registration — P3 — register guruconnect project_key + components (server, agent, dashboard) in the coordination API. (SPEC-001 §6)
• [~] Release distribution / update channels — P3 — beta→stable rollout with health metrics (mirrors RMM updates.rs). Deferred — larger subsystem, post-parity.

---

Core Remote Control

• Screen capture (DXGI primary, GDI fallback)
• Input injection (mouse/keyboard)
• Native viewer + guruconnect:// protocol handler
• Support-code (attended) and persistent (unattended) agent modes
• Protobuf-over-WSS transport, Zstd frame compression
• [~] React/TS web viewer (dashboard/src/components/RemoteViewer.tsx) — embeddable session viewer
• Headless Linux mode (direct TTY access) — P2 — Terminal-based remote access for Linux servers without GUI. PTY spawn (openpty), xterm.js web viewer, full ANSI/VT100 support. Enables server management, container debugging, emergency recovery via GuruConnect dashboard with audit logging. SSH replacement with centralized auth. (SPEC-012)
• Windows session selection and backstage mode — P2 — Enumerate and switch between Windows user sessions (Terminal Services/RDP/Fast User Switching) and access Session 0 (backstage) for system-level admin tasks. ScreenConnect parity: session selector shows all logged-on users, instant switching without reconnect. Backstage mode provides terminal/command interface for services management without disrupting any user desktop. Critical for multi-user server environments. (SPEC-013)
• Configurable notification overlay on viewer connection — P2 — Display a semi-transparent on-screen notification when a technician connects, showing technician name and company. Dashboard-configurable message template (supports {{technician_name}}, {{company}}, {{time}}), duration (5-60s), position (top-left/right, bottom-left/right, center), and dismissible behavior. Increases transparency and user awareness during remote support sessions. Compliance-friendly for privacy policies requiring user notification. (SPEC-015)
• Multi-monitor switching — P2
• File transfer — P3 (out of scope for native-remote-control v1)
• Session recording — P3 (out of scope for native-remote-control v1)

GuruRMM Integration

• Native remote control via broker — P2 — versioned integration contract so GuruRMM can launch/embed GC sessions on managed endpoints. Full spec: specs/native-remote-control/. (Contract owned by GC; RMM consumes it.)
• /api/integration/v1/ namespace + capability discovery — P2 (part of native-remote-control)
• Per-machine agent keys (replace shared AGENT_API_KEY) — P2
• Embedded-viewer framing allowlist (scoped frame-ancestors) — P2

Server / API

• JWT auth, Argon2id passwords, rate limiting, security headers
• Sessions / machines / support-codes / events
• Full machine inventory in the connection DB — P2 — persist per-machine device inventory (OS+locale+install, CPU/RAM, mfr/model/serial, external WAN IP captured server-side + private LAN IP + MAC, logged-on user, idle, time zone, uptime, local-admin) on connect_machines, refreshed each AgentStatus, shown in the dashboard machine detail (ScreenConnect "Guest Info" parity). Data layer for SPEC-002 Phase 2; closes GC side of agent-IP gap (todo 7459428e). [→ v2 Phase 2] (SPEC-003)
• Stable machine identity + session lifecycle reaping + operator removal — P1 — give the agent a deterministic machine-derived machine_uid (Windows MachineGuid-based) so the same box can't register duplicates (root cause: agent_id is a config-file random UUID that a portable/misconfigured run regenerates each launch); key registration on it; add TTL reaping + same-machine supersede as defense-in-depth; and admin-gated per-row + multi-select bulk removal of stale sessions/units. Identity must be bound to the per-machine agent key (spoof guard). Fixes ghost-session accumulation seen on the live console (15 sessions / 0 live, ~10 orphans for one machine). [→ v2 Phase 1] (SPEC-004)
• Machines list view — dual connection indicators + rich rows — P2 — ScreenConnect "Access"-list parity: per-row Host/Guest two-segment connection bar (Guest=agent online, Host=viewer connected, with names + durations) and rich inline metadata (company, site, device type, tags, logged-on user + idle, client version in red when outdated). Server-enriches /api/machines with live session state + SPEC-003 inventory. [→ v2 Phase 2] (SPEC-005)
• Machines "by Company" tree nav with per-company counts — P3 — left-nav grouping sidebar (screenshot parity). Follow-up sub-item of SPEC-005.
• Universal machine search ("everything is searchable") — P2 — server-side ?q= on /api/machines matching case-insensitive substring across ALL attributes (OS, logged-on user, external/private IP, company, site, tag, serial, MAC, version, …), pg_trgm GIN-indexed; multi-term AND + optional field-scoped syntax (os:, user:, ip:). Replaces the hostname-only client filter. Depends on SPEC-003 (attrs must be persisted). [→ v2 Phase 2] (SPEC-006)
• Managed-agent installer builder ("Build Installer") — P2 — dashboard wizard to build a pre-labeled persistent-agent installer (Name/Company/Site/Department/Device Type/Tag/Type) with Download / Copy URL / Send Link, reusing the existing embed-config download path; adds department + device_type to EmbeddedConfig/AgentStatus so labels persist at install time. Pairs with revocable per-machine keys; signature-vs-appended-config is the key open question. [→ v2 Phase 2] (SPEC-007)
• Valuable error messages (structured errors + no silent swallows) — P2 — one structured API error envelope with stable codes + a correlation id that also lands in the logs; contextual tracing on server/agent; sweep the 37 let _ = swallows (the pattern that hid the migration-005 bug); dashboard surfaces the real cause + id instead of a generic line. [→ v2 Phase 0/1 conventions] (SPEC-008)
• Feature-rich, fully-documented management API — P2 — everything the console can do, callable by API: OpenAPI 3.x generated from code (utoipa) + browsable docs at /api/docs, long-lived revocable scoped API tokens (PAT-style, distinct from the 24h JWT + agent keys), an API-completeness gap audit, and consistent pagination/error conventions. Distinct from the ADR-001 RMM integration contract. [→ v2 Phase 3] (SPEC-009)
• Branding and white-label configuration — P2 — Allow MSPs to customize logo, colors, and product name for white-labeled remote support. Dashboard admin settings page with logo upload (PNG/SVG, max 2MB), brand hue slider (OKLCH 0-360°, default 184=cyan), product name override, company name, and favicon. Agent tray tooltip uses custom product name from registry. Singleton database table with public GET endpoint for unauthenticated rendering. CSS variables (--brand-hue, --accent, --panel) for dynamic theming. [→ v2 Phase 2] (SPEC-014)
• Programmatic session pre-create + viewer-token (integration contract) — P2

Security & Infrastructure

• Phase-1 security hardening (SEC-1..5), systemd units, backups
• CI security audit gate (cargo audit) wired to release — P2

Future Considerations

• Cross-platform agent support (macOS and Linux) — P2 — Enable remote control beyond Windows with native agents for macOS 12+ and Ubuntu 22.04+ LTS. Platform abstraction layer for capture/input/encoding, VideoToolbox (macOS) and VA-API (Linux) H.264 encoding, .app/.deb/.rpm packaging. Unblocks multi-platform MSP adoption. (SPEC-010)
• Mobile agent support (iOS and Android as remote control targets) — P3 — Native mobile apps for supervised support sessions. iOS: ReplayKit screen sharing (view-only, no input injection due to sandboxing). Android: MediaProjection screen capture + Accessibility Service input injection. Support-code authentication, push notifications (APNs/FCM), consent-first model. Foreground-only operation (OS limitation). Distinct from GuruRMM SPEC-017 (MDM/management). (SPEC-011)
• Auto-update for the agent — P3