fix(client): 客户端低危修复——文件读写限制/更新状态机/崩溃恢复/迁移可诊断/preload白名单统一

- CL-L1: fs:read-file 禁止读取数据库文件（keban.db*）+ 50MB 大小限制
- CL-L2: ai:set-gateway-url 拒绝自定义端口与路径（CSP connect-src 动态放行的攻击面收窄）
- CL-L3: backup:save 校验 JSON 内容与 100MB 上限
- CL-L4: 自动更新状态机（idle/checking/available/downloading/downloaded/error）——install 仅 downloaded 态、download 仅 available 态，防止任意时机触发退出安装与并发下载
- CL-L5: chatRepository.getMessages limit 钳制 1-200
- CL-L6: preload 专用监听 API（onWindowClosing/onMaximizedChanged/onSyncBeforeQuit）纳入 ALLOWED_EVENT_CHANNELS 校验
- CL-L7: schema ALTER 区分 duplicate column（幂等成功）与其他错误（记日志且不推进 user_version，保留重试机会）
- CL-L8: video_record_stopped 确认事件校验绑定窗口 sender
- CL-L9: ai:stream 活跃流在发起窗口销毁时 abort 清理
- CL-L10: uncaughtException 崩溃恢复——DB checkpoint 落盘后 relaunch，不再带病运行
- CL-L11: saveAIConfigAction 网关地址同步失败抛错 + gatewaySyncError 状态可观测

验证: npm run lint (0 errors) + npm run test (875 passed) + npm run build 全部通过

Author: Aparencia

client/electron/ai/streamHandler.ts

