@adep/cli 0.4.4 → 0.4.6

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

@@ -0,0 +1,500 @@
+import Foundation
+
+/// 安装身份自举（iOS，APP-027；PRD §2.11.5「设备身份与恢复」/ ADR-0008 第 2 条）。
+///
+/// ## 这一层解决什么问题
+///
+/// ownerKey 必须由**服务端**签发（本地自造 / 构建期预置都判违规）。服务端侧
+/// `POST /api/v1/projects/:projectId/app-installations` 早已交付（APP-007），但客户端
+/// **从未有过调用方**——于是 `getOwnerKey` 恒返回 null、单主同步（`Bearer <ownerKey>`）
+/// 在真机上不可用、SQLCipher 库 key 恒落硬编码缺省（key 就在二进制里）。
+///
+/// 症状是「401 / 空分区 / 换了设备还是同一把库钥匙」，全部不像「功能没实现」——
+/// 属于本仓最忌讳的静默塌陷。本文件把「首启签发」这一步补上。
+///
+/// ## 三个刻意的边界
+///
+/// 1. **不做在 JS 面**：`dist/plugin.js` 的对象键集合不变（页面拿不到写凭据的通道——
+///    XSS 不能替换 ownerKey 劫持数据分区）。自举只发生在原生侧。
+/// 2. **失败不改变可用性**：断网 / 5xx / 响应形态不符 ⇒ 不写空值、不覆盖既有值、
+///    只留带**原因码**的日志，下次启动重试。首启失败不得阻止 app 启动（ownerKey 只影响
+///    同步与库 key，不影响页面加载）。
+/// 3. **幂等**：已有合法 ownerKey ⇒ 不请求（一枚安装只签发一次；分母断言见行为级门）。
+///
+/// ## 纯逻辑与传输分离（为什么拆这么细）
+///
+/// 判定（config 解析 / URL 组装 / ownerKey 形态 / 响应解析）与传输（`URLSession`）拆开，
+/// 判定层是 Foundation-only 的纯函数 ⇒ `adep-identity.test.ts` 能把**被测源码原样**编进
+/// 探针真跑（不做镜像实现）。响应解析一旦放宽，「写进去的不是 ownerKey」这种错会一直潜伏到
+/// 同步 401 才暴露。
+public struct AdepIdentityConfig: Equatable {
+    public let platformUrl: String
+    public let projectSlug: String
+
+    public init(platformUrl: String, projectSlug: String) {
+        self.platformUrl = platformUrl
+        self.projectSlug = projectSlug
+    }
+}
+
+/// 签发响应里客户端真正需要的东西（服务端还回 `partition`，它是 `sha256(ownerKey)`，客户端不用）。
+public struct AdepIdentityIssue: Equatable {
+    public let ownerKey: String
+    public let installationId: String
+    public let recoveryCode: String
+
+    public init(ownerKey: String, installationId: String, recoveryCode: String) {
+        self.ownerKey = ownerKey
+        self.installationId = installationId
+        self.recoveryCode = recoveryCode
+    }
+}
+
+/// 自举失败 / 跳过的原因码。日志里必须出现码本身（排障时先看码再看文案）。
+public enum AdepIdentityCode {
+    /// 包里没有 `adep.app.json`（CLI 未注入或 cap sync 没同步）。
+    public static let configMissing = "IDENTITY_CONFIG_MISSING"
+    /// 配置在但字段非法（platformUrl 不是 http(s) / projectSlug 形态不符）。
+    public static let configInvalid = "IDENTITY_CONFIG_INVALID"
+    /// 传输层失败或非 2xx（断网 / 超时 / 5xx / 429）。
+    public static let requestFailed = "IDENTITY_REQUEST_FAILED"
+    /// 2xx 但响应形态不符（不是 JSON / 缺 installation / ownerKey 形态不对）。
+    public static let responseInvalid = "IDENTITY_RESPONSE_INVALID"
+    /// 拿到合法 ownerKey 但落 Keychain 失败。
+    public static let storeFailed = "IDENTITY_STORE_FAILED"
+    /// 已签发（跳过，未发请求）。
+    public static let alreadyIssued = "IDENTITY_ALREADY_ISSUED"
+    /// 同一实例重复 start（跳过，未发请求）。
+    public static let alreadyStarted = "IDENTITY_ALREADY_STARTED"
+}
+
+public struct AdepIdentityFailure: Error, Equatable {
+    public let code: String
+    public let message: String
+
+    public init(code: String, message: String) {
+        self.code = code
+        self.message = message
+    }
+}
+
+/// 判定层（纯函数，Foundation-only ⇒ 行为级门真跑）。
+///
+/// ⚠️ 下面几个常量与 `server/domains/appbuild/identity/contract.ts` /
+/// `sync-routes.ts` **逐字对应**（`OWNER_KEY_PREFIX` / `OWNER_KEY_BYTES` /
+/// `APP_PLATFORMS` / 端点路径）。漂移由 `adep-identity.test.ts` 的跨端一致性门对账——
+/// 服务端改路径而客户端还打旧路径，症状是 404（像「服务没部署」）。
+public enum AdepIdentityLogic {
+    /// ownerKey 明文前缀（服务端 `OWNER_KEY_PREFIX`）。
+    public static let ownerKeyPrefix = "adep_ok_"
+    /// ownerKey 随机段 hex 长度（服务端 `OWNER_KEY_BYTES = 32` ⇒ 64 位 hex，256 位熵）。
+    public static let ownerKeyHexLength = 64
+    /// 签发端点路径（服务端 `sync-routes.ts` 的 `/v1/projects/:projectId/app-installations`，
+    /// 平台侧挂在 `/api` 前缀下；`:projectId` 接受 **id 或 slug**，见 `resolveProjectByIdOrSlug`）。
+    public static let issuePathPrefix = "/api/v1/projects/"
+    public static let issuePathSuffix = "/app-installations"
+
+    /// ownerKey 形态：前缀 + 64 位**小写** hex（与服务端正则完全同形）。
+    /// ⚠️ 这里刻意严格（不宽松地接受大写）：宽松会让「服务端换了编码」这类契约漂移
+    /// 在客户端静默通过，然后在同步侧 401——错误在最远的地方爆。
+    public static func isOwnerKey(_ value: String) -> Bool {
+        guard value.hasPrefix(ownerKeyPrefix) else { return false }
+        let hex = value.dropFirst(ownerKeyPrefix.count)
+        guard hex.count == ownerKeyHexLength else { return false }
+        return hex.allSatisfy { ($0 >= "0" && $0 <= "9") || ($0 >= "a" && $0 <= "f") }
+    }
+
+    /// projectSlug 形态（与 `adep.app.json` schema 的 `^[a-z][a-z0-9-]{0,62}$` 同形）。
+    /// 之所以在客户端再判一次：拼 URL 时 slug 会成为**路径段**，形态失守就是拼出一个别的端点。
+    public static func isProjectSlug(_ value: String) -> Bool {
+        guard let first = value.first, first >= "a", first <= "z" else { return false }
+        guard value.count <= 63 else { return false }
+        for char in value {
+            let allowed = (char >= "a" && char <= "z") || (char >= "0" && char <= "9") || char == "-"
+            if !allowed { return false }
+        }
+        return true
+    }
+
+    /// 解析包里（或测试注入的）`adep.app.json`。
+    /// 只取自举需要的两个字段；**其余字段不校验**（壳配置的完整校验在 CLI 侧
+    /// `app-config.ts`，客户端再抄一份 schema 只会漂移）。
+    public static func parseConfig(_ data: Data) throws -> AdepIdentityConfig {
+        guard let object = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.configInvalid,
+                message: "adep.app.json 不是 JSON 对象"
+            )
+        }
+        guard let rawURL = object["platformUrl"] as? String else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.configInvalid,
+                message: "adep.app.json 缺 platformUrl"
+            )
+        }
+        guard
+            let url = URL(string: rawURL),
+            let scheme = url.scheme?.lowercased(),
+            scheme == "http" || scheme == "https",
+            let host = url.host,
+            !host.isEmpty
+        else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.configInvalid,
+                message: "platformUrl 不是合法的 http(s) URL：\(rawURL)"
+            )
+        }
+        guard let slug = object["projectSlug"] as? String else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.configInvalid,
+                message: "adep.app.json 缺 projectSlug"
+            )
+        }
+        guard isProjectSlug(slug) else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.configInvalid,
+                message: "projectSlug 形态不符（需小写字母开头，仅小写字母/数字/连字符）：\(slug)"
+            )
+        }
+        return AdepIdentityConfig(platformUrl: rawURL, projectSlug: slug)
+    }
+
+    /// 组装签发端点 URL。`platformUrl` 常带尾斜杠（`https://adep.top/`）⇒ 先归一，
+    /// 否则拼出 `//api/v1/...`（服务端 404，症状像「端点没部署」）。
+    public static func issueURL(config: AdepIdentityConfig) throws -> URL {
+        guard var components = URLComponents(string: config.platformUrl) else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.configInvalid,
+                message: "platformUrl 无法解析：\(config.platformUrl)"
+            )
+        }
+        var base = components.path
+        while base.hasSuffix("/") { base.removeLast() }
+        components.path = base + issuePathPrefix + config.projectSlug + issuePathSuffix
+        // 平台地址上的 query / fragment 对端点无意义，带上只会污染请求。
+        components.query = nil
+        components.fragment = nil
+        guard let url = components.url else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.configInvalid,
+                message: "签发端点 URL 组装失败（platformUrl: \(config.platformUrl)）"
+            )
+        }
+        return url
+    }
+
+    /// 请求体：服务端 body 契约是 `{ platform }`（`t.Object({ platform: t.String() })`，
+    /// `additionalProperties: true`）。
+    public static func issueBody(platform: String) -> Data {
+        let escaped = platform.replacingOccurrences(of: "\\", with: "\\\\")
+            .replacingOccurrences(of: "\"", with: "\\\"")
+        return Data("{\"platform\":\"\(escaped)\"}".utf8)
+    }
+
+    /// 解析签发响应：`{ installation: { installationId, ownerKey, recoveryCode, partition, platform } }`。
+    ///
+    /// **形态不符一律抛**（不写「尽量取到的那部分」）：ownerKey 是 bearer 凭据，
+    /// 把一个空串 / 半截值写进 Keychain，等于把「设备身份」变成「永远 401」的垃圾状态，
+    /// 而且**看起来像已签发**（下次启动不再重试）——比直接失败难查得多。
+    public static func parseIssue(_ data: Data) throws -> AdepIdentityIssue {
+        guard let object = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any] else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.responseInvalid,
+                message: "签发响应不是 JSON 对象"
+            )
+        }
+        guard let installation = object["installation"] as? [String: Any] else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.responseInvalid,
+                message: "签发响应缺 installation 对象"
+            )
+        }
+        guard let ownerKey = installation["ownerKey"] as? String, isOwnerKey(ownerKey) else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.responseInvalid,
+                message: "installation.ownerKey 形态不符（期望 \(ownerKeyPrefix) + \(ownerKeyHexLength) 位小写 hex）"
+            )
+        }
+        guard let installationId = installation["installationId"] as? String, !installationId.isEmpty else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.responseInvalid,
+                message: "installation.installationId 缺失或为空"
+            )
+        }
+        guard let recoveryCode = installation["recoveryCode"] as? String, !recoveryCode.isEmpty else {
+            throw AdepIdentityFailure(
+                code: AdepIdentityCode.responseInvalid,
+                message: "installation.recoveryCode 缺失或为空"
+            )
+        }
+        return AdepIdentityIssue(
+            ownerKey: ownerKey,
+            installationId: installationId,
+            recoveryCode: recoveryCode
+        )
+    }
+
+    /// 恢复码脱敏（日志用）。恢复码形态 `<installationId>.<secret>`：**installationId 不是机密**
+    /// （它就是安装行主键，服务端接口里也以明文出现），secret 段才是凭据。
+    /// ⇒ 保留 installationId + secret 前 4 位 + 总长度（长度能看出「码被截断」这类畸形）。
+    public static func maskRecoveryCode(_ value: String, installationId: String) -> String {
+        let head = installationId.isEmpty ? "" : installationId + "."
+        let secret = value.hasPrefix(head) ? String(value.dropFirst(head.count)) : value
+        let keep = String(secret.prefix(4))
+        return "\(head)\(keep)…(len \(value.count))"
+    }
+}
+
+/// 传输层结果。`status == 0` 表示**没拿到 HTTP 响应**（断网 / DNS / 超时 / TLS），
+/// `error` 带传输层原因；`status != 0` 时看状态码分支。
+public struct AdepIdentityHTTPResult: Equatable {
+    public let status: Int
+    public let body: Data?
+    public let error: String?
+
+    public init(status: Int, body: Data?, error: String?) {
+        self.status = status
+        self.body = body
+        self.error = error
+    }
+}
+
+/// 传输协议（可注入 ⇒ 行为级门用假传输驱动全部失败分支，不打真网络）。
+public protocol AdepIdentityTransport {
+    func post(url: URL, body: Data, timeout: TimeInterval) -> AdepIdentityHTTPResult
+}
+
+/// 生产传输：`URLSession`（不引第三方依赖）。
+///
+/// ⚠️ **同步阻塞**（信号量等待）：自举本身在后台队列上跑（`AdepBridge.load()` 里
+/// `DispatchQueue.global()`），所以这里阻塞的是工作线程，不是主线程。
+public final class AdepURLSessionTransport: AdepIdentityTransport {
+    public init() {}
+
+    /// 回调线程与等待线程之间的结果传递（`URLSession` 的回调在别的队列，
+    /// 直接捕获 `var` 在 Swift 6 并发检查下是数据竞争）。
+    private final class Box: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value: AdepIdentityHTTPResult?
+        func store(_ result: AdepIdentityHTTPResult) {
+            lock.lock()
+            value = result
+            lock.unlock()
+        }
+        func load() -> AdepIdentityHTTPResult? {
+            lock.lock()
+            defer { lock.unlock() }
+            return value
+        }
+    }
+
+    public func post(url: URL, body: Data, timeout: TimeInterval) -> AdepIdentityHTTPResult {
+        var request = URLRequest(url: url, timeoutInterval: timeout)
+        request.httpMethod = "POST"
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.setValue("application/json", forHTTPHeaderField: "Accept")
+        request.httpBody = body
+
+        let box = Box()
+        let semaphore = DispatchSemaphore(value: 0)
+        let task = URLSession.shared.dataTask(with: request) { data, response, error in
+            defer { semaphore.signal() }
+            if let error {
+                box.store(AdepIdentityHTTPResult(status: 0, body: nil, error: error.localizedDescription))
+                return
+            }
+            guard let http = response as? HTTPURLResponse else {
+                box.store(AdepIdentityHTTPResult(status: 0, body: nil, error: "响应不是 HTTPURLResponse"))
+                return
+            }
+            box.store(AdepIdentityHTTPResult(status: http.statusCode, body: data, error: nil))
+        }
+        task.resume()
+        // 兜底超时比 URLRequest 的 timeoutInterval 略宽：正常情况下 URLSession 先报超时
+        // （那样能拿到 `error` 文案），这里只兜「回调永远不来」的极端形态。
+        _ = semaphore.wait(timeout: .now() + timeout + 5)
+        return box.load() ?? AdepIdentityHTTPResult(status: 0, body: nil, error: "URLSession 回调超时未返回")
+    }
+}
+
+/// 首启自举：查本地 → （缺则）签发 → 写 Keychain → 通知库换 key。
+///
+/// 依赖全是注入的闭包（存储、配置、传输、日志、换 key 回调）——生产装配见
+/// `AdepBridge.load()`，行为级门注入内存替身。这样「要不要请求」「写不写」「写什么」
+/// 三条判定都能真跑，而不是靠读源码猜。
+public final class AdepIdentityBootstrap {
+    /// 注入面。所有副作用都从这里出，`start()` 自身不碰任何全局状态。
+    public struct Environment {
+        /// 包里 `adep.app.json` 的字节（缺失返回 nil ⇒ `IDENTITY_CONFIG_MISSING`）。
+        public var configData: () -> Data?
+        /// 读本地既有 ownerKey（Keychain / Keystore）；无则 nil。
+        public var storedOwnerKey: () -> String?
+        /// 写 ownerKey，返回是否成功（Keychain 的 `SecItemAdd` 失败必须能被看见）。
+        public var persistOwnerKey: (String) -> Bool
+        /// 读本地既有恢复码（写后读回校验用；APP-028）。无则 nil。
+        public var storedRecoveryCode: () -> String?
+        /// 写恢复码，返回是否成功。**与 ownerKey 同生命周期**（每次成功签发覆盖两把）。
+        public var persistRecoveryCode: (String) -> Bool
+        /// 传输（生产 `AdepURLSessionTransport`）。
+        public var transport: AdepIdentityTransport
+        /// 设备平台（服务端枚举 `ios` / `android` / …）。
+        public var platform: String
+        /// 单次请求超时（秒）。
+        public var timeout: TimeInterval
+        /// 日志（生产走 NSLog：SpringBoard 拉起的 app 收不到 stdout）。
+        public var log: (String) -> Void
+        /// ownerKey 落库后的回调（换库 key / rekey；不改变本类的判定）。
+        public var onIssued: (String) -> Void
+
+        public init(
+            configData: @escaping () -> Data?,
+            storedOwnerKey: @escaping () -> String?,
+            persistOwnerKey: @escaping (String) -> Bool,
+            storedRecoveryCode: @escaping () -> String?,
+            persistRecoveryCode: @escaping (String) -> Bool,
+            transport: AdepIdentityTransport,
+            platform: String,
+            timeout: TimeInterval = 10,
+            log: @escaping (String) -> Void,
+            onIssued: @escaping (String) -> Void
+        ) {
+            self.configData = configData
+            self.storedOwnerKey = storedOwnerKey
+            self.persistOwnerKey = persistOwnerKey
+            self.storedRecoveryCode = storedRecoveryCode
+            self.persistRecoveryCode = persistRecoveryCode
+            self.transport = transport
+            self.platform = platform
+            self.timeout = timeout
+            self.log = log
+            self.onIssued = onIssued
+        }
+    }
+
+    public enum Outcome: Equatable {
+        /// 签发并落库成功（ownerKey 明文——调用方只用于日志脱敏后的读数，不要外传）。
+        case issued(ownerKey: String)
+        /// 未发请求：已签发 / 重复启动。
+        case skipped(code: String)
+        /// 失败（原因码 + 可读详情）。**没有任何本地写入发生**。
+        case failed(code: String, detail: String)
+    }
+
+    private let environment: Environment
+    private let lock = NSLock()
+    private var started = false
+
+    public init(environment: Environment) {
+        self.environment = environment
+    }
+
+    /// 启动一次自举。**幂等**：同一实例重复调用只发一次请求（第二次返回
+    /// `.skipped(alreadyStarted)`）。**同步阻塞** ⇒ 调用方必须放到后台队列。
+    @discardableResult
+    public func start() -> Outcome {
+        lock.lock()
+        if started {
+            lock.unlock()
+            environment.log("[adep-identity] \(AdepIdentityCode.alreadyStarted): 已启动过，忽略重复调用")
+            return .skipped(code: AdepIdentityCode.alreadyStarted)
+        }
+        started = true
+        lock.unlock()
+
+        // ① 已有合法 ownerKey ⇒ 一枚安装只签发一次（分母断言：这条路径下请求数必须为 0）。
+        if let existing = environment.storedOwnerKey(), !existing.isEmpty {
+            if AdepIdentityLogic.isOwnerKey(existing) {
+                let masked = String(existing.prefix(AdepIdentityLogic.ownerKeyPrefix.count + 6))
+                environment.log("[adep-identity] \(AdepIdentityCode.alreadyIssued): 本地已有 ownerKey（\(masked)…），不重复签发")
+                return .skipped(code: AdepIdentityCode.alreadyIssued)
+            }
+            // 形态不符（历史垃圾值 / 手写调试值）：不是可用身份，重新签发覆盖它。
+            // 不静默当成「已签发」——那会让 app 永远带着一枚服务端不认的凭据。
+            environment.log("[adep-identity] 本地 ownerKey 形态不符（长度 \(existing.count)），将重新签发")
+        }
+
+        // ② 配置（包里 adep.app.json）。缺失与非法分开报：前者是打包问题，后者是配置写错。
+        guard let configData = environment.configData() else {
+            return fail(AdepIdentityCode.configMissing, detail: "包内缺少 \(AdepShellConfig.configFileName)（候选位置：包根 / site/ / public/）")
+        }
+        let config: AdepIdentityConfig
+        do {
+            config = try AdepIdentityLogic.parseConfig(configData)
+        } catch let failure as AdepIdentityFailure {
+            return fail(failure.code, detail: failure.message)
+        } catch {
+            return fail(AdepIdentityCode.configInvalid, detail: error.localizedDescription)
+        }
+        let url: URL
+        do {
+            url = try AdepIdentityLogic.issueURL(config: config)
+        } catch let failure as AdepIdentityFailure {
+            return fail(failure.code, detail: failure.message)
+        } catch {
+            return fail(AdepIdentityCode.configInvalid, detail: error.localizedDescription)
+        }
+
+        // ③ 请求。非 2xx 与传输层失败都落 requestFailed，但 detail 区分（status 0 = 没拿到响应）。
+        let result = environment.transport.post(
+            url: url,
+            body: AdepIdentityLogic.issueBody(platform: environment.platform),
+            timeout: environment.timeout
+        )
+        guard result.status >= 200, result.status < 300 else {
+            if let transportError = result.error {
+                return fail(AdepIdentityCode.requestFailed, detail: "传输层失败：\(transportError)（url: \(url.absoluteString)）")
+            }
+            let snippet = result.body.flatMap { String(data: $0, encoding: .utf8) }?.prefix(200) ?? ""
+            return fail(AdepIdentityCode.requestFailed, detail: "HTTP \(result.status)（url: \(url.absoluteString)；响应：\(snippet)）")
+        }
+        guard let body = result.body else {
+            return fail(AdepIdentityCode.responseInvalid, detail: "HTTP \(result.status) 但响应体为空")
+        }
+
+        // ④ 解析 + 落库。写失败也算失败：没写进去 = 下次启动还会再签发一次（换来多一枚孤儿安装行）。
+        let issue: AdepIdentityIssue
+        do {
+            issue = try AdepIdentityLogic.parseIssue(body)
+        } catch let failure as AdepIdentityFailure {
+            return fail(failure.code, detail: failure.message)
+        } catch {
+            return fail(AdepIdentityCode.responseInvalid, detail: error.localizedDescription)
+        }
+        // ⑤ 恢复码**先**落库并读回校验（APP-028）。
+        //
+        // 顺序即不变量：**本地有 ownerKey ⇒ 本地必有与它同源的恢复码**。
+        // 反过来（先写 ownerKey）会出现「app 已带着这枚身份跑，用户却永远拿不到恢复码」——
+        // 恢复码明文只在这一次响应里存在（服务端只存 `recoveryCodeHash`，任何端点都不重发），
+        // 丢了就是该安装的分区永久不可认领。所以宁可不落 ownerKey、下次启动重签。
+        guard environment.persistRecoveryCode(issue.recoveryCode) else {
+            return fail(
+                AdepIdentityCode.storeFailed,
+                detail: "恢复码写入 Keychain / Keystore 失败（installationId: \(issue.installationId)）——本次不落 ownerKey，下次启动重新签发"
+            )
+        }
+        // 读回校验：`SecItemAdd` 报成功但读不出是真实故障形态（accessible 级别不匹配 /
+        // 条目被策略清掉）。只看写返回码会把「码已丢」当成功——正是 APP-028 要消灭的静默。
+        guard environment.storedRecoveryCode() == issue.recoveryCode else {
+            return fail(
+                AdepIdentityCode.storeFailed,
+                detail: "恢复码写入后读回不一致（installationId: \(issue.installationId)）——本次不落 ownerKey"
+            )
+        }
+        // ⑥ ownerKey 落库（写失败也算失败：没写进去 = 下次启动还会再签发一次，多一枚孤儿安装行）。
+        guard environment.persistOwnerKey(issue.ownerKey) else {
+            return fail(AdepIdentityCode.storeFailed, detail: "ownerKey 写入 Keychain / Keystore 失败（installationId: \(issue.installationId)）")
+        }
+        environment.log(
+            "[adep-identity] 签发成功（installationId: \(issue.installationId), platform: \(environment.platform), "
+                + "recoveryCode: \(AdepIdentityLogic.maskRecoveryCode(issue.recoveryCode, installationId: issue.installationId))）"
+        )
+        environment.onIssued(issue.ownerKey)
+        return .issued(ownerKey: issue.ownerKey)
+    }
+
+    /// 失败收口：日志必须带**原因码**（排障顺序：先看码，再看详情），并原样返回给调用方。
+    private func fail(_ code: String, detail: String) -> Outcome {
+        environment.log("[adep-identity] \(code): \(detail)")
+        return .failed(code: code, detail: detail)
+    }
+}

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

