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

package/src/components/Chat/Chat.tsx

@@ -5,6 +5,7 @@ import { Channel, OfflineDBState } from 'stream-chat';
 
 import { useAppSettings } from './hooks/useAppSettings';
 import { useCreateChatContext } from './hooks/useCreateChatContext';
+import { useInitializeOfflineDb } from './hooks/useInitializeOfflineDb';
 import { useIsOnline } from './hooks/useIsOnline';
 import { useMutedUsers } from './hooks/useMutedUsers';
 
@@ -22,7 +23,6 @@ import { useStreami18n } from '../../hooks/useStreami18n';
 import init from '../../init';
 
 import { NativeHandlers } from '../../native';
-import { OfflineDB } from '../../store/OfflineDB';
 
 import type { Streami18n } from '../../utils/i18n/Streami18n';
 import { version } from '../../version.json';
@@ -42,6 +42,50 @@ export type ChatProps = Pick<ChatContextValue, 'client'> &
      * Enables offline storage and loading for chat data.
      */
     enableOfflineSupport?: boolean;
+    /**
+     * Encrypts the offline database at rest with SQLCipher, using the key this
+     * resolves to. Only relevant when `enableOfflineSupport` is enabled. Leaving it
+     * unset keeps the offline database unencrypted, which is the default.
+     *
+     * Requires a native build of `@op-engineering/op-sqlite` that includes SQLCipher.
+     * Add the following to your application's `package.json` and rebuild the native
+     * app - without the flag the key is accepted and then silently ignored:
+     *
+     * ```json
+     * { "op-sqlite": { "sqlcipher": true } }
+     * ```
+     *
+     * **Wrap `<Chat>` in an error boundary.** If the database cannot be opened with
+     * the encryption you asked for, `<Chat>` throws a {@link SqliteClientError}
+     * from render instead of continuing without it. The SDK deliberately takes no
+     * recovery action of its own - it never deletes data, and never silently falls
+     * back to an unencrypted or absent cache. Discriminate on `code`:
+     *
+     * - `OFFLINE_DB_UNREADABLE` - the file exists but this key cannot read it (the
+     *   key changed, or the database predates encryption). **Recommended recovery:
+     *   `SqliteClient.deleteDatabase()`, then re-mount `<Chat>`.** The contents are a
+     *   cache and are refetched from the server; the exception is actions queued while
+     *   offline, which are lost - prompt the user first if that matters to you.
+     * - `ENCRYPTION_KEY_UNAVAILABLE` - the key could not be read (a locked keychain, a
+     *   launch before first unlock). The database is untouched. **Recommended
+     *   recovery: re-mount to retry** once the key is readable - for example when the
+     *   app next returns to the foreground.
+     * - `SQLCIPHER_BUILD_MISSING` - the native build has no SQLCipher, so the key
+     *   would be ignored and the database written in plaintext. Not recoverable at
+     *   runtime; it needs the build flag above and a new binary. **Recommended
+     *   recovery: re-mount with `enableOfflineSupport={false}`** so nothing is
+     *   persisted unencrypted.
+     *
+     * The key must be **stable for the lifetime of the database file**. There is no
+     * rekey path, so a key that changes costs one `OFFLINE_DB_UNREADABLE` and a
+     * rebuild. To rotate without paying that, rotate a key-encryption key and keep the
+     * database key it protects unchanged (envelope encryption).
+     *
+     * Switching encryption on, or back off, leaves a database from the other mode on
+     * disk and so raises `OFFLINE_DB_UNREADABLE` once in each direction. Deleting it
+     * from your boundary is all that is needed.
+     */
+    getOfflineDbEncryptionKey?: () => Promise<string | undefined>;
     /**
      * Instance of Streami18n class should be provided to Chat component to enable internationalization.
      *
@@ -143,6 +187,7 @@ const ChatWithContext = (props: PropsWithChildren<ChatProps>) => {
     client,
     closeConnectionOnBackground = true,
     enableOfflineSupport = false,
+    getOfflineDbEncryptionKey,
     i18nInstance,
     ImageComponent = Image,
     isMessageAIGenerated,
@@ -211,23 +256,12 @@ const ChatWithContext = (props: PropsWithChildren<ChatProps>) => {
 
   const setActiveChannel = (newChannel?: Channel) => setChannel(newChannel);
 
-  useEffect(() => {
-    if (!(userID && enableOfflineSupport)) {
-      return;
-    }
-
-    const initializeDatabase = async () => {
-      if (!client.offlineDb) {
-        client.setOfflineDBApi(new OfflineDB({ client }));
-      }
-
-      if (client.offlineDb) {
-        await client.offlineDb.init(userID);
-      }
-    };
-
-    initializeDatabase();
-  }, [userID, enableOfflineSupport, client]);
+  useInitializeOfflineDb({
+    client,
+    enabled: enableOfflineSupport,
+    options: { getEncryptionKey: getOfflineDbEncryptionKey },
+    userID,
+  });
 
   useEffect(() => {
     if (!client) {

package/src/components/Chat/__tests__/ChatOfflineDbEncryption.test.tsx

@@ -0,0 +1,248 @@
+import React, { PropsWithChildren } from 'react';
+import { View } from 'react-native';
+
+import { cleanup, render, waitFor } from '@testing-library/react-native';
+
+import { sqliteMock } from '../../../mock-builders/DB/mock';
+import { getTestClientWithUser } from '../../../mock-builders/mock';
+import { SqliteClient, SqliteClientError } from '../../../store/SqliteClient';
+import { Chat } from '../Chat';
+
+describe('Chat offline DB encryption', () => {
+  const installedSpies: jest.SpyInstance[] = [];
+
+  /**
+   * Registers a spy for teardown. Deliberately not jest.restoreAllMocks(): that also
+   * restores the connection privates mockClient() stubs out on every client created
+   * by earlier tests in this file, after which those clients reconnect for real and
+   * the failed websocket handshake resurfaces as an unhandled error somewhere else.
+   */
+  const track = <T extends jest.SpyInstance>(spy: T): T => {
+    installedSpies.push(spy);
+    return spy;
+  };
+
+  /**
+   * Chat mounts useIsOnline, which opens the websocket whenever the app comes to the
+   * foreground. Left real, that connection attempt outlives the test and rejects
+   * asynchronously. Nothing in this block needs a connection.
+   */
+  const createClient = async () => {
+    const client = await getTestClientWithUser({ id: 'testID' });
+    track(jest.spyOn(client, 'openConnection').mockResolvedValue(undefined));
+    track(jest.spyOn(client, 'closeConnection').mockResolvedValue(undefined));
+    return client;
+  };
+
+  /** Minimal error boundary, since `<Chat>` reports encryption failures by throwing. */
+  class Boundary extends React.Component<
+    PropsWithChildren<{ onCatch: (error: Error) => void }>,
+    { caught: boolean }
+  > {
+    state = { caught: false };
+
+    static getDerivedStateFromError() {
+      return { caught: true };
+    }
+
+    componentDidCatch(error: Error) {
+      this.props.onCatch(error);
+    }
+
+    render() {
+      return this.state.caught ? <View testID='boundary' /> : this.props.children;
+    }
+  }
+
+  afterEach(() => {
+    cleanup();
+    installedSpies.splice(0).forEach((spy) => spy.mockRestore());
+    SqliteClient.getEncryptionKey = undefined;
+  });
+
+  it('does not configure an encryption key when the prop is omitted', async () => {
+    const chatClientWithUser = await createClient();
+
+    render(<Chat client={chatClientWithUser} enableOfflineSupport />);
+
+    await waitFor(() => expect(chatClientWithUser.offlineDb).toBeDefined());
+    expect(SqliteClient.getEncryptionKey).toBeUndefined();
+  });
+
+  it('forwards getOfflineDbEncryptionKey to the sqlite client', async () => {
+    const chatClientWithUser = await createClient();
+    const getOfflineDbEncryptionKey = jest.fn().mockResolvedValue('a-stable-key');
+
+    render(
+      <Chat
+        client={chatClientWithUser}
+        enableOfflineSupport
+        getOfflineDbEncryptionKey={getOfflineDbEncryptionKey}
+      />,
+    );
+
+    await waitFor(() => expect(chatClientWithUser.offlineDb).toBeDefined());
+    await waitFor(() => expect(getOfflineDbEncryptionKey).toHaveBeenCalled());
+  });
+
+  it('does not re-initialize when getOfflineDbEncryptionKey is a new function every render', async () => {
+    const chatClientWithUser = await createClient();
+    const resolveKey = jest.fn().mockResolvedValue('a-stable-key');
+
+    // An inline arrow is the shape integrators reach for first, so a changing
+    // identity must not restart initialization on every render.
+    const { rerender } = render(
+      <Chat
+        client={chatClientWithUser}
+        enableOfflineSupport
+        getOfflineDbEncryptionKey={() => resolveKey()}
+      />,
+    );
+
+    await waitFor(() => expect(chatClientWithUser.offlineDb).toBeDefined());
+    const initSpy = track(jest.spyOn(chatClientWithUser.offlineDb!, 'init'));
+
+    rerender(
+      <Chat
+        client={chatClientWithUser}
+        enableOfflineSupport
+        getOfflineDbEncryptionKey={() => resolveKey()}
+      />,
+    );
+    rerender(
+      <Chat
+        client={chatClientWithUser}
+        enableOfflineSupport
+        getOfflineDbEncryptionKey={() => resolveKey()}
+      />,
+    );
+
+    await waitFor(() => expect(initSpy).not.toHaveBeenCalled());
+  });
+
+  it.each<[string, () => Promise<string | undefined>, string]>([
+    ['the key cannot be read', () => Promise.resolve(undefined), 'ENCRYPTION_KEY_UNAVAILABLE'],
+    [
+      'the key getter throws',
+      () => Promise.reject(new Error('keychain is locked')),
+      'ENCRYPTION_KEY_UNAVAILABLE',
+    ],
+  ])('throws %s so an error boundary can decide', async (_label, getKey, code) => {
+    const chatClientWithUser = await createClient();
+    track(jest.spyOn(console, 'warn').mockImplementation(() => undefined));
+    track(jest.spyOn(console, 'error').mockImplementation(() => undefined));
+    track(jest.spyOn(console, 'log').mockImplementation(() => undefined));
+    const onCatch = jest.fn();
+
+    const { getByTestId } = render(
+      <Boundary onCatch={onCatch}>
+        <Chat client={chatClientWithUser} enableOfflineSupport getOfflineDbEncryptionKey={getKey}>
+          <View testID='children' />
+        </Chat>
+      </Boundary>,
+    );
+
+    await waitFor(() => expect(getByTestId('boundary')).toBeTruthy());
+    expect(onCatch).toHaveBeenCalledWith(expect.any(SqliteClientError));
+    expect((onCatch.mock.calls[0][0] as SqliteClientError).code).toBe(code);
+    // Never silently downgraded to online-only.
+    expect(() => getByTestId('children')).toThrow();
+  });
+
+  it('throws when the native build has no SQLCipher', async () => {
+    const chatClientWithUser = await createClient();
+    track(jest.spyOn(console, 'error').mockImplementation(() => undefined));
+    track(jest.spyOn(console, 'log').mockImplementation(() => undefined));
+    track(jest.spyOn(sqliteMock, 'isSQLCipher').mockReturnValue(false));
+    const onCatch = jest.fn();
+
+    const { getByTestId } = render(
+      <Boundary onCatch={onCatch}>
+        <Chat
+          client={chatClientWithUser}
+          enableOfflineSupport
+          getOfflineDbEncryptionKey={() => Promise.resolve('a-stable-key')}
+        />
+      </Boundary>,
+    );
+
+    await waitFor(() => expect(getByTestId('boundary')).toBeTruthy());
+    expect((onCatch.mock.calls[0][0] as SqliteClientError).code).toBe('SQLCIPHER_BUILD_MISSING');
+  });
+
+  it('throws OFFLINE_DB_UNREADABLE without deleting the database', async () => {
+    const chatClientWithUser = await createClient();
+    track(jest.spyOn(console, 'warn').mockImplementation(() => undefined));
+    track(jest.spyOn(console, 'error').mockImplementation(() => undefined));
+    track(jest.spyOn(console, 'log').mockImplementation(() => undefined));
+    // Preflight passes, then the first read of the file fails to decrypt.
+    track(
+      jest
+        .spyOn(SqliteClient, 'getUserPragmaVersion')
+        .mockRejectedValue(new Error('Querying for user_version failed: file is not a database')),
+    );
+    const deleteSpy = track(jest.spyOn(SqliteClient, 'deleteDatabase'));
+    const onCatch = jest.fn();
+
+    const { getByTestId } = render(
+      <Boundary onCatch={onCatch}>
+        <Chat
+          client={chatClientWithUser}
+          enableOfflineSupport
+          getOfflineDbEncryptionKey={() => Promise.resolve('a-stable-key')}
+        />
+      </Boundary>,
+    );
+
+    await waitFor(() => expect(getByTestId('boundary')).toBeTruthy());
+    expect((onCatch.mock.calls[0][0] as SqliteClientError).code).toBe('OFFLINE_DB_UNREADABLE');
+    // Wiping is the integrator's decision, made from the boundary.
+    expect(deleteSpy).not.toHaveBeenCalled();
+  });
+
+  it('never attaches an offline DB it cannot open', async () => {
+    const chatClientWithUser = await createClient();
+    track(jest.spyOn(console, 'warn').mockImplementation(() => undefined));
+    track(jest.spyOn(console, 'error').mockImplementation(() => undefined));
+    track(jest.spyOn(console, 'log').mockImplementation(() => undefined));
+    const setOfflineDBApiSpy = track(jest.spyOn(chatClientWithUser, 'setOfflineDBApi'));
+
+    const { getByTestId } = render(
+      <Boundary onCatch={() => undefined}>
+        <Chat
+          client={chatClientWithUser}
+          enableOfflineSupport
+          getOfflineDbEncryptionKey={() => Promise.resolve(undefined)}
+        />
+      </Boundary>,
+    );
+
+    await waitFor(() => expect(getByTestId('boundary')).toBeTruthy());
+
+    // Parts of the client write through `client.offlineDb` without checking that it
+    // initialized - queryChannels upserts into it - so an instance we cannot open
+    // would turn those writes into rejections.
+    expect(setOfflineDBApiSpy).not.toHaveBeenCalled();
+    expect(chatClientWithUser.offlineDb).toBeUndefined();
+  });
+
+  it('renders normally when nothing is wrong with encryption', async () => {
+    const chatClientWithUser = await createClient();
+    const onCatch = jest.fn();
+
+    const { getByTestId } = render(
+      <Boundary onCatch={onCatch}>
+        <Chat
+          client={chatClientWithUser}
+          enableOfflineSupport
+          getOfflineDbEncryptionKey={() => Promise.resolve('a-stable-key')}
+        >
+          <View testID='children' />
+        </Chat>
+      </Boundary>,
+    );
+
+    await waitFor(() => expect(getByTestId('children')).toBeTruthy());
+    expect(onCatch).not.toHaveBeenCalled();
+  });
+});

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;
+    }
+  };
 }