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

package/src/components/Chat/hooks/useInitializeOfflineDb.ts

@@ -0,0 +1,109 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import type { StreamChat } from 'stream-chat';
+
+import { useStableCallback } from '../../../hooks/useStableCallback';
+import { OfflineDB } from '../../../store/OfflineDB';
+import { SqliteClient, SqliteClientError } from '../../../store/SqliteClient';
+
+export type InitializeOfflineDbOptions = {
+  /**
+   * Encrypts the offline database at rest with SQLCipher, using the key this resolves
+   * to. Leaving it unset opens the database unencrypted, which is the default. See
+   * `ChatProps.getOfflineDbEncryptionKey` for the build flag it requires, the stability
+   * requirement, and how failures are surfaced.
+   */
+  getEncryptionKey?: () => Promise<string | undefined>;
+};
+
+export type UseInitializeOfflineDbParams = {
+  client: StreamChat;
+  /** Whether offline support is enabled at all. */
+  enabled: boolean;
+  options?: InitializeOfflineDbOptions;
+  userID?: string;
+};
+
+/**
+ * Attaches an offline database to the client and initializes it for a user.
+ *
+ * **Raises** whatever prevented the database from opening, from render, so an error
+ * boundary above the caller can decide what to do. The offline database is never
+ * silently downgraded, because an integration that asked for encryption must not end
+ * up with an unencrypted cache.
+ */
+export const useInitializeOfflineDb = ({
+  client,
+  enabled,
+  options,
+  userID,
+}: UseInitializeOfflineDbParams) => {
+  /**
+   * Why this attempt could not open the offline database.
+   *
+   * Held per attempt rather than read from a longer-lived source: a value that outlived
+   * the attempt would be seen during the first render after a re-mount and raised
+   * before that mount's own attempt could run, so an error boundary that re-mounts to
+   * retry would loop forever.
+   */
+  const [initializationError, setInitializationError] = useState<SqliteClientError>();
+
+  const { getEncryptionKey } = options ?? {};
+
+  // `getEncryptionKey` is overwhelmingly likely to be an inline arrow. Stabilising it
+  // keeps a new identity per render out of the dependencies below, while still calling
+  // whatever the latest prop is.
+  const resolveEncryptionKey = useStableCallback(
+    () => getEncryptionKey?.() ?? Promise.resolve(undefined),
+  );
+  const isEncryptionEnabled = !!getEncryptionKey;
+
+  const initialize = useCallback(async () => {
+    if (!(userID && enabled)) {
+      return;
+    }
+
+    if (!client.offlineDb) {
+      const keyGetter = isEncryptionEnabled ? resolveEncryptionKey : undefined;
+
+      // Confirm the database can be opened before attaching it: the client writes
+      // through `client.offlineDb` without checking that it initialized, so one we
+      // cannot open turns those writes into rejections (and UI is affected directly).
+      if (keyGetter) {
+        SqliteClient.getEncryptionKey = keyGetter;
+        try {
+          await SqliteClient.preflightEncryption();
+        } catch (error) {
+          if (error instanceof SqliteClientError) {
+            setInitializationError(error);
+            return;
+          }
+          throw error;
+        }
+      }
+
+      client.setOfflineDBApi(new OfflineDB({ client, getEncryptionKey: keyGetter }));
+    }
+
+    const { offlineDb } = client;
+    if (offlineDb) {
+      await offlineDb.init(userID);
+      // Note: Since `init()` currently swallows errors by design, we have to rely
+      // on consuming the error later in order to be able to still rethrow without
+      // introducing a breaking change.
+      // TODO: The DB API should be changed in the next major to always throw upwards
+      //       and let integrators handle it if necessary.
+      setInitializationError(
+        offlineDb instanceof OfflineDB ? offlineDb.initializationError : undefined,
+      );
+    }
+  }, [client, enabled, isEncryptionEnabled, resolveEncryptionKey, userID]);
+
+  useEffect(() => {
+    initialize();
+  }, [initialize]);
+
+  if (initializationError) {
+    throw initializationError;
+  }
+};

