clideck-remote 0.1.0

package/LICENSE-REMOTE

@@ -0,0 +1,99 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor: Or Kuntzman
+
+Licensed Work: The CliDeck Remote components in this repository, currently:
+- remote.js
+- DESIGN-remote.md
+- relay/
+
+The Licensed Work is Copyright (c) 2026 Or Kuntzman and contributors.
+
+Additional Use Grant: You may make Production Use of the Licensed Work only as
+part of the official CliDeck desktop application, and only to access or use the
+remote or mobile service operated by or for the Licensor, for your own personal
+use or internal business use. You may not make Production Use of the Licensed
+Work to offer, operate, host, white-label, resell, or enable a hosted or
+managed service, relay service, mobile control service, or similar product that
+competes with CliDeck Remote or materially substitutes for it.
+
+Change Date: 2030-03-12
+
+Change License: GPL version 3.0 or later
+
+For information about alternative licensing arrangements, contact:
+licensing@clideck.dev
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved. "Business
+Source License" is a trademark of MariaDB plc.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under the
+terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or modified
+form from a third party, the terms and conditions set forth in this License
+apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your
+works, and to refer to it using the trademark "Business Source License", as
+long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+To specify as the Change License the GPL Version 2.0 or any later version, or
+a license that is compatible with GPL Version 2.0 or a later version, where
+"compatible" means that software provided under the Change License can be
+included in a program with software provided under GPL Version 2.0 or a later
+version. Licensor may specify additional Change Licenses without limitation.
+
+To either: (a) specify an additional grant of rights to use that does not
+impose any additional restriction on the right granted in this License, as the
+Additional Use Grant; or (b) insert the text "None" to specify a Change Date.
+
+Not to modify this License in any other way.

package/README.md

@@ -0,0 +1 @@
+# clideck-remote

package/bin/clideck-remote.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// clideck-remote CLI — interface contract for CliDeck OSS app
+// Commands: status, pair, unpair
+
+const command = process.argv[2];
+const json = process.argv.includes('--json');
+
+function out(obj) {
+  if (json) process.stdout.write(JSON.stringify(obj) + '\n');
+  else {
+    for (const [k, v] of Object.entries(obj)) console.log(`${k}: ${v}`);
+  }
+}
+
+switch (command) {
+  case 'status':
+    // TODO: check daemon state, relay connection, plan entitlement
+    out({ paired: false, connected: false, url: null, qr: null, plan: 'free' });
+    break;
+
+  case 'pair':
+    // TODO: start relay connection, generate keypair, return QR
+    out({ url: null, qr: null, roomId: null, plan: 'free' });
+    break;
+
+  case 'unpair':
+    // TODO: tear down relay connection
+    out({ ok: true });
+    break;
+
+  case '--version':
+  case '-v':
+    console.log(require('../package.json').version);
+    break;
+
+  case '--help':
+  case '-h':
+  case undefined:
+    console.log(`clideck-remote v${require('../package.json').version}
+
+Usage:
+  clideck-remote status [--json]   Check connection and plan state
+  clideck-remote pair [--json]     Start pairing (relay + QR)
+  clideck-remote unpair [--json]   Disconnect from relay
+  clideck-remote --version         Show version`);
+    break;
+
+  default:
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "clideck-remote",
+  "version": "0.1.0",
+  "description": "Mobile remote access for CliDeck — control your AI agents from your phone",
+  "main": "remote.js",
+  "bin": {
+    "clideck-remote": "bin/clideck-remote.js"
+  },
+  "keywords": [
+    "clideck",
+    "mobile",
+    "remote",
+    "cli",
+    "ai",
+    "agent"
+  ],
+  "author": "Or Kuntzman",
+  "license": "SEE LICENSE IN LICENSE-REMOTE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rustykuntz/clideck-remote.git"
+  },
+  "homepage": "https://clideck.dev/",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ws": "^8.19.0"
+  }
+}

package/remote.js

