pairshell-cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PairShell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# pairshell-cli
+
+Desktop agent CLI for PairShell — pair an Android device over an encrypted tunnel and drive a real terminal session. Works on Windows, macOS, and Linux.
+
+## Install / Run
+
+Requires Node.js >= 20. `node-pty` ships prebuilt binaries for Windows and macOS. On Linux, a C++ compiler and Python are needed (standard on any dev machine).
+
+**Global install** (run from anywhere):
+```bash
+npm install -g pairshell-cli
+pairshell-cli setup
+pairshell-cli start
+```
+
+**Direct via npx** (no install needed):
+```bash
+npx pairshell-cli setup
+npx pairshell-cli start
+```
+
+**Local install** (in a project):
+```bash
+npm install pairshell-cli
+npx pairshell-cli setup
+npx pairshell-cli start
+```
+
+## Commands
+
+### `start [path]`
+
+Start a WebSocket server in the current directory (or the given path). A pairing QR code is displayed. Scan it with the PairShell app to connect.
+
+While running:
+- **Press Enter** — generate a fresh pairing code
+- **Ctrl-C** — stop the server
+
+A tunnel is started automatically so the device can connect from anywhere. Use `--no-tunnel` for local-network-only access.
+
+```
+pairshell-cli start
+pairshell-cli start ~/projects/foo
+pairshell-cli start --no-tunnel
+pairshell-cli start --provider ngrok
+pairshell-cli start --port 8080
+```
+
+After pairing, the device gets a persistent session token. Reconnecting the same device skips the pairing step.
+
+### `revoke [device-id]`
+
+List all connected devices or revoke a device by ID. Device IDs were issued during initial pairing and are displayed when listing sessions.
+
+```
+pairshell-cli revoke           # list active sessions
+pairshell-cli revoke abc123    # revoke the device with ID abc123
+```
+
+The server must be running for this to work. It communicates with the local server directly over HTTP. A revoke removes all session tokens associated with the device, forcing it to re-pair on next connection.
+
+### `setup [provider]`
+
+Configure a tunnel provider. Default is `devtunnel`.
+
+```
+pairshell-cli setup                  # devtunnel (default)
+pairshell-cli setup ngrok --api-key YOUR_KEY
+pairshell-cli setup tailscale
+pairshell-cli setup --force          # re-run even if already configured
+```
+
+### `status`
+
+Show current configuration and network status.
+
+```
+pairshell-cli status
+```
+
+### `guide [provider]`
+
+Print setup instructions for a provider.
+
+```
+pairshell-cli guide devtunnel
+pairshell-cli guide ngrok
+pairshell-cli guide tailscale
+```
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--no-tunnel` | Local-only mode — no outbound tunnel. Use when both ends are on the same LAN (e.g., SSH from a laptop to a desktop on the same WiFi). |
+| `--port <n>` | Override the WebSocket server port |
+| `--provider <name>` | Use a specific tunnel provider |
+| `--list` | List available tunnel providers |
+| `--force` | Re-run setup even if already configured |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+## Tunnel Providers
+
+### devtunnel (default)
+
+Microsoft devtunnel. Requires the devtunnel CLI and a Microsoft account login.
+
+```
+devtunnel user login
+pairshell-cli setup devtunnel
+pairshell-cli start
+```
+
+The tunnel ID persists across restarts for a stable URL. The CLI can be installed from https://aka.ms/devtunnel/cli.
+
+**How it works:** Runs `devtunnel create --allow-anonymous` during setup to create a tunnel ID, then `devtunnel host <id> -p <port> --allow-anonymous` on each start. Outbound-only — no inbound ports needed.
+
+### ngrok
+
+Auto-downloads the ngrok binary on first use. Requires a free ngrok account and API key.
+
+```
+pairshell-cli setup ngrok --api-key YOUR_KEY
+pairshell-cli start
+```
+
+Get an API key at https://dashboard.ngrok.com/api-keys.
+
+For a custom static domain (paid plan):
+```json
+{ "ngrok": { "apiKey": "YOUR_KEY", "domain": "your-domain.ngrok.io" } }
+```
+
+**How it works:** Downloads ngrok from equinox.io, configures the authtoken, then runs `ngrok http <port>` and parses the JSON log output for the tunnel URL.
+
+### tailscale
+
+Uses Tailscale Funnel. Requires Tailscale installed, authenticated, and Funnel enabled in the admin console.
+
+```
+tailscale up
+# enable Funnel at https://login.tailscale.com/admin/machines
+pairshell-cli setup tailscale
+pairshell-cli start
+```
+
+**How it works:** Runs `tailscale funnel on --set-path=/ <port>` to serve the port, then reads `tailscale status --json` to get the machine's DNS name. Traffic stays within your tailnet — no third-party relay.
+
+## How Pairing Works
+
+1. The server generates a random 64-character hex token.
+2. The token is encoded into a WebSocket URL and displayed as a QR code.
+3. The device connects, presenting the token.
+4. The server validates the token (one-time use), then issues a persistent session token.
+5. On subsequent connections, the device can reconnect directly using the session token without re-pairing.
+
+## File Locations
+
+All data lives under `~/.pairshell/`:
+
+| File | Purpose |
+|---|---|
+| `~/.pairshell/config.json` | Provider config (tunnel ID, API keys, etc.) |
+| `~/.pairshell/session-tokens.json` | Persistent session tokens for reconnecting devices |
+| `~/.pairshell/bin/` | Auto-downloaded binaries (ngrok) |
+
+## Config File Format
+
+`~/.pairshell/config.json` stores provider configuration:
+
+```json
+{
+  "provider": "ngrok",
+  "ngrok": { "apiKey": "YOUR_KEY" },
+  "tailscale": {}
+}
+```
+
+For ngrok with a custom static domain (paid plan):
+```json
+{
+  "provider": "ngrok",
+  "ngrok": { "apiKey": "YOUR_KEY", "domain": "your-domain.ngrok.io" }
+}
+```
+
+## Security
+
+- Pairing tokens are 64-character hex strings, single-use, valid until consumed
+- Session tokens persist in `~/.pairshell/session-tokens.json` and allow reconnection without re-pairing
+- Tunnel traffic is end-to-end encrypted by the provider (TLS for devtunnel/ngrok, WireGuard for Tailscale Funnel)
+- No inbound ports opened on your network — tunnels are outbound-only
+- **Session encryption:** all terminal data (keystrokes, PTY output, resize events) is encrypted with tweetnacl secretbox (XSalsa20-Poly1305) before being sent over the WebSocket. The encryption key is derived via SHA-512 from the pairing or session token — every session uses a unique key.
+- **Token visible in handshake:** the pairing and session tokens are sent as query parameters in the WebSocket URL (e.g., `ws://host/?token=...`). The tunnel provider sees this URL during the TLS handshake, before any app-layer encryption applies. This is a small residual exposure — it's the same token a device would need to present, but worth documenting that it exists.
+- **Control frames in the clear:** JSON text messages (resize, ping/pong, auth) are deliberately sent unencrypted. Only binary terminal data carries the encryption overhead, since control messages are low-sensitivity and short-lived. This is a conscious scoping decision, not an oversight.
+- **Session revocation:** running `pairshell-cli revoke <device-id>` on the host deletes all of that device's session tokens, forcing it to re-pair on the next connection.
+
+## Uninstall
+
+```bash
+npm uninstall -g pairshell-cli
+rm -rf ~/.pairshell
+```
+
+## License
+
+MIT
+
+## Testing
+
+Two test scripts connect to a running server and verify the bridge:
+
+```bash
+node test/test-bridge.mjs ws://host:port/?token=TOKEN
+node test/test-reject-second.mjs ws://host:port/?token=TOKEN
+```
+
+- `test-bridge.mjs` — sends keystrokes, verifies PTY echo, tests ping/pong and resize
+- `test-reject-second.mjs` — verifies that a second connection with the same one-time token is rejected (code 4001)

