# 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).