feat(backup): introduce backup support

CLAUDE.md

@@ -74,7 +74,8 @@ Password / Biometric
       ↓ derive / unlock
    RootKek ───────────────────── never persisted
       ↓ unwrap
-   ARK (Account Root Key) ────── in-memory only (Session); wrapped in account_registry.pb
+   ARK (Account Root Key) ────── Session (in-memory); wrapped in account_registry.pb;
+                                 optionally escrowed in backup_ark_data.pb (see Backup Escrow)
       ↓ unwrap (one per vault)
    VaultKey ──────────────────── wrapped in VaultEntity.keyInformation (Room)
       ↓ unwrap (one per item)
@@ -92,6 +93,30 @@ Password / Biometric
 - **AAD** (`itemId + vaultId`) — bound to every ciphertext; prevents transplant attacks.
 - **Rust FFI** (`de.davis.keygo.rust`) implements all wrap/unwrap/derive operations.
 
+## Backup Escrow
+
+A scheduled backup runs with no user present, so it cannot reach the ARK the normal way. Scheduling
+one therefore escrows a second copy of the ARK, and the export passphrase alongside it, under
+Keystore aliases that deliberately do **not** require user authentication (`KeyId.BackupArkKey`,
+`KeyId.BackupPassphraseKey`; see `BackupArkUnlocker`).
+
+This is the one place the "ARK is never readable without authenticating" rule is relaxed, so it
+carries its own rules:
+
+- The escrow exists **only while a job is scheduled**. `CleanupBackupResourcesUseCase` releases it
+  the moment no live job remains, and `reconcile()` sweeps up jobs the scheduler dropped without a
+  run. `BackupWorker.MAX_ATTEMPTS` bounds retries so a deferring job cannot hold it open forever.
+- `reconcile()` runs once per process start (`BackupEscrowReconciler`, an eager Koin singleton), not
+  on entry to the backup screen. A dropped job produces no run to clean up after it, so the trigger
+  must not depend on the user navigating anywhere; process start bounds the escrow's stale lifetime
+  to a single process. Do not move it back behind a UI event.
+- Both aliases set `setUnlockedDeviceRequired(true)` on API 28+. On API 26-27 that constraint does
+  not exist, so on those levels the escrow is readable whenever the process runs.
+- A passphrase-sealed scheduled backup is not stronger than an ARK-sealed one: both keys sit under
+  the same auth-free policy.
+- Do not widen the escrow's lifetime, its auth policy, or the set of callers that can read it
+  without explicit instruction.
+
 ## Sensitive Areas
 
 - **Migration** — preserve backward compat, smallest safe change

README.md

@@ -1,4 +1,4 @@
-## KeyGo v2 — Your Secure Digital Vault
+## KeyGo v2 - Your Secure Digital Vault
 
 > [!CAUTION]
 > This branch (v2) is under active development. For the stable v1 release, switch to
