@bolloon/bolloon-agent 0.4.33 → 0.5.1

package/dist/utils/update-state.js

@@ -17,17 +17,13 @@ import * as path from 'path';
 import * as fs from 'fs';
 import * as fsp from 'fs/promises';
 import { resolveBolloonHome } from '../setup/setup-store.js';
+import { CHECK_STATUSES } from './version-identity.js';
 // ── 枚举 (冻结: 出口/状态都不许临时造词) ────────────────────────────────────
-/** 一次"检查"的结论。7 个值就是全部, 不认识的一律落进 registry_unavailable 并带原因。 */
-export const CHECK_STATUSES = [
-    'up_to_date', // 确认最新
-    'update_available', // 有新版本
-    'check_skipped', // 节流/显式跳过, 结论来自缓存
-    'offline', // 网络不可达 (≠ 最新)
-    'registry_unavailable', // 可达但拿不到有效数据 (5xx / 包不存在 / 无 dist-tags)
-    'local_version_unknown', // 读不到本地版本 (不猜 0.0.0)
-    'unsupported_installation', // 认得出本地版本, 但这种安装方式不支持自动更新
-];
+//
+// 2026-09-26: 结论枚举与 UpdatePrefs 的结构定义抽到 `version-identity.ts` (纯模块, 无 node:)。
+// **只有一个原因**: 手机端 WebView 里没有 `fs`/`os`, 但手机端必须用**同一份**结论语义
+// (9 个结论 + REFUSED_STATUSES 的拒绝口径)。这里原样再导出, 既有 import 路径不变。
+export { CHECK_STATUSES };
 /** 一次"更新执行"的流水线状态。 */
 export const UPDATE_RUN_STATUSES = [
     'planned', 'downloading', 'staged', 'switching', 'verifying',
@@ -72,6 +68,13 @@ export function emptyUpdateState(now = new Date()) {
         autoRestart: false,
         needsRestart: false,
         updatedAt: now.toISOString(),
+        installedChannel: null,
+        installedDevSha: null,
+        devSha: null,
+        devRef: null,
+        devCheckedAt: null,
+        sourceFacts: null,
+        switchableTo: null,
     };
 }
 // ── 读写 (原子) ─────────────────────────────────────────────────────────────

package/dist/utils/version-identity.js

