@adep/cli 0.1.17 → 0.2.0

package/templates/app-mobile/bridge/gate.mjs

@@ -0,0 +1,88 @@
+/**
+ * 权限门控核心（APP-009，PRD §2.11.5「原生能力与权限」）。
+ *
+ * 「未声明即不可用，且不得在运行时申请」的门控**做在原生侧**（ADR-0007 配套硬约束 3）：
+ * iOS Swift / Android Kotlin 的原生桥持有一份「已声明权限」清单，任何原生能力调用先过门控。
+ *
+ * 本文件是这条判定的 **host-side harness 镜像**（PRD §2.11.6 前言：可判定部分全部打在
+ * 引擎无关的 host-side harness 上，CI 用同一份设备端代码跑判定；真机只冒烟）。CI 没有
+ * iOS / Android 工具链，无法编译原生侧，因此用本文件在同一输入面上跑「未声明 → 拒绝 +
+ * 审计日志」的验收判据。
+ *
+ * ⚠️ **双实现漂移防线**（AGENTS §9：同一算法两端各存一份拷贝必须点名分叉并双向对账）：
+ * 原生桥与这里各自实现**同一规则**——`permissions` 白名单的 contains 判定 + 审计记录。
+ * 规则刻意极简（没有第二种判定形态），两侧共用同一份清单契约
+ * （`adep.permissions.json`，CLI build 时从服务端打包配置写入 `app/site/`）与同一错误码
+ * `PERMISSION_DENIED`。模板单测钉住「原生侧源码引用同一文件契约与同一错误码」，
+ * 防止一侧改规则另一侧不同步（漂移方向 = 实际放行面比声明面大）。
+ *
+ * 本文件**不**触碰系统权限 API（那是原生侧的事）：已声明但系统未授权由原生侧返回
+ * 系统状态码；这里只做「声明面」判定与审计。设备端函数（离线运行时）经原生桥调用
+ * 原生能力时，两侧门控按同一规则先后拦截。
+ *
+ * 注意：本文件是随壳工程分发的 **.mjs**（设备端 / host-side 都直接跑），不写 TypeScript
+ * 语法；类型以 JSDoc 表达。
+ */
+
+/** 未声明权限的机器码（原生侧与 JS 侧共用的契约常量）。 */
+export const PERMISSION_DENIED = 'PERMISSION_DENIED'
+
+/**
+ * 声明面判定：`capability` 是否在权限清单中。
+ *
+ * @param {readonly string[]} permissions 已声明权限清单（adep.permissions.json 的 permissions 数组）
+ * @param {string} capability 原生能力名（如 geolocation / camera / filesystem.read）
+ * @returns {boolean}
+ */
+export function isPermissionDeclared(permissions, capability) {
+  return Array.isArray(permissions) && permissions.includes(capability)
+}
+
+/**
+ * 内存审计 sink（host-side harness 用；每次调用追加一条）。
+ * 审计条目：`{ ts, capability, result, reason }`——拒绝原因固定为 `not_declared`（未声明），
+ * 该次尝试无论成功与否都留痕（审计不是「拒绝才记」，是「尝试即记」）。
+ *
+ * @returns {object} `{ sink, entries }`——sink.log(entry) 追加审计；entries 为已记条目数组。
+ *   entry 形状：`{ ts, capability, result, reason }`，result 为 'granted' | 'denied'，
+ *   reason 为 'not_declared' | 'ok'。
+ */
+export function createMemoryAudit() {
+  const entries = []
+  return {
+    sink: {
+      log(entry) {
+        entries.push(entry)
+      },
+    },
+    entries,
+  }
+}
+
+/**
+ * 权限门控（由权限清单 + 审计 sink 装配；CLI 构建期生成清单，运行时装配门控）。
+ *
+ * @param {object} input 门控装配输入——`permissions`（readonly string[]：已声明权限清单）、
+ *   `audit`（含 `log(entry)` 方法的审计 sink）。
+ * @returns {object} `{ check(capability) }`——check 返回 `{ ok: true }` 或
+ *   `{ ok: false, code: 'PERMISSION_DENIED', message }`。
+ */
+export function createPermissionGate(input) {
+  return {
+    check(capability) {
+      const declared = isPermissionDeclared(input.permissions, capability)
+      input.audit.log({
+        ts: new Date().toISOString(),
+        capability,
+        result: declared ? 'granted' : 'denied',
+        reason: declared ? 'ok' : 'not_declared',
+      })
+      if (declared) return { ok: true }
+      return {
+        ok: false,
+        code: PERMISSION_DENIED,
+        message: `原生能力 "${capability}" 未在应用 manifest 的 permissions 中声明（未声明即不可用，且不会在运行时申请）`,
+      }
+    },
+  }
+}

