ysagc-agent 0.1.0

package/src/pairing.js

@@ -0,0 +1,157 @@
+/**
+ * 配对流程（Agent 侧，T-M0-12）
+ * - 生成 6 位一次性配对码（10 分钟过期）
+ * - 定时上报后端 POST {backendUrl}/api/agent/pairing（预共享密钥签名，后端 T-M0-04 实现）
+ * - 收到 pairing.handshake → 签发 256 位 deviceToken → 写入本地白名单 + 持久化
+ * 后端未就绪/不可达时：码仍在本机显示（console），不阻塞使用
+ */
+'use strict';
+
+const crypto = require('crypto');
+const https = require('https');
+const http = require('http');
+const logger = require('./logger');
+const { saveConfig } = require('./config');
+
+const CODE_TTL_MS = 10 * 60 * 1000;
+const REPORT_INTERVAL_MS = 60 * 1000;
+const PRE_SHARED_SECRET = process.env.YSAGC_AGENT_PAIR_SECRET || 'ysagc-agent-pairing-v1';
+
+let current = null; // { code, agentId, createdAt }
+let reportTimer = null;
+let configRef = null;
+
+function generateCode() {
+  // 排除易混淆字符
+  const alphabet = '23456789';
+  let code = '';
+  const bytes = crypto.randomBytes(6);
+  for (let i = 0; i < 6; i++) code += alphabet[bytes[i] % alphabet.length];
+  return code;
+}
+
+function agentId() {
+  // 稳定 agentId：存于配置目录，无则生成
+  const { CONFIG_DIR } = require('./config');
+  const fs = require('fs');
+  const path = require('path');
+  const p = path.join(CONFIG_DIR, 'agent-id');
+  try {
+    if (fs.existsSync(p)) return fs.readFileSync(p, 'utf8').trim();
+  } catch {
+    /* ignore */
+  }
+  const id = crypto.randomUUID();
+  try {
+    fs.writeFileSync(p, id);
+  } catch {
+    /* ignore */
+  }
+  return id;
+}
+
+function sign(body) {
+  return crypto.createHmac('sha256', PRE_SHARED_SECRET).update(JSON.stringify(body)).digest('hex');
+}
+
+function postJson(url, body) {
+  return new Promise((resolve) => {
+    const data = JSON.stringify(body);
+    const mod = url.startsWith('https') ? https : http;
+    const u = new URL(url);
+    const req = mod.request(
+      {
+        hostname: u.hostname,
+        port: u.port || (u.protocol === 'https:' ? 443 : 80),
+        path: u.pathname + u.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(data),
+          'x-agent-signature': sign(body),
+        },
+        timeout: 8000,
+      },
+      (res) => {
+        let buf = '';
+        res.on('data', (c) => (buf += c));
+        res.on('end', () => {
+          try {
+            resolve({ status: res.statusCode, body: JSON.parse(buf || '{}') });
+          } catch {
+            resolve({ status: res.statusCode, body: {} });
+          }
+        });
+      }
+    );
+    req.on('timeout', () => req.destroy());
+    req.on('error', (e) => resolve({ status: 0, error: e.message }));
+    req.write(data);
+    req.end();
+  });
+}
+
+function rotateCode() {
+  current = { code: generateCode(), agentId: agentId(), createdAt: Date.now() };
+  console.log(`\n🔑 配对码: ${current.code}（10 分钟内有效，请在网站“设备管理”输入）\n`);
+  logger.info(`[pairing] 生成新配对码 ${current.code}`);
+  report();
+  return current;
+}
+
+async function report() {
+  const cfg = configRef ? configRef() : {};
+  const url = (cfg.backendUrl || '').replace(/\/$/, '') + '/api/agent/pairing';
+  if (!cfg.backendUrl) return;
+  try {
+    const res = await postJson(url, {
+      code: current.code,
+      agentId: current.agentId,
+      meta: { platform: `${process.platform} ${process.arch}`, hostname: require('os').hostname() },
+    });
+    if (res.status === 200) logger.info(`[pairing] 配对码已上报后端 ${url}`);
+    else logger.debug(`[pairing] 上报后端返回 ${res.status}`);
+  } catch (e) {
+    logger.debug(`[pairing] 上报后端失败: ${e.message}`);
+  }
+}
+
+function startPairing(getConfig) {
+  configRef = getConfig;
+  rotateCode();
+  reportTimer = setInterval(() => {
+    if (!current || Date.now() - current.createdAt > CODE_TTL_MS) rotateCode();
+    else report();
+  }, REPORT_INTERVAL_MS);
+  reportTimer.unref && reportTimer.unref();
+  // 注册 RPC：pairing.handshake（网站配对成功后由前端直连触发）
+  const { register } = require('./rpc');
+  register('pairing.handshake', async (params = {}) => {
+    const { code } = params;
+    if (!current || code !== current.code) {
+      throw new (require('./rpc').RpcError)('E_PAIRING_CODE_INVALID', '配对码无效或已过期');
+    }
+    if (Date.now() - current.createdAt > CODE_TTL_MS) {
+      throw new (require('./rpc').RpcError)('E_PAIRING_CODE_EXPIRED', '配对码已过期，请重新获取');
+    }
+    // 签发 deviceToken（256 位）
+    const deviceToken = crypto.randomBytes(32).toString('hex');
+    const hash = crypto.createHash('sha256').update(deviceToken).digest('hex');
+    const cfg = configRef();
+    if (!cfg.deviceTokenWhitelist.includes(hash)) {
+      // 1) 内存同步（auth 校验读内存配置）2) 持久化到 agent.json
+      cfg.deviceTokenWhitelist = [...cfg.deviceTokenWhitelist, hash];
+      saveConfig({ deviceTokenWhitelist: cfg.deviceTokenWhitelist });
+    }
+    current = null; // 单次使用
+    logger.info('[pairing] 握手成功，已签发 deviceToken 并加入白名单');
+    return { deviceToken, agentId: agentId(), agentVersion: require('../package.json').version, protocolVersion: 1 };
+  });
+}
+
+function stopPairing() {
+  if (reportTimer) clearInterval(reportTimer);
+  reportTimer = null;
+}
+
+module.exports = { startPairing, stopPairing, generateCode, agentId };

