Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
Refactor core/client to use SQL via interface (#2159)
Leendert de Borst3bac5da09bd8
diff --git a/apps/browser-extension/src/platform/ExtensionPlatform.ts b/apps/browser-extension/src/platform/ExtensionPlatform.tsindex ca4b76f49..d393a1cec 100644--- a/apps/browser-extension/src/platform/ExtensionPlatform.ts+++ b/apps/browser-extension/src/platform/ExtensionPlatform.ts@@ -2,7 +2,9 @@* The browser extension's implementations of the client core's platform interfaces (e.g. storage, logger, etc.) which are different per platform.*/+import { createSqlJsEngine } from '@aliasvault/client/database/SqlJsEngine';import { type IClientPlatform, type IKeyValueStore, type StorageKey, TranslatableMessage } from '@aliasvault/client/platform';+import { createWasmRustCore } from '@aliasvault/client/rust/WasmRustCore';import { browser } from 'wxt/browser';import { devError, devLog, devWarn } from '@/utils/devLogger/DevLogger';@@ -83,6 +85,13 @@ const extensionStorage: IKeyValueStore = {watch: <T,>(key: StorageKey, callback: (value: T | null) => void): (() => void) => storage.watch<T>(key, (value) => callback(value)),};+/**+ * Get the path to the sql.js support files.+ */+function locateSqlJsFile(file: string): string {+ return `src/${file}`;+}+/*** The platform the extension registers with the client core.*/@@ -97,16 +106,13 @@ export const extensionPlatform: IClientPlatform = {/*** Fetch the bundled Rust core binary.*/- loadRustCoreWasm: async (): Promise<BufferSource> => {+ rustCore: createWasmRustCore(async (): Promise<BufferSource> => {const wasmUrl = (browser.runtime.getURL as (path: string) => string)('src/aliasvault_core_bg.wasm');return (await fetch(wasmUrl)).arrayBuffer();- },- /**- * Locate the sql.js support file.- */- locateSqlJsFile: (file: string): string => `src/${file}`,+ }),+ sqlite: createSqlJsEngine(locateSqlJsFile),/**- * Resolve a core message.+ * Translate one of the core's own messages through the extension's i18n.*/translate: (message: TranslatableMessage): Promise<string> => t(TRANSLATION_KEYS[message]),};diff --git a/apps/browser-extension/tests/helpers/client-platform.ts b/apps/browser-extension/tests/helpers/client-platform.tsindex a81944533..ccb38963f 100644--- a/apps/browser-extension/tests/helpers/client-platform.ts+++ b/apps/browser-extension/tests/helpers/client-platform.ts@@ -9,20 +9,17 @@ import { createRequire } from 'node:module';import path from 'node:path';import { fileURLToPath } from 'node:url';+import { createSqlJsEngine } from '@aliasvault/client/database/SqlJsEngine';import { setPlatform } from '@aliasvault/client/platform';import { createInMemoryPlatform } from '@aliasvault/client/platform/InMemoryPlatform';+import { createWasmRustCore } from '@aliasvault/client/rust/WasmRustCore';const clientCoreDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../core/client');const requireFromClientCore = createRequire(path.join(clientCoreDir, 'package.json'));setPlatform(createInMemoryPlatform({- /**- * Load the Rust core WASM from the client core build output.- */- loadRustCoreWasm: async (): Promise<BufferSource> => readFileSync(path.join(clientCoreDir, 'wasm/aliasvault_core_bg.wasm')),- /**- * Locate a sql.js support file in the client core's node_modules.- * @param file - the file name sql.js asks for- */- locateSqlJsFile: (file: string): string => path.join(path.dirname(requireFromClientCore.resolve('sql.js')), file),+ // The Rust core WASM from the client core build output.+ rustCore: createWasmRustCore(async (): Promise<BufferSource> => readFileSync(path.join(clientCoreDir, 'wasm/aliasvault_core_bg.wasm'))),+ // sql.js support files from the client core's node_modules.+ sqlite: createSqlJsEngine((file: string): string => path.join(path.dirname(requireFromClientCore.resolve('sql.js')), file)),}));diff --git a/core/client/src/api/WebApiService.ts b/core/client/src/api/WebApiService.tsindex b36ad2042..851dc7daa 100644--- a/core/client/src/api/WebApiService.ts+++ b/core/client/src/api/WebApiService.ts@@ -34,6 +34,38 @@ const VAULT_TRANSFER_TIMEOUT_MS = 180000;*/const LARGE_TRANSFER_PATH = 'vault';+/**+ * A signal that aborts after `ms`.+ * @param ms - the timeout+ */+function timeoutAbortSignal(ms: number): AbortSignal {+ if (typeof AbortSignal.timeout === 'function') {+ return AbortSignal.timeout(ms);+ }+ const controller = new AbortController();+ setTimeout(() => controller.abort(new Error('TimeoutError')), ms);+ return controller.signal;+}++/**+ * A signal that aborts as soon as any of the given signals does.+ * @param signals - the signals to combine+ */+function anyAbortSignal(signals: AbortSignal[]): AbortSignal {+ if (typeof AbortSignal.any === 'function') {+ return AbortSignal.any(signals);+ }+ const controller = new AbortController();+ for (const signal of signals) {+ if (signal.aborted) {+ controller.abort(signal.reason);+ break;+ }+ signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });+ }+ return controller.signal;+}+/*** Type for the token response from the API.*/@@ -169,6 +201,11 @@ export class WebApiService {// Add client version header (using API_VERSION for server compatibility)headers.set('X-AliasVault-Client', `${AppInfo.CLIENT_NAME}-${AppInfo.API_VERSION}`);+ // Headers the host adds to every request (e.g. custom proxy headers for a self-hosted setup).+ for (const [name, value] of Object.entries(await getPlatform().requestHeaders?.() ?? {})) {+ headers.set(name, value);+ }+const requestOptions: RequestInit = {...options,headers,@@ -184,7 +221,7 @@ export class WebApiService {* The timeout signal aborts with a DOMException; no caller passes its own abort signal,* so any abort here means the request exceeded its timeout.*/- if (error instanceof DOMException && (error.name === 'TimeoutError' || error.name === 'AbortError')) {+ if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {throw new RequestTimeoutError(`Request timed out: ${endpoint}`, error);}// Convert fetch errors to NetworkError for proper error handling@@ -210,10 +247,8 @@ export class WebApiService {const path = endpoint.split('?')[0].replace(/^\/+|\/+$/g, '').toLowerCase();const isLargeTransfer = path === LARGE_TRANSFER_PATH || path.startsWith(`${LARGE_TRANSFER_PATH}/`) ||(headers.get('Accept') ?? '').toLowerCase().includes('application/octet-stream');- const timeoutSignal = AbortSignal.timeout(- isLargeTransfer ? VAULT_TRANSFER_TIMEOUT_MS : DEFAULT_REQUEST_TIMEOUT_MS- );- return callerSignal ? AbortSignal.any([callerSignal, timeoutSignal]) : timeoutSignal;+ const timeoutSignal = timeoutAbortSignal(isLargeTransfer ? VAULT_TRANSFER_TIMEOUT_MS : DEFAULT_REQUEST_TIMEOUT_MS);+ return callerSignal ? anyAbortSignal([callerSignal, timeoutSignal]) : timeoutSignal;}/**diff --git a/core/client/src/database/BaseRepository.ts b/core/client/src/database/BaseRepository.tsindex 3b97a46da..d3230d8ce 100644--- a/core/client/src/database/BaseRepository.ts+++ b/core/client/src/database/BaseRepository.ts@@ -2,7 +2,7 @@ import * as dateFormatter from '../utilities/DateFormatter';import { BaseQueries } from './queries/BaseQueries';-import type { Database } from 'sql.js';+import type { ISqliteDatabase } from '../platform/SqliteEngine';export type SqliteBindValue = string | number | null | Uint8Array;@@ -10,7 +10,7 @@ export type SqliteBindValue = string | number | null | Uint8Array;* Interface for the core database operations needed by repositories.*/export interface IDatabaseClient {- getDb(): Database | null;+ getDb(): ISqliteDatabase | null;executeQuery<T>(query: string, params?: SqliteBindValue[]): T[];executeUpdate(query: string, params?: SqliteBindValue[]): number;beginTransaction(): void;diff --git a/core/client/src/database/SqlJsEngine.ts b/core/client/src/database/SqlJsEngine.tsnew file mode 100644index 000000000..76f11405f--- /dev/null+++ b/core/client/src/database/SqlJsEngine.ts@@ -0,0 +1,103 @@+/**+ * The SQLite engine backed by sql.js, for hosts with a WebAssembly runtime (browser extension, web app, Node+ * tests).+ */+import initSqlJs from 'sql.js';++import type { ISqliteDatabase, ISqliteEngine, ISqliteStatement, SqliteValue } from '../platform/SqliteEngine';+import type { Database, SqlJsStatic } from 'sql.js';++/**+ * A sql.js database behind the engine interface.+ */+class SqlJsDatabase implements ISqliteDatabase {+ /**+ * Wrap an open sql.js database.+ * @param db - the open sql.js database+ */+ public constructor(private readonly db: Database) {}++ /** @inheritdoc */+ public run(sql: string, params: SqliteValue[] = []): number {+ const statement = this.db.prepare(sql);+ try {+ statement.bind(params);+ statement.step();+ return this.db.getRowsModified();+ } finally {+ statement.free();+ }+ }++ /** @inheritdoc */+ public query<T>(sql: string, params: SqliteValue[] = []): T[] {+ const statement = this.db.prepare(sql);+ try {+ statement.bind(params);+ const rows: T[] = [];+ while (statement.step()) {+ rows.push(statement.getAsObject() as T);+ }+ return rows;+ } finally {+ statement.free();+ }+ }++ /** @inheritdoc */+ public exec(sql: string): void {+ this.db.run(sql);+ }++ /** @inheritdoc */+ public prepare(sql: string): ISqliteStatement {+ const statement = this.db.prepare(sql);+ return {+ /** Bind and run. */+ run: (params: SqliteValue[]): void => {+ statement.run(params);+ },+ /** Free the statement. */+ finalize: (): void => {+ statement.free();+ },+ };+ }++ /** @inheritdoc */+ public export(): Uint8Array {+ return this.db.export();+ }++ /** @inheritdoc */+ public close(): void {+ this.db.close();+ }+}++/**+ * Bind the engine interface to sql.js.+ * @param locateFile - resolves a sql.js support file (`sql-wasm.wasm`) to a URL the runtime can fetch+ */+export function createSqlJsEngine(locateFile: (file: string) => string): ISqliteEngine {+ let sqlJs: Promise<SqlJsStatic> | null = null;++ /**+ * Load sql.js once; a failed load is forgotten so the next caller retries.+ */+ const load = (): Promise<SqlJsStatic> => {+ sqlJs ??= initSqlJs({ locateFile }).catch((error: unknown) => {+ sqlJs = null;+ throw error;+ });+ return sqlJs;+ };++ return {+ /** @inheritdoc */+ open: async (bytes?: Uint8Array): Promise<ISqliteDatabase> => {+ const SQL = await load();+ return new SqlJsDatabase(bytes ? new SQL.Database(bytes) : new SQL.Database());+ },+ };+}diff --git a/core/client/src/database/SqliteClient.ts b/core/client/src/database/SqliteClient.tsindex ff47a5c24..9f0392153 100644--- a/core/client/src/database/SqliteClient.ts+++ b/core/client/src/database/SqliteClient.ts@@ -1,5 +1,4 @@import { VaultSqlGenerator, checkVersionCompatibility, extractVersionFromMigrationId } from '@aliasvault/vault';-import initSqlJs from 'sql.js';import { VaultVersionIncompatibleError } from '../api/errors/VaultVersionIncompatibleError';import { StorageKeys } from '../constants/StorageKeys';@@ -19,8 +18,8 @@ import {} from './index';import type { IDatabaseClient, SqliteBindValue } from './BaseRepository';+import type { ISqliteDatabase } from '../platform/SqliteEngine';import type { VaultVersion } from '@aliasvault/vault';-import type { Database } from 'sql.js';/** Minimum number of free pages before a VACUUM is worth the full database rewrite on export. */const VACUUM_MIN_FREE_PAGES = 64;@@ -33,7 +32,7 @@ const VACUUM_FREE_PAGE_RATIO = 10;* Provides low-level database operations and exposes repositories for domain-specific operations.*/export class SqliteClient implements IDatabaseClient {- private db: Database | null = null;+ private db: ISqliteDatabase | null = null;private isInTransaction: boolean = false;/**@@ -159,7 +158,7 @@ export class SqliteClient implements IDatabaseClient {/*** Get the underlying database instance.*/- public getDb(): Database | null {+ public getDb(): ISqliteDatabase | null {return this.db;}@@ -177,18 +176,8 @@ export class SqliteClient implements IDatabaseClient {*/public async initializeFromBytes(bytes: Uint8Array): Promise<void> {try {- // Initialize SQL.js with the WASM file- const SQL = await initSqlJs({- /**- * Locates SQL.js files from the local file system.- * @param file - The name of the file to locate- * @returns The complete URL path to the file- */- locateFile: (file: string): string => getPlatform().locateSqlJsFile(file)- });-- // Create database from the binary data- this.db = new SQL.Database(bytes);+ // Open the database in memory through the host's SQLite engine.+ this.db = await getPlatform().sqlite.open(bytes);// Get the personal manifest id from local storagethis.personalManifestId = (await getPlatform().storage.get(StorageKeys.VAULT_PERSONAL_MANIFEST_ID)) as string | null;@@ -218,7 +207,7 @@ export class SqliteClient implements IDatabaseClient {}try {- this.db.run('BEGIN TRANSACTION');+ this.db.exec('BEGIN TRANSACTION');this.isInTransaction = true;} catch (error) {console.error('Error beginning transaction:', error);@@ -239,7 +228,7 @@ export class SqliteClient implements IDatabaseClient {}try {- this.db.run('COMMIT');+ this.db.exec('COMMIT');this.isInTransaction = false;} catch (error) {console.error('Error committing transaction:', error);@@ -260,7 +249,7 @@ export class SqliteClient implements IDatabaseClient {}try {- this.db.run('ROLLBACK');+ this.db.exec('ROLLBACK');this.isInTransaction = false;} catch (error) {console.error('Error rolling back transaction:', error);@@ -318,16 +307,7 @@ export class SqliteClient implements IDatabaseClient {}try {- const stmt = this.db.prepare(query);- stmt.bind(params);-- const results: T[] = [];- while (stmt.step()) {- results.push(stmt.getAsObject() as T);- }- stmt.free();-- return results;+ return this.db.query<T>(query, params);} catch (error) {console.error('Error executing query:', error);throw error;@@ -356,12 +336,7 @@ export class SqliteClient implements IDatabaseClient {}try {- const stmt = this.db.prepare(query);- stmt.bind(params);- stmt.step();- const changes = this.db.getRowsModified();- stmt.free();- return changes;+ return this.db.run(query, params);} catch (error) {console.error('Error executing update:', error);throw error;@@ -391,7 +366,7 @@ export class SqliteClient implements IDatabaseClient {continue;}- this.db.run(trimmedStatement);+ this.db.exec(trimmedStatement);}} catch (error) {console.error('Error executing raw SQL:', error);diff --git a/core/client/src/platform/ClientPlatform.ts b/core/client/src/platform/ClientPlatform.tsindex 93e372f2b..5a0168baf 100644--- a/core/client/src/platform/ClientPlatform.ts+++ b/core/client/src/platform/ClientPlatform.ts@@ -1,7 +1,9 @@import type { IAppIdentity } from './AppIdentity';import type { IKeyValueStore } from './KeyValueStore';import type { ILogger } from './Logger';+import type { ISqliteEngine } from './SqliteEngine';import type { TranslatableMessage } from './TranslatableMessage';+import type { IRustCore } from '../rust/RustCoreBinding';/*** Everything the client core needs from the host app. Each app (browser extension, web app, mobile app) implements@@ -17,21 +19,26 @@ export interface IClientPlatform {/** Version and client name of the host app. */app: IAppIdentity;+ /** The Rust core: WebAssembly on the web hosts (see WasmRustCore), the native uniffi bindings on mobile. */+ rustCore: IRustCore;++ /** The SQLite engine the vault is opened with: sql.js on the web hosts (see SqlJsEngine), expo-sqlite on mobile. */+ sqlite: ISqliteEngine;+/**- * Provide the Rust core WebAssembly binary.+ * Translate one of the core's own messages into the user's language.*/- loadRustCoreWasm(): Promise<BufferSource | Response>;+ translate(message: TranslatableMessage): Promise<string>;/**- * Resolve a sql.js support file (`sql-wasm.wasm`) to a URL the runtime can fetch.- * @param file - the file name sql.js asks for+ * The device's UI language as a BCP 47 tag. Hosts without `navigator.language` provide it here.*/- locateSqlJsFile(file: string): string;+ deviceLanguage?(): string;/**- * Translate one of the core's own messages into the user's language.+ * Extra headers to send with every API request, e.g. the custom proxy headers a self-hosted setup needs.*/- translate(message: TranslatableMessage): Promise<string>;+ requestHeaders?(): Promise<Record<string, string>>;}let current: IClientPlatform | null = null;@@ -46,18 +53,17 @@ export function setPlatform(platform: IClientPlatform): void {/*** The registered host platform.- * @throws Error when no platform was registered yet.+ * @throws When no platform has been registered yet.*/export function getPlatform(): IClientPlatform {if (!current) {- throw new Error('AliasVault client platform is not configured. Call setPlatform() before using the client core.');+ throw new Error('No client platform registered. Call setPlatform() before using the client core.');}return current;}/**- * The registered host platform, or null before registration. For code paths that must stay usable without a- * platform, such as logging.+ * The registered host platform, or null before registration. For code paths that must stay silent early on.*/export function tryGetPlatform(): IClientPlatform | null {return current;diff --git a/core/client/src/platform/DeviceLanguage.ts b/core/client/src/platform/DeviceLanguage.tsindex 8ddf32e03..59fb7ab4c 100644--- a/core/client/src/platform/DeviceLanguage.ts+++ b/core/client/src/platform/DeviceLanguage.ts@@ -1,6 +1,8 @@+import { tryGetPlatform } from './ClientPlatform';+/**- * The device's UI language as a BCP 47 tag, or English when the runtime exposes none.+ * The device's UI language as a BCP 47 tag: what the host reports, else the runtime's, else English.*/export function deviceLanguage(): string {- return globalThis.navigator?.language ?? 'en';+ return tryGetPlatform()?.deviceLanguage?.() ?? globalThis.navigator?.language ?? 'en';}diff --git a/core/client/src/platform/InMemoryPlatform.ts b/core/client/src/platform/InMemoryPlatform.tsindex 57814b328..6f008ce3c 100644--- a/core/client/src/platform/InMemoryPlatform.ts+++ b/core/client/src/platform/InMemoryPlatform.ts@@ -1,5 +1,7 @@import type { IClientPlatform } from './ClientPlatform';import type { IKeyValueStore, StorageKey } from './KeyValueStore';+import type { ISqliteEngine } from './SqliteEngine';+import type { IRustCore } from '../rust/RustCoreBinding';/*** A {@link IKeyValueStore} held in a Map. For unit tests and for hosts that keep session state in memory only.@@ -61,9 +63,20 @@ export class InMemoryKeyValueStore implements IKeyValueStore {}}+/**+ * A Rust core or SQLite engine that refuses every call, for platforms that did not provide one.+ * @param what - the member name, for the error message+ */+function unavailable<T extends object>(what: string): T {+ return new Proxy({} as T, {+ /** Every member access yields a rejecting function. */+ get: (_target, property): unknown => (): Promise<never> => Promise.reject(new Error(`No ${what} configured for this platform (${String(property)}).`)),+ });+}+/*** A platform with in-memory storage and no-op logging, for unit tests. Override what the test needs (typically- * the WASM loader and the sql.js locator).+ * the Rust core binding and the SQLite engine).* @param overrides - members to replace*/export function createInMemoryPlatform(overrides: Partial<IClientPlatform> = {}): IClientPlatform {@@ -78,10 +91,8 @@ export function createInMemoryPlatform(overrides: Partial<IClientPlatform> = {})error: (): void => {},},app: { version: '0.0.0-test', clientName: 'test', isDevelopment: false },- /** Not available unless overridden. */- loadRustCoreWasm: (): Promise<BufferSource> => Promise.reject(new Error('No Rust core WASM loader configured for this platform.')),- /** Not available unless overridden. */- locateSqlJsFile: (file: string): string => file,+ rustCore: unavailable<IRustCore>('Rust core'),+ sqlite: unavailable<ISqliteEngine>('SQLite engine'),/*** Echo the message id.*/diff --git a/core/client/src/platform/SqliteEngine.ts b/core/client/src/platform/SqliteEngine.tsnew file mode 100644index 000000000..11dea36f6--- /dev/null+++ b/core/client/src/platform/SqliteEngine.ts@@ -0,0 +1,67 @@+/**+ * A value bound to or read from a SQLite statement.+ */+export type SqliteValue = string | number | null | Uint8Array;++/**+ * A row as the engine returns it: column name to value. Byte columns come back as Uint8Array.+ */+export type SqliteRow = Record<string, SqliteValue>;++/**+ * A compiled statement, for bulk inserts that bind the same SQL many times.+ */+export interface ISqliteStatement {+ /** Bind the parameters and run the statement to completion. */+ run(params: SqliteValue[]): void;++ /** Release the statement. */+ finalize(): void;+}++/**+ * One open SQLite database. Every call is synchronous: the repositories and the codec drive the database+ * step by step, which only a synchronous engine can do without turning every read into a promise.+ */+export interface ISqliteDatabase {+ /**+ * Run a statement that returns no rows and report how many rows it changed.+ */+ run(sql: string, params?: SqliteValue[]): number;++ /**+ * Run a statement and return its rows.+ */+ query<T = SqliteRow>(sql: string, params?: SqliteValue[]): T[];++ /**+ * Run one or more statements separated by semicolons, without parameters.+ */+ exec(sql: string): void;++ /**+ * Compile a statement for repeated execution.+ */+ prepare(sql: string): ISqliteStatement;++ /**+ * The database as SQLite file bytes.+ */+ export(): Uint8Array;++ /**+ * Close the database and free its memory.+ */+ close(): void;+}++/**+ * The SQLite engine a host provides. The browser and web hosts use sql.js (see SqlJsEngine); the mobile host uses+ * expo-sqlite. Databases live in memory only: the vault at rest is the encrypted blob, never a database file.+ */+export interface ISqliteEngine {+ /**+ * Open a database in memory, from the given SQLite file bytes or empty when omitted.+ */+ open(bytes?: Uint8Array): Promise<ISqliteDatabase>;+}diff --git a/core/client/src/platform/index.ts b/core/client/src/platform/index.tsindex 029dc4438..7a9293fde 100644--- a/core/client/src/platform/index.ts+++ b/core/client/src/platform/index.ts@@ -2,4 +2,6 @@ export type { IAppIdentity } from './AppIdentity';export { getPlatform, setPlatform, tryGetPlatform, type IClientPlatform } from './ClientPlatform';export type { IKeyValueStore, StorageKey } from './KeyValueStore';export { devError, devLog, devWarn, type ILogger } from './Logger';+export type { ISqliteDatabase, ISqliteEngine, ISqliteStatement, SqliteRow, SqliteValue } from './SqliteEngine';export { TranslatableMessage } from './TranslatableMessage';+export type { IRustCore } from '../rust/RustCoreBinding';diff --git a/core/client/src/sync/VaultCodec.ts b/core/client/src/sync/VaultCodec.tsindex 1aaec30f6..26fc0bc31 100644--- a/core/client/src/sync/VaultCodec.ts+++ b/core/client/src/sync/VaultCodec.ts@@ -7,6 +7,7 @@ import { devLog } from '../platform/Logger';import { base64ToBytes as decodeBase64, bytesToBase64 as encodeBase64 } from '../utilities/Base64';import type SqliteClient from '../database/SqliteClient';+import type { ISqliteDatabase, ISqliteStatement, SqliteValue } from '../platform/SqliteEngine';import type {CodecManifest,CodecDataBucket,@@ -66,7 +67,7 @@ export function manifestIdKey(manifestId: string): string {}/**- * VaultCodec — sql.js read/insert methods.+ * VaultCodec: SQLite read/insert methods, on whichever engine the host provides.*/export class VaultCodec {/**@@ -151,11 +152,11 @@ export class VaultCodec {private static async readSchemaColumns(schemaSql: string): Promise<Record<string, string[]>> {const db = await this.createDatabase();try {- db.run(schemaSql);- const tables = db.exec("SELECT name FROM sqlite_master WHERE type='table'")[0]?.values.map(v => String(v[0])) ?? [];+ db.exec(schemaSql);+ const tables = db.query<{ name: string }>("SELECT name FROM sqlite_master WHERE type='table'").map(row => row.name);const out: Record<string, string[]> = {};for (const table of tables) {- out[table] = db.exec(`PRAGMA table_info("${table}")`)[0]?.values.map(v => String(v[1])) ?? [];+ out[table] = db.query<{ name: string }>(`PRAGMA table_info("${table}")`).map(row => row.name);}return out;} finally {@@ -175,7 +176,7 @@ export class VaultCodec {try {// 1) Apply the schema.- db.run(schemaSql);+ db.exec(schemaSql);devLog('[VaultCodec] Schema applied.');/*@@ -183,14 +184,14 @@ export class VaultCodec {* emitted them, so child rows (e.g. Attachments) may precede their parents (Items). Disable enforcement* for the bulk load; an explicit foreign_key_check below validates the fully-assembled result instead.*/- db.run('PRAGMA foreign_keys = OFF');- db.run('BEGIN TRANSACTION');+ db.exec('PRAGMA foreign_keys = OFF');+ db.exec('BEGIN TRANSACTION');// Compiled INSERT statements, keyed by table name plus the row's column set.- const statements = new Map<string, import('sql.js').Statement>();+ const statements = new Map<string, ISqliteStatement>();// Tables present in the freshly-created schema; rows for tables outside it cannot be inserted.- const schemaTables = new Set<string>(db.exec("SELECT name FROM sqlite_master WHERE type='table'")[0]?.values.map(v => String(v[0])) ?? []);+ const schemaTables = new Set<string>(db.query<{ name: string }>("SELECT name FROM sqlite_master WHERE type='table'").map(row => row.name));// 2) Insert every materialized table's rows.for (const { name: tableName, records: rows } of materialized.tables) {@@ -207,7 +208,7 @@ export class VaultCodec {devLog(`[VaultCodec] Inserting ${rows.length} rows into "${tableName}"...`);for (const row of rows) {const cols = Object.keys(row);- const values: unknown[] = cols.map(c => {+ const values: SqliteValue[] = cols.map(c => {const v = row[c];if (this.isBlobRef(v)) {return blobs.get((v as BlobRef).__blobRef) ?? null;@@ -216,7 +217,7 @@ export class VaultCodec {if (this.isInlineB64(v)) {return this.base64ToBytes((v as { __b64: string }).__b64);}- return (v === undefined ? null : v) as unknown;+ return (v === undefined ? null : v) as SqliteValue;});const statementKey = `${tableName}\u0000${cols.join('\u0000')}`;@@ -229,7 +230,7 @@ export class VaultCodec {}try {- statement.run(values as never);+ statement.run(values);} catch (e) {throw new Error(`VaultCodec: failed to insert row into "${tableName}" (columns: ${cols.join(', ')}): ${e instanceof Error ? e.message : String(e)}`);}@@ -237,17 +238,17 @@ export class VaultCodec {}for (const statement of statements.values()) {- statement.free();+ statement.finalize();}statements.clear();- db.run('COMMIT');+ db.exec('COMMIT');// 3) Verify referential integrity of the fully-assembled database.- const fkViolations = db.exec('PRAGMA foreign_key_check');+ const fkViolations = db.query<{ table: string; rowid: number; parent: string }>('PRAGMA foreign_key_check');if (fkViolations.length > 0) {- const sample = fkViolations[0].values.slice(0, 5).map(v => `${v[0]} row ${v[1]} → missing parent in ${v[2]}`).join('; ');- throw new Error(`VaultCodec: materialized database fails foreign key check (${fkViolations[0].values.length} violations): ${sample}`);+ const sample = fkViolations.slice(0, 5).map(v => `${v.table} row ${v.rowid} > missing parent in ${v.parent}`).join('; ');+ throw new Error(`VaultCodec: materialized database fails foreign key check (${fkViolations.length} violations): ${sample}`);}devLog('[VaultCodec] Foreign key check passed.');@@ -261,19 +262,10 @@ export class VaultCodec {}/**- * Open a fresh in-memory sql.js database.+ * Open a fresh in-memory database through the host's SQLite engine.*/- private static async createDatabase(): Promise<import('sql.js').Database> {- const initSqlJs = (await import('sql.js')).default;- const SQL = await initSqlJs({- /**- * Locates SQL.js files from the local file system.- * @param file - The name of the file to locate- * @returns The complete URL path to the file- */- locateFile: (file: string): string => getPlatform().locateSqlJsFile(file)- });- return new SQL.Database();+ private static async createDatabase(): Promise<ISqliteDatabase> {+ return getPlatform().sqlite.open();}/**diff --git a/core/client/src/sync/VaultMergeService.ts b/core/client/src/sync/VaultMergeService.tsindex 3f18ba044..1c0bd86ad 100644--- a/core/client/src/sync/VaultMergeService.ts+++ b/core/client/src/sync/VaultMergeService.ts@@ -1,89 +1,18 @@-import initSqlJs from 'sql.js';--import { getPruneTableQueries, getSyncableTableNames, mergeVaults, pruneVault } from '../../wasm/aliasvault_core.js';import { TRASH_RETENTION_DAYS } from '../constants/Vault';import { getPlatform } from '../platform/ClientPlatform';import { devLog } from '../platform/Logger';-import { initRustCore } from '../rust/RustCore';+import { rustCore } from '../rust/RustCore';import { base64ToBytes, bytesToBase64 } from '../utilities/Base64';import type { SqliteClient } from '../database/SqliteClient';-import type { Database, SqlJsStatic, SqlValue } from 'sql.js';+import type { ISqliteDatabase, SqliteValue } from '../platform/SqliteEngine';+import type { RustSqlStatement, RustTableData } from '../rust/RustCoreTypes';/*** Record type for JSON data passed to/from Rust.*/type JsonRecord = { [key: string]: unknown };-/**- * Table data structure for Rust merge input/output.- */-type TableData = {- name: string;- records: JsonRecord[];-}--/**- * Input structure for Rust merge function.- */-type MergeInput = {- local_tables: TableData[];- server_tables: TableData[];-}--/**- * One SQL parameter as returned by the Rust merge: a plain sql.js value, or the `{ __b64 }` byte- * payload the row reader encodes BLOB columns as.- */-type RustSqlParam = SqlValue | { __b64: string } | undefined;--/**- * SQL statement with parameters from Rust.- */-type SqlStatement = {- sql: string;- params: RustSqlParam[];-}--/**- * Statistics from Rust merge.- */-type RustMergeStats = {- tablesProcessed: number;- recordsFromLocal: number;- recordsFromServer: number;- recordsCreatedLocally: number;- conflicts: number;- recordsInserted: number;-}--/**- * Output structure from Rust merge function.- */-type MergeOutput = {- success: boolean;- statements: SqlStatement[];- stats: RustMergeStats;-}--/**- * Input structure for Rust prune function.- */-type PruneInput = {- tables: TableData[];- retention_days: number;- /** Current time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.sssZ). Use new Date().toISOString() */- current_time: string;-}--/**- * Output structure from Rust prune function.- */-type PruneOutput = {- success: boolean;- statements: SqlStatement[];-}-/*** Result of a merge operation.*/@@ -107,38 +36,22 @@ export type MergeStats = {/*** Service for merging two vault SQLite databases using Last-Write-Wins (LWW) strategy.*- * This implementation uses Rust WASM for the core merge logic, ensuring consistency+ * This implementation uses the Rust core for the merge logic, ensuring consistency* across all platforms (browser, iOS, Android, server).** The merge uses UpdatedAt timestamps on all SyncableEntity records to determine* which version of a record wins in case of conflict.*/export class VaultMergeService {- private sqlJsInstance: SqlJsStatic | null = null;- /**- * Get the SQL.js instance, initializing and caching it on first use.- */- private async getSqlJs(): Promise<SqlJsStatic> {- this.sqlJsInstance ??= await initSqlJs({- /**- * Locate the SQL.js WASM file.- * @param file - The file name to locate- * @returns The path to the file- */- locateFile: (file: string): string => getPlatform().locateSqlJsFile(file)- });- return this.sqlJsInstance;- }-/*** LEGACY: SQLite statement-level merge, kept only for the frozen sqlite-blob storage format (a* not-yet-migrated local vault). Manifest-v1 vaults merge at canonical level instead, see* `VaultSyncService.pullAndMerge`. TODO: delete this function once all users have migrated to manifest-v1.*- * Uses Rust WASM for the merge logic. The merge base is the SERVER vault (it is freshly+ * Uses the Rust core for the merge logic. The merge base is the SERVER vault (it is freshly* materialized with the newest schema and the newest codec overflow carrier), and the local* vault's winning changes are applied on top of it:- * 1. Load both SQLite databases with sql.js+ * 1. Load both SQLite databases* 2. Read the syncable tables from both as JSON* 3. Call Rust merge (returns SQL statements that bring local changes onto the server base)* 4. Execute SQL statements on the SERVER database@@ -150,39 +63,26 @@ export class VaultMergeService {*/public async merge(localVaultBase64: string, serverVaultBase64: string): Promise<MergeResult> {try {- // Initialize Rust WASM- await initRustCore();-- const SQL = await this.getSqlJs();+ const core = rustCore();// Load both databases- const localDb = this.loadDatabase(SQL, localVaultBase64);- const serverDb = this.loadDatabase(SQL, serverVaultBase64);+ const localDb = await this.loadDatabase(localVaultBase64);+ const serverDb = await this.loadDatabase(serverVaultBase64);try {- // Get syncable table names from Rust (or injected function)- const tableNames = getSyncableTableNames();+ const tableNames = await core.getSyncableTableNames();// Read all tables from both databases as JSON- const localTables: TableData[] = tableNames.map(name => ({+ const localTables: RustTableData[] = tableNames.map(name => ({name,records: this.readTableAsJson(localDb, name),}));- const serverTables: TableData[] = tableNames.map(name => ({+ const serverTables: RustTableData[] = tableNames.map(name => ({name,records: this.readTableAsJson(serverDb, name),}));- /*- * Call Rust WASM merge (or injected function).- * Use JSON stringify/parse to ensure no undefined values reach Rust/serde.- */- const mergeInput: MergeInput = JSON.parse(JSON.stringify({- local_tables: localTables,- server_tables: serverTables,- })) as MergeInput;-devLog('[VaultMerge] Merge input:', {localTableCount: localTables.length,serverTableCount: serverTables.length,@@ -190,7 +90,8 @@ export class VaultMergeService {serverTables: serverTables.map(t => ({ name: t.name, recordCount: t.records.length })),});- const mergeOutput = mergeVaults(mergeInput) as MergeOutput;+ // JSON roundtrip so no undefined value reaches Rust/serde.+ const mergeOutput = await core.mergeVaults(JSON.parse(JSON.stringify({ local_tables: localTables, server_tables: serverTables })));/** Execute SQL statements from Rust on the SERVER database (the merge base). The exported@@ -234,14 +135,13 @@ export class VaultMergeService {* @returns Number of SQL statements executed (0 when nothing was expired)*/public async pruneInPlace(client: SqliteClient, retentionDays: number = TRASH_RETENTION_DAYS): Promise<number> {- await initRustCore();+ const core = rustCore();- const tableQueries = getPruneTableQueries() as { name: string; query: string }[];- const tables: TableData[] = tableQueries.map(({ name, query }) => ({ name, records: client.executeQuery<JsonRecord>(query) }));+ const tableQueries = await core.getPruneTableQueries();+ const tables: RustTableData[] = tableQueries.map(({ name, query }) => ({ name, records: client.executeQuery<JsonRecord>(query) }));// JSON roundtrip converts undefined to null and ensures clean JSON types for Rust/serde.- const pruneInput: PruneInput = JSON.parse(JSON.stringify({ tables, retention_days: retentionDays, current_time: new Date().toISOString() })) as PruneInput;- const pruneOutput = pruneVault(pruneInput) as PruneOutput;+ const pruneOutput = await core.pruneVault(JSON.parse(JSON.stringify({ tables, retention_days: retentionDays, current_time: new Date().toISOString() })));for (const stmt of pruneOutput.statements) {client.executeUpdate(stmt.sql, stmt.params.map(toBindableParam));@@ -256,12 +156,11 @@ export class VaultMergeService {/*** Load a SQLite database from base64 string.- * @param SQL - The SQL.js instance* @param base64String - The base64 encoded database- * @returns The loaded Database instance+ * @returns The loaded database*/- private loadDatabase(SQL: SqlJsStatic, base64String: string): Database {- return new SQL.Database(base64ToBytes(base64String));+ private loadDatabase(base64String: string): Promise<ISqliteDatabase> {+ return getPlatform().sqlite.open(base64ToBytes(base64String));}/**@@ -269,8 +168,8 @@ export class VaultMergeService {* @param db - The database to export* @returns The base64 encoded database*/- private exportDatabase(db: Database): string {- db.run('VACUUM');+ private exportDatabase(db: ISqliteDatabase): string {+ db.exec('VACUUM');return bytesToBase64(db.export());}@@ -280,8 +179,8 @@ export class VaultMergeService {* @param tableName - The name of the table* @returns Array of records as JSON objects*/- private readTableAsJson(db: Database, tableName: string): JsonRecord[] {- const exists = this.readQueryAsJson(db, `SELECT name FROM sqlite_master WHERE type='table' AND name='${tableName}'`).length > 0;+ private readTableAsJson(db: ISqliteDatabase, tableName: string): JsonRecord[] {+ const exists = db.query(`SELECT name FROM sqlite_master WHERE type='table' AND name='${tableName}'`).length > 0;if (!exists) {return [];}@@ -289,38 +188,31 @@ export class VaultMergeService {}/**- * Read all rows of a query as JSON objects. BLOB columns come back from sql.js as Uint8Array,+ * Read all rows of a query as JSON objects. BLOB columns come back from the engine as Uint8Array,* which neither JSON nor serde can round-trip; they are encoded as `{ __b64 }` payloads that* {@link toBindableParam} decodes when a merge statement writes them back.* @param db - The database to query* @param query - The SELECT query to run* @returns Array of records as JSON objects*/- private readQueryAsJson(db: Database, query: string): JsonRecord[] {- const records: JsonRecord[] = [];- const stmt = db.prepare(query);-- while (stmt.step()) {- const row = stmt.getAsObject();+ private readQueryAsJson(db: ISqliteDatabase, query: string): JsonRecord[] {+ return db.query(query).map(row => {const record: JsonRecord = {};for (const [column, value] of Object.entries(row)) {record[column] = value instanceof Uint8Array ? { __b64: bytesToBase64(value) } : value ?? null;}- records.push(record);- }- stmt.free();-- return records;+ return record;+ });}}/**- * Decode one Rust-returned SQL parameter into a sql.js-bindable value: `{ __b64 }` byte payloads+ * Decode one Rust-returned SQL parameter into a bindable value: `{ __b64 }` byte payloads* become Uint8Array, undefined becomes null.* @param param - the parameter as returned by the Rust merge*/-function toBindableParam(param: RustSqlParam): SqlValue {- if (param !== null && typeof param === 'object' && '__b64' in param) {+function toBindableParam(param: RustSqlStatement['params'][number] | undefined): SqliteValue {+ if (param !== null && param !== undefined && typeof param === 'object' && '__b64' in param) {return base64ToBytes(param.__b64);}return param ?? null;diff --git a/core/client/vitest.setup.ts b/core/client/vitest.setup.tsindex 46b448d3d..7ce73335f 100644--- a/core/client/vitest.setup.ts+++ b/core/client/vitest.setup.ts@@ -2,8 +2,10 @@ import { readFileSync } from 'node:fs';import { createRequire } from 'node:module';import path from 'node:path';+import { createSqlJsEngine } from './src/database/SqlJsEngine';import { setPlatform } from './src/platform/ClientPlatform';import { createInMemoryPlatform } from './src/platform/InMemoryPlatform';+import { createWasmRustCore } from './src/rust/WasmRustCore';const require = createRequire(import.meta.url);@@ -11,6 +13,6 @@ const require = createRequire(import.meta.url);* Registers a Node-backed platform for the unit tests: WASM from the local build output, sql.js from node_modules.*/setPlatform(createInMemoryPlatform({- loadRustCoreWasm: async (): Promise<BufferSource> => readFileSync(path.join(import.meta.dirname, 'wasm/aliasvault_core_bg.wasm')),- locateSqlJsFile: (file: string): string => path.join(path.dirname(require.resolve('sql.js')), file),+ rustCore: createWasmRustCore(async (): Promise<BufferSource> => readFileSync(path.join(import.meta.dirname, 'wasm/aliasvault_core_bg.wasm'))),+ sqlite: createSqlJsEngine((file: string): string => path.join(path.dirname(require.resolve('sql.js')), file)),}));