fix(sovereignty): 审查修复——恢复表白名单扩展（world_snapshots/imports）+ 校验加固 + BOM/大小防御 + 超限提示

Author: Aparencia

client/electron/db/importWhitelist.ts

@@ -0,0 +1,27 @@
+/**
+ * 可导入表白名单（零依赖纯逻辑，供 migration.ts 与测试共用）
+ * Import whitelist (zero-dependency; shared by migration.ts and tests)
+ *
+ * @ai-context: importTable 的合法表 = IndexedDB 迁移白名单（TABLE_MAPPING
+ * 派生，migration.ts 持有）+ 世界恢复扩展（world_snapshots/imports，
+ * schema.ts 新增表）。扩展表单独声明，避免污染迁移流程；isImportableTable
+ * 供世界导出白名单（worldExport.ts WORLD_TABLE_WHITELIST）与迁移白名单
+ * 做一致性校验——导出/恢复信任动作的表名必须可被 importTable 接受。
+ *
+ * @ai-context: Importable tables = migration whitelist + restore-only
+ * extras. Kept separate so the migration flow is untouched; tests assert
+ * every exportable table is importable to prevent whitelist drift.
+ */
+
+/** 世界恢复扩展白名单（schema.ts 新增表，非 IndexedDB 迁移表） */
+export const RESTORE_EXTRA_TABLES = ['world_snapshots', 'imports'] as const;
+export type RestoreExtraTable = (typeof RESTORE_EXTRA_TABLES)[number];
+
+/**
+ * 判断表名是否可被 importTable 导入
+ * @param table - SQLite 表名
+ * @param migrationTables - 迁移白名单（TABLE_MAPPING 派生，由调用方传入）
+ */
+export function isImportableTable(table: string, migrationTables: readonly string[]): boolean {
+  return migrationTables.includes(table) || (RESTORE_EXTRA_TABLES as readonly string[]).includes(table);
+}

client/electron/db/migration.ts

@@ -9,6 +9,7 @@
 
 import type Database from 'better-sqlite3';
 import { getConnection } from './sqliteService.js';
+import { isImportableTable } from './importWhitelist.js';
 import { logger } from '../logger.js';
 
 // ================================================================
@@ -57,8 +58,8 @@ const TABLE_MAPPING: Array<{ dexie: string; sqlite: string }> = [
   { dexie: 'crdtChanges', sqlite: 'crdt_changes' },
 ];
 
