ghostterm 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -1,108 +1,27 @@
 # Changelog
 
-## 1.3.0 (2026-03-17)
+## 2.0.0 (2026-03-17)
 
-### Stability (35 issues fixed)
-- **Graceful shutdown** — SIGTERM/SIGINT properly kills all PTY sessions, closes relay, cleans PID file
-- **Heartbeat timeout** — detects dead relay within 40s, forces reconnect
-- **Buffer backpressure** — output buffer truncation now tracks `bufferStart` for correct delta sync
-- **Message queue** — queues up to 50 messages while disconnected, flushes on reconnect
-- **Spawn error handling** — node-pty spawn failure no longer crashes companion
-- **Create-session lock** — prevents duplicate session creation from rapid requests
-- **Create-session cooldown** — 1 second minimum between creates
-- **Input size limit** — rejects input payloads over 64KB
-- **Standby timer dedup** — prevents multiple standby preparation timers
-- **Login server cleanup** — closes HTTP server immediately on auth error
-- **VBS launcher cleanup** — deletes temporary launcher.vbs after use
-- **Send error handling** — ws.send wrapped in try-catch
-- **Worker stdio fix** — Windows worker inherits stdin for node-pty console compatibility
-
-### Relay Improvements (deployed separately)
-- Graceful shutdown, email validation, dead pair code reuse, dual companion protection
-- Sessions list caching for instant mobile reconnect
-- Message forwarding validation, health endpoint hardened
-
-## 1.2.3 (2026-03-17)
-
-### Features (Frontend)
-- **Long-press acceleration** — Backspace, arrow keys, Space, scroll buttons repeat with increasing speed (150ms → 30ms)
-- **Tap feedback** — all buttons show scale + color animation on press
-- **Paste button always visible** — shows "no file" when empty, glows on upload
-- **iOS file picker fix** — transparent file input overlay (bypasses iOS trusted gesture restriction)
-- **Service Worker removed** — fixes stale cache preventing updates
-- **Landing page SEO** — Open Graph tags, Twitter cards, PWA meta
-
-### Bug Fixes
-- **Cloudflare deploy** — must use `--branch=main` for production (was deploying to Preview)
-- **D-pad escape sequences** — `data-repeat` attribute now properly converts `\x1b` to ESC character
-- **Removed debug console.log** — no longer leaks sessionId to browser console
-
-## 1.2.2 (2026-03-17)
-
-### Bug Fixes
-- **Windows fully hidden** — use VBS launcher instead of `windowsHide` (which still showed in taskbar)
-
-## 1.2.1 (2026-03-17)
-
-### Bug Fixes
-- **Windows background mode** — fixed node-pty crash in detached mode
-- **Supervisor crash loop** — fixed `--supervisor` arg being caught by "already running" check
-
-## 1.2.0 (2026-03-17)
+### Breaking Changes
+- **Complete rewrite**: P2P architecture replaces relay server
+- Command changed from `npx ghostterm` to same — but now connects directly via WebRTC
+- No more Tailscale/relay dependency — works over any network
 
 ### Features
