@armadra/agent 0.5.1 → 0.6.1

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;

package/dist/auth/oauth/jwt.js

@@ -0,0 +1,81 @@
+/**
+ * JWT 解码与 JWKS 验签（R6 §4.11：`createPublicKey` + `verify`，零依赖）。[W6-O]
+ *
+ * 支持 RS256 / RS384 / RS512 / PS256 / ES256 / ES384；其它 alg（含 `none`）一律拒绝。
+ * 错误只带原因码，不带 token 原文。
+ */
+import { createPublicKey, verify, constants } from "node:crypto";
+import { AmaError } from "../../errors.js";
+function invalid(reason) {
+    return new AmaError("oauth_invalid_token", `invalid id_token: ${reason}`, { detail: { reason } });
+}
+function json(segment, what) {
+    try {
+        const value = JSON.parse(Buffer.from(segment ?? "", "base64url").toString("utf8"));
+        if (typeof value === "object" && value !== null && !Array.isArray(value))
+            return value;
+    }
+    catch {
+        // 落到下面
+    }
+    throw invalid(`malformed ${what}`);
+}
+export function decodeJwt(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw invalid("malformed");
+    return {
+        header: json(parts[0], "header"),
+        payload: json(parts[1], "payload"),
+        signingInput: `${parts[0]}.${parts[1]}`,
+        signature: Buffer.from(parts[2] ?? "", "base64url"),
+    };
+}
+/** 只解码 payload；解不开返回 undefined（codex flavor 取声明用，不验签）。 */
+export function jwtClaims(token) {
+    if (token === undefined)
+        return undefined;
+    try {
+        return decodeJwt(token).payload;
+    }
+    catch {
+        return undefined;
+    }
+}
+const ALGS = {
+    RS256: { hash: "sha256" },
+    RS384: { hash: "sha384" },
+    RS512: { hash: "sha512" },
+    PS256: { hash: "sha256", pss: true },
+    ES256: { hash: "sha256", ec: true },
+    ES384: { hash: "sha384", ec: true },
+};
+/** 按 header 的 alg / kid 在 JWKS 里找钥并验签；不通过抛 `oauth_invalid_token`。 */
+export function verifyJwtSignature(decoded, keys) {
+    const alg = typeof decoded.header["alg"] === "string" ? decoded.header["alg"] : "";
+    const spec = ALGS[alg];
+    if (spec === undefined)
+        throw invalid(`unsupported alg ${alg.slice(0, 16) || "(none)"}`);
+    const kid = decoded.header["kid"];
+    const candidates = keys.filter((key) => (kid === undefined || key.kid === kid) &&
+        (key.use === undefined || key.use === "sig") &&
+        (key.alg === undefined || key.alg === alg));
+    if (candidates.length === 0)
+        throw invalid("no matching key");
+    for (const jwk of candidates) {
+        try {
+            const key = createPublicKey({ key: jwk, format: "jwk" });
+            const ok = verify(spec.hash, Buffer.from(decoded.signingInput), spec.pss
+                ? { key, padding: constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 }
+                : spec.ec
+                    ? { key, dsaEncoding: "ieee-p1363" }
+                    : key, decoded.signature);
+            if (ok)
+                return;
+        }
+        catch {
+            // 这把钥不合用，试下一把
+        }
+    }
+    throw invalid("bad signature");
+}

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

@@ -0,0 +1,21 @@
+/**
+ * 进程内「活 token」登记（[W6-O]）：`ApiKeyResolver` 解析出 OAuth access token 时登记它的上下文，协议层
+ * （openai-responses 的 ChatGPT 后端）凭手里的 token 取回账户 id、flavor，并在 401 时强制刷新一次。
+ *
+ * 只存在内存里，不落盘、不进日志；最多保留 32 条（新的挤掉旧的）。
+ */
+import type { ChatGptFlavor } from "../../config/types-w6.js";
+export interface LiveToken {
+    provider: string;
+    flavor: ChatGptFlavor;
+    accountId?: string | undefined;
+    planType?: string | undefined;
+    /** 刷新永久失败、等用户重新登录：协议层不发请求，直接报 `auth_expired`。 */
+    needsLogin?: boolean;
+    /** 强制刷新（取锁、重读、必要时调 token 端点）；返回新 token，失败抛 `auth_expired`。 */
+    refresh(): Promise<string>;
+}
+export declare function registerLiveToken(token: string, context: LiveToken): void;
+export declare function liveToken(token: string | undefined): LiveToken | undefined;
+/** 测试用。 */
+export declare function clearLiveTokens(): void;

