@adep/cli 0.4.4 → 0.4.6

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

@@ -0,0 +1,235 @@
+package com.adep.bridge
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * 设备本地 SQLite 桥的**纯逻辑层**（Android，APP-023；PRD §2.11.3「设备本地 SQLite」行）。
+ *
+ * 与 iOS 侧 `AdepSqlite.swift` + `AdepBridge.swift` 的决策逻辑**逐字同源**（错误码 / 参数绑定
+ * 三态分流 / 类型映射 / 多语句拒绝 / 占位符计数 / 成功信封），但不依赖
+ * `android.database.sqlite.*`（framework）——本文件只 import 标准 `org.json`（纯 JVM 独立 JAR，
+ * Android 平台也内置同名包），因此 **kotlinc 行为级门可真编译真跑**（`app-android-sqlite.test.ts`，
+ * 等价 iOS 的 swiftc 同模块手法）。执行层 {@link AdepSqlite}（`android.database.sqlite.SQLiteDatabase`）
+ * 消费本文件的判定；framework 类型进不去行为级门，但**所有会漂移的决策都在这里、都能真跑钉住**。
+ *
+ * ## 与 iOS 的契约锚（跨实现一致性——错误码/形状/信封是锚，不可分叉）
+ *
+ * - 错误码：`SQLITE_OPEN_FAILED` / `SQLITE_MULTIPLE_STATEMENTS` / `SQLITE_PREPARE_FAILED` /
+ *   `SQLITE_EXEC_FAILED` / `SQLITE_BIND_FAILED` / `SQLITE_COLUMN_FAILED` / `SQLITE_INVALID_PARAM`，
+ *   与 iOS `AdepSqlite.Code.*`、JS 面 `offline-runtime.js` 的 catch 分支逐字一致；
+ * - 能力名：`sqlite.run` / `sqlite.all` / `sqlite.get`，与 `adep.permissions.json` 声明、
+ *   iOS `withSqlite(capability:)`、`@adep/runtime` `DeviceSqliteBridge` 三向一致；
+ * - 信封：成功带 `{ ok: true, <业务键> }`，失败带 `{ ok: false, code, message }`，与 iOS
+ *   逐字一致（页面侧运行时按 `envelope.ok !== true` 放行）。
+ */
+object SqliteCode {
+    const val OPEN_FAILED = "SQLITE_OPEN_FAILED"
+    const val MULTIPLE_STATEMENTS = "SQLITE_MULTIPLE_STATEMENTS"
+    const val PREPARE_FAILED = "SQLITE_PREPARE_FAILED"
+    const val EXEC_FAILED = "SQLITE_EXEC_FAILED"
+    const val BIND_FAILED = "SQLITE_BIND_FAILED"
+    const val COLUMN_FAILED = "SQLITE_COLUMN_FAILED"
+    const val INVALID_PARAM = "SQLITE_INVALID_PARAM"
+}
+
+/** 一条可读的 SQLite 执行错误（code + message；message 前缀是 JS 侧 catch 的锚，与 iOS 同形）。 */
+class SqliteBridgeError(val code: String, override val message: String) : Exception(message)
+
+/**
+ * 参数绑定值分流（三态，2026-10-22 iOS 真机第五轮实证——混并会导致 CAPPluginCall 悬空、
+ * JS promise 永不落定、页面装配**静默卡死**，比报错毒）。Capacitor 的 JS 值落地 JSON：
+ * String / 数值 / Boolean / `JSONObject.NULL`：
+ * - 键缺席 / null → `[]`（无绑定参数，合法——DDL / 无参 DML 走这）；
+ * - 数组内元素非法（对象 / 嵌套数组）→ 抛 `SqliteBridgeError(INVALID_PARAM, 点名下标)`；
+ * - 合法元素 → 逐个映射，null 用 `JSONObject.NULL` 表示（执行层直接落 NULL）。
+ *
+ * @param raw 页面侧 `params` 的 JSON 数组；可为空（无参）。
+ * @return 绑定值列表，与 SQL 占位符一一对应（顺序即占位符顺序）。
+ */
+fun sqliteBindParams(raw: JSONArray?): List<Any> {
+    if (raw == null) return emptyList()
+    val list = ArrayList<Any>(raw.length())
+    for (i in 0 until raw.length()) {
+        val item = raw.opt(i)
+        when {
+            item == null || item === JSONObject.NULL -> list.add(JSONObject.NULL)
+            item is String -> list.add(item)
+            item is Number -> list.add(item)
+            item is Boolean -> list.add(item)
+            else -> throw SqliteBridgeError(
+                SqliteCode.INVALID_PARAM,
+                "params[$i] 类型不支持（支持 string / number / boolean / null）",
+            )
+        }
+    }
+    return list
+}
+
+/**
+ * SQL 文本的**多语句判定**：统计「有效语句数」。iOS 侧是 `sqlite3_prepare_v2` 的 pzTail 判定
+ * （尾随非空即拒）；Android 侧 `SQLiteDatabase` 的 `execSQL` 也只执行第一条并**静默丢弃尾随**
+ * （同族静默陷阱）⇒ 在 Android 侧**先把多语句掐掉**，语义与 iOS 一致：引号内（`'...'`/`"..."`）
+ * 与注释内（`--` / `/* */`）的分号**不是**语句边界，末尾分号是终结符（不增段），纯注释/空白
+ * 文本 → 0。
+ *
+ * 口径：**分号分隔的「非空段」数**。末尾分号之后若只剩空白/注释，则它是终结符不产生新段。
+ *
+ * @return 有效语句数；空文本（全注释/空白）返回 0，单语句（含末分号 / 无分号）返回 1，多条 → >1。
+ */
+fun countSqlStatements(sql: String): Int {
+    var count = 0
+    var i = 0
+    var inSingle = false
+    var inDouble = false
+    var inLineComment = false
+    var inBlockComment = false
+    var inStatement = false // 当前是否在一条「有实质内容」的语句内（剥注释/空白）
+    val n = sql.length
+    while (i < n) {
+        val c = sql[i]
+        val next = if (i + 1 < n) sql[i + 1] else '\u0000'
+        if (inSingle) {
+            if (c == '\'') inSingle = false
+            inStatement = true
+            i++
+            continue
+        }
+        if (inDouble) {
+            if (c == '"') inDouble = false
+            inStatement = true
+            i++
+            continue
+        }
+        if (inLineComment) {
+            if (c == '\n') {
+                inLineComment = false
+                // 换行不算语句内容（剥），但也不终结语句。
+            }
+            i++
+            continue
+        }
+        if (inBlockComment) {
+            if (c == '*' && next == '/') {
+                inBlockComment = false
+                i++ // 跳过 `*`（当前 i 指向 *）；分支末尾的 i++ 会再跳过 `/`，使 / 不残留
+            }
+            i++
+            continue
+        }
+        when {
+            c == '\'' -> { inSingle = true; inStatement = true; i++ }
+            c == '"' -> { inDouble = true; inStatement = true; i++ }
+            c == '-' && next == '-' -> { inLineComment = true; i++ }
+            c == '/' && next == '*' -> { inBlockComment = true; i++ }
+            c == ';' -> {
+                if (inStatement) { count++ ; inStatement = false }
+                i++
+            }
+            c.isWhitespace() -> i++
+            else -> { inStatement = true; i++ }
+        }
+    }
+    if (inStatement) count++
+    return count
+}
+
+/**
+ * 占位符计数判定：JS 侧绑定值数必须**恰好等于** SQL 占位符数。
+ * ⚠️ SQLite 对「多了」静默忽略（SQLITE_RANGE），对「少了」把缺的占位符按 NULL 执行——
+ * 两者都不报错，积的是「不报错只恒不命中」的静默陷阱（iOS 行为探针 case12 实证：INSERT
+ * 两列只给一列 ⇒ 行照插、另一列 NULL）。两侧都 fail loud。
+ *
+ * @return 独立占位符个数（`?` / `?N` / `:name` 各算一个；同名命名占位符算一个）。
+ */
+fun countPlaceholders(sql: String): Int {
+    var count = 0
+    var i = 0
+    var inSingle = false
+    var inDouble = false
+    var inLineComment = false
+    var inBlockComment = false
+    val named = HashSet<String>()
+    val n = sql.length
+    while (i < n) {
+        val c = sql[i]
+        val next = if (i + 1 < n) sql[i + 1] else '\u0000'
+        if (inSingle) {
+            if (c == '\'') inSingle = false
+            i++
+            continue
+        }
+        if (inDouble) {
+            if (c == '"') inDouble = false
+            i++
+            continue
+        }
+        if (inLineComment) {
+            if (c == '\n') inLineComment = false
+            i++
+            continue
+        }
+        if (inBlockComment) {
+            if (c == '*' && next == '/') inBlockComment = false
+            i++
+            continue
+        }
+        when {
+            c == '-' && next == '-' -> { inLineComment = true; i++ }
+            c == '/' && next == '*' -> { inBlockComment = true; i++ }
+            c == '\'' -> inSingle = true
+            c == '"' -> inDouble = true
+            c == '?' -> {
+                // `?` / `?NNN` 整体算一个匿名占位符。
+                while (i + 1 < n && sql[i + 1].isDigit()) i++
+                count++
+            }
+            c == ':' || c == '@' || c == '$' -> {
+                // `:name` / `@name` / `$name` 命名占位符：同名去重，不同名各算一个。
+                var j = i + 1
+                while (j < n && (sql[j].isLetterOrDigit() || sql[j] == '_')) j++
+                if (j > i + 1) {
+                    val name = sql.substring(i, j)
+                    if (named.add(name)) count++
+                    i = j - 1
+                } else {
+                    count++
+                }
+            }
+        }
+        i++
+    }
+    return count
+}
+
+/**
+ * 类型映射：SQLite 存储类型值 → JS 侧类型标签。
+ *
+ * Android `Cursor.getType(column)` 返回 `Cursor.FIELD_TYPE_*`（INTEGER 1 / FLOAT 2 / STRING 3 /
+ * BLOB 4 / NULL 0）。映射为标签供执行层把 `Cursor` 读成 `JSONObject` 时用。⚠️ 超 2^53 精度：
+ * 设备端 owned 表 id 是 snowflake 的场景 id 一律字符串（SHOP-007 纪律），JS 侧由调用方保证。
+ *
+ * @param fieldType `Cursor.getType()` 的原始值（0..4）。
+ * @return 标签；未知类型 → null（调用方 fail loud）。
+ */
+fun mapCursorFieldType(fieldType: Int): String? = when (fieldType) {
+    1 -> "integer"
+    2 -> "float"
+    3 -> "string"
+    4 -> "blob"
+    0 -> "null"
+    else -> null
+}
+
+/**
+ * 成功信封（带 `ok: true`）的组装——**唯一**组装点（与 iOS `sqliteSuccessEnvelope` 同契约）。
+ * ⚠️ 必须带 `ok: true`：页面侧运行时（offline-runtime.js）放行条件是 `envelope.ok !== true`
+ * 即抛；成功信封漏 ok ⇒ 真机 `INVOKE ERR [undefined]`（iOS 2026-10-22 实测）。失败信封在
+ * 调用方直接带 `ok:false`（见 {@link AdepBridge}），本函数只管成功面。
+ *
+ * @param data 业务键（run → changes / all → rows / get → row），不得含 `ok`（会覆盖为 true）。
+ */
+fun sqliteSuccessEnvelope(data: JSONObject): JSONObject {
+    data.put("ok", true)
+    return data
+}

package/templates/app-mobile/plugins/adep-bridge/dist/plugin.js

@@ -38,6 +38,36 @@ const AdepBridge = registerPlugin('AdepBridge', {
       value: null,
       reason: 'NATIVE_UNAVAILABLE',
     }),
+  // 读恢复码（APP-034）：页面用它呈现 / 导出认领凭据（服务端只存摘要、无法重发）。
+  // 只读——写凭据的通道仍在原生侧（页面拿不到，XSS 不能替换 ownerKey 劫持分区）。
+  getRecoveryCode: () =>
+    Promise.resolve({
+      value: null,
+      reason: 'NATIVE_UNAVAILABLE',
+    }),
+  // —— 设备本地 SQLite（APP-022 B 段）——
+  // 三个方法与 AdepBridge.swift 的 pluginMethods **逐字**对齐（adep-bridge-spm.test.ts
+  // 的集合相等门咬着：多写少写都静默）。Web fallback 一律 NATIVE_UNAVAILABLE（fail-closed，
+  // 与门控方向一致）；原生成功信封 { ok: true, changes } / { ok: true, rows } /
+  // { ok: true, row }——ok 语义与 invokeNative 一致（页面侧运行时按 envelope.ok 放行）。
+  sqliteRun: () =>
+    Promise.resolve({
+      ok: false,
+      code: 'NATIVE_UNAVAILABLE',
+      message: '设备本地 SQLite 在 Web 环境不可用（移动壳原生侧才提供）',
+    }),
+  sqliteAll: () =>
+    Promise.resolve({
+      ok: false,
+      code: 'NATIVE_UNAVAILABLE',
+      message: '设备本地 SQLite 在 Web 环境不可用（移动壳原生侧才提供）',
+    }),
+  sqliteGet: () =>
+    Promise.resolve({
+      ok: false,
+      code: 'NATIVE_UNAVAILABLE',
+      message: '设备本地 SQLite 在 Web 环境不可用（移动壳原生侧才提供）',
+    }),
 })
 
 export { AdepBridge }

package/templates/app-mobile/plugins/adep-bridge/ios/AdepBridge.podspec

@@ -14,4 +14,7 @@ Pod::Spec.new do |s|
   s.source_files = 'Sources/**/*.swift'
   s.swift_version = '5.1'
   s.dependency 'Capacitor'
+  # APP-025：SQLCipher 加密（与 SPM 形态的 SQLCipher.swift 4.19 同源同版语义；
+  # CocoaPods 官方 SQLCipher pod 是源码编译形态，版本号与 SQLCipher.swift release 对齐）。
+  s.dependency 'SQLCipher', '~> 4.19'
 end

package/templates/app-mobile/plugins/adep-bridge/ios/Sources/AdepBridge.swift

@@ -1,5 +1,44 @@
 import Capacitor
 
+/// sqlite 成功信封的**唯一组装点**（纯函数，Foundation-only ⇒ 行为级门可真跑——
+/// `adep-bridge-envelope.test.ts` 与 `AdepSqlite` 同手法编译本函数验证信封形状）。
+///
+/// ⚠️ **必须带 `ok: true`**：页面侧运行时（offline-runtime.js）的放行条件是
+/// `envelope.ok !== true` 即抛。2026-10-22 真机实测：成功信封漏 ok ⇒ 函数一跑就
+/// `INVOKE ERR [undefined]`（ok / code 双 undefined）。失败信封一直带 ok/code，
+/// 唯独成功信封漏了——跨层契约只有行为级真跑能钉住（静态断言看不见「缺键」）。
+func sqliteSuccessEnvelope(_ data: [String: Any]) -> [String: Any] {
+    var envelope = data
+    envelope["ok"] = true
+    return envelope
+}
+
+/// params 绑定错误（调用方按 SQLITE_INVALID_PARAM 回信封——与执行期 SQLITE_ERROR 分流）。
+struct SqliteParamError: Error {
+    let message: String
+}
+
+/// params 元素 → SQLite 绑定值（纯函数，Foundation-only ⇒ 行为级门可真跑，与
+/// `sqliteSuccessEnvelope` 同手法）。Capacitor 的 JS 值落地即 String / Double / Bool /
+/// NSNull；其他类型（对象 / 嵌套数组 / 函数）不在 SQLite 标量绑定面，静默转字符串会
+/// 造出「查不出为什么等于不上」的行 ⇒ 抛错（点名下标，不静默）。
+func sqliteBindParams(_ raw: [Any]) throws -> [Any] {
+    var list: [Any] = []
+    for (index, item) in raw.enumerated() {
+        switch item {
+        case let text as String: list.append(text)
+        case let number as Double: list.append(number)
+        case let flag as Bool: list.append(flag)
+        case is NSNull: list.append(NSNull())
+        default:
+            throw SqliteParamError(
+                message: "params[\(index)] 类型不支持（支持 string / number / boolean / null）"
+            )
+        }
+    }
+    return list
+}
+
 /// AgentDeploy 移动壳原生桥（APP-009，iOS 侧）。
 ///
 /// 职责（与 bridge/gate.mjs 的 host-side 镜像同规则；Android 侧 AdepBridge.kt 同形）：
@@ -12,11 +51,55 @@ import Capacitor
 ///
 /// 权限清单来源：CLI `adep app build` 把 `adep.permissions.json` 写入 `app/site/`；
 /// `npx cap sync` 把它同步进 iOS 工程的 `Public/`（folder reference），运行时经
-/// `Bundle.main` 读取。
+/// `Bundle.main` 读取（候选路径见 `AdepPermissionGate.manifestCandidateSubdirectories`）。
+///
+/// ## 为什么要 conform `CAPBridgedPlugin`（APP-018）
+///
+/// Capacitor 7 的注册路径对插件有**强制**一致性要求（`internal typealias CapacitorPlugin =
+/// CAPPlugin & CAPBridgedPlugin`）：
+/// - `loadPlugin(type:)` 里 `type.init() as? CapacitorPlugin` 失败 → **只打一行日志**、返回 nil；
+/// - `registerPluginInstance(_:)` 同样 `as? CapacitorPlugin`，失败 → 同样只打日志；
+/// - 而 `registerPluginType(_:)` 首行是 `if autoRegisterPlugins { return }`，`CAPBridgeViewController`
+///   构造 bridge 时没传该开关（默认 true）⇒ **类型注册是空操作**。
+///
+/// 三者都不是编译错误、也不是抛异常：症状是 JS 侧回落到 `dist/plugin.js` 的
+/// `NATIVE_UNAVAILABLE` 桩——「一切都不可用」，而不是「插件没注册」。所以一致性声明是硬要求，
+/// 且必须与 JS 面**逐字对齐**（`identifier` / `jsName` / `pluginMethods`，见 `adep-bridge-spm.test.ts`）。
 @objc(AdepBridge)
