ghostterm 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 1.1.3 (2026-03-17)
+
+### Features
+- **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
+
+### 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

package/README.md

@@ -1,39 +1,34 @@
-# GhostTerm 👻
-
-**A mobile terminal for Claude Code fans.** Control your PC from your phone — real CLI, not a toy.
-
-> *GhostTerm is not affiliated with Anthropic. Just a fan who couldn't stop using Claude Code.*
-
----
-
-## Screenshots
-
 <p align="center">
   <img src="https://ghostterm.pages.dev/img/banner.png" width="500" alt="GhostTerm Banner">
 </p>
 
+<h1 align="center">GhostTerm</h1>
 <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 overview">
-  <img src="https://ghostterm.pages.dev/img/claude-code.jpg" width="220" alt="Claude Code on phone">
+  <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">
-  <em>Halloween-themed pixel office · 4 animated ghost terminals · Claude Code on your phone</em>
+  <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>
 
+> *GhostTerm is not affiliated with Anthropic. Just a fan who couldn't stop using Claude Code.*
+
 ---
 
-## Why GhostTerm?
+## 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:
 
-You're running Claude Code on your PC. You walk away. Now what?
+- 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
 
-- **Run `--dangerously-skip-permissions`** — let Claude go full auto, monitor from your phone while it codes for you
-- **4 terminal sessions at once** — more than Anthropic's official app
-- **Real xterm.js terminal** — full ANSI colors, scrollback, not a dumbed-down GUI
-- **Built-in shortcut keys** — `y` / `n` for approvals, `Tab`, `Ctrl+C`, arrow keys, all one-tap
-- **`claude` quick-launch button** — start new sessions, resume, or continue with one tap
-- **Pixel office mode** — see all 4 terminals as cute ghost desks
+No VPN. No Tailscale. No port forwarding. Just one command.
+
+---
 
 ## Quick Start
 
@@ -45,15 +40,96 @@ npx ghostterm
 
 First run opens a browser for Google sign-in. After that, it remembers you.
 
+**Run in background (no terminal window):**
+
+```bash
+pm2 start ghostterm.js --name ghostterm
+pm2 save
+```
+
 ### 2. On your phone
 
-Open **[ghostterm.pages.dev](https://ghostterm.pages.dev)** — sign in with the same Google account.
+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
+- **`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
+- **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** — after uploading, shows 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
+
+```
+Phone (browser)  ──WSS──>  Relay (Fly.io Tokyo)  <──WSS──  PC (ghostterm)
+                            encrypted WebSocket
+                            auto-pairs by Google account
+                            zero data stored
+```
+
+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
 
-That's it. Your terminal appears on your phone. No VPN. No Tailscale. No port forwarding.
+---
 
 ## Use Cases
 
-### 🔥 The "Dangerous" Workflow
+### The "Dangerous" Workflow
 
 ```bash
 claude --dangerously-skip-permissions
@@ -61,75 +137,140 @@ 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
+### 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
+### 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.
 
-### 📸 Screenshot & Upload
+---
 
-Take a screenshot of your phone screen and send it to your PC terminal. Upload files directly from your phone to your desktop.
+## System Requirements
 
-## Features
+### PC (Companion)
 
-| Feature | GhostTerm | Anthropic Mobile |
-|---|---|---|
-| Real CLI terminal | ✅ | ❌ |
-| Simultaneous sessions | 4 | 1 |
-| `--dangerously-skip-permissions` | ✅ monitor from phone | ❌ |
-| Custom shortcut keys | ✅ y/n/Tab/Ctrl+C | ❌ |
-| Pixel office view | ✅ | ❌ |
-| File upload to PC | ✅ | ❌ |
-| No VPN needed | ✅ | N/A |
-| Google auto-pairing | ✅ | - |
+- **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)
 
-## Controls
+- Any modern browser (iOS Safari 15+, Chrome, Firefox, Edge)
+- Internet connection
 
-**Top bar**: 4 ghost cells (tap to switch terminals, `+` to create new) · `🏠` pixel office view · `A` font size · `▼` hide controls
+---
 