package/templates/app-mobile/capacitor.config.ts

@@ -0,0 +1,23 @@
+import type { CapacitorConfig } from '@capacitor/cli'
+
+/**
+ * Capacitor 配置（APP-009 移动壳模板）。
+ *
+ * - `appId`：iOS bundle identifier（`{{iosBundleId}}`）。Android 的 applicationId 在
+ *   `npx cap add android` 生成工程后按 `{{androidPackageId}}` 修改（applicationId 不允许连字符，
+ *   iOS bundle id 不允许下划线——两端无法共用一个 id，见 README）。
+ * - `webDir`：CLI `adep app build` 注入的已发布前端产物（`app/site/`，与桌面壳同位置）。
+ *   `adep.permissions.json`（原生侧权限门控清单）由 CLI 构建时写入 `app/site/` 下，随
+ *   `npx cap sync` 同步进两端原生资源（Android `assets/public/` / iOS `Public/`）。
+ * - `server`：加载本地静态产物（不连 dev server）；在线运行时下云函数经 `platformUrl` 服务端执行。
+ */
+const config: CapacitorConfig = {
+  appId: '{{iosBundleId}}',
+  appName: '{{appName}}',
+  webDir: 'app/site',
+  server: {
+    androidScheme: 'https',
+  },
+}
+
+export default config

package/templates/app-mobile/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{projectSlug}}-mobile-app",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{appName}} —— AgentDeploy 移动应用（Capacitor 壳，在线运行时）",
+  "scripts": {
+    "cap:sync": "cap sync",
+    "cap:add:ios": "cap add ios",
+    "cap:add:android": "cap add android",
+    "build:ios": "adep app build --platform ios --dir .",
+    "build:android": "adep app build --platform android --dir .",
+    "open:ios": "cap open ios",
+    "open:android": "cap open android"
+  },
+  "dependencies": {
+    "@adep/bridge": "file:plugins/adep-bridge",
+    "@capacitor/core": "^7.0.0"
+  },
+  "devDependencies": {
+    "@capacitor/cli": "^7.0.0",
+    "@capacitor/ios": "^7.0.0",
+    "@capacitor/android": "^7.0.0"
+  }
+}

package/templates/app-mobile/plugins/adep-bridge/android/build.gradle

