Mike Swanson
81e4b99a34
All checks were successful
Phase 1 of SPEC-002 (GuruConnect v2). Keystone-first plan: Tasks 1-4 rebuild the auth/session core that closes the 3 audit CRITICALs by design (per-agent cak_ keys, plane separation, session-scoped viewer tokens, blacklist+frame-caps+throttle on the relay WS, single-use rate-limited support codes, tenancy-ready schema); Tasks 5-7 deliver attended consent, native full key fidelity (WH_KEYBOARD_LL hook, scan-code injection, SAS Ctrl+Alt+Del), and HW H.264 with raw+Zstd fallback. plan/shape/references/ standards. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
76 lines
5.0 KiB
Markdown
76 lines
5.0 KiB
Markdown
# v2 Secure Session Core — Shape & Constraints
|
|
|
|
> Spec created: 2026-05-29
|
|
> Parent: [`docs/specs/SPEC-002-v2-modernization-architecture.md`](../../docs/specs/SPEC-002-v2-modernization-architecture.md) → Phase 1
|
|
> Audit being fixed: [`reports/2026-05-29-gc-audit.md`](../../reports/2026-05-29-gc-audit.md)
|
|
|
|
## What this is
|
|
|
|
The foundation phase of the GuruConnect v2 rebuild: a rebuilt auth + session model that makes the
|
|
three audit CRITICALs structurally impossible, plus the native viewer delivering full keyboard
|
|
fidelity (Win+R, Ctrl+C/V, Ctrl+Alt+Del) and a hardware H.264 video path with a raw+Zstd fallback.
|
|
A technician can run a secure attended (consent-gated) or unattended (per-agent-key) session with
|
|
full control, end to end, with zero relay-plane auth holes.
|
|
|
|
## What this is NOT (out of scope — deferred to later v2 phases)
|
|
|
|
- **File transfer** (clipboard cut/paste + drag-and-drop) — SPEC-002 §4.4, **Phase 2**. Clipboard
|
|
*text/image* sync may land here; file `CF_HDROP` transfer does not.
|
|
- **Web / WebRTC viewer** — **Phase 2**. Phase 1 is the native viewer only.
|
|
- **The dashboard** (machines/sessions/codes/releases UI) — **Phase 2**. Phase 1 exposes the REST/WS
|
|
surface and the native viewer; the web dashboard is rebuilt next.
|
|
- **The `/api/integration/v1/` RMM contract** + embedded viewer + programmatic session pre-create —
|
|
**Phase 3**.
|
|
- **Multi-tenancy activation** (partner→client isolation, dev impersonation, SSO) — **Phase 4**. Phase 1
|
|
ships the tenancy-*ready* schema (nullable `tenant_id`, default tenant) but does NOT enforce isolation.
|
|
- **Session recording, BACKSTAGE mode, multi-monitor switching, quality-preset UI** — deferred.
|
|
- **Drag-out (remote→local) file transfer** — Phase 2+ (the hard `IDataObject` case).
|
|
- **macOS/Linux agents** — Windows-first remains.
|
|
|
|
## Hard constraints
|
|
|
|
- **Native-first, custom protobuf-over-WSS.** No WebRTC in this phase. Full key fidelity is the reason
|
|
(browsers can't deliver Win key / Ctrl+Alt+Del).
|
|
- **No TOML/config files for endpoints** (RMM rule): relay URL compiled into the agent; identity baked
|
|
at generation or in the registry; server secrets via env/SOPS only. Never an `agent.toml`.
|
|
- **Salvage, don't rewrite, the proven cores** (SPEC-002 §2): DXGI/GDI capture, input injection, the
|
|
SAS helper, the prost codec, the proto, the Gitea-Actions CI all carry over.
|
|
- **Single statically-linked Windows agent** (no .NET/VC++ redist); Win7 SP1+ target → raw+Zstd codec
|
|
fallback is mandatory for machines without a HW H.264 encoder.
|
|
- **Rust/Axum server, PostgreSQL + sqlx**; new queries use runtime `sqlx::query()`; idempotent
|
|
migrations applied on server startup.
|
|
- **No new standing credential granted to any party** — viewer tokens are short-lived and
|
|
session-scoped; agent keys are per-agent and revocable.
|
|
- **Clean wholesale cutover** — no v1 data migration; v2 replaces v1 at connect.azcomputerguru.com once
|
|
this phase is live.
|
|
|
|
## Key decisions (from SPEC-002, locked 2026-05-29)
|
|
|
|
- **Per-agent hashed keys** (`connect_agent_keys`, `cak_…`) replace the shared `AGENT_API_KEY` (RMM
|
|
Option 3). Shared key remains only as a deprecated fallback.
|
|
- **Plane separation:** agent auth = per-agent key OR support code; viewer auth = JWT. The
|
|
`validate_agent_api_key` JWT-accepting branch (`relay/mod.rs:224`) is **deleted**.
|
|
- **Session-scoped viewer tokens:** a viewer JWT is minted (~5 min TTL) only by an authenticated +
|
|
authorized request for a specific session; the WS verifies signature + expiry + blacklist + that the
|
|
token's session claim matches the requested `session_id`.
|
|
- **Single-use support codes:** atomic consume on first agent bind; widened entropy (human-readable,
|
|
not 6-digit numeric); rate-limit + lockout on the validate endpoint.
|
|
- **Bounded relay:** explicit `max_message_size`/`max_frame_size` on both WS upgrades; bounded +
|
|
rate-limited input queue.
|
|
- **Attended consent:** new proto `ConsentRequest`/`ConsentResponse`; the technician sees the session
|
|
only after the end user accepts on their machine.
|
|
- **Tenancy-ready, not tenant-yet:** nullable `tenant_id` on all scoped tables, default tenant; a
|
|
tenancy helper resolves to the default now and flips to enforcement in Phase 4 — no schema rewrite.
|
|
- **Codec:** H.264 default (Media Foundation, HW-accelerated), HEVC opt-in, raw+Zstd fallback,
|
|
negotiated per session via `AgentStatus` capability + `SessionResponse`.
|
|
|
|
## Priority
|
|
|
|
P1 — foundational; blocks all later v2 phases and fixes the live-production security CRITICALs.
|
|
|
|
## Roadmap reference
|
|
|
|
- [`docs/specs/SPEC-002-v2-modernization-architecture.md`](../../docs/specs/SPEC-002-v2-modernization-architecture.md) §6 Phase 1, §3 (architecture), §8 (security map).
|
|
- [`docs/FEATURE_ROADMAP.md`](../../docs/FEATURE_ROADMAP.md) → "Server/API" (the false `[x]` rate-limiting split), "Security & Infrastructure", and the GuruRMM-Integration "Per-machine agent keys" item.
|
|
- Prior shape-spec art: [`specs/native-remote-control/`](../native-remote-control/) (per-agent keys, session pre-create, viewer tokens, consent — Tasks 2/3/5/6 there).
|