@onyx-p/imlib-web 3.0.1 → 3.0.2

package/README.md

@@ -1,14 +1,117 @@
-## ac-imlib-web
+# ac-imlib-web
 
+Electron-only IM SDK with a Signal-style encrypted local message database.
 
-### 安装
-```
+## 安装
+
+```bash
 npm install @onyx-p/imlib-web --save
 ```
 
-### 代码集成
+The database runtime requires Electron 30 or newer. The local database uses
+`@signalapp/sqlcipher`; review its AGPL-3.0-only license before distribution.
+
+## Electron 主进程
+
+Initialize the database service after `app.whenReady()`. This creates one
+primary writer worker and three reader workers. The primary connection owns all
+writes and schema migrations.
+
+```js
+const { app, BrowserWindow } = require('electron')
+const {
+  initializeDatabaseMain
+} = require('@onyx-p/imlib-web/main')
+
+let database
+
+app.whenReady().then(() => {
+  database = initializeDatabaseMain({
+    // Recommended: restrict IPC to your own renderer origin.
+    isTrustedEvent(event) {
+      return event.senderFrame?.url.startsWith('file://') === true
+    }
+  })
+
+  const window = new BrowserWindow({
+    webPreferences: {
+      contextIsolation: true,
+      nodeIntegration: false,
+      preload: require.resolve('@onyx-p/imlib-web/preload')
+    }
+  })
+})
+```
+
+If the application already has a preload script, load the database preload
+entry from that script instead:
+
+```js
+require('@onyx-p/imlib-web/preload')
 ```
-// ES
+
+The preload exposes only `window.acimDatabase.request()`. Renderer code cannot
+execute arbitrary SQL or invoke arbitrary Electron channels.
+
+## Renderer
+
+The public IM API remains in the default package entry. Await user setup so the
+SQLCipher database, schema migrations, and legacy import finish before message
+synchronization starts.
+
+```js
 import * as ACIMLib from '@onyx-p/imlib-web'
