dsh-mcp-connector 0.2.26 → 0.2.27

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 ## [Unreleased]
 
+## [0.2.27] - 2026-08-28
+
+### Fixed
+
+- OAuth Refresh Token 轮换不再依赖 DSH JSON storage 的进程内缓存；新增每 Grant 独立原子日志和跨进程锁，Desktop 与 `dsh web` 同时运行时只轮换一次 Token，等待方直接采用最新凭据。
+- DSH Desktop 没有插件市场设置分区时，更新入口不再停留在普通设置页；改为中性的“查看更新方式”，并在确认无市场分区后打开 npm 安装说明。
+
+### Security
+
+- 跨进程 Grant journal 位于 `$DSH_HOME/storages/mcp_connector_grants_v1`，采用 0700 目录、0600 文件和同目录原子替换；Token 不进入运行日志、页面或 Git 仓库。
+
 ## [0.2.26] - 2026-08-27
 
 ### Fixed
@@ -426,7 +437,8 @@
 - 外部 URL 与导入 Header 执行安全校验。
 - iframe 消息校验同源和消息来源。
 
-[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.26...HEAD
+[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.27...HEAD
+[0.2.27]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.26...v0.2.27
 [0.2.26]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.25...v0.2.26
 [0.2.25]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.24...v0.2.25
 [0.2.24]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.23...v0.2.24

package/README.en.md

@@ -25,14 +25,14 @@ Browse and install MCP connectors from different providers in DeepSeek Harness D
 - Credential and MCP initialize validation before HTTP API-key connectors are saved as installed, plus declarative multi-field credential-to-env bindings for marketplace stdio connectors.
 - Dynamic tool discovery grouped by MCP server, including descriptions, search, batched rendering, and an independent scroll region.
 - Curated prompt templates that can open a DSH conversation and prefill its draft; missing variables are requested before the prompt is sent.
-- Persistent connection lifecycle management: restore on restart, enable/disable, disconnect, retry transient OAuth refresh failures with bounded backoff, and revoke authorization. Cards declaring issuer-level sharing reuse one grant; DCR client secrets remain local to that grant.
+- Persistent connection lifecycle management: restore on restart, enable/disable, disconnect, retry transient OAuth refresh failures with bounded backoff, and revoke authorization. Cards declaring issuer-level sharing reuse one grant; a cross-process lock and per-grant atomic journal prevent Desktop and Web hosts from consuming or overwriting the same rotating refresh token.
 - Built-in, remote, and local catalogs with `published` and `featured` controls.
 - A standalone remote Registry, allowing new marketplace cards to appear after refresh without publishing a new npm version.
-- Plugin version and one-click updates: version discovery is independent of the installation source, while an Update Provider adapter layer negotiates safe mutation capabilities. DSH Market API v1 is the first adapter and supports progress, normalized failures, rollback, and capability-gated restart/refresh actions; without a compatible provider, the UI falls back to the current plugin marketplace or npm.
+- Plugin version and one-click updates: version discovery is independent of the installation source, while an Update Provider adapter layer negotiates safe mutation capabilities. DSH Market API v1 is the first adapter and supports progress, normalized failures, rollback, and capability-gated restart/refresh actions. Without a compatible provider the UI offers update instructions; if Desktop has no plugin-market section, it opens the npm package page instead of leaving the user on generic Settings.
 - Explicit, non-destructive migration from the two earlier Qichacha OAuth plugins, plus active-plugin conflict detection that blocks duplicate server management and credential overwrites.
 
 <!-- catalog-stats:start -->
-As of 2026-08-25, the public Registry publishes 78 connector descriptors. After merging and deduplicating them with the 4 bundled Qichacha cards, the Marketplace exposes 82 cards across 9 business categories. Recommendations remain limited to the four Qichacha cards, PKULaw, and Wind, for 6 featured cards in total. The Registry evolves independently; the badge shown after a client refresh and the live badges above are the authoritative current counts.
+As of 2026-08-27, the public Registry publishes 79 connector descriptors. After merging and deduplicating them with the 4 bundled Qichacha cards, the Marketplace exposes 83 cards across 9 business categories. Recommendations remain limited to the four Qichacha cards, PKULaw, and Wind, for 6 featured cards in total. The Registry evolves independently; the badge shown after a client refresh and the live badges above are the authoritative current counts.
 <!-- catalog-stats:end -->
 
 ## Interface and demo
@@ -118,7 +118,7 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/DESKTOP-E2E.md](d
 
 ## Security and limitations
 
-- Credentials are stored only in the DSH storage domain and are not written to the catalog, Git repository, or conversation history.
+- Credentials stay inside the local DSH storage boundary: connection records use the storage domain, while rotating OAuth credentials are also saved in `$DSH_HOME/storages/mcp_connector_grants_v1` so stale host snapshots cannot overwrite them. The directory is mode 0700 and records are mode 0600; credentials are never written to the catalog, Git repository, page, logs, or conversation history.
 - Failed API key/token validation is not persisted; authentication, timeout, DNS, and TLS/network errors are reported separately.
 - External URLs must use HTTPS; HTTP is allowed only for loopback development.
 - Remote descriptors and catalogs are limited to 2 MiB, Web API requests to 1 MiB, and imported JSON is scanned for credential fields before normalization.

package/README.md

@@ -25,7 +25,7 @@
 - Prompt 模板：使用 `{{company}}` 等变量，发送前填写真实查询主体。
 - 三种接入：OAuth 2.0 PKCE、自定义 HTTP/stdio、导入 `mcpServers` JSON；也支持从连接器描述 URL 安装。OAuth 动态注册兼容公共客户端以及 `client_secret_post` / `client_secret_basic` 机密客户端。
 - 市场 Bearer/API Key 连接器先执行 MCP initialize 连通性与凭据校验，全部 HTTP Server 通过后才持久化凭据并进入“已安装”；stdio 卡片可声明多个本机凭据字段及其环境变量映射。
-- 生命周期管理：连接持久化、重启恢复、启停、断开、OAuth 自动刷新/退避恢复与撤销；同 issuer 卡片可共享一次授权，DCR 返回的客户端密钥与 Token 一同只保存在本机。
+- 生命周期管理：连接持久化、重启恢复、启停、断开、OAuth 自动刷新/退避恢复与撤销；同 issuer 卡片共享一次授权，跨进程锁与独立原子 Grant journal 防止 Desktop/Web 并行时重复消耗 Refresh Token。
 - 目录运营：内置目录、远程 registry、本地覆盖，支持 `published` 上下架与 `featured` 精选。
 - 独立远程 Registry：新市场卡片合并后客户端刷新即可见，无需重新发布 npm；远程不可用时自动回退内置目录。
 - 插件版本与一键更新：版本发现独立于安装来源；页面通过 Update Provider 适配层探测安全更新能力。DSH Market API v1 是首个适配器，支持进度、稳定失败码、回滚及按宿主能力提供的重启/刷新操作；无可用 Provider 时回退到当前插件市场或 npm。
@@ -34,7 +34,7 @@
 - 对话工具：`mcp_connector_catalog`、`connect`、`configure`、`import_json`、`install_from_url`、`status`、`health_check`、`set_enabled`、`disconnect`、`refresh_catalog`、`publish`、`tools_list`。
 
 <!-- catalog-stats:start -->
-截至 2026-08-25，公共 Registry 已发布 78 条连接器描述；与随包的 4 张企查查卡片合并去重后，市场页可浏览 82 张卡片，覆盖企业数据、金融投资、法律合规、开发工具、办公协作、调研分析、设计创意、效率工具、其他 9 类。推荐位严格保留 4 张企查查卡片、北大法宝和 Wind，共 6 张；其他连接器按业务分类展示。Registry 可独立持续更新，实际数量以客户端刷新后的市场页签徽标和上方实时统计徽标为准。
+截至 2026-08-27，公共 Registry 已发布 79 条连接器描述；与随包的 4 张企查查卡片合并去重后，市场页可浏览 83 张卡片，覆盖企业数据、金融投资、法律合规、开发工具、办公协作、调研分析、设计创意、效率工具、其他 9 类。推荐位严格保留 4 张企查查卡片、北大法宝和 Wind，共 6 张；其他连接器按业务分类展示。Registry 可独立持续更新，实际数量以客户端刷新后的市场页签徽标和上方实时统计徽标为准。
 <!-- catalog-stats:end -->
 
 ## 界面与演示
@@ -117,7 +117,7 @@ stdio 传输的架构、透传边界与安全约束见 [docs/STDIO-SUPPORT.md](d
 
 ## 安全与限制
 
-- 凭证只持久化在 DSH storage domain，不进入目录、Git 仓库或对话历史。
+- 凭证只持久化在本机 DSH storage 边界：连接记录使用 storage domain，OAuth 轮换凭据同步保存到 `$DSH_HOME/storages/mcp_connector_grants_v1`。该目录为 0700、文件为 0600；凭证不进入市场目录、Git 仓库、页面、日志或对话历史。
 - 市场 Key/Token 校验失败时不写入 storage domain；鉴权、超时、DNS、TLS/网络错误会分类提示。
 - 外部 URL 仅允许 HTTPS，HTTP 仅允许回环地址；导入配置会校验 URL 与 Header。
 - 远程目录/描述响应限制 2 MiB，Web API 请求限制 1 MiB；原始 JSON 在归一化前扫描凭据字段。

package/docs/PLUGIN-UPDATE.md

@@ -14,7 +14,7 @@ MCP连接器把“刷新连接器目录”和“升级插件代码”视为两
 
 每个 Provider 适配器只硬编码自己的 capabilities 入口，其余更新、任务、回滚和重启端点均从能力响应中读取。客户端只接受当前 DSH 页面的相对同源端点，拒绝跨域 URL、协议不匹配、缺少必要端点或未声明 `features.update` 的 Provider。
 
-DSH Market 适配器从 `GET /dsh-market/api/v1/capabilities` 开始，要求 `schema: dsh-market/update-api/v1` 与 `apiVersion: 1`。未安装任何可用 Provider、接口返回 404、协议不兼容或检查失败时，页面不会尝试私有更新路由，而是回退到“前往插件市场”；设置入口不可用时再打开 npm 包页面。
+DSH Market 适配器从 `GET /dsh-market/api/v1/capabilities` 开始，要求 `schema: dsh-market/update-api/v1` 与 `apiVersion: 1`。未安装任何可用 Provider、接口返回 404、协议不兼容或检查失败时，页面不会尝试私有更新路由，而是显示“查看更新方式”。页面会先尝试打开当前宿主的插件市场；设置入口不可用，或 DSH Desktop 设置中实际没有插件市场分区时，打开 npm 包页面与安装命令说明。
 
 ## 更新流程
 

package/docs/USER-GUIDE.md

@@ -42,7 +42,7 @@ dsh web
 - **已安装**：查看已经保存到本机的连接，页签徽标显示连接数。
 - **搜索**：按名称、服务商、简介和标签查找。
 - **添加连接**：导入 JSON、手动配置 HTTP/stdio，或从市场描述 URL 安装。
-- **版本与更新提示**：标题旁显示当前插件版本，版本检查不依赖安装所用的插件市场。检测到 npm 有新版本且当前宿主存在兼容 Update Provider 时，可在当前页面一键更新并查看进度、失败原因和可用回滚。DSH Market API v1 是当前首个 Provider；无可用 Provider 时自动回退为“前往插件市场”或 npm 页面。
+- **版本与更新提示**：标题旁显示当前插件版本，版本检查不依赖安装所用的插件市场。检测到 npm 有新版本且当前宿主存在兼容 Update Provider 时，可在当前页面一键更新并查看进度、失败原因和可用回滚。DSH Market API v1 是当前首个 Provider；无可用 Provider 时显示“查看更新方式”，宿主没有插件市场分区时会打开 npm 安装说明。
 - **刷新连接器目录**：重新拉取 Registry 卡片，并更新连接健康状态；该操作不会升级 MCP连接器插件本身。
 
 ## 3. 浏览市场与分类
@@ -75,7 +75,7 @@ stdio 市场卡片也可能显示一个或多个凭据字段，例如 API Token
 
 OAuth 一键连接要求服务商支持标准 OAuth 2.1/PKCE 和公开元数据发现。动态客户端注册既支持无需客户端密钥的 `none`，也支持服务商签发密钥的 `client_secret_post` 与 `client_secret_basic`。客户端密钥仅与 OAuth Grant 一同保存在 DSH 本机，用于换取、刷新和撤销 Token；插件不会要求用户把 OAuth Token 或客户端密钥复制到聊天中。
 
-当市场描述声明 `grantSharing: "issuer"` 时，同一账号下相同 issuer、scope 和客户端鉴权方式的卡片共享一组 Grant。首次授权仍只启用用户点击的卡片；之后连接同组卡片会直接复用现有授权，不再重复打开 OAuth 页面。升级时会验证并自动归并旧版本留下的同 issuer 多份 Grant；多个 DSH 进程并发轮换 Refresh Token 时也会重读较新的本机持久化凭据后自动恢复。网络、OAuth 元数据发现或服务端 5xx 等暂时故障只进入“自动重试中”，确认本机也没有其他进程保存的新 Token，且明确收到 Refresh Token/客户端失效错误时，才进入“需重新授权”。
+当市场描述声明 `grantSharing: "issuer"` 时，同一账号下相同 issuer、scope 和客户端鉴权方式的卡片共享一组 Grant。首次授权仍只启用用户点击的卡片；之后连接同组卡片会直接复用现有授权，不再重复打开 OAuth 页面。升级时会验证并自动归并旧版本留下的同 issuer 多份 Grant；Desktop 与 `dsh web` 并发时，插件使用跨进程锁串行轮换，并从每 Grant 独立原子日志读取最新 Token，避免 DSH 整文件 storage 的旧进程快照覆盖新凭据。网络、OAuth 元数据发现或服务端 5xx 等暂时故障只进入“自动重试中”；确认 journal 中也没有更新 Token，且明确收到 Refresh Token/客户端失效错误时，才进入“需重新授权”。
 
 ## 5. 查看详情、Prompt 与工具
 

package/lib/client.js

@@ -440,7 +440,8 @@ window.__ModuleLoader__.load({
 
 		/**
 		 * DSH 暂未公开“打开指定设置分区”服务：只依赖稳定的 sidebar.settings
-		 * slot 和可访问文本打开插件市场，不依赖构建生成的 CSS 类名。
+		 * slot 和可访问文本打开插件市场。Desktop 可能根本没有市场分区，
+		 * 轮询结束后必须回退到 npm 安装说明，不能把用户留在普通设置页。
 		 */
 		function openDshPluginMarket(actions) {
 			const settingsHost = document.querySelector('[data-slot="sidebar.settings"]');
@@ -463,7 +464,11 @@ window.__ModuleLoader__.load({
 						return;
 					}
 					attempts += 1;
-					if (attempts < 20) window.setTimeout(selectMarket, 50);
+					if (attempts < 20) {
+						window.setTimeout(selectMarket, 50);
+						return;
+					}
+					window.open(NPM_PACKAGE_URL, "_blank", "noopener,noreferrer");
 				};
 				window.requestAnimationFrame(selectMarket);
 			}, 0);
@@ -793,7 +798,7 @@ window.__ModuleLoader__.load({
 								type: "button",
 								className: "mcpConnectorUpdateButton mcpConnectorUpdateSecondary",
 								onClick: () => openDshPluginMarket(actions),
-								children: "打开插件市场"
+								children: "查看更新方式"
 							})
 						]
 					});
@@ -860,7 +865,7 @@ window.__ModuleLoader__.load({
 								type: "button",
 								className: "mcpConnectorUpdateButton mcpConnectorUpdateSecondary",
 								onClick: () => openDshPluginMarket(actions),
-								children: "打开插件市场"
+								children: "查看更新方式"
 							})
 						]
 					});