@@ -0,0 +1,22 @@
+apply plugin: 'com.android.library'
+
+android {
+    namespace "com.adep.bridge"
+    compileSdk 34
+    defaultConfig {
+        minSdk 22
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation 'com.getcapacitor:android:7.0.0'
+}

package/templates/app-mobile/plugins/adep-bridge/android/src/main/AndroidManifest.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  AdepBridge 插件（library 模块）**不声明任何系统权限**（uses-permission 留空）。
+  门控语义（PRD §2.11.5）：未在应用 manifest 的 permissions 声明的能力即不可用，
+  且不得在运行时申请——插件本体不主动索取任何系统权限；应用声明了哪些权限，
+  由壳工程在 cap add 生成的应用级 AndroidManifest.xml 里配相应 uses-permission
+  （README 有映射指引）。
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

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

@@ -0,0 +1,86 @@
+package com.adep.bridge
+
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+
+/**
+ * AgentDeploy 移动壳原生桥（APP-009，Android 侧）。
+ *
+ * 与 iOS 侧 AdepBridge.swift 同形（§3.2.8 硬约束④），与 bridge/gate.mjs 的 host-side
+ * 镜像同规则：**门控做在原生侧**——页面侧 `window.__ADEP_APP__.invokeNative` 经 Capacitor
+ * 消息进到这里，先过 [AdepPermissionGate]，未在 `adep.permissions.json` 声明的能力直接
+ * 拒绝 `PERMISSION_DENIED` 并记审计，绝不在运行时申请。
+ *
+ * ownerKey 只存 Android Keystore（[AdepKeystore]），明文不落 JS 侧 / 明文文件（§2.11.5）。
+ */
+@CapacitorPlugin(name = "AdepBridge")
+class AdepBridge : Plugin() {
+    private var gate: AdepPermissionGate? = null
+
+    override fun load() {
+        gate = try {
+            AdepPermissionGate.load(context)
+        } catch (error: Exception) {
+            // fail-closed：清单缺失 = 门控无法建立 = 一切原生能力不可用。
+            // 与 iOS 侧同口径：「清单没读到」≠「清单为空」。
+            android.util.Log.e("adep-bridge", "权限清单加载失败", error)
+            null
+        }
+    }
+
+    /** 调用原生能力。门控先于一切实现：未声明 → 拒绝 + 审计；已声明未实现 → NOT_IMPLEMENTED。 */
+    @PluginMethod
+    fun invokeNative(call: PluginCall) {
+        val capability = call.getString("capability")
+        if (capability.isNullOrEmpty()) {
+            call.resolve(jsObject("ok" to false, "code" to "INVALID_CAPABILITY", "message" to "capability 必须为非空字符串"))
+            return
+        }
+        val gate = gate ?: run {
+            call.resolve(jsObject("ok" to false, "code" to "GATE_UNAVAILABLE", "message" to "权限门控未建立（清单缺失）"))
+            return
+        }
+        when (gate.check(capability)) {
+            true -> call.resolve(
+                jsObject(
+                    "ok" to false,
+                    "code" to "NOT_IMPLEMENTED",
+                    "message" to "原生能力 \"$capability\" 已声明但本壳未实现"
+                )
+            )
+            false -> call.resolve(
+                jsObject(
+                    "ok" to false,
+                    "code" to AdepPermissionGate.PERMISSION_DENIED,
+                    "message" to "原生能力 \"$capability\" 未在应用 manifest 的 permissions 中声明（未声明即不可用，且不会在运行时申请）"
+                )
+            )
+        }
+    }
+
+    /** 读 ownerKey（Keystore）。无则返回 null（首启未签发）。 */
+    @PluginMethod
+    fun getOwnerKey(call: PluginCall) {
+        call.resolve(jsObject("value" to AdepKeystore.loadOwnerKey(context)))
+    }
+
+    /** 写 ownerKey（Keystore）。安装首启时由壳原生侧调用服务端签发端点后存入。 */
+    @PluginMethod
+    fun setOwnerKey(call: PluginCall) {
+        val key = call.getString("key")
+        if (key.isNullOrEmpty()) {
+            call.reject("key 必须为非空字符串")
+            return
+        }
+        AdepKeystore.saveOwnerKey(context, key)
+        call.resolve()
+    }
+
+    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
+    }
+}

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

@@ -0,0 +1,81 @@
+package com.adep.bridge
+
+import android.content.Context
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * ownerKey 的 Keystore 加密存储（Android，APP-009）。
+ *
+ * PRD §2.11.5「设备身份与恢复」：ownerKey 移动端**只存 Keychain / Keystore**——不落
+ * 明文 SharedPreferences / 文件（客户端产物等同公开，明文落盘等于把设备身份交给解包者）。
+ *
+ * 实现：Android Keystore 系统生成/持有 AES 密钥（不可导出），ownerKey 用 AES/GCM 加密后
+ * 存 SharedPreferences 密文。密钥本身留在 Keystore（硬件/系统隔离），应用进程只能用它
+ * 加解密、拿不到密钥材料。
+ */
+object AdepKeystore {
+    private const val KEYSTORE = "AndroidKeyStore"
+    private const val KEY_ALIAS = "adep_owner_key"
+    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 GCM_TAG_BITS = 128
+
+    /** 读 ownerKey；无则返回 null（首启未签发）。 */
+    fun loadOwnerKey(context: Context): String? {
+        val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        val ciphertext = prefs.getString(PREFS_CIPHERTEXT, null) ?: return null
+        val iv = prefs.getString(PREFS_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", "ownerKey 解密失败", error)
+            null
+        }
+    }
+
+    /** 写 ownerKey（覆盖旧值）。 */
+    fun saveOwnerKey(context: Context, key: String) {
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+        cipher.init(Cipher.ENCRYPT_MODE, loadOrCreateKey())
+        val ciphertext = cipher.doFinal(key.toByteArray(Charsets.UTF_8))
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit()
+            .putString(PREFS_CIPHERTEXT, Base64.encodeToString(ciphertext, Base64.NO_WRAP))
+            .putString(PREFS_IV, Base64.encodeToString(cipher.iv, Base64.NO_WRAP))
+            .apply()
+    }
+
+    /** 删 ownerKey（换装 / 恢复码认领时用）。 */
+    fun deleteOwnerKey(context: Context) {
+        context.getSharedPreferences(PREFS_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 }
+        val generator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE)
+        generator.init(
+            KeyGenParameterSpec.Builder(
+                KEY_ALIAS,
+                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT,
+            )
+                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                .build(),
+        )
+        return generator.generateKey()
+    }
+}

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

