@armadra/agent 0.5.0 → 0.6.0

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>>;

package/dist/auth/oauth/token-client.js

@@ -0,0 +1,121 @@
+/**
+ * OAuth 端点的 HTTP 调用（token 交换 / 刷新 / 撤销 / discovery）。[W6-O]
+ *
+ * 日志红线（docs/wave6-plan.md §4.3）：错误只带 HTTP 状态与 `error` 码（截断到 64 字符），从不带响应
+ * 原文、请求参数、code 或任何 token。
+ */
+import { AmaError } from "../../errors.js";
+export const OAUTH_TIMEOUT_MS = 30_000;
+/** OAuth 端点返回非 2xx：`status` 与 `error` 码（不含描述原文）。 */
+export class OAuthHttpError extends AmaError {
+    status;
+    error;
+    constructor(status, error, what) {
+        super("oauth_http", `${what} failed: HTTP ${status}${error ? ` ${error}` : ""}`, {
+            detail: { status, error },
+        });
+        this.status = status;
+        this.error = error;
+    }
+}
+/** 响应体里的错误码：`error`（字符串或 `{code|type}`）、`code`、`error_code`。 */
+export function oauthErrorCode(body) {
+    try {
+        const value = JSON.parse(body);
+        const error = value["error"];
+        const nested = typeof error === "object" && error !== null
+            ? (error["code"] ?? error["type"])
+            : error;
+        const code = nested ?? value["code"] ?? value["error_code"];
+        return typeof code === "string" && code !== "" ? code.slice(0, 64) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function signalOf(signal) {
+    const timeout = AbortSignal.timeout(OAUTH_TIMEOUT_MS);
+    return signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+}
+export async function postOAuth(fetchFn, url, params, options) {
+    let response;
+    try {
+        response = await fetchFn(url, {
+            method: "POST",
+            headers: options.encoding === "form"
+                ? { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }
+                : { "content-type": "application/json", accept: "application/json" },
+            body: options.encoding === "form"
+                ? new URLSearchParams(params).toString()
+                : JSON.stringify(params),
+            signal: signalOf(options.signal),
+        });
+    }
+    catch (error) {
+        throw new AmaError("oauth_network", `${options.what} failed: ${error.name}`, {
+            cause: undefined,
+        });
+    }
+    const text = await response.text().catch(() => "");
+    if (!response.ok)
+        throw new OAuthHttpError(response.status, oauthErrorCode(text), options.what);
+    if (text.trim() === "")
+        return {};
+    try {
+        const value = JSON.parse(text);
+        if (typeof value === "object" && value !== null)
+            return value;
+    }
+    catch {
+        // 落到下面
+    }
+    throw new AmaError("oauth_bad_response", `${options.what}: response is not JSON`);
+}
+export function parseTokenResponse(value, what) {
+    const access = value["access_token"];
+    if (typeof access !== "string" || access === "")
+        throw new AmaError("oauth_bad_response", `${what}: no access_token`);
+    const out = { accessToken: access };
+    const str = (key) => typeof value[key] === "string" && value[key] !== "" ? value[key] : undefined;
+    const refresh = str("refresh_token");
+    if (refresh !== undefined)
+        out.refreshToken = refresh;
+    const id = str("id_token");
+    if (id !== undefined)
+        out.idToken = id;
+    const scope = str("scope");
+    if (scope !== undefined)
+        out.scope = scope;
+    const clientId = str("client_id");
+    if (clientId !== undefined)
+        out.clientId = clientId;
+    const expires = value["expires_in"];
+    const seconds = typeof expires === "string" ? Number(expires) : expires;
+    if (typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0)
+        out.expiresIn = seconds;
+    return out;
+}
+export async function getJson(fetchFn, url, what, signal) {
+    let response;
+    try {
+        response = await fetchFn(url, {
+            headers: { accept: "application/json" },
+            signal: signalOf(signal),
+        });
+    }
+    catch (error) {
+        throw new AmaError("oauth_network", `${what} failed: ${error.name}`);
+    }
+    const text = await response.text().catch(() => "");
+    if (!response.ok)
+        throw new OAuthHttpError(response.status, oauthErrorCode(text), what);
+    try {
+        const value = JSON.parse(text);
+        if (typeof value === "object" && value !== null)
+            return value;
+    }
+    catch {
+        // 落到下面
+    }
+    throw new AmaError("oauth_bad_response", `${what}: response is not JSON`);
+}

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

@@ -0,0 +1,23 @@
+/**
+ * OAuth 条目的存取与跨进程刷新锁（docs/wave6-plan.md §4.3、D15）。[W6-O]
+ *
+ * - 读：每次都从磁盘读（绕过 `ApiKeyResolver.fileCache`，长会话才能看到别的进程刷新后的 token）；文件不存在 /
+ *   坏掉 / 不是 oauth 条目 → undefined；
+ * - 写：读-改-写 `auth.json` 整个文件，经 `writeAuthFile`（同目录临时文件 0600 → rename → chmod），其它条目原样保留；
+ * - 锁：`<auth.json>.lock`，`open(O_CREAT|O_EXCL)`（flag `wx`）写 `{ pid, at }`；等待 ≤ 15 s；锁文件超过 60 s 且
+ *   pid 已死视为陈旧，删除后重试。取锁后由调用方**重读文件**再决定要不要刷新。
+ */
+import { type OAuthAuthEntry } from "../../config/types-w6.js";
+export declare const LOCK_WAIT_MS = 15000;
+export declare const LOCK_STALE_MS = 60000;
+export declare function readOAuthEntry(path: string, provider: string): OAuthAuthEntry | undefined;
+/** 写入（`undefined` 删除）该供应商的条目，其余条目不动。 */
+export declare function writeOAuthEntry(path: string, provider: string, entry: OAuthAuthEntry | undefined): void;
+export declare function lockPath(authFile: string): string;
+/** 锁文件陈旧：超过 60 s 且写锁的进程已不在。 */
+export declare function isStaleLock(path: string, now?: number): boolean;
+export interface LockOptions {
+    waitMs?: number;
+}
+/** 在 `auth.json.lock` 下执行 `fn`；等不到锁抛 `auth_lock_timeout`。 */
+export declare function withRefreshLock<T>(authFile: string, fn: () => Promise<T>, options?: LockOptions): Promise<T>;