@m2canvas/connect 0.12.0 → 0.14.0

package/dist/bridge/session-token.js

@@ -0,0 +1,332 @@
+/**
+ * 会话令牌模式（change acp-session-m2-token D6 / D7 / T1 / T2；`connect/local-bridge` 契约 3 / 21）。
+ *
+ * M2 客户端主进程替已登录用户领一张 24 小时的 M2 会话令牌，写进 `~/.m2canvas/mcp-session/headers.json`（内容就是
+ * `{"Authorization":"Bearer m2st_…"}`，0600）。bridge 只读、不写不删这个文件；经 1a 客户端认证的连接在 `process/start`
+ * 带上 `m2Session: { userId }` 时，bridge 给这个 agent 进程加一条名为 `patch_session`、地址由 bridge 决定的 MCP 条目：
+ * - Claude：转发页面的 `session/new` / `session/load` / `session/resume` 时补 `_meta.claudeCode.options`
+ *   （`mcpServers` + `settings.deniedMcpServers`）。**三个入口一律补**：漏一个，该进程就没有注入的 M2，而且用户自己的
+ *   M2 条目不再被屏蔽（evidence T16）。页面自己发的 `_meta` 仍由 acp-guard.ts 先拒（这里只处理已经过检查的行）。
+ * - Codex：拉起适配器时设环境变量 `CODEX_CONFIG`（嵌套写法，evidence C4 / C9）。
+ * 令牌不进任何进程的参数与环境变量（macOS 的 /bin/ps 是 setuid root，本机任何账号都能看到全部参数，evidence T1）：
+ * 两家都经 helper 读文件。helper 是 bridge 写好的固定脚本（T1：Codex 只接受一个字符串、npm 包里的脚本装到本机没有执行位），
+ * 内容只有一行 `exec /bin/cat '<令牌文件>'`，不带参数。参数、环境、`_meta`、`CODEX_CONFIG` 里只有地址、脚本路径与屏蔽名单。
+ *
+ * 屏蔽名单：只对本进程生效、不写任何配置文件。按 MCP 主机认条目（`isM2Url`，与 connect 写配置同一判据），不看名字。
+ * - Claude 按名字屏蔽（按地址会连注入那条一起挡住，evidence E-e）；屏蔽不存在的名字没有副作用，所以多读几处：
+ *   `~/.claude.json`（设了 `CLAUDE_CONFIG_DIR` 时另读那里的）的用户级与本目录级、会话目录的 `.mcp.json`。
+ * - Codex 用 `{ enabled: false }`，只列它真会读到的条目：给不存在的条目只写 `enabled` 会让整个配置加载失败（T2 实测）。
+ *   只读 `$CODEX_HOME/config.toml`，用户已有任何名为 `patch_session` 的条目时不进会话令牌模式（深合并会混成一条）。
+ * 漏掉的条目（例如 claude.ai 网页里加的连接器）会与注入那条并存：页面的身份核对（面板契约 8–10）判 mismatch 并锁住进程。
+ *
+ * 维护约束：
+ * - 日志与错误里不得出现令牌或文件内容；只说状态、原因与到期时间。
+ * - 升级 Claude 适配器时（契约 7）复核：`_meta.claudeCode.options` 的 `mcpServers` / `settings` 仍并入 SDK 选项、
+ *   `headersHelper` 原样进 `--mcp-config`、`--settings` 只出现一次（evidence T15）。升级 Codex 时复核 `CODEX_CONFIG`
+ *   在页面不传 `mcpServers` 时仍原样生效、嵌套 `enabled = false` 只关该条、`http_headers_helper` 仍是一个字符串。
+ */
+import { join } from 'node:path';
+import { isM2Url } from '../config-files.js';
+import { isSafeAuthEntry } from './authorize.js';
+import { BridgeFailure } from './errors.js';
+/** 注入条目的名字（D7）。不与 connect 写入名 `patch` 相同：Codex 同名是按键深合并，Claude 同名时 helper 与已存 OAuth 谁优先未测 */
+export const SESSION_ENTRY = 'patch_session';
+/** 剩余有效期不足它就报 `expiring`、不进会话令牌模式（D6）：客户端每 4 小时刷新文件，正常不会低于 20 小时 */
+export const SESSION_READY_MIN_REMAINING_MS = 6 * 3600 * 1000;
+/** 令牌文件的大小上限：正常约 350 字节 */
+const MAX_HEADERS_FILE_BYTES = 4096;
+const TOKEN_TYP = 'm2-mcp-session';
+/** helper 路径能原样交给 shell 执行或直接执行的字符（T1）：家目录名带空格等时不进会话令牌模式 */
+const SAFE_HELPER_PATH = /^\/[A-Za-z0-9._/-]+$/;
+/** 页面传来的 userId：Supabase 用户 id 是 uuid；放宽到常见 id 字符，只用来比对 */
+const USER_ID = /^[A-Za-z0-9-]{1,128}$/;
+/** Claude 适配器会读 `_meta.claudeCode.options` 的会话方法（D6；页面能发的会话类方法里只有这三个会建会话） */
+export const SESSION_INJECT_METHODS = ['session/new', 'session/load', 'session/resume'];
+export function sessionPaths(home) {
+    return {
+        headersFile: join(home, '.m2canvas', 'mcp-session', 'headers.json'),
+        helper: join(home, '.m2canvas', 'bin', 'm2-mcp-session-headers'),
+    };
+}
+export function isUserId(value) {
+    return typeof value === 'string' && USER_ID.test(value);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 读令牌文件的状态（不验签：bridge 没有密钥，只看账号与剩余有效期；签名由服务端验）。
+ * 任何读不了、格式不对、已过期都按 `missing`：页面退回 OAuth 路径并说明原因（D8）。
+ */
+export function readSessionFile(read, headersFile, nowMs) {
+    const text = read(headersFile);
+    if (text === null || text.length > MAX_HEADERS_FILE_BYTES)
+        return { state: 'missing' };
+    let headers;
+    try {
+        headers = JSON.parse(text);
+    }
+    catch {
+        return { state: 'missing' };
+    }
+    if (!isObject(headers) || Object.keys(headers).length !== 1 || typeof headers.Authorization !== 'string')
+        return { state: 'missing' };
+    const match = /^Bearer m2st_([A-Za-z0-9_-]+)\.[A-Za-z0-9_-]{43}$/.exec(headers.Authorization);
+    if (!match)
+        return { state: 'missing' };
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(match[1], 'base64url').toString('utf8'));
+    }
+    catch {
+        return { state: 'missing' };
+    }
+    if (!isObject(payload) || payload.typ !== TOKEN_TYP || !isUserId(payload.sub) || typeof payload.exp !== 'number' || !Number.isFinite(payload.exp)) {
+        return { state: 'missing' };
+    }
+    const expiresAt = payload.exp * 1000;
+    const remaining = expiresAt - nowMs;
+    if (remaining <= 0)
+        return { state: 'missing' };
+    return { state: remaining >= SESSION_READY_MIN_REMAINING_MS ? 'ready' : 'expiring', sub: payload.sub, expiresAt };
+}
+export function isSafeHelperPath(path) {
+    return SAFE_HELPER_PATH.test(path);
+}
+/** helper 脚本的全文：不带参数、不读环境变量，只把令牌文件原样输出（文件就是 helper 要输出的 JSON 请求头） */
+export function helperScript(headersFile) {
+    return `#!/bin/sh\n# M2 local bridge (change acp-session-m2-token): prints the headers of the injected ${SESSION_ENTRY} MCP server.\nexec /bin/cat '${headersFile}'\n`;
+}
+// ───────────────────────────── 屏蔽名单 ─────────────────────────────
+/** 字符串里出现的 http(s) 地址有没有指向 M2（stdio 包装写法把地址放在 args / command 里） */
+function mentionsM2(value) {
+    if (typeof value !== 'string')
+        return false;
+    for (const found of value.match(/https?:\/\/[^\s"'`,\]]+/g) ?? [])
+        if (isM2Url(found))
+            return true;
+    return false;
+}
+/** Claude / `.mcp.json` 形状的一条 server 是否指向 M2：url / serverUrl，或 stdio 包装的 command / args 里带 M2 地址 */
+export function claudeEntryPointsToM2(entry) {
+    if (!isObject(entry))
+        return false;
+    if (isM2Url(entry.url) || isM2Url(entry.serverUrl))
+        return true;
+    if (mentionsM2(entry.command))
+        return true;
+    return Array.isArray(entry.args) && entry.args.some(mentionsM2);
+}
+function namesIn(servers) {
+    if (!isObject(servers))
+        return [];
+    return Object.entries(servers).filter(([, entry]) => claudeEntryPointsToM2(entry)).map(([name]) => name);
+}
+/**
+ * Claude 的 server 名只能是字母、数字、`-`、`_`（随包 claude 2.1.284 的校验文案「Server name can only contain letters, numbers, hyphens,
+ * and underscores」）：屏蔽名单里混进不合规的名字，整份 `--settings` 可能被拒、一条都屏蔽不了，所以 Claude 只收这种名字。
+ */
+const CLAUDE_SERVER_NAME = /^[A-Za-z0-9_-]{1,128}$/;
+function finish(found, valid = isSafeAuthEntry) {
+    const names = [];
+    const skipped = [];
+    for (const name of found) {
+        if (name === SESSION_ENTRY || names.includes(name) || skipped.includes(name))
+            continue;
+        if (valid(name))
+            names.push(name);
+        else
+            skipped.push(name);
+    }
+    return { names, skipped };
+}
+/**
+ * Claude 会读到的、指向 M2 的条目名（D7）。读不了的文件跳过：屏蔽名单是尽力而为，漏掉的由身份核对兜底；
+ * 注入的 `patch_session` 不进名单（Claude 按名字屏蔽，会连注入那条一起挡住，D7 第 3 条）；用户自己恰好有同名条目时以注入那条为准
+ * （evidence 验证点 3「E-同名」：`--mcp-config` 的同名条目整条盖过用户配置，`_meta` 走的也是 `--mcp-config`，T15）。
+ */
+export function claudeM2EntryNames(readJsonFile, options) {
+    const found = [];
+    const configs = [join(options.home, '.claude.json')];
+    if (options.claudeConfigDir)
+        configs.push(join(options.claudeConfigDir, '.claude.json'));
+    for (const path of configs) {
+        const config = readJsonFile(path);
+        if (!isObject(config))
+            continue;
+        found.push(...namesIn(config.mcpServers));
+        const project = isObject(config.projects) ? config.projects[options.cwd] : undefined;
+        if (isObject(project))
+            found.push(...namesIn(project.mcpServers));
+    }
+    const local = readJsonFile(join(options.cwd, '.mcp.json'));
+    if (isObject(local))
+        found.push(...namesIn(local.mcpServers));
+    return finish(found, (name) => CLAUDE_SERVER_NAME.test(name));
+}
+const BARE_OR_QUOTED = String.raw `(?:"([^"\\]+)"|'([^']+)'|([A-Za-z0-9_-]+))`;
+const MULTILINE_QUOTES = ['"""', "'''"];
+const nameOf = (match) => (match[1] ?? match[2] ?? match[3]);
+const SECTION = new RegExp(String.raw `^\[\s*mcp_servers\.${BARE_OR_QUOTED}\s*\]\s*(?:#.*)?$`);
+const SERVERS_TABLE = /^\[\s*mcp_servers\s*\]\s*(?:#.*)?$/;
+/** server 的子表（`[mcp_servers.<名>.env]` 等）：说明这个名字的条目存在（同名冲突要认它），子表里的行不算 server 本身的字段 */
+const SUB_SECTION = new RegExp(String.raw `^\[\s*mcp_servers\.${BARE_OR_QUOTED}\s*\.`);
+const INLINE_ENTRY = new RegExp(String.raw `^${BARE_OR_QUOTED}\s*=\s*\{(.*)\}\s*(?:#.*)?$`);
+/** `[mcp_servers]` 段里的点路径（`m2.url = "…"`）：认它的名字（冲突判断与指向 M2 都按它） */
+const SERVERS_DOTTED = new RegExp(String.raw `^${BARE_OR_QUOTED}\.[A-Za-z0-9_]+\s*=(.*)$`);
+const ROOT_DOTTED = new RegExp(String.raw `^mcp_servers\.${BARE_OR_QUOTED}\s*(?:\.|=)(.*)$`);
+/**
+ * Codex `config.toml` 里指向 M2 的条目名（T2）。不引 TOML 解析器，只认三种写法：`[mcp_servers.<名>]` 段（段内任何一行带 M2 地址
+ * 都算，覆盖 url 与 stdio 包装的 command / args，含跨行数组）、`[mcp_servers]` 段里的行内表、文件开头的点路径。
+ * 认不出的写法不列（不列只是两条并存，列错了会让 Codex 整个配置加载失败），名字一律过 `isSafeAuthEntry`。
+ * 多行字符串（`"""` / `'''`）里的行整段跳过：里面像段头的行不能被当成条目（列出不存在的条目会让 Codex 整个配置加载失败，review r1 S1）。
+ * 已知不认的写法（很少见，tasks CO-10）：文件开头的 `mcp_servers = { … }` 整表行内写法、跨行的行内表 —— 只会漏屏蔽 / 漏判同名
+ * （漏屏蔽由身份核对兜底），不会列出不存在的条目。
+ */
+export function codexM2Entries(toml) {
+    const found = [];
+    const all = new Set();
+    /** null = 文件开头（还没有任何表头）；'servers' = `[mcp_servers]`；其余 = 某个 server 段的名字；'' = 别的表 */
+    let table = null;
+    /** 正在哪种多行字符串里（null = 不在）：里面的行是字符串内容，整行跳过 */
+    let inMultiline = null;
+    for (const raw of (toml ?? '').split(/\r?\n/)) {
+        if (inMultiline !== null) {
+            if (raw.split(inMultiline).length % 2 === 0)
+                inMultiline = null;
+            continue;
+        }
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        // 这一行打开了多行字符串、却没在本行关上：本行照常看（键在这一行），之后的行跳过
+        for (const quote of MULTILINE_QUOTES)
+            if (line.split(quote).length % 2 === 0)
+                inMultiline = quote;
+        if (line.startsWith('[')) {
+            const section = SECTION.exec(line);
+            const sub = section ? null : SUB_SECTION.exec(line);
+            if (section) {
+                table = nameOf(section);
+                all.add(table);
+            }
+            else {
+                if (sub)
+                    all.add(nameOf(sub));
+                table = SERVERS_TABLE.test(line) ? 'servers' : '';
+            }
+            continue;
+        }
+        if (table === null) {
+            const dotted = ROOT_DOTTED.exec(line);
+            if (dotted) {
+                const name = nameOf(dotted);
+                all.add(name);
+                if (mentionsM2(dotted[4]))
+                    found.push(name);
+            }
+            continue;
+        }
+        if (table === 'servers') {
+            const entry = INLINE_ENTRY.exec(line) ?? SERVERS_DOTTED.exec(line);
+            if (entry) {
+                const name = nameOf(entry);
+                all.add(name);
+                if (mentionsM2(entry[4]))
+                    found.push(name);
+            }
+            continue;
+        }
+        if (table !== '' && mentionsM2(line))
+            found.push(table);
+    }
+    return { ...finish(found), conflict: all.has(SESSION_ENTRY) };
+}
+// ───────────────────────────── 注入 ─────────────────────────────
+/** Claude：补进 `session/new` / `load` / `resume` 的 `_meta`（D6，evidence T15 的形状） */
+export function claudeSessionMeta(mcpUrl, helper, denied) {
+    const options = { mcpServers: { [SESSION_ENTRY]: { type: 'http', url: mcpUrl, headersHelper: helper } } };
+    if (denied.length > 0)
+        options.settings = { deniedMcpServers: denied.map((serverName) => ({ serverName })) };
+    return { claudeCode: { options } };
+}
+/**
+ * 给页面发给 Claude 进程、已经过 acp-guard 检查的一行补 `_meta`：只改 `SESSION_INJECT_METHODS` 三个请求，其余原样。
+ * acp-guard 已保证这三个请求的 params 是对象且不带 `_meta`；万一不是对象就原样转发（agent 会自己报错），不在这里编造。
+ */
+export function withClaudeSessionMeta(line, meta) {
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        return line;
+    }
+    if (!isObject(message) || typeof message.method !== 'string' || !SESSION_INJECT_METHODS.includes(message.method) || !isObject(message.params))
+        return line;
+    return JSON.stringify({ ...message, params: { ...message.params, _meta: meta } });
+}
+/** Codex：拉起适配器时的 `CODEX_CONFIG`（嵌套写法；点路径写法无效，evidence C2 / C4） */
+export function codexSessionConfig(mcpUrl, helper, disabled) {
+    const servers = { [SESSION_ENTRY]: { url: mcpUrl, http_headers_helper: helper } };
+    for (const name of disabled)
+        servers[name] = { enabled: false };
+    return JSON.stringify({ mcp_servers: servers });
+}
+function unavailable(message) {
+    return new BridgeFailure('m2_session_unavailable', message);
+}
+export function createSessionTokens(deps) {
+    const paths = sessionPaths(deps.home);
+    const readJsonFile = (path) => {
+        const text = deps.readText(path);
+        if (text === null)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            deps.log(`Could not read ${path} while listing the M2 entries to hide for this session; skipping it.`);
+            return null;
+        }
+    };
+    const logSkipped = (agent, skipped) => {
+        if (skipped.length > 0)
+            deps.log(`${skipped.length} M2 entr${skipped.length === 1 ? 'y' : 'ies'} in ${agent}'s config can't be hidden safely (unusual name); the identity check covers it.`);
+    };
+    return {
+        state() {
+            return readSessionFile(deps.readText, paths.headersFile, deps.now()).state;
+        },
+        prepare(agent, userId) {
+            if (agent !== 'claude' && agent !== 'codex')
+                throw unavailable(`the M2 session token is only for Claude and Codex, not ${agent}`);
+            const file = readSessionFile(deps.readText, paths.headersFile, deps.now());
+            if (file.state !== 'ready' || file.sub === undefined || file.expiresAt === undefined) {
+                throw unavailable(file.state === 'expiring' ? 'the M2 session token expires soon; the M2 desktop app has not refreshed it yet' : 'no usable M2 session token on this machine');
+            }
+            if (file.sub !== userId)
+                throw new BridgeFailure('m2_session_mismatch', 'the M2 session token belongs to a different account than this page');
+            if (!isSafeHelperPath(paths.helper))
+                throw unavailable('the home directory path has characters the agents cannot run a helper from');
+            try {
+                deps.ensureHelper(paths.helper, helperScript(paths.headersFile));
+            }
+            catch (error) {
+                throw unavailable(`could not write the M2 session helper (${error instanceof Error ? error.message : String(error)})`);
+            }
+            if (agent === 'claude') {
+                const { names, skipped } = claudeM2EntryNames(readJsonFile, { home: deps.home, claudeConfigDir: deps.agentEnv.CLAUDE_CONFIG_DIR, cwd: deps.cwd });
+                logSkipped(agent, skipped);
+                const meta = claudeSessionMeta(deps.mcpUrl, paths.helper, names);
+                return { rewritePageLine: (line) => withClaudeSessionMeta(line, meta), expiresAt: file.expiresAt };
+            }
+            const codexHome = deps.agentEnv.CODEX_HOME || join(deps.home, '.codex');
+            const { names, skipped, conflict } = codexM2Entries(deps.readText(join(codexHome, 'config.toml')));
+            if (conflict)
+                throw unavailable(`Codex's config already has an MCP server named "${SESSION_ENTRY}"`);
+            logSkipped(agent, skipped);
+            return { env: { CODEX_CONFIG: codexSessionConfig(deps.mcpUrl, paths.helper, names) }, expiresAt: file.expiresAt };
+        },
+    };
+}

package/dist/bridge/ticket-socket.js

@@ -0,0 +1,104 @@
+/**
+ * 票据 socket（change bridge-client-only D2 / D3 / D4；取代 acp-bridge-one-time-install 的交接 socket）。
+ *
+ * 后台模式的本机连接监听 `~/.m2canvas/bridge-<port>.sock`。M2 客户端主进程在页面每次连本机连接之前来这里领一张一次性票据
+ * （`ticket.ts`），加进那次 WebSocket 握手的 `X-M2-Bridge-Ticket` 请求头；领不到就取消握手。
+ *
+ * 跨版本接口（客户端与本机连接各自更新，版本可能不同；`connect/local-bridge` 契约 13 / 14 草案）：
+ *  - 请求一行（不含换行最多 256 字节）：`{"type":"ticket"}\n`，多出的字段忽略；
+ *  - 回复一行：`{"ok":true,"ticket":"<43 字符>"}` 或 `{"ok":false,"error":"bad_request"}`，回复后断开。
+ *  - 认不出的请求（含旧客户端的 `status{commitment}`、旧启动器的 `arm{nonce}`）一律 `bad_request`。反过来，旧本机连接对
+ *    `ticket` 也回 `bad_request`：M2 客户端据此认出「端口上是用户自己的旧本机连接」，取消握手并带 `--replace` 换掉它（design D11）。
+ *  只能加字段；要改语义就换请求的 type，并让接收方继续认旧的。
+ *
+ * 维护约束：
+ * - 只有同一个账号能连：`~/.m2canvas` 0700、socket 0600。不要把 socket 放到别的目录，也不要放宽权限。
+ *   同一账号的进程能领票据，与今天它能直接改配置、读钥匙串同级（design 威胁分析类别 B）；跑在 agent 命令沙箱里、
+ *   能连 socket 却写不了 `~/.m2canvas` 的进程不另加门槛（design U9，用户 2026-11-08 定先不加；后续评估见 backlog 的「领票据门槛」）。
+ * - 票据不进日志、不进任何文件。
+ * - 每个连接只处理一行、有长度上限、有从连上起算的绝对超时：这是本机进程能碰到的入口，不能让它挂住本机连接或吃内存。
+ * - socket 路径受 macOS 的 sun_path 限制（104 字节含结尾 0）。建不起来时返回 null，调用方必须退出：没有 socket 就没有任何
+ *   页面连得上，留着进程只会让启动器一直报「已在运行」（F7）。
+ */
+import { chmodSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+/** sockaddr_un.sun_path 是 104 字节，含结尾的 0 */
+export const TICKET_SOCKET_MAX_PATH_BYTES = 103;
+export const TICKET_SOCKET_TIMEOUT_MS = 3_000;
+/** `{"type":"ticket"}` 不到 20 字节，留足给以后加字段 */
+const MAX_LINE_BYTES = 256;
+export function ticketSocketPath(dir, port) {
+    return join(dir, `bridge-${port}.sock`);
+}
+/** 路径放不进 sun_path 时给出原因（启动时先查，查出来就不去占端口）；没问题返回 null */
+export function ticketSocketPathProblem(dir, port) {
+    const path = ticketSocketPath(dir, port);
+    return Buffer.byteLength(path) > TICKET_SOCKET_MAX_PATH_BYTES ? `${path} is too long for a local socket (max ${TICKET_SOCKET_MAX_PATH_BYTES} bytes)` : null;
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isTicketRequest(line) {
+    try {
+        const request = JSON.parse(line);
+        return typeof request === 'object' && request !== null && !Array.isArray(request) && request.type === 'ticket';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 后台模式的本机连接在拿到端口之后调用：同名的 socket 残留（上次没清干净）先删掉 —— 端口在自己手里，这个端口的 socket 不可能属于别人。
+ * 返回 null = 没监听（路径太长或建不起来），已记日志；调用方据此退出。
+ */
+export async function listenForTicketRequests(options) {
+    const { dir, port, issue, log } = options;
+    const path = ticketSocketPath(dir, port);
+    const problem = ticketSocketPathProblem(dir, port);
+    if (problem) {
+        log(`The M2 desktop app can't reach this bridge: ${problem}.`);
+        return null;
+    }
+    const server = createServer((socket) => {
+        const deadline = setTimeout(() => socket.destroy(), TICKET_SOCKET_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;
+            socket.end(`${JSON.stringify(isTicketRequest(buffer.slice(0, end)) ? { ok: true, ticket: issue() } : { ok: false, error: 'bad_request' })}\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(`The M2 desktop app can't reach this bridge: couldn't listen on ${path} (${errorText(error)}).`);
+        return null;
+    }
+    return {
+        close() {
+            server.close();
+            rmSync(path, { force: true });
+        },
+    };
+}

package/dist/bridge/ticket.js

@@ -0,0 +1,70 @@
+/**
+ * 本机连接的一次性票据（change bridge-client-only D2 / D4；`connect/local-bridge` 契约 20 草案；19 已由换域名的 D-C1 使用）。
+ *
+ * 本机连接只接受 M2 客户端主进程替页面加了 `X-M2-Bridge-Ticket` 请求头的 WebSocket 握手。票据由后台模式的 socket
+ * （`ticket-socket.ts`，只有本账号能连）按需发出，页面自己既拿不到也看不到。浏览器里的页面加不了自定义请求头，所以天然被拒。
+ *
+ * 不变量（改动前先读 design D2 与威胁分析）：
+ * - 32 字节随机数（base64url，43 字符），内存里只存 sha256；60 秒有效、用一次即作废；没用过的最多 64 张，超出丢最早的。
+ * - 只在发出它的这个进程的内存里，进程退出全部失效 —— 端口抢占者即使收到票据，也只能拿到「已经死掉的那个本机连接发的」票据
+ *   （真本机连接占着端口时抢占者绑不上；它一退出，发过的票据就没用了）。不要落盘、不要跨进程共享、不要写日志。
+ * - 核对与用掉是同一步：不论之后握手成败，出示过的票据都不能再用。
+ * - 年龄为负（时钟往回拨过）当作过期，与预检缓存（契约 18）的口径一致。
+ */
+import { createHash, randomBytes } from 'node:crypto';
+export const TICKET_TTL_MS = 60_000;
+export const MAX_UNUSED_TICKETS = 64;
+const TICKET_BYTES = 32;
+/** 32 字节的 base64url（无填充）恰好 43 个字符 */
+const TICKET_RE = /^[A-Za-z0-9_-]{43}$/;
+export function isTicketShape(value) {
+    return TICKET_RE.test(value);
+}
+function digest(ticket) {
+    return createHash('sha256').update(ticket).digest('hex');
+}
+export class TicketBook {
+    now;
+    /** sha256 → 发出时刻。Map 按插入顺序迭代，最早发出的在前，超额时从头丢 */
+    unused = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    issue() {
+        this.prune();
+        while (this.unused.size >= MAX_UNUSED_TICKETS) {
+            const oldest = this.unused.keys().next();
+            if (oldest.done)
+                break;
+            this.unused.delete(oldest.value);
+        }
+        const ticket = randomBytes(TICKET_BYTES).toString('base64url');
+        this.unused.set(digest(ticket), this.now());
+        return ticket;
+    }
+    /** 核对并用掉。不是本进程发的、过期、用过、格式不对都返回 false */
+    redeem(ticket) {
+        if (typeof ticket !== 'string' || !isTicketShape(ticket))
+            return false;
+        const key = digest(ticket);
+        const issuedAt = this.unused.get(key);
+        if (issuedAt === undefined)
+            return false;
+        this.unused.delete(key);
+        return this.fresh(issuedAt);
+    }
+    /** 还能用的票据张数（测试与日志用） */
+    get size() {
+        this.prune();
+        return this.unused.size;
+    }
+    fresh(issuedAt) {
+        const age = this.now() - issuedAt;
+        return age >= 0 && age < TICKET_TTL_MS;
+    }
+    prune() {
+        for (const [key, issuedAt] of this.unused)
+            if (!this.fresh(issuedAt))
+                this.unused.delete(key);
+    }
+}

package/dist/bridge/uninstall-call.js

@@ -30,8 +30,8 @@ async function perform(ctx, uninstaller, request) {
 }
 /** 开始卸载；不能开始时返回要回给页面的错误（什么都不做） */
 export function startUninstall(ctx, request) {
-    if (!request.paired)
-        return { code: 'not_paired', message: 'pair this page first' };
+    if (!request.authenticated)
+        return { code: 'not_paired', message: 'this connection was not authorized by the M2 desktop app' };
     // 只能省略或是空对象：null、数组、字符串都不当成 {}；自有属性一个都不能有（`__proto__` 之类的也算）—— 页面不能传任何影响卸载的东西
     const { params } = request;
     const empty = params === undefined || (typeof params === 'object' && params !== null && !Array.isArray(params) && Object.keys(params).length === 0);

package/dist/bridge/uninstall.js

@@ -62,7 +62,7 @@ export async function runSelfUninstall(deps) {
         };
     }
     try {
-        deps.closeHandoff();
+        deps.closeTicketSocket();
     }
     catch {
         // socket 文件删不掉不影响卸载：脚本会把停掉的 bridge 的 socket 一并删掉

package/dist/bridge/update.js

@@ -17,7 +17,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { ADAPTERS, ADAPTER_READY_MARKER, adapterInstallDirName } from './adapters.js';
-import { NODE_PATH_FILE, connectCliPath, connectPackageDir } from './install-layout.js';
+import { NODE_PATH_FILE, connectCliPath, connectPackageDir, installLayout } from './install-layout.js';
 import { readInstanceRecord } from './instance.js';
 import { tail } from './precheck-parse.js';
 import { MANIFEST_URL, connectTarballUrls, isReleaseVersion, nodeDirName, nodeTarballUrls, parseReleaseManifest, wsTarballUrls, } from './release-manifest.js';
@@ -52,6 +52,26 @@ export function readRejected(path) {
         return [];
     }
 }
+/** welcome 里最多带几个拉黑的版本（change bridge-normal-update D6）：文件只增不减，只报最近的 */
+export const MAX_REPORTED_REJECTED = 20;
+/** 报给页面的拉黑名单：合法版本号、去重、保留最近的 {@link MAX_REPORTED_REJECTED} 个（按写入先后） */
+export function recentRejected(path) {
+    const unique = [];
+    for (const version of readRejected(path).reverse()) {
+        if (!unique.includes(version))
+            unique.push(version);
+        if (unique.length === MAX_REPORTED_REJECTED)
+            break;
+    }
+    return unique.reverse();
+}
+/**
+ * 交给 `startBridgeServer` 的拉黑名单来源（D6）：只有后台模式（由启动器拉起，才有拉黑这回事）注入；每次 welcome 现读。
+ * 终端模式返回空对象，welcome 不带 `rejected`。
+ */
+export function welcomeRejectedOption({ background, home }) {
+    return background ? { rejectedVersions: () => recentRejected(installLayout(home).rejected) } : {};
+}
 function readNodePath(versionDir) {
     try {
         const value = readFileSync(join(versionDir, NODE_PATH_FILE), 'utf8').trim();

package/dist/cli.js

@@ -26,7 +26,8 @@ sign-in steps.
   --dry-run      only show what would change
   -h, --help     show this help
 
-  bridge         run the local agent bridge so M2 can use the agents on this machine`;
+  bridge         run by the M2 desktop app so M2 can use the agents on this machine
+                 (local agents only work inside the M2 desktop app)`;
 async function confirm(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {

package/install/uninstall.sh

@@ -7,7 +7,8 @@
 #      SIGTERM, so it shuts down its agents cleanly).
 #   2. Removes what the installer put in ~/.m2canvas: runtime, bridge, bin, logs, acp-adapters,
 #      the pairing records, the bridge state files, pairing-handoff sockets and leftover
-#      handoff files.
+#      handoff files, and the M2 session token the M2 desktop app keeps for the bridge
+#      (mcp-session).
 #   3. Removes ~/.m2canvas/workspace only if it is empty; otherwise keeps it and prints its path.
 #      Removes ~/.m2canvas itself only if nothing else is left in it.
 # It does not touch your agents' M2 settings (set up by npx @m2canvas/connect, they work
@@ -80,7 +81,7 @@ main() {
 
   # 2. Remove what the installer created, and check that it is really gone.
   FAILED=""
-  for NAME in runtime bridge bin logs acp-adapters bridge-pairings.json; do
+  for NAME in runtime bridge bin logs acp-adapters bridge-pairings.json mcp-session; do
     rm -rf "${M2_HOME:?}/${NAME}"
     if [ -e "${M2_HOME}/${NAME}" ]; then
       FAILED="${FAILED} ${M2_HOME}/${NAME}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Connect your local agent clients (Claude Code, Codex, Cursor, OpenCode, Qoder) to M2 Canvas over MCP in one command, and run the local bridge that lets M2 drive them over ACP.",
   "type": "module",
   "bin": {