chore: update version number to 0.1.38

App.tsx

@@ -15,7 +15,7 @@ import {
   getInitialNotificationTap,
   getStoredRelayBaseUrl,
   setupPushNotifications,
-  teardownPushNotifications,
+  teardownPushNotificationsForAccount,
   type NotificationTapPayload,
 } from './src/lib/push-notifications';
 import type { MainTabsParamList, RootStackParamList } from './src/navigation/types';
@@ -36,11 +36,15 @@ import { useAuthStore } from './src/stores/auth-store';
 import { useCalendarStore } from './src/stores/calendar-store';
 import { useContactsStore } from './src/stores/contacts-store';
 import { useEmailStore } from './src/stores/email-store';
+import { useHasCalendar, useHasContacts, useHasFiles } from './src/lib/capabilities';
 import { useSettingsStore } from './src/stores/settings-store';
 import { useLocaleStore } from './src/stores/locale-store';
 import { useNetworkStore } from './src/stores/network-store';
 import { useUpdatesStore } from './src/stores/updates-store';
 import { UpdateBanner } from './src/components/UpdateBanner';
+import { OfflineCacheBanner } from './src/components/OfflineCacheBanner';
+import { useOfflineCacheStore } from './src/stores/offline-cache-store';
+import { runOfflineSync } from './src/lib/offline-sync';
 import { spacing, typography, type ThemePalette } from './src/theme/tokens';
 import { useColors } from './src/theme/colors';
 
@@ -48,8 +52,21 @@ const Stack = createNativeStackNavigator<RootStackParamList>();
 const Tab = createBottomTabNavigator<MainTabsParamList>();
 const navigationRef = createNavigationContainerRef<RootStackParamList>();
 