package/src/rpc.js

@@ -0,0 +1,62 @@
+/**
+ * JSON-RPC 2.0 分发框架（控制通道）
+ * - 请求：{jsonrpc:"2.0", id, method, params}
+ * - 响应：{jsonrpc:"2.0", id, result} | {jsonrpc:"2.0", id, error:{code, message, data:{code}}}
+ * - 事件：{jsonrpc:"2.0", method:"event.xxx", params}（服务端主动推送）
+ * 错误码见需求 7.4：data.code 为业务错误码（E_*）
+ */
+'use strict';
+
+const methods = new Map();
+
+/** 注册 RPC 方法 */
+function register(name, handler) {
+  if (methods.has(name)) throw new Error(`duplicate rpc method: ${name}`);
+  methods.set(name, handler);
+}
+
+function has(name) {
+  return methods.has(name);
+}
+
+/**
+ * 业务错误：throw new RpcError('E_PATH_ESCAPE', '越界路径', -32603)
+ */
+class RpcError extends Error {
+  constructor(code, message, rpcCode = -32603) {
+    super(message);
+    this.name = 'RpcError';
+    this.code = code; // E_* 业务错误码
+    this.rpcCode = rpcCode;
+  }
+}
+
+/**
+ * 处理一条 JSON-RPC 请求
+ * @param {object} msg 已 JSON.parse 的帧
+ * @param {object} ctx { socket, ws, deviceId, send, sendBinary }
+ * @returns {Promise<object|null>} 响应对象（null 表示无需响应）
+ */
+async function handleRequest(msg, ctx) {
+  const { id, method, params } = msg;
+  if (!method || typeof method !== 'string') {
+    return { jsonrpc: '2.0', id: id ?? null, error: { code: -32600, message: 'Invalid Request', data: { code: 'E_INVALID_REQUEST' } } };
+  }
+  if (!methods.has(method)) {
+    return { jsonrpc: '2.0', id: id ?? null, error: { code: -32601, message: `Method not found: ${method}`, data: { code: 'E_METHOD_NOT_FOUND' } } };
+  }
+  try {
+    const result = await methods.get(method)(params || {}, ctx);
+    // 通知类（id 为 null/undefined）无响应
+    if (id === null || id === undefined) return null;
+    return { jsonrpc: '2.0', id, result: result === undefined ? null : result };
+  } catch (e) {
+    const rpcCode = e && e.rpcCode ? e.rpcCode : -32603;
+    const code = e && e.code ? e.code : 'E_INTERNAL';
+    const message = e && e.message ? e.message : 'Internal error';
+    if (id === null || id === undefined) return null;
+    return { jsonrpc: '2.0', id, error: { code: rpcCode, message, data: { code } } };
+  }
+}
+
+module.exports = { register, has, handleRequest, RpcError };