-**Quick keys**: `y` / `n` (approve/deny) · `S+Tab` (shift-tab) · `/ cmd` (slash commands) · `Tab` · `←Bksp`
+## Configuration
 
-**Left column**: `⏻ claude` (launch menu: new / resume / continue / dangerous mode) · `Stop` (Ctrl+C) · `Close` (kill session)
+### Environment Variables
 
-**Center**: D-pad (↑↓←→) + `Enter`
+| Variable | Default | Description |
+|---|---|---|
+| `GHOSTTERM_RELAY` | `wss://ghostterm-relay.fly.dev` | Custom relay server URL |
 
-**Right column**: `Line↵` (newline) · `⬇` (scroll to bottom) · `Space` · `▲▼` (page up/down) · `Copy` (select mode)
+### Custom Relay
+
+If you want to self-host the relay:
+
+```bash
+GHOSTTERM_RELAY=wss://your-relay.example.com npx ghostterm
+```
 
-**Bottom**: Text input + `Send` · `📷 Shot` (screenshot to PC) · `📁 File` (upload to PC)
+---
 
 ## Pricing
 
-- **Free**: 1 hour/day, full features
-- **Pro**: $5/month or $12/quarter — unlimited access
+GhostTerm is currently **free** during early access. Pro plans coming soon.
 
-## How It Works
+---
+
+## 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
 ```
-Phone (browser)  ──WSS──▶  Relay (Fly.io Tokyo)  ◀──WSS──  PC (ghostterm)
-                            encrypted WebSocket
-                            auto-pairs by Google account
-                            zero data stored
+
+### "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
 ```
 
-All traffic is encrypted (WSS). The relay only forwards messages — no terminal data is stored.
+---
 
-## Requirements
+## Uninstall
 
-- **PC**: Node.js 18+
-  - Windows: may need `npm install -g windows-build-tools`
-  - macOS: `xcode-select --install`
-  - Linux: `apt install build-essential`
-- **Phone**: Any modern browser (iOS Safari, Chrome, etc.)
+GhostTerm stores a refresh token in `~/.ghostterm/` for auto-login. To fully remove:
 
-## Environment Variables
+```bash
+rm -rf ~/.ghostterm
+```
 
-| Variable | Default | Description |
-|---|---|---|
-| `GHOSTTERM_RELAY` | `wss://ghostterm-relay.fly.dev` | Custom relay server URL |
+---
+
+## 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
+
+---
+
+<p align="center">
+  Built with frustration and love by a Claude Code addict.
+</p>

package/bin/ghostterm.js

@@ -409,8 +409,19 @@ function handleRelayMessage(msg) {
 
     case 'upload':
       try {
+        const UPLOAD_MAX_SIZE = 5 * 1024 * 1024; // 5MB
+        const UPLOAD_EXT_WHITELIST = ['.png', '.jpg', '.jpeg', '.pdf', '.txt', '.md', '.json', '.csv', '.py', '.js', '.ts', '.html', '.css'];
+        const ext = (msg.ext || '.png').toLowerCase();
+        if (!UPLOAD_EXT_WHITELIST.includes(ext)) {
+          sendToRelay({ type: 'upload_error', message: `File type not allowed: ${ext}` });
+          break;
+        }
         const buf = Buffer.from(msg.data, 'base64');
-        const filename = `${Date.now()}-${Math.random().toString(36).slice(2, 6)}${msg.ext || '.png'}`;
+        if (buf.length > UPLOAD_MAX_SIZE) {
+          sendToRelay({ type: 'upload_error', message: `File too large: ${(buf.length / 1024 / 1024).toFixed(1)}MB (max 5MB)` });
+          break;
+        }
+        const filename = `${Date.now()}-${Math.random().toString(36).slice(2, 6)}${ext}`;
         const filePath = path.join(UPLOAD_DIR, filename);
         fs.writeFileSync(filePath, buf);
         sendToRelay({ type: 'upload_result', path: filePath, filename, size: buf.length });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostterm",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Mobile terminal for Claude Code — control your PC from your phone",
   "bin": {
     "ghostterm": "bin/ghostterm.js"