Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

18.4 KB
Raw Blame
import { VaultDataBucketCategory } from '@aliasvault/models/vault';
import { VaultSqlGenerator, checkVersionCompatibility, extractVersionFromMigrationId } from '@aliasvault/vault';

import { VaultVersionIncompatibleError } from '../api/errors/VaultVersionIncompatibleError';
import { StorageKeys } from '../constants/StorageKeys';
import { getPlatform } from '../platform/ClientPlatform';
import { bytesToBase64 } from '../utilities/Base64';
import { logDefect } from '../utilities/Diagnostics';
import { detectImageMimeType } from '../utilities/ImageType';

import { syncRepository } from './DbOp';

import {
  ItemRepository,
  ItemStatsRepository,
  PasskeyRepository,
  FolderRepository,
  SettingsRepository,
  EncryptionKeyRepository,
  LogoRepository,
  ImportExportRepository,
  StorageInsightsRepository
} from './index';

import type { ISyncDatabaseClient, SqliteBindValue } from './BaseRepository';
import type { SyncRepository } from './DbOp';
import type { ISqliteDatabase } from '../platform/SqliteEngine';
import type { VaultMutationScope } from '../sync/VaultMutationScope';
import type { VaultVersion } from '@aliasvault/vault';

/**
 * Core SQLite database client.
 * Provides low-level database operations and exposes repositories for domain-specific operations.
 */
export class SqliteClient implements ISyncDatabaseClient {
  private db: ISqliteDatabase | null = null;
  private transactionOpen: boolean = false;

  /**
   * The mutation scopes written into since the host last drained them. Writes on this client persist nothing
   * by themselves: the host exports the whole database afterwards, and reads this to know what changed.
   */
  private readonly pendingMutationScopes = new Set<VaultMutationScope>();

  /**
   * The id of the user's personal manifest.
   */
  private personalManifestId: string | null = null;

  // Lazy-initialized repositories
  private _items: SyncRepository<ItemRepository> | null = null;
  private _itemStats: SyncRepository<ItemStatsRepository> | null = null;
  private _passkeys: SyncRepository<PasskeyRepository> | null = null;
  private _folders: SyncRepository<FolderRepository> | null = null;
  private _settings: SyncRepository<SettingsRepository> | null = null;
  private _encryptionKeys: SyncRepository<EncryptionKeyRepository> | null = null;
  private _logos: SyncRepository<LogoRepository> | null = null;
  private _importExport: SyncRepository<ImportExportRepository> | null = null;
  private _storageInsights: SyncRepository<StorageInsightsRepository> | null = null;
  private _logoRepository: LogoRepository | null = null;

  /**
   * The id of the user's personal manifest, as reported by the last pull.
   * @returns The personal manifest id, or null when no pull has recorded one yet
   */
  public getPersonalManifestId(): string | null {
    return this.personalManifestId;
  }

  /**
   * Repository for Item CRUD operations.
   */
  public get items(): SyncRepository<ItemRepository> {
    if (!this._items) {
      this._items = syncRepository(new ItemRepository(this, this.logoRepository), this);
    }
    return this._items;
  }

  /**
   * Repository for per-item usage statistics (last used, use counts).
   */
  public get itemStats(): SyncRepository<ItemStatsRepository> {
    if (!this._itemStats) {
      this._itemStats = syncRepository(new ItemStatsRepository(this), this, VaultDataBucketCategory.Stats);
    }
    return this._itemStats;
  }

  /**
   * Repository for Passkey operations.
   */
  public get passkeys(): SyncRepository<PasskeyRepository> {
    if (!this._passkeys) {
      this._passkeys = syncRepository(new PasskeyRepository(this), this);
    }
    return this._passkeys;
  }

  /**
   * Repository for Folder operations.
   */
  public get folders(): SyncRepository<FolderRepository> {
    if (!this._folders) {
      this._folders = syncRepository(new FolderRepository(this), this);
    }
    return this._folders;
  }

  /**
   * Repository for the vault's user preferences.
   */
  public get settings(): SyncRepository<SettingsRepository> {
    if (!this._settings) {
      this._settings = syncRepository(new SettingsRepository(this), this, VaultDataBucketCategory.Settings);
    }
    return this._settings;
  }

  /**
   * Repository for the per-manifest keypairs that receive mail.
   */
  public get encryptionKeys(): SyncRepository<EncryptionKeyRepository> {
    if (!this._encryptionKeys) {
      this._encryptionKeys = syncRepository(new EncryptionKeyRepository(this), this);
    }
    return this._encryptionKeys;
  }

