stream-chat-react-native-core 9.7.6 → 9.8.0

package/lib/typescript/components/Chat/Chat.d.ts

@@ -15,6 +15,50 @@ export type ChatProps = Pick<ChatContextValue, 'client'> & Partial<Pick<ChatCont
      * 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>;
     /**
      * Optional positive cap on the number of events a single `/sync` response may
      * contain before the offline sync manager skips replaying those events into

package/lib/typescript/components/Chat/Chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../../../src/components/Chat/Chat.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,iBAAiB,EAAgC,MAAM,OAAO,CAAC;AAW/E,OAAO,EAAE,gBAAgB,EAAgB,MAAM,wCAAwC,CAAC;AAGxF,OAAO,EAAE,WAAW,EAA2B,MAAM,0CAA0C,CAAC;AAChG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AAarE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAM9D,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,GACtD,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,sBAAsB,CAAC,CAAC,GAAG;IACxD;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;OAEG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACpC;;;;;;;;OAQG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;CAC5B,CAAC;AA+JJ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,iBAAiB,CAAC,SAAS,CAAC,sBAIvD,CAAC"}
+{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../../../src/components/Chat/Chat.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,iBAAiB,EAAgC,MAAM,OAAO,CAAC;AAY/E,OAAO,EAAE,gBAAgB,EAAgB,MAAM,wCAAwC,CAAC;AAGxF,OAAO,EAAE,WAAW,EAA2B,MAAM,0CAA0C,CAAC;AAChG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yCAAyC,CAAC;AAYrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAM9D,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,GACtD,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,sBAAsB,CAAC,CAAC,GAAG;IACxD;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;OAEG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,yBAAyB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACpC;;;;;;;;OAQG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;CAC5B,CAAC;AAqJJ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,iBAAiB,CAAC,SAAS,CAAC,sBAIvD,CAAC"}

package/lib/typescript/components/Chat/hooks/useInitializeOfflineDb.d.ts

@@ -0,0 +1,33 @@
+import type { StreamChat } from 'stream-chat';
+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>;
+    /**
+     * Optional positive cap on the number of events a single `/sync` response may
+     * contain before the offline sync manager skips replaying those events into local
+     * storage. `false` opts out entirely.
+     */
+    maxSyncEventsLimit?: number | false;
+};
+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 declare const useInitializeOfflineDb: ({ client, enabled, options, userID, }: UseInitializeOfflineDbParams) => void;
+//# sourceMappingURL=useInitializeOfflineDb.d.ts.map

package/lib/typescript/components/Chat/hooks/useInitializeOfflineDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInitializeOfflineDb.d.ts","sourceRoot":"","sources":["../../../../../src/components/Chat/hooks/useInitializeOfflineDb.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM9C,MAAM,MAAM,0BAA0B,GAAG;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACrD;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GAAI,uCAKpC,4BAA4B,SAuE9B,CAAC"}

package/lib/typescript/index.d.ts

@@ -27,7 +27,7 @@ export { default as ptBRTranslations } from './i18n/pt-br.json';
 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';
 import * as OfflineStoreApis from './store/apis';

package/lib/typescript/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,6IAA6I;AAC7I,OAAO,kBAAkB,CAAC;AAC1B,OAAO,aAAa,CAAC;AAErB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,cAAc,YAAY,CAAC;AAE3B,cAAc,SAAS,CAAC;AAExB,cAAc,eAAe,CAAC;AAE9B,cAAc,eAAe,CAAC;AAE9B,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AAExC,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE3D,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC,OAAO,KAAK,gBAAgB,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,eAAO,MAAM,4BAA4B,qBAA8C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,6IAA6I;AAC7I,OAAO,kBAAkB,CAAC;AAC1B,OAAO,aAAa,CAAC;AAErB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,cAAc,YAAY,CAAC;AAE3B,cAAc,SAAS,CAAC;AAExB,cAAc,eAAe,CAAC;AAE9B,cAAc,eAAe,CAAC;AAE9B,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AACxC,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AAExC,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE3D,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC,OAAO,KAAK,gBAAgB,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,eAAO,MAAM,4BAA4B,qBAA8C,CAAC"}

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

