dsh-mcp-connector 0.2.25 → 0.2.26

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## [Unreleased]
 
+## [0.2.26] - 2026-08-27
+
+### Fixed
+
+- 升级启动时自动发现并归并历史版本为同 issuer 卡片保存的多份 OAuth Grant；归并前先验证过期 Grant 是否仍可刷新，避免用较新但已失效的凭据覆盖可恢复授权。
+- 多个 DSH 进程并发刷新同一组轮换式 Refresh Token 时，收到 `invalid_grant` 后会短暂重读本机持久化 Grant；发现其他进程已保存新 Token 时自动采用并重试，不再误报“需重新授权”。
+- 页面不再盲信 Update Provider 的 `succeeded`；独立校验更新前、预期与实际版本，检测降级、解析版本偏差或无效结果时拒绝重启，并在 Provider 保留恢复点时自动回滚。
+
+### Verification
+
+- 129 项自动测试、lint、npm 发布包白名单与敏感内容扫描通过；新增历史 Grant 安全归并、失效候选回退、跨进程 Token 轮换恢复和 Provider 版本完整性回归测试。
+
 ## [0.2.25] - 2026-08-27
 
 ### Added
@@ -414,7 +426,8 @@
 - 外部 URL 与导入 Header 执行安全校验。
 - iframe 消息校验同源和消息来源。
 