package/bin/pairshell-cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2)).catch((err) => {
+  const message = err && err.message ? err.message : String(err);
+  console.error(`pairshell-cli: ${message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "pairshell-cli",
+  "version": "0.0.1",
+  "description": "Desktop agent CLI for PairShell — pair an Android device over an encrypted tunnel and drive a real terminal session.",
+  "type": "module",
+  "bin": {
+    "pairshell-cli": "bin/pairshell-cli.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node test/test-bridge.mjs",
+    "start": "node bin/pairshell-cli.js"
+  },
+  "preferUnplugged": true,
+  "license": "MIT",
+  "author": "PairShell",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pairshell/pairshell-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Pairshell/pairshell-cli/issues"
+  },
+  "homepage": "https://github.com/Pairshell/pairshell-cli#readme",
+  "keywords": [
+    "pairshell",
+    "terminal",
+    "tunnel",
+    "remote",
+    "ssh",
+    "android",
+    "devtunnel",
+    "ngrok",
+    "tailscale"
+  ],
+  "dependencies": {
+    "node-pty": "^1.0.0",
+    "qrcode-terminal": "^0.12.0",
+    "tweetnacl": "^1.0.3",
+    "ws": "^8.18.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,138 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { startCommand } from "./start.js";
+import { setupCommand } from "./setup.js";
+import { statusCommand } from "./status.js";
+import { revokeCommand } from "./revoke.js";
+import { resolve as resolveProvider, listProviders } from "./providers/index.js";
+import { header, fail, BOLD, RESET } from "./format.js";
+
+const PKG_PATH = resolve(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+const VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version || "0.0.0";
+
+const COMMANDS = {
+  start: startCommand,
+  setup: setupCommand,
+  status: statusCommand,
+  revoke: revokeCommand,
+};
+
+function printHelp() {
+  console.log(`\n  pairshell-cli v${VERSION} — desktop agent for PairShell
+
+  USAGE
+    pairshell-cli <command> [options]
+
+  COMMANDS
+    start [path]      Start a session in the current or given directory
+    setup [provider]  One-time provider setup (default: devtunnel)
+    status            Show configuration and network status
+    revoke [device]   List sessions or revoke a device by ID
+    guide [provider]  Show setup instructions for a provider
+    help              Show this help
+
+  OPTIONS
+    --no-tunnel       Local-only mode (no outbound tunnel). Use when both
+                      ends are on the same LAN, e.g., SSHing into your
+                      desktop from a laptop on the same WiFi.
+    --port <n>        Override the WebSocket server port
+    --provider <name> Use a specific tunnel provider
+    --list            List available tunnel providers
+    --force           Re-run setup even if already configured
+    -h, --help        Show this help
+    -v, --version     Show version
+
+  PROVIDERS
+    devtunnel   Microsoft devtunnel (default, requires CLI + login)
+    ngrok       ngrok (auto-download binary, API key, free account)
+    tailscale   Tailscale Funnel (install + enable, no third-party relay)
+
+  EXAMPLES
+    pairshell-cli start
+    pairshell-cli start ~/projects/foo
+    pairshell-cli start --provider ngrok
+    pairshell-cli start --no-tunnel
+    pairshell-cli setup
+    pairshell-cli setup ngrok --api-key YOUR_KEY
+    pairshell-cli status
+    pairshell-cli revoke
+    pairshell-cli revoke abc123
+`);
+}
+
+function parseFlags(args) {
+  const flags = { tunnel: true, help: false, version: false, port: 0, force: false, list: false, path: null };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--no-tunnel") {
+      flags.tunnel = false;
+    } else if (arg === "-h" || arg === "--help") {
+      flags.help = true;
+    } else if (arg === "-v" || arg === "--version") {
+      flags.version = true;
+    } else if (arg === "--port") {
+      const value = Number(args[++i]);
+      if (Number.isInteger(value) && value > 0) flags.port = value;
+    } else if (arg === "--force") {
+      flags.force = true;
+    } else if (arg === "--list") {
+      flags.list = true;
+    } else if (arg === "--provider") {
+      flags.provider = args[++i];
+    } else if (arg === "--api-key") {
+      flags.apiKey = args[++i];
+    } else if (!arg.startsWith("-") && !flags.path) {
+      flags.path = arg;
+    }
+  }
+  return flags;
+}
+
+export async function run(argv) {
+  const flags = parseFlags(argv.slice(1));
+  const cmd = argv[0];
+
+  if (cmd === "-v" || cmd === "--version") {
+    console.log(`pairshell-cli v${VERSION}`);
+    return;
+  }
+
+  if (flags.list) {
+    console.log(`\n  Available providers: ${listProviders().join(", ")}\n`);
+    return;
+  }
+
+  if (cmd === "guide") {
+    const providerName = flags.provider || argv[1] || "devtunnel";
+    try {
+      const prov = resolveProvider(providerName);
+      header(`Guide: ${prov.label}`);
+      prov.printGuide();
+    } catch (err) {
+      fail(err.message);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (!cmd || cmd === "help" || flags.help) {
+    printHelp();
+    return;
+  }
+
+  const handler = COMMANDS[cmd];
+  if (!handler) {
+    fail(`Unknown command "${cmd}".`);
+    console.log(`\n  Run ${BOLD}pairshell-cli help${RESET} to see available commands.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.version) {
+    console.log(`pairshell-cli v${VERSION}`);
+    return;
+  }
+
+  await handler(flags);
+}

package/src/config.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { defaultProvider } from "./providers/index.js";
+
+const CONFIG_DIR = path.join(os.homedir(), ".pairshell");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+export function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(cfg) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), "utf8");
+  try {
+    fs.chmodSync(CONFIG_PATH, 0o600);
+  } catch {}
+}
+
+export function getProvider() {
+  const cfg = readConfig();
+  return typeof cfg.provider === "string" ? cfg.provider : defaultProvider();
+}
+
+export function setProvider(name) {
+  const cfg = readConfig();
+  cfg.provider = name;
+  writeConfig(cfg);
+}
+
+export function getProviderConfig(name) {
+  return readConfig()[name];
+}
+
+export function setProviderConfig(name, providerCfg) {
+  const cfg = readConfig();
+  cfg.provider = name;
+  cfg[name] = providerCfg;
+  writeConfig(cfg);
+}

