From ffbb88222778389ee0941f21ff64c3f9ed5f0f01 Mon Sep 17 00:00:00 2001 From: Jason Ross Date: Tue, 30 Jun 2026 23:56:18 -0500 Subject: [PATCH] feat(backup): opt-in Android Backup for settings only Add an opt-in (off by default) toggle to include app data in system Android Backup / Auto Backup, gated so only re-creatable user preferences are ever backed up. - Flip allowBackup to true and add LibreMailBackupAgent, which enforces the runtime opt-in: onFullBackup runs only when the user enables "Include settings in Android Backup" (default off), so no data leaves the device otherwise. allowBackup is a manifest flag and can't be toggled at runtime, hence the agent. - Rewrite data_extraction_rules.xml (API 31+) and add backup_rules.xml (API 29-30) as strict allowlists that back up ONLY the libremail_settings DataStore. The Keystore-sealed cache passphrase (libremail_dbkey) and the encrypted credentials + mail-cache database (libremail.db) are excluded by omission; the cache re-downloads on next sync. - Add includeInBackup preference + setter (nudges BackupManager on change) and a "Backup" settings section with F-Droid-honest copy (off by default, uses Google infrastructure). - BackupPolicy is the single source of truth for eligible/excluded paths; unit tests cover the toggle default and assert the shipped XML resources include only settings and never the secrets/DB. Co-Authored-By: Claude Opus 4.8 --- app/src/main/AndroidManifest.xml | 11 ++- .../org/libremail/backup/BackupPolicy.kt | 40 +++++++++ .../libremail/backup/LibreMailBackupAgent.kt | 42 +++++++++ .../data/settings/SettingsRepository.kt | 87 ++++++++++++------- .../libremail/ui/settings/SettingsScreen.kt | 9 ++ .../ui/settings/SettingsViewModel.kt | 1 + app/src/main/res/values/strings.xml | 5 ++ app/src/main/res/xml/backup_rules.xml | 16 ++++ .../main/res/xml/data_extraction_rules.xml | 23 +++-- .../org/libremail/backup/BackupPolicyTest.kt | 46 ++++++++++ .../backup/DataExtractionRulesTest.kt | 76 ++++++++++++++++ 11 files changed, 318 insertions(+), 38 deletions(-) create mode 100644 app/src/main/kotlin/org/libremail/backup/BackupPolicy.kt create mode 100644 app/src/main/kotlin/org/libremail/backup/LibreMailBackupAgent.kt create mode 100644 app/src/main/res/xml/backup_rules.xml create mode 100644 app/src/test/kotlin/org/libremail/backup/BackupPolicyTest.kt create mode 100644 app/src/test/kotlin/org/libremail/backup/DataExtractionRulesTest.kt diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml index 8ee562c..a942157 100644 --- a/app/src/main/AndroidManifest.xml +++ b/app/src/main/AndroidManifest.xml @@ -10,10 +10,19 @@ + = listOf( + // Keystore-sealed SQLCipher passphrase for the encrypted cache: the wrapping key is + // non-exportable and device-bound, so this ciphertext is useless anywhere else. + "datastore/libremail_dbkey.preferences_pb", + ) + + /** `databases`-dir-relative names that must never leave the device (encrypted credentials + mail cache). */ + val EXCLUDED_DATABASE_PATHS: List = listOf( + "libremail.db", + "libremail.db-wal", + "libremail.db-shm", + "libremail.db-journal", + ) + + /** + * Whether Android Backup may run for this app. Opt-in and OFF by default: nothing is backed up + * (or transferred device-to-device) unless the user has explicitly enabled it in Settings. + */ + fun shouldBackUp(settings: AppSettings): Boolean = settings.includeInBackup +} diff --git a/app/src/main/kotlin/org/libremail/backup/LibreMailBackupAgent.kt b/app/src/main/kotlin/org/libremail/backup/LibreMailBackupAgent.kt new file mode 100644 index 0000000..c62629d --- /dev/null +++ b/app/src/main/kotlin/org/libremail/backup/LibreMailBackupAgent.kt @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: GPL-3.0-or-later +package org.libremail.backup + +import android.app.backup.BackupAgentHelper +import android.app.backup.FullBackupDataOutput +import kotlinx.coroutines.flow.first +import kotlinx.coroutines.runBlocking +import org.libremail.data.settings.settingsDataStore +import org.libremail.data.settings.toAppSettings + +/** + * Enforces the runtime backup opt-in on top of Android Auto Backup. + * + * `android:allowBackup` is a manifest flag that can't be toggled at runtime, so the "include settings + * in Android Backup" preference is enforced here instead: [onFullBackup] runs the backup only when the + * user has opted in (the default is off, so no app data leaves the device). When opted in, it defers to + * the framework, which applies the allowlist in `res/xml/data_extraction_rules.xml` (and + * `res/xml/backup_rules.xml` on API < 31) — backing up the user-preferences DataStore only, never the + * mail cache, the encrypted credentials, or the Keystore-sealed cache passphrase. + * + * Extends [BackupAgentHelper] (rather than raw `BackupAgent`) so the unused key/value backup/restore + * paths inherit safe no-op implementations; only full-data backup is used (`fullBackupOnly=true`), and + * full-data restore uses the default `onRestoreFile` handling. + * + * The opt-in flag is read directly from the shared [settingsDataStore] singleton so it does not depend + * on Hilt or `Application.onCreate` having run in the framework's restricted backup mode. + */ +class LibreMailBackupAgent : BackupAgentHelper() { + + override fun onFullBackup(data: FullBackupDataOutput) { + if (backupOptedIn()) { + super.onFullBackup(data) + } + } + + /** Reads the opt-in flag; any failure defaults to "not opted in" so we never back up by accident. */ + private fun backupOptedIn(): Boolean = runCatching { + runBlocking { + BackupPolicy.shouldBackUp(applicationContext.settingsDataStore.data.first().toAppSettings()) + } + }.getOrDefault(false) +} diff --git a/app/src/main/kotlin/org/libremail/data/settings/SettingsRepository.kt b/app/src/main/kotlin/org/libremail/data/settings/SettingsRepository.kt index 6df882d..553ae00 100644 --- a/app/src/main/kotlin/org/libremail/data/settings/SettingsRepository.kt +++ b/app/src/main/kotlin/org/libremail/data/settings/SettingsRepository.kt @@ -1,6 +1,7 @@ // SPDX-License-Identifier: GPL-3.0-or-later package org.libremail.data.settings +import android.app.backup.BackupManager import android.content.Context import androidx.datastore.core.DataStore import androidx.datastore.preferences.core.Preferences @@ -15,7 +16,15 @@ import kotlinx.coroutines.flow.map import javax.inject.Inject import javax.inject.Singleton -private val Context.settingsDataStore: DataStore by preferencesDataStore(name = "libremail_settings") +/** + * User-preferences DataStore. Exposed as `internal` (not `private`) and read via [toAppSettings] so + * that [org.libremail.backup.LibreMailBackupAgent] can consult the backup opt-in flag through the + * exact same singleton instance. The system instantiates the backup agent in the app process while + * the app may already hold this DataStore open; constructing a second DataStore for the same file + * would crash with "There are multiple DataStores active for the same file", so both sides must go + * through this one delegate. + */ +internal val Context.settingsDataStore: DataStore by preferencesDataStore(name = "libremail_settings") /** * How aggressively the app downloads message content during sync. @@ -33,23 +42,40 @@ data class AppSettings( val allowStartTls: Boolean = false, val loadRemoteImages: Boolean = false, val encryptCache: Boolean = false, + val includeInBackup: Boolean = false, val fetchPolicy: FetchPolicy = FetchPolicy.ALWAYS, ) +private object Keys { + val DYNAMIC_COLOR = booleanPreferencesKey("dynamic_color") + val NEW_MAIL_NOTIFICATIONS = booleanPreferencesKey("new_mail_notifications") + val PUSH_IDLE = booleanPreferencesKey("push_idle") + val ALLOW_STARTTLS = booleanPreferencesKey("allow_starttls") + val LOAD_REMOTE_IMAGES = booleanPreferencesKey("load_remote_images") + val ENCRYPT_CACHE = booleanPreferencesKey("encrypt_cache") + val INCLUDE_IN_BACKUP = booleanPreferencesKey("include_in_backup") + val FETCH_POLICY = stringPreferencesKey("fetch_policy") +} + +/** + * Maps persisted preferences to [AppSettings]. Shared with the backup agent so it reads the opt-in + * flag (and its default) through exactly the same logic the app uses. + */ +internal fun Preferences.toAppSettings(): AppSettings = AppSettings( + dynamicColor = this[Keys.DYNAMIC_COLOR] ?: true, + newMailNotifications = this[Keys.NEW_MAIL_NOTIFICATIONS] ?: true, + pushIdle = this[Keys.PUSH_IDLE] ?: true, + allowStartTls = this[Keys.ALLOW_STARTTLS] ?: false, + loadRemoteImages = this[Keys.LOAD_REMOTE_IMAGES] ?: false, + encryptCache = this[Keys.ENCRYPT_CACHE] ?: false, + includeInBackup = this[Keys.INCLUDE_IN_BACKUP] ?: false, + fetchPolicy = this[Keys.FETCH_POLICY]?.let { runCatching { FetchPolicy.valueOf(it) }.getOrNull() } + ?: FetchPolicy.ALWAYS, +) + @Singleton class SettingsRepository @Inject constructor(@ApplicationContext private val context: Context) { - val settings: Flow = context.settingsDataStore.data.map { prefs -> - AppSettings( - dynamicColor = prefs[DYNAMIC_COLOR] ?: true, - newMailNotifications = prefs[NEW_MAIL_NOTIFICATIONS] ?: true, - pushIdle = prefs[PUSH_IDLE] ?: true, - allowStartTls = prefs[ALLOW_STARTTLS] ?: false, - loadRemoteImages = prefs[LOAD_REMOTE_IMAGES] ?: false, - encryptCache = prefs[ENCRYPT_CACHE] ?: false, - fetchPolicy = prefs[FETCH_POLICY]?.let { runCatching { FetchPolicy.valueOf(it) }.getOrNull() } - ?: FetchPolicy.ALWAYS, - ) - } + val settings: Flow = context.settingsDataStore.data.map { it.toAppSettings() } val dynamicColor: Flow = settings.map { it.dynamicColor } @@ -57,27 +83,28 @@ class SettingsRepository @Inject constructor(@ApplicationContext private val con suspend fun fetchPolicy(): FetchPolicy = settings.first().fetchPolicy - suspend fun setDynamicColor(value: Boolean) = put(DYNAMIC_COLOR, value) - suspend fun setNewMailNotifications(value: Boolean) = put(NEW_MAIL_NOTIFICATIONS, value) - suspend fun setPushIdle(value: Boolean) = put(PUSH_IDLE, value) - suspend fun setAllowStartTls(value: Boolean) = put(ALLOW_STARTTLS, value) - suspend fun setLoadRemoteImages(value: Boolean) = put(LOAD_REMOTE_IMAGES, value) - suspend fun setEncryptCache(value: Boolean) = put(ENCRYPT_CACHE, value) + suspend fun setDynamicColor(value: Boolean) = put(Keys.DYNAMIC_COLOR, value) + suspend fun setNewMailNotifications(value: Boolean) = put(Keys.NEW_MAIL_NOTIFICATIONS, value) + suspend fun setPushIdle(value: Boolean) = put(Keys.PUSH_IDLE, value) + suspend fun setAllowStartTls(value: Boolean) = put(Keys.ALLOW_STARTTLS, value) + suspend fun setLoadRemoteImages(value: Boolean) = put(Keys.LOAD_REMOTE_IMAGES, value) + suspend fun setEncryptCache(value: Boolean) = put(Keys.ENCRYPT_CACHE, value) + + /** + * Opts this app in/out of system Android Backup. Off by default. After persisting, nudges the + * framework so the change takes effect on the next backup pass — enabling schedules a backup of + * the safe settings, disabling schedules one that ships nothing (clearing any prior cloud copy). + */ + suspend fun setIncludeInBackup(value: Boolean) { + put(Keys.INCLUDE_IN_BACKUP, value) + runCatching { BackupManager(context).dataChanged() } + } + suspend fun setFetchPolicy(value: FetchPolicy) { - context.settingsDataStore.edit { it[FETCH_POLICY] = value.name } + context.settingsDataStore.edit { it[Keys.FETCH_POLICY] = value.name } } private suspend fun put(key: Preferences.Key, value: Boolean) { context.settingsDataStore.edit { it[key] = value } } - - private companion object { - val DYNAMIC_COLOR = booleanPreferencesKey("dynamic_color") - val NEW_MAIL_NOTIFICATIONS = booleanPreferencesKey("new_mail_notifications") - val PUSH_IDLE = booleanPreferencesKey("push_idle") - val ALLOW_STARTTLS = booleanPreferencesKey("allow_starttls") - val LOAD_REMOTE_IMAGES = booleanPreferencesKey("load_remote_images") - val ENCRYPT_CACHE = booleanPreferencesKey("encrypt_cache") - val FETCH_POLICY = stringPreferencesKey("fetch_policy") - } } diff --git a/app/src/main/kotlin/org/libremail/ui/settings/SettingsScreen.kt b/app/src/main/kotlin/org/libremail/ui/settings/SettingsScreen.kt index 32d925b..cab7c02 100644 --- a/app/src/main/kotlin/org/libremail/ui/settings/SettingsScreen.kt +++ b/app/src/main/kotlin/org/libremail/ui/settings/SettingsScreen.kt @@ -113,6 +113,15 @@ fun SettingsScreen( ) HorizontalDivider() + SectionHeader(stringResource(R.string.settings_backup)) + SwitchRow( + title = stringResource(R.string.settings_backup_include), + checked = settings.includeInBackup, + onCheckedChange = viewModel::setIncludeInBackup, + subtitle = stringResource(R.string.settings_backup_include_summary), + ) + HorizontalDivider() + AdvancedHeader(expanded = advancedExpanded, onToggle = viewModel::toggleAdvanced) AnimatedVisibility(visible = advancedExpanded) { Column { diff --git a/app/src/main/kotlin/org/libremail/ui/settings/SettingsViewModel.kt b/app/src/main/kotlin/org/libremail/ui/settings/SettingsViewModel.kt index 6006e83..52da6d4 100644 --- a/app/src/main/kotlin/org/libremail/ui/settings/SettingsViewModel.kt +++ b/app/src/main/kotlin/org/libremail/ui/settings/SettingsViewModel.kt @@ -41,6 +41,7 @@ class SettingsViewModel @Inject constructor( fun setAllowStartTls(value: Boolean) = update { settingsRepository.setAllowStartTls(value) } fun setLoadRemoteImages(value: Boolean) = update { settingsRepository.setLoadRemoteImages(value) } fun setEncryptCache(value: Boolean) = update { settingsRepository.setEncryptCache(value) } + fun setIncludeInBackup(value: Boolean) = update { settingsRepository.setIncludeInBackup(value) } fun setFetchPolicy(value: FetchPolicy) = update { settingsRepository.setFetchPolicy(value) } private inline fun update(crossinline action: suspend () -> Unit) { diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml index a4df47f..33b1ab9 100644 --- a/app/src/main/res/values/strings.xml +++ b/app/src/main/res/values/strings.xml @@ -143,6 +143,11 @@ No accounts yet Remove account + + Backup + Include settings in Android Backup + Let Android back up your LibreMail preferences (Google Auto Backup) so they restore when you set up a new device. Your mail, accounts, passwords, and encryption keys are never backed up — only app settings. Off by default; uses Google infrastructure. + Account Signature diff --git a/app/src/main/res/xml/backup_rules.xml b/app/src/main/res/xml/backup_rules.xml new file mode 100644 index 0000000..0059fd1 --- /dev/null +++ b/app/src/main/res/xml/backup_rules.xml @@ -0,0 +1,16 @@ + + + + + + diff --git a/app/src/main/res/xml/data_extraction_rules.xml b/app/src/main/res/xml/data_extraction_rules.xml index 39841b1..0f07896 100644 --- a/app/src/main/res/xml/data_extraction_rules.xml +++ b/app/src/main/res/xml/data_extraction_rules.xml @@ -1,17 +1,26 @@ - + - + diff --git a/app/src/test/kotlin/org/libremail/backup/BackupPolicyTest.kt b/app/src/test/kotlin/org/libremail/backup/BackupPolicyTest.kt new file mode 100644 index 0000000..c9d0924 --- /dev/null +++ b/app/src/test/kotlin/org/libremail/backup/BackupPolicyTest.kt @@ -0,0 +1,46 @@ +// SPDX-License-Identifier: GPL-3.0-or-later +package org.libremail.backup + +import org.junit.Test +import org.libremail.data.settings.AppSettings +import kotlin.test.assertEquals +import kotlin.test.assertFalse +import kotlin.test.assertTrue + +class BackupPolicyTest { + + @Test + fun `backup is off by default`() { + assertFalse(AppSettings().includeInBackup, "the opt-in default must be off") + assertFalse(BackupPolicy.shouldBackUp(AppSettings()), "no backup runs without opting in") + } + + @Test + fun `backup runs only when the user opts in`() { + assertTrue(BackupPolicy.shouldBackUp(AppSettings(includeInBackup = true))) + assertFalse(BackupPolicy.shouldBackUp(AppSettings(includeInBackup = false))) + } + + @Test + fun `only the settings datastore is eligible for backup`() { + assertEquals("datastore/libremail_settings.preferences_pb", BackupPolicy.SAFE_SETTINGS_FILE) + // The safe file must not be, or resemble, a secret store. + assertFalse(BackupPolicy.SAFE_SETTINGS_FILE.contains("dbkey")) + } + + @Test + fun `the keystore-sealed db key is never eligible for backup`() { + assertTrue( + BackupPolicy.EXCLUDED_FILE_PATHS.any { it.contains("libremail_dbkey") }, + "the sealed cache passphrase DataStore must be excluded", + ) + } + + @Test + fun `the credentials and mail-cache database is never eligible for backup`() { + assertTrue(BackupPolicy.EXCLUDED_DATABASE_PATHS.contains("libremail.db")) + // WAL/SHM/journal side-files can hold recently written rows too. + assertTrue(BackupPolicy.EXCLUDED_DATABASE_PATHS.contains("libremail.db-wal")) + assertTrue(BackupPolicy.EXCLUDED_DATABASE_PATHS.contains("libremail.db-shm")) + } +} diff --git a/app/src/test/kotlin/org/libremail/backup/DataExtractionRulesTest.kt b/app/src/test/kotlin/org/libremail/backup/DataExtractionRulesTest.kt new file mode 100644 index 0000000..2de642c --- /dev/null +++ b/app/src/test/kotlin/org/libremail/backup/DataExtractionRulesTest.kt @@ -0,0 +1,76 @@ +// SPDX-License-Identifier: GPL-3.0-or-later +package org.libremail.backup + +import org.junit.Test +import org.w3c.dom.Element +import java.io.File +import javax.xml.parsers.DocumentBuilderFactory +import kotlin.test.assertEquals +import kotlin.test.assertFalse +import kotlin.test.assertTrue + +/** + * Validates the shipped Android Backup rule resources directly, so they can't silently drift from + * [BackupPolicy] or from the acceptance criteria of issue #21: only the settings DataStore may be + * eligible, and the Keystore-sealed cache key plus the credentials/mail database must be excluded. + */ +class DataExtractionRulesTest { + + private data class Rules(val includes: Set, val excludes: Set) + + private fun resource(name: String): File { + // Gradle runs unit tests with the module dir (app/) as the working dir; fall back to the repo + // root in case a runner starts elsewhere. + val candidates = listOf( + File("src/main/res/xml/$name"), + File("app/src/main/res/xml/$name"), + ) + return candidates.firstOrNull { it.exists() } + ?: error("Could not locate $name; looked in ${candidates.map { it.absolutePath }}") + } + + /** Collects the `domain:path` pairs of every / under the given section element. */ + private fun parseSection(file: File, sectionTag: String): Rules { + val doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(file) + val section = doc.getElementsByTagName(sectionTag).item(0) as Element + fun collect(tag: String): Set { + val nodes = section.getElementsByTagName(tag) + return (0 until nodes.length).map { i -> + val e = nodes.item(i) as Element + "${e.getAttribute("domain")}:${e.getAttribute("path")}" + }.toSet() + } + return Rules(includes = collect("include"), excludes = collect("exclude")) + } + + private val safeFile = "file:${BackupPolicy.SAFE_SETTINGS_FILE}" + private val secretPaths: List = + BackupPolicy.EXCLUDED_FILE_PATHS.map { "file:$it" } + + BackupPolicy.EXCLUDED_DATABASE_PATHS.map { "database:$it" } + + private fun assertSafe(rules: Rules) { + // Strict allowlist: the settings DataStore is the ONLY thing eligible for backup/transfer. + // Everything else — crucially the Keystore-sealed cache key and the credentials/mail + // database — is excluded simply by not being listed. + assertEquals(setOf(safeFile), rules.includes, "only the settings DataStore may be backed up") + assertTrue(rules.excludes.isEmpty(), "rules are allowlist-only; no entries expected") + secretPaths.forEach { secret -> + assertFalse(secret in rules.includes, "$secret must never be eligible for backup") + } + } + + @Test + fun `data extraction rules (API 31+) back up only settings for cloud backup`() { + assertSafe(parseSection(resource("data_extraction_rules.xml"), "cloud-backup")) + } + + @Test + fun `data extraction rules (API 31+) back up only settings for device transfer`() { + assertSafe(parseSection(resource("data_extraction_rules.xml"), "device-transfer")) + } + + @Test + fun `full backup content (API 29-30) mirrors the same exclusions`() { + assertSafe(parseSection(resource("backup_rules.xml"), "full-backup-content")) + } +} -- 2.47.3