🎯 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: https://github.com/GetStream/docs-content/pull/1521

🛠 Implementation details

API

Chat takes one new prop:

<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

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

☑️ Checklist

• I have signed the Stream CLA (required)
• PR targets the develop branch
• Documentation is updated
• New code is tested in main example apps, including all possible scenarios
  • SampleApp iOS and Android
  • Expo iOS and Android