@_nazmiforreal/flutter-ota 0.1.25 → 0.1.27

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/PatcherConfig.kt

@@ -0,0 +1,173 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.content.pm.PackageManager
+import android.os.Build
+import android.util.Log
+import org.json.JSONArray
+
+/**
+ * 热更新运行时配置读写，统一走 SharedPreferences。
+ *
+ * 所有键值由 Dart 侧在 FlutterPatcher.init() 时下发，**不在** 库里硬编码任何
+ * 业务相关默认值（服务端 URL、公钥、渠道等）。
+ */
+internal object PatcherConfig {
+
+    const val PREFS_NAME = "flutter_patcher_prefs"
+
+    // ---- Config keys ----
+    private const val KEY_PUBLIC_KEY = "public_key_base64"
+    private const val KEY_MAX_CRASH = "max_crash_count"
+    private const val KEY_STRICT_SIG = "strict_signature"
+    private const val KEY_LOADER_FIELDS = "loader_field_candidates"
+    private const val KEY_LOADER_HEURISTIC = "loader_fallback_heuristic"
+    private const val KEY_MAX_PATCH_HISTORY = "max_patch_history"
+    private const val KEY_MAX_ASSET_HISTORY = "max_asset_history"
+
+    // ---- Runtime state keys (CrashGuard / PatchManager) ----
+    const val KEY_CRASH_COUNT = "crash_count"
+    const val KEY_PATCH_LOADING = "patch_loading"
+
+    /** PID written at [com.flutter_patcher.flutter_patcher.CrashGuard.markBooting]; consumed
+     *  next cold start to look up `ActivityManager.getHistoricalProcessExitReasons` (API 30+).
+     *  Unused on API < 30 — that path uses the naive "patch_loading=true ⇒ crash" rule. */
+    const val KEY_LAST_BOOTING_PID = "last_booting_pid"
+
+    /** Wall-clock time (epoch millis) when the patched process began booting, written together
+     *  with [KEY_LAST_BOOTING_PID] at markBooting. Used on API 30+ to bound crash attribution:
+     *  a crash is only treated as a *patch boot* failure when it occurred within
+     *  [BOOT_CRASH_WINDOW_MS] of this timestamp. Prevents an unrelated runtime crash/ANR hours
+     *  into a healthy session from tripping the circuit breaker and reverting the patch. */
+    const val KEY_BOOT_STARTED_AT = "boot_started_at"
+
+    // ---- File layout ----
+    const val PATCH_DIR = "flutter_patcher"
+    const val PATCH_FILENAME = "libapp_patch.so"
+    const val META_FILENAME = "patch_meta.json"
+
+    // ---- Meta JSON keys ----
+    const val META_KEY_TARGET_VERSION_CODE = "targetVersionCode"
+
+    // ---- Sentinels ----
+    const val INVALID_VERSION_CODE = -1L
+
+    // ---- Patch history limits ----
+    const val MAX_PATCH_HISTORY = 4
+    const val MAX_ASSET_HISTORY = 4
+
+    // ---- Defaults ----
+    /**
+     * 默认 1：补丁连续启动失败 1 次即立刻丢弃 + 入黑名单（fail-fast）。
+     *
+     * 设计依据：补丁加载后崩溃是明确"补丁有问题"信号，不应该再赌一次让用户多崩
+     * 一次。0.1 之前默认是 2，行为是"崩 2 次才回滚"，已确认对用户体验更糟。
+     * 业务侧若想保留旧行为，显式传 `FlutterPatcher.init(maxCrashCount: 2)`。
+     */
+    const val DEFAULT_MAX_CRASH = 1
+    const val DEFAULT_STRICT_SIG = true
+    const val DEFAULT_LOADER_HEURISTIC = false
+
+    /**
+     * How long after boot start a process death still counts as a *patch boot*
+     * failure (API 30+ ExitInfo path). Deaths later than this are treated as
+     * ordinary runtime exits and NOT charged against the patch.
+     *
+     * Rationale: once the app has rendered its first frame and run for a while,
+     * a later crash/ANR/force-stop is not evidence that the patch is bad. Before
+     * this bound, any REASON_CRASH / REASON_ANR / REASON_CRASH_NATIVE recorded
+     * for the last booting pid — even hours into a healthy session — was counted,
+     * so the circuit breaker would delete the patch and the app would silently
+     * revert to the pre-OTA build. 30s comfortably covers real boot-time crashes
+     * while excluding steady-state failures.
+     */
+    const val BOOT_CRASH_WINDOW_MS = 30_000L
+
+    fun prefs(context: Context): SharedPreferences =
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+
+    internal fun encodeLoaderFieldCandidates(fields: List<String>): String {
+        val normalized = fields
+            .map { it.trim() }
+            .filter { it.isNotEmpty() }
+            .distinct()
+        return JSONArray(normalized).toString()
+    }
+
+    internal fun decodeLoaderFieldCandidates(raw: Any?): List<String> {
+        return when (raw) {
+            is String -> try {
+                val arr = JSONArray(raw)
+                List(arr.length()) { arr.optString(it) }
+                    .map { it.trim() }
+                    .filter { it.isNotEmpty() }
+                    .distinct()
+            } catch (_: Exception) {
+                emptyList()
+            }
+            else -> emptyList()
+        }
+    }
+
+    fun saveConfig(
+        context: Context,
+        publicKeyBase64: String,
+        maxCrashCount: Int,
+        strictSignature: Boolean,
+        loaderFieldCandidates: List<String>,
+        loaderFallbackHeuristic: Boolean,
+        maxPatchHistory: Int = MAX_PATCH_HISTORY,
+        maxAssetHistory: Int = MAX_ASSET_HISTORY
+    ) {
+        prefs(context).edit()
+            .putString(KEY_PUBLIC_KEY, publicKeyBase64)
+            .putInt(KEY_MAX_CRASH, maxCrashCount.coerceAtLeast(1))
+            .putBoolean(KEY_STRICT_SIG, strictSignature)
+            .putString(KEY_LOADER_FIELDS, encodeLoaderFieldCandidates(loaderFieldCandidates))
+            .putBoolean(KEY_LOADER_HEURISTIC, loaderFallbackHeuristic)
+            .putInt(KEY_MAX_PATCH_HISTORY, maxPatchHistory.coerceAtLeast(0))
+            .putInt(KEY_MAX_ASSET_HISTORY, maxAssetHistory.coerceAtLeast(0))
+            .apply()
+    }
+
+    fun publicKey(context: Context): String =
+        prefs(context).getString(KEY_PUBLIC_KEY, "") ?: ""
+
+    fun maxCrashCount(context: Context): Int =
+        prefs(context).getInt(KEY_MAX_CRASH, DEFAULT_MAX_CRASH)
+
+    fun strictSignature(context: Context): Boolean =
+        prefs(context).getBoolean(KEY_STRICT_SIG, DEFAULT_STRICT_SIG)
+
+    fun loaderFieldCandidates(context: Context): List<String> =
+        decodeLoaderFieldCandidates(prefs(context).all[KEY_LOADER_FIELDS])
+
+    fun loaderFallbackHeuristic(context: Context): Boolean =
+        prefs(context).getBoolean(KEY_LOADER_HEURISTIC, DEFAULT_LOADER_HEURISTIC)
+
+    fun maxPatchHistory(context: Context): Int =
+        prefs(context).getInt(KEY_MAX_PATCH_HISTORY, MAX_PATCH_HISTORY)
+
+    fun maxAssetHistory(context: Context): Int =
+        prefs(context).getInt(KEY_MAX_ASSET_HISTORY, MAX_ASSET_HISTORY)
+
+    /**
+     * 读取当前宿主 APK 的 versionCode（API 28+ 用 longVersionCode，以下降级）。
+     * 查询自身包名不应失败，失败时返回 [INVALID_VERSION_CODE] 作为兜底。
+     */
+    fun currentVersionCode(context: Context): Long {
+        return try {
+            val pi = context.packageManager.getPackageInfo(context.packageName, 0)
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+                pi.longVersionCode
+            } else {
+                @Suppress("DEPRECATION")
+                pi.versionCode.toLong()
+            }
+        } catch (e: PackageManager.NameNotFoundException) {
+            Log.e("FlutterPatcher/Config", "own package not found", e)
+            INVALID_VERSION_CODE
+        }
+    }
+}

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/SignatureVerifier.kt

