peer-term 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# PeerTerm
+
+Share your terminal instantly over WebRTC using a 6-digit code. Fully end-to-end encrypted. No configuration or accounts required.
+
+## Quick Start
+
+You don't even need to install it. Just run:
+
+```bash
+npx peer-term
+```
+
+This will start a terminal sharing session and give you a 6-digit code.
+
+Share this code with your peer. They can view your terminal by going to https://peer-term-relay-production-9b7a.up.railway.app or https://peer-term-relay.onrender.com and entering the code.
+
+## Global Installation
+
+If you prefer to install it globally:
+
+```bash
+npm install -g peer-term
+```
+
+Then you can just run:
+
+```bash
+peer-term
+```
+
+## Usage
+
+```bash
+peer-term                              # starts at home directory
+peer-term --path ~/projects            # starts at ~/projects
+peer-term --path .                     # starts in current directory
+peer-term --readonly                   # view-only session
+peer-term --expiry 10m                 # custom expiry time
+peer-term --verbose                    # enable debug logging
+```
+
+## Features
+
+- **No Config**: Works instantly. No port forwarding or firewall configuration needed.
+- **End-to-End Encrypted**: Terminal data is encrypted locally using AES-GCM before being sent.
+- **WebRTC P2P**: Creates a direct Peer-to-Peer connection when possible for minimal latency.
+- **Read-Only Mode**: Guests can view your terminal but cannot type commands, ensuring your system remains secure.
+- **Custom Start Path**: Set the starting directory with `--path` so guests land right where you want them.
+
+## License
+
+MIT

