peer-term 1.2.5 → 1.2.7

package/README.md

@@ -14,6 +14,12 @@ 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.
 
+If you started the session with `--secure`, both sides will show a short security fingerprint. Compare it over a trusted channel. If it matches, authorize the session in the host CLI:
+
+```bash
+a <code>
+```
+
 ## Global Installation
 
 If you prefer to install it globally:
@@ -35,6 +41,7 @@ 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 --secure                     # require fingerprint verification
 peer-term --expiry 10m                 # custom expiry time
 peer-term --relay wss://custom         # use a custom relay server
 peer-term --verbose                    # enable debug logging
@@ -43,7 +50,7 @@ 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-256-GCM with ECDH P-256 key exchange. The relay never sees plaintext.
+- **End-to-End Encrypted**: Terminal data is encrypted locally using AES-256-GCM with ECDH P-256 key exchange. The relay never sees plaintext. A `--secure` flag enables an out-of-band fingerprint check for strict MITM protection.
 - **WebRTC P2P**: Creates a direct Peer-to-Peer connection on the same LAN for zero-latency, relay-free sessions.
 - **Read-Only Mode**: Guests can view your terminal but cannot type commands.
 - **Custom Start Path**: Set the starting directory with `--path`.
@@ -55,5 +62,6 @@ peer-term --verbose                    # enable debug logging
 1. **Host** registers a session on the relay and gets a 6-digit code
 2. **Client** opens the web UI and enters the code
 3. Both sides perform an **ECDH key exchange** to derive a shared AES-256-GCM secret
-4. All terminal I/O is encrypted end-to-end — the relay only forwards opaque blobs
-5. If both peers are on the same LAN, a **WebRTC DataChannel** is established to bypass the relay entirely
+4. If `--secure` is used, both sides compare a short fingerprint, then the host authorizes the verified session with `a <code>`
+5. All terminal I/O is encrypted end-to-end — the relay only forwards opaque blobs
+6. If both peers are on the same LAN, a **WebRTC DataChannel** is established to bypass the relay entirely

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peer-term",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "license": "MIT",
   "description": "Share your terminal instantly using a 6-digit code. Encrypted. No config.",
   "keywords": [

package/src/crypto.js

@@ -75,6 +75,24 @@ export async function deriveSharedKey(privateKey, peerPublicKey) {
   );
 }
 
