mn-ws 0.1.0 → 0.2.0

package/assets/groups.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "$comment": "group 名 → skill 名列表的别名表。路径恒由 assets/<skills[i]>/ 推导；本文件只做聚合。",
+  "groups": {
+    "mn-ws": {
+      "skills": ["mn-ws"],
+      "summary": "mn-ws 主 skill（默认 skill install 装的就是它）"
+    }
+  }
+}

package/assets/mn-ws/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: mn-ws
+description: HTTP 与 WebSocket 双向桥的客户端半：把本机 nx 服务桥给远端 HTTP 客户端。当用户要求操作本项目（启动服务/面板、查看路由与健康状态、安装本 skill、了解可用命令）时使用。触发词：mn-ws、启动面板、skill install、查看路由、健康检查。
+---
+# mn-ws skill
+
+本项目是「CLI 与 Web 面板同源」的本机工具：一条 action 声明同时派生出
+CLI 命令与 HTTP 路由，Web 上能做的，CLI 都能做。
+
+- 项目根（安装时注入，固定值）：`{{PROJECT_ROOT}}`
+
+## 常用命令
+
+在项目根目录执行：
+
+```bash
+# 启动 Web 面板（默认端口 7777）
+node bin/ws.mjs serve            # 开发期：pnpm dev
+
+# 查看全部命令与 HTTP 路由对照
+node bin/ws.mjs routes
+
+# 健康检查
+node bin/ws.mjs health
+
+# skill：列出 / 导出 / 安装
+node bin/ws.mjs skill list
+node bin/ws.mjs skill get mn-ws
+node bin/ws.mjs skill install mn-ws
+node bin/ws.mjs skill install --all   # 一次装全部 skill（与 name / --group 互斥）
+```
+
+加 `--json` 可获取机器可读输出（错误时同样输出 JSON）。
+
+## 端口与浏览器
+
+- `serve` 端口被占时不会报错：上面已经是本项目的面板就**直接打开它**（不重复启动），
+  是别的服务（或探测不出来）就顺延到下一个空闲端口再起自己的面板
+- 两种情况都会自动打开浏览器；`NX_SERVE_NO_OPEN=1`（所有 nx-xx 项目共用的同一个
+  环境变量）可全局关掉自动开浏览器，`--no-open` 只影响这一次调用
+- `pnpm dev` 同样先认领后端端口：自己的面板就复用（不再起第二个 serve），别的服务就
+  顺延到下一个空闲端口（vite 的代理目标会跟着一起走）；两种情况都会把浏览器指到 dev 地址
+
+## 典型会话
+
+1. 用户要求启动面板 → `serve`，确认端口可访问
+2. 用户问「有哪些接口/命令」→ `routes`
+3. 用户要把本 skill 装给 agent → `skill install mn-ws`
+   （安装钩子会校验当前目录是本项目根，并注入项目根路径）
+
+## 约束
+
+- 操作本项目一律在项目根目录内调用本地 CLI
+- 本 skill 只能在 mn-ws 项目根目录安装：非该目录会被安装钩子拒绝
+- 命令、参数与 flag 的权威清单看 `routes --json`，不要凭记忆杜撰

package/assets/mn-ws/hooks.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "$comment": "本 skill 的安装钩子，经通用 hook 总线执行。事件平面开放；match 为正则，匹配 skill 名。",
+  "hooks": {
+    "skill:pre-install": [
+      {
+        "match": "^mn-ws$",
+        "hooks": [
+          { "type": "module", "use": "./install/inject-root.mjs" }
+        ]
+      }
+    ]
+  }
+}

package/assets/mn-ws/install/inject-root.mjs