package/dist/auth/oauth/live.js

@@ -0,0 +1,25 @@
+/**
+ * 进程内「活 token」登记（[W6-O]）：`ApiKeyResolver` 解析出 OAuth access token 时登记它的上下文，协议层
+ * （openai-responses 的 ChatGPT 后端）凭手里的 token 取回账户 id、flavor，并在 401 时强制刷新一次。
+ *
+ * 只存在内存里，不落盘、不进日志；最多保留 32 条（新的挤掉旧的）。
+ */
+const MAX_LIVE = 32;
+const live = new Map();
+export function registerLiveToken(token, context) {
+    live.delete(token);
+    live.set(token, context);
+    while (live.size > MAX_LIVE) {
+        const oldest = live.keys().next().value;
+        if (oldest === undefined)
+            break;
+        live.delete(oldest);
+    }
+}
+export function liveToken(token) {
+    return token === undefined ? undefined : live.get(token);
+}
+/** 测试用。 */
+export function clearLiveTokens() {
+    live.clear();
+}

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

@@ -0,0 +1,26 @@
+/**
+ * OIDC discovery、JWKS 与 id_token 校验（docs/wave6-plan.md §4.1 id_token 行；R6 §1.1）。[W6-O]
+ *
+ * SIWC 必须：JWKS 验签 + `iss` = issuer、`aud` 含签发的 client id、`nonce` = 本次登录的、`exp` 未过
+ * （允许 60 s 时钟偏差）。discovery 与 JWKS 每进程按 issuer 缓存一次。
+ */
+import { type Jwk, type JwtPayload } from "./jwt.js";
+import { type FetchLike } from "./token-client.js";
+export interface OidcDiscovery {
+    issuer?: string;
+    jwksUri?: string;
+    revocationEndpoint?: string;
+}
+export declare function fetchDiscovery(fetchFn: FetchLike, issuer: string): Promise<OidcDiscovery>;
+export declare function fetchJwks(fetchFn: FetchLike, uri: string): Promise<Jwk[]>;
+/** 测试用：清掉 discovery 缓存。 */
+export declare function clearOidcCache(): void;
+export interface IdTokenExpectations {
+    issuer: string;
+    /** 签发的 client id；`aud` 必须含它。 */
+    audience: string;
+    nonce: string;
+    now?: number;
+}
+/** 验签并校验声明；返回 payload。 */
+export declare function validateIdToken(fetchFn: FetchLike, idToken: string, expect: IdTokenExpectations): Promise<JwtPayload>;

package/dist/auth/oauth/oidc.js

