hiwork-core 0.0.10 → 0.0.11

package/lib/types/managed-mcp.d.ts

@@ -0,0 +1,177 @@
+/**
+ * `/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 { type GatewayMcpAssignmentsView, type GatewayMcpAssertionTicket } from './ai-router-client.ts';
+/** RPC 频道；必须与 client 半边 `src/client/managed-mcp.ts` 的 `MANAGED_MCP_CHANNEL` 一致（由测试锁定）。 */
+export declare const MANAGED_MCP_RPC_CHANNEL = "/hiwork-managed-mcp";
+/**
+ * 端点白名单。
+ *
+ * `snapshot` 是「你现在有什么」（有缓存就直接给，冷启动才拉一次），`refresh` 是
+ * 「现在去拉一次」。分两个端点的理由：客户端的同步策略（启动 / 30 分钟 / 打开连接器页
+ * 且 >5min stale）由它自己定，Host 不该替它决定什么时候必须联网。
+ */
+export declare const MANAGED_MCP_RPC_ENDPOINTS: readonly ["snapshot", "refresh", "assertion"];
+export type ManagedMcpRpcEndpoint = (typeof MANAGED_MCP_RPC_ENDPOINTS)[number];
+/**
+ * Host 侧后台预热间隔：30 分钟（与客户端同步节奏同量级）。
+ * 它**不是**权威节奏——只为让客户端首次 `snapshot` 不必等一次网络往返。
+ */
+export declare const MANAGED_MCP_REFRESH_INTERVAL_MS: number;
+/** 一条分配交给客户端的形状（字段名与网关响应一致，是冻结契约的一部分）。 */
+export interface ManagedMcpAssignment {
+    assignmentId: string;
+    revision: number;
+    slug: string;
+    displayName: string;
+    serverName: string;
+    transport: string;
+    url: string;
+    extraHeaders: Record<string, string>;
+    auth: {
+        kind: string;
+        mintUrl: string;
+        revokeUrl: string;
+    };
+    updatedAt: string;
+}
+/**
+ * 一份清单快照。
+ *
+ * `stale` 为 true 表示「这是上一次成功的结果，最近一次拉取失败了」——调用方可以照常
+ * 展示，但**不得**把它用作删除本地连接的依据（那条路只允许走成功响应）。
+ */
+export interface ManagedMcpSnapshot {
+    /** 清单级序号（服务端任何影响清单的写入都 +1），客户端先比它再决定要不要深比对。 */
+    revision: number;
+    /** 本次成功拉取的时刻（RFC3339）。 */
+    fetchedAt: string;
+    assignments: ManagedMcpAssignment[];
+    stale: boolean;
+    /** 最近一次拉取失败的原因（成功时缺省）。 */
+    lastError?: ManagedMcpFailure;
+}
+/** 客户端可安全展示的失败。 */
+export interface ManagedMcpFailure {
+    code: string;
+    message: string;
+    /** DSH Connection 信封要求 `details` 是对象；协议层没有额外细节时补空对象。 */
+    details: object;
+}
+/** 端点结果信封（与 DSH Connection 的 `ConnectionRpcResult` 同形）。 */
+export type ManagedMcpRpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: ManagedMcpFailure;
+};
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export declare class ManagedMcpRequestError extends Error {
+    readonly code: 'bad-request';
+    constructor(code: 'bad-request', message: string);
+}
+/** Host 侧 RPC 依赖的最小上下文（结构兼容 cordis Context，便于单测伪造）。 */
+export interface ManagedMcpRpcConnection {
+    rpc: {
+        handle(channel: string, handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<unknown>, options: {
+            authority: 'loopback';
+        }): () => Promise<void> | void;
+    };
+}
+export interface ManagedMcpRpcContext {
+    readonly connection: ManagedMcpRpcConnection;
+    readonly logger: {
+        warn(message: string): void;
+    };
+}
+/** 网关客户端的 MCP 子集：只声明本频道真正调用的方法（结构兼容 `GatewayClient`）。 */
+export interface ManagedMcpGatewayPort {
+    getMyMcpAssignments(sessionCookie: string): Promise<GatewayMcpAssignmentsView>;
+    issueMyMcpAssertion(sessionCookie: string, assignmentId: string): Promise<GatewayMcpAssertionTicket>;
+}
+/** Host 侧取数依赖：会话解析 + 当前 baseURL 下的网关客户端。 */
+export interface ManagedMcpRpcDeps {
+    /**
+     * 解析网关会话 cookie（`AI_ROUTER_SESSION`）。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部使用，绝不出现在 RPC 响应里。**
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关客户端；baseURL 未配置时返回 undefined。 */
+    gateway(): ManagedMcpGatewayPort | undefined;
+    /** Host 日志出口（只记事件与错误类型，不记会话值 / 断言）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** 通用失败文案：不暴露任何网关细节。 */
+export declare const MANAGED_MCP_GENERIC_FAILURE_MESSAGE = "MCP \u6E05\u5355\u6682\u65F6\u65E0\u6CD5\u83B7\u53D6\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+/** 未登录 / 会话失效的统一文案（与用量、每日一句两个频道同口径）。 */
+export declare const MANAGED_MCP_SESSION_EXPIRED_MESSAGE = "\u767B\u5F55\u72B6\u6001\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55";
+/**
+ * 网关 message 消毒（与 `usage-rpc.ts` 的 `displayGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export declare function displayManagedMcpMessage(code: string, message: unknown): string;
+/** 端点入参：只有 `assertion` 带 `assignmentId`。 */
+export interface ManagedMcpRpcPayload {
+    assignmentId?: string | undefined;
+}
+/**
+ * payload 校验：`snapshot` / `refresh` 只放行空对象，`assertion` 只放行
+ * `{ assignmentId }`；其余字段 / 类型不符一律 `bad-request`。
+ */
+export declare function parseManagedMcpPayload(endpoint: ManagedMcpRpcEndpoint, raw: unknown): ManagedMcpRpcPayload;
+/** 是否为白名单端点。 */
+export declare function isManagedMcpRpcEndpoint(endpoint: string): endpoint is ManagedMcpRpcEndpoint;
+/**
+ * 清单缓存：**只有成功响应才覆写**，失败只记原因。
+ *
+ * 进程内的（不落盘）是有意的：清单是「服务端此刻认什么」的投影，跨重启的旧清单
+ * 没有任何价值——重启后客户端会立刻同步一次，拿到新的比拿到旧的更安全。
+ */
+export declare class ManagedMcpStore {
+    private readonly deps;
+    private readonly now;
+    private cached;
+    private lastError;
+    private inFlight;
+    constructor(deps: ManagedMcpRpcDeps, now?: () => number);
+    /**
+     * 当前缓存（同步读，不发请求）。从没成功过返回 undefined；
+     * 最近一次失败会以 `stale + lastError` 标注在上一次成功的结果上。
+     */
+    peek(): ManagedMcpSnapshot | undefined;
+    /**
+     * 去网关拉一次清单并更新缓存。失败时抛异常，且**缓存原样保留**。
+     *
+     * 并发调用合并成一次请求：后台预热与客户端手动同步撞在一起时不必打两遍网关。
+     */
+    load(): Promise<ManagedMcpSnapshot>;
+    private fetchOnce;
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ */
+export declare function handleManagedMcpEndpoint(endpoint: string, rawPayload: unknown, deps: ManagedMcpRpcDeps, store: ManagedMcpStore, signal?: AbortSignal): Promise<ManagedMcpRpcResult<unknown>>;
+/**
+ * 注册 `/hiwork-managed-mcp` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export declare function registerManagedMcpRpc(ctx: ManagedMcpRpcContext, deps: ManagedMcpRpcDeps, store: ManagedMcpStore): () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hiwork-core",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "type": "module",
   "description": "HiWork 企业统一登录与模型自动供给插件（ai-router 网关登录，Web 表单，无 CLI 认证）",
   "license": "UNLICENSED",