@@ -0,0 +1,81 @@
+package com.adep.bridge
+
+import android.content.Context
+import org.json.JSONObject
+import java.io.File
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+
+/**
+ * 原生侧权限门控（Android，APP-009）。
+ *
+ * 与 `bridge/gate.mjs`（host-side harness 镜像）**同规则**：`permissions` 白名单 contains
+ * 判定 + 审计记录。两侧独立实现、共用同一份清单契约（`adep.permissions.json`）与同一
+ * 错误码 `PERMISSION_DENIED`。规则刻意极简（没有第二种判定形态），漂移面最小；
+ * 模板单测钉住「Kotlin 源码引用同一清单文件名与错误码」。
+ */
+class AdepPermissionGate private constructor(
+    private val permissions: Set<String>,
+    private val audit: AdepAuditLog,
+) {
+    companion object {
+        /** 与 bridge/gate.mjs 共用的契约常量。 */
+        const val PERMISSION_DENIED = "PERMISSION_DENIED"
+        /** 与 CLI 写入文件名一致的契约常量（app/site/adep.permissions.json → cap sync → assets/public/）。 */
+        const val MANIFEST_FILE_NAME = "adep.permissions.json"
+
+        /**
+         * 工厂：从 assets 读权限清单装配门控。
+         * 清单缺失 / 非 JSON → throw（调用方 fail-closed：门控建立不了 = 一切原生能力不可用）。
+         */
+        fun load(context: Context): AdepPermissionGate {
+            val raw: String = try {
+                context.assets.open("public/$MANIFEST_FILE_NAME").bufferedReader().use { it.readText() }
+            } catch (error: Exception) {
+                throw IllegalStateException(
+                    "assets 缺少 public/$MANIFEST_FILE_NAME（CLI build 写入、cap sync 同步）",
+                    error,
+                )
+            }
+            val permissions: Set<String> = try {
+                JSONObject(raw).optJSONArray("permissions")?.let { array ->
+                    buildSet {
+                        for (i in 0 until array.length()) {
+                            array.optString(i).takeIf { it.isNotEmpty() }?.let { add(it) }
+                        }
+                    }
+                } ?: emptySet()
+            } catch (error: Exception) {
+                throw IllegalStateException("adep.permissions.json 不是合法 JSON", error)
+            }
+            return AdepPermissionGate(permissions, AdepAuditLog(context))
+        }
+    }
+
+    /** 声明面判定 + 审计（尝试即记，无论放行还是拒绝）。返回是否已声明。 */
+    fun check(capability: String): Boolean {
+        val declared = permissions.contains(capability)
+        audit.log(
+            ts = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ", Locale.US).format(Date()),
+            capability = capability,
+            result = if (declared) "granted" else "denied",
+            reason = if (declared) "ok" else "not_declared",
+        )
+        return declared
+    }
+}
+
+/** 设备侧审计日志（Android）：filesDir/adep-audit.log 追加一行，与 gate.mjs 的 AuditEntry 同形。 */
+class AdepAuditLog(private val context: Context) {
+    private val file: File = File(context.filesDir, "adep-audit.log")
+
+    fun log(ts: String, capability: String, result: String, reason: String) {
+        val line = "{\"ts\":\"$ts\",\"capability\":\"$capability\",\"result\":\"$result\",\"reason\":\"$reason\"}\n"
+        try {
+            file.appendText(line)
+        } catch (_: Exception) {
+            // 审计写失败不阻断门控判定（设备侧日志尽力而为，不因日志拖垮能力调用）。
+        }
+    }
+}

package/templates/app-mobile/plugins/adep-bridge/capacitor.plugin.json