-/** 合法的 SQLite 表名集合 */
-const VALID_SQLITE_TABLES = new Set(TABLE_MAPPING.map((m) => m.sqlite));
+/** 合法 SQLite 表名列表（迁移白名单；与 importWhitelist 扩展表共同构成可导入集） */
+const MIGRATION_TABLE_LIST = TABLE_MAPPING.map((m) => m.sqlite);
 
 /** camelCase → snake_case */
 function toSnake(s: string): string {
@@ -91,7 +92,7 @@ export function needsMigration(db: Database.Database): boolean {
  * @returns 成功插入的行数
  */
 export function importTable(sqliteTable: string, rows: Record<string, unknown>[]): number {
-  if (!VALID_SQLITE_TABLES.has(sqliteTable)) {
+  if (!isImportableTable(sqliteTable, MIGRATION_TABLE_LIST)) {
     throw new Error(`[Migration] Table "${sqliteTable}" is not in the migration whitelist`);
   }
 

client/electron/sovereigntyHandlers.ts

@@ -17,7 +17,7 @@
  * then rebuilds the FTS index.
  */
 import { dialog } from 'electron';
-import { writeFile, readFile } from 'fs/promises';
+import { writeFile, readFile, stat } from 'fs/promises';
 import { safeHandle } from './ipcUtils.js';
 import { logger } from './logger.js';
 import { getConnection } from './db/sqliteService.js';
@@ -28,13 +28,16 @@ import {
   buildWorldExport,
   validateWorldImport,
   WORLD_TABLE_WHITELIST,
+  WORLD_EXPORT_MAX_ROWS,
   type WorldTableBundle,
 } from '../src/features/sovereignty/lib/worldExport.js';
 
 /** 快照单行 id（与 useWorldSnapshotSync 的 SNAPSHOT_ID 对齐） / Snapshot row id */
 const SNAPSHOT_ID = 'latest';
 /** 入籍记录导出上限（叙述层防超大响应；恢复层 tables.imports 不受限） */
 const MAX_RECORDS = 5000;
+/** 恢复文件大小防御上限（防超大文件读入内存拖垮 JSON.parse） / Max import file bytes */
+const MAX_IMPORT_BYTES = 256 * 1024 * 1024;
 
 /** 恢复层表白名单（父表在前，满足外键约束；与 worldExport 白名单同源） */
 const EXPORT_TABLES = WORLD_TABLE_WHITELIST;
@@ -94,8 +97,13 @@ export function registerSovereigntyHandlers(): void {
       await writeFile(result.filePath, JSON.stringify(bundle, null, 2), 'utf-8');
       const rowCount = tables.reduce((s, t) => s + t.rows.length, 0);
       const nodeCount = Array.isArray(bundle.graph.nodes) ? bundle.graph.nodes.length : 0;
+      // 对称性提示：导出不受限（备份语义），但超过恢复上限时提醒用户
+      const overLimit = rowCount > WORLD_EXPORT_MAX_ROWS;
+      if (overLimit) {
+        logger.warn(`[Sovereignty] Export exceeds restore limit (${rowCount} > ${WORLD_EXPORT_MAX_ROWS} rows); the file will not be restorable`);
+      }
       logger.info(`[Sovereignty] World exported to ${result.filePath} (${rowCount} rows, ${nodeCount} nodes)`);
-      return { success: true, canceled: false, path: result.filePath };
+      return { success: true, canceled: false, path: result.filePath, overLimit };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       logger.error('[Sovereignty] Export failed', err);
@@ -121,7 +129,14 @@ export function registerSovereigntyHandlers(): void {
     }
 
     try {
-      const text = await readFile(result.filePaths[0], 'utf-8');
+      // 大小防御：超大文件先拒绝，避免全量读入内存 + JSON.parse 内存峰值
+      const fileStat = await stat(result.filePaths[0]);
+      if (fileStat.size > MAX_IMPORT_BYTES) {
+        return { success: false, error: '文件过大（超过 256MB），无法恢复' };
+      }
+      const rawText = await readFile(result.filePaths[0], 'utf-8');
+      // 兼容 Windows 记事本保存的 UTF-8 BOM
+      const text = rawText.charCodeAt(0) === 0xfeff ? rawText.slice(1) : rawText;
       let parsed: unknown;
       try {
         parsed = JSON.parse(text);

client/src/features/sovereignty/lib/importWhitelist.test.ts

@@ -0,0 +1,68 @@
+/**
+ * importWhitelist 单元测试（阶段 D 致命修复：恢复表可导入性）
+ * Import whitelist tests (stage-D fix: restore tables must be importable)
+ *
+ * @ai-context: 回归覆盖阶段 D 致命 bug——importTable 白名单曾不含
+ * world_snapshots/imports，世界恢复必然失败。本测试验证：
+ * ① 世界导出白名单（WORLD_TABLE_WHITELIST）全部表可被 importTable 接受
+ * （防双白名单漂移）；② 迁移白名单表仍可导入（未破坏迁移流程）；
+ * ③ 白名单外表拒绝。零依赖——不加载 better-sqlite3（Electron ABI），
+ * 纯逻辑验证 isImportableTable。
+ *
+ * @ai-context: Regression for the stage-D bug where world_snapshots and
+ * imports were rejected by importTable. Asserts every exportable table
+ * is importable (no whitelist drift), migration tables still work, and
+ * unknown tables are rejected.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  isImportableTable,
+  RESTORE_EXTRA_TABLES,
+} from '../../../../electron/db/importWhitelist.js';
+import { WORLD_TABLE_WHITELIST } from './worldExport';
+
+/** 迁移白名单样例（migration.ts TABLE_MAPPING 子集，覆盖代表性表） */
+const MIGRATION_TABLES = [
+  'note_folders',
+  'notes',
+  'flashcard_decks',
+  'flashcards',
+  'flashcard_reviews',
+  'feynman_notes',
+  'feynman_summaries',
+  'feynman_weak_points',
+  'app_settings',
+  'pomodoro_sessions',
+] as const;
+
+describe('isImportableTable（可导入表白名单）', () => {
+  it('世界导出白名单全部表均可导入（防双白名单漂移）', () => {
+    // Arrange & Act & Assert
+    for (const table of WORLD_TABLE_WHITELIST) {
+      expect(isImportableTable(table, MIGRATION_TABLES), `表 ${table} 应可导入`).toBe(true);
+    }
+  });
+
+  it('世界恢复扩展表含 world_snapshots 与 imports（阶段 D 致命修复回归）', () => {
+    // Arrange & Act & Assert
+    expect(RESTORE_EXTRA_TABLES).toContain('world_snapshots');
+    expect(RESTORE_EXTRA_TABLES).toContain('imports');
+    expect(isImportableTable('world_snapshots', MIGRATION_TABLES)).toBe(true);
+    expect(isImportableTable('imports', MIGRATION_TABLES)).toBe(true);
+  });
+
+  it('迁移白名单表仍可导入（扩展不破坏迁移流程）', () => {
+    // Arrange & Act & Assert
+    for (const table of MIGRATION_TABLES) {
+      expect(isImportableTable(table, MIGRATION_TABLES), `迁移表 ${table} 应可导入`).toBe(true);
+    }
+  });
+
+  it('白名单外表拒绝（evil_table / 空串）', () => {
+    // Arrange & Act & Assert
+    expect(isImportableTable('evil_table', MIGRATION_TABLES)).toBe(false);
+    expect(isImportableTable('', MIGRATION_TABLES)).toBe(false);
+    expect(isImportableTable('notes', [])).toBe(false); // 迁移列表为空时仅扩展表可导入
+    expect(isImportableTable('world_snapshots', [])).toBe(true);
+  });
+});

client/src/features/sovereignty/lib/worldExport.test.ts

@@ -197,4 +197,40 @@ describe('validateWorldImport（恢复前校验）', () => {
     expect(result.ok).toBe(false);
     if (!result.ok) expect(result.error).toContain('恢复数据量超出上限');
   });
+
+  it('拒绝 rows 含非对象行（防 Object.keys(null) 崩溃与空列 SQL）', () => {
+    // Arrange
+    const raw = makeBundle({ tables: [{ table: 'notes', rows: [{ id: 'n1' }, null, 'raw', 42] }] });
+
+    // Act
+    const result = validateWorldImport(raw);
+
+    // Assert
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain('含非对象行');
+  });
+
+  it('拒绝入籍记录超限（100001 条 > 100000）', () => {
+    // Arrange
+    const records = Array.from({ length: 100_001 }, (_, i) => ({ id: `r${i}` }));
+    const raw = makeBundle({ settlingRecords: records });
+
+    // Act
+    const result = validateWorldImport(raw);
+
+    // Assert
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain('入籍记录超出上限');
+  });
+
+  it('接受空世界（零记录 + 空恢复层）：迁移前或清库后仍可恢复', () => {
+    // Arrange
+    const raw = makeBundle({ settlingRecords: [], tables: [] });
+
+    // Act
+    const result = validateWorldImport(raw);
+
+    // Assert
+    expect(result.ok).toBe(true);
+  });
 });

client/src/features/sovereignty/lib/worldExport.ts

@@ -23,6 +23,8 @@ export const WORLD_EXPORT_FORMAT_VERSION = 1;
 export const WORLD_EXPORT_MAX_NODES = 5000;
 /** 恢复层总行数上限 / Max total restore rows */
 export const WORLD_EXPORT_MAX_ROWS = 100_000;
+/** 叙述层入籍记录上限（防超大文件拖垮解析，与行上限对称） / Max settling records */
+export const WORLD_EXPORT_MAX_RECORDS = 100_000;
 
 /** 恢复层表名白名单（与 schema.ts / importTable 白名单对齐） / Restore whitelist */
 export const WORLD_TABLE_WHITELIST = [
@@ -157,6 +159,12 @@ export function validateWorldImport(raw: unknown): WorldImportResult {
   if (!Array.isArray(raw.settlingRecords)) {
     return { ok: false, error: '入籍记录格式不正确' };
   }
+  if (raw.settlingRecords.length > WORLD_EXPORT_MAX_RECORDS) {
+    return {
+      ok: false,
+      error: `入籍记录超出上限（${raw.settlingRecords.length} 条 > ${WORLD_EXPORT_MAX_RECORDS}）`,
+    };
+  }
 
   if (!Array.isArray(raw.tables)) {
     return { ok: false, error: '恢复数据缺失（tables 不是数组）' };
@@ -172,6 +180,12 @@ export function validateWorldImport(raw: unknown): WorldImportResult {
     if (!Array.isArray(item.rows)) {
       return { ok: false, error: `恢复数据格式不正确（${item.table}.rows 不是数组）` };
     }
+    for (const row of item.rows) {
+      // 行必须是对象：防 Object.keys(null) 崩溃与空列 SQL 错误，且保证列名可推断
+      if (!isPlainObject(row)) {
+        return { ok: false, error: `恢复数据格式不正确（${item.table}.rows 含非对象行）` };
+      }
+    }
     totalRows += item.rows.length;
   }
   if (totalRows > WORLD_EXPORT_MAX_ROWS) {

client/src/pages/settings/WorldSovereigntySection.tsx

@@ -26,6 +26,8 @@ interface ExportResult {
   success: boolean;
   canceled?: boolean;
   path?: string | null;
+  /** 导出行数超过恢复上限（文件仍可作备份，但无法恢复） */
+  overLimit?: boolean;
   error?: string;
 }
 
@@ -52,11 +54,15 @@ export function WorldSovereigntySection() {
       if (res.canceled) return; // 用户取消保存框：静默
       if (res.success) {
         soundPlayer.play('data_export');
-        toast({
-          type: 'success',
-          message: res.path ? `世界之书已导出：${res.path}` : '世界之书已导出',
-          silent: true,
-        });
+        if (res.overLimit) {
+          toast({ type: 'error', message: '导出完成，但数据量超过恢复上限（10 万行）——此文件可作备份，无法用于恢复' });
+        } else {
+          toast({
+            type: 'success',
+            message: res.path ? `世界之书已导出：${res.path}` : '世界之书已导出',
+            silent: true,
+          });
+        }
       } else {
         toast({ type: 'error', message: res.error ?? '世界导出失败，请重试' });
       }