Add backup bundle creation with AES-GCM encryption

[lourou]

Summary

• add BackupManager actor that orchestrates the full backup flow
• vault archive + per-conversation XMTP archives + GRDB database snapshot + metadata
• encrypt bundle with AES-256-GCM using vault key databaseKey
• write to iCloud Drive (Documents/backups/<device-id>/) with local fallback
• write unencrypted metadata.json alongside the bundle for restore detection without decryption
• per-conversation archive failure is non-fatal (logged per-inboxId)
• BackupArchiveProvider protocol + ConvosBackupArchiveProvider concrete implementation
• createArchive/importArchive added to XMTPClientProvider protocol
• conversation archiving uses Client.build() (local-only, no network) for inactive inboxes
• path traversal / symlink escape protection in archive format
• AES-256-GCM crypto with package access control
• iCloud container entitlements + dynamic ICLOUD_CONTAINER_IDENTIFIER per environment
• 17 tests across 4 suites (crypto, tar, metadata, orchestrator)

Architecture

BackupManager.createBackup()
  ├── VaultManager.createArchive() → vault-archive.encrypted
  ├── per inbox: Client.build() + createArchive() → conversations/<inboxId>.encrypted
  ├── GRDB backup API → database.sqlite
  ├── metadata.json (version, device, timestamp, inbox count)
  ├── tar directory → AES-256-GCM encrypt with vault databaseKey
  └── write to iCloud Drive + metadata.json sidecar

Output:
  iCloud.org.convos.ios/Documents/backups/<device-id>/
    metadata.json              ← unencrypted, for restore detection
    backup-latest.encrypted    ← encrypted bundle

Why

This is PR 3 from docs/plans/icloud-backup-pr-briefings.md: create the encrypted backup bundle that will be restored in PR 4.

Open questions resolved

• Bundle encryption: AES-256-GCM with vault databaseKey
• Inactive clients: Client.build() is local-only, no network needed for archiving
• iCloud container: iCloud.$(MAIN_BUNDLE_ID) per environment (local/dev/prod)

New files

• ConvosCore/Sources/ConvosCore/Backup/BackupManager.swift
• ConvosCore/Sources/ConvosCore/Backup/BackupBundle.swift
• ConvosCore/Sources/ConvosCore/Backup/BackupBundleCrypto.swift
• ConvosCore/Sources/ConvosCore/Backup/BackupBundleMetadata.swift
• ConvosCore/Sources/ConvosCore/Backup/ConvosBackupArchiveProvider.swift
• ConvosCore/Tests/ConvosCoreTests/BackupBundleTests.swift

Modified files

