feat: offline db encryption (#3780)

## 🎯 Goal

Let integrators encrypt the offline database at rest. The offline cache
stores channels, messages, members, drafts and reminders, and right now
we write all of it as plaintext `SQLite`.

It's opt-in. Apps that don't pass the new prop behave exactly as they do
today.

One thing to know up front, since it shapes the rest of the PR:
`op-sqlite` accepts an `encryptionKey` on a build without `SQLCipher`
and then ignores it. You get a plaintext database and no error at any
layer. So part of this change is detecting that and refusing to open the
database, instead of passing the key along and assuming it was used.

Accompanying docs PR:
GetStream/docs-content#1521

## 🛠 Implementation details

### API

`Chat` takes one new prop:

```tsx
<Chat client={client} enableOfflineSupport getEncryptionKey={getEncryptionKey}>
```

`getEncryptionKey?: () => Promise<string | undefined>` runs once per
database open, so once per launch and again after a sign-out. Its result
is passed to `SQLCipher` through `op-sqlite`. `SqliteClientError` and
`SqliteClientErrorCode` are exported too.

### We throw instead of recovering

When the database can't be opened with the encryption that was asked
for, `Chat` throws a `SqliteClientError` from render and the
integrator's error boundary handles it. We don't fall back to plaintext,
we don't switch offline support off, and we don't delete anything.

The reason is that all of those recoveries have a security consequence
and there's no default that's right for everyone. Falling back to
plaintext defeats the point of the feature and nothing tells you it
happened. Dropping the cache decides a compliance question for the
integrator. Deleting the file throws away offline actions that are still
queued. We also can't tell "the Keystore isn't unlocked yet, try again
shortly" from "something is wrong here, sign this device out". So we
detect the failure and classify it, and the app decides what to do about
it.

### Scenarios

| Scenario | What it means | What the SDK does | Recommended recovery |
| ------------------------------------------------------- |
------------------------------------------------------------ |
---------------------------------------------- |
------------------------------------------------------------------ |
| No `getEncryptionKey` passed | Encryption not requested | Opens
plaintext, same as today | n/a |
| Key supplied, fresh install | Nothing on disk yet | Creates the
database encrypted with that key | n/a |
| Key supplied, plaintext database already on disk | Integrator is
turning encryption on for an existing install | Throws
`OFFLINE_DB_UNREADABLE` | Delete the database, remount `Chat` |
| Key differs from the one the database was written with | Key rotated,
or read from the wrong place | Throws `OFFLINE_DB_UNREADABLE` | Delete
the database, remount `Chat` |
| `getEncryptionKey` removed, encrypted database on disk | Integrator is
turning encryption off again | Throws `OFFLINE_DB_UNREADABLE` | Delete
the database, remount `Chat` |
| `getEncryptionKey` throws | Key isn't available yet, e.g. Keystore
still locked | Throws `ENCRYPTION_KEY_UNAVAILABLE` | Remount to retry,
e.g. on next app foreground |
| `getEncryptionKey` resolves `undefined` | Same as above | Throws
`ENCRYPTION_KEY_UNAVAILABLE` | Remount to retry, e.g. on next app
foreground |
| Key supplied, native build has no `SQLCipher` | The key would be
ignored and the database left plaintext | Throws
`SQLCIPHER_BUILD_MISSING`, doesn't open | Not fixable at runtime,
remount with `enableOfflineSupport={false}` |
| Database file corrupted | Nothing to do with encryption | Throws
`OFFLINE_DB_UNREADABLE` | Delete the database, remount `Chat` |

Two of those rows need a closer look in review.

`OFFLINE_DB_UNREADABLE` is not gated on `getEncryptionKey` being set,
and that's on purpose, because of the "turning encryption off again"
row. If we only threw it when a key was supplied, an integrator removing
the prop would get a blank screen instead of an error they can recover
from. I hit that on device.

The last row is why the boundary is useful even for apps that never use
encryption. A corrupted database gives you the same code, so anything
using `enableOfflineSupport` can end up there.

### Where the error comes from

`AbstractOfflineDB.init` in the LLC catches whatever `initializeDB`
throws and doesn't re-throw it, so a caller can't find out why
initialisation failed. I left that alone, because changing it would tie
this PR to an LLC release. `OfflineDB` stores the reason on the instance
on the way out instead, and the new hook reads it back once `init` has
settled. No LLC changes needed for this.

- `SqliteClient` resolves the key, opens through `SQLCipher` and maps
failures onto the codes above. It also gets `preflightEncryption()`,
which runs before `setOfflineDBApi`. Without that ordering the client
attaches a database that's already dead, and the unguarded `await
this.offlineDb.upsertChannels(...)` inside `queryChannels` rejects. You
end up on a loading screen that never resolves.
- `useInitializeOfflineDb()` is new and does preflight, attach, init and
raise, with the init options behind an `options` param. It's pulled out
of `Chat`, which loses 72 lines.
- `OfflineDB` records `initializationError` and re-throws, so `init`
still marks the database uninitialised.

## 🎨 UI Changes

## 🧪 Testing

<!-- Explain how this change can be tested (or why it can't be tested)
-->

## ☑️ Checklist

- [x] I have signed the [Stream
CLA](https://docs.google.com/forms/d/e/1FAIpQLScFKsKkAJI7mhCr7K9rEIOpqIDThrWxuvxnwUq2XkHyG154vQ/viewform)
(required)
- [x] PR targets the `develop` branch
- [x] Documentation is updated
- [ ] New code is tested in main example apps, including all possible
scenarios
  - [ ] SampleApp iOS and Android
  - [ ] Expo iOS and Android

Author: isekovanic

examples/SampleApp/App.tsx

@@ -27,6 +27,7 @@ import {
 } from 'stream-chat-react-native';
 
 import { MenuDrawer } from './src/components/MenuDrawer';
+import { OfflineDbBoundary } from './src/components/OfflineDbBoundary';
 import { useSampleAppComponentOverrides } from './src/components/SampleAppComponentOverrides';
 import {
   MessageInputFloatingConfigItem,
@@ -334,20 +335,35 @@ const DrawerNavigatorWrapper: React.FC<{
   chatClient: StreamChat;
   i18nInstance: Streami18n;
 }> = ({ chatClient, i18nInstance }) => {
+  // `attempt` re-mounts <Chat> after the offline database has been deleted;
+  // `offlineSupport` is switched off once there is no usable encryption key.
+  const [attempt, setAttempt] = useState(0);
+  const [offlineSupport, setOfflineSupport] = useState(true);
+
+  // The boundary stops rendering its children once it has caught (see its render), and
+  // nothing else clears that. Keying it on both recovery levers re-mounts it when one is
+  // pulled - without that it would sit on a blank screen forever, having already deleted
+  // the database.
   return (
-    <Chat
-      client={chatClient}
-      enableOfflineSupport
-      isMessageAIGenerated={isMessageAIGenerated}
-      i18nInstance={i18nInstance}
-      useNativeMultipartUpload
+    <OfflineDbBoundary
+      key={`${attempt}-${offlineSupport}`}
+      onGiveUp={() => setOfflineSupport(false)}
+      onRetry={() => setAttempt((value) => value + 1)}
     >
-      <StreamChatProvider>
-        <UserSearchProvider>
-          <DrawerNavigator />
-        </UserSearchProvider>
-      </StreamChatProvider>
-    </Chat>
+      <Chat
+        client={chatClient}
+        enableOfflineSupport={offlineSupport}
+        i18nInstance={i18nInstance}
+        isMessageAIGenerated={isMessageAIGenerated}
+        useNativeMultipartUpload
+      >
+        <StreamChatProvider>
+          <UserSearchProvider>
+            <DrawerNavigator />
+          </UserSearchProvider>
+        </StreamChatProvider>
+      </Chat>
+    </OfflineDbBoundary>
   );
 };
 

examples/SampleApp/ios/Podfile.lock

@@ -298,7 +298,7 @@ PODS:
     - React-utils
     - ReactNativeDependencies
     - Yoga
-  - React-Core-prebuilt (0.86.0):
+  - React-Core-prebuilt (0.86.2):
     - ReactNativeDependencies
   - React-Core/CoreModulesHeaders (0.86.2):
     - hermes-engine
@@ -2857,7 +2857,7 @@ PODS:
   - SDWebImageWebPCoder (0.15.0):
     - libwebp (~> 1.0)
     - SDWebImage/Core (~> 5.17)
-  - stream-chat-react-native (9.7.2):
+  - stream-chat-react-native (9.7.6):
     - hermes-engine
     - RCTRequired
     - RCTTypeSafety
@@ -3291,7 +3291,7 @@ SPEC CHECKSUMS:
   GoogleAppMeasurement: 57270ccc2b77472d7e85c4cbe45972564eff78bb
   GoogleDataTransport: aae35b7ea0c09004c3797d53c8c41f66f219d6a7
   GoogleUtilities: 766ace00c6b10d8148408f329d10c4f051931850
-  hermes-engine: 188393eb43a0cce2dfbf912e6d22c7bb6469957d
+  hermes-engine: 3730f5b467f988fa954ded67cbea8a9ba32d854c
   libavif: 84bbb62fb232c3018d6f1bab79beea87e35de7b7
   libdav1d: 23581a4d8ec811ff171ed5e2e05cd27bad64c39f
   libwebp: 02b23773aedb6ff1fd38cec7a77b81414c6842a8
@@ -3309,7 +3309,7 @@ SPEC CHECKSUMS:
   React: 4b2532a459d15e1adf6c22d3e399e5c85a94220f
   React-callinvoker: 0b8ce4057e02a0bd15cf0532596e8eb8c0392e92
   React-Core: 5af045531a540ba3f65f07de1e3f585ddfb27948
-  React-Core-prebuilt: 13924a267683b3d6fa4bde9c80380becf83a9c5c
+  React-Core-prebuilt: 405cf395d66cf694faf9aed3483a21b5515cec85
   React-CoreModules: 99b194a721de84ccfc1be149a0de52647dc38c0e
   React-cxxreact: b7e8e254074fd8111d147202b391ccf7816946a6
   React-debug: 3281bfefe5ece9a9d8b28bec3f871db229f9d8d8
@@ -3399,7 +3399,7 @@ SPEC CHECKSUMS:
   SDWebImageAVIFCoder: afe194a084e851f70228e4be35ef651df0fc5c57
   SDWebImageSVGCoder: 15a300a97ec1c8ac958f009c02220ac0402e936c
   SDWebImageWebPCoder: 0e06e365080397465cc73a7a9b472d8a3bd0f377
-  stream-chat-react-native: e97f6d3ed0c2828b20610ffc0023ad7f9c90738d
+  stream-chat-react-native: ea3499916019c499ecb745be61e7ecf82f0fd999
   Teleport: c56b30b08bd20d10da1efb0f21c6bc50c269ee6a
   Yoga: 542a30dafe5b0f5f1d9f185ea7b2a3811ac54801
 

examples/SampleApp/src/components/OfflineDbBoundary.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+
+import {
+  SqliteClient,
+  SqliteClientError,
+  type SqliteClientErrorCode,
+} from 'stream-chat-react-native';
+
+/**
+ * `<Chat>` throws a {@link SqliteClientError} from render when it cannot open the
+ * offline database - most often `OFFLINE_DB_UNREADABLE`, meaning the file on disk
+ * cannot be read (corruption, or a database left behind from a different encryption
+ * mode). It never silently continues without the cache; recovery is the application's
+ * decision.
+ *
+ * The recommended recovery, shown here: the contents are a cache, so delete the
+ * database and let it rebuild from the server. The only real loss is actions that were
+ * queued while offline, so a real app may want to confirm with the user first.
+ *
+ * The `onGiveUp` path covers the codes that mean "no usable encryption key"
+ * (`SQLCIPHER_BUILD_MISSING`, `ENCRYPTION_KEY_UNAVAILABLE`). Those only occur when
+ * `<Chat>` is given a `getOfflineDbEncryptionKey` prop, which this sample does not do -
+ * a new database would then be written in plaintext, so running online-only is the safe
+ * response.
+ */
+type BoundaryProps = React.PropsWithChildren<{
+  onGiveUp: () => void;
+  onRetry: () => void;
+}>;
+
+type BoundaryState = { code?: SqliteClientErrorCode };
+
+export class OfflineDbBoundary extends React.Component<BoundaryProps, BoundaryState> {
+  state: BoundaryState = {};
+
+  // Must return state, and render() must stop rendering the failing subtree. Returning
+  // null here would re-render the same children, they would throw again, and React
+  // would give up and unmount the whole app.
+  static getDerivedStateFromError(error: unknown) {
+    if (!(error instanceof SqliteClientError)) {
+      // Not one of ours - re-throw so it reaches whatever boundary owns it.
+      throw error;
+    }
+    return { code: error.code };
+  }
+
+  componentDidCatch(error: unknown) {
+    if (!(error instanceof SqliteClientError)) {
+      return;
+    }
+
+    if (error.code === 'OFFLINE_DB_UNREADABLE') {
+      // The recommended recovery: the contents are a cache, so drop the database and
+      // let it rebuild. Only actions queued while offline are lost.
+      try {
+        SqliteClient.deleteDatabase();
+      } catch (deleteError) {
+        console.warn('[SampleApp] could not delete the offline database', deleteError);
+      }
+      this.props.onRetry();
+      return;
+    }
+
+    // No usable key, so a new database would be plaintext. Run online-only instead.
+    console.warn(`[SampleApp] offline encryption unavailable (${error.code}); going online-only`);
+    this.props.onGiveUp();
+  }
+
+  render() {
+    return this.state.code ? null : this.props.children;
+  }
+}

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) {