@actiondock/core 2.19.0 → 2.21.0

package/dist/server/policy.js

@@ -1,11 +1,48 @@
 import { snapshotRunOrigin } from "../runtime/run-origin.js";
 import { parseActionRef } from "../catalog/resolve-action.js";
-import { ActionDockError, ACTION_FORBIDDEN, PACKAGE_NOT_ALLOWED } from "../errors.js";
+import { ActionDockError, ACTION_FORBIDDEN, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED } from "../errors.js";
+import { assertValidPackageId } from "../utils/index.js";
 import { safeEqual } from "./security.js";
 export { extractBearerToken } from "./security.js";
-/**
- * 动作未列入白名单拒绝访问异常。
- */
+/** 校验两类白名单授权；省略或空数组不增加授权，包列表中的独立 * 显式授予全部权限。 */
+export function assertServerPolicyValid(item, scope = "server options") {
+    for (const field of ["packageAllowlist", "actionAllowlist"]) {
+        const list = item[field];
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list)) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Invalid ${scope}.${field}: expected an array`);
+        }
+        for (const entry of list) {
+            if (typeof entry !== "string" || !entry.trim()) {
+                throw new ActionDockError(INVALID_ARGUMENT, `Invalid ${scope}.${field}: entries must be non-empty strings`);
+            }
+            try {
+                if (field === "packageAllowlist") {
+                    if (entry !== "*")
+                        assertValidPackageId(entry);
+                }
+                else {
+                    if (entry.includes("*") || entry.includes("?")) {
+                        throw new Error("wildcards are not supported in action references");
+                    }
+                    const ref = parseActionRef(entry);
+                    if (!ref.packageId) {
+                        throw new Error("action references must be fully qualified packageId/actionId references");
+                    }
+                    assertValidPackageId(ref.packageId);
+                }
+            }
+            catch (error) {
+                throw new ActionDockError(INVALID_ARGUMENT, `Invalid ${scope}.${field}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}
+/** 是否显式授予全部包与动作；不替代独立的管理能力门禁。 */
+export function isFullAccessGranted(policy) {
+    return policy?.packageAllowlist?.includes("*") === true;
+}
 export class ActionForbiddenError extends ActionDockError {
     status = 403;
     statusCode = 403;
@@ -15,9 +52,6 @@ export class ActionForbiddenError extends ActionDockError {
         Object.setPrototypeOf(this, ActionForbiddenError.prototype);
     }
 }
-/**
- * 包未列入白名单拒绝访问异常。
- */
 export class PackageNotAllowedError extends ActionDockError {
     status = 403;
     statusCode = 403;
@@ -27,41 +61,43 @@ export class PackageNotAllowedError extends ActionDockError {
         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) {
+    if (!trimmed)
         return undefined;
-    }
-    let matched = undefined;
+    let matched;
     for (const view of views) {
         const candidateToken = view.policy.token?.trim();
         if (candidateToken) {
             const isMatch = safeEqual(trimmed, candidateToken);
-            if (isMatch && !matched) {
+            if (isMatch && !matched)
                 matched = view;
-            }
         }
     }
     return matched;
 }
-/**
- * 归一化解析服务端配置的所有视图集合。
- * 保证默认视图与显式自定义视图具有统一的数据结构。
- *
- * @param options 服务端配置选项
- * @returns 默认视图与全部视图 Map 映射
- */
+function normalizeView(item, name) {
+    assertServerPolicyValid(item, `view '${name}'`);
+    return {
+        name,
+        policy: {
+            viewName: name,
+            token: item.token,
+            packageAllowlist: item.packageAllowlist?.slice(),
+            actionAllowlist: item.actionAllowlist?.map((entry) => {
+                const ref = parseActionRef(entry);
+                return `${ref.packageId}/${ref.actionId}`;
+            }),
+            enableManagement: item.enableManagement,
+        },
+        enableMcp: item.enableMcp !== false,
+        rawOptions: item,
+    };
+}
+/** 全局选项仅配置默认视图；命名视图独立授权，缺少授权的视图默认拒绝全部。 */
 export function normalizeServerViews(options) {
-    const views = new Map();
-    // 1. 初始化基于全局配置的默认视图
+    assertServerPolicyValid(options);
     const defaultRawOptions = {
         name: "default",
         token: options.token,
@@ -72,307 +108,114 @@ export function normalizeServerViews(options) {
         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,
-                    });
-                }
-            }
+    const entries = Array.isArray(options.views)
+        ? options.views.map((item, index) => [`view_${index}`, item])
+        : Object.entries(options.views || {});
+    for (const [key, item] of entries) {
+        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 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,
-                    });
-                }
-            }
+        else {
+            customViews.set(name, normalizeView(item, name));
         }
     }