@@ -75,6 +75,18 @@ export function registerStreamHandler(): void {
       const abortController = new AbortController();
       activeStreams.set(requestId, abortController);
 
+      // CL-L9: 发起流式请求的窗口销毁时清理活跃流——否则 for await 继续从
+      // 网关拉取直到流结束/超时（默认 300s），多次开关窗口累积残留流
+      const wc = event.sender;
+      wc.once('destroyed', () => {
+        const controller = activeStreams.get(requestId);
+        if (controller) {
+          controller.abort();
+          activeStreams.delete(requestId);
+          logger.info(`[AI] [stream] Window destroyed, aborted stream: requestId=${requestId}`);
+        }
+      });
+
       // 50ms 节流缓冲
       let chunkBuffer = '';
       let throttleTimer: ReturnType<typeof setTimeout> | null = null;

client/electron/db/chatRepository.ts

@@ -84,12 +84,14 @@ export function insertMessage(msg: Omit<MessageRow, 'id' | 'created_at'> & { id?
 
 export function getMessages(sessionId: string, limit = 50, before?: number): MessageRow[] {
   const db = getConnection();
+  // CL-L5: limit 钳制——渲染进程可传任意大值导致一次拉取整表消息经 IPC 全量传输
+  const safeLimit = Math.min(Math.max(1, Math.floor(limit)), 200);
   if (before) {
     return db.prepare('SELECT * FROM assistant_messages WHERE session_id = ? AND created_at < ? ORDER BY created_at DESC LIMIT ?')
-      .all(sessionId, before, limit) as MessageRow[];
+      .all(sessionId, before, safeLimit) as MessageRow[];
   }
   return db.prepare('SELECT * FROM assistant_messages WHERE session_id = ? ORDER BY created_at DESC LIMIT ?')
-    .all(sessionId, limit) as MessageRow[];
+    .all(sessionId, safeLimit) as MessageRow[];
 }
 
 // ── 触发记录 ──────────────────────────────────────────────────

client/electron/db/schema.ts

@@ -5,6 +5,7 @@
  * @ai-context: SQLite 建表 DDL 唯一权威源——新增表需同步 dbIpcHandlers.ALLOWED_TABLES 白名单。
  */
 import type Database from 'better-sqlite3';
+import { logger } from '../logger.js';
 
 export const SCHEMA_VERSION = 8;
 
@@ -231,12 +232,12 @@ export function initializeSchema(db: Database.Database): void {
   // v2 迁移：FSRS-5 扩展字段（条件 ALTER TABLE，幂等）
   const currentVersion = db.pragma('user_version', { simple: true }) as number;
   if (currentVersion < 2) {
-    try {
-      db.exec(`ALTER TABLE flashcards ADD COLUMN stability REAL DEFAULT NULL`);
-    } catch { /* 列已存在 */ }
-    try {
-      db.exec(`ALTER TABLE flashcards ADD COLUMN difficulty REAL DEFAULT NULL`);
-    } catch { /* 列已存在 */ }
+    const ok = alterTableAddColumn(db, `ALTER TABLE flashcards ADD COLUMN stability REAL DEFAULT NULL`)
+      && alterTableAddColumn(db, `ALTER TABLE flashcards ADD COLUMN difficulty REAL DEFAULT NULL`);
+    if (!ok) {
+      logger.error('[Schema] v2 迁移失败，不设置 user_version，下次启动重试');
+      return;
+    }
   }
 
   // v3 迁移：CRDT 同步引擎元数据表
@@ -246,12 +247,12 @@ export function initializeSchema(db: Database.Database): void {
 
   // v4 迁移：search_index 表增加 entity_id 和 entity_type 列
   if (currentVersion < 4) {
-    try {
-      db.exec(`ALTER TABLE search_index ADD COLUMN entity_id TEXT`);
-    } catch { /* 列已存在 */ }
-    try {
-      db.exec(`ALTER TABLE search_index ADD COLUMN entity_type TEXT`);
-    } catch { /* 列已存在 */ }
+    const ok = alterTableAddColumn(db, `ALTER TABLE search_index ADD COLUMN entity_id TEXT`)
+      && alterTableAddColumn(db, `ALTER TABLE search_index ADD COLUMN entity_type TEXT`);
+    if (!ok) {
+      logger.error('[Schema] v4 迁移失败，不设置 user_version，下次启动重试');
+      return;
+    }
   }
 
   // v5 迁移：AI 助手会话/消息/触发表（CREATE IF NOT EXISTS 幂等）
@@ -266,13 +267,32 @@ export function initializeSchema(db: Database.Database): void {
   // v8 迁移：知识入籍——imports 表（DDL 已含在 SCHEMA_DDL）；
   // notes/flashcards 增加 source_ref 溯源列（条件 ALTER TABLE，幂等，不破坏存量）
   if (currentVersion < 8) {
-    try {
-      db.exec(`ALTER TABLE notes ADD COLUMN source_ref TEXT`);
-    } catch { /* 列已存在 */ }
-    try {
-      db.exec(`ALTER TABLE flashcards ADD COLUMN source_ref TEXT`);
-    } catch { /* 列已存在 */ }
+    const ok = alterTableAddColumn(db, `ALTER TABLE notes ADD COLUMN source_ref TEXT`)
+      && alterTableAddColumn(db, `ALTER TABLE flashcards ADD COLUMN source_ref TEXT`);
+    if (!ok) {
+      logger.error('[Schema] v8 迁移失败，不设置 user_version，下次启动重试');
+      return;
+    }
   }
 
   db.pragma(`user_version = ${SCHEMA_VERSION}`);
 }
+
+/**
+ * CL-L7: 条件 ALTER TABLE ADD COLUMN——"列已存在"（幂等重试）静默视为成功，
+ * 其他错误（SQLITE_BUSY/磁盘/权限）记录日志并返回 false，由调用方决定
+ * 不推进 user_version（保留下次启动重试机会），避免迁移失败被永久掩盖。
+ */
+function alterTableAddColumn(db: Database.Database, sql: string): boolean {
+  try {
+    db.exec(sql);
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/duplicate column/i.test(msg)) {
+      return true; // 列已存在：幂等重试的正常情况
+    }
+    logger.error(`[Schema] ALTER TABLE 失败（非 duplicate column）: ${msg}`);
+    return false;
+  }
+}

client/electron/main.ts

@@ -115,6 +115,20 @@ if (!gotTheLock) {
 
   process.on('uncaughtException', (error) => {
     logger.crash('Uncaught Exception', error);
+    // CL-L10: 主进程在未知异常后处于"带病运行"状态（数据库连接可能损坏、
+    // 事件监听可能缺失）；记录后执行崩溃恢复——checkpoint 落盘 + relaunch
+    try {
+      const { checkpointAndClose } = require('./db/sqliteService.js') as typeof import('./db/sqliteService.js');
+      checkpointAndClose();
+      logger.info('[Main] Database checkpointed during crash recovery');
+    } catch (checkpointErr) {
+      logger.error('[Main] Checkpoint during crash recovery failed', checkpointErr);
+    }
+    // 延迟重启，确保崩溃日志已落盘
+    setTimeout(() => {
+      app.relaunch();
+      app.exit(1);
+    }, 500);
   });
 
   process.on('unhandledRejection', (reason) => {
@@ -225,6 +239,15 @@ if (!gotTheLock) {
       if (parsedUrl.protocol !== 'https:' && parsedUrl.hostname !== 'localhost' && parsedUrl.hostname !== '127.0.0.1') {
         throw new Error('生产环境必须使用 HTTPS');
       }
+      // CL-L2: 端口与路径收紧——同一受信任域名的任意端口/路径都会被 CSP
+      // connect-src 动态放行，同域攻击者可诱导请求到非预期端点；路径后缀
+      // 还会污染后续 ${base}${apiPath} 拼接
+      if (parsedUrl.port !== '') {
+        throw new Error('不允许自定义端口，请使用默认端口');
+      }
+      if (parsedUrl.pathname !== '/' && parsedUrl.pathname !== '') {
+        throw new Error('不允许自定义路径');
+      }
 
       await setRuntimeGatewayUrl(url);
       return { success: true };

client/electron/preload.ts

@@ -218,8 +218,12 @@ contextBridge.exposeInMainWorld('electronAPI', {
       console.warn(`[preload] 不允许的发送 channel: ${channel}`);
     }
   },
-  /** 监听主进程发出的窗口关闭事件 */
+  /** 监听主进程发出的窗口关闭事件（CL-L6: 统一纳入 ALLOWED_EVENT_CHANNELS 校验） */
   onWindowClosing: (callback: () => void) => {
+    if (!(ALLOWED_EVENT_CHANNELS as readonly string[]).includes('window:closing')) {
+      console.warn('[preload] 不允许的事件 channel: window:closing');
+      return () => {};
+    }
     const handler = () => callback();
     ipcRenderer.on('window:closing', handler);
     return () => ipcRenderer.removeListener('window:closing', handler);
@@ -234,12 +238,20 @@ contextBridge.exposeInMainWorld('electronAPI', {
   windowClose: () => ipcRenderer.invoke('window:close'),
   windowIsMaximized: () => ipcRenderer.invoke('window:isMaximized') as Promise<boolean>,
   onMaximizedChanged: (callback: (isMaximized: boolean) => void) => {
+    if (!(ALLOWED_EVENT_CHANNELS as readonly string[]).includes('window:maximized-changed')) {
+      console.warn('[preload] 不允许的事件 channel: window:maximized-changed');
+      return () => {};
+    }
     const handler = (_event: unknown, isMaximized: boolean) => callback(isMaximized);
     ipcRenderer.on('window:maximized-changed', handler);
     return () => ipcRenderer.removeListener('window:maximized-changed', handler);
   },
-  /** 监听退出前同步事件 */
+  /** 监听退出前同步事件（CL-L6: 统一纳入 ALLOWED_EVENT_CHANNELS 校验） */
   onSyncBeforeQuit: (callback: () => void) => {
+    if (!(ALLOWED_EVENT_CHANNELS as readonly string[]).includes('sync:before-quit')) {
+      console.warn('[preload] 不允许的事件 channel: sync:before-quit');
+      return () => {};
+    }
     const handler = () => callback();
     ipcRenderer.on('sync:before-quit', handler);
     return () => ipcRenderer.removeListener('sync:before-quit', handler);

client/electron/storageIpcHandlers.ts

@@ -58,6 +58,19 @@ export function registerStorageIpcHandlers(): void {
       throw new Error('不允许读取该路径的文件');
     }
 
+    // CL-L1: 禁止直接读取数据库文件（keban.db*）——整库读取是应用内数据泄露面；
+    // 大小限制 50MB，防止大文件读取占用主进程内存与 IPC 带宽
+    const fileName = path.basename(resolvedPath);
+    if (fileName === DB_FILE_NAME || fileName.startsWith(DB_FILE_NAME + '.')) {
+      throw new Error('不允许直接读取数据库文件');
+    }
+    const { stat } = await import('fs/promises');
+    const MAX_READ_SIZE = 50 * 1024 * 1024;
+    const fileStat = await stat(resolvedPath);
+    if (fileStat.size > MAX_READ_SIZE) {
+      throw new Error(`文件超过大小上限（50MB，当前 ${Math.ceil(fileStat.size / 1024 / 1024)}MB）`);
+    }
+
     const buffer = await readFile(resolvedPath);
     return buffer.buffer; // 返回 ArrayBuffer
   });
@@ -170,6 +183,18 @@ export function registerStorageIpcHandlers(): void {
       return { success: false, canceled: true, path: null };
     }
 
+    // CL-L3: 校验备份内容——仅接受 JSON 字符串且大小 ≤100MB，
+    // 防止注入代码借"保存备份"对话框将任意内容覆盖写入文件
+    const MAX_BACKUP_SIZE = 100 * 1024 * 1024;
+    if (typeof data !== 'string' || data.length > MAX_BACKUP_SIZE) {
+      return { success: false, canceled: false, path: null, error: '备份数据无效或超过 100MB 上限' };
+    }
+    try {
+      JSON.parse(data);
+    } catch {
+      return { success: false, canceled: false, path: null, error: '备份数据不是合法 JSON' };
+    }
+
     try {
       await writeFile(result.filePath, data, 'utf-8');
       return { success: true, canceled: false, path: result.filePath };

client/electron/updater.ts

@@ -67,6 +67,18 @@ const DOWNLOAD_RETRY_DELAYS = [30_000, 60_000, 120_000]; // 30s, 60s, 120s
 /** 标记当前是否正在下载（用于区分 error 事件来源） */
 let isDownloading = false;
 
+/**
+ * CL-L4: 更新状态机——主进程侧状态校验，防止渲染层在任意时机调用
+ * install（会立即退出应用）或重复触发 download（并发下载）
+ */
+type UpdateState = 'idle' | 'checking' | 'available' | 'downloading' | 'downloaded' | 'error';
+let updateState: UpdateState = 'idle';
+
+function setUpdateState(state: UpdateState): void {
+  updateState = state;
+  logger.info(`[AutoUpdater] State → ${state}`);
+}
+
 /**
  * 设置自动检查开关
  * 由 main.ts 的 IPC handler 调用
@@ -127,11 +139,13 @@ export function initAutoUpdater(mainWindow: BrowserWindow | null): void {
 
   autoUpdater.on('checking-for-update', () => {
     logger.info('[AutoUpdater] Checking for update...');
+    setUpdateState('checking');
     sendToRenderer(mainWindow, 'update-status', { status: 'checking' });
   });
 
   autoUpdater.on('update-available', (info: UpdateInfo) => {
     logger.info(`[AutoUpdater] Update available: v${info.version}`);
+    setUpdateState('available');
     sendToRenderer(mainWindow, 'update-status', {
       status: 'available',
       version: info.version,
@@ -141,10 +155,12 @@ export function initAutoUpdater(mainWindow: BrowserWindow | null): void {
 
   autoUpdater.on('update-not-available', () => {
     logger.info('[AutoUpdater] No update available');
+    setUpdateState('idle');
     sendToRenderer(mainWindow, 'update-status', { status: 'not-available' });
   });
 
   autoUpdater.on('download-progress', (progress: ProgressInfo) => {
+    setUpdateState('downloading');
     sendToRenderer(mainWindow, 'update-status', {
       status: 'downloading',
       percent: Math.round(progress.percent),
@@ -157,6 +173,7 @@ export function initAutoUpdater(mainWindow: BrowserWindow | null): void {
     // 下载成功，重置重试计数
     downloadRetryCount = 0;
     isDownloading = false;
+    setUpdateState('downloaded');
     sendToRenderer(mainWindow, 'update-status', {
       status: 'downloaded',
       version: info.version,
@@ -259,14 +276,25 @@ export function checkForUpdate(): void {
 }
 
 export function downloadUpdate(): void {
+  // CL-L4: 仅 available 态允许下载，防止重复触发并发下载
+  if (updateState !== 'available') {
+    logger.warn(`[AutoUpdater] downloadUpdate ignored (state=${updateState}, expected=available)`);
+    return;
+  }
   isDownloading = true;
   downloadRetryCount = 0;
+  setUpdateState('downloading');
   autoUpdater.downloadUpdate().catch((err) => {
     logger.error('[AutoUpdater] Download failed', err);
   });
 }
 
 export function installUpdate(): void {
+  // CL-L4: 仅 downloaded 态允许安装——quitAndInstall 会立即退出应用并安装
+  if (updateState !== 'downloaded') {
+    logger.warn(`[AutoUpdater] installUpdate ignored (state=${updateState}, expected=downloaded)`);
+    return;
+  }
   autoUpdater.quitAndInstall();
 }
 

client/electron/videoRecorder.ts

@@ -182,7 +182,12 @@ export class VideoRecorder {
         ipcMain.removeListener('video_record_stopped', onConfirmed);
         resolve();
       }, STOP_CONFIRM_TIMEOUT_MS);
-      function onConfirmed(): void {
+      function onConfirmed(event: Electron.IpcMainEvent): void {
+        // CL-L8: 仅接受绑定窗口的确认——非绑定窗口可发送伪造事件提前结束
+        // 等待窗口（与 SEC-005 sender 验证策略一致）
+        if (win && !win.isDestroyed() && event.sender.id !== win.webContents.id) {
+          return;
+        }
         clearTimeout(timeoutId);
         resolve();
       }

client/src/stores/useSettingsStore.ts

@@ -42,6 +42,8 @@ interface SettingsState {
   aiConfig: AIConfig;
   /** 音效设置（分类控制） */
   soundSettings: SoundSettings;
+  /** CL-L11: 主进程网关地址同步失败信息（null 表示同步成功或未执行） */
+  gatewaySyncError: string | null;
 
   /** 更新 AI 配置（内存态） */
   setAIConfig: (config: AIConfig) => void;
@@ -51,8 +53,8 @@ interface SettingsState {
    */
   updateSoundSettings: (partial: Partial<SoundSettings>) => void;
 
-  /** 保存 AI 配置到 localStorage */
-  saveAIConfigAction: () => void;
+  /** 保存 AI 配置到 localStorage（网关地址同步失败时抛错供 UI 提示） */
+  saveAIConfigAction: () => Promise<void>;
 }
 
 /** 初始化时加载音效设置并同步到 SoundPlayer */
@@ -62,6 +64,7 @@ soundPlayer.updateSettings(initialSoundSettings);
 export const useSettingsStore = create<SettingsState>((set, get) => ({
   aiConfig: getAIConfig(),
   soundSettings: initialSoundSettings,
+  gatewaySyncError: null,
 
   setAIConfig: (config) => set({ aiConfig: config }),
 
@@ -78,13 +81,23 @@ export const useSettingsStore = create<SettingsState>((set, get) => ({
     persistSoundSettings(next);
   },
 
-  saveAIConfigAction: () => {
+  saveAIConfigAction: async () => {
     const { aiConfig } = get();
     persistAIConfig(aiConfig);
     updateAIGatewayUrl(aiConfig.gatewayUrl);
     // 同步网关地址到 Electron 主进程（主进程无法访问 localStorage）
     if (window.electronAPI) {
-      window.electronAPI.invoke('ai:set-gateway-url', aiConfig.gatewayUrl).catch(() => {});
+      try {
+        await window.electronAPI.invoke('ai:set-gateway-url', aiConfig.gatewayUrl);
+        set({ gatewaySyncError: null });
+      } catch (err) {
+        // CL-L11: 主进程校验失败（URL 格式/域名/HTTPS/端口/路径）必须让用户感知，
+        // 否则 UI 显示"已保存"但实际仍用旧网关地址——AI 功能静默异常且难以定位
+        const message = err instanceof Error ? err.message : String(err);
+        console.error('[Settings] 网关地址同步失败:', message);
+        set({ gatewaySyncError: message });
+        throw new Error(`网关地址保存失败：${message}`);
+      }
     }
   },
 }));