feat(phase-1/m2.1): :core:backup — codecs + stream-based BackupBridge

Phase 1 M2 task 1 (tools/DESKTOP_PHASE_PLAN.md §4): extract the backup
bridge from :composeApp into a plain kotlin("jvm") module so the desktop
build can import/export the phone file format.

- git mv BackupCodec / EncryptedBackupCodec / EncryptedKeyCodec into
  core/backup, keeping the org.incido.compose.data.backup package so the
  Android diff is file moves + one dependency line (no import churn).
- New BackupBridge: the four BackupManager operations over
  InputStream/OutputStream instead of Uri (incl. the v0.3.3.3 preview
  hotfix catches); BackupPreview moves with it, same package.
- BackupManager stays in :composeApp as a thin Uri -> stream SAF shim,
  public API unchanged. Dedupe = task 3, desktop picker UI = task 2.

Verification passed: ./gradlew :core:backup:build :core:data-jvm:smoke
:spike:data-jvm:run + assembleDebug + :desktopApp:run --args="--data-dir
/tmp/incido-desktop-smoke --self-test --exit-after 6" — all green; run
output recorded in tools/DESKTOP_FEASIBILITY.md (Phase 1 status).
This commit is contained in:
Incido Developer committed 2026-10-05 18:51:07 +13:00
1 parent b11c02e1b4
commit 7cc4eda90d
9 files changed
+262 -92

No files matched your search