@@ -0,0 +1,26 @@
+// skill:pre-install 的 module handler（经本 skill 的 hooks.json 注册）。
+//
+//   cwd 不是本项目根（package.json name 不匹配）→ { block }，拒绝安装；
+//   是 → { vars: { PROJECT_ROOT } }，把项目根全路径渲染进 SKILL.md。
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export default async function injectRoot(payload) {
+  const root = payload.cwd;
+  let pkgName = null;
+  try {
+    pkgName = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).name;
+  } catch {
+    pkgName = null;
+  }
+  if (pkgName !== 'mn-ws') {
+    return {
+      block: [
+        `mn-ws skill 只能在 mn-ws 项目根目录内安装，当前目录不是：${root}`,
+        '判定条件：package.json 的 name 为 "mn-ws"。',
+        `请先 cd 到 mn-ws 项目根目录，再重新执行 skill install mn-ws。`,
+      ].join('\n'),
+    };
+  }
+  return { vars: { PROJECT_ROOT: root.replace(/\\/g, '/') } };
+}

package/bin/ws.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// mn-ws 唯一入口。
+//
+// 设计约定：Web 面板上每个按钮，都对应这里的一条 CLI 命令——二者由同一份 action
+// 声明派生（见 src/modules/*/index.ts），不是靠人维护两份清单。
+//
+// 运行的是构建产物 dist/（Node 侧 tsc 输出）。发布前必须先 pnpm build。
+import { runCli } from '../dist/runtime/cli.js';
+
+runCli(process.argv.slice(2)).catch((err) => {
+  console.error(err && err.stack ? err.stack : String(err));
+  process.exitCode = 1;
+});

package/dist/core/auth.d.ts

