@adep/cli 0.4.4 → 0.4.6

package/templates/app-mobile/plugins/adep-bridge/android/src/main/java/com/adep/bridge/AdepBridge.kt

@@ -4,6 +4,8 @@ import com.getcapacitor.Plugin
 import com.getcapacitor.PluginCall
 import com.getcapacitor.PluginMethod
 import com.getcapacitor.annotation.CapacitorPlugin
+import org.json.JSONArray
+import org.json.JSONObject
 
 /**
  * AgentDeploy 移动壳原生桥（APP-009，Android 侧）。
@@ -19,6 +21,13 @@ import com.getcapacitor.annotation.CapacitorPlugin
 class AdepBridge : Plugin() {
     private var gate: AdepPermissionGate? = null
 
+    /** 设备本地 SQLite（APP-023）。懒建：首次 sqlite 调用时初始化（与 iOS 同）。 */
+    @Volatile
+    private var sqlite: AdepSqlite? = null
+
+    /** 安装身份自举（APP-027）用的后台线程句柄（持有引用只为可读性；勿在主线程 join）。 */
+    private var identityThread: Thread? = null
+
     override fun load() {
         gate = try {
             AdepPermissionGate.load(context)
@@ -28,6 +37,69 @@ class AdepBridge : Plugin() {
             android.util.Log.e("adep-bridge", "权限清单加载失败", error)
             null
         }
+        startIdentityBootstrap()
+    }
+
+    /**
+     * 安装身份自举（APP-027）：首启向服务端签发端点换取 ownerKey，只存 Keystore。
+     *
+     * 三条边界（与 iOS `startIdentityBootstrap` 同口径）：
+     * 1. **后台线程**——`load()` 在插件注册链上，同步网络会阻塞首屏；
+     *    主线程发网络请求在 Android 上是直接抛 `NetworkOnMainThreadException`。
+     * 2. **失败不阻断**——断网 / 5xx / 响应形态不符只记带原因码的日志，下次启动重试。
+     * 3. **幂等**——已有 ownerKey 不发请求（行为级门的分母断言：请求数 == 1）。
+     *
+     * ⚠️ **不做在 JS 面**：`dist/plugin.js` 对象键集合不变（页面拿不到写凭据的通道）。
+     */
+    private fun startIdentityBootstrap() {
+        val appContext = context.applicationContext
+        val bootstrap = AdepIdentityBootstrap(
+            configData = {
+                try {
+                    appContext.assets.open("public/${AdepIdentityLogic.CONFIG_FILE_NAME}")
+                        .bufferedReader().use { it.readText() }
+                } catch (error: Exception) {
+                    null
+                }
+            },
+            storedOwnerKey = { AdepKeystore.loadOwnerKey(appContext) },
+            persistOwnerKey = { key ->
+                try {
+                    AdepKeystore.saveOwnerKey(appContext, key)
+                    true
+                } catch (error: Exception) {
+                    android.util.Log.e("adep-bridge", "ownerKey 写入 Keystore 失败", error)
+                    false
+                }
+            },
+            // APP-028：恢复码与 ownerKey 一起落 Keystore（服务端只存摘要，明文只此一次）。
+            // 读口的唯一用处是**写后读回校验**——写成功读不出等于码已丢。
+            storedRecoveryCode = { AdepKeystore.loadRecoveryCode(appContext) },
+            persistRecoveryCode = { code ->
+                try {
+                    AdepKeystore.saveRecoveryCode(appContext, code)
+                    true
+                } catch (error: Exception) {
+                    android.util.Log.e("adep-bridge", "恢复码写入 Keystore 失败", error)
+                    false
+                }
+            },
+            transport = AdepHttpTransport(),
+            platform = "android",
+            log = { message -> android.util.Log.i("adep-identity", message) },
+            // 库已有数据且此前用 FALLBACK_KEY 建的 ⇒ 这里换成正式 key（rekey 在 AdepSqlite 内收口）。
+            onIssued = { key -> sqlite?.adoptKey(key) },
+        )
+        identityThread = Thread({
+            val outcome = bootstrap.start()
+            if (outcome is AdepIdentityBootstrap.Outcome.Failed) {
+                // 失败已由 bootstrap 记过带原因码的日志；这里只留一条汇总便于搜索。
+                android.util.Log.w("adep-bridge", "ownerKey 首启签发失败：${outcome.code}")
+            }
+        }, "adep-identity").apply {
+            isDaemon = true
+            start()
+        }
     }
 
     /** 调用原生能力。门控先于一切实现：未声明 → 拒绝 + 审计；已声明未实现 → NOT_IMPLEMENTED。 */
@@ -60,27 +132,141 @@ class AdepBridge : Plugin() {
         }
     }
 
