@qzsy/dsh-bridge 0.0.0-stage → 2.18.0

package/lib/bridge-rpc.js

@@ -0,0 +1,722 @@
+// DSH Bridge - RPC Interface (server side)
+// Loopback-only RPC methods for browser UI
+
+import QRCode from 'qrcode';
+import { BRIDGE_RPC_CHANNEL, BRIDGE_ENDPOINTS } from './bridge-rpc-constants.js';
+import { registerRpcChannel } from './connection-compat.js';
+import { RateLimiter } from './security/rate-limiter.js';
+
+export { BRIDGE_RPC_CHANNEL, BRIDGE_ENDPOINTS };
+
+const rpcRateLimiter = new RateLimiter({ maxRequests: 30, windowMs: 60000 });
+
+function ok(value) {
+  return { ok: true, value };
+}
+
+function fail(code, message, details = {}) {
+  const allowedCodes = new Set([
+    'bad-request', 'cancelled', 'internal', 'settings-rejected', 'command-error',
+    // 'busy'：重启等操作因「有任务在跑」被拦下，需与普通 bad-request 区分，
+    // 面板据此弹二次确认（而不是报错）。
+    'busy'
+  ]);
+  const safeCode = allowedCodes.has(code) ? code : 'bad-request';
+  return {
+    ok: false,
+    error: {
+      code: safeCode,
+      message,
+      details: { issues: [{ message }], ...details },
+    },
+  };
+}
+
+// 把登录态里的二维码载荷渲染成浏览器可展示的 dataURL（带缓存，避免重复生成）
+async function renderQr(loginState) {
+  if (!loginState?.qrPayload) return null;
+  // issue #78：缓存键包含 instanceId，避免同类型多账号二维码互串
+  const cacheKey = `${loginState.instanceId ?? ''}:${loginState.qrKind}:${loginState.qrPayload.slice(0, 80)}`;
+  if (renderQr.cache && renderQr.cache.key === cacheKey) return renderQr.cache.url;
+  let url;
+  const payload = loginState.qrPayload;
+  if (loginState.qrKind === 'img') {
+    url = /^data:/i.test(payload) ? payload : `data:image/png;base64,${payload}`;
+  } else {
+    try {
+      url = await QRCode.toDataURL(payload, {
+        width: 300, margin: 2, color: { dark: '#1F2421', light: '#FFFFFF' },
+      });
+    } catch { url = null; }
+  }
+  renderQr.cache = { key: cacheKey, url };
+  return url;
+}
+
+/** 为某个平台 status 渲染登录二维码（带上 instanceId 参与缓存键，避免多账号互串）。 */
+function renderStatusQr(status) {
+  return renderQr({ ...(status?.login ?? {}), instanceId: status?.instanceId }).catch(() => null);
+}
+
+function checkAdminAuth(authManager, payload, { requireConfigured = false } = {}) {
+  if (!authManager) return null;
+  // local_only 最严格：即使关闭管理保护，也绝不远程放行（本机经 loopback-token 天然持有 adminToken）
+  // 注意：RPC 层无法区分本机/远程（代理以回环转发），local_only 的防线是 unlockAdmin 拒绝
+  // 远程解锁——因此这里管理保护关闭时也不放行 local_only，保持"仅本机可管理"的语义。
+  if (authManager.adminPolicy === 'local_only') {
+    // local_only 下必须持有有效 adminToken（只有本机 loopback-token / 本机解锁能拿到）
+    if (payload?.adminToken && authManager.validateAdminSession(payload.adminToken)) {
+      return null;
+    }
+    return fail('bad-request', '操作已被拦截：当前策略为仅限电脑本机管理');
+  }
+  // 管理保护独立开关：用户明确关闭后，管理操作免 adminToken（与访问认证 enabled 解耦）
+  if (authManager.adminProtection === false) return null;
+  if (authManager.adminPolicy === 'open') return null;
+  // 若系统尚未设置任何管理密码或访客密码，允许免密管理
+  const hasAnyPassword = authManager.hasAdminPassword || authManager.hasPassword;
+  // T2.9：高危操作（备份导出/导入、隧道配置与启动、目录浏览、添加工作区、升级、重启）
+  // 在系统从未设置任何密码时不再静默放行，强制先完成一次密码设置，
+  // 杜绝"未设密码 = 局域网/隧道内任何人都可导出全部凭证"的裸奔状态被直接利用
+  if (requireConfigured && !hasAnyPassword) {
+    return fail('bad-request', '该操作涉及敏感配置：请先在「安全认证」中设置访问密码或管理密码后再执行');
+  }
+  if (!hasAnyPassword) {
+    return null;
+  }
+  // 已设置密码时，必须提供经服务端校验有效的 adminToken（绝不依赖客户端自称的 isLocalhost）
+  if (payload?.adminToken && authManager.validateAdminSession(payload.adminToken)) {
+    return null;
+  }
+  return fail('bad-request', '操作已被拦截：需要管理员权限，请先在控制台输入管理密码解锁');
+}
+
+/** 从平台实例取实例标识（旧实例可能没有 instanceId，回退 id）。 */
+function platformRefOf(platform) {
+  const platformId = platform?.id;
+  return { platformId, instanceId: platform?.instanceId ?? platformId };
+}
+
+/** 给平台 status 补 instanceId/platformId/displayName（issue #78 契约 §4/§7）。 */
+function decoratePlatformStatus(platform) {
+  const status = platform?.getStatus?.() ?? {};
+  const { instanceId } = platformRefOf(platform);
+  return {
+    ...status,
+    instanceId: status.instanceId ?? instanceId,
+    platformId: platform?.id ?? status.platformId ?? status.id ?? instanceId,
+    displayName: platform?.displayName ?? status.displayName ?? platform?.name ?? status.name ?? instanceId,
+  };
+}
+
+/** 平台 RPC 成功响应：附加渲染后的二维码（保留旧字段处理）。 */
+function withRenderedQr(status, qr) {
+  return { ...status, login: { ...(status.login ?? {}), qr, qrPayload: undefined, qrKind: undefined } };
+}
+
+/**
+ * 解析平台定位参数：优先 instanceId，缺省回退 platformId（旧客户端兼容）。
+ * 返回 { platform } 或 { error }。
+ */
+function resolvePlatformParam(platformManager, payload) {
+  const ref = payload?.instanceId ?? payload?.platformId;
+  if (!ref) return { error: fail('bad-request', '缺少 instanceId/platformId 参数') };
+  const platform = platformManager.resolve ? platformManager.resolve(ref) : platformManager.get(ref);
+  if (!platform) return { error: fail('bad-request', `平台未注册: ${ref}`) };
+  return { platform };
+}
+
+export function installBridgeRpc(ctx, {
+  service,
+  authManager,
+  platformManager,
+  logger,
+  saveCustomTunnelConfig,
+  exportBackup,
+  importBackup,
+  runtime,
+  getUiFlags,
+  setUiFlags,
+  // issue #78：多账号运行时增删与保存前凭证查重（由 lib/index.js 注入，可缺省）
+  addPlatformAccount,
+  removePlatformAccount,
+  validatePlatformAccountConfig,
+}) {
+  if (!ctx?.connection?.rpc?.handle) {
+    logger.warn('dsh-bridge: Connection RPC unavailable — UI will not work');
+    return () => {};
+  }
+
+  // 运行中任务探测所需的引用（由 apply 注入）。缺失时探测退化为「无任务」，不阻断重启。
+  if (runtime) {
+    service.runtimeCtx = runtime.ctx ?? null;
+    service.platformManager = runtime.platformManager ?? null;
+  }
+
+  // 经 connection-compat 注册：兼容 DSH ≥ 0.1.5-alpha.1 的 webServer 注入回归
+  // （上游 register() 里对 connection 自身 ctx 取 webServer 而未加 inject 作用域）
+  return registerRpcChannel(
+    ctx,
+    BRIDGE_RPC_CHANNEL,
+    async (endpoint, payload = {}, signal) => {
+      if (signal?.aborted) return fail('cancelled', 'Request was cancelled');
+
+      try {
+        // 本通道内所有"管理员专属"分支都已先过 checkAdminAuth；这些分支返回的状态必须显式
+        // 声明管理员视图，否则 getStatus 会把仅限管理员可见的字段（外部隧道 URL/二维码、
+        // cloudflared token）按访客视图掩码掉，管理员保存后立刻拿到一份"被抹掉"的状态。
+        const adminStatus = () => service.getStatus({ adminAuthValid: true });
+
+        if (endpoint === BRIDGE_ENDPOINTS.getStatus) {
+          const isAdmin = checkAdminAuth(authManager, payload) === null;
+          const status = await service.getStatus({ adminAuthValid: isAdmin });
+          return ok(status);
+        }
+
+        // ---- 访问安全认证 ----
+
+        if (endpoint === BRIDGE_ENDPOINTS.authGetStatus) {
+          if (!authManager) return fail('bad-request', 'AuthManager 未初始化');
+          const isAdmin = checkAdminAuth(authManager, payload) === null;
+          return ok(authManager.getStatus({ masked: !isAdmin }));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.authUpdateConfig) {
+          if (!authManager) return fail('bad-request', 'AuthManager 未初始化');
+          const { enabled, mode, scope, adminPolicy, adminProtection, password, adminPassword } = payload;
+          // 仅切换 enabled（访问认证开关）不需要管理权限：用户应能自由决定是否开放访问，
+          // 否则"关闭访问认证"这个动作本身会被管理保护锁死（死锁：关闭要先解锁，解锁要过认证）。
+          // 其余字段（模式/范围/策略/密码/管理保护）均涉及安全配置，仍需管理权限。
+          const sensitive = mode !== undefined || scope !== undefined || adminPolicy !== undefined
+            || adminProtection !== undefined || password !== undefined || adminPassword !== undefined;
+          if (sensitive) {
+            const adminErr = checkAdminAuth(authManager, payload);
+            if (adminErr) return adminErr;
+          }
+
+          // 防自我锁死守卫（v2.10.5）：
+          // password_only（仅密码）模式下若从未设置任何密码，开启防护或维持该模式会把
+          // 管理员锁在登录墙外（无哈希可校验、密码登录被拒 → 进不去面板设密码 → 死锁）。
+          // 因此：无任何密码时禁止单独开启 enabled（除非本次同请求携带 password），
+          // 也禁止单独切换到 password_only（除非已设密码或本次带 password）。
+          const willHaveNoPassword = !authManager.hasPassword && !authManager.hasAdminPassword
+            && (password === undefined || !password);
+          const nextMode = mode ?? authManager.mode;
+          const nextEnabled = enabled ?? authManager.enabled;
+          if (willHaveNoPassword && nextMode === 'password_only') {
+            if (nextEnabled) {
+              return fail('bad-request', '仅密码模式需要先设置访问密码：请先在下方「设置外部访客访问密码」处设置密码，再开启安全防护');
+            }
+            if (mode !== undefined) {
+              return fail('bad-request', '仅密码模式需要先设置访问密码：请先在下方「设置外部访客访问密码」处设置密码后再切换');
+            }
+          }
+
+          if (enabled != null) await authManager.setEnabled(enabled);
+          if (mode != null) await authManager.setMode(mode);
+          if (scope != null) await authManager.setScope(scope);
+          if (adminPolicy != null) await authManager.setAdminPolicy(adminPolicy);
+          if (adminProtection != null) await authManager.setAdminProtection(adminProtection);
+          if (password !== undefined) await authManager.setPassword(password);
+          if (adminPassword !== undefined) await authManager.setAdminPassword(adminPassword);
+          return ok(authManager.getStatus({ masked: false }));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.dismissFirstRunGuide) {
+          // 无管理权限要求：这是纯本地提示状态，不涉及安全配置变更。
+          // 与 authUpdateConfig 中「切换 enabled 不需管理权限」同理，避免提示无法关闭。
+          return ok(await service.dismissFirstRunGuide());
+        }
+
+        // ---- 页面改写层用户偏好（设置面板可见开关）----
+        // 读开放（仅布尔偏好，无敏感信息）；写需管理权限（影响全部被代理页面的展示）。
+        if (endpoint === BRIDGE_ENDPOINTS.uiGetFlags) {
+          const flags = getUiFlags ? await getUiFlags() : { pageTweaks: true, hostAllows: true, effective: true };
+          return ok(flags);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.uiUpdateConfig) {
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+          if (!setUiFlags) return fail('internal', 'UI 配置持久化不可用');
+          const { pageTweaks } = payload ?? {};
+          if (pageTweaks !== undefined && typeof pageTweaks !== 'boolean') {
+            return fail('bad-request', 'pageTweaks 必须为布尔值');
+          }
+          return ok(await setUiFlags(pageTweaks === undefined ? {} : { pageTweaks }));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.authRegenerateToken) {
+          if (!authManager) return fail('bad-request', 'AuthManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          await authManager.regenerateSecretToken();
+          return ok(authManager.getStatus({ masked: false }));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.authAdminUnlock) {
+          if (!authManager) return fail('bad-request', 'AuthManager 未初始化');
+          const { password } = payload;
+          const res = await authManager.unlockAdmin(password);
+          if (res.ok) return ok({ adminToken: res.adminToken });
+          return fail('bad-request', res.error || '管理员密码错误');
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.authAdminLock) {
+          if (!authManager) return fail('bad-request', 'AuthManager 未初始化');
+          if (payload?.adminToken) authManager.revokeAdminSession(payload.adminToken);
+          return ok({ locked: true });
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.saveCustomTunnelConfig) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          // 未提供的字段保持 undefined 透传：服务端视为"保留现值"。
+          // mode/gatewayUrl 为 SaaS 扩展（面板模式切换与网关地址），不影响 self 语义。
+          const { serverUrl, accessToken, sseStreaming, mode, gatewayUrl } = payload;
+          await saveCustomTunnelConfig(serverUrl, accessToken, sseStreaming, { mode, gatewayUrl });
+          const status = await adminStatus();
+          return ok(status);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.saveCloudflaredConfig) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          const { token, hostname, protocol, edgeIpVersion, region } = payload;
+          await service.saveCloudflaredConfig({ token, hostname, protocol, edgeIpVersion, region });
+          const status = await adminStatus();
+          return ok(status);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.saveExternalTunnel) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          const { url } = payload;
+          await service.saveExternalTunnel({ url });
+          const status = await adminStatus();
+          return ok(status);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.setTunnelAutoStart) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          const { tunnel, autoStart } = payload;
+          await service.setTunnelAutoStart({ tunnel, autoStart });
+          const status = await adminStatus();
+          return ok(status);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.setLanIp) {
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          const { ip } = payload;
+          const status = await service.setLanIp({ ip, adminAuthValid: true });
+          return ok(status);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.startCustomTunnel) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          try {
+            await service.startCustomTunnel();
+            const status = await adminStatus();
+            return ok(status);
+          } catch (err) {
+            logger.error('Failed to start custom tunnel: %s', err.message);
+            return fail('bad-request', err.message);
+          }
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.stopCustomTunnel) {
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          service.stopCustomTunnel();
+          const status = await adminStatus();
+          return ok(status);
+        }
+
+        // ---- SaaS 隧道（设备码绑定 / 解绑）----
+        // 读状态：只要求管理员鉴权（不回传 deviceSecret 明文，仅掩码）
+        if (endpoint === BRIDGE_ENDPOINTS.saasGetStatus) {
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+          return ok(service.getSaasStatus({ adminAuthValid: true }));
+        }
+
+        // 绑定类操作涉及设备凭证落盘，与 saveCustomTunnelConfig/startCustomTunnel 同门槛：
+        // 系统从未设置任何密码时拒绝（requireConfigured），避免裸奔设备被他人绑定/解绑。
+        if (endpoint === BRIDGE_ENDPOINTS.saasRequestDeviceCode) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+          try {
+            return ok(await service.requestSaasDeviceCode({ gatewayUrl: payload?.gatewayUrl }));
+          } catch (err) {
+            logger.error('Failed to request SaaS device code: %s', err?.message ?? err);
+            return fail('bad-request', err?.message ?? String(err));
+          }
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.saasBindDevice) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+          try {
+            return ok(await service.bindSaasDevice({ code: payload?.code, gatewayUrl: payload?.gatewayUrl }));
+          } catch (err) {
+            logger.error('Failed to bind SaaS device: %s', err?.message ?? err);
+            return fail('bad-request', err?.message ?? String(err));
+          }
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.saasUnbindDevice) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+          try {
+            return ok(await service.unbindSaasDevice());
+          } catch (err) {
+            logger.error('Failed to unbind SaaS device: %s', err?.message ?? err);
+            return fail('bad-request', err?.message ?? String(err));
+          }
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.startCloudflared) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          try {
+            await service.startCloudflared();
+            const status = await adminStatus();
+            return ok(status);
+          } catch (err) {
+            logger.error('Failed to start cloudflared: %s', err.message);
+            return fail('bad-request', err.message);
+          }
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.stopCloudflared) {
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          service.stopCloudflared();
+          const status = await adminStatus();
+          return ok(status);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.resetCloudflared) {
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          await service.resetCloudflared();
+          const status = await adminStatus();
+          return ok(status);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.checkVersion) {
+          const result = await service.checkVersion();
+          return ok(result);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.upgradePlugin) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          const result = await service.upgradePlugin(payload);
+          return ok(result);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.upgradeDsh) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          const result = await service.upgradeDsh(payload);
+          return ok(result);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.restartDsh) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          // 打断保护：有任务在跑且调用方未显式确认时，**不重启**，改为把现场回给面板，
+          // 由面板弹二次确认。已确认（payload.confirm === true）则照常重启。
+          // 探测本身失败会降级为「无任务」，绝不会把重启锁死。
+          if (payload?.confirm !== true) {
+            let work;
+            try {
+              work = service.getActiveWork?.() ?? { total: 0, sessions: [], subagentSessions: [], pendingApprovals: [] };
+            } catch (err) {
+              logger?.debug?.('dsh-bridge: 重启前探测任务失败（按无任务处理）：%s', err?.message ?? err);
+              work = { total: 0, sessions: [], subagentSessions: [], pendingApprovals: [] };
+            }
+            if (work.total > 0) {
+              return fail('busy', '当前有任务正在运行，重启会打断它们', { activeWork: work });
+            }
+          }
+
+          const result = await service.restartDsh();
+          return ok(result);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.exportBackup) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          if (!exportBackup) return fail('bad-request', '备份导出服务不可用');
+          const backup = await exportBackup();
+          return ok(backup);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.importBackup) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          if (!importBackup) return fail('bad-request', '备份导入服务不可用');
+          const result = await importBackup(payload?.backup);
+          const status = await adminStatus();
+          return ok({ result, status });
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.diagnoseNetwork) {
+          const result = await service.diagnoseNetwork();
+          return ok(result);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.getSystemMetrics) {
+          const metrics = service.getSystemMetrics();
+          return ok(metrics);
+        }
+
+        // ---- 远程工作区管理与目录浏览 ----
+
+        if (endpoint === BRIDGE_ENDPOINTS.listRemoteDirectories) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          const clientKey = payload?.clientIp || payload?.adminToken || 'default';
+          const rateCheck = rpcRateLimiter.check(clientKey, 30);
+          if (!rateCheck.allowed) {
+            return fail('bad-request', `请求过于频繁，请等待 ${rateCheck.retryAfterSec} 秒后再试`);
+          }
+
+          const result = await service.listRemoteDirectories(payload?.path);
+          return ok(result);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.addRemoteWorkspace) {
+          const adminErr = checkAdminAuth(authManager, payload, { requireConfigured: true });
+          if (adminErr) return adminErr;
+
+          const clientKey = payload?.clientIp || payload?.adminToken || 'default';
+          const rateCheck = rpcRateLimiter.check(clientKey, 20);
+          if (!rateCheck.allowed) {
+            return fail('bad-request', `添加工作区请求过于频繁，请等待 ${rateCheck.retryAfterSec} 秒后再试`);
+          }
+
+          const result = await service.addWorkspace(payload?.path);
+          return ok(result);
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.listWorkspaces) {
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          const result = await service.getWorkspaces();
+          return ok(result);
+        }
+
+        // ---- 平台管理器（多 IM 平台）----
+
+        // 本机可用的 DSH agent preset（设置页下拉用）。
+        // 只读、不含敏感信息：DSH 未提供 agentPresets 服务（旧版本）或名册读取失败时
+        // 返回 available:false，前端退化为手填，不影响会话创建。
+        if (endpoint === BRIDGE_ENDPOINTS.listAgentPresets) {
+          try {
+            const presets = ctx.get?.('agentPresets');
+            if (!presets?.list) return ok({ available: false, default: null, presets: [] });
+            const rows = await presets.list();
+            return ok({
+              available: true,
+              default: typeof presets.defaultId === 'string' ? presets.defaultId : null,
+              presets: (Array.isArray(rows) ? rows : [])
+                // 坏掉的预设不列出来（DSH 自己也会在挂载前拒绝）
+                .filter((p) => p && typeof p.id === 'string' && p.broken === undefined)
+                .map((p) => ({ id: p.id, name: typeof p.name === 'string' ? p.name : p.id })),
+            });
+          } catch (err) {
+            // 服务被卸载 / 名册不可读：这是设置页的辅助信息，不该让整个请求失败
+            logger?.warn?.('dsh-bridge: listAgentPresets failed: %s', err?.message ?? err);
+            return ok({ available: false, default: null, presets: [] });
+          }
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.listPlatforms) {
+          // #55：缺失时必须显错并记日志——此前 ok({}) 让前端把“查询失败”画成“即将支持”
+          if (!platformManager) {
+            try { logger?.error?.('dsh-bridge: listPlatforms without platformManager (see issue #55)'); } catch {}
+            return fail('internal', 'PlatformManager 未初始化，IM 平台清单不可用');
+          }
+          // 每个平台的 login.qrPayload 渲染为 dataURL 后返回
+          const raw = platformManager.getStatus();
+          if (!raw || Object.keys(raw).length === 0) {
+            try { logger?.warn?.('dsh-bridge: listPlatforms returned empty platform table'); } catch {}
+          }
+          const out = {};
+          for (const [id, status] of Object.entries(raw)) {
+            let qr = null;
+            try { qr = await renderStatusQr(status); } catch { /* ignore */ }
+            out[id] = { ...status, login: { ...(status.login ?? {}), qr, qrPayload: undefined, qrKind: undefined } };
+          }
+          return ok(out);
+        }
+
+        // ---- 平台操作（统一接口）----
+        // 参数统一支持 instanceId（新客户端）与 platformId（旧客户端，回退到该类型第一个实例）
+
+        if (endpoint === BRIDGE_ENDPOINTS.platformLogin) {
+          if (!platformManager) return fail('bad-request', 'PlatformManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          const resolved = resolvePlatformParam(platformManager, payload);
+          if (resolved.error) return resolved.error;
+          const { platform } = resolved;
+          const { qrType, refresh } = payload;
+          const result = await platform.login({ qrType, refresh });
+          if (!result.ok) return fail('bad-request', result.error ?? '登录启动失败');
+          const status = decoratePlatformStatus(platform);
+          const qr = await renderStatusQr(status);
+          return ok(withRenderedQr(status, qr));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.platformSetAllowFrom) {
+          if (!platformManager) return fail('bad-request', 'PlatformManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          const resolved = resolvePlatformParam(platformManager, payload);
+          if (resolved.error) return resolved.error;
+          const { platform } = resolved;
+          await platform.setAllowFrom(payload.allowFrom);
+          const status = decoratePlatformStatus(platform);
+          const qr = await renderStatusQr(status);
+          return ok(withRenderedQr(status, qr));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.platformSetConfig) {
+          if (!platformManager) return fail('bad-request', 'PlatformManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          const resolved = resolvePlatformParam(platformManager, payload);
+          if (resolved.error) return resolved.error;
+          const { platform } = resolved;
+          const config = { ...payload };
+          delete config.instanceId;
+          delete config.platformId;
+          // 同类型重复凭证校验（契约 §5）：与其它账号冲突时返回可读中文错误
+          if (typeof validatePlatformAccountConfig === 'function') {
+            try {
+              await validatePlatformAccountConfig(platform, config);
+            } catch (err) {
+              return fail('bad-request', err?.message ?? String(err));
+            }
+          }
+          await platform.setConfig(config);
+          const status = decoratePlatformStatus(platform);
+          const qr = await renderStatusQr(status);
+          return ok(withRenderedQr(status, qr));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.platformStop) {
+          if (!platformManager) return fail('bad-request', 'PlatformManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          const resolved = resolvePlatformParam(platformManager, payload);
+          if (resolved.error) return resolved.error;
+          const { platform } = resolved;
+          await platform.stop();
+          const status = decoratePlatformStatus(platform);
+          const qr = await renderStatusQr(status);
+          return ok(withRenderedQr(status, qr));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.platformStart) {
+          if (!platformManager) return fail('bad-request', 'PlatformManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          const resolved = resolvePlatformParam(platformManager, payload);
+          if (resolved.error) return resolved.error;
+          const { platform } = resolved;
+          await platform.start();
+          const status = decoratePlatformStatus(platform);
+          const qr = await renderStatusQr(status);
+          return ok(withRenderedQr(status, qr));
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.platformUnbind) {
+          if (!platformManager) return fail('bad-request', 'PlatformManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+
+          const resolved = resolvePlatformParam(platformManager, payload);
+          if (resolved.error) return resolved.error;
+          const { platform } = resolved;
+          await platform.unbind();
+          const status = decoratePlatformStatus(platform);
+          const qr = await renderStatusQr(status);
+          return ok(withRenderedQr(status, qr));
+        }
+
+        // ---- 平台账号管理（issue #78 多账号，高危：鉴权同 platformSetConfig）----
+
+        if (endpoint === BRIDGE_ENDPOINTS.platformAddAccount) {
+          if (!platformManager) return fail('bad-request', 'PlatformManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+          if (typeof addPlatformAccount !== 'function') return fail('internal', '多账号能力未接线');
+
+          try {
+            const result = await addPlatformAccount({ platformId: payload.platformId, name: payload.name });
+            return ok({ instanceId: result?.instanceId, status: result?.status ?? null });
+          } catch (err) {
+            logger?.warn?.('dsh-bridge: platformAddAccount failed: %s', err?.message ?? err);
+            return fail('bad-request', err?.message ?? String(err));
+          }
+        }
+
+        if (endpoint === BRIDGE_ENDPOINTS.platformRemoveAccount) {
+          if (!platformManager) return fail('bad-request', 'PlatformManager 未初始化');
+          const adminErr = checkAdminAuth(authManager, payload);
+          if (adminErr) return adminErr;
+          if (typeof removePlatformAccount !== 'function') return fail('internal', '多账号能力未接线');
+
+          try {
+            const result = await removePlatformAccount({ instanceId: payload.instanceId });
+            return ok({ ok: true, instanceId: result?.instanceId ?? payload.instanceId });
+          } catch (err) {
+            logger?.warn?.('dsh-bridge: platformRemoveAccount failed: %s', err?.message ?? err);
+            return fail('bad-request', err?.message ?? String(err));
+          }
+        }
+
+        return fail('bad-request', `Unknown endpoint: ${endpoint}`);
+      } catch (err) {
+        logger.error('RPC endpoint %s failed: %s', endpoint, err.message);
+        return fail('bad-request', err.message);
+      }
+    },
+    // DSH 0.1.0/0.1.1 支持 authority 选项（仅回环可达）；0.1.2+ 忽略之，透传无副作用。
+    // 见 lib/connection-compat.js 的 registerRpcChannel 说明。
+    { authority: 'loopback' },
+    logger
+  );
+}
+