guru-connect/specs/v2-secure-session-core/shape.md

v2 Secure Session Core — Shape & Constraints

Spec created: 2026-05-29 Parent: docs/specs/SPEC-002-v2-modernization-architecture.md → Phase 1 Audit being fixed: 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 §6 Phase 1, §3 (architecture), §8 (security map).
• 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/ (per-agent keys, session pre-create, viewer tokens, consent — Tasks 2/3/5/6 there).