@actiondock/core 2.8.0 → 2.9.1

package/dist/server/policy.js

@@ -0,0 +1,368 @@
+import { parseActionRef } from "../catalog/resolve-action.js";
+import { ActionDockError, ACTION_FORBIDDEN, PACKAGE_NOT_ALLOWED } from "../errors.js";
+import { safeEqual } from "./security.js";
+export { extractBearerToken } from "./security.js";
+/**
+ * 动作未列入白名单拒绝访问异常。
+ */
+export class ActionForbiddenError extends ActionDockError {
+    status = 403;
+    statusCode = 403;
+    constructor(actionRef) {
+        super(ACTION_FORBIDDEN, `Action '${actionRef}' is not in the allowed action list`);
+        this.name = "ActionForbiddenError";
+        Object.setPrototypeOf(this, ActionForbiddenError.prototype);
+    }
+}
+/**
+ * 包未列入白名单拒绝访问异常。
+ */
+export class PackageNotAllowedError extends ActionDockError {
+    status = 403;
+    statusCode = 403;
+    constructor(packageId) {
+        super(PACKAGE_NOT_ALLOWED, `Package '${packageId}' is not in the allowed package list`);
+        this.name = "PackageNotAllowedError";
+        Object.setPrototypeOf(this, PackageNotAllowedError.prototype);
+    }
+}
+/**
+ * 根据客户端携带的 Token 智能匹配已注册的视图。
+ * 使用 safeEqual 进行恒定时间比较以防范时序攻击。
+ *
+ * @param token 客户端提供的 Bearer Token
+ * @param views 可遍历的视图集合
+ * @returns 匹配成功的视图对象，未命中返回 undefined
+ */
+export function matchViewByToken(token, views) {
+    const trimmed = token.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    let matched = undefined;
+    for (const view of views) {
+        const candidateToken = view.policy.token?.trim();
+        if (candidateToken) {
+            const isMatch = safeEqual(trimmed, candidateToken);
+            if (isMatch && !matched) {
+                matched = view;
+            }
+        }
+    }
+    return matched;
+}
+/**
+ * 归一化解析服务端配置的所有视图集合。
+ * 保证默认视图与显式自定义视图具有统一的数据结构。
+ *
+ * @param options 服务端配置选项
+ * @returns 默认视图与全部视图 Map 映射
+ */
+export function normalizeServerViews(options) {
+    const views = new Map();
+    // 1. 初始化基于全局配置的默认视图
+    const defaultRawOptions = {
+        name: "default",
+        token: options.token,
+        packageAllowlist: options.packageAllowlist,
+        actionAllowlist: options.actionAllowlist,
+        enableManagement: options.enableManagement,
+        enableMcp: options.enableMcp !== false,
+        mcpHandler: options.mcpHandler,
+    };
+    const customViews = new Map();
+    // 2. 解析 options.views 自定义视图
+    if (options.views) {
+        if (Array.isArray(options.views)) {
+            for (let i = 0; i < options.views.length; i++) {
+                const item = options.views[i];
+                if (!item || typeof item !== "object")
+                    continue;
+                const name = item.name?.trim() || `view_${i}`;
+                if (!name || name === "." || name === "..") {
+                    continue;
+                }
+                if (name === "default") {
+                    Object.assign(defaultRawOptions, item);
+                }
+                else {
+                    customViews.set(name, {
+                        name,
+                        policy: {
+                            viewName: name,
+                            token: item.token,
+                            packageAllowlist: item.packageAllowlist,
+                            actionAllowlist: item.actionAllowlist,
+                            enableManagement: item.enableManagement,
+                        },
+                        enableMcp: item.enableMcp !== false,
+                        rawOptions: item,
+                    });
+                }
+            }
+        }
+        else if (typeof options.views === "object") {
+            for (const [key, item] of Object.entries(options.views)) {
+                if (!item || typeof item !== "object")
+                    continue;
+                const name = item.name?.trim() || key.trim();
+                if (!name || name === "." || name === "..") {
+                    continue;
+                }
+                if (name === "default") {
+                    Object.assign(defaultRawOptions, item);
+                }
+                else {
+                    customViews.set(name, {
+                        name,
+                        policy: {
+                            viewName: name,
+                            token: item.token,
+                            packageAllowlist: item.packageAllowlist,
+                            actionAllowlist: item.actionAllowlist,
+                            enableManagement: item.enableManagement,
+                        },
+                        enableMcp: item.enableMcp !== false,
+                        rawOptions: item,
+                    });
+                }
+            }
+        }
+    }
+    const defaultView = {
+        name: "default",
+        policy: {
+            viewName: "default",
+            token: defaultRawOptions.token,
+            packageAllowlist: defaultRawOptions.packageAllowlist,
+            actionAllowlist: defaultRawOptions.actionAllowlist,
+            enableManagement: defaultRawOptions.enableManagement,
+        },
+        enableMcp: defaultRawOptions.enableMcp !== false,
+        rawOptions: defaultRawOptions,
+    };
+    // 默认视图置于首位，随后装载自定义视图
+    views.set("default", defaultView);
+    for (const [k, v] of customViews) {
+        views.set(k, v);
+    }
+    return { defaultView, views };
+}
+/**
+ * 校验目标动作是否在 actionAllowlist 允许白名单中。
+ * 支持短名 actionId 与全限定名 packageId/actionId 匹配：
+ * - 白名单项若含 '/'（如 pkg/act），则必须 packageId 与 actionId 同时精确匹配。
+ * - 白名单项若不含 '/'（如 act），则只需 actionId 匹配（不限包）。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param allowlist 允许动作白名单列表
+ * @returns 是否允许访问
+ */
+export function isActionAllowed(action, allowlist) {
+    if (!allowlist || !Array.isArray(allowlist) || allowlist.length === 0) {
+        return true;
+    }
+    if (!action) {
+        return false;
+    }
+    let target;
+    try {
+        if (typeof action === "string") {
+            target = parseActionRef(action);
+        }
+        else {
+            const rawId = action.actionId || action.id;
+            if (!rawId)
+                return false;
+            if (action.packageId) {
+                if (rawId.includes("/")) {
+                    target = parseActionRef(rawId);
+                }
+                else {
+                    target = parseActionRef({
+                        packageId: action.packageId,
+                        actionId: rawId,
+                    });
+                }
+            }
+            else {
+                target = parseActionRef(rawId);
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    for (const item of allowlist) {
+        if (typeof item !== "string")
+            continue;
+        const trimmed = item.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const rule = parseActionRef(trimmed);
+            if (rule.packageId) {
+                if (rule.packageId === target.packageId && rule.actionId === target.actionId) {
+                    return true;
+                }
+            }
+            else {
+                if (rule.actionId === target.actionId) {
+                    return true;
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return false;
+}
+/**
+ * 根据生效策略统一判定目标动作是否允许访问。
+ * 同时综合校验策略中的 packageAllowlist 与 actionAllowlist 约束。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export function isActionAllowedByPolicy(action, policy) {
+    if (!policy) {
+        return true;
+    }
+    if (!action) {
+        return false;
+    }
+    let pkgId;
+    let actId;
+    try {
+        if (typeof action === "string") {
+            const parsed = parseActionRef(action);
+            pkgId = parsed.packageId;
+            actId = parsed.actionId;
+        }
+        else {
+            pkgId = action.packageId;
+            const rawId = action.actionId || action.id;
+            if (!rawId)
+                return false;
+            if (rawId.includes("/")) {
+                const parsed = parseActionRef(rawId);
+                pkgId = parsed.packageId || pkgId;
+                actId = parsed.actionId;
+            }
+            else {
+                actId = rawId;
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    // 1. 若配置了 packageAllowlist，校验所属包白名单
+    if (policy.packageAllowlist && policy.packageAllowlist.length > 0) {
+        if (pkgId) {
+            if (!policy.packageAllowlist.includes(pkgId)) {
+                return false;
+            }
+        }
+        else {
+            // 未指明所属包时，仅当其动作标识明确列入 actionAllowlist 时才允许放行
+            if (!policy.actionAllowlist ||
+                policy.actionAllowlist.length === 0 ||
+                !isActionAllowed({ actionId: actId }, policy.actionAllowlist)) {
+                return false;
+            }
+        }
+    }
+    // 2. 若配置了 actionAllowlist，校验动作白名单
+    if (policy.actionAllowlist && policy.actionAllowlist.length > 0) {
+        if (!isActionAllowed({ packageId: pkgId, actionId: actId }, policy.actionAllowlist)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 根据生效策略统一判定目标包标识是否允许访问。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export function isPackageAllowedByPolicy(packageId, policy) {
+    if (!policy?.packageAllowlist || policy.packageAllowlist.length === 0) {
+        return true;
+    }
+    if (!packageId) {
+        return false;
+    }
+    return policy.packageAllowlist.includes(packageId);
+}
+/**
+ * 根据生效策略统一判定配置与状态管理路由是否开启。
+ *
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许管理操作
+ */
+export function isManagementAllowedByPolicy(policy) {
+    return policy?.enableManagement === true;
+}
+/**
+ * 根据生效策略对动作列表进行统一过滤。
+ *
+ * @param actions 待过滤的动作列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的动作列表
+ */
+export function filterActionsByPolicy(actions, policy) {
+    if (!policy) {
+        return actions;
+    }
+    const hasPkg = policy.packageAllowlist && policy.packageAllowlist.length > 0;
+    const hasAct = policy.actionAllowlist && policy.actionAllowlist.length > 0;
+    if (!hasPkg && !hasAct) {
+        return actions;
+    }
+    return actions.filter((a) => isActionAllowedByPolicy({ packageId: a.packageId, actionId: a.actionId || a.id }, policy));
+}
+/**
+ * 根据生效策略对包列表进行统一过滤。
+ *
+ * @param packages 待过滤的包列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的包列表
+ */
+export function filterPackagesByPolicy(packages, policy) {
+    if (!policy?.packageAllowlist || policy.packageAllowlist.length === 0) {
+        return packages;
+    }
+    return packages.filter((p) => p.id && policy.packageAllowlist.includes(p.id));
+}
+/**
+ * 校验目标动作是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param action 目标动作对象或引用
+ * @param policy 当前生效的服务端策略
+ */
+export function assertActionAllowedByPolicy(action, policy) {
+    if (!isActionAllowedByPolicy(action, policy)) {
+        const actRef = typeof action === "string"
+            ? action
+            : action.packageId
+                ? `${action.packageId}/${action.actionId || action.id}`
+                : action.actionId || action.id || "unknown";
+        throw new ActionForbiddenError(actRef);
+    }
+}
+/**
+ * 校验目标包是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ */
+export function assertPackageAllowedByPolicy(packageId, policy) {
+    if (!isPackageAllowedByPolicy(packageId, policy)) {
+        throw new PackageNotAllowedError(packageId);
+    }
+}

package/dist/server/routes/actions.js

@@ -1,13 +1,13 @@
 import { parseActionRef } from "../../catalog/resolve-action.js";
 import { filterByIntent } from "../../filter/index.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 { ACTION_EXECUTION_ERROR, ACTION_FORBIDDEN, 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";
+import { filterActionsByPolicy, getSubPath, isActionAllowedByPolicy, isPackageAllowedByPolicy, jsonResponse, } from "./common.js";
 /**
  * 处理 Action 相关的 HTTP 路由（列表、规范查询、同步执行与异步启动）。
  */
 export async function handleActionsRoutes(ctx) {
-    const { req, url, pathname, corsHeaders, options, service } = ctx;
+    const { req, url, pathname, corsHeaders, options, service, activePolicy: policy } = ctx;
     const subpath = getSubPath(pathname);
     // 1. Actions List: GET /api/v2/actions, GET /actions
     if (subpath === "/actions" && req.method === "GET") {
@@ -25,9 +25,7 @@ export async function handleActionsRoutes(ctx) {
             if (targetPkg) {
                 actions = actions.filter((a) => a.packageId === targetPkg || a.id.startsWith(`${targetPkg}/`));
             }
-            if (options.packageAllowlist && options.packageAllowlist.length > 0) {
-                actions = actions.filter((a) => a.packageId && options.packageAllowlist.includes(a.packageId));
-            }
+            actions = filterActionsByPolicy(actions, policy);
             if (intent) {
                 actions = filterByIntent(actions, intent, [(a) => a.id, (a) => a.description || "", (a) => a.packageId || ""], false);
             }
@@ -45,16 +43,23 @@ export async function handleActionsRoutes(ctx) {
     if (pkgActionShowMatch && req.method === "GET") {
         const packageId = decodeURIComponent(pkgActionShowMatch[1]);
         const actionId = decodeURIComponent(pkgActionShowMatch[2]);
-        if (options.packageAllowlist && options.packageAllowlist.length > 0) {
-            if (!options.packageAllowlist.includes(packageId)) {
-                return jsonResponse({
-                    ok: false,
-                    error: {
-                        code: PACKAGE_FORBIDDEN,
-                        message: `Package '${packageId}' is not in the allowed package list`,
-                    },
-                }, 403, corsHeaders);
-            }
+        if (!isPackageAllowedByPolicy(packageId, policy)) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: PACKAGE_FORBIDDEN,
+                    message: `Package '${packageId}' is not in the allowed package list`,
+                },
+            }, 403, corsHeaders);
+        }
+        if (!isActionAllowedByPolicy({ packageId, actionId }, policy)) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: ACTION_FORBIDDEN,
+                    message: `Action '${packageId}/${actionId}' is not in the allowed action list`,
+                },
+            }, 403, corsHeaders);
         }
         const ref = `${packageId}/${actionId}`;
         try {
@@ -77,8 +82,8 @@ export async function handleActionsRoutes(ctx) {
         const actionId = decodeURIComponent(actionShowMatch[1]);
         try {
             const parsed = parseActionRef(actionId);
-            if (parsed.packageId && options.packageAllowlist && options.packageAllowlist.length > 0) {
-                if (!options.packageAllowlist.includes(parsed.packageId)) {
+            if (parsed.packageId) {
+                if (!isPackageAllowedByPolicy(parsed.packageId, policy)) {
                     return jsonResponse({
                         ok: false,
                         error: {
@@ -87,19 +92,35 @@ export async function handleActionsRoutes(ctx) {
                         },
                     }, 403, corsHeaders);
                 }
+                if (!isActionAllowedByPolicy({ packageId: parsed.packageId, actionId: parsed.actionId }, policy)) {
+                    return jsonResponse({
+                        ok: false,
+                        error: {
+                            code: ACTION_FORBIDDEN,
+                            message: `Action '${actionId}' is not in the allowed action list`,
+                        },
+                    }, 403, corsHeaders);
+                }
             }
         }
         catch { }
         try {
             const spec = await service.discovery.describeAction(actionId);
-            if (options.packageAllowlist &&
-                options.packageAllowlist.length > 0 &&
-                (!spec.packageId || !options.packageAllowlist.includes(spec.packageId))) {
+            if (!isPackageAllowedByPolicy(spec.packageId, policy)) {
                 return jsonResponse({
                     ok: false,
                     error: {
                         code: PACKAGE_FORBIDDEN,
-                        message: `Package '${spec.packageId}' is not in the allowed package list`,
+                        message: `Package '${spec.packageId || "unknown"}' is not in the allowed package list`,
+                    },
+                }, 403, corsHeaders);
+            }
+            if (!isActionAllowedByPolicy({ packageId: spec.packageId, actionId: spec.id }, policy)) {
+                return jsonResponse({
+                    ok: false,
+                    error: {
+                        code: ACTION_FORBIDDEN,
+                        message: `Action '${spec.packageId ? `${spec.packageId}/${spec.id}` : spec.id}' is not in the allowed action list`,
                     },
                 }, 403, corsHeaders);
             }
@@ -127,9 +148,10 @@ export async function handleActionsRoutes(ctx) {
         let actionRef;
         let endpointMode;
         let pkgId;
+        let actId;
         if (pkgRunMatch) {
             pkgId = decodeURIComponent(pkgRunMatch[1]);
-            const actId = decodeURIComponent(pkgRunMatch[2]);
+            actId = decodeURIComponent(pkgRunMatch[2]);
             endpointMode = pkgRunMatch[3];
             actionRef = `${pkgId}/${actId}`;
         }
@@ -139,30 +161,52 @@ export async function handleActionsRoutes(ctx) {
             try {
                 const parsed = parseActionRef(actionRef);
                 pkgId = parsed.packageId;
+                actId = parsed.actionId;
             }
             catch { }
         }
-        // 校验 Package 允许白名单
-        if (options.packageAllowlist && options.packageAllowlist.length > 0) {
-            if (!pkgId) {
-                try {
-                    const spec = await service.discovery.describeAction(actionRef);
-                    pkgId = spec?.packageId;
-                }
-                catch { }
+        // 解析并补全包与动作标识（仅在必要时单次查询 spec）
+        if ((!pkgId || !actId) && (policy.packageAllowlist?.length || policy.actionAllowlist?.length)) {
+            try {
+                const spec = await service.discovery.describeAction(actionRef);
+                pkgId = pkgId || spec?.packageId;
+                actId = actId || spec?.id;
             }
-            if (!pkgId || !options.packageAllowlist.includes(pkgId)) {
-                return jsonResponse({
-                    ok: false,
-                    runId: "",
-                    error: {
-                        code: PACKAGE_FORBIDDEN,
-                        message: pkgId
-                            ? `Package '${pkgId}' is not in the allowed package list`
-                            : `Action '${actionRef}' does not belong to any allowed package`,
-                    },
-                }, 403, corsHeaders);
+            catch { }
+        }
+        if (!actId) {
+            try {
+                const parsed = parseActionRef(actionRef);
+                actId = parsed.actionId;
+                pkgId = pkgId || parsed.packageId;
             }
+            catch {
+                actId = actionRef;
+            }
+        }
+        // 校验 Package 允许白名单
+        if (!isPackageAllowedByPolicy(pkgId, policy)) {
+            return jsonResponse({
+                ok: false,
+                runId: "",
+                error: {
+                    code: PACKAGE_FORBIDDEN,
+                    message: pkgId
+                        ? `Package '${pkgId}' is not in the allowed package list`
+                        : `Action '${actionRef}' does not belong to any allowed package`,
+                },
+            }, 403, corsHeaders);
+        }
+        // 校验 Action 允许白名单
+        if (!isActionAllowedByPolicy({ packageId: pkgId, actionId: actId }, policy)) {
+            return jsonResponse({
+                ok: false,
+                runId: "",
+                error: {
+                    code: ACTION_FORBIDDEN,
+                    message: `Action '${actionRef}' is not in the allowed action list`,
+                },
+            }, 403, corsHeaders);
         }
         let body = {};
         try {

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

@@ -1,19 +1,8 @@
 import type { PackageInfo } from "../../package/types.js";
-import type { ActionDockService } from "../../service/types.js";
-import type { ServerOptions } from "../types.js";
-/**
- * 路由处理统一上下文对象。
- */
-export interface RouteContext {
-    req: Request;
-    url: URL;
-    pathname: string;
-    corsHeaders: Record<string, string>;
-    projectRoot: string | null;
-    customHome?: string;
-    service: ActionDockService;
-    options: ServerOptions;
-}
+import type { EffectiveServerPolicy, RouteContext, ServerOptions } from "../types.js";
+import { ActionForbiddenError, assertActionAllowedByPolicy, assertPackageAllowedByPolicy, filterActionsByPolicy, filterPackagesByPolicy, isActionAllowed, isActionAllowedByPolicy, isManagementAllowedByPolicy, isPackageAllowedByPolicy, PackageNotAllowedError } from "../policy.js";
+export type { RouteContext };
+export { ActionForbiddenError, PackageNotAllowedError, isActionAllowed, isActionAllowedByPolicy, isPackageAllowedByPolicy, isManagementAllowedByPolicy, filterActionsByPolicy, filterPackagesByPolicy, assertActionAllowedByPolicy, assertPackageAllowedByPolicy, };
 /**
  * 构造带 CORS 头的标准 JSON HTTP 响应。
  */
@@ -22,22 +11,22 @@ export declare function jsonResponse(data: unknown, status?: number, corsHeaders
  * 剥离标准版本前缀 (/api/v2/)，获取相对路由子路径。
  */
 export declare function getSubPath(pathname: string): string;
-import { ActionDockError } from "../../errors.js";
 /**
- * 包未列入白名单拒绝访问异常。
+ * 校验目标 action 是否属于允许动作白名单。
+ * 当 options 或 policy 中的 actionAllowlist 存在且目标 action 不在白名单中时抛出 403 ACTION_FORBIDDEN 异常。
  */
-export declare class PackageNotAllowedError extends ActionDockError {
-    status: number;
-    statusCode: number;
-    constructor(packageId: string);
-}
+export declare function assertActionAllowed(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string, options?: ServerOptions | EffectiveServerPolicy): void;
 /**
  * 校验目标 packageId 是否属于允许包白名单。
- * 当 options.packageAllowlist 存在且目标 packageId 不在白名单中时抛出 403 PACKAGE_NOT_ALLOWED 异常。
+ * 当 options 或 policy 中的 packageAllowlist 存在且目标 packageId 不在白名单中时抛出 403 PACKAGE_NOT_ALLOWED 异常。
  */
-export declare function assertPackageAllowed(packageId: string, options?: ServerOptions): void;
+export declare function assertPackageAllowed(packageId: string, options?: ServerOptions | EffectiveServerPolicy): void;
 /**
  * 解析并确定生效的目标 packageId。
  * 遵循严格的解析规则与白名单检查。
  */
-export declare function resolveTargetPackageId(packages: PackageInfo[], requestedPackageId?: string, options?: ServerOptions): string;
+export declare function resolveTargetPackageId(packages: PackageInfo[], requestedPackageId?: string, options?: ServerOptions | EffectiveServerPolicy): string;