@m2canvas/connect 0.4.0 → 0.5.0

package/README.md

@@ -32,11 +32,11 @@ After setup, restart each client so it loads the new server.
 npx -y @m2canvas/connect@latest bridge
 ```
 
-Lets M2 (in Chrome or another Chromium browser) start and talk to the agents on this machine over [ACP](https://agentclientprotocol.com): Claude Code, Codex, Cursor CLI, OpenCode and Qoder. Run it in the project directory you want the agents to work in, and keep the window open.
+Lets M2 (in Chrome or another Chromium browser) start and talk to the agents on this machine over [ACP](https://agentclientprotocol.com): Claude Code, Codex, Cursor CLI, OpenCode and Qoder. Run it in the project directory you want the agents to work in, and keep the window open. Copy the command from M2's Local Agent tab: it adds `--pair <value>` so that page pairs by itself.
 
 - **Local only.** It listens on `127.0.0.1:47821` and only accepts pages from `https://m2ui.ai`. Other sites, other machines and other hosts are refused before a connection is made. (`--dev` also accepts a local M2 dev server on port 5173; any app you serve on that port could then ask to pair, so only use it while developing M2.)
-- **Pairing gives the page your agents.** A paired page can make these agents read and change files and run commands as you, the same as typing into them yourself. Only enter the code into M2.
-- **Pairing.** The first time, M2 asks for the pairing code printed in this window; the window also shows which site is asking. After that the page remembers the pairing for 30 days of inactivity. After too many wrong codes, new pages can't pair until you restart the bridge (pages already paired keep working); close the page the window names first. `bridge --unpair` forgets all paired pages.
+- **Pairing gives the page your agents.** A paired page can make these agents read and change files and run commands as you, the same as typing into them yourself. Only run commands you copied from M2, and only enter the code into M2.
+- **Pairing.** When you start the bridge with the command M2 gives you, the page that gave it pairs automatically within 10 minutes. The command only carries a hash (`--pair`); the secret it matches stays in that browser tab, so the command is safe to appear in your shell history, and it works once. Any other page asks for the pairing code printed in this window; the window also shows which site is asking. After that the page remembers the pairing for 30 days of inactivity. After too many wrong codes, new pages can't pair until you restart the bridge (pages already paired keep working); close the page the window names first. `bridge --unpair` forgets all paired pages.
 - **Your own logins.** Agents use their own sign-in and their own M2 MCP setup; the bridge never signs in for you. It starts agents with a minimal environment, so variables set by a host app (for example `ANTHROPIC_BASE_URL` inside Claude Code) don't leak into them.
 - **Claude and Codex** run through pinned versions of the official adapters (`@agentclientprotocol/claude-agent-acp@0.84.0`, `@agentclientprotocol/codex-acp@2.1.0`). They are installed on first use into `~/.m2canvas/acp-adapters/` from the lockfiles in this package (a few hundred MB each, because they bundle the agent). Codex then needs its own M2 sign-in once, with the bundled `codex`; M2 shows the exact command.
 - Cursor runs as `agent acp`, OpenCode as `opencode acp`, Qoder as `qodercli --acp`.

package/dist/bridge/main.js

@@ -15,7 +15,7 @@ import { detectAgent } from './agents.js';
 import { buildAgentEnv, buildNpmEnv, buildProbeEnv } from './env.js';
 import { execCommand, killActiveExecs } from './exec.js';
 import { installShutdownSignals } from './lifecycle.js';
-import { PairingManager, createFilePairingStore } from './pairing.js';
+import { PairingManager, createFilePairingStore, isPairCommitment } from './pairing.js';
 import { BRIDGE_AGENT_IDS, BRIDGE_DEFAULT_PORT, BRIDGE_WS_PATH } from './protocol.js';
 import { DEV_ORIGINS, PROD_ORIGINS, allowedOrigins } from './security.js';
 import { startBridgeServer } from './server.js';
@@ -29,26 +29,30 @@ const LABELS = {
     opencode: 'OpenCode',
     qoder: 'Qoder',
 };