@@ -1,209 +0,0 @@
package org.incido.compose.data.backup
import kotlinx.coroutines.flow.first
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import org.incido.domain.model.Note
import org.incido.domain.model.NoteAttachment
import org.incido.domain.model.NoteColor
import org.incido.domain.model.NoteType
import org.incido.domain.repository.NoteRepository
/**
* v0.3.2.0: plain-JSON backup codec.
*
* File format: a single `.incido.json` containing notes (with their
* hashtags and Base64-encoded attachment bytes) + any orphaned hashtag
* rows. Format-versioned so future releases can branch.
*
* This codec does **no** encryption — that's [EncryptedBackupCodec]'s
* job. The two codecs share the same on-disk shape; the encrypted
* variant just wraps the JSON in a `magic + salt + iv + ciphertext`
* envelope.
*/
object BackupCodec {
private val json = Json {
prettyPrint = true
ignoreUnknownKeys = true
encodeDefaults = true
}
/**
* Build a serialisable snapshot of every note (and its attachments)
* in [repository], plus all hashtag rows.
*/
suspend fun exportSnapshot(
repository: NoteRepository,
appVersion: String,
): BackupFile {
// The repository exposes Flows; we materialise a one-shot
// snapshot via `.first()`. Notes come from `observeAllIncludingTrashed`,
// tags from `observeAllHashtags`.
// Backup includes active and trashed notes so a soft-deleted note
// can be restored after a device migration as well.
val noteList: List<Note> = repository.observeAllIncludingTrashed().first()
val tagList: List<String> = repository.observeAllHashtags().first()
// NoteAttachment.bytes is loaded on demand via
// `getAttachmentBytes(id)` — we resolve each attachment's
// bytes here so the JSON payload is self-contained.
val out = BackupFile(
formatVersion = FORMAT_VERSION,
exportedAt = System.currentTimeMillis(),
appVersion = appVersion,
notes = noteList.map { note -> note.toBackup(repository) },
orphanedHashtags = tagList,
)
return out
}
/** Serialise [file] to pretty-printed JSON. */
fun encode(file: BackupFile): String = json.encodeToString(BackupFile.serializer(), file)
/** Parse a JSON string produced by [encode]. */
fun decode(payload: String): BackupFile =
json.decodeFromString(BackupFile.serializer(), payload)
/**
* Import every note (with attachments + hashtags) in [file] into
* [repository]. Additive — existing notes are preserved; new
* notes are added with fresh ids. The repository's existing
* `saveNoteWithHashtags` handles hashtag reconciliation.
*/
suspend fun importSnapshot(
file: BackupFile,
repository: NoteRepository,
onProgress: (current: Int, total: Int) -> Unit = { _, _ -> },
) {
val total = file.notes.size
file.notes.forEachIndexed { idx, bn ->
val note = bn.toDomain()
// Persist the note and its tags in one transaction so
// the drawer's hashtag-usage observers fire once.
val saved = repository.saveNoteWithHashtags(
note = note.copy(id = 0L), // force a new id
hashtagsToAdd = bn.hashtags.toSet(),
hashtagsToRemove = emptySet(),
)
// Insert attachments with the newly assigned note id.
bn.attachments.forEach { ba ->
repository.addAttachment(
noteId = saved.id,
bytes = decodeBase64(ba.bytesBase64),
mimeType = ba.mimeType,
displayName = ba.displayName,
)
}
onProgress(idx + 1, total)
}
}
const val FORMAT_VERSION = 1
const val MIME_TYPE = "application/json"
const val FILE_EXTENSION = "incido.json"
}
/** Top-level serialisable backup payload. */
@Serializable
data class BackupFile(
val formatVersion: Int,
val exportedAt: Long,
val appVersion: String,
val notes: List<BackupNote>,
val orphanedHashtags: List<String> = emptyList(),
)
@Serializable
data class BackupNote(
val content: String,
val createdAt: Long,
val updatedAt: Long,
val isFavorite: Boolean,
/** Serialised as the [NoteColor] enum name (e.g. "RED"). */
val color: String,
val hashtags: List<String> = emptyList(),
val attachments: List<BackupAttachment> = emptyList(),
/** Preserve soft-delete state; defaults to false for older backups. */
val isTrashed: Boolean = false,
/** Preserve draft state; defaults to false for older backups. */
val isDraft: Boolean = false,
/**
* v0.3.8.0 — serialised as the [org.incido.domain.model.NoteType]
* enum name ("TEXT" / "TASK_LIST" / "SHOPPING_LIST" / "VOICE_NOTE").
* Defaulted so pre-v0.3.8.0 backup files import as plain-text notes.
*/
val noteType: String = "TEXT",
)
@Serializable
data class BackupAttachment(
val mimeType: String,
val displayName: String,
val createdAt: Long,
val sizeBytes: Long,
/** Raw attachment bytes, Base64-encoded so the JSON stays a text format. */
val bytesBase64: String,
)
/** Suspending overload that resolves attachment bytes via the repository. */
private suspend fun Note.toBackup(repository: NoteRepository): BackupNote {
val backups = attachments.map { attachment ->
val bytes = repository.getAttachmentBytes(attachment.id) ?: ByteArray(0)
BackupAttachment(
mimeType = attachment.mimeType,
displayName = attachment.displayName,
createdAt = attachment.createdAt,
sizeBytes = attachment.sizeBytes,
bytesBase64 = java.util.Base64.getEncoder().encodeToString(bytes),
)
}
return BackupNote(
content = content,
createdAt = createdAt,
updatedAt = updatedAt,
isFavorite = isFavorite,
color = color.name,
isTrashed = isTrashed,
isDraft = isDraft,
noteType = type.name,
hashtags = hashtags,
attachments = backups,
)
}
/** Pure (non-suspending) conversion for tests / unit conversion.
* Returns attachments without their bytes — use the suspending
* overload above for actual exports. */
@Suppress("unused")
private fun Note.toBackup(): BackupNote = BackupNote(
content = content,
createdAt = createdAt,
updatedAt = updatedAt,
isFavorite = isFavorite,
color = color.name,
isTrashed = isTrashed,
isDraft = isDraft,
noteType = type.name,
hashtags = hashtags,
attachments = emptyList(),
)
private fun BackupNote.toDomain(): Note = Note(
id = 0L,
content = content,
createdAt = createdAt,
updatedAt = updatedAt,
isFavorite = isFavorite,
color = runCatching { NoteColor.valueOf(color) }.getOrDefault(NoteColor.NONE),
isTrashed = isTrashed,
isDraft = isDraft,
type = runCatching { NoteType.valueOf(noteType) }.getOrDefault(NoteType.TEXT),
hashtags = hashtags,
// Attachments are inserted separately by importSnapshot so they
// get assigned to the freshly-created note id.
attachments = emptyList(),
)
private fun decodeBase64(b64: String): ByteArray =
java.util.Base64.getDecoder().decode(b64)
@@ -2,6 +2,7 @@ package org.incido.compose.data.backup
import android.content.Context
import android.net.Uri
import java.io.IOException
import java.io.InputStream
import java.io.OutputStream
import kotlinx.coroutines.Dispatchers
@@ -11,15 +12,16 @@ import org.incido.domain.repository.NoteRepository
/**
* v0.3.2.0: orchestration layer for Backup / Import / Export.
*
* Reads / writes go through the Storage Access Framework — the
* Activity hands in [Uri]s from
* `ActivityResultContracts.CreateDocument` / `OpenDocument` and the
* manager streams bytes in / out via ContentResolver. No fixed-path
* writes, no extra permissions.
* Phase 1 (M2 task 1): this class is now a **thin Storage Access
* Framework shim**. It converts the [Uri]s that
* `ActivityResultContracts.CreateDocument` / `OpenDocument` hand back
* into streams and delegates everything else — format, crypto,
* snapshotting — to [BackupManager]'s former body, now the platform-
* neutral [BackupBridge] in `:core:backup`. The desktop app (M2 task 2)
* calls [BackupBridge] directly with file streams.
*
* Encrypt-on-export and decrypt-on-import are selected by the caller;
* the codecs themselves ([BackupCodec], [EncryptedBackupCodec]) hold
* the format / cipher details.
* Public API is unchanged: [SettingsViewModel] and the backup screens
* compile exactly as before.
*/
class BackupManager(
private val context: Context,
@@ -37,14 +39,7 @@ class BackupManager(
appVersion: String,
onProgress: (current: Int, total: Int) -> Unit = { _, _ -> },
): Int = withContext(Dispatchers.IO) {
val file = BackupCodec.exportSnapshot(repository, appVersion)
val json = BackupCodec.encode(file)
context.contentResolver.openOutputStream(uri, "wt")?.use { out: OutputStream ->
out.write(json.toByteArray(Charsets.UTF_8))
out.flush()
} ?: throw java.io.IOException("Could not open output stream for $uri")
onProgress(file.notes.size, file.notes.size)
file.notes.size
BackupBridge.exportPlain(repository, openOutput(uri), appVersion, onProgress)
}
/**
@@ -58,15 +53,7 @@ class BackupManager(
appVersion: String,
onProgress: (current: Int, total: Int) -> Unit = { _, _ -> },
): Int = withContext(Dispatchers.IO) {
val file = BackupCodec.exportSnapshot(repository, appVersion)
val json = BackupCodec.encode(file)
val payload = EncryptedBackupCodec.encrypt(json, passphrase)
context.contentResolver.openOutputStream(uri, "wt")?.use { out ->
out.write(payload)
out.flush()
} ?: throw java.io.IOException("Could not open output stream for $uri")
onProgress(file.notes.size, file.notes.size)
file.notes.size
BackupBridge.exportEncrypted(repository, openOutput(uri), passphrase, appVersion, onProgress)
}
/**
@@ -82,20 +69,7 @@ class BackupManager(
passphrase: CharArray? = null,
onProgress: (current: Int, total: Int) -> Unit = { _, _ -> },
): Int = withContext(Dispatchers.IO) {
val bytes = context.contentResolver.openInputStream(uri)?.use { it.readBytes() }
?: throw java.io.IOException("Could not open input stream for $uri")
val json: String = if (EncryptedBackupCodec.isEncrypted(bytes)) {
val pass = passphrase
?: throw IllegalArgumentException("Encrypted backup requires a passphrase")
EncryptedBackupCodec.decrypt(bytes, pass)
} else {
String(bytes, Charsets.UTF_8)
}
val file = BackupCodec.decode(json)
BackupCodec.importSnapshot(file, repository) { cur, tot -> onProgress(cur, tot) }
file.notes.size
BackupBridge.import(repository, openInput(uri), passphrase, onProgress)
}
/**
@@ -108,60 +82,19 @@ class BackupManager(
*/
suspend fun preview(uri: Uri, passphrase: CharArray? = null): BackupPreview? =
withContext(Dispatchers.IO) {
val bytes: ByteArray = try {
context.contentResolver.openInputStream(uri)?.use(InputStream::readBytes)
?: return@withContext null
} catch (_: java.io.IOException) {
val input: InputStream = try {
context.contentResolver.openInputStream(uri) ?: return@withContext null
} catch (_: IOException) {
return@withContext null
}
val json: String = if (EncryptedBackupCodec.isEncrypted(bytes)) {
val pass = passphrase ?: return@withContext null
try {
EncryptedBackupCodec.decrypt(bytes, pass)
} catch (_: javax.crypto.AEADBadTagException) {
return@withContext null
} catch (_: javax.crypto.BadPaddingException) {
return@withContext null
} catch (_: IllegalArgumentException) {
// v0.3.3.3 hotfix: a truncated / corrupt envelope
// fails the require(...) size checks inside
// decrypt() with an IllegalArgumentException.
// Previously that escaped preview() and crashed the
// coroutine; treat it the same as a bad passphrase.
return@withContext null
} catch (_: java.security.GeneralSecurityException) {
// Catch-all for any other cipher-layer failure.
return@withContext null
}
} else {
try {
String(bytes, Charsets.UTF_8)
} catch (_: java.io.IOException) {
return@withContext null
}
}
val file: BackupFile = try {
BackupCodec.decode(json)
} catch (_: kotlinx.serialization.SerializationException) {
return@withContext null
} catch (_: Exception) {
// v0.3.3.3 hotfix: any other decode failure (e.g. the
// payload wasn't JSON after all) must not escape.
return@withContext null
}
BackupPreview(
noteCount = file.notes.size,
attachmentCount = file.notes.sumOf { it.attachments.size },
appVersion = file.appVersion,
exportedAt = file.exportedAt,
)
BackupBridge.preview(input, passphrase)
}
}
/** Lightweight DTO shown in the import confirmation dialog. */
data class BackupPreview(
val noteCount: Int,
val attachmentCount: Int,
val appVersion: String,
val exportedAt: Long,
)
private fun openOutput(uri: Uri): OutputStream =
context.contentResolver.openOutputStream(uri, "wt")
?: throw IOException("Could not open output stream for $uri")
private fun openInput(uri: Uri): InputStream =
context.contentResolver.openInputStream(uri)
?: throw IOException("Could not open input stream for $uri")
}
@@ -1,123 +0,0 @@
package org.incido.compose.data.backup
import java.security.SecureRandom
import javax.crypto.Cipher
import javax.crypto.SecretKeyFactory
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.PBEKeySpec
import javax.crypto.spec.SecretKeySpec
/**
* v0.3.2.0: passphrase-encrypted backup envelope.
*
* On-disk layout:
*
* ```
* magic "INCDBK1\0" (8 bytes)
* salt (16 bytes)
* iv (12 bytes)
* ciphertext + tag (variable)
* ```
*
* The plaintext payload is the JSON produced by [BackupCodec.encode].
* The key is derived from the user's passphrase via PBKDF2-HMAC-SHA256
* (200,000 iterations, 256-bit output). The body is encrypted with
* AES-256-GCM; the GCM tag is appended automatically by the JCE.
*
* The magic header is what lets the import side auto-detect the format
* without asking the user — plain JSON files start with `{` /
* whitespace, encrypted files start with `INCDBK1\0`.
*/
object EncryptedBackupCodec {
/** "Incido Backup v1" — null terminator included so it never
* collides with `{` (the first byte of any JSON object). */
val MAGIC: ByteArray = byteArrayOf(
0x49, 0x4E, 0x43, 0x44, 0x42, 0x4B, 0x31, 0x00,
)
private const val SALT_BYTES = 16
private const val IV_BYTES = 12
private const val GCM_TAG_BITS = 128
private const val PBKDF2_ITERATIONS = 200_000
private const val DERIVED_KEY_BITS = 256
private const val TRANSFORMATION = "AES/GCM/NoPadding"
private val secureRandom = SecureRandom()
/**
* True if [bytes] starts with [MAGIC] — used by the import side
* to distinguish encrypted payloads from plain JSON.
*/
fun isEncrypted(bytes: ByteArray): Boolean {
if (bytes.size < MAGIC.size) return false
return bytes.copyOfRange(0, MAGIC.size).contentEquals(MAGIC)
}
/**
* Encrypt [plaintextJson] with [passphrase] and return the full
* envelope (magic + salt + iv + ciphertext + tag).
*/
fun encrypt(plaintextJson: String, passphrase: CharArray): ByteArray {
val salt = ByteArray(SALT_BYTES).also(secureRandom::nextBytes)
val iv = ByteArray(IV_BYTES).also(secureRandom::nextBytes)
val keyBytes = deriveKey(passphrase, salt)
try {
val cipher = Cipher.getInstance(TRANSFORMATION)
cipher.init(
Cipher.ENCRYPT_MODE,
SecretKeySpec(keyBytes, "AES"),
GCMParameterSpec(GCM_TAG_BITS, iv),
)
val cipherText = cipher.doFinal(plaintextJson.toByteArray(Charsets.UTF_8))
return MAGIC + salt + iv + cipherText
} finally {
keyBytes.fill(0)
passphrase.fill('0')
}
}
/**
* Reverse of [encrypt]. Throws on bad passphrase or corrupted
* payload (GCM tag mismatch).
*/
fun decrypt(payload: ByteArray, passphrase: CharArray): String {
require(isEncrypted(payload)) { "Payload is not an Incido encrypted backup" }
require(payload.size >= MAGIC.size + SALT_BYTES + IV_BYTES + GCM_TAG_BITS / 8) {
"Encrypted backup is truncated"
}
val salt = payload.copyOfRange(MAGIC.size, MAGIC.size + SALT_BYTES)
val iv = payload.copyOfRange(
MAGIC.size + SALT_BYTES,
MAGIC.size + SALT_BYTES + IV_BYTES,
)
val cipherText = payload.copyOfRange(
MAGIC.size + SALT_BYTES + IV_BYTES,
payload.size,
)
val keyBytes = deriveKey(passphrase, salt)
try {
val cipher = Cipher.getInstance(TRANSFORMATION)
cipher.init(
Cipher.DECRYPT_MODE,
SecretKeySpec(keyBytes, "AES"),
GCMParameterSpec(GCM_TAG_BITS, iv),
)
val plain = cipher.doFinal(cipherText)
return plain.toString(Charsets.UTF_8)
} finally {
keyBytes.fill(0)
passphrase.fill('0')
}
}
private fun deriveKey(passphrase: CharArray, salt: ByteArray): ByteArray {
val spec = PBEKeySpec(passphrase, salt, PBKDF2_ITERATIONS, DERIVED_KEY_BITS)
try {
val factory = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256")
return factory.generateSecret(spec).encoded
} finally {
spec.clearPassword()
}
}
}
@@ -1,148 +0,0 @@
package org.incido.compose.data.backup
import java.security.SecureRandom
import javax.crypto.Cipher
import javax.crypto.SecretKeyFactory
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.PBEKeySpec
import javax.crypto.spec.SecretKeySpec
/**
* v0.3.6.0: passphrase-encrypted recovery-key envelope.
*
* Lets the user back up (and later restore) the
* [org.incido.compose.data.security.ObjectBoxKeyProvider] at-rest
* encryption key — the same 32-byte AES key that protects every
* encrypted note + attachment row. Without this, a device migration
* with encrypted notes has no recovery path other than restoring an
* encrypted backup.
*
* On-disk layout:
*
* ```
* magic "INCKEY1\0" (8 bytes)
* salt (16 bytes)
* iv (12 bytes)
* ciphertext + tag (variable — wraps exactly 32 key bytes)
* ```
*
* Identical KDF + AEAD to [EncryptedBackupCodec] (PBKDF2-HMAC-SHA256,
* 200,000 iterations → 256-bit AES key; AES-256-GCM body) so the
* import / export code path is symmetric. The magic header is what
* lets the import side auto-detect the format — the wrapper file is
* written via SAF so the user picks the destination.
*
* The Keystore master key itself is **not exportable** (it's
* device-bound by design); we only wrap the 32-byte field key, which
* is what actually encrypts note content. The recovery envelope is
* useless without the passphrase, so a stolen recovery file alone
* does not compromise the notes.
*/
object EncryptedKeyCodec {
/** "Incido Recovery Key v1" — null terminator included so it
* never collides with `{` (the first byte of any JSON object) or
* with the backup envelope's "INCDBK1\0" header. */
val MAGIC: ByteArray = byteArrayOf(
0x49, 0x4E, 0x43, 0x4B, 0x45, 0x59, 0x31, 0x00,
)
/** Number of bytes the wrapped payload holds — must be exactly
* [org.incido.compose.data.security.ObjectBoxKeyProvider.KEY_BYTES].
* Enforced on encrypt + decrypt so a tampered file is rejected
* before the cipher is installed. */
const val KEY_PAYLOAD_BYTES = 32
private const val SALT_BYTES = 16
private const val IV_BYTES = 12
private const val GCM_TAG_BITS = 128
private const val PBKDF2_ITERATIONS = 200_000
private const val DERIVED_KEY_BITS = 256
private const val TRANSFORMATION = "AES/GCM/NoPadding"
private val secureRandom = SecureRandom()
/** True if [bytes] starts with [MAGIC] — used by the import side
* to distinguish a recovery key from any other file the user
* might pick. */
fun isEncryptedKey(bytes: ByteArray): Boolean {
if (bytes.size < MAGIC.size) return false
return bytes.copyOfRange(0, MAGIC.size).contentEquals(MAGIC)
}
/**
* Encrypt exactly [KEY_PAYLOAD_BYTES] of [rawKey] with [passphrase]
* and return the full envelope. Throws if the input isn't the
* expected length.
*/
fun encrypt(rawKey: ByteArray, passphrase: CharArray): ByteArray {
require(rawKey.size == KEY_PAYLOAD_BYTES) {
"Recovery key payload must be $KEY_PAYLOAD_BYTES bytes (got ${rawKey.size})"
}
val salt = ByteArray(SALT_BYTES).also(secureRandom::nextBytes)
val iv = ByteArray(IV_BYTES).also(secureRandom::nextBytes)
val derived = deriveKey(passphrase, salt)
try {
val cipher = Cipher.getInstance(TRANSFORMATION)
cipher.init(
Cipher.ENCRYPT_MODE,
SecretKeySpec(derived, "AES"),
GCMParameterSpec(GCM_TAG_BITS, iv),
)
val cipherText = cipher.doFinal(rawKey)
return MAGIC + salt + iv + cipherText
} finally {
derived.fill(0)
passphrase.fill('0')
}
}
/**
* Reverse of [encrypt]. Returns the 32 raw key bytes. Throws on
* bad passphrase, wrong magic, truncated file, or wrong payload
* length (any of which is sufficient proof the file isn't a real
* Incido recovery key).
*/
fun decrypt(payload: ByteArray, passphrase: CharArray): ByteArray {
require(isEncryptedKey(payload)) { "Not an Incido recovery key file" }
require(payload.size >= MAGIC.size + SALT_BYTES + IV_BYTES + GCM_TAG_BITS / 8 + KEY_PAYLOAD_BYTES) {
"Recovery key file is truncated"
}
val salt = payload.copyOfRange(MAGIC.size, MAGIC.size + SALT_BYTES)
val iv = payload.copyOfRange(
MAGIC.size + SALT_BYTES,
MAGIC.size + SALT_BYTES + IV_BYTES,
)
val cipherText = payload.copyOfRange(
MAGIC.size + SALT_BYTES + IV_BYTES,
payload.size,
)
val derived = deriveKey(passphrase, salt)
try {
val cipher = Cipher.getInstance(TRANSFORMATION)
cipher.init(
Cipher.DECRYPT_MODE,
SecretKeySpec(derived, "AES"),
GCMParameterSpec(GCM_TAG_BITS, iv),
)
val raw = cipher.doFinal(cipherText)
require(raw.size == KEY_PAYLOAD_BYTES) {
"Recovery key payload is the wrong size (${raw.size} != $KEY_PAYLOAD_BYTES)"
}
return raw
} finally {
derived.fill(0)
passphrase.fill('0')
}
}
private fun deriveKey(passphrase: CharArray, salt: ByteArray): ByteArray {
val spec = PBEKeySpec(passphrase, salt, PBKDF2_ITERATIONS, DERIVED_KEY_BITS)
try {
val factory = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256")
return factory.generateSecret(spec).encoded
} finally {
spec.clearPassword()
}
}
}