@@ -0,0 +1,10 @@
+{
+  "ios": {
+    "src": "ios",
+    "dest": "ios"
+  },
+  "android": {
+    "src": "android",
+    "dest": "android"
+  }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * @adep/bridge —— AgentDeploy 移动壳原生桥的 JS 面（Capacitor 插件注册）。
+ *
+ * 页面侧经 `window.__ADEP_APP__.invokeNative(capability, args)` 进入（web/adep-bridge.js），
+ * 本模块把它转发给原生实现（AdepBridge.swift / AdepBridge.kt）。门控做在原生侧：
+ * 未在 `adep.permissions.json` 声明的能力 → 原生侧直接拒绝 `PERMISSION_DENIED` 并记审计，
+ * JS 面不持有任何放行决策（客户端产物等同公开，决策放 JS 侧等于没有门）。
+ *
+ * Web（非壳环境）fallback：非原生环境一律拒绝（fail-closed，与门控方向一致）。
+ */
+import { registerPlugin } from '@capacitor/core'
+
+const AdepBridge = registerPlugin('AdepBridge', {
+  /**
+   * 调用原生能力。返回 `{ ok: true, value }` 或 `{ ok: false, code, message }`；
+   * 未声明权限 → `code: 'PERMISSION_DENIED'`（与 bridge/gate.mjs 同一契约常量）。
+   */
+  invokeNative: (options) => {
+    const capability = options && options.capability
+    if (typeof capability !== 'string' || capability === '') {
+      return Promise.resolve({
+        ok: false,
+        code: 'INVALID_CAPABILITY',
+        message: 'capability 必须为非空字符串',
+      })
+    }
+    // Web fallback（浏览器预览 / 非壳环境）：原生能力一律不可用，不做任何模拟。
+    return Promise.resolve({
+      ok: false,
+      code: 'NATIVE_UNAVAILABLE',
+      message: `原生能力 "${capability}" 在 Web 环境不可用（移动壳原生侧才提供）`,
+    })
+  },
+  // ownerKey 只存 Keychain / Keystore（PRD §2.11.5「设备身份与恢复」）；JS 面只提供
+  // 存取接口，明文不过 JS 侧持久化。安装首启时由壳原生侧调用服务端签发端点换取。
+  getOwnerKey: () =>
+    Promise.resolve({
+      value: null,
+      reason: 'NATIVE_UNAVAILABLE',
+    }),
+})
+
+export { AdepBridge }
+export default AdepBridge

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

@@ -0,0 +1,14 @@
+Pod::Spec.new do |s|
+  s.name = 'AdepBridge'
+  s.version = '0.1.0'
+  s.summary = 'AgentDeploy mobile shell native bridge (APP-009)'
+  s.description = 'Native-side permission gate + ownerKey Keychain storage + native capability invoke routing'
+  s.homepage = 'https://adep.jajabjbj.top'
+  s.license = 'MIT'
+  s.author = 'AgentDeploy'
+  s.source = { :git => 'https://adep.jajabjbj.top/adep-bridge.git', :tag => s.version.to_s }
+  s.ios.deployment_target = '13.0'
+  s.source_files = 'Sources/**/*.swift'
+  s.swift_version = '5.1'
+  s.dependency 'Capacitor'
+end

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

@@ -0,0 +1,69 @@
+import Capacitor
+
+/// AgentDeploy 移动壳原生桥（APP-009，iOS 侧）。
+///
+/// 职责（与 bridge/gate.mjs 的 host-side 镜像同规则；Android 侧 AdepBridge.kt 同形）：
+/// 1. 原生能力 invoke 路由：页面侧 `window.__ADEP_APP__.invokeNative(capability, args)`
+///    经 Capacitor 消息进到这里；**门控做在原生侧**——先过 `AdepPermissionGate`，
+///    未在 `adep.permissions.json` 声明的能力直接拒绝 `PERMISSION_DENIED` 并记审计，
+///    绝不在运行时申请（PRD §2.11.5）。
+/// 2. ownerKey 只存 Keychain（`AdepKeychain`），明文不落 JS 侧 / 沙盒文件（§2.11.5
+///    「设备身份与恢复」）。
+///
+/// 权限清单来源：CLI `adep app build` 把 `adep.permissions.json` 写入 `app/site/`；
+/// `npx cap sync` 把它同步进 iOS 工程的 `Public/`（folder reference），运行时经
+/// `Bundle.main` 读取。
+@objc(AdepBridge)
+public class AdepBridge: CAPPlugin {
+    private var gate: AdepPermissionGate?
+
+    public override func load() {
+        super.load()
+        do {
+            gate = try AdepPermissionGate.load(from: Bundle.main)
+        } catch {
+            // fail loud：清单缺失 = 门控无法建立 = 一切原生能力不可用（fail-closed）。
+            // 不静默放行——「清单没读到」与「清单为空」的后果必须不同（后者=未声明即不可用）。
+            gate = nil
+            CAPLog.print("[adep-bridge] 权限清单加载失败：\(error)")
+        }
+    }
+
+    /// 调用原生能力。门控先于一切实现：未声明 → 拒绝 + 审计；已声明 → 按能力分发。
+    /// 本模板交付「门控 + 桥框架」：实际能力实现（定位 / 相机等）由应用侧按能力名
+    /// 扩展，未实现的能力返回 `NOT_IMPLEMENTED`（不静默返回成功）。
+    @objc func invokeNative(_ call: CAPPluginCall) {
+        guard let capability = call.getString("capability"), !capability.isEmpty else {
+            call.resolve(["ok": false, "code": "INVALID_CAPABILITY", "message": "capability 必须为非空字符串"])
+            return
+        }
+        guard let gate = gate else {
+            call.resolve(["ok": false, "code": "GATE_UNAVAILABLE", "message": "权限门控未建立（清单缺失）"])
+            return
+        }
+        switch gate.check(capability) {
+        case .granted:
+            // 能力分发点：后续按 capability 接真实现（如 `geolocation` → CoreLocation）。
+            // 本模板不含任何真实原生能力实现——未实现 = 明确报错，不是假装成功。
+            call.resolve(["ok": false, "code": "NOT_IMPLEMENTED", "message": "原生能力 \"\(capability)\" 已声明但本壳未实现"])
+        case .denied(let reason):
+            call.resolve(["ok": false, "code": AdepPermissionGate.permissionDenied, "message": reason])
+        }
+    }
+
+    /// 读 ownerKey（Keychain）。无则返回 null（首启未签发）。
+    @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 必须为非空字符串")
+            return
+        }
+        AdepKeychain.saveOwnerKey(key)
+        call.resolve()
+    }
+}

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