@@ -0,0 +1,302 @@
+// Licensed under the Business Source License 1.1.
+// See LICENSE-REMOTE at the repository root.
+//
+// CliDeck Remote — desktop-side relay connector with E2E encryption.
+// Connects outbound to the Cloudflare relay, encrypts all session content.
+
+const { webcrypto } = require('crypto');
+const subtle = webcrypto.subtle;
+const WebSocket = require('ws');
+const transcript = require('./transcript');
+const activity = require('./activity');
+
+const RELAY_URL = process.env.CLIDECK_RELAY_URL || 'wss://remote.clideck.dev';
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+
+let ctx = null; // { getSessions, getResumable, getConfig, input, resume, close, broadcast }
+
+// Pairing state
+let ws = null;
+let keyPair = null;
+let aesKey = null;
+let roomId = null;
+let subscribedSession = null;
+let paired = false;
+let pairingUrl = null;
+let lastMobileInput = null;
+
+// --- Base64url ---
+
+function toB64(buf) {
+  return Buffer.from(buf).toString('base64url');
+}
+function fromB64(s) {
+  return Buffer.from(s, 'base64url');
+}
+
+// --- Crypto (ECDH P-256 + HKDF + AES-256-GCM) ---
+
+async function generateKeyPair() {
+  return subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+}
+
+async function exportPub(kp) {
+  return toB64(await subtle.exportKey('raw', kp.publicKey));
+}
+
+async function deriveAesKey(privateKey, peerPubB64, room) {
+  const peerPub = await subtle.importKey(
+    'raw', fromB64(peerPubB64), { name: 'ECDH', namedCurve: 'P-256' }, false, []
+  );
+  const bits = await subtle.deriveBits({ name: 'ECDH', public: peerPub }, privateKey, 256);
+  const hkdf = await subtle.importKey('raw', bits, 'HKDF', false, ['deriveKey']);
+  return subtle.deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt: ENC.encode(room), info: ENC.encode('clideck-e2ee-v1') },
+    hkdf, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']
+  );
+}
+
+async function encrypt(key, obj) {
+  const iv = webcrypto.getRandomValues(new Uint8Array(12));
+  const ct = await subtle.encrypt({ name: 'AES-GCM', iv }, key, ENC.encode(JSON.stringify(obj)));
+  return JSON.stringify({ type: 'e', iv: toB64(iv), ct: toB64(ct) });
+}
+
+async function decrypt(key, msg) {
+  const plain = await subtle.decrypt({ name: 'AES-GCM', iv: fromB64(msg.iv) }, key, fromB64(msg.ct));
+  return JSON.parse(DEC.decode(plain));
+}
+
+// --- Send encrypted message to mobile ---
+
+async function sendToMobile(obj) {
+  if (!ws || ws.readyState !== 1 || !aesKey) return;
+  try { ws.send(await encrypt(aesKey, obj)); }
+  catch (e) { console.error('[remote] encrypt/send failed:', e.message); }
+}
+
+function agentType(id) {
+  return ctx.getSessions()?.get(id)?.presetId || null;
+}
+
+// --- Build full state snapshot for mobile ---
+
+function buildState() {
+  const sessions = ctx.getSessions();
+  const cfg = ctx.getConfig();
+  const active = [...sessions].map(([id, s]) => ({
+    id, name: s.name, commandId: s.commandId, projectId: s.projectId || null,
+    working: s._remoteWorking != null ? !!s._remoteWorking : activity.isActive(id),
+    preview: (s.lastPreview || '').slice(0, 120),
+    lastActivityAt: s.lastActivityAt || null,
+  }));
+  const resumable = (ctx.getResumable() || []).map(s => ({
+    id: s.id, name: s.name, commandId: s.commandId, projectId: s.projectId || null,
+    preview: (s.lastPreview || '').slice(0, 120),
+    lastActivityAt: s.lastActivityAt || null,
+  }));
+  const projects = (cfg?.projects || []).map(p => ({
+    id: p.id, name: p.name, color: p.color,
+  }));
+  return { active, resumable, projects };
+}
+
+function sendState() {
+  const s = buildState();
+  sendToMobile({ type: 'state', active: s.active, resumable: s.resumable, projects: s.projects });
+}
+
+// --- Handle messages from mobile ---
+
+async function handleMobileMessage(raw) {
+  let msg;
+  try { msg = JSON.parse(raw); } catch { return; }
+
+  // Key exchange — mobile sends its public key
+  if (msg.type === 'pub' && msg.key && keyPair) {
+    try {
+      aesKey = await deriveAesKey(keyPair.privateKey, msg.key, roomId);
+      paired = true;
+      console.log('[remote] paired — sending state');
+      sendState();
+      ctx.broadcast({ type: 'remote.status', paired: true, connected: true, url: pairingUrl });
+    } catch (e) {
+      console.error('[remote] key derivation failed:', e.message);
+    }
+    return;
+  }
+
+  // Relay tells us the mobile peer disconnected
+  if (msg.type === 'peer-disconnected' && msg.role === 'mobile') {
+    console.log('[remote] mobile disconnected');
+    paired = false;
+    aesKey = null;
+    subscribedSession = null;
+    ctx.broadcast({ type: 'remote.status', paired: false, connected: true, url: pairingUrl });
+    return;
+  }
+
+  // Relay tells us mobile reconnected — they'll re-send pub to re-derive keys
+  if (msg.type === 'peer-connected' && msg.role === 'mobile') {
+    console.log('[remote] mobile reconnected — awaiting key exchange');
+    return;
+  }
+
+  // Encrypted envelope
+  if (msg.type === 'e' && aesKey) {
+    let plain;
+    try { plain = await decrypt(aesKey, msg); } catch { return; }
+
+    switch (plain.type) {
+      case 'input':
+        if (plain.id && plain.text) {
+          if (plain.text !== '\r') lastMobileInput = plain.text.trim();
+          ctx.input({ id: plain.id, data: plain.text });
+        }
+        break;
+
+      case 'subscribe':
+        if (plain.id) {
+          subscribedSession = plain.id;
+          const turns = transcript.getScreenTurns(plain.id, agentType(plain.id)) || transcript.getLastTurns(plain.id, 4);
+          if (turns.length) sendToMobile({ type: 'history', id: plain.id, turns });
+        }
+        break;
+
+      case 'resume':
+        if (plain.id) {
+          const remoteWs = { send(data) {
+            try { const parsed = JSON.parse(data); if (parsed.type === 'error') sendToMobile({ type: 'error', text: parsed.message }); }
+            catch {}
+          }};
+          ctx.resume({ id: plain.id }, remoteWs, ctx.getConfig());
+        }
+        break;
+
+      case 'close':
+        if (plain.id) ctx.close({ id: plain.id });
+        break;
+    }
+    return;
+  }
+}
+
+// --- Broadcast listener — forward events to mobile ---
+
+function onBroadcast(msg) {
+  if (!paired) return;
+
+  switch (msg.type) {
+    case 'created':
+    case 'closed':
+    case 'sessions.resumable':
+      sendState();
+      if (msg.type === 'closed' && subscribedSession === msg.id) subscribedSession = null;
+      break;
+
+    case 'renamed':
+    case 'session.setProject':
+    case 'session.preview':
+    case 'config':
+      sendState();
+      break;
+
+    case 'session.status': {
+      const s = ctx.getSessions()?.get(msg.id);
+      if (s) s._remoteWorking = msg.working;
+      sendToMobile({ type: 'status', id: msg.id, working: msg.working });
+      break;
+    }
+
+    case 'screen.updated':
+      if (msg.id === subscribedSession) {
+        const turns = transcript.getScreenTurns(msg.id, agentType(msg.id)) || transcript.getLastTurns(msg.id, 2);
+        if (turns?.length) {
+          const last = turns[turns.length - 1];
+          if (last.role === 'agent') sendToMobile({ type: 'turn', id: msg.id, role: 'agent', text: last.text });
+        }
+      }
+      break;
+
+    case 'transcript.append':
+      // Forward desktop-originated user turns to mobile
+      if (msg.role === 'user' && msg.id === subscribedSession) {
+        if (lastMobileInput && msg.text === lastMobileInput) {
+          lastMobileInput = null; // dedupe — mobile already showed it
+        } else {
+          sendToMobile({ type: 'turn', id: msg.id, role: 'user', text: msg.text });
+        }
+      }
+      break;
+  }
+}
+
+// --- WebSocket connection to relay ---
+
+function connectRelay() {
+  if (!roomId) return;
+  const url = `${RELAY_URL}/ws?room=${roomId}&role=desktop`;
+  ws = new WebSocket(url);
+
+  ws.on('open', () => {
+    console.log('[remote] connected to relay');
+    ctx.broadcast({ type: 'remote.status', paired: false, connected: true, url: pairingUrl });
+  });
+
+  ws.on('message', (data) => handleMobileMessage(data.toString()));
+
+  ws.on('close', () => {
+    console.log('[remote] relay disconnected');
+    paired = false;
+    aesKey = null;
+    subscribedSession = null;
+    ctx.broadcast({ type: 'remote.status', paired: false, connected: false, url: pairingUrl });
+    if (roomId) setTimeout(connectRelay, 3000);
+  });
+
+  ws.on('error', (e) => {
+    console.error('[remote] relay error:', e.message);
+  });
+}
+
+// --- Public API ---
+
+async function startPairing() {
+  if (ws) stopPairing();
+
+  roomId = webcrypto.randomUUID();
+  keyPair = await generateKeyPair();
+  const pubB64 = await exportPub(keyPair);
+  paired = false;
+  aesKey = null;
+  subscribedSession = null;
+
+  connectRelay();
+
+  const mobileUrl = RELAY_URL.replace('wss://', 'https://').replace('ws://', 'http://');
+  pairingUrl = `${mobileUrl}/#r=${roomId}&k=${pubB64}`;
+  return { roomId, url: pairingUrl };
+}
+
+function stopPairing() {
+  roomId = null;
+  keyPair = null;
+  aesKey = null;
+  paired = false;
+  pairingUrl = null;
+  subscribedSession = null;
+  if (ws) { try { ws.close(); } catch {} ws = null; }
+}
+
+function isPaired() { return paired; }
+function isConnected() { return ws?.readyState === 1; }
+function getPairingUrl() { return pairingUrl; }
+
+function init(options) {
+  ctx = options;
+}
+
+function shutdown() { stopPairing(); }
+
+module.exports = { init, startPairing, stopPairing, isPaired, isConnected, getPairingUrl, onBroadcast, shutdown };