• ConvosCore/Sources/ConvosCore/Messaging/XMTPClientProvider.swift — createArchive/importArchive
• ConvosCore/Sources/ConvosCore/AppEnvironment.swift — iCloudContainerIdentifier
• Convos/Convos.entitlements — iCloud container entitlements
• Convos/Config/*.xcconfig — ICLOUD_CONTAINER_IDENTIFIER

Stack

• Base branch: vault-installation-revocation (PR Revoke other installations on restore and persist installationId #596)
• Head branch: vault-backup-bundle

Note

Add backup bundle creation with AES-GCM encryption and restore flow with stale device detection

• Adds BackupBundle, BackupBundleCrypto, and BackupBundleMetadata to create, encrypt (AES-GCM), and package backup bundles using a custom tar-like archive format.
• Adds BackupManager actor and RestoreManager actor to orchestrate multi-stage backup creation and restore, including vault key broadcast, per-conversation archive creation, database replacement with rollback, and installation revocation.
• Introduces StaleDeviceState (healthy/partialStale/fullStale) derived from InboxesRepository publishers; ConversationsViewModel filters stale-inbox conversations, disables start/join actions, and shows stale-device UI via StaleDeviceBanner.
• Adds isActive to Conversation/ConversationLocalState and isReconnection to DBMessage.Update; inactive conversations show an

^{Macroscope summarized 328118b.}

[lourou]

• Add restore flow: decrypt bundle, import vault, replace DB #618
• Add backup bundle creation with AES-GCM encryption #603 👈 (View in Graphite)
• Revoke other installations on restore and persist installationId #596
• Add vault key sync foundation + one-device debug recovery tools #591
• Add iCloud backup and restore flow #602 : 1 other dependent PR (#698 )
• Convos Vault: Multi-device key sync implementation #564
• dev

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Claude finished @lourou's task —— View job

---

Code Review Complete ✅

Tasks

• Read core backup/restore files
• Review architecture and design
• Check for bugs and security issues
• Evaluate test coverage
• Provide comprehensive feedback

---

Summary

This is a substantial PR adding backup/restore functionality with AES-256-GCM encryption. The architecture is well-designed with clear separation of concerns. The merge conflicts flagged by Macroscope have been resolved. The code quality is generally strong, but there are several important issues to address before merging.

Critical Issues 🔴

1. Rollback Logic Bug (RestoreManager.swift:88-193)

Location: ConvosCore/Sources/ConvosCore/Backup/RestoreManager.swift:88

The destructiveOpsStarted flag is set after preRestoreIdentities is assigned (line 128), but the snapshot is initialized as an empty array (line 87). If an error occurs between lines 119-127 (e.g., incompleteBackup error), the rollback at line 194 calls rollbackKeychain(to: []), which deletes all keychain identities without restoring anything.

Fix: Move destructiveOpsStarted = true to before the keychain snapshot (around line 124) or check the flag inside rollbackKeychain before calling deleteAll().

2. ConvosVaultArchiveImporter - Unused Parameter (ConvosVaultArchiveImporter.swift:8-10)

Location: ConvosCore/Sources/ConvosCore/Backup/ConvosVaultArchiveImporter.swift:8

The vaultKeyStore parameter in the initializer is accepted but never stored or used. This is misleading for callers who might expect identity-loading functionality.

Fix: Either store and use it, or remove the parameter entirely.

High-Priority Issues 🟠

3. Unhandled Reactivation Failures (StreamProcessor.swift:324-327)

Location: ConvosCore/Sources/ConvosCore/Syncing/StreamProcessor.swift:324

for conversationId in toReactivate {
    try await markRecentUpdatesAsReconnection(conversationId: conversationId)
    try await localStateWriter.setActive(true, for: conversationId)
}

If markRecentUpdatesAsReconnection or setActive throws for any conversation, the loop aborts and remaining conversations stay inactive permanently.

Fix: Wrap each iteration in do/catch to continue processing:

for conversationId in toReactivate {
    do {
        try await markRecentUpdatesAsReconnection(conversationId: conversationId)
        try await localStateWriter.setActive(true, for: conversationId)
    } catch {
        Log.warning("Failed to reactivate conversation \(conversationId): \(error)")
    }
}

4. Incomplete Removal from State (ConversationsViewModel.swift:440-449)

Location: Convos/Conversations List/ConversationsViewModel.swift:440

The .leftConversationNotification handler removes the conversation from conversations but not from unfilteredConversations. If recomputeVisibleConversations() runs before the database deletion propagates, the left conversation will reappear.

Fix: Remove from both arrays, matching the pattern in explodeConversation() at lines 700-703.

Medium-Priority Issues 🟡

5. Partial Key Save Failure (RestoreManager.swift:139-148)

Location: ConvosCore/Sources/ConvosCore/Backup/RestoreManager.swift:139

If 9 out of 10 keys fail to save to keychain, restore proceeds because failedKeyCount != keyEntries.count. The database gets replaced with all 10 inboxes, but only 1 keychain entry exists - users silently lose access to 9 conversations.

Recommendation: Consider aborting when any key fails, or track failed inboxes and exclude them from DB replacement. The current check (line 143) only catches total failure.

6. MockDatabaseManager Missing File Check (MockDatabaseManager.swift:23)

Location: ConvosCore/Sources/ConvosCore/Storage/MockDatabaseManager.swift:23

replaceDatabase(with:) opens backupPath without checking file existence. DatabaseQueue(path:) creates a new empty database when the path doesn't exist, so the mock silently "restores" from an empty database instead of throwing.

Fix: Add a file existence check matching DatabaseManager.replaceDatabase.

Positive Highlights ✅

1. Excellent path traversal protection - BackupBundle.swift:164-182 has robust checks against symlink escapes and path traversal attacks
2. Comprehensive test coverage - 17 tests across BackupBundle, crypto, and RestoreManager with good edge case coverage
3. Non-fatal per-conversation failures - Both backup and restore handle individual conversation failures gracefully
4. Clean rollback mechanism - XMTP files are staged and can be restored on restore failure
5. Good separation of concerns - Protocols (BackupArchiveProvider, RestoreArchiveImporter) enable testability
6. Encryption is properly handled - AES-256-GCM with proper key validation (32-byte requirement)

Architecture Review

Strengths:

• Clear orchestration in BackupManager and RestoreManager actors
• Protocol-based abstraction for XMTP operations
• Transactional approach with commit points in restore flow
• Good use of async/await throughout

Suggestions:

• Consider adding metrics/telemetry for backup/restore success rates in production
• The BackupBundle tar format is custom - document the format spec in a comment or ADR
• Consider adding a backup version migration strategy for future format changes

Test Coverage Assessment

Strong coverage:

• ✅ Encryption/decryption round trips
• ✅ Path traversal protection
• ✅ Partial failure scenarios
• ✅ Database replacement
• ✅ Lifecycle controller integration

Missing coverage:

• ⚠️ Rollback scenarios (keychain restore on error)
• ⚠️ Multiple vault key decryption attempts
• ⚠️ Concurrent backup attempts
• ⚠️ Disk space exhaustion during backup

Performance Considerations

1. Backup is synchronous - Large databases or many conversations could block for a long time. Consider adding progress reporting beyond the state enum.
2. No incremental backup - Every backup is full. For frequent backups, consider delta/incremental approach.
3. In-memory tar construction - The entire tar is built in memory (BackupBundle.swift:88-122). For large backups (>100MB), this could cause memory pressure.

Security Assessment

Strengths:

• ✅ AES-256-GCM encryption properly implemented
• ✅ Path traversal attacks prevented
• ✅ Keys never logged or exposed
• ✅ Synchronizable keychain support for iCloud sync

Notes:

• Unencrypted metadata.json is intentional for restore detection, contains no sensitive data
• Vault databaseKey is used as the bundle encryption key - appropriate key reuse
• No key derivation (PBKDF2/Argon2) since the vault key is already cryptographically strong

Recommended Actions Before Merge

1. Fix critical rollback bug (issue [Screen] Onboarding #1)
2. Remove unused parameter or use it properly (issue Contact Card Creation UI #2)
3. Add error handling to reactivation loop (issue Privy Integration #3)
4. Fix left conversation state management (issue Add PostHog for Analytics #4)
5. Consider stricter keychain restore validation (issue Add PostHog for Analytics #5)
6. Run /lint to ensure code style compliance
7. Run full test suite with /test

Overall Assessment

This is solid, production-quality code with a well-designed architecture. The critical and high-priority issues are fixable and don't represent fundamental design flaws. Once addressed, this PR will provide a robust backup/restore foundation for the app.

Recommendation: Request changes for issues #1-4, then approve after fixes.

---

[macroscopeapp]

Approvability

Verdict: Needs human review

3 blocking correctness issues found. Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[macroscopeapp]

🟠 High Backup/RestoreManager.swift:79

If restoreFromBackup fails before preRestoreIdentities is assigned (e.g., bundle decryption fails, metadata read fails, or incompleteBackup error is thrown), the rollback at line 193 calls rollbackKeychain(to: preRestoreIdentities) with an empty array. The rollbackKeychain function first calls identityStore.deleteAll() then iterates over the empty snapshot, deleting all keychain identities with nothing restored. Consider tracking whether destructive keychain operations have begun and only performing rollback if they have.

        var xmtpStashDir: URL?
         var preRestoreIdentities: [KeychainIdentity] = []
         var committed = false
+        var keychainCleared = false

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file ConvosCore/Sources/ConvosCore/Backup/RestoreManager.swift around lines 79-90:

If `restoreFromBackup` fails before `preRestoreIdentities` is assigned (e.g., bundle decryption fails, metadata read fails, or `incompleteBackup` error is thrown), the rollback at line 193 calls `rollbackKeychain(to: preRestoreIdentities)` with an empty array. The `rollbackKeychain` function first calls `identityStore.deleteAll()` then iterates over the empty snapshot, deleting all keychain identities with nothing restored. Consider tracking whether destructive keychain operations have begun and only performing rollback if they have.

Evidence trail:
ConvosCore/Sources/ConvosCore/Backup/RestoreManager.swift lines 89 (`var preRestoreIdentities: [KeychainIdentity] = []`), 93-125 (error-prone operations before assignment), 127-129 (actual assignment of preRestoreIdentities), 186-197 (catch block that calls rollbackKeychain unconditionally when !committed), 262-276 (rollbackKeychain function that calls deleteAll() first, then iterates over potentially empty snapshot)

[macroscopeapp]

🟢 Low Storage/MockDatabaseManager.swift:23

MockDatabaseManager.replaceDatabase(with:) opens backupPath without checking file existence first. DatabaseQueue(path:) creates a new empty database when the path doesn't exist, so the mock silently "restores" from an empty database instead of throwing an error for a missing backup. Consider adding a file existence check matching DatabaseManager.replaceDatabase.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file ConvosCore/Sources/ConvosCore/Storage/MockDatabaseManager.swift around line 23:

`MockDatabaseManager.replaceDatabase(with:)` opens `backupPath` without checking file existence first. `DatabaseQueue(path:)` creates a new empty database when the path doesn't exist, so the mock silently "restores" from an empty database instead of throwing an error for a missing backup. Consider adding a file existence check matching `DatabaseManager.replaceDatabase`.

[macroscopeapp]

🟡 Medium

https://github.com/xmtplabs/convos-ios/blob/3706936289ec925a87e470dabf13745d804d7828/Convos/Conversations List/ConversationsViewModel.swift#L440

When .leftConversationNotification fires, line 449 removes the conversation only from conversations but leaves it in unfilteredConversations. If recomputeVisibleConversations() runs before conversationsPublisher emits (triggered by stale inbox changes), the left conversation will incorrectly reappear in the visible list. The same pattern in explodeConversation() removes from both lists — this notification handler should do the same.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file Convos/Conversations List/ConversationsViewModel.swift around line 440:

When `.leftConversationNotification` fires, line 449 removes the conversation only from `conversations` but leaves it in `unfilteredConversations`. If `recomputeVisibleConversations()` runs before `conversationsPublisher` emits (triggered by stale inbox changes), the left conversation will incorrectly reappear in the visible list. The same pattern in `explodeConversation()` removes from both lists — this notification handler should do the same.

Evidence trail:
Convos/Conversations List/ConversationsViewModel.swift:
- Line 449: `conversations.removeAll { $0.id == conversationId }` (no removal from unfilteredConversations)
- Line 135: `private var unfilteredConversations: [Conversation] = []`
- Lines 388-397: `recomputeVisibleConversations()` reads from `unfilteredConversations`
- Lines 492-493: `staleInboxIdsPublisher` triggers `recomputeVisibleConversations()`
- Lines 700-703: `explodeConversation()` explicitly removes from `unfilteredConversations` showing the correct pattern

[macroscopeapp]

🟡 Medium Syncing/StreamProcessor.swift:324

The loop at lines 324–327 processes reactivations sequentially without individual error handling. If markRecentUpdatesAsReconnection or setActive throws for any conversation, the loop aborts and remaining conversations in toReactivate remain inactive permanently. Wrap the loop body in a do/catch to continue processing subsequent conversations when one fails.

         for conversationId in toReactivate {
-            try await markRecentUpdatesAsReconnection(conversationId: conversationId)
-            try await localStateWriter.setActive(true, for: conversationId)
+            do {
+                try await markRecentUpdatesAsReconnection(conversationId: conversationId)
+                try await localStateWriter.setActive(true, for: conversationId)
+            } catch {
+                Log.warning("Failed to reactivate conversation \(conversationId): \(error)")
+                continue
+            }
         }

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file ConvosCore/Sources/ConvosCore/Syncing/StreamProcessor.swift around lines 324-327:

The loop at lines 324–327 processes reactivations sequentially without individual error handling. If `markRecentUpdatesAsReconnection` or `setActive` throws for any conversation, the loop aborts and remaining conversations in `toReactivate` remain inactive permanently. Wrap the loop body in a `do/catch` to continue processing subsequent conversations when one fails.

Evidence trail:
ConvosCore/Sources/ConvosCore/Syncing/StreamProcessor.swift lines 337-340 (loop) and 342-343 (catch block) at REVIEWED_COMMIT. The `for conversationId in toReactivate` loop uses `try await` without individual `do/catch`, and the outer `catch` block only logs a warning before exiting.