-    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);
-    }
+    const defaultView = normalizeView(defaultRawOptions, "default");
+    const views = new Map([["default", defaultView], ...customViews]);
     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;
+/** 目标引用格式错误或包身份不一致时返回未命中，不能猜测其所属包。 */
+function parsePolicyAction(action) {
+    if (!action)
+        return undefined;
     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);
-            }
-        }
+        if (typeof action === "string")
+            return parseActionRef(action);
+        const rawId = action.actionId || action.id;
+        if (!rawId)
+            return undefined;
+        const ref = parseActionRef(rawId);
+        if (action.packageId && ref.packageId && action.packageId !== ref.packageId)
+            return undefined;
+        return { packageId: action.packageId || ref.packageId, actionId: ref.actionId };
     }
     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 undefined;
     }
-    return false;
 }
-/**
- * 根据生效策略统一判定目标动作是否允许访问。
- * 同时综合校验策略中的 packageAllowlist 与 actionAllowlist 约束。
- *
- * @param action 目标动作对象或引用字符串
- * @param policy 当前生效的服务端策略
- * @returns 是否允许访问
- */
+/** 动作列表仅按全限定引用匹配；省略或空列表不会授予任何动作。 */
+export function isActionAllowed(action, allowlist) {
+    const target = parsePolicyAction(action);
+    if (!target?.packageId)
+        return false;
+    return (allowlist || []).some((entry) => {
+        const rule = parsePolicyAction(entry);
+        return Boolean(rule?.packageId && rule.packageId === target.packageId && rule.actionId === target.actionId);
+    });
+}
+/** 整包授权与全限定单动作授权取并集；仅缺少策略对象的内部调用不执行过滤。 */
 export function isActionAllowedByPolicy(action, policy) {
-    if (!policy) {
+    if (!policy)
         return true;
-    }
-    if (!action) {
+    const target = parsePolicyAction(action);
+    if (!target)
         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 {
+    if (isFullAccessGranted(policy))
+        return true;
+    if (!target.packageId)
         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;
+    return Boolean(policy.packageAllowlist?.includes(target.packageId) ||
+        isActionAllowed(target, policy.actionAllowlist));
 }
-/**
- * 根据生效策略统一判定目标包标识是否允许访问。
- *
- * @param packageId 目标包 ID
- * @param policy 当前生效的服务端策略
- * @returns 是否允许访问
- */
+/** 整包能力授权，不从某个动作的授权推导配置、状态、规程或诊断权限。 */
 export function isPackageAllowedByPolicy(packageId, policy) {
-    if (!policy?.packageAllowlist || policy.packageAllowlist.length === 0) {
+    if (!policy || isFullAccessGranted(policy))
         return true;
-    }
-    if (!packageId) {
+    return Boolean(packageId && policy.packageAllowlist?.includes(packageId));
+}
+/** 单动作授权的包可发现必要身份信息，但不因此获得整包能力。 */
+export function isPackageVisibleByPolicy(packageId, policy) {
+    if (isPackageAllowedByPolicy(packageId, policy))
+        return true;
+    if (!packageId)
         return false;
-    }
-    return policy.packageAllowlist.includes(packageId);
+    return (policy?.actionAllowlist || []).some((entry) => parsePolicyAction(entry)?.packageId === packageId);
+}
+export function requiresMinimalPackageProjection(packageId, policy) {
+    return isPackageVisibleByPolicy(packageId, policy) && !isPackageAllowedByPolicy(packageId, policy);
 }
-/**
- * 根据生效策略统一判定配置与状态管理路由是否开启。
- *
- * @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) {
+    if (!policy)
         return actions;
-    }
-    return actions.filter((a) => isActionAllowedByPolicy({ packageId: a.packageId, actionId: a.actionId || a.id }, policy));
+    return actions.filter((action) => isActionAllowedByPolicy(action, policy));
 }
-/**
- * 根据生效策略对包列表进行统一过滤。
- *
- * @param packages 待过滤的包列表
- * @param policy 当前生效的服务端策略
- * @returns 过滤后允许访问的包列表
- */
 export function filterPackagesByPolicy(packages, policy) {
-    if (!policy?.packageAllowlist || policy.packageAllowlist.length === 0) {
+    if (!policy)
         return packages;
-    }
-    return packages.filter((p) => p.id && policy.packageAllowlist.includes(p.id));
+    return packages.filter((pkg) => isPackageVisibleByPolicy(pkg.id, policy));
 }
-/**
- * 校验目标动作是否属于允许白名单，不符合则抛出 403 异常。
- *
- * @param action 目标动作对象或引用
- * @param policy 当前生效的服务端策略
- */
 export function assertActionAllowedByPolicy(action, policy) {
     if (!isActionAllowedByPolicy(action, policy)) {
-        const actRef = typeof action === "string"
+        const ref = typeof action === "string"
             ? action
             : action.packageId
                 ? `${action.packageId}/${action.actionId || action.id}`
                 : action.actionId || action.id || "unknown";
-        throw new ActionForbiddenError(actRef);
+        throw new ActionForbiddenError(ref);
     }
 }
-/**
- * 校验目标包是否属于允许白名单，不符合则抛出 403 异常。
- *
- * @param packageId 目标包 ID
- * @param policy 当前生效的服务端策略
- */
 export function assertPackageAllowedByPolicy(packageId, policy) {
-    if (!isPackageAllowedByPolicy(packageId, policy)) {
+    if (!isPackageAllowedByPolicy(packageId, policy))
         throw new PackageNotAllowedError(packageId);
-    }
 }
-/**
- * 构造受信任的服务端执行来源快照。
- *
- * 仅挑选 channel、viewName（默认 "default"）与 authenticated（视图配置非空有效令牌）。
- * 严禁暴露令牌原文、片段或摘要。
- */
+/** 只记录受信任的执行来源，不能包含令牌原文、片段或摘要。 */
 export function createServerRunOrigin(policy, channel) {
     return snapshotRunOrigin({
         channel,

package/dist/server/routes/actions.js

@@ -3,7 +3,7 @@ import { filterByIntent } from "../../utils/intent.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 { createServerRunOrigin } from "../policy.js";
-import { filterActionsByPolicy, getSubPath, isActionAllowedByPolicy, isPackageAllowedByPolicy, jsonResponse, } from "./common.js";
+import { filterActionsByPolicy, getSubPath, isActionAllowedByPolicy, isPackageVisibleByPolicy, jsonResponse, } from "./common.js";
 /**
  * 处理 Action 相关的 HTTP 路由（列表、规范查询、同步执行与异步启动）。
  */
@@ -44,7 +44,9 @@ export async function handleActionsRoutes(ctx) {
     if (pkgActionShowMatch && req.method === "GET") {
         const packageId = decodeURIComponent(pkgActionShowMatch[1]);
         const actionId = decodeURIComponent(pkgActionShowMatch[2]);
-        if (!isPackageAllowedByPolicy(packageId, policy)) {
+        // 先按包可见性拦截完全无关包，再按实际完整引用判定动作授权，
+        // 保证仅持有单动作授权（如 B/read）时 B/read 可见可用
+        if (!isPackageVisibleByPolicy(packageId, policy)) {
             return jsonResponse({
                 ok: false,
                 error: {
@@ -84,7 +86,7 @@ export async function handleActionsRoutes(ctx) {
         try {
             const parsed = parseActionRef(actionId);
             if (parsed.packageId) {
-                if (!isPackageAllowedByPolicy(parsed.packageId, policy)) {
+                if (!isPackageVisibleByPolicy(parsed.packageId, policy)) {
                     return jsonResponse({
                         ok: false,
                         error: {
@@ -107,7 +109,7 @@ export async function handleActionsRoutes(ctx) {
         catch { }
         try {
             const spec = await service.discovery.describeAction(actionId);
-            if (!isPackageAllowedByPolicy(spec.packageId, policy)) {
+            if (!isPackageVisibleByPolicy(spec.packageId, policy)) {
                 return jsonResponse({
                     ok: false,
                     error: {
@@ -166,8 +168,8 @@ export async function handleActionsRoutes(ctx) {
             }
             catch { }
         }
-        // 解析并补全包与动作标识（仅在必要时单次查询 spec）
-        if ((!pkgId || !actId) && (policy.packageAllowlist?.length || policy.actionAllowlist?.length)) {
+        // 查询实际包与动作身份，短名请求不能绕过全限定授权判断。
+        if (!pkgId || !actId) {
             try {
                 const spec = await service.discovery.describeAction(actionRef);
                 pkgId = pkgId || spec?.packageId;
@@ -185,8 +187,8 @@ export async function handleActionsRoutes(ctx) {
                 actId = actionRef;
             }
         }
-        // 校验 Package 允许白名单
-        if (!isPackageAllowedByPolicy(pkgId, policy)) {
+        // 单动作授权只要求其所属包可见，不能用整包能力门禁将其拦截。
+        if (!isPackageVisibleByPolicy(pkgId, policy)) {
             return jsonResponse({
                 ok: false,
                 runId: "",

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

@@ -1,32 +1,17 @@
 import type { PackageInfo } from "../../package/types.js";
 import type { EffectiveServerPolicy, RouteContext, ServerOptions } from "../types.js";
-import { ActionForbiddenError, assertActionAllowedByPolicy, assertPackageAllowedByPolicy, filterActionsByPolicy, filterPackagesByPolicy, isActionAllowed, isActionAllowedByPolicy, isManagementAllowedByPolicy, isPackageAllowedByPolicy, PackageNotAllowedError } from "../policy.js";
+import { ActionForbiddenError, assertActionAllowedByPolicy, assertPackageAllowedByPolicy, filterActionsByPolicy, filterPackagesByPolicy, isActionAllowed, isActionAllowedByPolicy, isFullAccessGranted, isManagementAllowedByPolicy, isPackageAllowedByPolicy, isPackageVisibleByPolicy, PackageNotAllowedError, requiresMinimalPackageProjection } from "../policy.js";
 export type { RouteContext };
-export { ActionForbiddenError, PackageNotAllowedError, isActionAllowed, isActionAllowedByPolicy, isPackageAllowedByPolicy, isManagementAllowedByPolicy, filterActionsByPolicy, filterPackagesByPolicy, assertActionAllowedByPolicy, assertPackageAllowedByPolicy, };
-/**
- * 构造带 CORS 头的标准 JSON HTTP 响应。
- */
+export { ActionForbiddenError, PackageNotAllowedError, isActionAllowed, isActionAllowedByPolicy, isFullAccessGranted, isPackageAllowedByPolicy, isPackageVisibleByPolicy, isManagementAllowedByPolicy, requiresMinimalPackageProjection, filterActionsByPolicy, filterPackagesByPolicy, assertActionAllowedByPolicy, assertPackageAllowedByPolicy, };
 export declare function jsonResponse(data: unknown, status?: number, corsHeaders?: Record<string, string>): Response;
-/**
- * 剥离标准版本前缀 (/api/v2/)，获取相对路由子路径。
- */
 export declare function getSubPath(pathname: string): string;
-/**
- * 校验目标 action 是否属于允许动作白名单。
- * 当 options 或 policy 中的 actionAllowlist 存在且目标 action 不在白名单中时抛出 403 ACTION_FORBIDDEN 异常。
- */
 export declare function assertActionAllowed(action: {
     actionId?: string;
     id?: string;
     packageId?: string;
 } | string, options?: ServerOptions | EffectiveServerPolicy): void;
-/**
- * 校验目标 packageId 是否属于允许包白名单。
- * 当 options 或 policy 中的 packageAllowlist 存在且目标 packageId 不在白名单中时抛出 403 PACKAGE_NOT_ALLOWED 异常。
- */
 export declare function assertPackageAllowed(packageId: string, options?: ServerOptions | EffectiveServerPolicy): void;
-/**
- * 解析并确定生效的目标 packageId。
- * 遵循严格的解析规则与白名单检查。
- */
+/** 包发现可见性与整包能力分开判断，不能因单动作授权开放包级管理。 */
+export declare function assertPackageVisible(packageId: string, options?: ServerOptions | EffectiveServerPolicy): void;
+/** 管理接口只能选取整包授权目标；全局管理必须显式拥有全部授权。 */
 export declare function resolveTargetPackageId(packages: PackageInfo[], requestedPackageId?: string, options?: ServerOptions | EffectiveServerPolicy): string;