@lingerai/cli 0.1.0

package/src/oauth.js

@@ -0,0 +1,280 @@
+// OAuth 授权码 + PKCE + 本机回环登录流程（M3 实装 · M4/M5 加固）。
+//
+// 整条登录链（RFC 7636 PKCE + RFC 8252 本机回环）：
+//   1. 本机起一个临时 HTTP server（端口由系统随机分配）接授权回调
+//   2. 生成 PKCE 暗号 + state 防伪标记
+//   3. 打开默认浏览器到 Linger 授权确认页（/oauth/authorize）
+//   4. 用户在浏览器点「允许」→ 平台把浏览器跳回本机临时地址、带回授权码
+//   5. 本机 server 收到授权码 → 关掉自己
+//   6. 拿授权码 + 暗号原文向平台换 token（POST /oauth/token）
+//   7. token 存到本机 ~/.linger/credentials
+//
+// 设计原则：纯函数（buildAuthorizeUrl / exchangeToken）单独可测；
+//   带副作用的部分（起 server / 开浏览器）做成可注入，便于将来端到端测试。
+
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+
+import { generateVerifier, challengeFromVerifier, generateState } from './pkce.js';
+import { saveCredentials } from './credentials.js';
+
+// M5 预注册 client_id（已在平台 oauth_clients 表预注册，无需动态注册）。
+export const POC_CLIENT_ID = 'linger-cli';
+
+// 本机回环回调路径（与平台白名单登记的 path 必须一致 · 只端口可变）。
+const CALLBACK_PATH = '/callback';
+
+/**
+ * 拼装 Linger 授权确认页地址（/oauth/authorize）。纯字符串，无副作用。
+ *
+ * @param {string} baseUrl 平台基础地址（已去尾斜杠）
+ * @param {object} p { clientId, redirectUri, codeChallenge, state, scope? }
+ * @returns {string} 完整授权页 URL
+ */
+export function buildAuthorizeUrl(baseUrl, p) {
+  const url = new URL(`${baseUrl}/oauth/authorize`);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', p.clientId);
+  url.searchParams.set('redirect_uri', p.redirectUri);
+  url.searchParams.set('code_challenge', p.codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  url.searchParams.set('state', p.state);
+  url.searchParams.set('scope', p.scope || 'platform');
+  return url.toString();
+}
+
+/**
+ * 用授权码 + PKCE 暗号原文向平台换 token（POST /oauth/token）。
+ *
+ * 按 OAuth 2.0 §4.1.3 发 application/x-www-form-urlencoded（后端真实客户端口径）。
+ *
+ * @returns {Promise<object>} 平台返回的 token 对象 { access_token, refresh_token, ... }
+ * @throws {Error} 换码失败（HTTP 非 2xx 或网络错误）
+ */
+export async function exchangeToken(baseUrl, { code, codeVerifier, redirectUri, clientId }) {
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: codeVerifier,
+  });
+
+  const resp = await fetch(`${baseUrl}/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+
+  const text = await resp.text();
+  if (!resp.ok) {
+    let msg = text;
+    try {
+      const j = JSON.parse(text);
+      msg = (j.detail && (j.detail.message || j.detail.error)) || j.message || j.error || text;
+    } catch {
+      /* 非 JSON 错误体，原样用 */
+    }
+    throw new Error(`换取登录凭证失败（${resp.status}）：${msg}`);
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * 在本机起一个临时 HTTP server 接授权回调。端口由系统随机分配（port 0）。
+ *
+ * @param {object} [opts] { host?, port? } —— 仅测试用：覆盖监听 host/端口以强制 bind 失败回归；
+ *   生产默认 127.0.0.1:0（OS 随机分配空闲端口·天然无冲突）
+ * @returns {Promise<{ port, redirectUri, waitForCode, close }>}
+ *   - port: 系统分配的随机端口
+ *   - redirectUri: http://127.0.0.1:{port}/callback（拼授权请求用）
+ *   - waitForCode(): Promise<string> —— 等浏览器回调拿到授权码（或 state/error）
+ *   - close(): 关 server
+ */
+export function startLoopbackServer({ host = '127.0.0.1', port = 0 } = {}) {
+  let resolveCode, rejectCode;
+  const codePromise = new Promise((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+
+  // 外层 startup Promise 的 reject + 启动状态标记（bind 失败投递用·见 server.on('error')）
+  let rejectStartup;
+  let started = false;
+
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, 'http://127.0.0.1');
+    if (u.pathname !== CALLBACK_PATH) {
+      res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Not Found');
+      return;
+    }
+    const code = u.searchParams.get('code');
+    const error = u.searchParams.get('error');
+    const state = u.searchParams.get('state');
+
+    // 给浏览器一个「可以关掉这个标签页了」的极简页面
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    if (error) {
+      res.end('<p>授权未完成，可以关闭此页面，回到命令行查看。</p>');
+      rejectCode(new Error(`用户未授权或授权被拒绝：${error}`));
+    } else if (code) {
+      res.end('<p>登录成功，可以关闭此页面，回到命令行。</p>');
+      resolveCode({ code, state });
+    } else {
+      res.end('<p>回调缺少授权码，可以关闭此页面。</p>');
+      rejectCode(new Error('回调地址未带授权码'));
+    }
+  });
+
+  // B 组加固（bug-m5-cli-001 修正）：bind 失败（EADDRINUSE 等）必须让
+  // `await startLoopbackServer()` 立即失败、不静默挂起。按启动阶段区分投递目标：
+  //   - 启动阶段出错（started=false）→ reject 外层 startup Promise（await 处抛错）
+  //   - 启动后运行期出错（started=true）→ reject 内层 codePromise（waitForCode 处抛错）
+  // 两路互斥，避免「reject 了 codePromise 却无人 await」导致 unhandledRejection 逃逸。
+  server.on('error', (err) => {
+    const e = new Error(
+      `本机临时服务启动失败（${err.message}）。端口可能被占用，请重试 linger auth login，`
+      + `或加 --no-wait 在能打开浏览器的机器上完成授权。`
+    );
+    if (!started && rejectStartup) {
+      rejectStartup(e);
+    } else {
+      rejectCode(e);
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    rejectStartup = reject;
+    // 监听 host:port（默认 127.0.0.1:0 系统随机分配端口·本机回环）
+    server.listen(port, host, () => {
+      started = true;
+      const port = server.address().port;
+      resolve({
+        port,
+        redirectUri: `http://127.0.0.1:${port}${CALLBACK_PATH}`,
+        waitForCode: () => codePromise,
+        close: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+/**
+ * 尽力打开系统默认浏览器到指定 URL（跨平台·零依赖）。
+ * 打不开不致命：调用方会把 URL 打印出来让用户手动复制。
+ */
+export function openBrowser(url) {
+  let cmd, args;
+  if (process.platform === 'darwin') {
+    cmd = 'open';
+    args = [url];
+  } else if (process.platform === 'win32') {
+    cmd = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    cmd = 'xdg-open';
+    args = [url];
+  }
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {}); // 命令不存在等 → 忽略（调用方已打印 URL）
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 执行 `linger auth login` 全流程。
+ *
+ * @param {object} opts
+ *   - baseUrl: 平台地址
+ *   - noWait: true → 只准备好回环 + 打印授权 URL 就返回（对齐飞书 --no-wait，给 agent 用），
+ *             不阻塞等浏览器；调用方负责后续。返回 { url, redirectUri, server, verifier, state }。
+ *   - credDir: 凭证目录覆盖（测试用）
+ *   - log: 输出函数（默认 console.log，便于测试静默）
+ *   - timeoutMs: 等浏览器回调的超时（默认 5 分钟）
+ * @returns {Promise<object>} noWait=false → 存好的 credentials；noWait=true → 上述准备态对象
+ */
+export async function runAuthLogin(opts = {}) {
+  const {
+    baseUrl,
+    noWait = false,
+    credDir,
+    log = console.log,
+    timeoutMs = 5 * 60 * 1000,
+    clientId = POC_CLIENT_ID,
+  } = opts;
+
+  const verifier = generateVerifier();
+  const challenge = challengeFromVerifier(verifier);
+  const state = generateState();
+
+  const server = await startLoopbackServer();
+  const authUrl = buildAuthorizeUrl(baseUrl, {
+    clientId,
+    redirectUri: server.redirectUri,
+    codeChallenge: challenge,
+    state,
+    scope: 'platform',
+  });
+
+  if (noWait) {
+    // --no-wait：给 agent 用 —— 不开浏览器、不阻塞，只把授权 URL 交出去。
+    // 注意：此模式下回环 server 仍在监听，调用方需自行驱动 waitForCode + 换码 + close。
+    log(authUrl);
+    return { url: authUrl, redirectUri: server.redirectUri, server, verifier, state, clientId, baseUrl };
+  }
+
+  // 交互模式：打开浏览器 + 阻塞等回调
+  log('正在打开浏览器完成 Linger 授权…');
+  log(`如果浏览器没有自动打开，请手动访问：\n${authUrl}\n`);
+  openBrowser(authUrl);
+
+  // 超时保护：用户关了浏览器没授权 → 不静默挂起。
+  // B 组加固：
+  //   1. timer.unref()：让计时器不阻止进程退出（即使 timer 未 clear，进程也能正常退）。
+  //   2. clearTimeout(timerId)：成功/失败后主动清掉计时器（双重保险）。
+  let timerId;
+  const timeout = new Promise((_, rej) => {
+    timerId = setTimeout(
+      () => rej(new Error(
+        '等待授权超时（5 分钟内未完成）。\n'
+        + '• 如果当前环境无法打开浏览器，请加 --no-wait 参数（打印授权 URL 让你在别处完成）。\n'
+        + '• 或换一台能打开浏览器的机器重试 linger auth login。'
+      )),
+      timeoutMs
+    );
+    // unref：计时器不阻止进程退出（Node 进程事件循环里不会因为这个 timer 还在跑就不退出）
+    timerId.unref();
+  });
+
+  let codeResult;
+  try {
+    codeResult = await Promise.race([server.waitForCode(), timeout]);
+  } finally {
+    // 无论成功还是失败，都清掉超时计时器（double-unref）
+    clearTimeout(timerId);
+    await server.close();
+  }
+
+  // 校验 state 一致（防回调被伪造）
+  if (codeResult.state && codeResult.state !== state) {
+    throw new Error('授权回调的防伪标记不匹配，已中止（安全保护）。');
+  }
+
+  log('授权成功，正在换取登录凭证…');
+  const tokenObj = await exchangeToken(baseUrl, {
+    code: codeResult.code,
+    codeVerifier: verifier,
+    redirectUri: server.redirectUri,
+    clientId,
+  });
+
+  const creds = { ...tokenObj, base_url: baseUrl };
+  const file = saveCredentials(creds, credDir ? { dir: credDir } : {});
+  log(`登录完成，凭证已保存到 ${file}`);
+  return creds;
+}

package/src/pkce.js

@@ -0,0 +1,47 @@
+// PKCE（RFC 7636）+ state 生成。纯算法、无网络、无副作用。
+//
+// 命令行登录用「授权码 + PKCE」流程：
+//   1. 本地随机生成一段 verifier（暗号原文）
+//   2. 算出它的 S256 摘要 challenge（暗号摘要），随授权请求发给平台
+//   3. 换码时把 verifier 原文发回平台，平台重算摘要核对 → 防授权码被中途截走盗用
+//
+// ⚠ challenge 算法必须与 Linger 后端口径分毫不差：
+//   后端（a2a-backend/app/routes/oauth.py _handle_authorization_code）：
+//     base64url( sha256(verifier) ) 去掉结尾 '=' 补位。
+
+import crypto from 'node:crypto';
+
+/** base64url 编码（无 padding）：把 + / 换成 - _，去掉结尾的 =。 */
+function base64url(buf) {
+  return buf
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * 生成 PKCE code_verifier（暗号原文）。
+ * RFC 7636 §4.1：43~128 个 unreserved 字符。
+ * 32 字节随机 → base64url 后约 43 字符，落在合规区间。
+ */
+export function generateVerifier() {
+  return base64url(crypto.randomBytes(32));
+}
+
+/**
+ * 由 verifier 算出 S256 code_challenge（暗号摘要）。
+ * 必须与后端口径一致：base64url(sha256(verifier))，无 padding。
+ */
+export function challengeFromVerifier(verifier) {
+  const digest = crypto.createHash('sha256').update(verifier).digest();
+  return base64url(digest);
+}
+
+/**
+ * 生成 OAuth state（防伪标记 · 防登录回调被人伪造/CSRF）。
+ * 16 字节随机 → base64url。
+ */
+export function generateState() {
+  return base64url(crypto.randomBytes(16));
+}