@@ -0,0 +1,176 @@
+/**
+ * version-identity.ts — 版本身份 / 通道 / 结论分类的**纯词汇表** (2026-09-26)
+ *
+ * 为什么要从 `version-info.ts` 里抽出来 (抽出 ≠ 改写): 手机端 WebView **没有 node:**
+ * (`fs`/`os`/`path`/`child_process` 都没有), 而手机端双源更新必须用**和桌面同一份**
+ * 身份与结论语义 —— 否则同一台机器上的 `bolloon update status` 和手机上的"当前源"
+ * 会长出两套说法。所以:
+ *
+ *   本模块 = **不碰 node 的那一半** (纯函数 + 常量), 桌面与手机都 import 它;
+ *   `version-info.ts` = 本模块 + 需要 node 的探测 (安装识别 / git / npm / python / VersionInfo)
+ *
+ * 纪律 (改这里之前先读):
+ *   · 不许 import 任何 `node:*` / 不许在模块顶层直读 `process.env` (浏览器里会 ReferenceError);
+ *     环境变量一律走 `envValue()` (`typeof process` 守卫)。
+ *   · 版本比较语义与结论枚举**只此一份** (§12.1 / §3): stable 比 semver, dev 比 commit sha。
+ */
+// ── 包与上游 ────────────────────────────────────────────────────────────────
+export const PKG_NAME = '@bolloon/bolloon-agent';
+export const CONSTRAINT_PKG_NAME = '@bolloon/constraint-runtime';
+export const UPSTREAM_REPO = 'https://github.com/logos-42/bolloon';
+/** GitHub 上游 (owner/repo) —— 与 UPSTREAM_REPO 同一处, 这里给 API 用。 */
+export const GITHUB_UPSTREAM_SLUG = 'logos-42/bolloon';
+/**
+ * 环境变量读取 (浏览器安全的唯一入口)。
+ * `process` 在 WebView 里不存在 —— 直接写 `process.env.X` 会在**模块求值期**抛,
+ * 表现为整页 JS 不执行 (那样的红只有真浏览器能看见)。这里用 `typeof` 守卫。
+ */
+export function envValue(key) {
+    try {
+        // ① 壳层/页面的配置通道 (浏览器没有 process.env; 手机端由原生壳或验收 harness 注入)
+        const cfg = globalThis?.__bolloonUpdateConfig;
+        if (cfg && cfg[key] !== undefined && cfg[key] !== null)
+            return String(cfg[key]);
+        // ② 进程环境 (桌面 CLI / Node 验收)
+        const env = typeof process !== 'undefined' ? process?.env : null;
+        const v = env ? env[key] : undefined;
+        return v === undefined || v === null ? undefined : String(v);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** npm registry (可用 BOLLOON_NPM_REGISTRY 指向镜像/内网; 末尾斜杠统一去掉) */
+export const NPM_REGISTRY_BASE = (envValue('BOLLOON_NPM_REGISTRY') || 'https://registry.npmjs.org').replace(/\/+$/, '');
+/** GitHub API 根 (可被 BOLLOON_GITHUB_API 覆盖 → 受控假 API / 企业实例)。 */
+export const GITHUB_API_BASE = (envValue('BOLLOON_GITHUB_API') || 'https://api.github.com').replace(/\/+$/, '');
+/** dev 通道盯的分支 (冻结: master)。 */
+export const DEV_BRANCH = 'master';
+export const DEV_REF = `refs/heads/${DEV_BRANCH}`;
+// ── 安装方式 / 来源 / 通道 ──────────────────────────────────────────────────
+export const INSTALL_METHODS = [
+    'npm-global', 'npm-local', 'source-git', 'release-binary', 'development', 'unknown',
+];
+export const UPDATE_SOURCES = ['npm', 'github-release', 'git', 'unknown'];
+export const UPDATE_CHANNELS = ['stable', 'beta', 'dev'];
+/** 发行通道: 环境变量 > 配置 > stable。npm 只有 `latest` (stable) 一个 dist-tag, beta/dev 暂走同一标签。 */
+export function resolveUpdateChannel(explicit, env) {
+    const raw = (explicit || (env ? env.BOLLOON_UPDATE_CHANNEL : envValue('BOLLOON_UPDATE_CHANNEL')) || '').trim().toLowerCase();
+    if (raw === 'stable' || raw === 'beta' || raw === 'dev')
+        return raw;
+    return 'stable';
+}
+/** dist-tag 映射: stable → latest; beta/dev 暂与 stable 同源 (明说, 不假装有独立通道)。 */
+export function distTagForChannel(channel) {
+    return channel === 'beta' ? 'beta' : 'latest';
+}
+// ── 身份 (dev 用 commit sha, 不用 semver) ───────────────────────────────────
+/**
+ * 版本比较语义 (显式, 不是隐含约定):
+ *   semver  —— stable: 按 semver 数值段比大小
+ *   git-ref —— dev: **不用 semver**, 只判"是否同一 commit / 是否落后"
+ */
+export const CHANNEL_KINDS = ['semver', 'git-ref'];
+export function channelKindOf(channel) {
+    return channel === 'dev' ? 'git-ref' : 'semver';
+}
+/** dev 快照身份里的后缀标记 (`0.4.33+dev.a1b2c3d`)。 */
+export const DEV_IDENTITY_SEP = '+dev.';
+/** dev 快照身份 —— 用 commit sha (不是 semver) 当身份, 版本号只作参考展示。 */
+export function devIdentity(baseVersion, sha) {
+    return `${baseVersionOf(baseVersion)}${DEV_IDENTITY_SEP}${String(sha).slice(0, 7)}`;
+}
+/** 去掉 `+dev.<sha>` 后缀, 拿到基础版本号 (stable 目标的比对基准)。 */
+export function baseVersionOf(v) {
+    return String(v || '').split(DEV_IDENTITY_SEP)[0].trim();
+}
+/** 这个版本号是不是一个 dev 快照身份。 */
+export function isDevIdentity(v) {
+    return String(v || '').includes(DEV_IDENTITY_SEP);
+}
+/** 从 dev 身份里取 commit sha (前 7 位); 不是 dev 身份返回 null。 */
+export function devShaFromIdentity(v) {
+    if (!isDevIdentity(v))
+        return null;
+    const sha = String(v).split(DEV_IDENTITY_SEP)[1]?.trim();
+    return sha ? sha : null;
+}
+/**
+ * dev 通道的**唯一一句警告** (§12.4 硬约束 1) —— 检查 / 计划 / 执行 / 手机端四处打印同一句话。
+ * 定义在这里 (唯一事实层), 由 dual-source / update-manager / CLI / 手机端复用, 不允许各处自己造一句。
+ */
+export const DEV_CHANNEL_WARNING = '⚠️ dev 通道 = GitHub master HEAD 的即时快照 (未走发布门): 可能中断正在跑的 Goal/Run, 且不保证可回滚到上一个 dev 版。';
+/** 一键回 stable 的提示语 (同一份措辞)。 */
+export const DEV_BACK_TO_STABLE_HINT = '一键回稳定版: bolloon update now --channel stable';
+/** 手机端同一件事的说法 (原生层规则不同: 手机走 web 层 OTA, 不是 npm 全局安装)。 */
+export const DEV_BACK_TO_STABLE_HINT_MOBILE = '一键回稳定版: 手机端「更新」页 → 切回 stable';
+// ── 版本比较 (唯一一份) ─────────────────────────────────────────────────────
+export function parseVersion(v) {
+    const clean = String(v || '').trim().replace(/^v/, '').split('-')[0];
+    const parts = clean.split('.').map((p) => parseInt(p.replace(/\D.*$/, ''), 10));
+    return parts.map((n) => (Number.isFinite(n) ? n : 0));
+}
+/** -1 = a<b, 0 = 相等, 1 = a>b (只比数值段, 忽略预发布标签) */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x < y)
+            return -1;
+        if (x > y)
+            return 1;
+    }
+    return 0;
+}
+export function isKnownVersion(v) {
+    return !!v && v !== 'unknown' && /^\d/.test(String(v).trim().replace(/^v/, ''));
+}
+// ── 检查结论 + 拒绝语义 (§3 / §12.3 / §12.5) ────────────────────────────────
+/**
+ * 一次"检查"的结论。**9 个值就是全部** (桌面侧), 不认识的一律落进 registry_unavailable 并带原因。
+ *
+ * 2026-09-25 (update-protocol §12.3, 双源): **只增不改** —— 新增 2 个, 错误分类**不合并**:
+ *   github_unavailable     GitHub 不可达 / 403·429 限流 / 没有 Release / 没有 master
+ *   cross_check_mismatch   stable 下 npm 与 GitHub 指向不同版本 (两个源的事实都摆出来)
+ */
+export const CHECK_STATUSES = [
+    'up_to_date', // 确认最新
+    'update_available', // 有新版本
+    'check_skipped', // 节流/显式跳过, 结论来自缓存
+    'offline', // 网络不可达 (≠ 最新)
+    'registry_unavailable', // 可达但拿不到有效数据 (5xx / 包不存在 / 无 dist-tags)
+    'local_version_unknown', // 读不到本地版本 (不猜 0.0.0)
+    'unsupported_installation', // 认得出本地版本, 但这种安装方式不支持自动更新
+    'github_unavailable', // GitHub 源不可用 (offline / rate_limited / not_found / http_error)
+    'cross_check_mismatch', // npm 与 GitHub 两个源不一致 → 拒绝更新
+];
+/**
+ * "源不可达 / 版本不存在" 这一组结论 —— 它们必须**拒绝执行并说清**。
+ * 这是 §12.5 那一条的代码落点: 不许静默装回旧版, 也不许打印"已是最新"。
+ *
+ * **桌面与手机共用同一份** —— 手机上这几个状态同样会让 apply 直接 blocked, 一个字节都不下载。
+ */
+export const REFUSED_STATUSES = ['offline', 'registry_unavailable', 'local_version_unknown', 'github_unavailable', 'cross_check_mismatch'];
+/** 检查结论 → 退出码 (稳定约定, §2): 0 正常 / 2 检查不可用。 */
+export function checkExitCode(status) {
+    switch (status) {
+        case 'offline':
+        case 'registry_unavailable':
+        case 'local_version_unknown':
+        case 'github_unavailable':
+        case 'cross_check_mismatch':
+            return 2;
+        default:
+            return 0;
+    }
+}
+// ── 身份那一行的渲染 (§12.5: 桌面与手机同一份措辞) ──────────────────────────
+/** 双源身份那一行 (谁装的 / 哪个 sha / 能切回哪) —— 桌面 `--version`/`update status` 与手机端共用同一份措辞。 */
+export function describeSourceIdentity(info) {
+    const src = info.installedDevSha ? 'dev (GitHub master 快照)' : 'stable (npm registry)';
+    const ident = info.installedDevSha ? `commit ${info.installedDevSha}` : baseVersionOf(info.packageVersion);
+    const back = info.switchableTo ? ` · 可切回 ${info.switchableTo.channel} (${info.switchableTo.source})` : '';
+    return `当前安装源: ${src} · 版本/commit: ${ident} · 比较语义: ${info.channelKind}${back}`;
+}