@@ -887,7 +892,7 @@ window.__ModuleLoader__.load({
 					className: "mcpConnectorUpdateButton",
 					title: `npm 已发布 v${versionStatus?.latestVersion}`,
 					onClick: () => openDshPluginMarket(actions),
-					children: `前往插件市场更新到 v${versionStatus?.latestVersion}`
+					children: `查看 v${versionStatus?.latestVersion} 更新方式`
 				});
 			};
 			const src = window.location.origin + "/mcp-connector/ui/";

package/lib/grant-journal.js

@@ -0,0 +1,192 @@
+/**
+ * OAuth Grant 跨进程轮换日志。
+ *
+ * DSH JSON storage 以“每进程内存状态 + 整文件原子替换”实现，并不保证两个
+ * DSH Host 同时打开同一 domain 时的写入一致性。Refresh Token 又通常每次刷新都
+ * 会轮换，所以 Desktop 与 dsh web 并行时必须额外做跨进程串行化。
+ *
+ * 每个 Grant 独立文件，避免一个过期进程覆盖其他 Grant；文件与锁均位于
+ * $DSH_HOME/storages/mcp_connector_grants_v1，目录 0700、文件 0600。
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, mkdir, open, readFile, readdir, rename, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { grantRecordSchema } from './schema.js';
+
+const JOURNAL_VERSION = 1;
+const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
+const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
+
+function sleep(ms) {
+  return new Promise((done) => setTimeout(done, ms));
+}
+
+function fileId(grantKey) {
+  return createHash('sha256').update(grantKey).digest('hex');
+}
+
+export function defaultGrantJournalDir() {
+  if (process.env.NODE_TEST_CONTEXT) return null;
+  const dshHome = process.env.DSH_HOME?.trim() || join(homedir(), '.dsh');
+  return resolve(dshHome, 'storages', 'mcp_connector_grants_v1');
+}
+
+async function writeAtomic(path, document) {
+  const temp = join(dirname(path), `.${randomUUID()}.tmp`);
+  try {
+    const handle = await open(temp, 'wx', 0o600);
+    try {
+      await handle.writeFile(`${JSON.stringify(document, null, 2)}\n`, 'utf8');
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temp, path);
+    await chmod(path, 0o600);
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+function parseDocument(text, path) {
+  let document;
+  try {
+    document = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`OAuth grant journal is malformed: ${path}`, { cause: error });
+  }
+  if (document?.version !== JOURNAL_VERSION) {
+    throw new Error(`OAuth grant journal version is unsupported: ${path}`);
+  }
+  const parsed = grantRecordSchema.safeParse(document.grant);
+  if (!parsed.success) {
+    throw new Error(`OAuth grant journal record is invalid: ${path}`);
+  }
+  return parsed.data;
+}
+
+export class GrantJournal {
+  constructor({ rootDir = defaultGrantJournalDir(), logger } = {}) {
+    this.rootDir = rootDir ? resolve(rootDir) : null;
+    this.logger = logger;
+  }
+
+  get enabled() {
+    return this.rootDir !== null;
+  }
+
+  async ensureRoot() {
+    if (!this.rootDir) return;
+    await mkdir(this.rootDir, { recursive: true, mode: 0o700 });
+    await chmod(this.rootDir, 0o700);
+  }
+
+  recordPath(grantKey) {
+    return join(this.rootDir, `${fileId(grantKey)}.json`);
+  }
+
+  lockPath(grantKey) {
+    return join(this.rootDir, `${fileId(grantKey)}.lock`);
+  }
+
+  async get(grantKey) {
+    if (!this.rootDir) return undefined;
+    try {
+      return parseDocument(await readFile(this.recordPath(grantKey), 'utf8'), this.recordPath(grantKey));
+    } catch (error) {
+      if (error?.code === 'ENOENT') return undefined;
+      this.logger?.warn?.(`skip unreadable OAuth grant journal record ${fileId(grantKey)}: ${error.message}`);
+      return undefined;
+    }
+  }
+
+  async entries() {
+    if (!this.rootDir) return [];
+    await this.ensureRoot();
+    const names = await readdir(this.rootDir).catch((error) => {
+      if (error?.code === 'ENOENT') return [];
+      throw error;
+    });
+    const out = [];
+    for (const name of names.filter((item) => item.endsWith('.json'))) {
+      const path = join(this.rootDir, name);
+      try {
+        const grant = parseDocument(await readFile(path, 'utf8'), path);
+        out.push([grant.key, grant]);
+      } catch (error) {
+        this.logger?.warn?.(`skip unreadable OAuth grant journal record ${name}: ${error.message}`);
+      }
+    }
+    return out;
+  }
+
+  async put(grant) {
+    if (!this.rootDir) return grant;
+    await this.ensureRoot();
+    const parsed = grantRecordSchema.parse(grant);
+    await writeAtomic(this.recordPath(parsed.key), { version: JOURNAL_VERSION, grant: parsed });
+    return parsed;
+  }
+
+  async delete(grantKey) {
+    if (!this.rootDir) return false;
+    try {
+      await rm(this.recordPath(grantKey));
+      return true;
+    } catch (error) {
+      if (error?.code === 'ENOENT') return false;
+      throw error;
+    }
+  }
+
+  async withLock(grantKey, task, {
+    timeoutMs = DEFAULT_LOCK_TIMEOUT_MS,
+    staleLockMs = DEFAULT_STALE_LOCK_MS,
+  } = {}) {
+    if (!this.rootDir) return task();
+    await this.ensureRoot();
+    const path = this.lockPath(grantKey);
+    const startedAt = Date.now();
+    const owner = randomUUID();
+    let handle;
+    for (;;) {
+      try {
+        handle = await open(path, 'wx', 0o600);
+        try {
+          await handle.writeFile(JSON.stringify({ owner, pid: process.pid, createdAt: Date.now() }), 'utf8');
+          await handle.sync();
+        } catch (error) {
+          await handle.close().catch(() => {});
+          await rm(path, { force: true }).catch(() => {});
+          throw error;
+        }
+        break;
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+        const lockStat = await stat(path).catch(() => null);
+        if (lockStat && Date.now() - lockStat.mtimeMs > staleLockMs) {
+          await rm(path, { force: true });
+          continue;
+        }
+        if (Date.now() - startedAt >= timeoutMs) {
+          const timeout = new Error('timed out waiting for another DSH process to finish OAuth refresh');
+          timeout.code = 'refresh_lock_timeout';
+          throw timeout;
+        }
+        await sleep(100);
+      }
+    }
+    try {
+      return await task();
+    } finally {
+      await handle?.close().catch(() => {});
+      // 避免极端超时下旧持有者删掉已被新进程接管的锁（ABA）。
+      const current = await readFile(path, 'utf8').catch(() => '');
+      if (current.includes(`"owner":"${owner}"`)) {
+        await rm(path, { force: true }).catch(() => {});
+      }
+    }
+  }
+}

package/lib/index.js

@@ -4,7 +4,7 @@
  * 能力：
  *   - 连接器目录（内置 + 远程 registry + config 注入 + 本地上下架覆盖）
  *   - 三通道连接：通用 OAuth(PKCE) / 自定义配置 / 粘贴 JSON / URL 安装
- *   - 连接记录与 OAuth grant 持久化（ctx.storageDomain），重启恢复
+ *   - 连接记录与 OAuth grant 持久化，重启恢复与跨 Host Token 轮换
  *   - 通过 ctx.loader 动态配置 @deepseek-ai/dsh-mcp-client 条目
  *   - 对话工具：mcp_connector_catalog / connect / configure / import_json /
  *     install_from_url / status / set_enabled / disconnect / refresh_catalog / publish
@@ -95,7 +95,12 @@ export async function apply(ctx, config) {
   });
 
   const connectionStore = new ConnectionStore(domain);
-  const grantStore = new GrantStore(domain);
+  const grantStore = new GrantStore(domain, {
+    // 只有真实持久化模式才启用跨进程 Grant journal。测试可通过内部字段
+    // 传入临时目录，不让 fake storage 触碰用户真实 $DSH_HOME。
+    journalDir: config.persistSecrets ? config.__grantJournalDir : null,
+    logger,
+  });
   const catalogStore = new CatalogStore(domain);
 
   const state = {
@@ -382,7 +387,27 @@ export async function apply(ctx, config) {
   async function refreshGrantWithRecovery(grantKey, phase) {
     const observed = state.grants.get(grantKey)?.grant;
     try {
-      return await refreshGrant(grantKey);
+      return await grantStore.withRefreshLock(grantKey, async () => {
+        // 锁内必须从独立 journal 重读，不能依赖 DSH domain 的进程内缓存。
+        // 如果另一 Host 已完成轮换，直接采用新 Grant，避免再次消耗
+        // 一次性 Refresh Token。
+        const persisted = await grantStore.get(grantKey).catch(() => undefined);
+        const entry = state.grants.get(grantKey);
+        if (entry && persisted
+            && persisted.updatedAt > entry.grant.updatedAt
+            && persisted.refreshToken !== entry.grant.refreshToken) {
+          entry.grant = persisted;
+          entry.needsReauth = false;
+          entry.refreshFailureKind = null;
+          entry.lastRefreshError = null;
+          logger.info(`OAuth grant ${grantKey} adopted a newer cross-process journal token`);
+          if (persisted.accessTokenExpiresAt > Date.now()) {
+            scheduleRefresh(grantKey);
+            return persisted;
+          }
+        }
+        return refreshGrant(grantKey);
+      }, { timeoutMs: Math.max(30_000, config.requestTimeoutMs * 2) });
     } catch (error) {
       let finalError = error;
       const initialFailure = classifyRefreshFailure(error);
@@ -405,7 +430,13 @@ export async function apply(ctx, config) {
           entry.lastRefreshError = null;
           logger.info(`OAuth grant ${grantKey} adopted a newer persisted token after a concurrent rotation`);
           try {
-            return await refreshGrant(grantKey);
+            if (persisted.accessTokenExpiresAt > Date.now()) {
+              scheduleRefresh(grantKey);
+              return persisted;
+            }
+            return await grantStore.withRefreshLock(grantKey, () => refreshGrant(grantKey), {
+              timeoutMs: Math.max(30_000, config.requestTimeoutMs * 2),
+            });
           } catch (retryError) {
             finalError = retryError;
           }

package/lib/stores.js

@@ -1,11 +1,13 @@
 /**
  * 存储域封装：一个 domain 三张表（connections / grants / catalog）。
- * 落盘 ~/.dsh/storages/（0700），凭证不进入 loader 配置树以外的任何地方。
+ * OAuth grant 同步写入本机受限权限 journal，防止多 Host 的整文件
+ * last-write-wins 覆盖新轮换 Token；凭证不进入 loader 配置树或日志。
  */
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
 import { connectionRecordSchema, grantRecordSchema, catalogRecordSchema } from './schema.js';
 import { DEFAULT_ACCOUNT } from './constants.js';
 import { shortHash } from './util.js';