@@ -1,20 +1,73 @@
 import Foundation
 import Security
 
-/// ownerKey 的 Keychain 存储（iOS，APP-009）。
+/// 设备凭据的 Keychain 存储（iOS，APP-009 / APP-027 / APP-028）。
 ///
-/// PRD §2.11.5「设备身份与恢复」：ownerKey 移动端**只存 Keychain / Keystore**——
+/// PRD §2.11.5「设备身份与恢复」：ownerKey 与**恢复码**在移动端**只存 Keychain / Keystore**——
 /// 不落 UserDefaults / 沙盒文件 / JS 侧持久化（客户端产物等同公开，明文落盘等于
 /// 把设备身份直接交给解包者）。Keychain 由系统加密保护，应用卸载后条目随钥匙串
 /// 条目保留策略由系统管理（本实现用 kSecAttrAccessibleAfterFirstUnlock，设备
 /// 重启后首次解锁即可读，适合后台同步场景）。
+///
+/// ## 两个槽位（service 区分）
+///
+/// - `adep.ownerKey`：分区凭据（同步 Bearer + 库 key 同源）。
+/// - `adep.recoveryCode`：换机 / 重装认领同一分区用（APP-028）。**服务端只存它的摘要，
+///   明文只在签发响应里出现一次** ⇒ 这里写不进去就是永久丢失，所以自举会做写后读回校验。
+///
+/// ⚠️ **service / account 名不可改**：已装机设备的 Keychain 里是既有条目，改名 = 读不到
+/// ownerKey ⇒ 库 key 失配 ⇒ 数据全丢（不是「重新签发一次就好」——库是用旧 key 建的）。
 enum AdepKeychain {
-    private static let service = "adep.ownerKey"
+    private static let ownerService = "adep.ownerKey"
+    private static let recoveryService = "adep.recoveryCode"
     private static let account = "default"
 
+    // MARK: - ownerKey
+
     /// 读 ownerKey；无则返回 nil（首启未签发）。
     static func loadOwnerKey() -> String? {
-        var query = baseQuery()
+        load(service: ownerService)
+    }
+
+    /// 写 ownerKey（已存在则覆盖）。
+    @discardableResult
+    static func saveOwnerKey(_ key: String) -> Bool {
+        save(key, service: ownerService)
+    }
+
+    /// 删 ownerKey（换装 / 恢复码认领时用）。
+    @discardableResult
+    static func deleteOwnerKey() -> Bool {
+        delete(service: ownerService)
+    }
+
+    // MARK: - 恢复码（APP-028）
+
+    /// 读恢复码；无则 nil（首启未签发，或签发时写入失败——后者由自举的读回校验报出来）。
+    static func loadRecoveryCode() -> String? {
+        load(service: recoveryService)
+    }
+
+    /// 写恢复码（已存在则覆盖）。
+    ///
+    /// **覆盖而不是 write-once**：恢复码与 ownerKey 同属一次签发；本地 ownerKey 形态不符会重签
+    /// ⇒ 新安装 / 新恢复码。此时保留旧码会让用户认领到**旧分区**（数据是旧的、当前 app 也不用它），
+    /// 比「没有码」更难发现。语义与 `saveOwnerKey` 保持一致。
+    @discardableResult
+    static func saveRecoveryCode(_ code: String) -> Bool {
+        save(code, service: recoveryService)
+    }
+
+    /// 删恢复码（认领成功后清理本地绑定等场景）。
+    @discardableResult
+    static func deleteRecoveryCode() -> Bool {
+        delete(service: recoveryService)
+    }
+
+    // MARK: - 内部
+
+    private static func load(service: String) -> String? {
+        var query = baseQuery(service: service)
         query[kSecReturnData as String] = true
         query[kSecMatchLimit as String] = kSecMatchLimitOne
         var item: CFTypeRef?
@@ -23,22 +76,21 @@ enum AdepKeychain {
         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)
+    /// 写（delete + add）。刻意「先删再写」而不是 `SecItemUpdate`：两条路径的返回值语义不同
+    /// （update 在条目不存在时是 errSecItemNotFound），混用会把「没写成」判成成功。
+    private static func save(_ value: String, service: String) -> Bool {
+        _ = delete(service: service)
+        var query = baseQuery(service: service)
+        query[kSecValueData as String] = Data(value.utf8)
         return SecItemAdd(query as CFDictionary, nil) == errSecSuccess
     }
 
-    /// 删 ownerKey（换装 / 恢复码认领时用）。
-    @discardableResult
-    static func deleteOwnerKey() -> Bool {
-        SecItemDelete(baseQuery() as CFDictionary) == errSecSuccess || errSecItemNotFoundCheck()
+    private static func delete(service: String) -> Bool {
+        SecItemDelete(baseQuery(service: service) as CFDictionary) == errSecSuccess
+            || errSecItemNotFoundCheck(service: service)
     }
 
-    private static func baseQuery() -> [String: Any] {
+    private static func baseQuery(service: String) -> [String: Any] {
         return [
             kSecClass as String: kSecClassGenericPassword,
             kSecAttrService as String: service,
@@ -48,9 +100,9 @@ enum AdepKeychain {
     }
 
     /// delete 在「无条目」时返回 errSecItemNotFound，等同成功（幂等删除）。
-    private static func errSecItemNotFoundCheck() -> Bool {
+    private static func errSecItemNotFoundCheck(service: String) -> Bool {
         // 上一条删除若因条目不存在失败，这里重查一次确认「确实不存在」即可算成功。
-        var query = baseQuery()
+        var query = baseQuery(service: service)
         query[kSecReturnData as String] = true
         var item: CFTypeRef?
         return SecItemCopyMatching(query as CFDictionary, &item) == errSecItemNotFound