package/src/crypto.js

@@ -0,0 +1,28 @@
+import nacl from "tweetnacl";
+import { randomBytes } from "node:crypto";
+
+const KEY_CONTEXT = "pairshell-session-key-v1";
+const KEY_LENGTH = nacl.secretbox.keyLength;
+const NONCE_LENGTH = nacl.secretbox.nonceLength;
+
+export function deriveKey(token) {
+  const input = new TextEncoder().encode(token + KEY_CONTEXT);
+  const hash = nacl.hash(input);
+  return hash.slice(0, KEY_LENGTH);
+}
+
+export function encrypt(plaintext, key) {
+  const nonce = randomBytes(NONCE_LENGTH);
+  const data = typeof plaintext === "string" ? new TextEncoder().encode(plaintext) : plaintext;
+  const ciphertext = nacl.secretbox(data, nonce, key);
+  return Buffer.concat([nonce, Buffer.from(ciphertext)]);
+}
+
+export function decrypt(packet, key) {
+  if (packet.length < NONCE_LENGTH + nacl.secretbox.overheadLength) return null;
+  const nonce = packet.subarray(0, NONCE_LENGTH);
+  const ciphertext = packet.subarray(NONCE_LENGTH);
+  const plaintext = nacl.secretbox.open(ciphertext, nonce, key);
+  if (!plaintext) return null;
+  return Buffer.from(plaintext);
+}

