@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/core/lib/license-device.mjs

@@ -0,0 +1,314 @@
+/**
+ * 离线设备绑定 —— **设备码（指纹摘要）+ 比对 + 自助重绑计数**（§3.6，2026-10-03）
+ *
+ * ## 一句话
+ * 新签发的许可载荷里可以带一份 `device` 声明（§3.6③）；客户端只做**相等/不等**比对，
+ * 不解释它、不拿它当"已验签字段"（v1 的签名 payload 仍是 9 项，见下方"局限"）。
+ *
+ * ## ⛔ 指纹只认一项本机事实：`IOPlatformUUID`（D3）
+ * 主机名 / MAC / IP / node 或 dsh 安装路径**一律禁止**当指纹 —— 它们会在客户什么都没干的时候变
+ * （换网络、改 WiFi、USB 网卡插拔、虚拟机克隆；node 一升级路径就变，而现网 dsh-web 的 macOS TCC
+ * 身份正好落在 `/opt/homebrew/bin/node` 上）。拿它们当指纹 = 客户"什么都没干就被判换机"，
+ * **比不绑定更糟**（把授权变成随机故障）。⇒ 本文件是**唯一实现**：只 spawn 一条 `ioreg` 读它。
+ *
+ * ## 局限（如实标注，别让调用方误以为这是防伪）
+ *   · v1 的签名字段固定 9 项（`core/lib/license-file.mjs`）⇒ **`device` 没有进签名**，
+ *     它是"**服务端声明 + 客户端比对**"。改了许可文件里的 `device` 不会让验签失败
+ *     （签名覆盖的仍是那 9 项）—— 也就是说本机制**防君子不防小人**，它防的是"误装到别的机器"，
+ *     不是"伪造授权"。要真防伪得服务端升 v2 把 `device` 纳入 payload（跨仓库，见 §6.2 A-⑨）。
+ *   · 重绑计数落本机 `$ARGENT_DATA_DIR/license-rebind.json` ⇒ 它是**礼貌上限**，
+ *     不是可强制执行的限制：删掉那个文件 = 计数归零。我们不为此加密/混淆（那只会把
+ *     "礼貌"伪装成"安全"）；真正的额度控制只能在服务端签发侧（每设备签几份）。
+ *   · 非 Darwin 平台读不到该事实 ⇒ 按 **unbound 放行 + 明确标注**（不做 fail-closed：
+ *     陪跑式的宿主不保证是 macOS，见 §3.6 风险③）。
+ */
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { resolveDataDir } from './argent-datadir.mjs'
+
+/** 本版只有一种指纹算法；将来换算法时靠这个标识**不破坏老文件**（§3.6③）。 */
+export const DEVICE_ALGO = 'ioplatformuuid-sha256'
+/** 自助重绑次数上限（D2：3 次）；第 4 次起一律拒绝 + 人工指引。 */
+export const MAX_REBINDS = 3
+/** 设备码不匹配的宽限天数（D2：7 天）——宽限内 `state=grace`：提示但不拦。 */
+export const REBIND_GRACE_DAYS = 7
+export const REBIND_FILE = 'license-rebind.json'
+const DAY_MS = 86400000
+
+/**
+ * 读本机指纹**唯一来源**（`ioreg -rd1 -c IOPlatformExpertDevice` 的 IOPlatformUUID 行）。
+ * @param {{exec?:Function, platform?:string}} [opts] exec 供测试注入（夹具不跑真 ioreg）
+ * @returns {{ok:boolean, uuid:string, reason:string, error:string}}
+ *   reason：`ok` ｜ `device_unsupported`（非 Darwin ⇒ 本机不支持设备绑定）｜ `device_read_failed`
+ */
+export function readFingerprint({ exec = spawnSync, platform = process.platform } = {}) {
+  if (platform !== 'darwin') {
+    return { ok: false, uuid: '', reason: 'device_unsupported',
+      error: `本机不支持设备绑定（platform=${platform}）：设备码只认 IOPlatformUUID（仅 macOS 提供）⇒ 按 unbound 放行（不 fail-closed）` }
+  }
+  const r = exec('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { encoding: 'utf8', timeout: 10000 })
+  if (r && r.error) return { ok: false, uuid: '', reason: 'device_read_failed', error: `读本机指纹失败：${r.error.message || r.error}` }
+  const out = String((r && r.stdout) || '')
+  if ((r && r.status) !== 0 && !out) {
+    return { ok: false, uuid: '', reason: 'device_read_failed',
+      error: `ioreg 退出码 ${(r && r.status) ?? '?'}：${String((r && r.stderr) || '').trim().slice(0, 200) || '无输出'}` }
+  }
+  const m = /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(out)
+  if (!m || !m[1].trim()) {
+    return { ok: false, uuid: '', reason: 'device_read_failed', error: 'ioreg 输出里没有 IOPlatformUUID（虚拟机/受限环境？）' }
+  }
+  return { ok: true, uuid: m[1].trim(), reason: 'ok', error: '' }
+}
+
+/**
+ * 设备码 = `sha256("<algo>:<指纹>")` 的 hex（小写，64 位）。
+ * 服务端与客户端**都必须用这一条**（算法标识进摘要 ⇒ 换算法不会撞码）。
+ */
+export function deviceCodeOf(uuid, algo = DEVICE_ALGO) {
+  return createHash('sha256').update(`${algo}:${String(uuid)}`).digest('hex')
+}
+
+/**
+ * 本机设备码（§3.6① 第 1 步 `license request` 就是打印它）。
+ * @returns {{ok:boolean, code:string, algo:string, issuedAt:string, reason:string, error:string, uuid:string}}
+ *   ⚠️ `uuid` 是**内部字段**（只给比对/测试用），对外输出（`--json`）**不要**打印原始 UUID。
+ */
+export function currentDevice({ exec = spawnSync, platform = process.platform, now = new Date() } = {}) {
+  const fp = readFingerprint({ exec, platform })
+  const issuedAt = now instanceof Date ? now.toISOString() : new Date(now).toISOString()
+  if (!fp.ok) return { ok: false, code: '', algo: DEVICE_ALGO, issuedAt, reason: fp.reason, error: fp.error, uuid: '' }
+  return { ok: true, code: deviceCodeOf(fp.uuid), algo: DEVICE_ALGO, issuedAt, reason: 'ok', error: '', uuid: fp.uuid }
+}
+
+/**
+ * 许可载荷里的 `device` 声明（v1 里**未进签名**；只校验形状，不做任何解释）。
+ * ⚠️ v2 的载荷归一要用**更严**的那一份：见文件末尾 `deviceClaimForSignature()`
+ * （要求 `issuedAt` 是可解析时间；形状坏 ⇒ 拒绝，而不是"当没声明"）。
+ * @returns {{code:string, algo:string, issuedAt:string}|null} 缺失/形状非法 ⇒ null（= unbound 放行）
+ */
+export function deviceClaimOf(file) {
+  const d = file && typeof file === 'object' && !Array.isArray(file) ? file.device : null
+  if (!d || typeof d !== 'object' || Array.isArray(d)) return null
+  const code = String(d.code || '').trim()
+  if (!code) return null
+  return { code, algo: String(d.algo || DEVICE_ALGO).trim(), issuedAt: String(d.issuedAt || '') }
+}
+
+// ── 自助重绑计数（落 $ARGENT_DATA_DIR；不联网、不入注册表）────────────────────
+export function rebindStorePath(env = process.env) {
+  return join(resolveDataDir({ env }).dir, REBIND_FILE)
+}
+
+/** 空计数（缺文件/坏文件统一形状：调用方不用判字段存在性）。 */
+function emptyStore() {
+  return { v: 1, count: 0, acceptedCodes: [], rebinds: [], firstMismatchAt: null, broken: false }
+}
+
+/**
+ * 读重绑计数。缺文件 ⇒ 全 0（**首次**运行是正常态，不是错误）；坏文件 ⇒ 全 0 + `broken:true`
+ * （宁可让客户重绑，也不因一个坏计数把人锁死）。
+ */
+export function readRebindStore({ path, env = process.env } = {}) {
+  const p = path || rebindStorePath(env)
+  if (!existsSync(p)) return { ...emptyStore(), path: p }
+  try {
+    const j = JSON.parse(readFileSync(p, 'utf8'))
+    const codes = Array.isArray(j.acceptedCodes) ? j.acceptedCodes.map(String).filter(Boolean) : []
+    return {
+      v: Number(j.v || 1),
+      count: Number.isFinite(Number(j.count)) ? Number(j.count) : 0,
+      acceptedCodes: codes,
+      rebinds: Array.isArray(j.rebinds) ? j.rebinds : [],
+      firstMismatchAt: j.firstMismatchAt ? String(j.firstMismatchAt) : null,
+      broken: false,
+      path: p,
+    }
+  } catch {
+    return { ...emptyStore(), broken: true, path: p }
+  }
+}
+
+/** 原子写计数（0600；失败不抛 —— 计数写不下**不该**让业务/安装失败）。 */
+export function writeRebindStore(store, { path, env = process.env } = {}) {
+  const p = path || rebindStorePath(env)
+  try {
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 })
+    const body = {
+      v: 1,
+      count: Number(store.count || 0),
+      acceptedCodes: [...new Set((store.acceptedCodes || []).map(String).filter(Boolean))],
+      rebinds: store.rebinds || [],
+      firstMismatchAt: store.firstMismatchAt || null,
+    }
+    const tmp = `${p}.tmp`
+    writeFileSync(tmp, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 })
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, p)
+    return { ok: true, path: p }
+  } catch (e) {
+    return { ok: false, path: p, error: String(e.message || e) }
+  }
+}
+
+/**
+ * 设备绑定判定（**纯函数**，唯一判据；调用方不需要也不得另写一套）。
+ *
+ * @param {object} o
+ * @param {object|null} o.claimed  许可载荷里的 `device`（`deviceClaimOf` 的结果；null = unbound）
+ * @param {object} o.current       `currentDevice()` 的结果
+ * @param {object} o.store         `readRebindStore()` 的结果
+ * @param {number} [o.now]
+ * @returns {{binding:'unbound'|'match'|'rebound'|'mismatch'|'unsupported', reason:string,
+ *            sanctioned:boolean, state:'valid'|'grace'|'denied', graceUntil:string|null,
+ *            graceLeftDays:number|null, rebindsLeft:number, machineCode:string, claimedCode:string,
+ *            note:string, warnings:string[]}}
+ *   binding：unbound（无声明 ⇒ **放行**，存量许可不受影响）｜match ｜rebound（自助重绑过 ⇒ 放行）
+ *            ｜mismatch（不匹配：宽限内 grace / 超限或次数用尽 denied）｜unsupported（读不到指纹 ⇒ 放行+标注）
+ */
+export function bindingOf({ claimed = null, current, store, now = Date.now() } = {}) {
+  const cur = current || { ok: false, code: '', reason: 'device_read_failed', error: '未读本机指纹' }
+  const st = store || emptyStore()
+  const rebindsLeft = Math.max(0, MAX_REBINDS - Number(st.count || 0))
+  const machineCode = cur.code || ''
+  const base = { graceUntil: null, graceLeftDays: null, rebindsLeft, machineCode, claimedCode: claimed ? claimed.code : '', warnings: [] }
+
+  // ① 无 device 声明 ⇒ unbound 放行（D1-兼容：**不得**让存量许可失效）
+  if (!claimed) {
+    return { ...base, binding: 'unbound', reason: 'unbound', sanctioned: true, state: 'valid',
+      note: '许可未声明设备（unbound）⇒ 不做比对、按今天的三态判（存量许可继续有效）' }
+  }
+  // ② 读不到本机指纹 / 算法不认识 ⇒ 无法比对 ⇒ 放行 + **明确标注**（不做 fail-closed）
+  if (!cur.ok) {
+    return { ...base, binding: 'unsupported', reason: cur.reason || 'device_read_failed', sanctioned: true, state: 'valid',
+      note: `${cur.error || '读不到本机指纹'} ⇒ 无法比对，按 unbound 放行并如实标注`,
+      warnings: ['本机读不到设备指纹：本次**没有**做设备绑定校验（不是"校验通过"）'] }
+  }
+  if (claimed.algo && claimed.algo !== DEVICE_ALGO) {
+    return { ...base, binding: 'unsupported', reason: 'device_algo_unknown', sanctioned: true, state: 'valid',
+      note: `许可声明的指纹算法 ${claimed.algo} 本客户端不认识（只认 ${DEVICE_ALGO}）⇒ 无法比对，按 unbound 放行`,
+      warnings: [`设备指纹算法不认识（${claimed.algo}）⇒ 本次没有做设备绑定校验`] }
+  }
+  // ③ 相等 / 之前自助重绑过 ⇒ 放行
+  if (claimed.code === machineCode) {
+    return { ...base, binding: 'match', reason: 'device_match', sanctioned: true, state: 'valid',
+      note: `设备码一致（${machineCode.slice(0, 12)}…）` }
+  }
+  if ((st.acceptedCodes || []).includes(claimed.code)) {
+    return { ...base, binding: 'rebound', reason: 'device_rebound', sanctioned: true, state: 'valid',
+      note: `本机自助重绑过这份许可的设备码（已用 ${Number(st.count || 0)}/${MAX_REBINDS} 次）⇒ 放行` }
+  }
+
+  // ④ 不匹配：次数用尽 ⇒ 拒绝；宽限内 ⇒ grace（提示但不拦）；超宽限 ⇒ 拒绝
+  if (rebindsLeft <= 0) {
+    return { ...base, binding: 'mismatch', reason: 'rebind_exhausted', sanctioned: false, state: 'denied',
+      claimedCode: claimed.code,
+      note: `设备码不匹配，且自助重绑 ${MAX_REBINDS} 次已用尽 ⇒ 需人工：让服务端重签一份绑定本机设备码的许可`
+        + `（本机设备码见 \`argent license request\`），或人工重绑（见 §3.6② D2）`,
+      warnings: ['设备码不匹配且自助重绑次数已用尽（rebind_exhausted）⇒ 拒绝'] }
+  }
+  const started = st.firstMismatchAt ? Date.parse(st.firstMismatchAt) : NaN
+  const graceUntilMs = (Number.isFinite(started) ? started : now) + REBIND_GRACE_DAYS * DAY_MS
+  const graceUntil = new Date(graceUntilMs).toISOString()
+  if (now > graceUntilMs) {
+    return { ...base, binding: 'mismatch', reason: 'device_mismatch', sanctioned: false, state: 'denied', graceUntil, graceLeftDays: 0,
+      note: `设备码不匹配且 ${REBIND_GRACE_DAYS} 天宽限已过（至 ${graceUntil}）⇒ 拒绝；自助重绑还剩 ${rebindsLeft} 次`
+        + '（`argent license install --file <许可> --rebind --apply`）',
+      warnings: [`设备码不匹配且宽限期已过（device_mismatch）⇒ 拒绝`] }
+  }
+  return { ...base, binding: 'mismatch', reason: 'device_mismatch', sanctioned: true, state: 'grace', graceUntil,
+    graceLeftDays: Math.max(0, (graceUntilMs - now) / DAY_MS),
+    note: `设备码不匹配（本机 ${machineCode.slice(0, 12)}… ≠ 许可 ${claimed.code.slice(0, 12)}…）`
+      + ` ⇒ 宽限期内放行（剩 ${Math.max(0, (graceUntilMs - now) / DAY_MS).toFixed(1)} 天，至 ${graceUntil}）`
+      + `，请尽快自助重绑（还剩 ${rebindsLeft} 次）或让服务端重签`,
+    warnings: [`设备码与许可声明的设备不一致（宽限期内，剩 ${Math.max(0, (graceUntilMs - now) / DAY_MS).toFixed(1)} 天）—— 业务放行，但必须上报`] }
+}
+
+/**
+ * 记一次"自助重绑"（**写**：只在真写路径调用，dry-run 绝不调）。
+ * 计数 +1、把被接受的设备码记进 `acceptedCodes`（此后 `bindingOf` 判 `rebound`）。
+ */
+export function recordRebind(store, { code, at = new Date().toISOString(), path, env = process.env } = {}) {
+  const next = {
+    v: 1,
+    count: Number(store?.count || 0) + 1,
+    acceptedCodes: [...(store?.acceptedCodes || []), String(code || '')].filter(Boolean),
+    rebinds: [...(store?.rebinds || []), { at, code: String(code || '') }],
+    firstMismatchAt: store?.firstMismatchAt || at,
+  }
+  const w = writeRebindStore(next, { path, env })
+  return { ...next, ok: w.ok, path: w.path, error: w.error }
+}
+
+/** 记"第一次发现不匹配"的时刻（宽限 7 天的起点；已记过就不动 —— 幂等）。 */
+export function noteMismatch(store, { at = new Date().toISOString(), path, env = process.env } = {}) {
+  if (store?.firstMismatchAt) return { ...store, ok: true, path: store.path }
+  const next = {
+    v: 1,
+    count: Number(store?.count || 0),
+    acceptedCodes: store?.acceptedCodes || [],
+    rebinds: store?.rebinds || [],
+    firstMismatchAt: at,
+  }
+  const w = writeRebindStore(next, { path, env })
+  return { ...next, ok: w.ok, path: w.path, error: w.error }
+}
+
+/** 只读展示用：计数文件是否可读、权限是否 0600（不拦人，只如实报）。 */
+export function rebindStoreInfo({ path, env = process.env } = {}) {
+  const p = path || rebindStorePath(env)
+  let mode = null
+  try { if (existsSync(p)) mode = `0${(statSync(p).mode & 0o777).toString(8)}` } catch { /* 拿不到不致命 */ }
+  return { path: p, mode }
+}
+
+// ── v2 签名载荷里的 device 形状（**严格版**，2026-10-03）──────────────────────
+// 与上面的 `deviceClaimOf` 的**唯一区别**（v1 判据一字不改，故不合并）：
+//   · `deviceClaimOf` 面向 v1（**不参与签名**）⇒ 宽容：缺字段补默认、形状坏 ⇒ 当没声明（放行）；
+//   · 本函数面向 v2（**要进签名**）⇒ 严格：三键必须写全且合法，形状坏 ⇒ **拒绝**（malformed），
+//     绝不"当没声明"（否则"绑定写坏了"会被静默降级成"没绑定"= 一次静默的授权放宽）。
+// 缺位（键不存在 **或** 值为 null）= **未声明**，是**合法**状态；它同样进签名（"缺位"被覆盖）。
+
+/** 服务端/客户端共用的时间形态：ISO（UTC、毫秒精度）。不可解析 ⇒ null。 */
+function toIsoStrict(v) {
+  if (v === null || v === undefined || v === '') return null
+  const t = Date.parse(String(v))
+  return Number.isFinite(t) ? new Date(t).toISOString() : null
+}
+
+/**
+ * 归一无符号的 v2 `device` 声明（**签名载荷专用**）。
+ * @returns {{ok:boolean, present:boolean, device:{code:string,algo:string,issuedAt:string}|null, warning:string}}
+ *   ok:false ⇒ 形状非法（调用方按 `malformed` 拒绝，**不得**退回 unbound）
+ *   present:false ⇒ 未声明（缺位或 null）⇒ payload 里**不含** device 键
+ */
+export function deviceClaimForSignature(file) {
+  const f = file && typeof file === 'object' && !Array.isArray(file) ? file : null
+  const raw = f ? f.device : null
+  if (raw === null || raw === undefined) return { ok: true, present: false, device: null, warning: '' }
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ok: false, present: true, device: null,
+      warning: 'v2 许可的 `device` 必须是对象（三键：code/algo/issuedAt）⇒ 判 malformed（不降级成 unbound）' }
+  }
+  // 三键**必须写全**（缺任一 ⇒ malformed）：签名载荷按"恰好这三键"构造，
+  // 让"缺 algo ⇒ 客户端补默认"这类隐形归一消失（那会让两侧 payload 悄悄漂移）。
+  const missing = ['code', 'algo', 'issuedAt'].filter((k) => raw[k] === undefined || raw[k] === null || raw[k] === '')
+  if (missing.length) {
+    return { ok: false, present: true, device: null,
+      warning: `v2 许可的 \`device\` 缺字段 ${missing.join('/')}（v2 要求三键写全：code/algo/issuedAt）⇒ 判 malformed` }
+  }
+  if (typeof raw.code !== 'string' || !raw.code.trim()) {
+    return { ok: false, present: true, device: null, warning: 'v2 许可的 `device.code` 必须是非空字符串 ⇒ 判 malformed' }
+  }
+  if (typeof raw.algo !== 'string' || !raw.algo.trim()) {
+    return { ok: false, present: true, device: null, warning: 'v2 许可的 `device.algo` 必须是非空字符串 ⇒ 判 malformed' }
+  }
+  const issuedAt = toIsoStrict(raw.issuedAt)
+  if (!issuedAt) {
+    return { ok: false, present: true, device: null,
+      warning: 'v2 许可的 `device.issuedAt` 不是可解析时间（必须是与 issuedAt/expiresAt 同规的 ISO 形态）⇒ 判 malformed' }
+  }
+  // 只取这三键进签名：device 里的**额外键不参与签名**，客户端也**不得**读它们（多键不等于多判据）
+  return { ok: true, present: true, device: { code: raw.code.trim(), algo: raw.algo.trim(), issuedAt }, warning: '' }
+}