@m2canvas/connect 0.12.0 → 0.14.0

package/dist/bridge/handoff.js

@@ -1,213 +0,0 @@
-/**
- * 把命令承诺交给正在运行的后台 bridge（change acp-bridge-one-time-install design D27、R11、review r3 R3-S1；`connect/local-bridge` 契约 2 delta）。
- *
- * 后台模式的 bridge 不出配对码，新页面只能靠启动命令里的承诺配对；原来承诺只能在启动时经 `--pair` 带进去，
- * 换一个浏览器就得 `--replace` 重启 bridge，打断其他页面上正在跑的 agent。现在：
- *  - 后台模式的 bridge 监听 `~/.m2canvas/bridge-<port>.sock`；
- *  - 启动器拉起的新 `bridge --background --pair <c>` 撞上认定的 M2 bridge 时，把 c 写进 `~/.m2canvas/handoff-<编号>.pending`，
- *    经 socket 只发这个编号；bridge 读出承诺、删掉文件、挂上，再回复。交出方随后以退出码 3 退出。
- *
- * 跨版本接口（启动器只随重装更新，bridge 会自动更新，交出方与接收方可能是不同版本；`connect/local-bridge` 契约 14 delta）：
- *  - 请求一行（不含换行最多 256 字节）：`{"type":"arm","nonce":"<32 位小写十六进制>"}\n`；承诺在 `<m2 目录>/handoff-<nonce>.pending`（普通文件、属于本账号）；
- *  - 回复一行：`{"ok":true,"until":<毫秒时间戳>}` 或 `{"ok":false,"error":"…"}`，回复后断开。
- *  - 只读状态查询（change desktop-bridge-launcher D15 起；具体版本见 connect 的发布记录）：请求 `{"type":"status","commitment":"<22 位 base64url>"}\n`，
- *    回复 `{"ok":true,"state":"waiting","until":…}` / `{"ok":true,"state":"paired","origin":"…","at":…}` / `{"ok":true,"state":"unknown"}`，
- *    可带 `"rejected":{"origin":"…","at":…}`（最近一次因 Origin 不在白名单被拒的连接）。旧版本对它回 `bad_request`，
- *    M2 Mac 客户端据此判定「不支持」。
- *  只能加字段；要改语义就换请求的 type，并让接收方继续认旧的。
- *
- * 维护约束：
- * - 门槛是「能写 `~/.m2canvas`」，而不只是「能连 socket」（R3-S1）：agent 沙箱里的命令可能被放开了本机 socket，
- *   但默认只能写工作目录与临时目录；只靠 socket 的话，它就能配上、再经 bridge 驱动沙箱外的 agent。能写这个目录的进程
- *   本来就能配对（bridge 每次校验 token 都重读 `bridge-pairings.json`，往里加一条记录即可；在沙箱里、做不到 `--replace` 也一样），
- *   所以不算新的攻击者类别。这条论证依赖「每次重读配对文件」：改成只在启动时读或缓存时，要重新评估这里的门槛。
- *   不要退回「socket 上直接带承诺」，也不要放宽文件名（只认 32 位十六进制）。
- * - `status` 只读、承诺随请求一起发，不要求能写 `~/.m2canvas`：它只透露「这个承诺配没配上、配给了哪个 origin、最近被拒的 origin」，
- *   这些本来就写在 `~/.m2canvas/logs/bridge.log` 里，能连这个 socket 的本账号进程也能读到；不回 S、不回 token、不改任何状态，
- *   也不能用来猜承诺（128 bit）。回复里要加别的东西时，先重做这条论证（design D15）。
- * - socket 上不收 S、不回 token：拿 token 仍要页面在 hello 里出示 S，Origin 白名单照旧。
- * - 只有同一个账号能连：`~/.m2canvas` 0700、socket 0600。不要把 socket 放到别的目录，也不要放宽权限。
- * - 每个连接只处理一行、有长度上限、有从连上起算的绝对超时：这是本机进程能碰到的入口，不能让它挂住 bridge 或吃内存。
- * - socket 路径受 macOS 的 sun_path 限制（104 字节含结尾 0）：超出就不监听，只记日志（交接不可用，页面用 `--replace` 兜底）。
- */
-import { randomBytes } from 'node:crypto';
-import { chmodSync, lstatSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { createConnection, createServer } from 'node:net';
-import { basename, dirname, join } from 'node:path';
-import { isPairCommitment } from './pairing.js';
-/** sockaddr_un.sun_path 是 104 字节，含结尾的 0 */
-export const HANDOFF_MAX_PATH_BYTES = 103;
-export const HANDOFF_TIMEOUT_MS = 3_000;
-/** `{"type":"arm","nonce":"<32 字符>"}` 不到 60 字节，留足余量 */
-const MAX_LINE_BYTES = 256;
-const NONCE_RE = /^[0-9a-f]{32}$/;
-/** 承诺文件只放 22 个字符（可能带换行） */
-const MAX_PENDING_BYTES = 64;
-export function handoffSocketPath(dir, port) {
-    return join(dir, `bridge-${port}.sock`);
-}
-function pendingPath(dir, nonce) {
-    return join(dir, `handoff-${nonce}.pending`);
-}
-/** 删不掉（例如被换成了目录）只当没删：这里的异常没人接，抛出会让 bridge 退出（契约 5，r3 复核 R3C-N1） */
-function removeQuietly(path) {
-    try {
-        rmSync(path, { force: true });
-    }
-    catch {
-        // 留下的残留由卸载脚本或下一次同名交接处理
-    }
-}
-function errorText(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function parseRequest(line) {
-    try {
-        const request = JSON.parse(line);
-        if (typeof request !== 'object' || request === null)
-            return null;
-        const { type, nonce, commitment } = request;
-        if (type === 'arm' && typeof nonce === 'string' && NONCE_RE.test(nonce))
-            return { type, nonce };
-        if (type === 'status' && typeof commitment === 'string' && isPairCommitment(commitment))
-            return { type, commitment };
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
-/** 读出交出方写的承诺并删掉文件；不是本账号的普通文件、内容不对都当没有（不跟随符号链接） */
-function takePendingCommitment(dir, nonce) {
-    const path = pendingPath(dir, nonce);
-    // 编号的正则已经挡住了路径分隔符；这里再按路径结构核一次，正则被改松时也不会读到目录外（r3 复核 R3C-S1）
-    if (dirname(path) !== join(dir) || basename(path) !== `handoff-${nonce}.pending`)
-        return null;
-    try {
-        const info = lstatSync(path);
-        const uid = typeof process.getuid === 'function' ? process.getuid() : info.uid;
-        if (!info.isFile() || info.uid !== uid || info.size > MAX_PENDING_BYTES)
-            return null;
-        const commitment = readFileSync(path, 'utf8').trim();
-        return isPairCommitment(commitment) ? commitment : null;
-    }
-    catch {
-        return null;
-    }
-    finally {
-        removeQuietly(path);
-    }
-}
-/**
- * 后台模式的 bridge 在拿到端口之后调用：同名的 socket 残留（上次没清干净）先删掉 —— 端口在自己手里，这个端口的 socket 不可能属于别人。
- * 返回 null = 没监听（路径太长或建不起来），只记日志，不影响 bridge 本身。
- */
-export async function listenForHandoff(options) {
-    const { dir, port, arm, status, log } = options;
-    const path = handoffSocketPath(dir, port);
-    if (Buffer.byteLength(path) > HANDOFF_MAX_PATH_BYTES) {
-        log(`Pairing handoff is unavailable: ${path} is too long for a local socket. A new browser has to use the reconnect command instead.`);
-        return null;
-    }
-    const server = createServer((socket) => {
-        const deadline = setTimeout(() => socket.destroy(), HANDOFF_TIMEOUT_MS);
-        socket.on('close', () => clearTimeout(deadline));
-        socket.on('error', () => undefined);
-        let buffer = '';
-        let done = false;
-        socket.on('data', (chunk) => {
-            // 只处理第一行：之后再发什么都丢掉（不暂停读取，对方断开时这边也跟着关）
-            if (done)
-                return;
-            buffer += chunk.toString('utf8');
-            const end = buffer.indexOf('\n');
-            if (Buffer.byteLength(end < 0 ? buffer : buffer.slice(0, end)) > MAX_LINE_BYTES) {
-                socket.destroy();
-                return;
-            }
-            if (end < 0)
-                return;
-            done = true;
-            const request = parseRequest(buffer.slice(0, end));
-            if (request?.type === 'status' && status) {
-                socket.end(`${JSON.stringify({ ok: true, ...status(request.commitment) })}\n`);
-                return;
-            }
-            const nonce = request?.type === 'arm' ? request.nonce : null;
-            const commitment = nonce ? takePendingCommitment(dir, nonce) : null;
-            if (!commitment) {
-                socket.end(`${JSON.stringify({ ok: false, error: nonce ? 'not_found' : 'bad_request' })}\n`);
-                return;
-            }
-            const until = arm(commitment);
-            log('Armed a pairing value received over the local handoff socket; the page that holds it can pair now.');
-            socket.end(`${JSON.stringify({ ok: true, until })}\n`);
-        });
-    });
-    try {
-        rmSync(path, { force: true });
-        await new Promise((resolve, reject) => {
-            server.once('error', reject);
-            server.listen(path, () => resolve());
-        });
-        chmodSync(path, 0o600);
-    }
-    catch (error) {
-        server.close();
-        log(`Pairing handoff is unavailable (${errorText(error)}). A new browser has to use the reconnect command instead.`);
-        return null;
-    }
-    return {
-        close() {
-            server.close();
-            rmSync(path, { force: true });
-        },
-    };
-}
-/**
- * 新的 `bridge --background --pair <c>` 撞上认定的 M2 bridge 时调用：把承诺写进一次性文件，经 socket 发编号。
- * true = 对方确认挂上了；没人在听、对方拒绝、超时都是 false（调用方照常以退出码 3 退出，只是新页面配不上）。文件无论如何都删掉。
- */
-export function handOffCommitment(options) {
-    const { dir, port, commitment, timeoutMs = HANDOFF_TIMEOUT_MS } = options;
-    if (!isPairCommitment(commitment))
-        return Promise.resolve(false);
-    const nonce = randomBytes(16).toString('hex');
-    const file = pendingPath(dir, nonce);
-    try {
-        writeFileSync(file, commitment, { mode: 0o600, flag: 'wx' });
-    }
-    catch {
-        return Promise.resolve(false);
-    }
-    return new Promise((resolve) => {
-        let reply = '';
-        let settled = false;
-        const socket = createConnection(handoffSocketPath(dir, port));
-        const finish = (ok) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            socket.destroy();
-            resolve(ok);
-        };
-        const timer = setTimeout(() => finish(false), timeoutMs);
-        socket.on('error', () => finish(false));
-        socket.on('data', (chunk) => {
-            reply += chunk.toString('utf8');
-            if (reply.length > MAX_LINE_BYTES)
-                finish(false);
-        });
-        socket.on('end', () => {
-            try {
-                const answer = JSON.parse(reply.trim());
-                finish(typeof answer === 'object' && answer !== null && answer.ok === true);
-            }
-            catch {
-                finish(false);
-            }
-        });
-        socket.on('connect', () => socket.write(`${JSON.stringify({ type: 'arm', nonce })}\n`));
-    }).finally(() => removeQuietly(file));
-}

package/dist/bridge/pair-call.js

@@ -1,31 +0,0 @@
-/**
- * bridge 方法 `pair`（页面输码换 token）：校验参数、调用 PairingManager.pair、把失败映射成页面看得懂的错误码。
- * 只负责「这次输码对不对」；配对成功后把连接标为已配对、记日志、回 cwd 由 server.ts 负责（连接状态只在那里改）。
- *
- * 错误码的语义是页面协议的一部分（`protocol.ts` 的 BridgeErrorCode，`connect/local-bridge` 契约 9）：
- * - pairing_invalid：错码，带剩余次数；
- * - pairing_code_rotated：码过期或错太多次被换掉，新码已打印在终端；
- * - pairing_locked：累计错码太多，只有重启 bridge 才解除；
- * - pairing_code_unavailable：后台模式（`bridge --background`）根本不出码，页面要改走「重新连接」（change acp-bridge-one-time-install D17）。
- * 不要把后两种并进 pairing_code_rotated：页面据此决定是让用户看终端，还是让 agent 重新拉起 bridge。
- */
-import { BridgeFailure } from './errors.js';
-/** 成功时返回新签发的 token；失败抛 BridgeFailure */
-export function handlePairCall(pairing, origin, params) {
-    const code = params.code;
-    if (typeof code !== 'string')
-        throw new BridgeFailure('bad_message', 'pair needs a string "code"');
-    const result = pairing.pair(code, origin);
-    if (result.ok)
-        return result.token;
-    switch (result.code) {
-        case 'pairing_invalid':
-            throw new BridgeFailure('pairing_invalid', 'wrong pairing code', { attemptsLeft: result.attemptsLeft });
-        case 'pairing_locked':
-            throw new BridgeFailure('pairing_locked', 'too many wrong pairing codes; new pages cannot pair until the bridge is restarted');
-        case 'pairing_code_unavailable':
-            throw new BridgeFailure('pairing_code_unavailable', 'this bridge was started in the background and shows no pairing code; reconnect from M2 to pair');
-        case 'pairing_code_rotated':
-            throw new BridgeFailure('pairing_code_rotated', 'pairing code expired or used up; a new one is shown in the terminal');
-    }
-}

package/dist/bridge/pairing.js

@@ -1,349 +0,0 @@
-/**
- * 配对：安全三条里的第三条。Origin 白名单挡住了其他网站，但挡不住两类来源 —— `--dev` 时本机其他跑在开发端口上的页面
- * 和本机其他进程（可以伪造 Origin）。它们都拿不到只出现在终端里的配对码。
- * 配对 = 授权该页面以用户的身份驱动本机 agent（包括执行命令），所以码和 token 都按这个级别保管。
- *
- * 两条途径，都要证明「终端用户同意了这个页面」（change acp-bridge-command-pairing）：
- * - 输码：终端打印一次性配对码 → 用户在页面输入 → 换取长期 token（页面存 localStorage）→ 之后每次 hello 带上。
- * - 命令承诺：页面生成密钥 S，启动命令只带承诺 c = base64url(sha256(S) 的前 16 字节)（`bridge --pair c`）；
- *   页面在 hello 里出示 S，一致就换取同样的 token。「在自己终端里运行了这个页面给的命令」与「抄了终端里的码」证明的是同一件事。
- *   命令会进 `ps` 与 shell 历史，所以命令里只能有承诺、不能有 S；承诺只在内存里、自挂上起 CODE_TTL_MS 有效、成功一次即作废。
- *
- * 维护约束：
- * - 本地只存 token 的 sha256，不存明文；文件 0600、目录 0700。
- * - token 绑定配对时的 Origin：开发域名配出的 token 不能拿到正式域名用。
- * - 配对码约 40 bit，每个码最多错 MAX_CODE_FAILURES 次、CODE_TTL_MS 后过期，二者都会轮换并在终端重新打印；
- *   自上次成功配对以来累计错 MAX_TOTAL_FAILURES 次就锁定（不论中间换过几个码、码是不是过期换的），只有重启 bridge 才解除
- *   （锁只在内存里）。锁定不影响已配对的页面。
- *   不要为了「方便」放宽次数、延长有效期或加一个页面能触发的解锁：码是唯一挡住本机恶意页面的东西。
- *   也不要改成「在终端按回车解锁」：那需要读终端，而 bridge 放到后台（`… bridge &`）时读终端会被系统挂起（review r2 实测）。
- * - 比较用常量时间（timingSafeEqual），不要改回 ===。
- * - 后台模式（`issueCodes: false`，`bridge --background`，change acp-bridge-one-time-install D17）不出码：没有终端，stdout 写的是日志文件，
- *   出码就等于把码写盘。这时 `issueCode` / `ensureCode` 什么都不做，`pair` 一律 pairing_code_unavailable，配对只剩命令承诺与已有 token。
- *   不要给后台模式另开出码通道（文件、系统对话框）：「把码写进文件」已被否决过（`connect/local-bridge` 契约 2 / 13）。
- */
-import { createHash, randomBytes, randomInt, randomUUID, timingSafeEqual } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-export const CODE_TTL_MS = 10 * 60 * 1000;
-export const MAX_CODE_FAILURES = 5;
-export const TOKEN_IDLE_MS = 30 * 24 * 60 * 60 * 1000;
-export const TOKEN_IDLE_DAYS = 30;
-export const MAX_PAIRINGS = 20;
-/**
- * 自上次成功配对以来累计错这么多次就锁定，重启 bridge 才解除。按累计而不是「因错码轮换的次数」计：
- * 码过期换新时不清零 —— 否则每个码错 4 次再等它过期就能无限猜下去（review r3 S4）。
- */
-export const MAX_TOTAL_FAILURES = 15;
-/** 同一 Origin、同一个码在终端的重复提示间隔 */
-const PROMPT_DEDUPE_MS = 60_000;
-/** Crockford base32：去掉易混的 I、L、O、U */
-const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
-const CODE_LENGTH = 8;
-/** 页面密钥 S：32 字节随机数的 base64url（无填充） */
-const PAIR_SECRET_RE = /^[A-Za-z0-9_-]{43}$/;
-/** 承诺：sha256(S) 前 16 字节的 base64url（无填充） */
-const PAIR_COMMITMENT_RE = /^[A-Za-z0-9_-]{22}$/;
-const COMMITMENT_BYTES = 16;
-export function isPairCommitment(value) {
-    return PAIR_COMMITMENT_RE.test(value);
-}
-/** 承诺 = base64url(sha256(S 的 UTF-8) 的前 16 字节)。前端 `bridge-pair-secret.ts` 用 WebCrypto 算同一个值，改这里要同批改那边。 */
-export function pairCommitmentOf(secret) {
-    return sha256(secret).subarray(0, COMMITMENT_BYTES).toString('base64url');
-}
-/** 用户输入归一：大小写、空格、连字符；按 Crockford 规则把 O 视同 0、I / L 视同 1 */
-export function normalizePairingCode(input) {
-    return input
-        .toUpperCase()
-        .replace(/[\s-]/g, '')
-        .replace(/O/g, '0')
-        .replace(/[IL]/g, '1');
-}
-function formatCode(code) {
-    return `${code.slice(0, 4)}-${code.slice(4)}`;
-}
-function sha256(value) {
-    return createHash('sha256').update(value).digest();
-}
-function sameSecret(a, b) {
-    const left = sha256(a);
-    const right = sha256(b);
-    return timingSafeEqual(left, right);
-}
-function errorText(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-export class PairingManager {
-    active = null;
-    /** `--pair` 挂上的承诺（只在内存里：bridge 重启即失效，重新运行同一条命令会重新挂上） */
-    commitment = null;
-    /** 已用掉的承诺：同一个密钥再出现时告警（只在内存里，只记最近一个） */
-    consumed = null;
-    /** 自上次成功配对以来累计的错码次数（跨码、跨过期）；配对成功时清零 */
-    failuresSinceSuccess = 0;
-    locked = false;
-    /** Origin → 上次在终端提示它的时间与当时的码，用于去重 */
-    lastPrompt = new Map();
-    store;
-    now;
-    issueCodes;
-    onCodeIssued;
-    onLocked;
-    onProblem;
-    onCommitmentReused;
-    constructor(options) {
-        this.store = options.store;
-        this.now = options.now ?? Date.now;
-        this.issueCodes = options.issueCodes ?? true;
-        this.onCodeIssued = options.onCodeIssued;
-        this.onLocked = options.onLocked ?? (() => undefined);
-        this.onProblem = options.onProblem ?? (() => undefined);
-        this.onCommitmentReused = options.onCommitmentReused ?? (() => undefined);
-    }
-    /** 生成新码（旧码立即失效）并通知调用方打印，返回显示形式；后台模式不出码，返回 null */
-    issueCode(reason, origin = null) {
-        if (!this.issueCodes)
-            return null;
-        let code = '';
-        for (let i = 0; i < CODE_LENGTH; i++)
-            code += ALPHABET[randomInt(ALPHABET.length)];
-        this.active = { code, issuedAt: this.now(), failures: 0 };
-        const display = formatCode(code);
-        if (origin)
-            this.lastPrompt.set(origin, { at: this.now(), code });
-        this.onCodeIssued({ display, reason, origin, expiresAt: this.active.issuedAt + CODE_TTL_MS });
-        return display;
-    }
-    hasValidCode() {
-        return this.active !== null && this.now() - this.active.issuedAt <= CODE_TTL_MS;
-    }
-    isLocked() {
-        return this.locked;
-    }
-    /**
-     * 未配对页面连上时调用。没有有效码就出新码；有有效码也把它连同发起方 Origin 再提示一次 ——
-     * 最常见的首次流程是「启动 bridge 后马上打开页面」，终端里只有一个不带 Origin 的启动码，
-     * 不再提示的话用户看不到是哪个页面在请求配对。同一 Origin、同一个码一分钟内只提示一次（页面重连不刷屏）。
-     * 锁定期间、后台模式下什么都不做。
-     */
-    ensureCode(origin) {
-        if (this.locked || !this.issueCodes)
-            return;
-        if (!this.hasValidCode() || !this.active) {
-            this.issueCode('requested', origin);
-            return;
-        }
-        const last = this.lastPrompt.get(origin);
-        if (last && last.code === this.active.code && this.now() - last.at < PROMPT_DEDUPE_MS)
-            return;
-        this.lastPrompt.set(origin, { at: this.now(), code: this.active.code });
-        this.onCodeIssued({ display: formatCode(this.active.code), reason: 'requested', origin, expiresAt: this.active.issuedAt + CODE_TTL_MS });
-    }
-    /**
-     * 配对。保存 token 失败时抛出（调用方回给页面 internal），此时码不被消耗、可以重试。
-     *
-     * 暴力尝试的上限：每个码最多错 MAX_CODE_FAILURES 次（然后换码），自上次成功以来累计错 MAX_TOTAL_FAILURES 次锁定，
-     * 锁定期间不再出码、不再比对，只有重启 bridge 才解除。没有累计上限，换码本身就是无限次尝试
-     * （review r1 实测 1.6 秒 20000 次），还会让陌生页面把用户的配对码一直刷掉。
-     */
-    pair(input, origin) {
-        // 后台模式没有码可比：在锁定检查之前返回，也不计入错码次数（页面并没有猜码，只是不知道这个 bridge 不出码）
-        if (!this.issueCodes)
-            return { ok: false, code: 'pairing_code_unavailable' };
-        if (this.locked)
-            return { ok: false, code: 'pairing_locked' };
-        if (!this.active) {
-            // 码已被消费：请用户看终端里的新码
-            this.issueCode('requested', origin);
-            return { ok: false, code: 'pairing_code_rotated' };
-        }
-        if (!this.hasValidCode()) {
-            this.issueCode('expired', origin);
-            return { ok: false, code: 'pairing_code_rotated' };
-        }
-        const active = this.active;
-        if (sameSecret(normalizePairingCode(input), active.code)) {
-            const token = this.createToken(origin);
-            this.active = null;
-            this.failuresSinceSuccess = 0;
-            return { ok: true, token };
-        }
-        active.failures += 1;
-        this.failuresSinceSuccess += 1;
-        if (this.failuresSinceSuccess >= MAX_TOTAL_FAILURES) {
-            this.locked = true;
-            this.active = null;
-            this.onLocked(origin);
-            return { ok: false, code: 'pairing_locked' };
-        }
-        if (active.failures < MAX_CODE_FAILURES) {
-            const attemptsLeft = Math.min(MAX_CODE_FAILURES - active.failures, MAX_TOTAL_FAILURES - this.failuresSinceSuccess);
-            return { ok: false, code: 'pairing_invalid', attemptsLeft };
-        }
-        this.issueCode('too_many_failures', origin);
-        return { ok: false, code: 'pairing_code_rotated' };
-    }
-    /** 挂上启动命令里的承诺，返回它的过期时刻。格式不对时抛出：由 `--pair` 的参数解析先挡掉。 */
-    armCommitment(commitment) {
-        if (!isPairCommitment(commitment))
-            throw new Error('invalid pairing commitment');
-        const armedAt = this.now();
-        this.commitment = { value: Buffer.from(commitment, 'base64url'), armedAt };
-        return armedAt + CODE_TTL_MS;
-    }
-    /**
-     * 承诺的状态（change desktop-bridge-launcher D15）：M2 Mac 客户端运行启动器交上承诺之后，用它查页面有没有真的配上。
-     * 只读，不改变任何状态；比较用常量时间。只看两个槽：挂着的（10 分钟内）与最近一次用掉的 —— 被更新的承诺替换、过期、
-     * bridge 重启过的都是 unknown，调用方按「还没确认」处理。
-     */
-    commitmentStatus(commitment) {
-        if (!isPairCommitment(commitment))
-            return { state: 'unknown' };
-        const value = Buffer.from(commitment, 'base64url');
-        const armed = this.commitment;
-        if (armed && armed.value.length === value.length && timingSafeEqual(armed.value, value) && this.now() - armed.armedAt <= CODE_TTL_MS) {
-            return { state: 'waiting', until: armed.armedAt + CODE_TTL_MS };
-        }
-        const consumed = this.consumed;
-        if (consumed && consumed.value.length === value.length && timingSafeEqual(consumed.value, value)) {
-            return { state: 'paired', origin: consumed.origin, at: consumed.usedAt };
-        }
-        return { state: 'unknown' };
-    }
-    /**
-     * 页面在 hello 里出示 S。对不上不计入错码次数：S 有 32 字节、承诺有 128 bit，不存在可猜性，
-     * 计入只会让多标签页、旧 S 这类无害的不匹配把用户锁住。锁定期间一律不成立 —— 「锁定只能重启解除」不设例外。
-     * 签发 token 写盘失败时不抛出（hello 里抛出会以 1011 关闭，等待中的页面会反复撞上）、不消费承诺，交给调用方按未配对处理。
-     */
-    pairWithSecret(secret, origin) {
-        const commitment = this.commitment;
-        // 重现检查在锁定检查之前：否则抢先配对的一方再用错码把 bridge 锁住，就能压掉这次告警（review r2 S1）
-        if (!commitment)
-            return this.checkReused(secret, origin);
-        if (this.locked)
-            return { ok: false, reason: 'locked' };
-        if (this.now() - commitment.armedAt > CODE_TTL_MS) {
-            this.commitment = null;
-            return { ok: false, reason: 'expired' };
-        }
-        if (!PAIR_SECRET_RE.test(secret))
-            return { ok: false, reason: 'malformed' };
-        if (!timingSafeEqual(sha256(secret).subarray(0, COMMITMENT_BYTES), commitment.value))
-            return { ok: false, reason: 'mismatch' };
-        let token;
-        try {
-            token = this.createToken(origin);
-        }
-        catch (error) {
-            this.onProblem(`Could not save the pairing (${errorText(error)}). This page will be asked for a pairing code instead.`);
-            return { ok: false, reason: 'store_failed' };
-        }
-        this.commitment = null;
-        this.consumed = { value: commitment.value, origin, usedAt: this.now(), warned: false };
-        this.failuresSinceSuccess = 0;
-        return { ok: true, token };
-    }
-    checkReused(secret, origin) {
-        const consumed = this.consumed;
-        if (!consumed || !PAIR_SECRET_RE.test(secret))
-            return { ok: false, reason: 'no_commitment' };
-        if (!timingSafeEqual(sha256(secret).subarray(0, COMMITMENT_BYTES), consumed.value))
-            return { ok: false, reason: 'no_commitment' };
-        if (!consumed.warned) {
-            consumed.warned = true;
-            this.onCommitmentReused({ origin, firstOrigin: consumed.origin, usedAt: consumed.usedAt });
-        }
-        return { ok: false, reason: 'reused' };
-    }
-    createToken(origin) {
-        const token = randomBytes(32).toString('base64url');
-        const nowIso = new Date(this.now()).toISOString();
-        const records = this.liveRecords();
-        records.push({ id: randomUUID(), tokenHash: sha256(token).toString('hex'), origin, createdAt: nowIso, lastUsedAt: nowIso });
-        // 超出上限时淘汰最久未用的
-        records.sort((a, b) => Date.parse(b.lastUsedAt) - Date.parse(a.lastUsedAt));
-        // 这里的写失败必须抛出：token 没存下来，页面拿到也用不了
-        this.store.save(records.slice(0, MAX_PAIRINGS));
-        return token;
-    }
-    /**
-     * 读出未过期的记录；顺带把过期的从存储里删掉（删不掉只告警：不影响本次判定）。
-     * 每次都从存储读（不缓存）：交接 socket 的门槛论证依赖这一点（`handoff.ts` 文件头），改成缓存时要一起重新评估。
-     */
-    liveRecords() {
-        const all = this.store.load();
-        const live = all.filter((record) => this.now() - Date.parse(record.lastUsedAt) <= TOKEN_IDLE_MS);
-        if (live.length !== all.length)
-            this.trySave(live);
-        return live;
-    }
-    trySave(records) {
-        try {
-            this.store.save(records);
-        }
-        catch (error) {
-            this.onProblem(`Could not update the pairing file (${errorText(error)}). Pairings still work for now but may not survive a restart.`);
-        }
-    }
-    /**
-     * token 有效且与当前 Origin 匹配时返回 true，并刷新 lastUsedAt（闲置期从此刻重新计算）。
-     * 刷新写盘失败只告警、仍判有效：判定本身只依赖读到的记录，不能因为磁盘满让已配对的页面全部掉线（更不能让 bridge 崩溃）。
-     */
-    verifyToken(token, origin) {
-        if (typeof token !== 'string' || token.length === 0)
-            return false;
-        const hash = sha256(token);
-        const records = this.liveRecords();
-        const match = records.find((record) => {
-            const stored = Buffer.from(record.tokenHash, 'hex');
-            return stored.length === hash.length && timingSafeEqual(stored, hash) && record.origin === origin;
-        });
-        if (!match)
-            return false;
-        match.lastUsedAt = new Date(this.now()).toISOString();
-        this.trySave(records);
-        return true;
-    }
-    unpairAll() {
-        this.store.clear();
-    }
-}
-function isRecord(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    const record = value;
-    return ['id', 'tokenHash', 'origin', 'createdAt', 'lastUsedAt'].every((key) => typeof record[key] === 'string');
-}
-/**
- * `~/.m2canvas/bridge-pairings.json`。文件损坏按空处理（用户需要重新配对）并经 onProblem 报告，
- * 不抛错：bridge 仍应能启动，只是之前的配对作废。
- */
-export function createFilePairingStore(path, onProblem = () => undefined) {
-    return {
-        load() {
-            if (!existsSync(path))
-                return [];
-            try {
-                const parsed = JSON.parse(readFileSync(path, 'utf8'));
-                const list = typeof parsed === 'object' && parsed !== null ? parsed.pairings : undefined;
-                if (!Array.isArray(list))
-                    throw new Error('missing "pairings" array');
-                return list.filter(isRecord);
-            }
-            catch (error) {
-                onProblem(`Ignoring unreadable pairing file ${path} (${error instanceof Error ? error.message : String(error)}). Pages will need to pair again.`);
-                return [];
-            }
-        },
-        save(records) {
-            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-            chmodSync(dirname(path), 0o700);
-            writeFileSync(path, `${JSON.stringify({ version: 1, pairings: records }, null, 2)}\n`, { mode: 0o600 });
-            chmodSync(path, 0o600);
-        },
-        clear() {
-            rmSync(path, { force: true });
-        },
-    };
-}