package/src/format.js

@@ -0,0 +1,50 @@
+const isColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function esc(code) {
+  return isColor ? `\x1b[${code}m` : "";
+}
+
+export const RESET = esc(0);
+export const BOLD = esc(1);
+const DIM = esc(2);
+const RED = esc(31);
+const GREEN = esc(32);
+const YELLOW = esc(33);
+const BLUE = esc(34);
+const MAGENTA = esc(35);
+const CYAN = esc(36);
+
+export function ok(label) {
+  console.log(`  ${GREEN}ok${RESET}  ${label}`);
+}
+
+export function info(label) {
+  console.log(`  ${BLUE}→${RESET}  ${label}`);
+}
+
+export function warn(label) {
+  console.log(`  ${YELLOW}warn${RESET} ${label}`);
+}
+
+export function fail(label) {
+  console.log(`  ${RED}ERROR${RESET} ${label}`);
+}
+
+export function header(text) {
+  console.log(`\n${BOLD}${CYAN}═══ ${text} ${RESET}${DIM}${"─".repeat(Math.max(0, 60 - text.length - 4))}${RESET}\n`);
+}
+
+export function pairingUrl(url) {
+  const colored = url.replace(
+    /(wss?:\/\/)([^/]+)(\/?.*)/,
+    (_, proto, host, rest) => `${CYAN}${proto}${RESET}${BOLD}${host}${RESET}${DIM}${rest}${RESET}`,
+  );
+  return colored;
+}
+
+export function kv(items) {
+  const keyLen = Math.max(...items.map(([k]) => k.length));
+  for (const [key, val] of items) {
+    console.log(`  ${BOLD}${key.padEnd(keyLen)}${RESET}  ${val}`);
+  }
+}

