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

package/lib/typescript/store/SqliteClient.d.ts

@@ -1,6 +1,18 @@
 import type { DB } from '@op-engineering/op-sqlite';
 import { Logger } from 'stream-chat';
 import type { PreparedBatchQueries, Scalar } 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 declare class SqliteClientError extends Error {
+    readonly code: SqliteClientErrorCode;
+    constructor(code: SqliteClientErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * SqliteClient takes care of any direct interaction with sqlite.
  * This way usage @op-engineering/op-sqlite package is scoped to a single class/file.
@@ -11,14 +23,63 @@ export declare class SqliteClient {
     static dbLocation: string;
     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;
+    /** Busy/disk/memory failures. Checked first: wiping over these destroys a good db. */
+    private static TRANSIENT_ERROR;
+    /**
+     * 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;
     static getDbVersion: () => number;
     static setDbVersion: (version: number) => number;
+    /**
+     * 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;
+    /**
+     * 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: () => Promise<void>;
+    /**
+     * 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;
     static openDB: () => Promise<void>;
     static closeDB: () => void;
     static executeSqlBatch: (queries: PreparedBatchQueries[]) => Promise<void>;
     static executeSql: (query: string, params?: Scalar[]) => Promise<Record<string, string>[]>;
     static dropTables: () => Promise<void>;
     static deleteDatabase: () => boolean;
+    /**
+     * 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) => boolean;
     static initializeDatabase: () => Promise<boolean>;
     static updateUserPragmaVersion: (version: number) => Promise<void>;
     static getUserPragmaVersion: () => Promise<number>;

package/lib/typescript/store/SqliteClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SqliteClient.d.ts","sourceRoot":"","sources":["../../../src/store/SqliteClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAiB,MAAM,2BAA2B,CAAC;AAkBnE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAKrC,OAAO,KAAK,EAAE,oBAAoB,EAAmB,MAAM,EAAS,MAAM,SAAS,CAAC;AAEpF;;;GAGG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,SAAS,SAAM;IAEtB,MAAM,CAAC,MAAM,SAAW;IACxB,MAAM,CAAC,UAAU,SAAe;IAChC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,SAAS,CAAC;IAE1B,MAAM,CAAC,YAAY,eAAgC;IAEnD,MAAM,CAAC,YAAY,GAAI,SAAS,MAAM,YAAwC;IAE9E,MAAM,CAAC,MAAM,sBAmBX;IAEF,MAAM,CAAC,OAAO,aAaZ;IAEF,MAAM,CAAC,eAAe,GAAU,SAAS,oBAAoB,EAAE,mBA2B7D;IAEF,MAAM,CAAC,UAAU,GAAU,OAAO,MAAM,EAAE,SAAS,MAAM,EAAE,uCAezD;IAEF,MAAM,CAAC,UAAU,sBASf;IAEF,MAAM,CAAC,cAAc,gBAoBnB;IAEF,MAAM,CAAC,kBAAkB,yBAmCvB;IAEF,MAAM,CAAC,uBAAuB,GAAU,SAAS,MAAM,mBAMrD;IAEF,MAAM,CAAC,oBAAoB,wBAezB;IAEF,MAAM,CAAC,OAAO,sBAOZ;CACH"}
+{"version":3,"file":"SqliteClient.d.ts","sourceRoot":"","sources":["../../../src/store/SqliteClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAiB,MAAM,2BAA2B,CAAC;AAkBnE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAKrC,OAAO,KAAK,EAAE,oBAAoB,EAAmB,MAAM,EAAS,MAAM,SAAS,CAAC;AAEpF;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B,yBAAyB,GACzB,4BAA4B,GAC5B,uBAAuB,CAAC;AAE5B,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,IAAI,EAAE,qBAAqB,CAAC;gBAEhC,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQxF;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,SAAS,SAAM;IAEtB,MAAM,CAAC,MAAM,SAAW;IACxB,MAAM,CAAC,UAAU,SAAe;IAChC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,SAAS,CAAC;IAE1B;;;;;;OAMG;IACH,MAAM,CAAC,gBAAgB,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IAEzE,wFAAwF;IACxF,OAAO,CAAC,MAAM,CAAC,cAAc,CAAqB;IAElD,sFAAsF;IACtF,OAAO,CAAC,MAAM,CAAC,eAAe,CACiG;IAE/H;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB,CACsG;IAErI,MAAM,CAAC,YAAY,eAAgC;IAEnD,MAAM,CAAC,YAAY,GAAI,SAAS,MAAM,YAAwC;IAE9E;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW,CAIxB;IAEF;;;;;;;;OAQG;IACH,MAAM,CAAC,mBAAmB,sBASxB;IAEF;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAoDjC;IAEF,MAAM,CAAC,MAAM,sBA8BX;IAEF,MAAM,CAAC,OAAO,aAaZ;IAEF,MAAM,CAAC,eAAe,GAAU,SAAS,oBAAoB,EAAE,mBA2B7D;IAEF,MAAM,CAAC,UAAU,GAAU,OAAO,MAAM,EAAE,SAAS,MAAM,EAAE,uCAezD;IAEF,MAAM,CAAC,UAAU,sBASf;IAEF,MAAM,CAAC,cAAc,gBAoBnB;IAEF;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,GAAI,GAAG,OAAO,aAQtC;IAEF,MAAM,CAAC,kBAAkB,QAAa,OAAO,CAAC,OAAO,CAAC,CAqDpD;IAEF,MAAM,CAAC,uBAAuB,GAAU,SAAS,MAAM,mBAMrD;IAEF,MAAM,CAAC,oBAAoB,wBAezB;IAEF,MAAM,CAAC,OAAO,sBAOZ;CACH"}

package/lib/typescript/test-utils/BetterSqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BetterSqlite.d.ts","sourceRoot":"","sources":["../../../src/test-utils/BetterSqlite.js"],"names":[],"mappings":"AAIA;IAGE,0BAEE;IAEF,2BAEE;IAEF,yCAGE;IAEF,iCAOE;IAEF,yBAAgC,UAAK,wBAKnC;IA7BF,SAAU;CA8BX"}
+{"version":3,"file":"BetterSqlite.d.ts","sourceRoot":"","sources":["../../../src/test-utils/BetterSqlite.js"],"names":[],"mappings":"AAOA;IAGE,0BAEE;IAEF,2BAEE;IAEF,yCAGE;IAEF,iCAOE;IAEF,yBAAgC,UAAK,wBAKnC;IA7BF,SAAU;CA8BX"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stream-chat-react-native-core",
   "description": "The official React Native and Expo components for Stream Chat, a service for building chat applications",
-  "version": "8.13.18",
+  "version": "8.14.0",
   "author": {
     "company": "Stream.io Inc",
     "name": "Stream.io Inc"
@@ -82,7 +82,7 @@
     "path": "0.12.7",
     "react-native-markdown-package": "1.8.2",
     "react-native-url-polyfill": "^2.0.0",
-    "stream-chat": "^9.50.1",
+    "stream-chat": "^9.50.3",
     "use-sync-external-store": "^1.5.0"
   },
   "peerDependencies": {

package/src/components/ChannelList/__tests__/ChannelList.test.js

@@ -67,6 +67,17 @@ const RefreshingProbe = () => {
   return <Text testID='refreshing'>{`${refreshing}`}</Text>;
 };
 
+/**
+ * Probe that captures the context `refreshList` (the public, non-forced pull-to-refresh handler) so a
+ * test can invoke it directly.
+ */
+let capturedRefreshList;
+const RefreshListProbe = () => {
+  const { refreshing, refreshList } = useChannelsContext();
+  capturedRefreshList = refreshList;
+  return <Text testID='refreshing'>{`${refreshing}`}</Text>;
+};
+
 class DeferredPromise {
   constructor() {
     this.promise = new Promise((resolve, reject) => {
@@ -677,12 +688,16 @@ describe('ChannelList', () => {
     });
 
     describe('connection.changed', () => {
-      it('should keep background reconnection refreshes debounced and out of pull-to-refresh UI', async () => {
+      it('should force reconnection refreshes past the pull-to-refresh debounce while keeping them out of the refreshing UI', async () => {
+        // Regression guard: a reconnect is the sole trigger that re-watches channels on the fresh
+        // socket, so it must bypass the 5s pull-to-refresh throttle (`force`). Without the bypass a
+        // second reconnect landing inside the debounce window is dropped and its channels stay
+        // un-watched (frozen last message / unread) until the next reconnect > 5s later.
         useMockedApis(chatClient, [queryChannelsApi([testChannel1])]);
-        const deferredPromise = new DeferredPromise();
-        const dateNowSpy = jest.spyOn(Date, 'now');
-        dateNowSpy.mockReturnValueOnce(0);
-        dateNowSpy.mockReturnValue(6000);
+        const createChannelManagerSpy = jest.spyOn(chatClient, 'createChannelManager');
+        // Freeze the clock at t=0 for the whole mount so `lastRefresh` is seeded to 0 regardless of
+        // how many `Date.now()` calls the render makes.
+        const dateNowSpy = jest.spyOn(Date, 'now').mockReturnValue(0);
 
         render(
           <Chat client={chatClient}>
@@ -690,36 +705,88 @@ describe('ChannelList', () => {
           </Chat>,
         );
 
+        // The probe only renders once the mount query populates the list.
         await waitFor(() => {
           expect(screen.getByTestId('refreshing').children[0]).toBe('false');
         });
 
-        const queryChannelsSpy = jest
-          .spyOn(chatClient, 'queryChannels')
-          .mockImplementation(() => deferredPromise.promise);
+        // Advance the clock 6s past mount so both reconnects observe t=6000.
+        dateNowSpy.mockReturnValue(6000);
 
-        await act(async () => {
-          dispatchConnectionChangedEvent(chatClient, false);
-          dispatchConnectionChangedEvent(chatClient, true);
-          await Promise.resolve();
-        });
+        const channelManager = createChannelManagerSpy.mock.results[0]?.value;
+        // Spy (not replace) so reconnect queries still hydrate through the mocked axios response and
+        // keep the list — and therefore the refreshing probe — mounted.
+        const querySpy = jest.spyOn(chatClient, 'queryChannels');
 
+        // Reconnect #1 at t=6000, i.e. 6s after mount → outside the debounce window.
+        act(() => dispatchConnectionChangedEvent(chatClient, false));
+        act(() => dispatchConnectionChangedEvent(chatClient, true));
+        await waitFor(() => {
+          expect(querySpy).toHaveBeenCalledTimes(1);
+        });
+        // Let query #1 settle so the ChannelManager's in-flight guard (isLoading) clears; otherwise it,
+        // not the debounce, would be what drops the second query.
         await waitFor(() => {
-          expect(queryChannelsSpy).toHaveBeenCalledTimes(1);
+          expect(channelManager.state.getLatestValue().pagination.isLoading).toBe(false);
         });
 
-        await act(async () => {
-          dispatchConnectionChangedEvent(chatClient, true);
-          await Promise.resolve();
+        // Reconnect #2 at t=6000, i.e. 0ms after reconnect #1 → inside the debounce window. It fires a
+        // fresh query only because reconnection refreshes are forced past the throttle.
+        act(() => dispatchConnectionChangedEvent(chatClient, false));
+        act(() => dispatchConnectionChangedEvent(chatClient, true));
+        await waitFor(() => {
+          expect(querySpy).toHaveBeenCalledTimes(2);
         });
 
-        expect(queryChannelsSpy).toHaveBeenCalledTimes(1);
+        // Background reconnection refreshes never surface in the pull-to-refresh UI.
         expect(screen.getByTestId('refreshing').children[0]).toBe('false');
 
+        await waitFor(() => {
+          expect(channelManager.state.getLatestValue().pagination.isLoading).toBe(false);
+        });
+        dateNowSpy.mockRestore();
+      });
+    });
+
+    describe('refreshList (pull-to-refresh)', () => {
+      it('should throttle a non-forced refresh that lands within the retry interval', async () => {
+        // Counterpart to the forced reconnect above: the public `refreshList` is NOT forced, so its
+        // 5s debounce must still hold — a second pull within the window of the last successful refresh
+        // is a no-op and fires no query.
+        useMockedApis(chatClient, [queryChannelsApi([testChannel1])]);
+        const createChannelManagerSpy = jest.spyOn(chatClient, 'createChannelManager');
+        const dateNowSpy = jest.spyOn(Date, 'now').mockReturnValue(0); // mount seeds `lastRefresh` to 0
+
+        render(
+          <Chat client={chatClient}>
+            <ChannelList {...props} List={RefreshListProbe} />
+          </Chat>,
+        );
+
+        await waitFor(() => {
+          expect(screen.getByTestId('refreshing').children[0]).toBe('false');
+        });
+
+        const channelManager = createChannelManagerSpy.mock.results[0]?.value;
+        const querySpy = jest.spyOn(chatClient, 'queryChannels');
+
+        // First pull at t=6000 (6s after mount → outside the window) fires a query.
+        dateNowSpy.mockReturnValue(6000);
+        await act(async () => {
+          await capturedRefreshList?.();
+        });
+        await waitFor(() => {
+          expect(querySpy).toHaveBeenCalledTimes(1);
+        });
+        await waitFor(() => {
+          expect(channelManager.state.getLatestValue().pagination.isLoading).toBe(false);
+        });
+
+        // Second pull at t=6000 (0ms later → inside the window) is throttled: no additional query.
         await act(async () => {
-          deferredPromise.resolve([generateChannel({ id: testChannel1.channel.id })]);
-          await deferredPromise.promise;
+          await capturedRefreshList?.();
         });
+        expect(querySpy).toHaveBeenCalledTimes(1);
 
         dateNowSpy.mockRestore();
       });

package/src/components/ChannelList/hooks/usePaginatedChannels.ts

@@ -130,10 +130,14 @@ export const usePaginatedChannels = ({
     setActiveQueryType(null);
   };
 
-  const refreshList = async ({ isBackground = false }: { isBackground?: boolean } = {}) => {
+  const refreshList = async ({
+    force = false,
+    isBackground = false,
+  }: { force?: boolean; isBackground?: boolean } = {}) => {
     const now = Date.now();
-    // Only allow pull-to-refresh 5 seconds after last successful refresh.
-    if (now - lastRefresh.current < RETRY_INTERVAL_IN_MS && error === undefined) {
+    // Only allow pull-to-refresh 5 seconds after last successful refresh, unless the request
+    // is invoked with force: true.
+    if (!force && now - lastRefresh.current < RETRY_INTERVAL_IN_MS && error === undefined) {
       return;
     }
 
@@ -168,9 +172,10 @@ export const usePaginatedChannels = ({
       'connection.changed',
       async (event) => {
         if (event.online) {
-          // Reconnection refreshes should stay silent, but still share the same debounce
-          // path as pull-to-refresh.
-          await refreshList({ isBackground: true });
+          // Reconnection refreshes stay silent but must NOT be throttled by the
+          // pull-to-refresh debounce. This is the query that rewatches the
+          // channels on the fresh socket.
+          await refreshList({ force: true, isBackground: true });
         }
       },
     );

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