-- **Background mode by default** — `npx ghostterm` now runs in the background automatically, no terminal window
-- **CLI commands** — `npx ghostterm stop`, `npx ghostterm status`, `npx ghostterm logs`
-- **First-run login** — opens browser for Google sign-in in foreground, then auto-restarts as daemon
-- **Duplicate detection** — prevents starting multiple instances
-- **12345 numpad popup** — quick number selection for CLI surveys/prompts (raw keypress without Enter)
-- **Screen button** — renamed from "Shot" for clarity
-- **Paste button shows filename** — after uploading, displays shortened filename instead of generic "Paste"
-- **Session persistence** — refreshing the page restores your last active terminal session
-- **PM2 support** — can run in background without a terminal window
-
-### Security & Stability
-- **Heartbeat ping/pong** — relay pings every 20s; mobile detects dead connections within 30s and auto-reconnects
-- **Disconnect overlay** — clear full-screen prompt when companion goes offline
-- **Session loading spinner** — visual feedback when switching sessions
-- **Improved toast notifications** — slide-in animation
-
-### Docs
-- Updated README with new features, PM2 instructions, heartbeat details
-- Added CHANGELOG
-
-## 1.1.1 (2026-03-16)
-
-### Security Hardening
-- **Rate limiting** — 50 messages/second per WebSocket connection
-- **IP connection limit** — max 5 concurrent connections per IP
-- **Brute force protection** — pair code entry locked after 3 failed attempts (60s cooldown)
-- **Origin verification** — only ghostterm.pages.dev allowed
-- **Max payload** — 1MB limit per WebSocket message
-- **Timing-safe HMAC** — prevents timing attacks on token verification
-- **Upload validation** — 5MB size limit + extension whitelist
-- **Pair code format validation** — must be exactly 6 digits
-- **WSS enforcement** — prevents MITM downgrade attacks
-- **Exponential backoff** — reconnection delay 1s → 30s max
+- WebRTC P2P direct connection between phone and PC terminal
+- 6-digit pair code + QR code for easy pairing
+- Multi-session support (up to 4 concurrent terminals)
+- End-to-end encrypted (DTLS) — terminal data never touches the server
+- File upload from phone to PC via DataChannel
+- Delta sync for reconnection recovery
+- Automatic reconnect with exponential backoff
+- Google Sign-In authentication
+- DataChannel flow control (backpressure)
+- PWA install support
+- Latency monitoring (ping display)
 
 ### Bug Fixes
-- Fixed ghost duplication (stale session list cleared on reconnect)
-- Fixed auto-scroll during thinking output (touch/button scroll disables auto-scroll)
-- Fixed smartScroll jumping to top of terminal
-
-## 1.1.0 (2026-03-15)
-
-### Features
-- Google OAuth auto-pairing (sign in once, auto-reconnects)
-- Long-lived token (30 days, no repeated Google sign-in)
-- 4 simultaneous terminal sessions with ghost cell previews
-- Pixel office mode
-- File upload and screenshot support
-- D-pad controls, quick keys (y/n/Tab/Shift+Tab)
-- Copy mode for terminal text selection
-
-## 1.0.0 (2026-03-14)
-
-- Initial release
-- Basic terminal relay via WebSocket
-- Pair code pairing
+- Fixed terminal rendering: use conpty (not winpty) for proper ANSI escape code support
+- Fixed `bufferSeq` calculation to match byte-length tracking
+- Fixed delta sync to send sliced buffer instead of full buffer
+- Fixed `attach`/`close-session` sessionId passthrough from DataChannel message format

package/README.md

@@ -1,287 +1,45 @@
-<p align="center">
-  <img src="https://ghostterm.pages.dev/img/banner.png" width="500" alt="GhostTerm Banner">
-</p>
+# GhostTerm P2P
 
-<h1 align="center">GhostTerm</h1>
-<p align="center">
-  <strong>A mobile terminal for Claude Code fans.</strong><br>
-  Control your PC from your phone — real CLI, not a toy.
-</p>
-<p align="center">
-  <a href="https://www.npmjs.com/package/ghostterm"><img src="https://img.shields.io/npm/v/ghostterm.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/ghostterm"><img src="https://img.shields.io/npm/dm/ghostterm.svg" alt="npm downloads"></a>
-  <img src="https://img.shields.io/node/v/ghostterm" alt="node version">
-  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license">
-</p>
+Control your PC terminal from your phone — direct P2P, no server in between.
 
-> *GhostTerm is not affiliated with Anthropic. Just a fan who couldn't stop using Claude Code.*
+## How it works
 
----
+1. Run `npx ghostterm-p2p` on your PC
+2. A 6-digit pair code appears (with a QR code)
+3. Open the mobile site on your phone and enter the code
+4. A direct WebRTC P2P connection is established
+5. All terminal data flows directly between your phone and PC, encrypted end-to-end
+6. The signaling server only helps with the initial pairing — it never sees your terminal data
 
-## What is GhostTerm?
-
-GhostTerm lets you **control your PC terminal from your phone** over the internet. It's built specifically for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) users who want to:
-
-- Run `claude --dangerously-skip-permissions` and monitor everything from their phone
-- Approve/deny tool calls from anywhere (bus, bed, coffee shop)
-- Manage 4 terminal sessions simultaneously
-
-No VPN. No Tailscale. No port forwarding. Just one command.
-
----
-
-## Quick Start
-
-### 1. On your PC
+## Install & Run
 
 ```bash
-npx ghostterm
+npx ghostterm-p2p
 ```
 
