@actiondock/core 2.7.0 → 2.8.0

package/dist/server/mcp-endpoint.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 共享 MCP 端点处理器工厂配置选项。
+ *
+ * 覆盖 core 网关与 mcp 独立 HTTP 服务双方共同消费的配置面：
+ * - token 与 allowQueryToken 决定 Bearer 鉴权（含查询参数放行开关）；
+ * - corsOrigins 决定跨域响应头解析；
+ * - maxBodyBytes 决定请求体有界读取上限（防 DoS）；
+ * - corsApplyMode 决定 MCP 响应的 CORS 头部应用方式。
+ */
+export interface McpEndpointHandlerOptions {
+    /** 服务端预期的 Bearer Token（未配置时默认放行） */
+    token?: string;
+    /** 是否允许通过 URL 查询参数携带 Token（默认 false） */
+    allowQueryToken?: boolean;
+    /** 允许跨域请求的 CORS Origin 白名单列表 */
+    corsOrigins?: string[];
+    /** 最大允许的请求体字节限制（默认 1 MiB，防 DoS） */
+    maxBodyBytes?: number;
+    /** MCP 响应的 CORS 头部应用模式（默认 inherit 透传响应原头部） */
+    corsApplyMode?: McpCorsApplyMode;
+}
+/**
+ * MCP 委托处理器契约。
+ * 接收经限流重建后的标准 Request，返回 MCP 协议响应；
+ * 返回 null / undefined 表示委托方未处理，交回调用方继续后续路由。
+ */
+export type McpDelegateHandler = (req: Request) => Promise<Response | null | undefined> | Response | null | undefined;
+/**
+ * 构造 MCP 响应的 CORS 头部回写规则。
+ * - inherit：透传 MCP 响应自身头部（core 网关行为）；
+ * - merge：将解析出的 CORS 头部合并覆盖到 MCP 响应（mcp 独立服务行为）。
+ */
+export type McpCorsApplyMode = "inherit" | "merge";
+/**
+ * 共享 MCP 端点处理器契约。
+ *
+ * 返回 Response 表示已完整处理；返回 null / undefined 表示委托方未处理，
+ * 交回调用方继续后续路由分发。
+ */
+export type McpEndpointHandler = (req: Request) => Promise<Response | null | undefined>;
+/**
+ * 构造可复用的 MCP 端点处理器。
+ *
+ * 统一承载 core 网关端点与 mcp 独立 HTTP 服务共同遵循的请求处理子序列：
+ * verifyBearerToken 鉴权（401 标准 JSON）→ readBodyWithLimit 有界读取
+ * （413 处理）→ 委托 MCP 处理器 → 按 corsApplyMode 应用 CORS 头部。
+ *
+ * CORS 头部解析与 OPTIONS 预检由外层路由分发统一承担（两端点在健康检查、
+ * 全局鉴权等前置路由上存在形态差异，不宜在此收敛）；本处理器聚焦 MCP
+ * 端点自身的鉴权与请求体防护序列。
+ *
+ * 鉴权失败响应默认产出 core 网关标准错误形态；需要 JSON-RPC 错误形态的
+ * 调用方（如 mcp 独立服务）可通过 unauthorizedResponse 定制。
+ *
+ * @param delegate MCP 委托处理器（接收限流重建后的 Request）
+ * @param options 端点配置选项
+ */
+export declare function createMcpEndpointHandler(delegate: McpDelegateHandler, options?: McpEndpointHandlerOptions & {
+    /** 鉴权失败响应构造（默认产出 core 网关标准 401 JSON） */
+    unauthorizedResponse?: (corsHeaders: Record<string, string>) => Response;
+}): McpEndpointHandler;

package/dist/server/mcp-endpoint.js