@@ -8,5 +8,5 @@ For further information, please see the [v1 branch](https://github.com/OffRange/
 
 ### License
 
-Licensed under the GNU General Public License v3.0. This means KeyGo is free software — you can
+Licensed under the GNU General Public License v3.0. This means KeyGo is free software: you can
 redistribute and/or modify it under GPLv3 terms. For full details, see the [LICENSE](LICENSE) file.

app/build.gradle.kts

@@ -98,6 +98,7 @@ dependencies {
     implementation(project.dependencies.platform(libs.koin.bom))
     implementation(libs.koin.androidx.compose)
     implementation(libs.koin.annotations)
+    implementation(libs.koin.androidx.workmanager)
 
     implementation(libs.aboutlibraries.compose.m3)
 
@@ -116,6 +117,7 @@ dependencies {
     implementation(projects.feature.creditCard)
     implementation(projects.feature.autofill)
     implementation(projects.feature.settings)
+    implementation(projects.feature.backup)
     implementation(projects.migrationCreateAccess)
 
     implementation(libs.androidx.core.ktx)

app/src/main/kotlin/de/davis/keygo/app/KeyGoApplication.kt

@@ -3,6 +3,7 @@ package de.davis.keygo.app
 import android.app.Application
 import org.koin.android.ext.koin.androidContext
 import org.koin.android.ext.koin.androidLogger
+import org.koin.androidx.workmanager.koin.workManagerFactory
 import org.koin.core.annotation.KoinApplication
 import org.koin.plugin.module.dsl.startKoin
 
@@ -14,6 +15,7 @@ class KeyGoApplication : Application() {
         startKoin<KeyGoApplication> {
             androidLogger()
             androidContext(this@KeyGoApplication)
+            workManagerFactory()
         }
     }
 }

app/src/main/kotlin/de/davis/keygo/app/presentation/MainActivity.kt

@@ -40,6 +40,8 @@ import de.davis.keygo.dashboard.presentation.DetailType
 import de.davis.keygo.dashboard.presentation.dashboardGraph
 import de.davis.keygo.feature.auth.presentation.AuthRoute
 import de.davis.keygo.feature.auth.presentation.authGraph
+import de.davis.keygo.feature.backup.presentation.BackupHubRoute
+import de.davis.keygo.feature.backup.presentation.backupGraph
 import de.davis.keygo.feature.settings.presentation.ChangePasswordRoute
 import de.davis.keygo.feature.settings.presentation.settingsGraph
 import de.davis.keygo.item.dialog.SelectItemContent
@@ -165,6 +167,7 @@ private fun App() {
                 settingsGraph(
                     onOpenChangePassword = { navController.navigate(ChangePasswordRoute) },
                     onShowLibraries = { navController.navigate(RouteDestination.Libraries) },
+                    onOpenBackup = { navController.navigate(BackupHubRoute) },
                     onUp = { navController.navigateUp() },
                 )
 
@@ -185,6 +188,11 @@ private fun App() {
                     )
                 }
             }
+
+            backupGraph(
+                navigateToDestination = navController::navigate,
+                navigateUp = { navController.navigateUp() },
+            )
         }
     }
 }

core/identity/src/main/kotlin/de/davis/keygo/core/identity/di/CoreIdentityModule.kt

@@ -5,6 +5,7 @@ import androidx.datastore.dataStore
 import de.davis.keygo.core.identity.data.local.model.ProtoAccountState
 import de.davis.keygo.core.identity.di.annotation.AccountRegistryQualifier
 import de.davis.keygo.core.security.di.CoreSecurityModule
+import de.davis.keygo.core.util.data.serializer.DefaultProtoSerializer
 import org.koin.core.annotation.ComponentScan
 import org.koin.core.annotation.Configuration
 import org.koin.core.annotation.Module

core/identity/src/main/kotlin/de/davis/keygo/core/identity/domain/usecase/CreateAccessUseCase.kt

