@actiondock/core 2.0.0

package/src/server/security.ts

@@ -0,0 +1,115 @@
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * 恒定时间字符串比较（Constant-time comparison）。
+ * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。
+ * 
+ * @param a 字符串 A
+ * @param b 字符串 B
+ * @returns 两个字符串内容是否完全一致
+ */
+export function safeEqual(a: string, b: string): boolean {
+  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: string): boolean {
+  const trimmed = host.trim().toLowerCase();
+  return (
+    trimmed === "127.0.0.1" ||
+    trimmed === "::1" ||
+    trimmed === "localhost" ||
+    trimmed === "0:0:0:0:0:0:0:1"
+  );
+}
+
+/**
+ * 校验 HTTP 请求中的鉴权令牌是否有效。
+ * 
+ * 支持两种凭证携带模式（均通过恒定时间对比）：
+ * 1. HTTP 请求头: `Authorization: Bearer <token>`
+ * 2. URL 查询参数: `?token=<token>`（便于浏览器/Web 调试）
+ * 
+ * @param req 传入的 HTTP Request 对象
+ * @param expectedToken 服务端预期的正确 Token（若未配置 Token 则默认放行）
+ * @returns 是否鉴权成功
+ */
+export function verifyBearerToken(req: Request, expectedToken?: string): boolean {
+  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>
+  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: string | null,
+  allowedOrigins?: string[]
+): Record<string, string> {
+  if (!allowedOrigins || allowedOrigins.length === 0) {
+    return {};
+  }
+
+  const hasWildcard = allowedOrigins.includes("*");
+  if (hasWildcard) {
+    return {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type, Authorization",
+      Vary: "Origin",
+    };
+  }
+
+  if (origin && allowedOrigins.includes(origin)) {
+    return {
+      "Access-Control-Allow-Origin": origin,
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type, Authorization",
+      Vary: "Origin",
+    };
+  }
+
+  return {};
+}

package/src/server/server.ts

