@armadra/agent 0.5.0 → 0.6.0

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"));
+        },
+    };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * 授权流程（docs/wave6-plan.md §4.2、D16；R6 §4.2、§4.3、§1.2 设备码行）。[W6-O]
+ *
+ * 三种拿授权码的方式，产出同一个 `AuthorizationResult`，由各预设的登录模块去换 token：
+ * - `browser`：本地回调服务 + 打开浏览器（打不开就只给 URL）；
+ * - `paste`：只给 URL，用户把浏览器地址栏里的回调 URL 粘回来（SSH / 宿主场景）；
+ * - `device`：设备码（只有 codex 预设），轮询 `/api/accounts/deviceauth/token`，15 分钟上限。
+ *
+ * 给人看的东西经 `onStep` 交给界面层渲染（i18n 在那里）；本模块不打印、不记日志，code 与 verifier
+ * 只出现在返回值里。
+ */
+import type { BrowserOpener } from "./browser.js";
+import { type CallbackPages, type CallbackParams } from "./callback-server.js";
+import { type FetchLike } from "./token-client.js";
+export type LoginStep = {
+    kind: "open_url";
+    url: string;
+    opened: boolean;
+} | {
+    kind: "paste_prompt";
+    url: string;
+} | {
+    kind: "device_code";
+    url: string;
+    userCode: string;
+};
+export interface FlowDeps {
+    fetch: FetchLike;
+    openBrowser: BrowserOpener;
+    onStep(step: LoginStep): void;
+    /** `--paste`：读一行（回调 URL）。 */
+    readLine(): Promise<string>;
+    signal?: AbortSignal | undefined;
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+    now?: (() => number) | undefined;
+    pages?: CallbackPages | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface FlowPreset {
+    issuer: string;
+    clientId: string;
+    redirectPorts: readonly number[];
+    /** 给定回调地址与随机串，产出授权 URL。 */
+    buildAuthorizeUrl(input: {
+        redirectUri: string;
+        state: string;
+        challenge: string;
+        nonce: string;
+    }): string;
+}
+export interface AuthorizationResult extends CallbackParams {
+    redirectUri: string;
+    verifier: string;
+    nonce: string;
+}
+export declare function loginBrowser(preset: FlowPreset, deps: FlowDeps, options?: {
+    noBrowser?: boolean;
+}): Promise<AuthorizationResult>;
+export declare function loginPaste(preset: FlowPreset, deps: FlowDeps): Promise<AuthorizationResult>;
+export declare const DEVICE_MAX_WAIT_MS: number;
+/** 设备码：`{issuer}/api/accounts/deviceauth/usercode` → 用户在 `{issuer}/codex/device` 输入 → 轮询。 */
+export declare function loginDevice(preset: FlowPreset, deps: FlowDeps): Promise<AuthorizationResult>;

package/dist/auth/oauth/flows.js

@@ -0,0 +1,113 @@
+/**
+ * 授权流程（docs/wave6-plan.md §4.2、D16；R6 §4.2、§4.3、§1.2 设备码行）。[W6-O]
+ *
+ * 三种拿授权码的方式，产出同一个 `AuthorizationResult`，由各预设的登录模块去换 token：
+ * - `browser`：本地回调服务 + 打开浏览器（打不开就只给 URL）；
+ * - `paste`：只给 URL，用户把浏览器地址栏里的回调 URL 粘回来（SSH / 宿主场景）；
+ * - `device`：设备码（只有 codex 预设），轮询 `/api/accounts/deviceauth/token`，15 分钟上限。
+ *
+ * 给人看的东西经 `onStep` 交给界面层渲染（i18n 在那里）；本模块不打印、不记日志，code 与 verifier
+ * 只出现在返回值里。
+ */
+import { AmaError } from "../../errors.js";
+import { CALLBACK_HOST, CALLBACK_PATH, parseCallbackUrl, startCallbackServer, } from "./callback-server.js";
+import { generatePkce, randomToken } from "./pkce.js";
+import { OAuthHttpError, postOAuth } from "./token-client.js";
+export async function loginBrowser(preset, deps, options = {}) {
+    const pkce = generatePkce();
+    const state = randomToken();
+    const nonce = randomToken();
+    const server = await startCallbackServer({
+        ports: preset.redirectPorts,
+        state,
+        signal: deps.signal,
+        pages: deps.pages,
+        timeoutMs: deps.timeoutMs,
+    });
+    try {
+        const url = preset.buildAuthorizeUrl({
+            redirectUri: server.redirectUri,
+            state,
+            challenge: pkce.challenge,
+            nonce,
+        });
+        const opened = options.noBrowser === true ? false : await deps.openBrowser(url);
+        deps.onStep({ kind: "open_url", url, opened });
+        const params = await server.result;
+        return { ...params, redirectUri: server.redirectUri, verifier: pkce.verifier, nonce };
+    }
+    finally {
+        await server.close();
+    }
+}
+export async function loginPaste(preset, deps) {
+    const pkce = generatePkce();
+    const state = randomToken();
+    const nonce = randomToken();
+    const port = preset.redirectPorts.find((p) => p > 0) ?? 1455;
+    const redirectUri = `http://${CALLBACK_HOST}:${port}${CALLBACK_PATH}`;
+    const url = preset.buildAuthorizeUrl({ redirectUri, state, challenge: pkce.challenge, nonce });
+    deps.onStep({ kind: "paste_prompt", url });
+    const line = await deps.readLine();
+    if (line.trim() === "")
+        throw new AmaError("aborted", "login aborted");
+    const params = parseCallbackUrl(line, state);
+    return { ...params, redirectUri, verifier: pkce.verifier, nonce };
+}
+export const DEVICE_MAX_WAIT_MS = 15 * 60_000;
+function defaultSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new AmaError("aborted", "login aborted"));
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new AmaError("aborted", "login aborted"));
+        }, { once: true });
+    });
+}
+/** 设备码：`{issuer}/api/accounts/deviceauth/usercode` → 用户在 `{issuer}/codex/device` 输入 → 轮询。 */
+export async function loginDevice(preset, deps) {
+    const api = `${preset.issuer}/api/accounts`;
+    let start;
+    try {
+        start = await postOAuth(deps.fetch, `${api}/deviceauth/usercode`, { client_id: preset.clientId }, { encoding: "json", what: "device code request", signal: deps.signal });
+    }
+    catch (error) {
+        if (error instanceof OAuthHttpError && error.status === 404)
+            throw new AmaError("oauth_device_unavailable", "device code login is not enabled");
+        throw error;
+    }
+    const deviceAuthId = start["device_auth_id"];
+    const userCode = start["user_code"] ?? start["usercode"];
+    if (typeof deviceAuthId !== "string" || typeof userCode !== "string")
+        throw new AmaError("oauth_bad_response", "device code request: unexpected response");
+    const interval = Math.max(1, Number(start["interval"] ?? 5) || 5) * 1000;
+    deps.onStep({ kind: "device_code", url: `${preset.issuer}/codex/device`, userCode });
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => defaultSleep(ms, deps.signal));
+    const began = now();
+    for (;;) {
+        try {
+            const done = await postOAuth(deps.fetch, `${api}/deviceauth/token`, { device_auth_id: deviceAuthId, user_code: userCode }, { encoding: "json", what: "device code poll", signal: deps.signal });
+            const code = done["authorization_code"];
+            const verifier = done["code_verifier"];
+            if (typeof code !== "string" || typeof verifier !== "string")
+                throw new AmaError("oauth_bad_response", "device code poll: unexpected response");
+            return {
+                code,
+                verifier,
+                nonce: "",
+                redirectUri: `${preset.issuer}/deviceauth/callback`,
+            };
+        }
+        catch (error) {
+            const pending = error instanceof OAuthHttpError && (error.status === 403 || error.status === 404);
+            if (!pending)
+                throw error;
+        }
+        if (now() - began >= DEVICE_MAX_WAIT_MS)
+            throw new AmaError("oauth_timeout", "device code login timed out");
+        await sleep(interval);
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * JWT 解码与 JWKS 验签（R6 §4.11：`createPublicKey` + `verify`，零依赖）。[W6-O]
+ *
+ * 支持 RS256 / RS384 / RS512 / PS256 / ES256 / ES384；其它 alg（含 `none`）一律拒绝。
+ * 错误只带原因码，不带 token 原文。
+ */
+import { type JsonWebKey } from "node:crypto";
+export type JwtPayload = Record<string, unknown>;
+export interface DecodedJwt {
+    header: Record<string, unknown>;
+    payload: JwtPayload;
+    signingInput: string;
+    signature: Buffer;
+}
+export declare function decodeJwt(token: string): DecodedJwt;
+/** 只解码 payload；解不开返回 undefined（codex flavor 取声明用，不验签）。 */
+export declare function jwtClaims(token: string | undefined): JwtPayload | undefined;
+export interface Jwk extends JsonWebKey {
+    kid?: string;
+    alg?: string;
+    use?: string;
+}
+/** 按 header 的 alg / kid 在 JWKS 里找钥并验签；不通过抛 `oauth_invalid_token`。 */
+export declare function verifyJwtSignature(decoded: DecodedJwt, keys: readonly Jwk[]): void;