hiwork-core 0.0.10 → 0.0.16

package/lib/managed-mcp.js

@@ -0,0 +1,334 @@
+/**
+ * `/hiwork-managed-mcp` loopback RPC 的 Host 实现：管理员下发的 MCP 清单 + 换令牌用的短期断言。
+ *
+ * 设计要点（与 `src/usage-rpc.ts` / `src/daily-rpc.ts` 同构，差异都在下面写清）：
+ *  - 只注册一个 channel，endpoint 白名单在 {@link MANAGED_MCP_RPC_ENDPOINTS}，未知
+ *    endpoint 直接 `bad-request`；
+ *  - payload 严格校验：`snapshot` / `refresh` 只接受空对象，`assertion` 只接受
+ *    `{ assignmentId }`（这是唯一一处客户端可控输入，形状卡死在 Host）；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方拿到的是清单与断言，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - **本频道不换令牌、不持有令牌**。断言只是一张 120 秒的门票，拿它去 MCP 服务的
+ *    `/mcp-credential-exchange` 换 per-user 令牌是客户端（hiwork-capabilities）的事。
+ *    这样 ai-hub 与 hiwork-core 全程经手不了任何 MCP 凭据，被攻破也拿不到东西。
+ *  - **拉清单失败绝不清空上一次成功的清单**：客户端只有在拿到一份「成功拉到的清单」
+ *    时才允许删除本地受管连接，所以失败必须以「保留旧值 + 标注失败原因」的形状返回，
+ *    否则一次网络抖动就会让员工端把自己卸载干净。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link ManagedMcpRpcContext} 端口，
+ * 便于单测直接伪造。
+ */
+import { GatewayError, } from "./ai-router-client.js";
+/** RPC 频道；必须与 client 半边 `src/client/managed-mcp.ts` 的 `MANAGED_MCP_CHANNEL` 一致（由测试锁定）。 */
+export const MANAGED_MCP_RPC_CHANNEL = '/hiwork-managed-mcp';
+/**
+ * 端点白名单。
+ *
+ * `snapshot` 是「你现在有什么」（有缓存就直接给，冷启动才拉一次），`refresh` 是
+ * 「现在去拉一次」。分两个端点的理由：客户端的同步策略（启动 / 30 分钟 / 打开连接器页
+ * 且 >5min stale）由它自己定，Host 不该替它决定什么时候必须联网。
+ */
+export const MANAGED_MCP_RPC_ENDPOINTS = ['snapshot', 'refresh', 'assertion'];
+/**
+ * Host 侧后台预热间隔：30 分钟（与客户端同步节奏同量级）。
+ * 它**不是**权威节奏——只为让客户端首次 `snapshot` 不必等一次网络往返。
+ */
+export const MANAGED_MCP_REFRESH_INTERVAL_MS = 30 * 60_000;
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export class ManagedMcpRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ManagedMcpRequestError';
+    }
+}
+/** 各稳定错误码的用户可见文案（网关 message 含实现细节时用它兜底）。 */
+const MANAGED_MCP_MESSAGE_FALLBACK = {
+    SESSION_EXPIRED: '登录状态已过期，请重新登录',
+    GATEWAY_UNREACHABLE: '网关暂时不可用，请稍后重试',
+    MCP_ASSIGNMENT_GONE: '这条分配已失效，稍后同步会重新核对',
+    MCP_NOT_DELIVERABLE: '该 MCP 服务当前不可下发，请联系管理员',
+    MCP_ASSERTION_DISABLED: '本部署未启用 MCP 断言签发，请联系管理员',
+    NO_KEY_ASSIGNED: '当前账号尚未被分配虚拟 KEY，请联系管理员',
+};
+/** 通用失败文案：不暴露任何网关细节。 */
+export const MANAGED_MCP_GENERIC_FAILURE_MESSAGE = 'MCP 清单暂时无法获取，请稍后重试';
+/** 未登录 / 会话失效的统一文案（与用量、每日一句两个频道同口径）。 */
+export const MANAGED_MCP_SESSION_EXPIRED_MESSAGE = '登录状态已过期，请重新登录';
+/**
+ * 网关 message 消毒（与 `usage-rpc.ts` 的 `displayGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export function displayManagedMcpMessage(code, message) {
+    const text = typeof message === 'string' ? message.trim() : '';
+    if (text === '')
+        return MANAGED_MCP_MESSAGE_FALLBACK[code] ?? MANAGED_MCP_GENERIC_FAILURE_MESSAGE;
+    const leaksImplementationDetail = /https?:\/\//i.test(text)
+        || /\bHTTP\s*\d{3}\b/i.test(text)
+        || /\bbaseURL\b/i.test(text);
+    if (leaksImplementationDetail)
+        return MANAGED_MCP_MESSAGE_FALLBACK[code] ?? MANAGED_MCP_GENERIC_FAILURE_MESSAGE;
+    return text;
+}
+/**
+ * `assertion` 的 assignmentId 形状：只放行 uuid 用的字符集与长度（1–64）。
+ * 这是全频道唯一一处客户端可控输入，卡在 Host 比卡在网关早——一个带空格 / 换行 /
+ * 百分号的串没有任何合法来源，直接 `bad-request`。
+ */
+const ASSIGNMENT_ID_PATTERN = /^[0-9a-fA-F-]{1,64}$/;
+/**
+ * payload 校验：`snapshot` / `refresh` 只放行空对象，`assertion` 只放行
+ * `{ assignmentId }`；其余字段 / 类型不符一律 `bad-request`。
+ */
+export function parseManagedMcpPayload(endpoint, raw) {
+    if (raw === undefined || raw === null) {
+        if (endpoint === 'assertion')
+            throw new ManagedMcpRequestError('bad-request', '取断言请求缺少 assignmentId。');
+        return {};
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ManagedMcpRequestError('bad-request', 'MCP 清单请求参数不合法。');
+    }
+    const record = raw;
+    const keys = Object.keys(record);
+    if (endpoint !== 'assertion') {
+        // snapshot / refresh 无任何入参：出现任何字段都是客户端实现缺陷。
+        if (keys.length > 0)
+            throw new ManagedMcpRequestError('bad-request', `MCP 清单请求包含未知字段 '${keys[0]}'。`);
+        return {};
+    }
+    for (const key of keys) {
+        if (key !== 'assignmentId')
+            throw new ManagedMcpRequestError('bad-request', `取断言请求包含未知字段 '${key}'。`);
+    }
+    const rawId = record['assignmentId'];
+    if (typeof rawId !== 'string' || !ASSIGNMENT_ID_PATTERN.test(rawId.trim())) {
+        throw new ManagedMcpRequestError('bad-request', '取断言请求的 assignmentId 不合法。');
+    }
+    return { assignmentId: rawId.trim() };
+}
+/** 是否为白名单端点。 */
+export function isManagedMcpRpcEndpoint(endpoint) {
+    return MANAGED_MCP_RPC_ENDPOINTS.includes(endpoint);
+}
+/** 非空字符串或 undefined（清单里一个字段坏了不该让整条清单失败）。 */
+function textOrUndefined(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * 把网关响应里的一条分配规范化成 {@link ManagedMcpAssignment}。
+ *
+ * **结构不完整就整条丢弃**（缺 id / serverName / url / auth.mintUrl 的条目装不了，
+ * 留着只会在下游变成一次诡异的失败），丢弃时记一条日志——服务端数据问题的证据在
+ * Host 侧，客户端看不到网关响应。
+ *
+ * **但 `transport` 与 `auth.kind` 不做白名单过滤**：认不认识的判断属于连接器域
+ * （hiwork-capabilities 知道自己能装什么），它要按「不认识的 kind 跳过并报冲突」的
+ * 契约把问题报到界面上；Host 在这里悄悄丢掉，冲突就永远不会被人看见。
+ */
+function normalizeAssignment(raw, log) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const assignmentId = textOrUndefined(record['assignmentId']);
+    const serverName = textOrUndefined(record['serverName']);
+    const url = textOrUndefined(record['url']);
+    const transport = textOrUndefined(record['transport']);
+    const authRaw = record['auth'];
+    const auth = typeof authRaw === 'object' && authRaw !== null && !Array.isArray(authRaw)
+        ? authRaw
+        : undefined;
+    const kind = textOrUndefined(auth?.['kind']);
+    const mintUrl = textOrUndefined(auth?.['mintUrl']);
+    if (assignmentId === undefined || serverName === undefined || url === undefined
+        || transport === undefined || kind === undefined || mintUrl === undefined) {
+        log?.('hiwork-core: MCP 清单里有一条结构不完整的分配，已跳过');
+        return undefined;
+    }
+    const revision = record['revision'];
+    return {
+        assignmentId,
+        revision: typeof revision === 'number' && Number.isFinite(revision) ? revision : 0,
+        slug: textOrUndefined(record['slug']) ?? serverName,
+        displayName: textOrUndefined(record['displayName']) ?? serverName,
+        serverName,
+        transport,
+        url,
+        extraHeaders: stringMap(record['extraHeaders']),
+        auth: { kind, mintUrl, revokeUrl: textOrUndefined(auth?.['revokeUrl']) ?? '' },
+        updatedAt: textOrUndefined(record['updatedAt']) ?? '',
+    };
+}
+/** 头映射：只保留值为字符串的键（其余静默丢弃，头值只能是字符串）。 */
+function stringMap(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === 'string')
+            out[key] = value;
+    }
+    return out;
+}
+/** 任意异常 → 可展示的失败（网关 code 透传，message 消毒；其余收敛为通用失败）。 */
+function failureOf(error) {
+    if (error instanceof ManagedMcpRequestError)
+        return { code: error.code, message: error.message, details: {} };
+    if (error instanceof GatewayError) {
+        return { code: error.code, message: displayManagedMcpMessage(error.code, error.message), details: {} };
+    }
+    return { code: 'internal', message: MANAGED_MCP_GENERIC_FAILURE_MESSAGE, details: {} };
+}
+/**
+ * 清单缓存：**只有成功响应才覆写**，失败只记原因。
+ *
+ * 进程内的（不落盘）是有意的：清单是「服务端此刻认什么」的投影，跨重启的旧清单
+ * 没有任何价值——重启后客户端会立刻同步一次，拿到新的比拿到旧的更安全。
+ */
+export class ManagedMcpStore {
+    deps;
+    now;
+    cached;
+    lastError;
+    inFlight;
+    constructor(deps, now = () => Date.now()) {
+        this.deps = deps;
+        this.now = now;
+    }
+    /**
+     * 当前缓存（同步读，不发请求）。从没成功过返回 undefined；
+     * 最近一次失败会以 `stale + lastError` 标注在上一次成功的结果上。
+     */
+    peek() {
+        if (this.cached === undefined)
+            return undefined;
+        return this.lastError === undefined
+            ? this.cached
+            : { ...this.cached, stale: true, lastError: this.lastError };
+    }
+    /**
+     * 去网关拉一次清单并更新缓存。失败时抛异常，且**缓存原样保留**。
+     *
+     * 并发调用合并成一次请求：后台预热与客户端手动同步撞在一起时不必打两遍网关。
+     */
+    async load() {
+        if (this.inFlight !== undefined)
+            return await this.inFlight;
+        const task = this.fetchOnce();
+        this.inFlight = task;
+        try {
+            return await task;
+        }
+        finally {
+            this.inFlight = undefined;
+        }
+    }
+    async fetchOnce() {
+        try {
+            const sessionCookie = await this.deps.resolveSession();
+            if (sessionCookie === undefined || sessionCookie === '') {
+                throw new GatewayError('SESSION_EXPIRED', MANAGED_MCP_SESSION_EXPIRED_MESSAGE);
+            }
+            const gateway = this.deps.gateway();
+            if (gateway === undefined) {
+                throw new GatewayError('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+            }
+            const view = await gateway.getMyMcpAssignments(sessionCookie);
+            const assignments = [];
+            for (const item of Array.isArray(view?.assignments) ? view.assignments : []) {
+                const normalized = normalizeAssignment(item, this.deps.log);
+                if (normalized !== undefined)
+                    assignments.push(normalized);
+            }
+            const snapshot = {
+                revision: typeof view?.revision === 'number' && Number.isFinite(view.revision) ? view.revision : 0,
+                fetchedAt: new Date(this.now()).toISOString(),
+                assignments,
+                stale: false,
+            };
+            this.cached = snapshot;
+            this.lastError = undefined;
+            return snapshot;
+        }
+        catch (error) {
+            this.lastError = failureOf(error);
+            throw error;
+        }
+    }
+}
+/** 取消判定（用函数包一层，避免 TS 把属性窄化固化到 `await` 之后）。 */
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ */
+export async function handleManagedMcpEndpoint(endpoint, rawPayload, deps, store, signal) {
+    try {
+        if (isAborted(signal))
+            return failure('cancelled', 'MCP 清单请求已取消。');
+        if (!isManagedMcpRpcEndpoint(endpoint)) {
+            throw new ManagedMcpRequestError('bad-request', `未知的 MCP 清单端点 '${endpoint}'`);
+        }
+        const payload = parseManagedMcpPayload(endpoint, rawPayload);
+        if (endpoint === 'assertion') {
+            const assignmentId = payload.assignmentId;
+            if (assignmentId === undefined)
+                throw new ManagedMcpRequestError('bad-request', '取断言请求缺少 assignmentId。');
+            return await handleAssertion(assignmentId, deps, signal);
+        }
+        // snapshot：有缓存就直接给（可能是 stale），冷启动才走一次网络。
+        const cached = store.peek();
+        if (endpoint === 'snapshot' && cached !== undefined)
+            return { ok: true, value: cached };
+        return { ok: true, value: await store.load() };
+    }
+    catch (error) {
+        deps.log?.(`hiwork-core: MCP 清单 RPC '${endpoint}' 失败（${error instanceof Error ? error.name : typeof error}）`);
+        return { ok: false, error: failureOf(error) };
+    }
+}
+/** `assertion`：每次都要新的（120 秒的门票，缓存下来的那一张只会是废纸）。 */
+async function handleAssertion(assignmentId, deps, signal) {
+    const sessionCookie = await deps.resolveSession();
+    if (sessionCookie === undefined || sessionCookie === '') {
+        return failure('SESSION_EXPIRED', MANAGED_MCP_SESSION_EXPIRED_MESSAGE);
+    }
+    const gateway = deps.gateway();
+    if (gateway === undefined) {
+        return failure('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+    }
+    if (isAborted(signal))
+        return failure('cancelled', 'MCP 清单请求已取消。');
+    const ticket = await gateway.issueMyMcpAssertion(sessionCookie, assignmentId);
+    const assertion = textOrUndefined(ticket?.assertion);
+    const mintUrl = textOrUndefined(ticket?.mintUrl);
+    if (assertion === undefined || mintUrl === undefined) {
+        deps.log?.('hiwork-core: 取断言收到无效响应（缺 assertion / mintUrl）');
+        return failure('internal', MANAGED_MCP_GENERIC_FAILURE_MESSAGE);
+    }
+    return {
+        ok: true,
+        value: {
+            assertion,
+            mintUrl,
+            revokeUrl: textOrUndefined(ticket?.revokeUrl) ?? '',
+            expiresAt: textOrUndefined(ticket?.expiresAt) ?? '',
+            serverName: textOrUndefined(ticket?.serverName) ?? '',
+        },
+    };
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/**
+ * 注册 `/hiwork-managed-mcp` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export function registerManagedMcpRpc(ctx, deps, store) {
+    const handler = (endpoint, payload, signal) => handleManagedMcpEndpoint(endpoint, payload, deps, store, signal);
+    const remove = ctx.connection.rpc.handle(MANAGED_MCP_RPC_CHANNEL, handler, { authority: 'loopback' });
+    return async () => { await remove(); };
+}