@armadra/agent 0.5.1 → 0.6.1

package/dist/auth/chatgpt/host-id.js

@@ -0,0 +1,26 @@
+/**
+ * SIWC 的 `ext_agent_host_id`（docs/wave6-plan.md D16）：每个安装稳定不变，存
+ * `<dataDir>/chatgpt-host.json`（0600，按安装、不随 dotfiles 同步），形如 `urn:uuid:…`。[W6-O]
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const HOST_ID_FILE = "chatgpt-host.json";
+export function hostIdPath(dataDir) {
+    return join(dataDir, HOST_ID_FILE);
+}
+export function readOrCreateHostId(dataDir) {
+    const path = hostIdPath(dataDir);
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof value.hostId === "string" && /^urn:uuid:[0-9a-f-]{36}$/i.test(value.hostId))
+            return value.hostId;
+    }
+    catch {
+        // 不存在或损坏：重建
+    }
+    const hostId = `urn:uuid:${randomUUID()}`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify({ version: 1, hostId }, null, 2)}\n`, { mode: 0o600 });
+    return hostId;
+}

package/dist/auth/chatgpt/login.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ChatGPT 登录 / 登出编排（docs/wave6-plan.md §4.1–§4.3、D13–D16）。[W6-O]
+ *
+ * 登录：预设 → 授权码（browser / paste / device）→ 换 token（表单编码；SIWC 带 `resource`，client id 用
+ * 回调带回的签发 id）→ 校验（SIWC：JWKS 验签 iss / aud / nonce / exp + 授予 scope 含
+ * `chatgpt.tokens.use.direct`；codex：只解码取账户）→ `OAuthAuthEntry`。写文件由调用方经 token-store 做。
+ *
+ * 登出：SIWC 调 discovery 里的 `revocation_endpoint`（`token=<refresh>`、`token_type_hint=refresh_token`、
+ * `client_id`），失败不阻止删除本地条目；codex 只删本地。
+ */
+import type { ChatGptFlavor, OAuthAuthEntry } from "../../config/types-w6.js";
+import { type AuthorizationResult, type FlowDeps } from "../oauth/flows.js";
+import { type FetchLike } from "../oauth/token-client.js";
+import { type ChatGptPreset, type PresetOverrides } from "./presets.js";
+export type LoginMethod = "browser" | "paste" | "device";
+export interface ChatGptLoginOptions extends PresetOverrides {
+    flavor: ChatGptFlavor;
+    method: LoginMethod;
+    noBrowser?: boolean;
+    /** SIWC 的 `ext_agent_host_id` 存放目录（`<dataDir>`）。 */
+    dataDir: string;
+    /** codex 的一次性确认时刻（ISO）；调用方负责问。 */
+    acknowledgedAt?: string | undefined;
+    deps: FlowDeps;
+}
+export declare const DEFAULT_ACCESS_TTL_S = 3600;
+export declare function exchangeCode(fetchFn: FetchLike, preset: ChatGptPreset, auth: AuthorizationResult, signal?: AbortSignal): Promise<OAuthAuthEntry>;
+export declare function loginChatGpt(options: ChatGptLoginOptions): Promise<OAuthAuthEntry>;
+/** SIWC 登出：撤销 refresh token。返回是否确认撤销（失败 / 不支持为 false，不抛）。 */
+export declare function revokeChatGpt(fetchFn: FetchLike, entry: OAuthAuthEntry, overrides?: PresetOverrides): Promise<boolean>;

package/dist/auth/chatgpt/login.js