@@ -0,0 +1,58 @@
+import Foundation
+import Security
+
+/// ownerKey 的 Keychain 存储（iOS，APP-009）。
+///
+/// PRD §2.11.5「设备身份与恢复」：ownerKey 移动端**只存 Keychain / Keystore**——
+/// 不落 UserDefaults / 沙盒文件 / JS 侧持久化（客户端产物等同公开，明文落盘等于
+/// 把设备身份直接交给解包者）。Keychain 由系统加密保护，应用卸载后条目随钥匙串
+/// 条目保留策略由系统管理（本实现用 kSecAttrAccessibleAfterFirstUnlock，设备
+/// 重启后首次解锁即可读，适合后台同步场景）。
+enum AdepKeychain {
+    private static let service = "adep.ownerKey"
+    private static let account = "default"
+
+    /// 读 ownerKey；无则返回 nil（首启未签发）。
+    static func loadOwnerKey() -> String? {
+        var query = baseQuery()
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        var item: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &item)
+        guard status == errSecSuccess, let data = item as? Data else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+
+    /// 写 ownerKey（已存在则覆盖）。
+    @discardableResult
+    static func saveOwnerKey(_ key: String) -> Bool {
+        deleteOwnerKey()
+        var query = baseQuery()
+        query[kSecValueData as String] = Data(key.utf8)
+        return SecItemAdd(query as CFDictionary, nil) == errSecSuccess
+    }
+
+    /// 删 ownerKey（换装 / 恢复码认领时用）。
+    @discardableResult
+    static func deleteOwnerKey() -> Bool {
+        SecItemDelete(baseQuery() as CFDictionary) == errSecSuccess || errSecItemNotFoundCheck()
+    }
+
+    private static func baseQuery() -> [String: Any] {
+        return [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+            kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
+        ]
+    }
+
+    /// delete 在「无条目」时返回 errSecItemNotFound，等同成功（幂等删除）。
+    private static func errSecItemNotFoundCheck() -> Bool {
+        // 上一条删除若因条目不存在失败，这里重查一次确认「确实不存在」即可算成功。
+        var query = baseQuery()
+        query[kSecReturnData as String] = true
+        var item: CFTypeRef?
+        return SecItemCopyMatching(query as CFDictionary, &item) == errSecItemNotFound
+    }
+}