cli-setu 0.2.6 → 0.2.8

package/README.md

@@ -1,6 +1,6 @@
 # cli-setu
 
-Bridge your terminal to your phone. Run Claude Code, Codex, or any plain shell on your laptop, and approve prompts, type, and watch the live output from the [CLIसेतु](https://clisetu.com) app on your phone.
+Bridge your terminal to your phone. Run Claude Code, Codex, or any plain shell on your laptop, and approve prompts, type, and watch the live output from the [cli-setu](https://clisetu.com) app on your phone.
 
 ## Install
 
@@ -16,7 +16,7 @@ cli-setu --cli claude # same, but runs Claude Code inside the bridged session
 cli-setu --cli codex  # or Codex
 ```
 
-The first time you run it, `cli-setu` prints a QR code (and an 8-digit fallback code) - scan it with the CLIसेतु app to pair this computer and start watching the session live.
+The first time you run it, `cli-setu` prints a QR code (and an 8-digit fallback code) - scan it with the cli-setu app to pair this computer and start watching the session live.
 
 Once paired, running `cli-setu` in any folder just works - no QR code needed again, unless this is a device you haven't paired before.
 
@@ -33,7 +33,7 @@ cli-setu --help    # show all commands
 
 ## How it works
 
-`cli-setu` spawns your real terminal (or Claude Code/Codex) inside a PTY, same as any terminal emulator. Every byte it produces streams live to the CLIसेतु app over a secure relay; anything you type on the phone writes back into that same PTY, exactly like a local keystroke. Permission prompts (file edits, shell commands, etc.) are detected and relayed as structured approve/reject cards instead of raw text, when the adapter for your CLI supports it.
+`cli-setu` spawns your real terminal (or Claude Code/Codex) inside a PTY, same as any terminal emulator. Every byte it produces streams live to the cli-setu app over a secure relay; anything you type on the phone writes back into that same PTY, exactly like a local keystroke. Permission prompts (file edits, shell commands, etc.) are detected and relayed as structured approve/reject cards instead of raw text, when the adapter for your CLI supports it.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-setu",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Bridge your terminal to your phone — run and approve Claude Code, Codex CLI and other AI coding agents from anywhere.",
   "type": "commonjs",
   "bin": {

package/src/config.js

@@ -44,6 +44,17 @@ function loadOrCreateConfig() {
   return { deviceName: defaultDeviceName(), deviceToken: null };
 }
 
+// Section 1 E2E: this device's own X25519 keypair, generated once (first
+// `cli-setu pair`) and reused for the lifetime of this pairing - same
+// lifetime as deviceToken itself, so a re-pair naturally mints a fresh
+// keypair too, same as it mints a fresh token. Private key stored
+// base64-encoded in the same config.json deviceToken already lives in -
+// no new file, no new permissions model; this machine's own user-profile
+// access already protects deviceToken the same way.
+function hasKeypair(config) {
+  return !!(config.devicePrivateKey && config.devicePublicKey);
+}
+
 module.exports = {
   CONFIG_DIR,
   CONFIG_FILE,
@@ -51,4 +62,5 @@ module.exports = {
   readConfig,
   writeConfig,
   loadOrCreateConfig,
+  hasKeypair,
 };

package/src/crypto.js

@@ -0,0 +1,104 @@
+// Section 1 E2E: real end-to-end encryption for terminal.input/output,
+// so the backend relay can forward packets without being able to read
+// them (previously it could - see this file's own commit message / the
+// privacy policy fix this exists to make true instead of false).
+//
+// Design: X25519 ECDH key exchange, one keypair per laptop, generated
+// once at pair time and reused for the life of that pairing (same
+// lifetime as the device token itself - a re-pair generates a fresh
+// keypair, same as it mints a fresh token). The shared secret is
+// derived once per phone public key via HKDF-SHA256 and cached; AES-
+// 256-GCM encrypts each terminal payload with a fresh random IV.
+//
+// The backend only ever sees: this device's PUBLIC key (at pairing) and
+// ciphertext (at relay time) - never the private key, never the derived
+// secret, never plaintext. That's what makes this actually end-to-end,
+// not just "encrypted somewhere."
+const crypto = require('crypto');
+
+// Node's 'x25519' curve via the generic Diffie-Hellman API - available
+// since Node 13, well within this project's >=18 engines requirement.
+function generateKeypair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+  return { publicKey, privateKey };
+}
+
+// Node's KeyObject export format for a raw X25519 public key is a DER-
+// wrapped SPKI blob, not the raw 32 bytes - stripping to raw bytes here
+// so the wire format matches what @noble/curves on the app side produces
+// and expects directly (no ASN.1 parsing needed on that end).
+const RAW_PUBLIC_KEY_LEN = 32;
+
+function publicKeyToRaw(publicKey) {
+  const der = publicKey.export({ type: 'spki', format: 'der' });
+  return der.subarray(der.length - RAW_PUBLIC_KEY_LEN);
+}
+
+function publicKeyFromRaw(rawBytes) {
+  // SPKI header for X25519 is fixed (12 bytes) - prepending it lets
+  // Node's crypto module import a raw 32-byte public key the same way
+  // it exports one above.
+  const SPKI_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+  const der = Buffer.concat([SPKI_PREFIX, rawBytes]);
+  return crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+}
+
+function publicKeyToBase64(publicKey) {
+  return publicKeyToRaw(publicKey).toString('base64');
+}
+
+// Private key storage shape: Node's native PKCS8 DER export, base64-
+// encoded - config.js stores it this way in config.json alongside
+// deviceToken (same file, same OS-level file permissions already
+// protecting that token, so no new secret-storage mechanism needed).
+function privateKeyToBase64(privateKey) {
+  return privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64');
+}
+
+function privateKeyFromBase64(base64) {
+  return crypto.createPrivateKey({ key: Buffer.from(base64, 'base64'), format: 'der', type: 'pkcs8' });
+}
+
+function deriveSharedSecret(privateKey, peerPublicKeyBase64) {
+  const peerPublicKey = publicKeyFromRaw(Buffer.from(peerPublicKeyBase64, 'base64'));
+  const rawSecret = crypto.diffieHellman({ privateKey, publicKey: peerPublicKey });
+  // HKDF-SHA256, no salt (both sides derive deterministically from the
+  // same ECDH output - a salt would need its own exchange for no real
+  // benefit here), fixed info string scoping this key to this exact
+  // purpose so it can never collide with a key derived elsewhere for a
+  // different purpose from the same raw ECDH secret.
+  return Buffer.from(crypto.hkdfSync('sha256', rawSecret, Buffer.alloc(0), 'cli-setu-terminal-v1', 32));
+}
+
+// AES-256-GCM: a fresh random 12-byte IV per message (GCM's own
+// requirement - reusing an IV with the same key breaks its security
+// guarantees entirely), the 16-byte auth tag appended, both prepended/
+// appended to the ciphertext so the wire format is one self-contained
+// base64 string: IV (12) || ciphertext || authTag (16).
+function encrypt(sharedSecret, plaintext) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', sharedSecret, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return Buffer.concat([iv, ciphertext, authTag]).toString('base64');
+}
+
+function decrypt(sharedSecret, payloadBase64) {
+  const buf = Buffer.from(payloadBase64, 'base64');
+  const iv = buf.subarray(0, 12);
+  const authTag = buf.subarray(buf.length - 16);
+  const ciphertext = buf.subarray(12, buf.length - 16);
+  const decipher = crypto.createDecipheriv('aes-256-gcm', sharedSecret, iv);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}
+
+module.exports = {
+  generateKeypair,
+  publicKeyToBase64,
+  privateKeyToBase64,
+  privateKeyFromBase64,
+  deriveSharedSecret,
+  encrypt,
+  decrypt,
+};

package/src/pair.js

@@ -5,11 +5,25 @@
 // of a hand-typed argv, and the result is saved to ~/.cli-setu/config.json
 // instead of a per-device-name file in the install folder.
 const qrcode = require('qrcode-terminal');
-const { loadOrCreateConfig, writeConfig } = require('./config');
+const { loadOrCreateConfig, writeConfig, hasKeypair } = require('./config');
+const { generateKeypair, publicKeyToBase64, privateKeyToBase64 } = require('./crypto');
 
 async function pair(authServer, authServerPublic) {
   const config = loadOrCreateConfig();
 
+  // Section 1 E2E: generate this device's own keypair up front, before
+  // either pairing path below, so both qr-start and pair/start can send
+  // the SAME public key no matter which path the user actually takes
+  // (scan vs typed code - both start by calling this function). A
+  // re-pair (config.deviceToken was cleared just below, or this is a
+  // genuinely fresh config) always gets a FRESH keypair - never reuses
+  // a stale one left over from a previous, now-dead pairing.
+  if (!hasKeypair(config)) {
+    const { privateKey, publicKey } = generateKeypair();
+    config.devicePrivateKey = privateKeyToBase64(privateKey);
+    config.devicePublicKey = publicKeyToBase64(publicKey);
+  }
+
   if (config.deviceToken) {
     // Real bug found by testing: unpairing from the phone deletes the
     // device server-side, but the laptop's local config.json still has
@@ -55,7 +69,7 @@ async function pair(authServer, authServerPublic) {
   const startRes = await fetch(`${authServer}/device/pair/qr-start`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ deviceName: config.deviceName, sessionId: 'pairing' }),
+    body: JSON.stringify({ deviceName: config.deviceName, sessionId: 'pairing', devicePublicKey: config.devicePublicKey }),
   });
   const { qrToken } = await startRes.json();
 
@@ -69,7 +83,7 @@ async function pair(authServer, authServerPublic) {
   const codeRes = await fetch(`${authServer}/device/pair/start`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ deviceName: config.deviceName }),
+    body: JSON.stringify({ deviceName: config.deviceName, devicePublicKey: config.devicePublicKey }),
   });
   const { code: typedCode, pairId: typedPairId } = await codeRes.json();
   console.log(`[cli-setu] Or type this code in the app's Devices tab: ${typedCode}`);
@@ -84,6 +98,10 @@ async function pair(authServer, authServerPublic) {
     if (status.status === 'CONFIRMED') {
       confirmed = true;
       config.deviceToken = status.deviceToken;
+      // Section 1 E2E: the phone's public key, so this laptop can derive
+      // the shared secret for terminal.input/output - see crypto.js's
+      // deriveSharedSecret and supervisor.js's own use of it.
+      if (status.phonePublicKey) config.phonePublicKey = status.phonePublicKey;
       writeConfig(config);
       console.log(`[cli-setu] ✓ Paired via QR and saved to ~/.cli-setu/config.json`);
       break;
@@ -100,6 +118,7 @@ async function pair(authServer, authServerPublic) {
     if (typedStatus.status === 'CONFIRMED') {
       confirmed = true;
       config.deviceToken = typedStatus.deviceToken;
+      if (typedStatus.phonePublicKey) config.phonePublicKey = typedStatus.phonePublicKey;
       writeConfig(config);
       console.log(`[cli-setu] ✓ Paired via typed code and saved to ~/.cli-setu/config.json`);
       break;

package/src/supervisor.js

@@ -42,6 +42,7 @@ const execAsync = promisify(exec);
 // data, not part of the command syntax itself.
 const execFileAsync = promisify(execFile);
 const { getAdapter } = require('./cli-adapters');
+const setuCrypto = require('./crypto');
 
 // Real bug found by testing: this script's own console.log/console.error
 // calls write to the SAME process.stdout the PTY's raw output is echoed
@@ -166,6 +167,25 @@ let ws = null;
 let azureReady = false;
 const pendingPrompts = new Map();
 
+// Section 1 E2E: derived once at startup, same lifetime as this process.
+// Null whenever either half is missing - a device paired before this
+// feature existed has devicePrivateKey/phonePublicKey absent from its
+// config.json, and terminal.input/output/snapshot below deliberately
+// fall back to sending PLAINTEXT for exactly that case (see this
+// project's own decision: no forced re-pair, upgrade happens naturally
+// on the next real re-pair). Never silently "half encrypt" - either a
+// real secret is available and used for every payload this session, or
+// none is and nothing here pretends otherwise.
+let sharedSecret = null;
+if (config.devicePrivateKey && config.phonePublicKey) {
+  try {
+    const privateKey = setuCrypto.privateKeyFromBase64(config.devicePrivateKey);
+    sharedSecret = setuCrypto.deriveSharedSecret(privateKey, config.phonePublicKey);
+  } catch (err) {
+    console.error('[cli-setu] Could not derive E2E encryption key (falling back to unencrypted relay):', err.message);
+  }
+}
+
 // Phase 6, Section 7: a rolling raw-byte scrollback so a phone that opens
 // terminal.html AFTER the session has been running for a while gets caught
 // up instantly via session.snapshot, instead of an empty screen. Capped so
@@ -255,6 +275,12 @@ async function connectToAzure() {
   }
   const conn = await res.json();
   deviceId = conn.deviceId;
+  // See this function's own call site (main()'s former focusTimer
+  // comment) for why this starts HERE and not unconditionally at
+  // startup - deviceId must be real before pollFocus's heartbeat is
+  // worth sending at all. Guarded so a reconnect (connectToAzure called
+  // again after a dropped WebSocket) never stacks a second timer.
+  if (!focusTimer) focusTimer = setInterval(pollFocus, 2000);
   log(`[supervisor] Connecting to Azure as device:${deviceId} (owner: ${conn.userId})...`);
   // Diagnostic found by testing: a session not appearing in the phone's
   // Terminal tab had no visible cause from the laptop's own side - this
@@ -283,7 +309,28 @@ async function connectToAzure() {
       // Section 11f Step 2: typed input from the phone, written to the PTY
       // exactly like a local keystroke - this is the "arbitrary remote
       // input" half of the DoD, not just approve/reject.
-      ptyProcess.write(msg.data);
+      //
+      // Section 1 E2E: msg.data is ciphertext whenever sharedSecret exists
+      // (the phone encrypts before sending - see TerminalScreen.js's own
+      // sendInput). msg.encrypted distinguishes the two wire shapes so a
+      // pre-upgrade phone build (no E2E yet) and a pre-upgrade laptop
+      // build talking to each other don't try to decrypt plaintext or
+      // vice versa - see this file's own sharedSecret comment for why
+      // that fallback has to be all-or-nothing, never silent guessing.
+      let data = msg.data;
+      if (msg.encrypted) {
+        if (!sharedSecret) {
+          log('[supervisor] Dropped an encrypted terminal.input - this device has no shared secret to decrypt it (re-pair to fix).');
+          return;
+        }
+        try {
+          data = setuCrypto.decrypt(sharedSecret, msg.data);
+        } catch (err) {
+          log('[supervisor] Failed to decrypt terminal.input, dropping:', err.message);
+          return;
+        }
+      }
+      ptyProcess.write(data);
     }
     if (msg.type === 'terminal.resize' && msg.sessionId === SESSION_ID) {
       // Real bug found by testing: this used to call ptyProcess.resize()
@@ -371,14 +418,17 @@ async function sendSnapshot() {
     // pre-TUI history too, not just whatever the current alt-screen
     // buffer still happens to show.
     const history = await preservedHistoryText();
-    const screen = history ? `${history}\n${scrollback}` : scrollback;
+    const plainScreen = history ? `${history}\n${scrollback}` : scrollback;
+    // Section 1 E2E: see terminal.input's own comment on why this is
+    // all-or-nothing, never a silent per-message guess.
+    const screen = sharedSecret ? setuCrypto.encrypt(sharedSecret, plainScreen) : plainScreen;
     await fetch(`${AUTH_SERVER}/relay/terminal-snapshot`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
       // cols/rows: the real PTY's actual geometry, so a phone attaching
       // can lock its terminal to match instead of guessing its own size -
       // see auth-server.js's matching comment for why this matters.
-      body: JSON.stringify({ sessionId: SESSION_ID, screen, cols: PTY_COLS, rows: PTY_ROWS }),
+      body: JSON.stringify({ sessionId: SESSION_ID, screen, encrypted: !!sharedSecret, cols: PTY_COLS, rows: PTY_ROWS }),
     });
   } catch (err) {
     log('[supervisor] Failed to send snapshot:', err.message);
@@ -555,10 +605,13 @@ function flushOutputBuffer() {
   // fetch() itself should resolve quickly regardless of Azure's own cost.
   sendInFlight = sendInFlight.then(async () => {
     try {
+      // Section 1 E2E: see terminal.input's own comment on why this is
+      // all-or-nothing, never a silent per-message guess.
+      const data = sharedSecret ? setuCrypto.encrypt(sharedSecret, batch) : batch;
       await fetch(`${AUTH_SERVER}/relay/terminal-output`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deviceToken}` },
-        body: JSON.stringify({ sessionId: SESSION_ID, seq: ++outputSeq, data: batch }),
+        body: JSON.stringify({ sessionId: SESSION_ID, seq: ++outputSeq, data, encrypted: !!sharedSecret }),
       });
     } catch (err) {
       // A dropped terminal.output batch isn't fatal the way a dropped
@@ -1249,15 +1302,20 @@ async function main() {
   // ptyProcess.onExit's cleanup still has a valid, harmless no-op target.
 
   pollTimer = setInterval(pollForRequests, POLL_INTERVAL_MS);
-  // Real gap found by testing: closing the shell directly (no graceful
-  // Ctrl+C) leaves no explicit "I'm done" signal for the Backend at all
-  // (see this function's onExit handler) - the ONLY way a dead session
-  // ever stops showing live on the phone is this heartbeat simply going
-  // quiet long enough for auth-server.js's own LIVE_SESSION_STALE_MS to
-  // notice. 2000ms (was 3000ms) keeps a comfortable multiple of margin
-  // under that window (now 7000ms) even if a poll or two is delayed,
-  // while detecting a real disconnect meaningfully faster than before.
-  focusTimer = setInterval(pollFocus, 2000);
+  // Real bug found by testing (PM report: "device shows offline after
+  // connecting"): focusTimer used to start HERE, unconditionally, before
+  // connectToAzure() (called at the bottom of this function, unawaited)
+  // had any chance to resolve its /device/connect call and set the real
+  // deviceId below. pollFocus's own deviceId-aware URL building silently
+  // omits the heartbeat whenever deviceId is still null - harmless for a
+  // couple of ticks on a normal fast connect, but genuinely persistent
+  // (heartbeat omitted for the ENTIRE outage) whenever /device/connect is
+  // stuck in its own 3s retry loop (network hiccup, backend restart) -
+  // every tick silently did nothing, with no visible error, for as long
+  // as that retry loop ran. Moved to start right where deviceId itself
+  // gets set, inside connectToAzure() (see its own comment there) -
+  // "Offline" on the phone now correctly means "genuinely not
+  // connected," never "connected, but the heartbeat hasn't started yet."
   // CLI-agnostic - runs for every adapter (Claude Code, Codex, generic),
   // since battery is a property of the LAPTOP, not of whatever CLI it
   // happens to be running.