diff --git a/CLAUDE.md b/CLAUDE.md index 74a8d6e..d09cebd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,117 +1,200 @@ -# GuruConnect +# GuruConnect - Project Guidelines -Remote desktop solution similar to ScreenConnect, integrated with GuruRMM. +## Overview -## Project Overview - -GuruConnect provides remote screen control and backstage tools for Windows systems. -It's designed to be fast, secure, and enterprise-ready. +GuruConnect is a remote desktop solution for MSPs, similar to ConnectWise ScreenConnect. It provides real-time screen sharing, remote control, and support session management. ## Architecture ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Dashboard │◄───────►│ GuruConnect │◄───────►│ GuruConnect │ -│ (React) │ WSS │ Server (Rust) │ WSS │ Agent (Rust) │ +│ (HTML/JS) │ WSS │ Server (Rust) │ WSS │ Agent (Rust) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ + │ ▼ + │ ┌─────────────────┐ + └──────────────────►│ PostgreSQL │ + └─────────────────┘ ``` -## Directory Structure +## Design Constraints -- `agent/` - Windows remote desktop agent (Rust) -- `server/` - Relay server (Rust + Axum) -- `dashboard/` - Web viewer (React, to be integrated with GuruRMM) -- `proto/` - Protobuf protocol definitions +### Agent (Windows) +- **Target OS:** Windows 7 SP1 and later (including Server 2008 R2+) +- **Single binary:** Agent and viewer in one executable +- **No runtime dependencies:** Statically linked, no .NET or VC++ redistributables +- **Protocol handler:** `guruconnect://` URL scheme for launching viewer +- **Tray icon:** System tray presence with status and exit option +- **UAC aware:** Graceful handling of elevated/non-elevated contexts +- **Auto-install:** Detects if not installed and offers installation -## Building +### Server (Linux) +- **Target OS:** Ubuntu 22.04 LTS +- **Framework:** Axum for HTTP/WebSocket +- **Database:** PostgreSQL with sqlx (compile-time checked queries) +- **Static files:** Served from `server/static/` +- **No containers required:** Runs as systemd service or direct binary -### Prerequisites +### Protocol +- **Wire format:** Protocol Buffers (protobuf) for ALL client-server messages +- **Transport:** WebSocket over TLS (wss://) +- **Compression:** Zstd for video frames +- **Schema:** `proto/guruconnect.proto` is the source of truth -- Rust 1.75+ (install via rustup) -- Windows SDK (for agent) -- protoc (Protocol Buffers compiler) +## Security Rules -### Build Commands +### Authentication +- **Dashboard/API:** JWT tokens required for all endpoints except `/health` and `/api/auth/login` +- **Viewer WebSocket:** JWT token required in `token` query parameter +- **Agent WebSocket:** Must provide either: + - Valid support code (for ad-hoc support sessions) + - Valid API key (for persistent/managed agents) +- **Never** accept unauthenticated agent connections +### Credentials +- **Never** hardcode secrets in source code +- **Never** commit credentials to git +- Use environment variables for all secrets: + - `JWT_SECRET` - JWT signing key + - `DATABASE_URL` - PostgreSQL connection string + - `AGENT_API_KEY` - Optional shared key for agents + +### Password Storage +- Use Argon2id for password hashing +- Never store plaintext passwords + +## Coding Standards + +### Rust +- Use `tracing` crate for logging (not `println!` or `log`) +- Use `anyhow` for error handling in binaries +- Use `thiserror` for library error types +- Prefer `async`/`await` over blocking code +- Run `cargo clippy` before commits + +### Logging Levels +- `error!` - Failures that need attention +- `warn!` - Unexpected but handled situations +- `info!` - Normal operational messages (startup, connections, sessions) +- `debug!` - Detailed debugging info +- `trace!` - Very verbose, message-level tracing + +### Naming +- Rust: `snake_case` for functions/variables, `PascalCase` for types +- Protobuf: `PascalCase` for messages, `snake_case` for fields +- Database: `snake_case` for tables and columns + +## Build & Version + +### Version Format +- Semantic versioning: `MAJOR.MINOR.PATCH` +- Build identification: `VERSION-GITHASH[-dirty]` +- Example: `0.1.0-48076e1` or `0.1.0-48076e1-dirty` + +### Build Info (Agent) +The agent embeds at compile time: +- `VERSION` - Cargo.toml version +- `GIT_HASH` - Short commit hash (8 chars) +- `GIT_BRANCH` - Branch name +- `GIT_DIRTY` - "clean" or "dirty" +- `BUILD_TIMESTAMP` - UTC build time +- `BUILD_TARGET` - Target triple + +### Commands ```bash -# Build all (from workspace root) -cargo build --release +# Build agent (Windows) +cargo build -p guruconnect --release -# Build agent only -cargo build -p guruconnect-agent --release +# Build server (Linux, from Linux or cross-compile) +cargo build -p guruconnect-server --release --target x86_64-unknown-linux-gnu -# Build server only -cargo build -p guruconnect-server --release +# Check version +./guruconnect --version # Short: 0.1.0-48076e1 +./guruconnect version-info # Full details ``` -### Cross-compilation (Agent for Windows) +## Database Schema -From Linux build server: -```bash -# Install Windows target -rustup target add x86_64-pc-windows-msvc +### Key Tables +- `users` - Dashboard users (admin-created only) +- `machines` - Registered agents (persistent) +- `sessions` - Connection sessions (historical) +- `events` - Audit log +- `support_codes` - One-time support codes -# Build (requires cross or appropriate linker) -cross build -p guruconnect-agent --target x86_64-pc-windows-msvc --release +### Conventions +- Primary keys: `id UUID DEFAULT gen_random_uuid()` +- Timestamps: `created_at TIMESTAMPTZ DEFAULT NOW()` +- Soft deletes: Prefer `deleted_at` over hard deletes for audit trail +- Foreign keys: Always with `ON DELETE CASCADE` or explicit handling + +## File Structure + +``` +guru-connect/ +├── agent/ # Windows agent + viewer +│ ├── src/ +│ │ ├── main.rs # CLI entry point +│ │ ├── capture/ # Screen capture (DXGI, GDI) +│ │ ├── encoder/ # Video encoding +│ │ ├── input/ # Mouse/keyboard injection +│ │ ├── viewer/ # Native viewer window +│ │ ├── transport/ # WebSocket client +│ │ ├── session/ # Session management +│ │ ├── tray/ # System tray +│ │ └── install.rs # Installation & protocol handler +│ ├── build.rs # Build script (protobuf, version info) +│ └── Cargo.toml +├── server/ # Linux relay server +│ ├── src/ +│ │ ├── main.rs # Server entry point +│ │ ├── relay/ # WebSocket relay handlers +│ │ ├── session/ # Session state management +│ │ ├── auth/ # JWT authentication +│ │ ├── api/ # REST API handlers +│ │ └── db/ # Database operations +│ ├── static/ # Dashboard HTML/JS/CSS +│ │ ├── login.html +│ │ ├── dashboard.html +│ │ ├── viewer.html +│ │ └── downloads/ # Agent binaries +│ ├── migrations/ # SQL migrations +│ └── Cargo.toml +├── proto/ # Protocol definitions +│ └── guruconnect.proto +└── CLAUDE.md # This file ``` -## Development +## Deployment -### Running the Server +### Server (172.16.3.30) +- **Binary:** `/home/guru/guru-connect/target/x86_64-unknown-linux-gnu/release/guruconnect-server` +- **Static:** `/home/guru/guru-connect/server/static/` +- **Startup:** `~/guru-connect/start-server.sh` +- **Port:** 3002 (proxied via NPM to connect.azcomputerguru.com) -```bash -# Development -cargo run -p guruconnect-server +### Agent Distribution +- **Download URL:** https://connect.azcomputerguru.com/downloads/guruconnect.exe +- **Auto-update:** Not yet implemented (future feature) -# With environment variables -DATABASE_URL=postgres://... JWT_SECRET=... cargo run -p guruconnect-server -``` +## Issue Tracking -### Testing the Agent +Use Gitea issues: https://git.azcomputerguru.com/azcomputerguru/guru-connect/issues -The agent must be run on Windows: -```powershell -# Run from Windows -.\target\release\guruconnect-agent.exe -``` +Reference issues in commits: +- `Fixes #1` - Closes the issue +- `Related to #1` - Links without closing -## Protocol +## Testing Checklist -Uses Protocol Buffers for efficient message serialization. -See `proto/guruconnect.proto` for message definitions. - -Key message types: -- `VideoFrame` - Screen frames (raw+zstd, VP9, H264) -- `MouseEvent` - Mouse input -- `KeyEvent` - Keyboard input -- `SessionRequest/Response` - Session management - -## Encoding Strategy - -| Scenario | Encoding | -|----------|----------| -| LAN (<20ms RTT) | Raw BGRA + Zstd + dirty rects | -| WAN + GPU | H264 hardware | -| WAN - GPU | VP9 software | - -## Key References - -- RustDesk source: `~/claude-projects/reference/rustdesk/` -- GuruRMM: `~/claude-projects/gururmm/` -- Plan: `~/.claude/plans/shimmering-wandering-crane.md` - -## Phase 1 MVP Goals - -1. DXGI screen capture with GDI fallback -2. Raw + Zstd encoding with dirty rectangle detection -3. Mouse and keyboard input injection -4. WebSocket relay through server -5. Basic React viewer - -## Security Considerations - -- All connections use TLS -- JWT authentication for dashboard users -- API key authentication for agents -- Session audit logging -- Optional session recording (Phase 4) +Before releasing: +- [ ] Agent connects with support code +- [ ] Agent connects with API key +- [ ] Viewer connects with JWT token +- [ ] Unauthenticated connections rejected +- [ ] Screen capture works (DXGI primary, GDI fallback) +- [ ] Mouse/keyboard input works +- [ ] Chat messages relay correctly +- [ ] Protocol handler launches viewer +- [ ] Tray icon shows correct status