@chainberry/trust-wallet-core 2.5.0 → 2.5.2

package/android/src/main/java/com/chainberry/trustwalletcore/ChainberryTrustWalletCoreModule.kt

@@ -1,12 +1,14 @@
 package com.chainberry.trustwalletcore
 
 import android.app.AlertDialog
+import android.util.Log
 import androidx.fragment.app.FragmentActivity
 import expo.modules.kotlin.exception.CodedException
 import expo.modules.kotlin.functions.Coroutine
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.sync.Mutex
 import wallet.core.jni.HDWallet
 import java.util.UUID
 import kotlin.coroutines.resume
@@ -21,6 +23,13 @@ class ChainberryTrustWalletCoreModule : Module() {
       // Must be loaded once before any JNI calls
       System.loadLibrary("TrustWalletCore")
     }
+
+    // Global, not per-walletId: createWallet/importWallet/deleteWallet all read-modify-write the
+    // *entire* metadata map, so two concurrent calls touching different wallet ids would still
+    // race each other on that shared blob — a per-id lock wouldn't protect against that. See
+    // docs/adr/0002. A single companion-object Mutex (rather than an instance property) keeps
+    // this a true process-wide lock even if more than one module instance is ever created.
+    private val lifecycleMutex = Mutex()
   }
 
   private val context get() = appContext.reactContext
