@actiondock/core 2.7.0 → 2.9.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/policy.d.ts

@@ -0,0 +1,138 @@
+import { ActionDockError } from "../errors.js";
+import type { McpEndpointHandler } from "./mcp-endpoint.js";
+import type { EffectiveServerPolicy, ServerOptions, ServerViewOptions } from "./types.js";
+export { extractBearerToken } from "./security.js";
+/**
+ * 动作未列入白名单拒绝访问异常。
+ */
+export declare class ActionForbiddenError extends ActionDockError {
+    status: number;
+    statusCode: number;
+    constructor(actionRef: string);
+}
+/**
+ * 包未列入白名单拒绝访问异常。
+ */
+export declare class PackageNotAllowedError extends ActionDockError {
+    status: number;
+    statusCode: number;
+    constructor(packageId: string);
+}
+/**
+ * 归一化后的单个服务视图结构。
+ */
+export interface NormalizedServerView {
+    /** 视图唯一标识名称 */
+    name: string;
+    /** 该视图生效的统一安全策略 */
+    policy: EffectiveServerPolicy;
+    /** 该视图是否启用 MCP 端点 */
+    enableMcp: boolean;
+    /** 原始配置选项 */
+    rawOptions: ServerViewOptions;
+    /** 为该视图独立装配的 MCP 端点处理器 */
+    mcpEndpointHandler?: McpEndpointHandler;
+}
+/**
+ * 根据客户端携带的 Token 智能匹配已注册的视图。
+ * 使用 safeEqual 进行恒定时间比较以防范时序攻击。
+ *
+ * @param token 客户端提供的 Bearer Token
+ * @param views 可遍历的视图集合
+ * @returns 匹配成功的视图对象，未命中返回 undefined
+ */
+export declare function matchViewByToken(token: string, views: Iterable<NormalizedServerView>): NormalizedServerView | undefined;
+/**
+ * 归一化解析服务端配置的所有视图集合。
+ * 保证默认视图与显式自定义视图具有统一的数据结构。
+ *
+ * @param options 服务端配置选项
+ * @returns 默认视图与全部视图 Map 映射
+ */
+export declare function normalizeServerViews(options: ServerOptions): {
+    defaultView: NormalizedServerView;
+    views: Map<string, NormalizedServerView>;
+};
+/**
+ * 校验目标动作是否在 actionAllowlist 允许白名单中。
+ * 支持短名 actionId 与全限定名 packageId/actionId 匹配：
+ * - 白名单项若含 '/'（如 pkg/act），则必须 packageId 与 actionId 同时精确匹配。
+ * - 白名单项若不含 '/'（如 act），则只需 actionId 匹配（不限包）。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param allowlist 允许动作白名单列表
+ * @returns 是否允许访问
+ */
+export declare function isActionAllowed(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string | null | undefined, allowlist?: string[]): boolean;
+/**
+ * 根据生效策略统一判定目标动作是否允许访问。
+ * 同时综合校验策略中的 packageAllowlist 与 actionAllowlist 约束。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export declare function isActionAllowedByPolicy(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string | null | undefined, policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略统一判定目标包标识是否允许访问。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export declare function isPackageAllowedByPolicy(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略统一判定配置与状态管理路由是否开启。
+ *
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许管理操作
+ */
+export declare function isManagementAllowedByPolicy(policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略对动作列表进行统一过滤。
+ *
+ * @param actions 待过滤的动作列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的动作列表
+ */
+export declare function filterActionsByPolicy<T extends {
+    id: string;
+    packageId?: string;
+    actionId?: string;
+}>(actions: T[], policy?: EffectiveServerPolicy): T[];
+/**
+ * 根据生效策略对包列表进行统一过滤。
+ *
+ * @param packages 待过滤的包列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的包列表
+ */
+export declare function filterPackagesByPolicy<T extends {
+    id: string;
+}>(packages: T[], policy?: EffectiveServerPolicy): T[];
+/**
+ * 校验目标动作是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param action 目标动作对象或引用
+ * @param policy 当前生效的服务端策略
+ */
+export declare function assertActionAllowedByPolicy(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string, policy?: EffectiveServerPolicy): void;
+/**
+ * 校验目标包是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ */
+export declare function assertPackageAllowedByPolicy(packageId: string, policy?: EffectiveServerPolicy): void;

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);
+    }
+}