  /**
   * Repository for item logo operations (favicons, built-in logos and uploaded images alike).
   */
  public get logos(): SyncRepository<LogoRepository> {
    if (!this._logos) {
      this._logos = syncRepository(this.logoRepository, this);
    }
    return this._logos;
  }

  /**
   * Repository for the import/export logic.
   */
  public get importExport(): SyncRepository<ImportExportRepository> {
    if (!this._importExport) {
      this._importExport = syncRepository(new ImportExportRepository(this, this.logoRepository), this);
    }
    return this._importExport;
  }

  /**
   * Repository for the storage statistics of the local vault.
   */
  public get storageInsights(): SyncRepository<StorageInsightsRepository> {
    if (!this._storageInsights) {
      this._storageInsights = syncRepository(new StorageInsightsRepository(this), this);
    }
    return this._storageInsights;
  }

  /**
   * The logo repository itself, which the item and import/export repositories call into.
   */
  private get logoRepository(): LogoRepository {
    if (!this._logoRepository) {
      this._logoRepository = new LogoRepository(this);
    }
    return this._logoRepository;
  }

  // ===== IDatabaseClient Implementation =====

  /**
   * Get the underlying database instance.
   */
  public getDb(): ISqliteDatabase | null {
    return this.db;
  }

  /**
   * Initialize the SQLite database from the raw database bytes.
   * @param bytes - the SQLite database
   */
  public async initializeFromBytes(bytes: Uint8Array): Promise<void> {
    try {
      // 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;

      // Reset repository instances when database changes
      this._items = null;
      this._passkeys = null;
      this._folders = null;
      this._settings = null;
      this._logos = null;
      this._importExport = null;
    } catch (error) {
      logDefect('[Sqlite] Initializing the database failed', error);
      throw error;
    }
  }

  /**
   * Whether a transaction is open.
   */
  public isInTransaction(): boolean {
    return this.transactionOpen;
  }

  /**
   * Begin a new transaction.
   */
  public beginTransaction(): void {
    if (!this.db) {
      throw new Error('Database not initialized');
    }

    if (this.transactionOpen) {
      throw new Error('Transaction already in progress');
    }

    try {
      this.db.exec('BEGIN TRANSACTION');
      this.transactionOpen = true;
    } catch (error) {
      logDefect('[Sqlite] BEGIN TRANSACTION failed', error);
      throw error;
    }
  }

  /**
   * Commit the current transaction.
   */
  public async commitTransaction(): Promise<void> {
    if (!this.db) {
      throw new Error('Database not initialized');
    }

    if (!this.transactionOpen) {
      throw new Error('No transaction in progress');
    }

    try {
      this.db.exec('COMMIT');
      this.transactionOpen = false;
    } catch (error) {
      logDefect('[Sqlite] COMMIT failed', error);
      throw error;
    }
  }

  /**
   * Record that a repository wrote into a mutation scope.
   * @param scope - The scope that was written into
   */
  public recordMutationScope(scope: VaultMutationScope): void {
    this.pendingMutationScopes.add(scope);
  }

  /**
   * Take the scopes written into since the last drain, and clear them. Called by the host right after the
   * operation it is about to persist, so the sync knows whether a bucket-only push covers the change. A host
   * whose persist then fails puts them back through {@link recordMutationScope}: the write stays in the
   * database either way, and an unrecorded scope can strand it behind a later bucket-only push.
   * @returns The scopes written into, empty when nothing was written
   */
  public takeMutationScopes(): VaultMutationScope[] {
    const scopes = [...this.pendingMutationScopes];
    this.pendingMutationScopes.clear();
    return scopes;
  }

  /**
   * Rollback the current transaction.
   */
  public rollbackTransaction(): void {
    if (!this.db) {
      throw new Error('Database not initialized');
    }

    if (!this.transactionOpen) {
      throw new Error('No transaction in progress');
    }

    try {
      this.db.exec('ROLLBACK');
      this.transactionOpen = false;
    } catch (error) {
      logDefect('[Sqlite] ROLLBACK failed', error);
      throw error;
    }
  }

  /**
   * Export the SQLite database as raw bytes (the Rust core compacts it first when fragmented).
   * @returns The database bytes
   */
  public exportToBytes(): Uint8Array {
    if (!this.db) {
      throw new Error('Database not initialized');
    }

    try {
      return this.db.export();
    } catch (error) {
      logDefect('[Sqlite] Exporting the database failed', error);
      throw error;
    }
  }