-function navigateToNotificationTap(payload: NotificationTapPayload): void {
+async function navigateToNotificationTap(payload: NotificationTapPayload): Promise<void> {
   if (!navigationRef.isReady()) return;
+
+  // The notification carries the account it was generated for. If the user
+  // has since switched to a different account (or had a different one active
+  // when the notification arrived), opening EmailThread under the active
+  // account would fetch the email from the wrong server and fail.
+  const auth = useAuthStore.getState();
+  if (payload.accountId && payload.accountId !== auth.activeAccountId) {
+    const account = useAccountStore.getState().getAccountById(payload.accountId);
+    if (!account) return; // account was logged out — nothing safe to open.
+    await auth.switchAccount(payload.accountId);
+    if (useAuthStore.getState().activeAccountId !== payload.accountId) return;
+  }
+
   navigationRef.navigate('EmailThread', {
     emailId: payload.emailId,
     threadId: payload.threadId,
@@ -72,10 +89,15 @@ function MainTabsNavigator({ navigation }: NativeStackScreenProps<RootStackParam
   const mailboxes = useEmailStore((state) => state.mailboxes);
   const logout = useAuthStore((state) => state.logout);
   const inboxUnreadCount = mailboxes.find((mailbox) => mailbox.role === 'inbox')?.unreadEmails ?? 0;
+  const hasCalendar = useHasCalendar();
+  const hasContacts = useHasContacts();
+  const hasFiles = useHasFiles();
+  const disabledTabStyle = { opacity: 0.4 } as const;
 
   return (
     <View style={{ flex: 1, backgroundColor: c.background }}>
       <UpdateBanner />
+      <OfflineCacheBanner />
     <Tab.Navigator
       screenOptions={{
         headerShown: false,
@@ -132,6 +154,13 @@ function MainTabsNavigator({ navigation }: NativeStackScreenProps<RootStackParam
         component={CalendarScreen}
         options={{
           tabBarIcon: ({ color, size }) => <Calendar size={size} color={color} />,
+          tabBarItemStyle: hasCalendar ? undefined : disabledTabStyle,
+          tabBarAccessibilityLabel: hasCalendar ? 'Calendar' : 'Calendar (unavailable)',
+        }}
+        listeners={{
+          tabPress: (e) => {
+            if (!hasCalendar) e.preventDefault();
+          },
         }}
       />
       <Tab.Screen
@@ -139,6 +168,13 @@ function MainTabsNavigator({ navigation }: NativeStackScreenProps<RootStackParam
         component={ContactsScreen}
         options={{
           tabBarIcon: ({ color, size }) => <BookUser size={size} color={color} />,
+          tabBarItemStyle: hasContacts ? undefined : disabledTabStyle,
+          tabBarAccessibilityLabel: hasContacts ? 'Contacts' : 'Contacts (unavailable)',
+        }}
+        listeners={{
+          tabPress: (e) => {
+            if (!hasContacts) e.preventDefault();
+          },
         }}
       />
       <Tab.Screen
@@ -146,6 +182,13 @@ function MainTabsNavigator({ navigation }: NativeStackScreenProps<RootStackParam
         component={FilesScreen}
         options={{
           tabBarIcon: ({ color, size }) => <HardDrive size={size} color={color} />,
+          tabBarItemStyle: hasFiles ? undefined : disabledTabStyle,
+          tabBarAccessibilityLabel: hasFiles ? 'Files' : 'Files (unavailable)',
+        }}
+        listeners={{
+          tabPress: (e) => {
+            if (!hasFiles) e.preventDefault();
+          },
         }}
       />
       <Tab.Screen
@@ -193,6 +236,18 @@ export default function App() {
     return useNetworkStore.getState().init();
   }, []);
 
+  // When the network flips back on while we're authenticated-but-offline
+  // (no live JMAP session), retry the session so the user lands back on
+  // live data without needing to relaunch.
+  React.useEffect(() => {
+    if (!isAuthenticated) return;
+    return useNetworkStore.subscribe((state, prev) => {
+      if (state.online && !prev.online && !useAuthStore.getState().session) {
+        void useAuthStore.getState().retrySession();
+      }
+    });
+  }, [isAuthenticated]);
+
   React.useEffect(() => {
     let cancelled = false;
     void (async () => {
@@ -206,6 +261,24 @@ export default function App() {
     return () => { cancelled = true; };
   }, []);
 
+  // Offline mail cache: hydrate the cache index on launch, and kick off a
+  // background sync once we have a live JMAP session and the user has the
+  // feature enabled. Re-runs whenever the user changes the days window.
+  const offlineCacheEnabled = useSettingsStore((s) => s.offlineCacheEnabled);
+  const offlineCacheDays = useSettingsStore((s) => s.offlineCacheDays);
+  const haveLiveSession = useAuthStore((s) => s.session != null);
+  React.useEffect(() => {
+    void useOfflineCacheStore.getState().hydrate();
+  }, []);
+  React.useEffect(() => {
+    if (!offlineCacheEnabled || !haveLiveSession) return;
+    // Slight delay so cold start doesn't compete with the inbox load.
+    const t = setTimeout(() => {
+      void runOfflineSync({ days: offlineCacheDays });
+    }, 2000);
+    return () => clearTimeout(t);
+  }, [offlineCacheEnabled, offlineCacheDays, haveLiveSession]);
+
   // Listen for FCM messages so the app can refresh state even when woken
   // from the background - the FirebaseMessagingService also posts the system
   // notification so the user sees it regardless of RN runtime state.
@@ -227,11 +300,11 @@ export default function App() {
     void (async () => {
       const initial = await getInitialNotificationTap();
       if (cancelled || !initial) return;
-      navigateToNotificationTap(initial);
+      await navigateToNotificationTap(initial);
     })();
 
     const unsubscribe = addNotificationTapListener((payload) => {
-      navigateToNotificationTap(payload);
+      void navigateToNotificationTap(payload);
     });
 
     return () => {
@@ -242,18 +315,24 @@ export default function App() {
 
   // Re-register the device with the configured relay once authenticated,
   // and whenever the FCM token rotates. Honours the user's notification
-  // preference - flipping it off tears down the active subscription so the
-  // FirebaseMessagingService stops receiving pings for this device.
+  // preference - flipping it off tears down THIS account's subscription so
+  // notifications stop arriving for it. Other logged-in accounts keep their
+  // setups intact.
   const emailNotificationsEnabled = useSettingsStore(
     (s) => s.emailNotificationsEnabled,
   );
+  const activeAccountId = useAuthStore((s) => s.activeAccountId);
   React.useEffect(() => {
     if (!isAuthenticated || !client) return;
 
     let cancelled = false;
     const doSetup = async () => {
       if (!emailNotificationsEnabled) {
-        await teardownPushNotifications().catch(() => undefined);
+        if (activeAccountId) {
+          await teardownPushNotificationsForAccount(activeAccountId).catch(
+            () => undefined,
+          );
+        }
         return;
       }
       const relayBaseUrl = await getStoredRelayBaseUrl();
@@ -281,7 +360,7 @@ export default function App() {
       cancelled = true;
       unsubscribe();
     };
-  }, [client, isAuthenticated, emailNotificationsEnabled]);
+  }, [client, isAuthenticated, emailNotificationsEnabled, activeAccountId]);
 
   React.useEffect(() => {
     if (!isAuthenticated || !client) {

VERSION

@@ -1 +1 @@
-0.1.19
+0.1.38

android/app/src/main/AndroidManifest.xml

@@ -2,11 +2,9 @@
   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
   <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES"/>
-  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
-  <uses-permission android:name="android.permission.RECORD_AUDIO"/>
-  <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
+  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32"/>
+  <uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
   <uses-permission android:name="android.permission.VIBRATE"/>
-  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
   <queries>
     <intent>
       <action android:name="android.intent.action.VIEW"/>

android/app/src/main/java/com/anonymous/bulwarkmobile/BulwarkClientCertModule.kt

@@ -0,0 +1,286 @@
+package com.anonymous.bulwarkmobile
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.security.KeyChain
+import android.security.KeyChainAliasCallback
+import android.util.Base64
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+import java.io.ByteArrayOutputStream
+import java.net.HttpURLConnection
+import java.net.Socket
+import java.net.URL
+import java.security.Principal
+import java.security.PrivateKey
+import java.security.cert.X509Certificate
+import javax.net.ssl.HttpsURLConnection
+import javax.net.ssl.SSLContext
+import javax.net.ssl.SSLEngine
+import javax.net.ssl.SSLSocketFactory
+import javax.net.ssl.TrustManager
+import javax.net.ssl.TrustManagerFactory
+import javax.net.ssl.X509ExtendedKeyManager
+import javax.net.ssl.X509TrustManager
+import kotlin.concurrent.thread
+
+/**
+ * Bridges Android's KeyChain client-certificate machinery into JS so the
+ * mobile app can authenticate to a reverse proxy that asks for mTLS.
+ *
+ * Two surfaces:
+ *   1. `pickAlias` / `getAlias` / `clearAlias` — UI flow that lets the user
+ *      pick a cert installed in Android's system credential store. The
+ *      selected alias is persisted in SharedPreferences so the choice
+ *      survives app restarts.
+ *   2. `fetchSecure` — a fetch shim built on `HttpsURLConnection` that
+ *      injects the picked cert into the TLS handshake. JS-side `fetch`
+ *      can't present a client cert because RN's bundled OkHttp client
+ *      doesn't expose its KeyManager hook to userland; this method is
+ *      the workaround.
+ */
+class BulwarkClientCertModule(reactContext: ReactApplicationContext)
+    : ReactContextBaseJavaModule(reactContext) {
+
+    private val prefs: SharedPreferences =
+        reactContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+
+    @Volatile private var cachedAlias: String? = prefs.getString(PREF_ALIAS, null)
+    @Volatile private var cachedFactory: SSLSocketFactory? = null
+    @Volatile private var cachedFactoryForAlias: String? = null
+
+    override fun getName(): String = MODULE_NAME
+
+    // ── alias management ────────────────────────────────────────
+
+    @ReactMethod
+    fun getAlias(promise: Promise) {
+        promise.resolve(cachedAlias)
+    }
+
+    @ReactMethod
+    fun clearAlias(promise: Promise) {
+        prefs.edit().remove(PREF_ALIAS).apply()
+        cachedAlias = null
+        invalidateFactory()
+        promise.resolve(null)
+    }
+
+    /**
+     * Show the system "Choose a certificate" picker. Resolves with the
+     * selected alias, or `null` when the user dismisses the picker.
+     */
+    @ReactMethod
+    fun pickAlias(host: String?, promise: Promise) {
+        // ReactContextBaseJavaModule no longer exposes a Kotlin synthetic
+        // `currentActivity` property in RN 0.80+ (compiles as an unresolved
+        // reference). The explicit Java-style getter on the application
+        // context is the supported call site.
+        val activity: android.app.Activity? = reactApplicationContext.getCurrentActivity()
+        if (activity == null) {
+            promise.reject("no_activity", "No current activity to host the cert picker")
+            return
+        }
+        val callback = KeyChainAliasCallback { alias ->
+            // Callback runs off the main thread; persist + resolve directly.
+            if (alias.isNullOrBlank()) {
+                promise.resolve(null)
+                return@KeyChainAliasCallback
+            }
+            prefs.edit().putString(PREF_ALIAS, alias).apply()
+            cachedAlias = alias
+            invalidateFactory()
+            promise.resolve(alias)
+        }
+        try {
+            KeyChain.choosePrivateKeyAlias(
+                activity,
+                callback,
+                /* keyTypes */ arrayOf("RSA", "EC"),
+                /* issuers */ null,
+                /* host */ host,
+                /* port */ -1,
+                /* alias */ cachedAlias,
+            )
+        } catch (e: Exception) {
+            promise.reject("pick_failed", e.message, e)
+        }
+    }
+
+    // ── secure fetch ────────────────────────────────────────────
+
+    /**
+     * Perform an HTTP request that presents the persisted client cert (if
+     * any) during the TLS handshake.
+     *
+     * @param request {url, method, headers: {k:v}, bodyBase64: string|null, timeoutMs: number}
+     *
+     * Resolves with `{status, statusText, headers, bodyBase64}` so JS can
+     * reconstruct a standard `Response`-like object.
+     */
+    @ReactMethod
+    fun fetchSecure(request: ReadableMap, promise: Promise) {
+        val url = request.getString("url")
+        if (url.isNullOrBlank()) {
+            promise.reject("bad_args", "url is required")
+            return
+        }
+        val method = (request.getString("method") ?: "GET").uppercase()
+        val timeoutMs = if (request.hasKey("timeoutMs")) request.getInt("timeoutMs") else 30_000
+        val headersMap = request.getMap("headers")
+        val bodyBase64 = request.getString("bodyBase64")
+        val bodyBytes = bodyBase64?.let { Base64.decode(it, Base64.NO_WRAP) }
+
+        thread(name = "BulwarkClientCert.fetch") {
+            try {
+                val conn = (URL(url).openConnection() as HttpURLConnection).apply {
+                    connectTimeout = timeoutMs
+                    readTimeout = timeoutMs
+                    requestMethod = method
+                    instanceFollowRedirects = true
+                    if (bodyBytes != null) {
+                        doOutput = true
+                        setFixedLengthStreamingMode(bodyBytes.size)
+                    }
+                }
+                if (conn is HttpsURLConnection && cachedAlias != null) {
+                    conn.sslSocketFactory = buildOrReuseSocketFactory()
+                }
+                headersMap?.let { h ->
+                    val it = h.keySetIterator()
+                    while (it.hasNextKey()) {
+                        val k = it.nextKey()
+                        val v = h.getString(k)
+                        if (v != null) conn.setRequestProperty(k, v)
+                    }
+                }
+                conn.connect()
+                if (bodyBytes != null) {
+                    conn.outputStream.use { out -> out.write(bodyBytes) }
+                }
+
+                val status = conn.responseCode
+                val statusText = conn.responseMessage ?: ""
+                val responseStream = try {
+                    conn.inputStream
+                } catch (_: Exception) {
+                    conn.errorStream
+                }
+                val responseBytes = if (responseStream != null) {
+                    val buf = ByteArrayOutputStream()
+                    responseStream.copyTo(buf)
+                    responseStream.close()
+                    buf.toByteArray()
+                } else {
+                    ByteArray(0)
+                }
+
+                val out = Arguments.createMap()
+                out.putInt("status", status)
+                out.putString("statusText", statusText)
+                val headers = Arguments.createMap()
+                // headerFields is a `Map<String?, List<String>>`; the null
+                // key is the HTTP status line, which we don't need to copy.
+                for ((name, values) in conn.headerFields) {
+                    if (name == null || values == null) continue
+                    headers.putString(name, values.joinToString(", "))
+                }
+                out.putMap("headers", headers)
+                out.putString("bodyBase64", Base64.encodeToString(responseBytes, Base64.NO_WRAP))
+                conn.disconnect()
+                promise.resolve(out)
+            } catch (e: Exception) {
+                promise.reject("fetch_failed", e.message ?: e.javaClass.simpleName, e)
+            }
+        }
+    }
+
+    // ── internals ───────────────────────────────────────────────
+
+    private fun invalidateFactory() {
+        cachedFactory = null
+        cachedFactoryForAlias = null
+    }
+
+    private fun buildOrReuseSocketFactory(): SSLSocketFactory {
+        val alias = cachedAlias ?: throw IllegalStateException("No client-cert alias selected")
+        val existing = cachedFactory
+        if (existing != null && cachedFactoryForAlias == alias) return existing
+
+        val ctx = reactApplicationContext
+        val km = KeyChainKeyManager(ctx, alias)
+        val tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm())
+        tmf.init(null as java.security.KeyStore?)
+        val trustManagers = tmf.trustManagers
+        val tm = trustManagers.firstOrNull { it is X509TrustManager } as X509TrustManager?
+            ?: throw IllegalStateException("No X509TrustManager available")
+        val sslContext = SSLContext.getInstance("TLS")
+        sslContext.init(arrayOf(km), arrayOf<TrustManager>(tm), null)
+        val factory = sslContext.socketFactory
+        cachedFactory = factory
+        cachedFactoryForAlias = alias
+        return factory
+    }
+
+    /**
+     * X509ExtendedKeyManager that always returns the same KeyChain alias.
+     * KeyChain.getPrivateKey / getCertificateChain are blocking; we call
+     * them lazily during the TLS handshake, which is fine since the
+     * fetch already runs off-main-thread.
+     */
+    private class KeyChainKeyManager(
+        private val context: Context,
+        private val alias: String,
+    ) : X509ExtendedKeyManager() {
+
+        override fun chooseClientAlias(
+            keyTypes: Array<out String>?,
+            issuers: Array<out Principal>?,
+            socket: Socket?,
+        ): String = alias
+
+        override fun chooseEngineClientAlias(
+            keyType: Array<out String>?,
+            issuers: Array<out Principal>?,
+            engine: SSLEngine?,
+        ): String = alias
+
+        override fun getCertificateChain(alias: String?): Array<X509Certificate>? {
+            return try {
+                KeyChain.getCertificateChain(context, this.alias)
+            } catch (_: Exception) {
+                null
+            }
+        }
+
+        override fun getPrivateKey(alias: String?): PrivateKey? {
+            return try {
+                KeyChain.getPrivateKey(context, this.alias)
+            } catch (_: Exception) {
+                null
+            }
+        }
+
+        override fun getClientAliases(keyType: String?, issuers: Array<out Principal>?): Array<String> =
+            arrayOf(alias)
+
+        override fun getServerAliases(keyType: String?, issuers: Array<out Principal>?): Array<String> =
+            emptyArray()
+
+        override fun chooseServerAlias(
+            keyType: String?,
+            issuers: Array<out Principal>?,
+            socket: Socket?,
+        ): String? = null
+    }
+
+    companion object {
+        const val MODULE_NAME = "BulwarkClientCert"
+        private const val PREFS_NAME = "bulwark_client_cert"
+        private const val PREF_ALIAS = "alias"
+    }
+}

android/app/src/main/java/com/anonymous/bulwarkmobile/BulwarkFcmModule.kt

@@ -19,6 +19,7 @@ import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.DeviceEventManagerModule.RCTDeviceEventEmitter
 import com.google.firebase.messaging.FirebaseMessaging
+import java.io.ByteArrayOutputStream
 import java.net.HttpURLConnection
 import java.net.URL
 import kotlin.concurrent.thread
@@ -64,6 +65,7 @@ class BulwarkFcmModule(reactContext: ReactApplicationContext)
         val emailId = options.getString("emailId")
         val threadId = options.getString("threadId")
         val subject = options.takeIf { it.hasKey("subject") }?.getString("subject")
+        val accountId = options.takeIf { it.hasKey("accountId") }?.getString("accountId")
 
         // Bitmap fetch + draw off the bridge thread so the caller doesn't
         // block waiting for the favicon request.
@@ -72,7 +74,7 @@ class BulwarkFcmModule(reactContext: ReactApplicationContext)
                 ?: makeLetterAvatar(initials, bgColorHex)
             postNotification(
                 notificationId, title, body, largeIcon, bgColorHex,
-                emailId, threadId, subject,
+                emailId, threadId, subject, accountId,
             )
             promise.resolve(null)
         }
@@ -93,6 +95,7 @@ class BulwarkFcmModule(reactContext: ReactApplicationContext)
         emailId: String?,
         threadId: String?,
         subject: String?,
+        accountId: String?,
     ) {
         val ctx = reactApplicationContext
         val intent = Intent(ctx, MainActivity::class.java).apply {
@@ -100,6 +103,7 @@ class BulwarkFcmModule(reactContext: ReactApplicationContext)
             if (emailId != null) putExtra(NotificationTapStore.EXTRA_EMAIL_ID, emailId)
             if (threadId != null) putExtra(NotificationTapStore.EXTRA_THREAD_ID, threadId)
             if (subject != null) putExtra(NotificationTapStore.EXTRA_SUBJECT, subject)
+            if (accountId != null) putExtra(NotificationTapStore.EXTRA_ACCOUNT_ID, accountId)
         }
         val pending = PendingIntent.getActivity(
             ctx,
@@ -148,7 +152,36 @@ class BulwarkFcmModule(reactContext: ReactApplicationContext)
         conn.readTimeout = 3000
         conn.instanceFollowRedirects = true
         conn.setRequestProperty("User-Agent", "bulwark-mobile")
-        conn.inputStream.use { BitmapFactory.decodeStream(it) }
+        // Cap the response to MAX_FAVICON_BYTES so a hostile / misconfigured
+        // server can't OOM the headless task with a multi-megabyte image.
+        // We also sample down to ~256x256 since it'll only render at 192px.
+        val stream = conn.inputStream
+        val bytes = stream.use { input ->
+            val limit = MAX_FAVICON_BYTES
+            val buf = ByteArrayOutputStream()
+            val chunk = ByteArray(8 * 1024)
+            var total = 0
+            while (true) {
+                val n = input.read(chunk)
+                if (n <= 0) break
+                total += n
+                if (total > limit) return@use null
+                buf.write(chunk, 0, n)
+            }
+            buf.toByteArray()
+        } ?: return null
+        val opts = BitmapFactory.Options().apply {
+            inJustDecodeBounds = true
+        }
+        BitmapFactory.decodeByteArray(bytes, 0, bytes.size, opts)
+        var sample = 1
+        while ((opts.outWidth / sample) > 384 || (opts.outHeight / sample) > 384) {
+            sample *= 2
+        }
+        val decodeOpts = BitmapFactory.Options().apply {
+            inSampleSize = sample
+        }
+        BitmapFactory.decodeByteArray(bytes, 0, bytes.size, decodeOpts)
     } catch (_: Exception) {
         null
     }
@@ -167,6 +200,9 @@ class BulwarkFcmModule(reactContext: ReactApplicationContext)
     fun removeListeners(count: Int) {}
 
     companion object {
+        // 1 MiB is plenty for a favicon; anything bigger is a sign of trouble.
+        private const val MAX_FAVICON_BYTES = 1 * 1024 * 1024
+
         @Volatile private var currentInstance: BulwarkFcmModule? = null
 
         fun emit(eventName: String, params: WritableMap?) {

android/app/src/main/java/com/anonymous/bulwarkmobile/BulwarkFcmPackage.kt

@@ -7,7 +7,10 @@ import com.facebook.react.uimanager.ViewManager
 
 class BulwarkFcmPackage : ReactPackage {
     override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
-        listOf(BulwarkFcmModule(reactContext))
+        listOf(
+            BulwarkFcmModule(reactContext),
+            BulwarkClientCertModule(reactContext),
+        )
 
     override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
         emptyList()

android/app/src/main/java/com/anonymous/bulwarkmobile/NotificationTapStore.kt

@@ -17,17 +17,36 @@ object NotificationTapStore {
         return value
     }
 
+    // The activity is exported (required by the LAUNCHER intent filter), so
+    // any third-party app on the device can craft a starting intent that
+    // includes these extras. Reject anything that doesn't look like the IDs
+    // our notification builder writes — preventing other apps from
+    // navigating us to a forged email/thread.
+    private val ID_PATTERN = Regex("^[A-Za-z0-9_-]{1,128}$")
+    // accountId is `username@host` (see generateAccountId), so it needs `.`,
+    // `@`, `+` etc. — cap length and restrict charset to what that helper can
+    // emit. accountId is optional: notifications created before this field
+    // existed still navigate (using the active account as a fallback).
+    private val ACCOUNT_ID_PATTERN = Regex("^[A-Za-z0-9._+@-]{1,256}$")
+
     fun captureFromIntent(intent: Intent?): TapPayload? {
         val extras = intent?.extras ?: return null
-        val emailId = extras.getString(EXTRA_EMAIL_ID) ?: return null
-        val threadId = extras.getString(EXTRA_THREAD_ID) ?: return null
-        val subject = extras.getString(EXTRA_SUBJECT)
-        val payload = TapPayload(emailId, threadId, subject)
+        val emailId = extras.getString(EXTRA_EMAIL_ID)?.takeIf { ID_PATTERN.matches(it) }
+            ?: return null
+        val threadId = extras.getString(EXTRA_THREAD_ID)?.takeIf { ID_PATTERN.matches(it) }
+            ?: return null
+        // Subject is human-readable text and may legitimately contain anything;
+        // cap its length so a hostile launcher can't ship a 1MB string into
+        // the navigation payload.
+        val subject = extras.getString(EXTRA_SUBJECT)?.take(512)
+        val accountId = extras.getString(EXTRA_ACCOUNT_ID)?.takeIf { ACCOUNT_ID_PATTERN.matches(it) }
+        val payload = TapPayload(emailId, threadId, subject, accountId)
         pending = payload
         // Clear so a subsequent activity lifecycle event doesn't replay this.
         extras.remove(EXTRA_EMAIL_ID)
         extras.remove(EXTRA_THREAD_ID)
         extras.remove(EXTRA_SUBJECT)
+        extras.remove(EXTRA_ACCOUNT_ID)
         return payload
     }
 
@@ -35,15 +54,18 @@ object NotificationTapStore {
         val emailId: String,
         val threadId: String,
         val subject: String?,
+        val accountId: String?,
     ) {
         fun toMap(): WritableMap = Arguments.createMap().apply {
             putString("emailId", emailId)
             putString("threadId", threadId)
             if (subject != null) putString("subject", subject)
+            if (accountId != null) putString("accountId", accountId)
         }
     }
 
     const val EXTRA_EMAIL_ID = "bulwark.notification.emailId"
     const val EXTRA_THREAD_ID = "bulwark.notification.threadId"
     const val EXTRA_SUBJECT = "bulwark.notification.subject"
+    const val EXTRA_ACCOUNT_ID = "bulwark.notification.accountId"
 }

app.config.js

@@ -20,6 +20,7 @@ module.exports = {
   expo: {
     name: 'Bulwark Mobile',
     slug: 'bulwark-mobile',
+    scheme: 'bulwarkmobile',
     version: VERSION,
     orientation: 'portrait',
     icon: './assets/icon.png',

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bulwark-mobile",
-  "version": "0.1.19",
+  "version": "0.1.38",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bulwark-mobile",
-      "version": "0.1.19",
+      "version": "0.1.38",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "@react-native-async-storage/async-storage": "2.2.0",
@@ -17,6 +17,7 @@
         "@react-navigation/native-stack": "^7.14.10",
         "date-fns": "^4.1.0",
         "expo": "~54.0.33",
+        "expo-document-picker": "~14.0.8",
         "expo-file-system": "~19.0.21",
         "expo-image-picker": "~17.0.10",
         "expo-intent-launcher": "~13.0.8",
@@ -24,6 +25,7 @@
         "expo-secure-store": "~15.0.8",
         "expo-sharing": "~14.0.8",
         "expo-status-bar": "~3.0.9",
+        "expo-web-browser": "~15.0.8",
         "lucide-react-native": "^1.7.0",
         "react": "19.1.0",
         "react-native": "0.81.5",
@@ -5216,6 +5218,15 @@
         "react-native": "*"
       }
     },
+    "node_modules/expo-document-picker": {
+      "version": "14.0.8",
+      "resolved": "https://registry.npmjs.org/expo-document-picker/-/expo-document-picker-14.0.8.tgz",
+      "integrity": "sha512-3tyQKpPqWWFlI8p9RiMX1+T1Zge5mEKeBuXWp1h8PEItFMUDSiOJbQ112sfdC6Hxt8wSxreV9bCRl/NgBdt+fA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "expo": "*"
+      }
+    },
     "node_modules/expo-file-system": {
       "version": "19.0.21",
       "resolved": "https://registry.npmjs.org/expo-file-system/-/expo-file-system-19.0.21.tgz",
@@ -5408,6 +5419,16 @@
         "react-native": "*"
       }
     },
+    "node_modules/expo-web-browser": {
+      "version": "15.0.11",
+      "resolved": "https://registry.npmjs.org/expo-web-browser/-/expo-web-browser-15.0.11.tgz",
+      "integrity": "sha512-r2LS4Ro6DgUPZkcaEfgt8mp9eJuoA93x11Jh7S6utFe0FEzvUNn2yFhxg8XVwESaaHGt2k5V8LuK36rsp0BeIw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "expo": "*",
+        "react-native": "*"
+      }
+    },
     "node_modules/expo/node_modules/@babel/code-frame": {
       "version": "7.29.0",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulwark-mobile",
-  "version": "0.1.19",
+  "version": "0.1.38",
   "license": "AGPL-3.0-only",
   "main": "index.ts",
   "scripts": {
@@ -10,6 +10,7 @@
     "web": "expo start --web",
     "test": "vitest run",
     "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
     "bump": "node scripts/bump-version.mjs",
     "sync-locales": "node scripts/sync-locales.mjs"
   },
@@ -22,6 +23,7 @@
     "@react-navigation/native-stack": "^7.14.10",
     "date-fns": "^4.1.0",
     "expo": "~54.0.33",
+    "expo-document-picker": "~14.0.8",
     "expo-file-system": "~19.0.21",
     "expo-image-picker": "~17.0.10",
     "expo-intent-launcher": "~13.0.8",
@@ -29,6 +31,7 @@
     "expo-secure-store": "~15.0.8",
     "expo-sharing": "~14.0.8",
     "expo-status-bar": "~3.0.9",
+    "expo-web-browser": "~15.0.8",
     "lucide-react-native": "^1.7.0",
     "react": "19.1.0",
     "react-native": "0.81.5",

src/api/__tests__/calendar.test.ts

@@ -4,6 +4,7 @@ vi.mock('../jmap-client', () => ({
   jmapClient: {
     accountId: 'acc-1',
     request: vi.fn(),
+    getMaxObjectsInGet: () => 500,
   },
 }));
 
@@ -41,7 +42,10 @@ describe('calendar operations', () => {
   });
 
   describe('queryEvents', () => {
-    it('should query events within date range', async () => {
+    it('should send a CalendarEvent/query without server-side filter', async () => {
+      // Stalwart rejects inCalendars/after/before, so we fetch unfiltered and
+      // filter client-side. Asserting on the absence of `filter` keeps that
+      // contract pinned.
       mockRequest.mockResolvedValue({
         methodResponses: [['CalendarEvent/query', { ids: ['ev1', 'ev2'] }, '0']],
       });
@@ -50,12 +54,9 @@ describe('calendar operations', () => {
       expect(result).toEqual(['ev1', 'ev2']);
 
       const call = mockRequest.mock.calls[0][0][0];
-      expect(call[1].filter).toEqual({
-        inCalendars: ['cal-1'],
-        after: '2026-03-01T00:00:00Z',
-        before: '2026-03-31T23:59:59Z',
-        types: ['Event'],
-      });
+      expect(call[0]).toBe('CalendarEvent/query');
+      expect(call[1].filter).toBeUndefined();
+      expect(call[1].accountId).toBe('acc-1');
     });
   });
 

src/api/__tests__/contacts.test.ts

@@ -4,6 +4,7 @@ vi.mock('../jmap-client', () => ({
   jmapClient: {
     accountId: 'acc-1',
     request: vi.fn(),
+    getMaxObjectsInGet: () => 500,
   },
 }));
 
@@ -50,14 +51,14 @@ describe('contacts operations', () => {
       expect(result).toEqual(['c1', 'c2']);
     });
 
-    it('should use default empty filter', async () => {
+    it('should omit filter when none provided', async () => {
       mockRequest.mockResolvedValue({
         methodResponses: [['ContactCard/query', { ids: [] }, '0']],
       });
 
       await queryContacts();
       const call = mockRequest.mock.calls[0][0][0];
-      expect(call[1].filter).toEqual({});
+      expect(call[1].filter).toBeUndefined();
     });
   });
 

src/api/__tests__/email.test.ts

@@ -90,6 +90,24 @@ describe('email operations', () => {
       const call = mockRequest.mock.calls[0][0][0];
       expect(call[1].filter).toEqual({ inMailbox: 'mb-1', hasKeyword: '$flagged' });
     });
+
+    it('should AND-wrap a FilterOperator instead of spreading it', async () => {
+      mockRequest.mockResolvedValue({
+        methodResponses: [['Email/query', { ids: [], total: 0 }, '0']],
+      });
+
+      const userFilter = {
+        operator: 'AND',
+        conditions: [{ inMailbox: 'mb-1' }, { notKeyword: '$seen' }],
+      };
+      await queryEmails('mb-1', { filter: userFilter });
+
+      const call = mockRequest.mock.calls[0][0][0];
+      expect(call[1].filter).toEqual({
+        operator: 'AND',
+        conditions: [{ inMailbox: 'mb-1' }, userFilter],
+      });
+    });
   });
 
   describe('getEmails', () => {
@@ -197,7 +215,7 @@ describe('email operations', () => {
 
       expect(result).toEqual(['e1']);
       const call = mockRequest.mock.calls[0][0][0];
-      expect(call[1].filter).toEqual({ text: 'test query' });
+      expect(call[1].filter).toEqual({ text: 'test* query*' });
     });
 
     it('should include mailbox filter if specified', async () => {
@@ -208,7 +226,7 @@ describe('email operations', () => {
       await searchEmails('query', 'mb-1');
 
       const call = mockRequest.mock.calls[0][0][0];
-      expect(call[1].filter).toEqual({ text: 'query', inMailbox: 'mb-1' });
+      expect(call[1].filter).toEqual({ text: 'query*', inMailbox: 'mb-1' });
     });
   });
 

src/api/blob.ts

@@ -1,5 +1,6 @@
 import { File } from 'expo-file-system';
 import { jmapClient } from './jmap-client';
+import { secureFetch } from '../lib/client-cert';
 
 export async function uploadBlob(
   uri: string,
@@ -20,7 +21,7 @@ export async function uploadBlob(
   // empty/garbage upload.
   const bytes = await new File(uri).bytes();
 
-  const response = await fetch(uploadUrl, {
+  const response = await secureFetch(uploadUrl, {
     method: 'POST',
     headers: {
       'Content-Type': type || 'application/octet-stream',
@@ -60,6 +61,57 @@ export async function uploadBlob(
   throw new Error('Upload succeeded but response did not include a blobId');
 }
 
+// Direct in-memory upload. The on-disk variant goes through expo-file-system's
+// `new File(uri).bytes()`, which is overkill when we already have the bytes
+// (e.g. the empty-blob trick used to create directories on Stalwart).
+export async function uploadBytes(
+  bytes: Uint8Array,
+  type: string,
+): Promise<{ blobId: string; size: number; type: string }> {
+  const session = jmapClient.currentSession;
+  if (!session) throw new Error('Not connected');
+
+  const uploadUrl = session.uploadUrl.replace(
+    '{accountId}',
+    encodeURIComponent(jmapClient.accountId),
+  );
+
+  const response = await secureFetch(uploadUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': type || 'application/octet-stream',
+      Authorization: jmapClient.authHeader,
+    },
+    body: bytes.buffer as ArrayBuffer,
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '');
+    throw new Error(`Upload failed: ${response.status}${detail ? ` ${detail}` : ''}`);
+  }
+
+  const raw = (await response.json()) as Record<string, unknown>;
+  const direct = raw as { blobId?: string; type?: string; size?: number };
+  if (typeof direct.blobId === 'string') {
+    return {
+      blobId: direct.blobId,
+      size: typeof direct.size === 'number' ? direct.size : bytes.byteLength,
+      type: typeof direct.type === 'string' && direct.type ? direct.type : type,
+    };
+  }
+  const nested = raw[jmapClient.accountId] as
+    | { blobId?: string; type?: string; size?: number }
+    | undefined;
+  if (nested?.blobId) {
+    return {
+      blobId: nested.blobId,
+      size: typeof nested.size === 'number' ? nested.size : bytes.byteLength,
+      type: typeof nested.type === 'string' && nested.type ? nested.type : type,
+    };
+  }
+  throw new Error('Upload succeeded but response did not include a blobId');
+}
+
 export function getDownloadUrl(
   blobId: string,
   name?: string,

src/api/email.ts

@@ -22,6 +22,55 @@ export async function getMailboxes(): Promise<Mailbox[]> {
   return res.methodResponses[0][1].list;
 }
 
+// Variant that also returns the JMAP `state` token so callers can later issue
+// Mailbox/changes(sinceState=…) to fetch only what changed.
+export async function getMailboxesWithState(): Promise<{ list: Mailbox[]; state: string }> {
+  const accountId = jmapClient.accountId;
+  const res = await jmapClient.request(
+    [['Mailbox/get', { accountId }, '0']],
+  );
+  const body = res.methodResponses[0][1];
+  return { list: body.list as Mailbox[], state: body.state as string };
+}
+
+export async function getMailboxesByIds(ids: string[]): Promise<{ list: Mailbox[]; state: string }> {
+  if (ids.length === 0) return { list: [], state: '' };
+  const accountId = jmapClient.accountId;
+  const res = await jmapClient.request(
+    [['Mailbox/get', { accountId, ids }, '0']],
+  );
+  const body = res.methodResponses[0][1];
+  return { list: body.list as Mailbox[], state: body.state as string };
+}
+
+export interface MailboxChangesResult {
+  oldState: string;
+  newState: string;
+  hasMoreChanges: boolean;
+  created: string[];
+  updated: string[];
+  destroyed: string[];
+}
+
+// Returns null when the server can't compute the diff (typically
+// `cannotCalculateChanges`); callers should fall back to a full Mailbox/get.
+export async function getMailboxChanges(sinceState: string): Promise<MailboxChangesResult | null> {
+  const accountId = jmapClient.accountId;
+  const res = await jmapClient.request(
+    [['Mailbox/changes', { accountId, sinceState }, '0']],
+  );
+  const [name, body] = res.methodResponses[0];
+  if (name === 'error') return null;
+  return {
+    oldState: body.oldState as string,
+    newState: body.newState as string,
+    hasMoreChanges: Boolean(body.hasMoreChanges),
+    created: (body.created as string[]) ?? [],
+    updated: (body.updated as string[]) ?? [],
+    destroyed: (body.destroyed as string[]) ?? [],
+  };
+}
+
 export async function createMailbox(
   data: { name: string; parentId?: string | null },
 ): Promise<string> {
@@ -83,6 +132,22 @@ export async function deleteMailbox(id: string): Promise<void> {
   }
 }
 
+function buildMailboxQueryFilter(
+  mailboxId: string,
+  userFilter: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const inMailbox = { inMailbox: mailboxId };
+  // JMAP filters are either a FilterCondition or a FilterOperator (operator +
+  // conditions) — never both. Spreading a FilterOperator next to `inMailbox`
+  // produces a hybrid object that servers reduce to the FilterCondition,
+  // silently dropping the operator's conditions (e.g. the "unread" toggle).
+  if (!userFilter || Object.keys(userFilter).length === 0) return inMailbox;
+  if ('operator' in userFilter) {
+    return { operator: 'AND', conditions: [inMailbox, userFilter] };
+  }
+  return { ...inMailbox, ...userFilter };
+}
+
 export async function queryEmails(
   mailboxId: string,
   options?: {
@@ -91,21 +156,69 @@ export async function queryEmails(
     sort?: Array<{ property: string; isAscending: boolean }>;
     filter?: Record<string, unknown>;
   },
-): Promise<{ ids: string[]; total: number }> {
+): Promise<{ ids: string[]; total: number; queryState?: string }> {
   const accountId = jmapClient.accountId;
+  const filter = buildMailboxQueryFilter(mailboxId, options?.filter);
   const res = await jmapClient.request([
     ['Email/query', {
       accountId,
-      filter: { inMailbox: mailboxId, ...options?.filter },
+      filter,
       sort: options?.sort ?? [{ property: 'receivedAt', isAscending: false }],
       position: options?.position ?? 0,
       limit: options?.limit ?? 50,
       calculateTotal: true,
     }, '0'],
   ]);
+  const body = res.methodResponses[0][1];
   return {
-    ids: res.methodResponses[0][1].ids,
-    total: res.methodResponses[0][1].total,
+    ids: body.ids,
+    total: body.total,
+    queryState: body.queryState as string | undefined,
+  };
+}
+
+export interface EmailQueryChangesResult {
+  oldQueryState: string;
+  newQueryState: string;
+  total: number;
+  removed: string[];
+  added: Array<{ id: string; index: number }>;
+}
+
+// Run Email/queryChanges for the standard "by receivedAt desc, in this mailbox"
+// query. Returns null when the server replies with `cannotCalculateChanges`
+// (or any other error) — caller should fall back to a fresh Email/query.
+export async function getEmailQueryChanges(
+  mailboxId: string,
+  sinceQueryState: string,
+  options?: {
+    sort?: Array<{ property: string; isAscending: boolean }>;
+    filter?: Record<string, unknown>;
+    upToId?: string;
+    maxChanges?: number;
+  },
+): Promise<EmailQueryChangesResult | null> {
+  const accountId = jmapClient.accountId;
+  const filter = buildMailboxQueryFilter(mailboxId, options?.filter);
+  const args: Record<string, unknown> = {
+    accountId,
+    filter,
+    sort: options?.sort ?? [{ property: 'receivedAt', isAscending: false }],
+    sinceQueryState,
+    calculateTotal: true,
+  };
+  if (options?.upToId) args.upToId = options.upToId;
+  if (options?.maxChanges) args.maxChanges = options.maxChanges;
+
+  const res = await jmapClient.request([['Email/queryChanges', args, '0']]);
+  const [name, body] = res.methodResponses[0];
+  if (name === 'error') return null;
+  return {
+    oldQueryState: body.oldQueryState as string,
+    newQueryState: body.newQueryState as string,
+    total: (body.total as number) ?? 0,
+    removed: (body.removed as string[]) ?? [],
+    added: (body.added as Array<{ id: string; index: number }>) ?? [],
   };
 }
 
@@ -117,6 +230,59 @@ export async function getEmails(ids: string[]): Promise<Email[]> {
   return res.methodResponses[0][1].list;
 }
 
+// Returns the Email/get response with the JMAP `state` token. Used by the
+// store so we can later issue Email/changes(sinceState=…) for incremental
+// updates instead of re-fetching the full list.
+export async function getEmailsWithState(ids: string[]): Promise<{ list: Email[]; state: string }> {
+  if (ids.length === 0) {
+    // Email/get with an empty id list still returns a state token; useful for
+    // priming the store after an empty mailbox query.
+    const accountId = jmapClient.accountId;
+    const res = await jmapClient.request([
+      ['Email/get', { accountId, ids: [], properties: EMAIL_LIST_PROPERTIES }, '0'],
+    ]);
+    const body = res.methodResponses[0][1];
+    return { list: [], state: body.state as string };
+  }
+  const accountId = jmapClient.accountId;
+  const res = await jmapClient.request([
+    ['Email/get', { accountId, ids, properties: EMAIL_LIST_PROPERTIES }, '0'],
+  ]);
+  const body = res.methodResponses[0][1];
+  return { list: body.list as Email[], state: body.state as string };
+}
+
+export interface EmailChangesResult {
+  oldState: string;
+  newState: string;
+  hasMoreChanges: boolean;
+  created: string[];
+  updated: string[];
+  destroyed: string[];
+}
+
+// Returns null when the server replies with `cannotCalculateChanges` or any
+// other error response; caller should treat that as "rebuild from scratch".
+export async function getEmailChanges(
+  sinceState: string,
+  maxChanges?: number,
+): Promise<EmailChangesResult | null> {
+  const accountId = jmapClient.accountId;
+  const args: Record<string, unknown> = { accountId, sinceState };
+  if (maxChanges) args.maxChanges = maxChanges;
+  const res = await jmapClient.request([['Email/changes', args, '0']]);
+  const [name, body] = res.methodResponses[0];
+  if (name === 'error') return null;
+  return {
+    oldState: body.oldState as string,
+    newState: body.newState as string,
+    hasMoreChanges: Boolean(body.hasMoreChanges),
+    created: (body.created as string[]) ?? [],
+    updated: (body.updated as string[]) ?? [],
+    destroyed: (body.destroyed as string[]) ?? [],
+  };
+}
+
 export async function getFullEmail(id: string): Promise<Email> {
   const accountId = jmapClient.accountId;
   const res = await jmapClient.request([
@@ -135,6 +301,26 @@ export async function getFullEmail(id: string): Promise<Email> {
   return email;
 }
 
+// Batch variant for offline sync. JMAP servers cap how many objects can be
+// returned in a single Email/get; the caller should chunk to that ceiling
+// (the client exposes maxObjectsInGet via getMaxObjectsInGet()).
+export async function getFullEmails(ids: string[]): Promise<Email[]> {
+  if (ids.length === 0) return [];
+  const accountId = jmapClient.accountId;
+  const res = await jmapClient.request([
+    ['Email/get', {
+      accountId,
+      ids,
+      properties: EMAIL_FULL_PROPERTIES,
+      fetchHTMLBodyValues: true,
+      fetchTextBodyValues: true,
+      fetchAllBodyValues: true,
+      maxBodyValueBytes: 512000,
+    }, '0'],
+  ]);
+  return res.methodResponses[0][1].list as Email[];
+}
+
 export async function getThread(threadId: string): Promise<Thread> {
   const accountId = jmapClient.accountId;
   const res = await jmapClient.request(

src/api/files.ts

@@ -1,19 +1,68 @@
 import { jmapClient } from './jmap-client';
 import { CAPABILITIES } from './types';
 import type { FileNode } from './types';
+import { getDownloadUrl, uploadBlob, uploadBytes } from './blob';
 
-const USING = [CAPABILITIES.CORE, CAPABILITIES.MAIL];
+const USING = [CAPABILITIES.CORE, CAPABILITIES.FILES];
 
-export async function getFileNodes(parentId?: string | null): Promise<FileNode[]> {
+// Stalwart and other JMAP servers use one of these strings on FileNode.type to
+// mark a directory; everything else is a MIME type.
+const DIRECTORY_TYPES = new Set([
+  'd',
+  'application/x-directory',
+  'text/directory',
+  'httpd/unix-directory',
+  'inode/directory',
+]);
+
+export function isDirectory(node: Pick<FileNode, 'type'>): boolean {
+  const t = node.type;
+  if (!t) return false;
+  return DIRECTORY_TYPES.has(t) || t.includes('directory');
+}
+
+// Stalwart rejects `/` in FileNode names, so the webmail (and now this app)
+// uses U+2215 DIVISION SLASH as the path separator inside the flat `name`
+// field. Hierarchy is encoded into the name — there is no `parentId` nesting.
+// e.g. a file inside the `Documents` folder is stored with
+// `name = "Documents∕report.pdf"`. The display name shown to the user
+// strips the prefix.
+export const PATH_SEP = '∕';
+
+// Path is a list of folder display names from root. [] is root,
+// ['Documents'] is inside Documents, ['Documents','sub'] is inside the
+// `sub` folder under Documents.
+export function pathToPrefix(path: readonly string[]): string {
+  if (path.length === 0) return '';
+  return path.join(PATH_SEP) + PATH_SEP;
+}
+
+// True when `node` is a direct child (not a descendant) of `prefix`.
+export function isDirectChildOfPrefix(node: Pick<FileNode, 'name'>, prefix: string): boolean {
+  if (!node.name) return false;
+  if (prefix === '') return !node.name.includes(PATH_SEP);
+  if (!node.name.startsWith(prefix)) return false;
+  const rest = node.name.slice(prefix.length);
+  return rest.length > 0 && !rest.includes(PATH_SEP);
+}
+
+export function nodeDisplayName(node: Pick<FileNode, 'name'>, prefix: string): string {
+  return prefix && node.name.startsWith(prefix) ? node.name.slice(prefix.length) : node.name;
+}
+
+// Stalwart's FileNode/get does not support a parentId filter and some builds
+// omit `type` from the default property set. We fetch the whole tree and
+// filter client-side; properties are listed explicitly so `isDirectory()`
+// always has a value to look at.
+const FILE_NODE_PROPERTIES = ['id', 'parentId', 'name', 'type', 'blobId', 'size', 'created', 'updated'];
+
+export async function getAllFileNodes(): Promise<FileNode[]> {
   const accountId = jmapClient.accountId;
-  const filter: Record<string, unknown> = {};
-  if (parentId !== undefined) filter.parentId = parentId;
-
   const res = await jmapClient.request(
-    [['FileNode/get', { accountId, filter }, '0']],
+    [['FileNode/get', { accountId, ids: null, properties: FILE_NODE_PROPERTIES }, '0']],
     USING,
   );
-  return res.methodResponses[0][1].list;
+  return (res.methodResponses[0][1].list ?? []) as FileNode[];
 }
 
 export async function createFileNode(
@@ -27,13 +76,113 @@ export async function createFileNode(
     }, '0']],
     USING,
   );
-  return res.methodResponses[0][1].created['new-file'];
+  const created = res.methodResponses[0][1].created?.['new-file'];
+  if (!created) {
+    const err = res.methodResponses[0][1].notCreated?.['new-file'];
+    throw new Error(err?.description || 'Create failed');
+  }
+  return created;
+}
+
+export async function createFolder(
+  displayName: string,
+  currentPath: readonly string[],
+): Promise<FileNode> {
+  // Stalwart's FileNode/set rejects directory creates without a blobId
+  // ("Missing blob id"), so we upload an empty blob first and reference it.
+  // Mirrors the webmail's createFileDirectory.
+  const blob = await uploadBytes(new Uint8Array(0), 'application/x-directory');
+  const fullName = pathToPrefix(currentPath) + displayName;
+  return createFileNode({ name: fullName, type: 'd', blobId: blob.blobId, size: 0 });
+}
+
+export async function updateFileNode(
+  id: string,
+  updates: Partial<Pick<FileNode, 'name' | 'parentId'>>,
+): Promise<void> {
+  const accountId = jmapClient.accountId;
+  const res = await jmapClient.request(
+    [['FileNode/set', { accountId, update: { [id]: updates } }, '0']],
+    USING,
+  );
+  const notUpdated = res.methodResponses[0][1].notUpdated?.[id];
+  if (notUpdated) throw new Error(notUpdated.description || 'Update failed');
+}
+
+// Rename a node and, if it's a folder, cascade the rename to every descendant
+// so the encoded path stays consistent. The webmail does this same dance.
+export async function renameFileNode(
+  node: FileNode,
+  newDisplayName: string,
+  currentPath: readonly string[],
+  allNodes: readonly FileNode[],
+): Promise<void> {
+  const prefix = pathToPrefix(currentPath);
+  const oldServerName = node.name;
+  const newServerName = prefix + newDisplayName;
+  if (oldServerName === newServerName) return;
+
+  await updateFileNode(node.id, { name: newServerName });
+
+  if (isDirectory(node)) {
+    const oldFolderPrefix = oldServerName + PATH_SEP;
+    const newFolderPrefix = newServerName + PATH_SEP;
+    for (const n of allNodes) {
+      if (n.id === node.id) continue;
+      if (n.name.startsWith(oldFolderPrefix)) {
+        await updateFileNode(n.id, { name: newFolderPrefix + n.name.slice(oldFolderPrefix.length) });
+      }
+    }
+  }
 }
 
 export async function deleteFileNodes(ids: string[]): Promise<void> {
+  if (ids.length === 0) return;
   const accountId = jmapClient.accountId;
   await jmapClient.request(
     [['FileNode/set', { accountId, destroy: ids }, '0']],
     USING,
   );
 }
+
+// Delete `targets` and every descendant. Stalwart doesn't enforce parent
+// references, so we collect descendants by name-prefix and destroy them all
+// in one call. Without this, deleting a folder leaves its files orphaned and
+// still discoverable at the old encoded path.
+export async function deleteWithDescendants(
+  targets: readonly FileNode[],
+  allNodes: readonly FileNode[],
+): Promise<void> {
+  const ids = new Set<string>();
+  for (const node of targets) {
+    ids.add(node.id);
+    if (isDirectory(node)) {
+      const folderPrefix = node.name + PATH_SEP;
+      for (const n of allNodes) {
+        if (n.name.startsWith(folderPrefix)) ids.add(n.id);
+      }
+    }
+  }
+  await deleteFileNodes(Array.from(ids));
+}
+
+export function getFileNodeDownloadUrl(node: FileNode): string {
+  if (!node.blobId) throw new Error('Folders cannot be downloaded');
+  return getDownloadUrl(node.blobId, node.name, node.type);
+}
+
+export async function uploadFileNode(
+  uri: string,
+  displayName: string,
+  mimeType: string,
+  currentPath: readonly string[],
+): Promise<FileNode> {
+  const blob = await uploadBlob(uri, mimeType);
+  const fullName = pathToPrefix(currentPath) + displayName;
+  return createFileNode({
+    name: fullName,
+    type: blob.type || mimeType || 'application/octet-stream',
+    blobId: blob.blobId,
+    size: blob.size,
+  });
+}

src/api/jmap-client.ts

@@ -7,6 +7,12 @@ import type {
 } from './types';
 import { CAPABILITIES } from './types';
 import { generateAccountId } from '../lib/account-utils';
+import { secureFetch } from '../lib/client-cert';
+import { refreshOAuthAccessToken, type OAuthTokens } from '../lib/oauth';
+
+// Refresh OAuth access tokens this many ms before they actually expire so
+// in-flight requests don't race the expiry window.
+const TOKEN_REFRESH_LEEWAY_MS = 60_000;
 
 const LEGACY_CREDENTIALS_KEY = 'jmap_credentials';
 const CREDENTIALS_PREFIX = 'jmap_credentials__';
@@ -21,6 +27,13 @@ export interface StoredCredentials {
   username: string;
   password: string;
   accessToken?: string;
+  // OAuth-only — present when credentials came in via the webmail handoff
+  // OAuth path rather than password auth. The token endpoint and client id
+  // are needed for refresh; without them the access token would just expire.
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenEndpoint?: string;
+  clientId?: string;
 }
 
 export class JMAPClient {
@@ -92,6 +105,113 @@ export class JMAPClient {
     return this.session;
   }
 
+  // OAuth login via webmail handoff. The webmail did the OAuth dance against
+  // Stalwart and handed us a complete token bundle. We persist the bundle
+  // so subsequent launches can refresh without prompting the user again.
+  async connectWithOAuth(
+    serverUrl: string,
+    tokens: OAuthTokens,
+  ): Promise<{ session: JMAPSession; username: string; accountId: string }> {
+    const baseUrl = serverUrl.replace(/\/+$/, '');
+    this.credentials = {
+      serverUrl: baseUrl,
+      username: '',
+      password: '',
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+      expiresAt: tokens.expiresAt,
+      tokenEndpoint: tokens.tokenEndpoint,
+      clientId: tokens.clientId,
+    };
+
+    this.session = this.rewriteSessionUrls(await this.fetchSession(baseUrl), baseUrl);
+    this._accountId = this.resolveAccountId(this.session);
+
+    // The JMAP session document carries the authenticated user's identifier
+    // — use it as the username so per-account storage keys are stable across
+    // restarts and OAuth re-logins.
+    const username = this.session.username || tokens.accessToken.slice(0, 8);
+    this.credentials.username = username;
+
+    const accountId = generateAccountId(username, baseUrl);
+    await SecureStore.setItemAsync(
+      credentialsKey(accountId),
+      JSON.stringify(this.credentials),
+    );
+
+    return { session: this.session, username, accountId };
+  }
+
+  private async persistRefreshedTokens(next: OAuthTokens): Promise<void> {
+    if (!this.credentials) return;
+    this.credentials = {
+      ...this.credentials,
+      accessToken: next.accessToken,
+      // Some IdPs rotate refresh tokens; others reuse. Fall back to the
+      // existing one when the response omits it.
+      refreshToken: next.refreshToken ?? this.credentials.refreshToken,
+      expiresAt: next.expiresAt,
+      tokenEndpoint: next.tokenEndpoint,
+      clientId: next.clientId,
+    };
+    const accountId = generateAccountId(
+      this.credentials.username,
+      this.credentials.serverUrl,
+    );
+    await SecureStore.setItemAsync(
+      credentialsKey(accountId),
+      JSON.stringify(this.credentials),
+    );
+  }
+
+  private currentOAuthTokens(): OAuthTokens | null {
+    if (
+      !this.credentials?.accessToken ||
+      !this.credentials.refreshToken ||
+      !this.credentials.tokenEndpoint ||
+      !this.credentials.clientId
+    ) {
+      return null;
+    }
+    return {
+      accessToken: this.credentials.accessToken,
+      refreshToken: this.credentials.refreshToken,
+      expiresAt: this.credentials.expiresAt,
+      tokenEndpoint: this.credentials.tokenEndpoint,
+      clientId: this.credentials.clientId,
+    };
+  }
+
+  // Proactive refresh: when the access token is about to expire, swap it for
+  // a fresh one. Quiet no-op for password credentials.
+  private async ensureFreshToken(): Promise<void> {
+    const tokens = this.currentOAuthTokens();
+    if (!tokens) return;
+    if (tokens.expiresAt == null) return;
+    if (tokens.expiresAt - Date.now() > TOKEN_REFRESH_LEEWAY_MS) return;
+    try {
+      const next = await refreshOAuthAccessToken(tokens);
+      await this.persistRefreshedTokens(next);
+    } catch {
+      // Surface as AuthenticationError on the next 401; refresh may be
+      // temporarily failing (network) and the reactive retry path catches it.
+    }
+  }
+
+  // Reactive refresh after a 401. Returns true if a fresh token was obtained
+  // so the caller can retry the original request.
+  private async forceRefreshToken(): Promise<boolean> {
+    const tokens = this.currentOAuthTokens();
+    if (!tokens) return false;
+    try {
+      const next = await refreshOAuthAccessToken(tokens);
+      await this.persistRefreshedTokens(next);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   // Legacy single-slot restore - kept for backward-compat tests. New code
   // should use loadAccount(accountId) driven by the account registry.
   async restoreSession(): Promise<boolean> {
@@ -117,18 +237,38 @@ export class JMAPClient {
     const stored = await SecureStore.getItemAsync(credentialsKey(accountId));
     if (!stored) return false;
 
+    let creds: StoredCredentials;
+    try {
+      creds = JSON.parse(stored);
+    } catch {
+      // Corrupt entry — credentials can't be used. Caller should evict.
+      return false;
+    }
+
+    // Errors past this point propagate so callers can distinguish
+    // unrecoverable (AuthenticationError) from transient (NetworkError) and
+    // avoid clearing credentials when the server is just unreachable.
+    this.credentials = creds;
     try {
-      const creds: StoredCredentials = JSON.parse(stored);
-      this.credentials = creds;
       this.session = this.rewriteSessionUrls(
         await this.fetchSession(creds.serverUrl),
         creds.serverUrl,
       );
-      this._accountId = this.resolveAccountId(this.session);
-      return true;
-    } catch {
-      return false;
+    } catch (err) {
+      // Don't leave a half-populated client behind; the caller needs to know
+      // the session is unavailable. Credentials stay in memory so a retry
+      // after the network comes back doesn't need a re-login.
+      this.session = null;
+      this._accountId = null;
+      if (err instanceof AuthenticationError) throw err;
+      // Anything else is treated as transport-level. Wrapping rather than
+      // rethrowing the raw fetch error gives callers a single check.
+      throw new NetworkError(
+        err instanceof Error ? err.message : 'Server unreachable',
+      );
     }
+    this._accountId = this.resolveAccountId(this.session);
+    return true;
   }
 
   async clearAccountCredentials(accountId: string): Promise<void> {
@@ -214,12 +354,18 @@ export class JMAPClient {
 
   private async fetchSession(baseUrl: string): Promise<JMAPSession> {
     const url = `${baseUrl}/.well-known/jmap`;
-    const response = await fetch(url, {
-      headers: {
-        Authorization: this.authHeader,
-        Accept: 'application/json',
-      },
-    });
+    await this.ensureFreshToken();
+    const doFetch = () =>
+      secureFetch(url, {
+        headers: {
+          Authorization: this.authHeader,
+          Accept: 'application/json',
+        },
+      });
+    let response = await doFetch();
+    if (response.status === 401 && (await this.forceRefreshToken())) {
+      response = await doFetch();
+    }
 
     if (response.status === 401) {
       throw new AuthenticationError('Invalid credentials');
@@ -259,14 +405,21 @@ export class JMAPClient {
       methodCalls,
     };
 
-    const response = await fetch(this.session.apiUrl, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: this.authHeader,
-      },
-      body: JSON.stringify(body),
-    });
+    await this.ensureFreshToken();
+    const doFetch = () =>
+      secureFetch(this.session!.apiUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: this.authHeader,
+        },
+        body: JSON.stringify(body),
+      });
+
+    let response = await doFetch();
+    if (response.status === 401 && (await this.forceRefreshToken())) {
+      response = await doFetch();
+    }
 
     if (response.status === 401) {
       throw new AuthenticationError('Session expired');
@@ -314,9 +467,12 @@ export class JMAPClient {
 
   async fetchBlobArrayBuffer(blobId: string, name?: string, type?: string): Promise<ArrayBuffer> {
     const url = this.getBlobDownloadUrl(blobId, name, type);
-    const response = await fetch(url, {
-      headers: { Authorization: this.authHeader },
-    });
+    await this.ensureFreshToken();
+    const doFetch = () => secureFetch(url, { headers: { Authorization: this.authHeader } });
+    let response = await doFetch();
+    if (response.status === 401 && (await this.forceRefreshToken())) {
+      response = await doFetch();
+    }
     if (response.status === 401) throw new AuthenticationError('Session expired');
     if (!response.ok) throw new Error(`Failed to fetch blob: ${response.status}`);
     return response.arrayBuffer();
@@ -332,6 +488,15 @@ export class AuthenticationError extends Error {
   }
 }
 
+// Server unreachable / transient transport failure. Callers should keep
+// stored credentials and surface an offline state rather than logging out.
+export class NetworkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NetworkError';
+  }
+}
+
 export class RateLimitError extends Error {
   retryAfterMs: number;
   constructor(retryAfterMs: number) {

src/api/push.ts

@@ -201,13 +201,35 @@ export function startPolling(
   return () => clearInterval(timer);
 }
 
+export interface StartPushOptions {
+  onStateChange: StateChangeHandler;
+  onError?: (error: Error) => void;
+}
+
 /**
- * Start real-time updates, preferring SSE with polling fallback.
+ * Start real-time updates, preferring SSE with polling fallback. The `_client`
+ * argument is unused today (the underlying event source uses the singleton
+ * `jmapClient`) but is part of the call signature so the host App can pass
+ * the active client reference and trigger React re-runs on account switch.
  */
 export function startPushUpdates(
-  onStateChange: StateChangeHandler,
+  _client: unknown,
+  opts: StartPushOptions,
 ): () => void {
-  const cleanup = connectEventSource(onStateChange);
-  if (cleanup) return cleanup;
-  return startPolling(onStateChange);
+  const onError = opts.onError;
+  const safeOnStateChange: StateChangeHandler = (change) => {
+    try {
+      opts.onStateChange(change);
+    } catch (err) {
+      if (onError) onError(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+  try {
+    const cleanup = connectEventSource(safeOnStateChange);
+    if (cleanup) return cleanup;
+    return startPolling(safeOnStateChange);
+  } catch (err) {
+    if (onError) onError(err instanceof Error ? err : new Error(String(err)));
+    return () => undefined;
+  }
 }

src/api/types.ts

@@ -9,6 +9,10 @@ export interface JMAPSession {
   accounts: Record<string, JMAPAccountInfo>;
   capabilities: Record<string, unknown>;
   state: string;
+  // RFC 8620 §2 — authenticated user identifier. Optional because not all
+  // servers populate it; OAuth login uses it as the account label when
+  // there's no password username to fall back on.
+  username?: string;
 }
 
 export interface JMAPAccountInfo {
@@ -429,7 +433,7 @@ export interface FileNode {
   name: string;
   parentId?: string | null;
   type: string;
-  blobId?: string;
+  blobId?: string | null;
   size?: number;
   created?: string;
   updated?: string;
@@ -465,4 +469,5 @@ export const CAPABILITIES = {
   CALENDARS: 'urn:ietf:params:jmap:calendars',
   SIEVE: 'urn:ietf:params:jmap:sieve',
   QUOTA: 'urn:ietf:params:jmap:quota',
+  FILES: 'urn:ietf:params:jmap:filenode',
 } as const;

src/api/updates.ts

@@ -13,6 +13,45 @@ export interface LatestRelease {
   publishedAt: string;
   body: string;
   apkAsset: ReleaseAsset | null;
+  // Lower-case hex SHA-256 of the APK, parsed from a `*.apk.sha256` companion
+  // asset or from the release body. Null when the release didn't publish one;
+  // the installer falls back to relying solely on Android's package signing
+  // check in that case (still strong, but less defense-in-depth).
+  apkSha256: string | null;
+}
+
+const SHA256_RE = /\b([a-f0-9]{64})\b/i;
+
+function extractSha256(body: string, apkName: string | undefined): string | null {
+  if (!body) return null;
+  // Prefer a line that explicitly references the APK so we don't pick up the
+  // hash of an unrelated asset.
+  const lines = body.split(/\r?\n/);
+  if (apkName) {
+    for (const line of lines) {
+      if (line.includes(apkName)) {
+        const m = SHA256_RE.exec(line);
+        if (m) return m[1].toLowerCase();
+      }
+    }
+  }
+  // Fallback: a single SHA256 anywhere in the body — common when the release
+  // notes just list one checksum.
+  const m = SHA256_RE.exec(body);
+  return m ? m[1].toLowerCase() : null;
+}
+
+async function fetchCompanionSha256(asset: ReleaseAsset | undefined): Promise<string | null> {
+  if (!asset) return null;
+  try {
+    const res = await fetch(asset.browser_download_url);
+    if (!res.ok) return null;
+    const text = await res.text();
+    const m = SHA256_RE.exec(text);
+    return m ? m[1].toLowerCase() : null;
+  } catch {
+    return null;
+  }
 }
 
 export async function fetchLatestRelease(repo: string = UPDATE_REPO): Promise<LatestRelease | null> {
@@ -32,6 +71,14 @@ export async function fetchLatestRelease(repo: string = UPDATE_REPO): Promise<La
     assets: ReleaseAsset[];
   };
   const apkAsset = json.assets.find((a) => a.name.endsWith('.apk')) ?? null;
+  const sha256Asset = apkAsset
+    ? json.assets.find(
+        (a) => a.name === `${apkAsset.name}.sha256` || a.name === `${apkAsset.name}.SHA256`,
+      )
+    : undefined;
+  const apkSha256 =
+    (await fetchCompanionSha256(sha256Asset)) ??
+    extractSha256(json.body || '', apkAsset?.name);
   return {
     tag: json.tag_name,
     name: json.name || json.tag_name,
@@ -39,5 +86,6 @@ export async function fetchLatestRelease(repo: string = UPDATE_REPO): Promise<La
     publishedAt: json.published_at,
     body: json.body || '',
     apkAsset,
+    apkSha256,
   };
 }

src/components/EmailBodyView.tsx

@@ -297,7 +297,7 @@ export default function EmailBodyView({ email, senderEmail }: EmailBodyViewProps
       <View style={[styles.webContainer, { height }]}>
         <WebView
           ref={webviewRef}
-          originWhitelist={['about:*']}
+          originWhitelist={['about:blank']}
           source={source}
           javaScriptEnabled
           injectedJavaScript={HEIGHT_REPORTER}

src/components/OfflineCacheBanner.tsx

@@ -0,0 +1,143 @@
+// Live banner that mirrors the UpdateBanner's footprint, surfaced while the
+// offline mail sync is running. Hidden once the sync settles to idle/done.
+
+import React from 'react';
+import { View, Text, StyleSheet, Pressable } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { CloudDownload, X } from 'lucide-react-native';
+import { useOfflineCacheStore } from '../stores/offline-cache-store';
+import { useUpdatesStore } from '../stores/updates-store';
+import { formatBytes } from '../lib/offline-sync';
+import { spacing, radius, typography, type ThemePalette } from '../theme/tokens';
+import { useColors } from '../theme/colors';
+
+export function OfflineCacheBanner(): React.ReactElement | null {
+  const c = useColors();
+  const styles = React.useMemo(() => makeStyles(c), [c]);
+  const insets = useSafeAreaInsets();
+  const sync = useOfflineCacheStore((s) => s.sync);
+  const requestAbort = useOfflineCacheStore((s) => s.requestAbort);
+  const resetSync = useOfflineCacheStore((s) => s.resetSync);
+  // When UpdateBanner is stacked above us it already absorbs the status-bar
+  // inset, so we only add it when we're the topmost banner.
+  const cachedLatest = useUpdatesStore((s) => s.cachedLatest);
+  const dismissedTag = useUpdatesStore((s) => s.dismissedTag);
+  const hasUpdate = useUpdatesStore((s) => s.hasUpdate);
+  const updateBannerVisible =
+    hasUpdate() && cachedLatest?.apkAsset != null && dismissedTag !== cachedLatest.tag;
+  const topInset = updateBannerVisible ? 0 : insets.top;
+  const [hideTimer, setHideTimer] = React.useState<ReturnType<typeof setTimeout> | null>(null);
+
+  // Auto-dismiss the "done" state after a few seconds so the bar isn't a
+  // permanent fixture; the Settings screen still shows the cache stats.
+  React.useEffect(() => {
+    if (sync.phase === 'done' || sync.phase === 'cancelled') {
+      const t = setTimeout(() => resetSync(), 4000);
+      setHideTimer(t);
+      return () => clearTimeout(t);
+    }
+    if (hideTimer) clearTimeout(hideTimer);
+    return undefined;
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sync.phase, resetSync]);
+
+  if (sync.phase === 'idle') return null;
+
+  const pct =
+    sync.total > 0
+      ? Math.min(100, Math.round((sync.completed / sync.total) * 100))
+      : sync.phase === 'done' ? 100 : 0;
+
+  let title = 'Offline sync';
+  let subtitle = '';
+  switch (sync.phase) {
+    case 'scanning':
+      title = 'Syncing offline mail';
+      subtitle = 'Scanning recent messages…';
+      break;
+    case 'fetching':
+      title = 'Syncing offline mail';
+      subtitle = `${sync.completed}/${sync.total} • ${formatBytes(sync.bytes)}`;
+      break;
+    case 'done':
+      title = 'Offline mail ready';
+      subtitle = sync.fetched > 0
+        ? `${sync.fetched} new message${sync.fetched === 1 ? '' : 's'} cached • ${formatBytes(sync.bytes)}`
+        : 'Already up to date';
+      break;
+    case 'cancelled':
+      title = 'Sync cancelled';
+      subtitle = `${sync.completed}/${sync.total} processed`;
+      break;
+    case 'error':
+      title = 'Offline sync failed';
+      subtitle = sync.message ?? 'Unable to download';
+      break;
+    default:
+      return null;
+  }
+
+  const showCancel = sync.phase === 'scanning' || sync.phase === 'fetching';
+  const showDismiss = sync.phase === 'done' || sync.phase === 'cancelled' || sync.phase === 'error';
+  const isError = sync.phase === 'error';
+
+  return (
+    <View style={[styles.banner, isError && styles.bannerError, { paddingTop: spacing.sm + topInset }]}>
+      <CloudDownload size={16} color={c.primaryForeground} />
+      <View style={{ flex: 1 }}>
+        <Text style={styles.title}>{title}</Text>
+        {!!subtitle && <Text style={styles.subtitle}>{subtitle}</Text>}
+        {(sync.phase === 'fetching' || sync.phase === 'scanning') && (
+          <View style={styles.progressTrack}>
+            <View style={[styles.progressFill, { width: `${pct}%` }]} />
+          </View>
+        )}
+      </View>
+      {showCancel && (
+        <Pressable style={styles.cancelButton} onPress={requestAbort} hitSlop={6}>
+          <Text style={styles.cancelText}>Cancel</Text>
+        </Pressable>
+      )}
+      {showDismiss && (
+        <Pressable style={styles.dismiss} onPress={resetSync} hitSlop={8}>
+          <X size={14} color={c.primaryForeground} />
+        </Pressable>
+      )}
+    </View>
+  );
+}
+
+function makeStyles(c: ThemePalette) {
+  return StyleSheet.create({
+    banner: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: spacing.md,
+      paddingHorizontal: spacing.lg,
+      paddingVertical: spacing.sm,
+      backgroundColor: c.primary,
+    },
+    bannerError: { backgroundColor: c.error },
+    title: { ...typography.bodyMedium, color: c.primaryForeground },
+    subtitle: { ...typography.caption, color: c.primaryForeground, opacity: 0.85, marginTop: 2 },
+    progressTrack: {
+      marginTop: 6,
+      height: 3,
+      borderRadius: radius.full,
+      backgroundColor: 'rgba(255,255,255,0.25)',
+      overflow: 'hidden',
+    },
+    progressFill: {
+      height: '100%',
+      backgroundColor: c.primaryForeground,
+    },
+    cancelButton: {
+      paddingHorizontal: spacing.md,
+      paddingVertical: 6,
+      borderRadius: radius.sm,
+      backgroundColor: 'rgba(255,255,255,0.2)',
+    },
+    cancelText: { ...typography.captionMedium, color: c.primaryForeground },
+    dismiss: { padding: 4 },
+  });
+}

src/components/RichTextEditor.tsx

@@ -263,20 +263,30 @@ function buildEditorHtml(opts: {
     },
     insertLink: function (url, label) {
       editor.focus();
+      // Reject anything that isn't a safe scheme or an absolute path, so the
+      // user can't accidentally (or via a malicious paste) ship a
+      // javascript:/data: link to their recipient.
+      var safeSchemeRe = /^(https?:|mailto:|tel:|sms:|\/|\?|#)/i;
+      var trimmed = (url || '').trim();
+      if (!trimmed || !safeSchemeRe.test(trimmed)) return;
       var sel = window.getSelection();
       var hasSelection = sel && sel.rangeCount && !sel.getRangeAt(0).collapsed;
       if (hasSelection) {
-        try { document.execCommand('createLink', false, url); } catch (e) {}
+        try { document.execCommand('createLink', false, trimmed); } catch (e) {}
         // execCommand doesn't set rel; tag every anchor that points at this URL.
         Array.prototype.forEach.call(editor.getElementsByTagName('a'), function (a) {
-          if (a.getAttribute('href') === url) {
+          if (a.getAttribute('href') === trimmed) {
             a.setAttribute('rel', 'noopener noreferrer nofollow');
           }
         });
       } else {
-        var text = label && label.trim() ? label : url;
+        var text = label && label.trim() ? label : trimmed;
         var safe = text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-        var safeUrl = url.replace(/"/g, '&quot;');
+        var safeUrl = trimmed
+          .replace(/&/g, '&amp;')
+          .replace(/"/g, '&quot;')
+          .replace(/</g, '&lt;')
+          .replace(/>/g, '&gt;');
         var html = '<a href="' + safeUrl + '" rel="noopener noreferrer nofollow">' + safe + '</a>';
         try { document.execCommand('insertHTML', false, html); } catch (e) {}
       }
@@ -409,7 +419,7 @@ const RichTextEditor = React.forwardRef<RichTextEditorHandle, Props>(function Ri
     <View style={[styles.container, { height }]}>
       <WebView
         ref={webViewRef}
-        originWhitelist={['about:*']}
+        originWhitelist={['about:blank']}
         source={{ html }}
         onMessage={onMessage}
         javaScriptEnabled
@@ -433,9 +443,11 @@ const RichTextEditor = React.forwardRef<RichTextEditorHandle, Props>(function Ri
         style={styles.webview}
         containerStyle={styles.webviewContainer}
         onShouldStartLoadWithRequest={(request) => {
-          // Allow only the initial about:blank doc + data URIs we emit ourselves.
+          // Allow only the initial about:blank doc + data URIs we emit
+          // ourselves. Reject `about:*` (e.g. about:srcdoc) and every other
+          // scheme so a paste-injected anchor can't navigate the editor.
           const url = request.url;
-          return !url || url === 'about:blank' || url.startsWith('data:') || url.startsWith('about:');
+          return !url || url === 'about:blank' || url.startsWith('data:');
         }}
       />
     </View>

src/components/SidebarDrawer.tsx

@@ -487,7 +487,9 @@ function makeStyles(c: ThemePalette) {
     top: 0, bottom: 0, left: 0,
     width: '85%',
     maxWidth: 340,
-    backgroundColor: '#262626', // matches webmail bg-secondary (dark mode)
+    // Mirror webmail's bg-secondary in both palettes - was hardcoded to the
+    // dark-mode value, which left light mode unreadable (dark bg + dark text).
+    backgroundColor: c.secondary,
     borderRightWidth: 1,
     borderRightColor: c.border,
   },
@@ -537,7 +539,7 @@ function makeStyles(c: ThemePalette) {
     marginHorizontal: spacing.sm,
     marginTop: spacing.xs,
     marginBottom: spacing.sm,
-    backgroundColor: '#1f1f1f',
+    backgroundColor: c.popover,
     borderRadius: radius.md,
     borderWidth: 1,
     borderColor: c.border,

src/components/calendar/CalendarSidebarDrawer.tsx

@@ -191,7 +191,7 @@ function makeStyles(c: ThemePalette) {
     left: 0,
     width: '85%',
     maxWidth: 340,
-    backgroundColor: '#262626',
+    backgroundColor: c.secondary,
     borderRightWidth: 1,
     borderRightColor: c.border,
   },

src/components/contacts/ContactsSidebarDrawer.tsx

@@ -228,7 +228,7 @@ function makeStyles(c: ThemePalette) {
     top: 0, bottom: 0, left: 0,
     width: '85%',
     maxWidth: 340,
-    backgroundColor: '#262626',
+    backgroundColor: c.secondary,
     borderRightWidth: 1,
     borderRightColor: c.border,
   },

src/components/settings/AboutDataSettings.tsx

@@ -1,16 +1,36 @@
 import React, { useEffect, useState } from 'react';
-import { View, Text, StyleSheet, Pressable, Linking, Alert } from 'react-native';
+import { View, Text, StyleSheet, Pressable, Linking, Alert, ActivityIndicator } from 'react-native';
 import Constants from 'expo-constants';
-import { ExternalLink } from 'lucide-react-native';
-import { SettingsSection, SettingItem, ToggleSwitch } from './settings-section';
+import { CloudDownload, ExternalLink } from 'lucide-react-native';
+import { SettingsSection, SettingItem, Select, ToggleSwitch } from './settings-section';
 import Button from '../Button';
 import { spacing, radius, typography, type ThemePalette } from '../../theme/tokens';
 import { useColors } from '../../theme/colors';
 import { useSettingsStore } from '../../stores/settings-store';
+import { useOfflineCacheStore } from '../../stores/offline-cache-store';
+import { runOfflineSync, formatBytes } from '../../lib/offline-sync';
 
 const APP_VERSION = Constants.expoConfig?.version ?? '0.0.0';
 const GIT_COMMIT = (Constants.expoConfig?.extra as { commit?: string } | undefined)?.commit ?? 'dev';
 
+const DAY_OPTIONS = [
+  { value: '1',  label: 'Last 24 hours' },
+  { value: '3',  label: 'Last 3 days' },
+  { value: '7',  label: 'Last 7 days' },
+  { value: '14', label: 'Last 14 days' },
+  { value: '30', label: 'Last 30 days' },
+  { value: '90', label: 'Last 90 days' },
+];
+
+function formatRelativeTime(ms: number | undefined): string {
+  if (!ms) return 'never';
+  const diff = Date.now() - ms;
+  if (diff < 60_000) return 'just now';
+  if (diff < 60 * 60_000) return `${Math.round(diff / 60_000)} min ago`;
+  if (diff < 24 * 60 * 60_000) return `${Math.round(diff / (60 * 60_000))} h ago`;
+  return `${Math.round(diff / (24 * 60 * 60_000))} d ago`;
+}
+
 const DEBUG_CATEGORIES = [
   { id: 'jmap',       label: 'JMAP',       description: 'JMAP request and response logs.' },
   { id: 'auth',       label: 'Auth',       description: 'Authentication and session events.' },
@@ -36,9 +56,36 @@ export function AboutDataSettings() {
   const [syncEnabled, setSyncEnabled] = useState(true);
   const [confirmReset, setConfirmReset] = useState(false);
 
+  const offlineEnabled = useSettingsStore((s) => s.offlineCacheEnabled);
+  const offlineDays = useSettingsStore((s) => s.offlineCacheDays);
+  const updateSetting = useSettingsStore((s) => s.updateSetting);
+  const cacheCount = useOfflineCacheStore((s) => s.totalCount());
+  const cacheBytes = useOfflineCacheStore((s) => s.totalSize());
+  const cacheHydrated = useOfflineCacheStore((s) => s.hydrated);
+  const cacheHydrate = useOfflineCacheStore((s) => s.hydrate);
+  const sync = useOfflineCacheStore((s) => s.sync);
+  const clearAllCache = useOfflineCacheStore((s) => s.clearAll);
+  const syncBusy = sync.phase === 'scanning' || sync.phase === 'fetching';
+
   useEffect(() => {
     if (!hydrated) void hydrate();
-  }, [hydrated, hydrate]);
+    if (!cacheHydrated) void cacheHydrate();
+  }, [hydrated, hydrate, cacheHydrated, cacheHydrate]);
+
+  const handleSyncNow = () => {
+    void runOfflineSync({ days: offlineDays });
+  };
+
+  const handleClearCache = () => {
+    Alert.alert(
+      'Clear offline mail',
+      `Remove ${cacheCount} cached message${cacheCount === 1 ? '' : 's'} (${formatBytes(cacheBytes)})?`,
+      [
+        { text: 'Cancel', style: 'cancel' },
+        { text: 'Clear', style: 'destructive', onPress: () => { void clearAllCache(); } },
+      ],
+    );
+  };
 
   const handleReset = () => {
     resetExternalContentPolicy('ask');
@@ -72,6 +119,80 @@ export function AboutDataSettings() {
         </View>
       </View>
 
+      <SettingsSection
+        title="Offline mail"
+        description="Download recent messages so they open instantly and remain readable without a connection. Bodies only — attachments are still fetched on demand."
+      >
+        <SettingItem
+          label="Cache recent mail"
+          description="When on, the app keeps message bodies for the selected window on this device."
+        >
+          <ToggleSwitch
+            checked={offlineEnabled}
+            onChange={(v) => updateSetting('offlineCacheEnabled', v)}
+          />
+        </SettingItem>
+        <SettingItem
+          label="Window"
+          description="How far back to cache, measured by message receipt date."
+        >
+          <Select
+            value={String(offlineDays)}
+            onChange={(v) => updateSetting('offlineCacheDays', Number(v))}
+            options={DAY_OPTIONS}
+          />
+        </SettingItem>
+
+        <View style={styles.cacheStatsBox}>
+          <View style={styles.cacheStatsHeader}>
+            <CloudDownload size={16} color={c.textSecondary} />
+            <Text style={styles.cacheStatsTitle}>
+              {cacheCount === 0
+                ? 'Nothing cached yet'
+                : `${cacheCount} message${cacheCount === 1 ? '' : 's'} • ${formatBytes(cacheBytes)}`}
+            </Text>
+          </View>
+          <Text style={styles.cacheStatsSub}>
+            {sync.phase === 'fetching'
+              ? `Downloading ${sync.completed}/${sync.total}…`
+              : sync.phase === 'scanning'
+                ? 'Scanning recent mail…'
+                : sync.phase === 'error'
+                  ? `Last sync failed: ${sync.message ?? 'unknown error'}`
+                  : `Last sync ${formatRelativeTime(sync.finishedAt)}`}
+          </Text>
+          {syncBusy && sync.total > 0 && (
+            <View style={styles.progressTrack}>
+              <View
+                style={[
+                  styles.progressFill,
+                  { width: `${Math.min(100, Math.round((sync.completed / sync.total) * 100))}%` },
+                ]}
+              />
+            </View>
+          )}
+          <View style={styles.cacheActions}>
+            <Button
+              variant="outline"
+              size="sm"
+              onPress={handleSyncNow}
+              disabled={!offlineEnabled || syncBusy}
+              icon={syncBusy ? <ActivityIndicator size="small" color={c.text} /> : undefined}
+            >
+              {syncBusy ? 'Syncing…' : 'Sync now'}
+            </Button>
+            <Button
+              variant="outline"
+              size="sm"
+              onPress={handleClearCache}
+              disabled={cacheCount === 0 || syncBusy}
+            >
+              Clear cache
+            </Button>
+          </View>
+        </View>
+      </SettingsSection>
+
       <SettingsSection title="Advanced" description="Low-level options and troubleshooting.">
         <SettingItem label="Debug mode" description="Enable verbose logging for support and development.">
           <ToggleSwitch checked={debugMode} onChange={setDebugMode} />
@@ -170,5 +291,29 @@ function makeStyles(c: ThemePalette) {
     color: c.mutedForeground,
     marginBottom: spacing.sm,
   },
+  cacheStatsBox: {
+    marginTop: spacing.md,
+    padding: spacing.md,
+    borderRadius: radius.md,
+    borderWidth: 1,
+    borderColor: c.border,
+    backgroundColor: c.muted,
+    gap: spacing.sm,
+  },
+  cacheStatsHeader: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm,
+  },
+  cacheStatsTitle: { ...typography.bodyMedium, color: c.text, flex: 1 },
+  cacheStatsSub: { ...typography.caption, color: c.mutedForeground },
+  progressTrack: {
+    height: 4,
+    borderRadius: radius.full,
+    backgroundColor: c.border,
+    overflow: 'hidden',
+  },
+  progressFill: { height: '100%', backgroundColor: c.primary },
+  cacheActions: { flexDirection: 'row', gap: spacing.sm, marginTop: 4 },
 });
 }

src/components/settings/AccountSecuritySettings.tsx

@@ -1,11 +1,18 @@
-import React, { useState } from 'react';
-import { View, Text, StyleSheet, Pressable } from 'react-native';
-import { Key, Smartphone, Lock, Eye, EyeOff, Shield, Monitor, Trash2 } from 'lucide-react-native';
+import React, { useEffect, useState } from 'react';
+import { Alert, View, Text, StyleSheet, Pressable } from 'react-native';
+import { Key, Smartphone, Lock, Eye, EyeOff, ShieldCheck, Monitor, Trash2 } from 'lucide-react-native';
 import { SettingsSection, SettingItem, ToggleSwitch } from './settings-section';
 import Input from '../Input';
 import Button from '../Button';
 import { spacing, radius, typography, type ThemePalette } from '../../theme/tokens';
 import { useColors } from '../../theme/colors';
+import { jmapClient } from '../../api/jmap-client';
+import {
+  clearClientCertAlias,
+  getClientCertAlias,
+  isClientCertSupported,
+  pickClientCertAlias,
+} from '../../lib/client-cert';
 
 interface Session {
   id: string;
@@ -30,8 +37,96 @@ export function AccountSecuritySettings() {
   const [twoFactor, setTwoFactor] = useState(false);
   const [appPwds] = useState<{ id: string; label: string; created: string }[]>([]);
 
+  const certSupported = isClientCertSupported();
+  const [certAlias, setCertAlias] = useState<string | null>(null);
+  const [certBusy, setCertBusy] = useState(false);
+
+  useEffect(() => {
+    if (!certSupported) return;
+    void getClientCertAlias().then(setCertAlias);
+  }, [certSupported]);
+
+  const onPickCert = async () => {
+    if (certBusy) return;
+    setCertBusy(true);
+    try {
+      // Hint the picker with the JMAP server host so it can pre-filter to certs
+      // issued for it when the OEM picker honours that.
+      const host = jmapClient.serverUrl ? new URL(jmapClient.serverUrl).hostname : null;
+      const alias = await pickClientCertAlias(host);
+      setCertAlias(alias);
+    } catch (err) {
+      Alert.alert('Pick failed', err instanceof Error ? err.message : String(err));
+    } finally {
+      setCertBusy(false);
+    }
+  };
+
+  const onClearCert = async () => {
+    if (certBusy) return;
+    Alert.alert(
+      'Stop using client certificate?',
+      'New requests will no longer present a certificate. The certificate stays installed in Android.',
+      [
+        { text: 'Cancel', style: 'cancel' },
+        {
+          text: 'Clear',
+          style: 'destructive',
+          onPress: async () => {
+            setCertBusy(true);
+            try {
+              await clearClientCertAlias();
+              setCertAlias(null);
+            } finally {
+              setCertBusy(false);
+            }
+          },
+        },
+      ],
+    );
+  };
+
   return (
     <View style={styles.container}>
+      {certSupported && (
+        <SettingsSection
+          title="TLS client certificate"
+          description="Picks an installed Android certificate to authenticate to the server during the TLS handshake. Useful when the reverse proxy enforces mTLS."
+        >
+          <View style={styles.certRow}>
+            <ShieldCheck size={18} color={certAlias ? c.success : c.mutedForeground} />
+            <View style={{ flex: 1 }}>
+              <Text style={styles.certStatus}>
+                {certAlias ? `Active: ${certAlias}` : 'Not set'}
+              </Text>
+              <Text style={styles.certHint}>
+                Install the certificate via Android Settings → Security → Encryption &amp; credentials, then pick it here.
+              </Text>
+            </View>
+          </View>
+          <View style={styles.certActions}>
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={certBusy}
+              onPress={() => { void onPickCert(); }}
+            >
+              {certAlias ? 'Choose another' : 'Pick certificate'}
+            </Button>
+            {certAlias && (
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={certBusy}
+                onPress={() => { void onClearCert(); }}
+              >
+                Clear
+              </Button>
+            )}
+          </View>
+        </SettingsSection>
+      )}
+
       <SettingsSection title="Password" description="Change the password for this account.">
         <View style={{ gap: spacing.md }}>
           <View style={styles.pwField}>
@@ -196,5 +291,14 @@ function makeStyles(c: ThemePalette) {
     justifyContent: 'center',
     borderRadius: radius.sm,
   },
+  certRow: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: spacing.md,
+    paddingVertical: spacing.md,
+  },
+  certStatus: { ...typography.bodyMedium, color: c.text },
+  certHint: { ...typography.caption, color: c.mutedForeground, marginTop: 4 },
+  certActions: { flexDirection: 'row', gap: spacing.sm, flexWrap: 'wrap' },
 });
 }

src/components/settings/NotificationSettings.tsx

@@ -17,9 +17,10 @@ import { useSettingsStore, type NotificationSound } from '../../stores/settings-
 import {
   DEFAULT_RELAY_BASE_URL,
   getStoredRelayBaseUrl,
+  readPushAccountIds,
   setStoredRelayBaseUrl,
   setupPushNotifications,
-  teardownPushNotifications,
+  teardownPushNotificationsForAccount,
 } from '../../lib/push-notifications';
 
 const SOUNDS: { value: NotificationSound; label: string }[] = [
@@ -40,6 +41,7 @@ export function NotificationSettings() {
   const c = useColors();
   const styles = React.useMemo(() => makeStyles(c), [c]);
   const username = useAuthStore((s) => s.username);
+  const activeAccountId = useAuthStore((s) => s.activeAccountId);
 
   const hydrated = useSettingsStore((s) => s.hydrated);
   const hydrate = useSettingsStore((s) => s.hydrate);
@@ -106,10 +108,20 @@ export function NotificationSettings() {
     setConfirmDisable(false);
     setPushStatus({ kind: 'busy', message: 'Disabling…' });
     try {
-      await teardownPushNotifications();
-      await setStoredRelayBaseUrl(null);
-      setRelayUrl(DEFAULT_RELAY_BASE_URL);
-      setHasSaved(false);
+      if (activeAccountId) {
+        await teardownPushNotificationsForAccount(activeAccountId);
+      }
+      // The relay base URL is a device-wide setting shared with any other
+      // accounts that are still using push. Only clear it (and reset the UI
+      // to "not configured") when no accounts are using push any more —
+      // otherwise the remaining accounts would lose their relay URL and
+      // their next setup attempt would no-op.
+      const remaining = await readPushAccountIds();
+      if (remaining.length === 0) {
+        await setStoredRelayBaseUrl(null);
+        setRelayUrl(DEFAULT_RELAY_BASE_URL);
+        setHasSaved(false);
+      }
       setPushStatus({ kind: 'idle' });
     } catch (error) {
       setPushStatus({

src/lib/capabilities.ts

@@ -0,0 +1,35 @@
+import { CAPABILITIES } from '../api/types';
+import { useAuthStore } from '../stores/auth-store';
+
+// When the session is null (cold start, offline restore) we assume features
+// are available so they don't flicker off mid-restore. Once the live session
+// arrives, the real capability set takes over.
+function sessionHasCapability(capability: string): boolean {
+  const session = useAuthStore.getState().session;
+  if (!session) return true;
+  return capability in session.capabilities;
+}
+
+export function hasCalendarCapability(): boolean {
+  return sessionHasCapability(CAPABILITIES.CALENDARS);
+}
+
+export function hasContactsCapability(): boolean {
+  return sessionHasCapability(CAPABILITIES.CONTACTS);
+}
+
+export function hasFilesCapability(): boolean {
+  return sessionHasCapability(CAPABILITIES.FILES);
+}
+
+export function useHasCalendar(): boolean {
+  return useAuthStore((s) => (s.session ? CAPABILITIES.CALENDARS in s.session.capabilities : true));
+}
+
+export function useHasContacts(): boolean {
+  return useAuthStore((s) => (s.session ? CAPABILITIES.CONTACTS in s.session.capabilities : true));
+}
+
+export function useHasFiles(): boolean {
+  return useAuthStore((s) => (s.session ? CAPABILITIES.FILES in s.session.capabilities : true));
+}

src/lib/client-cert.ts

@@ -0,0 +1,185 @@
+// Bridge to the native BulwarkClientCert module. Wraps the alias pick / get /
+// clear flow and exposes a `secureFetch` that mirrors the global `fetch` API
+// closely enough that callers can swap them out.
+//
+// On non-Android platforms (or when the user has not picked a cert) we fall
+// straight back to the global `fetch` so we don't pay any bridge overhead.
+
+type Native = {
+  getAlias(): Promise<string | null>;
+  pickAlias(host: string | null): Promise<string | null>;
+  clearAlias(): Promise<void>;
+  fetchSecure(request: {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    bodyBase64: string | null;
+    timeoutMs: number;
+  }): Promise<{
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    bodyBase64: string;
+  }>;
+};
+
+// Lazy-loaded so unit tests (which run in plain Node) don't have to parse the
+// `react-native` entry point. We resolve the module on first access; the
+// result is cached by the require cache.
+let nativeProbed = false;
+let nativeModule: Native | null = null;
+
+function getNative(): Native | null {
+  if (nativeProbed) return nativeModule;
+  nativeProbed = true;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const rn = require('react-native') as {
+      Platform: { OS: string };
+      NativeModules: Record<string, unknown>;
+    };
+    if (rn.Platform.OS !== 'android') return (nativeModule = null);
+    nativeModule = (rn.NativeModules.BulwarkClientCert as Native | undefined) ?? null;
+  } catch {
+    nativeModule = null;
+  }
+  return nativeModule;
+}
+
+// Cached so the hot path can short-circuit without a bridge round-trip.
+let cachedAlias: string | null | undefined;
+
+export function isClientCertSupported(): boolean {
+  return getNative() != null;
+}
+
+export async function getClientCertAlias(): Promise<string | null> {
+  const native = getNative();
+  if (!native) return null;
+  if (cachedAlias !== undefined) return cachedAlias;
+  cachedAlias = await native.getAlias();
+  return cachedAlias;
+}
+
+export async function pickClientCertAlias(host: string | null): Promise<string | null> {
+  const native = getNative();
+  if (!native) throw new Error('Client certificates require Android');
+  const alias = await native.pickAlias(host);
+  cachedAlias = alias;
+  return alias;
+}
+
+export async function clearClientCertAlias(): Promise<void> {
+  const native = getNative();
+  if (!native) return;
+  await native.clearAlias();
+  cachedAlias = null;
+}
+
+// ── secureFetch ───────────────────────────────────────────────
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let bin = '';
+  const chunk = 0x8000;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    bin += String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + chunk)));
+  }
+  return globalThis.btoa ? globalThis.btoa(bin) : btoa(bin);
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  const bin = globalThis.atob ? globalThis.atob(b64) : atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function bodyToBase64(body: BodyInit | null | undefined): Promise<string | null> {
+  if (body == null) return null;
+  if (typeof body === 'string') {
+    // UTF-8 encode then base64.
+    const encoder = new TextEncoder();
+    return bytesToBase64(encoder.encode(body));
+  }
+  if (body instanceof ArrayBuffer) {
+    return bytesToBase64(new Uint8Array(body));
+  }
+  if (ArrayBuffer.isView(body)) {
+    const view = body as ArrayBufferView;
+    return bytesToBase64(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+  }
+  // Blob / FormData / URLSearchParams / ReadableStream are not used in the
+  // current code paths. If they appear, the caller should pre-serialize.
+  throw new Error(`secureFetch: unsupported body type ${(body as object).constructor?.name}`);
+}
+
+function flattenHeaders(input: HeadersInit | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!input) return out;
+  if (Array.isArray(input)) {
+    for (const [k, v] of input) out[k] = v;
+    return out;
+  }
+  if (typeof Headers !== 'undefined' && input instanceof Headers) {
+    input.forEach((v, k) => { out[k] = v; });
+    return out;
+  }
+  return { ...(input as Record<string, string>) };
+}
+
+function buildResponse(raw: {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  bodyBase64: string;
+}): Response {
+  const bytes = raw.bodyBase64 ? base64ToBytes(raw.bodyBase64) : new Uint8Array(0);
+  const blob = new Blob([bytes as unknown as BlobPart]);
+  return new Response(blob, {
+    status: raw.status,
+    statusText: raw.statusText,
+    headers: raw.headers,
+  });
+}
+
+/**
+ * Drop-in replacement for `fetch` that routes through the native client when
+ * the user has selected a client certificate. When no cert is set (or we're
+ * on iOS), it just calls the platform `fetch` and the caller pays no
+ * bridge overhead.
+ */
+export async function secureFetch(
+  url: string,
+  init?: RequestInit,
+): Promise<Response> {
+  const native = getNative();
+  if (!native) return fetch(url, init);
+  const alias = await getClientCertAlias();
+  if (!alias) return fetch(url, init);
+
+  const method = init?.method ?? 'GET';
+  const headers = flattenHeaders(init?.headers);
+  const bodyBase64 = await bodyToBase64(init?.body);
+  // Force Content-Length to come from the body bytes - some servers (Stalwart
+  // behind nginx in particular) reject chunked uploads when an explicit
+  // length isn't provided alongside the bytes.
+  if (bodyBase64 != null) {
+    const decoded = base64ToBytes(bodyBase64);
+    headers['Content-Length'] = String(decoded.byteLength);
+  }
+  try {
+    const raw = await native.fetchSecure({
+      url,
+      method,
+      headers,
+      bodyBase64,
+      timeoutMs: 30_000,
+    });
+    return buildResponse(raw);
+  } catch (err) {
+    // Surface as a TypeError to mimic fetch's network-error contract; keep
+    // the original message for diagnostics.
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new TypeError(`secureFetch failed: ${msg}`);
+  }
+}

src/lib/email-export.ts

@@ -1,7 +1,8 @@
-import { File, Paths } from 'expo-file-system';
+import { Directory, File, Paths } from 'expo-file-system';
 import * as Sharing from 'expo-sharing';
 import { jmapClient } from '../api/jmap-client';
 import { getDownloadUrl } from '../api/blob';
+import { getClientCertAlias, secureFetch } from './client-cert';
 
 const RFC822 = 'message/rfc822';
 
@@ -21,6 +22,40 @@ function safeAttachmentName(name: string | undefined, type: string | undefined):
 // itself with its bundled SharingFileProvider before launching the share
 // intent, so we must NOT pre-translate to `file.contentUri`.
 
+// Routes the download via the client-cert-aware native module when the user
+// has picked a cert, and via expo-file-system's native streaming downloader
+// otherwise. The streaming path scales to large attachments without buffering
+// in JS, so we keep using it as the default.
+async function downloadInto(
+  url: string,
+  dest: File,
+  parent: Directory,
+): Promise<File> {
+  const alias = await getClientCertAlias();
+  if (!alias) {
+    // The static returns a separately-typed `FileSystemFile`; we already
+    // have a fully-typed `File` referencing the same uri, so we ignore the
+    // return value and re-use our `dest` reference for downstream code.
+    await File.downloadFileAsync(url, dest, {
+      headers: { Authorization: authHeader() },
+      idempotent: true,
+    });
+    return dest;
+  }
+  const response = await secureFetch(url, {
+    headers: { Authorization: authHeader() },
+  });
+  if (!response.ok) {
+    throw new Error(`Download failed: ${response.status}`);
+  }
+  if (!parent.exists) parent.create({ intermediates: true, idempotent: true });
+  if (dest.exists) dest.delete();
+  const buffer = await response.arrayBuffer();
+  dest.create();
+  dest.write(new Uint8Array(buffer));
+  return dest;
+}
+
 export async function shareAttachment(
   blobId: string,
   name: string | undefined,
@@ -30,10 +65,7 @@ export async function shareAttachment(
   const mimeType = type || 'application/octet-stream';
   const dest = new File(Paths.cache, filename);
   const url = getDownloadUrl(blobId, filename, mimeType);
-  const downloaded = await File.downloadFileAsync(url, dest, {
-    headers: { Authorization: authHeader() },
-    idempotent: true,
-  });
+  const downloaded = await downloadInto(url, dest, Paths.cache);
   if (!(await Sharing.isAvailableAsync())) {
     throw new Error('Sharing is not available on this device');
   }
@@ -57,10 +89,7 @@ export async function downloadAttachment(
   const mimeType = type || 'application/octet-stream';
   const dest = new File(Paths.document, filename);
   const url = getDownloadUrl(blobId, filename, mimeType);
-  const downloaded = await File.downloadFileAsync(url, dest, {
-    headers: { Authorization: authHeader() },
-    idempotent: true,
-  });
+  const downloaded = await downloadInto(url, dest, Paths.document);
   if (!(await Sharing.isAvailableAsync())) {
     throw new Error('Sharing is not available on this device');
   }
@@ -72,7 +101,7 @@ export async function downloadAttachment(
 
 export async function fetchRawEmail(blobId: string): Promise<string> {
   const url = getDownloadUrl(blobId, 'email.eml', RFC822);
-  const r = await fetch(url, { headers: { Authorization: authHeader() } });
+  const r = await secureFetch(url, { headers: { Authorization: authHeader() } });
   if (!r.ok) throw new Error(`Download failed: ${r.status}`);
   return r.text();
 }
@@ -85,10 +114,7 @@ function safeFilename(subject: string | undefined): string {
 export async function shareEmailEml(blobId: string, subject?: string): Promise<void> {
   const dest = new File(Paths.cache, safeFilename(subject));
   const url = getDownloadUrl(blobId, dest.name, RFC822);
-  const downloaded = await File.downloadFileAsync(url, dest, {
-    headers: { Authorization: authHeader() },
-    idempotent: true,
-  });
+  const downloaded = await downloadInto(url, dest, Paths.cache);
   if (!(await Sharing.isAvailableAsync())) {
     throw new Error('Sharing is not available on this device');
   }

src/lib/install-update.ts

@@ -3,12 +3,18 @@ import { File, Paths } from 'expo-file-system';
 import * as FileSystemLegacy from 'expo-file-system/legacy';
 import * as IntentLauncher from 'expo-intent-launcher';
 import type { ReleaseAsset } from '../api/updates';
+import { Sha256 } from './sha256';
 
 const FLAG_GRANT_READ_URI_PERMISSION = 0x00000001;
 const FLAG_ACTIVITY_NEW_TASK = 0x10000000;
 
+// Bytes per file-read chunk while computing the post-download SHA-256. Larger
+// chunks are faster but balloon the JS string buffer (base64 reads on this
+// platform). 256 KiB keeps memory bounded while still amortising the bridge.
+const HASH_CHUNK_BYTES = 256 * 1024;
+
 export interface InstallProgress {
-  phase: 'downloading' | 'installing';
+  phase: 'downloading' | 'verifying' | 'installing';
   /** 0-1 during download; undefined for installing phase */
   progress?: number;
   /** Bytes received during current download */
@@ -19,10 +25,51 @@ export interface InstallProgress {
 
 export type InstallProgressListener = (p: InstallProgress) => void;
 
+export interface InstallParams {
+  asset: ReleaseAsset;
+  /** Optional lower-case hex SHA-256. When present, mismatched downloads abort. */
+  expectedSha256?: string | null;
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  const bin = globalThis.atob ? globalThis.atob(b64) : atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function hashFile(uri: string, totalBytes: number, onProgress?: InstallProgressListener): Promise<string> {
+  const hasher = new Sha256();
+  let offset = 0;
+  while (offset < totalBytes || totalBytes === 0) {
+    const length = Math.min(HASH_CHUNK_BYTES, totalBytes ? totalBytes - offset : HASH_CHUNK_BYTES);
+    const chunkB64 = await FileSystemLegacy.readAsStringAsync(uri, {
+      encoding: FileSystemLegacy.EncodingType.Base64,
+      position: offset,
+      length,
+    });
+    if (!chunkB64) break;
+    const bytes = base64ToBytes(chunkB64);
+    if (bytes.length === 0) break;
+    hasher.update(bytes);
+    offset += bytes.length;
+    if (totalBytes > 0) {
+      onProgress?.({ phase: 'verifying', progress: offset / totalBytes });
+    }
+    if (bytes.length < length) break;
+  }
+  return hasher.digestHex();
+}
+
 export async function downloadAndInstallApk(
-  asset: ReleaseAsset,
+  params: InstallParams | ReleaseAsset,
   onProgress?: InstallProgressListener,
 ): Promise<void> {
+  // Backwards-compat: callers used to pass the asset directly. Promote to the
+  // params shape so the verification path is opt-in by passing a checksum.
+  const { asset, expectedSha256 }: InstallParams =
+    'asset' in params ? params : { asset: params, expectedSha256: null };
+
   if (Platform.OS !== 'android') {
     throw new Error('APK install is only supported on Android');
   }
@@ -53,6 +100,33 @@ export async function downloadAndInstallApk(
     throw new Error('APK download failed');
   }
 
+  // Size sanity check. GitHub's `assets[].size` is signed by their TLS cert,
+  // so a byte-count mismatch is a strong signal the file was truncated /
+  // tampered with in transport. Cheap to compute, fail-fast.
+  const info = await FileSystemLegacy.getInfoAsync(result.uri);
+  const actualSize = (info as { size?: number }).size ?? 0;
+  if (asset.size > 0 && actualSize !== asset.size) {
+    await tryDelete(result.uri);
+    throw new Error(
+      `APK size mismatch: expected ${asset.size} bytes, got ${actualSize}`,
+    );
+  }
+
+  // SHA-256 verification when the release publishes one. Without it, we still
+  // get Android's package-signer check at install time — which rejects an APK
+  // signed with a different key — but that fails late (after the user sees a
+  // confusing system dialog). Bailing here surfaces the problem cleanly.
+  if (expectedSha256) {
+    onProgress?.({ phase: 'verifying', progress: 0 });
+    const actual = await hashFile(result.uri, actualSize || asset.size, onProgress);
+    if (actual.toLowerCase() !== expectedSha256.toLowerCase()) {
+      await tryDelete(result.uri);
+      throw new Error(
+        `APK checksum mismatch: expected ${expectedSha256}, got ${actual}`,
+      );
+    }
+  }
+
   onProgress?.({ phase: 'installing' });
 
   const contentUri = await FileSystemLegacy.getContentUriAsync(result.uri);
@@ -64,6 +138,14 @@ export async function downloadAndInstallApk(
   });
 }
 
+async function tryDelete(uri: string): Promise<void> {
+  try {
+    await FileSystemLegacy.deleteAsync(uri, { idempotent: true });
+  } catch {
+    /* best effort */
+  }
+}
+
 /**
  * Open the system "Install unknown apps" settings page for this app, so the
  * user can grant permission to install APKs from the package installer.

src/lib/oauth.ts

@@ -0,0 +1,166 @@
+import * as WebBrowser from 'expo-web-browser';
+import { secureFetch } from './client-cert';
+
+// Webmail-mediated login. The app opens the webmail's normal login page with
+// extra `mobile_redirect_uri` and `mobile_state` query params. The webmail
+// uses its existing password and OAuth flows, and once the user is signed
+// in, redirects back to the app's custom scheme with credentials packed into
+// the URL fragment. Fragments aren't sent to the server, so password and
+// token material don't appear in HTTP access logs along the way.
+
+export const HANDOFF_REDIRECT_URI = 'bulwarkmobile://auth/callback';
+
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number; // epoch ms
+  tokenEndpoint: string;
+  clientId: string;
+}
+
+export type HandoffResult =
+  | {
+      flow: 'password';
+      serverUrl: string;
+      username: string;
+      password: string;
+    }
+  | {
+      flow: 'oauth';
+      serverUrl: string;
+      tokens: OAuthTokens;
+    };
+
+export class HandoffError extends Error {}
+export class HandoffCancelledError extends HandoffError {
+  constructor() {
+    super('Sign-in cancelled');
+  }
+}
+
+function randomState(): string {
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  let s = '';
+  for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s;
+}
+
+function buildHandoffUrl(webmailUrl: string, state: string): string {
+  const base = webmailUrl.replace(/\/+$/, '');
+  const params = new URLSearchParams({
+    mobile_redirect_uri: HANDOFF_REDIRECT_URI,
+    mobile_state: state,
+  });
+  return `${base}/login?${params.toString()}`;
+}
+
+function parseFragment(url: string): URLSearchParams {
+  const hashIdx = url.indexOf('#');
+  if (hashIdx === -1) return new URLSearchParams();
+  return new URLSearchParams(url.slice(hashIdx + 1));
+}
+
+export async function runWebmailHandoff(webmailUrl: string): Promise<HandoffResult> {
+  const state = randomState();
+  const handoffUrl = buildHandoffUrl(webmailUrl, state);
+
+  const result = await WebBrowser.openAuthSessionAsync(handoffUrl, HANDOFF_REDIRECT_URI);
+
+  if (result.type === 'cancel' || result.type === 'dismiss') {
+    throw new HandoffCancelledError();
+  }
+  if (result.type !== 'success' || !result.url) {
+    throw new HandoffError(`Sign-in failed: ${result.type}`);
+  }
+
+  const params = parseFragment(result.url);
+  const err = params.get('error');
+  if (err) throw new HandoffError(err);
+
+  // CSRF guard: the state we generated must round-trip through the webmail
+  // unchanged. A mismatch means the redirect didn't come from the flow we
+  // started, and the rest of the fragment shouldn't be trusted.
+  if (params.get('state') !== state) {
+    throw new HandoffError('State mismatch');
+  }
+
+  const flow = params.get('flow');
+  const serverUrl = params.get('server_url');
+  if (!serverUrl) throw new HandoffError('Sign-in response missing server URL');
+
+  if (flow === 'password') {
+    const username = params.get('username');
+    const password = params.get('password');
+    if (!username || !password) {
+      throw new HandoffError('Sign-in response missing credentials');
+    }
+    return { flow: 'password', serverUrl, username, password };
+  }
+
+  if (flow === 'oauth') {
+    const accessToken = params.get('access_token');
+    const tokenEndpoint = params.get('token_endpoint');
+    const clientId = params.get('client_id');
+    if (!accessToken || !tokenEndpoint || !clientId) {
+      throw new HandoffError('Sign-in response missing OAuth tokens');
+    }
+    const refreshToken = params.get('refresh_token') ?? undefined;
+    const expiresIn = params.get('expires_in');
+    return {
+      flow: 'oauth',
+      serverUrl,
+      tokens: {
+        accessToken,
+        refreshToken,
+        expiresAt: expiresIn ? Date.now() + parseInt(expiresIn, 10) * 1000 : undefined,
+        tokenEndpoint,
+        clientId,
+      },
+    };
+  }
+
+  throw new HandoffError(`Unknown sign-in flow: ${flow ?? 'missing'}`);
+}
+
+// OAuth refresh — exchanges the refresh token at the original token endpoint
+// for a new access token. Returns the updated bundle so the caller can
+// persist it.
+export async function refreshOAuthAccessToken(tokens: OAuthTokens): Promise<OAuthTokens> {
+  if (!tokens.refreshToken) {
+    throw new HandoffError('No refresh token available');
+  }
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: tokens.refreshToken,
+    client_id: tokens.clientId,
+  });
+  const response = await secureFetch(tokens.tokenEndpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: body.toString(),
+  });
+  if (!response.ok) {
+    throw new HandoffError(`Token refresh failed: ${response.status}`);
+  }
+  const data = (await response.json()) as {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+  };
+  if (!data.access_token) {
+    throw new HandoffError('Token refresh response missing access_token');
+  }
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token ?? tokens.refreshToken,
+    expiresAt: data.expires_in ? Date.now() + data.expires_in * 1000 : undefined,
+    tokenEndpoint: tokens.tokenEndpoint,
+    clientId: tokens.clientId,
+  };
+}
+
+WebBrowser.maybeCompleteAuthSession();

src/lib/offline-sync.ts

@@ -0,0 +1,148 @@
+// Background sync that fills the offline mail cache. Runs the discovery
+// query (Email/query filtered by `after`), then fetches full bodies in
+// batches, reporting progress to the offline-cache-store so the
+// OfflineCacheBanner and the Settings screen can show live updates.
+
+import { jmapClient } from '../api/jmap-client';
+import { queryEmailsByFilter, getFullEmails } from '../api/email';
+import { useOfflineCacheStore } from '../stores/offline-cache-store';
+import type { Email } from '../api/types';
+
+// Approximate the on-disk size of a serialised Email so we can show "Y MB
+// downloaded" without measuring AsyncStorage usage. Body values dominate; the
+// envelope is small. Using JSON.stringify().length is correct in code-units
+// not bytes, but it's close enough for a UI-facing estimate.
+function approxSize(email: Email): number {
+  try {
+    return JSON.stringify(email).length;
+  } catch {
+    return 0;
+  }
+}
+
+// Hard cap so a misconfigured "30 days" against a noisy account doesn't try
+// to enumerate 100k messages.
+const DISCOVERY_LIMIT = 5000;
+// Each Email/get request is bounded by the server's maxObjectsInGet. We
+// further chunk to keep individual responses small (a 50-message response
+// with full bodies + body values is already several MB).
+const FETCH_CHUNK_FALLBACK = 25;
+
+export interface RunOptions {
+  days: number;
+}
+
+export async function runOfflineSync(opts: RunOptions): Promise<void> {
+  const cache = useOfflineCacheStore.getState();
+  // If a sync is in flight, request its abort and wait for the next caller
+  // to start fresh. We don't queue — the most recent intent wins.
+  if (cache.sync.phase === 'scanning' || cache.sync.phase === 'fetching') {
+    cache.requestAbort();
+    return;
+  }
+  if (!cache.hydrated) await cache.hydrate();
+  cache.resetSync();
+
+  const startedAt = Date.now();
+  cache.setSyncState({ phase: 'scanning', startedAt });
+
+  const since = new Date(startedAt - opts.days * 24 * 60 * 60 * 1000).toISOString();
+
+  let ids: string[] = [];
+  try {
+    ids = await queryEmailsByFilter({ after: since }, DISCOVERY_LIMIT);
+  } catch (err) {
+    cache.setSyncState({
+      phase: 'error',
+      message: err instanceof Error ? err.message : 'Discovery query failed',
+      finishedAt: Date.now(),
+    });
+    return;
+  }
+
+  // Drop entries from the cache that fell out of the lookback window — the
+  // user expects the cache to track "the last X days", not grow forever.
+  const keepSet = new Set(ids);
+  const stale = Object.keys(cache.index.entries).filter((id) => !keepSet.has(id));
+  if (stale.length > 0) {
+    await cache.remove(stale);
+  }
+
+  const total = ids.length;
+  cache.setSyncState({ phase: 'fetching', total, completed: 0, fetched: 0, bytes: 0 });
+
+  // Skip already-cached ids — bodies on disk are immutable per messageId.
+  const toFetch = ids.filter((id) => !cache.has(id));
+  const skipped = total - toFetch.length;
+  cache.setSyncState({ completed: skipped });
+
+  if (toFetch.length === 0) {
+    cache.setSyncState({
+      phase: 'done',
+      finishedAt: Date.now(),
+    });
+    return;
+  }
+
+  const chunkSize = Math.min(
+    FETCH_CHUNK_FALLBACK,
+    Math.max(1, jmapClient.getMaxObjectsInGet()),
+  );
+
+  let fetched = 0;
+  let bytes = 0;
+  let completed = skipped;
+
+  for (let i = 0; i < toFetch.length; i += chunkSize) {
+    if (useOfflineCacheStore.getState().consumeAbort()) {
+      cache.setSyncState({
+        phase: 'cancelled',
+        finishedAt: Date.now(),
+      });
+      return;
+    }
+
+    const chunk = toFetch.slice(i, i + chunkSize);
+    let emails: Email[];
+    try {
+      emails = await getFullEmails(chunk);
+    } catch (err) {
+      cache.setSyncState({
+        phase: 'error',
+        message: err instanceof Error ? err.message : 'Fetch failed',
+        finishedAt: Date.now(),
+      });
+      return;
+    }
+
+    for (const email of emails) {
+      const size = approxSize(email);
+      await cache.put(email, size);
+      fetched += 1;
+      bytes += size;
+      completed += 1;
+    }
+
+    // Some chunked ids may have been deleted server-side between query and
+    // fetch — they don't come back. Account for that in the completed count
+    // so the progress bar still finishes at 100%.
+    completed += chunk.length - emails.length;
+
+    cache.setSyncState({ completed, fetched, bytes });
+  }
+
+  cache.setSyncState({
+    phase: 'done',
+    completed: total,
+    fetched,
+    bytes,
+    finishedAt: Date.now(),
+  });
+}
+
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}

src/lib/push-background-task.ts

@@ -8,13 +8,22 @@ import {
   getFaviconDomain,
   getFaviconUrl,
 } from './avatar-utils';
+import {
+  deviceClientIdKey,
+  lastNotifiedKey,
+  migrateLegacyPushKeys,
+  readPushAccountIds,
+} from './push-notifications';
 
-const PUSH_ACCOUNT_ID_KEY = 'push:accountId:v1';
-const LAST_NOTIFIED_EMAIL_ID_KEY = 'push:lastNotifiedEmailId:v1';
 // Mirrors STORAGE_KEY in `stores/settings-store.ts`. The headless task can't
 // import the Zustand store (would pull in React) so we read AsyncStorage
 // directly. Keep this in sync if the store key ever changes.
 const SETTINGS_STORAGE_KEY = 'webmail:settings:v1';
+// Mirrors the persist name in `stores/account-store.ts`. We use it to find
+// the user's active account at the end of the headless task so we can leave
+// the jmapClient singleton in a state consistent with what the UI expects
+// when the app resumes.
+const ACCOUNT_REGISTRY_KEY = 'account-registry';
 
 interface PushPersistedSettings {
   emailNotificationsEnabled?: boolean;
@@ -41,76 +50,151 @@ interface ShowNotificationOptions {
   emailId: string;
   threadId: string;
   subject?: string;
+  accountId: string;
 }
 
 interface BulwarkFcmNative {
   showNotification(opts: ShowNotificationOptions): Promise<void>;
 }
 
+// The relay forwards each JMAP push to FCM tagged with the deviceClientId it
+// received the push on (the URL slot from createPushSubscription). The exact
+// key the relay uses isn't part of any client-controlled contract, so rather
+// than guessing a field name we scan all string values in the data payload
+// and look for one that matches a deviceClientId we've registered locally.
+// Returns null if nothing matches (e.g. legacy relay payload format) so the
+// caller falls back to iterating every known account.
+async function identifyAccountFromFcmData(
+  data: unknown,
+  accountIds: string[],
+): Promise<string | null> {
+  if (!data || typeof data !== 'object') return null;
+
+  const reverseMap = new Map<string, string>();
+  for (const accountId of accountIds) {
+    const dcid = await AsyncStorage.getItem(deviceClientIdKey(accountId));
+    if (dcid) reverseMap.set(dcid, accountId);
+  }
+  if (reverseMap.size === 0) return null;
+
+  for (const value of Object.values(data as Record<string, unknown>)) {
+    if (typeof value === 'string') {
+      const match = reverseMap.get(value);
+      if (match) return match;
+    }
+  }
+  return null;
+}
+
+// Read the persisted active account directly from AsyncStorage (Zustand's
+// persist middleware stores the JSON-serialised state under its `name`).
+async function readActiveAccountId(): Promise<string | null> {
+  try {
+    const raw = await AsyncStorage.getItem(ACCOUNT_REGISTRY_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as { state?: { activeAccountId?: string | null } };
+    return parsed.state?.activeAccountId ?? null;
+  } catch {
+    return null;
+  }
+}
+
 // Fired by BulwarkPushTaskService when a data FCM message arrives. Runs in a
 // short-lived headless JS runtime - keep it fast, catch all errors, and always
 // resolve so the native service can release its wake lock.
-export async function pushBackgroundTask(_data: unknown): Promise<void> {
+export async function pushBackgroundTask(data: unknown): Promise<void> {
+  let activeAccountId: string | null = null;
   try {
     if (!(await emailNotificationsAllowed())) return;
 
-    const accountId = await AsyncStorage.getItem(PUSH_ACCOUNT_ID_KEY);
-    if (!accountId) return;
+    await migrateLegacyPushKeys();
 
-    const loaded = await jmapClient.loadAccount(accountId);
-    if (!loaded) return;
+    const accountIds = await readPushAccountIds();
+    if (accountIds.length === 0) return;
 
-    const mailboxes = await getMailboxes();
-    const inbox = mailboxes.find((m) => m.role === 'inbox');
-    if (!inbox) return;
+    activeAccountId = await readActiveAccountId();
 
-    const { ids } = await queryEmails(inbox.id, {
-      filter: { notKeyword: '$seen' },
-      limit: 1,
-    });
-    if (ids.length === 0) return;
+    const matched = await identifyAccountFromFcmData(data, accountIds);
+    const accountsToCheck = matched ? [matched] : accountIds;
 
-    const emailId = ids[0];
-    const previouslyNotified = await AsyncStorage.getItem(LAST_NOTIFIED_EMAIL_ID_KEY);
-    if (previouslyNotified === emailId) return;
-
-    const [email] = await getEmails([emailId]);
-    if (!email) return;
-
-    const from = email.from?.[0];
-    const name = from?.name ?? '';
-    const address = from?.email ?? '';
-    const title = name || address || 'New mail';
-    const body = email.subject || '(no subject)';
-    const initials = getEmailInitials(name, address);
-    const bgColorHex = hslToHex(generateEmailAvatarColor(name, address));
-    const faviconDomain = getFaviconDomain(address);
-    const iconUrl = faviconDomain ? getFaviconUrl(faviconDomain) : undefined;
-
-    const native = NativeModules.BulwarkFcm as BulwarkFcmNative | undefined;
-    if (!native?.showNotification) return;
-
-    await native.showNotification({
-      notificationId: `mail:${emailId}`,
-      title,
-      body,
-      initials,
-      bgColorHex,
-      iconUrl,
-      emailId,
-      threadId: email.threadId,
-      subject: email.subject ?? undefined,
-    });
-
-    await AsyncStorage.setItem(LAST_NOTIFIED_EMAIL_ID_KEY, emailId);
+    for (const accountId of accountsToCheck) {
+      try {
+        await processAccountForPush(accountId);
+      } catch (err) {
+        console.warn(
+          '[push] background check failed for account',
+          accountId,
+          err instanceof Error ? err.message : err,
+        );
+      }
+    }
   } catch (error) {
     console.warn(
       '[push] background task failed:',
       error instanceof Error ? error.message : error,
     );
+  } finally {
+    // Leave the singleton bound to the user's active account so the UI sees
+    // a consistent jmapClient state when the app resumes. Without this, the
+    // last account processed above would remain loaded and the UI's cached
+    // email-store data would not match what the next JMAP request returns.
+    if (activeAccountId) {
+      await jmapClient.loadAccount(activeAccountId).catch(() => undefined);
+    }
   }
 }
 
+async function processAccountForPush(accountId: string): Promise<void> {
+  const loaded = await jmapClient.loadAccount(accountId);
+  if (!loaded) return;
+
+  const mailboxes = await getMailboxes();
+  const inbox = mailboxes.find((m) => m.role === 'inbox');
+  if (!inbox) return;
+
+  const { ids } = await queryEmails(inbox.id, {
+    filter: { notKeyword: '$seen' },
+    limit: 1,
+  });
+  if (ids.length === 0) return;
+
+  const emailId = ids[0];
+  const lastKey = lastNotifiedKey(accountId);
+  const previouslyNotified = await AsyncStorage.getItem(lastKey);
+  if (previouslyNotified === emailId) return;
+
+  const [email] = await getEmails([emailId]);
+  if (!email) return;
+
+  const from = email.from?.[0];
+  const name = from?.name ?? '';
+  const address = from?.email ?? '';
+  const title = name || address || 'New mail';
+  const body = email.subject || '(no subject)';
+  const initials = getEmailInitials(name, address);
+  const bgColorHex = hslToHex(generateEmailAvatarColor(name, address));
+  const faviconDomain = getFaviconDomain(address);
+  const iconUrl = faviconDomain ? getFaviconUrl(faviconDomain) : undefined;
+
+  const native = NativeModules.BulwarkFcm as BulwarkFcmNative | undefined;
+  if (!native?.showNotification) return;
+
+  await native.showNotification({
+    notificationId: `mail:${emailId}`,
+    title,
+    body,
+    initials,
+    bgColorHex,
+    iconUrl,
+    emailId,
+    threadId: email.threadId,
+    subject: email.subject ?? undefined,
+    accountId,
+  });
+
+  await AsyncStorage.setItem(lastKey, emailId);
+}
+
 function hslToHex(hsl: string): string {
   const match = hsl.match(/hsl\(\s*(\d+)\s*,\s*(\d+)%\s*,\s*(\d+)%\s*\)/);
   if (!match) return '#2563eb';

src/lib/push-notifications.ts

@@ -11,12 +11,88 @@ import { jmapClient } from '../api/jmap-client';
 import { generateAccountId } from './account-utils';
 
 // Persist identifiers across launches so we reuse the same JMAP subscription
-// after app restarts. deviceClientId also routes to the relay slot.
-const DEVICE_CLIENT_ID_KEY = 'push:deviceClientId:v1';
-const SUBSCRIPTION_ID_KEY = 'push:subscriptionId:v1';
+// after app restarts. Each account gets its own deviceClientId so the hosted
+// relay can distinguish per-account pushes via the URL slot it forwards.
 const RELAY_BASE_URL_KEY = 'push:relayBaseUrl:v1';
-const PUSH_ACCOUNT_ID_KEY = 'push:accountId:v1';
-const LAST_NOTIFIED_EMAIL_ID_KEY = 'push:lastNotifiedEmailId:v1';
+const PUSH_ACCOUNT_IDS_KEY = 'push:accountIds:v1';
+const DEVICE_CLIENT_ID_PREFIX = 'push:deviceClientId:v2:';
+const SUBSCRIPTION_ID_PREFIX = 'push:subscriptionId:v2:';
+export const LAST_NOTIFIED_EMAIL_ID_PREFIX = 'push:lastNotifiedEmailId:v2:';
+
+// Legacy single-account keys (pre-multi-account). Migrated lazily on the next
+// setupPushNotifications / pushBackgroundTask call, then deleted.
+const LEGACY_DEVICE_CLIENT_ID_KEY = 'push:deviceClientId:v1';
+const LEGACY_SUBSCRIPTION_ID_KEY = 'push:subscriptionId:v1';
+const LEGACY_PUSH_ACCOUNT_ID_KEY = 'push:accountId:v1';
+const LEGACY_LAST_NOTIFIED_EMAIL_ID_KEY = 'push:lastNotifiedEmailId:v1';
+
+export function deviceClientIdKey(accountId: string): string {
+  return DEVICE_CLIENT_ID_PREFIX + accountId;
+}
+
+function subscriptionIdKey(accountId: string): string {
+  return SUBSCRIPTION_ID_PREFIX + accountId;
+}
+
+export function lastNotifiedKey(accountId: string): string {
+  return LAST_NOTIFIED_EMAIL_ID_PREFIX + accountId;
+}
+
+export async function readPushAccountIds(): Promise<string[]> {
+  const raw = await AsyncStorage.getItem(PUSH_ACCOUNT_IDS_KEY);
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((s): s is string => typeof s === 'string');
+  } catch {
+    return [];
+  }
+}
+
+async function writePushAccountIds(ids: string[]): Promise<void> {
+  const deduped = Array.from(new Set(ids));
+  if (deduped.length === 0) {
+    await AsyncStorage.removeItem(PUSH_ACCOUNT_IDS_KEY);
+  } else {
+    await AsyncStorage.setItem(PUSH_ACCOUNT_IDS_KEY, JSON.stringify(deduped));
+  }
+}
+
+// One-shot migration from the pre-multi-account schema. If the legacy
+// PUSH_ACCOUNT_ID_KEY exists, treat that account as the only pre-existing
+// setup: reuse the legacy deviceClientId and JMAP subscription id under
+// the new per-account keys so the user doesn't lose push on upgrade.
+export async function migrateLegacyPushKeys(): Promise<void> {
+  const legacyAccountId = await AsyncStorage.getItem(LEGACY_PUSH_ACCOUNT_ID_KEY);
+  if (!legacyAccountId) return;
+
+  const legacyDcid = await AsyncStorage.getItem(LEGACY_DEVICE_CLIENT_ID_KEY);
+  const legacySubId = await AsyncStorage.getItem(LEGACY_SUBSCRIPTION_ID_KEY);
+  const legacyLastId = await AsyncStorage.getItem(LEGACY_LAST_NOTIFIED_EMAIL_ID_KEY);
+
+  if (legacyDcid) {
+    await AsyncStorage.setItem(deviceClientIdKey(legacyAccountId), legacyDcid);
+  }
+  if (legacySubId) {
+    await AsyncStorage.setItem(subscriptionIdKey(legacyAccountId), legacySubId);
+  }
+  if (legacyLastId) {
+    await AsyncStorage.setItem(lastNotifiedKey(legacyAccountId), legacyLastId);
+  }
+
+  const ids = await readPushAccountIds();
+  if (!ids.includes(legacyAccountId)) {
+    await writePushAccountIds([...ids, legacyAccountId]);
+  }
+
+  await AsyncStorage.multiRemove([
+    LEGACY_PUSH_ACCOUNT_ID_KEY,
+    LEGACY_DEVICE_CLIENT_ID_KEY,
+    LEGACY_SUBSCRIPTION_ID_KEY,
+    LEGACY_LAST_NOTIFIED_EMAIL_ID_KEY,
+  ]);
+}
 
 // Hosted relay so users don't need to run their own Firebase project. The
 // relay only ever sees FCM tokens + JMAP state-id hashes - no mail content.
@@ -72,11 +148,12 @@ function randomClientId(): string {
   return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
 }
 
-async function getOrCreateDeviceClientId(): Promise<string> {
-  const existing = await AsyncStorage.getItem(DEVICE_CLIENT_ID_KEY);
+async function getOrCreateDeviceClientId(accountId: string): Promise<string> {
+  const key = deviceClientIdKey(accountId);
+  const existing = await AsyncStorage.getItem(key);
   if (existing) return existing;
   const next = randomClientId();
-  await AsyncStorage.setItem(DEVICE_CLIENT_ID_KEY, next);
+  await AsyncStorage.setItem(key, next);
   return next;
 }
 
@@ -184,20 +261,24 @@ export async function setupPushNotifications(
   const fcmToken = await native.getToken();
   if (!fcmToken) throw new Error('FCM token unavailable');
 
-  const deviceClientId = await getOrCreateDeviceClientId();
-  await setStoredRelayBaseUrl(relayBaseUrl);
-
-  // Persist the account id so the background push task can reload credentials
-  // from SecureStore without the main app being running.
+  // setupPushNotifications operates on the currently-loaded jmapClient. We
+  // need its username/serverUrl up-front so we can key per-account state.
   const username = jmapClient.username;
   const serverUrl = jmapClient.serverUrl;
-  if (username && serverUrl) {
-    await AsyncStorage.setItem(
-      PUSH_ACCOUNT_ID_KEY,
-      generateAccountId(username, serverUrl),
-    );
+  if (!username || !serverUrl) {
+    throw new Error('No account loaded - cannot set up push');
   }
+  const accountId = generateAccountId(username, serverUrl);
 
+  await migrateLegacyPushKeys();
+
+  const deviceClientId = await getOrCreateDeviceClientId(accountId);
+  await setStoredRelayBaseUrl(relayBaseUrl);
+
+  // Register this account's device-client-id with the relay. Multiple
+  // accounts on the same device end up as separate registrations sharing
+  // one fcmToken - the relay forwards each push individually so the headless
+  // task can identify the source account via the FCM data payload.
   await registerWithRelay({
     relayBaseUrl,
     subscriptionId: deviceClientId,
@@ -208,26 +289,31 @@ export async function setupPushNotifications(
   // Reuse the previous JMAP subscription when the server still has it, but
   // push the expiry forward so it doesn't time out before the next app start.
   const existingSubs = await listPushSubscriptions().catch(() => []);
-  const storedServerId = await AsyncStorage.getItem(SUBSCRIPTION_ID_KEY);
+  const subKey = subscriptionIdKey(accountId);
+  const storedServerId = await AsyncStorage.getItem(subKey);
   if (storedServerId) {
     const match = existingSubs.find((s) => s.id === storedServerId);
     if (match) {
       const refreshed = await refreshSubscriptionExpires(match);
       if (refreshed) {
+        await addPushAccountId(accountId);
         return { subscriptionId: storedServerId, verified: true };
       }
       // Server rejected the refresh (likely the subscription was already
       // deleted server-side) - drop the stale id and recreate below.
       await destroyPushSubscription(storedServerId).catch(() => undefined);
     }
-    await AsyncStorage.removeItem(SUBSCRIPTION_ID_KEY);
+    await AsyncStorage.removeItem(subKey);
   }
 
-  // Reap any leftover Stalwart subscriptions still bound to this device.
-  // These pile up when a previous enable attempt failed mid-flow (verify
-  // race, network blip, app killed). Stalwart per-account rate-limits
-  // PushVerification posts, so leaving stragglers around blocks the new
-  // one's verification - the symptom is a confusing "code does not match".
+  // Reap any leftover Stalwart subscriptions still bound to this account's
+  // deviceClientId. These pile up when a previous enable attempt failed
+  // mid-flow (verify race, network blip, app killed). Stalwart per-account
+  // rate-limits PushVerification posts, so leaving stragglers around blocks
+  // the new one's verification - the symptom is a confusing "code does not
+  // match". Only reap matches for THIS account's deviceClientId; other
+  // accounts' subscriptions on this server (rare but possible if the same
+  // JMAP server backs multiple accounts) must be left alone.
   const stragglers = existingSubs.filter(
     (s) => s.deviceClientId === deviceClientId && s.id !== storedServerId,
   );
@@ -245,11 +331,19 @@ export async function setupPushNotifications(
   const verificationCode = await pollVerificationCode(relayBaseUrl, deviceClientId);
   await verifyPushSubscription(serverAssignedId, verificationCode);
 
-  await AsyncStorage.setItem(SUBSCRIPTION_ID_KEY, serverAssignedId);
+  await AsyncStorage.setItem(subKey, serverAssignedId);
+  await addPushAccountId(accountId);
 
   return { subscriptionId: serverAssignedId, verified: true };
 }
 
+async function addPushAccountId(accountId: string): Promise<void> {
+  const ids = await readPushAccountIds();
+  if (!ids.includes(accountId)) {
+    await writePushAccountIds([...ids, accountId]);
+  }
+}
+
 // Push the subscription's expires forward when it's getting close to the
 // server's ceiling. Returns false if the server rejects the update, which the
 // caller treats as "recreate".
@@ -273,28 +367,92 @@ async function refreshSubscriptionExpires(
   }
 }
 
+async function deregisterFromRelay(
+  relayBaseUrl: string,
+  deviceClientId: string,
+): Promise<void> {
+  await fetch(
+    buildRelayUrl(relayBaseUrl, `/api/push/register/${encodeURIComponent(deviceClientId)}`),
+    { method: 'DELETE' },
+  ).catch(() => undefined);
+}
+
 /**
- * Tear down push on logout / disable. Removes the server-side JMAP
- * subscription, tells the relay to drop the mapping, and clears the local
- * FCM token. Never throws - callers treat teardown as best effort.
+ * Tear down push for a single account. Destroys that account's JMAP
+ * subscription (assumes the jmapClient is currently authenticated to that
+ * account; the active-account logout flow guarantees this) and tells the
+ * relay to drop its mapping. Other accounts' push setups are untouched.
+ *
+ * If no accounts have push left after removal, also deletes the FCM token
+ * so the device stops receiving FCM messages entirely. Never throws -
+ * callers treat teardown as best effort.
+ */
+export async function teardownPushNotificationsForAccount(
+  accountId: string,
+): Promise<void> {
+  await migrateLegacyPushKeys();
+
+  const subKey = subscriptionIdKey(accountId);
+  const storedSubId = await AsyncStorage.getItem(subKey);
+  const dcidKey = deviceClientIdKey(accountId);
+  const storedDcid = await AsyncStorage.getItem(dcidKey);
+  const relayBaseUrl = await getStoredRelayBaseUrl();
+
+  if (storedSubId) {
+    await destroyPushSubscription(storedSubId).catch(() => undefined);
+  }
+  if (relayBaseUrl && storedDcid) {
+    await deregisterFromRelay(relayBaseUrl, storedDcid);
+  }
+
+  await AsyncStorage.multiRemove([subKey, dcidKey, lastNotifiedKey(accountId)]);
+
+  const remaining = (await readPushAccountIds()).filter((id) => id !== accountId);
+  await writePushAccountIds(remaining);
+
+  // If this was the last account with push, kill the FCM token so the device
+  // truly goes silent. Otherwise the token stays alive so the remaining
+  // accounts keep receiving pushes.
+  if (remaining.length === 0) {
+    const native = getNative();
+    if (native) {
+      await native.deleteToken().catch(() => undefined);
+    }
+  }
+}
+
+/**
+ * Tear down push for ALL accounts on this device. Used by the logout-all
+ * flow; best-effort because we typically aren't authenticated to every
+ * account's JMAP server at the moment we need to call destroy on it. The
+ * FCM token is always deleted so no push gets through regardless.
  */
 export async function teardownPushNotifications(): Promise<void> {
-  const storedId = await AsyncStorage.getItem(SUBSCRIPTION_ID_KEY);
-  const relayBaseUrl = await getStoredRelayBaseUrl();
-  const deviceClientId = await AsyncStorage.getItem(DEVICE_CLIENT_ID_KEY);
+  await migrateLegacyPushKeys();
 
-  if (storedId) {
-    await destroyPushSubscription(storedId).catch(() => undefined);
-    await AsyncStorage.removeItem(SUBSCRIPTION_ID_KEY);
+  const accountIds = await readPushAccountIds();
+  const relayBaseUrl = await getStoredRelayBaseUrl();
+
+  for (const accountId of accountIds) {
+    const subKey = subscriptionIdKey(accountId);
+    const dcidKey = deviceClientIdKey(accountId);
+    const storedSubId = await AsyncStorage.getItem(subKey);
+    const storedDcid = await AsyncStorage.getItem(dcidKey);
+
+    if (storedSubId) {
+      // Will only succeed if the jmapClient happens to be authenticated to
+      // this account right now. We don't switch the client to attempt each
+      // one; the subscription will expire server-side instead (90-day TTL).
+      await destroyPushSubscription(storedSubId).catch(() => undefined);
+    }
+    if (relayBaseUrl && storedDcid) {
+      await deregisterFromRelay(relayBaseUrl, storedDcid);
+    }
+    await AsyncStorage.multiRemove([subKey, dcidKey, lastNotifiedKey(accountId)]);
   }
-  if (relayBaseUrl && deviceClientId) {
-    await fetch(
-      buildRelayUrl(relayBaseUrl, `/api/push/register/${encodeURIComponent(deviceClientId)}`),
-      { method: 'DELETE' },
-    ).catch(() => undefined);
-  }
-  await AsyncStorage.removeItem(PUSH_ACCOUNT_ID_KEY);
-  await AsyncStorage.removeItem(LAST_NOTIFIED_EMAIL_ID_KEY);
+
+  await AsyncStorage.removeItem(PUSH_ACCOUNT_IDS_KEY);
+
   const native = getNative();
   if (native) {
     await native.deleteToken().catch(() => undefined);
@@ -327,6 +485,10 @@ export interface NotificationTapPayload {
   emailId: string;
   threadId: string;
   subject?: string;
+  // Identifies which logged-in account the notification was generated for.
+  // Optional for back-compat: older notifications already on the system tray
+  // won't carry this and will fall back to the active account on tap.
+  accountId?: string;
 }
 
 // Returns - and clears - any pending "notification tap" that launched the app

src/lib/sha256.ts

@@ -0,0 +1,131 @@
+// Minimal SHA-256 implementation. Used to verify APK update downloads against
+// the checksum published in the GitHub release body — the JS runtime has no
+// built-in `crypto.subtle.digest` and we don't currently depend on
+// `expo-crypto`. Public-domain algorithm (FIPS 180-4); typical sub-second per
+// MB on a modern phone, which is fine for the rare update flow.
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+  0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+  0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function rotr(x: number, n: number): number {
+  return (x >>> n) | (x << (32 - n));
+}
+
+export class Sha256 {
+  private h = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+    0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  private buffer = new Uint8Array(64);
+  private bufferLen = 0;
+  private byteCount = 0;
+
+  update(bytes: Uint8Array): void {
+    let i = 0;
+    this.byteCount += bytes.length;
+    while (i < bytes.length) {
+      const room = 64 - this.bufferLen;
+      const chunk = Math.min(room, bytes.length - i);
+      this.buffer.set(bytes.subarray(i, i + chunk), this.bufferLen);
+      this.bufferLen += chunk;
+      i += chunk;
+      if (this.bufferLen === 64) {
+        this.process(this.buffer);
+        this.bufferLen = 0;
+      }
+    }
+  }
+
+  digestHex(): string {
+    // Final block: append 0x80, pad with zeros, then 8-byte big-endian length.
+    const totalBits = this.byteCount * 8;
+    this.buffer[this.bufferLen++] = 0x80;
+    if (this.bufferLen > 56) {
+      while (this.bufferLen < 64) this.buffer[this.bufferLen++] = 0;
+      this.process(this.buffer);
+      this.bufferLen = 0;
+    }
+    while (this.bufferLen < 56) this.buffer[this.bufferLen++] = 0;
+    // 64-bit length, big-endian. We can't represent >2^53 - JS bitops are
+    // 32-bit, so split into hi/lo words.
+    const hi = Math.floor(totalBits / 0x100000000);
+    const lo = totalBits >>> 0;
+    this.buffer[56] = (hi >>> 24) & 0xff;
+    this.buffer[57] = (hi >>> 16) & 0xff;
+    this.buffer[58] = (hi >>> 8) & 0xff;
+    this.buffer[59] = hi & 0xff;
+    this.buffer[60] = (lo >>> 24) & 0xff;
+    this.buffer[61] = (lo >>> 16) & 0xff;
+    this.buffer[62] = (lo >>> 8) & 0xff;
+    this.buffer[63] = lo & 0xff;
+    this.process(this.buffer);
+
+    let out = '';
+    for (let i = 0; i < 8; i++) {
+      out += this.h[i].toString(16).padStart(8, '0');
+    }
+    return out;
+  }
+
+  private process(block: Uint8Array): void {
+    const w = new Uint32Array(64);
+    for (let i = 0; i < 16; i++) {
+      w[i] =
+        (block[i * 4] << 24) |
+        (block[i * 4 + 1] << 16) |
+        (block[i * 4 + 2] << 8) |
+        block[i * 4 + 3];
+    }
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+    }
+
+    let a = this.h[0], b = this.h[1], c = this.h[2], d = this.h[3];
+    let e = this.h[4], f = this.h[5], g = this.h[6], hh = this.h[7];
+
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const temp1 = (hh + S1 + ch + K[i] + w[i]) | 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const mj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (S0 + mj) | 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = (d + temp1) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) | 0;
+    }
+
+    this.h[0] = (this.h[0] + a) | 0;
+    this.h[1] = (this.h[1] + b) | 0;
+    this.h[2] = (this.h[2] + c) | 0;
+    this.h[3] = (this.h[3] + d) | 0;
+    this.h[4] = (this.h[4] + e) | 0;
+    this.h[5] = (this.h[5] + f) | 0;
+    this.h[6] = (this.h[6] + g) | 0;
+    this.h[7] = (this.h[7] + hh) | 0;
+  }
+}
+
+export function sha256Hex(bytes: Uint8Array): string {
+  const h = new Sha256();
+  h.update(bytes);
+  return h.digestHex();
+}

src/screens/LoginScreen.tsx

@@ -1,12 +1,15 @@
 import React from 'react';
 import { View, Text, Pressable, StyleSheet, KeyboardAvoidingView, Platform, Image } from 'react-native';
 import { SafeAreaView } from 'react-native-safe-area-context';
+import Constants from 'expo-constants';
 import { Eye, EyeOff, X } from 'lucide-react-native';
 import { spacing, radius, typography, componentSizes, type ThemePalette } from '../theme/tokens';
 import { useColors } from '../theme/colors';
 import { Button, Input } from '../components';
 import { useAuthStore } from '../stores/auth-store';
 
+const APP_VERSION = Constants.expoConfig?.version ?? '0.0.0';
+
 interface LoginScreenProps {
   onLogin?: () => void;
   isAddMode?: boolean;
@@ -17,6 +20,7 @@ export default function LoginScreen({ onLogin, isAddMode, onCancel }: LoginScree
   const c = useColors();
   const styles = React.useMemo(() => makeStyles(c), [c]);
   const login = useAuthStore((state) => state.login);
+  const loginViaWebmail = useAuthStore((state) => state.loginViaWebmail);
   const isLoading = useAuthStore((state) => state.isLoading);
   const error = useAuthStore((state) => state.error);
   const clearError = useAuthStore((state) => state.clearError);
@@ -27,6 +31,7 @@ export default function LoginScreen({ onLogin, isAddMode, onCancel }: LoginScree
   const [showPassword, setShowPassword] = React.useState(false);
 
   const canSubmit = Boolean(serverUrl.trim() && email.trim() && password);
+  const canHandoff = Boolean(serverUrl.trim());
 
   const handleLogin = async () => {
     if (!canSubmit) {
@@ -41,6 +46,25 @@ export default function LoginScreen({ onLogin, isAddMode, onCancel }: LoginScree
     }
   };
 
+  const handleWebmailHandoff = async () => {
+    if (!canHandoff) return;
+    try {
+      const before = useAuthStore.getState().isAuthenticated;
+      await loginViaWebmail(serverUrl.trim(), { addAccount: isAddMode });
+      // loginViaWebmail swallows the "user cancelled the browser" case
+      // silently — only fire the navigation hook when authentication
+      // actually completed.
+      const after = useAuthStore.getState().isAuthenticated;
+      if (after && !before) {
+        onLogin?.();
+      } else if (isAddMode && after) {
+        onLogin?.();
+      }
+    } catch {
+      // Store state already contains the user-facing error.
+    }
+  };
+
   const updateField = React.useCallback(
     (setter: React.Dispatch<React.SetStateAction<string>>) => (value: string) => {
       if (useAuthStore.getState().error) {
@@ -146,17 +170,24 @@ export default function LoginScreen({ onLogin, isAddMode, onCancel }: LoginScree
               <View style={styles.dividerLine} />
             </View>
 
-            {/* OAuth buttons */}
+            {/* Webmail-mediated login */}
             <View style={styles.oauthRow}>
-              <Button variant="outline" size="md" disabled>
-                SSO Provider
+              <Button
+                variant="outline"
+                size="md"
+                onPress={() => {
+                  void handleWebmailHandoff();
+                }}
+                disabled={!canHandoff || isLoading}
+              >
+                Sign in via webmail
               </Button>
             </View>
           </View>
 
           {/* Footer */}
           <View style={styles.footer}>
-            <Text style={styles.footerText}>Bulwark Mobile v0.0.1</Text>
+            <Text style={styles.footerText}>Bulwark Mobile v{APP_VERSION}</Text>
             <Text style={styles.footerLink}>Privacy Policy</Text>
           </View>
         </View>

src/screens/SettingsScreen.tsx

@@ -36,6 +36,7 @@ import { LanguageSettings } from '../components/settings/LanguageSettings';
 import { ComposingSettings } from '../components/settings/ComposingSettings';
 import { LayoutSettings } from '../components/settings/LayoutSettings';
 import { useLocaleStore } from '../stores/locale-store';
+import { useHasCalendar, useHasContacts, useHasFiles } from '../lib/capabilities';
 
 type Tab =
   | 'account' | 'language' | 'notifications'
@@ -155,6 +156,16 @@ export default function SettingsScreen({ onLogout, onBack, onTabSelect }: Settin
   // Subscribe to locale so labels re-render when the user picks a different language.
   const locale = useLocaleStore((s) => s.locale);
   const t = useLocaleStore((s) => s.t);
+  const hasCalendar = useHasCalendar();
+  const hasContacts = useHasContacts();
+  const hasFiles = useHasFiles();
+  const unavailableTabs = React.useMemo(() => {
+    const set = new Set<Tab>();
+    if (!hasCalendar) set.add('calendar');
+    if (!hasContacts) set.add('contacts');
+    if (!hasFiles) set.add('files');
+    return set;
+  }, [hasCalendar, hasContacts, hasFiles]);
   const groupedTabs = React.useMemo(() => {
     void locale; // dependency: re-translate on locale change
     return groupTabs().map((g) => ({
@@ -178,6 +189,7 @@ export default function SettingsScreen({ onLogout, onBack, onTabSelect }: Settin
 
   const handleTabPress = (tab: TabDef) => {
     if (!tab.implemented) return;
+    if (unavailableTabs.has(tab.id)) return;
     setSelectedTab(tab.id);
     onTabSelect?.(tab.id);
   };
@@ -210,14 +222,20 @@ export default function SettingsScreen({ onLogout, onBack, onTabSelect }: Settin
 
   return (
     <SafeAreaView style={styles.container} edges={['top']}>
-      {/* Header - matches webmail mobile: h-14, border-b, back button + icon + title */}
+      {/* Header - matches webmail mobile: h-14, border-b, back button + icon + title.
+          Settings is a tab root, so the back button is only rendered when a
+          parent passes onBack (it'd otherwise lead nowhere). */}
       <View style={styles.header}>
-        <Pressable
-          onPress={onBack}
-          style={({ pressed }) => [styles.headerBackBtn, pressed && styles.headerBackBtnPressed]}
-        >
-          <ArrowLeft size={20} color={c.text} />
-        </Pressable>
+        {onBack ? (
+          <Pressable
+            onPress={onBack}
+            style={({ pressed }) => [styles.headerBackBtn, pressed && styles.headerBackBtnPressed]}
+          >
+            <ArrowLeft size={20} color={c.text} />
+          </Pressable>
+        ) : (
+          <View style={styles.headerLeftSpacer} />
+        )}
         <Settings size={20} color={c.mutedForeground} />
         <Text style={styles.headerTitle}>{t('settings.title', 'Settings')}</Text>
       </View>
@@ -235,7 +253,13 @@ export default function SettingsScreen({ onLogout, onBack, onTabSelect }: Settin
 
               {group.items.map((tab) => {
                 const Icon = tab.icon;
-                const disabled = !tab.implemented;
+                const unavailable = unavailableTabs.has(tab.id);
+                const disabled = !tab.implemented || unavailable;
+                const badgeLabel = !tab.implemented
+                  ? 'Not implemented'
+                  : unavailable
+                    ? 'Unavailable'
+                    : null;
                 return (
                   <Pressable
                     key={tab.id}
@@ -263,9 +287,9 @@ export default function SettingsScreen({ onLogout, onBack, onTabSelect }: Settin
                         </View>
                       )}
                     </View>
-                    {disabled ? (
+                    {badgeLabel ? (
                       <View style={styles.notWorkingBadge}>
-                        <Text style={styles.notWorkingText}>Not implemented</Text>
+                        <Text style={styles.notWorkingText}>{badgeLabel}</Text>
                       </View>
                     ) : (
                       <ChevronRight size={16} color={c.mutedForeground} />
@@ -310,6 +334,7 @@ function makeStyles(c: ThemePalette) {
       borderRadius: radius.md,
     },
     headerBackBtnPressed: { backgroundColor: c.accent },
+    headerLeftSpacer: { width: spacing.sm },
     headerTitle: { ...typography.h3, color: c.text },
 
     scrollArea: { flex: 1 },

src/stores/__tests__/auth-store.test.ts

@@ -1,42 +1,63 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 
-vi.mock('expo-secure-store', () => ({
-  setItemAsync: vi.fn(),
-  getItemAsync: vi.fn(),
-  deleteItemAsync: vi.fn(),
-}));
-
 vi.mock('../../api/jmap-client', () => ({
   jmapClient: {
     connect: vi.fn(),
     logout: vi.fn(),
     restoreSession: vi.fn(),
+    loadAccount: vi.fn(),
+    consumeLegacyCredentials: vi.fn(async () => null),
+    clearAccountCredentials: vi.fn(async () => undefined),
+    clearAllCredentials: vi.fn(async () => undefined),
+    reset: vi.fn(),
     accountId: 'acc-1',
     currentSession: { apiUrl: 'https://mail.example.com/jmap/' },
+    username: 'user',
+    serverUrl: 'https://mail.example.com',
   },
   AuthenticationError: class AuthenticationError extends Error {
     constructor(msg: string) { super(msg); this.name = 'AuthenticationError'; }
   },
+  NetworkError: class NetworkError extends Error {
+    constructor(msg: string) { super(msg); this.name = 'NetworkError'; }
+  },
+}));
+
+vi.mock('../../lib/push-notifications', () => ({
+  teardownPushNotifications: vi.fn(async () => undefined),
+  teardownPushNotificationsForAccount: vi.fn(async () => undefined),
 }));
 
 import { jmapClient } from '../../api/jmap-client';
 import { useAuthStore } from '../auth-store';
+import { useAccountStore } from '../account-store';
 
 const mockConnect = jmapClient.connect as ReturnType<typeof vi.fn>;
 const mockLogout = jmapClient.logout as ReturnType<typeof vi.fn>;
-const mockRestore = jmapClient.restoreSession as ReturnType<typeof vi.fn>;
+const mockLoadAccount = jmapClient.loadAccount as ReturnType<typeof vi.fn>;
+
+function resetAccountStore(): void {
+  useAccountStore.setState({
+    accounts: [],
+    activeAccountId: null,
+    defaultAccountId: null,
+  });
+}
 
 beforeEach(() => {
   vi.clearAllMocks();
-  // Reset store state
+  resetAccountStore();
   useAuthStore.setState({
     isAuthenticated: false,
     isLoading: false,
+    hasRestoredSession: false,
     error: null,
     serverUrl: null,
     username: null,
     session: null,
     accountId: null,
+    activeAccountId: null,
+    client: null,
   });
 });
 
@@ -83,7 +104,7 @@ describe('auth-store', () => {
   });
 
   describe('logout', () => {
-    it('should reset all state', async () => {
+    it('should reset all state when no other accounts remain', async () => {
       useAuthStore.setState({ isAuthenticated: true, serverUrl: 'x', username: 'y' });
       mockLogout.mockResolvedValue(undefined);
 
@@ -97,23 +118,40 @@ describe('auth-store', () => {
   });
 
   describe('restoreSession', () => {
-    it('should restore on success', async () => {
-      mockRestore.mockResolvedValue(true);
+    it('should return false when there is no registered account', async () => {
+      const restored = await useAuthStore.getState().restoreSession();
+
+      expect(restored).toBe(false);
+      expect(useAuthStore.getState().isAuthenticated).toBe(false);
+      expect(useAuthStore.getState().hasRestoredSession).toBe(true);
+    });
+
+    it('should restore when loadAccount succeeds for the active account', async () => {
+      useAccountStore.setState({
+        accounts: [
+          {
+            id: 'acc-1',
+            serverUrl: 'https://mail.example.com',
+            username: 'user',
+            displayName: 'user',
+            email: 'user',
+            avatarColor: '#000',
+            lastLoginAt: 0,
+            isConnected: false,
+            hasError: false,
+            isDefault: true,
+          },
+        ],
+        activeAccountId: 'acc-1',
+        defaultAccountId: 'acc-1',
+      });
+      mockLoadAccount.mockResolvedValue(true);
 
       const restored = await useAuthStore.getState().restoreSession();
 
       expect(restored).toBe(true);
       expect(useAuthStore.getState().isAuthenticated).toBe(true);
     });
-
-    it('should return false when no session to restore', async () => {
-      mockRestore.mockResolvedValue(false);
-
-      const restored = await useAuthStore.getState().restoreSession();
-
-      expect(restored).toBe(false);
-      expect(useAuthStore.getState().isAuthenticated).toBe(false);
-    });
   });
 
   describe('clearError', () => {

src/stores/__tests__/calendar-store.test.ts

@@ -20,6 +20,7 @@ vi.mock('@react-native-async-storage/async-storage', () => ({
 vi.mock('../../api/jmap-client', () => ({
   jmapClient: {
     accountId: 'acc-1',
+    isConnected: true,
   },
 }));
 

src/stores/__tests__/contacts-store.test.ts

@@ -20,6 +20,7 @@ vi.mock('@react-native-async-storage/async-storage', () => ({
 vi.mock('../../api/jmap-client', () => ({
   jmapClient: {
     accountId: 'acc-1',
+    isConnected: true,
   },
 }));
 

src/stores/__tests__/email-store.test.ts

@@ -2,8 +2,16 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 
 vi.mock('../../api/email', () => ({
   getMailboxes: vi.fn(),
+  // New helpers used by the incremental-sync path. Default behavior: behave
+  // like a first-ever load — no prior state, full re-query expected.
+  getMailboxesWithState: vi.fn(async () => ({ list: [], state: 'mb-state-0' })),
+  getMailboxesByIds: vi.fn(async () => ({ list: [], state: 'mb-state-0' })),
+  getMailboxChanges: vi.fn(async () => null),
   queryEmails: vi.fn(),
+  getEmailQueryChanges: vi.fn(async () => null),
   getEmails: vi.fn(),
+  getEmailsWithState: vi.fn(async () => ({ list: [], state: 'em-state-0' })),
+  getEmailChanges: vi.fn(async () => null),
   getFullEmail: vi.fn(),
   setEmailKeywords: vi.fn(),
   moveEmail: vi.fn(),
@@ -17,15 +25,57 @@ vi.mock('../../api/email', () => ({
 // trip on react-native's Flow-typed entrypoint under vitest. The store only
 // reads archiveMode in archiveEmail, so a minimal stub is enough.
 vi.mock('../settings-store', () => ({
-  useSettingsStore: { getState: () => ({ archiveMode: 'single' }) },
+  useSettingsStore: { getState: () => ({ archiveMode: 'single', emailsPerPage: 25 }) },
 }));
 
+// offline-cache-store is touched by selectMailbox (cache-seed fallback),
+// getEmailDetail (best-effort body refresh), and setActiveAccount (account
+// switch). Stub it as an empty cache so tests don't need to set up
+// AsyncStorage.
+vi.mock('../offline-cache-store', () => ({
+  useOfflineCacheStore: {
+    getState: () => ({
+      activeAccountId: null,
+      hydrated: true,
+      hydrate: vi.fn(),
+      setAccount: vi.fn(async () => undefined),
+      totalCount: () => 0,
+      getEmailsInMailbox: vi.fn(async () => []),
+      has: () => false,
+      get: vi.fn(async () => null),
+      put: vi.fn(async () => undefined),
+    }),
+  },
+}));
+
+// email-store now early-returns from fetch actions unless jmapClient is
+// connected AND serving the same logical account the store has active
+// (`generateAccountId(username, serverUrl) === activeAccountId`). The
+// tests exercise those actions, so present a fully connected stub plus
+// the matching username/serverUrl pair. beforeEach() syncs the store's
+// activeAccountId to the id these credentials produce.
+vi.mock('../../api/jmap-client', () => ({
+  jmapClient: {
+    isConnected: true,
+    accountId: 'acc-1',
+    username: 'test@example.com',
+    serverUrl: 'https://mail.example.com',
+    currentSession: { apiUrl: 'https://mail.example.com/jmap/' },
+    // refreshEmails / loadMoreEmails chunk by this value when fetching ids.
+    getMaxObjectsInGet: () => 500,
+  },
+}));
+
+import { generateAccountId } from '../../lib/account-utils';
+const TEST_ACCOUNT_ID = generateAccountId('test@example.com', 'https://mail.example.com');
+
 import * as emailApi from '../../api/email';
 import { useEmailStore } from '../email-store';
 
-const mockGetMailboxes = emailApi.getMailboxes as ReturnType<typeof vi.fn>;
+const mockGetMailboxesWithState = emailApi.getMailboxesWithState as ReturnType<typeof vi.fn>;
 const mockQueryEmails = emailApi.queryEmails as ReturnType<typeof vi.fn>;
 const mockGetEmails = emailApi.getEmails as ReturnType<typeof vi.fn>;
+const mockGetEmailsWithState = emailApi.getEmailsWithState as ReturnType<typeof vi.fn>;
 const mockGetFullEmail = emailApi.getFullEmail as ReturnType<typeof vi.fn>;
 const mockSetKeywords = emailApi.setEmailKeywords as ReturnType<typeof vi.fn>;
 const mockMoveEmail = emailApi.moveEmail as ReturnType<typeof vi.fn>;
@@ -35,6 +85,10 @@ const mockSearchEmails = emailApi.searchEmails as ReturnType<typeof vi.fn>;
 beforeEach(() => {
   vi.clearAllMocks();
   useEmailStore.getState().reset();
+  // Wire the store's active account to the one the mocked jmapClient is
+  // serving, so the guard inside fetchMailboxes / refreshEmails / etc.
+  // doesn't short-circuit the tests.
+  useEmailStore.setState({ activeAccountId: TEST_ACCOUNT_ID });
 });
 
 describe('email-store', () => {
@@ -44,7 +98,7 @@ describe('email-store', () => {
         { id: 'mb-1', name: 'Inbox', role: 'inbox' },
         { id: 'mb-2', name: 'Sent', role: 'sent' },
       ];
-      mockGetMailboxes.mockResolvedValue(mailboxes);
+      mockGetMailboxesWithState.mockResolvedValue({ list: mailboxes, state: 'mb-state-1' });
 
       await useEmailStore.getState().fetchMailboxes();
 
@@ -52,7 +106,7 @@ describe('email-store', () => {
     });
 
     it('should set error on failure', async () => {
-      mockGetMailboxes.mockRejectedValue(new Error('Network error'));
+      mockGetMailboxesWithState.mockRejectedValue(new Error('Network error'));
 
       await useEmailStore.getState().fetchMailboxes();
 
@@ -62,12 +116,12 @@ describe('email-store', () => {
 
   describe('selectMailbox', () => {
     it('should query and fetch emails for mailbox', async () => {
-      mockQueryEmails.mockResolvedValue({ ids: ['e1', 'e2'], total: 2 });
+      mockQueryEmails.mockResolvedValue({ ids: ['e1', 'e2'], total: 2, queryState: 'q-1' });
       const emails = [
         { id: 'e1', subject: 'Email 1' },
         { id: 'e2', subject: 'Email 2' },
       ];
-      mockGetEmails.mockResolvedValue(emails);
+      mockGetEmailsWithState.mockResolvedValue({ list: emails, state: 'em-state-1' });
 
       await useEmailStore.getState().selectMailbox('mb-1');
 
@@ -79,11 +133,14 @@ describe('email-store', () => {
     });
 
     it('should handle empty mailbox', async () => {
-      mockQueryEmails.mockResolvedValue({ ids: [], total: 0 });
+      mockQueryEmails.mockResolvedValue({ ids: [], total: 0, queryState: 'q-empty' });
 
       await useEmailStore.getState().selectMailbox('mb-empty');
 
       expect(useEmailStore.getState().emails).toEqual([]);
+      // First-time load with no ids hits getEmailsWithState only to prime
+      // emailState (with an empty ids array). It should NOT call legacy
+      // getEmails — that path is reserved for pagination/search.
       expect(mockGetEmails).not.toHaveBeenCalled();
     });
   });

src/stores/auth-store.ts

@@ -1,12 +1,16 @@
 import { create } from 'zustand';
-import { jmapClient, AuthenticationError } from '../api/jmap-client';
+import { jmapClient, AuthenticationError, NetworkError } from '../api/jmap-client';
 import type { JMAPSession } from '../api/types';
 import { useAccountStore } from './account-store';
 import { useEmailStore } from './email-store';
 import { useContactsStore } from './contacts-store';
 import { useCalendarStore } from './calendar-store';
 import { generateAccountId } from '../lib/account-utils';
-import { teardownPushNotifications } from '../lib/push-notifications';
+import { runWebmailHandoff, HandoffCancelledError } from '../lib/oauth';
+import {
+  teardownPushNotifications,
+  teardownPushNotificationsForAccount,
+} from '../lib/push-notifications';
 
 // Persist middleware hydrates asynchronously on cold start. Without this
 // guard, restoreSession() can read the account-store before AsyncStorage has
@@ -35,15 +39,37 @@ export interface AuthState {
   client: typeof jmapClient | null;
 
   login: (serverUrl: string, username: string, password: string, opts?: { addAccount?: boolean }) => Promise<void>;
+  loginViaWebmail: (webmailUrl: string, opts?: { addAccount?: boolean }) => Promise<void>;
   logout: () => Promise<void>;
   logoutAll: () => Promise<void>;
   switchAccount: (accountId: string) => Promise<void>;
   restoreSession: () => Promise<boolean>;
+  retrySession: () => Promise<boolean>;
   clearError: () => void;
 }
 
-function resetFeatureStores(): void {
-  useEmailStore.getState().reset();
+// Wipe ALL cached feature data for ALL accounts. Used for logoutAll where
+// the user is signing out of everything — we don't want stale snapshots
+// lingering on disk for accounts that no longer exist.
+function clearAllFeatureStores(): void {
+  useEmailStore.getState().clearAllAccounts();
+  useContactsStore.getState().reset();
+  useCalendarStore.getState().reset();
+}
+
+// Drop the named account from the email cache, then reset the (per-session,
+// not yet per-account) contacts and calendar stores. Used by logout when
+// signing one account out while others remain.
+function clearAccountFeatureStores(accountId: string | null): void {
+  if (accountId) {
+    useEmailStore.getState().removeAccount(accountId);
+  } else {
+    useEmailStore.getState().clearAllAccounts();
+  }
+  // Contacts and calendar stores aren't yet keyed by account — the safe
+  // thing on logout is still to wipe them so the next account doesn't see
+  // the previous user's data. Per-account caching for those stores is a
+  // follow-up.
   useContactsStore.getState().reset();
   useCalendarStore.getState().reset();
 }
@@ -104,11 +130,13 @@ export const useAuthStore = create<AuthState>((set, get) => ({
   login: async (serverUrl, username, password, opts) => {
     set({ isLoading: true, error: null });
     try {
-      // Adding an additional account - snapshot/reset feature stores so the
-      // new account starts with a clean slate.
+      // Adding an additional account - snapshot the current account away so
+      // its cache survives, then reset the JMAP client for the new login.
+      // Contacts/calendar are still single-bucket, so wipe those.
       if (opts?.addAccount && get().isAuthenticated) {
         jmapClient.reset();
-        resetFeatureStores();
+        useContactsStore.getState().reset();
+        useCalendarStore.getState().reset();
       }
 
       const session = await jmapClient.connect(serverUrl, username, password);
@@ -125,6 +153,9 @@ export const useAuthStore = create<AuthState>((set, get) => ({
         hasError: false,
       });
       accountStore.setActiveAccount(accountId);
+      // Swap the email store's active view to the new account so the rest of
+      // this function (and refetchFeatureStores) writes to the right bucket.
+      useEmailStore.getState().setActiveAccount(accountId);
 
       applyConnectedState(set, session, serverUrl.replace(/\/+$/, ''), username, accountId);
     } catch (err) {
@@ -138,13 +169,83 @@ export const useAuthStore = create<AuthState>((set, get) => ({
     }
   },
 
+  loginViaWebmail: async (webmailUrl, opts) => {
+    set({ isLoading: true, error: null });
+    let result;
+    try {
+      result = await runWebmailHandoff(webmailUrl);
+    } catch (err) {
+      if (err instanceof HandoffCancelledError) {
+        // User closed the browser tab — quiet exit, no error banner.
+        set({ isLoading: false, error: null });
+        return;
+      }
+      const message = err instanceof Error ? err.message : 'Sign-in failed';
+      set({ isLoading: false, error: message });
+      throw err;
+    }
+
+    if (result.flow === 'password') {
+      // Hand the credentials to the existing password login path so account
+      // registration + feature-store wiring all behave identically to a
+      // manual sign-in.
+      await get().login(result.serverUrl, result.username, result.password, opts);
+      return;
+    }
+
+    // OAuth — the webmail did the dance against Stalwart and handed us a
+    // token bundle. Bootstrap the JMAP session with Bearer auth and let
+    // ensure/forceRefreshToken keep it alive going forward.
+    try {
+      if (opts?.addAccount && get().isAuthenticated) {
+        jmapClient.reset();
+        useContactsStore.getState().reset();
+        useCalendarStore.getState().reset();
+      }
+
+      const { session, username, accountId } = await jmapClient.connectWithOAuth(
+        result.serverUrl,
+        result.tokens,
+      );
+
+      const accountStore = useAccountStore.getState();
+      accountStore.addAccount({
+        serverUrl: result.serverUrl.replace(/\/+$/, ''),
+        username,
+        displayName: username,
+        email: username,
+        lastLoginAt: Date.now(),
+        isConnected: true,
+        hasError: false,
+      });
+      accountStore.setActiveAccount(accountId);
+      useEmailStore.getState().setActiveAccount(accountId);
+
+      applyConnectedState(set, session, result.serverUrl.replace(/\/+$/, ''), username, accountId);
+    } catch (err) {
+      const message =
+        err instanceof AuthenticationError
+          ? 'Authentication rejected by server'
+          : err instanceof Error
+            ? err.message
+            : 'OAuth sign-in failed';
+      set({ isLoading: false, error: message });
+      throw err;
+    }
+  },
+
   logout: async () => {
     const accountStore = useAccountStore.getState();
     const currentId = get().activeAccountId;
 
-    // Best-effort: revoke the JMAP PushSubscription and drop the relay
-    // mapping before we lose credentials. Do not abort logout on failure.
-    await teardownPushNotifications().catch(() => undefined);
+    // Best-effort: revoke this account's JMAP PushSubscription and drop its
+    // relay mapping before we lose credentials. Other logged-in accounts'
+    // push setups remain untouched. Do not abort logout on failure.
+    if (currentId) {
+      await teardownPushNotificationsForAccount(currentId).catch(() => undefined);
+    } else {
+      await teardownPushNotifications().catch(() => undefined);
+    }
 
     // Clear credentials for this account first
     if (currentId) {
@@ -155,7 +256,7 @@ export const useAuthStore = create<AuthState>((set, get) => ({
     }
 
     jmapClient.reset();
-    resetFeatureStores();
+    clearAccountFeatureStores(currentId);
 
     // Switch to next remaining account, if any
     const remaining = accountStore.accounts;
@@ -189,7 +290,7 @@ export const useAuthStore = create<AuthState>((set, get) => ({
     await teardownPushNotifications().catch(() => undefined);
     await jmapClient.clearAllCredentials(ids);
     jmapClient.reset();
-    resetFeatureStores();
+    clearAllFeatureStores();
 
     for (const id of ids) accountStore.removeAccount(id);
 
@@ -216,14 +317,50 @@ export const useAuthStore = create<AuthState>((set, get) => ({
 
     set({ isLoading: true, error: null });
 
-    jmapClient.reset();
-    resetFeatureStores();
+    // Swap the email-store view to the new account *before* the network
+    // round-trip. The previous account's data is tucked into its snapshot;
+    // the new account's data (if previously cached) is restored to the
+    // top-level fields so the EmailListScreen immediately shows the new
+    // account's last-known mail instead of flashing empty. The network
+    // refresh below applies incremental updates on top.
+    useEmailStore.getState().setActiveAccount(accountId);
 
-    const ok = await jmapClient.loadAccount(accountId);
-    if (!ok) {
-      // Credentials missing - evict stale entry and surface error
-      accountStore.removeAccount(accountId);
-      set({ isLoading: false, error: 'Session expired for this account' });
+    // Contacts and calendar stores aren't yet per-account, so they still
+    // need a reset to avoid showing the previous account's data.
+    useContactsStore.getState().reset();
+    useCalendarStore.getState().reset();
+
+    // Load the new account's session. loadAccount overwrites
+    // credentials/session/_accountId itself, so we don't need to reset
+    // jmapClient first. If it fails, restore the previous active account
+    // so we don't leave the user stranded on a half-switched state.
+    const previousActive = get().activeAccountId;
+    try {
+      const ok = await jmapClient.loadAccount(accountId);
+      if (!ok) {
+        // Credentials missing - evict stale entry and surface error
+        accountStore.removeAccount(accountId);
+        useEmailStore.getState().removeAccount(accountId);
+        if (previousActive) useEmailStore.getState().setActiveAccount(previousActive);
+        set({ isLoading: false, error: 'Session expired for this account' });
+        return;
+      }
+    } catch (err) {
+      if (err instanceof AuthenticationError) {
+        await jmapClient.clearAccountCredentials(accountId).catch(() => undefined);
+        accountStore.removeAccount(accountId);
+        useEmailStore.getState().removeAccount(accountId);
+        if (previousActive) useEmailStore.getState().setActiveAccount(previousActive);
+        set({ isLoading: false, error: 'Session expired for this account' });
+        return;
+      }
+      // NetworkError or anything else - keep the previous active account
+      // intact instead of stranding the user on a half-switched state.
+      if (previousActive) useEmailStore.getState().setActiveAccount(previousActive);
+      set({
+        isLoading: false,
+        error: err instanceof Error ? err.message : 'Failed to switch account',
+      });
       return;
     }
 
@@ -286,15 +423,64 @@ export const useAuthStore = create<AuthState>((set, get) => ({
         return false;
       }
 
-      const ok = await jmapClient.loadAccount(target.id);
-      if (!ok) {
-        accountStore.removeAccount(target.id);
-        set({ isLoading: false, hasRestoredSession: true });
-        return false;
+      // Point the email store at the target account before any await — so
+      // the EmailListScreen, which re-renders the moment the persisted state
+      // hydrates, sees the right account's cached emails instead of stale
+      // data from a previous session.
+      useEmailStore.getState().setActiveAccount(target.id);
+
+      try {
+        const ok = await jmapClient.loadAccount(target.id);
+        if (!ok) {
+          // No stored credentials (or corrupt) — genuine logout.
+          accountStore.removeAccount(target.id);
+          useEmailStore.getState().removeAccount(target.id);
+          set({ isLoading: false, hasRestoredSession: true });
+          return false;
+        }
+      } catch (err) {
+        if (err instanceof NetworkError) {
+          // Server unreachable. Keep credentials, mark account offline, and
+          // surface the cached UI so the user can still browse persisted
+          // mail / contacts / calendar. The login screen would lose their
+          // settings without recourse, which is the bug we're fixing here.
+          accountStore.setActiveAccount(target.id);
+          accountStore.updateAccount(target.id, {
+            isConnected: false,
+            hasError: true,
+            errorMessage: err.message,
+          });
+          set({
+            isAuthenticated: true,
+            isLoading: false,
+            hasRestoredSession: true,
+            error: null,
+            serverUrl: target.serverUrl,
+            username: target.username,
+            session: null,
+            accountId: null,
+            activeAccountId: target.id,
+            client: jmapClient,
+          });
+          return true;
+        }
+        if (err instanceof AuthenticationError) {
+          // Server reachable but credentials rejected — drop them.
+          await jmapClient.clearAccountCredentials(target.id).catch(() => undefined);
+          accountStore.removeAccount(target.id);
+          useEmailStore.getState().removeAccount(target.id);
+          set({ isLoading: false, hasRestoredSession: true, error: 'Session expired' });
+          return false;
+        }
+        throw err;
       }
 
       accountStore.setActiveAccount(target.id);
-      accountStore.updateAccount(target.id, { isConnected: true, hasError: false });
+      accountStore.updateAccount(target.id, {
+        isConnected: true,
+        hasError: false,
+        errorMessage: undefined,
+      });
 
       const session = jmapClient.currentSession!;
       applyConnectedState(set, session, target.serverUrl, target.username, target.id);
@@ -309,5 +495,51 @@ export const useAuthStore = create<AuthState>((set, get) => ({
     }
   },
 
+  // Re-attempt session establishment for the currently active account
+  // without disturbing UI state on failure. Used by the network-recovery
+  // watcher and any explicit "retry" button. Idempotent: returns true if
+  // a session is already live.
+  retrySession: async () => {
+    const { activeAccountId, session } = get();
+    if (!activeAccountId) return false;
+    if (session) return true;
+    const accountStore = useAccountStore.getState();
+    const target = accountStore.getAccountById(activeAccountId);
+    if (!target) return false;
+    try {
+      const ok = await jmapClient.loadAccount(activeAccountId);
+      if (!ok) return false;
+      accountStore.updateAccount(activeAccountId, {
+        isConnected: true,
+        hasError: false,
+        errorMessage: undefined,
+      });
+      const fresh = jmapClient.currentSession!;
+      applyConnectedState(set, fresh, target.serverUrl, target.username, activeAccountId);
+      refetchFeatureStores();
+      return true;
+    } catch (err) {
+      if (err instanceof AuthenticationError) {
+        // Now we know the credentials are bad — fall back to logout flow.
+        await jmapClient.clearAccountCredentials(activeAccountId).catch(() => undefined);
+        accountStore.removeAccount(activeAccountId);
+        set({
+          isAuthenticated: false,
+          isLoading: false,
+          hasRestoredSession: true,
+          error: 'Session expired',
+          serverUrl: null,
+          username: null,
+          session: null,
+          accountId: null,
+          activeAccountId: null,
+          client: null,
+        });
+      }
+      // NetworkError or anything else: stay where we are.
+      return false;
+    }
+  },
+
   clearError: () => set({ error: null }),
 }));

src/stores/calendar-store.ts

@@ -89,6 +89,11 @@ export const useCalendarStore = create<CalendarState>()(
   },
 
   fetchCalendars: async () => {
+    // CalendarScreen fires this on mount; on cold start that happens before
+    // restoreSession has connected jmapClient. Bail rather than surfacing
+    // a "Not authenticated" error - the refetch driven by the auth-store
+    // will run this again once the session is live.
+    if (!jmapClient.isConnected) return;
     try {
       const calendars = (await fetchCalendars()) ?? [];
       set({ calendars });
@@ -98,6 +103,7 @@ export const useCalendarStore = create<CalendarState>()(
   },
 
   fetchEvents: async (calendarIds, after, before) => {
+    if (!jmapClient.isConnected) return;
     set({ loading: true, error: null });
     try {
       const ids = (await queryEvents(calendarIds, after, before)) ?? [];
@@ -142,6 +148,7 @@ export const useCalendarStore = create<CalendarState>()(
   },
 
   handleStateChange: async (change) => {
+    if (!jmapClient.isConnected) return;
     const accountId = jmapClient.accountId;
     const accountChanges = change.changed?.[accountId];
     if (!accountChanges) return;

src/stores/contacts-store.ts

@@ -87,6 +87,10 @@ export const useContactsStore = create<ContactsState>()(
   },
 
   fetchAddressBooks: async () => {
+    // No-op until a JMAP session exists. ContactsScreen fires this from a
+    // mount-time useEffect, which on cold start runs before restoreSession
+    // has set up the client.
+    if (!jmapClient.isConnected) return;
     try {
       const addressBooks = (await fetchAddressBooks()) ?? [];
       set({ addressBooks });
@@ -96,6 +100,7 @@ export const useContactsStore = create<ContactsState>()(
   },
 
   fetchContacts: async (filter) => {
+    if (!jmapClient.isConnected) return;
     set({ loading: true, error: null });
     try {
       const ids = (await queryContacts(filter)) ?? [];
@@ -111,6 +116,7 @@ export const useContactsStore = create<ContactsState>()(
   },
 
   handleStateChange: async (change) => {
+    if (!jmapClient.isConnected) return;
     const accountId = jmapClient.accountId;
     const accountChanges = change.changed?.[accountId];
     if (!accountChanges) return;

src/stores/email-store.ts

@@ -1,11 +1,18 @@
 import { create } from 'zustand';
 import { persist, createJSONStorage } from 'zustand/middleware';
 import AsyncStorage from '@react-native-async-storage/async-storage';
-import type { Email, Mailbox } from '../api/types';
+import type { Email, Mailbox, StateChange } from '../api/types';
+import { jmapClient } from '../api/jmap-client';
 import {
   getMailboxes as fetchMailboxes,
+  getMailboxesWithState,
+  getMailboxesByIds,
+  getMailboxChanges,
   queryEmails,
+  getEmailQueryChanges,
   getEmails as fetchEmails,
+  getEmailsWithState,
+  getEmailChanges,
   getFullEmail,
   setEmailKeywords,
   moveEmail,
@@ -15,7 +22,26 @@ import {
   searchEmails as apiSearchEmails,
 } from '../api/email';
 import { toWildcardQuery } from '../lib/search-utils';
+import { generateAccountId } from '../lib/account-utils';
 import { useSettingsStore } from './settings-store';
+import { useOfflineCacheStore } from './offline-cache-store';
+
+// True only when the JMAP client is actually serving the email-store's active
+// account. During an account switch there's a window between
+// setActiveAccount() (which swaps the email-store view immediately) and
+// jmapClient.loadAccount() resolving, when the client is still on the
+// *previous* account. Without this guard, any fetchMailboxes/refreshEmails
+// fired in that window (e.g. by an EmailListScreen useEffect reacting to
+// the empty new-account view) would return the previous account's data and
+// stamp it into the new account's snapshot.
+function jmapClientServesActiveAccount(activeAccountId: string | null): boolean {
+  if (!activeAccountId) return false;
+  if (!jmapClient.isConnected) return false;
+  const username = jmapClient.username;
+  const serverUrl = jmapClient.serverUrl;
+  if (!username || !serverUrl) return false;
+  return generateAccountId(username, serverUrl) === activeAccountId;
+}
 
 export interface EmailFilters {
   from?: string;
@@ -41,21 +67,61 @@ export interface UndoEntry {
   items: Array<{ email: Email; originalMailboxIds: Record<string, boolean> }>;
 }
 
-export interface EmailState {
+// Cached emails for one mailbox (the base view: no search query, no filters).
+// `queryState` is the JMAP queryState for the matching Email/query, used to
+// drive Email/queryChanges on the next refresh.
+interface MailboxSnapshot {
+  emails: Email[];
+  total: number;
+  queryState?: string;
+}
+
+// Everything we cache for one account so switching accounts can restore the
+// previous view instantly instead of going through a network round-trip.
+interface AccountSnapshot {
   mailboxes: Mailbox[];
+  mailboxState?: string;       // JMAP Mailbox state (drives Mailbox/changes)
+  emailState?: string;         // JMAP Email state (drives Email/changes)
   currentMailboxId: string | null;
+  mailboxSnapshots: Record<string, MailboxSnapshot>;
+}
+
+export interface EmailState {
+  // ── Per-account persisted caches ──────────────────────────────
+  // accountSnapshots is the source of truth for accounts the user is *not*
+  // currently viewing. The active account's data lives in the top-level
+  // fields below (`mailboxes`, `mailboxSnapshots`, `mailboxState`, `emailState`,
+  // `currentMailboxId`, `emails`, `totalEmails`, `queryState`) so consumers
+  // keep reading the same shape they always have.
+  accountSnapshots: Record<string, AccountSnapshot>;
+  activeAccountId: string | null;
+
+  // ── Active view (the currently-shown account/mailbox) ─────────
+  mailboxes: Mailbox[];
+  mailboxState?: string;
+  emailState?: string;
+  currentMailboxId: string | null;
+  mailboxSnapshots: Record<string, MailboxSnapshot>;
   emails: Email[];
   totalEmails: number;
+  queryState?: string;          // queryState for the currently-shown mailbox
+
+  // ── UI state (not persisted, not per-account) ─────────────────
   loading: boolean;
   error: string | null;
   searchQuery: string;
   filters: EmailFilters;
   pendingUndo: UndoEntry | null;
 
+  // ── Actions ────────────────────────────────────────────────────
+  setActiveAccount: (accountId: string | null) => void;
+  removeAccount: (accountId: string) => void;
+  clearAllAccounts: () => void;
   fetchMailboxes: () => Promise<void>;
   selectMailbox: (mailboxId: string) => Promise<void>;
   loadMoreEmails: () => Promise<void>;
   refreshEmails: () => Promise<void>;
+  handleStateChange: (change: StateChange) => Promise<void>;
   getEmailDetail: (id: string) => Promise<Email>;
   markRead: (emailId: string) => Promise<void>;
   markUnread: (emailId: string) => Promise<void>;
@@ -112,58 +178,360 @@ function buildJmapFilter(
   return { operator: 'AND', conditions };
 }
 
+// True when the user has no search/filters active. Only in this case do we
+// touch the per-mailbox snapshot cache or use Email/queryChanges — once a
+// filter is in play, the queryState belongs to a different query and the
+// cached list no longer represents what's on screen.
+function isBaseView(searchQuery: string, filters: EmailFilters): boolean {
+  return !searchQuery.trim() && Object.keys(filters).length === 0;
+}
+
+function snapshotFromActive(state: EmailState): AccountSnapshot {
+  // Persist the currently-visible mailbox into its snapshot before tucking
+  // the whole account away.
+  let mailboxSnapshots = state.mailboxSnapshots;
+  if (state.currentMailboxId && isBaseView(state.searchQuery, state.filters)) {
+    mailboxSnapshots = {
+      ...mailboxSnapshots,
+      [state.currentMailboxId]: {
+        emails: state.emails,
+        total: state.totalEmails,
+        queryState: state.queryState,
+      },
+    };
+  }
+  return {
+    mailboxes: state.mailboxes,
+    mailboxState: state.mailboxState,
+    emailState: state.emailState,
+    currentMailboxId: state.currentMailboxId,
+    mailboxSnapshots,
+  };
+}
+
+function viewFromSnapshot(snap: AccountSnapshot | null): {
+  mailboxes: Mailbox[];
+  mailboxState?: string;
+  emailState?: string;
+  currentMailboxId: string | null;
+  mailboxSnapshots: Record<string, MailboxSnapshot>;
+  emails: Email[];
+  totalEmails: number;
+  queryState?: string;
+} {
+  if (!snap) {
+    return {
+      mailboxes: [],
+      mailboxState: undefined,
+      emailState: undefined,
+      currentMailboxId: null,
+      mailboxSnapshots: {},
+      emails: [],
+      totalEmails: 0,
+      queryState: undefined,
+    };
+  }
+  const mailboxSnap = snap.currentMailboxId
+    ? snap.mailboxSnapshots[snap.currentMailboxId]
+    : undefined;
+  return {
+    mailboxes: snap.mailboxes,
+    mailboxState: snap.mailboxState,
+    emailState: snap.emailState,
+    currentMailboxId: snap.currentMailboxId,
+    mailboxSnapshots: snap.mailboxSnapshots,
+    emails: mailboxSnap?.emails ?? [],
+    totalEmails: mailboxSnap?.total ?? 0,
+    queryState: mailboxSnap?.queryState,
+  };
+}
+
+// JMAP's maxObjectsInGet bounds how many ids we can pull in one Email/get.
+// Chunk to that ceiling (with a small safety fallback) so large change sets
+// don't trip 429/413 responses.
+async function fetchEmailsChunked(ids: string[]): Promise<Email[]> {
+  if (ids.length === 0) return [];
+  const cap = Math.max(1, jmapClient.getMaxObjectsInGet());
+  const chunk = Math.min(cap, 200);
+  if (ids.length <= chunk) return fetchEmails(ids);
+  const out: Email[] = [];
+  for (let i = 0; i < ids.length; i += chunk) {
+    const slice = await fetchEmails(ids.slice(i, i + chunk));
+    out.push(...slice);
+  }
+  return out;
+}
+
+// Merge a fresh batch of emails into an existing list keyed by id. New entries
+// replace stale ones (keywords/mailboxIds may have changed); destroyed ids are
+// dropped. Order is preserved according to the supplied id order — pass the
+// authoritative id list from Email/query when re-syncing.
+function applyEmailDiff(
+  current: Email[],
+  orderedIds: string[],
+  fetched: Email[],
+  destroyed: Set<string>,
+): Email[] {
+  const byId = new Map<string, Email>();
+  for (const e of current) byId.set(e.id, e);
+  for (const e of fetched) byId.set(e.id, e);
+  const out: Email[] = [];
+  for (const id of orderedIds) {
+    if (destroyed.has(id)) continue;
+    const e = byId.get(id);
+    if (e) out.push(e);
+  }
+  return out;
+}
+
 export const useEmailStore = create<EmailState>()(
   persist(
     (set, get) => ({
+  accountSnapshots: {},
+  activeAccountId: null,
+
   mailboxes: [],
+  mailboxState: undefined,
+  emailState: undefined,
   currentMailboxId: null,
+  mailboxSnapshots: {},
   emails: [],
   totalEmails: 0,
+  queryState: undefined,
+
   loading: false,
   error: null,
   searchQuery: '',
   filters: {},
   pendingUndo: null,
 
+  // Swap which account's data is currently visible. The previous account's
+  // view is tucked into accountSnapshots so a return-trip can restore it
+  // without a network call; the new account's view is pulled from its
+  // snapshot (or empty defaults if we've never seen it). Callers (auth-store)
+  // run the network refresh afterwards.
+  setActiveAccount: (accountId) => {
+    const state = get();
+    if (state.activeAccountId === accountId) return;
+
+    const nextSnapshots = { ...state.accountSnapshots };
+    if (state.activeAccountId) {
+      nextSnapshots[state.activeAccountId] = snapshotFromActive(state);
+    }
+    const incoming = accountId ? nextSnapshots[accountId] ?? null : null;
+    const view = viewFromSnapshot(incoming);
+
+    set({
+      accountSnapshots: nextSnapshots,
+      activeAccountId: accountId,
+      ...view,
+      // UI state is reset on switch — search/filters and pending undo belong
+      // to the previous account's intent.
+      searchQuery: '',
+      filters: {},
+      pendingUndo: null,
+      error: null,
+      loading: false,
+    });
+
+    // Point the offline body cache at the same account so getEmailDetail's
+    // fallback and selectMailbox's seed read from the right bucket. Fire-
+    // and-forget — the cache returns empty until hydration completes,
+    // which is the correct degraded behaviour.
+    void useOfflineCacheStore.getState().setAccount(accountId);
+  },
+
+  removeAccount: (accountId) => {
+    const state = get();
+    const { [accountId]: _drop, ...rest } = state.accountSnapshots;
+    if (state.activeAccountId === accountId) {
+      set({
+        accountSnapshots: rest,
+        activeAccountId: null,
+        mailboxes: [],
+        mailboxState: undefined,
+        emailState: undefined,
+        currentMailboxId: null,
+        mailboxSnapshots: {},
+        emails: [],
+        totalEmails: 0,
+        queryState: undefined,
+        searchQuery: '',
+        filters: {},
+        pendingUndo: null,
+      });
+      void useOfflineCacheStore.getState().setAccount(null);
+    } else {
+      set({ accountSnapshots: rest });
+    }
+  },
+
+  clearAllAccounts: () => {
+    set({
+      accountSnapshots: {},
+      activeAccountId: null,
+      mailboxes: [],
+      mailboxState: undefined,
+      emailState: undefined,
+      currentMailboxId: null,
+      mailboxSnapshots: {},
+      emails: [],
+      totalEmails: 0,
+      queryState: undefined,
+      searchQuery: '',
+      filters: {},
+      pendingUndo: null,
+      error: null,
+      loading: false,
+    });
+    void useOfflineCacheStore.getState().setAccount(null);
+  },
+
   fetchMailboxes: async () => {
+    // Skip silently when there's no live session, or when jmapClient is
+    // mid-transition to a different account (see jmapClientServesActiveAccount).
+    // Screens fire this from mount-time useEffects, and on cold start
+    // App.tsx renders MainTabs before restoreSession() finishes; without
+    // this guard the underlying API call would either throw "Not
+    // authenticated - call connect() first" or — worse, during an account
+    // switch — return the *previous* account's mailboxes and stamp them
+    // into the new account's snapshot.
+    const activeAccountId = get().activeAccountId;
+    if (!jmapClientServesActiveAccount(activeAccountId)) return;
+
+    const prevState = get().mailboxState;
     try {
-      const mailboxes = await fetchMailboxes();
-      set({ mailboxes });
+      // Incremental path: ask for just what changed since last time. Fall
+      // through to a full refetch when the server can't compute the diff or
+      // we have no previous state to compare against.
+      if (prevState) {
+        const changes = await getMailboxChanges(prevState);
+        // Bail if the user switched accounts during the await — anything we
+        // set() now would land in the wrong account's bucket.
+        if (get().activeAccountId !== activeAccountId) return;
+        if (changes) {
+          // No changes at all — keep the cached list, just bump the state.
+          if (
+            changes.created.length === 0 &&
+            changes.updated.length === 0 &&
+            changes.destroyed.length === 0
+          ) {
+            set({ mailboxState: changes.newState });
+            return;
+          }
+          const toFetch = [...changes.created, ...changes.updated];
+          const fetched = toFetch.length > 0
+            ? (await getMailboxesByIds(toFetch)).list
+            : [];
+          if (get().activeAccountId !== activeAccountId) return;
+          const destroyed = new Set(changes.destroyed);
+          const byId = new Map<string, Mailbox>();
+          for (const m of get().mailboxes) byId.set(m.id, m);
+          for (const m of fetched) byId.set(m.id, m);
+          for (const id of destroyed) byId.delete(id);
+          set({
+            mailboxes: Array.from(byId.values()),
+            mailboxState: changes.hasMoreChanges ? prevState : changes.newState,
+          });
+          // hasMoreChanges = there are still pending changes past the
+          // server's response cap. Run the same path again to drain.
+          if (changes.hasMoreChanges) {
+            void get().fetchMailboxes();
+          }
+          return;
+        }
+        // changes === null → cannotCalculateChanges. Fall through to full.
+      }
+
+      const { list, state } = await getMailboxesWithState();
+      if (get().activeAccountId !== activeAccountId) return;
+      set({ mailboxes: list, mailboxState: state });
     } catch (err) {
       console.warn('[email-store] fetchMailboxes failed:', err);
-      set({ error: err instanceof Error ? err.message : 'Failed to load mailboxes' });
+      if (get().activeAccountId !== activeAccountId) return;
+      // Don't overwrite the cached list on a transient failure — the user
+      // can still navigate folders. Only surface the error when we have no
+      // mailboxes at all to show.
+      if (get().mailboxes.length === 0) {
+        set({ error: err instanceof Error ? err.message : 'Failed to load mailboxes' });
+      }
     }
   },
 
   selectMailbox: async (mailboxId) => {
-    // Reset search/filters when switching mailbox - matches webmail behavior.
-    // Switching mailboxes invalidates any pending undo: the snackbar would be
-    // stale and the restored email would re-appear in a different view.
+    const state = get();
+    // Tuck the previously-visible mailbox into its snapshot so a return-trip
+    // can restore it without a network call. Only do this for the base view —
+    // a filter or search makes the visible list unrepresentative of the
+    // cached "no-filter" snapshot.
+    let mailboxSnapshots = state.mailboxSnapshots;
+    if (
+      state.currentMailboxId &&
+      state.currentMailboxId !== mailboxId &&
+      isBaseView(state.searchQuery, state.filters)
+    ) {
+      mailboxSnapshots = {
+        ...mailboxSnapshots,
+        [state.currentMailboxId]: {
+          emails: state.emails,
+          total: state.totalEmails,
+          queryState: state.queryState,
+        },
+      };
+    }
+
+    const incoming = mailboxSnapshots[mailboxId];
+    // Swap to the new mailbox's cached view immediately. If there's no
+    // snapshot, fall through to the offline cache as a second-best seed;
+    // if that's also empty we render the empty-state, not a spinner over
+    // a blank list — better than the previous flash to "Loading…".
+    let seededEmails: Email[] = incoming?.emails ?? [];
+    let seededTotal = incoming?.total ?? 0;
+    let seededQueryState = incoming?.queryState;
+
+    if (seededEmails.length === 0) {
+      const cacheStore = useOfflineCacheStore.getState();
+      if (!cacheStore.hydrated) await cacheStore.hydrate();
+      if (cacheStore.totalCount() > 0) {
+        try {
+          const limit = useSettingsStore.getState().emailsPerPage;
+          seededEmails = await cacheStore.getEmailsInMailbox(mailboxId, Math.max(limit, 50));
+          seededTotal = seededEmails.length;
+        } catch (err) {
+          console.warn('[email-store] cache seed failed:', err);
+        }
+      }
+    }
+
     set({
       currentMailboxId: mailboxId,
+      emails: seededEmails,
+      totalEmails: seededTotal,
+      queryState: seededQueryState,
+      mailboxSnapshots,
       loading: true,
       error: null,
-      emails: [],
-      totalEmails: 0,
       searchQuery: '',
       filters: {},
       pendingUndo: null,
     });
-    try {
-      const filter = buildJmapFilter(mailboxId, '', {});
-      const limit = useSettingsStore.getState().emailsPerPage;
-      const { ids, total } = await queryEmails(mailboxId, { limit, filter });
-      const emails = ids.length > 0 ? await fetchEmails(ids) : [];
-      set({ emails, totalEmails: total, loading: false });
-    } catch (err) {
-      console.warn('[email-store] selectMailbox failed:', err);
-      set({ loading: false, error: err instanceof Error ? err.message : 'Failed to load emails' });
+
+    // Stop here if there's no live session OR jmapClient is mid-transition
+    // to a different account. The cached seed already gave the user
+    // something to look at, and the refetch driven by restoreSession() /
+    // switchAccount will run the network half once the client catches up.
+    if (!jmapClientServesActiveAccount(get().activeAccountId)) {
+      set({ loading: false });
+      return;
     }
+
+    await get().refreshEmails();
   },
 
   loadMoreEmails: async () => {
-    const { currentMailboxId, emails, totalEmails, loading, searchQuery, filters } = get();
+    const { currentMailboxId, emails, totalEmails, loading, searchQuery, filters, activeAccountId } = get();
     if (!currentMailboxId || loading || emails.length >= totalEmails) return;
+    if (!jmapClientServesActiveAccount(activeAccountId)) return;
 
     set({ loading: true });
     try {
@@ -174,28 +542,220 @@ export const useEmailStore = create<EmailState>()(
         limit,
         filter,
       });
-      const newEmails = ids.length > 0 ? await fetchEmails(ids) : [];
-      set({ emails: [...emails, ...newEmails], loading: false });
+      if (get().activeAccountId !== activeAccountId || get().currentMailboxId !== currentMailboxId) return;
+      const newEmails = ids.length > 0 ? await fetchEmailsChunked(ids) : [];
+      if (get().activeAccountId !== activeAccountId || get().currentMailboxId !== currentMailboxId) return;
+      const merged = [...emails, ...newEmails];
+      const updates: Partial<EmailState> = { emails: merged, loading: false };
+      if (isBaseView(searchQuery, filters)) {
+        updates.mailboxSnapshots = {
+          ...get().mailboxSnapshots,
+          [currentMailboxId]: {
+            emails: merged,
+            total: get().totalEmails,
+            queryState: get().queryState,
+          },
+        };
+      }
+      set(updates);
     } catch (err) {
+      if (get().activeAccountId !== activeAccountId) return;
       set({ loading: false, error: err instanceof Error ? err.message : 'Failed to load more' });
     }
   },
 
   refreshEmails: async () => {
-    const { currentMailboxId, searchQuery, filters } = get();
+    const state = get();
+    const { currentMailboxId, searchQuery, filters, emails: existing, queryState, emailState, activeAccountId } = state;
     if (!currentMailboxId) return;
-    // Keep existing emails visible while refreshing - swap atomically once
-    // the new list is ready so pull-to-refresh doesn't flash an empty list.
+    if (!jmapClientServesActiveAccount(activeAccountId)) return;
     set({ loading: true, error: null });
+
+    const filter = buildJmapFilter(currentMailboxId, searchQuery, filters);
+    const limit = useSettingsStore.getState().emailsPerPage;
+    const baseView = isBaseView(searchQuery, filters);
+
     try {
-      const filter = buildJmapFilter(currentMailboxId, searchQuery, filters);
-      const limit = useSettingsStore.getState().emailsPerPage;
-      const { ids, total } = await queryEmails(currentMailboxId, { limit, filter });
-      const emails = ids.length > 0 ? await fetchEmails(ids) : [];
-      set({ emails, totalEmails: total, loading: false });
+      // Incremental sync path: requires the base unfiltered view AND a known
+      // queryState (so Email/queryChanges has something to diff against).
+      // Anything else — search, filter active, first-ever load — falls
+      // through to a full re-query.
+      if (baseView && queryState) {
+        const queryChanges = await getEmailQueryChanges(currentMailboxId, queryState, {
+          filter: undefined,
+        });
+        if (queryChanges) {
+          // What's in the visible window now: drop removed ids, then apply
+          // added (id, index) entries. Newly added ids need bodies fetched.
+          const removed = new Set(queryChanges.removed);
+          const addedIds = queryChanges.added.map((a) => a.id);
+
+          // Email/changes catches updates to messages already in our list
+          // (e.g. another device toggled $seen) that queryChanges wouldn't
+          // report. Skipped when we have no emailState yet — first refresh
+          // after a cold start primes it from the Email/get below.
+          let updatedIds: string[] = [];
+          let destroyedExtra: string[] = [];
+          let nextEmailState: string | undefined = emailState;
+          if (emailState) {
+            const ec = await getEmailChanges(emailState);
+            if (ec) {
+              updatedIds = ec.updated;
+              destroyedExtra = ec.destroyed;
+              nextEmailState = ec.newState;
+            } else {
+              // cannotCalculateChanges → forget the state and rely on the
+              // next full re-sync to repopulate it.
+              nextEmailState = undefined;
+            }
+          }
+
+          // Fetch only what we don't already have. `addedIds` are new to the
+          // window; `updatedIds` may already be in `existing` but their
+          // keywords/mailboxIds need refreshing.
+          const existingById = new Map(existing.map((e) => [e.id, e]));
+          const idsToFetch = [
+            ...addedIds.filter((id) => !existingById.has(id)),
+            ...updatedIds.filter((id) => existingById.has(id)),
+          ];
+          let fetchState: string | undefined;
+          let fetched: Email[] = [];
+          if (idsToFetch.length > 0) {
+            const res = await getEmailsWithState(idsToFetch);
+            fetched = res.list;
+            fetchState = res.state;
+          }
+
+          // Rebuild the visible window order: start with existing emails,
+          // drop removed/destroyed, then splice added at their indices.
+          const allDestroyed = new Set([...destroyedExtra, ...removed]);
+          const kept = existing.filter((e) => !allDestroyed.has(e.id));
+          // Map updated entries onto kept array
+          const fetchedById = new Map(fetched.map((e) => [e.id, e]));
+          const updatedKept = kept.map((e) => fetchedById.get(e.id) ?? e);
+
+          // Insert added entries at the indices the server gave us. Sort
+          // ascending by index so each splice lands at the right offset.
+          const sortedAdded = [...queryChanges.added].sort((a, b) => a.index - b.index);
+          const out = [...updatedKept];
+          for (const entry of sortedAdded) {
+            const email = fetchedById.get(entry.id);
+            if (!email) continue;
+            const idx = Math.min(entry.index, out.length);
+            out.splice(idx, 0, email);
+          }
+          // Cap the visible list to the user's page size — Email/queryChanges
+          // can push entries past the original window if many were added.
+          const trimmed = out.slice(0, Math.max(limit, out.length));
+
+          const nextQueryState = queryChanges.newQueryState;
+          const nextTotal = queryChanges.total;
+
+          if (get().activeAccountId !== activeAccountId || get().currentMailboxId !== currentMailboxId) return;
+
+          set({
+            emails: trimmed,
+            totalEmails: nextTotal,
+            queryState: nextQueryState,
+            emailState: nextEmailState ?? fetchState ?? emailState,
+            loading: false,
+            mailboxSnapshots: {
+              ...get().mailboxSnapshots,
+              [currentMailboxId]: {
+                emails: trimmed,
+                total: nextTotal,
+                queryState: nextQueryState,
+              },
+            },
+          });
+          return;
+        }
+        // queryChanges === null → cannotCalculateChanges. Drop our queryState
+        // and fall through to a full re-query, which will repopulate it.
+      }
+
+      // Full re-query path. Used when there's no prior queryState, when the
+      // user has search/filters active (queryState only tracks the base
+      // query), or when the server returned cannotCalculateChanges above.
+      const queryRes = await queryEmails(currentMailboxId, { limit, filter });
+      const fetched = queryRes.ids.length > 0
+        ? await getEmailsWithState(queryRes.ids)
+        : { list: [], state: undefined as string | undefined };
+
+      if (get().currentMailboxId !== currentMailboxId) return;
+
+      const updates: Partial<EmailState> = {
+        emails: fetched.list,
+        totalEmails: queryRes.total,
+        loading: false,
+      };
+      if (baseView) {
+        updates.queryState = queryRes.queryState;
+        updates.emailState = fetched.state;
+        updates.mailboxSnapshots = {
+          ...get().mailboxSnapshots,
+          [currentMailboxId]: {
+            emails: fetched.list,
+            total: queryRes.total,
+            queryState: queryRes.queryState,
+          },
+        };
+      }
+      set(updates);
     } catch (err) {
       console.warn('[email-store] refreshEmails failed:', err);
-      set({ loading: false, error: err instanceof Error ? err.message : 'Failed to load emails' });
+      if (get().activeAccountId !== activeAccountId || get().currentMailboxId !== currentMailboxId) return;
+      // Keep whatever's visible; only surface the error when the list is
+      // empty. With cached emails on screen the OfflineBanner already
+      // tells the user the data is stale.
+      if (existing.length === 0) {
+        try {
+          const cacheStore = useOfflineCacheStore.getState();
+          if (!cacheStore.hydrated) await cacheStore.hydrate();
+          if (cacheStore.totalCount() > 0) {
+            const cached = await cacheStore.getEmailsInMailbox(
+              currentMailboxId,
+              Math.max(limit, 50),
+            );
+            if (
+              get().activeAccountId === activeAccountId &&
+              get().currentMailboxId === currentMailboxId &&
+              cached.length > 0
+            ) {
+              set({ emails: cached, totalEmails: cached.length, loading: false, error: null });
+              return;
+            }
+          }
+        } catch (cacheErr) {
+          console.warn('[email-store] refresh cache fallback failed:', cacheErr);
+        }
+      }
+      set({
+        loading: false,
+        error: existing.length > 0 ? null : (err instanceof Error ? err.message : 'Failed to load emails'),
+      });
+    }
+  },
+
+  handleStateChange: async (change) => {
+    if (!jmapClient.currentSession) return;
+    // Drop changes that arrived for a different account than the one we're
+    // currently showing (e.g. push notifications received during/just after
+    // an account switch).
+    if (!jmapClientServesActiveAccount(get().activeAccountId)) return;
+    const accountId = jmapClient.accountId;
+    const accountChanges = change.changed?.[accountId];
+    if (!accountChanges) return;
+
+    const mailboxChanged = 'Mailbox' in accountChanges;
+    const emailChanged = 'Email' in accountChanges || 'EmailDelivery' in accountChanges;
+    if (!mailboxChanged && !emailChanged) return;
+
+    if (mailboxChanged) {
+      await get().fetchMailboxes();
+    }
+    if (emailChanged && get().currentMailboxId) {
+      await get().refreshEmails();
     }
   },
 
@@ -217,7 +777,27 @@ export const useEmailStore = create<EmailState>()(
   },
 
   getEmailDetail: async (id) => {
-    return getFullEmail(id);
+    // Try the network first so the user sees fresh keywords/flags. If that
+    // fails (offline / server unreachable), fall back to the offline cache
+    // when the message is in it. Without the cache hit, propagate the error
+    // so the caller can surface it.
+    try {
+      const fresh = await getFullEmail(id);
+      // Opportunistically refresh the cached copy so the next offline open
+      // reflects the latest keywords without needing a full sync.
+      const cache = useOfflineCacheStore.getState();
+      if (cache.has(id)) {
+        try {
+          const size = JSON.stringify(fresh).length;
+          await cache.put(fresh, size);
+        } catch { /* ignore — best-effort refresh */ }
+      }
+      return fresh;
+    } catch (err) {
+      const cached = await useOfflineCacheStore.getState().get(id);
+      if (cached) return cached;
+      throw err;
+    }
   },
 
   markRead: async (emailId) => {
@@ -418,9 +998,13 @@ export const useEmailStore = create<EmailState>()(
 
   reset: () => set({
     mailboxes: [],
+    mailboxState: undefined,
+    emailState: undefined,
     currentMailboxId: null,
+    mailboxSnapshots: {},
     emails: [],
     totalEmails: 0,
+    queryState: undefined,
     loading: false,
     error: null,
     searchQuery: '',
@@ -428,16 +1012,23 @@ export const useEmailStore = create<EmailState>()(
   }),
     }),
     {
-      // Persist the mail list so the UI can render instantly on re-open,
-      // before the JMAP session has finished restoring. auth-store triggers
-      // a background refresh once the session is ready.
+      // Persist the per-account caches and the active view so the UI can
+      // render instantly on re-open / account switch, before the JMAP
+      // session has finished restoring. auth-store triggers a background
+      // refresh once the session is ready.
       name: 'email-cache',
       storage: createJSONStorage(() => AsyncStorage),
       partialize: (state) => ({
+        accountSnapshots: state.accountSnapshots,
+        activeAccountId: state.activeAccountId,
         mailboxes: state.mailboxes,
+        mailboxState: state.mailboxState,
+        emailState: state.emailState,
         currentMailboxId: state.currentMailboxId,
+        mailboxSnapshots: state.mailboxSnapshots,
         emails: state.emails,
         totalEmails: state.totalEmails,
+        queryState: state.queryState,
       }),
     },
   ),

src/stores/offline-cache-store.ts

@@ -0,0 +1,278 @@
+// Persistent cache for full email bodies (and optional attachment blobs)
+// powering offline mail viewing. Bodies are JSON-serialised and kept in
+// AsyncStorage; attachment blobs go to expo-file-system under
+// `Paths.document/offline-attachments/`. The store also exposes the live
+// progress state the OfflineCacheBanner reads from.
+//
+// Storage is keyed by the email-store's `activeAccountId` so logged-in
+// accounts don't leak cached bodies into each other. The store loads one
+// account's bucket at a time (the active one); switching accounts via
+// setAccount() persists the current bucket then hydrates the new one.
+
+import { create } from 'zustand';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { Email } from '../api/types';
+
+const INDEX_KEY_PREFIX = 'webmail:offline-cache:index:v2:';
+const ENTRY_KEY_PREFIX = 'webmail:offline-cache:entry:v2:';
+
+function indexKey(accountId: string): string {
+  return `${INDEX_KEY_PREFIX}${accountId}`;
+}
+
+function entryKey(accountId: string, emailId: string): string {
+  return `${ENTRY_KEY_PREFIX}${accountId}:${emailId}`;
+}
+
+export interface OfflineCacheIndexEntry {
+  id: string;
+  receivedAt: string;
+  size: number;          // approx bytes of cached payload
+  cachedAt: number;
+}
+
+interface CacheIndex {
+  entries: Record<string, OfflineCacheIndexEntry>;
+}
+
+export type SyncPhase = 'idle' | 'scanning' | 'fetching' | 'done' | 'error' | 'cancelled';
+
+export interface SyncState {
+  phase: SyncPhase;
+  total: number;       // total emails the sync expects to process
+  completed: number;   // emails processed (skipped or fetched)
+  fetched: number;     // emails actually downloaded (not already cached)
+  bytes: number;       // bytes downloaded this run
+  message?: string;    // human-readable status (errors etc.)
+  startedAt?: number;
+  finishedAt?: number;
+}
+
+const IDLE: SyncState = { phase: 'idle', total: 0, completed: 0, fetched: 0, bytes: 0 };
+const EMPTY_INDEX: CacheIndex = { entries: {} };
+
+interface OfflineCacheState {
+  // Currently-loaded bucket. null = no account active (no reads/writes).
+  activeAccountId: string | null;
+  index: CacheIndex;
+  hydrated: boolean;
+  sync: SyncState;
+  // Allows the sync orchestrator to abort mid-run when the user disables the
+  // setting or kicks off a fresh sync. Stored on the singleton because
+  // AbortControllers need to survive across the function boundary.
+  abortRequested: boolean;
+
+  // Point the store at the given account, hydrating its bucket from
+  // AsyncStorage. Pass null to detach (no reads/writes will hit storage).
+  setAccount: (accountId: string | null) => Promise<void>;
+  hydrate: () => Promise<void>;
+  has: (id: string) => boolean;
+  get: (id: string) => Promise<Email | null>;
+  put: (email: Email, approxBytes: number) => Promise<void>;
+  remove: (ids: string[]) => Promise<void>;
+  clearAll: () => Promise<void>;
+
+  // Returns cached emails whose `mailboxIds` include the given mailbox,
+  // sorted by `receivedAt` descending. Used by selectMailbox to seed the
+  // list when the network is unavailable. Loads each entry from
+  // AsyncStorage; the index doesn't carry the mailbox set.
+  getEmailsInMailbox: (mailboxId: string, limit?: number) => Promise<Email[]>;
+
+  totalSize: () => number;
+  totalCount: () => number;
+
+  setSyncState: (next: Partial<SyncState>) => void;
+  resetSync: () => void;
+  requestAbort: () => void;
+  consumeAbort: () => boolean;
+}
+
+function persistIndex(accountId: string, index: CacheIndex): void {
+  void AsyncStorage.setItem(indexKey(accountId), JSON.stringify(index)).catch((err) => {
+    console.warn('[offline-cache] persist index failed', err);
+  });
+}
+
+async function loadIndex(accountId: string): Promise<CacheIndex> {
+  try {
+    const raw = await AsyncStorage.getItem(indexKey(accountId));
+    if (raw) {
+      const parsed = JSON.parse(raw) as CacheIndex;
+      if (parsed && typeof parsed === 'object' && parsed.entries) {
+        return parsed;
+      }
+    }
+  } catch (err) {
+    console.warn('[offline-cache] hydrate failed', err);
+  }
+  return { entries: {} };
+}
+
+export const useOfflineCacheStore = create<OfflineCacheState>((set, get) => ({
+  activeAccountId: null,
+  index: { entries: {} },
+  hydrated: false,
+  sync: { ...IDLE },
+  abortRequested: false,
+
+  setAccount: async (accountId) => {
+    const state = get();
+    if (state.activeAccountId === accountId) {
+      // Same account — make sure we've hydrated.
+      if (!state.hydrated) await get().hydrate();
+      return;
+    }
+    // Drop any in-flight sync state from the previous account; the abort flag
+    // makes runOfflineSync stop on its next chunk boundary.
+    set({
+      activeAccountId: accountId,
+      index: { ...EMPTY_INDEX },
+      hydrated: false,
+      sync: { ...IDLE },
+      abortRequested: true,
+    });
+    if (accountId) {
+      const index = await loadIndex(accountId);
+      // Re-check in case another setAccount call raced past us.
+      if (get().activeAccountId !== accountId) return;
+      set({ index, hydrated: true, abortRequested: false });
+    } else {
+      set({ hydrated: true, abortRequested: false });
+    }
+  },
+
+  hydrate: async () => {
+    const state = get();
+    if (state.hydrated) return;
+    const accountId = state.activeAccountId;
+    if (!accountId) {
+      // No active account yet — mark hydrated so callers that block on this
+      // (selectMailbox cache-seed path) don't spin. Reads will return empty.
+      set({ hydrated: true });
+      return;
+    }
+    const index = await loadIndex(accountId);
+    if (get().activeAccountId !== accountId) return;
+    set({ index, hydrated: true });
+  },
+
+  has: (id) => Boolean(get().index.entries[id]),
+
+  get: async (id) => {
+    const state = get();
+    if (!state.activeAccountId) return null;
+    if (!state.index.entries[id]) return null;
+    try {
+      const raw = await AsyncStorage.getItem(entryKey(state.activeAccountId, id));
+      if (!raw) return null;
+      return JSON.parse(raw) as Email;
+    } catch (err) {
+      console.warn('[offline-cache] get failed', id, err);
+      return null;
+    }
+  },
+
+  put: async (email, approxBytes) => {
+    const state = get();
+    const accountId = state.activeAccountId;
+    if (!accountId) return;
+    try {
+      await AsyncStorage.setItem(entryKey(accountId, email.id), JSON.stringify(email));
+    } catch (err) {
+      console.warn('[offline-cache] put failed', email.id, err);
+      return;
+    }
+    // Re-read the active account in case it changed while we were awaiting
+    // AsyncStorage — don't stamp the new account's index with the old
+    // account's entry.
+    if (get().activeAccountId !== accountId) return;
+    const nextEntries = {
+      ...get().index.entries,
+      [email.id]: {
+        id: email.id,
+        receivedAt: email.receivedAt,
+        size: approxBytes,
+        cachedAt: Date.now(),
+      },
+    };
+    const index = { entries: nextEntries };
+    set({ index });
+    persistIndex(accountId, index);
+  },
+
+  remove: async (ids) => {
+    if (ids.length === 0) return;
+    const accountId = get().activeAccountId;
+    if (!accountId) return;
+    await Promise.all(
+      ids.map((id) => AsyncStorage.removeItem(entryKey(accountId, id)).catch(() => undefined)),
+    );
+    if (get().activeAccountId !== accountId) return;
+    const next = { ...get().index.entries };
+    for (const id of ids) delete next[id];
+    const index = { entries: next };
+    set({ index });
+    persistIndex(accountId, index);
+  },
+
+  clearAll: async () => {
+    const accountId = get().activeAccountId;
+    if (!accountId) return;
+    const ids = Object.keys(get().index.entries);
+    await Promise.all(
+      ids.map((id) => AsyncStorage.removeItem(entryKey(accountId, id)).catch(() => undefined)),
+    );
+    if (get().activeAccountId !== accountId) return;
+    const index = { entries: {} };
+    set({ index, sync: { ...IDLE } });
+    persistIndex(accountId, index);
+  },
+
+  getEmailsInMailbox: async (mailboxId, limit = 200) => {
+    const state = get();
+    const accountId = state.activeAccountId;
+    if (!accountId) return [];
+    // Sort the index by receivedAt descending first so we don't have to read
+    // entries we won't return — the index already carries receivedAt.
+    const sorted = Object.values(state.index.entries).sort((a, b) => {
+      const at = a.receivedAt ? new Date(a.receivedAt).getTime() : 0;
+      const bt = b.receivedAt ? new Date(b.receivedAt).getTime() : 0;
+      return bt - at;
+    });
+    const matches: Email[] = [];
+    for (const entry of sorted) {
+      if (matches.length >= limit) break;
+      try {
+        const raw = await AsyncStorage.getItem(entryKey(accountId, entry.id));
+        if (!raw) continue;
+        const email = JSON.parse(raw) as Email;
+        if (email.mailboxIds?.[mailboxId]) {
+          matches.push(email);
+        }
+      } catch {
+        // skip corrupt entries — they'll be replaced on next sync
+      }
+    }
+    return matches;
+  },
+
+  totalSize: () => {
+    let n = 0;
+    for (const e of Object.values(get().index.entries)) n += e.size;
+    return n;
+  },
+
+  totalCount: () => Object.keys(get().index.entries).length,
+
+  setSyncState: (next) => set({ sync: { ...get().sync, ...next } }),
+
+  resetSync: () => set({ sync: { ...IDLE }, abortRequested: false }),
+
+  requestAbort: () => set({ abortRequested: true }),
+
+  consumeAbort: () => {
+    const v = get().abortRequested;
+    if (v) set({ abortRequested: false });
+    return v;
+  },
+}));

src/stores/settings-store.ts

@@ -131,6 +131,13 @@ interface PersistedSettings {
 
   // Plugins (UI-level enable map)
   pluginEnabled: Record<string, boolean>;
+
+  // Offline mail cache: download recent message bodies in the background so
+  // they can be opened without network. Days windows the lookback. Attachment
+  // caching is intentionally not implemented yet — bodies-only is much
+  // smaller and covers the "open recent mail offline" UX on its own.
+  offlineCacheEnabled: boolean;
+  offlineCacheDays: number;
 }
 
 const DEFAULT_PERSISTED: PersistedSettings = {
@@ -207,6 +214,9 @@ const DEFAULT_PERSISTED: PersistedSettings = {
   filtersExpandedView: false,
 
   pluginEnabled: {},
+
+  offlineCacheEnabled: false,
+  offlineCacheDays: 7,
 };
 
 export interface SettingsState extends PersistedSettings {

src/stores/updates-store.ts

@@ -108,9 +108,15 @@ export const useUpdatesStore = create<UpdatesState>((set, get) => ({
     if (s.installing || !s.cachedLatest?.apkAsset) return;
     set({ installing: true, error: null, installProgress: { phase: 'downloading', progress: 0 } });
     try {
-      await downloadAndInstallApk(s.cachedLatest.apkAsset, (p) => {
-        set({ installProgress: p });
-      });
+      await downloadAndInstallApk(
+        {
+          asset: s.cachedLatest.apkAsset,
+          expectedSha256: s.cachedLatest.apkSha256,
+        },
+        (p) => {
+          set({ installProgress: p });
+        },
+      );
       set({ installing: false, installProgress: null });
     } catch (err) {
       set({

src/test-setup.ts

@@ -0,0 +1,74 @@
+// Vitest setup. Two pieces of plumbing the unit tests need:
+//
+// 1. AsyncStorage: the Zustand `persist` middleware used by several stores
+//    reaches in during `set()` calls, which on a `node` environment crashes
+//    inside the RN AsyncStorage shim (no `window` global). Swap in an
+//    in-memory implementation.
+// 2. react-native: the bundled entry point is Flow-typed and rolldown can't
+//    parse it. Stub the few surfaces used at module-load time so any store
+//    that transitively imports `react-native` (via push / client-cert
+//    bridges) loads cleanly. Tests that actually exercise native modules
+//    re-mock the relevant module locally.
+
+import { vi } from 'vitest';
+
+const memory = new Map<string, string>();
+
+vi.mock('@react-native-async-storage/async-storage', () => ({
+  default: {
+    getItem: vi.fn(async (key: string) => memory.get(key) ?? null),
+    setItem: vi.fn(async (key: string, value: string) => {
+      memory.set(key, value);
+    }),
+    removeItem: vi.fn(async (key: string) => {
+      memory.delete(key);
+    }),
+    clear: vi.fn(async () => {
+      memory.clear();
+    }),
+    getAllKeys: vi.fn(async () => Array.from(memory.keys())),
+    multiGet: vi.fn(async (keys: string[]) =>
+      keys.map((k) => [k, memory.get(k) ?? null] as [string, string | null]),
+    ),
+    multiSet: vi.fn(async (pairs: [string, string][]) => {
+      for (const [k, v] of pairs) memory.set(k, v);
+    }),
+    multiRemove: vi.fn(async (keys: string[]) => {
+      for (const k of keys) memory.delete(k);
+    }),
+  },
+}));
+
+vi.mock('react-native', () => {
+  class NativeEventEmitter {
+    addListener() {
+      return { remove: () => undefined };
+    }
+    removeAllListeners() {}
+  }
+  return {
+    Platform: { OS: 'android', Version: 33, select: <T,>(spec: { default?: T; android?: T; ios?: T }) => spec.android ?? spec.default ?? spec.ios },
+    NativeModules: {},
+    NativeEventEmitter,
+    PermissionsAndroid: {
+      RESULTS: { GRANTED: 'granted', DENIED: 'denied', NEVER_ASK_AGAIN: 'never_ask_again' },
+      request: async () => 'granted',
+    },
+    Linking: { openURL: async () => undefined },
+    Appearance: { getColorScheme: () => 'dark', addChangeListener: () => ({ remove: () => undefined }) },
+  };
+});
+
+vi.mock('expo-secure-store', () => ({
+  setItemAsync: vi.fn(async () => undefined),
+  getItemAsync: vi.fn(async () => null),
+  deleteItemAsync: vi.fn(async () => undefined),
+}));
+
+// expo-web-browser transitively pulls in expo-modules-core, which evaluates
+// RN-only globals at module load. The unit tests don't exercise the real
+// browser handoff flow, so stubbing the surface is enough.
+vi.mock('expo-web-browser', () => ({
+  openAuthSessionAsync: vi.fn(async () => ({ type: 'cancel' as const })),
+  maybeCompleteAuthSession: vi.fn(),
+}));

vitest.config.ts

@@ -5,5 +5,6 @@ export default defineConfig({
     globals: true,
     environment: 'node',
     include: ['src/**/__tests__/**/*.test.ts'],
+    setupFiles: ['src/test-setup.ts'],
   },
 });