@@ -0,0 +1,194 @@
+/**
+ * client 半的统一登录：PKCE 授权码流程。
+ *
+ * ## 两种发起方式，同一套协议
+ *
+ *   · **CLI**（`mn-ws auth login`）：在**随机端口**起一次性回环监听，
+ *     浏览器把授权码送回来，CLI 自己换 token。
+ *   · **Web 面板**（面板里点「登录」）：在**面板自己的端口**上收码
+ *     （路径固定 /callback），面板后端换 token。
+ *
+ * 两者用的是同一个 client_id（`mn-ws-client`），回调白名单是
+ * `http://127.0.0.1:<任意端口>/callback` —— 端口通配、路径固定，主机与路径都严格受限。
+ *
+ * ⚠️ 上面那句「任意端口」在别处写成字面量会出事：端口通配的形态是
+ * 「星号紧跟斜杠」，出现在**块注释里**会把注释提前闭合 ——
+ * 文件后半截被当成代码，报一堆莫名其妙的语法错。mn-rt 真实踩过一次。
+ *
+ * ## 为什么 CLI 自己换 token（而不是交给 server 换）
+ *
+ * 交给 server 换需要 server 自己发起 authorize 并持有 PKCE verifier ——
+ * 那就多一份 RP 会话（cookie/存储）要实现。CLI 自己换 token 只需登记
+ * 回环通配（127.0.0.1 端口任意、路径固定 /callback）—— RFC 8252 给原生
+ * 客户端的标准做法。
+ */
+/** CLI 侧回环回调路径。端口 0 让内核分配，再回填进 authorize 请求。 */
+export declare const LOOPBACK_PATH = "/callback";
+/** 等用户完成登录的时间上限（5 分钟）。 */
+export declare const LOGIN_TIMEOUT_MS: number;
+export declare function b64url(buf: Buffer | string): string;
+/**
+ * 取「发起授权码流程时该用的 client_id」。
+ *
+ * 两端拆开之后：**server 半有它自己的身份**（mn-ws-server），而真正发起授权码
+ * 流程的是 **client 半**（mn-ws-client）。server 半通过 /auth/oidc/config 把
+ * 后者一并发布出来，所以新装的 client 半不需要额外配置 —— 与 mn-rt
+ * 「server 告诉 client 用哪个 client_id」的做法一致，只是这里明确分成了两个身份。
+ *
+ * 回落 cfg.clientId：老的 server 只发布一个 client_id，那时的登录用的就是它。
+ */
+export declare function loginClientIdOf(cfg: {
+    loginClientId?: string;
+    clientId?: string;
+} | null | undefined): string;
+/** 一次授权请求的 PKCE 参数与一次性参数。 */
+export interface AuthRequest {
+    verifier: string;
+    challenge: string;
+    state: string;
+    nonce: string;
+    authorizeParams: Record<string, string>;
+}
+/**
+ * 生成 PKCE 与一次性参数。
+ *
+ * 注意 state 只有**一个**值：authorizeParams 里的那个就是真正发出去的，
+ * 也是回调回来后要比对的。曾经同时返回两个独立随机值，导致每次登录都必然
+ * 报 state 不一致 —— 这里只留一份。
+ */
+export declare function createAuthRequest(redirectUri: string): AuthRequest;
+/** 认证中心下发的公开参数（来自 server 半的 /auth/oidc/config）。 */
+export interface IdpConfig {
+    enabled?: boolean;
+    issuer?: string;
+    clientId?: string;
+    loginClientId?: string;
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    scopes?: string[];
+    [k: string]: unknown;
+}
+/** 组 authorize URL。 */
+export declare function buildAuthorizeUrl(cfg: IdpConfig, req: AuthRequest, { promptLogin }?: {
+    promptLogin?: boolean | undefined;
+}): string;
+/** 回环监听器。 */
+export interface Loopback {
+    /** 起监听；port=0 让内核分配（CLI），port=N 用固定端口（面板）。 */
+    start(): Promise<string>;
+    wait(ms?: number): Promise<{
+        code: string;
+        state: string;
+    }>;
+    close(): void;
+}
+/**
+ * 起一次性回环监听，等浏览器把 code 送回来。
+ *
+ * 只绑 127.0.0.1：绑 0.0.0.0 会让同网段任何人都能来抢这个 code。
+ */
+export declare function openLoopback({ port }?: {
+    port?: number;
+}): Loopback;
+/**
+ * 各平台打开浏览器的命令与参数。
+ *
+ * ── Windows 为什么绝不借道 `cmd /c start` ────────────────────────────────
+ * 授权 URL 里全是 `&`。Node execFile 对不含空格的参数不加引号，命令行到达
+ * cmd.exe 后 `&` 被**当成命令分隔符**：浏览器只收到第一个 `&` 之前的部分，
+ * redirect_uri / code_challenge 全被切掉，报「redirect_uri 未在白名单内」。
+ * rundll32 的 FileProtocolHandler 不经任何 shell 解析，命令行原样到达。
+ */
+export declare function openBrowserArgs(platform: string, url: string): [string, string[]];
+export declare function openBrowser(url: string): void;
+/** 一个 HTTP JSON 响应。 */
+export interface JsonResponse {
+    status: number;
+    json: Record<string, unknown> | null;
+    raw: string;
+}
+export declare function getJson(url: string): Promise<JsonResponse>;
+/** POST 一个 form（application/x-www-form-urlencoded）。 */
+export declare function postJson(url: string, { form }: {
+    form: Record<string, string>;
+}): Promise<JsonResponse>;
+/** 登录的最终产物。 */
+export interface LoginResult {
+    userId?: string;
+    email?: string;
+    username?: string;
+    nickname?: string;
+    token?: string;
+    tokenExpiresAt?: number;
+    clientId?: string;
+    deviceName?: string;
+    /** --no-open 模式：只打印地址，没走完授权 */
+    pending?: boolean;
+    authorizeUrl?: string;
+}
+/** authLogin 的参数。 */
+export interface AuthLoginOptions {
+    serverHttp: string;
+    clientId: string;
+    deviceName?: string;
+    /** 只打印地址不弹浏览器（SSH / 无桌面环境） */
+    noOpen?: boolean;
+    /** authorize 带 prompt=login（换人登录用） */
+    promptLogin?: boolean;
+    /** 面板场景：回环监听用面板自己的端口 */
+    loopbackPort?: number;
+    onUrl?: (url: string) => void;
+}
+/**
+ * 起一次授权码流程。
+ *
+ * 拆成「起流程」与「收回调」两半，是因为**收回调的位置不一样**：
+ *   · CLI：在**随机端口**另起一个一次性回环监听
+ *   · 面板：回调落在**面板自己的 HTTP 服务器**上（/callback）
+ * 协议部分（PKCE、state、换 token）两边完全一样，所以只写一份。
+ *
+ * @param cfg      认证中心参数（server 半的 /auth/oidc/config）
+ * @param redirectUri 回调地址（必须在白名单内）
+ */
+export declare function beginOauth(cfg: IdpConfig, redirectUri: string, { promptLogin }?: {
+    promptLogin?: boolean | undefined;
+}): {
+    authorizeUrl: string;
+    req: AuthRequest;
+};
+/**
+ * 收回调：用 code + verifier 换 access_token。
+ *
+ * state 不匹配只有两种可能：回调被串了，或有人在伪造一次登录完成。都必须中止。
+ */
+export declare function finishOauth(cfg: IdpConfig, req: AuthRequest, callback: {
+    code: string;
+    state: string;
+}): Promise<{
+    accessToken: string;
+    tokenType?: string;
+    expiresIn?: number;
+}>;
+/** 拉取 server 半发布的认证中心参数。 */
+export declare function fetchIdpConfig(serverHttp: string): Promise<IdpConfig>;
+/**
+ * 完整登录一次（CLI 用）。
+ *
+ * @param opts.serverHttp  server 半的 HTTP 基址，如 http://1.94.101.189:7777
+ * @param opts.clientId    本机稳定 clientId
+ */
+export declare function authLogin(opts: AuthLoginOptions): Promise<LoginResult>;
+/**
+ * 用 access_token 换 mn-ws 自己的设备令牌。
+ *
+ * 这一步是**跨机**的（CLI → 公网机），走的明文 HTTP 时中间人能看到
+ * 那枚 access_token —— 它 10 分钟有效，但窗口内被截获就等于账号接管。
+ * 所以部署侧必须前置 TLS（见 docs/DEPLOY.md 的「已知风险」）。
+ */
+export declare function verifyExchange({ serverHttp, accessToken, clientId, deviceName, }: {
+    serverHttp: string;
+    accessToken: string;
+    clientId: string;
+    deviceName?: string;
+}): Promise<LoginResult>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/core/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/core/auth.ts"],"names":[],"mappings":"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"}