package/bin/peer-term.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * PeerTerm — CLI Entry Point
+ *
+ * This is the shebang entry point for `npx peer-term` and global installs.
+ * It imports the main host agent and handles uncaught exceptions gracefully.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// ─── Global Error Handling ───────────────────────────────────────────────────
+
+const LOG_DIR = path.join(os.homedir(), '.peerterm', 'logs');
+const ERROR_LOG = path.join(LOG_DIR, 'error.log');
+
+function logFatalError(label, err) {
+  // Write full stack to file
+  try {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+    const ts = new Date().toISOString();
+    const entry = `[${ts}] ${label}: ${err.message || err}\n${err.stack || ''}\n\n`;
+    fs.appendFileSync(ERROR_LOG, entry);
+  } catch {
+    // Can't even log — nothing to do
+  }
+
+  // Print friendly message to terminal
+  console.error('');
+  console.error(`  ✖ ${label}: ${err.message || err}`);
+  console.error(`    Details logged to: ${ERROR_LOG}`);
+  console.error('');
+}
+
+process.on('uncaughtException', (err) => {
+  logFatalError('Uncaught exception', err);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  const err = reason instanceof Error ? reason : new Error(String(reason));
+  logFatalError('Unhandled promise rejection', err);
+  process.exit(1);
+});
+
+// ─── Launch Main ─────────────────────────────────────────────────────────────
+
+import('../src/index.js').catch((err) => {
+  logFatalError('Failed to start PeerTerm', err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "peer-term",
+  "version": "1.0.0",
+  "description": "Share your terminal instantly using a 6-digit code. Encrypted. No config.",
+  "main": "src/index.js",
+  "bin": {
+    "peer-term": "./bin/peer-term.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node bin/peer-term.js",
+    "build": "npx @yao-pkg/pkg . --compress GZip",
+    "build:linux-x64": "npx @yao-pkg/pkg . --targets node18-linux-x64 --output dist/peer-term-linux-x64",
+    "build:linux-arm64": "npx @yao-pkg/pkg . --targets node18-linux-arm64 --output dist/peer-term-linux-arm64",
+    "build:macos-x64": "npx @yao-pkg/pkg . --targets node18-macos-x64 --output dist/peer-term-macos-x64",
+    "build:macos-arm64": "npx @yao-pkg/pkg . --targets node18-macos-arm64 --output dist/peer-term-macos-arm64",
+    "build:win": "npx @yao-pkg/pkg . --targets node18-win-x64 --output dist/peer-term-win-x64.exe",
+    "postinstall": "node src/check-deps.js"
+  },
+  "pkg": {
+    "scripts": "src/**/*.js",
+    "assets": [],
+    "targets": [
+      "node18-linux-x64",
+      "node18-linux-arm64",
+      "node18-macos-x64",
+      "node18-macos-arm64",
+      "node18-win-x64"
+    ],
+    "outputPath": "dist/"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "minimist": "^1.2.8",
+    "node-datachannel": "^0.32.3",
+    "node-pty": "^1.0.0",
+    "ws": "^8.18.0"
+  }
+}

package/src/check-deps.js

@@ -0,0 +1,83 @@
+/**
+ * PeerTerm — Native Dependency Check
+ *
+ * Postinstall script that verifies native modules (node-pty, node-datachannel)
+ * are available. Prints clear errors with platform-specific fix instructions
+ * if they're missing. Exits cleanly (warning, not error) so npm install
+ * doesn't fail.
+ */
+
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+
+let allGood = true;
+
+// ─── Check node-pty ──────────────────────────────────────────────────────────
+
+try {
+  require('node-pty');
+} catch {
+  allGood = false;
+  console.warn('');
+  console.warn('  ⚠  node-pty failed to load.');
+  console.warn('');
+  console.warn('  node-pty is a native C++ module that requires build tools.');
+  console.warn('');
+
+  if (process.platform === 'win32') {
+    console.warn('  Windows fix:');
+    console.warn('    npm install -g windows-build-tools');
+    console.warn('    — or —');
+    console.warn('    Install Visual Studio Build Tools with "Desktop development with C++"');
+  } else if (process.platform === 'darwin') {
+    console.warn('  macOS fix:');
+    console.warn('    xcode-select --install');
+  } else {
+    console.warn('  Linux fix:');
+    console.warn('    sudo apt install build-essential python3   (Debian/Ubuntu)');
+    console.warn('    sudo yum groupinstall "Development Tools"  (RHEL/CentOS)');
+  }
+
+  console.warn('');
+  console.warn('  Then run: npm rebuild node-pty');
+  console.warn('');
+}
+
+// ─── Check node-datachannel ──────────────────────────────────────────────────
+
+try {
+  require('node-datachannel');
+} catch {
+  allGood = false;
+  console.warn('');
+  console.warn('  ⚠  node-datachannel failed to load.');
+  console.warn('');
+  console.warn('  node-datachannel is a native module for WebRTC DataChannels.');
+  console.warn('  It requires CMake and C++ build tools.');
+  console.warn('');
+
+  if (process.platform === 'win32') {
+    console.warn('  Windows fix:');
+    console.warn('    Install CMake from https://cmake.org/download/');
+    console.warn('    Install Visual Studio Build Tools with "Desktop development with C++"');
+  } else if (process.platform === 'darwin') {
+    console.warn('  macOS fix:');
+    console.warn('    brew install cmake');
+    console.warn('    xcode-select --install');
+  } else {
+    console.warn('  Linux fix:');
+    console.warn('    sudo apt install cmake build-essential   (Debian/Ubuntu)');
+    console.warn('    sudo yum install cmake gcc-c++           (RHEL/CentOS)');
+  }
+
+  console.warn('');
+  console.warn('  Then run: npm rebuild node-datachannel');
+  console.warn('');
+}
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+if (allGood) {
+  console.log('  ✓ All native dependencies loaded successfully.');
+}

package/src/crypto.js

@@ -0,0 +1,147 @@
+/**
+ * PeerTerm — Encryption Helpers (Host-side)
+ * 
+ * Implements ECDH P-256 key exchange and AES-256-GCM encryption/decryption
+ * using Node.js crypto.webcrypto (SubtleCrypto API).
+ * 
+ * Encryption spec:
+ *   - Key exchange: ECDH with P-256 curve
+ *   - Derived key: AES-GCM, 256-bit, extractable: false
+ *   - Per message: 12-byte random IV prepended to ciphertext, encoded as base64
+ */
+
+import { webcrypto } from 'crypto';
+const subtle = webcrypto.subtle;
+
+// ─── Key Pair Generation ─────────────────────────────────────────────────────
+
+/**
+ * Generate an ephemeral ECDH P-256 key pair.
+ * Returns { publicKey, privateKey } as CryptoKey objects.
+ */
+export async function generateKeyPair() {
+  return await subtle.generateKey(
+    { name: 'ECDH', namedCurve: 'P-256' },
+    false, // not extractable (private key stays in memory)
+    ['deriveKey']
+  );
+}
+
+// ─── Public Key Export / Import ──────────────────────────────────────────────
+
+/**
+ * Export a public CryptoKey to a base64 string (raw format).
+ * This is what gets sent over the wire to the peer.
+ */
+export async function exportPublicKey(publicKey) {
+  const raw = await subtle.exportKey('raw', publicKey);
+  return Buffer.from(raw).toString('base64');
+}
+
+/**
+ * Import a peer's public key from a base64 string.
+ * Returns a CryptoKey suitable for ECDH key derivation.
+ */
+export async function importPublicKey(base64) {
+  const raw = Buffer.from(base64, 'base64');
+  return await subtle.importKey(
+    'raw',
+    raw,
+    { name: 'ECDH', namedCurve: 'P-256' },
+    false,
+    []
+  );
+}
+
+// ─── Shared Key Derivation ──────────────────────────────────────────────────
+
+/**
+ * Derive a shared AES-256-GCM key from our private key and the peer's public key.
+ * Both sides independently derive the same key (ECDH magic).
+ * 
+ * The derived key is:
+ *   - Algorithm: AES-GCM
+ *   - Length: 256 bits
+ *   - Extractable: false (cannot be exported, only used for encrypt/decrypt)
+ *   - Usages: ['encrypt', 'decrypt']
+ */
+export async function deriveSharedKey(privateKey, peerPublicKey) {
+  return await subtle.deriveKey(
+    { name: 'ECDH', public: peerPublicKey },
+    privateKey,
+    { name: 'AES-GCM', length: 256 },
+    false, // not extractable
+    ['encrypt', 'decrypt']
+  );
+}
+
+// ─── Encryption ─────────────────────────────────────────────────────────────
+
+/**
+ * Encrypt plaintext with AES-256-GCM.
+ * 
+ * Steps:
+ *   1. Generate a random 12-byte IV
+ *   2. Encrypt the plaintext with AES-GCM using the shared key and IV
+ *   3. Concatenate [IV (12 bytes) + ciphertext]
+ *   4. Encode the result as a base64 string
+ * 
+ * @param {CryptoKey} sharedKey - The derived AES-GCM key
+ * @param {string} plaintext - The data to encrypt
+ * @returns {string} base64-encoded IV + ciphertext
+ */
+export async function encrypt(sharedKey, plaintext) {
+  // 1. Fresh random IV for every message (critical for AES-GCM security)
+  const iv = webcrypto.getRandomValues(new Uint8Array(12));
+
+  // 2. Encrypt
+  const encoded = new TextEncoder().encode(plaintext);
+  const ciphertext = await subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    sharedKey,
+    encoded
+  );
+
+  // 3. Concatenate IV + ciphertext
+  const combined = new Uint8Array(iv.length + ciphertext.byteLength);
+  combined.set(iv, 0);
+  combined.set(new Uint8Array(ciphertext), iv.length);
+
+  // 4. Encode as base64
+  return Buffer.from(combined).toString('base64');
+}
+
+// ─── Decryption ─────────────────────────────────────────────────────────────
+
+/**
+ * Decrypt a base64-encoded AES-GCM message.
+ * 
+ * Steps:
+ *   1. Base64 decode the input
+ *   2. Split: first 12 bytes = IV, rest = ciphertext
+ *   3. Decrypt with AES-GCM
+ *   4. Return plaintext string
+ * 
+ * @param {CryptoKey} sharedKey - The derived AES-GCM key
+ * @param {string} base64data - The encrypted message (IV + ciphertext in base64)
+ * @returns {string} Decrypted plaintext
+ */
+export async function decrypt(sharedKey, base64data) {
+  // 1. Base64 decode
+  const combined = Buffer.from(base64data, 'base64');
+
+  // 2. Split IV and ciphertext
+  const iv = combined.slice(0, 12);
+  const ciphertext = combined.slice(12);
+
+  // 3. Decrypt
+  const plaintext = await subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    sharedKey,
+    ciphertext
+  );
+
+  // 4. Return as string
+  return new TextDecoder().decode(plaintext);
+}
+