@actiondock/core 2.0.11 → 2.2.0

package/dist/server/security.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 恒定时间字符串比较（Constant-time comparison）。
+ * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。
+ *
+ * @param a 字符串 A
+ * @param b 字符串 B
+ * @returns 两个字符串内容是否完全一致
+ */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * 检查指定的主机地址是否为本地回环接口（Loopback Host）。
+ * 支持 127.0.0.1, localhost, ::1 等形式。
+ *
+ * @param host 主机名或 IP 字符串
+ */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * 校验 HTTP 请求中的鉴权令牌选项。
+ */
+export interface VerifyBearerTokenOptions {
+    /** 是否允许通过 URL 查询参数携带 Token（默认 false） */
+    allowQueryToken?: boolean;
+}
+/**
+ * 校验 HTTP 请求中的鉴权令牌是否有效。
+ *
+ * 默认仅接受 HTTP 请求头: `Authorization: Bearer <token>`。
+ * 仅当 options.allowQueryToken 为 true 时才允许解析 URL 查询参数 `?token=<token>`。
+ *
+ * @param req 传入的 HTTP Request 对象
+ * @param expectedToken 服务端预期的正确 Token（若未配置 Token 则默认放行）
+ * @param options 校验选项或布尔值 allowQueryToken 开关
+ * @returns 是否鉴权成功
+ */
+export declare function verifyBearerToken(req: Request, expectedToken?: string, options?: VerifyBearerTokenOptions | boolean): boolean;
+/**
+ * 根据配置的 CORS 白名单解析并返回跨域响应头。
+ * 默认情况下若未配置 corsOrigins，返回空对象（即默认关闭跨域访问，防范 CSRF）。
+ *
+ * @param origin 请求头中的 Origin 字段
+ * @param allowedOrigins 允许跨域的白名单来源数组
+ * @returns 包含 Access-Control-* 的响应头对象
+ */
+export declare function resolveCorsHeaders(origin: string | null, allowedOrigins?: string[]): Record<string, string>;

package/dist/server/security.js

@@ -0,0 +1,101 @@
+import { timingSafeEqual } from "node:crypto";
+/**
+ * 恒定时间字符串比较（Constant-time comparison）。
+ * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。
+ *
+ * @param a 字符串 A
+ * @param b 字符串 B
+ * @returns 两个字符串内容是否完全一致
+ */
+export function safeEqual(a, b) {
+    const aa = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (aa.length !== bb.length) {
+        return false;
+    }
+    return timingSafeEqual(aa, bb);
+}
+/**
+ * 检查指定的主机地址是否为本地回环接口（Loopback Host）。
+ * 支持 127.0.0.1, localhost, ::1 等形式。
+ *
+ * @param host 主机名或 IP 字符串
+ */
+export function isLoopbackHost(host) {
+    const trimmed = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    return (trimmed === "127.0.0.1" ||
+        trimmed === "::1" ||
+        trimmed === "localhost" ||
+        trimmed === "0:0:0:0:0:0:0:1");
+}
+/**
+ * 校验 HTTP 请求中的鉴权令牌是否有效。
+ *
+ * 默认仅接受 HTTP 请求头: `Authorization: Bearer <token>`。
+ * 仅当 options.allowQueryToken 为 true 时才允许解析 URL 查询参数 `?token=<token>`。
+ *
+ * @param req 传入的 HTTP Request 对象
+ * @param expectedToken 服务端预期的正确 Token（若未配置 Token 则默认放行）
+ * @param options 校验选项或布尔值 allowQueryToken 开关
+ * @returns 是否鉴权成功
+ */
+export function verifyBearerToken(req, expectedToken, options) {
+    if (!expectedToken || !expectedToken.trim()) {
+        return true;
+    }
+    const trimmedExpected = expectedToken.trim();
+    // 1. 请求头 Authorization: Bearer <token>
+    const authHeader = req.headers.get("authorization");
+    if (authHeader && authHeader.startsWith("Bearer ")) {
+        const token = authHeader.slice(7).trim();
+        if (safeEqual(token, trimmedExpected)) {
+            return true;
+        }
+    }
+    // 2. URL 查询参数: ?token=<token>（仅当显式开启 allowQueryToken 时允许）
+    const allowQuery = typeof options === "boolean" ? options : options?.allowQueryToken === true;
+    if (allowQuery) {
+        try {
+            const url = new URL(req.url);
+            const tokenParam = url.searchParams.get("token");
+            if (tokenParam && safeEqual(tokenParam.trim(), trimmedExpected)) {
+                return true;
+            }
+        }
+        catch {
+            // 畸形 URL 视作鉴权失败
+        }
+    }
+    return false;
+}
+/**
+ * 根据配置的 CORS 白名单解析并返回跨域响应头。
+ * 默认情况下若未配置 corsOrigins，返回空对象（即默认关闭跨域访问，防范 CSRF）。
+ *
+ * @param origin 请求头中的 Origin 字段
+ * @param allowedOrigins 允许跨域的白名单来源数组
+ * @returns 包含 Access-Control-* 的响应头对象
+ */
+export function resolveCorsHeaders(origin, allowedOrigins) {
+    if (!allowedOrigins || allowedOrigins.length === 0) {
+        return {};
+    }
+    const hasWildcard = allowedOrigins.includes("*");
+    if (hasWildcard) {
+        return {
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type, Authorization, Idempotency-Key, X-Request-Id, Last-Event-ID",
+            Vary: "Origin",
+        };
+    }
+    if (origin && allowedOrigins.includes(origin)) {
+        return {
+            "Access-Control-Allow-Origin": origin,
+            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type, Authorization, Idempotency-Key, X-Request-Id, Last-Event-ID",
+            Vary: "Origin",
+        };
+    }
+    return {};
+}

