@m2canvas/connect 0.11.0 → 0.13.0

package/dist/bridge/security.js

@@ -1,22 +1,5 @@
-/**
- * 本机 ACP bridge 的连接准入判定（纯函数）。在 HTTP upgrade 阶段、完成 WebSocket 握手之前调用。
- *
- * 这里管的是「谁能连上来」：Origin 白名单与只接受本机连接（第三道「配对 token」在 pairing.ts）。
- * 浏览器这层不可依赖：开了本机代理的用户，Chrome 不会弹本地网络访问框（ACP PoC 报告 §3），
- * 所以任何网站都能尝试连 127.0.0.1，只能靠 bridge 自己挡。
- * 连上并配对之后页面能做什么，见 server.ts / acp-guard.ts 的文件头：配对 = 授权该页面驱动本机 agent。
- *
- * 维护约束：
- * - Origin 必须精确匹配（scheme + host + port 全等）。不要改成后缀匹配、正则或「包含主站主机名」——
- *   `https://<主站主机>.evil.com`、`https://evil.<主站主机>` 都必须被拒。名单作为参数传入：名单为空即全部拒绝。
- * - 默认只放行主站。开发域名只在 `bridge --dev` 时放行：`localhost:5173` 是所有本机 Vite 项目共用的 Origin、
- *   共用 localStorage，给开发版 M2 配对过后，任何跑在 5173 的项目（包括它的依赖）都能读走 token 免码连上
- *   （review r3 B2，用户 2026-10-02 拍板改为 --dev，推翻了最初的「开发域名常开」）。名单写死在包里（主站 origin 在
- *   `site-config.ts`），不提供任意扩展参数。
- * - Host 校验防 DNS rebinding：攻击者域名解析到 127.0.0.1 时，Host 头是攻击者域名。
- */
 import { PROD_ORIGINS } from '../site-config.js';
-import { BRIDGE_WS_PATH } from './protocol.js';
+import { BRIDGE_TICKET_HEADER, BRIDGE_WS_PATH } from './protocol.js';
 export { PROD_ORIGINS };
 /** 本地开发 M2 用（Vite 默认端口）；只有 `bridge --dev` 才放行 */
 export const DEV_ORIGINS = ['http://localhost:5173', 'http://127.0.0.1:5173'];
