@whyshu/argent-engine 0.0.0-stage → 0.6.0

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

@@ -0,0 +1,349 @@
+/**
+ * 离线签名许可（客户端验签，2026-09-30）
+ *
+ * ## 为什么需要它
+ * 客户机是「BYO（自带 DeepSeek Key）+ **不登录问述账号**」⇒ 机器上没有账号 JWT，
+ * `/api/argent/entitlements`、`/api/argent/lease` 这类要鉴权的接口一个都调不了。
+ * 授权改为一份由服务端**离线签名**的许可文件（`~/.dsh/argent/license.json`）：
+ * 装机时由 `scripts/install-license.mjs` 验签后落盘，之后**断网也能自证授权**。
+ *
+ * ## 签名契约（与服务端 `whyshu-svr/src/services/licenseFile.js` **逐字节一致**，改一侧必须同步另一侧）
+ *   payload = canonicalJson({ v, userId, capabilities, verticals, seats, issuedAt, expiresAt, graceDays, instanceHint })
+ *   sig     = HMAC-SHA256(LICENSE_SIGNING_SECRET, payload) 的 hex（小写）
+ *   canonicalJson = 键按字典序、**无空白**、数组保序（嵌套同样规则）
+ * v1 的签名字段集**固定为上面 9 项**（多余字段不参与签名）。
+ *
+ * ## v2（2026-10-03）：把 `device` 纳入签名 —— 精确契约（跨仓库唯一口径）
+ * ```text
+ * payloadV2 = canonicalJson({
+ *   v: 2, userId, capabilities, verticals, seats, issuedAt, expiresAt, graceDays, instanceHint,  // ← 与 v1 同 9 项
+ *   device: { code, algo, issuedAt }                                                            // ← 仅当**声明**了设备
+ * })
+ * ```
+ * 规则（三处必须逐字节一致：本模块 / 服务端 `licenseFile.js` / `plugins/argent-core` 的内联退路）：
+ *   ① **字段集随 `v` 定**：`v:1` ⇒ 恰好 9 项（`device` **被忽略**，哪怕写了也不进签名 —— v1 判据一字不改）；
+ *      `v:2` ⇒ 9 项 + **device 键**。`v` 不在 {1,2} ⇒ `bad_version`。
+ *   ② **"缺位"也是被签名的状态**：`v:2` 未声明设备（`device` 键不存在 **或** 值为 `null`）⇒ payloadV2 **不含**
+ *      `device` 键。⇒ 事后往一份"未声明"的 v2 许可里塞 `device` 会改变 payload ⇒ **bad_signature**。
+ *   ③ 从一份"已声明"的 v2 许可里**摘掉** `device`（保留 `v:2`，或把 `v` 降成 1 重拼载荷）⇒ payload 变 ⇒
+ *      **bad_signature**（这就是 v1 做不到的那件事：v1 里改 `device` 不影响验签）。
+ *   ④ `device` 声明的三键**必须写全**（`code`/`algo`/`issuedAt`）；缺任一或形状非法 ⇒ **malformed**
+ *      （**不得**降级成 unbound：那会把"绑定写坏了"静默变成"没绑定"= 一次静默的授权放宽）。
+ *      `device` 内的**额外键不参与签名**，客户端也**不得**读（判据只有这三键）。
+ *   ⑤ `device.issuedAt` 与 `issuedAt`/`expiresAt` 同规：ISO(UTC, 毫秒) —— 服务端必须写 `toISOString()` 形态。
+ *   ⑥ `device` 必须**经 v2 验签通过**才可采信：`loadLicenseFile().deviceSigned`（= `签名版本 2 ∧ 验签通过`）
+ *      是唯一的机器可判形式；v1 的 `device` 仍只是"**服务端声明 + 客户端比对**"（`deviceSigned:false`）。
+ * ⚠️ **v2 也不是"防伪"的全部**（如实标注）：签名是 **HMAC-SHA256（对称密钥）**，而验签方**必须持有**
+ * 同一把密钥 ⇒ 能读 `license.secret` 的人**仍然可以自签一份**。v2 堵掉的是**最低成本的那条绕过**
+ * （改字段/摘字段不改签名）与"混用/降级重拼"；要真正防伪造得换成**非对称签名**（Ed25519，客户端只拿公钥，
+ * 见 §3.6③ 与 `docs/Argent-陪跑式交付-实施方案.md` 服务端方案的 v3 候选）。
+ *
+ * ## 密钥从哪来（**绝不硬编码**）
+ *   ① 环境变量 `ARGENT_LICENSE_SECRET`；② `~/.dsh/argent/license.secret`（600）。
+ *   两处都没有 ⇒ `reason: 'no_secret'` —— **拒绝**，而不是"没密钥就当通过"。
+ *
+ * ## 口径（与服务端 entitlement.checkAccess 对齐）
+ *   capabilities：**白名单**，空数组 = 什么能力都没有（不是"全部"）；
+ *   verticals   ：空数组 = 不限业务线；
+ *   到期        ：`expiresAt` 之后仍在 `graceDays` 内 ⇒ `ok:true` + `inGrace:true`（放行但必须告警）；
+ *                 超出宽限 ⇒ `ok:false` + `reason:'expired'`（fail-closed）。
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolveDataDir } from './argent-datadir.mjs';
+import { deviceClaimForSignature, deviceClaimOf } from './license-device.mjs';
+import { join } from 'node:path';
+
+/** v1 = 默认版本（判据一字不改）；v2 = 把 `device` 纳入签名（2026-10-03）。 */
+export const LICENSE_FILE_VERSION = 1;
+export const LICENSE_FILE_VERSION_MAX = 2;
+/** 本客户端认识的签名版本（`v` 不在此列 ⇒ `bad_version`）。 */
+export const LICENSE_SIGNATURE_VERSIONS = [1, 2];
+export const DEFAULT_GRACE_DAYS = 14;
+/** v1 参与签名的字段集（顺序无关，规范化时按键排序）。 */
+export const LICENSE_FILE_FIELDS = [
+  'v', 'userId', 'capabilities', 'verticals', 'seats', 'issuedAt', 'expiresAt', 'graceDays', 'instanceHint',
+];
+/** v2 参与签名的字段集 = v1 的 9 项 + `device`（**仅当声明了设备**；缺位时 payload 里不含该键）。 */
+export const LICENSE_FILE_V2_FIELDS = [...LICENSE_FILE_FIELDS, 'device'];
+/** `device` 声明进签名的**恰好**三键（额外键不参与签名、客户端不读）。 */
+export const DEVICE_CLAIM_FIELDS = ['code', 'algo', 'issuedAt'];
+const DAY_MS = 86400000;
+
+/**
+ * 数据目录：**唯一判据在内核** `core/lib/argent-datadir.mjs`
+ * （`ARGENT_DATA_DIR → $DSH_HOME/argent → ~/.dsh/argent`，2026-10-01 统一）。
+ * 此前这里只看 `ARGENT_DATA_DIR`、**不看 `DSH_HOME`** ⇒ 桌面端隔离实例会读生产许可文件。
+ * ⚠️ 与 `plugins/argent-core` 的 `licenseDataDir()` 必须同判据（那边同样取内核 `DATA_DIR`）。
+ */
+export function dataDir() {
+  return resolveDataDir({ env: process.env }).dir;
+}
+export function defaultLicensePath() {
+  return join(dataDir(), 'license.json');
+}
+export function defaultSecretPath() {
+  return join(dataDir(), 'license.secret');
+}
+
+/**
+ * 规范化 JSON：键按字典序、无空格、数组保序。
+ * 必须与服务端逐字节一致 —— 任何"更漂亮"的写法都会让两侧哈希漂移（历史教训：租约签名串漂移过一次）。
+ */
+export function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map((v) => canonicalJson(v)).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+/** 时间一律归一成 ISO（UTC，毫秒精度），容忍 `+08:00` / 无毫秒的写法。 */
+function toIso(v) {
+  if (v === null || v === undefined || v === '') return '';
+  const d = new Date(v);
+  return Number.isNaN(d.getTime()) ? '' : d.toISOString();
+}
+
+const uniqSorted = (arr) => [...new Set((Array.isArray(arr) ? arr : []).map((x) => String(x)).filter(Boolean))].sort();
+
+/** 归一化到 v1 字段集；时间不可解析 ⇒ null（判 malformed，绝不"宽容"成永不过期）。 */
+export function normalizeLicenseFile(file) {
+  const f = file && typeof file === 'object' ? file : {};
+  const issuedAt = toIso(f.issuedAt);
+  const expiresAt = toIso(f.expiresAt);
+  if (!issuedAt || !expiresAt) return null;
+  const graceDays = Number(f.graceDays ?? DEFAULT_GRACE_DAYS);
+  return {
+    v: Number(f.v ?? LICENSE_FILE_VERSION),
+    userId: String(f.userId ?? ''),
+    capabilities: uniqSorted(f.capabilities),
+    verticals: uniqSorted(f.verticals),
+    seats: Number(f.seats ?? 1),
+    issuedAt,
+    expiresAt,
+    graceDays: Number.isFinite(graceDays) && graceDays >= 0 ? graceDays : DEFAULT_GRACE_DAYS,
+    instanceHint: String(f.instanceHint ?? ''),
+  };
+}
+
+/**
+ * v2 归一（**只增不改** v1）：v1 的 9 项（`v` 替换为 2）+ 可选的 `device`。
+ *   · `device` 缺位（键不存在或 null）⇒ 结果里**没有** `device` 键（缺位本身进签名）
+ *   · `device` 存在 ⇒ 必须三键合法（形状判据在 `license-device.mjs#deviceClaimForSignature`）
+ * @returns {object|null} 时间不可解析/`device` 形状非法 ⇒ null（调用方按 `malformed` 拒绝）
+ */
+export function normalizeLicenseFileV2(file) {
+  const base = normalizeLicenseFile(file);
+  if (!base) return null;
+  const claim = deviceClaimForSignature(file);
+  if (!claim.ok) return null;
+  const out = { ...base, v: 2 };
+  if (claim.device) out.device = claim.device;      // 只放签名的三键；额外键不入载荷
+  return out;
+}
+
+/** 签名版本（1 / 2）；不认识（缺失、非数字、v3…）⇒ null。 */
+export function signatureVersionOf(file) {
+  const v = Number(file && typeof file === 'object' ? file.v : NaN);
+  return LICENSE_SIGNATURE_VERSIONS.includes(v) ? v : null;
+}
+
+/** 按 `v` 取签名载荷（v1 9 项 / v2 9 项 + 可选 device）；形状非法 ⇒ null。 */
+export function signaturePayloadOf(file) {
+  const version = signatureVersionOf(file);
+  if (version === null) return null;
+  const normalized = version === 2 ? normalizeLicenseFileV2(file) : normalizeLicenseFile(file);
+  return normalized ? { version, normalized, payload: canonicalJson(normalized) } : null;
+}
+
+/**
+ * **本地签名**（自签 / 离线演练 / 与服务端同口径的签发实现）。
+ *
+ * ⛔ 它**不是**签发服务：真正的签发在服务端（`whyshu-svr`）。本函数存在的理由有两个 ——
+ *   ① 让"离线激活"闭环可在**没有服务端**的场合演练（`license request` → 自签 → `install --file`）；
+ *   ② 把 v2 载荷的构造**只写一份**（`scripts/install-license.mjs --sign-v2` 与自签工具都用它），
+ *      否则第二个实现早晚与契约漂移。
+ * ⚠️ 它**不扩权**：`capabilities/verticals/seats/issuedAt/expiresAt/graceDays` 逐字取自入参文件，
+ *    调用方必须先 `verifyLicenseFile()` 验过原件再重签（`install-license.mjs` 就是这么做的）。
+ *
+ * @param {object} file    许可（v1 或 v2 形态；`v` 由 `version` 决定）
+ * @param {string} secret  签名密钥
+ * @param {object} [opts]  { version=1|2, now=Date }
+ * @returns {{ok:true, file:object, payload:string, signatureVersion:number}|{ok:false, reason:string, warning?:string}}
+ */
+export function signLicenseFile(file, secret, { version = LICENSE_FILE_VERSION, now = new Date() } = {}) {
+  const v = Number(version);
+  if (!LICENSE_SIGNATURE_VERSIONS.includes(v)) return { ok: false, reason: 'bad_version' };
+  const key = String(secret || '');
+  if (!key) return { ok: false, reason: 'no_secret' };
+  const src = { ...(file && typeof file === 'object' && !Array.isArray(file) ? file : {}), v };
+  if (v === 2) {
+    const claim = deviceClaimForSignature(src);
+    if (!claim.ok) return { ok: false, reason: 'malformed', warning: claim.warning };
+  }
+  const normalized = v === 2 ? normalizeLicenseFileV2(src) : normalizeLicenseFile(src);
+  if (!normalized || !normalized.userId) return { ok: false, reason: 'malformed' };
+  // **只签不改**：本函数不动任何字段值（`issuedAt` 由调用方决定 —— 服务端 `buildLicenseFile`
+  // 自己把 issuedAt 设成"这份文件的签发时刻"；本地重签是否刷新它由 `install-license --sign-v2` 定）。
+  const payload = canonicalJson(normalized);
+  const sig = createHmac('sha256', key).update(payload).digest('hex');
+  return { ok: true, file: { ...normalized, sig }, payload, signatureVersion: v };
+}
+
+/** 宽限截止时刻（ISO）；到期时间不可解析 ⇒ null。 */
+export function graceUntilOf(file) {  const exp = new Date(file?.expiresAt).getTime();
+  if (!Number.isFinite(exp)) return null;
+  const g = Number(file?.graceDays ?? DEFAULT_GRACE_DAYS);
+  return new Date(exp + (Number.isFinite(g) && g >= 0 ? g : DEFAULT_GRACE_DAYS) * DAY_MS).toISOString();
+}
+
+/**
+ * 取签名密钥：`ARGENT_LICENSE_SECRET` → `~/.dsh/argent/license.secret`（600）。
+ * @returns {{secret:string, source:string, warning:string|null}}
+ */
+export function resolveSecret({ secret, secretPath } = {}) {
+  if (secret) return { secret: String(secret), source: 'explicit', warning: null };
+  const fromEnv = String(process.env.ARGENT_LICENSE_SECRET || '').trim();
+  if (fromEnv) return { secret: fromEnv, source: 'env', warning: null };
+  const p = secretPath || defaultSecretPath();
+  if (!existsSync(p)) return { secret: '', source: 'none', warning: null };
+  let warning = null;
+  try {
+    const mode = statSync(p).mode & 0o777;
+    // 权限过松只告警不拒绝：许可本身是签名的（泄漏的是"能不能验签"而不是"能不能伪造"），
+    // 但密钥文件可读 = 同机其他用户可以伪造许可 ⇒ 必须响亮提示（install-license.mjs 落盘时强制 600）。
+    if (mode & 0o077) warning = `密钥文件权限过松（0${mode.toString(8)}，应为 0600）：${p}`;
+  } catch { /* stat 失败不影响读取 */ }
+  let text = '';
+  try { text = readFileSync(p, 'utf-8').trim(); } catch { /* 读不到按缺密钥处理 */ }
+  return { secret: text, source: text ? 'file' : 'none', warning };
+}
+
+/** 空结果（缺文件/缺密钥/坏文件统一形状，调用方不用判字段存在性）。 */
+function emptyResult(reason, extra = {}) {
+  return {
+    ok: false, reason, capabilities: [], verticals: [], userId: '', seats: 0,
+    instanceHint: '', issuedAt: '', expiresAt: '', graceDays: DEFAULT_GRACE_DAYS,
+    graceUntil: null, inGrace: false, warnings: [],
+    // 签名版本 / 设备是否进签名：**判不出来就 null / false**（绝不乐观默认）
+    signatureVersion: null, deviceSigned: false, ...extra,
+  };
+}
+
+/**
+ * 验签 + 判期（**唯一判定入口**）。
+ *
+ * v1 / v2 的分派在**这里**（唯一一处）：`v:1` 走 9 项载荷（判据与 2026-09-30 版**逐字一致**）；
+ * `v:2` 走 9 项 + 可选 `device` 的载荷。载荷定义见文件头 "v2 精确契约"。
+ *
+ * @param {object} obj       许可文件内容（已 JSON.parse）
+ * @param {object} opts      { secret, now }（secret 缺省按 resolveSecret 取；now 供测试注入）
+ * @returns {{ok:boolean, reason:string, capabilities:string[], verticals:string[], userId:string,
+ *            seats:number, issuedAt:string, expiresAt:string, graceDays:number,
+ *            graceUntil:string|null, inGrace:boolean, warnings:string[],
+ *            signatureVersion:1|2|null, deviceSigned:boolean}}
+ *   reason：ok ｜ in_grace ｜ bad_signature ｜ expired ｜ malformed ｜ bad_version ｜ no_secret
+ *   `deviceSigned` = **签名版本为 2 且验签通过**（此刻 `device` 声明的内容/缺位才真的被覆盖）；
+ *   验签失败/版本未知一律 `false` —— 免得"没验过的字段"被读成已验签（§3.6③ 的机器可判形式）。
+ */
+export function verifyLicenseFile(obj, { secret, now = Date.now(), secretPath } = {}) {
+  const key = resolveSecret({ secret, secretPath });
+  if (!key.secret) return emptyResult('no_secret', { warnings: key.warning ? [key.warning] : [] });
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return emptyResult('malformed');
+  const version = signatureVersionOf(obj);
+  if (version === null) return emptyResult('bad_version');
+  const warnings = key.warning ? [key.warning] : [];
+  // ── 形状归一（**先形状、后验签**：形状坏 ⇒ malformed，不做"猜一半"的验签）──
+  let normalized = null;
+  if (version === 2) {
+    const claim = deviceClaimForSignature(obj);
+    // device 形状坏 ⇒ **拒绝**（不降级成 unbound）：否则"绑定写坏了"会静默变成"没绑定"
+    if (!claim.ok) return emptyResult('malformed', { warnings: [...warnings, claim.warning], signatureVersion: 2 });
+    normalized = normalizeLicenseFileV2(obj);
+  } else {
+    normalized = normalizeLicenseFile(obj);
+  }
+  if (!normalized || !normalized.userId) return emptyResult('malformed', { warnings, signatureVersion: version });
+
+  const base = {
+    capabilities: normalized.capabilities, verticals: normalized.verticals, userId: normalized.userId,
+    seats: normalized.seats, instanceHint: normalized.instanceHint, issuedAt: normalized.issuedAt,
+    expiresAt: normalized.expiresAt, graceDays: normalized.graceDays, graceUntil: graceUntilOf(normalized),
+    signatureVersion: version,
+    deviceSigned: false,                       // 只有**验签通过**才置 true（下面两处出口）
+  };
+  // 常量时间比较（长度不等直接判否；hex 解不出内容也算否，绝不放行）
+  const actual = Buffer.from(String(obj.sig || '').toLowerCase(), 'hex');
+  const expected = Buffer.from(createHmac('sha256', key.secret).update(canonicalJson(normalized)).digest('hex'), 'hex');
+  if (actual.length !== expected.length || actual.length === 0 || !timingSafeEqual(actual, expected)) {
+    return emptyResult('bad_signature', { ...base, warnings });
+  }
+  const signed = { ...base, deviceSigned: version === 2 };
+  const exp = new Date(normalized.expiresAt).getTime();
+  const graceUntil = signed.graceUntil;
+  if (now > exp) {
+    if (now > new Date(graceUntil).getTime()) {
+      return emptyResult('expired', { ...signed, warnings: [...warnings, `许可已于 ${normalized.expiresAt} 到期（宽限 ${normalized.graceDays} 天已用完）`] });
+    }
+    const leftDays = Math.max(0, (new Date(graceUntil).getTime() - now) / DAY_MS);
+    return {
+      ok: true, reason: 'in_grace', ...signed, inGrace: true,
+      warnings: [...warnings, `许可已过期，处于宽限期（剩 ${leftDays.toFixed(1)} 天，至 ${graceUntil}）—— 请尽快续期`],
+    };
+  }
+  return { ok: true, reason: 'ok', ...signed, inGrace: false, warnings };
+}
+
+/**
+ * 读取并验签本地许可文件。
+ *
+ * ⚠️ **`deviceClaimed` 是不是"已验签的字段"要看 `deviceSigned`**：
+ *   · `v:1` ⇒ 签名只覆盖 `LICENSE_FILE_FIELDS` 那 9 项，载荷里多出来的 `device` **不参与签名**
+ *     ⇒ `deviceSigned:false`：它是"**服务端声明 + 客户端比对**"，**不得**被当成已验签字段引用；
+ *   · `v:2` **验签通过** ⇒ `deviceSigned:true`：`device` 的内容（或它的**缺位**）确实被签名覆盖。
+ *   判据只有这一处（`signatureVersion` + `deviceSigned`），调用方不要自己再判一遍版本。
+ *
+ * @param {string} [path]   缺省 `~/.dsh/argent/license.json`（`ARGENT_DATA_DIR` 可隔离）
+ * @returns 同 verifyLicenseFile，外加 `path` / `source` / `mode` / `deviceClaimed`；文件不存在 ⇒ `{ok:false, reason:'missing'}`
+ */
+export function loadLicenseFile(path, { secret, now = Date.now(), secretPath } = {}) {
+  const p = path || defaultLicensePath();
+  if (!existsSync(p)) return { ...emptyResult('missing'), path: p, deviceClaimed: null };
+  let mode = null;
+  try { mode = statSync(p).mode & 0o777; } catch { /* 拿不到权限不致命 */ }
+  let raw = '';
+  try { raw = readFileSync(p, 'utf-8'); } catch (e) {
+    return { ...emptyResult('unreadable', { warnings: [String(e.message)] }), path: p, mode, deviceClaimed: null };
+  }
+  let obj = null;
+  try { obj = JSON.parse(raw); } catch {
+    return { ...emptyResult('malformed', { warnings: ['许可文件不是合法 JSON'] }), path: p, mode, deviceClaimed: null };
+  }
+  const r = verifyLicenseFile(obj, { secret, now, secretPath });
+  const warnings = [...r.warnings];
+  // 0600 检查：只是卫生要求（许可内容是公开可读也不影响安全性），过松就告警，不拦人
+  if (mode !== null && (mode & 0o077)) warnings.push(`许可文件权限过松（0${mode.toString(8)}，应为 0600）：${p}`);
+  return { ...r, warnings, path: p, mode, deviceClaimed: deviceClaimOf(obj) };
+}
+
+/**
+ * 能力判定（与服务端 `checkAccess` 同口径）：
+ *   ① 许可未通过验签/已超宽限 ⇒ 拒；② capabilityId 为空 ⇒ 只看许可有效性；
+ *   ③ 否则 `capabilities` 必须**显式包含**该 id（空数组 = 什么都不许，不是"全部"）。
+ * @param {object} license  **验签过**的许可（verifyLicenseFile/loadLicenseFile 的结果或文件对象）
+ * @param {string} capabilityId
+ * @param {object} [opts]   { now }
+ */
+export function capabilityAllowed(license, capabilityId, { now = Date.now() } = {}) {
+  if (!license || typeof license !== 'object') return false;
+  if (license.ok === false) return false;                       // 传进来的是失败结果 ⇒ 直接拒
+  const exp = new Date(license.expiresAt).getTime();
+  if (!Number.isFinite(exp)) return false;                      // 判不了到期 ⇒ 拒（fail-closed）
+  const g = Number(license.graceDays ?? DEFAULT_GRACE_DAYS);
+  const graceUntil = exp + (Number.isFinite(g) && g >= 0 ? g : DEFAULT_GRACE_DAYS) * DAY_MS;
+  if (now > graceUntil) return false;                           // 超出宽限 ⇒ 全部拒
+  const id = String(capabilityId || '');
+  if (!id) return true;
+  const caps = Array.isArray(license.capabilities) ? license.capabilities.map(String) : [];
+  return caps.includes(id);
+}

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