-    /** 读 ownerKey（Keystore）。无则返回 null（首启未签发）。 */
+    /**
+     * 读 ownerKey（Keystore）。首启尚未签发（或签发失败）时返回 null。
+     *
+     * ⚠️ **`setOwnerKey` 已删除**（APP-027）：它曾是「页面调不到、原生也没人调」的死方法——
+     * 写凭据的入口现在只有 [AdepIdentityBootstrap]（首启自举）与 [AdepKeystore.saveOwnerKey]
+     * （恢复码换键流程的前置），两者都在原生侧，页面永远拿不到写凭据的通道。
+     */
     @PluginMethod
     fun getOwnerKey(call: PluginCall) {
         call.resolve(jsObject("value" to AdepKeystore.loadOwnerKey(context)))
     }
 
-    /** 写 ownerKey（Keystore）。安装首启时由壳原生侧调用服务端签发端点后存入。 */
+    /**
+     * 读恢复码（APP-034，独立 prefs 文件 `adep_keystore_recovery`）。无则 null。
+     *
+     * ⚠️ **只读**：写口在 [AdepIdentityBootstrap]（首启自举），页面没有写凭据的通道。
+     * 页面拿它做呈现 / 导出（认领凭据——服务端只存摘要、无法重发）；与 iOS 侧
+     * `getRecoveryCode` 同形（app-android-bridge-contract 的三向对齐门咬着）。
+     */
     @PluginMethod
