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:
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()
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user