@@ -0,0 +1,572 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { filterByIntent } from "../filter";
+import {
+  findProjectRoot,
+  loadActions,
+  loadPlaybooks,
+  loadProjectConfig,
+} from "../project/loader";
+import { listLinkedPackages, resolveActionProject } from "../registry/registry";
+import { ActionRunner } from "../runtime/runner";
+import { InvalidJsonError, readJsonBody, RequestTooLargeError } from "./body";
+import { ServerRuntimeRegistry } from "./runtime-registry";
+import { isLoopbackHost, resolveCorsHeaders, verifyBearerToken } from "./security";
+import type { ActionDockServerInstance, ServerOptions } from "./types";
+
+/**
+ * 辅助函数：快速构造带 CORS 头的 JSON HTTP 响应。
+ */
+function jsonResponse(
+  data: unknown,
+  status = 200,
+  corsHeaders: Record<string, string> = {}
+): Response {
+  return new Response(JSON.stringify(data, null, 2), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+      ...corsHeaders,
+    },
+  });
+}
+
+/**
+ * 跨内存活跃连接与所有已知持久化存储全局检索指定 runId 的运行记录。
+ */
+function findRunAcrossStorages(
+  runId: string,
+  runtimeRegistry: ServerRuntimeRegistry,
+  projectRoot?: string | null,
+  customHome?: string
+) {
+  const inMemory = runtimeRegistry.findRun(runId);
+  if (inMemory) return inMemory;
+
+  if (projectRoot) {
+    try {
+      const config = loadProjectConfig(projectRoot);
+      const storage = runtimeRegistry.getStorage(config.id, projectRoot);
+      const run = storage.getRun(runId);
+      if (run) return { storage, run };
+    } catch {
+      // 忽略读取错误
+    }
+  }
+
+  try {
+    const linked = listLinkedPackages(customHome);
+    for (const pkg of linked) {
+      if (!existsSync(pkg.path)) continue;
+      const storage = runtimeRegistry.getStorage(pkg.id, pkg.path);
+      const run = storage.getRun(runId);
+      if (run) return { storage, run };
+    }
+  } catch {
+    // 忽略读取错误
+  }
+
+  return null;
+}
+
+/**
+ * 启动 ActionDock 2.0 原生轻量级 HTTP Runner 服务端。
+ * 
+ * 提供 RESTful API 供跨机器或远端 AI Agent 执行 Action：
+ * - `GET  /api/v1/health` : 健康检查与就绪状态
+ * - `GET  /api/v1/info`   : 项目元数据、Action 与 Playbook 概览
+ * - `GET  /api/v1/actions`: 列出可用 Actions（支持 ?intent= 过滤）
+ * - `GET  /api/v1/actions/:id`: 查看单个 Action 的 Schema 详情
+ * - `POST /api/v1/actions/:id/run`: 同步或异步（202 Accepted）执行 Action
+ * - `GET  /api/v1/runs/:runId`: 查询历史或异步任务运行状态
+ * - `POST /api/v1/runs/:runId/cancel`: 中断在途任务
+ * 
+ * @param options 服务端启动配置参数
+ * @returns ActionDockServerInstance 服务端实例句柄
+ */
+export function startActionDockServer(
+  options: ServerOptions = {}
+): ActionDockServerInstance {
+  const port = options.port ?? 5177;
+  const host = options.host ?? "127.0.0.1";
+  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."
+    );
+  }
+
+  const runtimeRegistry = new ServerRuntimeRegistry();
+
+  const server = Bun.serve({
+    port,
+    hostname: host,
+    async fetch(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;
+
+      // 1. Health Check (supports /api/v1/health and /health)
+      if (pathname === "/api/v1/health" || pathname === "/health") {
+        if (!verifyBearerToken(req, token)) {
+          return jsonResponse(
+            {
+              ok: false,
+              error: {
+                code: "UNAUTHORIZED",
+                message: "Invalid or missing Bearer token",
+              },
+            },
+            401,
+            corsHeaders
+          );
+        }
+        const healthData: Record<string, unknown> = {
+          status: "ok",
+          version: "2.0.0",
+          timestamp: new Date().toISOString(),
+          uptime: process.uptime(),
+        };
+        if (options.exposeDebugInfo && projectRoot) {
+          healthData.projectRoot = projectRoot;
+        }
+        return jsonResponse(healthData, 200, corsHeaders);
+      }
+
+      // Check authentication for remaining endpoints
+      if (!verifyBearerToken(req, token)) {
+        return jsonResponse(
+          {
+            ok: false,
+            error: {
+              code: "UNAUTHORIZED",
+              message: "Invalid or missing Bearer token",
+            },
+          },
+          401,
+          corsHeaders
+        );
+      }
+
+      // 2. Info: GET /api/v1/info
+      if (pathname === "/api/v1/info" && req.method === "GET") {
+        try {
+          if (projectRoot) {
+            const config = loadProjectConfig(projectRoot);
+            const actions = await loadActions(projectRoot, config.actionsDir);
+            const playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
+            const infoData: Record<string, unknown> = {
+              ok: true,
+              id: config.id,
+              name: config.name,
+              version: config.version,
+              description: config.description,
+              actionsCount: actions.size,
+              playbooksCount: playbooks.size,
+              actions: Array.from(actions.keys()),
+              playbooks: Array.from(playbooks.keys()),
+            };
+            if (options.exposeDebugInfo) {
+              infoData.projectRoot = projectRoot;
+            }
+            return jsonResponse(infoData, 200, corsHeaders);
+          } else {
+            const linked = listLinkedPackages(customHome);
+            return jsonResponse(
+              {
+                ok: true,
+                version: "2.0.0",
+                linkedPackages: linked,
+              },
+              200,
+              corsHeaders
+            );
+          }
+        } catch (err: any) {
+          return jsonResponse(
+            {
+              ok: false,
+              error: { code: "INFO_ERROR", message: err.message },
+            },
+            500,
+            corsHeaders
+          );
+        }
+      }
+
+      // 3. Actions List: GET /api/v1/actions
+      if (pathname === "/api/v1/actions" && req.method === "GET") {
+        try {
+          const actionList: Array<{
+            id: string;
+            description: string;
+            packageId?: string;
+          }> = [];
+
+          if (projectRoot) {
+            const config = loadProjectConfig(projectRoot);
+            const actions = await loadActions(projectRoot, config.actionsDir);
+            for (const [id, a] of actions.entries()) {
+              actionList.push({
+                id,
+                description: a.description || "",
+                packageId: config.id,
+              });
+            }
+          }
+
+          const linked = listLinkedPackages(customHome);
+          for (const pkg of linked) {
+            if (projectRoot && pkg.path === projectRoot) continue;
+            if (!existsSync(pkg.path)) continue;
+            try {
+              const config = loadProjectConfig(pkg.path);
+              const actions = await loadActions(pkg.path, config.actionsDir);
+              for (const [id, a] of actions.entries()) {
+                actionList.push({
+                  id,
+                  description: a.description || "",
+                  packageId: pkg.id,
+                });
+              }
+            } catch {
+              // Ignore broken package
+            }
+          }
+
+          const intent = url.searchParams.get("intent");
+          const filtered = intent
+            ? filterByIntent(
+                actionList,
+                intent,
+                [(a) => a.id, (a) => a.description, (a) => a.packageId],
+                false
+              )
+            : actionList;
+
+          return jsonResponse(filtered, 200, corsHeaders);
+        } catch (err: any) {
+          return jsonResponse(
+            {
+              ok: false,
+              error: { code: "ACTIONS_LIST_ERROR", message: err.message },
+            },
+            500,
+            corsHeaders
+          );
+        }
+      }
+
+      // 4. Action Show: GET /api/v1/actions/:id
+      const actionShowMatch = pathname.match(/^\/api\/v1\/actions\/([^/]+)$/);
+      if (actionShowMatch && req.method === "GET") {
+        const actionId = decodeURIComponent(actionShowMatch[1]);
+        try {
+          const resolved = await resolveActionProject(
+            actionId,
+            projectRoot || process.cwd(),
+            customHome
+          );
+          const config = loadProjectConfig(resolved.projectRoot);
+          const actions = await loadActions(resolved.projectRoot, config.actionsDir);
+          const action = actions.get(resolved.actionId);
+          if (!action) {
+            return jsonResponse(
+              {
+                ok: false,
+                error: {
+                  code: "ACTION_NOT_FOUND",
+                  message: `Action '${resolved.actionId}' not found in package '${resolved.packageId}'`,
+                },
+              },
+              404,
+              corsHeaders
+            );
+          }
+
+          return jsonResponse(
+            {
+              id: action.id,
+              packageId: resolved.packageId,
+              description: action.description || "",
+              inputSchema: action.inputSchema || null,
+              outputSchema: action.outputSchema || null,
+            },
+            200,
+            corsHeaders
+          );
+        } catch (err: any) {
+          return jsonResponse(
+            {
+              ok: false,
+              error: { code: "ACTION_NOT_FOUND", message: err.message },
+            },
+            404,
+            corsHeaders
+          );
+        }
+      }
+
+      // 5. Action Run: POST /api/v1/actions/:id/run
+      const actionRunMatch = pathname.match(/^\/api\/v1\/actions\/([^/]+)\/run$/);
+      if (actionRunMatch && req.method === "POST") {
+        const actionId = decodeURIComponent(actionRunMatch[1]);
+        let body: any = {};
+        try {
+          body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
+        } catch (err: any) {
+          if (err instanceof RequestTooLargeError) {
+            return jsonResponse(
+              {
+                ok: false,
+                runId: randomUUID(),
+                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,
+                },
+              },
+              400,
+              corsHeaders
+            );
+          }
+          return jsonResponse(
+            {
+              ok: false,
+              runId: randomUUID(),
+              error: {
+                code: "INVALID_JSON",
+                message: `Failed to parse request body: ${err.message}`,
+              },
+            },
+            400,
+            corsHeaders
+          );
+        }
+
+        try {
+          const resolved = await resolveActionProject(
+            actionId,
+            projectRoot || process.cwd(),
+            customHome
+          );
+          const config = loadProjectConfig(resolved.projectRoot);
+          const actions = await loadActions(resolved.projectRoot, config.actionsDir);
+          const storage = runtimeRegistry.getStorage(config.id, resolved.projectRoot);
+
+          const runner = new ActionRunner({
+            packageId: config.id,
+            storage,
+            projectConfig: config,
+            configOverrides: body?.config || {},
+            actions,
+          });
+
+          const executionMode = body?.execution?.mode || "sync";
+          const timeoutMs =
+            typeof body?.execution?.timeoutMs === "number" && body.execution.timeoutMs > 0
+              ? body.execution.timeoutMs
+              : undefined;
+
+          if (executionMode === "async") {
+            const handle = runner.start(resolved.actionId, body?.input || {}, {
+              timeoutMs,
+            });
+            runtimeRegistry.executionManager.register(handle);
+
+            return jsonResponse(
+              {
+                ok: true,
+                runId: handle.runId,
+                status: "running",
+              },
+              202,
+              corsHeaders
+            );
+          }
+
+          // Sync execution mode
+          const handle = runner.start(resolved.actionId, body?.input || {}, {
+            signal: req.signal,
+            timeoutMs,
+          });
+          runtimeRegistry.executionManager.register(handle);
+          const result = await handle.result;
+
+          return jsonResponse(result, 200, corsHeaders);
+        } catch (err: any) {
+          return jsonResponse(
+            {
+              ok: false,
+              runId: randomUUID(),
+              error: {
+                code: "ACTION_EXECUTION_ERROR",
+                message: err.message || String(err),
+              },
+            },
+            500,
+            corsHeaders
+          );
+        }
+      }
+
+      // 6. Run Show: GET /api/v1/runs/:runId
+      const runShowMatch = pathname.match(/^\/api\/v1\/runs\/([^/]+)$/);
+      if (runShowMatch && req.method === "GET") {
+        const runId = decodeURIComponent(runShowMatch[1]);
+        const found = findRunAcrossStorages(runId, runtimeRegistry, projectRoot, customHome);
+
+        if (!found) {
+          return jsonResponse(
+            {
+              ok: false,
+              error: {
+                code: "RUN_NOT_FOUND",
+                message: `Run '${runId}' not found`,
+              },
+            },
+            404,
+            corsHeaders
+          );
+        }
+
+        return jsonResponse(found.run, 200, corsHeaders);
+      }
+
+      // 7. Run Cancel: POST /api/v1/runs/:runId/cancel
+      const runCancelMatch = pathname.match(/^\/api\/v1\/runs\/([^/]+)\/cancel$/);
+      if (runCancelMatch && req.method === "POST") {
+        const runId = decodeURIComponent(runCancelMatch[1]);
+        let body: any = {};
+        try {
+          body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
+        } catch {
+          // Body is optional
+        }
+
+        const reason = body?.reason || "Cancelled by client request";
+
+        // 1. Try cancelling in-memory active handle
+        const activeHandle = runtimeRegistry.executionManager.get(runId);
+        if (activeHandle) {
+          const cancelled = runtimeRegistry.executionManager.cancel(runId, reason);
+          if (cancelled) {
+            return jsonResponse(
+              {
+                ok: true,
+                runId,
+                status: "cancelled",
+              },
+              200,
+              corsHeaders
+            );
+          }
+        }
+
+        // 2. Check storage for run status
+        const found = findRunAcrossStorages(runId, runtimeRegistry, projectRoot, customHome);
+
+        if (!found) {
+          return jsonResponse(
+            {
+              ok: false,
+              error: {
+                code: "RUN_NOT_FOUND",
+                message: `Run '${runId}' not found`,
+              },
+            },
+            404,
+            corsHeaders
+          );
+        }
+
+        const { storage, run } = found;
+        if (run.status === "success" || run.status === "failed" || run.status === "cancelled") {
+          return jsonResponse(
+            {
+              ok: false,
+              error: {
+                code: "RUN_ALREADY_FINISHED",
+                message: `Run '${runId}' has already finished with status '${run.status}'`,
+              },
+            },
+            409,
+            corsHeaders
+          );
+        }
+
+        // Running in storage but no longer in memory
+        storage.updateRun(runId, "cancelled", undefined, {
+          code: "ACTION_CANCELLED",
+          message: reason,
+        });
+
+        return jsonResponse(
+          {
+            ok: true,
+            runId,
+            status: "cancelled",
+          },
+          200,
+          corsHeaders
+        );
+      }
+
+      // 404 Not Found
+      return jsonResponse(
+        {
+          ok: false,
+          error: {
+            code: "NOT_FOUND",
+            message: `Route not found: ${req.method} ${pathname}`,
+          },
+        },
+        404,
+        corsHeaders
+      );
+    },
+  });
+
+  const actualHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+  const url = `http://${actualHost}:${server.port}`;
+
+  return {
+    port: server.port ?? port,
+    host,
+    url,
+    runtimeRegistry,
+    stop: () => {
+      runtimeRegistry.close();
+      server.stop(true);
+    },
+  };
+}