-[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.25...HEAD
+[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.26...HEAD
+[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
 [0.2.23]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.22...v0.2.23

package/docs/PLUGIN-UPDATE.md

@@ -21,10 +21,11 @@ DSH Market 适配器从 `GET /dsh-market/api/v1/capabilities` 开始，要求 `s
 1. 插件自己的服务端缓存检查 npm `latest` 与 GitHub Release，只在 npm 已有可安装新版本时提示升级。
 2. 选中的 Provider 再检查本 profile 中 `dsh-mcp-connector` 的实际安装版本和目标版本。
 3. 用户点击“一键更新”后，Provider 立即返回 `operationId`；页面通过适配器轮询任务状态，展示排队、解析、下载和安装进度。
-4. 成功后按 Provider 返回的激活结论展示“刷新生效”或重启提示。Web 且 Provider 明确允许进程重启时才展示“立即重启”；Desktop 等由外壳管理生命周期的宿主只提示用户重启，不自行杀进程。
-5. Provider 保留恢复点时展示“回滚”。回滚仍由 Provider 执行，MCP连接器不直接修改 profile、lockfile 或 `node_modules`。
+4. Provider 报告成功后，页面仍会独立校验 `beforeVersion`、点击时的预期版本与 `installedVersion`。降级、目标不一致或无效结果会被拒绝；Provider 保留恢复点时自动回滚，不向用户展示重启。
+5. 完整性校验通过后，按 Provider 返回的激活结论展示“刷新生效”或重启提示。Web 且 Provider 明确允许进程重启时才展示“立即重启”；Desktop 等由外壳管理生命周期的宿主只提示用户重启，不自行杀进程。
+6. Provider 保留恢复点时展示“回滚”。回滚仍由 Provider 执行，MCP连接器不直接修改 profile、lockfile 或 `node_modules`。
 
-失败结果使用稳定代码区分正在运行的 Agent、其他安装任务占用、镜像同步、版本未变化、超时和权限拒绝。可重试失败保留重试操作；Registry 刚发布但镜像仍未同步时，用户可在看到明确提示后选择强制重试。
+失败结果使用稳定代码区分正在运行的 Agent、其他安装任务占用、镜像同步、版本未变化、超时和权限拒绝，以及 `DOWNGRADE_DETECTED`、`RESOLVED_VERSION_MISMATCH`、`INVALID_UPDATE_RESULT` 三类完整性故障。可重试失败保留重试操作；Registry 刚发布但镜像仍未同步时，用户可在看到明确提示后选择强制重试。
 
 ## 安全边界
 

package/docs/USER-GUIDE.md

@@ -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 页面。网络、OAuth 元数据发现或服务端 5xx 等暂时故障只进入“自动重试中”，明确收到 Refresh Token/客户端失效错误时才进入“需重新授权”。
+当市场描述声明 `grantSharing: "issuer"` 时，同一账号下相同 issuer、scope 和客户端鉴权方式的卡片共享一组 Grant。首次授权仍只启用用户点击的卡片；之后连接同组卡片会直接复用现有授权，不再重复打开 OAuth 页面。升级时会验证并自动归并旧版本留下的同 issuer 多份 Grant；多个 DSH 进程并发轮换 Refresh Token 时也会重读较新的本机持久化凭据后自动恢复。网络、OAuth 元数据发现或服务端 5xx 等暂时故障只进入“自动重试中”，确认本机也没有其他进程保存的新 Token，且明确收到 Refresh Token/客户端失效错误时，才进入“需重新授权”。
 
 ## 5. 查看详情、Prompt 与工具
 

package/lib/client.js

@@ -363,6 +363,9 @@ window.__ModuleLoader__.load({
 				OPERATION_BUSY: "插件市场正在处理其他任务",
 				RELEASE_TOO_FRESH: "新版本仍在镜像同步",
 				VERSION_UNCHANGED: "下载后版本未变化",
+				DOWNGRADE_DETECTED: "已阻止版本降级",
+				RESOLVED_VERSION_MISMATCH: "下载版本与预期不一致",
+				INVALID_UPDATE_RESULT: "更新服务未返回有效版本",
 				UPDATE_TIMEOUT: "更新超时",
 				UPDATE_FORBIDDEN: "更新请求被拒绝",
 				UPDATE_REJECTED: "无法执行本次更新"
@@ -370,6 +373,71 @@ window.__ModuleLoader__.load({
 			return labels[failure?.code] ?? failure?.message ?? "更新失败";
 		}
 
+		function parseClientVersion(value) {
+			if (typeof value !== "string") return null;
+			const normalized = value.trim().replace(/^v/i, "");
+			if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(normalized)) return null;
+			const [withoutBuild] = normalized.split("+");
+			const [core, prerelease] = withoutBuild.split("-", 2);
+			return { normalized, core: core.split(".").map(Number), prerelease: prerelease?.split(".") ?? [] };
+		}
+
+		function compareClientVersions(left, right) {
+			const a = parseClientVersion(left);
+			const b = parseClientVersion(right);
+			if (a === null || b === null) return null;
+			for (let index = 0; index < 3; index += 1) {
+				if (a.core[index] !== b.core[index]) return a.core[index] - b.core[index];
+			}
+			if (a.prerelease.length === 0 && b.prerelease.length > 0) return 1;
+			if (a.prerelease.length > 0 && b.prerelease.length === 0) return -1;
+			const length = Math.max(a.prerelease.length, b.prerelease.length);
+			for (let index = 0; index < length; index += 1) {
+				const aPart = a.prerelease[index];
+				const bPart = b.prerelease[index];
+				if (aPart === void 0) return -1;
+				if (bPart === void 0) return 1;
+				if (aPart === bPart) continue;
+				const aNumeric = /^\d+$/.test(aPart);
+				const bNumeric = /^\d+$/.test(bPart);
+				if (aNumeric && bNumeric) return Number(aPart) - Number(bPart);
+				if (aNumeric) return -1;
+				if (bNumeric) return 1;
+				return aPart.localeCompare(bPart);
+			}
+			return 0;
+		}
+
+		/** Independently verify a provider's terminal success before asking the user to restart. */
+		function completedUpdateIntegrityFailure(operation, expectedVersion) {
+			if (operation?.state !== "succeeded") return null;
+			const installed = parseClientVersion(operation.installedVersion);
+			if (installed === null) {
+				return {
+					code: "INVALID_UPDATE_RESULT",
+					message: "更新服务报告成功，但未返回有效的已安装版本",
+					retryable: false
+				};
+			}
+			const before = parseClientVersion(operation.beforeVersion);
+			if (before !== null && compareClientVersions(installed.normalized, before.normalized) < 0) {
+				return {
+					code: "DOWNGRADE_DETECTED",
+					message: `更新服务将插件从 v${before.normalized} 降级到 v${installed.normalized}`,
+					retryable: false
+				};
+			}
+			const expected = parseClientVersion(expectedVersion);
+			if (expected !== null && compareClientVersions(installed.normalized, expected.normalized) !== 0) {
+				return {
+					code: "RESOLVED_VERSION_MISMATCH",
+					message: `预期安装 v${expected.normalized}，更新服务实际安装了 v${installed.normalized}`,
+					retryable: true
+				};
+			}
+			return null;
+		}
+
 		/**
 		 * DSH 暂未公开“打开指定设置分区”服务：只依赖稳定的 sidebar.settings
 		 * slot 和可访问文本打开插件市场，不依赖构建生成的 CSS 类名。
@@ -451,6 +519,7 @@ window.__ModuleLoader__.load({
 			const [updateProviderState, setUpdateProviderState] = (0, react.useState)("checking");
 			const [updateProviderSelection, setUpdateProviderSelection] = (0, react.useState)(null);
 			const [providerUpdateCheck, setProviderUpdateCheck] = (0, react.useState)(null);
+			const [expectedUpdateVersion, setExpectedUpdateVersion] = (0, react.useState)(null);
 			const [updateOperation, setUpdateOperation] = (0, react.useState)(null);
 			const [updateError, setUpdateError] = (0, react.useState)(null);
 			const [updateStarting, setUpdateStarting] = (0, react.useState)(false);
@@ -564,6 +633,34 @@ window.__ModuleLoader__.load({
 					provider.operation(capabilities, operationId).then((operation) => {
 						if (disposed) return;
 						setUpdateError(null);
+						const integrityFailure = completedUpdateIntegrityFailure(operation, expectedUpdateVersion);
+						if (integrityFailure !== null) {
+							const failedOperation = { ...operation, state: "failed", failure: integrityFailure };
+							setUpdateOperation(failedOperation);
+							const canRollback = capabilities.features?.rollback === true
+								&& operation.outcome?.rollback?.available === true
+								&& capabilities.endpoints.rollback !== null;
+							if (!canRollback) return;
+							setRollbackRunning(true);
+							provider.rollback(capabilities, operationId).then((rolledBackOperation) => {
+								if (disposed) return;
+								setRollbackRunning(false);
+								setUpdateOperation({ ...rolledBackOperation, integrityFailure });
+							}, (error) => {
+								console.error("[mcp-connector] automatic rollback failed:", error);
+								if (disposed) return;
+								const detail = error instanceof Error ? error.message : String(error);
+								setRollbackRunning(false);
+								setUpdateOperation({
+									...failedOperation,
+									outcome: {
+										...failedOperation.outcome,
+										rollback: { available: true, state: "failed", detail }
+									}
+								});
+							});
+							return;
+						}
 						setUpdateOperation(operation);
 						if (["queued", "running"].includes(operation.state)) {
 							timer = window.setTimeout(poll, UPDATE_PROVIDER_OPERATION_POLL_MS);
@@ -584,7 +681,7 @@ window.__ModuleLoader__.load({
 					disposed = true;
 					window.clearTimeout(timer);
 				};
-			}, [open, updateOperation?.operationId, updateProviderSelection?.provider?.id]);
+			}, [open, updateOperation?.operationId, updateProviderSelection?.provider?.id, expectedUpdateVersion]);
 			(0, react.useEffect)(() => {
 				if (!open) return void 0;
 				closeRef.current?.focus?.();
@@ -600,6 +697,7 @@ window.__ModuleLoader__.load({
 				if (updateRunning || provider === void 0 || capabilities === void 0) return;
 				setUpdateError(null);
 				setUpdateStarting(true);
+				setExpectedUpdateVersion(providerUpdateCheck?.latestVersion ?? versionStatus?.latestVersion ?? null);
 				provider.start(capabilities, PLUGIN_PACKAGE_NAME, force).then((operation) => {
 					setUpdateStarting(false);
 					setUpdateOperation(operation);
@@ -687,6 +785,10 @@ window.__ModuleLoader__.load({
 								onClick: () => startUpdate(force),
 								children: force ? "强制重试" : "重试更新"
 							}),
+							rollbackRunning && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+								className: "mcpConnectorUpdateStatus",
+								children: "检测到异常版本，正在自动回滚…"
+							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								type: "button",
 								className: "mcpConnectorUpdateButton mcpConnectorUpdateSecondary",
@@ -707,7 +809,7 @@ window.__ModuleLoader__.load({
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 								className: "mcpConnectorUpdateStatus",
 								children: rolledBack
-									? "已回滚"
+									? updateOperation.integrityFailure === void 0 ? "已回滚" : "已阻止异常版本并回滚"
 									: `已安装 v${updateOperation.installedVersion ?? versionStatus?.latestVersion}`
 							}),
 							rollbackFailed && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {

package/lib/index.js

@@ -380,12 +380,41 @@ export async function apply(ctx, config) {
   }
 
   async function refreshGrantWithRecovery(grantKey, phase) {
+    const observed = state.grants.get(grantKey)?.grant;
     try {
       return await refreshGrant(grantKey);
     } catch (error) {
+      let finalError = error;
+      const initialFailure = classifyRefreshFailure(error);
+      // Refresh tokens are commonly rotated. If another DSH process refreshed
+      // the same persisted grant first, this process still holds the old token
+      // and receives invalid_grant. Re-read storage before declaring the user
+      // logged out; a newer token is authoritative and can be retried once.
+      if (config.persistSecrets && observed
+          && ['invalid_grant', 'invalid_token'].includes(initialFailure.code)) {
+        for (const delayMs of [0, 100, 250]) {
+          if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+          const persisted = await grantStore.get(grantKey).catch(() => undefined);
+          const entry = state.grants.get(grantKey);
+          if (!entry || !persisted
+              || persisted.updatedAt <= observed.updatedAt
+              || persisted.refreshToken === observed.refreshToken) continue;
+          entry.grant = persisted;
+          entry.needsReauth = false;
+          entry.refreshFailureKind = null;
+          entry.lastRefreshError = null;
+          logger.info(`OAuth grant ${grantKey} adopted a newer persisted token after a concurrent rotation`);
+          try {
+            return await refreshGrant(grantKey);
+          } catch (retryError) {
+            finalError = retryError;
+          }
+          break;
+        }
+      }
       // 多个调用方可能等待同一个 refreshPromise；同一次失败只能记一次并调度一个重试。
-      if (!error.refreshFailure) error.refreshFailure = recordRefreshFailure(grantKey, error, phase);
-      throw error;
+      if (!finalError.refreshFailure) finalError.refreshFailure = recordRefreshFailure(grantKey, finalError, phase);
+      throw finalError;
     }
   }
 
@@ -858,6 +887,86 @@ export async function apply(ctx, config) {
     }
   }
 
+  /**
+   * v0.2.22 及更早版本会让四张企查查卡片分别保存动态客户端和 Grant。
+   * 新版升级时把同 issuer、同资源域且授权范围完整的历史记录归并为一组，
+   * 这样启动只刷新一个 refresh token，之后任意一张卡片重新授权也会修复整组。
+   */
+  async function consolidatePersistedSharedGrants() {
+    const groups = new Map();
+    for (const record of state.connections.values()) {
+      if (record.auth?.mode !== 'oauth' || !record.auth.grantKey) continue;
+      const connector = state.merged.find((item) => item.id === record.connectorId);
+      if (connector?.auth?.grantSharing !== 'issuer') continue;
+      const groupKey = oauthSharingKey(connector);
+      const group = groups.get(groupKey) ?? { records: [], grantKeys: new Set() };
+      group.records.push(record);
+      group.grantKeys.add(record.auth.grantKey);
+      groups.set(groupKey, group);
+    }
+
+    let consolidated = 0;
+    for (const group of groups.values()) {
+      if (group.grantKeys.size <= 1) continue;
+      const requiredResources = new Set(group.records.map((record) => record.url).filter(Boolean));
+      const candidates = [...group.grantKeys]
+        .map((key) => [key, state.grants.get(key)])
+        .filter(([, entry]) => entry
+          && [...requiredResources].every((resource) => entry.grant.authorizedResources.includes(resource)))
+        .sort((left, right) => (
+          (right[1].grant.updatedAt ?? 0) - (left[1].grant.updatedAt ?? 0)
+          || (right[1].grant.accessTokenExpiresAt ?? 0) - (left[1].grant.accessTokenExpiresAt ?? 0)
+        ));
+      if (candidates.length === 0) continue;
+
+      // Do not retire three recoverable historical grants in favour of a newer
+      // but already-revoked refresh token. Validate expired candidates in
+      // recency order and only consolidate after one grant is demonstrably
+      // usable. If none is usable, preserve every grant so one subsequent
+      // authorization can replace the group without destroying recovery data.
+      let winnerCandidate;
+      for (const candidate of candidates) {
+        const [candidateKey, candidateEntry] = candidate;
+        if (candidateEntry.needsReauth) continue;
+        if (candidateEntry.grant.accessTokenExpiresAt <= Date.now()) {
+          try {
+            await refreshGrantWithRecovery(candidateKey, 'startup-consolidation');
+          } catch {
+            continue;
+          }
+        }
+        winnerCandidate = candidate;
+        break;
+      }
+      if (winnerCandidate === undefined) {
+        logger.warn(`preserved ${group.grantKeys.size} historical issuer-shared OAuth grants because none could be refreshed`);
+        continue;
+      }
+
+      const [winnerKey, winnerEntry] = winnerCandidate;
+      const connectorIds = [...new Set([
+        ...(winnerEntry.grant.connectorIds ?? []),
+        ...group.records.map((record) => record.connectorId),
+      ])];
+      const winner = { ...winnerEntry.grant, connectorIds, updatedAt: Date.now() };
+      winnerEntry.grant = winner;
+      if (config.persistSecrets) await grantStore.put(winner);
+
+      for (const record of group.records) {
+        if (record.auth.grantKey === winnerKey) continue;
+        const next = { ...record, auth: { ...record.auth, grantKey: winnerKey }, updatedAt: Date.now() };
+        const persisted = config.persistSecrets ? await connectionStore.put(next) : next;
+        state.connections.set(record.key, persisted);
+      }
+      for (const losingKey of group.grantKeys) {
+        if (losingKey !== winnerKey) await retireGrantIfUnused(losingKey);
+      }
+      consolidated += group.grantKeys.size - 1;
+      logger.info(`consolidated ${group.grantKeys.size} issuer-shared OAuth grants into ${winnerKey}`);
+    }
+    return consolidated;
+  }
+
   /* ───────────────────────── api 门面 ───────────────────────── */
 
   const api = {
@@ -1612,6 +1721,9 @@ export async function apply(ctx, config) {
     }
   }
 
+  const consolidatedGrantCount = await consolidatePersistedSharedGrants();
+  if (consolidatedGrantCount > 0) logger.info(`consolidated ${consolidatedGrantCount} historical OAuth grant(s) during startup`);
+
   const prunedGrantCount = await pruneOrphanGrants();
   if (prunedGrantCount > 0) logger.info(`removed ${prunedGrantCount} unreferenced OAuth grant(s) from local storage`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "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",