@@ -0,0 +1,72 @@
+/**
+ * OIDC discovery、JWKS 与 id_token 校验（docs/wave6-plan.md §4.1 id_token 行；R6 §1.1）。[W6-O]
+ *
+ * SIWC 必须：JWKS 验签 + `iss` = issuer、`aud` 含签发的 client id、`nonce` = 本次登录的、`exp` 未过
+ * （允许 60 s 时钟偏差）。discovery 与 JWKS 每进程按 issuer 缓存一次。
+ */
+import { AmaError } from "../../errors.js";
+import { decodeJwt, verifyJwtSignature } from "./jwt.js";
+import { getJson } from "./token-client.js";
+const discoveryCache = new Map();
+function trimSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+export function fetchDiscovery(fetchFn, issuer) {
+    const key = trimSlash(issuer);
+    let pending = discoveryCache.get(key);
+    if (pending === undefined) {
+        pending = getJson(fetchFn, `${key}/.well-known/openid-configuration`, "OIDC discovery").then((value) => {
+            const str = (k) => typeof value[k] === "string" ? value[k] : undefined;
+            const out = {};
+            const iss = str("issuer");
+            if (iss !== undefined)
+                out.issuer = iss;
+            const jwks = str("jwks_uri");
+            if (jwks !== undefined)
+                out.jwksUri = jwks;
+            const revoke = str("revocation_endpoint");
+            if (revoke !== undefined)
+                out.revocationEndpoint = revoke;
+            return out;
+        });
+        pending.catch(() => discoveryCache.delete(key));
+        discoveryCache.set(key, pending);
+    }
+    return pending;
+}
+export async function fetchJwks(fetchFn, uri) {
+    const value = await getJson(fetchFn, uri, "JWKS");
+    const keys = value["keys"];
+    return Array.isArray(keys)
+        ? keys.filter((k) => typeof k === "object" && k !== null)
+        : [];
+}
+/** 测试用：清掉 discovery 缓存。 */
+export function clearOidcCache() {
+    discoveryCache.clear();
+}
+function reject(reason) {
+    return new AmaError("oauth_invalid_token", `invalid id_token: ${reason}`, { detail: { reason } });
+}
+/** 验签并校验声明；返回 payload。 */
+export async function validateIdToken(fetchFn, idToken, expect) {
+    const decoded = decodeJwt(idToken);
+    const discovery = await fetchDiscovery(fetchFn, expect.issuer);
+    if (discovery.jwksUri === undefined)
+        throw reject("issuer has no jwks_uri");
+    verifyJwtSignature(decoded, await fetchJwks(fetchFn, discovery.jwksUri));
+    const claims = decoded.payload;
+    if (trimSlash(String(claims["iss"] ?? "")) !== trimSlash(expect.issuer))
+        throw reject("iss");
+    const aud = claims["aud"];
+    const audiences = Array.isArray(aud) ? aud : [aud];
+    if (!audiences.includes(expect.audience))
+        throw reject("aud");
+    if (claims["nonce"] !== expect.nonce)
+        throw reject("nonce");
+    const exp = claims["exp"];
+    const now = (expect.now ?? Date.now()) / 1000;
+    if (typeof exp !== "number" || exp + 60 < now)
+        throw reject("exp");
+    return claims;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * PKCE（RFC 7636，S256）与随机串（docs/wave6-plan.md §4.1；R6 §4.3）。[W6-O]
+ *
+ * verifier 32 字节随机数的 base64url（43 字符），challenge = base64url(SHA-256(verifier)) 无填充；
+ * `state` / `nonce` 同样 32 字节随机。只用 `node:crypto`。
+ */
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+    method: "S256";
+}
+export declare function base64url(input: Buffer | Uint8Array): string;
+export declare function randomToken(bytes?: number): string;
+export declare function s256(verifier: string): string;
+export declare function generatePkce(): PkcePair;

package/dist/auth/oauth/pkce.js

@@ -0,0 +1,20 @@
+/**
+ * PKCE（RFC 7636，S256）与随机串（docs/wave6-plan.md §4.1；R6 §4.3）。[W6-O]
+ *
+ * verifier 32 字节随机数的 base64url（43 字符），challenge = base64url(SHA-256(verifier)) 无填充；
+ * `state` / `nonce` 同样 32 字节随机。只用 `node:crypto`。
+ */
+import { createHash, randomBytes } from "node:crypto";
+export function base64url(input) {
+    return Buffer.from(input).toString("base64url");
+}
+export function randomToken(bytes = 32) {
+    return base64url(randomBytes(bytes));
+}
+export function s256(verifier) {
+    return base64url(createHash("sha256").update(verifier, "ascii").digest());
+}
+export function generatePkce() {
+    const verifier = randomToken(32);
+    return { verifier, challenge: s256(verifier), method: "S256" };
+}

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

@@ -0,0 +1,35 @@
+/**
+ * OAuth access token 的取用与刷新（docs/wave6-plan.md §4.3、D15）。[W6-O]
+ *
+ * - 触发：`expiresAt − now < 5 min`，或协议层 401 后 `force`；
+ * - 进程内：同一 (auth.json, 供应商) 共用一个刷新 Promise；
+ * - 跨进程：`withRefreshLock` 取锁后**重读**文件——`refreshToken` 已变（别的进程刷过）且 token 仍新鲜就直接用；
+ *   否则调 token 端点（SIWC 表单 + `resource`；codex JSON），原子写回后释放；
+ * - 永久失败（`refresh_token_expired` / `_reused` / `_invalidated` / `invalid_grant` / `invalid_refresh_token` /
+ *   `token_expired` / `invalid_client` / 401）：条目标 `needsLogin: true`（不删 token），抛 `auth_expired`；
+ *   暂时失败（网络、5xx、429）退避重试 2 次，仍失败抛原错误。
+ */
+import type { ChatGptAuthConfig, OAuthAuthEntry } from "../../config/types-w6.js";
+import { AmaError } from "../../errors.js";
+import { type FetchLike } from "./token-client.js";
+export declare const REFRESH_MARGIN_MS: number;
+export declare const RETRY_DELAYS_MS: readonly [500, 1500];
+export interface RefreshDeps {
+    fetch?: FetchLike | undefined;
+    now?: (() => number) | undefined;
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+    env?: Readonly<Record<string, string | undefined>> | undefined;
+    config?: ChatGptAuthConfig | undefined;
+    /** 锁等待（测试缩短）。 */
+    lockWaitMs?: number | undefined;
+}
+export declare function authExpiredError(provider: string): AmaError;
+export declare function isFresh(entry: OAuthAuthEntry, now: number): boolean;
+/**
+ * 取可用的条目：新鲜就直接返回，否则刷新。`force`：协议层 401 后强制刷新（`staleToken` 是被拒的那个，别的
+ * 进程已换掉它就直接用新的）。条目不存在返回 undefined；`needsLogin` 抛 `auth_expired`。
+ */
+export declare function freshOAuthEntry(authFile: string, provider: string, deps?: RefreshDeps, options?: {
+    force?: boolean;
+    staleToken?: string;
+}): Promise<OAuthAuthEntry | undefined>;