@@ -76,7 +76,7 @@ class CreateAccessUseCase(
 
         // Persist the account before the vault: the vault is encrypted under the account's
         // ARK, so a vault row without a recoverable account is dead weight. If the vault
-        // write fails after this, the half-state is recoverable on retry — `set` overwrites.
+        // write fails after this, the half-state is recoverable on retry, since `set` overwrites.
         accountRepository.set(
             Account(
                 id = accountHolder.account.id,

core/item/src/main/kotlin/de/davis/keygo/core/item/data/local/dao/CreditCardDao.kt

@@ -7,6 +7,7 @@ import androidx.room.Upsert
 import de.davis.keygo.core.item.data.local.entity.CreditCardEntity
 import de.davis.keygo.core.item.data.local.pojo.CreditCardProjection
 import de.davis.keygo.core.item.domain.alias.ItemId
+import de.davis.keygo.core.item.domain.alias.VaultId
 import kotlinx.coroutines.flow.Flow
 
 @Dao
@@ -22,4 +23,8 @@ internal interface CreditCardDao {
     @Transaction
     @Query("SELECT * FROM credit_card WHERE id = :id")
     suspend fun getById(id: ItemId): CreditCardProjection?
-}
+
+    @Transaction
+    @Query("SELECT * FROM credit_card WHERE id IN (SELECT id FROM item WHERE vault_id = :vaultId)")
+    suspend fun getByVault(vaultId: VaultId): List<CreditCardProjection>
+}

core/item/src/main/kotlin/de/davis/keygo/core/item/data/local/dao/PasskeyDao.kt

@@ -5,6 +5,7 @@ import androidx.room.Insert
 import androidx.room.Query
 import de.davis.keygo.core.item.data.local.entity.credential.PasskeyEntity
 import de.davis.keygo.core.item.data.local.pojo.PasskeyMetadataPojo
+import de.davis.keygo.core.item.domain.alias.ItemId
 
 @Dao
 internal interface PasskeyDao {
@@ -15,6 +16,9 @@ internal interface PasskeyDao {
     @Query("SELECT * FROM passkey WHERE credential_id = :credentialId")
     suspend fun getPasskey(credentialId: ByteArray): PasskeyEntity?
 
+    @Query("SELECT * FROM passkey WHERE login_id = :loginId")
+    suspend fun getPasskeysForLogin(loginId: ItemId): List<PasskeyEntity>
+
     @Query("SELECT EXISTS (SELECT 1 FROM passkey WHERE credential_id IN (:credentialIds))")
     suspend fun doesCredentialIdsExist(credentialIds: Set<ByteArray>): Boolean
 

core/item/src/main/kotlin/de/davis/keygo/core/item/data/local/entity/credential/PasswordEntity.kt

@@ -10,7 +10,7 @@ import de.davis.keygo.core.item.domain.alias.ItemId
 import de.davis.keygo.core.item.domain.model.EncryptedPayload
 import de.davis.keygo.core.item.domain.model.PasswordScore
 
-// The primary key is shared with ItemEntity — one ItemId identifies both the base item row and
+// The primary key is shared with ItemEntity: one ItemId identifies both the base item row and
 // this password row. This models the "is-a" relationship at the DB level (joined-table
 // inheritance): there is no separate password-specific ID.
 @Entity(

core/item/src/main/kotlin/de/davis/keygo/core/item/data/repository/CreditCardRepositoryImpl.kt

@@ -4,10 +4,12 @@ import androidx.room.withTransaction
 import de.davis.keygo.core.item.data.local.dao.CreditCardDao
 import de.davis.keygo.core.item.data.local.dao.ItemDao
 import de.davis.keygo.core.item.data.local.datasource.ItemDatabase
+import de.davis.keygo.core.item.data.local.pojo.CreditCardProjection
 import de.davis.keygo.core.item.data.mapper.toCreditCardEntity
 import de.davis.keygo.core.item.data.mapper.toData
 import de.davis.keygo.core.item.data.mapper.toDomain
 import de.davis.keygo.core.item.domain.alias.ItemId
+import de.davis.keygo.core.item.domain.alias.VaultId
 import de.davis.keygo.core.item.domain.model.CreditCard
 import de.davis.keygo.core.item.domain.repository.CreditCardRepository
 import de.davis.keygo.core.util.Result
@@ -40,4 +42,7 @@ internal class CreditCardRepositoryImpl(
 
     override suspend fun getCreditCardById(itemId: ItemId): CreditCard? =
         creditCardDao.getById(itemId)?.toDomain()
-}
+
+    override suspend fun getCreditCardsByVault(vaultId: VaultId): List<CreditCard> =
+        creditCardDao.getByVault(vaultId).map(CreditCardProjection::toDomain)
+}

core/item/src/main/kotlin/de/davis/keygo/core/item/data/repository/PasskeyRepositoryImpl.kt

@@ -1,9 +1,11 @@
 package de.davis.keygo.core.item.data.repository
 
 import de.davis.keygo.core.item.data.local.dao.PasskeyDao
+import de.davis.keygo.core.item.data.local.entity.credential.PasskeyEntity
 import de.davis.keygo.core.item.data.local.pojo.PasskeyMetadataPojo
 import de.davis.keygo.core.item.data.mapper.toData
 import de.davis.keygo.core.item.data.mapper.toDomain
+import de.davis.keygo.core.item.domain.alias.ItemId
 import de.davis.keygo.core.item.domain.model.Passkey
 import de.davis.keygo.core.item.domain.model.PasskeyMetadata
 import de.davis.keygo.core.item.domain.repository.PasskeyRepository
@@ -26,4 +28,7 @@ internal class PasskeyRepositoryImpl(
 
     override suspend fun getPasskey(credentialId: ByteArray): Passkey? =
         passkeyDao.getPasskey(credentialId)?.toDomain()
+
+    override suspend fun getPasskeysByLogin(loginId: ItemId): List<Passkey> =
+        passkeyDao.getPasskeysForLogin(loginId).map(PasskeyEntity::toDomain)
 }

core/item/src/main/kotlin/de/davis/keygo/core/item/data/repository/RoomTransactionRunner.kt

@@ -0,0 +1,14 @@
+package de.davis.keygo.core.item.data.repository
+
+import androidx.room.withTransaction
+import de.davis.keygo.core.item.data.local.datasource.ItemDatabase
+import de.davis.keygo.core.item.domain.TransactionRunner
+import org.koin.core.annotation.Single
+
+@Single
+internal class RoomTransactionRunner(
+    private val database: ItemDatabase,
+) : TransactionRunner {
+    override suspend fun <R> runInTransaction(block: suspend () -> R): R =
+        database.withTransaction { block() }
+}

core/item/src/main/kotlin/de/davis/keygo/core/item/domain/TransactionRunner.kt

@@ -0,0 +1,13 @@
+package de.davis.keygo.core.item.domain
+
+/**
+ * Runs a block of persistence work as a single atomic unit: either every write inside [block]
+ * commits, or none of them do. If the calling coroutine is cancelled or [block] throws, the
+ * transaction rolls back.
+ *
+ * Nested calls join the outermost transaction rather than opening a new one, so callers can safely
+ * compose operations that already run their own transactions internally.
+ */
+interface TransactionRunner {
+    suspend fun <R> runInTransaction(block: suspend () -> R): R
+}

core/item/src/main/kotlin/de/davis/keygo/core/item/domain/repository/CreditCardRepository.kt

@@ -1,6 +1,7 @@
 package de.davis.keygo.core.item.domain.repository
 
 import de.davis.keygo.core.item.domain.alias.ItemId
+import de.davis.keygo.core.item.domain.alias.VaultId
 import de.davis.keygo.core.item.domain.model.CreditCard
 import de.davis.keygo.core.util.Result
 import kotlinx.coroutines.flow.Flow
@@ -10,4 +11,5 @@ interface CreditCardRepository {
 
     fun observeCreditCardById(itemId: ItemId): Flow<CreditCard?>
     suspend fun getCreditCardById(itemId: ItemId): CreditCard?
+    suspend fun getCreditCardsByVault(vaultId: VaultId): List<CreditCard>
 }

core/item/src/main/kotlin/de/davis/keygo/core/item/domain/repository/PasskeyRepository.kt

@@ -1,5 +1,6 @@
 package de.davis.keygo.core.item.domain.repository
 
+import de.davis.keygo.core.item.domain.alias.ItemId
 import de.davis.keygo.core.item.domain.model.Passkey
 import de.davis.keygo.core.item.domain.model.PasskeyMetadata
 
@@ -11,4 +12,6 @@ interface PasskeyRepository {
     suspend fun getPasskeysForRP(rpId: String): List<PasskeyMetadata>
 
     suspend fun getPasskey(credentialId: ByteArray): Passkey?
+
+    suspend fun getPasskeysByLogin(loginId: ItemId): List<Passkey>
 }

core/item/src/main/kotlin/de/davis/keygo/core/item/presentation/VaultIconPicker.kt

@@ -0,0 +1,64 @@
+package de.davis.keygo.core.item.presentation
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.FlowRow
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.size
+import androidx.compose.material3.ExperimentalMaterial3ExpressiveApi
+import androidx.compose.material3.FilledTonalIconToggleButton
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButtonDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.minimumInteractiveComponentSize
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.tooling.preview.Preview
+import androidx.compose.ui.unit.dp
+import de.davis.keygo.core.item.domain.model.Vault
+
+/**
+ * Every [Vault.Icon] as a toggle grid, one of which is [selected].
+ *
+ * Lives here rather than in a feature module because more than one flow creates vaults, and the
+ * picker has to look and behave the same in all of them. Callers supply their own heading.
+ */
+@OptIn(ExperimentalMaterial3ExpressiveApi::class)
+@Composable
+fun VaultIconPicker(
+    selected: Vault.Icon,
+    onSelect: (Vault.Icon) -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    FlowRow(
+        modifier = modifier.fillMaxWidth(),
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+    ) {
+        Vault.Icon.entries.forEach { icon ->
+            FilledTonalIconToggleButton(
+                checked = selected == icon,
+                onCheckedChange = { onSelect(icon) },
+                modifier = Modifier
+                    .minimumInteractiveComponentSize()
+                    .size(IconButtonDefaults.mediumContainerSize()),
+                shapes = IconButtonDefaults.toggleableShapes(),
+            ) {
+                Icon(
+                    imageVector = icon.toImageVector(),
+                    contentDescription = null,
+                )
+            }
+        }
+    }
+}
+
+@Preview
+@Composable
+private fun VaultIconPickerPreview() {
+    MaterialTheme {
+        Surface {
+            VaultIconPicker(selected = Vault.Icon.Work, onSelect = {})
+        }
+    }
+}

core/item/src/test/kotlin/de/davis/keygo/core/item/data/mapper/ItemMapperTest.kt

@@ -42,7 +42,7 @@ class ItemMapperTest {
         keyInformation = KeyInformation(byteArrayOf(), byteArrayOf()),
     )
 
-    // Item.toData() → ItemEntity
+    // Item.toData() -> ItemEntity
 
     @Test
     fun `Login toData maps id and vaultId`() {
@@ -80,7 +80,7 @@ class ItemMapperTest {
         assertFalse((testLogin(pinned = false) as Item).toData().pinned)
     }
 
-    // LightweightItem.toDomain() → LiteItem.Concrete
+    // LightweightItem.toDomain() -> LiteItem.Concrete
 
     @Test
     fun `LightweightItem toDomain copies all fields`() {
@@ -100,7 +100,7 @@ class ItemMapperTest {
         assertTrue(lite.pinned)
     }
 
-    // LightweightItemSearchResult.toDomain() → LiteItemSearchResult
+    // LightweightItemSearchResult.toDomain() -> LiteItemSearchResult
 
     @Test
     fun `LightweightItemSearchResult toDomain copies all fields`() {
@@ -126,7 +126,7 @@ class ItemMapperTest {
         assertFalse(result.pinned)
     }
 
-    // MovableItemPojo.toDomain() → MovableItem
+    // MovableItemPojo.toDomain() -> MovableItem
 
     @Test
     fun `MovableItemPojo toDomain maps id`() {

core/item/src/testFixtures/kotlin/de/davis/keygo/core/item/FakeCreditCardRepository.kt

@@ -1,6 +1,7 @@
 package de.davis.keygo.core.item
 
 import de.davis.keygo.core.item.domain.alias.ItemId
+import de.davis.keygo.core.item.domain.alias.VaultId
 import de.davis.keygo.core.item.domain.model.CreditCard
 import de.davis.keygo.core.item.domain.repository.CreditCardRepository
 import de.davis.keygo.core.util.Result
@@ -50,4 +51,7 @@ class FakeCreditCardRepository : CreditCardRepository {
         store.map { it[itemId] }
 
     override suspend fun getCreditCardById(itemId: ItemId): CreditCard? = store.value[itemId]
+
+    override suspend fun getCreditCardsByVault(vaultId: VaultId): List<CreditCard> =
+        store.value.values.filter { it.vaultId == vaultId }
 }