@sema-agent/client-core 0.13.0 → 0.15.0

package/dist/model/catalogLoader.js

@@ -0,0 +1,382 @@
+/**
+ * catalogLoader.ts — **目录候选链的宿主 loader**(design/166 §1-§3,2026-08-04)。
+ *
+ * ## 它与 `catalog.ts` 的分工(🔴 委托,不平行重做)
+ *
+ * `catalog.ts` 已经是三层源解析器:`resolveModelCatalog`(线上→包内→用户覆盖三层合并)+
+ * `validateOnlineCatalog`(schemaVersion 区间 / 逐行 `isProviderRow` / **绝不半解析** / 不回显载荷)
+ * + `CatalogFetchJson` 注入端口 + `CatalogSource`·`CatalogRejectReason` 两张词表。
+ * 本文件**只补 catalog.ts 声明不管的宿主面**,四件事:
+ *
+ *   ① **候选链遍历**(`DEFAULT_CATALOG_SOURCES` = raw.githubusercontent → jsDelivr,可配);
+ *   ② **传输安全硬门**:https + 域白名单(拨号**之前**判,域外源连请求都不发)——
+ *      而且**重定向目标过同一道门**(fetch 默认跟随重定向,不设门 = 白名单可被 302 绕过);
+ *   ③ **`catalog.sha256` 旁签**(同源同路径,SHA-256 hex 比对);
+ *   ④ **缓存**(`configHome/cache/model-catalog.json`)的信封与读回语义。
+ *
+ * 载荷面的判决(schemaVersion / 逐行形状 / 整份弃 / 不回显)**一行都不在这里重写** ——
+ * 本文件拿到字节流之后做的唯一一件事是 `JSON.parse`,然后把结果交给 `resolveModelCatalog`,
+ * 由它去 `validateOnlineCatalog`。UI 渲染也只认 `ModelCatalogResult.source` + `online.reason`
+ * (+ 本文件加的 `cacheHit`),**不发明第二套 origin 词表**。
+ *
+ * ## 🔴 为什么缓存的**落盘动作**在宿主而不在这里(与设计档 §3 的偏差,记在这)
+ *
+ * 设计档 §3 写的是「loader 原子写(tmp+rename)」。但本包有一条机械门守着的硬法:
+ * `src/**` 的 index 值级闭包**零 Node 内建**(`scripts/run-client-core-portability-test.mjs`
+ * ①c 段),因为同一份代码要在浏览器/桌面渲染进程里跑。`node:fs` 一进来,那道门当场红。
+ * ⇒ 落盘走**注入口** `CatalogCachePort`(与 `host.ts` 的 `FsPort`、`catalog.ts` 的
+ * `CatalogFetchJson` 同一条纪律:能力由宿主注入,库不自己 `require('fs')`)。
+ * **tmp+rename 的原子性是 `writeAtomic` 实现方的契约**,本文件在类型注释里把它写成要求;
+ * Node 宿主的十行参考实现见 `CatalogCachePort.writeAtomic` 的注释。
+ * 缺席该口 ⇒ 缓存腿整条不启用(`cacheHit` 键**缺席**,不是 `false` —— 「没查过」和「查过没用上」
+ * 是两件事,[honest-absence-not-fabricated-zero])。
+ *
+ * ## 🔴 `forceRefresh` 为什么没有(与设计档 §1 签名的偏差)
+ *
+ * 本 loader **恒先走网络**,缓存只在候选链**全败**时顶上(设计档 §3 自己就是这么定的读时机)。
+ * 也就是说没有任何一条「优先吃缓存」的路径可供 `forceRefresh` 去绕过 —— 收下这个参数只会
+ * 得到一个恒为空操作的旋钮,而空操作的旋钮是**假 affordance**(调用方以为自己强制刷新了)。
+ * 真要「手动刷新」,直接再调一次本函数就是最新语义。
+ *
+ * ## 时钟
+ *
+ * 与 `catalog.ts` 同一口径:**绝不偷读时钟**。`nowMs` 缺席 ⇒ 缓存信封不写 `fetchedAt`、
+ * 陈旧判定不做(`cacheStale` 键缺席),而不是 `Date.now()` 兜底。
+ */
+import { hostEnv } from '../hostEnv.js';
+import { resolveModelCatalog, } from './catalog.js';
+/**
+ * 默认候选链(design/166 §1;clay 裁「可配置,默认 github」)。
+ * 第二跳 jsDelivr 对 gh 仓是被动 CDN、零接入成本 —— 这就是大陆可达性的零维护替身。
+ * 🔴 顺序即优先级:逐源尝试,前一跳成了就不拨下一跳。
+ */
+export const DEFAULT_CATALOG_SOURCES = [
+    'https://raw.githubusercontent.com/sema-agent/sema-model-catalog/main/dist/catalog.json',
+    'https://cdn.jsdelivr.net/gh/sema-agent/sema-model-catalog@main/dist/catalog.json',
+];
+/** 默认域白名单 = 默认链两跳的 host。用户显式配置的源 host 在运行期并入(用户自担)。 */
+export const CATALOG_DEFAULT_HOSTS = ['raw.githubusercontent.com', 'cdn.jsdelivr.net'];
+/** 候选链的 env 键(一键安装脚本改这里;settings.json `env` 块同名同义,见 design/166 §2)。 */
+export const CATALOG_SOURCES_ENV = 'SEMA_CATALOG_SOURCES';
+/** 每源传输预算(design/166 §1:onboard 不能被网络拖住)。 */
+export const DEFAULT_CATALOG_TIMEOUT_MS = 3500;
+/** 缓存相对 configHome 的落点(design/166 §3)。 */
+export const CATALOG_CACHE_RELATIVE_PATH = 'cache/model-catalog.json';
+/** 缓存陈旧阈值:30 天(照用,但如实标 stale)。 */
+export const CATALOG_CACHE_STALE_MS = 30 * 24 * 60 * 60 * 1000;
+/** 单源允许的重定向跳数上限(有界:302 环不许把 onboard 转死)。 */
+const MAX_REDIRECTS = 5;
+/** 异常 → 短 detail(只取 message 前段,绝不带栈、绝不带载荷;与 catalog.ts 同一口径)。 */
+function shortError(e) {
+    return (e instanceof Error ? e.message : String(e)).slice(0, 160);
+}
+/** `SEMA_CATALOG_SOURCES` 的逗号列表解析(去空白、丢空项;缺席 ⇒ 空列表)。 */
+export function parseCatalogSources(raw) {
+    if (typeof raw !== 'string')
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * 候选链优先级(design/166 §2,高→低):env `SEMA_CATALOG_SOURCES` > 调用方(settings)> 默认链。
+ * 🔴 「配了但解析出空列表」按**没配**处理:空链会把目录腿整条静默关掉,而调用方以为自己配了。
+ */
+export function resolveCatalogSources(opts) {
+    const env = opts?.env ?? hostEnv();
+    const fromEnv = parseCatalogSources(env[CATALOG_SOURCES_ENV]);
+    if (fromEnv.length > 0)
+        return fromEnv;
+    const given = (opts?.sources ?? []).map((s) => s.trim()).filter((s) => s.length > 0);
+    if (given.length > 0)
+        return given;
+    return [...DEFAULT_CATALOG_SOURCES];
+}
+/** 取 URL 的 host(含 port);解析不动 ⇒ undefined。 */
+function hostOf(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        parsed = undefined; // 解析不动 = 不是合法 URL,调用方按「拒」处理(判决在 isAllowedCatalogUrl)
+    }
+    return parsed?.host;
+}
+/**
+ * 传输面硬门:**https + host 在白名单内**。拨号之前判 —— 不合格的地址连请求都不发。
+ * 🔴 白名单是**域**的门、https 是**协议**的门,两道都要过:白名单里的 host 走 http 照样拒
+ * (明文信道下目录可被改写成钓鱼网关,而目录决定的正是出站地址)。
+ */
+export function isAllowedCatalogUrl(url, allowedHosts) {
+    let parsed;
+    try {
+        parsed = new URL(url.trim());
+    }
+    catch {
+        parsed = undefined; // 非法 URL ⇒ 拒(下面那一行判它)
+    }
+    if (parsed === undefined)
+        return false;
+    if (parsed.protocol !== 'https:')
+        return false;
+    return allowedHosts.has(parsed.host);
+}
+/** 旁签地址 = 同源同路径换后缀(design/165 §4:`dist/catalog.sha256`)。 */
+export function catalogShaUrlFor(catalogUrl) {
+    return catalogUrl.endsWith('.json') ? `${catalogUrl.slice(0, -'.json'.length)}.sha256` : `${catalogUrl}.sha256`;
+}
+/** 缓存文件绝对路径(design/166 §3)。POSIX 分隔符 —— Node 侧 `path.join` 对它是幂等的。 */
+export function catalogCachePath(configHome) {
+    return `${configHome.replace(/\/+$/, '')}/${CATALOG_CACHE_RELATIVE_PATH}`;
+}
+/** SHA-256 hex(WebCrypto;Node 18+ 与浏览器都有。拿不到实现 ⇒ null = 本次不比对)。 */
+async function sha256Hex(text) {
+    const g = globalThis;
+    const subtle = g.crypto?.subtle;
+    const Enc = g.TextEncoder;
+    if (subtle === undefined || Enc === undefined)
+        return null;
+    const digest = await subtle.digest('SHA-256', new Enc().encode(text));
+    let out = '';
+    for (const b of new Uint8Array(digest))
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+/** sha 文件内容 → hex(容忍 `<hex>  <filename>` 的 shasum 形与大小写)。认不出 ⇒ null。 */
+function parseShaFile(text) {
+    const m = /\b([0-9a-fA-F]{64})\b/.exec(text);
+    return m?.[1] === undefined ? null : m[1].toLowerCase();
+}
+async function guardedGet(url, allowedHosts, fetchImpl, timeoutMs) {
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (!isAllowedCatalogUrl(current, allowedHosts)) {
+            const insecure = !/^https:/i.test(current.trim());
+            return {
+                outcome: hop === 0 ? (insecure ? 'insecure-url' : 'host-not-allowed') : 'redirect-blocked',
+                detail: hop === 0
+                    ? `source rejected before dialing: ${insecure ? 'not https' : `host not allowlisted (${hostOf(current) ?? 'unparsable'})`}`
+                    : `redirect target rejected: ${hostOf(current) ?? 'unparsable'}`,
+            };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        let dialError;
+        try {
+            // 🔴 `redirect:'manual'` 是这道门的**执行体**:默认的 'follow' 会让 undici/浏览器替我们
+            //    跟到域外去(白名单被 302 绕过);手动跟 = 每一跳都回到上面那道 isAllowedCatalogUrl。
+            res = await fetchImpl(current, { method: 'GET', redirect: 'manual', signal: controller.signal });
+        }
+        catch (e) {
+            dialError = shortError(e);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (res === undefined)
+            return { outcome: 'network-error', detail: dialError ?? 'dial failed' };
+        // 浏览器的 `redirect:'manual'` 给的是 opaqueredirect(status 0、无头)——看不见目标就
+        // **拒**(fail-closed):看不见的重定向恰恰是这道门要防的那种。
+        if (res.status === 0)
+            return { outcome: 'redirect-opaque', status: 0, detail: 'opaque redirect: target not inspectable' };
+        if (res.status >= 300 && res.status < 400) {
+            const loc = res.headers.get('location');
+            if (loc === null || loc.length === 0) {
+                return { outcome: 'http-error', status: res.status, detail: 'redirect without Location' };
+            }
+            let next;
+            try {
+                next = new URL(loc, current).toString();
+            }
+            catch (e) {
+                return { outcome: 'redirect-blocked', status: res.status, detail: `unparsable Location: ${shortError(e)}` };
+            }
+            current = next;
+            continue;
+        }
+        if (res.status < 200 || res.status >= 300) {
+            return { outcome: 'http-error', status: res.status, detail: `HTTP ${res.status}` };
+        }
+        let text;
+        let readError;
+        try {
+            text = await res.text();
+        }
+        catch (e) {
+            readError = shortError(e);
+        }
+        if (text === undefined)
+            return { outcome: 'network-error', status: res.status, detail: readError ?? 'body read failed' };
+        return { outcome: 'ok', status: res.status, finalUrl: current, text };
+    }
+    return { outcome: 'redirect-loop', detail: `more than ${MAX_REDIRECTS} redirects` };
+}
+/**
+ * 解析出一份可用的 provider 目录 —— **候选链 + 传输硬门 + 旁签 + 缓存**,载荷判决全委托
+ * `resolveModelCatalog`。🔴 **永不 reject**:onboard 不能因为网络死。
+ */
+export async function loadCatalogWithSources(opts) {
+    const sources = resolveCatalogSources({
+        ...(opts?.env !== undefined ? { env: opts.env } : {}),
+        ...(opts?.sources !== undefined ? { sources: opts.sources } : {}),
+    });
+    // 白名单 = 默认两域 + **用户显式配置的源 host**(显式意愿=自担;doctor 如实标 user-configured)。
+    const allowedHosts = new Set(CATALOG_DEFAULT_HOSTS);
+    for (const s of sources) {
+        const h = hostOf(s);
+        if (h !== undefined)
+            allowedHosts.add(h);
+    }
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_CATALOG_TIMEOUT_MS;
+    const attempts = [];
+    const warnings = [];
+    let hit = null;
+    let lastDialed;
+    for (const src of sources) {
+        if (hit !== null)
+            break;
+        const got = await guardedGet(src, allowedHosts, fetchImpl, timeoutMs);
+        if (got.outcome !== 'insecure-url' && got.outcome !== 'host-not-allowed')
+            lastDialed = src;
+        if (got.outcome !== 'ok' || got.text === undefined) {
+            attempts.push({
+                url: src,
+                outcome: got.outcome,
+                ...(got.status !== undefined ? { status: got.status } : {}),
+                ...(got.detail !== undefined ? { detail: got.detail } : {}),
+            });
+            continue;
+        }
+        const finalUrl = got.finalUrl ?? src;
+        let doc;
+        let parseError;
+        try {
+            doc = JSON.parse(got.text);
+        }
+        catch (e) {
+            parseError = shortError(e);
+        }
+        if (parseError !== undefined) {
+            attempts.push({ url: src, outcome: 'invalid-json', ...(got.status !== undefined ? { status: got.status } : {}), detail: parseError });
+            continue;
+        }
+        // 旁签:同源同路径。拿不到 ⇒ 记 warn 放行(design/165 §4:它是防传输损坏的纵深,
+        // 不是防主动篡改 —— 把「拿不到」当「篡改」会让 CDN 的半更新窗把整条链打死)。
+        const shaGot = await guardedGet(catalogShaUrlFor(finalUrl), allowedHosts, fetchImpl, timeoutMs);
+        let shaChecked = false;
+        if (shaGot.outcome === 'ok' && shaGot.text !== undefined) {
+            const expected = parseShaFile(shaGot.text);
+            const actual = await sha256Hex(got.text);
+            if (expected === null) {
+                warnings.push(`catalog sha256 sidecar for ${finalUrl} is not a hex digest — payload accepted without the checksum`);
+            }
+            else if (actual === null) {
+                warnings.push('no WebCrypto SHA-256 in this host — catalog payload accepted without the checksum');
+            }
+            else if (expected !== actual) {
+                attempts.push({ url: src, outcome: 'sha-mismatch', detail: 'catalog.sha256 does not match the payload digest' });
+                continue;
+            }
+            else {
+                shaChecked = true;
+            }
+        }
+        else {
+            warnings.push(`catalog sha256 sidecar unavailable for ${finalUrl} (${shaGot.outcome}) — payload accepted without the checksum`);
+        }
+        attempts.push({ url: src, outcome: 'ok', ...(got.status !== undefined ? { status: got.status } : {}), shaChecked });
+        hit = { url: finalUrl, doc, raw: got.text, shaChecked };
+    }
+    // ── 缓存腿(口缺席 ⇒ 整条不启用,cacheHit 键缺席)────────────────────────────────────────
+    const cache = opts?.cache;
+    const cachePath = opts?.configHome !== undefined ? catalogCachePath(opts.configHome) : undefined;
+    let cacheHit = cache !== undefined ? false : undefined;
+    let cacheStale;
+    let cachedSourceUrl;
+    if (hit === null && cache !== undefined && cachePath !== undefined) {
+        let text = null;
+        let readError;
+        try {
+            text = await cache.read(cachePath);
+        }
+        catch (e) {
+            readError = shortError(e);
+        }
+        if (readError !== undefined)
+            warnings.push(`catalog cache read failed: ${readError}`);
+        if (typeof text === 'string' && text.length > 0) {
+            let env;
+            let envError;
+            try {
+                env = JSON.parse(text);
+            }
+            catch (e) {
+                envError = shortError(e);
+            }
+            if (envError !== undefined)
+                warnings.push(`catalog cache is not parsable JSON (ignored): ${envError}`);
+            const doc = env?.catalog;
+            const url = env?.sourceUrl;
+            if (doc !== undefined && typeof url === 'string' && url.length > 0) {
+                // 缓存里那份**就是**当初的线上载荷 —— 照样过 validateOnlineCatalog(下面同一条路),
+                // 不给它开后门:一份当年合法、今天已超区间的文档必须照样被拒。
+                hit = { url, doc, raw: text, shaChecked: false };
+                cacheHit = true;
+                cachedSourceUrl = url;
+                if (opts?.nowMs !== undefined && typeof env?.fetchedAt === 'number') {
+                    cacheStale = opts.nowMs - env.fetchedAt > CATALOG_CACHE_STALE_MS;
+                }
+            }
+            else if (envError === undefined) {
+                warnings.push('catalog cache envelope missing sourceUrl/catalog (ignored)');
+            }
+        }
+    }
+    // ── 委托:载荷判决 / 三层合并 / 来源标注全在 resolveModelCatalog ──────────────────────────
+    // 传给它的 `fetchJson` 只是「把已经拿到的这一份交出去」的闭包 —— 候选链与传输门是本文件的活,
+    // 校验与合并是它的活,两边不重叠也不互相重写。
+    const payload = hit;
+    const onlineUrl = payload?.url ?? lastDialed ?? sources[0];
+    const resolveOpts = {
+        ...(onlineUrl !== undefined ? { onlineUrl } : {}),
+        fetchJson: async () => {
+            if (payload === null)
+                throw new Error(`all ${sources.length} catalog source(s) failed; see attempts[]`);
+            return payload.doc;
+        },
+        ...(opts?.overrides !== undefined ? { overrides: opts.overrides } : {}),
+        ...(opts?.nowMs !== undefined ? { nowMs: opts.nowMs } : {}),
+    };
+    const base = await resolveModelCatalog(resolveOpts);
+    // 线上腿真的被接受了才写缓存(被 validateOnlineCatalog 拒掉的载荷绝不进缓存 ——
+    // 否则下一次断网时我们会把一份已知不合格的文档当兜底)。
+    if (base.online.ok && payload !== null && cacheHit !== true && cache !== undefined && cachePath !== undefined) {
+        const envelope = {
+            ...(opts?.nowMs !== undefined ? { fetchedAt: opts.nowMs } : {}),
+            sourceUrl: payload.url,
+            catalog: payload.doc,
+        };
+        let writeError;
+        try {
+            await cache.writeAtomic(cachePath, JSON.stringify(envelope));
+        }
+        catch (e) {
+            writeError = shortError(e);
+        }
+        if (writeError !== undefined)
+            warnings.push(`catalog cache write failed: ${writeError}`);
+    }
+    const sourceUrl = base.online.ok ? (cachedSourceUrl ?? payload?.url) : undefined;
+    return {
+        ...base,
+        ...(sourceUrl !== undefined ? { sourceUrl } : {}),
+        ...(cacheHit !== undefined ? { cacheHit } : {}),
+        ...(cacheStale !== undefined ? { cacheStale } : {}),
+        attempts,
+        warnings,
+    };
+}

package/dist/model/providerAuth.d.ts

@@ -0,0 +1,155 @@
+/**
+ * providerAuth.ts — **模型供应商凭证轨**的双轨 seam(design/166 §5「B 档:设备码流」,2026-08-04)。
+ *
+ * ## 边界(先说清楚它**不是**什么)
+ *
+ * 🔴 [reuse-single-sso-no-parallel-auth]:registry SSO(cloudAuth,「登录 sema」那条)**绝不复用、
+ * 绝不被改造**。本文件是**模型供应商**的凭证轨(拿一把 API key 去调某家模型),与 registry 登录轨
+ * 物理分文件、零共享代码。两者唯一的相似点是「都会弹一个浏览器」,那不构成复用理由。
+ *
+ * 🔴 design/166 §6 已定谳:**授权码 + PKCE(C 档)不做、不留 seam、不留枚举位** —— Anthropic 侧
+ * 条款明文禁止第三方代理其订阅凭证,而公开实现全都依赖冒用官方 client_id + 伪装 UA。本文件里
+ * 因此**只有** api_key 与 device_code 两轨,没有第三个 kind 位。
+ *
+ * ## 能力真值 = 目录键 ∧ 包内实现(两者与)
+ *
+ * 目录(design/165 §2)里的 `deviceAuth` 键**只是能力开关**,client_id 与端点**绝不目录化下发**
+ * (远端可改鉴权端点 = 钓鱼面)。所以 UI 是否显示「Sign in with device code」的判据是
+ * `supportsDeviceCodeAuth(id, preset.deviceAuth)`:
+ *   · 目录说有、包里没有 ⇒ **不显示**(防目录先行造出一个点了没反应的假 affordance);
+ *   · 包里有、目录没说 ⇒ **不显示**(那家还没被目录确认支持)。
+ *
+ * ## 🔴 `DEVICE_AUTH_PROVIDERS` 今天是**空表**(宁空勿假 —— 这是有意的,不是没写完)
+ *
+ * 设计档写「首发 1 家:GitHub Copilot 形」。落码时的事实是:device flow 需要一个 **client_id**,
+ * 而公开可查到的 Copilot client_id 全部是**别的编辑器插件自己的** app id(copilot.vim / VS Code
+ * 扩展)。把它们编进我们的包 = 以别人的 app 身份向 GitHub 发起授权,与 §6 判 C 档出局时用的
+ * **同一条判据**(「冒用官方 client_id」是主动欺骗,不是灰区)。我们自己名下的 OAuth app 尚未
+ * 申请 ⇒ 这一格的诚实值是**空**,而不是先填一个能跑的别人的号。
+ *
+ * 空表不是把这条腿废了:轮询器、退避、上限、终态词表全部在位并被门覆盖(门用一份合成 descriptor
+ * 跑真 HTTP)。**注册一家 = 往这张表加一行**,零代码改动。在那之前 `supportsDeviceCodeAuth`
+ * 对每一家如实返回 false,UI 不显示该选项 —— 这正是「能力真值 = 两者与」自带的正确降级。
+ *
+ * ## key 到手之后
+ *
+ * 🔴 **落盘不在包内做**。`poll()` 把 key 原样返给宿主,宿主走**与手填完全相同的那条路径**
+ * (壳 = `applyOnboard.ts` 写 settings `env.MODEL_API_KEY`)。两树都没有 auth.json 实体,
+ * 本文件也不新建任何持久面(design/166 §5 复核 M4:零新持久面,禁造)。
+ */
+import type { ProviderPreset, ProviderDeviceAuthHint } from './providerPresets.js';
+/**
+ * 一个 provider 可用的凭证轨。
+ * `api_key` 是现状唯一轨(手填,env 名来自 preset.authEnv);`device_code` 是 B 档新轨。
+ */
+export type ProviderAuthMethod = {
+    kind: 'api_key';
+    env: string;
+} | {
+    kind: 'device_code';
+    providerId: string;
+};
+/**
+ * 设备码端点三件套 —— **编译进包**(design/165 §2 红线:client_id / token 端点 / authorize 端点
+ * 一律不进目录)。
+ */
+export interface DeviceCodeEndpoints {
+    clientId: string;
+    /** RFC 8628 device authorization endpoint。 */
+    deviceCodeUrl: string;
+    /** token endpoint(轮询这一个)。 */
+    tokenUrl: string;
+    /** 申请的 scope(留空 = 不发这个参数)。 */
+    scope?: string;
+}
+/** 包内登记的一家设备码 provider。 */
+export interface DeviceAuthProvider {
+    /** 与目录/preset 的 `id` 同一个命名空间(用户 settings 里的持久引用)。 */
+    providerId: string;
+    label: string;
+    endpoints: DeviceCodeEndpoints;
+}
+/**
+ * 包内实现的设备码 provider 表。
+ * 🔴 **今天是空的,理由见文件头**(宁空勿假:没有我们自己名下的 client_id 之前,填一行 = 冒用)。
+ * 加一家 = 加一行;端点必须 https(门 ④a 逐行校)。
+ */
+export declare const DEVICE_AUTH_PROVIDERS: readonly DeviceAuthProvider[];
+/** 包内是否实现了这一家(能力真值的一半)。 */
+export declare function deviceAuthProviderFor(providerId: string): DeviceAuthProvider | undefined;
+/**
+ * UI 是否显示「设备码登录」= **目录说有** ∧ **包里有实现**。
+ * 任一缺席 ⇒ false(见文件头「能力真值」段)。
+ */
+export declare function supportsDeviceCodeAuth(providerId: string, catalogHint: ProviderDeviceAuthHint | undefined): boolean;
+/**
+ * 一家 provider 摆给用户的轨(顺序 = UI 呈现序)。`api_key` 恒在;`device_code` 只在能力真值成立时出。
+ */
+export declare function providerAuthMethods(preset: ProviderPreset): ProviderAuthMethod[];
+/**
+ * 一次 `poll()` 的结局。
+ *
+ * 🔴 比设计档草案多两个终态,理由是诚实:草案只有 `pending|ok|expired`,于是
+ * 「用户点了拒绝」与「会话被本地取消」都只能冒充 `expired`(= 骗用户「过期了,再来一次」,
+ * 而事实是再来一次还会被拒 / 是他自己取消的)。两者各占一位:
+ *   · `denied`    —— 授权服务器说 access_denied;
+ *   · `cancelled` —— 本地调过 `cancel()`。
+ */
+export type DeviceCodeStatus = 'pending' | 'ok' | 'expired' | 'denied' | 'cancelled';
+export interface DeviceCodePollResult {
+    status: DeviceCodeStatus;
+    /** 只在 `ok` 时在场。🔴 宿主拿去走与手填同一条落盘路径;包内零持久面。 */
+    key?: string;
+    /** 人话细节(分诊用;绝不带 key、绝不带完整响应体)。 */
+    detail?: string;
+}
+/**
+ * 一次设备码会话。**宿主驱动**:UI 渲大字码 + URL,自己按 `intervalMs` 起节拍调 `poll()`
+ * (等待型判据,不固定拍)。包内不起定时器 —— 定时器是宿主资产(与 `TimersPort` 同一条纪律)。
+ */
+export interface DeviceCodeSession {
+    /** 用户要在浏览器里输入的大字码。 */
+    userCode: string;
+    /** 用户要打开的验证页。 */
+    verificationUrl: string;
+    /** 建议轮询间隔(毫秒)。429 / slow_down 之后会**变大**,宿主每拍都该重读这个值。 */
+    intervalMs: number;
+    /** 本会话的墙钟终点(min(服务端 expires_in, 15min 上限))。 */
+    expiresAtMs: number;
+    poll(): Promise<DeviceCodePollResult>;
+    cancel(): void;
+}
+/**
+ * 设备码流的宿主注入面。
+ * 🔴 `nowMs` **必填**:5s 间隔与 15min 上限都是墙钟判据,而本包绝不偷读时钟
+ * (与 `catalog.ts` / `AdapterContext.now` 同一口径)。宿主传 `() => Date.now()`。
+ */
+export interface DeviceCodeAuthOptions {
+    nowMs: () => number;
+    /** 传输注入口(缺省全局 `fetch`)。 */
+    fetchImpl?: typeof fetch;
+    /** 单次 HTTP 预算(缺省 `DEVICE_CODE_HTTP_TIMEOUT_MS`)。 */
+    timeoutMs?: number;
+}
+/** 轮询间隔下限(RFC 8628 建议 5s;服务端给更大的值时听服务端的)。 */
+export declare const DEVICE_CODE_MIN_INTERVAL_MS = 5000;
+/** 会话墙钟上限(design/166 §5:15min)。服务端 `expires_in` 更短时听服务端的。 */
+export declare const DEVICE_CODE_MAX_LIFETIME_MS: number;
+/** 429 / slow_down 的退避增量(RFC 8628 §3.5 就是「加 5 秒」)。 */
+export declare const DEVICE_CODE_BACKOFF_STEP_MS = 5000;
+/** 单次 HTTP 预算。 */
+export declare const DEVICE_CODE_HTTP_TIMEOUT_MS = 10000;
+/**
+ * 开一次设备码会话 —— **端点由调用方给**(包内表里那一行,或门的合成 descriptor)。
+ * 🔴 端点是**编译进包的常量**,不是远端数据,所以本函数不对它再做白名单;真正的门是
+ * 「client_id/端点绝不目录化下发」(design/165 §2 红线)+ 表内每行必须 https(门 ④a)。
+ *
+ * 失败(网络 / 非 2xx / 缺 user_code)⇒ **throw**(§C1 三选一里的 throw):开不出会话就是开不出,
+ * 绝不返回一个永远 pending 的假会话。
+ */
+export declare function openDeviceCodeSession(endpoints: DeviceCodeEndpoints, opts: DeviceCodeAuthOptions): Promise<DeviceCodeSession>;
+/**
+ * 按 providerId 开设备码会话(UI 入口)。
+ * 包内没有这一家 ⇒ **throw**(UI 本就不该显示这个选项;走到这里说明能力判据被绕过了)。
+ */
+export declare function beginDeviceCodeAuth(providerId: string, opts: DeviceCodeAuthOptions): Promise<DeviceCodeSession>;