package/dist/auth/oauth/refresh.js

@@ -0,0 +1,129 @@
+/**
+ * OAuth access token 的取用与刷新（docs/wave6-plan.md §4.3、D15）。[W6-O]
+ *
+ * - 触发：`expiresAt − now < 5 min`，或协议层 401 后 `force`；
+ * - 进程内：同一 (auth.json, 供应商) 共用一个刷新 Promise；
+ * - 跨进程：`withRefreshLock` 取锁后**重读**文件——`refreshToken` 已变（别的进程刷过）且 token 仍新鲜就直接用；
+ *   否则调 token 端点（SIWC 表单 + `resource`；codex JSON），原子写回后释放；
+ * - 永久失败（`refresh_token_expired` / `_reused` / `_invalidated` / `invalid_grant` / `invalid_refresh_token` /
+ *   `token_expired` / `invalid_client` / 401）：条目标 `needsLogin: true`（不删 token），抛 `auth_expired`；
+ *   暂时失败（网络、5xx、429）退避重试 2 次，仍失败抛原错误。
+ */
+import { AmaError } from "../../errors.js";
+import { resolveChatGptPreset } from "../chatgpt/presets.js";
+import { OAuthHttpError, parseTokenResponse, postOAuth } from "./token-client.js";
+import { readOAuthEntry, withRefreshLock, writeOAuthEntry } from "./token-store.js";
+export const REFRESH_MARGIN_MS = 5 * 60_000;
+export const RETRY_DELAYS_MS = [500, 1500];
+const PERMANENT = new Set([
+    "refresh_token_expired",
+    "refresh_token_reused",
+    "refresh_token_invalidated",
+    "invalid_grant",
+    "invalid_refresh_token",
+    "token_expired",
+    "invalid_client",
+]);
+export function authExpiredError(provider) {
+    return new AmaError("auth_expired", `auth_expired: ${provider} login expired; run \`ama auth login ${provider}\``, { detail: { provider } });
+}
+export function isFresh(entry, now) {
+    return entry.expiresAt - now > REFRESH_MARGIN_MS;
+}
+const inflight = new Map();
+async function callTokenEndpoint(entry, deps) {
+    const preset = resolveChatGptPreset(entry.flavor, { entry, env: deps.env, config: deps.config });
+    // token 属于签发它的 issuer：条目里记的优先
+    const issuer = (entry.issuer ?? preset.issuer).replace(/\/+$/, "");
+    const tokenUrl = entry.flavor === "siwc" ? `${issuer}/api/accounts/oauth/token` : `${issuer}/oauth/token`;
+    const params = {
+        grant_type: "refresh_token",
+        client_id: entry.clientId ?? preset.clientId,
+        refresh_token: entry.refreshToken,
+    };
+    if (preset.resource !== undefined)
+        params["resource"] = preset.resource;
+    const fetchFn = deps.fetch ?? fetch;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await postOAuth(fetchFn, tokenUrl, params, {
+                encoding: preset.refreshEncoding,
+                what: "token refresh",
+            });
+        }
+        catch (error) {
+            const permanent = error instanceof OAuthHttpError &&
+                (error.status === 401 || (error.error !== undefined && PERMANENT.has(error.error)));
+            if (permanent)
+                throw error;
+            const temporary = !(error instanceof OAuthHttpError) || error.status >= 500 || error.status === 429;
+            const delay = RETRY_DELAYS_MS[attempt];
+            if (!temporary || delay === undefined)
+                throw error;
+            await sleep(delay);
+        }
+    }
+}
+async function refreshLocked(authFile, provider, seen, force, deps) {
+    const now = deps.now ?? Date.now;
+    return withRefreshLock(authFile, async () => {
+        const current = readOAuthEntry(authFile, provider);
+        if (current === undefined)
+            throw authExpiredError(provider);
+        if (current.needsLogin === true)
+            throw authExpiredError(provider);
+        // 别的进程已经刷过：直接用
+        const rotated = current.refreshToken !== seen.refreshToken || current.accessToken !== seen.accessToken;
+        if ((rotated || !force) && isFresh(current, now()))
+            return current;
+        let raw;
+        try {
+            raw = await callTokenEndpoint(current, deps);
+        }
+        catch (error) {
+            if (error instanceof OAuthHttpError &&
+                (error.status === 401 || (error.error !== undefined && PERMANENT.has(error.error)))) {
+                writeOAuthEntry(authFile, provider, { ...current, needsLogin: true });
+                throw authExpiredError(provider);
+            }
+            throw error;
+        }
+        const token = parseTokenResponse(raw, "token refresh");
+        const at = now();
+        const next = {
+            ...current,
+            accessToken: token.accessToken,
+            refreshToken: token.refreshToken ?? current.refreshToken,
+            expiresAt: at + (token.expiresIn ?? 3600) * 1000,
+            lastRefresh: new Date(at).toISOString(),
+        };
+        if (token.idToken !== undefined)
+            next.idToken = token.idToken;
+        delete next.needsLogin;
+        writeOAuthEntry(authFile, provider, next);
+        return next;
+    }, deps.lockWaitMs === undefined ? {} : { waitMs: deps.lockWaitMs });
+}
+/**
+ * 取可用的条目：新鲜就直接返回，否则刷新。`force`：协议层 401 后强制刷新（`staleToken` 是被拒的那个，别的
+ * 进程已换掉它就直接用新的）。条目不存在返回 undefined；`needsLogin` 抛 `auth_expired`。
+ */
+export async function freshOAuthEntry(authFile, provider, deps = {}, options = {}) {
+    const now = deps.now ?? Date.now;
+    const entry = readOAuthEntry(authFile, provider);
+    if (entry === undefined)
+        return undefined;
+    if (entry.needsLogin === true)
+        throw authExpiredError(provider);
+    const force = options.force === true && entry.accessToken === (options.staleToken ?? entry.accessToken);
+    if (!force && isFresh(entry, now()))
+        return entry;
+    const key = `${authFile}\0${provider}`;
+    let pending = inflight.get(key);
+    if (pending === undefined) {
+        pending = refreshLocked(authFile, provider, entry, force, deps).finally(() => inflight.delete(key));
+        inflight.set(key, pending);
+    }
+    return pending;
+}

