stream-chat-react-native-core 8.13.19 → 8.14.0

package/src/store/SqliteClient.ts

@@ -23,6 +23,29 @@ import { tables } from './schema';
 import { createCreateTableQuery } from './sqlite-utils/createCreateTableQuery';
 import type { PreparedBatchQueries, PreparedQueries, Scalar, Table } from './types';
 
+/**
+ * Why the offline database could not be opened. The first two only arise when
+ * {@link SqliteClient.getEncryptionKey} is set; `OFFLINE_DB_UNREADABLE` can also mean
+ * plain corruption, or a database left behind from the other encryption mode.
+ */
+export type SqliteClientErrorCode =
+  | 'SQLCIPHER_BUILD_MISSING'
+  | 'ENCRYPTION_KEY_UNAVAILABLE'
+  | 'OFFLINE_DB_UNREADABLE';
+
+export class SqliteClientError extends Error {
+  public readonly code: SqliteClientErrorCode;
+
+  constructor(code: SqliteClientErrorCode, message: string, options?: { cause?: unknown }) {
+    super(message);
+    this.name = 'SqliteClientError';
+    this.code = code;
+    // Assigned here rather than passed through `super(message, { cause })` because
+    // Hermes does not reliably honour the ErrorOptions overload.
+    this.cause = options?.cause;
+  }
+}
+
 /**
  * SqliteClient takes care of any direct interaction with sqlite.
  * This way usage @op-engineering/op-sqlite package is scoped to a single class/file.
@@ -35,10 +58,126 @@ export class SqliteClient {
   static logger: Logger | undefined;
   static db: DB | undefined;
 
+  /**
+   * Supplies the SQLCipher key the offline database is opened with; `undefined`
+   * opens it unencrypted, which is the default. The key must be stable for the
+   * lifetime of the database file - there is no rekey path, so a database this key
+   * cannot read raises `OFFLINE_DB_UNREADABLE` on the first page read. The file is
+   * left untouched; recovery is `SqliteClient.deleteDatabase()` and a re-mount.
+   */
+  static getEncryptionKey: (() => Promise<string | undefined>) | undefined;
+
+  /** Key resolved by {@link preflightEncryption}, consumed by the next {@link openDB}. */
+  private static preflightedKey: string | undefined;
+
+  /** Busy/disk/memory failures. Checked first: wiping over these destroys a good db. */
+  private static TRANSIENT_ERROR =
+    /database is locked|SQLITE_BUSY|SQLITE_LOCKED|disk i\/o|SQLITE_IOERR|unable to open|SQLITE_CANTOPEN|out of memory|readonly/i;
+
+  /**
+   * The bytes on disk cannot be read with the key we have: wrong/rotated key,
+   * plaintext-encrypted mismatch or corruption. SQLCipher has no decrypt specific
+   * code and overloads NOTADB (26), occasionally CORRUPT (11).
+   */
+  private static UNREADABLE_ERROR =
+    /not a database|file is encrypted|malformed|disk image is malformed|SQLite (?:error )?code:?\s*(?:26|11)\b|NOTADB|SQLITE_CORRUPT/i;
+
   static getDbVersion = () => SqliteClient.dbVersion;
   // Force a specific db version. This is mainly useful for testsuit.
   static setDbVersion = (version: number) => (SqliteClient.dbVersion = version);
 
