claude-remote 0.3.0 → 0.4.0

package/README.md

@@ -59,9 +59,56 @@ claude-remote /path/to/project --resume abc123
 PORT=8080 claude-remote
 ```
 
-### 3. App 连接
+### 3. 安全认证
 
-安装 Android App 后，在设置页输入服务器地址连接。根据你的网络环境，有以下三种方式：
+`claude-remote` 内置 Token 鉴权机制，防止未授权的客户端控制你的 Claude Code。
+
+#### 工作原理
+
+1. **首次启动时自动生成 Token** —— 桥接器启动后会自动生成一个随机 Token，持久化到 `~/.claude-remote-token` 文件，并在启动 banner 中显示
+2. **客户端必须提供 Token** —— App 在添加/编辑服务器时填入 Token，连接时通过 `hello` 握手消息发送给服务器
+3. **服务器验证 Token** —— 使用 `crypto.timingSafeEqual` 安全比对，防止时序攻击。验证通过后才发送会话数据
+4. **认证超时** —— 连接后 5 秒内未完成认证将被自动断开（close code 4002）
+5. **认证失败** —— Token 不匹配时连接立即关闭（close code 4001），App 会弹出编辑对话框提示修正
+
+#### Token 来源优先级
+
+| 优先级 | 来源 | 说明 |
+|--------|------|------|
+| 1 | `--token <value>` | CLI 参数，最高优先级 |
+| 2 | `CLAUDE_REMOTE_TOKEN` 环境变量 | 适合 CI/脚本场景 |
+| 3 | `~/.claude-remote-token` 文件 | 自动生成并持久化，首次启动时创建 |
+
+```bash
+# 使用自定义 Token
+claude-remote --token my-secret-token
+
+# 通过环境变量
+CLAUDE_REMOTE_TOKEN=my-secret-token claude-remote
+
+# 默认行为：自动生成并保存到 ~/.claude-remote-token
+claude-remote
+```
+
+#### 禁用认证
+
+> ⚠️ 仅在安全网络环境下使用，如本地开发或 VPN 内网。
+
+```bash
+# CLI 参数
+claude-remote --no-auth
+
+# 环境变量
+NO_AUTH=1 claude-remote
+```
+
+#### App 端配置
+
+在连接中心添加或编辑服务器时，填入 Token 字段即可。Token 输入框支持密码显示/隐藏切换。认证失败时 App 会自动弹出编辑对话框，方便修正 Token。
+
+### 4. App 连接
+
+安装 Android App 后，在连接中心添加服务器地址连接。根据你的网络环境，有以下三种方式：
 
 #### 方式一：局域网直连
 
@@ -107,7 +154,7 @@ wss://xxx.trycloudflare.com
 
 > 适合在外网或移动网络下远程控制，支持 HTTPS/WSS 加密。
 
-### 4. 编译 Android App
+### 5. 编译 Android App
 
 ```bash
 cd app
@@ -143,6 +190,7 @@ npx tauri android dev
 | 工具调用追踪 | 折叠式 step group，shimmer 加载动效 |
 | 权限队列 | 批量审批，计数器显示剩余数量 |
 | 模式切换 | 四种模式一键切换，彩色状态标识 |