+import { GrantJournal } from './grant-journal.js';
 
 export function defineConnectorDomain() {
   return defineDomain({
@@ -49,9 +51,10 @@ export class ConnectionStore {
 
 /** OAuth 授权表（通用多 issuer / 多账号） */
 export class GrantStore {
-  constructor(domain) {
+  constructor(domain, { journalDir, journal, logger } = {}) {
     this.table = domain.tables.get('grants');
     if (!this.table) throw new Error('mcp-connector: domain table "grants" not found');
+    this.journal = journal ?? new GrantJournal({ rootDir: journalDir, logger });
   }
 
   keyFor(account, issuer, clientId, scope) {
@@ -59,23 +62,42 @@ export class GrantStore {
   }
 
   async get(key) {
-    return this.table.get(key);
+    const legacy = await this.table.get(key);
+    const journal = await this.journal.get(key);
+    if (!legacy) return journal;
+    if (!journal) return legacy;
+    return journal.updatedAt >= legacy.updatedAt ? journal : legacy;
   }
 
   async put(grant) {
     const next = { ...grant, updatedAt: Date.now() };
+    // Journal 先落盘：即使 DSH JSON domain 被另一进程的旧内存整文件覆盖，
+    // 下次刷新仍能从独立记录取回最新的轮换 Token。
+    await this.journal.put(next);
     await this.table.put(grant.key, next);
     return next;
   }
 
   async delete(key) {
-    return this.table.delete(key);
+    const [journalDeleted, tableDeleted] = await Promise.all([
+      this.journal.delete(key),
+      this.table.delete(key),
+    ]);
+    return journalDeleted || tableDeleted;
   }
 
   async entries() {
-    const out = [];
-    for (const [key, value] of this.table.entries()) out.push([key, value]);
-    return out;
+    const merged = new Map();
+    for (const [key, value] of this.table.entries()) merged.set(key, value);
+    for (const [key, value] of await this.journal.entries()) {
+      const current = merged.get(key);
+      if (!current || value.updatedAt >= current.updatedAt) merged.set(key, value);
+    }
+    return [...merged.entries()];
+  }
+
+  async withRefreshLock(key, task, options) {
+    return this.journal.withLock(key, task, options);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "description": "General-purpose MCP connector, connection manager, plugin extension, and integration marketplace for DeepSeek Harness, initiated and maintained by Qichacha/QCC.",
   "type": "module",
   "main": "lib/index.js",
@@ -34,7 +34,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check lib/index.js && node --check lib/web.js && node --check lib/client.js && node --check lib/version-status.js && node --check lib/schema.js && node --check lib/catalog.js && node --check lib/prompts.js && node --check lib/probe.js && node --check lib/mcp-validation.js && node --check lib/mcp-http.js && node --check lib/migration.js && node --check lib/stores.js && node --check lib/oauth.js && node --check lib/grant-lifecycle.js && node --check lib/callback-server.js && node --check lib/mcp-provision.js && node --check lib/util.js && node --check lib/constants.js && node --check lib/tools.js && node --check lib/connectors/oauth-connector.js && node --check lib/connectors/manual-connector.js && node --check lib/connectors/json-connector.js && node --check scripts/probe-connector.mjs && node --check scripts/build-registry.mjs && node --check scripts/ui-harness.mjs && node --check scripts/check-market-registration.mjs && node --check scripts/sync-registry-stats.mjs",
+    "lint": "node --check lib/index.js && node --check lib/web.js && node --check lib/client.js && node --check lib/version-status.js && node --check lib/schema.js && node --check lib/catalog.js && node --check lib/prompts.js && node --check lib/probe.js && node --check lib/mcp-validation.js && node --check lib/mcp-http.js && node --check lib/migration.js && node --check lib/stores.js && node --check lib/grant-journal.js && node --check lib/oauth.js && node --check lib/grant-lifecycle.js && node --check lib/callback-server.js && node --check lib/mcp-provision.js && node --check lib/util.js && node --check lib/constants.js && node --check lib/tools.js && node --check lib/connectors/oauth-connector.js && node --check lib/connectors/manual-connector.js && node --check lib/connectors/json-connector.js && node --check scripts/probe-connector.mjs && node --check scripts/build-registry.mjs && node --check scripts/ui-harness.mjs && node --check scripts/check-market-registration.mjs && node --check scripts/sync-registry-stats.mjs",
     "registry:build": "node scripts/build-registry.mjs",
     "registry:validate": "node scripts/probe-connector.mjs catalog/catalog.json --validate-only",
     "dev:ui": "node scripts/ui-harness.mjs",