package/src/sandbox.js

@@ -0,0 +1,178 @@
+/**
+ * 路径沙箱（T-M0-13）
+ * - allowlist（用户显式添加的项目根目录）内才能操作
+ * - realpath 校验，符号链接逃逸一律拒绝
+ * - .git 内部路径拒绝（文件操作层面；Git 操作走 git.* 方法）
+ * - 越界一律记审计日志（本地 + 上报后端由后端接口负责）
+ * 原则：前端不拼路径，一切路径由本模块校验后再执行。
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { RpcError } = require('./rpc');
+const logger = require('./logger');
+
+function normalizeRoot(root) {
+  if (typeof root !== 'string' || !root.trim()) return null;
+  const abs = path.isAbsolute(root) ? path.normalize(root) : path.resolve(root);
+  try {
+    const real = fs.realpathSync(abs);
+    return real;
+  } catch {
+    return abs;
+  }
+}
+
+class Sandbox {
+  constructor(roots = []) {
+    this.roots = new Set();
+    for (const r of roots) {
+      const n = normalizeRoot(r);
+      if (n) this.roots.add(n);
+    }
+  }
+
+  listRoots() {
+    return [...this.roots];
+  }
+
+  addRoot(root, opts = {}) {
+    const n = normalizeRoot(root);
+    if (!n) throw new RpcError('E_INVALID_PATH', '无效的项目目录');
+    if (!opts.force && !fs.existsSync(n)) {
+      throw new RpcError('E_PATH_NOT_FOUND', `目录不存在: ${root}`);
+    }
+    if (!fs.statSync(n).isDirectory()) {
+      throw new RpcError('E_PATH_NOT_DIR', `不是目录: ${root}`);
+    }
+    // 防过宽路径
+    const blocked = ['C:\\', 'C:/', '/', path.parse(n).root];
+    if (blocked.includes(n.replace(/[\\/]+$/, ''))) {
+      throw new RpcError('E_PATH_TOO_WIDE', '不允许授权过宽的路径（磁盘根目录等）');
+    }
+    // 禁止与已有项目互为父子目录
+    for (const r of this.roots) {
+      if (r === n || r.startsWith(n + path.sep) || n.startsWith(r + path.sep)) {
+        throw new RpcError('E_PATH_OVERLAP', '该目录与已添加的项目互为父子目录，不允许');
+      }
+    }
+    this.roots.add(n);
+    logger.info(`[sandbox] 已授权项目目录: ${n}`);
+    return n;
+  }
+
+  removeRoot(root) {
+    const n = normalizeRoot(root);
+    if (n && this.roots.has(n)) {
+      this.roots.delete(n);
+      logger.info(`[sandbox] 已移除项目目录授权: ${n}`);
+      return true;
+    }
+    return false;
+  }
+
+  hasRoots() {
+    return this.roots.size > 0;
+  }
+
+  auditEscape(target, reason) {
+    logger.warn(`[sandbox][越界拒绝] target=${target} reason=${reason}`);
+    // 审计记录透传给后端（workspace_audit_logs），由后端接口负责写入
+    return { opType: 'fs.access', target: String(target).slice(0, 500), result: 'denied', errorCode: 'E_PATH_ESCAPE', reason };
+  }
+
+  /**
+   * 解析并校验目标路径
+   * @param {string} target 绝对路径或相对路径
+   * @param {string} [base] 相对路径基准（项目根）
+   * @param {{allowMissing?:boolean}} [opts]
+   * @returns {{abs:string, root:string, rel:string}}
+   */
+  resolve(target, base, opts = {}) {
+    if (typeof target !== 'string') target = '';
+    // 空路径 = 项目根目录（fs.list 根 / trash 根等场景）
+    if (!target.trim() && (!base || !String(base).trim())) {
+      const first = [...this.roots][0];
+      if (!first) throw new RpcError('E_INVALID_PATH', '路径为空');
+      target = first;
+    }
+    // 相对路径：以 base 为基准；未传 base 时以已授权项目根为基准（前端不拼路径，只传相对路径）
+    let abs;
+    if (path.isAbsolute(target)) {
+      abs = path.normalize(target);
+    } else if (base && String(base).trim()) {
+      abs = path.resolve(base, target);
+    } else {
+      const roots = [...this.roots];
+      if (roots.length === 1) {
+        abs = path.join(roots[0], target);
+      } else if (roots.length > 1) {
+        const hit = roots.find((r) => fs.existsSync(path.join(r, target)));
+        if (hit) abs = path.join(hit, target);
+        else abs = path.join(roots[0], target);
+      } else {
+        abs = path.resolve(process.cwd(), target);
+      }
+    }
+
+    // 1. 词法检查（快速拒绝越界）
+    const lexicalRoot = [...this.roots].find((r) => abs === r || abs.startsWith(r + path.sep));
+    if (!lexicalRoot) {
+      this.auditEscape(target, 'lexical escape');
+      throw new RpcError('E_PATH_ESCAPE', `路径越界（不在任何已授权项目目录内）: ${target}`);
+    }
+
+    // 2. realpath 校验（防符号链接逃逸）
+    let real;
+    try {
+      real = fs.realpathSync(abs);
+    } catch {
+      real = null;
+    }
+    if (real) {
+      const realRoot = [...this.roots].find((r) => real === r || real.startsWith(r + path.sep));
+      if (!realRoot) {
+        this.auditEscape(target, 'symlink escape');
+        throw new RpcError('E_PATH_ESCAPE', '路径经符号链接指向项目目录之外，已拒绝');
+      }
+      return this.finalize(real, realRoot);
+    }
+
+    // 3. 目标不存在（新建场景）：最近的已存在父目录必须落在沙箱内
+    let parent = path.dirname(abs);
+    for (let i = 0; i < 64; i++) {
+      let rp;
+      try {
+        rp = fs.realpathSync(parent);
+      } catch {
+        rp = null;
+      }
+      if (rp) {
+        const okRoot = [...this.roots].find((r) => rp === r || rp.startsWith(r + path.sep));
+        if (!okRoot) {
+          this.auditEscape(target, 'parent symlink escape');
+          throw new RpcError('E_PATH_ESCAPE', '路径的父目录经符号链接指向项目目录之外，已拒绝');
+        }
+        return this.finalize(abs, okRoot);
+      }
+      const next = path.dirname(parent);
+      if (next === parent) break;
+      parent = next;
+    }
+    this.auditEscape(target, 'unresolvable');
+    throw new RpcError('E_PATH_ESCAPE', '路径无法解析到任何已授权项目目录');
+  }
+
+  finalize(abs, root) {
+    const rel = path.relative(root, abs);
+    // .git 内部拒绝（Git 操作走 git.*，不允许文件层直改 .git）
+    if (rel === '.git' || rel.startsWith('.git' + path.sep) || rel.split(path.sep).includes('.git')) {
+      this.auditEscape(abs, 'git internal');
+      throw new RpcError('E_PATH_GIT_INTERNAL', '禁止直接操作 .git 内部文件，请使用 Git 面板');
+    }
+    return { abs, root, rel };
+  }
+}
+
+module.exports = { Sandbox, normalizeRoot };