-    fun setOwnerKey(call: PluginCall) {
-        val key = call.getString("key")
-        if (key.isNullOrEmpty()) {
-            call.reject("key 必须为非空字符串")
+    fun getRecoveryCode(call: PluginCall) {
+        call.resolve(jsObject("value" to AdepKeystore.loadRecoveryCode(context)))
+    }
+
+    // MARK: - 设备本地 SQLite（APP-023，与 iOS AdepBridge.swift withSqlite 同形）
+
+    /**
+     * sqlite 三方法的公共骨架：门控 → sqlite 懒建（长持复用）→ params 三态分流 → 执行 → 信封。
+     * 形状对齐 `DeviceSqliteBridge`（bridge.ts）：sql + params（可选数组）；
+     * run → { changes }，all → { rows }，get → { row | null }。
+     *
+     * ⚠️ **sqlite 实例必须懒建一次、跨调用复用**（2026-10-22 iOS 真机第六轮教训）：
+     * `runOwnedWrite` 事务协议（SAVEPOINT → 业务 → RELEASE/ROLLBACK）是**三次独立桥调用**，
+     * SAVEPOINT 是连接级状态——每次调用重建实例 = 连接换 = 「no such savepoint」。这里字段
+     * `sqlite` 首调建、其后复用（配合执行层 {@link AdepSqlite} 的内部 helper 长持连接）。
+     *
+     * ⚠️ **每条路径必须恰好 resolve 一次**（2026-10-22 iOS 真机第五轮血的教训：params
+     * 缺席被误判为非法 ⇒ CAPPluginCall 悬空、JS promise 永不落定、页面装配**静默卡死**）。
+     * 三态分流在纯逻辑层 {@link sqliteBindParams}；失败信封带 ok/code/message，成功信封
+     * 经唯一组装点 {@link sqliteSuccessEnvelope}。
+     */
+    private fun withSqlite(call: PluginCall, capability: String, body: (AdepSqlite, String, List<Any>) -> JSONObject) {
+        val gate = gate
+        if (gate == null) {
+            call.resolve(jsObject("ok" to false, "code" to "GATE_UNAVAILABLE", "message" to "权限门控未建立（清单缺失）"))
+            return
+        }
+        if (!gate.check(capability)) {
+            call.resolve(
+                jsObject(
+                    "ok" to false,
+                    "code" to AdepPermissionGate.PERMISSION_DENIED,
+                    "message" to "原生能力 \"$capability\" 未在应用 manifest 的 permissions 中声明（未声明即不可用，且不会在运行时申请）",
+                )
+            )
+            return
+        }
+        val sql = call.getString("sql")
+        if (sql.isNullOrEmpty()) {
+            call.resolve(jsObject("ok" to false, "code" to SqliteCode.INVALID_PARAM, "message" to "sql 必须为非空字符串"))
             return
         }
-        AdepKeystore.saveOwnerKey(context, key)
-        call.resolve()
+        // isNullOrEmpty 后 sql 智能转型为非空，闭包捕获的 sql 即非空。
+        // 懒建一次、跨调用复用（长持连接是 SAVEPOINT 跨调用存活的前提）。首调失败 → fail loud。
+        val instance = sqlite ?: runCatching { AdepSqlite.open(context) }
+            .getOrNull()
+            ?: run {
+                call.resolve(jsObject("ok" to false, "code" to SqliteCode.OPEN_FAILED, "message" to "SQLite 打开失败"))
+                return
+            }
+        this.sqlite = instance
+        // params 三态分流（纯逻辑层）：缺席 → []（合法无参）；元素非法 → 抛（回 INVALID_PARAM）。
+        val bindParams = try {
+            sqliteBindParams(call.getArray("params"))
+        } catch (error: SqliteBridgeError) {
+            call.resolve(jsObject("ok" to false, "code" to error.code, "message" to error.message))
+            return
+        }
+        try {
+            val data = body(instance, sql, bindParams)
+            // sqliteSuccessEnvelope 返回 JSONObject（纯逻辑层契约），resolve 要 JSObject
+            // ⇒ 经 jsObject 重建（字段平移，键集不变——ok/changes/rows/row + 业务键）。
+            val envelope = sqliteSuccessEnvelope(data)
+            val payload = com.getcapacitor.JSObject()
+            val keys = envelope.names() ?: org.json.JSONArray()
+            for (i in 0 until keys.length()) {
+                val k = keys.getString(i)
+                payload.put(k, envelope.get(k))
+            }
+            call.resolve(payload)
+        } catch (error: SqliteBridgeError) {
+            call.resolve(jsObject("ok" to false, "code" to error.code, "message" to error.message))
+        } catch (error: Exception) {
+            call.resolve(jsObject("ok" to false, "code" to SqliteCode.EXEC_FAILED, "message" to error.message))
+        }
+    }
+
+    /** 执行写语句（DDL / DML）。JS 面：`AdepBridge.sqliteRun({ sql, params? })` → `{ changes }`。 */
+    @PluginMethod
+    fun sqliteRun(call: PluginCall) {
+        withSqlite(call, "sqlite.run") { sqlite, sql, params ->
+            jsObject("changes" to sqlite.run(sql, params))
+        }
+    }
+
+    /** 执行查询返回多行。JS 面：`AdepBridge.sqliteAll({ sql, params? })` → `{ rows }`。 */
+    @PluginMethod
+    fun sqliteAll(call: PluginCall) {
+        withSqlite(call, "sqlite.all") { sqlite, sql, params ->
+            jsObject("rows" to sqlite.all(sql, params))
+        }
+    }
+
+    /** 执行单行查询。JS 面：`AdepBridge.sqliteGet({ sql, params? })` → `{ row | null }`。 */
+    @PluginMethod
+    fun sqliteGet(call: PluginCall) {
+        withSqlite(call, "sqlite.get") { sqlite, sql, params ->
+            jsObject("row" to sqlite.get(sql, params))
+        }
+    }
+
+    /** 插件销毁时关闭长持连接（幂等；等价 iOS `close()`，防 WebView reload 场景 fd 泄漏）。 */
+    override fun handleOnDestroy() {
+        sqlite?.close()
+        sqlite = null
+        super.handleOnDestroy()
     }
 
-    private fun jsObject(vararg pairs: Pair<String, Any?>): org.json.JSONObject {
-        val object = org.json.JSONObject()
-        for ((key, value) in pairs) object.put(key, value)
-        return object
+    /** 组 JS 回包对象。⚠️ 必须是 `JSObject`（Capacitor 7 的 `PluginCall.resolve` 只收它），
+     *  裸 `JSONObject` 编译不过（APP-026 行为级门把执行层拉进 kotlinc 编译面时暴露）。
+     *  ⚠️ `object` 是 Kotlin 关键字，不能当变量名（此前写 `val object =` 是靠「从未真编译」
+     *  存活的死代码形态）——变量名改 `envelope`。 */
+    private fun jsObject(vararg pairs: Pair<String, Any?>): com.getcapacitor.JSObject {
+        val envelope = com.getcapacitor.JSObject()
+        for ((key, value) in pairs) envelope.put(key, value)
+        return envelope
     }
 }

package/templates/app-mobile/plugins/adep-bridge/android/src/main/java/com/adep/bridge/AdepIdentity.kt

@@ -0,0 +1,342 @@
+package com.adep.bridge
+
+import org.json.JSONObject
+import java.net.HttpURLConnection
+import java.net.URL
+
+/**
+ * 安装身份自举（Android，APP-027；PRD §2.11.5「设备身份与恢复」/ ADR-0008 第 2 条）。
+ *
+ * 与 iOS `AdepIdentity.swift` **逐条同语义**（§3.2.8 硬约束④：两平台桥同形）：
+ *
+ * 1. **ownerKey 只能由服务端签发**（本地自造 / 构建期预置判违规）。服务端
+ *    `POST /api/v1/projects/:projectId/app-installations` 早在 APP-007 交付，但客户端
+ *    从来没有调用方 ⇒ `getOwnerKey` 恒 null、单主同步（`Bearer <ownerKey>`）真机不可用、
+ *    SQLCipher 库 key 恒落硬编码缺省（key 就在二进制里）。
+ * 2. **不做在 JS 面**：`dist/plugin.js` 对象键集合不变——页面没有写凭据的通道
+ *    （XSS 不能替换 ownerKey 劫持数据分区）。
+ * 3. **失败不改变可用性**：断网 / 5xx / 响应形态不符 ⇒ 不写空值、不覆盖既有值，
+ *    只留带原因码的日志，下次启动重试；首启签发失败不阻止 app 启动。
+ * 4. **幂等**：已有合法 ownerKey ⇒ 不发请求（行为级门的分母断言：请求数 == 1）。
+ *
+ * ⚠️ **本文件只依赖 JVM + org.json**（不 import 任何 `android.*`）：这样 `kotlinc` 编完
+ * 能用 `java` 直接真跑（`adep-identity.test.ts` 的 Android 段），判定逻辑不必靠读源码猜。
+ * 需要 `Context` 的部分（读 `assets/public/adep.app.json`）留在 `AdepBridge`。
+ */
+data class AdepIdentityConfig(val platformUrl: String, val projectSlug: String)
+
+/** 签发响应里客户端真正需要的三样（`partition` 是 `sha256(ownerKey)`，客户端不用）。 */
+data class AdepIdentityIssue(val ownerKey: String, val installationId: String, val recoveryCode: String)
+
+/** 自举失败（原因码 + 可读详情）。`code` 会原样进日志，排障先看码。 */
+class AdepIdentityFailure(val code: String, message: String) : Exception(message)
+
+/** 自举失败 / 跳过的原因码（与 iOS `AdepIdentityCode` 逐字同值）。 */
+object AdepIdentityCode {
+    const val CONFIG_MISSING = "IDENTITY_CONFIG_MISSING"
+    const val CONFIG_INVALID = "IDENTITY_CONFIG_INVALID"
+    const val REQUEST_FAILED = "IDENTITY_REQUEST_FAILED"
+    const val RESPONSE_INVALID = "IDENTITY_RESPONSE_INVALID"
+    const val STORE_FAILED = "IDENTITY_STORE_FAILED"
+    const val ALREADY_ISSUED = "IDENTITY_ALREADY_ISSUED"
+    const val ALREADY_STARTED = "IDENTITY_ALREADY_STARTED"
+}
+
+/**
+ * 判定层（纯函数）。常量与服务端 `identity/contract.ts` / `sync-routes.ts` **逐字对应**
+ * （`OWNER_KEY_PREFIX` / `OWNER_KEY_BYTES=32` ⇒ 64 位 hex / 端点路径）；漂移由
+ * `adep-identity.test.ts` 的跨端一致性门对账。
+ */
+object AdepIdentityLogic {
+    /** 壳配置文件名（与 iOS `AdepShellConfig.configFileName` 同值；Android 侧落点只有 assets/public）。 */
+    const val CONFIG_FILE_NAME = "adep.app.json"
+    const val OWNER_KEY_PREFIX = "adep_ok_"
+    const val OWNER_KEY_HEX_LENGTH = 64
+
+    /** 签发端点（平台侧挂在 `/api` 前缀下；`:projectId` 服务端接受 **id 或 slug**）。 */
+    const val ISSUE_PATH_PREFIX = "/api/v1/projects/"
+    const val ISSUE_PATH_SUFFIX = "/app-installations"
+
+    private val HEX = "0123456789abcdef".toSet()
+
+    /** ownerKey 形态：前缀 + 64 位**小写** hex（与服务端正则同形，刻意不宽松）。 */
+    fun isOwnerKey(value: String): Boolean {
+        if (!value.startsWith(OWNER_KEY_PREFIX)) return false
+        val hex = value.substring(OWNER_KEY_PREFIX.length)
+        if (hex.length != OWNER_KEY_HEX_LENGTH) return false
+        return hex.all { it in HEX }
+    }
+
+    /** projectSlug 形态（与 `adep.app.json` schema 的 `^[a-z][a-z0-9-]{0,62}$` 同形）。 */
+    fun isProjectSlug(value: String): Boolean {
+        if (value.isEmpty() || value.length > 63) return false
+        if (value[0] !in 'a'..'z') return false
+        return value.all { it in 'a'..'z' || it in '0'..'9' || it == '-' }
+    }
+
+    /** 解析 `adep.app.json`（只取签发需要的两个字段；完整 schema 校验在 CLI 侧）。 */
+    fun parseConfig(raw: String): AdepIdentityConfig {
+        val object0 = try {
+            JSONObject(raw)
+        } catch (error: Exception) {
+            throw AdepIdentityFailure(AdepIdentityCode.CONFIG_INVALID, "adep.app.json 不是 JSON 对象")
+        }
+        val platformUrl = object0.optString("platformUrl").takeIf { it.isNotEmpty() }
+            ?: throw AdepIdentityFailure(AdepIdentityCode.CONFIG_INVALID, "adep.app.json 缺 platformUrl")
+        val scheme = try {
+            val parsed = URL(platformUrl)
+            val protocol = parsed.protocol.lowercase()
+            if (protocol != "http" && protocol != "https") null else parsed.host
+        } catch (error: Exception) {
+            null
+        }
+        if (scheme.isNullOrEmpty()) {
+            throw AdepIdentityFailure(
+                AdepIdentityCode.CONFIG_INVALID,
+                "platformUrl 不是合法的 http(s) URL：$platformUrl",
+            )
+        }
+        val slug = object0.optString("projectSlug").takeIf { it.isNotEmpty() }
+            ?: throw AdepIdentityFailure(AdepIdentityCode.CONFIG_INVALID, "adep.app.json 缺 projectSlug")
+        if (!isProjectSlug(slug)) {
+            throw AdepIdentityFailure(
+                AdepIdentityCode.CONFIG_INVALID,
+                "projectSlug 形态不符（需小写字母开头，仅小写字母/数字/连字符）：$slug",
+            )
+        }
+        return AdepIdentityConfig(platformUrl, slug)
+    }
+
+    /**
+     * 组装签发端点。`platformUrl` 常带尾斜杠（`https://adep.top/`）⇒ 先归一，
+     * 否则拼出 `//api/v1/...`（服务端 404，症状像「端点没部署」）。
+     */
+    fun issueUrl(config: AdepIdentityConfig): String =
+        config.platformUrl.trimEnd('/') + ISSUE_PATH_PREFIX + config.projectSlug + ISSUE_PATH_SUFFIX
+
+    /** 请求体：服务端 body 契约是 `{ platform }`（`t.Object({ platform: t.String() })`）。 */
+    fun issueBody(platform: String): String {
+        val escaped = platform.replace("\\", "\\\\").replace("\"", "\\\"")
+        return "{\"platform\":\"$escaped\"}"
+    }
+
+    /**
+     * 解析签发响应：`{ installation: { installationId, ownerKey, recoveryCode, … } }`。
+     *
+     * **形态不符一律抛**（不写「尽量取到的那部分」）：ownerKey 是 bearer 凭据，把空串 /
+     * 半截值写进 Keystore 等于把设备身份变成「永远 401」的垃圾状态，而且看起来像已签发
+     * （下次启动不再重试）——比直接失败难查得多。
+     */
+    fun parseIssue(raw: String): AdepIdentityIssue {
+        val object0 = try {
+            JSONObject(raw)
+        } catch (error: Exception) {
+            throw AdepIdentityFailure(AdepIdentityCode.RESPONSE_INVALID, "签发响应不是 JSON 对象")
+        }
+        val installation = object0.optJSONObject("installation")
+            ?: throw AdepIdentityFailure(AdepIdentityCode.RESPONSE_INVALID, "签发响应缺 installation 对象")
+        val ownerKey = installation.optString("ownerKey")
+        if (!isOwnerKey(ownerKey)) {
+            throw AdepIdentityFailure(
+                AdepIdentityCode.RESPONSE_INVALID,
+                "installation.ownerKey 形态不符（期望 ${OWNER_KEY_PREFIX} + $OWNER_KEY_HEX_LENGTH 位小写 hex）",
+            )
+        }
+        val installationId = installation.optString("installationId")
+        if (installationId.isEmpty()) {
+            throw AdepIdentityFailure(AdepIdentityCode.RESPONSE_INVALID, "installation.installationId 缺失或为空")
+        }
+        val recoveryCode = installation.optString("recoveryCode")
+        if (recoveryCode.isEmpty()) {
+            throw AdepIdentityFailure(AdepIdentityCode.RESPONSE_INVALID, "installation.recoveryCode 缺失或为空")
+        }
+        return AdepIdentityIssue(ownerKey, installationId, recoveryCode)
+    }
+
+    /** 日志脱敏：只留前缀与 6 位（凭据本身绝不进日志）。 */
+    fun maskOwnerKey(value: String): String {
+        val keep = OWNER_KEY_PREFIX.length + 6
+        return if (value.length <= keep) value else value.take(keep) + "…"
+    }
+
+    /**
+     * 恢复码脱敏（日志用，APP-028）。形态 `<installationId>.<secret>`：**installationId 不是机密**
+     * （它就是安装行主键，服务端接口里也以明文出现），secret 段才是凭据。
+     * ⇒ 保留 installationId + secret 前 4 位 + 总长度（长度能看出「码被截断」这类畸形）。
+     */
+    fun maskRecoveryCode(value: String, installationId: String): String {
+        val head = if (installationId.isEmpty()) "" else "$installationId."
+        val secret = if (head.isNotEmpty() && value.startsWith(head)) value.removePrefix(head) else value
+        return "$head${secret.take(4)}…(len ${value.length})"
+    }
+}
+
+/** 传输层结果。`status == 0` = 没拿到 HTTP 响应（断网 / DNS / 超时 / TLS），`error` 带原因。 */
+data class AdepIdentityHttpResult(val status: Int, val body: String?, val error: String?)
+
+/** 传输协议（可注入 ⇒ 行为级门用假传输驱动全部失败分支，不打真网络）。 */
+fun interface AdepIdentityTransport {
+    fun post(url: String, body: String, timeoutMillis: Int): AdepIdentityHttpResult
+}
+
+/** 生产传输：`HttpURLConnection`（不引第三方依赖）。阻塞式——调用方必须在后台线程。 */
+class AdepHttpTransport : AdepIdentityTransport {
+    override fun post(url: String, body: String, timeoutMillis: Int): AdepIdentityHttpResult {
+        var connection: HttpURLConnection? = null
+        return try {
+            connection = URL(url).openConnection() as HttpURLConnection
+            connection.requestMethod = "POST"
+            connection.connectTimeout = timeoutMillis
+            connection.readTimeout = timeoutMillis
+            connection.doOutput = true
+            connection.setRequestProperty("Content-Type", "application/json")
+            connection.setRequestProperty("Accept", "application/json")
+            connection.outputStream.use { it.write(body.toByteArray(Charsets.UTF_8)) }
+            val status = connection.responseCode
+            val stream = if (status in 200..299) connection.inputStream else connection.errorStream
+            val text = stream?.bufferedReader()?.use { it.readText() }
+            AdepIdentityHttpResult(status, text, null)
+        } catch (error: Exception) {
+            AdepIdentityHttpResult(0, null, error.message ?: error.javaClass.simpleName)
+        } finally {
+            connection?.disconnect()
+        }
+    }
+}
+
+/**
+ * 首启自举：查本地 →（缺则）签发 → 写 Keystore → 通知库换 key。
+ *
+ * 副作用全部经构造参数注入（存储 / 配置 / 传输 / 日志 / 换 key）⇒ 三条判定
+ * （要不要请求、写不写、写什么）都能被行为级门真跑。
+ *
+ * ⚠️ `start()` **同步阻塞**；插件在后台线程上调用它（主线程网络 = NetworkOnMainThreadException）。
+ */
+class AdepIdentityBootstrap(
+    private val configData: () -> String?,
+    private val storedOwnerKey: () -> String?,
+    private val persistOwnerKey: (String) -> Boolean,
+    /** 读本地既有恢复码（写后读回校验用；APP-028）。 */
+    private val storedRecoveryCode: () -> String?,
+    /** 写恢复码；**与 ownerKey 同生命周期**（每次成功签发覆盖两把）。 */
+    private val persistRecoveryCode: (String) -> Boolean,
+    private val transport: AdepIdentityTransport,
+    private val platform: String,
+    private val log: (String) -> Unit,
+    private val onIssued: (String) -> Unit,
+    private val timeoutMillis: Int = 10_000,
+) {
+    /** 自举结果（与 iOS `AdepIdentityBootstrap.Outcome` 同形）。 */
+    sealed class Outcome {
+        /** 签发并落库成功。 */
+        class Issued(val ownerKey: String) : Outcome()
+
+        /** 未发请求：已签发 / 重复启动。 */
+        class Skipped(val code: String) : Outcome()
+
+        /** 失败（原因码 + 详情）。**没有任何本地写入发生**。 */
+        class Failed(val code: String, val detail: String) : Outcome()
+    }
+
+    private val lock = Any()
+    private var started = false
+
+    @Suppress("ReturnCount")
+    fun start(): Outcome {
+        synchronized(lock) {
+            if (started) {
+                log("[adep-identity] ${AdepIdentityCode.ALREADY_STARTED}: 已启动过，忽略重复调用")
+                return Outcome.Skipped(AdepIdentityCode.ALREADY_STARTED)
+            }
+            started = true
+        }
+
+        // ① 已有合法 ownerKey ⇒ 一枚安装只签发一次（这条路径下请求数必须为 0）。
+        val existing = storedOwnerKey()
+        if (!existing.isNullOrEmpty()) {
+            if (AdepIdentityLogic.isOwnerKey(existing)) {
+                log(
+                    "[adep-identity] ${AdepIdentityCode.ALREADY_ISSUED}: 本地已有 ownerKey" +
+                        "（${AdepIdentityLogic.maskOwnerKey(existing)}），不重复签发",
+                )
+                return Outcome.Skipped(AdepIdentityCode.ALREADY_ISSUED)
+            }
+            // 形态不符（历史垃圾值 / 手写调试值）：不是可用身份，重新签发覆盖它——
+            // 不静默当「已签发」，那会让 app 永远带着一枚服务端不认的凭据。
+            log("[adep-identity] 本地 ownerKey 形态不符（长度 ${existing.length}），将重新签发")
+        }
+
+        // ② 配置（assets/public/adep.app.json）。缺失与非法分开报：打包问题 vs 配置写错。
+        val rawConfig = configData()
+            ?: return fail(
+                AdepIdentityCode.CONFIG_MISSING,
+                "assets 缺少 public/${AdepIdentityLogic.CONFIG_FILE_NAME}（CLI build 写入、cap sync 同步）",
+            )
+        val config = try {
+            AdepIdentityLogic.parseConfig(rawConfig)
+        } catch (error: AdepIdentityFailure) {
+            return fail(error.code, error.message ?: "")
+        } catch (error: Exception) {
+            return fail(AdepIdentityCode.CONFIG_INVALID, error.message ?: error.javaClass.simpleName)
+        }
+
+        // ③ 请求（status 0 = 没拿到响应；非 2xx = 服务端拒绝，两者都落 REQUEST_FAILED）。
+        val url = AdepIdentityLogic.issueUrl(config)
+        val result = transport.post(url, AdepIdentityLogic.issueBody(platform), timeoutMillis)
+        if (result.status !in 200..299) {
+            val detail = result.error?.let { "传输层失败：$it（url: $url）" }
+                ?: "HTTP ${result.status}（url: $url；响应：${result.body?.take(200) ?: ""}）"
+            return fail(AdepIdentityCode.REQUEST_FAILED, detail)
+        }
+        val rawBody = result.body
+            ?: return fail(AdepIdentityCode.RESPONSE_INVALID, "HTTP ${result.status} 但响应体为空")
+
+        // ④ 解析 + 落库。写失败也算失败：没写进去 = 下次还会签发（多一枚孤儿安装行）。
+        val issue = try {
+            AdepIdentityLogic.parseIssue(rawBody)
+        } catch (error: AdepIdentityFailure) {
+            return fail(error.code, error.message ?: "")
+        } catch (error: Exception) {
+            return fail(AdepIdentityCode.RESPONSE_INVALID, error.message ?: error.javaClass.simpleName)
+        }
+        // ⑤ 恢复码**先**落库并读回校验（APP-028）。
+        //
+        // 顺序即不变量：**本地有 ownerKey ⇒ 本地必有与它同源的恢复码**。
+        // 反过来（先写 ownerKey）会出现「app 已带着这枚身份跑，用户却永远拿不到恢复码」——
+        // 恢复码明文只在这一次响应里存在（服务端只存 recoveryCodeHash，任何端点都不重发），
+        // 丢了就是该安装的分区永久不可认领。所以宁可不落 ownerKey、下次启动重签。
+        if (!persistRecoveryCode(issue.recoveryCode)) {
+            return fail(
+                AdepIdentityCode.STORE_FAILED,
+                "恢复码写入 Keystore 失败（installationId: ${issue.installationId}）——本次不落 ownerKey，下次启动重新签发",
+            )
+        }
+        // 读回校验：写报成功但读不出是真实故障形态（Keystore 密钥失效 / prefs 被清）。
+        // 只看写返回码会把「码已丢」当成功——正是 APP-028 要消灭的静默。
+        if (storedRecoveryCode() != issue.recoveryCode) {
+            return fail(
+                AdepIdentityCode.STORE_FAILED,
+                "恢复码写入后读回不一致（installationId: ${issue.installationId}）——本次不落 ownerKey",
+            )
+        }
+        // ⑥ ownerKey 落库（写失败也算失败：没写进去 = 下次还会签发，多一枚孤儿安装行）。
+        if (!persistOwnerKey(issue.ownerKey)) {
+            return fail(
+                AdepIdentityCode.STORE_FAILED,
+                "ownerKey 写入 Keystore 失败（installationId: ${issue.installationId}）",
+            )
+        }
+        log(
+            "[adep-identity] 签发成功（installationId: ${issue.installationId}, platform: $platform, " +
+                "recoveryCode: ${AdepIdentityLogic.maskRecoveryCode(issue.recoveryCode, issue.installationId)}）",
+        )
+        onIssued(issue.ownerKey)
+        return Outcome.Issued(issue.ownerKey)
+    }
+
+    /** 失败收口：日志带原因码（排障先看码），并原样返回。 */
+    private fun fail(code: String, detail: String): Outcome {
+        log("[adep-identity] $code: $detail")
+        return Outcome.Failed(code, detail)
+    }
+}

package/templates/app-mobile/plugins/adep-bridge/android/src/main/java/com/adep/bridge/AdepKeystore.kt

@@ -11,14 +11,25 @@ import javax.crypto.SecretKey
 import javax.crypto.spec.GCMParameterSpec
 
 /**
- * ownerKey 的 Keystore 加密存储（Android，APP-009）。
+ * ownerKey / 恢复码的 Keystore 加密存储（Android，APP-009 / APP-027 / APP-028）。
  *
  * PRD §2.11.5「设备身份与恢复」：ownerKey 移动端**只存 Keychain / Keystore**——不落
  * 明文 SharedPreferences / 文件（客户端产物等同公开，明文落盘等于把设备身份交给解包者）。
  *
- * 实现：Android Keystore 系统生成/持有 AES 密钥（不可导出），ownerKey 用 AES/GCM 加密后
+ * 实现：Android Keystore 系统生成/持有 AES 密钥（不可导出），凭据用 AES/GCM 加密后
  * 存 SharedPreferences 密文。密钥本身留在 Keystore（硬件/系统隔离），应用进程只能用它
  * 加解密、拿不到密钥材料。
+ *
+ * ## 两个槽位（prefs 文件区分，APP-028）
+ *
+ * - `adep_keystore`（`owner_key_*` 键）：分区凭据。
+ * - `adep_keystore_recovery`（`recovery_code_*` 键）：换机 / 重装认领同一分区用的恢复码。
+ *
+ * ⚠️ **刻意不复用同一个 prefs 文件**：[deleteOwnerKey] 会 `.clear()` 整个文件，恢复码若同文件
+ * 会在换装 / 认领时被顺手抹掉——而服务端只存摘要，抹掉即永久丢失。
+ *
+ * ⚠️ **既有 ownerKey 的 prefs 文件名与键名不可改**：已装机设备上是既有状态，改名 = 读不到
+ * ownerKey ⇒ 库 key 失配 ⇒ 数据全丢（库是用旧 key 建的，重新签发救不回来）。
  */
 object AdepKeystore {
     private const val KEYSTORE = "AndroidKeyStore"
@@ -26,6 +37,9 @@ object AdepKeystore {
     private const val PREFS_NAME = "adep_keystore"
     private const val PREFS_CIPHERTEXT = "owner_key_ciphertext"
     private const val PREFS_IV = "owner_key_iv"
+    private const val PREFS_RECOVERY_NAME = "adep_keystore_recovery"
+    private const val PREFS_RECOVERY_CIPHERTEXT = "recovery_code_ciphertext"
+    private const val PREFS_RECOVERY_IV = "recovery_code_iv"
     private const val GCM_TAG_BITS = 128
 
     /** 读 ownerKey；无则返回 null（首启未签发）。 */
@@ -63,6 +77,46 @@ object AdepKeystore {
         context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit().clear().apply()
     }
 
+    // MARK: - 恢复码（APP-028，独立 prefs 文件）
+
+    /** 读恢复码；无则 null（首启未签发，或写入失败——后者由自举的读回校验报出来）。 */
+    fun loadRecoveryCode(context: Context): String? {
+        val prefs = context.getSharedPreferences(PREFS_RECOVERY_NAME, Context.MODE_PRIVATE)
+        val ciphertext = prefs.getString(PREFS_RECOVERY_CIPHERTEXT, null) ?: return null
+        val iv = prefs.getString(PREFS_RECOVERY_IV, null) ?: return null
+        return try {
+            val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+            cipher.init(
+                Cipher.DECRYPT_MODE,
+                loadOrCreateKey(),
+                GCMParameterSpec(GCM_TAG_BITS, Base64.decode(iv, Base64.NO_WRAP)),
+            )
+            String(cipher.doFinal(Base64.decode(ciphertext, Base64.NO_WRAP)), Charsets.UTF_8)
+        } catch (error: Exception) {
+            android.util.Log.e("adep-bridge", "恢复码解密失败", error)
+            null
+        }
+    }
+
+    /**
+     * 写恢复码（覆盖旧值）。失败直接抛——调用方 [AdepBridge] 会转成 `false`，
+     * 由自举判定「本次不落 ownerKey」（恢复码丢了不能只留日志）。
+     */
+    fun saveRecoveryCode(context: Context, code: String) {
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+        cipher.init(Cipher.ENCRYPT_MODE, loadOrCreateKey())
+        val ciphertext = cipher.doFinal(code.toByteArray(Charsets.UTF_8))
+        context.getSharedPreferences(PREFS_RECOVERY_NAME, Context.MODE_PRIVATE).edit()
+            .putString(PREFS_RECOVERY_CIPHERTEXT, Base64.encodeToString(ciphertext, Base64.NO_WRAP))
+            .putString(PREFS_RECOVERY_IV, Base64.encodeToString(cipher.iv, Base64.NO_WRAP))
+            .apply()
+    }
+
+    /** 删恢复码（认领成功后清理本地绑定等场景）。 */
+    fun deleteRecoveryCode(context: Context) {
+        context.getSharedPreferences(PREFS_RECOVERY_NAME, Context.MODE_PRIVATE).edit().clear().apply()
+    }
+
     private fun loadOrCreateKey(): SecretKey {
         val store = KeyStore.getInstance(KEYSTORE).apply { load(null) }
         (store.getKey(KEY_ALIAS, null) as? SecretKey)?.let { return it }