package/src/index.ts

@@ -32,7 +32,7 @@ export { default as ruTranslations } from './i18n/ru.json';
 export { default as trTranslations } from './i18n/tr.json';
 
 export * from './state-store';
-export { SqliteClient } from './store/SqliteClient';
+export { SqliteClient, SqliteClientError, type SqliteClientErrorCode } from './store/SqliteClient';
 export { OfflineDB } from './store/OfflineDB';
 export { version } from './version.json';
 

package/src/mock-builders/DB/mock.ts

@@ -1,12 +1,21 @@
+import { rmSync } from 'fs';
+
 import Sqlite3 from 'better-sqlite3';
 
 import type { PreparedQueries } from '../../store/types';
 
 let db: Sqlite3.Database;
+// Per jest worker: workers run in parallel, and `delete()` below unlinks this file.
+const testDbName = `foobar-${process.env.JEST_WORKER_ID ?? '0'}.db`;
 
 export const sqliteMock = {
+  // better-sqlite3 has no SQLCipher, so an `encryptionKey` passed to open() is
+  // simply ignored. Reporting a SQLCipher build keeps the encrypted path
+  // exercisable in tests; whether the bytes on disk are actually encrypted can
+  // only be verified on a device. Spy on this to test the build-missing guard.
+  isSQLCipher: () => true,
   open: () => {
-    db = new Sqlite3('foobar.db');
+    db = new Sqlite3(testDbName);
     return {
       close: () => {
         db.close();
@@ -15,6 +24,12 @@ export const sqliteMock = {
           status: 0,
         };
       },
+      // Mirrors op-sqlite's delete(): closes the handle and unlinks the file, so a
+      // subsequent open() starts from an empty database.
+      delete: () => {
+        db.close();
+        rmSync(testDbName, { force: true });
+      },
       execute: async (queryInput: string, params: unknown[]) => {
         const query = queryInput.trim().toLowerCase();
 

package/src/store/OfflineDB.ts

@@ -9,11 +9,25 @@ import type {
 } from 'stream-chat';
 
 import * as api from './apis';
-import { SqliteClient } from './SqliteClient';
+import { SqliteClient, SqliteClientError } from './SqliteClient';
 
 export class OfflineDB extends AbstractOfflineDB {
-  constructor({ client }: { client: StreamChat }) {
+  constructor({
+    client,
+    getEncryptionKey,
+  }: {
+    client: StreamChat;
+    /**
+     * Supplies the SQLCipher key the offline database is opened with. See
+     * {@link SqliteClient.getEncryptionKey} for the stability requirement.
+     */
+    getEncryptionKey?: () => Promise<string | undefined>;
+  }) {
     super({ client });
+    // Assigned unconditionally: SqliteClient holds this statically, so leaving a
+    // previous instance's getter in place would keep encrypting after the caller
+    // stopped asking for it.
+    SqliteClient.getEncryptionKey = getEncryptionKey;
   }
 
   upsertCidsForQuery = api.upsertCidsForQuery;
@@ -102,5 +116,26 @@ export class OfflineDB extends AbstractOfflineDB {
 
   executeSqlBatch = SqliteClient.executeSqlBatch;
 
-  initializeDB = SqliteClient.initializeDatabase;
+  /**
+   * Why the most recent {@link initializeDB} failed, if it did.
+   *
+   * `AbstractOfflineDB.init` catches whatever `initializeDB` throws and does not
+   * re-throw it, so a caller has no way to see the reason. Recording it here on the
+   * way out gives the caller something to read back once `init` has settled. Kept on
+   * the instance rather than a static so two clients cannot overwrite each other.
+   */
+  initializationError: SqliteClientError | undefined;
+
+  initializeDB = async () => {
+    this.initializationError = undefined;
+    try {
+      return await SqliteClient.initializeDatabase();
+    } catch (error) {
+      if (error instanceof SqliteClientError) {
+        this.initializationError = error;
+      }
+      // Re-thrown so `AbstractOfflineDB.init` still marks the database uninitialized.
+      throw error;
+    }
+  };
 }

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,