-First run opens a browser for Google sign-in. After that, it runs in the background automatically — no terminal window.
-
-```
-$ npx ghostterm
-  ✅ GhostTerm running in background (PID: 12345)
-  📱 Open: ghostterm.pages.dev
-  🛑 Stop: npx ghostterm stop
-  📋 Logs: npx ghostterm logs
-```
-
-Other commands:
+Or install globally:
 
 ```bash
-npx ghostterm status   # check if running
-npx ghostterm stop     # stop the background process
-npx ghostterm logs     # show recent logs
+npm install -g ghostterm-p2p
+ghostterm-p2p
 ```
 
-### 2. On your phone
-
-Open **[ghostterm.pages.dev](https://ghostterm.pages.dev)** in any mobile browser. Sign in with the same Google account.
-
-**That's it.** Your terminal appears on your phone.
-
----
-
-## Screenshots
-
-<p align="center">
-  <img src="https://ghostterm.pages.dev/img/office-busy.jpg" width="220" alt="Ghosts working">
-  <img src="https://ghostterm.pages.dev/img/pixel-office.jpg" width="220" alt="Pixel office">
-  <img src="https://ghostterm.pages.dev/img/claude-code.jpg" width="220" alt="Claude Code on phone">
-</p>
-<p align="center">
-  <em>Pixel ghost office · 4 terminal sessions · Claude Code on your phone</em>
-</p>
-
----
-
-## Features
-
-### Terminal
-
-- **Real xterm.js terminal** — full ANSI colors, 256-color, scrollback buffer
-- **4 simultaneous sessions** — more than Anthropic's official mobile app
-- **Auto-resize** — terminal adapts to your phone's screen size
-- **Scrollback history** — scroll up to see previous output, page up/down buttons
-
-### Controls
-
-- **Quick keys** — one-tap `y`/`n` for Claude Code approvals
-- **12345 numpad** — tap to pop up number selection for CLI surveys/prompts (raw keypress, no Enter)
-- **D-pad** — arrow keys, Enter, Tab, Shift+Tab, Space
-- **Long-press acceleration** — hold Backspace, arrow keys, Space, or scroll buttons to repeat with increasing speed
-- **`claude` button** — quick-launch menu: new session, resume, continue, dangerous mode
-- **Ctrl+C (Stop)** — interrupt running processes
-- **Text input** — full keyboard input with Send button
-- **Tap feedback** — all buttons show visual press animation
-- **Copy mode** — select and copy terminal text
-
-### File Transfer
-
-- **Screen** — capture your terminal screen and send it to your PC as a file
-- **File upload** — upload files directly from your phone to your desktop
-- **Paste button** — always visible; glows for 5 seconds after upload with shortened filename; tap to paste the file path into the terminal
-
-### Visual
-
-- **Pixel office mode** — see all 4 terminals as cute ghost desks in a Halloween-themed pixel office
-- **Ghost cell previews** — live miniature terminal previews in the header
-- **Dark theme** — easy on the eyes, matches terminal aesthetics
-
-### Connection
-
-- **Google auto-pairing** — sign in once, auto-reconnects forever
-- **Encrypted relay** — all traffic over WSS (WebSocket Secure)
-- **Zero data stored** — the relay only forwards messages
-- **Heartbeat** — relay pings every 20s; dead connections detected and auto-reconnected within 30s
-- **Auto-reconnect** — exponential backoff (1s → 30s max), handles network drops gracefully
-- **Session persistence** — refreshing the page restores your last active terminal session
-
----
-
-## How It Works
+## Options
 
 ```
-Phone (browser)  ──WSS──>  Relay (Fly.io Tokyo)  <──WSS──  PC (ghostterm)
-                            encrypted WebSocket
-                            auto-pairs by Google account
-                            zero data stored
+-s, --signal <url>   Signaling server URL
+--site <url>         Mobile site URL
+-h, --help           Show help
 ```
 
-1. `npx ghostterm` starts a companion process on your PC that connects to the relay server
-2. The companion spawns a real PTY (pseudo-terminal) using `node-pty`
-3. Your phone connects to the same relay via WebSocket
-4. The relay matches both sides by Google account and forwards messages
-5. Terminal output streams to your phone; your input streams to the PTY
-
----
-
-## Use Cases
-
-### The "Dangerous" Workflow
-
-```bash
-claude --dangerously-skip-permissions
-```
-
-Let Claude Code run fully autonomous on your PC. Monitor everything from your phone. Intervene when needed. Go make coffee.
-
-### Multi-Session Power
-
-4 ghost cells = 4 terminals. Run Claude Code in one, `git log` in another, `npm test` in a third. Switch between them with a tap.
-
-### On-the-Go Approval
-
-Claude Code asking "May I edit server.js?" — tap `y` from the bus. No need to rush back to your desk.
-
----
-
-## System Requirements
-
-### PC (Companion)
-
-- **Node.js** 18 or later
-- **Operating System**: Windows, macOS, or Linux
-- **Platform-specific build tools** (for `node-pty`):
-  - **Windows**: Visual Studio Build Tools or `npm install -g windows-build-tools`
-  - **macOS**: `xcode-select --install`
-  - **Linux**: `apt install build-essential` (Debian/Ubuntu) or equivalent
-- **Google account** for pairing
-
-### Phone (Client)
-
-- Any modern browser (iOS Safari 15+, Chrome, Firefox, Edge)
-- Internet connection
-
----
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|---|---|---|
-| `GHOSTTERM_RELAY` | `wss://ghostterm-relay.fly.dev` | Custom relay server URL |
-
-### Custom Relay
-
-If you want to self-host the relay:
-
-```bash
-GHOSTTERM_RELAY=wss://your-relay.example.com npx ghostterm
-```
-
----
-
-## Pricing
-
-GhostTerm is currently **free** during early access. Pro plans coming soon.
-
----
-
-## Troubleshooting
-
-### "Failed to install node-pty" / build errors
-
-`node-pty` requires native compilation. Make sure you have build tools installed:
-
-```bash
-# Windows (run as Administrator)
-npm install -g windows-build-tools
-
-# macOS
-xcode-select --install
-
-# Linux (Debian/Ubuntu)
-sudo apt install build-essential python3
-```
-
-### "Google sign-in window doesn't open"
-
-- Make sure your default browser isn't blocking pop-ups
-- Try running `npx ghostterm` again — it retries automatically
-- If behind a corporate proxy, ensure `accounts.google.com` is accessible
-
-### "Phone can't connect" / "Waiting for companion..."
-
-- Ensure the PC companion is still running (`npx ghostterm`)
-- Both devices must use the **same Google account**
-- Check your phone's internet connection
-- Try refreshing the page on your phone
-
-### "Terminal shows garbled text"
-
-- Make sure your phone browser supports modern CSS/JS
-- Try switching to a different terminal session (tap a ghost cell)
-- Clear browser cache and reload
-
-### "Session keeps disconnecting"
-
-- Check your network stability on both PC and phone
-- The relay auto-reconnects with exponential backoff
-- If using a VPN, try disabling it (GhostTerm doesn't need one)
-
-### node-pty on Apple Silicon (M1/M2/M3)
-
-If you see architecture mismatch errors:
-
-```bash
-# Force rebuild for current architecture
-npm rebuild node-pty
-```
-
----
-
-## Uninstall
-
-GhostTerm stores a refresh token in `~/.ghostterm/` for auto-login. To fully remove:
-
-```bash
-rm -rf ~/.ghostterm
-```
-
----
-
 ## Security
 
-- All communication is encrypted via WSS (WebSocket Secure)
-- Google OAuth 2.0 for authentication — GhostTerm never sees your Google password
-- The relay server is stateless — no terminal data is stored
-- Pair codes expire after 5 minutes
-- Brute-force protection on pair code entry
-- Rate limiting on all WebSocket connections
-- Connection limits per IP address
-
----
-
-## License
-
-MIT
+- **End-to-end encrypted**: WebRTC DTLS encryption protects all terminal data
+- **No data on servers**: The signaling server only relays WebRTC connection setup messages
+- **One-time pair codes**: Codes are deleted after use and expire in 5 minutes
+- **Brute force protection**: 3 wrong codes = 60 second lockout
 
----
+## Requirements
 
-<p align="center">
-  Built with frustration and love by a Claude Code addict.
-</p>
+- Node.js >= 18
+- Windows, macOS, or Linux