@@ -0,0 +1,130 @@
+/**
+ * ChatGPT 登录 / 登出编排（docs/wave6-plan.md §4.1–§4.3、D13–D16）。[W6-O]
+ *
+ * 登录：预设 → 授权码（browser / paste / device）→ 换 token（表单编码；SIWC 带 `resource`，client id 用
+ * 回调带回的签发 id）→ 校验（SIWC：JWKS 验签 iss / aud / nonce / exp + 授予 scope 含
+ * `chatgpt.tokens.use.direct`；codex：只解码取账户）→ `OAuthAuthEntry`。写文件由调用方经 token-store 做。
+ *
+ * 登出：SIWC 调 discovery 里的 `revocation_endpoint`（`token=<refresh>`、`token_type_hint=refresh_token`、
+ * `client_id`），失败不阻止删除本地条目；codex 只删本地。
+ */
+import { AmaError } from "../../errors.js";
+import { loginBrowser, loginDevice, loginPaste, } from "../oauth/flows.js";
+import { jwtClaims } from "../oauth/jwt.js";
+import { fetchDiscovery, validateIdToken } from "../oauth/oidc.js";
+import { parseTokenResponse, postOAuth } from "../oauth/token-client.js";
+import { chatgptAccount, hasScope } from "./claims.js";
+import { readOrCreateHostId } from "./host-id.js";
+import { SIWC_REGISTRATION_CLIENT_ID, authorizeUrl, resolveChatGptPreset, } from "./presets.js";
+export const DEFAULT_ACCESS_TTL_S = 3600;
+function flowPreset(preset, hostId) {
+    return {
+        issuer: preset.issuer,
+        clientId: preset.clientId,
+        redirectPorts: preset.redirectPorts,
+        buildAuthorizeUrl: (input) => authorizeUrl(preset, { ...input, hostId }),
+    };
+}
+function issuedClientId(preset, auth, tokenClientId, idToken) {
+    if (!preset.registering)
+        return preset.clientId;
+    const fromAud = () => {
+        const aud = jwtClaims(idToken)?.["aud"];
+        const list = Array.isArray(aud) ? aud : [aud];
+        return list.find((a) => typeof a === "string" && a !== SIWC_REGISTRATION_CLIENT_ID);
+    };
+    const issued = auth.clientId ?? tokenClientId ?? fromAud();
+    if (issued === undefined || issued === SIWC_REGISTRATION_CLIENT_ID)
+        throw new AmaError("oauth_no_client_id", "dynamic registration returned no client id");
+    return issued;
+}
+export async function exchangeCode(fetchFn, preset, auth, signal) {
+    // 新注册：交换要用签发的 id（回调带回）；回调没带时先用注册入口换，再从 id_token 的 aud 取
+    const exchangeClient = preset.registering ? (auth.clientId ?? preset.clientId) : preset.clientId;
+    const params = {
+        grant_type: "authorization_code",
+        code: auth.code,
+        redirect_uri: auth.redirectUri,
+        client_id: exchangeClient,
+        code_verifier: auth.verifier,
+    };
+    if (preset.resource !== undefined)
+        params["resource"] = preset.resource;
+    const token = parseTokenResponse(await postOAuth(fetchFn, preset.tokenUrl, params, {
+        encoding: "form",
+        what: "token exchange",
+        signal,
+    }), "token exchange");
+    if (token.refreshToken === undefined)
+        throw new AmaError("oauth_bad_response", "token exchange: no refresh_token");
+    const clientId = issuedClientId(preset, auth, token.clientId, token.idToken);
+    let claims = jwtClaims(token.idToken);
+    if (preset.verifyIdToken) {
+        if (token.idToken === undefined)
+            throw new AmaError("oauth_invalid_token", "invalid id_token: missing");
+        claims = await validateIdToken(fetchFn, token.idToken, {
+            issuer: preset.issuer,
+            audience: clientId,
+            nonce: auth.nonce,
+        });
+        const scope = auth.scope ?? token.scope;
+        if (preset.requiredScope !== undefined && !hasScope(scope, preset.requiredScope))
+            throw new AmaError("oauth_scope_missing", `granted scope lacks ${preset.requiredScope}`, {
+                detail: { scope: preset.requiredScope },
+            });
+    }
+    const account = chatgptAccount(claims, preset.flavor);
+    if (preset.flavor === "codex" && account.accountId === undefined)
+        throw new AmaError("oauth_no_account", "id_token has no ChatGPT account id");
+    const now = Date.now();
+    const entry = {
+        type: "oauth",
+        flavor: preset.flavor,
+        clientId,
+        issuer: preset.issuer,
+        ...account,
+        accessToken: token.accessToken,
+        refreshToken: token.refreshToken,
+        ...(token.idToken !== undefined ? { idToken: token.idToken } : {}),
+        expiresAt: now + (token.expiresIn ?? DEFAULT_ACCESS_TTL_S) * 1000,
+        lastRefresh: new Date(now).toISOString(),
+    };
+    return entry;
+}
+export async function loginChatGpt(options) {
+    const preset = resolveChatGptPreset(options.flavor, options);
+    if (options.method === "device" && !preset.device)
+        throw new AmaError("oauth_device_unsupported", "device code login needs --flavor codex");
+    const hostId = preset.flavor === "siwc" ? readOrCreateHostId(options.dataDir) : undefined;
+    const flow = flowPreset(preset, hostId);
+    const auth = options.method === "device"
+        ? await loginDevice(flow, options.deps)
+        : options.method === "paste"
+            ? await loginPaste(flow, options.deps)
+            : await loginBrowser(flow, options.deps, { noBrowser: options.noBrowser === true });
+    const entry = await exchangeCode(options.deps.fetch, preset, auth, options.deps.signal);
+    if (options.acknowledgedAt !== undefined)
+        entry.acknowledgedAt = options.acknowledgedAt;
+    return entry;
+}
+/** SIWC 登出：撤销 refresh token。返回是否确认撤销（失败 / 不支持为 false，不抛）。 */
+export async function revokeChatGpt(fetchFn, entry, overrides = {}) {
+    const preset = resolveChatGptPreset(entry.flavor, { ...overrides, entry });
+    if (!preset.revoke)
+        return false;
+    const issuer = entry.issuer ?? preset.issuer;
+    try {
+        const discovery = await fetchDiscovery(fetchFn, issuer);
+        if (discovery.revocationEndpoint === undefined)
+            return false;
+        await postOAuth(fetchFn, discovery.revocationEndpoint, {
+            token: entry.refreshToken,
+            token_type_hint: "refresh_token",
+            client_id: entry.clientId ?? preset.clientId,
+        }, { encoding: "form", what: "token revocation" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/auth/chatgpt/presets.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ChatGPT 登录预设表（docs/wave6-plan.md §4.1、D13–D16；R6 §1.1、§1.2、§4.10）。[W6-O]
+ *
+ * 两条路径共用 PKCE / 回调 / 存储 / 锁 / 配额框架，差异全部在这张表里：
+ * - `siwc`（缺省，官方动态注册）：`/api/accounts/*`，首次 `client_id=dynamic_agent_client`，回调带回签发的
+ *   id 后存进条目；表单编码、带 `resource`；id_token 必须 JWKS 验签；推理走 `api.openai.com/v1`；
+ * - `codex`（显式开启的备用）：Codex CLI 的公开客户端，`/oauth/*`，刷新 JSON 编码；id_token 只解码；
+ *   推理走 `chatgpt.com/backend-api/codex`，另发 `ChatGPT-Account-ID` 与 `originator`。
+ *
+ * 覆盖：`AMA_CHATGPT_CLIENT_ID` / `AMA_CHATGPT_ISSUER`（测试用）/ `AMA_CHATGPT_BASE_URL` > 配置
+ * `auth.chatgpt.*` > 条目里签发的 client id > 缺省。
+ */
+import type { ChatGptAuthConfig, ChatGptFlavor, OAuthAuthEntry } from "../../config/types-w6.js";
+export declare const CHATGPT_PROVIDER_ID = "chatgpt";
+export declare const DEFAULT_ISSUER = "https://auth.openai.com";
+export declare const SIWC_REGISTRATION_CLIENT_ID = "dynamic_agent_client";
+export declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export declare const SIWC_RESOURCE = "https://api.openai.com/v1";
+export declare const SIWC_REQUIRED_SCOPE = "chatgpt.tokens.use.direct";
+export declare const AGENT_NAME_HINT = "ama";
+export declare const DEFAULT_ORIGINATOR = "codex_cli_rs";
+export declare const CHATGPT_BASE_URLS: Readonly<Record<ChatGptFlavor, string>>;
+export interface AuthorizeInput {
+    redirectUri: string;
+    state: string;
+    challenge: string;
+    nonce: string;
+    /** SIWC：`<dataDir>/chatgpt-host.json` 的安装 id。 */
+    hostId?: string | undefined;
+}
+export interface ChatGptPreset {
+    flavor: ChatGptFlavor;
+    issuer: string;
+    clientId: string;
+    /** SIWC 还没有签发 id（用注册入口登录）。 */
+    registering: boolean;
+    authorizeUrl: string;
+    tokenUrl: string;
+    scopes: readonly string[];
+    redirectPorts: readonly number[];
+    /** SIWC 的 `resource`（交换与刷新都带）。 */
+    resource?: string;
+    refreshEncoding: "form" | "json";
+    /** 推理端点（渠道 baseUrl）。 */
+    baseUrl: string;
+    /** SIWC：id_token 必须 JWKS 验签，且授予 scope 含 `chatgpt.tokens.use.direct`。 */
+    verifyIdToken: boolean;
+    requiredScope?: string;
+    /** 设备码（只有 codex）。 */
+    device: boolean;
+    /** 登出调 revocation_endpoint（只有 SIWC）。 */
+    revoke: boolean;
+    originator?: string;
+}
+export interface PresetOverrides {
+    config?: ChatGptAuthConfig | undefined;
+    env?: Readonly<Record<string, string | undefined>> | undefined;
+    /** 已有条目：SIWC 复用签发的 client id。 */
+    entry?: OAuthAuthEntry | undefined;
+    /** `--port N`。 */
+    port?: number | undefined;
+}
+export declare function chatgptBaseUrl(flavor: ChatGptFlavor, env?: Readonly<Record<string, string | undefined>>): string;
+export declare function resolveChatGptPreset(flavor: ChatGptFlavor, overrides?: PresetOverrides): ChatGptPreset;
+/** 授权 URL（参数顺序固定，便于测试）。 */
+export declare function authorizeUrl(preset: ChatGptPreset, input: AuthorizeInput): string;

package/dist/auth/chatgpt/presets.js

@@ -0,0 +1,120 @@
+/**
+ * ChatGPT 登录预设表（docs/wave6-plan.md §4.1、D13–D16；R6 §1.1、§1.2、§4.10）。[W6-O]
+ *
+ * 两条路径共用 PKCE / 回调 / 存储 / 锁 / 配额框架，差异全部在这张表里：
+ * - `siwc`（缺省，官方动态注册）：`/api/accounts/*`，首次 `client_id=dynamic_agent_client`，回调带回签发的
+ *   id 后存进条目；表单编码、带 `resource`；id_token 必须 JWKS 验签；推理走 `api.openai.com/v1`；
+ * - `codex`（显式开启的备用）：Codex CLI 的公开客户端，`/oauth/*`，刷新 JSON 编码；id_token 只解码；
+ *   推理走 `chatgpt.com/backend-api/codex`，另发 `ChatGPT-Account-ID` 与 `originator`。
+ *
+ * 覆盖：`AMA_CHATGPT_CLIENT_ID` / `AMA_CHATGPT_ISSUER`（测试用）/ `AMA_CHATGPT_BASE_URL` > 配置
+ * `auth.chatgpt.*` > 条目里签发的 client id > 缺省。
+ */
+export const CHATGPT_PROVIDER_ID = "chatgpt";
+export const DEFAULT_ISSUER = "https://auth.openai.com";
+export const SIWC_REGISTRATION_CLIENT_ID = "dynamic_agent_client";
+export const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export const SIWC_RESOURCE = "https://api.openai.com/v1";
+export const SIWC_REQUIRED_SCOPE = "chatgpt.tokens.use.direct";
+export const AGENT_NAME_HINT = "ama";
+export const DEFAULT_ORIGINATOR = "codex_cli_rs";
+export const CHATGPT_BASE_URLS = {
+    siwc: "https://api.openai.com/v1",
+    codex: "https://chatgpt.com/backend-api/codex",
+};
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+export function chatgptBaseUrl(flavor, env = process.env) {
+    return nonEmpty(env["AMA_CHATGPT_BASE_URL"]) ?? CHATGPT_BASE_URLS[flavor];
+}
+export function resolveChatGptPreset(flavor, overrides = {}) {
+    const env = overrides.env ?? process.env;
+    const config = overrides.config;
+    const issuer = (nonEmpty(env["AMA_CHATGPT_ISSUER"]) ??
+        nonEmpty(config?.issuer) ??
+        DEFAULT_ISSUER).replace(/\/+$/, "");
+    const sameFlavor = overrides.entry?.flavor === flavor ? overrides.entry : undefined;
+    const explicitClient = nonEmpty(env["AMA_CHATGPT_CLIENT_ID"]) ?? nonEmpty(config?.clientId);
+    const ports = overrides.port !== undefined
+        ? [overrides.port]
+        : config?.redirectPorts !== undefined && config.redirectPorts.length > 0
+            ? [...config.redirectPorts]
+            : undefined;
+    if (flavor === "siwc") {
+        const issued = sameFlavor?.clientId !== SIWC_REGISTRATION_CLIENT_ID ? sameFlavor?.clientId : undefined;
+        const clientId = explicitClient ?? issued ?? SIWC_REGISTRATION_CLIENT_ID;
+        return {
+            flavor,
+            issuer,
+            clientId,
+            registering: clientId === SIWC_REGISTRATION_CLIENT_ID,
+            authorizeUrl: `${issuer}/api/accounts/authorize`,
+            tokenUrl: `${issuer}/api/accounts/oauth/token`,
+            scopes: [
+                "openid",
+                "profile",
+                "email",
+                "offline_access",
+                "resource.invoke",
+                SIWC_REQUIRED_SCOPE,
+            ],
+            // 端口可变（scheme / host / path 不变）：1455 被占用就用任意空闲端口
+            redirectPorts: ports ?? [1455, 0],
+            resource: SIWC_RESOURCE,
+            refreshEncoding: "form",
+            baseUrl: chatgptBaseUrl(flavor, env),
+            verifyIdToken: true,
+            requiredScope: SIWC_REQUIRED_SCOPE,
+            device: false,
+            revoke: true,
+        };
+    }
+    return {
+        flavor,
+        issuer,
+        clientId: explicitClient ?? CODEX_CLIENT_ID,
+        registering: false,
+        authorizeUrl: `${issuer}/oauth/authorize`,
+        tokenUrl: `${issuer}/oauth/token`,
+        scopes: ["openid", "profile", "email", "offline_access"],
+        // 公开客户端只登记了这两个端口；被占用不抢占
+        redirectPorts: ports ?? [1455, 1457],
+        refreshEncoding: "json",
+        baseUrl: chatgptBaseUrl(flavor, env),
+        verifyIdToken: false,
+        device: true,
+        revoke: false,
+        originator: nonEmpty(config?.originator) ?? DEFAULT_ORIGINATOR,
+    };
+}
+/** 授权 URL（参数顺序固定，便于测试）。 */
+export function authorizeUrl(preset, input) {
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: preset.clientId,
+        redirect_uri: input.redirectUri,
+        scope: preset.scopes.join(" "),
+        code_challenge: input.challenge,
+        code_challenge_method: "S256",
+        state: input.state,
+    });
+    if (preset.flavor === "siwc") {
+        params.set("nonce", input.nonce);
+        if (preset.resource !== undefined)
+            params.set("resource", preset.resource);
+        if (input.hostId !== undefined)
+            params.set("ext_agent_host_id", input.hostId);
+        // 只在首次动态注册时带
+        if (preset.registering)
+            params.set("agent_name_hint", AGENT_NAME_HINT);
+    }
+    else {
+        params.set("id_token_add_organizations", "true");
+        params.set("codex_cli_simplified_flow", "true");
+        if (preset.originator !== undefined)
+            params.set("originator", preset.originator);
+    }
+    return `${preset.authorizeUrl}?${params.toString()}`;
+}

package/dist/auth/chatgpt/quota-text.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 配额的人读文本（`ama auth status`、`/session`、doctor 共用）。[W6-O]
+ *
+ * `5 小时 42%（14:20 重置）· 周 18%（10-09 08:00 重置）`；重置时间按本地时区，24 小时内只给时分。
+ */
+import type { QuotaWindow } from "../../agent/types-w6.js";
+export interface QuotaLike {
+    primary?: QuotaWindow | undefined;
+    secondary?: QuotaWindow | undefined;
+}
+export declare function resetClock(at: number, now?: number): string;
+/** 没有任何窗口时 undefined。 */
+export declare function quotaParts(quota: QuotaLike, now?: number): string | undefined;

package/dist/auth/chatgpt/quota-text.js

@@ -0,0 +1,36 @@
+/**
+ * 配额的人读文本（`ama auth status`、`/session`、doctor 共用）。[W6-O]
+ *
+ * `5 小时 42%（14:20 重置）· 周 18%（10-09 08:00 重置）`；重置时间按本地时区，24 小时内只给时分。
+ */
+import { formatDuration, msg } from "../../i18n/index.js";
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+export function resetClock(at, now = Date.now()) {
+    const d = new Date(at);
+    const time = `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+    return at - now < 24 * 3_600_000 ? time : `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${time}`;
+}
+function windowName(minutes, fallback) {
+    const m = msg().auth.status;
+    if (minutes === 300)
+        return m.window5h;
+    if (minutes === 10_080)
+        return m.windowWeek;
+    if (minutes !== undefined)
+        return m.windowOther(formatDuration(minutes * 60_000));
+    return fallback === "primary" ? m.window5h : m.windowWeek;
+}
+/** 没有任何窗口时 undefined。 */
+export function quotaParts(quota, now = Date.now()) {
+    const m = msg().auth.status;
+    const parts = [];
+    for (const which of ["primary", "secondary"]) {
+        const w = quota[which];
+        if (w === undefined)
+            continue;
+        parts.push(m.quotaWindow(windowName(w.windowMinutes, which), Math.round(w.usedPercent), w.resetsAt === undefined ? undefined : resetClock(w.resetsAt, now)));
+    }
+    return parts.length === 0 ? undefined : parts.join(" · ");
+}

package/dist/auth/oauth/browser.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 打开系统浏览器（R6 §4.11）。[W6-O]
+ *
+ * macOS `open`、Windows `cmd /c start ""`、其余 `xdg-open`；URL 作为 argv 传入，不拼 shell 字符串。
+ * 打不开（命令不存在、非零退出）返回 false，调用方改为只打印 URL。
+ */
+export type BrowserOpener = (url: string) => Promise<boolean>;
+export declare function browserCommand(url: string, platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+export declare const openBrowser: BrowserOpener;

package/dist/auth/oauth/browser.js

@@ -0,0 +1,27 @@
+/**
+ * 打开系统浏览器（R6 §4.11）。[W6-O]
+ *
+ * macOS `open`、Windows `cmd /c start ""`、其余 `xdg-open`；URL 作为 argv 传入，不拼 shell 字符串。
+ * 打不开（命令不存在、非零退出）返回 false，调用方改为只打印 URL。
+ */
+import { spawn } from "node:child_process";
+export function browserCommand(url, platform = process.platform) {
+    if (platform === "darwin")
+        return { command: "open", args: [url] };
+    // `start` 的第一个带引号参数是窗口标题；URL 里的 & 需要 cmd 转义
+    if (platform === "win32")
+        return { command: "cmd", args: ["/c", "start", '""', url.replace(/&/g, "^&")] };
+    return { command: "xdg-open", args: [url] };
+}
+export const openBrowser = (url) => new Promise((resolve) => {
+    const { command, args } = browserCommand(url);
+    try {
+        const child = spawn(command, args, { stdio: "ignore", detached: true, windowsHide: true });
+        child.once("error", () => resolve(false));
+        child.once("exit", (code) => resolve(code === 0 || code === null));
+        child.unref();
+    }
+    catch {
+        resolve(false);
+    }
+});

package/dist/auth/oauth/callback-server.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 本地 OAuth 回调服务（docs/wave6-plan.md §4.1 回调行；R6 §4.3）。[W6-O]
+ *
+ * - 只监听 `127.0.0.1`；端口按 `ports` 依次尝试（0 = 任意空闲端口），被占用就试下一个；全被占用报
+ *   `oauth_ports_busy`（**不**像别的客户端那样发 `/cancel` 抢占他人的监听）；
+ * - 只认 `GET <path>`：`state` 不符 → `oauth_state_mismatch`；带 `error` → `oauth_denied`（只带 error 码，
+ *   不带描述原文）；成功返回静态页，**页面不回显 code**；
+ * - 超时（缺省 5 分钟）→ `oauth_timeout`；signal 中止 → `aborted`。结束后自动关闭监听。
+ *
+ * `parseCallbackUrl` 给 `--paste` 用：校验粘回来的回调 URL 的 state 并取出 code。
+ * SIWC 首次动态注册时回调还带签发的 `client_id` 与授予的 `scope`（空格分隔），一并交出。
+ */
+export declare const CALLBACK_PATH = "/auth/callback";
+export declare const CALLBACK_HOST = "127.0.0.1";
+export declare const DEFAULT_LOGIN_TIMEOUT_MS: number;
+export interface CallbackPages {
+    success: string;
+    failure: string;
+}
+export interface CallbackServerOptions {
+    ports: readonly number[];
+    state: string;
+    path?: string | undefined;
+    timeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+    pages?: CallbackPages | undefined;
+}
+/** 回调里的有用参数（不含 state）。 */
+export interface CallbackParams {
+    code: string;
+    /** SIWC 动态注册签发的 client id。 */
+    clientId?: string;
+    /** 授予的 scope（空格分隔）。 */
+    scope?: string;
+}
+export interface CallbackServer {
+    port: number;
+    redirectUri: string;
+    /** 收到合法回调后 resolve；失败 reject AmaError。 */
+    result: Promise<CallbackParams>;
+    close(): Promise<void>;
+}
+/** 回调参数 → code；state 不符 / 带 error / 缺 code 抛 AmaError（不含 code 原文）。 */
+export declare function codeFromParams(params: URLSearchParams, state: string): CallbackParams;
+/** `--paste`：粘回来的整条回调 URL（或只有查询串）。 */
+export declare function parseCallbackUrl(input: string, state: string): CallbackParams;
+export declare function startCallbackServer(options: CallbackServerOptions): Promise<CallbackServer>;

package/dist/auth/oauth/callback-server.js

@@ -0,0 +1,147 @@
+/**
+ * 本地 OAuth 回调服务（docs/wave6-plan.md §4.1 回调行；R6 §4.3）。[W6-O]
+ *
+ * - 只监听 `127.0.0.1`；端口按 `ports` 依次尝试（0 = 任意空闲端口），被占用就试下一个；全被占用报
+ *   `oauth_ports_busy`（**不**像别的客户端那样发 `/cancel` 抢占他人的监听）；
+ * - 只认 `GET <path>`：`state` 不符 → `oauth_state_mismatch`；带 `error` → `oauth_denied`（只带 error 码，
+ *   不带描述原文）；成功返回静态页，**页面不回显 code**；
+ * - 超时（缺省 5 分钟）→ `oauth_timeout`；signal 中止 → `aborted`。结束后自动关闭监听。
+ *
+ * `parseCallbackUrl` 给 `--paste` 用：校验粘回来的回调 URL 的 state 并取出 code。
+ * SIWC 首次动态注册时回调还带签发的 `client_id` 与授予的 `scope`（空格分隔），一并交出。
+ */
+import { createServer } from "node:http";
+import { AmaError } from "../../errors.js";
+export const CALLBACK_PATH = "/auth/callback";
+export const CALLBACK_HOST = "127.0.0.1";
+export const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_PAGES = {
+    success: "Signed in. You can close this page and return to the terminal.",
+    failure: "Sign-in failed. Return to the terminal for details.",
+};
+function page(text) {
+    const escaped = text.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
+    return `<!doctype html><meta charset="utf-8"><title>ama</title><body style="font-family:sans-serif;padding:3em"><p>${escaped}</p></body>`;
+}
+/** 回调参数 → code；state 不符 / 带 error / 缺 code 抛 AmaError（不含 code 原文）。 */
+export function codeFromParams(params, state) {
+    const error = params.get("error");
+    if (error !== null) {
+        throw new AmaError("oauth_denied", `authorization failed: ${error.slice(0, 64)}`, {
+            detail: { error: error.slice(0, 64) },
+        });
+    }
+    if (params.get("state") !== state) {
+        throw new AmaError("oauth_state_mismatch", "OAuth state mismatch");
+    }
+    const code = params.get("code");
+    if (code === null || code === "")
+        throw new AmaError("oauth_no_code", "callback has no code");
+    const out = { code };
+    const clientId = params.get("client_id");
+    if (clientId)
+        out.clientId = clientId;
+    const scope = params.get("scope");
+    if (scope)
+        out.scope = scope;
+    return out;
+}
+/** `--paste`：粘回来的整条回调 URL（或只有查询串）。 */
+export function parseCallbackUrl(input, state) {
+    const text = input.trim();
+    let params;
+    try {
+        params = new URL(text).searchParams;
+    }
+    catch {
+        params = new URLSearchParams(text.startsWith("?") ? text.slice(1) : text);
+    }
+    return codeFromParams(params, state);
+}
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            const address = server.address();
+            resolve(typeof address === "object" && address !== null ? address.port : port);
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, CALLBACK_HOST);
+    });
+}
+export async function startCallbackServer(options) {
+    const path = options.path ?? CALLBACK_PATH;
+    const pages = options.pages ?? DEFAULT_PAGES;
+    let settle;
+    const result = new Promise((resolve, reject) => {
+        settle = { resolve, reject };
+    });
+    // 调用方可能只在失败时才 await
+    result.catch(() => { });
+    let done = false;
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", `http://${CALLBACK_HOST}`);
+        if (req.method !== "GET" || url.pathname !== path || done) {
+            res.writeHead(404, { "content-type": "text/plain" }).end("not found");
+            return;
+        }
+        try {
+            const params = codeFromParams(url.searchParams, options.state);
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page(pages.success));
+            finish(undefined, params);
+        }
+        catch (error) {
+            res.writeHead(400, { "content-type": "text/html; charset=utf-8" }).end(page(pages.failure));
+            // state 不符可能是别人的请求：只有 error 回调才结束等待
+            if (error.code !== "oauth_state_mismatch")
+                finish(error);
+        }
+    });
+    let port;
+    for (const candidate of options.ports) {
+        try {
+            port = await listen(server, candidate);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EADDRINUSE")
+                throw error;
+        }
+    }
+    if (port === undefined) {
+        throw new AmaError("oauth_ports_busy", `callback ports busy: ${options.ports.join(", ")}`, {
+            detail: { ports: [...options.ports] },
+        });
+    }
+    const timer = setTimeout(() => finish(new AmaError("oauth_timeout", "login timed out")), options.timeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS);
+    const onAbort = () => finish(new AmaError("aborted", "login aborted"));
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    function finish(error, params) {
+        if (done)
+            return;
+        done = true;
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        server.close();
+        server.closeAllConnections?.();
+        if (params !== undefined)
+            settle?.resolve(params);
+        else
+            settle?.reject(error);
+    }
+    if (options.signal?.aborted)
+        onAbort();
+    return {
+        port,
+        redirectUri: `http://${CALLBACK_HOST}:${port}${path}`,
+        result,
+        close: async () => {
+            finish(new AmaError("aborted", "login aborted"));
+        },
+    };
+}