+
+ACIMLib.init({ appkey: 'your-app-key' })
+await ACIMLib.setUserLogged(profile)
+await ACIMLib.connect()
+```
+
+## 数据库与迁移
+
+- Database files are stored below Electron's `userData/sql` directory.
+- Account identifiers are hashed before being used as filenames.
+- Each account receives an independent random 256-bit SQLCipher key.
+- Keys are encrypted with Electron `safeStorage` before they are written to
+  `database-keys.json`.
+- Schema changes run automatically through ordered `PRAGMA user_version`
+  migrations in the primary worker.
+- SQLCipher runs in WAL mode with foreign keys enabled and full synchronous
+  durability.
+
+On first open, the renderer looks for the previous IndexedDB database named
+`im_message_cache_1_<appKey>_<userId>`. Existing `messages_new` and
+`dialogStates_new` records are read in bounded batches, legacy content fields
+are decrypted, and records are idempotently inserted into SQLCipher. Completion
+is recorded only after every batch commits. The old IndexedDB database is kept
+as a recovery copy.
+
+Migration runs automatically. It can also be retried explicitly with progress:
+
+```js
+const result = await ACIMLib.migrateLegacyDatabase(progress => {
+  console.log(
+    `Migrated ${progress.processedMessages} messages and ` +
+    `${progress.processedDialogStates} dialog states`
+  )
+})
+
+console.log(result)
+// { migrated: true|false, messages: number, dialogStates: number }
 ```
 
+If migration is interrupted, call the same API again. Imports use upserts, so
+already committed batches are safe to repeat.
+
+## 消息搜索
+
+单会话搜索接口保持不变。全局搜索使用 Signal 风格的 FTS5 前缀匹配，
+按消息时间倒序返回，默认最多 500 条：
+
+```js
+const result = await ACIMLib.searchMessages('项目进度')
+console.log(result.data)
+
+// 可选：限制返回数量
+const recent = await ACIMLib.searchMessages('signal', 50)
+```

package/database/main.cjs

@@ -0,0 +1,341 @@
+'use strict';
+
+var node_path = require('node:path');
+var electron = require('electron');
+var node_crypto = require('node:crypto');
+var node_fs = require('node:fs');
+var node_worker_threads = require('node:worker_threads');
+
+class DatabaseKeyStore {
+    directory;
+    safeStorage;
+    filePath;
+    constructor(directory, safeStorage) {
+        this.directory = directory;
+        this.safeStorage = safeStorage;
+        this.filePath = node_path.join(directory, 'database-keys.json');
+    }
+    getOrCreate(accountId) {
+        const keys = this.readKeys();
+        const encrypted = keys[accountId];
+        if (encrypted) {
+            const key = this.safeStorage.decryptString(Buffer.from(encrypted, 'base64'));
+            this.validateKey(key);
+            return key;
+        }
+        const key = node_crypto.randomBytes(32).toString('hex');
+        keys[accountId] = Buffer.from(this.safeStorage.encryptString(key)).toString('base64');
+        this.writeKeys(keys);
+        return key;
+    }
+    readKeys() {
+        try {
+            const parsed = JSON.parse(node_fs.readFileSync(this.filePath, 'utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error('Database key file must contain an object');
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return Object.create(null);
+            }
+            throw error;
+        }
+    }
+    writeKeys(keys) {
+        node_fs.mkdirSync(this.directory, { recursive: true });
+        const temporaryPath = `${this.filePath}.tmp`;
+        node_fs.writeFileSync(temporaryPath, JSON.stringify(keys), { mode: 0o600 });
+        node_fs.renameSync(temporaryPath, this.filePath);
+    }
+    validateKey(key) {
+        if (!/^[0-9a-f]{64}$/i.test(key)) {
+            throw new Error('Stored database key is invalid');
+        }
+    }
+}
+
+const DATABASE_CHANNEL = 'acim-database:request';
+const READ_METHOD_NAMES = [
+    'getMessages',
+    'getLatestMessage',
+    'getLatestMessages',
+    'getDialogLoadedState',
+    'getMessageById',
+    'getMessageByUId',
+    'getMessageIdRange',
+    'searchMessages',
+    'searchTextMessages',
+    'getLegacyMigrationState'
+];
+const WRITE_METHOD_NAMES = [
+    'addMessages',
+    'clearConversationCache',
+    'clearAllCache',
+    'removeMessagesByUId',
+    'updateMessageReceiptStatus',
+    'clearBurnAfterReadingExpiredMessages',
+    'upsertMessage',
+    'convertToRecallMessages',
+    'importLegacyBatch',
+    'completeLegacyMigration'
+];
+const READ_METHODS = new Set(READ_METHOD_NAMES);
+const WRITE_METHODS = new Set(WRITE_METHOD_NAMES);
+function serializeDatabaseError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack
+        };
+    }
+    return {
+        name: 'Error',
+        message: String(error),
+        stack: undefined
+    };
+}
+
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isTopLevelSender(event) {
+    if (!isRecord(event)) {
+        return false;
+    }
+    const candidate = event;
+    return (candidate.senderFrame !== undefined &&
+        candidate.senderFrame === candidate.sender?.mainFrame);
+}
+function parseRequest(value) {
+    if (!isRecord(value) || typeof value.type !== 'string') {
+        throw new Error('Invalid database IPC request');
+    }
+    if (value.type === 'close') {
+        return { type: 'close' };
+    }
+    if (value.type === 'open') {
+        if (!isRecord(value.options) ||
+            typeof value.options.appKey !== 'string' ||
+            typeof value.options.userId !== 'string' ||
+            !value.options.appKey ||
+            !value.options.userId) {
+            throw new Error('Invalid database open options');
+        }
+        return {
+            type: 'open',
+            options: { appKey: value.options.appKey, userId: value.options.userId }
+        };
+    }
+    if (value.type === 'read' || value.type === 'write') {
+        const allowed = value.type === 'read' ? READ_METHODS : WRITE_METHODS;
+        if (typeof value.method !== 'string' ||
+            !allowed.has(value.method) ||
+            !Array.isArray(value.args)) {
+            throw new Error(`Invalid database ${value.type} request`);
+        }
+        return value;
+    }
+    throw new Error(`Unsupported database IPC request: ${value.type}`);
+}
+function registerDatabaseIpc({ ipcMain, service, isTrustedEvent = isTopLevelSender }) {
+    ipcMain.handle(DATABASE_CHANNEL, async (event, value) => {
+        try {
+            if (!isTrustedEvent(event)) {
+                throw new Error('Database IPC sender is not trusted');
+            }
+            const request = parseRequest(value);
+            let result;
+            if (request.type === 'open') {
+                result = await service.open(request.options);
+            }
+            else if (request.type === 'close') {
+                result = await service.close();
+            }
+            else if (request.type === 'read') {
+                result = await service.read(request.method, request.args);
+            }
+            else {
+                result = await service.write(request.method, request.args);
+            }
+            return { ok: true, value: result };
+        }
+        catch (error) {
+            return { ok: false, error: serializeDatabaseError(error) };
+        }
+    });
+    return () => ipcMain.removeHandler(DATABASE_CHANNEL);
+}
+
+class MainDatabaseService {
+    options;
+    workerCount;
+    pool = [];
+    accountId = null;
+    constructor(options) {
+        this.options = options;
+        this.workerCount = options.workerCount ?? 4;
+        if (this.workerCount < 2) {
+            throw new Error('Database service requires one writer and at least one reader');
+        }
+    }
+    async open(options) {
+        const accountId = node_crypto.createHash('sha256')
+            .update(`${options.appKey}:${options.userId}`)
+            .digest('hex');
+        if (this.accountId === accountId && this.pool.length > 0) {
+            return;
+        }
+        await this.close();
+        const sqlDirectory = node_path.join(this.options.userDataPath, 'sql');
+        node_fs.mkdirSync(sqlDirectory, { recursive: true });
+        const dbPath = node_path.join(sqlDirectory, `${accountId}.sqlite`);
+        const key = this.options.keyStore.getOrCreate(accountId);
+        try {
+            for (let index = 0; index < this.workerCount; index += 1) {
+                this.pool.push({ client: this.options.workerFactory(index), load: 0 });
+            }
+            await this.pool[0].client.request({
+                type: 'init',
+                dbPath,
+                key,
+                isPrimary: true
+            });
+            await Promise.all(this.pool.slice(1).map(entry => entry.client.request({ type: 'init', dbPath, key, isPrimary: false })));
+            this.accountId = accountId;
+        }
+        catch (error) {
+            await this.close();
+            throw error;
+        }
+    }
+    async read(method, args) {
+        this.assertOpen();
+        const readers = this.pool.slice(1);
+        const entry = readers.reduce((least, candidate) => candidate.load < least.load ? candidate : least);
+        entry.load += 1;
+        try {
+            return await entry.client.request({ type: 'call', access: 'read', method, args });
+        }
+        finally {
+            entry.load -= 1;
+        }
+    }
+    async write(method, args) {
+        this.assertOpen();
+        const primary = this.pool[0];
+        primary.load += 1;
+        try {
+            return await primary.client.request({ type: 'call', access: 'write', method, args });
+        }
+        finally {
+            primary.load -= 1;
+        }
+    }
+    async close() {
+        const entries = this.pool.splice(0);
+        this.accountId = null;
+        await Promise.all(entries.map(async (entry) => {
+            try {
+                await entry.client.request({ type: 'close' });
+            }
+            finally {
+                await entry.client.close();
+            }
+        }));
+    }
+    assertOpen() {
+        if (!this.accountId || this.pool.length === 0) {
+            throw new Error('Database service is not open');
+        }
+    }
+}
+class ThreadWorkerClient {
+    worker;
+    sequence = 0;
+    pending = new Map();
+    constructor(worker) {
+        this.worker = worker;
+        worker.on('message', (response) => {
+            const pending = this.pending.get(response.sequence);
+            if (!pending) {
+                return;
+            }
+            this.pending.delete(response.sequence);
+            if (response.ok) {
+                pending.resolve(response.value);
+            }
+            else {
+                const error = new Error(response.error?.message ?? 'Database worker failed');
+                error.name = response.error?.name ?? 'Error';
+                error.stack = response.error?.stack;
+                pending.reject(error);
+            }
+        });
+        const rejectAll = (error) => {
+            for (const pending of this.pending.values()) {
+                pending.reject(error);
+            }
+            this.pending.clear();
+        };
+        worker.on('error', rejectAll);
+        worker.on('exit', code => {
+            if (code !== 0) {
+                rejectAll(new Error(`Database worker exited with code ${code}`));
+            }
+        });
+    }
+    request(request) {
+        const sequence = ++this.sequence;
+        return new Promise((resolve, reject) => {
+            this.pending.set(sequence, { resolve, reject });
+            const wrapped = { sequence, request };
+            this.worker.postMessage(wrapped);
+        });
+    }
+    async close() {
+        await this.worker.terminate();
+    }
+}
+function createThreadWorkerFactory(workerPath) {
+    return () => new ThreadWorkerClient(new node_worker_threads.Worker(workerPath));
+}
+
+function initializeDatabaseMain(options = {}) {
+    if (!electron.safeStorage.isEncryptionAvailable()) {
+        throw new Error('Electron safeStorage is unavailable; refusing to persist a database key');
+    }
+    const userDataPath = options.userDataPath ?? electron.app.getPath('userData');
+    const workerPath = options.workerPath ?? node_path.join(__dirname, 'worker.cjs');
+    const keyStore = new DatabaseKeyStore(node_path.join(userDataPath, 'sql'), electron.safeStorage);
+    const service = new MainDatabaseService({
+        userDataPath,
+        keyStore,
+        workerFactory: createThreadWorkerFactory(workerPath)
+    });
+    const removeIpcHandler = registerDatabaseIpc({
+        ipcMain: electron.ipcMain,
+        service,
+        isTrustedEvent: options.isTrustedEvent
+    });
+    const closeBeforeQuit = () => {
+        void service.close();
+    };
+    electron.app.once('before-quit', closeBeforeQuit);
+    return {
+        service,
+        async dispose() {
+            removeIpcHandler();
+            electron.app.removeListener('before-quit', closeBeforeQuit);
+            await service.close();
+        }
+    };
+}
+
+exports.DatabaseKeyStore = DatabaseKeyStore;
+exports.MainDatabaseService = MainDatabaseService;
+exports.ThreadWorkerClient = ThreadWorkerClient;
+exports.createThreadWorkerFactory = createThreadWorkerFactory;
+exports.initializeDatabaseMain = initializeDatabaseMain;

package/database/preload.cjs

@@ -0,0 +1,45 @@
+'use strict';
+
+var electron = require('electron');
+
+const DATABASE_GLOBAL = 'acimDatabase';
+const DATABASE_CHANNEL = 'acim-database:request';
+const READ_METHOD_NAMES = [
+    'getMessages',
+    'getLatestMessage',
+    'getLatestMessages',
+    'getDialogLoadedState',
+    'getMessageById',
+    'getMessageByUId',
+    'getMessageIdRange',
+    'searchMessages',
+    'searchTextMessages',
+    'getLegacyMigrationState'
+];
+const WRITE_METHOD_NAMES = [
+    'addMessages',
+    'clearConversationCache',
+    'clearAllCache',
+    'removeMessagesByUId',
+    'updateMessageReceiptStatus',
+    'clearBurnAfterReadingExpiredMessages',
+    'upsertMessage',
+    'convertToRecallMessages',
+    'importLegacyBatch',
+    'completeLegacyMigration'
+];
+new Set(READ_METHOD_NAMES);
+new Set(WRITE_METHOD_NAMES);
+
+function exposeDatabaseBridge(contextBridge, ipcRenderer) {
+    const bridge = {
+        request(request) {
+            return ipcRenderer.invoke(DATABASE_CHANNEL, request);
+        }
+    };
+    contextBridge.exposeInMainWorld(DATABASE_GLOBAL, bridge);
+}
+
+exposeDatabaseBridge(electron.contextBridge, electron.ipcRenderer);
+
+exports.exposeDatabaseBridge = exposeDatabaseBridge;