package/dist/auth/oauth/token-client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * OAuth 端点的 HTTP 调用（token 交换 / 刷新 / 撤销 / discovery）。[W6-O]
+ *
+ * 日志红线（docs/wave6-plan.md §4.3）：错误只带 HTTP 状态与 `error` 码（截断到 64 字符），从不带响应
+ * 原文、请求参数、code 或任何 token。
+ */
+import { AmaError } from "../../errors.js";
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export declare const OAUTH_TIMEOUT_MS = 30000;
+export interface TokenResponse {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    /** 秒。 */
+    expiresIn?: number;
+    scope?: string;
+    clientId?: string;
+}
+/** OAuth 端点返回非 2xx：`status` 与 `error` 码（不含描述原文）。 */
+export declare class OAuthHttpError extends AmaError {
+    readonly status: number;
+    readonly error: string | undefined;
+    constructor(status: number, error: string | undefined, what: string);
+}
+/** 响应体里的错误码：`error`（字符串或 `{code|type}`）、`code`、`error_code`。 */
+export declare function oauthErrorCode(body: string): string | undefined;
+export declare function postOAuth(fetchFn: FetchLike, url: string, params: Record<string, string>, options: {
+    encoding: "form" | "json";
+    what: string;
+    signal?: AbortSignal | undefined;
+}): Promise<Record<string, unknown>>;
+export declare function parseTokenResponse(value: Record<string, unknown>, what: string): TokenResponse;
+export declare function getJson(fetchFn: FetchLike, url: string, what: string, signal?: AbortSignal): Promise<Record<string, unknown>>;