@m2canvas/connect 0.5.0 → 0.6.0

package/dist/bridge/server.js

@@ -8,17 +8,22 @@
  * - 只监听 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、环境。
+ * - bridge 自己的方法里，页面可控的参数只有 agent id（枚举校验）、授权动作（枚举校验）、配对码、processId —— 进不了 spawn 的命令、参数、cwd、环境。
+ *   agent/authorize 与 agent/authorize-cancel 的 params 只能有规定的键，多一个就 bad_message（分派在 auth-call.ts，命令清单写死在 authorize.ts）。
  * - 页面发给 agent 的 ACP 行禁止含换行，并经 acp-guard.ts 检查：只能用白名单里的方法、会话目录固定为 bridge 的 cwd、不能让 agent 额外拉起 MCP 服务器。
  *
- * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责），不替用户登录。
+ * 边界：bridge 不解析 agent 发来的 ACP，不判断用户是否开通了本地 Agent（change 4 / 3 负责）。
+ * 登录 / m2 授权只代跑写死清单里的命令，授权页由用户在浏览器里亲自完成（authorize.ts）；授权链接只发给发起的连接，不进终端日志。
  */
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
 import { WebSocketServer } from 'ws';
 import { TOKEN_IDLE_DAYS } from './pairing.js';
 import { ProcessError, ProcessManager } from './processes.js';
-import { BRIDGE_AGENT_IDS, BRIDGE_CLOSE_CODES, BRIDGE_METHODS, BRIDGE_SUPPORTED_PROTOCOLS, } from './protocol.js';
+import { isBridgeAgentId } from './agents.js';
+import { handleAuthCall } from './auth-call.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 { BridgeFailure } from './service.js';
@@ -32,9 +37,6 @@ const MAX_CALL_ID = 64;
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function isAgentId(value) {
-    return typeof value === 'string' && BRIDGE_AGENT_IDS.includes(value);
-}
 function isMethod(value) {
     return typeof value === 'string' && BRIDGE_METHODS.includes(value);
 }
@@ -77,6 +79,23 @@ export function startBridgeServer(options) {
         },
         onStderr: options.verbose ? (_id, agent, text) => process.stderr.write(`[${agent}] ${text}`) : undefined,
     });
+    const authorizations = new AuthorizationManager({
+        timeoutMs: options.timing?.authTimeoutMs,
+        graceMs: options.timing?.authGraceMs,
+        pollMs: options.timing?.authPollMs,
+    });
+    const authContext = {
+        authorizations,
+        service: options.service,
+        log,
+        isConnected: (ownerId) => connections.has(ownerId),
+        // 授权链接只发给发起的连接（D4）
+        sendLink: (ownerId, data) => {
+            const owner = connections.get(ownerId);
+            if (owner)
+                send(owner, { type: 'event', event: 'auth/link', data });
+        },
+    };
     const unpairedCount = () => [...connections.values()].filter((conn) => !conn.paired).length;
     const markPaired = (conn) => {
         conn.paired = true;
@@ -111,8 +130,10 @@ export function startBridgeServer(options) {
         }
         if (method === 'agents/list')
             return { agents: await options.service.list() };
+        if (method === 'agent/authorize' || method === 'agent/authorize-cancel')
+            return handleAuthCall(authContext, conn.id, method, params);
         const agent = params.agent;
-        if (!isAgentId(agent))
+        if (!isBridgeAgentId(agent))
             throw new BridgeFailure('unknown_agent', `unknown agent ${String(agent)}`);
         switch (method) {
             case 'agent/prepare':
@@ -296,12 +317,12 @@ export function startBridgeServer(options) {
                     clearTimeout(conn.timer);
                 connections.delete(conn.id);
                 processes.stopOwner(conn.id);
+                authorizations.cancelOwner(conn.id);
             });
             // ws 的错误（非法帧、超过 maxPayload 等）之后必然紧跟 'close'，清理在 close 里做；这里只防止未处理的 error 事件让进程崩溃
             ws.on('error', () => undefined);
         });
     });
-    // 心跳：浏览器自动回 pong；连续一个周期没回（休眠、崩溃、断网）就断开并清理它的进程
     // 被拒连接的终端日志限频：任何网站都能反复连 127.0.0.1，逐条打印会把配对码和「X wants to pair」顶出视野（review r3 S5）。
     // 同一原因在一个窗口内只打第一条，窗口结束时汇总被合并的次数。
     const rejectWindowMs = options.timing?.rejectLogWindowMs ?? REJECT_LOG_WINDOW_MS;