+| Token 鉴权 | 自动生成 Token，timingSafeEqual 安全比对，防止未授权访问 |
 | 对话压缩 | /compact 带 spinner 遮罩，压缩完自动恢复 |
 | 斜杠命令菜单 | 输入 `/` 弹出命令面板 |
 | 模型切换 | 底部面板选择，toast 即时反馈 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-remote",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Remote control bridge for Claude Code REPL - drive from phone/WebUI",
   "main": "server.js",
   "bin": {

package/server.js

@@ -4,6 +4,7 @@ const path = require('path');
 const os = require('os');
 const pty = require('node-pty');
 const { WebSocketServer, WebSocket } = require('ws');
+const crypto = require('crypto');
 const { execSync } = require('child_process');
 
 // --- CLI argument parsing ---
@@ -26,6 +27,8 @@ const BLOCKED_FLAGS = new Set([
   '--help', '-h',                    // exits immediately
   '--init-only',                     // exits immediately
   '--maintenance',                   // exits immediately
+  '--token',                         // bridge-only: auth token
+  '--no-auth',                       // bridge-only: disable auth
 ]);
 
 // Flags that consume the next argument as a value
@@ -42,6 +45,7 @@ const FLAGS_WITH_VALUE = new Set([
   '--output-format', '--input-format', '--json-schema',
   '--max-budget-usd', '--max-turns', '--fallback-model',
   '--permission-prompt-tool',
+  '--token',                         // bridge-only: auth token
 ]);
 
 function parseCliArgs(argv) {
@@ -49,6 +53,8 @@ function parseCliArgs(argv) {
   let cwd = null;
   const claudeArgs = [];
   const blocked = [];
+  let token = null;
+  let noAuth = false;
 
   let i = 0;
   while (i < rawArgs.length) {
@@ -75,6 +81,25 @@ function parseCliArgs(argv) {
     const eqIdx = arg.indexOf('=');
     const flagName = eqIdx > 0 ? arg.substring(0, eqIdx) : arg;
 
+    // Intercept bridge-only flags
+    if (flagName === '--token') {
+      if (eqIdx > 0) {
+        token = arg.substring(eqIdx + 1);
+      } else if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('-')) {
+        i++;
+        token = rawArgs[i];
+      } else {
+        token = '';
+      }
+      i++;
+      continue;
+    }
+    if (flagName === '--no-auth') {
+      noAuth = true;
+      i++;
+      continue;
+    }
+
     if (BLOCKED_FLAGS.has(flagName)) {
       blocked.push(flagName);
       if (eqIdx > 0) {
@@ -96,10 +121,36 @@ function parseCliArgs(argv) {
     i++;
   }
 
-  return { cwd: cwd || process.cwd(), claudeArgs, blocked };
+  return { cwd: cwd || process.cwd(), claudeArgs, blocked, token, noAuth };
 }
 
-const { cwd: _parsedCwd, claudeArgs: CLAUDE_EXTRA_ARGS, blocked: _blockedArgs } = parseCliArgs(process.argv);
+const { cwd: _parsedCwd, claudeArgs: CLAUDE_EXTRA_ARGS, blocked: _blockedArgs, token: _cliToken, noAuth: _cliNoAuth } = parseCliArgs(process.argv);
+
+// --- Auth token resolution ---
+const AUTH_TOKEN_ENV_VAR = 'CLAUDE_REMOTE_TOKEN';
+const LEGACY_AUTH_TOKEN_ENV_VAR = 'TOKEN';
+const AUTH_DISABLED = _cliNoAuth || process.env.NO_AUTH === '1';
+const TOKEN_FILE = path.join(os.homedir(), '.claude-remote-token');
+const UNUSED_LEGACY_TOKEN_ENV = !!process.env[LEGACY_AUTH_TOKEN_ENV_VAR] && !process.env[AUTH_TOKEN_ENV_VAR];
+
+function resolveAuthToken() {
+  if (AUTH_DISABLED) return null;
+  // 1. CLI --token
+  if (_cliToken) return _cliToken;
+  // 2. Namespaced env
+  if (process.env[AUTH_TOKEN_ENV_VAR]) return process.env[AUTH_TOKEN_ENV_VAR];
+  // 3. Persisted file
+  try {
+    const saved = fs.readFileSync(TOKEN_FILE, 'utf8').trim();
+    if (saved) return saved;
+  } catch {}
+  // 4. Generate and persist
+  const generated = crypto.randomBytes(24).toString('base64url');
+  try { fs.writeFileSync(TOKEN_FILE, generated + '\n', { mode: 0o600 }); } catch {}
+  return generated;
+}
+
+const AUTH_TOKEN = resolveAuthToken();
 
 // --- Config ---
 const PORT = parseInt(process.env.PORT || '3100', 10);
@@ -107,6 +158,11 @@ let CWD = _parsedCwd;
 const CLAUDE_HOME = path.join(os.homedir(), '.claude');
 const CLAUDE_STATE_FILE = path.join(os.homedir(), '.claude.json');
 const PROJECTS_DIR = path.join(CLAUDE_HOME, 'projects');
+const AUTH_HELLO_TIMEOUT_MS = 5000;
+const WS_CLOSE_AUTH_FAILED = 4001;
+const WS_CLOSE_AUTH_TIMEOUT = 4002;
+const WS_CLOSE_REASON_AUTH_FAILED = 'auth_failed';
+const WS_CLOSE_REASON_AUTH_TIMEOUT = 'auth_timeout';
 
 // --- State ---
 let claudeProc = null;
@@ -129,6 +185,7 @@ let tailCatchingUp = false; // true while reading historical transcript content
 const isTTY = process.stdin.isTTY && process.stdout.isTTY;
 const LEGACY_REPLAY_DELAY_MS = 1500;
 const IMAGE_UPLOAD_TTL_MS = 15 * 60 * 1000;
+const IMAGE_UPLOAD_DIR = path.join(CLAUDE_HOME, 'remote-uploads');
 let turnStateVersion = 0;
 let turnState = {
   phase: 'idle',
@@ -161,6 +218,10 @@ function wsLabel(ws) {
   return `ws#${ws && ws._bridgeId ? ws._bridgeId : '?'}${clientId}`;
 }
 
+function isAuthenticatedClient(ws) {
+  return !!ws && ws.readyState === WebSocket.OPEN && !!ws._authenticated;
+}
+
 function sendWs(ws, msg, context = '') {
   if (!ws || ws.readyState !== WebSocket.OPEN) return false;
   ws.send(JSON.stringify(msg));
@@ -399,7 +460,7 @@ const server = http.createServer((req, res) => {
       }
 
       // No WebUI clients → fall back to terminal prompt
-      const clients = [...wss.clients].filter(c => c.readyState === WebSocket.OPEN);
+      const clients = [...wss.clients].filter(isAuthenticatedClient);
       if (clients.length === 0) {
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ decision: 'ask' }));
@@ -505,7 +566,7 @@ function broadcast(msg) {
   const raw = JSON.stringify(msg);
   const recipients = [];
   for (const ws of wss.clients) {
-    if (ws.readyState === WebSocket.OPEN) {
+    if (isAuthenticatedClient(ws)) {
       ws.send(raw);
       recipients.push(wsLabel(ws));
     }
@@ -566,14 +627,18 @@ function cleanupImageUpload(uploadId) {
 
 function cleanupClientUploads(ws) {
   for (const [uploadId, upload] of pendingImageUploads) {
-    if (upload.owner === ws) cleanupImageUpload(uploadId);
+    if (upload.owner === ws && !upload.submitted) cleanupImageUpload(uploadId);
   }
 }
 
 function createTempImageFile(buffer, mediaType, uploadId) {
-  const tmpDir = process.env.CLAUDE_CODE_TMPDIR || os.tmpdir();
+  const isLinux = process.platform !== 'win32' && process.platform !== 'darwin';
+  const tmpDir = isLinux
+    ? IMAGE_UPLOAD_DIR
+    : (process.env.CLAUDE_CODE_TMPDIR || os.tmpdir());
   const type = String(mediaType || 'image/png').toLowerCase();
   const ext = type.includes('jpeg') || type.includes('jpg') ? '.jpg' : '.png';
+  fs.mkdirSync(tmpDir, { recursive: true });
   const tmpFile = path.join(tmpDir, `bridge_upload_${uploadId}_${Date.now()}${ext}`);
   fs.writeFileSync(tmpFile, buffer);
   return tmpFile;
@@ -588,11 +653,7 @@ setInterval(() => {
   }
 }, 60 * 1000).unref();
 
-wss.on('connection', (ws, req) => {
-  ws._bridgeId = ++nextWsId;
-  ws._clientInstanceId = '';
-  log(`WS connected: ${wsLabel(ws)} remote=${req.socket.remoteAddress || '?'} ua=${JSON.stringify(req.headers['user-agent'] || '')}`);
-
+function sendInitialMessages(ws) {
   sendWs(ws, {
     type: 'status',
     status: claudeProc ? 'running' : 'starting',
@@ -610,20 +671,86 @@ wss.on('connection', (ws, req) => {
       lastSeq: latestEventSeq(),
     }, 'initial');
   }
+}
+
+function sendAuthOk(ws) {
+  sendWs(ws, {
+    type: 'auth_ok',
+    authRequired: !AUTH_DISABLED,
+  }, 'auth_ok');
+}
+
+wss.on('connection', (ws, req) => {
+  ws._bridgeId = ++nextWsId;
+  ws._clientInstanceId = '';
+  ws._authenticated = AUTH_DISABLED; // skip auth if disabled
+  ws._authTimer = null;
+  log(`WS connected: ${wsLabel(ws)} remote=${req.socket.remoteAddress || '?'} ua=${JSON.stringify(req.headers['user-agent'] || '')} authRequired=${!AUTH_DISABLED}`);
+
+  // If auth is disabled, send initial messages immediately
+  if (AUTH_DISABLED) {
+    sendAuthOk(ws);
+    sendInitialMessages(ws);
+  } else {
+    ws._authTimer = setTimeout(() => {
+      if (ws.readyState !== WebSocket.OPEN || ws._authenticated) return;
+      log(`Auth timeout for ${wsLabel(ws)}`);
+      ws.close(WS_CLOSE_AUTH_TIMEOUT, WS_CLOSE_REASON_AUTH_TIMEOUT);
+    }, AUTH_HELLO_TIMEOUT_MS);
+  }
 
   // New clients should explicitly request a resume window. Keep a delayed
   // full replay fallback so older clients still work.
   ws._resumeHandled = false;
-  ws._legacyReplayTimer = setTimeout(() => {
-    if (ws.readyState !== WebSocket.OPEN || ws._resumeHandled) return;
-    ws._resumeHandled = true;
-    sendReplay(ws, null);
-  }, LEGACY_REPLAY_DELAY_MS);
+  ws._legacyReplayTimer = null;
+  if (AUTH_DISABLED) {
+    ws._legacyReplayTimer = setTimeout(() => {
+      if (ws.readyState !== WebSocket.OPEN || ws._resumeHandled) return;
+      ws._resumeHandled = true;
+      sendReplay(ws, null);
+    }, LEGACY_REPLAY_DELAY_MS);
+  }
 
   ws.on('message', async (raw) => {
     let msg;
     try { msg = JSON.parse(raw); } catch { return; }
 
+    // --- Authentication gate ---
+    if (!ws._authenticated) {
+      if (msg.type !== 'hello') return; // ignore non-hello when not authenticated
+      ws._clientInstanceId = String(msg.clientInstanceId || ws._clientInstanceId || '');
+      log(`WS hello from ${wsLabel(ws)} page=${JSON.stringify(msg.page || '')} ua=${JSON.stringify(msg.userAgent || '')}`);
+
+      const clientToken = String(msg.token || '');
+      if (!AUTH_TOKEN || !clientToken) {
+        log(`Auth failed for ${wsLabel(ws)}: missing token`);
+        ws.close(WS_CLOSE_AUTH_FAILED, WS_CLOSE_REASON_AUTH_FAILED);
+        return;
+      }
+      const a = Buffer.from(AUTH_TOKEN, 'utf8');
+      const b = Buffer.from(clientToken, 'utf8');
+      if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
+        log(`Auth failed for ${wsLabel(ws)}: invalid token`);
+        ws.close(WS_CLOSE_AUTH_FAILED, WS_CLOSE_REASON_AUTH_FAILED);
+        return;
+      }
+      ws._authenticated = true;
+      if (ws._authTimer) {
+        clearTimeout(ws._authTimer);
+        ws._authTimer = null;
+      }
+      log(`Auth OK for ${wsLabel(ws)}`);
+
+      sendAuthOk(ws);
+      sendInitialMessages(ws);
+      ws._legacyReplayTimer = setTimeout(() => {
+        if (ws.readyState !== WebSocket.OPEN || ws._resumeHandled) return;
+        ws._resumeHandled = true;
+        sendReplay(ws, null);
+      }, LEGACY_REPLAY_DELAY_MS);
+      return;
+    }
+
     switch (msg.type) {
       case 'hello':
         ws._clientInstanceId = String(msg.clientInstanceId || ws._clientInstanceId || '');
@@ -860,13 +987,16 @@ wss.on('connection', (ws, req) => {
           break;
         }
         try {
+          const shouldCleanupAfterSubmit = process.platform === 'win32' || process.platform === 'darwin';
           handlePreparedImageUpload({
             tmpFile: upload.tmpFile,
             mediaType: upload.mediaType,
             text: msg.text || '',
             logLabel: upload.name || uploadId,
-            onCleanup: () => cleanupImageUpload(uploadId),
+            onCleanup: shouldCleanupAfterSubmit ? () => cleanupImageUpload(uploadId) : null,
           });
+          upload.submitted = true;
+          upload.updatedAt = Date.now();
           setTurnState('running', { reason: 'image_submit' });
           sendUploadStatus(ws, uploadId, 'submitted');
         } catch (err) {
@@ -932,6 +1062,10 @@ wss.on('connection', (ws, req) => {
   });
 
   ws.on('close', () => {
+    if (ws._authTimer) {
+      clearTimeout(ws._authTimer);
+      ws._authTimer = null;
+    }
     if (ws._legacyReplayTimer) {
       clearTimeout(ws._legacyReplayTimer);
       ws._legacyReplayTimer = null;
@@ -1493,11 +1627,27 @@ function handlePreparedImageUpload({ tmpFile, mediaType, text, logLabel = '', on
 
   const isWin = process.platform === 'win32';
   const isMac = process.platform === 'darwin';
+  const isLinux = !isWin && !isMac;
 
   try {
     const stat = fs.statSync(tmpFile);
     log(`Image ready: ${logLabel || path.basename(tmpFile)} (${stat.size} bytes)`);
 
+    if (isLinux) {
+      const quotedPath = JSON.stringify(tmpFile);
+      const trimmedText = (text || '').trim();
+      const prompt = trimmedText
+        ? `Please analyze the image at this path: ${quotedPath}\n\nUser note:\n${trimmedText}`
+        : `Analyze this image: ${quotedPath}`;
+
+      claudeProc.write(prompt);
+      setTimeout(() => {
+        if (claudeProc) claudeProc.write('\r');
+        log(`Sent Linux image path prompt: ${tmpFile}`);
+      }, 150);
+      return;
+    }
+
     if (isWin) {
       const psCmd = `Add-Type -AssemblyName System.Drawing; Add-Type -AssemblyName System.Windows.Forms; $img = [System.Drawing.Image]::FromFile('${tmpFile.replace(/'/g, "''")}'); [System.Windows.Forms.Clipboard]::SetImage($img); $img.Dispose()`;
       execSync(`powershell -NoProfile -STA -Command "${psCmd}"`, { timeout: 10000 });
@@ -1563,6 +1713,11 @@ function handleImageUpload(msg) {
       mediaType: msg.mediaType,
       text: msg.text || '',
     });
+    if (process.platform !== 'win32' && process.platform !== 'darwin') {
+      setTimeout(() => {
+        try { fs.unlinkSync(tmpFile); } catch {}
+      }, IMAGE_UPLOAD_TTL_MS).unref();
+    }
     setTurnState('running', { reason: 'legacy_image_upload' });
   } catch (err) {
     log(`Image upload error: ${err.message}`);
@@ -1684,6 +1839,14 @@ server.listen(PORT, '0.0.0.0', () => {
   CWD:    ${CWD}
   Log:    ${LOG_FILE}
 `;
+  if (AUTH_DISABLED) {
+    banner += `  Auth:   DISABLED (no authentication)\n`;
+  } else {
+    banner += `  Token:  ${AUTH_TOKEN}\n`;
+  }
+  if (UNUSED_LEGACY_TOKEN_ENV) {
+    banner += `  Note:   Ignoring legacy ${LEGACY_AUTH_TOKEN_ENV_VAR}; use ${AUTH_TOKEN_ENV_VAR} instead\n`;
+  }
   if (CLAUDE_EXTRA_ARGS.length > 0) {
     banner += `  Args:   claude ${CLAUDE_EXTRA_ARGS.join(' ')}\n`;
   }