@@ -0,0 +1,177 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.os.Build
+import android.util.Base64
+import android.util.Log
+import java.io.File
+import java.security.KeyFactory
+import java.security.MessageDigest
+import java.security.Signature
+import java.security.spec.X509EncodedKeySpec
+
+/**
+ * 补丁文件完整性与签名校验。
+ *
+ * 策略：
+ * - MD5 校验：始终执行（来自 [com.flutter_patcher.flutter_patcher.PatchInfo.md5]）
+ * - Ed25519 签名：
+ *   - signature 为空 → 跳过（仅靠 MD5 + 传输层防篡改）
+ *   - signature 非空 且 API >= 33 → 使用 JDK 原生 Ed25519 验签
+ *   - signature 非空 且 API < 33：
+ *     - strictSignature=true（默认安全） → **拒绝加载**，防止攻击者通过降级到低
+ *       版本设备绕过签名校验
+ *     - strictSignature=false → 跳过验签（调用方显式选择降级）
+ *
+ * 签名的消息体约定为 **MD5 小写 hex 字符串的 UTF-8 字节**，
+ * 与 Dart 侧 PatchInfo.signature 含义保持一致。
+ */
+internal object SignatureVerifier {
+
+    private const val TAG = "FlutterPatcher/Sig"
+
+    /** 计算文件 MD5（小写 hex）。 */
+    fun md5(file: File): String {
+        val digest = MessageDigest.getInstance("MD5")
+        file.inputStream().use { input ->
+            val buf = ByteArray(8192)
+            while (true) {
+                val n = input.read(buf)
+                if (n <= 0) break
+                digest.update(buf, 0, n)
+            }
+        }
+        return digest.digest().joinToString("") { "%02x".format(it) }
+    }
+
+    /**
+     * 仅校验 Ed25519 签名（调用方已确认 MD5 匹配）。
+     *
+     * - signature 为空 → 跳过返回 true
+     * - signature 非空但 publicKey 未配置 → 拒绝
+     * - API < 33 且 strictSignature=true → 拒绝（防止降级攻击）
+     * - API < 33 且 strictSignature=false → 跳过返回 true
+     * - API >= 33 → 真实 Ed25519 验签
+     *
+     * @param md5HexLower 已匹配并**小写化**的 md5 hex 字符串（作为签名消息体）
+     */
+    fun verifySignatureOnly(
+        md5HexLower: String,
+        signatureBase64: String,
+        publicKeyBase64: String,
+        strictSignature: Boolean = true
+    ): Boolean {
+        val sig = signatureBase64.trim()
+        if (sig.isEmpty() || sig.equals("null", ignoreCase = true)) {
+            Log.d(TAG, "signature empty, skip Ed25519 check")
+            return true
+        }
+        if (publicKeyBase64.isEmpty()) {
+            Log.w(TAG, "signature present but no public key configured, reject")
+            return false
+        }
+
+        if (Build.VERSION.SDK_INT < 33) {
+            if (strictSignature) {
+                Log.e(
+                    TAG,
+                    "API ${Build.VERSION.SDK_INT} < 33, Ed25519 not supported; strict mode rejects. " +
+                        "Pass strictSignature=false to FlutterPatcher.init to downgrade (NOT recommended)."
+                )
+                return false
+            }
+            Log.w(
+                TAG,
+                "API ${Build.VERSION.SDK_INT} < 33, Ed25519 not supported; strictSignature=false, skip"
+            )
+            return true
+        }
+
+        return try {
+            verifyEd25519(md5HexLower, sig, publicKeyBase64)
+        } catch (e: Exception) {
+            Log.e(TAG, "Ed25519 verify failed", e)
+            false
+        }
+    }
+
+    /**
+     * [verify] 的细粒度结果。调用方据此可区分"被丢弃的具体原因"用于诊断上报，
+     * 见 [BootDiagnosticStore.DROPPED_MD5_MISMATCH] / [BootDiagnosticStore.DROPPED_SIGNATURE_INVALID]。
+     */
+    enum class VerifyResult { OK, MD5_MISMATCH, SIGNATURE_INVALID }
+
+    /**
+     * 完整校验（细粒度版本）：MD5 + 可选 Ed25519。返回失败原因分类。
+     *
+     * 注意：[expectedMd5] 为空时整体跳过 MD5 与签名校验，直接返回
+     * [VerifyResult.OK]（调用方明确选择"不下发 md5"，仅依赖 HTTPS）。
+     * 启动路径目前仍依赖 meta.effectiveMd5 非空，故启动期不会走到这条分支；
+     * 该分支主要服务于 [PatchManager.applyPatch] 期间的重复使用。
+     */
+    fun verifyDetailed(
+        file: File,
+        expectedMd5: String,
+        signatureBase64: String,
+        publicKeyBase64: String,
+        strictSignature: Boolean = true
+    ): VerifyResult {
+        if (expectedMd5.isEmpty()) {
+            Log.w(TAG, "expected md5 empty, skip md5 & signature verify")
+            return VerifyResult.OK
+        }
+        val actualMd5 = md5(file)
+        if (!actualMd5.equals(expectedMd5, ignoreCase = true)) {
+            Log.e(TAG, "md5 mismatch: expected=$expectedMd5, actual=$actualMd5")
+            return VerifyResult.MD5_MISMATCH
+        }
+        return if (verifySignatureOnly(
+                actualMd5.lowercase(),
+                signatureBase64,
+                publicKeyBase64,
+                strictSignature
+            )
+        ) {
+            VerifyResult.OK
+        } else {
+            VerifyResult.SIGNATURE_INVALID
+        }
+    }
+
+    /**
+     * 完整校验：MD5 + 可选 Ed25519。
+     *
+     * @param file             已下载的补丁文件
+     * @param expectedMd5      manifest 中的预期 MD5（小写 hex）
+     * @param signatureBase64  manifest 中的 Ed25519 签名（Base64，允许为空）
+     * @param publicKeyBase64  X.509 SubjectPublicKeyInfo 的 Base64 公钥（允许为空）
+     * @param strictSignature  API < 33 是否拒绝签名校验（默认 true，安全）
+     * @return 是否通过校验
+     */
+    fun verify(
+        file: File,
+        expectedMd5: String,
+        signatureBase64: String,
+        publicKeyBase64: String,
+        strictSignature: Boolean = true
+    ): Boolean = verifyDetailed(
+        file, expectedMd5, signatureBase64, publicKeyBase64, strictSignature
+    ) == VerifyResult.OK
+
+    private fun verifyEd25519(
+        md5Hex: String,
+        signatureBase64: String,
+        publicKeyBase64: String
+    ): Boolean {
+        val pkBytes = Base64.decode(publicKeyBase64, Base64.NO_WRAP)
+        val keySpec = X509EncodedKeySpec(pkBytes)
+        val kf = KeyFactory.getInstance("Ed25519")
+        val pk = kf.generatePublic(keySpec)
+
+        val sig = Signature.getInstance("Ed25519")
+        sig.initVerify(pk)
+        sig.update(md5Hex.toByteArray(Charsets.UTF_8))
+
+        val sigBytes = Base64.decode(signatureBase64, Base64.NO_WRAP)
+        return sig.verify(sigBytes)
+    }
+}