-public class AdepBridge: CAPPlugin {
+public class AdepBridge: CAPPlugin, CAPBridgedPlugin {
+    /// 原生侧插件标识；与 `jsName` 同值（Capacitor 用 `jsName` 做注册表的键）。
+    public let identifier = "AdepBridge"
+    /// JS 侧注册名：必须与 `dist/plugin.js` 的 `registerPlugin('AdepBridge', …)` 首个参数逐字相等，
+    /// 否则页面永远找不到原生实现（且不报错）。
+    public let jsName = "AdepBridge"
+
+    /// 暴露给 JS 的方法清单。
+    ///
+    /// ⚠️ 这份名单**只列 JS 面声明过的方法**（`dist/plugin.js` 的对象键），且必须与它**相等**：
+    /// 多列一个 = JS 面永远调不到的注册项；少列一个 = 页面静默回落 NATIVE_UNAVAILABLE 桩。
+    /// 写凭据的入口不在 JS 面（APP-027：ownerKey 由原生自举签发，页面只能读）。
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "invokeNative", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getOwnerKey", returnType: CAPPluginReturnPromise),
+        // APP-034：读恢复码（只读；写口仍在原生侧）。与 dist/plugin.js 对象键逐字对齐。
+        CAPPluginMethod(name: "getRecoveryCode", returnType: CAPPluginReturnPromise),
+        // APP-022 B 段：设备本地 SQLite（PRD §2.11.3）。三个方法与 dist/plugin.js 的
+        // 对象键**逐字**对齐（adep-bridge-spm.test.ts 的集合相等门咬着）；门控与
+        // invokeNative 同一条路：未在 adep.permissions.json 声明即 PERMISSION_DENIED。
+        CAPPluginMethod(name: "sqliteRun", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "sqliteAll", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "sqliteGet", returnType: CAPPluginReturnPromise),
+    ]
+
     private var gate: AdepPermissionGate?
 
+    /// 设备本地 SQLite（APP-022 B 段）。懒建：首次 sqlite 调用时初始化
+    /// （Application Support 目录在首启前可能尚未就绪；懒加载避免 load() 期做 IO）。
+    private var sqlite: AdepSqlite?
+
+    /// 安装身份自举（APP-027）。持有引用只为防提前释放（自举在后台队列上跑）。
+    private var identity: AdepIdentityBootstrap?
+
     public override func load() {
         super.load()
         do {
@@ -27,6 +110,47 @@ public class AdepBridge: CAPPlugin {
             gate = nil
             CAPLog.print("[adep-bridge] 权限清单加载失败：\(error)")
         }
+        // APP-025：库 key = Keychain 的 ownerKey（§2.11.5 设备身份与库加密同源——拿到
+        // 设备身份即拿到库钥匙；卸载重装后 Keychain 条目仍在，库仍可读）。静态钩子在
+        // AdepSqlite（被行为级门单文件编译，不拖 Security framework），这里只接线。
+        AdepSqlite.defaultKeyProvider = { AdepKeychain.loadOwnerKey() }
+        let database = AdepSqlite()
+        sqlite = database
+        startIdentityBootstrap(database: database)
+    }
+
+    /// 安装身份自举（APP-027）：首启向服务端签发端点换取 ownerKey，只存 Keychain
+    /// （APP-028：恢复码同批落库——服务端只存摘要，明文只在这次响应里存在）。
+    ///
+    /// 三条边界（与 `AdepIdentityBootstrap` 的注释同口径）：
+    /// 1. **后台队列**——`load()` 在 `viewDidLoad` 链上，同步网络会阻塞首屏；
+    /// 2. **失败不阻断**——断网 / 5xx / 响应形态不符只记带原因码的日志，下次启动重试；
+    /// 3. **幂等**——已有 ownerKey 不发请求（行为级门的分母断言：请求数 == 1）。
+    ///
+    /// ⚠️ **不做在 JS 面**：页面拿不到写凭据的通道（XSS 不能替换 ownerKey 劫持分区），
+    /// `dist/plugin.js` 的对象键集合与 `pluginMethods` 名单都不变。
+    private func startIdentityBootstrap(database: AdepSqlite) {
+        let bootstrap = AdepIdentityBootstrap(
+            environment: AdepIdentityBootstrap.Environment(
+                configData: { AdepShellConfig.data(named: AdepShellConfig.configFileName, in: Bundle.main) },
+                storedOwnerKey: { AdepKeychain.loadOwnerKey() },
+                persistOwnerKey: { AdepKeychain.saveOwnerKey($0) },
+                // APP-028：恢复码与 ownerKey 一起落 Keychain（服务端只存摘要，明文只此一次）。
+                // 读口在此的唯一用处是**写后读回校验**——写成功读不出等于码已丢。
+                storedRecoveryCode: { AdepKeychain.loadRecoveryCode() },
+                persistRecoveryCode: { AdepKeychain.saveRecoveryCode($0) },
+                transport: AdepURLSessionTransport(),
+                platform: "ios",
+                // NSLog 而非 CAPLog.print：SpringBoard 拉起的 app 没人接 stdout（见 DiagMessageHandler）。
+                log: { NSLog("[adep-identity] \($0)") },
+                // 库已有数据且此前用 fallbackKey 建的 ⇒ 这里换成正式 key（rekey 在 AdepSqlite 内收口）。
+                onIssued: { key in database.adoptKey(key) }
+            )
+        )
+        identity = bootstrap
+        DispatchQueue.global(qos: .utility).async {
+            bootstrap.start()
+        }
     }
 
     /// 调用原生能力。门控先于一切实现：未声明 → 拒绝 + 审计；已声明 → 按能力分发。
@@ -51,19 +175,107 @@ public class AdepBridge: CAPPlugin {
         }
     }
 
-    /// 读 ownerKey（Keychain）。无则返回 null（首启未签发）。
+    /// 读 ownerKey（Keychain）。首启尚未签发（或签发失败）时返回 null。
+    ///
+    /// ⚠️ **`setOwnerKey` 已删除**（APP-027）：它曾是「页面调不到、原生也没人调」的死方法——
+    /// 写凭据的入口现在只有 `AdepIdentityBootstrap`（首启自举）与 `AdepKeychain.saveOwnerKey`
+    /// （恢复码换键流程的前置），两者都在原生侧，页面永远拿不到写凭据的通道。
     @objc func getOwnerKey(_ call: CAPPluginCall) {
         let value = AdepKeychain.loadOwnerKey()
         call.resolve(["value": value ?? NSNull()])
     }
 
-    /// 写 ownerKey（Keychain）。安装首启时由壳原生侧调用服务端签发端点后存入。
-    @objc func setOwnerKey(_ call: CAPPluginCall) {
-        guard let key = call.getString("key"), !key.isEmpty else {
-            call.reject("key 必须为非空字符串")
+    /// 读恢复码（APP-034，Keychain `adep.recoveryCode`）。无则 null（未签发 / 读失败）。
+    ///
+    /// ⚠️ **只读**：恢复码的写口在 `AdepIdentityBootstrap`（首启自举），页面没有写凭据的
+    /// 通道。页面拿它做呈现 / 导出（认领凭据——服务端只存摘要、无法重发，丢了等于放弃
+    /// 认领）；一次性弹层的节奏由页面产品代码决定，壳只保证「读得到」。
+    @objc func getRecoveryCode(_ call: CAPPluginCall) {
+        let value = AdepKeychain.loadRecoveryCode()
+        call.resolve(["value": value ?? NSNull()])
+    }
+
+    // MARK: - 设备本地 SQLite（APP-022 B 段）
+
+    /// 把 CAPPluginCall 的 `params`（JS 数组）转成 AdepSqlite 的绑定面 `[Any]`。
+    ///
+    /// ⚠️ 三态必须分流（2026-10-22 真机第五轮实测：缺席与「数组内元素非法」共用 nil
+    /// 返回 ⇒ `withSqlite` 的 guard-else 以为「错误信封已 resolve」直接 return，而缺席
+    /// 路径什么都没 resolve ⇒ CAPPluginCall 悬空，JS 侧 promise 永不落定，页面装配
+    /// **静默卡死**——比报错毒得多，浮层连 ERR 行都没有）：
+    /// - 键缺席 / JS 传 null → 返回 `[]`（无绑定参数，合法——DDL/无参 DML 走这）；
+    /// - 数组内元素非法 → 抛 `SqliteParamError`（调用方回 SQLITE_INVALID_PARAM）；
+    /// - 合法元素 → 逐个映射。
+    private func convertParams(_ call: CAPPluginCall) throws -> [Any] {
+        guard let raw = call.getArray("params") else { return [] }
+        return try sqliteBindParams(raw)
+    }
+
+    /// sqlite 三方法的公共骨架：门控 → 取参 → 执行 → 信封返回。
+    /// 形状对齐 `DeviceSqliteBridge`（bridge.ts）：sql + params（可选数组）；
+    /// run → { changes }，all → { rows }，get → { row | null }。
+    private func withSqlite(
+        _ call: CAPPluginCall,
+        capability: String,
+        _ body: (AdepSqlite, String, [Any]) throws -> [String: Any]
+    ) {
+        guard let gate = gate else {
+            call.resolve(["ok": false, "code": "GATE_UNAVAILABLE", "message": "权限门控未建立（清单缺失）"])
+            return
+        }
+        guard case .granted = gate.check(capability) else {
+            // 门控拒绝的 reason 已进审计；这里只做信封。code 用 PERMISSION_DENIED（契约常量）。
+            call.resolve([
+                "ok": false, "code": AdepPermissionGate.permissionDenied,
+                "message": "原生能力 \(capability) 未在应用 manifest 的 permissions 中声明",
+            ])
             return
         }
-        AdepKeychain.saveOwnerKey(key)
-        call.resolve()
+        guard let sql = call.getString("sql"), !sql.isEmpty else {
+            call.resolve(["ok": false, "code": "SQLITE_INVALID_PARAM", "message": "sql 必须为非空字符串"])
+            return
+        }
+        guard let sqlite = sqlite else {
+            call.resolve(["ok": false, "code": "SQLITE_OPEN_FAILED", "message": "SQLite 未初始化"])
+            return
+        }
+        do {
+            // params 缺席 → []（合法无参），元素非法 → 抛错回 SQLITE_INVALID_PARAM——
+            // 三态分流见 convertParams 注释；每条路径都恰好 resolve 一次。
+            let bindParams = try convertParams(call)
+            let data = try body(sqlite, sql, bindParams)
+            // 成功信封统一经唯一组装点（ok: true 契约的注释与门见函数声明处）。
+            call.resolve(sqliteSuccessEnvelope(data))
+        } catch let error as SqliteParamError {
+            call.resolve(["ok": false, "code": "SQLITE_INVALID_PARAM", "message": error.message])
+        } catch {
+            // fail loud（AdepSqlite 的错误 message 已带 code 前缀与 sql 片段）；
+            // resolve 而非 reject：JS 侧统一按 { ok, code, message } 信封分支。
+            call.resolve(["ok": false, "code": "SQLITE_ERROR", "message": error.localizedDescription])
+        }
+    }
+
+    /// 执行写语句（DDL / DML）。JS 面：`AdepBridge.sqliteRun({ sql, params? })` → `{ changes }`。
+    @objc func sqliteRun(_ call: CAPPluginCall) {
+        withSqlite(call, capability: "sqlite.run") { sqlite, sql, params in
+            let changes = try sqlite.run(sql, params: params.isEmpty ? nil : params)
+            return ["changes": changes]
+        }
+    }
+
+    /// 执行查询返回多行。JS 面：`AdepBridge.sqliteAll({ sql, params? })` → `{ rows }`。
+    @objc func sqliteAll(_ call: CAPPluginCall) {
+        withSqlite(call, capability: "sqlite.all") { sqlite, sql, params in
+            let rows = try sqlite.all(sql, params: params.isEmpty ? nil : params)
+            return ["rows": rows]
+        }
+    }
+
+    /// 执行单行查询。JS 面：`AdepBridge.sqliteGet({ sql, params? })` → `{ row | null }`。
+    @objc func sqliteGet(_ call: CAPPluginCall) {
+        withSqlite(call, capability: "sqlite.get") { sqlite, sql, params in
+            let row = try sqlite.get(sql, params: params.isEmpty ? nil : params)
+            return ["row": row ?? NSNull()]
+        }
     }
 }