@@ -0,0 +1,118 @@
+import { UNAUTHORIZED, REQUEST_TOO_LARGE } from "../errors.js";
+import { jsonResponse } from "./routes/common.js";
+import { DEFAULT_MAX_BODY_BYTES, readBodyWithLimit, RequestTooLargeError } from "./body.js";
+import { resolveCorsHeaders, verifyBearerToken } from "./security.js";
+/**
+ * 构造 413 Payload Too Large JSON 响应。
+ */
+function requestTooLargeResponse(corsHeaders) {
+    return jsonResponse({
+        ok: false,
+        error: {
+            code: REQUEST_TOO_LARGE,
+            message: "Request body exceeds maximum allowed size",
+        },
+    }, 413, corsHeaders);
+}
+/**
+ * 有界读取请求体并重建 Request。
+ *
+ * 读取与超限判定统一复用 body 域的 readBodyWithLimit 单一事实源；
+ * 超限时返回 null 表示应回退 413 响应，由调用方构造错误响应。
+ * 空请求体保持 body 为 undefined，与 core 网关历史行为逐字节一致。
+ *
+ * @param req 原始请求
+ * @param maxBytes 单次请求体允许的最大字节数
+ * @returns 重建后的请求；体积超限时返回 null
+ */
+async function rebuildRequestWithLimit(req, maxBytes) {
+    let merged;
+    try {
+        merged = await readBodyWithLimit(req, { maxBytes });
+    }
+    catch (err) {
+        if (err instanceof RequestTooLargeError) {
+            return null;
+        }
+        throw err;
+    }
+    const bodyInit = merged.byteLength > 0 ? new Blob([merged]) : undefined;
+    return new Request(req.url, {
+        method: req.method,
+        headers: req.headers,
+        body: bodyInit,
+        signal: req.signal,
+    });
+}
+/**
+ * 按指定模式为 MCP 响应附加 CORS 头部。
+ *
+ * @param response MCP 委托处理器返回的原始响应
+ * @param corsHeaders 本次请求解析出的 CORS 响应头
+ * @param mode CORS 头部应用模式（默认 inherit 透传）
+ */
+function applyCorsToResponse(response, corsHeaders, mode) {
+    if (mode !== "merge" || Object.keys(corsHeaders).length === 0) {
+        return response;
+    }
+    const newHeaders = new Headers(response.headers);
+    for (const [k, v] of Object.entries(corsHeaders)) {
+        newHeaders.set(k, String(v));
+    }
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: newHeaders,
+    });
+}
+/**
+ * 构造可复用的 MCP 端点处理器。
+ *
+ * 统一承载 core 网关端点与 mcp 独立 HTTP 服务共同遵循的请求处理子序列：
+ * verifyBearerToken 鉴权（401 标准 JSON）→ readBodyWithLimit 有界读取
+ * （413 处理）→ 委托 MCP 处理器 → 按 corsApplyMode 应用 CORS 头部。
+ *
+ * CORS 头部解析与 OPTIONS 预检由外层路由分发统一承担（两端点在健康检查、
+ * 全局鉴权等前置路由上存在形态差异，不宜在此收敛）；本处理器聚焦 MCP
+ * 端点自身的鉴权与请求体防护序列。
+ *
+ * 鉴权失败响应默认产出 core 网关标准错误形态；需要 JSON-RPC 错误形态的
+ * 调用方（如 mcp 独立服务）可通过 unauthorizedResponse 定制。
+ *
+ * @param delegate MCP 委托处理器（接收限流重建后的 Request）
+ * @param options 端点配置选项
+ */
+export function createMcpEndpointHandler(delegate, options = {}) {
+    const { token, allowQueryToken, corsOrigins, maxBodyBytes, unauthorizedResponse, } = options;
+    const maxBytes = maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const verifyOptions = { allowQueryToken };
+    return async (req) => {
+        const origin = req.headers.get("origin");
+        const corsHeaders = resolveCorsHeaders(origin, corsOrigins);
+        // Bearer Token 鉴权拦截
+        if (!verifyBearerToken(req, token, verifyOptions)) {
+            return (unauthorizedResponse?.(corsHeaders) ??
+                jsonResponse({
+                    ok: false,
+                    error: {
+                        code: UNAUTHORIZED,
+                        message: "Invalid or missing Bearer token",
+                    },
+                }, 401, corsHeaders));
+        }
+        // 请求体体积限制保护（复用 body 域有界读取单一事实源）
+        let mcpReq = req;
+        if (req.body && req.method !== "GET" && req.method !== "HEAD") {
+            const rebuilt = await rebuildRequestWithLimit(req, maxBytes);
+            if (!rebuilt) {
+                return requestTooLargeResponse(corsHeaders);
+            }
+            mcpReq = rebuilt;
+        }
+        const mcpRes = await delegate(mcpReq);
+        if (mcpRes) {
+            return applyCorsToResponse(mcpRes, corsHeaders, options.corsApplyMode ?? "inherit");
+        }
+        return mcpRes;
+    };
+}

