@eddyskywalker/dsh-chatgpt-subscription 0.31.0 → 0.33.0

package/lib/types/host/qoder/oauth.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Qoder（订阅）线路的登录：浏览器设备流（仅全球区）+ PAT 兑换 + 令牌刷新。
+ *
+ * 协议逐字来源：
+ *
+ * - 设备流（PKCE 风格 challenge/verifier + nonce 轮询，**不开本地回调端口**）：
+ *   qodercli2api \`docs/oauth.md\` §2（官方 CLI v1.1.34 的 frozen fixtures 互操作基线），
+ *   与 pi-provider \`src/auth/login.ts\`（live 验证）互相印证；
+ * - PAT 兑换：docs.qoder.com/cli/authentication（官方文档）+ pi-provider \`src/auth/pat.ts\`；
+ * - 刷新：pi-provider \`src/auth/oauth.ts\` \`refreshQoderTokenForMode\`（live 验证）。
+ *
+ * 与 step-code 的 oauth.ts 同构的部分（流程状态机外壳：flow / controller /
+ * getXxxLoginStatus / resetXxxLogin / takeXxxLoginCredential）是因为设置卡片跟随的是
+ * 同一组四个入口；与它的**差异**（凭据会过期、可刷新）全部集中在
+ * {@link refreshQoderCredential} 与凭据装配段。
+ *
+ * 凭据形状由 token-store.ts 的 \`QoderCredentials\` 定义；本文件只负责「把一次登录
+ * 变成一份凭据」，不持有凭据存储。
+ */
+import type { QoderLoginFlowStatus, QoderRegion } from '../../shared/qoder-contracts.ts';
+import { type QoderRequestOptions } from './client.ts';
+import { type QoderCredentials } from './token-store.ts';
+/**
+ * PKCE 风格参数。
+ *
+ * - verifier：43..128 字符（A-Z a-z 0-9 -._~）——32 字节 base64url 正好 43 字符；
+ * - challenge：base64url_nopad(SHA256(verifier))；
+ * - nonce：random UUID；
+ * - machineId：36 字符 UUID（本机既有那把就用那把，见 cosy.ts 的读取顺序）。
+ */
+export declare function createQoderDeviceParams(env?: NodeJS.ProcessEnv): {
+    verifier: string;
+    challenge: string;
+    nonce: string;
+    machineId: string;
+};
+/**
+ * 授权页 URL（host 拼，卡片打开）。
+ *
+ * 逐字 docs/oauth.md §2.1 的参数表（challenge / challenge_method=S256 / nonce /
+ * machine_id / client_id=官方 CLI 的固定值）。没有 scope、redirect URI 或本地回调。
+ */
+export declare function qoderDeviceAuthorizeUrl(params: {
+    challenge: string;
+    nonce: string;
+    machineId: string;
+}): string;
+/** 一次轮询的三种结果。 */
+export type QoderDevicePoll = {
+    readonly state: 'pending';
+} | {
+    readonly state: 'ready';
+    readonly token: string;
+    readonly userId: string | null;
+    readonly refreshToken: string | null;
+    readonly expiresAt: number;
+} | {
+    readonly state: 'failed';
+    readonly reason: string;
+};
+/**
+ * GET {openapi}/api/v1/deviceToken/poll?nonce=…&verifier=…&challenge_method=S256。
+ *
+ * 逐字 docs/oauth.md §2.2 与 pi-provider \`login.ts\` 的状态语义：
+ *
+ * - 404 / 202 = pending（用户还没在浏览器里确认）；
+ * - 200 = 取 token（**缺 token 的 200 立即失败**——看形状，不只看状态码）；
+ * - 其余非 2xx = 立即失败；
+ * - transport 错误由外层轮询循环按间隔重试（到截止为止），不在这里判死。
+ */
+export declare function pollQoderDeviceToken(params: {
+    nonce: string;
+    verifier: string;
+}, options?: QoderRequestOptions): Promise<QoderDevicePoll>;
+/**
+ * 设备流轮询结果 → 落盘凭据。
+ *
+ * userinfo 是 best-effort 的补齐（uid 缺失会让 CN 拒成 105；全球区的设备流
+ * 轮询自己带 \`user_id\`），补齐失败不使登录失败（docs/oauth.md §2：
+ * enrichment 失败不使登录失败）。
+ */
+export declare function qoderCredentialsFromDevicePoll(ready: {
+    token: string;
+    userId: string | null;
+    refreshToken: string | null;
+    expiresAt: number;
+}, machineId: string, options?: QoderRequestOptions): Promise<QoderCredentials>;
+/**
+ * PAT → 落盘凭据。
+ *
+ * 兑换 + userinfo 补齐；**PAT 本体留在凭据里**（host-only），因为 PAT 的「刷新」
+ * 就是拿它重新兑换一把 job token（pi-provider 把 PAT 编进 refresh 字段，
+ * 本线路把它放进一个具名字段——同一件事，更好读）。
+ */
+export declare function qoderCredentialsFromPat(personalToken: string, region: QoderRegion, options?: QoderRequestOptions): Promise<QoderCredentials>;
+/**
+ * 刷新一份凭据（号池 refresh 钩子的实现）。
+ *
+ * 两条路径（凭据的 origin 决定）：
+ *
+ * - **PAT**：拿存下的 PAT 重新兑换（pi-provider 的 isPatRefresh 路径同一做法）；
+ * - **其余**：\`refreshToken\` 走 center 刷新端点；没有 refreshToken 的凭据
+ *   无法刷新，抛出明确的错误（号池据此把账号标成需要重新登录）。
+ *
+ * 失败带上 \`status\`（有 HTTP 状态时），号池据此分类「这个账号要重登」还是
+ * 「瞬时故障，别判死」。
+ */
+export declare function refreshQoderCredential(credentials: QoderCredentials, fetchFn?: typeof fetch): Promise<QoderCredentials>;
+/** 卡片轮询的状态切片。返回副本，调用方改不到内部状态。 */
+export declare function getQoderLoginStatus(): QoderLoginFlowStatus;
+/** 取消进行中的流程并回到 idle（设置卡片的「取消」）。 */
+export declare function resetQoderLogin(): void;
+/** 看看有没有一份已经拿到、还没被取走的凭据（纯内存读）。 */
+export declare function peekQoderLoginCredential(): QoderCredentials | null;
+/** 取走那份凭据并清空（同一份凭据只该被落盘一次）。 */
+export declare function takeQoderLoginCredential(): QoderCredentials | null;
+export interface QoderLoginOptions {
+    /** 测试缝。默认 fetch。 */
+    fetchFn?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    /** 完成的登录写到哪里（接入层传号池的保存函数）。 */
+    onSave?: (credential: QoderCredentials) => Promise<unknown>;
+    /** 本地总时限；缺省 10 分钟，可由 QODER_LOGIN_TIMEOUT_MS 覆盖。 */
+    timeoutMs?: number;
+}
+/**
+ * 开始一次浏览器设备流登录（**仅全球区**；CN 没有设备流，走 PAT 或 adopt）。
+ *
+ * 流程跑在 host 上（controller + flow），设置卡片只跟随 getQoderLoginStatus——
+ * 与其余各线路的登录面同构。轮询节奏 2 秒一次，总超时取本地总时限
+ * （服务端对 verifier 的硬截止由 404→failed 的翻转表达）。
+ */
+export declare function beginQoderLogin(region: QoderRegion, options?: QoderLoginOptions): Promise<QoderLoginFlowStatus>;
+//# sourceMappingURL=oauth.d.ts.map

package/lib/types/host/qoder/oauth.d.ts.map

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

package/lib/types/host/qoder/routes.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Qoder（订阅）线路的 web 路由。
+ *
+ * 路由表与客户端 \`src/client/qoder/api.ts\` 里那一份是**同一个约定**，两边必须逐条对上：
+ *
+ * \`\`\`
+ * GET  /status           -> QoderStatusDto（页面的唯一读口）
+ * POST /settings         QoderSettingsUpdateDto -> QoderStatusDto
+ * POST /accounts         { action, accountId } / { action:'strategy', strategy } -> QoderStatusDto
+ * POST /login/start      { region } -> QoderLoginFlowStatus（设备流，仅全球区）
+ * GET  /login/status     -> QoderLoginFlowStatus
+ * POST /login/cancel     { } -> QoderLoginFlowStatus
+ * POST /login/manual     { region, token } -> QoderStatusDto（请求体带 PAT，不在冻结契约里）
+ * POST /adopt            { } -> QoderAdoptResultDto（裸 DTO；失败永不阻断）
+ * POST /connection/test  { } -> QoderConnectionDto（裸 DTO）
+ * POST /quota            { } -> QoderStatusDto（强制刷新额度）
+ * POST /catalog/refresh  { } -> QoderStatusDto
+ * \`\`\`
+ *
+ * 信封：除 \`/adopt\` 与 \`/connection/test\` 外一律 \`{ ok, value }\`（客户端的
+ * \`createLineApi\` 会把信封拆掉；那两条路由的契约把 DTO 定在顶层，所以它们直接返回 DTO）。
+ *
+ * 同源校验不可省：每个 POST 都过 \`isSameOriginMutation\`，与兄弟线路同一份实现。
+ *
+ * 本文件**不持有任何凭据，也不算任何用量**：落盘与刷新交给 token-store / account-pool /
+ * oauth / adopt，上游 I/O 交给 client.ts，缓存用量的累计是 adapter.ts 的累计器。
+ * 它只做三件事：读设置、组装状态面、把同源的 POST 翻译成对上面那些模块的一次调用。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AccountRotationStrategy } from '../../shared/account-pool-contracts.ts';
+import { type QoderAccountSummaryDto, type QoderCacheStatsDto, type QoderQuotaSnapshotDto, type QoderRegion, type QoderStatusDto } from '../../shared/qoder-contracts.ts';
+import { type QoderAccountPool } from './account-pool.ts';
+import { type QoderModelEntry } from './model-catalog.ts';
+import { QoderModelSettingsStore, type QoderModelSettings, type QoderPreferenceStore, type QoderSettingsPatch } from './token-store.ts';
+/** 一个请求寻址的子路径（剥掉契约前缀）。 */
+export declare function qoderSubPathOf(requestUrl: string): string;
+/**
+ * 设置来源：register 后端与文件后端形状不同，这里收敛成一个（与 step-code 同形）。
+ */
+export interface QoderSettingsSource {
+    status(): QoderModelSettings | Promise<QoderModelSettings>;
+    update(patch: QoderSettingsPatch): Promise<QoderModelSettings>;
+}
+/** 设置来源：register 后端优先，没有就落回凭据旁边的 JSON 文件。 */
+export declare function qoderSettingsSource(preferences: QoderPreferenceStore | undefined, fallback: QoderModelSettingsStore): QoderSettingsSource;
+export interface QoderRouteOptions {
+    fetchFn?: typeof fetch;
+    /** 本插件是否正在服务这条 Provider 路由；每次状态都重新读。 */
+    serving?: boolean | (() => boolean);
+    /** 路由被别的适配器占用时的诊断文案；每次状态都重新读。 */
+    conflict?: string | null | (() => string | null);
+    /** 号池；本进程装了才有。 */
+    accountPool?: QoderAccountPool;
+    /** 环境变量读取处；缺省 process.env，且**调用时**读取。 */
+    env?: NodeJS.ProcessEnv;
+}
+/** 号池切片的收紧形状（本线路状态面实际持有的那一部分）。 */
+export interface QoderPoolSlice {
+    accounts: QoderAccountSummaryDto[];
+    rotationStrategy: AccountRotationStrategy;
+    activeAccountId?: string;
+}
+export interface QoderStatusSources {
+    options: QoderRouteOptions;
+    settings: QoderSettingsSource;
+    /** 下一次登录要用的区域。 */
+    region: QoderRegion;
+    /** 号池切片：唯一装配它的地方是 account-pool 的 qoderPoolStatusSlice（这里只收紧形状）。 */
+    pool: QoderPoolSlice;
+    /** 本次读到的账号（卡片渲染用，不带任何凭据）。 */
+    account: QoderAccountSummaryDto | null;
+    /** 这个部署当前的模型目录（缓存读，轮询不联网）。 */
+    catalog: readonly QoderModelEntry[];
+    /** 本进程为当前账号记住的额度快照。 */
+    quota: QoderQuotaSnapshotDto | null;
+    /** 本次应答背后是否正在刷新额度。 */
+    quotaRefreshing: boolean;
+    /** 上一次额度读失败的原因；没有快照可渲染时为 null。 */
+    quotaError: string | null;
+    /** 本进程累计的缓存用量；尚无样本时为 undefined（客户端据此渲染占位符）。 */
+    cacheStats: QoderCacheStatsDto | undefined;
+}
+/**
+ * 组装 \`QoderStatusDto\`。
+ *
+ * 号池读不出来不能带倒整张卡：连接那一半仍然值得渲染，只是账号列表是空的。
+ */
+export declare function getQoderStatus(sources: QoderStatusSources): Promise<QoderStatusDto>;
+/**
+ * 注册本线路的路由。
+ *
+ * 本文件不持有凭据：账号的落盘与轮转在号池，凭据由号池镜像。
+ * 设置的唯一写入点是 \`POST /settings\`。
+ */
+export declare function registerQoderRoutes(ctx: Context, settings: QoderSettingsSource, options?: QoderRouteOptions): () => void;
+//# sourceMappingURL=routes.d.ts.map

package/lib/types/host/qoder/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../../src/host/qoder/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAA;AACrF,OAAO,EAKL,KAAK,sBAAsB,EAE3B,KAAK,kBAAkB,EAEvB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,cAAc,EACpB,MAAM,iCAAiC,CAAA;AAMxC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAA;AAS1B,OAAO,EAA+C,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAOtG,OAAO,EAEL,uBAAuB,EAEvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAA;AA+CzB,0BAA0B;AAC1B,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOzD;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,IAAI,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAC1D,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAC/D;AAUD,6CAA6C;AAC7C,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,oBAAoB,GAAG,SAAS,EAC7C,QAAQ,EAAE,uBAAuB,GAChC,mBAAmB,CAErB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;IACtB,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;IACnC,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAA;IAChD,kBAAkB;IAClB,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CACxB;AAyBD,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,sBAAsB,EAAE,CAAA;IAClC,gBAAgB,EAAE,uBAAuB,CAAA;IACzC,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,iBAAiB,CAAA;IAC1B,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,kBAAkB;IAClB,MAAM,EAAE,WAAW,CAAA;IACnB,mEAAmE;IACnE,IAAI,EAAE,cAAc,CAAA;IACpB,6BAA6B;IAC7B,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAA;IACtC,8BAA8B;IAC9B,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;IACnC,uBAAuB;IACvB,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAAA;IACnC,sBAAsB;IACtB,eAAe,EAAE,OAAO,CAAA;IACxB,kCAAkC;IAClC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,+CAA+C;IAC/C,UAAU,EAAE,kBAAkB,GAAG,SAAS,CAAA;CAC3C;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAiCzF;AAiCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,MAAM,IAAI,CAkTZ"}

package/lib/types/host/qoder/token-store.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Qoder（订阅）线路的凭据 / 模型设置 / 偏好三件套。
+ *
+ * 本线路的凭据与 step-code 相反的那个性质先说清楚，因为它决定了本文件的设计：
+ *
+ * **凭据会过期、可刷新。** Qoder 的 job/device token 带着 `expires_at` / `expires_in`
+ * （pi-provider `pat.ts` / `login.ts`；qodercli2api `docs/oauth.md` §3）。所以：
+ *
+ * - 本文件**有** refresh 相关的一切（过期时刻、提前刷新量、刷新输入的留存）；
+ * - PAT 来源的凭据**留住 PAT 本体**（host-only，绝不进共享契约），因为 PAT 的
+ *   「刷新」就是拿它重新兑换一把 job token（pi-provider `oauth.ts` 的
+ *   `isPatRefresh` 路径同一做法）；
+ * - 号池的 `expiresAt`/`needsRefresh`/`refresh` 钩子都是活的，
+ *   刷新失败按 401/403 → expired、其余 → 瞬时 分类（account-pool.ts）。
+ *
+ * 第二件必须记住的事：**本线路自己拥有它的凭据副本，但从不拥有 qodercli 的文件**。
+ * adopt 只是把 `~/.qoder/.auth/user` 读成一份快照存进本插件自己的凭据存储
+ * （`adopt.ts` 只读、不写、不删）。落盘的 adopt 凭据带 `adopted / source / sourcePath`
+ * 三个判别式字段，与其它线路的 adopt 语义一致。
+ *
+ * 三件套的分工与兄弟线路一致：凭据走 DPAPI / Keychain / Secret Service；
+ * 模型设置是明文 JSON，带写后回读校验；偏好在 harness 还提供 register 接缝时注册进
+ * 设置文档，没有就落回那个 JSON 文件。
+ */
+import type { CredentialStore } from '../token-store.ts';
+import { type ContextWindowOverridePatch } from '../common/context-window-overrides.ts';
+import type { QoderReasoningEffort, QoderRegion } from '../../shared/qoder-contracts.ts';
+import { listModelIds } from './model-catalog.ts';
+/** 本线路在设置文档里注册的命名空间。 */
+export declare const QODER_PREFERENCES_NAMESPACE = "dsh-qoder";
+/**
+ * 这份凭据是从哪条路来的。
+ *
+ * - `device`：浏览器设备流（仅全球区）。
+ * - `pat`：用户手动粘贴的 Personal Access Token 兑换来的 job token。
+ * - `adopt`：从本机 qodercli 客户端读来的登录态快照。
+ *
+ * 它与 `region` 是**两件事**：`region` 决定打哪套端点，`origin` 决定这份东西
+ * 怎么刷新（PAT 重兑换 vs refresh_token）以及本插件能不能对它做任何写操作。
+ */
+export type QoderCredentialOrigin = 'device' | 'pat' | 'adopt';
+/** 本线路读 qodercli 登录态时的来源标记（与兄弟线路的 adopt 判别式同构）。 */
+export declare const QODER_CLI_CREDENTIAL_SOURCE = "qoder-cli";
+/**
+ * 一份可服务请求的 Qoder 凭据。
+ *
+ * 真正发请求只用 `accessToken`（Bearer + COSY 载荷里的 `security_oauth_token`）。
+ * 其余字段分四类：
+ *
+ * - **刷新输入**（`refreshToken` / `expiresAt` / `personalToken`）：过期后续命的原料；
+ * - **非机密的账号事实**（`uid` / `email` / `accountName`）：COSY 载荷与卡片渲染用；
+ * - **路由事实**（`region`）：它唯一决定端点表，见 `./types.ts` 的 `REGION_HOSTS`；
+ * - **COSY 头的条件字段**（`organizationId` / `organizationTags` / `dataPolicyAgreed`）：
+ *   非空才出现在请求头里（inference-protocol.md §2 的 presence 矩阵）；
+ * - adopt 判别式（`adopted` / `source` / `sourcePath`）：见文件头。
+ */
+export interface QoderCredentials {
+    /** 真正发请求用的 job/device token。Host-only，永不过共享边界。 */
+    accessToken: string;
+    /** 刷新令牌（`jrt-...` 或设备流的 refresh_token）；没有时为 null。 */
+    refreshToken: string | null;
+    /** 过期时刻（Unix 毫秒，已含安全边）；上游没给时按兑换时刻 + 24h 兜底。 */
+    expiresAt: number;
+    /** 凭据自述的区域；**端点由它唯一决定**，不另存一份。 */
+    region: QoderRegion;
+    origin: QoderCredentialOrigin;
+    /** 上游账号 id（COSY 的 `Cosy-User`）；缺它 CN 会报「Login expired」（105）。 */
+    uid: string | null;
+    /** 账号邮箱（COSY UserInfo 的 `email`，非机密）；没有时为 null。 */
+    email: string | null;
+    /** 账号显示名（COSY UserInfo 的 `name`）；没有时为 null。 */
+    accountName: string | null;
+    /**
+     * PAT 来源的凭据留住的 PAT 本体（`pt-...`）。
+     *
+     * **Host-only，永远不过共享契约的边界**：它的唯一用途是过期后重新兑换一把
+     * job token（pi-provider 把 PAT 编进 refresh 字段，同一件事）。非 PAT 来源为 null。
+     */
+    personalToken: string | null;
+    /** 组织 id（`Cosy-Organization-Id` 的条件字段）；个人账号为 null。 */
+    organizationId: string | null;
+    /** 组织 tags（`Cosy-Organization-Tags` 的条件字段，逗号连接前的那份数组）。 */
+    organizationTags: string[];
+    /** `Cosy-Data-Policy` 的取值开关：true → `agree`，否则 `disagree`（fixture 的默认）。 */
+    dataPolicyAgreed: boolean;
+    /** 本插件接管这份凭据的时刻（Unix 毫秒）。 */
+    authenticatedAt: number;
+    /** 判别式，取字面量 `true`（与兄弟线路同：一个布尔比一句注释更难被忽略）。 */
+    adopted?: true;
+    /** 恒为 {@link QODER_CLI_CREDENTIAL_SOURCE}。 */
+    source?: typeof QODER_CLI_CREDENTIAL_SOURCE;
+    /** 读的是哪个文件，卡片照它显示。 */
+    sourcePath?: string;
+}
+/**
+ * 校验并归一化一份落盘的凭据。
+ *
+ * 缺的字段一律拒绝而不是补默认值：缺 `accessToken` 的凭据发出去一定是一次 401；
+ * 缺 `uid` 的凭据在 CN 会被报「Login expired」（105）——但它不拒绝：全球区对这个字段
+ * 更宽容，而号池装配侧会在发卡前尽力补齐（oauth.ts 的 userinfo 步骤）。
+ *
+ * `region` 认不出来时**拒绝**而不是回落默认：落盘的凭据总该自述；猜错的代价是
+ * 拿一区的凭据去打另一区的端点，一次明确的鉴权失败，排查成本远高于重新登录。
+ */
+export declare function parseQoderCredentials(value: unknown): QoderCredentials;
+/**
+ * 一份凭据是不是 adopt 快照（号池与适配器据此知道它的上游权威是 qodercli 的文件）。
+ *
+ * 它读的是**凭据对象本身**而不是某个内存标记（同 step-code 的同名函数的理由）。
+ */
+export declare function isAdoptedQoderCredential(credentials: QoderCredentials): boolean;
+/**
+ * 凭据的失效时刻：自述的 `expiresAt`；缺 0 时按「接管时刻 + 24h」补一份诚实的兜底
+ * （pi-provider 的缺省寿命），让号池的刷新钩子有东西可判。
+ */
+export declare function qoderCredentialsExpireAt(credentials: QoderCredentials): number;
+/**
+ * 这份凭据需不需要刷新：`expiresAt - 3600_000 < now` 时刷新
+ * （逐字 qodercli2api `docs/oauth.md` §3 的提前 1 小时）。
+ */
+export declare function qoderCredentialsNeedRefresh(credentials: QoderCredentials, now: number): boolean;
+/**
+ * 兑换/刷新响应里的过期时刻 → Unix 毫秒（已含 5 分钟安全边）。
+ *
+ * 三种形态都收（计划 §9 风险 6）：
+ *
+ * - `expiresAt`：ISO 字符串或 Unix 秒/毫秒——用**量级**分辨（10^10 秒是 2286 年，
+ *   更大的数一定已经是毫秒）；
+ * - `expiresIn`：相对时长。pi-provider 注释说观测到的是**毫秒**，qodercli2api 按秒读；
+ *   同一量级判据两处都兼容（小于 10^7 的值按秒才合理：10^7 秒约 4 个月，
+ *   而一把 job token 的寿命以小时/天计）。
+ */
+export declare function qoderExpiresAtFrom(expiresAt: unknown, expiresIn: unknown, now?: number): number;
+/** 凭据文件路径（本线路自己拥有；号池把主账号镜像到这里）。 */
+export declare function credentialPath(): string;
+/** 模型设置文件路径。 */
+export declare function modelSettingsPath(): string;
+/**
+ * machine id 文件路径（本线路自己持有的那份）。
+ *
+ * adopt 优先读 qodercli 的 `~/.qoder/.auth/machine_id`（解密它的凭据文件必须用那把
+ * 原配 key）；本线路自己发请求用的 machine id 落在这里——不与 qodercli 的混用，
+ * 也不写它的目录（读取顺序见 cosy.ts）。
+ */
+export declare function machineIdPath(): string;
+/**
+ * 加密凭据存储。
+ *
+ * 与兄弟线路同构：写入之后回读比对；按路径排队，避免两个同时落地的写互相丢掉。
+ * 没有明文迁移分支（本线路从未发布过，没有历史文件要迁）。
+ */
+export declare class QoderCredentialStore {
+    private readonly filePath;
+    private readonly backend;
+    constructor(filePath?: string, backend?: CredentialStore<QoderCredentials>);
+    /** 人可读的存储位置说明（Windows DPAPI / macOS Keychain / Linux Secret Service）。 */
+    path(): string;
+    read(): Promise<QoderCredentials | null>;
+    write(credentials: QoderCredentials): Promise<void>;
+    delete(): Promise<void>;
+}
+/**
+ * 本线路设置文档里**用户自己**的那一半。
+ *
+ * 随包目录 `QODER_MODEL_CATALOG_*` 刻意不存：它跟着代码走（同 step-code 的理由）。
+ */
+export interface QoderModelSettings {
+    /** 线路总开关。只有显式 false 才是关闭。 */
+    enabled?: boolean;
+    /**
+     * 用户勾选的模型 id；缺省或空数组 = **不过滤（全选）**，非空 = 显式选择。
+     * （语义逐字照抄 step-code：schemastery 会把缺省的 `z.array(z.string())` 归一化成
+     * `[]`，所以没有「null = 不过滤」的第三态。）
+     */
+    enabledModelIds?: string[];
+    /** 逐模型上下文窗口覆盖；缺省用目录声明值。 */
+    contextWindowOverrides: Record<string, number>;
+    /** 会话没指定档位时用的档位；null 表示各模型用自己的默认。 */
+    defaultReasoningEffort: QoderReasoningEffort | null;
+    /** 手动指定下一个请求使用的账号；null 交回号池调度。 */
+    selectedAccountId: string | null;
+}
+/** 一个设置补丁。 */
+export interface QoderSettingsPatch {
+    enabled?: boolean;
+    enabledModelIds?: string[];
+    /** 补丁而不是整张表：`null` 必须能作为一个**值**活下来（卡片的「恢复目录默认」）。 */
+    contextWindowOverrides?: ContextWindowOverridePatch;
+    defaultReasoningEffort?: QoderReasoningEffort | null;
+    selectedAccountId?: string | null;
+}
+/**
+ * 路由与适配器共用的接缝（与 step-code 同一个形状，`status()` 同步的理由也相同）。
+ */
+export interface QoderPreferenceStore {
+    ready(): Promise<void>;
+    status(): QoderModelSettings;
+    update(patch: QoderSettingsPatch): Promise<QoderModelSettings>;
+}
+/** 一次全新安装的设置：全开、无过滤、无覆盖、无指定账号。 */
+export declare function defaultQoderModelSettings(): QoderModelSettings;
+/**
+ * 归一化一份解析出来的设置文档。什么都不抛：手改过或降级过的文档必须降级成一份
+ * 可用的选择，而不是让整条线路不可用。
+ */
+export declare function parseQoderModelSettings(value: unknown): QoderModelSettings;
+/** 把一个补丁应用到一份设置文档上（register 与文件两个后端共用这一套规则）。 */
+export declare function mergeQoderSettings(current: QoderModelSettings, patch: QoderSettingsPatch): QoderModelSettings;
+/**
+ * 凭据旁边的设置文件（没有 register 接缝的 harness 启动时读的就是它）。
+ * 写入走「临时文件 + rename」，写完立刻回读比对再报告成功。
+ */
+export declare class QoderModelSettingsStore {
+    private readonly filePath;
+    constructor(filePath?: string);
+    path(): string;
+    read(): Promise<QoderModelSettings>;
+    write(settings: QoderModelSettings): Promise<void>;
+    /** 在与凭据写入同一条按路径排队的锁里做「读-改-写」。 */
+    updateSettings(patch: QoderSettingsPatch): Promise<QoderModelSettings>;
+}
+/**
+ * 把模型选择绑到 DSH 设置文档（harness 还提供 register 接缝时），
+ * 否则绑到凭据旁边的 JSON 文件。
+ *
+ * ⚠ `enabledModelIds` 不给 `.default()`（与 step-code 同一处实测：
+ * schemastery 会把缺省的数组归一化成 `[]`，而 `[]` 与「不过滤」同义）。
+ */
+export declare function registerQoderPreferenceStore(settings?: unknown, fallbackStore?: QoderModelSettingsStore): QoderPreferenceStore;
+export { listModelIds };
+//# sourceMappingURL=token-store.d.ts.map

package/lib/types/host/qoder/token-store.d.ts.map

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