@adep/cli 0.4.1 → 0.4.5

package/package.json

@@ -7,7 +7,7 @@
   },
   "homepage": "https://adep.top",
   "bugs": "https://gitcode.com/yunqiang_wu/ai-yunke/issues",
-  "version": "0.4.1",
+  "version": "0.4.5",
   "type": "module",
   "description": "`adep` 命令行工具包位：登录 / 初始化 / 本地调试 / 部署 / 数据库维护 / 云存储 / 静态托管 / 微前端组件（widget），实现见任务单 CLI-001 ~ CLI-003 与 FE-002；子路径 `@adep/cli/vite` 提供云函数 vite 插件（CLI-014）",
   "bin": {
@@ -29,14 +29,15 @@
     "commander": "14.0.2",
     "esbuild": "0.25.12",
     "yaml": "2.9.1",
-    "zod": "^4.4.3",
-    "@adep/cf-compat": "0.1.2",
-    "@adep/runtime": "0.3.3",
+    "zod": "^4.6.6",
+    "@adep/cf-compat": "0.1.4",
+    "@adep/app-runtime": "0.1.1",
+    "@adep/runtime": "0.3.5",
     "@adep/crypto": "0.1.1",
     "@adep/vite-plugin": "0.1.9"
   },
   "devDependencies": {
-    "@adep/types": "0.3.1"
+    "@adep/types": "0.3.2"
   },
   "scripts": {
     "test": "vitest run",

package/templates/app-desktop/README.md

@@ -18,7 +18,7 @@ GUI（前端产物）随包本地加载，云函数经 HTTP 在服务端执行
 
 1. 把平台项目的前端构建产物放进 `app/site/`（`adep app build` 会自动拉取已发布产物）；
 2. `npm install`；
-3. `npm start`（配置从 `adep.app.json` 读取，无需环境变量）。
+3. `npm start`（或仓库根的 `adep app open`，等价——直接调壳工程内的 electron；配置从 `adep.app.json` 读取，无需环境变量）。
 
 ## 页面侧调用云函数（在线运行时）
 
@@ -31,12 +31,77 @@ const client = createAdepClient({ baseUrl: window.__ADEP_APP__.platformUrl })
 const result = await client.invokeFunction('hello', { name: 'world' })
 ```
 
+## 设备身份与同步（离线构建之后）
+
+离线构建把设备端运行时注入 `app/offline/`，首次启动时在 `data/offline.sqlite` 建本地库：
+白名单函数在本地执行，写 owned 表时同时追加变更流。
+
+**设备身份是首启自动签发的**（APP-033 / PRD §2.11.5）：主进程启动后在后台调一次
+`POST /api/v1/projects/<slug>/app-installations`（`platform` 按**宿主 OS** 映射为
+`macos` / `windows` / `linux`——服务端没有 `desktop` 这个取值），拿到 `ownerKey` +
+一次性恢复码后写进受保护存储；此后每次启动只读不发请求。
+
+```text
+identity.mjs        判定层（配置 / 端点 / 形态 / 响应解析 / 平台映射）+ 自举流程
+identity-store.mjs  受保护存储：macOS 钥匙串 → Linux Secret Service → 0600 文件（明说降级）
+recovery-ui.mjs     恢复码呈现与导出（APP-034；全在主进程，页面侧拿不到）
+sync-loop.mjs       后台同步驱动（首轮延迟 → 每 5 分钟一轮；不重叠、失败不致命）
+```
+
+存储后端：
+
+- macOS：`security add-generic-password`（登录钥匙串）；
+- Linux：`secret-tool`（Secret Service）；
+- **Windows 与「系统库不可用」**：退化到 `data/identity/` 下的 0600 文件，并在日志与
+  `adep app doctor` 里**明说「非系统凭据」**——不会静默假装是钥匙串。
+
+身份状态（**非机密**：只有存储类型 / 原因码 / 安装 id / 时间）写在
+`data/identity/status.json`，`adep app doctor` 的 `identity` 项读它：
+
+```bash
+adep app doctor        # 已签发（系统凭据库 keychain） / 非系统凭据（file） / 首启签发失败（原因码）
+```
+
+⚠️ **页面侧拿不到 `ownerKey`**（与移动壳同一条边界）：同步跑在主进程，渲染进程不需要这枚
+bearer 凭据，给它等于「任意 XSS 都能劫持该设备的数据分区」。
+
+## 恢复码（APP-034：呈现 / 再次查看 / 导出）
+
+签发响应里的恢复码**只出现一次**（服务端只存摘要、任何端点不重发），壳负责把它递到用户手里：
+
+- **首次呈现**：自举成功后自动弹一次原生对话框（码可读且没呈现过才弹——老安装升级上来
+  同样有机会看到）。此后不再主动弹，标记写在 `data/identity/recovery-code-shown`；
+- **再次查看 / 导出**：应用菜单 **「凭据」→「查看恢复码…」/「导出恢复码…」**（导出文件
+  头部写明「服务端无法重发，丢了码等于放弃认领」）；
+- **复制到剪贴板**：两个对话框里都有一键复制。
+
+呈现与导出**全在主进程**（应用菜单 + 原生对话框）：不开 IPC、不改 preload，恢复码与
+`ownerKey` 一样不进渲染进程。码不可读时（未签发 / 存储失败）对话框会说明原因并指向
+`adep app doctor`，不是静默空窗。
+
+身份就绪后主进程自动把同步挂到运行时上：
+
+```js
+const runtime = await createOfflineRuntime() // 页面先可用
+const sync = runtime.attachSync({ ownerKey }) // 身份到位后再挂（不重开库）
+await sync.push() // 本地变更流 → outbox → 云端
+await sync.pull() // 云端增量 → 本地库（直写驱动，不回灌 outbox）
+```
+
+手动同步（开发期 / 排障）仍用 CLI：`adep app sync --push`（身份取 `--owner-key` 或
+`ADEP_OWNER_KEY`）。**不要**在 `adep.app.json` 或环境变量里编一个 key：本地自造会写出一个
+「看起来成功」的空分区（PRD §2.11.5 明确「本地自造判违规」）。
+
+⚠️ 已知限制（已登记）：打包形态下 `data/` 仍在应用目录内（`.app` / Program Files），
+写入可能被系统拒绝——此时 `identity` 项会显示 `IDENTITY_STORE_FAILED`，属于**响亮失败**。
+把本地数据目录迁到 `app.getPath('userData')` 是独立的一批（含 `data/offline.sqlite`）。
+
 ## 打安装包
 
 推荐用 CLI（会自动拉取**已发布**的前端产物、回写产物版本、产出构建报告）：
 
 ```bash
-adep app build            # 当前平台、走 package.json build 段的 target（mac dmg / win nsis / linux AppImage）
+adep app build            # 当前平台、走 package.json build 段的 target（mac dmg / win nsis+zip / linux AppImage+deb）
 adep app build --target dir        # 只出未压缩目录（macOS 即 .app），本地快速验证
 adep app build --prepare-only      # 只拉产物 + 注入 + 出构建报告，不调 electron-builder
 ```

package/templates/app-desktop/identity-store.mjs

@@ -0,0 +1,309 @@
+/**
+ * 桌面端受保护存储（APP-033；PRD §2.11.5「桌面端存系统凭据/受保护存储」）。
+ *
+ * ## 为什么不是「写个 0600 文件就完事」
+ *
+ * 0600 文件只挡同机其他用户，**挡不住以该用户身份运行的其他进程**（同用户读得到）。
+ * 系统凭据库（macOS Keychain / Linux Secret Service）多一层「条目归属 + 访问控制」，
+ * 这是 PRD 要求它的原因。所以本模块的顺序是：**先试系统凭据库，失败才退化**。
+ *
+ * ## 退化必须是响亮的
+ *
+ * 退化形态（`data/identity/*` 0600 文件）与系统凭据在调用侧**返回值完全同形**——
+ * 差别只在 `backend` 这一个字段。所以：
+ * - `backend` 是**读写**属性（不是构造期快照）：系统库写失败当场改成 `file`，
+ *   调用方读到的永远是「实际生效的那一个」，不会出现「报告说 Keychain、实际在明文文件里」；
+ * - 退化时打 `IDENTITY_STORE_FALLBACK` 码 + 一句人话，状态文件里也写 `backend: "file"`，
+ *   `adep app doctor` 据此显示「非系统凭据」——**不静默假装是 Keychain**（验收标准第 4 条）。
+ *
+ * ## Windows 的实况（如实登记，不假装）
+ *
+ * 本批只落了 macOS（`security`）与 Linux（`secret-tool`）。Windows 的 DPAPI / Credential
+ * Manager 需要 PowerShell 或原生模块，**本机无法验证**（与 SQLCipher 真机证据同口径）⇒
+ * 不写一段跑不到、也没人验过的 PowerShell：Windows 上直接走退化文件并打同一个 fallback 码。
+ * 缺口登记在 APP-033 的归档卡「超出范围」里，不在这里假装已支持。
+ */
+
+/** 受保护存储后端标识（进状态文件与 doctor 读数，**不要**改字面值）。 */
+export const STORE_BACKENDS = {
+  /** macOS 登录钥匙串（`security` 命令行）。 */
+  keychain: 'keychain',
+  /** Linux Secret Service（`secret-tool`，GNOME Keyring / KWallet 的通用前端）。 */
+  secretService: 'secret-service',
+  /** 退化形态：`data/identity/**` 下 0600 文件。 */
+  file: 'file',
+}
+
+/** 身份文件目录（相对壳工程根）。doctor 读同一个目录 ⇒ 改这里要同步改 `app-doctor.ts`。 */
+export const IDENTITY_DIR = 'data/identity'
+/** ownerKey 文件名（0600）。 */
+export const OWNER_KEY_FILE = 'owner-key'
+/** 恢复码文件名（0600）。 */
+export const RECOVERY_CODE_FILE = 'recovery-code'
+/** 身份状态文件名（**非机密**：backend / 码 / installationId / 时间）。 */
+export const STATUS_FILE = 'status.json'
+
+/** 退化原因码（日志与状态文件都带它，排障时先看码）。 */
+export const STORE_CODES = {
+  fallback: 'IDENTITY_STORE_FALLBACK',
+  unavailable: 'IDENTITY_STORE_UNAVAILABLE',
+}
+
+/**
+ * 后端选择：看宿主 OS，不看配置。
+ *
+ * @param {string} platform `process.platform` 取值
+ * @returns {'keychain'|'secret-service'|null} null 表示该平台没有系统凭据库实现（Windows 属此形态）
+ */
+export function systemBackendFor(platform) {
+  if (platform === 'darwin') return STORE_BACKENDS.keychain
+  if (platform === 'linux') return STORE_BACKENDS.secretService
+  return null
+}
+
+/**
+ * 缺省执行器：`execFile` + stdin 注入，失败折成 `{ ok: false }`（不 throw，调用方按 ok 分支）。
+ *
+ * 注入点存在的理由：`app-desktop-identity.test.ts` 要能造「系统库不可用 / 写成功但读回空 /
+ * 命令超时」这些形态，而它们在本机（macOS）要么做不到、要么会污染真实钥匙串。
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {string} [input] 写进子进程 stdin 的内容（`secret-tool store` 从 stdin 读密文）
+ * @returns {Promise<{ ok: boolean, stdout: string, error: string | null }>}
+ */
+export function createExecFileRunner() {
+  return async (command, args, input) => {
+    const { execFile } = await import('node:child_process')
+    return await new Promise((resolve) => {
+      const child = execFile(
+        command,
+        args,
+        { timeout: 15_000, windowsHide: true },
+        (error, stdout) => {
+          resolve({
+            ok: error === null,
+            stdout: typeof stdout === 'string' ? stdout : String(stdout),
+            error: error === null ? null : error.message,
+          })
+        }
+      )
+      if (input !== undefined && child.stdin !== null) {
+        child.stdin.end(input)
+      }
+    })
+  }
+}
+
+/**
+ * 值形态守卫：换行 / NUL 会让「写进去的」与「读回来的」不是同一个串
+ * （`security -w` 会把后续行当新参数，`secret-tool` 走 stdin 时换行直接截断）。
+ *
+ * @param {string} account
+ * @param {string} value
+ */
+function assertStorableValue(account, value) {
+  if (typeof value !== 'string' || value === '') {
+    throw new Error(`${account} 不能为空`)
+  }
+  if (value.includes('\n') || value.includes('\r') || value.includes('\u0000')) {
+    throw new Error(`${account} 不能包含换行或 NUL（换行会被凭据命令截断）`)
+  }
+}
+
+/**
+ * @typedef {Object} adepStoreOptions
+ * @property {string} root 壳工程根（data/identity/ 落在这里）
+ * @property {string} service 凭据条目的 service 串（如 `adep-app:<projectSlug>`）
+ * @property {string} [platform] 宿主平台（缺省 process.platform）
+ * @property {(command: string, args: string[], input?: string) => Promise<{ok: boolean, stdout: string, error: string | null}>} [exec] 凭据命令执行器（测试注入）
+ * @property {(line: string) => void} [log] 降级 / 失败日志
+ */
+
+/**
+ * 造一个受保护存储。
+ *
+ * @param {adepStoreOptions} options
+ */
+export function createProtectedStore(options) {
+  const {
+    root,
+    service,
+    platform = process.platform,
+    exec = createExecFileRunner(),
+    log = () => {},
+  } = options
+  const system = systemBackendFor(platform)
+  /** @type {string} 实际生效的后端（系统库写失败会当场降级） */
+  let effective = system ?? STORE_BACKENDS.file
+  const dir = joinPath(root, IDENTITY_DIR)
+
+  // ⚠️ 命令按**期望后端**（`system`）选，不按 `effective`：降级之后 `effective` 已是 `file`，
+  // 若拿它选命令，macOS 上会去调 `secret-tool`（不存在）——写失败被判成「系统库不可用」，
+  // 而真正的 `security` 一次都没试过。
+  const commandFor = (/** @type {string} */ action, /** @type {string} */ account, /** @type {string|undefined} */ value) => {
+    if (system === STORE_BACKENDS.keychain) {
+      if (action === 'read') {
+        return { command: 'security', args: ['find-generic-password', '-s', service, '-a', account, '-w'] }
+      }
+      if (action === 'write') {
+        // -U：同 service/account 已存在时原地更新（不 -U 会报 duplicate item）。
+        return { command: 'security', args: ['add-generic-password', '-U', '-s', service, '-a', account, '-w', String(value)] }
+      }
+      return { command: 'security', args: ['delete-generic-password', '-s', service, '-a', account] }
+    }
+    if (action === 'read') {
+      return { command: 'secret-tool', args: ['lookup', 'service', service, 'account', account] }
+    }
+    if (action === 'write') {
+      return {
+        command: 'secret-tool',
+        args: ['store', `--label=${service} ${account}`, 'service', service, 'account', account],
+        input: String(value),
+      }
+    }
+    return { command: 'secret-tool', args: ['clear', 'service', service, 'account', account] }
+  }
+
+  /** 系统凭据库读：不存在 / 命令失败都当「没有」，交给退化路径兜。 */
+  const readSystem = async (/** @type {string} */ account) => {
+    if (system === null) return null
+    const { command, args } = commandFor('read', account, undefined)
+    const result = await exec(command, args)
+    if (!result.ok) return null
+    const value = result.stdout.trim()
+    return value === '' ? null : value
+  }
+
+  /** 退化快照：文件不存在返回 null（**不**把「读失败」当成空值写回）。 */
+  const readFileValue = async (/** @type {string} */ name) => {
+    const { readFile } = await import('node:fs/promises')
+    try {
+      const text = await readFile(joinPath(dir, name), 'utf8')
+      return text === '' ? null : text
+    } catch {
+      return null
+    }
+  }
+
+  /** 退化写：目录 0700、文件 0600（先建后 chmod，旧文件已存在时 mode 参数不生效）。 */
+  const writeFileValue = async (/** @type {string} */ name, /** @type {string} */ value) => {
+    const { chmod, mkdir, writeFile } = await import('node:fs/promises')
+    await mkdir(dir, { recursive: true, mode: 0o700 })
+    const file = joinPath(dir, name)
+    await writeFile(file, value, { encoding: 'utf8', mode: 0o600 })
+    // mode 在文件已存在时被忽略 ⇒ 显式再 chmod 一次（0600 是这条路径唯一的保护）。
+    await chmod(file, 0o600)
+    return file
+  }
+
+  /** 写系统凭据库；失败返回 false（由调用方降级）。 */
+  const writeSystem = async (/** @type {string} */ account, /** @type {string} */ value) => {
+    if (system === null) return false
+    const { command, args, input } = commandFor('write', account, value)
+    const result = await exec(command, args, input)
+    if (!result.ok) {
+      log(
+        `[adep-identity] ${STORE_CODES.fallback}: 系统凭据库写入失败（${system}：${result.error ?? '未知原因'}）`
+      )
+    }
+    return result.ok
+  }
+
+  const read = async (/** @type {string} */ account, /** @type {string} */ file) => {
+    const fromSystem = await readSystem(account)
+    if (fromSystem !== null) return fromSystem
+    return await readFileValue(file)
+  }
+
+  const write = async (
+    /** @type {string} */ account,
+    /** @type {string} */ file,
+    /** @type {string} */ value
+  ) => {
+    assertStorableValue(account, value)
+    if (await writeSystem(account, value)) {
+      // 系统库成功 ⇒ 清掉退化副本（同一枚凭据只留一份，避免「哪份是活的」歧义）。
+      await removeFileQuietly(joinPath(dir, file))
+      effective = system ?? STORE_BACKENDS.file
+      return
+    }
+    if (effective !== STORE_BACKENDS.file) {
+      effective = STORE_BACKENDS.file
+      log(
+        `[adep-identity] ${STORE_CODES.fallback}: ${account} 落到 data/identity/${file}（0600）——**非系统凭据**，同机同用户进程可读`
+      )
+    }
+    await writeFileValue(file, value)
+  }
+
+  return {
+    /** 实际生效的后端（退化后变成 `file`）。 */
+    get backend() {
+      return effective
+    },
+    /** 期望后端（诊断用：`file` 表示这台机器从一开始就没有系统凭据库）。 */
+    get preferredBackend() {
+      return system ?? STORE_BACKENDS.file
+    },
+    readOwnerKey: () => read('ownerKey', OWNER_KEY_FILE),
+    writeOwnerKey: (/** @type {string} */ value) => write('ownerKey', OWNER_KEY_FILE, value),
+    readRecoveryCode: () => read('recoveryCode', RECOVERY_CODE_FILE),
+    writeRecoveryCode: (/** @type {string} */ value) => write('recoveryCode', RECOVERY_CODE_FILE, value),
+    /** 吊销 / 换发时清空两把（本批未接 UI，留给轮换路径用）。 */
+    async clear() {
+      const targets = [
+        ['ownerKey', OWNER_KEY_FILE],
+        ['recoveryCode', RECOVERY_CODE_FILE],
+      ]
+      await Promise.all(
+        targets.map(async ([account, file]) => {
+          if (system !== null) {
+            const { command, args } = commandFor('delete', String(account), undefined)
+            await exec(command, args)
+          }
+          await removeFileQuietly(joinPath(dir, String(file)))
+        })
+      )
+    },
+  }
+}
+
+/**
+ * 写身份状态（**非机密**，0600 + 原子替换）。
+ *
+ * 为什么要有这个文件：桌面壳是 GUI，日志（stderr）用户看不到；身份到底签没签、用的哪种
+ * 存储，必须有一条**可判读**的读数路径。`adep app doctor` 读的就是它（APP-030 的教训：
+ * 读数存在但读不出来等于没有）。
+ *
+ * @param {string} root 壳工程根
+ * @param {Record<string, unknown>} record
+ * @returns {Promise<string>} 状态文件绝对路径
+ */
+export async function writeIdentityStatus(root, record) {
+  const { chmod, mkdir, rename, writeFile } = await import('node:fs/promises')
+  const dir = joinPath(root, IDENTITY_DIR)
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  const file = joinPath(dir, STATUS_FILE)
+  // 原子替换：doctor 可能正好在写的时候读，读到半截 JSON 会被判成「损坏」。
+  const temp = `${file}.tmp-${process.pid}`
+  await writeFile(temp, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+  await rename(temp, file)
+  await chmod(file, 0o600)
+  return file
+}
+
+/** 最小路径拼接（避免为了一个 join 引 node:path 的 ESM 互操作差异）。 */
+function joinPath(/** @type {string} */ base, /** @type {string} */ rel) {
+  return `${base.replace(/[\\/]+$/, '')}/${rel}`
+}
+
+/** 删文件（不存在 / 无权限都静默：它只是「清副本」，失败不改变主路径结果）。 */
+async function removeFileQuietly(/** @type {string} */ file) {
+  const { rm } = await import('node:fs/promises')
+  try {
+    await rm(file, { force: true })
+  } catch {
+    // 清不掉退化副本不是致命错：主凭据已经写进系统库，这里只影响整洁度。
+  }
+}