Skip to content

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 storage
this.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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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)),
}));