package/dist/core/auth.js

@@ -0,0 +1,331 @@
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import { URL } from 'node:url';
+/**
+ * client 半的统一登录：PKCE 授权码流程。
+ *
+ * ## 两种发起方式，同一套协议
+ *
+ *   · **CLI**（`mn-ws auth login`）：在**随机端口**起一次性回环监听，
+ *     浏览器把授权码送回来，CLI 自己换 token。
+ *   · **Web 面板**（面板里点「登录」）：在**面板自己的端口**上收码
+ *     （路径固定 /callback），面板后端换 token。
+ *
+ * 两者用的是同一个 client_id（`mn-ws-client`），回调白名单是
+ * `http://127.0.0.1:<任意端口>/callback` —— 端口通配、路径固定，主机与路径都严格受限。
+ *
+ * ⚠️ 上面那句「任意端口」在别处写成字面量会出事：端口通配的形态是
+ * 「星号紧跟斜杠」，出现在**块注释里**会把注释提前闭合 ——
+ * 文件后半截被当成代码，报一堆莫名其妙的语法错。mn-rt 真实踩过一次。
+ *
+ * ## 为什么 CLI 自己换 token（而不是交给 server 换）
+ *
+ * 交给 server 换需要 server 自己发起 authorize 并持有 PKCE verifier ——
+ * 那就多一份 RP 会话（cookie/存储）要实现。CLI 自己换 token 只需登记
+ * 回环通配（127.0.0.1 端口任意、路径固定 /callback）—— RFC 8252 给原生
+ * 客户端的标准做法。
+ */
+/** CLI 侧回环回调路径。端口 0 让内核分配，再回填进 authorize 请求。 */
+export const LOOPBACK_PATH = '/callback';
+/** 等用户完成登录的时间上限（5 分钟）。 */
+export const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+export function b64url(buf) {
+    return Buffer.from(buf).toString('base64')
+        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * 取「发起授权码流程时该用的 client_id」。
+ *
+ * 两端拆开之后：**server 半有它自己的身份**（mn-ws-server），而真正发起授权码
+ * 流程的是 **client 半**（mn-ws-client）。server 半通过 /auth/oidc/config 把
+ * 后者一并发布出来，所以新装的 client 半不需要额外配置 —— 与 mn-rt
+ * 「server 告诉 client 用哪个 client_id」的做法一致，只是这里明确分成了两个身份。
+ *
+ * 回落 cfg.clientId：老的 server 只发布一个 client_id，那时的登录用的就是它。
+ */
+export function loginClientIdOf(cfg) {
+    return String((cfg && cfg.loginClientId) || (cfg && cfg.clientId) || '').trim();
+}
+/**
+ * 生成 PKCE 与一次性参数。
+ *
+ * 注意 state 只有**一个**值：authorizeParams 里的那个就是真正发出去的，
+ * 也是回调回来后要比对的。曾经同时返回两个独立随机值，导致每次登录都必然
+ * 报 state 不一致 —— 这里只留一份。
+ */
+export function createAuthRequest(redirectUri) {
+    const verifier = b64url(crypto.randomBytes(32));
+    // PKCE 的 challenge = BASE64URL(SHA256(verifier))，S256
+    const challenge = b64url(crypto.createHash('sha256').update(verifier).digest());
+    const state = b64url(crypto.randomBytes(16));
+    return {
+        verifier,
+        challenge,
+        state,
+        nonce: b64url(crypto.randomBytes(16)),
+        authorizeParams: {
+            response_type: 'code',
+            redirect_uri: redirectUri,
+            code_challenge: challenge,
+            code_challenge_method: 'S256',
+            state,
+        },
+    };
+}
+/** 组 authorize URL。 */
+export function buildAuthorizeUrl(cfg, req, { promptLogin = false } = {}) {
+    const authorizeUrl = new URL(cfg.authorizationEndpoint || `${cfg.issuer}/oauth2/auth`);
+    authorizeUrl.searchParams.set('client_id', loginClientIdOf(cfg));
+    authorizeUrl.searchParams.set('scope', (cfg.scopes || ['openid', 'profile', 'email']).join(' '));
+    authorizeUrl.searchParams.set('state', req.state);
+    authorizeUrl.searchParams.set('nonce', req.nonce);
+    for (const [k, v] of Object.entries(req.authorizeParams))
+        authorizeUrl.searchParams.set(k, v);
+    if (promptLogin)
+        authorizeUrl.searchParams.set('prompt', 'login');
+    return authorizeUrl.toString();
+}
+/**
+ * 起一次性回环监听，等浏览器把 code 送回来。
+ *
+ * 只绑 127.0.0.1：绑 0.0.0.0 会让同网段任何人都能来抢这个 code。
+ */
+export function openLoopback({ port = 0 } = {}) {
+    let server;
+    let resolveFn;
+    let rejectFn;
+    const got = new Promise((res, rej) => { resolveFn = res; rejectFn = rej; });
+    return {
+        start() {
+            return new Promise((resolve, reject) => {
+                server = http.createServer((req, res) => {
+                    const u = new URL(req.url || '/', 'http://127.0.0.1');
+                    if (u.pathname !== LOOPBACK_PATH) {
+                        res.writeHead(404).end();
+                        return;
+                    }
+                    const err = u.searchParams.get('error');
+                    if (err) {
+                        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+                            .end('<h3>授权未通过</h3><p>可以关闭这个页面了。</p>');
+                        rejectFn?.(new Error(`授权被拒绝：${err}`));
+                        return;
+                    }
+                    const code = u.searchParams.get('code');
+                    const state = u.searchParams.get('state');
+                    if (!code) {
+                        rejectFn?.(new Error('回调里没有 code'));
+                        return;
+                    }
+                    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+                        .end('<h3>✅ 已收到授权</h3><p>可以关闭浏览器，回到终端了。</p>');
+                    resolveFn?.({ code, state: state || '' });
+                });
+                server.once('error', reject);
+                server.listen(port, '127.0.0.1', () => {
+                    const addr = server?.address();
+                    const actual = typeof addr === 'object' && addr ? addr.port : port;
+                    resolve(`http://127.0.0.1:${actual}${LOOPBACK_PATH}`);
+                });
+            });
+        },
+        wait(ms = LOGIN_TIMEOUT_MS) {
+            return Promise.race([
+                got,
+                new Promise((_, rej) => {
+                    const t = setTimeout(() => rej(new Error('登录超时（5 分钟未完成）')), ms);
+                    t.unref?.();
+                }),
+            ]);
+        },
+        close() {
+            try {
+                server?.close();
+            }
+            catch { /* ignore */ }
+        },
+    };
+}
+/**
+ * 各平台打开浏览器的命令与参数。
+ *
+ * ── Windows 为什么绝不借道 `cmd /c start` ────────────────────────────────
+ * 授权 URL 里全是 `&`。Node execFile 对不含空格的参数不加引号，命令行到达
+ * cmd.exe 后 `&` 被**当成命令分隔符**：浏览器只收到第一个 `&` 之前的部分，
+ * redirect_uri / code_challenge 全被切掉，报「redirect_uri 未在白名单内」。
+ * rundll32 的 FileProtocolHandler 不经任何 shell 解析，命令行原样到达。
+ */
+export function openBrowserArgs(platform, url) {
+    if (platform === 'darwin')
+        return ['open', [url]];
+    if (platform === 'win32')
+        return ['rundll32', ['url.dll,FileProtocolHandler', url]];
+    return ['xdg-open', [url]];
+}
+export function openBrowser(url) {
+    const [cmd, args] = openBrowserArgs(process.platform, url);
+    // spawn + detached + unref：开浏览器**不能**拖住 CLI（execFile 会等它退出）。
+    // detached 让它脱离父进程，unref 让它不占着事件循环。
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    child.on('error', (e) => {
+        process.stderr.write(`自动打开浏览器失败（${e.message.split('\n')[0]}），请手动打开上面打印的授权地址\n`);
+    });
+    child.unref();
+}
+export async function getJson(url) {
+    const res = await fetch(url, { headers: { accept: 'application/json' } });
+    const raw = await res.text();
+    let json = null;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch { /* ignore */ }
+    return { status: res.status, json, raw };
+}
+/** POST 一个 form（application/x-www-form-urlencoded）。 */
+export async function postJson(url, { form }) {
+    const body = new URLSearchParams(form).toString();
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body,
+    });
+    const raw = await res.text();
+    let json = null;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch { /* ignore */ }
+    return { status: res.status, json, raw };
+}
+/**
+ * 起一次授权码流程。
+ *
+ * 拆成「起流程」与「收回调」两半，是因为**收回调的位置不一样**：
+ *   · CLI：在**随机端口**另起一个一次性回环监听
+ *   · 面板：回调落在**面板自己的 HTTP 服务器**上（/callback）
+ * 协议部分（PKCE、state、换 token）两边完全一样，所以只写一份。
+ *
+ * @param cfg      认证中心参数（server 半的 /auth/oidc/config）
+ * @param redirectUri 回调地址（必须在白名单内）
+ */
+export function beginOauth(cfg, redirectUri, { promptLogin = false } = {}) {
+    const req = createAuthRequest(redirectUri);
+    const authorizeUrl = buildAuthorizeUrl(cfg, req, { promptLogin });
+    return { authorizeUrl, req };
+}
+/**
+ * 收回调：用 code + verifier 换 access_token。
+ *
+ * state 不匹配只有两种可能：回调被串了，或有人在伪造一次登录完成。都必须中止。
+ */
+export async function finishOauth(cfg, req, callback) {
+    if (callback.state !== req.state)
+        throw new Error('state 不一致，已中止登录');
+    const loginClientId = loginClientIdOf(cfg);
+    if (!loginClientId)
+        throw new Error('服务端未发布登录用的 client_id（loginClientId / clientId）');
+    // CLI 自己换 token（公共客户端 + PKCE，无 secret）
+    const tokRes = await postJson(cfg.tokenEndpoint || `${cfg.issuer}/oauth2/token`, {
+        form: {
+            grant_type: 'authorization_code',
+            code: callback.code,
+            client_id: loginClientId,
+            redirect_uri: req.authorizeParams.redirect_uri || '',
+            code_verifier: req.verifier,
+        },
+    });
+    const tok = tokRes.json || {};
+    if (!tokRes.status || tokRes.status >= 400 || !tok.access_token) {
+        throw new Error(`换 token 失败：${String(tok.error || tokRes.raw || `HTTP ${tokRes.status}`)}`);
+    }
+    return {
+        accessToken: String(tok.access_token),
+        tokenType: tok.token_type ? String(tok.token_type) : undefined,
+        expiresIn: typeof tok.expires_in === 'number' ? tok.expires_in : undefined,
+    };
+}
+/** 拉取 server 半发布的认证中心参数。 */
+export async function fetchIdpConfig(serverHttp) {
+    const base = serverHttp.replace(/\/+$/, '');
+    if (!base)
+        throw new Error('缺少服务端地址（--url 或配置文件）');
+    const cfgRes = await getJson(`${base}/auth/oidc/config`);
+    const cfg = (cfgRes.json || {});
+    if (!cfg.enabled) {
+        throw new Error('服务端未开启统一登录（MN_WS_AUTH_ENABLED）。'
+            + '旧用法仍可用：mn-ws --token <门禁token>');
+    }
+    if (!cfg.issuer || !cfg.clientId) {
+        throw new Error(`服务端统一登录配置不完整：${JSON.stringify(cfg)}`);
+    }
+    return cfg;
+}
+/**
+ * 完整登录一次（CLI 用）。
+ *
+ * @param opts.serverHttp  server 半的 HTTP 基址，如 http://1.94.101.189:7777
+ * @param opts.clientId    本机稳定 clientId
+ */
+export async function authLogin(opts) {
+    const base = opts.serverHttp.replace(/\/+$/, '');
+    if (!base)
+        throw new Error('缺少服务端地址（--url 或配置文件）');
+    const cfg = await fetchIdpConfig(base);
+    const lb = openLoopback({ port: opts.loopbackPort ?? 0 });
+    const redirectUri = await lb.start();
+    const { authorizeUrl, req } = beginOauth(cfg, redirectUri, { promptLogin: opts.promptLogin === true });
+    if (opts.onUrl)
+        opts.onUrl(authorizeUrl);
+    if (opts.noOpen) {
+        lb.close();
+        return { pending: true, authorizeUrl };
+    }
+    openBrowser(authorizeUrl);
+    let callback;
+    try {
+        callback = await lb.wait();
+    }
+    finally {
+        lb.close();
+    }
+    const tok = await finishOauth(cfg, req, callback);
+    // ⑤ 换 mn-ws 自己的设备令牌
+    const res = await verifyExchange({
+        serverHttp: base,
+        accessToken: tok.accessToken,
+        clientId: opts.clientId,
+        deviceName: opts.deviceName,
+    });
+    return { ...res, clientId: res.clientId || opts.clientId };
+}
+/**
+ * 用 access_token 换 mn-ws 自己的设备令牌。
+ *
+ * 这一步是**跨机**的（CLI → 公网机），走的明文 HTTP 时中间人能看到
+ * 那枚 access_token —— 它 10 分钟有效，但窗口内被截获就等于账号接管。
+ * 所以部署侧必须前置 TLS（见 docs/DEPLOY.md 的「已知风险」）。
+ */
+export async function verifyExchange({ serverHttp, accessToken, clientId, deviceName, }) {
+    const res = await fetch(`${serverHttp.replace(/\/+$/, '')}/auth/verify`, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${accessToken}`,
+            'content-type': 'application/json',
+            accept: 'application/json',
+        },
+        body: JSON.stringify({ clientId, deviceName: deviceName || '' }),
+    });
+    const raw = await res.text();
+    let json = null;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch { /* ignore */ }
+    if (!res.ok || !json || json.ok !== true) {
+        throw new Error(`换设备令牌失败：${String((json && json.error) || raw || `HTTP ${res.status}`)}`);
+    }
+    return json;
+}
+//# sourceMappingURL=auth.js.map