  /**
   * Execute a SELECT query.
   * @param query - SQL query string
   * @param params - Query parameters
   * @returns Array of result objects
   */
  public executeQuery<T>(query: string, params: SqliteBindValue[] = []): T[] {
    if (!this.db) {
      throw new Error('Database not initialized');
    }

    try {
      return this.db.query<T>(query, params);
    } catch (error) {
      logDefect(`[Sqlite] Query failed: ${query}`, error);
      throw error;
    }
  }

  /**
   * Whether a table has a given column.
   * @param table - Table name
   * @param column - Column name
   * @returns True when the table exists and has the column
   */
  public hasColumn(table: string, column: string): boolean {
    return this.executeQuery<{ name: string }>('SELECT name FROM pragma_table_info(?) WHERE name = ?', [table, column]).length > 0;
  }

  /**
   * Execute an INSERT, UPDATE, or DELETE query.
   * @param query - SQL query string
   * @param params - Query parameters
   * @returns Number of rows affected
   */
  public executeUpdate(query: string, params: SqliteBindValue[] = []): number {
    if (!this.db) {
      throw new Error('Database not initialized');
    }

    try {
      return this.db.run(query, params);
    } catch (error) {
      logDefect(`[Sqlite] Update failed: ${query}`, error);
      throw error;
    }
  }

  /**
   * Execute raw SQL command(s).
   * @param query - SQL command(s) to execute (may contain multiple statements separated by semicolons)
   */
  public executeRaw(query: string): void {
    if (!this.db) {
      throw new Error('Database not initialized');
    }

    try {
      const statements = query.split(';');

      for (const statement of statements) {
        const trimmedStatement = statement.trim();

        // Skip empty statements and transaction control statements
        if (trimmedStatement.length === 0 ||
            trimmedStatement.toUpperCase().startsWith('BEGIN TRANSACTION') ||
            trimmedStatement.toUpperCase().startsWith('COMMIT') ||
            trimmedStatement.toUpperCase().startsWith('ROLLBACK')) {
          continue;
        }

        this.db.exec(trimmedStatement);
      }
    } catch (error) {
      logDefect('[Sqlite] Raw SQL failed', error);
      throw error;
    }
  }

  /**
   * Close the database connection and free resources.
   */
  public close(): void {
    if (this.db) {
      this.db.close();
      this.db = null;
    }
  }

  /**
   * Get the current database version from the migrations history.
   *
   * LEGACY: part of the sqlite-blob upgrade chain (frozen up to 2.0.0); remove once every account
   * has migrated. New schema changes ship via requiresSchemaMigration / migrateVaultToCurrentSchema instead.
   * @returns The database version information
   */
  public async getDatabaseVersion(): Promise<VaultVersion> {
    if (!this.db) {
      throw new Error('Database not initialized');
    }

    try {
      const results = this.executeQuery<{ MigrationId: string }>(`
        SELECT MigrationId
        FROM __EFMigrationsHistory
        ORDER BY MigrationId DESC
        LIMIT 1`);

      if (results.length === 0) {
        throw new Error('No migrations found in the database.');
      }

      const migrationId = results[0].MigrationId;
      const databaseVersion = extractVersionFromMigrationId(migrationId);

      if (!databaseVersion) {
        throw new Error('Could not extract version from migration ID');
      }

      const compatibilityResult = checkVersionCompatibility(databaseVersion);

      if (!compatibilityResult.isCompatible) {
        const errorMessage = await getPlatform().translate('common.errors.clientOutdated');
        throw new VaultVersionIncompatibleError(errorMessage);
      }

      if (compatibilityResult.isKnownVersion && compatibilityResult.clientVersion) {
        return compatibilityResult.clientVersion;
      }

      const vaultSqlGenerator = new VaultSqlGenerator();
      const latestClientVersion = vaultSqlGenerator.getLatestVersion();

      return {
        revision: latestClientVersion.revision,
        version: databaseVersion,
        description: `Unknown version ${databaseVersion} (backwards compatible)`,
        releaseVersion: latestClientVersion.releaseVersion,
        compatibleUpToVersion: latestClientVersion.compatibleUpToVersion
      };
    } catch (error) {
      logDefect('[Sqlite] Reading the database version failed', error);
      throw error;
    }
  }

  /**
   * Get the latest available database version.
   *
   * LEGACY: part of the sqlite-blob upgrade chain (frozen up to 2.0.0); remove once every account
   * has migrated. New schema changes ship via requiresSchemaMigration / migrateVaultToCurrentSchema instead.
   * @returns The latest VaultVersion
   */
  public async getLatestDatabaseVersion(): Promise<VaultVersion> {
    const vaultSqlGenerator = new VaultSqlGenerator();
    const allVersions = vaultSqlGenerator.getAllVersions();
    return allVersions[allVersions.length - 1];
  }