package/dist/server/server.d.ts

@@ -0,0 +1,15 @@
+import type { ActionDockServerInstance, CoreHttpServerInstance, ServerOptions } from "./types.js";
+/**
+ * 规范化主机地址用于拼接 URL。
+ * 若 host 包含冒号 : 且不以 [ 开头，则添加中括号包裹（IPv6 标准格式）。
+ */
+export declare function formatHostForUrl(host: string): string;
+/**
+ * 根据当前运行时环境启动标准 Web Request/Response 兼容的 HTTP 服务。
+ */
+export declare function launchHttpServer(port: number, host: string, fetchHandler: (req: Request) => Promise<Response>): Promise<CoreHttpServerInstance>;
+/**
+ * 启动 ActionDock 2.0 原生轻量级 HTTP 服务端。
+ * 作为 ActionDockHost 与 ActionDockTarget 的薄适配层，负责中间件流转、认证拦截与路由分发。
+ */
+export declare function startActionDockServer(options?: ServerOptions): Promise<ActionDockServerInstance>;

package/dist/server/server.js

@@ -0,0 +1,355 @@
+import { createServer as createNodeHttpServer } from "node:http";
+import { resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createActionDockHost } from "../host/host.js";
+import { NOT_FOUND, UNAUTHORIZED } from "../errors.js";
+import { ensureDependencyClosure } from "../project/closure.js";
+import { findProjectRoot } from "../project/loader.js";
+import { listLinkedPackages, resolvePackageRoot } from "../registry/registry.js";
+import { LocalActionDockTarget } from "../target/local.js";
+import { handleActionsRoutes, handleConfigRoutes, handleDoctorRoute, handleHealthRoute, handleInfoRoute, handlePlaybooksRoutes, handleRunsRoutes, handleStateRoutes, jsonResponse, } from "./routes/index.js";
+import { DEFAULT_MAX_BODY_BYTES } from "./body.js";
+import { isLoopbackHost, resolveCorsHeaders, verifyBearerToken } from "./security.js";
+/**
+ * 规范化主机地址用于拼接 URL。
+ * 若 host 包含冒号 : 且不以 [ 开头，则添加中括号包裹（IPv6 标准格式）。
+ */
+export function formatHostForUrl(host) {
+    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+/**
+ * 根据当前运行时环境启动标准 Web Request/Response 兼容的 HTTP 服务。
+ */
+export async function launchHttpServer(port, host, fetchHandler) {
+    const srv = createNodeHttpServer(async (req, res) => {
+        const ac = new AbortController();
+        const onReqClose = () => {
+            if (!req.complete) {
+                ac.abort(new Error("Request aborted by client"));
+            }
+        };
+        const onResClose = () => {
+            if (!res.writableFinished) {
+                ac.abort(new Error("Request aborted by client"));
+            }
+        };
+        req.on("close", onReqClose);
+        res.on("close", onResClose);
+        try {
+            const protocol = req.socket?.encrypted ? "https" : "http";
+            const hostHeader = req.headers.host || "127.0.0.1";
+            const url = new URL(req.url || "/", `${protocol}://${hostHeader}`).href;
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers)) {
+                if (v === undefined)
+                    continue;
+                if (Array.isArray(v)) {
+                    for (const item of v)
+                        headers.append(k, item);
+                }
+                else {
+                    headers.set(k, v);
+                }
+            }
+            const method = (req.method || "GET").toUpperCase();
+            const hasBody = method !== "GET" && method !== "HEAD";
+            const init = { method, headers, signal: ac.signal };
+            if (hasBody) {
+                init.body = Readable.toWeb(req);
+                init.duplex = "half";
+            }
+            const webReq = new Request(url, init);
+            const webRes = await fetchHandler(webReq);
+            res.statusCode = webRes.status;
+            if (webRes.statusText)
+                res.statusMessage = webRes.statusText;
+            webRes.headers.forEach((v, k) => res.setHeader(k, v));
+            if (!webRes.body) {
+                res.end();
+                return;
+            }
+            await pipeline(Readable.fromWeb(webRes.body), res);
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.end(JSON.stringify({ error: err?.message || String(err) }));
+            }
+            else {
+                res.destroy(err);
+            }
+        }
+        finally {
+            req.removeListener("close", onReqClose);
+            res.removeListener("close", onResClose);
+        }
+    });
+    const instance = {
+        port,
+        stop: async () => {
+            await new Promise((resolve) => {
+                srv.close(() => resolve());
+                srv.closeAllConnections?.();
+            });
+        },
+    };
+    await new Promise((resolve, reject) => {
+        srv.once("error", (err) => {
+            reject(err);
+        });
+        srv.listen(port, host, () => {
+            const addr = srv.address();
+            if (typeof addr === "object" && addr) {
+                instance.port = addr.port;
+            }
+            resolve();
+        });
+    });
+    instance.ready = Promise.resolve();
+    return instance;
+}
+/**
+ * 启动 ActionDock 2.0 原生轻量级 HTTP 服务端。
+ * 作为 ActionDockHost 与 ActionDockTarget 的薄适配层，负责中间件流转、认证拦截与路由分发。
+ */
+export async function startActionDockServer(options = {}) {
+    let hostInstance = options.hostInstance ??
+        (options.host && typeof options.host === "object" && "listActions" in options.host
+            ? options.host
+            : undefined);
+    let targetInstance = options.target;
+    const hostString = typeof options.host === "string"
+        ? options.host
+        : (options.hostname ?? "127.0.0.1");
+    const port = options.port ?? 5177;
+    const host = hostString;
+    const token = options.token;
+    const customHome = options.customHome;
+    const projectRoot = options.projectRoot
+        ? resolve(options.projectRoot)
+        : findProjectRoot(process.cwd());
+    // 非回环地址强制要求配置 Token 鉴权（防裸奔）
+    if (!isLoopbackHost(host) && !token && !options.allowInsecureNoAuth) {
+        throw new Error("Authentication token is required when binding to a non-loopback address. Use --allow-insecure-no-auth to override.");
+    }
+    // 若调用方未传入 host 或 target，通过 projectRoot、customHome、platform 等直接创建宿主
+    if (!targetInstance && !hostInstance) {
+        const scanLinkedPackages = options.scanLinkedPackages ?? !projectRoot;
+        hostInstance = await createActionDockHost({
+            projectRoot: projectRoot || undefined,
+            customHome,
+            platform: options.platform,
+            dataDir: options.dataDir,
+            inMemory: options.inMemory,
+            scanLinkedPackages,
+            autoLoadCurrentProject: true,
+        });
+    }
+    if (!targetInstance && hostInstance) {
+        targetInstance = new LocalActionDockTarget(hostInstance);
+    }
+    else if (targetInstance && !hostInstance) {
+        const inner = targetInstance?.unwrap?.();
+        if (inner && "listApps" in inner) {
+            hostInstance = inner;
+        }
+    }
+    const roots = [];
+    if (projectRoot) {
+        roots.push(projectRoot);
+    }
+    if (options.packageAllowlist && options.packageAllowlist.length > 0) {
+        for (const pkgId of options.packageAllowlist) {
+            const r = resolvePackageRoot(pkgId, projectRoot || undefined, customHome);
+            if (r && !roots.includes(r)) {
+                roots.push(r);
+            }
+        }
+    }
+    else if (!projectRoot) {
+        for (const pkg of listLinkedPackages(customHome)) {
+            if (!roots.includes(pkg.path)) {
+                roots.push(pkg.path);
+            }
+        }
+    }
+    if (roots.length > 0) {
+        await ensureDependencyClosure(roots, { customHome });
+    }
+    const fetchHandler = async (req) => {
+        const origin = req.headers.get("origin");
+        const corsHeaders = resolveCorsHeaders(origin, options.corsOrigins);
+        if (req.method === "OPTIONS") {
+            return new Response(null, {
+                status: 204,
+                headers: corsHeaders,
+            });
+        }
+        const url = new URL(req.url);
+        const pathname = url.pathname;
+        const ctx = {
+            req,
+            url,
+            pathname,
+            corsHeaders,
+            projectRoot,
+            customHome,
+            host: hostInstance,
+            target: targetInstance,
+            options,
+        };
+        // 1. 健康检查路由（内部处理独立鉴权逻辑）
+        const healthResponse = await handleHealthRoute(ctx);
+        if (healthResponse) {
+            return healthResponse;
+        }
+        // 2. MCP 统一网关端点
+        if (options.enableMcp !== false &&
+            options.mcpHandler &&
+            (pathname === "/mcp" || pathname.startsWith("/mcp/"))) {
+            if (!verifyBearerToken(req, token, options)) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: UNAUTHORIZED,
+                        message: "Invalid or missing Bearer token",
+                    },
+                }, 401, corsHeaders);
+            }
+            // 请求体体积限制保护
+            const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+            const contentLengthHeader = req.headers.get("content-length");
+            if (contentLengthHeader) {
+                const parsedLength = parseInt(contentLengthHeader, 10);
+                if (!isNaN(parsedLength) && parsedLength > maxBytes) {
+                    return jsonResponse({
+                        ok: false,
+                        error: {
+                            code: "REQUEST_TOO_LARGE",
+                            message: "Request body exceeds maximum allowed size",
+                        },
+                    }, 413, corsHeaders);
+                }
+            }
+            let mcpReq = req;
+            if (req.body && req.method !== "GET" && req.method !== "HEAD") {
+                const reader = req.body.getReader();
+                const chunks = [];
+                let totalBytes = 0;
+                let tooLarge = false;
+                try {
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        if (value) {
+                            totalBytes += value.byteLength;
+                            if (totalBytes > maxBytes) {
+                                tooLarge = true;
+                                await reader.cancel();
+                                break;
+                            }
+                            chunks.push(value);
+                        }
+                    }
+                }
+                finally {
+                    reader.releaseLock();
+                }
+                if (tooLarge) {
+                    return jsonResponse({
+                        ok: false,
+                        error: {
+                            code: "REQUEST_TOO_LARGE",
+                            message: "Request body exceeds maximum allowed size",
+                        },
+                    }, 413, corsHeaders);
+                }
+                const merged = new Uint8Array(totalBytes);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    merged.set(chunk, offset);
+                    offset += chunk.byteLength;
+                }
+                mcpReq = new Request(req.url, {
+                    method: req.method,
+                    headers: req.headers,
+                    body: merged,
+                    signal: req.signal,
+                });
+            }
+            const mcpRes = await options.mcpHandler(mcpReq);
+            if (mcpRes)
+                return mcpRes;
+        }
+        // 3. 全局 API 认证鉴权拦截
+        if (!verifyBearerToken(req, token, options)) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: UNAUTHORIZED,
+                    message: "Invalid or missing Bearer token",
+                },
+            }, 401, corsHeaders);
+        }
+        // 4. 业务领域路由分发（完全委托 Target / Host）
+        const routeResponse = (await handleInfoRoute(ctx)) ||
+            (await handleDoctorRoute(ctx)) ||
+            (await handleActionsRoutes(ctx)) ||
+            (await handlePlaybooksRoutes(ctx)) ||
+            (await handleRunsRoutes(ctx)) ||
+            (await handleStateRoutes(ctx)) ||
+            (await handleConfigRoutes(ctx));
+        if (routeResponse) {
+            return routeResponse;
+        }
+        // 5. 404 路由兜底
+        return jsonResponse({
+            ok: false,
+            error: {
+                code: NOT_FOUND,
+                message: `Route not found: ${req.method} ${pathname}`,
+            },
+        }, 404, corsHeaders);
+    };
+    const server = await launchHttpServer(port, host, fetchHandler);
+    if (server.ready) {
+        await server.ready;
+    }
+    const actualHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+    const instance = {
+        get port() {
+            return server.port ?? port;
+        },
+        set port(val) {
+            server.port = val;
+        },
+        host: hostInstance,
+        target: targetInstance,
+        get url() {
+            return `http://${formatHostForUrl(actualHost)}:${this.port}`;
+        },
+        ready: Promise.resolve(),
+        stop: async (stopOptions) => {
+            if (targetInstance) {
+                try {
+                    await targetInstance.close();
+                }
+                catch {
+                    // 忽略关闭异常
+                }
+            }
+            if (hostInstance && hostInstance !== targetInstance?.unwrap?.()) {
+                try {
+                    await hostInstance.close(stopOptions);
+                }
+                catch {
+                    // 忽略宿主关闭异常
+                }
+            }
+            await server.stop(true);
+        },
+    };
+    return instance;
+}