@@ -1,8 +1,14 @@
 import { AbstractOfflineDB, StreamChat } from 'stream-chat';
 import type { DBGetAppSettingsType, DBGetChannelsForQueryType, DBGetChannelsType, DBGetLastSyncedAtType, DBUpsertAppSettingsType, DBUpsertUserSyncStatusType } from 'stream-chat';
+import { SqliteClientError } from './SqliteClient';
 export declare class OfflineDB extends AbstractOfflineDB {
-    constructor({ client, maxSyncEventsLimit, }: {
+    constructor({ client, getEncryptionKey, maxSyncEventsLimit, }: {
         client: StreamChat;
+        /**
+         * Supplies the SQLCipher key the offline database is opened with. See
+         * {@link SqliteClient.getEncryptionKey} for the stability requirement.
+         */
+        getEncryptionKey?: () => Promise<string | undefined>;
         maxSyncEventsLimit?: number | false;
     });
     upsertCidsForQuery: ({ cids, filters, execute, options, sort, }: {
@@ -121,6 +127,15 @@ export declare class OfflineDB extends AbstractOfflineDB {
     }) => Promise<boolean>;
     resetDB: () => Promise<void>;
     executeSqlBatch: (queries: import("./types").PreparedBatchQueries[]) => Promise<void>;
+    /**
+     * 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: () => Promise<boolean>;
 }
 //# sourceMappingURL=OfflineDB.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"OfflineDB.d.ts","sourceRoot":"","sources":["../../../src/store/OfflineDB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EACV,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AAKrB,qBAAa,SAAU,SAAQ,iBAAiB;gBAClC,EACV,MAAM,EACN,kBAAkB,GACnB,EAAE;QACD,MAAM,EAAE,UAAU,CAAC;QACnB,kBAAkB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;KACrC;IAOD,kBAAkB;;eAZV,CAAC;eAET,CAAC;eACa,CAAC;YACA,CAAC;uDAQ4B;IAE5C,cAAc;;eAAK,CAAC;2BAER,CAAC;uDAFuB;IAGpC,oBAAoB,GAAI,mCAAmC,0BAA0B,kDACR;IAG7E,iBAAiB,GAAI,kCAAkC,uBAAuB,kDACL;IAEzE,UAAU;;eA1BgC,CAAC;uDA0Bf;IAE5B,WAAW;;eAlB6D,CAAC;uDAkB3C;IAE9B,QAAQ;;;iBAxBY,CAAC;8DAwBG;IAExB,WAAW;;iBAtCW,CAAC;eACX,CAAC;uDAqCiB;IAE9B,iBAAiB;;eAlCc,CAAC;uDAkCU;IAE1C,WAAW;;;eA9BL,CAAC;uDA8BuB;IAE9B,cAAc;;eApBU,CAAC;uDAoBW;IAEpC,aAAa;;;eAlCqB,CAAC;uDAkCD;IAElC,aAAa;;eA1BS,CAAC;uDA0BW;IAGlC,WAAW,GAAI,kBAAkB,iBAAiB,2EACa;IAG/D,mBAAmB,GAAI,oCAAoC,yBAAyB,kFACF;IAElF,iBAAiB,0BAAwB;IAGzC,eAAe,GAAI,YAAY,qBAAqB,iCACH;IAEjD,cAAc,GAAI,YAAY,oBAAoB,kEACF;IAEhD,YAAY;;eA3C+B,CAAC;YAAuC,CAAC;aAC5E,CAAC;mEA0CoC;IAE7C,cAAc,4EAAsB;IAEpC,iBAAiB,gHAAyB;IAE1C,iBAAiB;;uDAAyB;IAE1C,cAAc;;eAhEX,CAAC;eAC4B,CAAC;uDA+DG;IAEpC,YAAY;;;eAzEe,CAAA;uDAyEK;IAEhC,aAAa;;eA/EJ,CAAC;uDA+EwB;IAElC,wBAAwB;;oBAlFxB,CAAF;eAAmB,CAAC;mDAkFsC;IAExD,gBAAgB;;eA3DgD,CAAC;uDA2DzB;IAExC,iBAAiB;;eApFA,CAAC;uDAoFoB;IAEtC,iBAAiB,6HAAyB;IAE1C,eAAe;iBArFR,CAAC;uDAqF8B;IAEtC,cAAc;;;eAnE6B,CAAC;uDAmER;IAEpC,cAAc;;;eA7ES,CAAC;uDA6EY;IAEpC,aAAa;;2BAAqB;IAElC,OAAO,sBAAwB;IAE/B,eAAe,uEAAgC;IAE/C,YAAY,yBAAmC;CAChD"}
+{"version":3,"file":"OfflineDB.d.ts","sourceRoot":"","sources":["../../../src/store/OfflineDB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EACV,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAgB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEjE,qBAAa,SAAU,SAAQ,iBAAiB;gBAClC,EACV,MAAM,EACN,gBAAgB,EAChB,kBAAkB,GACnB,EAAE;QACD,MAAM,EAAE,UAAU,CAAC;QACnB;;;WAGG;QACH,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;QACrD,kBAAkB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;KACrC;IAWD,kBAAkB;;eAvBb,CAAC;eAED,CAAC;eACF,CAAC;YAEH,CAAH;uDAkB6C;IAE5C,cAAc;;eAfoB,CAAC;2BAC1B,CAAC;uDAc0B;IAGpC,oBAAoB,GAAI,mCAAmC,0BAA0B,kDACR;IAG7E,iBAAiB,GAAI,kCAAkC,uBAAuB,kDACL;IAEzE,UAAU;;eApCa,CAAC;uDAoCI;IAE5B,WAAW;;eA7BW,CAAC;uDA6BO;IAE9B,QAAQ;;;iBAlCL,CAAC;8DAkCoB;IAExB,WAAW;;iBAhDW,CAAC;eACX,CAAC;uDA+CiB;IAE9B,iBAAiB;;eA5CL,CAAC;uDA4C6B;IAE1C,WAAW;;;eA1CS,CAAC;uDA0CS;IAE9B,cAAc;;eApCO,CAAC;uDAoCc;IAEpC,aAAa;;;eA5CI,CAAC;uDA4CgB;IAElC,aAAa;;eAzCwB,CAAC;uDAyCJ;IAGlC,WAAW,GAAI,kBAAkB,iBAAiB,2EACa;IAG/D,mBAAmB,GAAI,oCAAoC,yBAAyB,kFACF;IAElF,iBAAiB,0BAAwB;IAGzC,eAAe,GAAI,YAAY,qBAAqB,iCACH;IAEjD,cAAc,GAAI,YAAY,oBAAoB,kEACF;IAEhD,YAAY;;eA1DZ,CAAA;YAGM,CAAC;aAAuB,CAAC;mEAuDc;IAE7C,cAAc,4EAAsB;IAEpC,iBAAiB,gHAAyB;IAE1C,iBAAiB;;uDAAyB;IAE1C,cAAc;;eA5EC,CAAC;eAGD,CAAC;uDAyEoB;IAEpC,YAAY;;;eAnFc,CAAC;uDAmFK;IAEhC,aAAa;;eAzFJ,CAAC;uDAyFwB;IAElC,wBAAwB;;oBA5FxB,CAAF;eAAmB,CAAC;mDA4FsC;IAExD,gBAAgB;;eAxEZ,CAAF;uDAwEsC;IAExC,iBAAiB;;eA9FA,CAAC;uDA8FoB;IAEtC,iBAAiB,6HAAyB;IAE1C,eAAe;iBA/FR,CAAC;uDA+F8B;IAEtC,cAAc;;;eAlFd,CAAA;uDAkFoC;IAEpC,cAAc;;;eAzFkC,CAAC;uDAyFb;IAEpC,aAAa;;2BAAqB;IAElC,OAAO,sBAAwB;IAE/B,eAAe,uEAAgC;IAE/C;;;;;;;OAOG;IACH,mBAAmB,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAEnD,YAAY,yBAWV;CACH"}

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

@@ -1,6 +1,18 @@
 import type { _InternalDB } 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: _InternalDB | 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,WAAW,EAAiB,MAAM,2BAA2B,CAAC;AAkB5E,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,WAAW,GAAG,SAAS,CAAC;IAEnC,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,WAAW,EAAiB,MAAM,2BAA2B,CAAC;AAkB5E,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,WAAW,GAAG,SAAS,CAAC;IAEnC;;;;;;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/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": "9.7.6",
+  "version": "9.8.0",
   "author": {
     "company": "Stream.io Inc",
     "name": "Stream.io Inc"

package/src/components/Chat/Chat.tsx

@@ -6,6 +6,7 @@ import { Channel, OfflineDBState } from 'stream-chat';
 import { useClientMutedUsers } from './hooks';
 import { useAppSettings } from './hooks/useAppSettings';
 import { useCreateChatContext } from './hooks/useCreateChatContext';
+import { useInitializeOfflineDb } from './hooks/useInitializeOfflineDb';
 import { useIsOnline } from './hooks/useIsOnline';
 
 import { ChannelsStateProvider } from '../../contexts/channelsStateContext/ChannelsStateContext';
@@ -24,7 +25,6 @@ import init from '../../init';
 
 import { NativeHandlers } from '../../native';
 import { DEFAULT_MAX_SYNC_EVENTS_LIMIT } from '../../store/constants';
-import { OfflineDB } from '../../store/OfflineDB';
 
 import type { Streami18n } from '../../utils/i18n/Streami18n';
 import { installNativeMultipartAdapter } from '../../utils/installNativeMultipartAdapter';
@@ -45,6 +45,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>;
     /**
      * Optional positive cap on the number of events a single `/sync` response may
      * contain before the offline sync manager skips replaying those events into
@@ -172,6 +216,7 @@ const ChatWithContext = (props: PropsWithChildren<ChatProps>) => {
     client,
     closeConnectionOnBackground = true,
     enableOfflineSupport = false,
+    getOfflineDbEncryptionKey,
     i18nInstance,
     isMessageAIGenerated,
     maxSyncEventsLimit = DEFAULT_MAX_SYNC_EVENTS_LIMIT,
@@ -241,23 +286,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, maxSyncEventsLimit }));
-      }
-
-      if (client.offlineDb) {
-        await client.offlineDb.init(userID);
-      }
-    };
-
-    initializeDatabase();
-  }, [userID, enableOfflineSupport, client, maxSyncEventsLimit]);
+  useInitializeOfflineDb({
+    client,
+    enabled: enableOfflineSupport,
+    options: { getEncryptionKey: getOfflineDbEncryptionKey, maxSyncEventsLimit },
+    userID,
+  });
 
   useEffect(() => {
     if (!client) {

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

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { PropsWithChildren } from 'react';
 import { View } from 'react-native';
 
 import NetInfo from '@react-native-community/netinfo';
@@ -9,10 +9,12 @@ import { useChatContext } from '../../../contexts/chatContext/ChatContext';
 
 import type { TranslationContextValue } from '../../../contexts/translationContext/TranslationContext';
 import { useTranslationContext } from '../../../contexts/translationContext/TranslationContext';
+import { sqliteMock } from '../../../mock-builders/DB/mock';
 import dispatchConnectionChangedEvent from '../../../mock-builders/event/connectionChanged';
 import dispatchConnectionRecoveredEvent from '../../../mock-builders/event/connectionRecovered';
 import { getTestClient, getTestClientWithUser, setUser } from '../../../mock-builders/mock';
 import { DEFAULT_MAX_SYNC_EVENTS_LIMIT } from '../../../store/constants';
+import { SqliteClient, SqliteClientError } from '../../../store/SqliteClient';
 import { Streami18n } from '../../../utils/i18n/Streami18n';
 import { Chat } from '../Chat';
 
@@ -368,3 +370,242 @@ describe('TranslationContext', () => {
     expect(chatClientWithUser.offlineDb!.syncManager.syncMaxEventCount).toBeUndefined();
   });
 });
+
+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();
+  });
+});