sriram
95 lines
4.1 KiB
Markdown
95 lines
4.1 KiB
Markdown
# Remote Access Platform — Alpha
|
||
|
||
A self-hostable remote support platform for IT teams: technicians log in to a web
|
||
console, see their team's machines, and start a screen-share + remote-control
|
||
session to any online machine after the end user grants consent. Built to the
|
||
spec in `PRD-remote-access-platform.md`.
|
||
|
||
This alpha implements the PRD's P0 requirements: authenticated console, **MFA**,
|
||
**RBAC**, **machine enrollment**, **per-session consent**, **WebRTC screen
|
||
streaming + remote input**, and an **immutable audit log**.
|
||
|
||
```
|
||
remote-access-app/
|
||
├── server/ Backend: HTTP API + WebSocket signaling + SQLite
|
||
│ ├── server.js Auth, MFA, machines, audit API + signaling broker
|
||
│ ├── auth.js scrypt passwords, TOTP MFA, tokens (no external auth deps)
|
||
│ ├── db.js Schema via Node's built-in node:sqlite
|
||
│ ├── public/ Web console (index.html) + remote viewer (viewer.html)
|
||
│ └── test/e2e.js 26-check end-to-end test of the whole backend flow
|
||
└── agent/ Native host agent (Electron)
|
||
├── main.js Consent window, screen source, OS input injection
|
||
├── input/inject.js Mouse/keyboard injection via nut-js (Win32 SendInput)
|
||
└── renderer/ Agent UI + WebRTC screen capture
|
||
```
|
||
|
||
## Quick start
|
||
|
||
### 1. Server (any OS, Node 22.5+)
|
||
|
||
```bash
|
||
cd server
|
||
npm install # only dependency is `ws`
|
||
npm start # serves http://localhost:8090
|
||
```
|
||
|
||
Open **http://localhost:8090**, click **Register team**, then set up MFA
|
||
(add the shown secret to Google Authenticator / Authy / 1Password and enter a code).
|
||
Log in, and enroll a machine — you'll get an `AGENT_ENROLL_TOKEN`.
|
||
|
||
### 2. Agent (on the Windows/macOS PC to be controlled)
|
||
|
||
```bash
|
||
cd agent
|
||
npm install # installs Electron + nut-js (input injection)
|
||
set SERVER_URL=http://<server-ip>:8090 # Windows
|
||
set AGENT_ENROLL_TOKEN=<token from console>
|
||
npm start
|
||
```
|
||
|
||
The agent window comes online; the machine shows green in the console.
|
||
Click **Connect** in the console — the agent shows a consent prompt. On **Allow**,
|
||
the technician sees the live screen and can control it. A red banner stays on the
|
||
host screen for the whole session, and every step is written to the audit log.
|
||
|
||
> Set a machine to **unattended** at enrollment to skip the consent prompt
|
||
> (for servers / headless machines), per the PRD's unattended-access policy.
|
||
|
||
## What's tested (in this sandbox)
|
||
|
||
```
|
||
cd server && npm test # 26/26 checks pass
|
||
cd agent && npm run test:input # 5/5 input-mapping checks pass
|
||
```
|
||
|
||
The e2e test drives the real backend: register → enable MFA → login (password +
|
||
TOTP) → enroll machine → agent connects → technician requests session → consent →
|
||
SDP/ICE relay → session end → audit verification → consent-denial path.
|
||
|
||
## What requires real hardware (not testable in a headless sandbox)
|
||
|
||
- **OS input injection** runs through `nut-js` (Win32 `SendInput` on Windows,
|
||
`CGEvent` on macOS). Without it installed, `inject.js` degrades to a safe
|
||
logging no-op so the agent still runs. Verify on a real desktop.
|
||
- **Screen capture** uses Electron's `desktopCapturer` / `getDisplayMedia`.
|
||
|
||
## Architecture notes
|
||
|
||
- **Media is peer-to-peer.** The server only brokers signaling (SDP/ICE) and
|
||
consent; screen frames and input never pass through it. Channels are
|
||
DTLS-encrypted by WebRTC.
|
||
- **NAT traversal** uses a public STUN server. ~10–15% of connections behind
|
||
symmetric NATs will need a **TURN relay** (coturn) — the next infra item.
|
||
- **Auth** uses scrypt password hashing and RFC-6238 TOTP, implemented on Node's
|
||
built-in `crypto` — no `bcrypt`/`jsonwebtoken`/`speakeasy` dependencies.
|
||
- **Storage** is `node:sqlite` (built into Node 22.5+), so the backend has a
|
||
single runtime dependency (`ws`).
|
||
|
||
## Gaps before production (from PRD §5)
|
||
|
||
1. **TURN relay** for non-P2P connections (coturn).
|
||
2. **macOS/Linux agents** + code-signed installers; packaged Windows binary.
|
||
3. **File transfer, clipboard sync, multi-monitor** (PRD P1).
|
||
4. **SSO, session recording, SOC 2** (PRD P1/T8).
|
||
5. Harden signaling: rate limiting, per-session authz checks, CSRF on cookie API.
|