@adep/cli 0.4.4 → 0.4.6

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 {
+    // 清不掉退化副本不是致命错：主凭据已经写进系统库，这里只影响整洁度。
+  }
+}