package/dist/utils/version-info.js

@@ -26,27 +26,13 @@ import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveBolloonHome } from '../setup/setup-store.js';
 import { renderRuntimeLines } from './runtime-bootstrap.js';
-export const PKG_NAME = '@bolloon/bolloon-agent';
-export const CONSTRAINT_PKG_NAME = '@bolloon/constraint-runtime';
-/** npm registry (可用 BOLLOON_NPM_REGISTRY 指向镜像/内网; 末尾斜杠统一去掉) */
-export const NPM_REGISTRY_BASE = (process.env.BOLLOON_NPM_REGISTRY || 'https://registry.npmjs.org').replace(/\/+$/, '');
-export const UPSTREAM_REPO = 'https://github.com/logos-42/bolloon';
-export const INSTALL_METHODS = [
-    'npm-global', 'npm-local', 'source-git', 'release-binary', 'development', 'unknown',
-];
-export const UPDATE_SOURCES = ['npm', 'github-release', 'git', 'unknown'];
-export const UPDATE_CHANNELS = ['stable', 'beta', 'dev'];
-/** 发行通道: 环境变量 > 配置 > stable。npm 只有 `latest` (stable) 一个 dist-tag, beta/dev 暂走同一标签。 */
-export function resolveUpdateChannel(explicit) {
-    const raw = (explicit || process.env.BOLLOON_UPDATE_CHANNEL || '').trim().toLowerCase();
-    if (raw === 'stable' || raw === 'beta' || raw === 'dev')
-        return raw;
-    return 'stable';
-}
-/** dist-tag 映射: stable → latest; beta/dev 暂与 stable 同源 (明说, 不假装有独立通道)。 */
-export function distTagForChannel(channel) {
-    return channel === 'beta' ? 'beta' : 'latest';
-}
+import { PKG_NAME, CONSTRAINT_PKG_NAME, UPSTREAM_REPO, GITHUB_UPSTREAM_SLUG, INSTALL_METHODS, UPDATE_SOURCES, UPDATE_CHANNELS, CHANNEL_KINDS, DEV_BRANCH, DEV_REF, DEV_IDENTITY_SEP, DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT, NPM_REGISTRY_BASE, GITHUB_API_BASE, resolveUpdateChannel, distTagForChannel, channelKindOf, devIdentity, baseVersionOf, isDevIdentity, devShaFromIdentity, parseVersion, compareVersions, isKnownVersion, checkExitCode, REFUSED_STATUSES, CHECK_STATUSES, describeSourceIdentity, } from './version-identity.js';
+/**
+ * 版本身份 / 通道 / 结论分类的**纯词汇表**已抽到 `version-identity.ts` (2026-09-26),
+ * 这里原样再导出 —— 既有 import 路径 (`from './version-info.js'`) 一行都不用改,
+ * 手机端 (无 node:) 直接 import 那份纯模块即可, 两边共用同一套语义。
+ */
+export { PKG_NAME, CONSTRAINT_PKG_NAME, UPSTREAM_REPO, GITHUB_UPSTREAM_SLUG, INSTALL_METHODS, UPDATE_SOURCES, UPDATE_CHANNELS, CHANNEL_KINDS, DEV_BRANCH, DEV_REF, DEV_IDENTITY_SEP, DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT, NPM_REGISTRY_BASE, GITHUB_API_BASE, resolveUpdateChannel, distTagForChannel, channelKindOf, devIdentity, baseVersionOf, isDevIdentity, devShaFromIdentity, parseVersion, compareVersions, isKnownVersion, checkExitCode, REFUSED_STATUSES, CHECK_STATUSES, describeSourceIdentity, };
 // ── 包根定位 ────────────────────────────────────────────────────────────────
 /**
  * 从当前模块 URL 定位**运行中的**包根。
@@ -385,6 +371,11 @@ export function collectVersionInfo(opts = {}) {
     }
     if (!gitCommit)
         gitCommitSource = 'unknown';
+    // dev 身份从**磁盘上的版本号**读 (不是从状态文件猜): `0.4.33+dev.a1b2c3d` → sha=a1b2c3d
+    const installedDevSha = devShaFromIdentity(pkg?.version) || (opts.update?.installedDevSha ?? null);
+    const switchableTo = opts.update?.switchableTo ?? (installedDevSha
+        ? { channel: 'stable', source: 'npm', target: null }
+        : null);
     return {
         schema: 'bolloon-version/1',
         packageName: pkg?.name || PKG_NAME,
@@ -406,11 +397,14 @@ export function collectVersionInfo(opts = {}) {
         binPath: install.binPath,
         configDir: home,
         channel,
+        channelKind: channelKindOf(channel),
         upstream: UPSTREAM_REPO,
         registry: `${NPM_REGISTRY_BASE}/${PKG_NAME}`,
         updateSource: install.updateSource,
         autoUpdatable: install.autoUpdatable,
         installReason: install.reason,
+        installedDevSha,
+        switchableTo,
         update: opts.update ?? null,
         runtime: opts.runtime ?? null,
         runtimeConfigBacked: opts.runtimeConfigBacked ?? false,
@@ -444,9 +438,15 @@ export function describeUpdateLine(info) {
         case 'registry_unavailable': return `更新检查: registry 不可用${u.lastCheckReason ? ` (${u.lastCheckReason})` : ''} (不等于最新)`;
         case 'local_version_unknown': return '更新检查: 读不到本地版本 — 不判断是否有更新';
         case 'unsupported_installation': return '更新检查: 当前安装方式不支持自动更新';
+        case 'github_unavailable': return `更新检查: GitHub 源不可用${u.lastCheckReason ? ` (${u.lastCheckReason})` : ''} (不等于最新)`;
+        case 'cross_check_mismatch': return `更新检查: 两个源不一致 (npm ↔ GitHub) — 不执行更新`;
         default: return `更新检查: ${u.lastCheckStatus}`;
     }
 }
+/**
+ * 双源身份那一行 (谁装的 / 哪个 sha / 能切回哪) —— 已在 `version-identity.ts` (唯一一份,
+ * 桌面 `--version` 与 `update status` 共用同一份措辞)。这里只留注释, 避免出现第二份实现。
+ */
 export function renderVersionText(info, opts = {}) {
     if (opts.verbose) {
         const lines = [
@@ -464,10 +464,12 @@ export function renderVersionText(info, opts = {}) {
             `运行入口:    ${info.entryPath}`,
             `bin shim:    ${info.binPath || 'unknown'}`,
             `配置目录:    ${info.configDir}`,
-            `更新通道:    ${info.channel}`,
+            `更新通道:    ${info.channel} (比较语义: ${info.channelKind})`,
             `更新来源:    ${info.updateSource}${info.autoUpdatable ? '' : ' (不支持自动更新)'}`,
+            describeSourceIdentity(info),
             `上游地址:    ${info.upstream}`,
             `registry:    ${info.registry}`,
+            `GitHub:      ${GITHUB_UPSTREAM_SLUG} (${DEV_BRANCH} HEAD = dev 通道的源)`,
             describeUpdateLine(info),
             `上次检查:    ${fmtTime(info.update?.lastCheckAt)}`,
         ];
@@ -493,12 +495,15 @@ export function renderVersionText(info, opts = {}) {
         `安装目录: ${info.installDir}`,
         `运行入口: ${info.binPath || info.entryPath}`,
         `更新通道: ${info.channel}`,
+        describeSourceIdentity(info),
         `Node.js: ${info.nodeVersion}`,
         `平台: ${info.platform} ${info.arch}`,
         `上游提交: ${info.gitCommit || 'unknown'}`,
         describeUpdateLine(info),
         `上次检查: ${fmtTime(info.update?.lastCheckAt)}`,
     ];
+    if (info.installedDevSha)
+        lines.push(DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT);
     if (info.runtime) {
         lines.push('');
         lines.push(...renderRuntimeLines(info.runtime, { verbose: false, configBacked: info.runtimeConfigBacked }));

package/dist/web/bolloon-web.json

@@ -0,0 +1,10 @@
+{
+  "schema": "bolloon-mobile-web/1",
+  "version": "0.5.1",
+  "channel": "stable",
+  "build": "stable",
+  "commit": "8efb696025ea635cc4f0c907c275ea41c1ecf7a1",
+  "builtAt": "2026-09-27T15:24:38.506Z",
+  "layer": "web",
+  "note": "web 资源层构建戳 (手机端 OTA 的身份第 ③ 级回退; 装机后以 OTA state.json 为准)"
+}

package/dist/web/mobile-contacts.js

@@ -89,21 +89,54 @@ async function importPrivate(storage, c) {
 }
 /** 用设备私钥签一条 Grant (核心: 手机确认 → 桌面才认) */
 export async function signGrantOnDevice(grant, storage, c) {
-    const cobj = cryptoOf(c);
-    const key = await importPrivate(storage, cobj);
-    const payload = canonicalGrantPayload(grant);
-    const sig = await cobj.subtle.sign({ name: 'Ed25519' }, key, bytesOf(payload));
-    const dev = await loadOrCreateDeviceKey(storage, cobj);
-    return { deviceId: dev.deviceId, alg: 'ed25519', payloadHash: await sha256Hex(cobj, payload), sig: b64(sig) };
+    return signPayloadOnDevice(canonicalGrantPayload(grant), storage, c);
 }
 /** 撤销也要签名 (桌面拒收未登记设备的撤销) */
 export async function signRevocationOnDevice(rev, storage, c) {
+    return signPayloadOnDevice(canonicalRevocationPayload(rev), storage, c);
+}
+/**
+ * 通用: 用**同一把设备私钥**签任意规范载荷 (2026-09-25)。
+ *
+ * 抽出来的原因: 手机上所有"要桌面认账"的动作 (长期授权 · 撤销 · 高风险任务动作
+ * 入群/发公告/过程留痕) 必须是**同一把设备密钥 + 同一套验签纪律** ——
+ * 各写一份签名实现迟早出现"某条路径没签名也能过"的缝。
+ * 载荷的规范化由调用方提供 (grant-payload / mobile-task-actions), 本函数只管签。
+ */
+export async function signPayloadOnDevice(payload, storage, c) {
+    const cobj = cryptoOf(c);
+    if (!cobj?.subtle)
+        throw new Error('device_signing_unavailable: 本机没有 WebCrypto');
+    // 只加载一次设备材料: deviceId 与签名必须来自**同一份**密钥
+    // (2026-09-25 修: 之前在这里二次 loadOrCreateDeviceKey, storage 不持久化时会生成另一把密钥
+    //  → 桌面 device_mismatch 403。真机 localStorage 下看不出来, 但那是运气不是设计。)
+    const material = await loadOrCreateDeviceKey(storage, cobj);
+    const key = await cobj.subtle.importKey('jwk', material.privateKeyJwk, { name: 'Ed25519' }, false, ['sign']);
+    const bytes = bytesOf(String(payload ?? ''));
+    const sig = await cobj.subtle.sign({ name: 'Ed25519' }, key, bytes);
+    return { deviceId: material.deviceId, alg: 'ed25519', payloadHash: await sha256Hex(cobj, String(payload ?? '')), sig: b64(sig) };
+}
+/** sha256 hex (手机侧与桌面 Node 同值) —— 任务动作的内容摘要用它算 */
+export async function sha256HexOf(text, c) {
     const cobj = cryptoOf(c);
-    const key = await importPrivate(storage, cobj);
-    const payload = canonicalRevocationPayload(rev);
-    const sig = await cobj.subtle.sign({ name: 'Ed25519' }, key, bytesOf(payload));
-    const dev = await loadOrCreateDeviceKey(storage, cobj);
-    return { deviceId: dev.deviceId, alg: 'ed25519', payloadHash: await sha256Hex(cobj, payload), sig: b64(sig) };
+    if (!cobj?.subtle)
+        throw new Error('device_signing_unavailable: 本机没有 WebCrypto');
+    return sha256Hex(cobj, String(text ?? ''));
+}
+/**
+ * 用**已经加载好的**设备材料签名 (调用方自己拿 deviceId)。
+ *
+ * 为什么留这个口: 高风险任务动作的载荷里含 deviceId, 签名必须与那个 deviceId 同源。
+ * 若"取 deviceId"与"签名"各调一次 loadOrCreateDeviceKey, 在 storage 不持久化的环境
+ * (隐私模式 / storage 被禁) 会拿到两把不同密钥 → 桌面 device_mismatch 403。
+ */
+export async function signPayloadWithMaterial(payload, material, c) {
+    const cobj = cryptoOf(c);
+    if (!cobj?.subtle)
+        throw new Error('device_signing_unavailable: 本机没有 WebCrypto');
+    const key = await cobj.subtle.importKey('jwk', material.privateKeyJwk, { name: 'Ed25519' }, false, ['sign']);
+    const sig = await cobj.subtle.sign({ name: 'Ed25519' }, key, bytesOf(String(payload ?? '')));
+    return { deviceId: material.deviceId, alg: 'ed25519', payloadHash: await sha256Hex(cobj, String(payload ?? '')), sig: b64(sig) };
 }
 async function post(base, path, body, f) {
     const res = await f(`${String(base).replace(/\/+$/, '')}${path}`, {