@@ -332,25 +353,33 @@ export function startBridgeServer(options) {
             },
         };
     })();
-    const heartbeat = setInterval(() => {
-        for (const conn of connections.values()) {
-            if (!conn.alive) {
-                conn.ws.terminate();
-                continue;
-            }
-            conn.alive = false;
-            conn.ws.ping();
-        }
-    }, timing.pingIntervalMs);
     return new Promise((resolve, reject) => {
-        http.once('error', reject);
+        // 监听失败（端口被占）时停掉已经开始的计时器：--replace 会在同一进程里再监听一次（review r4 N4）。心跳在监听成功后才开始
+        const fail = (error) => {
+            rejectLog.stop();
+            wss.close();
+            reject(error);
+        };
+        http.once('error', fail);
         http.listen(options.port, '127.0.0.1', () => {
-            http.off('error', reject);
+            http.off('error', fail);
+            // 心跳：浏览器自动回 pong；连续一个周期没回（休眠、崩溃、断网）就断开并清理它的进程
+            const heartbeat = setInterval(() => {
+                for (const conn of connections.values()) {
+                    if (!conn.alive) {
+                        conn.ws.terminate();
+                        continue;
+                    }
+                    conn.alive = false;
+                    conn.ws.ping();
+                }
+            }, timing.pingIntervalMs);
             const address = http.address();
             resolve({
                 port: address.port,
                 address: address.address,
                 processes,
+                authorizations,
                 broadcast(event, data) {
                     for (const conn of connections.values())
                         if (conn.paired)
@@ -359,6 +388,8 @@ export function startBridgeServer(options) {
                 close() {
                     clearInterval(heartbeat);
                     rejectLog.stop();
+                    // 先于关闭连接：标记取消，被杀掉的授权命令不会被当成「失败」再去重跑预检
+                    authorizations.killAllNow();
                     for (const conn of connections.values())
                         conn.ws.close(BRIDGE_CLOSE_CODES.goingAway, 'bridge is shutting down');
                     processes.stopAll();

package/dist/bridge/service.js

@@ -1,19 +1,29 @@
 /**
- * 页面方法背后的 agent 操作：列表、准备适配器、预检、写 m2 配置、生成启动规格。server.ts 只做协议，这里只做业务。
+ * 页面方法背后的 agent 操作：列表、准备适配器、预检、写 m2 配置、生成启动规格与授权命令计划。server.ts 只做协议，这里只做业务。
  *
  * 前置条件统一在这里检查，错误以 BridgeFailure（带协议错误码）抛出：
- * - 未安装 → agent_not_installed（安装命令与文档链接由前端提供，bridge 不代装）；
+ * - 拉不起来 → agent_not_installed（安装命令与文档链接由前端提供，bridge 不代装）。claude / codex 用适配器自带的程序，
+ *   本机没装命令行也能拉起（D11：`available` 恒为 true；`installed` 仍只表示本机检测到了命令行）；
  * - 适配器类 agent 未就绪 → adapter_not_ready（页面要先调 agent/prepare）。
  *
  * m2/configure 以子进程运行本包自己的 cli.js `--client <id> --yes`：stdin 不是 TTY，cli.js 走现有的非交互分支
  * （只写配置、不跑登录、退出码 0 = 全部写入或已存在）。这样一字不改 clients.ts，也不让它的 spawnSync 卡住转发。
- * 改 cli.js 非交互分支的行为时要同步检查这里。
+ * 改 cli.js 非交互分支的行为时要同步检查这里。clients.ts 只认 PATH 上跑得起来的 claude / codex，所以对这两家把自带程序所在目录
+ * 和 bridge 自己的 node 排到 PATH 最前（D10），本机没装命令行也能写配置。
+ *
+ * 授权（change acp-terminal-free-auth）：authorizePlan 按写死清单生成命令（authorize.ts），m2 的配置项名只取 bridge 自己的 m2 预检：
+ * 优先用最近一次预检 / 写配置时得到的名字（D19，页面先预检才会显示按钮，省掉一次重跑 —— Claude 的 `mcp list` 实测约 5 秒），没有记录时重跑；
+ * 预检 / 写配置的结果按同一判据带上 `authorize` 能力，页面只在能力存在时才调用 agent/authorize。
  */
+import { dirname, join } from 'node:path';
 import { ADAPTERS, isAdapterAgent } from './adapters.js';
+import { BridgeFailure } from './errors.js';
 import { LAUNCH_KIND, NATIVE_ACP_ARGS } from './agents.js';
+import { authCapability, buildAuthPlan, isSafeAuthEntry } from './authorize.js';
+import { prependPath } from './env.js';
 import { combinedOutput } from './exec.js';
 import { precheckAgent, precheckM2 } from './precheck.js';
-import { BRIDGE_AGENT_IDS } from './protocol.js';
+import { BRIDGE_AGENT_IDS, } from './protocol.js';
 export const CONFIGURE_TIMEOUT_MS = 120_000;
 /**
  * Claude 适配器（claude-agent-acp@0.84.0）声明 `node >=22`，实测在 Node 20 上可用（ACP PoC 与本 change 的端到端都是 Node 20）；
@@ -21,15 +31,7 @@ export const CONFIGURE_TIMEOUT_MS = 120_000;
  */
 export const MIN_NODE_MAJOR_FOR_CLAUDE = 20;
 const CONFIGURE_OUTPUT_LIMIT = 4096;
-export class BridgeFailure extends Error {
-    code;
-    data;
-    constructor(code, message, data) {
-        super(message);
-        this.code = code;
-        this.data = data;
-    }
-}
+export { BridgeFailure };
 /** bridge 的 agent id → connect `--client` 的取值 */
 const CLIENT_ID = {
     claude: 'claude-code',
@@ -40,25 +42,74 @@ const CLIENT_ID = {
 };
 export function createAgentService(deps) {
     const precheckDeps = { ...deps, env: deps.probeEnv };
-    async function installed(agent) {
+    /**
+     * 最近一次 m2 预检得到的配置项名（D19）。只由 bridge 自己的预检写入，页面仍不能指定（契约 3）；
+     * 最近一次没有名字（未配置、读不出）就清掉，授权时重跑。名字过期（预检到点击之间用户改了配置）时，授权命令失败并带输出（再点一次即可：命令结束后的预检已经刷新了记录），
+     * 或者针对同名的新配置项（用户在授权页上看得到授权对象）。Claude / Codex / Cursor 实测名字不存在时退出码 1；OpenCode 不是，所以它不用记录（见下）。
+     */
+    const m2Entries = new Map();
+    /**
+     * 授权前总是重新检查、不用记录的 agent（D21）。OpenCode 的 m2 授权先 `mcp logout <entry>`：名字过期时可能删掉同名的别的服务器的凭证；
+     * 而且名字不存在时 `mcp logout` / `mcp auth` 都以退出码 0 结束（实测 1.18.5），bridge 会判成成功。多 2–4 秒，换来名字一定是当下的。
+     */
+    const alwaysRecheck = new Set(['opencode']);
+    function remember(agent, m2) {
+        if (m2.state !== 'not_configured' && m2.entry)
+            m2Entries.set(agent, m2.entry);
+        else
+            m2Entries.delete(agent);
+        return m2;
+    }
+    /** 能拉起（D11）：claude / codex 用适配器自带的程序，不要求本机命令行；其余三家要本机装了 */
+    async function available(agent) {
         const detected = await deps.detect(agent);
-        if (!detected.installed)
+        if (!isAdapterAgent(agent) && !detected.installed)
             throw new BridgeFailure('agent_not_installed', `${agent} is not installed on this machine`);
         return detected;
     }
     async function ready(agent) {
-        const detected = await installed(agent);
+        const detected = await available(agent);
         if (isAdapterAgent(agent) && !deps.adapters.isReady(agent)) {
             throw new BridgeFailure('adapter_not_ready', `call agent/prepare for ${agent} first`, { adapter: deps.adapters.info(agent) });
         }
         return detected;
     }
+    const capability = (agent, action) => authCapability(agent, action, {
+        platform: deps.platform,
+        expectAvailable: deps.expectAvailable(),
+        claudeBinary: agent === 'claude' ? deps.adapters.claudeBinary() : null,
+    });
+    /** 预检 / 写配置结果带上「能不能代跑」：与 authorizePlan 用同一判据（含 m2 配置项名的校验），页面看到按钮就一定能调用 */
+    function withCapability(check, agent, action) {
+        const authorize = capability(agent, action);
+        const entry = 'entry' in check ? check.entry : null;
+        if (!authorize || (entry !== null && !isSafeAuthEntry(entry)))
+            return check;
+        return { ...check, authorize };
+    }
+    const withCapabilities = (result) => ({
+        ...result,
+        login: withCapability(result.login, result.agent, 'login'),
+        m2: withCapability(result.m2, result.agent, 'm2'),
+    });
+    /** D10：clients.ts 只认 PATH 上能跑起来的 claude / codex */
+    function configureEnv(agent) {
+        const node = dirname(deps.nodePath);
+        if (agent === 'claude') {
+            const claude = deps.adapters.claudeBinary();
+            return prependPath(deps.probeEnv, claude ? [dirname(claude), node] : [node], deps.platform);
+        }
+        if (agent === 'codex')
+            return prependPath(deps.probeEnv, [join(deps.adapters.installDir('codex'), 'node_modules', '.bin'), node], deps.platform);
+        return deps.probeEnv;
+    }
     return {
         async list() {
             const detected = await Promise.all(BRIDGE_AGENT_IDS.map((id) => deps.detect(id)));
             return detected.map((agent) => ({
                 id: agent.id,
                 installed: agent.installed,
+                available: isAdapterAgent(agent.id) || agent.installed,
                 path: agent.path,
                 version: agent.version,
                 launch: LAUNCH_KIND[agent.id],
@@ -66,7 +117,7 @@ export function createAgentService(deps) {
             }));
         },
         async prepare(agent) {
-            await installed(agent);
+            await available(agent);
             if (!isAdapterAgent(agent))
                 return null;
             const major = Number(deps.nodeVersion.split('.')[0]);
@@ -80,12 +131,14 @@ export function createAgentService(deps) {
             return info;
         },
         async precheck(agent) {
-            return precheckAgent(await ready(agent), precheckDeps);
+            const result = await precheckAgent(await ready(agent), precheckDeps);
+            remember(agent, result.m2);
+            return withCapabilities(result);
         },
         async configure(agent) {
             const detected = await ready(agent);
             const result = await deps.exec(deps.nodePath, [deps.cliPath, '--client', CLIENT_ID[agent], '--yes'], {
-                env: deps.probeEnv,
+                env: configureEnv(agent),
                 cwd: deps.cwd,
                 timeoutMs: CONFIGURE_TIMEOUT_MS,
             });
@@ -93,7 +146,7 @@ export function createAgentService(deps) {
             return {
                 ok: result.code === 0,
                 output: output.length > CONFIGURE_OUTPUT_LIMIT ? output.slice(-CONFIGURE_OUTPUT_LIMIT) : output,
-                m2: await precheckM2(detected, precheckDeps),
+                m2: withCapability(remember(agent, await precheckM2(detected, precheckDeps)), agent, 'm2'),
             };
         },
         async launch(agent) {
@@ -105,5 +158,35 @@ export function createAgentService(deps) {
                 throw new BridgeFailure('internal', `no executable path for ${agent}`);
             return { command: detected.path, args: NATIVE_ACP_ARGS[agent] };
         },
+        async authorizePlan(agent, action) {
+            const verb = action === 'login' ? 'sign-in' : 'M2 authorization';
+            if (deps.platform !== 'darwin')
+                throw new BridgeFailure('auth_unavailable', `the bridge only runs ${verb} on macOS; use the terminal command instead`);
+            const detected = await ready(agent);
+            if (!capability(agent, action))
+                throw new BridgeFailure('auth_unavailable', `the bridge cannot run ${verb} for ${agent}; use the terminal command instead`);
+            let entry = null;
+            if (action === 'm2') {
+                // 配置项名不一定叫 m2，也不能由页面指定：用 bridge 最近一次预检的结果，没有就重跑（D19）；OpenCode 总是重跑（D21）
+                const rechecked = alwaysRecheck.has(agent) || !m2Entries.has(agent) ? remember(agent, await precheckM2(detected, precheckDeps)) : null;
+                entry = m2Entries.get(agent) ?? null;
+                if (!entry) {
+                    // 读不出（unknown）不等于没配置：不能叫已经配置了 M2 的用户「先添加」（review r5 R5-N5）
+                    const why = rechecked?.state === 'unknown' ? `couldn't read ${agent}'s MCP config; check again, or use the terminal command` : `add M2 to ${agent}'s MCP config first (m2/configure)`;
+                    throw new BridgeFailure('auth_unavailable', why);
+                }
+            }
+            return buildAuthPlan({
+                agent,
+                action,
+                detected,
+                entry,
+                cwd: deps.cwd,
+                env: deps.probeEnv,
+                nodePath: deps.nodePath,
+                claudeBinary: agent === 'claude' ? deps.adapters.claudeBinary() : null,
+                codexDir: deps.adapters.installDir('codex'),
+            });
+        },
     };
 }

package/package.json

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