@cjhyy/code-shell-core 0.6.0-rc.9 → 0.7.0

package/dist/credentials/access.js

@@ -0,0 +1,185 @@
+import { existsSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CredentialStore } from "./store.js";
+import { formatNetscapeCookies, parseCookieJar } from "./cookie-jar.js";
+import { summarizeOAuthCredentialSecret } from "./oauth.js";
+const COOKIE_FILE_PREFIX = "codeshell-cred-cookie-";
+const COOKIE_FILE_MAX_AGE_MS = 30 * 60 * 1000;
+let defaultCredentialAccess = null;
+export function setDefaultCredentialAccess(access) {
+    defaultCredentialAccess = access ?? null;
+}
+export function getCredentialAccess() {
+    return defaultCredentialAccess ?? localCredentialAccess;
+}
+export function createIpcCredentialAccess(transport) {
+    let snapshot = { revision: 0, entries: [] };
+    let nextId = 1;
+    const pending = new Map();
+    transport.onMessage((msg) => {
+        if ("method" in msg && msg.method === "desktop/credentialSnapshot") {
+            const params = msg.params;
+            if (params && typeof params.revision === "number" && Array.isArray(params.entries)) {
+                snapshot = {
+                    revision: params.revision,
+                    entries: params.entries,
+                };
+            }
+            return;
+        }
+        if (!("id" in msg) || "method" in msg)
+            return;
+        const id = String(msg.id);
+        const waiter = pending.get(id);
+        if (!waiter)
+            return;
+        pending.delete(id);
+        clearTimeout(waiter.timer);
+        if ("error" in msg && msg.error) {
+            waiter.reject(new Error(msg.error.message));
+        }
+        else {
+            waiter.resolve(msg.result);
+        }
+    });
+    const request = (method, params) => {
+        const id = `cred-${nextId++}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new Error(`${method} timed out`));
+            }, 30_000);
+            pending.set(id, { resolve, reject, timer });
+            transport.send({ jsonrpc: "2.0", id, method, params });
+        });
+    };
+    const entryFor = (cwd) => {
+        const key = cwd ?? "";
+        return snapshot.entries.find((entry) => (entry.cwd ?? "") === key);
+    };
+    return {
+        listMasked(cwd, scope) {
+            const entry = entryFor(cwd);
+            if (!entry)
+                return [];
+            return scope === "project" ? cloneMetadata(entry.project) : cloneMetadata(entry.full);
+        },
+        resolveMeta(cwd, id, scope) {
+            const entry = entryFor(cwd);
+            if (!entry)
+                return undefined;
+            const list = scope === "project" ? entry.project : entry.full;
+            return cloneMetadata(list).find((cred) => cred.id === id);
+        },
+        envExposures(cwd, scope) {
+            const entry = entryFor(cwd);
+            if (!entry)
+                return {};
+            return { ...(scope === "project" ? entry.envProject : entry.envFull) };
+        },
+        async resolveValue(req) {
+            const result = (await request("desktop/credentialResolve", req));
+            if (typeof result?.value !== "string")
+                throw new Error(`credential "${req.id}" is unavailable`);
+            return result.value;
+        },
+        async materializeCookie(req) {
+            const result = (await request("desktop/credentialMaterializeCookie", req));
+            if (typeof result?.cookiesFile !== "string" || typeof result.count !== "number") {
+                throw new Error(`cookie credential "${req.id}" is unavailable`);
+            }
+            return { cookiesFile: result.cookiesFile, count: result.count };
+        },
+    };
+}
+export function credentialAccessScope(scope) {
+    return scope === "full" || scope === undefined ? "full" : "project";
+}
+export function isCredentialSecretAvailable(secret) {
+    return typeof secret === "string" && secret.length > 0 && !secret.startsWith("enc:");
+}
+function toMetadata(cred) {
+    const secret = cred.secret;
+    const available = isCredentialSecretAvailable(secret);
+    const { secret: _secret, ...rest } = cred;
+    return {
+        ...rest,
+        hasSecret: available,
+        secretHint: available ? (secret.length > 4 ? `****${secret.slice(-4)}` : "****") : undefined,
+        ...(cred.type === "oauth" ? { oauthStatus: summarizeOAuthCredentialSecret(secret) } : {}),
+    };
+}
+function cloneMetadata(list) {
+    return list.map((cred) => ({ ...cred, meta: cred.meta ? { ...cred.meta } : undefined }));
+}
+function storeFor(cwd) {
+    return new CredentialStore(cwd);
+}
+export const localCredentialAccess = {
+    listMasked(cwd, scope) {
+        return storeFor(cwd).list(scope).map(toMetadata);
+    },
+    resolveMeta(cwd, id, scope) {
+        const cred = storeFor(cwd).resolve(id, scope);
+        return cred ? toMetadata(cred) : undefined;
+    },
+    envExposures(cwd, scope) {
+        const out = {};
+        const creds = storeFor(cwd).list(scope);
+        for (const cred of creds) {
+            const name = cred.exposeAsEnv?.trim();
+            if (name && isCredentialSecretAvailable(cred.secret))
+                out[name] = cred.secret;
+        }
+        return out;
+    },
+    async resolveValue(req) {
+        const cred = storeFor(req.cwd).resolve(req.id, req.scope);
+        if (!cred || !isCredentialSecretAvailable(cred.secret)) {
+            throw new Error(`credential "${req.id}" is unavailable`);
+        }
+        return cred.secret;
+    },
+    async materializeCookie(req) {
+        const cred = storeFor(req.cwd).resolve(req.id, req.scope);
+        if (!cred || cred.type !== "cookie" || !isCredentialSecretAvailable(cred.secret)) {
+            throw new Error(`cookie credential "${req.id}" is unavailable`);
+        }
+        return materializeCookieSecret(cred.id, cred.secret);
+    },
+};
+export function materializeCookieSecret(credentialId, secret) {
+    const jar = parseCookieJar(secret);
+    if (jar.length === 0)
+        throw new Error("cookie jar is empty or invalid");
+    const file = join(tmpdir(), `${COOKIE_FILE_PREFIX}${safeFileName(credentialId)}-${process.pid}-${randomUUID()}.txt`);
+    writeFileSync(file, formatNetscapeCookies(jar), { mode: 0o600 });
+    return { cookiesFile: file, count: jar.length };
+}
+export function sweepStaleCredentialCookieFiles(now = Date.now()) {
+    const dir = tmpdir();
+    try {
+        if (!existsSync(dir))
+            return;
+        for (const f of readdirSync(dir)) {
+            if (!f.startsWith(COOKIE_FILE_PREFIX))
+                continue;
+            const p = join(dir, f);
+            try {
+                if (now - statSync(p).mtimeMs > COOKIE_FILE_MAX_AGE_MS)
+                    rmSync(p, { force: true });
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function safeFileName(s) {
+    return s.replace(/[^a-zA-Z0-9_.-]/g, "_");
+}

package/dist/credentials/index.d.ts

@@ -1,7 +1,9 @@
 export { CredentialStore } from "./store.js";
 export type { CredentialScope, MaskedCredential } from "./store.js";
 export { type EncryptionCipher, PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./cipher.js";
-export type { Credential, CredentialType, CredentialStoreFile } from "./types.js";
+export { getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, isCredentialSecretAvailable, materializeCookieSecret, type CredentialAccess, type CredentialAccessScope, type CredentialMetadata, type CredentialSnapshot, type CredentialSnapshotEntry, } from "./access.js";
+export type { Credential, CredentialType, CredentialStoreFile, OAuthCredentialPublicStatus, OAuthCredentialSecret, } from "./types.js";
+export { buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, summarizeOAuthCredentialSecret, type OAuthClockOptions, type OAuthRefreshHandler, type OAuthRefreshRequest, } from "./oauth.js";
 export { formatNetscapeCookies, parseCookieJar, type CookieLike } from "./cookie-jar.js";
 export { useCredentialToolDef, useCredentialToolDefFor, useCredentialTool, sweepStaleCredentialCookies, } from "./use-credential-tool.js";
 export { credentialUseGate } from "./use-gate.js";

package/dist/credentials/index.js

@@ -1,5 +1,7 @@
 export { CredentialStore } from "./store.js";
 export { PlaintextCipher, setDefaultCredentialCipher, getDefaultCredentialCipher, } from "./cipher.js";
+export { getCredentialAccess, setDefaultCredentialAccess, createIpcCredentialAccess, localCredentialAccess, credentialAccessScope, isCredentialSecretAvailable, materializeCookieSecret, } from "./access.js";
+export { buildOAuthRefreshRequest, isOAuthAccessTokenExpired, oauthCredentialStatus, parseOAuthCredentialSecret, summarizeOAuthCredentialSecret, } from "./oauth.js";
 export { formatNetscapeCookies, parseCookieJar } from "./cookie-jar.js";
 export { useCredentialToolDef, useCredentialToolDefFor, useCredentialTool, sweepStaleCredentialCookies, } from "./use-credential-tool.js";
 export { credentialUseGate } from "./use-gate.js";

package/dist/credentials/inject-credential-tool.d.ts

@@ -12,9 +12,11 @@
  */
 import type { ToolDefinition } from "../types.js";
 import type { ToolContext } from "../tool-system/context.js";
+import { type SettingsScope } from "../settings/manager.js";
 export declare const injectCredentialToolDef: ToolDefinition;
 /** 该工具仅在有 cookie 凭证 且 宿主接了注入回调时才可见(BUILTIN_TOOL_GUARDS)。 */
-export declare function isInjectCredentialAvailable(cwd: string): boolean;
+export declare function isInjectCredentialAvailable(cwd: string, settingsScope?: SettingsScope): boolean;
 export declare function injectCredentialTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 /** 测试钩子:清空会话 allow 集。 */
 export declare function __resetInjectCredentialSessionAllowForTests(): void;
+export declare function clearInjectCredentialSessionAllow(sessionId: string): void;

package/dist/credentials/inject-credential-tool.js

@@ -10,9 +10,9 @@
  * 跨进程:实际的 restoreCookiesToBrowser 在 desktop main(core 够不到 Electron
  * session),经 `ctx.injectCredentialToBrowser` 回调(宿主注入,镜像 askUser)触发。
  */
-import { CredentialStore } from "./store.js";
 import { credentialUseGate, } from "./use-gate.js";
 import { SettingsManager } from "../settings/manager.js";
+import { credentialAccessScope, getCredentialAccess } from "./access.js";
 const TOOL_NAME = "InjectCredential";
 const BASE_DESCRIPTION = "Inject a stored COOKIE credential into the built-in browser to restore its " +
     "login state, so you can then drive the page as that logged-in account with the " +
@@ -62,9 +62,14 @@ function sessionAllowFor(ctx) {
     }
     return set;
 }
-function readAutoApprove(cwd) {
+// CredentialStore only distinguishes full user+project from project-only.
+// Isolated engines must be at least as restrictive as project-scoped engines.
+function credentialScope(scope) {
+    return credentialAccessScope(scope);
+}
+function readAutoApprove(cwd, scope) {
     try {
-        const s = new SettingsManager(cwd, "full").get();
+        const s = new SettingsManager(cwd, scope === "full" ? "full" : "project").get();
         return s.credentialUse?.autoApprove === true;
     }
     catch {
@@ -72,9 +77,11 @@ function readAutoApprove(cwd) {
     }
 }
 /** 该工具仅在有 cookie 凭证 且 宿主接了注入回调时才可见(BUILTIN_TOOL_GUARDS)。 */
-export function isInjectCredentialAvailable(cwd) {
+export function isInjectCredentialAvailable(cwd, settingsScope) {
     try {
-        return new CredentialStore(cwd).listMasked().some((c) => c.type === "cookie");
+        return getCredentialAccess()
+            .listMasked(cwd, credentialScope(settingsScope))
+            .some((c) => c.type === "cookie");
     }
     catch {
         return false;
@@ -82,10 +89,14 @@ export function isInjectCredentialAvailable(cwd) {
 }
 export async function injectCredentialTool(args, ctx) {
     const cwd = ctx?.cwd ?? process.cwd();
+    const scope = credentialScope(ctx?.settingsScope);
     const id = typeof args.id === "string" ? args.id.trim() : "";
     const purpose = typeof args.purpose === "string" ? args.purpose : undefined;
     if (!id) {
-        return json({ kind: "error", error: "缺少 id。先用 UseCredential(无参)列出凭证,再用 cookie 凭证的 id 调本工具。" });
+        return json({
+            kind: "error",
+            error: "缺少 id。先用 UseCredential(无参)列出凭证,再用 cookie 凭证的 id 调本工具。",
+        });
     }
     if (!ctx?.injectCredentialToBrowser) {
         return json({
@@ -93,17 +104,22 @@ export async function injectCredentialTool(args, ctx) {
             error: "当前环境无内置浏览器(headless/无面板),无法注入。请改用 UseCredential 取 cookie 走 HTTP 请求。",
         });
     }
-    const cred = new CredentialStore(cwd).resolve(id);
+    const cred = getCredentialAccess().resolveMeta(cwd, id, scope);
     if (!cred) {
-        return json({ kind: "error", error: `凭证不存在: "${id}"。调用 UseCredential(无参)可列出可用凭证。` });
+        return json({
+            kind: "error",
+            error: `凭证不存在: "${id}"。调用 UseCredential(无参)可列出可用凭证。`,
+        });
     }
     if (cred.type !== "cookie") {
         return json({ kind: "error", error: `凭证「${cred.label}」不是 cookie 类型,不能注入浏览器。` });
     }
     // 过门:复用三档,但用该凭证的 autoInjectByAI(不是 autoUseByAI)。
-    const ask = ctx.askUser ? (q, opts) => ctx.askUser(q, opts) : undefined;
+    const ask = ctx.askUser
+        ? (q, opts) => ctx.askUser(q, opts)
+        : undefined;
     const decision = await credentialUseGate({ id: cred.id, label: cred.label, purpose }, {
-        autoApprove: readAutoApprove(cwd),
+        autoApprove: readAutoApprove(cwd, scope),
         credentialAutoUse: cred.autoInjectByAI === true,
         sessionAllow: sessionAllowFor(ctx),
         ask,
@@ -115,7 +131,7 @@ export async function injectCredentialTool(args, ctx) {
         return json({ kind: "error", error: msg });
     }
     // 跨进程触发宿主注入。
-    const res = await ctx.injectCredentialToBrowser(cred.id);
+    const res = await ctx.injectCredentialToBrowser(cred.id, scope);
     if (!res.ok) {
         return json({ kind: "error", error: res.error ?? "注入浏览器失败(宿主未返回成功)。" });
     }
@@ -128,3 +144,6 @@ function json(r) {
 export function __resetInjectCredentialSessionAllowForTests() {
     injectSessionAllowByEngine.clear();
 }
+export function clearInjectCredentialSessionAllow(sessionId) {
+    injectSessionAllowByEngine.delete(sessionId);
+}

package/dist/credentials/oauth.d.ts

@@ -0,0 +1,20 @@
+import type { OAuthCredentialPublicStatus, OAuthCredentialSecret } from "./types.js";
+export interface OAuthClockOptions {
+    now?: number | (() => number);
+    skewMs?: number;
+}
+export interface OAuthRefreshRequest {
+    credentialId: string;
+    tokenEndpoint: string;
+    refreshToken: string;
+    clientId?: string;
+    clientSecret?: string;
+    scope?: string;
+    scopes?: string[];
+}
+export type OAuthRefreshHandler = (req: OAuthRefreshRequest) => Promise<OAuthCredentialSecret>;
+export declare function parseOAuthCredentialSecret(secret: string): OAuthCredentialSecret;
+export declare function isOAuthAccessTokenExpired(secret: Pick<OAuthCredentialSecret, "accessToken" | "expiresAt">, opts?: OAuthClockOptions): boolean;
+export declare function oauthCredentialStatus(secret: Pick<OAuthCredentialSecret, "accessToken" | "expiresAt">, opts?: OAuthClockOptions): Pick<OAuthCredentialPublicStatus, "state" | "expiresAt" | "expiresInMs">;
+export declare function buildOAuthRefreshRequest(credentialId: string, secret: OAuthCredentialSecret): OAuthRefreshRequest | undefined;
+export declare function summarizeOAuthCredentialSecret(secret: string | undefined, opts?: OAuthClockOptions): OAuthCredentialPublicStatus;

package/dist/credentials/oauth.js

@@ -0,0 +1,114 @@
+const DEFAULT_OAUTH_REFRESH_SKEW_MS = 60_000;
+function nowMs(opts = {}) {
+    if (typeof opts.now === "function")
+        return opts.now();
+    if (typeof opts.now === "number")
+        return opts.now;
+    return Date.now();
+}
+function optionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function optionalStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = value.filter((x) => typeof x === "string" && x.length > 0);
+    return out.length > 0 ? out : undefined;
+}
+function parseExpiresAt(value) {
+    if (!value)
+        return undefined;
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms)) {
+        throw new Error(`OAuth credential secret has invalid expiresAt: ${value}`);
+    }
+    return ms;
+}
+export function parseOAuthCredentialSecret(secret) {
+    let parsed;
+    try {
+        parsed = JSON.parse(secret);
+    }
+    catch {
+        throw new Error("OAuth credential secret must be a JSON object");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("OAuth credential secret must be a JSON object");
+    }
+    const raw = parsed;
+    if (raw.version !== undefined && raw.version !== 1) {
+        throw new Error("OAuth credential secret version must be 1");
+    }
+    const accessToken = optionalString(raw.accessToken);
+    if (!accessToken) {
+        throw new Error("OAuth credential secret must include accessToken");
+    }
+    const expiresAt = optionalString(raw.expiresAt);
+    parseExpiresAt(expiresAt);
+    return {
+        version: raw.version === 1 ? 1 : undefined,
+        accessToken,
+        refreshToken: optionalString(raw.refreshToken),
+        expiresAt,
+        tokenType: optionalString(raw.tokenType),
+        scope: optionalString(raw.scope),
+        scopes: optionalStringArray(raw.scopes),
+        tokenEndpoint: optionalString(raw.tokenEndpoint),
+        clientId: optionalString(raw.clientId),
+        clientSecret: optionalString(raw.clientSecret),
+    };
+}
+export function isOAuthAccessTokenExpired(secret, opts = {}) {
+    const expiresAtMs = parseExpiresAt(secret.expiresAt);
+    if (expiresAtMs === undefined)
+        return false;
+    const skewMs = opts.skewMs ?? DEFAULT_OAUTH_REFRESH_SKEW_MS;
+    return expiresAtMs <= nowMs(opts) + skewMs;
+}
+export function oauthCredentialStatus(secret, opts = {}) {
+    const expiresAtMs = parseExpiresAt(secret.expiresAt);
+    if (expiresAtMs === undefined) {
+        return { state: "valid", expiresAt: undefined, expiresInMs: undefined };
+    }
+    const expiresInMs = expiresAtMs - nowMs(opts);
+    return {
+        state: isOAuthAccessTokenExpired(secret, opts) ? "expired" : "valid",
+        expiresAt: secret.expiresAt,
+        expiresInMs,
+    };
+}
+export function buildOAuthRefreshRequest(credentialId, secret) {
+    if (!secret.refreshToken || !secret.tokenEndpoint)
+        return undefined;
+    return {
+        credentialId,
+        tokenEndpoint: secret.tokenEndpoint,
+        refreshToken: secret.refreshToken,
+        clientId: secret.clientId,
+        clientSecret: secret.clientSecret,
+        scope: secret.scope,
+        scopes: secret.scopes,
+    };
+}
+export function summarizeOAuthCredentialSecret(secret, opts = {}) {
+    if (!secret)
+        return { state: "missing" };
+    try {
+        const parsed = parseOAuthCredentialSecret(secret);
+        const status = oauthCredentialStatus(parsed, opts);
+        return {
+            ...status,
+            hasRefreshToken: Boolean(parsed.refreshToken),
+            tokenEndpoint: parsed.tokenEndpoint,
+            clientId: parsed.clientId,
+            scope: parsed.scope,
+            scopes: parsed.scopes,
+        };
+    }
+    catch (err) {
+        return {
+            state: "invalid",
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/dist/credentials/store.d.ts

@@ -5,6 +5,7 @@ export interface MaskedCredential extends Omit<Credential, "secret"> {
     hasSecret: boolean;
     /** 形如 `****abcd`,绝不含完整明文。 */
     secretHint?: string;
+    oauthStatus?: import("./types.js").OAuthCredentialPublicStatus;
 }
 /**
  * 两层凭证库,镜像 SettingsManager 的 user(~/.code-shell)/ project(<cwd>/.code-shell)

package/dist/credentials/store.js

@@ -1,8 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { getDefaultCredentialCipher } from "./cipher.js";
 import { logger } from "../logging/logger.js";
+import { summarizeOAuthCredentialSecret } from "./oauth.js";
 /** 测试可经 process.env.HOME 覆盖(镜像 settings/manager.ts userHome)。 */
 function userHome() {
     return process.env.HOME ?? homedir();
@@ -178,6 +179,7 @@ export class CredentialStore {
                 // than 4, so those chars aren't the whole secret. `"ab".slice(-4)` is
                 // "ab", so a short secret would otherwise leak in full through the hint.
                 secretHint: secret ? (secret.length > 4 ? `****${secret.slice(-4)}` : "****") : undefined,
+                ...(c.type === "oauth" ? { oauthStatus: summarizeOAuthCredentialSecret(secret) } : {}),
             };
         });
     }

package/dist/credentials/types.d.ts

@@ -3,7 +3,40 @@
  * - token/link 第一期已有;cookie 第二期改为「具名 cookie 凭证」进库
  *   (用户主动按域拓取存,支持同域多账号),见 credential-use-gate 设计稿。
  */
-export type CredentialType = "token" | "link" | "cookie";
+export type CredentialType = "token" | "link" | "cookie" | "oauth";
+export interface OAuthCredentialSecret {
+    /** Schema version for the JSON stored in Credential.secret. */
+    version?: 1;
+    /** Current access token. MCP HTTP auth sends this as Authorization: Bearer. */
+    accessToken: string;
+    /** Optional refresh token. Stored encrypted with the credential secret. */
+    refreshToken?: string;
+    /** ISO-8601 expiry time for accessToken. Missing means "unknown", not expired. */
+    expiresAt?: string;
+    /** Upstream token type, usually Bearer. Stored for round-trip/debugging. */
+    tokenType?: string;
+    /** Space-delimited OAuth scope string returned by many token endpoints. */
+    scope?: string;
+    /** Structured scopes used by first-party UI/catalog metadata. */
+    scopes?: string[];
+    /** Token endpoint to use when a future refresh flow is wired. */
+    tokenEndpoint?: string;
+    /** OAuth client id associated with this token. */
+    clientId?: string;
+    /** Optional confidential client secret, if the integration requires it. */
+    clientSecret?: string;
+}
+export interface OAuthCredentialPublicStatus {
+    state: "valid" | "expired" | "missing" | "invalid";
+    expiresAt?: string;
+    expiresInMs?: number;
+    hasRefreshToken?: boolean;
+    tokenEndpoint?: string;
+    clientId?: string;
+    scope?: string;
+    scopes?: string[];
+    error?: string;
+}
 export interface Credential {
     /**
      * 引用键,kebab-case,全局/项目两层内唯一。
@@ -19,6 +52,7 @@ export interface Credential {
      * 密文(UI 只显示掩码):
      * - token: token 值;
      * - link: client id/secret 等的 JSON 字符串;
+     * - oauth: OAuthCredentialSecret JSON 字符串(access/refresh/expiry/client info);
      * - cookie: 序列化的 cookie jar(JSON.stringify 的 ElectronCookieLike[])。
      */
     secret?: string;
@@ -39,8 +73,8 @@ export interface Credential {
     /**
      * link: 业务方 app 注册地址;cookie: 拓取所用平台与主域 + 抓取范围 + 切换策略。
      * - scope="all" 表示该 jar 是整分区全量抓的(切换时整包导回);缺省/"domain" = 仅该域。
-     * - switchMode 决定「切换」时怎么写回浏览器:"clear"(默认)先清空整分区再注入(干净换号);
-     *   "merge" 只覆盖同名 cookie、保留分区里其他站(不踢掉别的登录态)。
+     * - switchMode 决定「切换」时怎么写回浏览器:"merge"(默认)只覆盖同名 cookie、保留
+     *   分区里其他站(不踢掉别的登录态);"clear" 先清空整分区再注入(干净换号,需显式选)。
      */
     meta?: {
         appUrl?: string;
@@ -48,6 +82,18 @@ export interface Credential {
         domain?: string;
         scope?: "domain" | "all";
         switchMode?: "clear" | "merge";
+        /** OAuth provider/integration id, e.g. "figma". */
+        oauthProvider?: string;
+        /** OAuth authorization endpoint, used by UI/login launchers. */
+        authUrl?: string;
+        /** OAuth token endpoint, duplicated from secret for non-secret UI display. */
+        tokenEndpoint?: string;
+        /** OAuth client id, duplicated from secret for non-secret UI display. */
+        clientId?: string;
+        /** OAuth scopes requested for this credential. */
+        scopes?: string[];
+        /** Last successful refresh time; refresh wiring is reserved for a later step. */
+        lastRefreshAt?: string;
     };
 }
 export interface CredentialStoreFile {

package/dist/credentials/use-credential-tool.d.ts

@@ -7,7 +7,8 @@
  *     - token/link → `{ kind: "value", value }`
  *     - cookie     → 就地写临时 cookies.txt(0600),返回 `{ kind: "cookie", cookiesFile, count }`
  *
- * 取值全部 core 直读 CredentialStore(cookie 值第二期已进库),无跨进程。
+ * desktop 下通过 host credential access IPC 按需解析 secret；headless/SDK
+ * 仍可使用本地 CredentialStore。
  * 集中在 core/src/credentials/ 下,只经 ToolDefinition 注册 + ToolContext.askUser 耦合 core,
  * 满足设计稿 §1「可整块外移」约束。
  */
@@ -25,5 +26,12 @@ export declare function useCredentialToolDefFor(cwd: string): ToolDefinition;
  */
 export declare function sweepStaleCredentialCookies(now?: number): void;
 export declare function useCredentialTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function useCredentialBuiltinTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | {
+    result: string;
+    sensitive: true;
+    displayResult: string;
+    transcriptResult: string;
+}>;
 /** 测试钩子:清空会话 allow 集(避免跨用例污染)。 */
 export declare function __resetCredentialSessionAllowForTests(): void;
+export declare function clearCredentialSessionAllow(sessionId: string): void;