@@ -0,0 +1,123 @@
+/**
+ * 写类 verb 的**许可闸门**（§3.6① 第 4 步 + §3.5① 纪律 1）—— 薄封装，**不复制任何判据**。
+ *
+ * ## 它做什么
+ * 「任何写操作前先判 `valid|grace|denied`」：本模块调**既有** `scripts/license-gate.mjs`
+ * （flow-trigger.sh:238 用的同一个模块、同一套 `off/observe/enforce` 语义、同一个证据文件），
+ * 把它的 `--json` 结论翻译成写类 verb 要的形状。判定与取证**一份都不重写**：
+ *   · 判定 = `license-gate.mjs` → `evaluate()` → `core/lib/license-verdict.mjs`（三态 + 设备）
+ *   · 证据 = `<数据目录>/license-gate.jsonl`（每次判定一行；observe 也留，`decision:would_block`）
+ *
+ * ## 模式（`ARGENT_LICENSE_ENFORCE`，与 flow-trigger.sh 同一套取值）
+ *   `0`/`off`   **不查**（连判定都不做；也不落证据）—— 逃生阀
+ *   `observe`   **默认**：照常判定 + 留证据，但**绝不拦**（`would_block` 只写进证据）
+ *   `enforce`   判定不可用 ⇒ 写操作被拒：非零 + `reason:"license_denied"`（**零副作用**：不写台账/不落盘）
+ *
+ * ## 失败形态（与 flow-trigger.sh 同口径：**宁可不拦，不可误停**）
+ * 闸门自己跑不起来（脚本缺失/输出不可解析/超时）⇒ **放行 + 响亮告警**，证据里记 `gate_error`。
+ * 理由：闸门是我们的零件，坏了不该把客户的业务停掉 —— 与 flow-trigger.sh 对缺 `license-gate.mjs`
+ * 的既有处置逐字一致（"旧机器：响亮告警但不停派"）。
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 与 `scripts/license-gate.mjs#normalizeMode` 同取值（这里只做"要不要查"的分支，不重写判定）。 */
+export function gateModeOf(env = process.env) {
+  const v = String(env.ARGENT_LICENSE_ENFORCE ?? '').trim().toLowerCase()
+  if (['0', 'off', 'false', 'no', 'skip'].includes(v)) return 'off'
+  if (['enforce', '1', 'true', 'yes', 'on'].includes(v)) return 'enforce'
+  return 'observe'
+}
+
+/**
+ * 跑一次闸门判定。
+ *
+ * @param {object} o
+ * @param {string} o.repo     仓库根（找 `scripts/license-gate.mjs`）
+ * @param {string} o.flow     流程名（仅证据/文案）
+ * @param {string} [o.cap]    能力 id（缺省用 flow）—— 能力门判据在 check-license 里，不在这里
+ * @param {string} [o.vertical] 业务线（缺省不传 ⇒ 只看能力）
+ * @param {object} [o.env]    环境（`ARGENT_LICENSE_ENFORCE` / 数据目录）
+ * @param {string} [o.mode]   显式指定模式（缺省按 env）
+ * @param {Function} [o.spawn] 注入 spawn（夹具）
+ * @returns {{checked:boolean, mode:string, allowed:boolean, blocked:boolean, code:number,
+ *            reason:string, licenseState:string, decision:string, human:string, error:string,
+ *            evidence:string, verdict:object|null}}
+ */
+export function gateWrite({ repo, flow, cap = '', vertical = null, env = process.env, mode = null, spawn = spawnSync, timeout = 30000 } = {}) {
+  const m = mode || gateModeOf(env)
+  const base = { checked: false, mode: m, allowed: true, blocked: false, code: 0, reason: 'enforce_off',
+    licenseState: 'skipped', decision: 'bypassed', human: '', error: '', verdict: null }
+  // `off`：**不查**（不 spawn、不读许可、不落证据）—— 逃生阀的字面含义
+  if (m === 'off') return { ...base, human: '许可闸门[off]：逃生阀已开（ARGENT_LICENSE_ENFORCE=off）⇒ 跳过许可判定，照常写' }
+
+  const script = join(repo, 'scripts', 'license-gate.mjs')
+  if (!existsSync(script)) {
+    // 旧克隆/半坏机器：**响亮告警但不停**（与 flow-trigger.sh 对缺文件的处置逐字一致）
+    return { ...base, checked: false, reason: 'gate_error', error: `缺少 ${script}（旧版本？）⇒ 闸门不生效，本次照常写（enforce 下也一样：不拦）` }
+  }
+  const args = [script, '--flow', String(flow || '?'), '--cap', String(cap || flow || '?'),
+    '--mode', m, '--json', '--quiet']
+  if (vertical) args.push('--vertical', String(vertical))
+  let r = null
+  try { r = spawn(process.execPath, args, { encoding: 'utf8', timeout, env }) } catch (e) {
+    return { ...base, reason: 'gate_error', error: `闸门执行异常：${String(e.message || e)}` }
+  }
+  const out = String((r && r.stdout) || '')
+  let j = null
+  try { j = JSON.parse(out.slice(out.indexOf('{'))) } catch { j = null }
+  if (!j || typeof j.allowed !== 'boolean') {
+    const err = String((r && r.stderr) || (r && r.error && r.error.message) || '').trim().slice(0, 200)
+    return { ...base, reason: 'gate_error', error: `闸门输出不可解析（exit=${r && r.status}${err ? `: ${err}` : ''}）⇒ 不拦` }
+  }
+  // 证据落在哪：由 license-gate.mjs 自己回报（`--json` 里的 log 字段）——本层不猜路径
+  const evidence = j.log || null
+  const allowed = j.allowed === true
+  const blocked = m === 'enforce' && !allowed
+  return {
+    checked: true,
+    mode: m,
+    allowed,
+    blocked,
+    code: blocked ? 1 : (allowed && j.licenseState === 'grace' ? 3 : 0),
+    reason: blocked ? 'license_denied' : (allowed && j.licenseState === 'grace' ? 'license_grace' : j.reason || 'ok'),
+    licenseState: j.licenseState || 'unknown',
+    decision: j.decision || 'unknown',
+    human: j.human || '',
+    error: '',
+    evidence,
+    verdict: j,
+  }
+}
+
+/**
+ * 把闸门结论并进写类 verb 的 JSON（A2）。
+ *   · `observe` 下 `blocked:false` —— **只留证据、不拦**（这是本批的真实姿态，别对外说成 enforce）
+ *   · grace ⇒ `code:3`（A1：3 只表示许可宽限放行）+ `reason:"license_grace"`（必须上报）
+ *   · enforce 且不可用 ⇒ 调用方据此**整体拒绝**（不执行写）
+ */
+export function applyGate(json, gate) {
+  const out = { ...json }
+  out.license = {
+    checked: gate.checked, mode: gate.mode, allowed: gate.allowed, blocked: gate.blocked,
+    state: gate.licenseState, decision: gate.decision, reason: gate.reason,
+    evidence: gate.evidence || null, human: gate.human || null,
+    note: gate.mode === 'observe'
+      ? '当前是 observe（默认）：**只留证据、不拦**；enforce 下同样的判定会拒绝本次写'
+      : (gate.mode === 'off' ? '逃生阀 off：没有做许可判定' : 'enforce：不可用即拒绝'),
+  }
+  if (gate.error) out.license.error = gate.error
+  if (gate.blocked) {
+    out.ok = false
+    out.empty = false
+    out.code = 1
+    out.reason = 'license_denied'
+    out.error = gate.human || '离线许可不可用（enforce）⇒ 拒绝写操作（零副作用）'
+  } else if (gate.checked && gate.licenseState === 'grace') {
+    out.code = 3
+    out.reason = 'license_grace'
+    out.licenseReport = '许可在宽限期内：业务放行，但**必须上报**（A1：code 3 只表示许可宽限放行）'
+  }
+  return out
+}