@chainberry/trust-wallet-core 2.5.0 → 2.5.1

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
@@ -236,6 +237,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()
@@ -581,6 +598,81 @@ object NativeWalletStore {
     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

@@ -271,4 +271,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())
+  }
 }