-const HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev]
+export const BRIDGE_HELP = `Usage: npx @m2canvas/connect bridge [--port <n>] [--cwd <dir>] [--verbose] [--dev] [--pair <value>]
        npx @m2canvas/connect bridge --unpair
 
 Runs the local agent bridge so M2 (in Chrome) can start and talk to the agents
 installed on this machine: Claude Code, Codex, Cursor CLI, OpenCode and Qoder.
 
 It only listens on 127.0.0.1 and only accepts the M2 web app (${PROD_ORIGINS.join(', ')}).
-The first time, M2 asks for the pairing code shown here. A paired page can make
-these agents read and change files and run commands as you, so only pair M2.
+The command M2 gives you pairs that page automatically; other pages ask for the
+pairing code shown here. A paired page can make these agents read and change
+files and run commands as you, so only run commands you copied from M2.
 Agents run in the directory you start the bridge from (or --cwd), with your own logins.
 
-  --port <n>   port to listen on (default ${BRIDGE_DEFAULT_PORT})
-  --cwd <dir>  working directory for agent sessions (default: current directory)
-  --verbose    also print agent stderr and connection details
-  --dev        also accept a local M2 dev server (${DEV_ORIGINS.join(', ')});
-               any app served on that port could then ask to pair
-  --unpair     forget all paired pages and exit
-  -h, --help   show this help`;
-function parseArgs(argv) {
-    const args = { port: BRIDGE_DEFAULT_PORT, cwd: process.cwd(), verbose: false, unpair: false, help: false, dev: false };
+  --port <n>      port to listen on (default ${BRIDGE_DEFAULT_PORT})
+  --cwd <dir>     working directory for agent sessions (default: current directory)
+  --verbose       also print agent stderr and connection details
+  --dev           also accept a local M2 dev server (${DEV_ORIGINS.join(', ')});
+                  any app served on that port could then ask to pair
+  --pair <value>  pair the M2 page that gave you this command (M2 adds it for you;
+                  valid for 10 minutes, once)
+  --unpair        forget all paired pages and exit
+  -h, --help      show this help`;
+/** 解析 `bridge` 之后的参数；返回字符串表示参数错误（调用方连同帮助打印、退出码 2）。 */
+export function parseBridgeArgs(argv) {
+    const args = { port: BRIDGE_DEFAULT_PORT, cwd: process.cwd(), verbose: false, unpair: false, help: false, dev: false, pair: null };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '-h' || arg === '--help')
@@ -59,6 +63,14 @@ function parseArgs(argv) {
             args.unpair = true;
         else if (arg === '--dev')
             args.dev = true;
+        else if (arg === '--pair') {
+            const value = argv[++i];
+            if (value === undefined)
+                return '--pair needs a value';
+            if (!isPairCommitment(value))
+                return `invalid --pair value ${value}; copy the start command from M2 again`;
+            args.pair = value;
+        }
         else if (arg === '--port' || arg === '--cwd') {
             const value = argv[++i];
             if (value === undefined)
@@ -96,6 +108,15 @@ function printCode(info) {
     else
         console.log(`\n→ Too many wrong pairing codes${info.origin ? ` from ${info.origin}` : ''}. New ${code}\n`);
 }
+function clock(at) {
+    return new Date(at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+}
+/** 启动命令里的配对已被用掉，同一个密钥又出现：同一个 M2 标签页被复制 / 连接途中刷新，或者别的程序抢先配对了（review r1 S2） */
+function printReused(info) {
+    console.log(`\n→ Warning: the pairing in your start command was already used (by ${info.firstOrigin} at ${clock(info.usedAt)}), ` +
+        `and ${info.origin} just presented it again. If you didn't duplicate or reload that M2 tab while it was connecting, another program on this machine ` +
+        `may have paired with this bridge: press Ctrl+C, run "npx @m2canvas/connect bridge --unpair", then start the bridge again.\n`);
+}
 function printLocked(origin) {
     const from = origin ? ` (the last ones came from ${origin})` : '';
     console.log(`\n→ Too many wrong pairing codes${from}. New pages can't pair until you restart the bridge (Ctrl+C, then run it again); ` +
@@ -112,13 +133,13 @@ function describeAdapter(agent, info) {
     return null;
 }
 export async function runBridge(argv) {
-    const parsed = parseArgs(argv);
+    const parsed = parseBridgeArgs(argv);
     if (typeof parsed === 'string') {
-        console.error(`${parsed}\n\n${HELP}`);
+        console.error(`${parsed}\n\n${BRIDGE_HELP}`);
         return 2;
     }
     if (parsed.help) {
-        console.log(HELP);
+        console.log(BRIDGE_HELP);
         return 0;
     }
     const m2Dir = join(home, '.m2canvas');
@@ -142,7 +163,10 @@ export async function runBridge(argv) {
         onCodeIssued: printCode,
         onLocked: printLocked,
         onProblem: (message) => console.warn(message),
+        onCommitmentReused: printReused,
     });
+    // 承诺必须在开始监听之前挂上：等待中的页面每 2 秒探测一次，监听一开始就可能连上；晚挂一步它就撞上 no_commitment、落到输码
+    const pairUntil = parsed.pair ? pairing.armCommitment(parsed.pair) : null;
     const adapters = new AdapterManager({
         sourceRoot: join(PACKAGE_ROOT, 'adapters'),
         installRoot: join(m2Dir, 'acp-adapters'),
@@ -237,7 +261,12 @@ export async function runBridge(argv) {
     console.log(`  Accepts pages from: ${origins.join(', ')}`);
     if (parsed.dev)
         console.log('  --dev: any app on the dev port can ask to pair. Only enter the code into your own M2 dev server.');
-    pairing.issueCode('startup');
+    // 带 --pair（命令是从 M2 页面复制的）：主路径上用户不需要启动码，打印出来反而让人以为要去输码；
+    // 页面对不上承诺时会以未配对状态连上，那时照常出码并带上发起方 Origin
+    if (pairUntil !== null)
+        console.log(`  Waiting for the M2 page that gave you this command (until ${clock(pairUntil)})…`);
+    else
+        pairing.issueCode('startup');
     const found = await Promise.all(BRIDGE_AGENT_IDS.map(detect));
     console.log(`  Agents: ${found.map((agent) => `${LABELS[agent.id]} ${agent.installed ? '✓' : '–'}`).join('   ')}`);
     console.log('  Keep this window open while you use local agents in M2. Press Ctrl+C to stop.\n');

package/dist/bridge/pairing.js

@@ -3,7 +3,11 @@
  * 和本机其他进程（可以伪造 Origin）。它们都拿不到只出现在终端里的配对码。
  * 配对 = 授权该页面以用户的身份驱动本机 agent（包括执行命令），所以码和 token 都按这个级别保管。
  *
- * 流程：终端打印一次性配对码 → 用户在页面输入 → 换取长期 token（页面存 localStorage）→ 之后每次 hello 带上。
+ * 两条途径，都要证明「终端用户同意了这个页面」（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。
@@ -33,6 +37,18 @@ 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
@@ -57,6 +73,10 @@ function errorText(error) {
 }
 export class PairingManager {
     active = null;
+    /** `--pair` 挂上的承诺（只在内存里：bridge 重启即失效，重新运行同一条命令会重新挂上） */
+    commitment = null;
+    /** 已用掉的承诺：同一个密钥再出现时告警（只在内存里，只记最近一个） */
+    consumed = null;
     /** 自上次成功配对以来累计的错码次数（跨码、跨过期）；配对成功时清零 */
     failuresSinceSuccess = 0;
     locked = false;
@@ -67,12 +87,14 @@ export class PairingManager {
     onCodeIssued;
     onLocked;
     onProblem;
+    onCommitmentReused;
     constructor(options) {
         this.store = options.store;
         this.now = options.now ?? Date.now;
         this.onCodeIssued = options.onCodeIssued;
         this.onLocked = options.onLocked ?? (() => undefined);
         this.onProblem = options.onProblem ?? (() => undefined);
+        this.onCommitmentReused = options.onCommitmentReused ?? (() => undefined);
     }
     /** 生成新码（旧码立即失效）并通知调用方打印，返回显示形式 */
     issueCode(reason, origin = null) {
@@ -152,6 +174,59 @@ export class PairingManager {
         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;
+    }
+    /**
+     * 页面在 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();

package/dist/bridge/server.js

@@ -7,6 +7,7 @@
  * 都由页面发出）。所以安全的重心在「谁能配对」，配对之后能做的事只做纵深防御：
  * - 只监听 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、环境。
  * - 页面发给 agent 的 ACP 行禁止含换行，并经 acp-guard.ts 检查：只能用白名单里的方法、会话目录固定为 bridge 的 cwd、不能让 agent 额外拉起 MCP 服务器。
  *
@@ -159,7 +160,19 @@ export function startBridgeServer(options) {
             clearTimeout(conn.timer);
         conn.timer = null;
         const token = typeof frame.token === 'string' ? frame.token : undefined;
-        const paired = options.pairing.verifyToken(token, conn.origin);
+        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);
         }
@@ -182,6 +195,7 @@ export function startBridgeServer(options) {
             paired,
             tokenRejected: token !== undefined && !paired,
             cwd: paired ? options.cwd : null,
+            ...(issuedToken ? { token: issuedToken } : {}),
         });
     }
     function onFrame(conn, data, isBinary) {

package/package.json

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