package/dist/server/routes/actions.js

@@ -1,14 +1,13 @@
-import { randomUUID } from "node:crypto";
-import { ActionResolver } from "../../catalog/action-resolver.js";
+import { parseActionRef } from "../../catalog/resolve-action.js";
 import { filterByIntent } from "../../filter/index.js";
-import { ACTION_NOT_FOUND, ACTION_TIMEOUT, IDEMPOTENCY_CONFLICT, INPUT_VALIDATION_FAILED, PACKAGE_NOT_FOUND } from "../../errors.js";
+import { ACTION_EXECUTION_ERROR, ACTION_NOT_FOUND, ACTION_START_FAILED, ACTION_TIMEOUT, ACTIONS_LIST_ERROR, IDEMPOTENCY_CONFLICT, INPUT_VALIDATION_FAILED, INVALID_JSON, PACKAGE_FORBIDDEN, PACKAGE_NOT_FOUND, REQUEST_TOO_LARGE, } from "../../errors.js";
 import { InvalidJsonError, readJsonBody, RequestTooLargeError } from "../body.js";
 import { getSubPath, jsonResponse } from "./common.js";
 /**
  * 处理 Action 相关的 HTTP 路由（列表、规范查询、同步执行与异步启动）。
  */
 export async function handleActionsRoutes(ctx) {
-    const { req, url, pathname, corsHeaders, options, target } = ctx;
+    const { req, url, pathname, corsHeaders, options, service } = ctx;
     const subpath = getSubPath(pathname);
     // 1. Actions List: GET /api/v2/actions, GET /actions
     if (subpath === "/actions" && req.method === "GET") {
@@ -18,7 +17,7 @@ export async function handleActionsRoutes(ctx) {
             const targetPkg = url.searchParams.get("package") || url.searchParams.get("packageId") || undefined;
             const prefix = url.searchParams.get("prefix") || undefined;
             const tags = url.searchParams.getAll("tag");
-            let actions = await target.listActions({
+            let actions = await service.discovery.listActions({
                 query,
                 prefix,
                 tags: tags.length > 0 ? tags : undefined,
@@ -37,7 +36,7 @@ export async function handleActionsRoutes(ctx) {
         catch (err) {
             return jsonResponse({
                 ok: false,
-                error: { code: "ACTIONS_LIST_ERROR", message: err.message },
+                error: { code: ACTIONS_LIST_ERROR, message: err.message },
             }, 500, corsHeaders);
         }
     }
@@ -51,7 +50,7 @@ export async function handleActionsRoutes(ctx) {
                 return jsonResponse({
                     ok: false,
                     error: {
-                        code: "PACKAGE_FORBIDDEN",
+                        code: PACKAGE_FORBIDDEN,
                         message: `Package '${packageId}' is not in the allowed package list`,
                     },
                 }, 403, corsHeaders);
@@ -59,7 +58,7 @@ export async function handleActionsRoutes(ctx) {
         }
         const ref = `${packageId}/${actionId}`;
         try {
-            const spec = await target.describeAction(ref);
+            const spec = await service.discovery.describeAction(ref);
             return jsonResponse(spec, 200, corsHeaders);
         }
         catch (err) {
@@ -77,13 +76,13 @@ export async function handleActionsRoutes(ctx) {
     if (actionShowMatch && req.method === "GET") {
         const actionId = decodeURIComponent(actionShowMatch[1]);
         try {
-            const parsed = ActionResolver.parseRef(actionId);
+            const parsed = parseActionRef(actionId);
             if (parsed.packageId && options.packageAllowlist && options.packageAllowlist.length > 0) {
                 if (!options.packageAllowlist.includes(parsed.packageId)) {
                     return jsonResponse({
                         ok: false,
                         error: {
-                            code: "PACKAGE_FORBIDDEN",
+                            code: PACKAGE_FORBIDDEN,
                             message: `Package '${parsed.packageId}' is not in the allowed package list`,
                         },
                     }, 403, corsHeaders);
@@ -92,14 +91,14 @@ export async function handleActionsRoutes(ctx) {
         }
         catch { }
         try {
-            const spec = await target.describeAction(actionId);
+            const spec = await service.discovery.describeAction(actionId);
             if (options.packageAllowlist &&
                 options.packageAllowlist.length > 0 &&
                 (!spec.packageId || !options.packageAllowlist.includes(spec.packageId))) {
                 return jsonResponse({
                     ok: false,
                     error: {
-                        code: "PACKAGE_FORBIDDEN",
+                        code: PACKAGE_FORBIDDEN,
                         message: `Package '${spec.packageId}' is not in the allowed package list`,
                     },
                 }, 403, corsHeaders);
@@ -138,7 +137,7 @@ export async function handleActionsRoutes(ctx) {
             actionRef = decodeURIComponent(shortRunMatch[1]);
             endpointMode = shortRunMatch[2];
             try {
-                const parsed = ActionResolver.parseRef(actionRef);
+                const parsed = parseActionRef(actionRef);
                 pkgId = parsed.packageId;
             }
             catch { }
@@ -147,7 +146,7 @@ export async function handleActionsRoutes(ctx) {
         if (options.packageAllowlist && options.packageAllowlist.length > 0) {
             if (!pkgId) {
                 try {
-                    const spec = await target.describeAction(actionRef);
+                    const spec = await service.discovery.describeAction(actionRef);
                     pkgId = spec?.packageId;
                 }
                 catch { }
@@ -155,9 +154,9 @@ export async function handleActionsRoutes(ctx) {
             if (!pkgId || !options.packageAllowlist.includes(pkgId)) {
                 return jsonResponse({
                     ok: false,
-                    runId: randomUUID(),
+                    runId: "",
                     error: {
-                        code: "PACKAGE_FORBIDDEN",
+                        code: PACKAGE_FORBIDDEN,
                         message: pkgId
                             ? `Package '${pkgId}' is not in the allowed package list`
                             : `Action '${actionRef}' does not belong to any allowed package`,
@@ -173,21 +172,21 @@ export async function handleActionsRoutes(ctx) {
             if (err instanceof RequestTooLargeError) {
                 return jsonResponse({
                     ok: false,
-                    runId: randomUUID(),
-                    error: { code: "REQUEST_TOO_LARGE", message: err.message },
+                    runId: "",
+                    error: { code: REQUEST_TOO_LARGE, message: err.message },
                 }, 413, corsHeaders);
             }
             if (err instanceof InvalidJsonError) {
                 return jsonResponse({
                     ok: false,
-                    runId: randomUUID(),
-                    error: { code: "INVALID_JSON", message: err.message },
+                    runId: "",
+                    error: { code: INVALID_JSON, message: err.message },
                 }, 400, corsHeaders);
             }
             return jsonResponse({
                 ok: false,
-                runId: randomUUID(),
-                error: { code: "INVALID_JSON", message: `Failed to parse request body: ${err.message}` },
+                runId: "",
+                error: { code: INVALID_JSON, message: `Failed to parse request body: ${err.message}` },
             }, 400, corsHeaders);
         }
         const isAsync = endpointMode === "start" ||
@@ -205,9 +204,16 @@ export async function handleActionsRoutes(ctx) {
             body?.requestId ||
             body?.execution?.requestId ||
             undefined;
+        let actionRefObj;
+        try {
+            actionRefObj = parseActionRef(actionRef);
+        }
+        catch {
+            actionRefObj = { actionId: actionRef };
+        }
         if (isAsync) {
             try {
-                const ticket = await target.startAction(actionRef, input, {
+                const ticket = await service.execution.start(actionRefObj, input, {
                     timeoutMs,
                     config: configOverrides,
                     requestId,
@@ -236,9 +242,9 @@ export async function handleActionsRoutes(ctx) {
                 }
                 return jsonResponse({
                     ok: false,
-                    runId: randomUUID(),
+                    runId: "",
                     error: {
-                        code: "ACTION_START_FAILED",
+                        code: ACTION_START_FAILED,
                         message: err.message || String(err),
                     },
                 }, 500, corsHeaders);
@@ -246,7 +252,7 @@ export async function handleActionsRoutes(ctx) {
         }
         // 同步执行模式
         try {
-            const result = await target.runAction(actionRef, input, {
+            const result = await service.execution.run(actionRefObj, input, {
                 signal: req.signal,
                 timeoutMs,
                 config: configOverrides,
@@ -286,9 +292,9 @@ export async function handleActionsRoutes(ctx) {
             }
             return jsonResponse({
                 ok: false,
-                runId: randomUUID(),
+                runId: "",
                 error: {
-                    code: "ACTION_EXECUTION_ERROR",
+                    code: ACTION_EXECUTION_ERROR,
                     message: err.message || String(err),
                 },
             }, 500, corsHeaders);

package/dist/server/routes/common.d.ts

@@ -1,6 +1,5 @@
-import type { ActionDockApp } from "../../app/types.js";
-import type { ActionDockHost } from "../../host/types.js";
-import type { ActionDockTarget } from "../../target/types.js";
+import type { PackageInfo } from "../../package/types.js";
+import type { ActionDockService } from "../../service/types.js";
 import type { ServerOptions } from "../types.js";
 /**
  * 路由处理统一上下文对象。
@@ -12,8 +11,7 @@ export interface RouteContext {
     corsHeaders: Record<string, string>;
     projectRoot: string | null;
     customHome?: string;
-    host?: ActionDockHost;
-    target: ActionDockTarget;
+    service: ActionDockService;
     options: ServerOptions;
 }
 /**
@@ -21,27 +19,25 @@ export interface RouteContext {
  */
 export declare function jsonResponse(data: unknown, status?: number, corsHeaders?: Record<string, string>): Response;
 /**
- * 剥离标准版本前缀 (/api/v2/ 与兼容的 /api/v1/)，获取相对路由子路径。
+ * 剥离标准版本前缀 (/api/v2/)，获取相对路由子路径。
  */
 export declare function getSubPath(pathname: string): string;
+import { ActionDockError } from "../../errors.js";
 /**
  * 包未列入白名单拒绝访问异常。
  */
-export declare class PackageNotAllowedError extends Error {
+export declare class PackageNotAllowedError extends ActionDockError {
     status: number;
     statusCode: number;
-    code: string;
     constructor(packageId: string);
 }
 /**
  * 校验目标 packageId 是否属于允许包白名单。
  * 当 options.packageAllowlist 存在且目标 packageId 不在白名单中时抛出 403 PACKAGE_NOT_ALLOWED 异常。
  */
-export declare function assertPackageAllowed(packageId: string | undefined | null, options?: {
-    packageAllowlist?: string[];
-}): void;
+export declare function assertPackageAllowed(packageId: string, options?: ServerOptions): void;
 /**
- * 从 Host 或 Target 中依据 packageId 解析对应的 ActionDockApp 实例。
- * 若提供了 options，过滤或优先选择白名单内的 app。
+ * 解析并确定生效的目标 packageId。
+ * 遵循严格的解析规则与白名单检查。
  */
-export declare function resolveAppForPackage(packageIdOrPath: string | undefined, host?: ActionDockHost, target?: ActionDockTarget, options?: ServerOptions): ActionDockApp;
+export declare function resolveTargetPackageId(packages: PackageInfo[], requestedPackageId?: string, options?: ServerOptions): string;

package/dist/server/routes/common.js

@@ -12,27 +12,25 @@ export function jsonResponse(data, status = 200, corsHeaders = {}) {
     });
 }
 /**
- * 剥离标准版本前缀 (/api/v2/ 与兼容的 /api/v1/)，获取相对路由子路径。
+ * 剥离标准版本前缀 (/api/v2/)，获取相对路由子路径。
  */
 export function getSubPath(pathname) {
     if (pathname.startsWith("/api/v2/")) {
         return pathname.slice(7);
     }
-    if (pathname.startsWith("/api/v1/")) {
-        return pathname.slice(7);
-    }
     return pathname;
 }
+import { ActionDockError, PACKAGE_NOT_FOUND, PACKAGE_NOT_ALLOWED } from "../../errors.js";
 /**
  * 包未列入白名单拒绝访问异常。
  */
-export class PackageNotAllowedError extends Error {
+export class PackageNotAllowedError extends ActionDockError {
     status = 403;
     statusCode = 403;
-    code = "PACKAGE_NOT_ALLOWED";
     constructor(packageId) {
-        super(`Package '${packageId}' is not in the allowed package list`);
+        super(PACKAGE_NOT_ALLOWED, `Package '${packageId}' is not in the allowed package list`);
         this.name = "PackageNotAllowedError";
+        Object.setPrototypeOf(this, PackageNotAllowedError.prototype);
     }
 }
 /**
@@ -42,63 +40,41 @@ export class PackageNotAllowedError extends Error {
 export function assertPackageAllowed(packageId, options) {
     if (options?.packageAllowlist &&
         Array.isArray(options.packageAllowlist) &&
-        options.packageAllowlist.length > 0) {
-        if (!packageId || !options.packageAllowlist.includes(packageId)) {
-            throw new PackageNotAllowedError(packageId || "");
-        }
+        options.packageAllowlist.length > 0 &&
+        !options.packageAllowlist.includes(packageId)) {
+        throw new PackageNotAllowedError(packageId);
     }
 }
 /**
- * 从 Host 或 Target 中依据 packageId 解析对应的 ActionDockApp 实例。
- * 若提供了 options，过滤或优先选择白名单内的 app。
+ * 解析并确定生效的目标 packageId。
+ * 遵循严格的解析规则与白名单检查。
  */
-export function resolveAppForPackage(packageIdOrPath, host, target, options) {
-    if (packageIdOrPath) {
-        assertPackageAllowed(packageIdOrPath, options);
-        assertValidPackageId(packageIdOrPath);
-        if (host) {
-            const app = host.getApp(packageIdOrPath);
-            if (app)
-                return app;
-        }
-        const innerTarget = target?.unwrap?.();
-        if (innerTarget && "packageId" in innerTarget && innerTarget.packageId === packageIdOrPath) {
-            return innerTarget;
+export function resolveTargetPackageId(packages, requestedPackageId, options) {
+    if (requestedPackageId) {
+        if (requestedPackageId === "global") {
+            return "global";
         }
-        if (innerTarget && "getApp" in innerTarget) {
-            const app = innerTarget.getApp(packageIdOrPath);
-            if (app)
-                return app;
+        assertValidPackageId(requestedPackageId);
+        assertPackageAllowed(requestedPackageId, options);
+        const matched = packages.find((p) => p.id === requestedPackageId || p.packageRoot === requestedPackageId);
+        if (!matched) {
+            throw new ActionDockError(PACKAGE_NOT_FOUND, `Unknown or unregistered package: '${requestedPackageId}'`);
         }
-        throw new Error(`Unknown or unregistered package: '${packageIdOrPath}'`);
+        return matched.id;
     }
-    if (host) {
-        const apps = host.listApps();
-        if (options?.packageAllowlist &&
-            Array.isArray(options.packageAllowlist) &&
-            options.packageAllowlist.length > 0) {
-            const allowedApp = apps.find((a) => options.packageAllowlist.includes(a.packageId));
-            if (allowedApp)
-                return allowedApp;
-        }
-        if (apps.length > 0)
-            return apps[0];
+    let targetId;
+    if (options?.packageAllowlist &&
+        Array.isArray(options.packageAllowlist) &&
+        options.packageAllowlist.length > 0) {
+        const allowed = packages.find((p) => options.packageAllowlist.includes(p.id));
+        targetId = allowed ? allowed.id : (packages[0]?.id || "");
     }
-    const innerTarget = target?.unwrap?.();
-    if (innerTarget && "listApps" in innerTarget) {
-        const apps = innerTarget.listApps();
-        if (options?.packageAllowlist &&
-            Array.isArray(options.packageAllowlist) &&
-            options.packageAllowlist.length > 0) {
-            const allowedApp = apps.find((a) => options.packageAllowlist.includes(a.packageId));
-            if (allowedApp)
-                return allowedApp;
-        }
-        if (apps.length > 0)
-            return apps[0];
+    else if (packages.length > 0) {
+        targetId = packages[0].id;
     }
-    if (innerTarget && "packageId" in innerTarget) {
-        return innerTarget;
+    else {
+        throw new ActionDockError(PACKAGE_NOT_FOUND, "No registered package found in service");
     }
-    throw new Error("No registered package found in host or target");
+    assertPackageAllowed(targetId, options);
+    return targetId;
 }