@m2canvas/connect 0.12.0 → 0.14.0

package/dist/bridge/processes.js

@@ -18,6 +18,25 @@ export const KILL_GRACE_MS = 3_000;
 export const MAX_LINE_CHARS = 64 * 1024 * 1024;
 const STDERR_KEEP = 8 * 1024;
 const STDERR_REPORT = 4 * 1024;
+/**
+ * M2 会话令牌（`m2st_…`，change acp-session-m2-token）的打码：stderr 尾巴会经 `process/exited` 发给页面（页面里跑着不可信的 DS 代码），
+ * agent 在 helper 出错或令牌被拒时会不会把请求头打到 stderr 不受我们控制（review r1 残余风险），所以转发前一律替换掉。
+ * 正在写的半截令牌（只有 `m2st_` 开头）也替换。
+ */
+export function redactSessionTokens(text) {
+    return text.replace(/m2st_[A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]*)?/g, 'm2st_[redacted]');
+}
+/**
+ * 只留最后 `max` 个字符；被截断时从第一个空白之后开始 —— 令牌不含空白，截在令牌中间时丢掉那半截
+ * （否则 `m2st_` 前缀已被截掉、只剩签名段，打码认不出它）。
+ */
+export function keepTail(text, max) {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(-max);
+    const space = cut.search(/\s/);
+    return space === -1 ? '' : cut.slice(space);
+}
 export class ProcessError extends Error {
     code;
     constructor(code, message) {
@@ -96,7 +115,7 @@ export class ProcessManager {
         try {
             child = spawn(launch.command, launch.args, {
                 cwd: this.options.cwd,
-                env: this.options.env,
+                env: launch.env ? { ...this.options.env, ...launch.env } : this.options.env,
                 stdio: ['pipe', 'pipe', 'pipe'],
                 detached: process.platform !== 'win32',
                 windowsHide: true,
@@ -107,7 +126,7 @@ export class ProcessManager {
             this.adjustStarting(ownerId, -1);
             return Promise.reject(new ProcessError('spawn_failed', `${launch.command}: ${error instanceof Error ? error.message : String(error)}`));
         }
-        const managed = { id, ownerId, agent, child, stopping: false, tooLarge: false, stderr: '', killTimer: null };
+        const managed = { id, ownerId, agent, child, rewritePageLine: launch.rewritePageLine ?? null, stopping: false, tooLarge: false, stderr: '', stderrDropping: false, killTimer: null };
         return new Promise((resolve, reject) => {
             let started = false;
             child.once('spawn', () => {
@@ -150,8 +169,19 @@ export class ProcessManager {
         });
         child.stderr?.setEncoding('utf8');
         child.stderr?.on('data', (chunk) => {
-            managed.stderr = (managed.stderr + chunk).slice(-STDERR_KEEP);
-            this.options.onStderr?.(managed.id, managed.agent, chunk);
+            let piece = chunk;
+            if (managed.stderrDropping) {
+                const space = piece.search(/\s/);
+                piece = space === -1 ? '' : piece.slice(space);
+                managed.stderrDropping = space === -1;
+            }
+            const joined = managed.stderr + piece;
+            managed.stderr = keepTail(joined, STDERR_KEEP);
+            // 截成空：结尾可能正是一个被拆开的令牌的前半截，它的后半截会在下一块开头
+            if (joined.length > 0 && managed.stderr === '')
+                managed.stderrDropping = true;
+            // 只在 --verbose 时打到 bridge 自己的终端：逐块打码，尽力而为（跨块的令牌只会出现在同账号的终端里）
+            this.options.onStderr?.(managed.id, managed.agent, redactSessionTokens(chunk));
         });
         // 'close' 在 stdio 全部关闭后触发，保证最后几行先于退出事件送出
         child.on('close', (code, signal) => {
@@ -171,7 +201,7 @@ export class ProcessManager {
                 code,
                 signal,
                 reason: managed.tooLarge ? 'output_too_large' : managed.stopping ? 'stopped' : 'exited',
-                stderrTail: managed.stderr.slice(-STDERR_REPORT),
+                stderrTail: redactSessionTokens(keepTail(managed.stderr, STDERR_REPORT)),
             });
         });
     }
@@ -185,7 +215,8 @@ export class ProcessManager {
         const managed = this.processes.get(processId);
         if (!managed || managed.ownerId !== ownerId || managed.stopping)
             return false;
-        managed.child.stdin?.write(`${line}\n`);
+        const out = managed.rewritePageLine ? managed.rewritePageLine(line) : line;
+        managed.child.stdin?.write(`${out}\n`);
         return true;
     }
     stopManaged(managed) {

package/dist/bridge/protocol.js

@@ -11,7 +11,11 @@
  *   bridge 至少同时支持前一个版本。页面必须忽略不认识的字段 / 事件，把不认识的 state 当成 unknown。
  * - bridge 不翻译 ACP：agent → 页面的 `acp` 行原样转发（不保证是 JSON）；页面 → agent 的行只做方法白名单、会话范围与无人值守模式检查（acp-guard.ts），
  *   翻译全部在页面做。
- * - 配对 = 授权该页面以用户的身份驱动本机 agent（包括让它执行命令）；页面代码与 token 的保管要按这个级别对待。
+ * - 连上本机连接 = 授权该页面以用户的身份驱动本机 agent（包括让它执行命令）。change bridge-client-only 起只有 M2 客户端主进程
+ *   替页面加了一次性票据（`BRIDGE_TICKET_HEADER`）的握手才被接受，页面不持有任何本机连接凭证；配对整体删掉（hello 的
+ *   `token` / `pairSecret`、`pair` 方法、`pairing_*` 错误码、`tooManyUnpaired`、welcome 的 `token`），类型随页面一起删了（1a 阶段 B）。
+ *   不升协议版本、也不同时支持前一版本：这是契约 9「同版本只加法」经用户拍板的例外（U5 / F6，不兼容旧版本）。
+ *   welcome 的 `paired` / `tokenRejected` 本机连接仍按旧形状发出（恒为 true / false），页面不再读。
  */
 /** 本 bridge 支持的协议版本（页面在 hello 里给出自己支持的列表，bridge 选双方共有的最大值） */
 export const BRIDGE_PROTOCOL_VERSION = 1;
@@ -19,6 +23,12 @@ export const BRIDGE_SUPPORTED_PROTOCOLS = [1];
 /** 默认端口与路径。页面必须连 127.0.0.1（不是 localhost：localhost 可能先解析到 ::1，bridge 不监听 IPv6）。 */
 export const BRIDGE_DEFAULT_PORT = 47821;
 export const BRIDGE_WS_PATH = '/bridge';
+/**
+ * M2 客户端主进程替页面加进 WebSocket 握手的一次性票据请求头（change bridge-client-only D3 / D4 起）。
+ * 票据从后台模式的 `~/.m2canvas/bridge-<port>.sock` 领（请求 `{"type":"ticket"}`）。页面代码不会、也不能设置它：
+ * 浏览器的 WebSocket API 加不了自定义请求头。客户端那边各存一份常量，由防漂移单测对照这里（mac-client 契约 11）。
+ */
+export const BRIDGE_TICKET_HEADER = 'X-M2-Bridge-Ticket';
 /** 与前端 src/lib/agent-types 的 AgentType 取值一致（是它的子集），顺序即 agents/list 的返回顺序 */
 export const BRIDGE_AGENT_IDS = ['claude', 'codex', 'cursor', 'opencode', 'qoder'];
 /**
@@ -64,7 +74,6 @@ export const BRIDGE_UNATTENDED_MODE_VALUES = {
     qoder: ['yolo'],
 };
 export const BRIDGE_METHODS = [
-    'pair',
     'agents/list',
     'agent/prepare',
     'agent/precheck',
@@ -86,5 +95,4 @@ export const BRIDGE_CLOSE_CODES = {
     badHandshake: 4400,
     timeout: 4408,
     protocolUnsupported: 4426,
-    tooManyUnpaired: 4429,
 };

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,21 @@
 /**
- * 本机 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、`process/start` 的会话令牌开关与用于比对的
+ *   userId（change acp-session-m2-token，契约 21）—— 进不了 spawn 的命令、参数、cwd、环境。会话令牌模式下 bridge 自己给进程加的 MCP 条目
+ *   （Claude 的 `_meta`、Codex 的 `CODEX_CONFIG`）在页面的行过了 acp-guard 之后才加，内容全部由 bridge 决定（session-token.ts）。
  *   方法分派在 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 +28,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 +118,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 +138,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 } : {}),
+            bridge: options.rejectedVersions ? { ...options.bridge, rejected: options.rejectedVersions() } : options.bridge,
+            // 页面侧类型在 1a 阶段 B 才删：这三个字段的形状对现有页面不变（恒为已连上）
+            paired: true,
+            tokenRejected: false,
+            cwd: options.cwd,
         });
     }
     function onFrame(conn, data, isBinary) {
@@ -200,7 +178,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 +195,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 +222,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 +249,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 +289,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 +348,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/service.js

@@ -15,6 +15,9 @@
  * 优先用最近一次预检 / 写配置时得到的名字（D19，页面先预检才会显示按钮，省掉一次重跑 —— Claude 的 `mcp list` 实测约 5 秒），没有记录时重跑；
  * 预检 / 写配置的结果按同一判据带上 `authorize` 能力，页面只在能力存在时才调用 agent/authorize。
  *
+ * 会话令牌（change acp-session-m2-token，契约 21，规则在 session-token.ts）：claude / codex 的预检结果带 `m2Session`，每次给出时现读
+ * 令牌文件、不进预检缓存；`launch` 带 `session` 时由 session-token.ts 核对文件与账号并给出这个进程要加的环境 / 行改写。
+ *
  * 预检缓存（change bridge-precheck-speedup，契约 18，规则在 precheck-cache.ts）：带连接 id 的预检是页面的 `agent/precheck`，
  * 每条连接第一次查某家可以用缓存；不带的（授权结束后的重查）一律真跑并写回。写配置、授权在**开始运行之前**作废这家的缓存 ——
  * 前置条件不满足而什么都没运行时不作废。缓存存不带能力的原始结果，给出时再按当前判据加 `authorize`。
@@ -92,11 +95,21 @@ export function createAgentService(deps) {
             return check;
         return { ...check, authorize };
     }
-    const withCapabilities = (result) => ({
-        ...result,
-        login: withCapability(result.login, result.agent, 'login'),
-        m2: withCapability(result.m2, result.agent, 'm2'),
-    });
+    /**
+     * 给出预检结果时加上能力与 `m2Session`。缓存只存原始结果；`m2Session` 每次现读令牌文件（客户端随时会换掉它，契约 21），
+     * 所以缓存命中、真跑、`precheck/updated` 推送三条路径给出的都是此刻的状态。只有 claude / codex 带。
+     */
+    const withCapabilities = (result) => {
+        const decorated = {
+            ...result,
+            login: withCapability(result.login, result.agent, 'login'),
+            m2: withCapability(result.m2, result.agent, 'm2'),
+        };
+        delete decorated.m2Session;
+        if (deps.sessionTokens && isAdapterAgent(result.agent))
+            decorated.m2Session = deps.sessionTokens.state();
+        return decorated;
+    };
     const precheckCache = new PrecheckCache({
         run: async (agent) => {
             const result = await precheckAgent(await ready(agent), precheckDeps);
@@ -174,10 +187,19 @@ export function createAgentService(deps) {
                 m2: withCapability(remember(agent, await precheckM2(detected, precheckDeps)), agent, 'm2'),
             };
         },
-        async launch(agent) {
+        async launch(agent, session) {
+            if (session && !deps.sessionTokens)
+                throw new BridgeFailure('m2_session_unavailable', 'this bridge does not support the M2 session token');
             const detected = await ready(agent);
-            if (isAdapterAgent(agent))
-                return { command: deps.nodePath, args: [deps.adapters.entryPath(agent)] };
+            if (isAdapterAgent(agent)) {
+                const spec = { command: deps.nodePath, args: [deps.adapters.entryPath(agent)] };
+                if (!session || !deps.sessionTokens)
+                    return spec;
+                const { env, rewritePageLine, expiresAt } = deps.sessionTokens.prepare(agent, session.userId);
+                return { ...spec, ...(env ? { env } : {}), ...(rewritePageLine ? { rewritePageLine } : {}), m2SessionExpiresAt: expiresAt };
+            }
+            if (session)
+                throw new BridgeFailure('m2_session_unavailable', `the M2 session token is only for Claude and Codex, not ${agent}`);
             // 已安装的原生 agent 必有 path（detectAgent 的约定），这里只为收窄类型
             if (!detected.path)
                 throw new BridgeFailure('internal', `no executable path for ${agent}`);

package/dist/bridge/session-token-io.js

@@ -0,0 +1,41 @@
+/**
+ * 会话令牌模式的本机文件读写（change acp-session-m2-token T1）：读令牌文件与 agent 配置、写 helper 脚本。
+ * 规则在 session-token.ts；这里只做文件操作，单测用临时家目录。
+ *
+ * bridge 只写 helper（`~/.m2canvas/bin/m2-mcp-session-headers`），从不写、不删令牌文件（客户端负责，design D4）。
+ * helper 先写同目录临时文件（0700）再改名，读到的总是完整的旧脚本或新脚本；内容与权限都对就不写。
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** 读文本文件；不存在、读不了、超过 `maxBytes` 都返回 null（调用方按「没有」处理，不区分原因、不打印内容） */
+export function readTextFile(path, maxBytes = 1024 * 1024) {
+    try {
+        if (statSync(path).size > maxBytes)
+            return null;
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function ensureHelperScript(path, content) {
+    try {
+        const stat = statSync(path);
+        if ((stat.mode & 0o777) === 0o700 && stat.isFile() && readFileSync(path, 'utf8') === content)
+            return;
+    }
+    catch {
+        // 不存在：照常写
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, content, { mode: 0o700 });
+        chmodSync(tmp, 0o700);
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}