  /**
   * Whether the vault still has to walk the sqlite-blob upgrade chain (VAULT_VERSIONS, frozen at 2.0.0) via the /upgrade
   * page before it is eligible for anything else.
   *
   * LEGACY: the sqlite-blob migration path, which will stop being supported later; remove once every
   * account has migrated. New schema changes ship via requiresSchemaMigration / migrateVaultToCurrentSchema instead.
   * @returns True if there are pending migrations
   */
  public async requiresLegacySqliteBlobMigration(): Promise<boolean> {
    try {
      const currentVersion = await this.getDatabaseVersion();
      const latestVersion = await this.getLatestDatabaseVersion();

      return currentVersion.revision < latestVersion.revision;
    } catch (error) {
      logDefect('[Sqlite] Checking for pending migrations failed', error);
      throw error;
    }
  }

  /**
   * Whether the local database schema is older than the current full schema (COMPLETE_SCHEMA_SQL).
   * 
   * @returns True when the local schema predates the current full schema
   */
  public async requiresSchemaMigration(): Promise<boolean> {
    if (await this.requiresLegacySqliteBlobMigration()) {
      /*
       * Still on the sqlite-blob upgrade chain: that upgrade has to run first, so the migration is not applicable yet.
       * LEGACY: remove once every account has migrated.
       */
      return false;
    }

    const localMigrationId = this.getLatestMigrationId();
    const schemaMigrationId = new VaultSqlGenerator().getCompleteSchemaMigrationId();

    // An unstamped database or an unreadable schema constant gives no evidence of staleness; don't block on a guess.
    if (!localMigrationId || !schemaMigrationId) {
      return false;
    }

    return localMigrationId < schemaMigrationId;
  }

  /**
   * The latest EF migration id the vault is stamped with, or an empty string when it carries none.
   */
  private getLatestMigrationId(): string {
    try {
      return this.executeQuery<{ MigrationId: string }>('SELECT MigrationId FROM __EFMigrationsHistory ORDER BY MigrationId DESC LIMIT 1')[0]?.MigrationId ?? '';
    } catch {
      return '';
    }
  }

  /**
   * Convert binary data to a base64 encoded image source.
   * @param bytes - Binary image data
   * @returns Data URL for the image, or null if no valid image data
   */
  public static imgSrcFromBytes(bytes: Uint8Array<ArrayBufferLike> | number[] | undefined): string | null {
    if (!bytes || (Array.isArray(bytes) && bytes.length === 0) || (bytes instanceof Uint8Array && bytes.length === 0)) {
      return null;
    }

    try {
      const logoBytes = this.toUint8Array(bytes);
      const base64Logo = this.base64Encode(logoBytes);
      if (!base64Logo) {
        return null;
      }
      const mimeType = this.detectMimeType(logoBytes);
      return `data:${mimeType};base64,${base64Logo}`;
    } catch (error) {
      logDefect('[Sqlite] Building the logo data URL failed', error);
      return null;
    }
  }

  /**
   * Detect MIME type from file signature (magic numbers), defaulting to an icon.
   * @param bytes - Binary data to analyze
   * @returns MIME type string
   */
  private static detectMimeType(bytes: Uint8Array): string {
    return detectImageMimeType(bytes) ?? 'image/x-icon';
  }

  /**
   * Convert various binary data formats to Uint8Array.
   * @param buffer - Binary data in various formats
   * @returns Normalized Uint8Array
   */
  private static toUint8Array(buffer: Uint8Array | number[] | { [key: number]: number }): Uint8Array {
    if (buffer instanceof Uint8Array) {
      return buffer;
    }

    if (Array.isArray(buffer)) {
      return new Uint8Array(buffer);
    }

    const length = Object.keys(buffer).length;
    const arr = new Uint8Array(length);
    for (let i = 0; i < length; i++) {
      arr[i] = buffer[i];
    }

    return arr;
  }

  /**
   * Base64 encode binary data.
   * @param buffer - Binary data to encode
   * @returns Base64 encoded string or null on error
   */
  private static base64Encode(buffer: Uint8Array | number[] | { [key: number]: number }): string | null {
    try {
      return bytesToBase64(this.toUint8Array(buffer));
    } catch (error) {
      logDefect('[Sqlite] Base64 encoding failed', error);
      return null;
    }
  }
}

export default SqliteClient;