wkgeo-cli 0.2.0

package/lib/device.mjs

@@ -0,0 +1,427 @@
+/**
+ * 设备码授权（RFC 8628）—— CLI 侧的完整实现
+ * ===========================================================================
+ *   wkgeo login --device              申请短码 → 打印 → 轮询 → 写凭据
+ *   wkgeo login --device --no-wait    只申请 + 打印就退出（给 AI 端用，见下）
+ *   wkgeo login --device-continue     续跑上一次没等完的设备码
+ *
+ * ## 为什么要有这条路（老板决定 AB 都做）
+ *   本地回调模式要求"CLI 所在机器能起一个回环监听端口，并且**浏览器能把 code 送回
+ *   127.0.0.1**"。这在下面这些场景里做不到：
+ *     * CLI 跑在远程服务器 / 容器里，用户在另一台机器上点浏览器；
+ *     * 用户环境有防火墙/安全软件拦本地监听；
+ *     * ★ **用户开着系统/全局代理，且代理没绕过 127.0.0.1** —— 回环请求被代理接管，
+ *       CLI 的本地服务永远收不到 code（2026-10-02 老板报的就是这个）。
+ *   设备码模式**只需要一次出网请求 + 轮询**，不需要任何回调地址，因此对代理天然免疫。
+ *
+ * ## 流程（严格按 RFC 8628）
+ *   1. `POST {device_authorization_endpoint}`（表单：`client_id`、`scope`）
+ *      → `{device_code, user_code, verification_uri, verification_uri_complete?,
+ *          expires_in, interval}`
+ *   2. CLI 打印「请打开 <网址> 并确认授权；短码：XXXX-XXXX」，必要时自动打开浏览器
+ *   3. CLI 以 `interval` 秒为间隔轮询 `POST /api/oauth/token`：
+ *        `grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=…&client_id=…`
+ *      中间态（**不是错误**，要继续轮询）：
+ *        * `authorization_pending` —— 用户还没确认
+ *        * `slow_down`             —— 轮询太快，`interval += 5`
+ *        * `expired_token`         —— 设备码过期（终止）
+ *        * `access_denied`         —— 用户拒绝（终止）
+ *   4. 成功 → 拿 `access_token` → 写本地凭据（0600，与回调模式完全同一份文件/格式）
+ *
+ * ## ⚠️ 安全边界（写进 README/SKILL，别让 AI 端误解自己的权限）
+ *   "用户确认"这一步（`POST /api/oauth/device_confirm`）**必须由用户自己的浏览器会话完成**
+ *   （它要求平台登录态；AI 端/CLI 都没有、也不该有用户的网页会话 Cookie）。
+ *   所以"用户把短码发到 AI 对话框"之后，AI 端能做的是**把网址 + 短码清楚地转达给用户、
+ *   引导他点确认**，**不能**替用户点同意。CLI 在这里只负责"申请码 + 等结果"。
+ *
+ * ## 实现结构（三个步骤拆开，是为了 `--no-wait` / `--device-continue`）
+ *   requestDeviceCode()  —— 只管申请（失败就按失败报，绝不假装成功）
+ *   announceDeviceCode() —— 只管把网址/短码交给用户（人读 + 机读 + 开浏览器）
+ *   pollDeviceToken()    —— 只管轮询 + 写凭据
+ *   runDeviceLogin()     —— 上面三步串起来（原有的一口气跑完的入口，测试与兼容用）
+ *
+ * ## 服务端现状（2026-10-02 线上实测）
+ *   `POST /api/oauth/device_authorization` **已实现**，metadata 里也声明了
+ *   `device_authorization_endpoint` 与 `grant_types_supported` 含 device_code。
+ *   但"端点不存在"这条分支**必须保留**（历史版本 / 别的环境可能还没有），
+ *   命中时给"服务端缺口 + 改用回调模式"的明确错误，而不是含糊失败。
+ */
+
+import { createApi } from './api.mjs';
+import { writeCredentials, credentialsFromToken } from './credentials.mjs';
+import { withTrailingSlash } from './config.mjs';
+import { CliError, EXIT, loginHint } from './errors.mjs';
+import { defaultOpenBrowser, resolveBrowserIntent, browserOpenedText, browserFailedHintLines } from './login.mjs';
+
+/** RFC 8628 规定的 urn */
+export const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+export const DEFAULT_DEVICE_PATH = '/api/oauth/device_authorization';
+export const DEFAULT_DEVICE_INTERVAL_SEC = 5;
+export const DEFAULT_DEVICE_EXPIRES_SEC = 600;
+
+const sleepDefault = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** 端点不存在 / 未实现 的判定（404、或统一信封里的"未知操作"、或 HTML 404 页） */
+function looksNotImplemented(res) {
+  if (!res) return false;
+  if (res.status === 404 || res.status === 405 || res.status === 501) return true;
+  const body = res.body;
+  if (body && typeof body === 'object') {
+    const msg = String(body.message || body.error_description || body.error || '');
+    if (/未知操作|未在权限表中登记|unknown action|not_?found|unsupported_grant_type/i.test(msg)) return true;
+  }
+  return false;
+}
+
+/**
+ * 第 1 步：申请设备码（**不发浏览器、不打印、不轮询**）。
+ *
+ * @returns {Promise<object>} 归一化后的设备码对象：
+ *   { device_code, user_code, verification_uri, verification_uri_complete, open_url,
+ *     expires_in, interval, expires_at, requested_at, endpoint_path, metadata }
+ */
+export async function requestDeviceCode({ config, deps = {} }) {
+  const fetchImpl = deps.fetchImpl || globalThis.fetch;
+  const now = deps.now || (() => Date.now());
+  const api = createApi({ config, fetchImpl });
+
+  /* ---- 0. 发现端点：优先用 metadata 声明的；没有就用默认路径 ---- */
+  let metadata = deps.metadata || null;
+  if (!metadata) {
+    try {
+      metadata = await api.metadata();
+    } catch {
+      /* metadata 拿不到不是致命问题，用默认路径试 */
+    }
+  }
+  const endpointPath =
+    metadata && metadata.device_authorization_endpoint
+      ? String(metadata.device_authorization_endpoint).replace(config.base, '')
+      : DEFAULT_DEVICE_PATH;
+
+  /* ---- 1. 申请设备码 ---- */
+  const req = await api.oauthForm(endpointPath, { client_id: config.clientId, scope: config.scope });
+  if (req.networkError) {
+    throw new CliError(`申请设备码失败：${req.networkError}`, {
+      kind: 'network',
+      hint: '检查网络后重试；也可以改用本地回调模式 `wkgeo login`',
+    });
+  }
+  if (looksNotImplemented(req)) {
+    throw new CliError(
+      `服务端未实现设备码授权（POST ${endpointPath} → HTTP ${req.status}${req.body && req.body.message ? '，' + req.body.message : ''}）`,
+      {
+        kind: 'not_implemented',
+        code: req.status,
+        hint:
+          '这是**服务端能力缺口**（不是命令用错）：请改用本地回调模式 `wkgeo login`；' +
+          '服务端补端点的最小方案见 cli/docs/设备码授权-服务端最小方案.md',
+        exitCode: EXIT.ERROR,
+      },
+    );
+  }
+  const body = req.body || {};
+  if (!body.device_code || !body.user_code) {
+    // 端点存在但返回的形状不对（比如返回了统一信封）→ 如实报错，别猜
+    const cls =
+      body.code !== undefined && body.code !== 0
+        ? `服务端返回 code=${body.code}：${body.message || ''}`
+        : `服务端返回的形状不符合 RFC 8628（缺少 device_code / user_code）：${JSON.stringify(body).slice(0, 200)}`;
+    throw new CliError(`设备码申请失败：${cls}`, {
+      kind: 'device_authorization_failed',
+      code: body.code,
+      hint: '可改用本地回调模式 `wkgeo login` 完成授权',
+    });
+  }
+
+  const userCode = String(body.user_code);
+  /**
+   * ⚠️ 兜底地址**必须带尾斜杠**：`${基址}/oauth/device`（不带斜杠）会踩同一个坑 ——
+   *    托管侧对目录路径做 302 且**丢掉 query**，`?user_code=…` 预填参数会被剥光，
+   *    用户就得自己手输短码（甚至显示"授权请求不完整"）。
+   *    拼法统一走 `withTrailingSlash()`（cli/lib 里唯一入口，见 config.mjs）。
+   *    服务端 metadata 给的 `verification_uri` 也一样过一道：不能假设它永远配得对。
+   * ★ 2026-10-02（三站拆分）：兜底基址改用**授权站子域** `config.oauthWebBase`。
+   */
+  const verificationUri = withTrailingSlash(
+    String(body.verification_uri || `${config.oauthWebBase}/oauth/device`),
+  );
+  /**
+   * `verification_uri_complete`（带短码预填的地址）：服务端给了就用它的，
+   * **没给就自己拼一个**。
+   *
+   * ⚠️ 为什么不再"服务端没给就留空"：
+   *   这条流程的整个卖点是"用户只点一下、不用手输短码"（老板要的友好路径）。
+   *   留空的话用户得自己把 `ABCD-1234` 敲进页面，而我们**明明能拼**——
+   *   RFC 8628 §3.3.1 就把 `verification_uri_complete` 定义为"已经带好用户码的地址"。
+   *   参数名必须与确认页一致（`admin-web/src/pages/device/index.tsx` 读 `user_code`），
+   *   所以这里拼的是 `?user_code=<码>`；地址本身已经过 `withTrailingSlash()`
+   *   （尾斜杠必须在 `?` **之前**，否则托管侧 302 会把 query 丢掉）。
+   */
+  const verificationUriComplete = body.verification_uri_complete
+    ? withTrailingSlash(String(body.verification_uri_complete))
+    : buildVerificationUriComplete(verificationUri, userCode);
+  const expiresInSec = Number(body.expires_in) > 0 ? Number(body.expires_in) : DEFAULT_DEVICE_EXPIRES_SEC;
+  const intervalSec = Number(body.interval) > 0 ? Number(body.interval) : DEFAULT_DEVICE_INTERVAL_SEC;
+
+  return {
+    device_code: String(body.device_code),
+    user_code: userCode,
+    verification_uri: verificationUri,
+    verification_uri_complete: verificationUriComplete,
+    open_url: verificationUriComplete || verificationUri,
+    expires_in: expiresInSec,
+    interval: intervalSec,
+    /**
+     * ★ 绝对到期时刻（毫秒）。**必须落成绝对时间**（而不是"还能等 N 秒"）：
+     *    `--no-wait` 会把这份状态写到磁盘，用户可能 3 分钟后才回来续跑，
+     *    相对秒数在那种情况下会算错（变成"又能等 600 秒"），绝对时刻不会。
+     */
+    expires_at: now() + expiresInSec * 1000,
+    requested_at: now(),
+    endpoint_path: endpointPath,
+    metadata,
+  };
+}
+
+/** 用户可直接复制的那句话（AI 端拿到 `paste_text` 就能原样转达，不用自己组织语言） */
+export function devicePasteText(device) {
+  return `请打开 ${device.open_url} 并完成「同意授权」（短码：${device.user_code}）。`;
+}
+
+/**
+ * 由 `verification_uri` + 短码拼出"单击即用"的确认地址。
+ *
+ * ⚠️ 用 `URL` 而不是字符串拼接，是为了让 **fragment / 已有 query** 都落到正确位置
+ *    （手拼时 `#frag` 之后的内容对服务器无意义，还可能拼出两个 `?`）。
+ * ⚠️ 参数名**必须**是 `user_code`：确认页 `admin-web/src/pages/device/index.tsx`
+ *    就是读这个名字（改这里 = 改前后端契约，两边必须同时改）。
+ * ⚠️ 解析失败（地址不合法）也不能抛错：这是"锦上添花"的地址，抛错会连累整条授权流程。
+ */
+export function buildVerificationUriComplete(verificationUri, userCode) {
+  try {
+    const u = new URL(verificationUri);
+    u.searchParams.set('user_code', String(userCode));
+    return u.toString();
+  } catch {
+    const sep = String(verificationUri).includes('?') ? '&' : '?';
+    return `${verificationUri}${sep}user_code=${encodeURIComponent(String(userCode))}`;
+  }
+}
+
+/**
+ * 第 2 步：把网址/短码交给用户（人读一段 + 机器读一份 + 必要时自动打开浏览器）。
+ *
+ * @param {object} args
+ * @param {object} args.device requestDeviceCode() 的返回值
+ * @param {object} [args.extra]  额外合进 `onDeviceCode(info)` 的字段（例如 --no-wait 的 resume_command）
+ */
+export function announceDeviceCode({ config, log = () => {}, deps = {}, device, extra = {} }) {
+  const pasteText = devicePasteText(device);
+  log('');
+  log('请在浏览器中完成授权（设备码模式，不需要任何回调地址）：');
+  log('');
+  log(`  1) 打开：${device.open_url}`);
+  /**
+   * ⚠️ 短码**始终**打印一遍（哪怕地址里已经预填了）：页面万一没读到 `?user_code=`，
+   *    用户还能照着敲；这也是用户"复制给 AI 端"时最需要的那串字符。
+   */
+  log(`  2) 如果页面没有自动填好短码，请输入：${device.user_code}`);
+  log('');
+  /**
+   * ★ 这一行是给"用户把信息复制到 AI 对话框"这个用法准备的（老板明确要的形态）：
+   *    一整句、带完整网址和短码，选中复制就能用，不需要用户自己拼。
+   */
+  log(`📋 可以直接复制这段发给 AI 端或转给用户：${pasteText}`);
+  log('');
+  if (typeof deps.onDeviceCode === 'function') {
+    deps.onDeviceCode({
+      user_code: device.user_code,
+      verification_uri: device.verification_uri,
+      verification_uri_complete: device.verification_uri_complete,
+      expires_in: device.expires_in,
+      interval: device.interval,
+      open_url: device.open_url,
+      paste_text: pasteText,
+      ...extra,
+    });
+  }
+  /**
+   * ★ 走**同一个闸门**（`resolveBrowserIntent`，与 login 回调模式、钱包充值完全同一份逻辑）。
+   *
+   * ★ 老板最终拍板走**传统路线**：**默认总是尝试打开**系统浏览器（设备码模式同样如此，
+   *   人在终端与 AI 场景都一样）；唯一的"不打开"开关是 `--no-browser`。
+   *   （历史：2026-10-01 曾改成"只有人在终端才弹"，那版已按老板最终决定回退。）
+   */
+  const browserIntent = resolveBrowserIntent({
+    isTTY: deps.isTTY === true,
+    json: deps.json === true,
+    forceOpen: deps.forceBrowser === true,
+    noBrowser: deps.openBrowser === false || deps.noBrowser === true,
+  });
+  if (browserIntent.allow) {
+    // 传入函数时用注入的（测试/自定义）；否则用**真·打开浏览器**
+    const opener = typeof deps.openBrowser === 'function' ? deps.openBrowser : defaultOpenBrowser(deps, log);
+    /**
+     * 打开失败**绝不中断授权**：地址已经完整打印在上面了，而且失败提示里会**再带一遍完整 URL**
+     * （见 login.mjs 的 browserFailedHintLines；Windows 上 `&` 被 cmd 当命令分隔符吃掉的坑
+     *  见 login.mjs 顶部对 BROWSER_STRATEGY_TABLE 的说明）。
+     * ⚠️ 同步版 `defaultOpenBrowser` 只能判断"进程有没有被创建出来"：
+     *    异步失败（emit error）会由它自己的 onError 再打一段同样的提示，这里不重复。
+     */
+    const opened = opener(device.open_url);
+    if (opened) {
+      log(browserOpenedText({ kind: 'auth' }));
+    } else {
+      for (const line of browserFailedHintLines(device.open_url, { kind: 'auth', agent: browserIntent.mode === 'agent' })) {
+        log(line);
+      }
+    }
+  } else if (browserIntent.skipped_reason === 'no_browser') {
+    // 用户主动关掉的，不该报"失败"
+    log('（已按 --no-browser 跳过自动打开）');
+  }
+  return pasteText;
+}
+
+/**
+ * 第 3 步：轮询换票，成功后写本地凭据。
+ *
+ * @param {object} args.device  requestDeviceCode() 的返回值（或从 `--device-continue` 读回的状态）
+ * @param {object} [args.deps]
+ *   ★ `deps.shouldStop()` —— 可选。返回 true 时**立刻停止轮询**并抛 `kind = 'cancelled'`。
+ *     用途只有一个：`commands/auth.mjs` 里"回调 / 设备码**两条路并存**"时，回调那条路先拿到令牌，
+ *     设备码这条就不该再对同一个授权做第二次换票（也不该继续占着进程）。
+ *     ⚠️ 每个循环的**睡醒之后**也要再查一次：`sleep` 可能是几秒的定时器，醒来时另一条路可能已经赢了。
+ * @returns {Promise<object>} {credentials, account, mode, metadata, mode_name, user_code,
+ *                             verification_uri, poll_attempts}
+ */
+export async function pollDeviceToken({ config, log = () => {}, deps = {}, device }) {
+  const fetchImpl = deps.fetchImpl || globalThis.fetch;
+  const sleep = deps.sleep || sleepDefault;
+  const now = deps.now || (() => Date.now());
+  /** ★ 另一条路赢了就停（见上面 deps.shouldStop 的说明） */
+  const shouldStop = typeof deps.shouldStop === 'function' ? deps.shouldStop : null;
+  const stopped = () =>
+    new CliError('设备码轮询已停止（另一条路已经完成登录）', {
+      kind: 'cancelled',
+      hint: '不需要做任何事：登录已经完成',
+      exitCode: EXIT.AUTH,
+    });
+  const api = createApi({ config, fetchImpl });
+
+  const expiresAt = Number(device.expires_at) > 0 ? Number(device.expires_at) : now() + device.expires_in * 1000;
+  let intervalMs = (Number(device.interval) > 0 ? Number(device.interval) : DEFAULT_DEVICE_INTERVAL_SEC) * 1000;
+  const expiresInSec = Math.max(0, Math.round((expiresAt - now()) / 1000));
+
+  log(`等待你在浏览器里完成授权…（每 ${Math.round(intervalMs / 1000)} 秒轮询一次，最多 ${expiresInSec} 秒）`);
+
+  let attempts = 0;
+  for (;;) {
+    if (shouldStop && shouldStop()) throw stopped();
+    if (now() >= expiresAt) {
+      throw new CliError(`设备码已过期（等待超过 ${device.expires_in} 秒）`, {
+        kind: 'expired',
+        hint: `重新运行 \`${config.cmdName || 'wkgeo'} login --device\` 获取新的短码`,
+        exitCode: EXIT.AUTH,
+      });
+    }
+    await sleep(intervalMs);
+    // ★ 睡醒后必须再查一次：这一觉可能睡了几秒，期间另一条路可能已经拿到令牌了
+    if (shouldStop && shouldStop()) throw stopped();
+    attempts++;
+
+    const res = await api.oauthForm('/api/oauth/token', {
+      grant_type: DEVICE_GRANT_TYPE,
+      device_code: device.device_code,
+      client_id: config.clientId,
+    });
+    if (res.networkError) {
+      // 网络抖一下不该让整个授权作废：记一笔继续轮询（直到过期）
+      log(`⚠️ 第 ${attempts} 次轮询网络失败（${res.networkError}），继续重试…`);
+      continue;
+    }
+    const rb = res.body || {};
+    if (res.status === 200 && rb.access_token) {
+      let account = null;
+      try {
+        account = await api.userinfo(rb.access_token);
+      } catch {
+        /* 身份信息拿不到不影响已登录这个事实 */
+      }
+      const credentials = credentialsFromToken({
+        clientId: config.clientId,
+        tokenResponse: rb,
+        account,
+        scope: config.scope,
+        now: now(),
+      });
+      const mode = writeCredentials(config.credentialsFile, credentials, { now: now() });
+      log('✅ 授权成功，凭据已保存到本机。');
+      return {
+        credentials,
+        account,
+        mode,
+        metadata: device.metadata || null,
+        mode_name: 'device',
+        user_code: device.user_code,
+        verification_uri: device.verification_uri,
+        /** 再给一份"可直接复制给 AI 端"的话（成功回执里也带上，方便用户补发） */
+        paste_text: devicePasteText(device),
+        poll_attempts: attempts,
+      };
+    }
+
+    const err = String(rb.error || '');
+    if (err === 'authorization_pending') {
+      log(`  …等待用户确认（第 ${attempts} 次轮询）`);
+      continue;
+    }
+    if (err === 'slow_down') {
+      intervalMs += 5000; // RFC 8628：被要求放慢就 +5 秒
+      log(`  服务端要求放慢轮询，间隔改为 ${Math.round(intervalMs / 1000)} 秒`);
+      continue;
+    }
+    if (err === 'access_denied') {
+      throw new CliError('用户在浏览器里拒绝了本次授权', {
+        kind: 'denied',
+        code: 'access_denied',
+        hint: '没有写入任何凭据；需要时重新运行 `wkgeo login --device`',
+        exitCode: EXIT.AUTH,
+      });
+    }
+    if (err === 'expired_token') {
+      throw new CliError('设备码已过期', {
+        kind: 'expired',
+        code: 'expired_token',
+        hint: '重新运行 `wkgeo login --device` 获取新的短码',
+        exitCode: EXIT.AUTH,
+      });
+    }
+    if (looksNotImplemented(res)) {
+      throw new CliError(`服务端不支持设备码换票（HTTP ${res.status}）`, {
+        kind: 'not_implemented',
+        code: res.status,
+        hint: '服务端缺口：见 cli/docs/设备码授权-服务端最小方案.md；可改用 `wkgeo login`',
+      });
+    }
+    // 其它错误：保留原始 error / error_description，绝不吞
+    const msg = String(rb.error_description || rb.message || rb.error || `HTTP ${res.status}`);
+    throw new CliError(`换取令牌失败：${msg}`, {
+      kind: 'token_exchange',
+      code: rb.error || res.status,
+      hint: `原始响应：${JSON.stringify(rb).slice(0, 200)}；${loginHint(config.cmdName || 'wkgeo')}`,
+    });
+  }
+}
+
+/**
+ * 一口气跑完：申请 → 交给用户 → 轮询 → 写凭据。
+ * （命令层为了支持 `--no-wait` / `--device-continue` 会自己按顺序调上面三步；
+ *   这个入口保留给"就是要一次跑完"的调用方与既有单测。）
+ */
+export async function runDeviceLogin({ config, log = () => {}, deps = {} }) {
+  const device = await requestDeviceCode({ config, deps });
+  announceDeviceCode({ config, log, deps, device });
+  return pollDeviceToken({ config, log, deps, device });
+}