From 03f62d413fc72e7aa74f3b23389747cb69e0e4e6 Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Sat, 30 May 2026 17:26:47 -0700 Subject: [PATCH] docs: annotate roadmap with v2-first direction + phase mapping Mark SPEC-003..009 as work-items inside the SPEC-002 v2 phases (not standalone v1 backlog): banner records the v2-reset decision + the Sprint-0 relay-auth CRITICAL hotfix, a phase-mapping table (004->P1, 008->P0/1, 003/005/006/007->P2, 009->P3), inline [-> v2 Phase N] tags per spec, and a note to bake SPEC-003 inventory cols + SPEC-004 machine_uid + connect_agent_keys into the Phase-0 fresh schema. Sprint planning 2026-05-30 (Mike: v2 reset first). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/FEATURE_ROADMAP.md | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/docs/FEATURE_ROADMAP.md b/docs/FEATURE_ROADMAP.md index 2923612..938f282 100644 --- a/docs/FEATURE_ROADMAP.md +++ b/docs/FEATURE_ROADMAP.md @@ -8,6 +8,26 @@ GuruConnect is a standalone remote-support product (ScreenConnect/Splashtop-clas stack. It ships independently of GuruRMM and integrates with it via a versioned contract (see `specs/native-remote-control/` and ADR-001). +> **Active direction (2026-05-30): v2 reset.** Per [SPEC-002](specs/SPEC-002-v2-modernization-architecture.md), +> GuruConnect is being rebuilt above the salvaged Windows-internals cores. The feature specs below +> (SPEC-003–009) are **work-items inside the v2 phases**, not independent v1 backlog — see the mapping. +> **Sprint 0 (do first):** surgical v1 hotfix closing the 3 relay-auth CRITICALs (delete the +> JWT-as-agent-key branch; enforce blacklist + session-claim checks on the viewer WS) — the bypasses +> are live and the full v2 rebuild is multi-month. + +### 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: SPEC-002 Phase 0's "fresh v2 schema" should already carry SPEC-003's inventory columns, +> SPEC-004's `machine_uid`, and `connect_agent_keys` — born into v2, not retrofitted as later migrations. + --- ## Operational Tooling & Release Engineering @@ -47,14 +67,14 @@ Bringing GC to parity with GuruRMM's release engineering. Full plan: [SPEC-001]( - [x] JWT auth, Argon2id passwords, rate limiting, security headers - [x] 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). ([SPEC-003](specs/SPEC-003-machine-inventory.md)) -- [ ] **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). ([SPEC-004](specs/SPEC-004-session-lifecycle-and-removal.md)) -- [ ] **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. ([SPEC-005](specs/SPEC-005-machines-list-view-parity.md)) +- [ ] **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](specs/SPEC-003-machine-inventory.md)) +- [ ] **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](specs/SPEC-004-session-lifecycle-and-removal.md)) +- [ ] **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](specs/SPEC-005-machines-list-view-parity.md)) - [ ] 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). ([SPEC-006](specs/SPEC-006-universal-machine-search.md)) -- [ ] **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. ([SPEC-007](specs/SPEC-007-managed-agent-installer-builder.md)) -- [ ] **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. ([SPEC-008](specs/SPEC-008-valuable-error-messages.md)) -- [ ] **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. ([SPEC-009](specs/SPEC-009-feature-rich-documented-api.md)) +- [ ] **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](specs/SPEC-006-universal-machine-search.md)) +- [ ] **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](specs/SPEC-007-managed-agent-installer-builder.md)) +- [ ] **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](specs/SPEC-008-valuable-error-messages.md)) +- [ ] **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](specs/SPEC-009-feature-rich-documented-api.md)) - [ ] Programmatic session pre-create + viewer-token (integration contract) — P2 ## Security & Infrastructure