+  /**
+   * Records and re-throws. Deliberately does not write to the console: the error is
+   * thrown, so logging it here would duplicate whatever the caller's error boundary
+   * reports - and in dev React already logs every boundary-caught error, which is what
+   * LogBox turns red.
+   */
+  private static recordError = (e: SqliteClientError) => {
+    this.logger?.('error', e.message, { tag: e.code });
+
+    throw e;
+  };
+
+  /**
+   * Resolves the encryption key without opening the database, so callers can decide
+   * whether to attach an `OfflineDB` at all. Parts of the client write through
+   * `client.offlineDb` without checking that it initialized (`queryChannels` upserts
+   * into it), so attaching one we cannot open turns those writes into rejections.
+   *
+   * Throws {@link SqliteClientError}. The key is handed to the next
+   * {@link openDB} rather than read from `getEncryptionKey` twice.
+   */
+  static preflightEncryption = async () => {
+    try {
+      this.preflightedKey = await this.resolveEncryptionKey();
+    } catch (e) {
+      if (e instanceof SqliteClientError) {
+        this.recordError(e);
+      }
+      throw e;
+    }
+  };
+
+  /**
+   * The key to open with, or `undefined` when the database is meant to be
+   * unencrypted. Throws rather than silently falling back to an unencrypted
+   * database, which would hand an integration that asked for encryption a plaintext
+   * cache of its users' messages.
+   */
+  private static resolveEncryptionKey = async () => {
+    const { getEncryptionKey } = this;
+
+    if (!getEncryptionKey) {
+      return undefined;
+    }
+
+    // A non-SQLCipher build accepts `encryptionKey` at the JSI boundary and then
+    // drops it - plaintext database, no error anywhere. `isSQLCipher` has existed
+    // since op-sqlite 9, well below the peer floor, so the typeof check is not really
+    // necessary but we'll keep it in case something changes in the future so that
+    // we at least have a clearer error.
+    if (sqlite === undefined) {
+      throw new SqliteClientError(
+        'SQLCIPHER_BUILD_MISSING',
+        'An offline database encryption key was provided but "@op-engineering/op-sqlite" ' +
+          'is not installed.',
+      );
+    }
+    if (typeof sqlite.isSQLCipher !== 'function' || !sqlite.isSQLCipher()) {
+      throw new SqliteClientError(
+        'SQLCIPHER_BUILD_MISSING',
+        'An offline database encryption key was provided but @op-engineering/op-sqlite was ' +
+          'not built with SQLCipher, so the key would be silently ignored and the offline ' +
+          'database written in plaintext. Add { "op-sqlite": { "sqlcipher": true } } to your ' +
+          "application's package.json and rebuild, or stop providing a key.",
+      );
+    }
+
+    let encryptionKey: string | undefined;
+
+    try {
+      encryptionKey = await getEncryptionKey();
+    } catch (error) {
+      throw new SqliteClientError(
+        'ENCRYPTION_KEY_UNAVAILABLE',
+        'The offline database encryption key getter threw, so the database cannot be opened.',
+        { cause: error },
+      );
+    }
+
+    // Not being handed a key is not the same as being handed the wrong one, so a locked
+    // keychain must not cost us a database we can still read later.
+    if (!encryptionKey) {
+      throw new SqliteClientError(
+        'ENCRYPTION_KEY_UNAVAILABLE',
+        'The offline database encryption key getter resolved without a key, so the database ' +
+          'cannot be opened.',
+      );
+    }
+
+    return encryptionKey;
+  };
+
   static openDB = async () => {
     try {
       if (sqlite === undefined) {
@@ -46,13 +185,24 @@ export class SqliteClient {
           'Please install "@op-engineering/op-sqlite" package to enable offline support',
         );
       }
+      const encryptionKey = this.preflightedKey ?? (await this.resolveEncryptionKey());
+      this.preflightedKey = undefined;
+
       this.db = sqlite.open({
         location: SqliteClient.dbLocation,
         name: SqliteClient.dbName,
+        ...(encryptionKey ? { encryptionKey } : {}),
       });
 
+      // Note: this will not fail on an encryption key mismatch, as we do not read
+      // any pages, but rather look at a connection level flag. The first failure
+      // is going to be whatever actually reads something, which is going to be
+      // the user_version read in initializeDatabase.
       await this.db?.execute('PRAGMA foreign_keys = ON', []);
     } catch (e) {
+      if (e instanceof SqliteClientError) {
+        throw e;
+      }
       this.logger?.('error', `Error opening database ${SqliteClient.dbName}`, {
         error: e,
       });
@@ -154,7 +304,23 @@ export class SqliteClient {
     return true;
   };
 
-  static initializeDatabase = async () => {
+  /**
+   * Whether the file cannot be read with the key we have, as opposed to being
+   * temporarily unavailable (busy, locked, disk). Works off message text because
+   * op-sqlite rejects with a plain Error and this class re-wraps those messages, so
+   * no numeric code survives. Drives `OFFLINE_DB_UNREADABLE`.
+   */
+  static isUnreadableDbError = (e: unknown) => {
+    const message = String((e as Error)?.message ?? e);
+
+    if (this.TRANSIENT_ERROR.test(message)) {
+      return false;
+    }
+
+    return this.UNREADABLE_ERROR.test(message);
+  };
+
+  static initializeDatabase = async (): Promise<boolean> => {
     try {
       await SqliteClient.openDB();
       const version = await SqliteClient.getUserPragmaVersion();
@@ -180,6 +346,24 @@ export class SqliteClient {
 
       return true;
     } catch (e) {
+      if (e instanceof SqliteClientError) {
+        this.recordError(e);
+      }
+
+      if (this.isUnreadableDbError(e)) {
+        this.recordError(
+          new SqliteClientError(
+            'OFFLINE_DB_UNREADABLE',
+            'The offline database exists but could not be read. Usually the encryption ' +
+              'key changed, or encryption was turned on or off while a database from ' +
+              'the other mode was still on disk. Delete it with ' +
+              'SqliteClient.deleteDatabase() and re-mount to rebuild from the server - ' +
+              'everything in it is a cache, except queued offline actions, which are lost.',
+            { cause: e },
+          ),
+        );
+      }
+
       console.log('Error initializing DB', e);
       this.logger?.('error', 'Error initializing DB', {
         dbLocation: SqliteClient.dbLocation,

package/src/store/__tests__/SqliteClient.test.ts

@@ -0,0 +1,258 @@
+import { sqliteMock } from '../../mock-builders/DB/mock';
+import { SqliteClient, SqliteClientError } from '../SqliteClient';
+
+// Captured before any spy is installed so the spy can call through to a real
+// better-sqlite3 handle while still observing the arguments open() was given.
+const openDatabase = sqliteMock.open;
+
+/** Runs `initializeDatabase` once and returns the error it threw. */
+const captureInitError = async () => {
+  try {
+    await SqliteClient.initializeDatabase();
+  } catch (error) {
+    return error as SqliteClientError;
+  }
+  throw new Error('expected initializeDatabase to reject, but it resolved');
+};
+
+describe('SqliteClient encryption', () => {
+  let openSpy: jest.SpyInstance<ReturnType<typeof sqliteMock.open>>;
+  let deleteMocks: jest.Mock[];
+
+  beforeEach(() => {
+    SqliteClient.getEncryptionKey = undefined;
+    SqliteClient.db = undefined;
+    SqliteClient.logger = jest.fn();
+
+    deleteMocks = [];
+    openSpy = jest.spyOn(sqliteMock, 'open').mockImplementation(() => {
+      const db = openDatabase();
+      const originalDelete = db.delete;
+      const deleteMock = jest.fn(() => originalDelete());
+      deleteMocks.push(deleteMock);
+      return { ...db, delete: deleteMock };
+    });
+
+    jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+    jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    jest.spyOn(console, 'log').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    SqliteClient.getEncryptionKey = undefined;
+    SqliteClient.logger = undefined;
+    SqliteClient.db = undefined;
+  });
+
+  describe('opening without encryption', () => {
+    it('does not pass an encryption key when no getter is configured', async () => {
+      await expect(SqliteClient.initializeDatabase()).resolves.toBe(true);
+
+      expect(openSpy).toHaveBeenCalledTimes(1);
+      expect(openSpy.mock.calls[0][0]).not.toHaveProperty('encryptionKey');
+    });
+
+    it('never consults isSQLCipher when no getter is configured', async () => {
+      const isSQLCipherSpy = jest.spyOn(sqliteMock, 'isSQLCipher');
+
+      await SqliteClient.initializeDatabase();
+
+      expect(isSQLCipherSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('opening with encryption', () => {
+    it('passes the resolved key to open()', async () => {
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue('a-stable-key');
+
+      await expect(SqliteClient.initializeDatabase()).resolves.toBe(true);
+
+      expect(SqliteClient.getEncryptionKey).toHaveBeenCalledTimes(1);
+      expect(openSpy.mock.calls[0][0]).toMatchObject({ encryptionKey: 'a-stable-key' });
+    });
+
+    it('refuses to open at all when op-sqlite has no SQLCipher build', async () => {
+      jest.spyOn(sqliteMock, 'isSQLCipher').mockReturnValue(false);
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue('a-stable-key');
+
+      const error = await captureInitError();
+
+      expect(error).toBeInstanceOf(SqliteClientError);
+
+      expect(error.code).toBe('SQLCIPHER_BUILD_MISSING');
+      // The whole point: no database is created, so nothing is written in plaintext.
+      expect(openSpy).not.toHaveBeenCalled();
+      // Nor is the key ever requested - the build is unusable regardless of it.
+      expect(SqliteClient.getEncryptionKey).not.toHaveBeenCalled();
+      expect(deleteMocks).toHaveLength(0);
+    });
+
+    it('refuses to open when isSQLCipher is missing from the installed op-sqlite', async () => {
+      // An op-sqlite too old to expose the check cannot be verified, so it is
+      // treated exactly like a build without SQLCipher.
+      const { isSQLCipher } = sqliteMock;
+      // @ts-expect-error deliberately simulating an older op-sqlite
+      delete sqliteMock.isSQLCipher;
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue('a-stable-key');
+
+      try {
+        const error = await captureInitError();
+
+        expect(error).toBeInstanceOf(SqliteClientError);
+        expect(error.code).toBe('SQLCIPHER_BUILD_MISSING');
+        expect(openSpy).not.toHaveBeenCalled();
+      } finally {
+        sqliteMock.isSQLCipher = isSQLCipher;
+      }
+    });
+  });
+
+  describe('when the encryption key cannot be obtained', () => {
+    it('gives up without wiping when the getter throws', async () => {
+      const cause = new Error('keychain is locked');
+      SqliteClient.getEncryptionKey = jest.fn().mockRejectedValue(cause);
+
+      const error = await captureInitError();
+
+      expect(error).toBeInstanceOf(SqliteClientError);
+
+      expect(error.code).toBe('ENCRYPTION_KEY_UNAVAILABLE');
+      expect(error.cause).toBe(cause);
+      expect(openSpy).not.toHaveBeenCalled();
+      // Not being handed a key says nothing about the database on disk, so it stays.
+      expect(deleteMocks).toHaveLength(0);
+    });
+
+    it('gives up without wiping when the getter resolves without a key', async () => {
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue(undefined);
+
+      const error = await captureInitError();
+
+      expect(error).toBeInstanceOf(SqliteClientError);
+
+      expect(error.code).toBe('ENCRYPTION_KEY_UNAVAILABLE');
+      expect(openSpy).not.toHaveBeenCalled();
+      expect(deleteMocks).toHaveLength(0);
+    });
+
+    it('treats an empty string as no key', async () => {
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue('');
+
+      const error = await captureInitError();
+
+      expect(error).toBeInstanceOf(SqliteClientError);
+
+      expect(error.code).toBe('ENCRYPTION_KEY_UNAVAILABLE');
+      expect(openSpy).not.toHaveBeenCalled();
+    });
+
+    it('clears a recorded encryption error once initialization succeeds', async () => {
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue(undefined);
+      const error = await captureInitError();
+
+      expect(error).toBeInstanceOf(SqliteClientError);
+      expect(error).toBeDefined();
+
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue('a-stable-key');
+      await expect(SqliteClient.initializeDatabase()).resolves.toBe(true);
+    });
+  });
+
+  describe('when the database cannot be read', () => {
+    const notADatabase = () =>
+      new Error('Querying for user_version failed: Error: file is not a database');
+
+    it('throws OFFLINE_DB_UNREADABLE instead of wiping it', async () => {
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue('a-stable-key');
+      jest.spyOn(SqliteClient, 'getUserPragmaVersion').mockRejectedValue(notADatabase());
+
+      const error = await captureInitError();
+
+      expect(error).toBeInstanceOf(SqliteClientError);
+
+      expect(error.code).toBe('OFFLINE_DB_UNREADABLE');
+      // Deleting it is the caller's decision - the pending-task queue lives in there.
+      expect(deleteMocks.every((m) => m.mock.calls.length === 0)).toBe(true);
+    });
+
+    it('keeps the original cause on the thrown error', async () => {
+      const cause = notADatabase();
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue('a-stable-key');
+      jest.spyOn(SqliteClient, 'getUserPragmaVersion').mockRejectedValue(cause);
+
+      const error = await captureInitError();
+
+      expect(error).toBeInstanceOf(SqliteClientError);
+
+      expect(error.cause).toBe(cause);
+    });
+
+    it('throws even with no encryption configured', async () => {
+      // Turning encryption off leaves an encrypted file and no key to read it. Simply
+      // reporting failure would leave offline support uninitialized forever, so the
+      // caller is told and can delete it.
+      jest.spyOn(SqliteClient, 'getUserPragmaVersion').mockRejectedValue(notADatabase());
+
+      const error = await captureInitError();
+
+      expect(error).toBeInstanceOf(SqliteClientError);
+
+      expect(error.code).toBe('OFFLINE_DB_UNREADABLE');
+    });
+
+    it('does not throw on a transient failure', async () => {
+      SqliteClient.getEncryptionKey = jest.fn().mockResolvedValue('a-stable-key');
+      jest
+        .spyOn(SqliteClient, 'getUserPragmaVersion')
+        .mockRejectedValue(new Error('Query failed: Error: database is locked'));
+
+      await expect(SqliteClient.initializeDatabase()).resolves.toBe(false);
+    });
+  });
+
+  describe('isUnreadableDbError', () => {
+    it.each([
+      'file is not a database',
+      'SQLite error code: 26',
+      'SQLite code:11',
+      'NOTADB',
+      'SQLITE_CORRUPT',
+      'database disk image is malformed',
+      'file is encrypted or is not a database',
+    ])('treats %p as unreadable', (message) => {
+      expect(SqliteClient.isUnreadableDbError(new Error(message))).toBe(true);
+    });
+
+    it.each([
+      'database is locked',
+      'SQLITE_BUSY',
+      'SQLITE_LOCKED',
+      'disk I/O error',
+      'SQLITE_IOERR',
+      'unable to open database file',
+      'SQLITE_CANTOPEN',
+      'out of memory',
+      'attempt to write a readonly database',
+      'DB is not open or initialized.',
+      'Please install "@op-engineering/op-sqlite" package to enable offline support',
+    ])('does not treat %p as unreadable', (message) => {
+      expect(SqliteClient.isUnreadableDbError(new Error(message))).toBe(false);
+    });
+
+    it('lets a transient reason win when both are present in one message', () => {
+      // Pins the precedence rule: a message that could be read either way must not
+      // trigger a wipe. Guessing wrong in this direction destroys a good database.
+      expect(
+        SqliteClient.isUnreadableDbError(
+          new Error('unable to open database file: file is not a database'),
+        ),
+      ).toBe(false);
+    });
+
+    it('handles non-Error throwables', () => {
+      expect(SqliteClient.isUnreadableDbError('file is not a database')).toBe(true);
+      expect(SqliteClient.isUnreadableDbError(undefined)).toBe(false);
+    });
+  });
+});

package/src/test-utils/BetterSqlite.js

@@ -2,11 +2,14 @@ import Database from 'better-sqlite3';
 
 import { tables } from '../store/schema';
 
+// Must match the name used by mock-builders/DB/mock.ts.
+const testDbName = `foobar-${process.env.JEST_WORKER_ID ?? '0'}.db`;
+
 export class BetterSqlite {
   db = null;
 
   static openDB = () => {
-    this.db = new Database('foobar.db');
+    this.db = new Database(testDbName);
   };
 
   static closeDB = () => {

package/src/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "8.13.19"
+  "version": "8.14.0"
 }