@@ -30,22 +39,68 @@ class ChainberryTrustWalletCoreModule : Module() {
     get() = appContext.currentActivity as? FragmentActivity
       ?: throw CodedException("NoActivity", "No foreground FragmentActivity to host the biometric prompt", null)
 
+  /**
+   * Serializes the whole body — including the biometric/device-credential prompt, not just the
+   * store writes — against every other lifecycle-mutating call, so at most one is ever touching
+   * the shared metadata store at a time (see docs/adr/0002). Also forecloses a second, separate
+   * bug: two concurrent `BiometricPrompt` invocations racing each other.
+   *
+   * [rejectIfBusy] chooses the policy for a caller that finds the lock already held:
+   * `createWallet`/`importWallet` reject immediately (`ERR_WALLET_OPERATION_IN_PROGRESS`) so a
+   * double-tap can never mint two wallets; `deleteWallet` queues instead, since two distinct
+   * deletes are both legitimate and should both eventually happen.
+   */
+  private suspend fun <T> withLifecycleLock(rejectIfBusy: Boolean, body: suspend () -> T): T {
+    if (rejectIfBusy) {
+      if (!lifecycleMutex.tryLock()) {
+        throw CodedException(
+          "ERR_WALLET_OPERATION_IN_PROGRESS",
+          "Another wallet operation is already in progress",
+          null,
+        )
+      }
+    } else {
+      lifecycleMutex.lock()
+    }
+    try {
+      return body()
+    } finally {
+      lifecycleMutex.unlock()
+    }
+  }
+
   override fun definition() = ModuleDefinition {
     Name("TrustWalletCore")
 
-    // strength 128 = 12 words, 256 = 24 words. Returns { walletId, addresses }.
+    // Runs once, right after module init, before any of the AsyncFunctions below can be
+    // reached from JS — so nothing can legitimately be mid-operation yet, which is exactly what
+    // makes a one-shot pass here sufficient (no lock/grace-period needed against an in-flight
+    // call). This is the actual crash-safety mechanism for an interrupted create/delete; see
+    // CONTEXT.md and docs/adr/0001. Never allowed to block or crash startup.
+    OnCreate {
+      val reactContext = appContext.reactContext
+      if (reactContext == null) {
+        Log.w("TrustWalletCoreModule", "reconciliation: react context unavailable at module init, skipping")
+      } else {
+        NativeWalletStore.reconcileOrphans(reactContext)
+      }
+    }
+
+    // strength 128 = 12 words, 256 = 24 words. Returns { walletId, addresses, isTestnet }.
     // No BIP-39 passphrase support: signTransaction always reconstructs the wallet with an
     // empty passphrase, so accepting one here would derive addresses from a seed different
     // from the one actually used to sign — always pass "" to stay consistent with that.
     // isTestnet selects the address format for BTC/LTC/BCH (see ChainSigner.addressForChain) —
-    // every other chain's address is the same on mainnet and testnet.
+    // every other chain's address is the same on mainnet and testnet. This value is persisted
+    // as immutable per-wallet metadata (NativeWalletStore.WalletRecord) — signTransaction reads
+    // it back from there instead of accepting it as a parameter, so it can never drift.
     AsyncFunction("createWallet") Coroutine { strength: Int, isTestnet: Boolean ->
       val wallet = HDWallet(strength, "")
       persistNewWallet(wallet, isTestnet)
     }
 
     // One-time mnemonic exposure from JS, at import only — never retained after this call.
-    // Returns { walletId, addresses }. No BIP-39 passphrase support (see `createWallet`).
+    // Returns { walletId, addresses, isTestnet }. No BIP-39 passphrase support (see `createWallet`).
     AsyncFunction("importWallet") Coroutine { mnemonic: String, isTestnet: Boolean ->
       val wallet = HDWallet(mnemonic, "") // throws on invalid mnemonic
       persistNewWallet(wallet, isTestnet)
@@ -53,8 +108,8 @@ class ChainberryTrustWalletCoreModule : Module() {
 
     // Reads only the ungated metadata store — no biometric prompt.
     AsyncFunction("listWallets") {
-      NativeWalletStore.loadMetadata(context).map { (walletId, addresses) ->
-        mapOf("walletId" to walletId, "addresses" to addresses)
+      NativeWalletStore.loadMetadata(context).map { (walletId, record) ->
+        mapOf("walletId" to walletId, "addresses" to record.addresses, "isTestnet" to record.isTestnet)
       }
     }
 
@@ -62,25 +117,53 @@ class ChainberryTrustWalletCoreModule : Module() {
     // anything is deleted, same gate as `signTransaction`/`exportMnemonic`. A
     // compromised/malicious JS caller can still invoke this directly (there's no UI call
     // site today), so the gate must live here rather than in JS.
+    //
+    // Removes the metadata entry *before* the secret (mnemonic file + Keystore key) — the
+    // reverse of the old ordering. If this is interrupted between the two steps, the wallet is
+    // already gone from `listWallets` and only an orphaned secret-side resource is left behind,
+    // which the next app launch's reconciliation pass cleans up (see docs/adr/0001) — never a
+    // metadata record still pointing at a secret that's already gone.
     AsyncFunction("deleteWallet") Coroutine { walletId: String ->
-      val id = NativeWalletStore.validateWalletId(walletId)
-      NativeWalletStore.confirmIdentity(activity, context, "Delete wallet")
-      NativeWalletStore.deleteMnemonic(context, id)
-      val metadata = NativeWalletStore.loadMetadata(context).toMutableMap()
-      metadata.remove(id)
-      NativeWalletStore.saveMetadata(context, metadata)
+      withLifecycleLock(rejectIfBusy = false) {
+        val id = NativeWalletStore.validateWalletId(walletId)
+        NativeWalletStore.confirmIdentity(activity, context, "Delete wallet")
+        val metadata = NativeWalletStore.loadMetadata(context).toMutableMap()
+        metadata.remove(id)
+        NativeWalletStore.saveMetadata(context, metadata)
+        NativeWalletStore.deleteMnemonic(context, id)
+      }
     }
 
     // Triggers the native biometry/device-credential prompt, then signs entirely in-process.
-    // Returns { signedTx, meta? }. isTestnet must match whatever `createWallet`/`importWallet`
-    // used — see ChainSigner.keyForChain (a mismatch signs with the wrong key for BTC/LTC).
-    AsyncFunction("signTransaction") Coroutine { walletId: String, chain: String, unsignedTx: Map<String, Any>, isTestnet: Boolean ->
+    // Returns { signedTx, meta? }. Network mode (mainnet/testnet) is read from the wallet's own
+    // persisted record, not accepted as a parameter — see ChainSigner.keyForChain and
+    // NativeWalletStore.WalletRecord for why a caller-supplied value here could sign with the
+    // wrong key for BTC/LTC.
+    AsyncFunction("signTransaction") Coroutine { walletId: String, chain: String, unsignedTx: Map<String, Any> ->
       val id = NativeWalletStore.validateWalletId(walletId)
       val chainKey = ChainKey.fromJs(chain)
       confirmTransaction(chainKey, unsignedTx)
       val cipher = NativeWalletStore.authenticateForExistingWallet(activity, context, id, "Sign transaction")
       val mnemonic = NativeWalletStore.loadMnemonic(context, id, cipher)
       val wallet = HDWallet(mnemonic, "")
+      // Backfill any addresses missing from metadata (chains added after wallet was created).
+      // Runs silently after the biometric gate — no extra prompt needed.
+      val metadata = NativeWalletStore.loadMetadata(context).toMutableMap()
+      val record = metadata[id] ?: throw NativeWalletStoreError.NotFound(id)
+      val isTestnet = record.isTestnet
+      val storedAddresses = record.addresses.toMutableMap()
+      var changed = false
+      for (chainEntry in ChainKey.entries) {
+        val key = chainEntry.name.lowercase()
+        if (!storedAddresses.containsKey(key)) {
+          storedAddresses[key] = ChainSigner.addressForChain(wallet, chainEntry, isTestnet)
+          changed = true
+        }
+      }
+      if (changed) {
+        metadata[id] = record.copy(addresses = storedAddresses)
+        runCatching { NativeWalletStore.saveMetadata(context, metadata) }
+      }
       val result = ChainSigner.sign(chainKey, wallet, unsignedTx, isTestnet)
       val response = mutableMapOf<String, Any>("signedTx" to result.signedTx)
       result.meta?.let { response["meta"] = it }
@@ -95,8 +178,8 @@ class ChainberryTrustWalletCoreModule : Module() {
     }
   }
 
-  /// Shows a native AlertDialog with decoded tx details before biometric auth fires.
-  /// The user must tap "Confirm & Sign" — cancelling throws UserCancelled.
+  // Shows a native AlertDialog with decoded tx details before biometric auth fires.
+  // The user must tap "Confirm & Sign" — cancelling throws UserCancelled.
   private suspend fun confirmTransaction(chain: ChainKey, unsignedTx: Map<String, Any>) {
     val message = ChainSigner.buildSummary(chain, unsignedTx)
     suspendCancellableCoroutine<Unit> { continuation ->
@@ -131,7 +214,7 @@ class ChainberryTrustWalletCoreModule : Module() {
 
     try {
       val metadata = NativeWalletStore.loadMetadata(context).toMutableMap()
-      metadata[walletId] = addresses
+      metadata[walletId] = NativeWalletStore.WalletRecord(isTestnet, addresses)
       NativeWalletStore.saveMetadata(context, metadata)
     } catch (e: Exception) {
       // The mnemonic/key is already persisted but has no metadata pointer — compensate by
@@ -142,6 +225,6 @@ class ChainberryTrustWalletCoreModule : Module() {
       throw e
     }
 
-    return mapOf("walletId" to walletId, "addresses" to addresses)
+    return mapOf("walletId" to walletId, "addresses" to addresses, "isTestnet" to isTestnet)
   }
 }

package/android/src/main/java/com/chainberry/trustwalletcore/NativeWalletStore.kt

@@ -21,6 +21,7 @@ import org.json.JSONException
 import org.json.JSONObject
 import java.io.File
 import java.security.KeyStore
+import java.util.Collections
 import java.util.UUID
 import javax.crypto.Cipher
 import javax.crypto.KeyGenerator
@@ -79,8 +80,7 @@ enum class AuthMode(val aliasInfix: String) {
  * Extends `CodedException` directly (rather than a flat `Exception`) so `.code` survives the
  * Expo bridge losslessly with no extra wrapping step.
  */
-sealed class NativeWalletStoreError private constructor(code: String, message: String, cause: Throwable? = null) :
-  CodedException(code, message, cause) {
+sealed class NativeWalletStoreError private constructor(code: String, message: String, cause: Throwable? = null) : CodedException(code, message, cause) {
 
   class NotFound(walletId: String) :
     NativeWalletStoreError("ERR_WALLET_NOT_FOUND", "Wallet not found: $walletId")
@@ -236,6 +236,22 @@ object NativeWalletStore {
    * metadata field needed. */
   internal fun keyAlias(mode: AuthMode, walletId: String): String = KEY_ALIAS_PREFIX + mode.aliasInfix + walletId
 
+  /** Inverse of [keyAlias]: recovers `(mode, walletId)` from a raw Keystore alias string, or
+   * `null` if it doesn't match this module's alias scheme at all (some other feature's Keystore
+   * entry, sharing the same `AndroidKeyStore` provider). Checks the longer/specific infixes
+   * (`bio_`, `cred_`) before the empty [AuthMode.LEGACY_COMBINED] infix, which would otherwise
+   * match every alias under [KEY_ALIAS_PREFIX] — relies on [AuthMode.entries] iterating in
+   * declaration order, same assumption [resolveExistingMode] makes. Used by [reconcileOrphans]
+   * to identify which Keystore aliases belong to which wallet id, without needing a Context. */
+  internal fun parseKeyAlias(alias: String): Pair<AuthMode, String>? {
+    if (!alias.startsWith(KEY_ALIAS_PREFIX)) return null
+    for (mode in AuthMode.entries) {
+      val prefix = KEY_ALIAS_PREFIX + mode.aliasInfix
+      if (alias.startsWith(prefix)) return mode to alias.removePrefix(prefix)
+    }
+    return null
+  }
+
   private fun getOrCreateKey(walletId: String, mode: AuthMode): SecretKey {
     val alias = keyAlias(mode, walletId)
     val ks = keyStore()
@@ -525,17 +541,27 @@ object NativeWalletStore {
     }
   }
 
-  // MARK: - Metadata (ungated: walletId -> { chain: address })
+  // MARK: - Metadata (ungated: walletId -> { isTestnet, addresses: { chain: address } })
+
+  /** A wallet's network mode is fixed at creation time ([ChainberryTrustWalletCoreModule
+   * .persistNewWallet]) and never changes thereafter — [isTestnet] is the authoritative value
+   * `signTransaction` must derive/sign with, replacing the old pattern of accepting it fresh as
+   * a parameter on every call (see docs/adr and the security remediation this type was
+   * introduced for). */
+  data class WalletRecord(val isTestnet: Boolean, val addresses: Map<String, String>)
 
   /** Atomically replaces [target] via a temp-file write + `File.renameTo` (an atomic
    * `rename(2)` on the same filesystem/mount, since the temp file is created alongside
    * [target] in the same directory) — never a direct in-place overwrite, which could leave a
    * torn file if the process is killed mid-write. Pure/`File`-based so it's unit-testable on
    * the plain JVM without an Android `Context`. */
-  internal fun saveMetadataToFile(target: File, wallets: Map<String, Map<String, String>>) {
+  internal fun saveMetadataToFile(target: File, wallets: Map<String, WalletRecord>) {
     val root = JSONObject()
-    for ((walletId, addresses) in wallets) {
-      root.put(walletId, JSONObject(addresses as Map<*, *>))
+    for ((walletId, record) in wallets) {
+      val entry = JSONObject()
+      entry.put("isTestnet", record.isTestnet)
+      entry.put("addresses", JSONObject(record.addresses as Map<*, *>))
+      root.put(walletId, entry)
     }
     val temp = File(target.parentFile, "$METADATA_FILE.tmp-${System.nanoTime()}")
     try {
@@ -552,35 +578,119 @@ object NativeWalletStore {
 
   /** Distinguishes "no metadata has ever been written" (legitimately empty) from a genuine
    * parse/corruption failure, which now throws a typed [NativeWalletStoreError.Corrupted]
-   * instead of letting a raw, uncaught `JSONException` leak through the Expo bridge.
-   * Pure/`File`-based so it's unit-testable on the plain JVM without an Android `Context`. */
-  internal fun loadMetadataFromFile(file: File): Map<String, Map<String, String>> {
+   * instead of letting a raw, uncaught `JSONException`/[org.json.JSONException] leak through
+   * the Expo bridge. A record missing `isTestnet` or `addresses` (e.g. data written by a
+   * pre-migration build under the old flat schema) is treated the same way — corrupted, not
+   * silently reinterpreted — there is no legacy-shape fallback. Pure/`File`-based so it's
+   * unit-testable on the plain JVM without an Android `Context`. */
+  internal fun loadMetadataFromFile(file: File): Map<String, WalletRecord> {
     if (!file.exists()) return emptyMap()
     val root = try {
       JSONObject(file.readText())
     } catch (e: JSONException) {
       throw NativeWalletStoreError.Corrupted("metadata.json is not valid JSON", e)
     }
-    val result = mutableMapOf<String, Map<String, String>>()
-    for (walletId in root.keys()) {
-      val addressesJson = root.getJSONObject(walletId)
-      val addresses = mutableMapOf<String, String>()
-      for (chain in addressesJson.keys()) {
-        addresses[chain] = addressesJson.getString(chain)
+    val result = mutableMapOf<String, WalletRecord>()
+    try {
+      for (walletId in root.keys()) {
+        val entry = root.getJSONObject(walletId)
+        val isTestnet = entry.getBoolean("isTestnet")
+        val addressesJson = entry.getJSONObject("addresses")
+        val addresses = mutableMapOf<String, String>()
+        for (chain in addressesJson.keys()) {
+          addresses[chain] = addressesJson.getString(chain)
+        }
+        result[walletId] = WalletRecord(isTestnet, addresses)
       }
-      result[walletId] = addresses
+    } catch (e: JSONException) {
+      throw NativeWalletStoreError.Corrupted("metadata.json entry has an unexpected shape", e)
     }
     return result
   }
 
-  fun saveMetadata(context: Context, wallets: Map<String, Map<String, String>>) {
+  fun saveMetadata(context: Context, wallets: Map<String, WalletRecord>) {
     saveMetadataToFile(metadataFile(context), wallets)
   }
 
-  fun loadMetadata(context: Context): Map<String, Map<String, String>> {
+  fun loadMetadata(context: Context): Map<String, WalletRecord> {
     return loadMetadataFromFile(metadataFile(context))
   }
 
+  // MARK: - Reconciliation (see CONTEXT.md "orphan"/"reconciliation pass", docs/adr/0001)
+
+  /** Every `.enc` file in [walletsDir] whose wallet id has no entry in [liveIds] — the
+   * file-side half of an orphan. Pure/`File`-based so it's unit-testable on the plain JVM.
+   * Deliberately does not also match `METADATA_FILE` itself: that file has no `.enc` suffix. */
+  internal fun findOrphanFiles(walletsDir: File, liveIds: Set<String>): List<File> =
+    walletsDir.listFiles { f -> f.name.endsWith(".enc") }
+      ?.filter { it.name.removeSuffix(".enc") !in liveIds }
+      ?: emptyList()
+
+  /** Every leftover `metadata.json.tmp-*` file in [walletsDir] — pure litter from a
+   * [saveMetadataToFile] interrupted between writing the temp file and renaming it over the
+   * target (the rename itself is atomic, so the target is never at risk; only the temp file
+   * can be left behind). Not a security or correctness concern, just disk hygiene swept up
+   * alongside the real orphan checks since reconciliation is already scanning this directory. */
+  internal fun findStaleMetadataTempFiles(walletsDir: File): List<File> =
+    walletsDir.listFiles { f -> f.name.startsWith("$METADATA_FILE.tmp-") }?.toList() ?: emptyList()
+
+  /**
+   * Runs once at module init (see `TrustWalletCoreModule`'s `OnCreate`), before the JS layer can
+   * issue its first `createWallet`/`importWallet`/`deleteWallet` call — the actual source of
+   * crash-safety for an interrupted create or delete, not the in-call rollback in
+   * `persistNewWallet`. Android has *two* independently-persistable secret-side resources per
+   * wallet — the `.enc` file and its Keystore key alias, since [getOrCreateKey] creates the key
+   * before [saveMnemonic] ever writes the file — so both are checked against the metadata store
+   * independently, neither gated on the other's presence.
+   *
+   * Best-effort and never throws: any failure here is logged and skipped rather than propagated,
+   * since a broken reconciliation pass must never become "the app won't launch." A metadata entry
+   * with no matching secret-side resource (the reverse shape — a "zombie") is deliberately left
+   * untouched here; see [NativeWalletStoreError.NotFound] and docs/adr/0001 for why.
+   */
+  fun reconcileOrphans(context: Context) {
+    val liveIds = try {
+      loadMetadata(context).keys
+    } catch (e: Exception) {
+      Log.w(TAG, "reconciliation: failed to load metadata, skipping this pass entirely", e)
+      return
+    }
+
+    val dir = walletsDir(context)
+
+    try {
+      for (file in findOrphanFiles(dir, liveIds)) {
+        if (!file.delete()) {
+          Log.w(TAG, "reconciliation: failed to delete orphaned file ${file.name}")
+        }
+      }
+    } catch (e: Exception) {
+      Log.w(TAG, "reconciliation: failed while cleaning up orphaned files", e)
+    }
+
+    try {
+      val ks = keyStore()
+      for (alias in Collections.list(ks.aliases())) {
+        val (_, walletId) = parseKeyAlias(alias) ?: continue
+        if (walletId !in liveIds) {
+          try {
+            ks.deleteEntry(alias)
+          } catch (e: Exception) {
+            Log.w(TAG, "reconciliation: failed to delete orphaned key alias $alias", e)
+          }
+        }
+      }
+    } catch (e: Exception) {
+      Log.w(TAG, "reconciliation: failed while enumerating Keystore aliases", e)
+    }
+
+    try {
+      findStaleMetadataTempFiles(dir).forEach { it.delete() }
+    } catch (e: Exception) {
+      Log.w(TAG, "reconciliation: failed while cleaning up stale metadata temp files", e)
+    }
+  }
+
   // MARK: - Biometric/device-credential prompt
 
   /** Authenticates and returns a `Cipher` ready for [saveMnemonic], for a brand-new wallet id.

package/android/src/test/java/com/chainberry/trustwalletcore/NativeWalletStoreTest.kt

@@ -69,13 +69,28 @@ class NativeWalletStoreTest {
   fun metadata_roundTrips() {
     val file = File(tmp.root, "metadata.json")
     val wallets = mapOf(
-      "id-1" to mapOf("ethereum" to "0xabc"),
-      "id-2" to mapOf("bitcoin" to "bc1abc"),
+      "id-1" to NativeWalletStore.WalletRecord(isTestnet = false, addresses = mapOf("ethereum" to "0xabc")),
+      "id-2" to NativeWalletStore.WalletRecord(isTestnet = true, addresses = mapOf("bitcoin" to "bc1abc")),
     )
     NativeWalletStore.saveMetadataToFile(file, wallets)
     assertEquals(wallets, NativeWalletStore.loadMetadataFromFile(file))
   }
 
+  @Test
+  fun metadata_legacyFlatShapeThrowsCorrupted_notSilentlyMisread() {
+    // Data written by a pre-migration build (walletId -> {chain: address} with no
+    // isTestnet/addresses wrapper) must never be silently reinterpreted — there is no
+    // migration path, so this must surface as Corrupted, same as any other unexpected shape.
+    val file = File(tmp.root, "metadata.json")
+    file.writeText("""{"id-1":{"ethereum":"0xabc"}}""")
+    try {
+      NativeWalletStore.loadMetadataFromFile(file)
+      fail("expected Corrupted for legacy flat-shape metadata")
+    } catch (e: NativeWalletStoreError.Corrupted) {
+      // expected
+    }
+  }
+
   @Test
   fun metadata_missingFileIsEmptyMap() {
     val file = File(tmp.root, "does-not-exist.json")
@@ -99,7 +114,7 @@ class NativeWalletStoreTest {
   @Test
   fun metadata_failedWrite_leavesExistingFileUntouched() {
     val target = File(tmp.root, "metadata.json")
-    val original = mapOf("id-1" to mapOf("ethereum" to "0xabc"))
+    val original = mapOf("id-1" to NativeWalletStore.WalletRecord(isTestnet = false, addresses = mapOf("ethereum" to "0xabc")))
     NativeWalletStore.saveMetadataToFile(target, original)
 
     // Making the parent directory read-only blocks creating the temp file at all (the
@@ -111,7 +126,10 @@ class NativeWalletStoreTest {
     target.parentFile!!.setWritable(false)
     try {
       try {
-        NativeWalletStore.saveMetadataToFile(target, mapOf("id-2" to mapOf("bitcoin" to "bc1xyz")))
+        NativeWalletStore.saveMetadataToFile(
+          target,
+          mapOf("id-2" to NativeWalletStore.WalletRecord(isTestnet = false, addresses = mapOf("bitcoin" to "bc1xyz"))),
+        )
         // Some filesystems/CI runners ignore setWritable(false) for the owner (e.g. root).
         // If the write unexpectedly succeeded, there's nothing to assert here.
       } catch (e: NativeWalletStoreError.PermissionDenied) {
@@ -271,4 +289,74 @@ class NativeWalletStoreTest {
   fun describeLegacySecurityLevel_notInsideSecureHardwareIsSoftware() {
     assertEquals("SOFTWARE", NativeWalletStore.describeLegacySecurityLevel(false))
   }
+
+  // ─── parseKeyAlias ───────────────────────────────────────────────────────────
+
+  @Test
+  fun parseKeyAlias_isTheInverseOfKeyAlias() {
+    val id = UUID.randomUUID().toString()
+    for (mode in AuthMode.entries) {
+      val alias = NativeWalletStore.keyAlias(mode, id)
+      assertEquals(mode to id, NativeWalletStore.parseKeyAlias(alias))
+    }
+  }
+
+  @Test
+  fun parseKeyAlias_legacyInfixDoesNotSwallowBioOrCredAliases() {
+    // Regression check: LEGACY_COMBINED's infix is "", which is a prefix of every alias under
+    // KEY_ALIAS_PREFIX — parseKeyAlias must still resolve a bio_/cred_ alias to its actual mode,
+    // not fall through to LEGACY_COMBINED just because the empty-infix check would also match.
+    val id = UUID.randomUUID().toString()
+    assertEquals(
+      AuthMode.BIOMETRIC_STRONG to id,
+      NativeWalletStore.parseKeyAlias(NativeWalletStore.keyAlias(AuthMode.BIOMETRIC_STRONG, id)),
+    )
+    assertEquals(
+      AuthMode.DEVICE_CREDENTIAL to id,
+      NativeWalletStore.parseKeyAlias(NativeWalletStore.keyAlias(AuthMode.DEVICE_CREDENTIAL, id)),
+    )
+  }
+
+  @Test
+  fun parseKeyAlias_unrelatedAliasReturnsNull() {
+    assertEquals(null, NativeWalletStore.parseKeyAlias("some_other_features_key"))
+  }
+
+  // ─── findOrphanFiles / findStaleMetadataTempFiles (reconciliation, docs/adr/0001) ────────────
+
+  @Test
+  fun findOrphanFiles_fileWithNoMetadataEntryIsOrphaned() {
+    File(tmp.root, "orphan-id.enc").writeBytes(byteArrayOf(1))
+    val orphans = NativeWalletStore.findOrphanFiles(tmp.root, liveIds = emptySet())
+    assertEquals(listOf("orphan-id.enc"), orphans.map { it.name })
+  }
+
+  @Test
+  fun findOrphanFiles_fileWithMatchingMetadataEntryIsNotOrphaned() {
+    File(tmp.root, "live-id.enc").writeBytes(byteArrayOf(1))
+    val orphans = NativeWalletStore.findOrphanFiles(tmp.root, liveIds = setOf("live-id"))
+    assertTrue(orphans.isEmpty())
+  }
+
+  @Test
+  fun findOrphanFiles_ignoresNonEncFiles() {
+    // metadata.json itself (and any stray temp file) must never be swept up as a wallet orphan.
+    File(tmp.root, "metadata.json").writeText("{}")
+    val orphans = NativeWalletStore.findOrphanFiles(tmp.root, liveIds = emptySet())
+    assertTrue(orphans.isEmpty())
+  }
+
+  @Test
+  fun findStaleMetadataTempFiles_findsLeftoverTempFile() {
+    // Simulates a saveMetadataToFile interrupted after the temp write but before the rename.
+    File(tmp.root, "metadata.json.tmp-12345").writeText("{}")
+    val stale = NativeWalletStore.findStaleMetadataTempFiles(tmp.root)
+    assertEquals(listOf("metadata.json.tmp-12345"), stale.map { it.name })
+  }
+
+  @Test
+  fun findStaleMetadataTempFiles_ignoresCommittedMetadataFile() {
+    File(tmp.root, "metadata.json").writeText("{}")
+    assertTrue(NativeWalletStore.findStaleMetadataTempFiles(tmp.root).isEmpty())
+  }
 }