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

v2 Secure Session Core — Code References

All paths relative to projects/msp-tools/guru-connect/. Line numbers are from the v1 tree as of the 2026-05-29 audit; treat them as anchors, re-grep before editing.

Files that will be REBUILT (v1 broken/unsafe — see audit)

• server/src/relay/mod.rs — the relay. agent_ws_handler:55, validate_agent_api_key:224 (the JWT-as-agent-key CRITICAL — delete the JWT branch), viewer_ws_handler:242 (no per-session authz, no blacklist check — the two other CRITICALs), handle_viewer_connection:595, input forward :669 (no throttle). No WS frame-size caps anywhere. Rebuild auth + add caps + throttle (Tasks 2–4).
• server/src/middleware/rate_limit.rs + middleware/mod.rs:3-11 — rate limiting commented out and non-compiling. Rebuild + wire (Task 4).
• server/src/db/support_codes.rs — codes accepted in pending OR connected state (reusable); 6-digit numeric. Add single-use consume + widen (Task 4).
• server/src/db/{sessions,machines,events,users}.rs, server/src/db/mod.rs — flat, no tenant_id, no agent-key table. Rebuild with tenancy-ready schema + agent_keys.rs (Task 1).
• server/src/session/mod.rs — persistent reattach keyed on query-string agent_id:98 (no crypto proof). Bind to authenticated identity; reconcile on startup (Task 3).
• server/src/auth/{mod,jwt,token_blacklist,password}.rs — keep Argon2id + exp enforcement; add per-agent-key validation + session-scoped viewer-token minting; expose blacklist to the WS layer (Task 2).
• server/migrations/00{1,2,3}_*.sql — v1 schema. New v2 migrations layer on top (Task 1).

Files that will be SALVAGED (proven — extend, don't rewrite)

• agent/src/capture/{dxgi,gdi,display,mod}.rs — screen capture (DXGI primary, GDI fallback, multi-display). Feed the encoder (Task 7).
• agent/src/input/{keyboard,mouse,mod}.rs — input injection. Extend keyboard.rs for scan-code + extended-key fidelity (Task 6).
• agent/src/bin/sas_service.rs — the privileged Ctrl+Alt+Del (SendSAS) helper. Wire to SpecialKeyEvent.CTRL_ALT_DEL (Task 6).
• agent/src/encoder/{mod,raw}.rs — raw BGRA + Zstd path. Keep as the fallback; add h264.rs (Task 7).
• agent/src/transport/{mod,websocket.rs} — prost-over-WSS codec (audit-confirmed correct). Reuse; rebuild only the auth handshake.
• proto/guruconnect.proto — well-modeled. Extend: ConsentRequest/ConsentResponse (Task 5), AgentStatus codec capability + SessionResponse codec (Task 7); KeyEvent/SpecialKeyEvent already cover full fidelity.
• server/static/viewer.html:196-489 — the correct protobuf parser (reference; not used in Phase 1's native path).

Similar existing implementations to follow

• Per-agent hashed keys + issuance + session pre-create + viewer tokens + consent: specs/native-remote-control/plan.md Tasks 2/3/5/6 — the prior shape-spec that already designed these for the RMM-integration case. Phase 1 makes them the core model, not integration-only.
• Blacklist already consulted for REST: server/src/auth/mod.rs:116 — replicate this check on the WS paths (the gap that caused the viewer-WS blacklist-bypass CRITICAL).
• Framing allowlist pattern: server/src/middleware/security_headers.rs:30 (frame-ancestors 'none') — untouched in Phase 1; the per-route allowlist is Phase 3.
• GuruRMM enrollment (agk_ keys, POST /api/enroll, hashed storage): projects/msp-tools/guru-rmm/ server/src/api/enroll.rs + db/enroll.rs — the Option-3 pattern GC's cak_ keys mirror.

Database schema

v1 tables (connect_machines, connect_sessions, connect_session_events, connect_support_codes, users, user_permissions, user_client_access, releases) carry over with new nullable tenant_id columns + a seed tenants table + new connect_agent_keys table (Task 1). UUID PKs, TIMESTAMPTZ, soft-delete preference, FK ON DELETE CASCADE (GC + RMM convention). Idempotent migrations, runtime sqlx::query(), applied on startup — see .claude/standards/gururmm/sqlx-migrations.md.