package/dist/server/types.d.ts

@@ -0,0 +1,78 @@
+import type { ActionDockHost } from "../host/types.js";
+import type { ActionDockTarget } from "../target/types.js";
+export interface CoreHttpServerInstance {
+    port: number;
+    stop: (closeActiveConnections?: boolean) => void | Promise<void>;
+    ready?: Promise<void>;
+}
+export type CoreHttpServerFactory = (options: {
+    port: number;
+    host: string;
+    fetch: (req: Request) => Promise<Response>;
+}) => CoreHttpServerInstance | Promise<CoreHttpServerInstance>;
+/**
+ * 启动 ActionDock HTTP Runner 服务端的配置选项。
+ */
+export interface ServerOptions {
+    /** 监听端口号（默认 5177） */
+    port?: number;
+    /** 绑定监听的主机地址（默认 "127.0.0.1"），或关联的 ActionDockHost 宿主实例 */
+    host?: string | ActionDockHost;
+    /** 显式绑定的 ActionDockHost 宿主实例（向前兼容别名） */
+    hostInstance?: ActionDockHost;
+    /** 关联的目标 ActionDockTarget 门面实例 */
+    target?: ActionDockTarget;
+    /** 显式绑定的主机地址（当 host 传入 ActionDockHost 时的可选覆盖项） */
+    hostname?: string;
+    /** 用于 HTTP Bearer Token 鉴权的密钥令牌 */
+    token?: string;
+    /** 是否允许通过 URL 查询参数携带 Token 进行鉴权（默认 false，关闭以防泄露） */
+    allowQueryToken?: boolean;
+    /** 服务的项目根目录（可选，若未指定则自动向上查找或进入全局 Registry 模式） */
+    projectRoot?: string;
+    /** 自定义 ActionDock 用户家目录 */
+    customHome?: string;
+    /** 数据持久化存储目录 */
+    dataDir?: string;
+    /** 是否采用纯内存运行模式 */
+    inMemory?: boolean;
+    /** 是否允许非回环地址（如 0.0.0.0）在未配置 Token 的情况下启动（不安全） */
+    allowInsecureNoAuth?: boolean;
+    /** 允许跨域请求的 CORS Origin 白名单列表 */
+    corsOrigins?: string[];
+    /** 允许访问执行的 Package ID 白名单列表（为空允许全部） */
+    packageAllowlist?: string[];
+    /** 最大允许的请求体字节限制（默认 1MB，防 DoS） */
+    maxBodyBytes?: number;
+    /** 是否在 health 和 info 接口中透传本地 projectRoot 等调试路径 */
+    exposeDebugInfo?: boolean;
+    /** 是否启用一体化 MCP 协议支持（默认开启） */
+    enableMcp?: boolean;
+    /** 自定义 MCP 请求处理器钩子（若挂载则 /mcp 路由交由其处理） */
+    mcpHandler?: (req: Request) => Promise<Response | null | undefined> | Response | null | undefined;
+    /** 可选注入的统一运行时底层平台 */
+    platform?: import("../platform/types.js").RuntimePlatform;
+    /** 是否显式开启配置与状态管理路由能力（默认关闭，关闭时返回 403） */
+    enableManagement?: boolean;
+    /** 是否扫描并加载外部链接包（默认在未指定 projectRoot 时为 true，指定时为 false） */
+    scanLinkedPackages?: boolean;
+}
+/**
+ * 已启动的 ActionDock HTTP Runner 实例句柄。
+ */
+export interface ActionDockServerInstance {
+    /** 实际监听的端口号 */
+    port: number;
+    /** 关联的 ActionDockHost 宿主实例（若启动时传入或创建） */
+    host?: ActionDockHost;
+    /** 关联的 ActionDockTarget 目标门面实例 */
+    target?: ActionDockTarget;
+    /** 服务端可访问的基础 URL（如 "http://127.0.0.1:5177"） */
+    url: string;
+    /** 服务就绪 Promise（可等待端口解析与监听建立） */
+    ready?: Promise<void>;
+    /** 优雅关闭服务端并释放底层资源 */
+    stop: (options?: {
+        graceMs?: number;
+    }) => Promise<void> | void;
+}

package/dist/server/types.js

@@ -0,0 +1 @@
+export {};