package/dart-src/root/android/src/test/kotlin/com/flutter_patcher/flutter_patcher/CrashGuardTest.kt

@@ -0,0 +1,61 @@
+package com.flutter_patcher.flutter_patcher
+
+import kotlin.test.Test
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+/**
+ * Unit tests for the boot-window crash attribution rule that prevents a
+ * healthy OTA patch from being reverted by an unrelated runtime crash/ANR
+ * hours into a session.
+ */
+class CrashGuardTest {
+
+    private val window = PatcherConfig.BOOT_CRASH_WINDOW_MS
+
+    @Test
+    fun crashWithinWindowIsChargedToPatch() {
+        val bootAt = 1_000_000L
+        // Crash 5s after boot — clearly a boot failure.
+        assertTrue(CrashGuard.isWithinBootWindow(bootAt, bootAt + 5_000L))
+    }
+
+    @Test
+    fun crashAtExactWindowEdgeIsCharged() {
+        val bootAt = 1_000_000L
+        assertTrue(CrashGuard.isWithinBootWindow(bootAt, bootAt + window))
+    }
+
+    @Test
+    fun crashLongAfterBootIsNotChargedToPatch() {
+        val bootAt = 1_000_000L
+        // Crash 2 hours into a healthy session — must NOT revert the patch.
+        val twoHours = 2 * 60 * 60 * 1000L
+        assertFalse(CrashGuard.isWithinBootWindow(bootAt, bootAt + twoHours))
+    }
+
+    @Test
+    fun crashJustPastWindowIsNotCharged() {
+        val bootAt = 1_000_000L
+        assertFalse(CrashGuard.isWithinBootWindow(bootAt, bootAt + window + 1L))
+    }
+
+    @Test
+    fun unknownBootTimestampFallsBackToCharging() {
+        // No boot timestamp recorded (legacy state / upgrade) → conservative,
+        // preserve prior fail-fast behavior.
+        assertTrue(CrashGuard.isWithinBootWindow(0L, 5_000_000L))
+    }
+
+    @Test
+    fun unknownCrashTimestampFallsBackToCharging() {
+        assertTrue(CrashGuard.isWithinBootWindow(1_000_000L, 0L))
+    }
+
+    @Test
+    fun clockSkewNegativeElapsedTreatedAsInWindow() {
+        // ExitInfo timestamp earlier than recorded boot (device clock change) →
+        // treat as in-window rather than silently ignoring a genuine boot crash.
+        assertTrue(CrashGuard.isWithinBootWindow(2_000_000L, 1_000_000L))
+    }
+}

package/dart-src/root/android/src/test/kotlin/com/flutter_patcher/flutter_patcher/LoaderHookTest.kt

@@ -0,0 +1,25 @@
+package com.flutter_patcher.flutter_patcher
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class LoaderHookTest {
+    @Test
+    fun patchedAssetLookupKeysUseBundlePath() {
+        assertEquals(
+            "flutter_patcher_assets/images/hero.png",
+            patchedAssetLookupKey(
+                "flutter_patcher_assets",
+                "images/hero.png"
+            )
+        )
+        assertEquals(
+            "flutter_patcher_assets/packages/demo/images/hero.png",
+            patchedPackageAssetLookupKey(
+                "flutter_patcher_assets",
+                "images/hero.png",
+                "demo"
+            )
+        )
+    }
+}