+/**
+ * Compute the short authentication string shown to both users.
+ * The relay can forward keys, but it cannot make a MITM split produce the same
+ * fingerprint on both sides unless the users skip the out-of-band comparison.
+ */
+export async function fingerprintPublicKeys(sessionCode, hostPublicKeyBase64, clientPublicKeyBase64) {
+  const transcript = [
+    'PeerTerm SAS v1',
+    String(sessionCode || ''),
+    String(hostPublicKeyBase64 || ''),
+    String(clientPublicKeyBase64 || ''),
+  ].join('\n');
+
+  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(transcript));
+  const hex = Buffer.from(digest).toString('hex').toUpperCase().slice(0, 16);
+  return hex.match(/.{1,4}/g).join('-');
+}
+
 // ─── Encryption ─────────────────────────────────────────────────────────────
 
 /**
@@ -144,4 +162,3 @@ export async function decrypt(sharedKey, base64data) {
   // 4. Return as string
   return new TextDecoder().decode(plaintext);
 }
-

package/src/index.js

@@ -35,6 +35,7 @@ import {
   exportPublicKey,
   importPublicKey,
   deriveSharedKey,
+  fingerprintPublicKeys,
   encrypt,
   decrypt,
 } from './crypto.js';
@@ -60,7 +61,7 @@ try {
 // ─── CLI Argument Parsing ────────────────────────────────────────────────────
 
 const argv = minimist(process.argv.slice(2), {
-  boolean: ['readonly', 'verbose', 'help', 'version'],
+  boolean: ['readonly', 'verbose', 'help', 'version', 'secure'],
   string: ['expiry', 'rejoin', 'relay', 'path'],
   alias: { h: 'help', v: 'version', V: 'verbose' },
 });
@@ -307,12 +308,17 @@ class Session {
     this.readOnly = readOnly;
     this.startPath = startPath;
     this.onDestroy = onDestroy;
+    this.secureMode = argv.secure || false;
 
     this.ws = null;
     this.code = null;
     this.hostToken = null;
     this.keyPair = null;
+    this.hostPublicKeyBase64 = null;
+    this.clientPublicKeyBase64 = null;
     this.sharedKey = null;
+    this.securityFingerprint = null;
+    this.fingerprintAuthorized = false;
     this.ptyProcess = null;
     this.heartbeatInterval = null;
     this.missedPings = 0;
@@ -343,6 +349,85 @@ class Session {
     logger.debug(`${prefix} ${msg}`);
   }
 
+  async _beginKeyExchange() {
+    this.keyPair = await generateKeyPair();
+    this.hostPublicKeyBase64 = await exportPublicKey(this.keyPair.publicKey);
+    this.clientPublicKeyBase64 = null;
+    this.sharedKey = null;
+    this.securityFingerprint = null;
+    this.fingerprintAuthorized = false;
+    this.stopHeartbeat();
+    this._cleanupWebRTC();
+    this.ws.send(JSON.stringify({ 
+      type: 'key-exchange', 
+      publicKey: this.hostPublicKeyBase64,
+      secureMode: this.secureMode 
+    }));
+  }
+
+  async _completeKeyExchange(clientPublicKeyBase64) {
+    if (!this.keyPair || !this.hostPublicKeyBase64) return;
+
+    this.logDebug('Deriving shared secret...');
+    this.clientPublicKeyBase64 = clientPublicKeyBase64;
+
+    const peerPublicKey = await importPublicKey(clientPublicKeyBase64);
+    this.sharedKey = await deriveSharedKey(this.keyPair.privateKey, peerPublicKey);
+
+    if (this.secureMode) {
+      this.securityFingerprint = await fingerprintPublicKeys(
+        this.code,
+        this.hostPublicKeyBase64,
+        this.clientPublicKeyBase64
+      );
+      this.fingerprintAuthorized = false;
+      this._printFingerprintAuthorization();
+    } else {
+      this.fingerprintAuthorized = true;
+      await this._activateSecureSession();
+    }
+  }
+
+  _printFingerprintAuthorization() {
+    console.log('');
+    this.log('Encrypted candidate established. Verify before terminal access.');
+    console.log(`  Fingerprint: ${this.securityFingerprint}`);
+    console.log('  Ask the viewer to compare this exact fingerprint.');
+    console.log(`  Type "a ${this.code}" after it matches, or "k ${this.code}" to kill the session.`);
+    console.log('');
+  }
+
+  async authorizeFingerprint() {
+    if (!this.sharedKey || !this.securityFingerprint) {
+      logger.warn(`Session ${this.code} has no fingerprint awaiting authorization.`);
+      return false;
+    }
+    if (this.fingerprintAuthorized) {
+      logger.info(`Session ${this.code} is already authorized.`);
+      return true;
+    }
+
+    this.fingerprintAuthorized = true;
+    await this._activateSecureSession();
+    return true;
+  }
+
+  async _activateSecureSession() {
+    if (!this.sharedKey || !this.fingerprintAuthorized) return;
+
+    this.log(`Fingerprint authorized: ${this.securityFingerprint}`);
+    this.log('Encrypted tunnel active');
+    await this._sendSessionConfig();
+
+    this.startHeartbeat();
+
+    if (!this.ptyProcess) {
+      this.spawnTerminal();
+    }
+
+    this._initiateWebRTC();
+  }
+
   async _sendSessionConfig() {
     if (!this.sharedKey || !this.ws || this.ws.readyState !== WebSocket.OPEN) return;
 
@@ -411,7 +496,7 @@ class Session {
               code: this.code,
               expiry: formatDuration(this.expiryMs),
               rejoinWindow: formatDuration(this.rejoinMs),
-              mode: this.readOnly ? 'Read-Only' : 'Read-Write',
+              mode: (this.readOnly ? 'Read-Only' : 'Read-Write') + (this.secureMode ? ' (Secure)' : ''),
               shell: this.shell,
               startPath: this.startPath,
               shareUrl: url.replace(/^wss:\/\//i, 'https://').replace(/^ws:\/\//i, 'http://')
@@ -430,29 +515,12 @@ class Session {
             this.isClientConnected = true;
             this.missedPings = 0;
 
-            this.keyPair = await generateKeyPair();
-            const pubKeyBase64 = await exportPublicKey(this.keyPair.publicKey);
-            this.ws.send(JSON.stringify({ type: 'key-exchange', publicKey: pubKeyBase64 }));
+            await this._beginKeyExchange();
             break;
           }
 
           case 'key-exchange': {
-            if (!this.keyPair) return;
-            this.logDebug('Deriving shared secret...');
-
-            const peerPublicKey = await importPublicKey(msg.publicKey);
-            this.sharedKey = await deriveSharedKey(this.keyPair.privateKey, peerPublicKey);
-            this.log('Encrypted tunnel active');
-            await this._sendSessionConfig();
-
-            this.startHeartbeat();
-
-            if (!this.ptyProcess) {
-              this.spawnTerminal();
-            }
-
-            // Phase 4: Initiate WebRTC after encryption is ready
-            this._initiateWebRTC();
+            await this._completeKeyExchange(msg.publicKey);
             break;
           }
 
@@ -513,6 +581,10 @@ class Session {
             this.awaitingRejoin = true;
             this.sharedKey = null;
             this.keyPair = null;
+            this.hostPublicKeyBase64 = null;
+            this.clientPublicKeyBase64 = null;
+            this.securityFingerprint = null;
+            this.fingerprintAuthorized = false;
             this.stopHeartbeat();
             // Phase 4: Clean up WebRTC on peer disconnect
             this._cleanupWebRTC();
@@ -601,6 +673,10 @@ class Session {
         this.awaitingRejoin = true;
         this.sharedKey = null;
         this.keyPair = null;
+        this.hostPublicKeyBase64 = null;
+        this.clientPublicKeyBase64 = null;
+        this.securityFingerprint = null;
+        this.fingerprintAuthorized = false;
         this.stopHeartbeat();
       }
     }, HEARTBEAT_INTERVAL_MS);
@@ -872,28 +948,12 @@ class Session {
             break;
           }
 
-          this.keyPair = await generateKeyPair();
-          const pubKeyBase64 = await exportPublicKey(this.keyPair.publicKey);
-          this.ws.send(JSON.stringify({ type: 'key-exchange', publicKey: pubKeyBase64 }));
+          await this._beginKeyExchange();
           break;
         }
 
         case 'key-exchange': {
-          if (!this.keyPair) return;
-          this.logDebug('Deriving shared secret...');
-
-          const peerPublicKey = await importPublicKey(msg.publicKey);
-          this.sharedKey = await deriveSharedKey(this.keyPair.privateKey, peerPublicKey);
-          this.log('Encrypted tunnel active');
-          await this._sendSessionConfig();
-
-          this.startHeartbeat();
-
-          if (!this.ptyProcess) {
-            this.spawnTerminal();
-          }
-
-          this._initiateWebRTC();
+          await this._completeKeyExchange(msg.publicKey);
           break;
         }
 
@@ -951,6 +1011,10 @@ class Session {
           this.awaitingRejoin = true;
           this.sharedKey = null;
           this.keyPair = null;
+          this.hostPublicKeyBase64 = null;
+          this.clientPublicKeyBase64 = null;
+          this.securityFingerprint = null;
+          this.fingerprintAuthorized = false;
           this.stopHeartbeat();
           this._cleanupWebRTC();
           break;
@@ -1096,14 +1160,14 @@ class Session {
     }
 
     this.sharedKey = null;
+    this.hostPublicKeyBase64 = null;
+    this.clientPublicKeyBase64 = null;
+    this.securityFingerprint = null;
+    this.fingerprintAuthorized = false;
     this._cleanupWebRTC();
 
-    this.keyPair = await generateKeyPair();
-    const pubKeyBase64 = await exportPublicKey(this.keyPair.publicKey);
-
     if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-      this.ws.send(JSON.stringify({ type: 'key-exchange', publicKey: pubKeyBase64 }));
-      this.startHeartbeat();
+      await this._beginKeyExchange();
     }
   }
 
@@ -1120,7 +1184,9 @@ class Session {
     const elapsed = Date.now() - this.createdAt;
     const remaining = Math.max(0, this.expiryMs - elapsed);
     let status = '';
-    if (this.isClientConnected) {
+    if (this.securityFingerprint && !this.fingerprintAuthorized) {
+      status = `verify fingerprint ${this.securityFingerprint}`;
+    } else if (this.isClientConnected) {
       status = 'client connected';
     } else if (this.awaitingRejoin) {
       status = 'awaiting rejoin';
@@ -1182,6 +1248,15 @@ class SessionManager {
     logger.info(`Session ${code} killed.`);
   }
 
+  async authorizeSession(code) {
+    const session = this.sessions.get(code);
+    if (!session) {
+      logger.warn(`Session ${code} not found.`);
+      return;
+    }
+    await session.authorizeFingerprint();
+  }
+
   killAll() {
     for (const [, session] of this.sessions) {
       session.destroy();
@@ -1228,6 +1303,7 @@ async function main() {
   console.log('  Commands:');
   console.log('    [n] New session');
   console.log('    [l] List sessions');
+  console.log('    [a <code>] Authorize verified fingerprint');
   console.log('    [k <code>] Kill session');
   console.log('    [q] Quit all');
   console.log('  ─────────────────────────────────────────');
@@ -1249,6 +1325,9 @@ async function main() {
       await manager.createSession();
     } else if (input === 'l') {
       manager.listSessions();
+    } else if (input.startsWith('a ')) {
+      const code = input.slice(2).trim();
+      await manager.authorizeSession(code);
     } else if (input.startsWith('k ')) {
       const code = input.slice(2).trim();
       manager.killSession(code);
@@ -1258,7 +1337,7 @@ async function main() {
       rl.close();
       process.exit(0);
     } else if (input) {
-      console.log('  Unknown command. Use n, l, k <code>, or q.');
+      console.log('  Unknown command. Use n, l, a <code>, k <code>, or q.');
     }
 
     rl.prompt();

package/src/ui.js

@@ -101,6 +101,7 @@ Options:
   --expiry <time>     Session expiry time (e.g. 5m, 30s, 1h)  [default: 5m]
   --rejoin <time>     Reconnection window (e.g. 5m, 1h, 6h)   [default: 2m]
   --readonly          Share in view-only mode
+  --secure            Enable fingerprint verification for MITM protection
   --path <dir>        Starting directory for the terminal session  [default: home]
   --relay <url>       Custom relay server URL
   --verbose           Enable debug logging
@@ -112,6 +113,7 @@ Examples:
   peer-term --expiry 10m           Custom expiry
   peer-term --rejoin 30m           Custom reconnection window
   peer-term --readonly             View-only session
+  peer-term --secure               Require fingerprint verification
   peer-term --path ~/projects      Start in ~/projects
   peer-term --verbose              Debug logs
   peer-term --relay wss://custom   Use custom relay server