package/src/net.js

@@ -0,0 +1,43 @@
+import os from "node:os";
+
+const SKIP_INTERFACES = [
+  "docker", "veth", "br-", "vbox", "vmnet",
+  "vEthernet", "hyper-v", "virtualbox",
+  "loopback", "lo",
+];
+
+function isVirtual(name) {
+  const lower = name.toLowerCase();
+  return SKIP_INTERFACES.some((k) => lower.includes(k));
+}
+
+export function lanAddress() {
+  const interfaces = os.networkInterfaces();
+  const candidates = [];
+
+  for (const name of Object.keys(interfaces)) {
+    if (isVirtual(name)) continue;
+    for (const iface of interfaces[name] || []) {
+      if ((iface.family === "IPv4" || iface.family === 4) && !iface.internal) {
+        const addr = iface.address;
+        // Skip link-local and VirtualBox default host-only subnet
+        if (addr.startsWith("169.254.") || addr.startsWith("192.168.56.")) {
+          continue;
+        }
+        candidates.push({ name, address: addr });
+      }
+    }
+  }
+
+  if (candidates.length > 0) {
+    // Prioritize Wi-Fi/WLAN network interfaces if present
+    const wifi = candidates.find((c) => {
+      const lower = c.name.toLowerCase();
+      return lower.includes("wi-fi") || lower.includes("wifi") || lower.includes("wlan");
+    });
+    if (wifi) return wifi.address;
+    return candidates[0].address;
+  }
+
+  return "127.0.0.1";
+}

package/src/pairing.js

@@ -0,0 +1,19 @@
+import { randomBytes } from "node:crypto";
+
+export class PairingStore {
+  constructor() {
+    this.tokens = new Set();
+  }
+
+  create() {
+    const token = randomBytes(32).toString("hex");
+    this.tokens.add(token);
+    return token;
+  }
+
+  consume(token) {
+    if (!token || !this.tokens.has(token)) return false;
+    this.tokens.delete(token);
+    return true;
+  }
+}