@@ -34,13 +17,19 @@ export function isAllowedHost(host, port) {
 export function isLoopbackAddress(address) {
     return address === '127.0.0.1' || address === '::ffff:127.0.0.1' || address === '::1';
 }
-const MAX_REPORTED_ORIGIN_CHARS = 200;
+/** Node 把请求头名转成小写；同名头出现多次时自定义头会被拼成一个字符串（再由票据格式挡掉），数组一律当没有 */
+export function readTicketHeader(headers) {
+    const value = headers[BRIDGE_TICKET_HEADER.toLowerCase()];
+    return typeof value === 'string' ? value : undefined;
+}
 /**
  * 拒绝时返回 HTTP 状态，由调用方直接写回并销毁 socket，不完成握手。
- * 403 而不是「握手后再关」：不对非白名单页面完成任何握手。注意这挡不住「探测 bridge 是否在运行」——
+ * 403 / 401 而不是「握手后再关」：不对非白名单页面、没有票据的连接完成任何握手。注意这挡不住「探测 bridge 是否在运行」——
  * 任何网站用 no-cors 请求 http://127.0.0.1:<port>/ 都能分辨「有响应」与「连接被拒」，只暴露这一点信息。
+ *
+ * `redeem` 核对并用掉票据（TicketBook.redeem）；只在前三条都通过后调用。
  */
-export function checkUpgrade(info, port, origins) {
+export function checkUpgrade(info, port, origins, redeem) {
     const pathname = (info.path ?? '').split('?')[0];
     if (pathname !== BRIDGE_WS_PATH)
         return { ok: false, status: 404, reason: `unknown path ${pathname}` };
@@ -48,10 +37,11 @@ export function checkUpgrade(info, port, origins) {
         return { ok: false, status: 403, reason: `remote ${info.remoteAddress ?? 'unknown'}` };
     if (!isAllowedHost(info.host, port))
         return { ok: false, status: 403, reason: `host ${info.host ?? 'missing'}` };
-    if (!isAllowedOrigin(info.origin, origins)) {
-        if (info.origin === undefined)
-            return { ok: false, status: 403, reason: 'origin missing' };
-        return { ok: false, status: 403, reason: `origin ${info.origin}`, rejectedOrigin: info.origin.slice(0, MAX_REPORTED_ORIGIN_CHARS) };
-    }
-    return { ok: true };
+    if (!isAllowedOrigin(info.origin, origins))
+        return { ok: false, status: 403, reason: info.origin === undefined ? 'origin missing' : `origin ${info.origin}` };
+    if (info.ticket === undefined)
+        return { ok: false, status: 401, reason: 'missing ticket' };
+    if (!redeem(info.ticket))
+        return { ok: false, status: 401, reason: 'invalid ticket' };
+    return { ok: true, auth: 'client-ticket' };
 }

package/dist/bridge/server.js

@@ -1,17 +1,19 @@
 /**
- * 本机 ACP bridge 的 HTTP + WebSocket 服务：连接准入、握手、配对、方法分派、ACP 转发（页面 → agent 先经 acp-guard.ts 检查，agent → 页面原样）、心跳与清理。
+ * 本机 ACP bridge 的 HTTP + WebSocket 服务：连接准入、握手、方法分派、ACP 转发（页面 → agent 先经 acp-guard.ts 检查，agent → 页面原样）、心跳与清理。
  * 协议规范见 protocol.ts 文件头指向的 design「页面协议」一节。
  *
- * 安全模型（改动前先读 security.ts / pairing.ts / acp-guard.ts 的文件头）：
- * **配对 = 授权该页面以用户的身份驱动本机 agent**，包括让 agent 读写文件、执行命令（提示词、替用户回答审批、切换工作模式
- * 都由页面发出）。所以安全的重心在「谁能配对」，配对之后能做的事只做纵深防御：
- * - 只监听 127.0.0.1；upgrade 校验（对端、Host、Origin、路径）在完成握手之前，失败直接写 HTTP 状态并销毁 socket。
- * - 握手后第一条消息必须是 hello；未配对的连接只能调用 pair，其余已知方法与 acp 帧一律 not_paired。
- *   连接只有两种方式成为已配对：hello 带有效 token，或 hello 的 pairSecret 与启动命令的承诺一致（pairing.ts 文件头）。
- * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、授权动作（枚举校验）、配对码、processId —— 进不了 spawn 的命令、参数、cwd、环境。
+ * 安全模型（改动前先读 security.ts / ticket.ts / acp-guard.ts 的文件头）：
+ * **连上 = 授权该页面以用户的身份驱动本机 agent**，包括让 agent 读写文件、执行命令（提示词、替用户回答审批、切换工作模式
+ * 都由页面发出）。所以安全的重心在「谁能连上」，连上之后能做的事只做纵深防御：
+ * - 只监听 127.0.0.1；upgrade 校验（对端、Host、Origin、路径、M2 客户端主进程替页面加的一次性票据）在完成握手之前，
+ *   失败直接写 HTTP 状态并销毁 socket（change bridge-client-only D4）。没有任何不经票据的连接，也没有配对。
+ * - 握手后第一条消息必须是 hello，且只认 protocols 与 client：带 token / pairSecret（旧页面）或其他键一律 bad_message 并关闭。
+ * - 每条被接受的连接标记 `auth: 'client-ticket'`；方法调用、acp 帧、广播都再判一次（纵深判断，正常走不到另一支），
+ *   以后只开给客户端认证连接的能力（1b 的会话令牌模式）也按这个标记判。
+ * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、授权动作（枚举校验）、processId —— 进不了 spawn 的命令、参数、cwd、环境。
  *   方法分派在 call-dispatch.ts；agent/authorize 与 agent/authorize-cancel 的 params 只能有规定的键，多一个就 bad_message（auth-call.ts，命令清单写死在 authorize.ts）。
  * - 页面发给 agent 的 ACP 行禁止含换行，并经 acp-guard.ts 检查：只能用白名单里的方法、会话目录固定为 bridge 的 cwd、不能让 agent 额外拉起 MCP 服务器。
- * - bridge/uninstall（0.8.0，uninstall-call.ts）：开始后拒绝新连接与一切其他帧（握手与配对会写盘、重建 ~/.m2canvas），端口占到退出，结果回出去后退出。
+ * - bridge/uninstall（0.8.0，uninstall-call.ts）：开始后拒绝新连接与一切其他帧，端口占到退出，结果回出去后退出。
  *
  * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责）。
  * 登录 / m2 授权只代跑写死清单里的命令，授权页由用户在浏览器里亲自完成（authorize.ts）；授权链接只发给发起的连接，不进终端日志。
@@ -24,31 +26,35 @@ import { handleCall } from './call-dispatch.js';
 import { AuthorizationManager } from './authorize.js';
 import { BRIDGE_CLOSE_CODES, BRIDGE_METHODS, BRIDGE_SUPPORTED_PROTOCOLS, } from './protocol.js';
 import { checkPageAcpLine } from './acp-guard.js';
-import { checkUpgrade } from './security.js';
+import { checkUpgrade, readTicketHeader } from './security.js';
 import { BridgeFailure } from './service.js';
 import { startUninstall } from './uninstall-call.js';
 export const HELLO_TIMEOUT_MS = 10_000;
-export const UNPAIRED_TIMEOUT_MS = 10 * 60 * 1000;
-export const MAX_UNPAIRED_CONNECTIONS = 4;
 export const PING_INTERVAL_MS = 30_000;
 export const MAX_FRAME_BYTES = 64 * 1024 * 1024;
 export const REJECT_LOG_WINDOW_MS = 60_000;
 const MAX_CALL_ID = 64;
+/** hello 里只认这几个键（change bridge-client-only D4）：带 token / pairSecret 的旧页面与任何多出的键一律 bad_message */
+const HELLO_KEYS = new Set(['type', 'protocols', 'client']);
+/** 纵深判断：只有经 M2 客户端票据认证、且完成了 hello 的连接才能调用方法、收发 acp 与广播 */
+function isReady(conn) {
+    return conn.hello && conn.auth === 'client-ticket';
+}
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function isMethod(value) {
     return typeof value === 'string' && BRIDGE_METHODS.includes(value);
 }
+const STATUS_TEXT = { 401: 'Unauthorized', 403: 'Forbidden', 404: 'Not Found', 503: 'Service Unavailable' };
 function rejectUpgrade(socket, status) {
-    const text = status === 403 ? 'Forbidden' : status === 404 ? 'Not Found' : 'Service Unavailable';
+    const text = STATUS_TEXT[status];
     socket.end(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
     socket.destroy();
 }
 export function startBridgeServer(options) {
     const timing = {
         helloTimeoutMs: options.timing?.helloTimeoutMs ?? HELLO_TIMEOUT_MS,
-        unpairedTimeoutMs: options.timing?.unpairedTimeoutMs ?? UNPAIRED_TIMEOUT_MS,
         pingIntervalMs: options.timing?.pingIntervalMs ?? PING_INTERVAL_MS,
     };
     const connections = new Map();
@@ -110,26 +116,13 @@ export function startBridgeServer(options) {
         },
         log,
     };
-    const unpairedCount = () => [...connections.values()].filter((conn) => !conn.paired).length;
-    const markPaired = (conn) => {
-        conn.paired = true;
-        if (conn.timer)
-            clearTimeout(conn.timer);
-        conn.timer = null;
-    };
     const callContext = {
         cwd: options.cwd,
-        pairing: options.pairing,
         service: options.service,
         processes,
         auth: authContext,
         log,
         isConnected: (connectionId) => connections.has(connectionId),
-        markPaired: (connectionId) => {
-            const conn = connections.get(connectionId);
-            if (conn)
-                markPaired(conn);
-        },
     };
     function onHello(conn, frame) {
         const protocols = Array.isArray(frame.protocols) ? frame.protocols.filter((value) => typeof value === 'number') : [];
@@ -143,48 +136,31 @@ export function startBridgeServer(options) {
             conn.ws.close(BRIDGE_CLOSE_CODES.protocolUnsupported, 'protocol unsupported');
             return;
         }
-        // conn.hello 等 welcome 发出前一刻才置位：中间任何一步抛异常时，消息监听器的 catch 看到「还在握手」，
-        // 以 1011 关闭连接，而不是留下一个收不到 welcome、计时器又已清掉的挂起连接
+        const extra = Object.keys(frame).filter((key) => !HELLO_KEYS.has(key));
+        if (extra.length > 0) {
+            // 旧页面（带 token / pairSecret）刷新后就好；键名截短，不把页面给的任意内容原样写进日志
+            const names = extra.slice(0, 3).map((key) => key.slice(0, 32)).join(', ');
+            if (options.verbose)
+                log(`Refused a hello from ${conn.origin} with unexpected fields (${names}).`);
+            sendError(conn, null, { code: 'bad_message', message: `hello only accepts protocols and client (got ${names}); reload M2` });
+            conn.ws.close(BRIDGE_CLOSE_CODES.badHandshake, 'unexpected hello fields');
+            return;
+        }
         if (conn.timer)
             clearTimeout(conn.timer);
         conn.timer = null;
-        const token = typeof frame.token === 'string' ? frame.token : undefined;
-        let paired = options.pairing.verifyToken(token, conn.origin);
-        // 命令承诺配对：在未配对名额检查之前 —— 合法页面不被别人占满的未配对名额挡住。对不上（含写盘失败）一律按未配对继续，不抛出
-        let issuedToken;
-        if (!paired && typeof frame.pairSecret === 'string') {
-            const result = options.pairing.pairWithSecret(frame.pairSecret, conn.origin);
-            if (result.ok) {
-                paired = true;
-                issuedToken = result.token;
-                log(`Paired with ${conn.origin}.`);
-            }
-            else if (options.verbose)
-                log(`${conn.origin} did not pair from the start command (${result.reason}).`);
-        }
-        if (paired) {
-            markPaired(conn);
-        }
-        else {
-            if (unpairedCount() > MAX_UNPAIRED_CONNECTIONS) {
-                conn.ws.close(BRIDGE_CLOSE_CODES.tooManyUnpaired, 'too many unpaired pages');
-                return;
-            }
-            options.pairing.ensureCode(conn.origin);
-            conn.timer = setTimeout(() => conn.ws.close(BRIDGE_CLOSE_CODES.timeout, 'pairing timed out'), timing.unpairedTimeoutMs);
-        }
         const client = isObject(frame.client) && typeof frame.client.name === 'string' ? ` (${frame.client.name})` : '';
         if (options.verbose)
-            log(`Page connected from ${conn.origin}${client}, ${paired ? 'paired' : 'not paired'}.`);
+            log(`Page connected from ${conn.origin}${client}.`);
         conn.hello = true;
         send(conn, {
             type: 'welcome',
             protocol: Math.max(...common),
             bridge: options.bridge,
-            paired,
-            tokenRejected: token !== undefined && !paired,
-            cwd: paired ? options.cwd : null,
-            ...(issuedToken ? { token: issuedToken } : {}),
+            // 页面侧类型在 1a 阶段 B 才删：这三个字段的形状对现有页面不变（恒为已连上）
+            paired: true,
+            tokenRejected: false,
+            cwd: options.cwd,
         });
     }
     function onFrame(conn, data, isBinary) {
@@ -200,7 +176,7 @@ export function startBridgeServer(options) {
             frame = null;
         }
         if (uninstalling) {
-            // 卸载开始后：不再握手（带 token 的 hello 会刷新使用时间、写配对文件），也不再处理任何调用
+            // 卸载开始后：不再握手，也不再处理任何调用
             if (!conn.hello)
                 return conn.ws.close(BRIDGE_CLOSE_CODES.goingAway, 'bridge is uninstalling');
             const id = isObject(frame) && typeof frame.id === 'string' && frame.id.length > 0 && frame.id.length <= MAX_CALL_ID ? frame.id : null;
@@ -217,9 +193,11 @@ export function startBridgeServer(options) {
             sendError(conn, null, { code: 'bad_message', message: 'frame must be a JSON object' });
             return;
         }
+        if (!isReady(conn)) {
+            // 纵深判断：upgrade 只放行带有效票据的连接，正常走不到这里
+            return sendError(conn, null, { code: 'not_paired', message: 'this connection was not authorized by the M2 desktop app' });
+        }
         if (frame.type === 'acp') {
-            if (!conn.paired)
-                return sendError(conn, null, { code: 'not_paired', message: 'pair this page first' });
             const { processId, line } = frame;
             if (typeof processId !== 'string' || typeof line !== 'string' || /[\r\n]/.test(line)) {
                 return sendError(conn, null, { code: 'bad_message', message: 'acp frame needs processId and a single-line "line"' });
@@ -242,7 +220,7 @@ export function startBridgeServer(options) {
                 return sendError(conn, id, { code: 'unknown_method', message: `unknown method ${String(method)}` });
             const params = isObject(frame.params) ? frame.params : {};
             if (method === 'bridge/uninstall') {
-                const refusal = startUninstall(uninstallContext, { paired: conn.paired, params: frame.params, reply: (result) => sendAndWait(conn, { type: 'result', id, result }) });
+                const refusal = startUninstall(uninstallContext, { authenticated: isReady(conn), params: frame.params, reply: (result) => sendAndWait(conn, { type: 'result', id, result }) });
                 if (refusal)
                     sendError(conn, id, refusal);
                 return;
@@ -269,16 +247,15 @@ export function startBridgeServer(options) {
         if (uninstalling)
             return rejectUpgrade(socket, 503);
         const port = http.address()?.port ?? options.port;
-        const decision = checkUpgrade({ origin: req.headers.origin, host: req.headers.host, remoteAddress: req.socket.remoteAddress, path: req.url }, port, options.allowedOrigins);
+        const decision = checkUpgrade({ origin: req.headers.origin, host: req.headers.host, remoteAddress: req.socket.remoteAddress, path: req.url, ticket: readTicketHeader(req.headers) }, port, options.allowedOrigins, (ticket) => options.tickets.redeem(ticket));
         if (!decision.ok) {
             rejectLog.note(decision.reason);
-            if (decision.rejectedOrigin !== undefined)
-                options.onOriginRejected?.(decision.rejectedOrigin);
             rejectUpgrade(socket, decision.status);
             return;
         }
+        const auth = decision.auth;
         wss.handleUpgrade(req, socket, head, (ws) => {
-            const conn = { id: randomUUID(), ws, origin: req.headers.origin, hello: false, paired: false, alive: true, timer: null };
+            const conn = { id: randomUUID(), ws, origin: req.headers.origin, auth, hello: false, alive: true, timer: null };
             connections.set(conn.id, conn);
             conn.timer = setTimeout(() => ws.close(BRIDGE_CLOSE_CODES.timeout, 'hello timed out'), timing.helloTimeoutMs);
             ws.on('pong', () => {
@@ -310,7 +287,7 @@ export function startBridgeServer(options) {
             ws.on('error', () => undefined);
         });
     });
-    // 被拒连接的终端日志限频：任何网站都能反复连 127.0.0.1，逐条打印会把配对码和「X wants to pair」顶出视野（review r3 S5）。
+    // 被拒连接的日志限频：任何网站都能反复连 127.0.0.1，逐条打印会刷满日志（review r3 S5）。
     // 同一原因在一个窗口内只打第一条，窗口结束时汇总被合并的次数。
     const rejectWindowMs = options.timing?.rejectLogWindowMs ?? REJECT_LOG_WINDOW_MS;
     const rejectLog = (() => {
@@ -369,7 +346,7 @@ export function startBridgeServer(options) {
                 authorizations,
                 broadcast(event, data) {
                     for (const conn of connections.values())
-                        if (conn.paired)
+                        if (isReady(conn))
                             send(conn, { type: 'event', event, data });
                 },
                 close() {

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/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/dist/clients.js

@@ -6,7 +6,7 @@ function jsonExisting(path, find) {
     const read = readJson(path);
     return read.kind === 'ok' ? find(read.value) : null;
 }
-/** 用户级 server 表里同名 `m2` 指向别处 → blocked 提示（D-C1）；读不出文件按无冲突，由客户端自己的 CLI 报错 */
+/** 用户级 server 表里同名（`SERVER_NAME`）入口指向别处 → blocked 提示（D-C1）；读不出文件按无冲突，由客户端自己的 CLI 报错 */
 function jsonConflict(path, servers) {
     const read = readJson(path);
     return read.kind === 'ok' && hasNameConflictInServers(servers(read.value)) ? nameConflictNote(path) : null;

package/dist/config-files.js

@@ -1,8 +1,13 @@
-// 各客户端配置文件的纯函数读写：查已有 m2 入口、按原格式合并。全部不碰磁盘，便于单测。
+// 各客户端配置文件的纯函数读写：查已有的本产品入口（按 MCP 主机认，不看名字）、按原格式合并。全部不碰磁盘，便于单测。
 // MCP 地址来自 site-config.ts（connect 唯一的站点配置来源），这里转出供 cli.ts / clients.ts 沿用原导出名。
 import { M2_MCP_URL, MCP_HOST } from './site-config.js';
 export { M2_MCP_URL };
-export const SERVER_NAME = 'm2';
+/**
+ * connect 写进各家 agent 配置的条目名（change mcp-entry-name-patch，2026-11-10 起由 `m2` 改为 `patch`）。
+ * 只用于新写入与同名冲突判断；识别已有条目一律按 MCP 主机（`isM2Url`），所以改名前写下、指向当前主机的 `m2`
+ * 照常认作已配置，不改名、不追加第二条（design D2）。网站接入片段与 `agent-setup.md` 用同一个名字，改动时同步。
+ */
+export const SERVER_NAME = 'patch';
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -28,9 +33,10 @@ export function findM2Entry(servers) {
     return null;
 }
 /**
- * server 表里已有名为 `m2`、但不指向 M2 的入口（change domain-cutover design D-C1）。
- * 我们只会以 `m2` 这个名字写入；同名入口指向别处时既不能追加（Codex 的 TOML 会出现重复表、整个文件解析失败），
- * 也不能覆盖（那可能是用户自己的 server，或换域名前留下的旧入口，静默改掉用户看不出发生了什么）。一律报冲突交给用户。
+ * server 表里已有名为 `SERVER_NAME`、但不指向当前 MCP 主机的入口（change domain-cutover design D-C1，
+ * mcp-entry-name-patch D3 起判的是 `patch`）。我们只会以这个名字写入；同名入口指向别处时既不能追加
+ * （Codex 的 TOML 会出现重复表、整个文件解析失败），也不能覆盖（那可能是用户自己的 server，静默改掉用户看不出发生了什么）。
+ * 一律报冲突交给用户。
  */
 export function hasNameConflictInServers(servers) {
     if (!isObject(servers) || !Object.hasOwn(servers, SERVER_NAME))
@@ -40,7 +46,7 @@ export function hasNameConflictInServers(servers) {
 }
 /** 同名冲突的提示（给 ClientPlan.blocked 用）：说明不改的原因与用户要做的事，不打印对方的地址 */
 export function nameConflictNote(where) {
-    return `${where} already has an MCP server named "${SERVER_NAME}" that does not point to M2 (for example one left from an old M2 address). Remove or rename it, then run this again.`;
+    return `${where} already has an MCP server named "${SERVER_NAME}" that does not point to Patch (${MCP_HOST}). Remove or rename it, then run this again.`;
 }
 /** Claude Code `~/.claude.json` 顶层 mcpServers = user scope。 */
 export function findInClaudeConfig(config) {
@@ -73,7 +79,7 @@ export function findInCodexToml(toml) {
     }
     return null;
 }
-/** Codex `config.toml` 里已有 `[mcp_servers.m2]` 段且段内 url 不指向 M2（判定见 `hasNameConflictInServers`） */
+/** Codex `config.toml` 里已有 `[mcp_servers.<SERVER_NAME>]` 段且段内 url 不指向当前 MCP 主机（判定见 `hasNameConflictInServers`） */
 export function hasCodexNameConflict(toml) {
     let inTarget = false;
     let found = false;
@@ -132,7 +138,7 @@ export function mergeOpencodeConfig(config) {
     return { existing: null, conflict: false, config: { ...base, mcp: nextMcp } };
 }
 /**
- * Codex `config.toml` 追加 m2 段。不走 `codex mcp add`：它在没有已存 token 时会顺手启动 OAuth
+ * Codex `config.toml` 追加 `[mcp_servers.<SERVER_NAME>]` 段。不走 `codex mcp add`：它在没有已存 token 时会顺手启动 OAuth
  * 并阻塞等浏览器回调（实测），agent 代跑时输出被捕获、链接不可见，命令永远不返回。
  * 只做追加、不解析重写，用户原有内容与注释逐字保留；调用方先用 findInCodexToml 判重。
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.11.0",
+  "version": "0.13.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": {