@actiondock/core 2.19.0 → 2.21.0

package/dist/security/config-key.js

@@ -0,0 +1,469 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { ActionDockError, CONFIG_ENCRYPTION_ERROR } from "../errors.js";
+import { getActionDockHome } from "../utils/index.js";
+import { configKeyId } from "./config-cipher.js";
+/** 环境变量密钥来源名称，值必须为严格的 64 位十六进制字符串 */
+const ENV_KEY_NAME = "ACTIONDOCK_ENCRYPTION_KEY";
+/**
+ * 环境密钥的严格格式：恰好 64 位十六进制字符（解码后恰为 32 字节 AES-256 密钥）。
+ * 空字符串、空白或前后填充均视为非法取值，绝不允许回退到本地密钥来源。
+ */
+const ENV_KEY_PATTERN = /^[0-9a-fA-F]{64}$/;
+/** AES-256 密钥字节长度 */
+const KEY_BYTES = 32;
+/** 密钥文件与身份标记规范权限：仅属主可读写 */
+const KEY_FILE_MODE = 0o600;
+/** 密钥目录规范权限：仅属主可访问 */
+const KEY_DIR_MODE = 0o700;
+/** 密钥指纹的规范形式：64 位小写十六进制字符 */
+const KEY_ID_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * POSIX 权限位语义在 Windows 上不存在，权限强制校验仅在 POSIX 平台执行；
+ * 常规文件与真实目录（拒绝符号链接）检查在所有平台始终生效。
+ */
+const IS_POSIX = process.platform !== "win32";
+/**
+ * 平台明确不支持目录 fsync 的错误码集合，仅这些可安全忽略；
+ * EIO 等真实 I/O 故障必须作为失败透传，不得静默吞没。
+ */
+const DIRECTORY_FSYNC_UNSUPPORTED_CODES = new Set([
+    "EINVAL",
+    "ENOTSUP",
+    "EOPNOTSUPP",
+]);
+/** Windows 可能拒绝打开目录句柄；POSIX 上同类权限错误必须透传。 */
+const WINDOWS_DIRECTORY_FSYNC_UNSUPPORTED_CODES = new Set(["EPERM", "EACCES", "EISDIR"]);
+/**
+ * 创建配置加密密钥提供器。
+ *
+ * 来源优先级：
+ * - 显式注入 key：纯内存材料，绝不读取环境变量或真实用户目录，也无需钉住持久身份；
+ * - 环境变量 ACTIONDOCK_ENCRYPTION_KEY：必须为恰好 64 位十六进制字符，
+ *   只要被设置（含空串或空白）就必须严格合法，非法取值立即报错，
+ *   绝不静默回退到本地密钥；
+ * - 本地密钥文件：dataDir 有值时为 <dataDir>/keys/config.key，
+ *   否则为 getActionDockHome(customHome)/.actiondock/keys/config.key。
+ *
+ * 构造时不发生任何环境读取、文件访问或目录创建；全部定位与加载在
+ * 首次调用时完成并缓存，此后同一提供器实例不再感知环境变化（宿主快照）。
+ * 若首次调用以 create 为 false 加载了未钉住身份的材料，后续 create 为 true
+ * 的调用会先原子创建或校验身份标记再返回缓存材料，保证允许写入前
+ * 持久域身份一定已经落盘。
+ *
+ * 身份保护：标记存在而密钥材料丢失时直接报错，绝不为同一存储域重新
+ * 生成新密钥；提供密钥与标记指纹不符时同样拒绝。
+ */
+export function createConfigKeyProvider(options) {
+    const opts = options ?? {};
+    let cached;
+    return (create) => {
+        if (cached === undefined) {
+            cached =
+                opts.key !== undefined
+                    ? { material: materialFromInjectedKey(opts.key), pinned: true, source: "injected" }
+                    : loadMaterialFromEnvironmentOrFile(opts, create);
+            return cached.material;
+        }
+        if (create && !cached.pinned) {
+            pinPersistedIdentity(opts, cached);
+            cached = { ...cached, pinned: true };
+        }
+        return cached.material;
+    };
+}
+/**
+ * 为缓存的未钉住材料补齐持久域身份：原子创建或校验身份标记。
+ *
+ * 首次以只读方式（create 为 false）加载的材料可能尚未在磁盘钉住身份；
+ * 在任何允许写入的调用返回前必须补齐，防止宿主进程在从未落盘身份的
+ * 状态下写出密文后丢失密钥归属。注入来源纯内存，直接跳过。
+ */
+function pinPersistedIdentity(opts, state) {
+    if (state.source === "injected") {
+        return;
+    }
+    const paths = resolveKeyPaths(opts);
+    const id = state.material.id;
+    if (state.source === "env" && existsSync(paths.keyPath)) {
+        assertSecureKeyDirectory(paths.keyDir);
+        const fileBytes = readKeyFile(paths.keyPath);
+        if (configKeyId(fileBytes) !== id) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Environment key identity does not match the existing local key file '${paths.keyPath}'`);
+        }
+    }
+    const markerId = readMarkerIdIfExists(paths.markerPath);
+    if (markerId !== undefined) {
+        assertSecureKeyDirectory(paths.keyDir);
+        if (markerId !== id) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Recorded key identity marker '${paths.markerPath}' does not match the active key; refusing to continue with a different key`);
+        }
+        return;
+    }
+    assertOrCreateSecureKeyDirectory(paths.keyDir);
+    publishMarkerFile(paths.markerPath, id);
+}
+/**
+ * 解析密钥存储路径集合。
+ */
+function resolveKeyPaths(opts) {
+    const keyDir = opts.dataDir && opts.dataDir.length > 0
+        ? join(opts.dataDir, "keys")
+        : join(getActionDockHome(opts.customHome), ".actiondock", "keys");
+    return {
+        keyDir,
+        keyPath: join(keyDir, "config.key"),
+        markerPath: join(keyDir, "config.key.id"),
+    };
+}
+/**
+ * 构造显式注入密钥的材料。
+ *
+ * 纯内存路径：仅校验密钥长度并计算指纹，不读取环境变量，
+ * 不访问、校验或创建任何真实文件系统路径，也不持久化身份标记。
+ */
+function materialFromInjectedKey(key) {
+    if (!(key instanceof Uint8Array) || key.byteLength !== KEY_BYTES) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Invalid injected config encryption key: expected ${KEY_BYTES} bytes, got ${key instanceof Uint8Array ? key.byteLength : typeof key}`);
+    }
+    return { key, id: configKeyId(key) };
+}
+/**
+ * 依据来源优先级加载持久化密钥材料：环境变量优先于本地密钥文件。
+ *
+ * 环境变量一旦被设置（包括空串、空白或任何非法形态）就必须严格合法，
+ * 不存在“视为未设置”的宽松路径，杜绝无效配置静默回退。
+ */
+function loadMaterialFromEnvironmentOrFile(opts, create) {
+    const paths = resolveKeyPaths(opts);
+    const envSource = opts.env ?? process.env;
+    const raw = envSource[ENV_KEY_NAME];
+    if (raw !== undefined) {
+        return loadEnvKeyMaterial(raw, paths, create);
+    }
+    return loadLocalKeyMaterial(paths, create);
+}
+/**
+ * 解析环境变量密钥来源。
+ *
+ * 值必须为恰好 64 位十六进制字符（仅允许大小写差异），空串、空白、
+ * 前后填充或任何非法字符均立即抛出 CONFIG_ENCRYPTION_ERROR，绝不回退
+ * 到本地密钥文件。首次允许创建时同样原子记录身份标记；若本地密钥文件
+ * 或标记已存在且指纹不同，则拒绝使用该环境密钥，防止用第二把有效密钥
+ * 写入历史密钥的存储域。标记存在时密钥目录必须通过安全校验，不因
+ * 缺少本地密钥文件而绕过目录检查。
+ */
+function loadEnvKeyMaterial(raw, paths, create) {
+    if (typeof raw !== "string" || !ENV_KEY_PATTERN.test(raw)) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Environment variable ${ENV_KEY_NAME} must be exactly 64 hex characters (32 bytes); the configured value is invalid and falling back to another key source is not permitted`);
+    }
+    const keyBytes = Buffer.from(raw, "hex");
+    const id = configKeyId(keyBytes);
+    if (existsSync(paths.keyPath)) {
+        assertSecureKeyDirectory(paths.keyDir);
+        const fileBytes = readKeyFile(paths.keyPath);
+        if (configKeyId(fileBytes) !== id) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Environment key identity does not match the existing local key file '${paths.keyPath}'`);
+        }
+    }
+    const markerId = readMarkerIdIfExists(paths.markerPath);
+    if (markerId !== undefined) {
+        assertSecureKeyDirectory(paths.keyDir);
+        if (markerId !== id) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Environment key identity does not match the recorded key identity marker '${paths.markerPath}'`);
+        }
+        return { material: { key: keyBytes, id }, pinned: true, source: "env" };
+    }
+    if (create) {
+        assertOrCreateSecureKeyDirectory(paths.keyDir);
+        publishMarkerFile(paths.markerPath, id);
+        return { material: { key: keyBytes, id }, pinned: true, source: "env" };
+    }
+    return { material: { key: keyBytes, id }, pinned: false, source: "env" };
+}
+/**
+ * 加载本地密钥文件材料，必要时按安全约束生成并发布新密钥。
+ */
+function loadLocalKeyMaterial(paths, create) {
+    const markerId = readMarkerIdIfExists(paths.markerPath);
+    if (!existsSync(paths.keyPath)) {
+        if (markerId !== undefined) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key file '${paths.keyPath}' is missing while identity marker '${paths.markerPath}' still pins key id '${markerId}'; refusing to generate a new key for this storage domain. Restore the original key file or provide ${ENV_KEY_NAME}`, { keyPath: paths.keyPath, markerPath: paths.markerPath });
+        }
+        if (!create) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key file '${paths.keyPath}' does not exist and key creation is disabled for this call`, { keyPath: paths.keyPath });
+        }
+        publishGeneratedKeyFile(paths.keyDir, paths.keyPath);
+    }
+    assertSecureKeyDirectory(paths.keyDir);
+    const keyBytes = readKeyFile(paths.keyPath);
+    const id = configKeyId(keyBytes);
+    if (markerId !== undefined) {
+        if (markerId !== id) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key file '${paths.keyPath}' does not match the recorded key identity marker '${paths.markerPath}'`, { keyPath: paths.keyPath, markerPath: paths.markerPath });
+        }
+        return { material: { key: keyBytes, id }, pinned: true, source: "file" };
+    }
+    if (create) {
+        publishMarkerFile(paths.markerPath, id);
+        return { material: { key: keyBytes, id }, pinned: true, source: "file" };
+    }
+    return { material: { key: keyBytes, id }, pinned: false, source: "file" };
+}
+/**
+ * 生成随机密钥并安全发布到目标路径。
+ *
+ * 发布语义：先在私有临时文件中完整写入 32 字节随机密钥并 fsync，
+ * 再以不覆盖的硬链接原子发布；竞争失败方直接读取胜者已发布的完整文件，
+ * 绝不出现先用独占标志创建目标再缓慢写入导致他人读到半文件的窗口。
+ */
+function publishGeneratedKeyFile(keyDir, keyPath) {
+    assertOrCreateSecureKeyDirectory(keyDir);
+    const material = randomBytes(KEY_BYTES);
+    publishAtomically(keyPath, material, KEY_FILE_MODE);
+}
+/**
+ * 原子发布身份标记文件，竞争发布失败时复核既有标记一致性。
+ *
+ * 发布成功路径内含所属目录的尽力 fsync，确保标记目录项先于密文持久化。
+ */
+function publishMarkerFile(markerPath, id) {
+    const published = publishAtomically(markerPath, Buffer.from(`${id}\n`, "utf8"), KEY_FILE_MODE);
+    if (!published) {
+        const existing = readMarkerIdIfExists(markerPath);
+        if (existing !== id) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Recorded key identity marker '${markerPath}' does not match the active key; refusing to overwrite`);
+        }
+    }
+}
+/**
+ * 以不覆盖方式原子发布文件内容。
+ *
+ * 发布分三段且各段失败均清理临时文件：完整写入并 fsync 私有临时文件、
+ * 修正权限位、以硬链接原子发布到目标路径。目标已存在（EEXIST）时返回
+ * false 表示竞争失败，由调用方读取胜者已发布的完整文件。
+ *
+ * 临时文件承载主密钥内容：任何失败路径都必须尽力删除临时文件；发布成功
+ * 后临时文件名与目标共享同一 inode，也必须移除临时名，避免密钥材料多出
+ * 一条可达路径。清理失败与真实 I/O 故障一律包装为 CONFIG_ENCRYPTION_ERROR
+ * 透传，不得静默吞没。
+ */
+function publishAtomically(targetPath, content, mode) {
+    const dir = dirname(targetPath);
+    const tmpPath = join(dir, `.${basename(targetPath)}.tmp.${process.pid}.${randomUUID()}`);
+    try {
+        const fd = openSync(tmpPath, "wx", mode);
+        try {
+            writeAll(fd, content);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        if (IS_POSIX) {
+            chmodSync(tmpPath, mode);
+        }
+    }
+    catch (err) {
+        if (!cleanupTempFile(tmpPath)) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Failed to write key-bearing temporary file '${tmpPath}' and its cleanup also failed; remove the file manually before retrying`, { path: tmpPath });
+        }
+        throw wrapFsError(err, tmpPath);
+    }
+    try {
+        linkSync(tmpPath, targetPath);
+    }
+    catch (err) {
+        if (!cleanupTempFile(tmpPath)) {
+            throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Failed to publish '${targetPath}' and cleaning up key-bearing temporary file '${tmpPath}' also failed; remove the file manually before retrying`, { path: tmpPath });
+        }
+        if (err instanceof Error && err.code === "EEXIST") {
+            return false;
+        }
+        throw wrapFsError(err, targetPath);
+    }
+    if (!cleanupTempFile(tmpPath)) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Published '${targetPath}' but removing its temporary name '${tmpPath}' failed; both names currently expose the same key material`, { path: tmpPath });
+    }
+    fsyncDirectory(dir);
+    return true;
+}
+/**
+ * 删除承载密钥材料的临时文件；返回是否清理成功。
+ *
+ * 文件不存在视为已清理；其余失败向上交由调用方以统一错误透传，
+ * 因为残留的临时文件本身就是主密钥的一条可达路径。
+ */
+function cleanupTempFile(tmpPath) {
+    try {
+        unlinkSync(tmpPath);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof Error && err.code === "ENOENT") {
+            return true;
+        }
+        return false;
+    }
+}
+/**
+ * 循环写入直至全部字节落盘。
+ */
+function writeAll(fd, content) {
+    let offset = 0;
+    while (offset < content.byteLength) {
+        offset += writeSync(fd, content, offset, content.byteLength - offset);
+    }
+}
+/**
+ * 同步目录项以确保发布链接在断电后仍然存在。
+ *
+ * 崩溃耐久性：仅 fsync 临时文件不足以保证断电后文件名存在，发布链接后
+ * 必须 fsync 所属目录，使目录项先于任何依赖该密钥的密文持久化；提供器
+ * 在目录同步完成后才返回材料，保证调用方后续写入的密文不会引用一个
+ * 掉电后丢失的密钥名。仅平台明确不支持目录 fsync 的错误码可忽略，
+ * EIO 等真实故障必须失败。
+ */
+function fsyncDirectory(dir) {
+    let fd;
+    try {
+        fd = openSync(dir, "r");
+        fsyncSync(fd);
+    }
+    catch (err) {
+        const code = err instanceof Error && typeof err.code === "string" ? err.code : undefined;
+        if (code !== undefined && (DIRECTORY_FSYNC_UNSUPPORTED_CODES.has(code) ||
+            (!IS_POSIX && WINDOWS_DIRECTORY_FSYNC_UNSUPPORTED_CODES.has(code)))) {
+            return;
+        }
+        throw wrapFsError(err, dir);
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // fsync 已完成，描述符关闭失败不影响目录项持久化语义
+            }
+        }
+    }
+}
+/**
+ * 读取并严格校验本地密钥文件。
+ *
+ * 所有平台拒绝符号链接与任何非常规文件、非 32 字节长度；
+ * POSIX 平台额外强制权限位恰为 0600，安全权限异常不得被忽略。
+ */
+function readKeyFile(keyPath) {
+    let stat;
+    try {
+        stat = lstatSync(keyPath);
+    }
+    catch (err) {
+        throw wrapFsError(err, keyPath);
+    }
+    if (!stat.isFile()) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key file '${keyPath}' is not a regular file (symlinks and special files are rejected)`);
+    }
+    if (IS_POSIX && (stat.mode & 0o777) !== KEY_FILE_MODE) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key file '${keyPath}' has unsafe permissions ${(stat.mode & 0o777).toString(8)} (expected ${KEY_FILE_MODE.toString(8)})`);
+    }
+    let content;
+    try {
+        content = readFileSync(keyPath);
+    }
+    catch (err) {
+        throw wrapFsError(err, keyPath);
+    }
+    if (content.byteLength !== KEY_BYTES) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key file '${keyPath}' must contain exactly ${KEY_BYTES} bytes, got ${content.byteLength}`);
+    }
+    return content;
+}
+/**
+ * 读取身份标记文件中的指纹；不存在时返回 undefined，存在但损坏即报错。
+ *
+ * 所有平台拒绝非常规文件；POSIX 平台额外强制权限位恰为 0600，
+ * 标记与密钥文件同级安全，不得因非敏感而放宽。
+ */
+function readMarkerIdIfExists(markerPath) {
+    let stat;
+    try {
+        stat = lstatSync(markerPath);
+    }
+    catch (err) {
+        if (err instanceof Error && err.code === "ENOENT") {
+            return undefined;
+        }
+        throw wrapFsError(err, markerPath);
+    }
+    if (!stat.isFile()) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config key identity marker '${markerPath}' is not a regular file`);
+    }
+    if (IS_POSIX && (stat.mode & 0o777) !== KEY_FILE_MODE) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config key identity marker '${markerPath}' has unsafe permissions ${(stat.mode & 0o777).toString(8)} (expected ${KEY_FILE_MODE.toString(8)})`);
+    }
+    let content;
+    try {
+        content = readFileSync(markerPath, "utf8");
+    }
+    catch (err) {
+        throw wrapFsError(err, markerPath);
+    }
+    const id = content.trim();
+    if (!KEY_ID_PATTERN.test(id)) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config key identity marker '${markerPath}' is corrupted (expected 64 lowercase hex characters)`);
+    }
+    return id;
+}
+/**
+ * 校验密钥目录为真实目录（拒绝符号链接）；POSIX 平台额外强制权限恰为 0700。
+ */
+function assertSecureKeyDirectory(keyDir) {
+    let stat;
+    try {
+        stat = lstatSync(keyDir);
+    }
+    catch (err) {
+        throw wrapFsError(err, keyDir);
+    }
+    if (!stat.isDirectory()) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key directory '${keyDir}' is not a real directory (symlinks are rejected)`);
+    }
+    if (IS_POSIX && (stat.mode & 0o777) !== KEY_DIR_MODE) {
+        throw new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key directory '${keyDir}' has unsafe permissions ${(stat.mode & 0o777).toString(8)} (expected ${KEY_DIR_MODE.toString(8)})`);
+    }
+}
+/**
+ * 确保密钥目录存在且安全：缺失时以 0700 递归创建并显式修正权限。
+ */
+function assertOrCreateSecureKeyDirectory(keyDir) {
+    if (existsSync(keyDir)) {
+        assertSecureKeyDirectory(keyDir);
+        return;
+    }
+    try {
+        mkdirSync(keyDir, { recursive: true, mode: KEY_DIR_MODE });
+    }
+    catch (err) {
+        throw wrapFsError(err, keyDir);
+    }
+    if (IS_POSIX) {
+        try {
+            chmodSync(keyDir, KEY_DIR_MODE);
+        }
+        catch (err) {
+            throw wrapFsError(err, keyDir);
+        }
+    }
+    assertSecureKeyDirectory(keyDir);
+}
+/**
+ * 将文件系统异常包装为统一的结构化加密配置错误，消息不携带任何秘密。
+ */
+function wrapFsError(err, path) {
+    const reason = err instanceof Error && typeof err.code === "string" ? err.code : undefined;
+    return new ActionDockError(CONFIG_ENCRYPTION_ERROR, `Config encryption key storage operation failed on '${path}'${reason ? ` (${reason})` : ""}`, { path });
+}

package/dist/server/policy.d.ts

@@ -3,144 +3,61 @@ 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";
-/**
- * 动作未列入白名单拒绝访问异常。
- */
+type PolicyAction = {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string;
+/** 校验两类白名单授权；省略或空数组不增加授权，包列表中的独立 * 显式授予全部权限。 */
+export declare function assertServerPolicyValid(item: {
+    packageAllowlist?: unknown;
+    actionAllowlist?: unknown;
+}, scope?: string): void;
+/** 是否显式授予全部包与动作；不替代独立的管理能力门禁。 */
+export declare function isFullAccessGranted(policy?: EffectiveServerPolicy | null): boolean;
 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 isActionAllowed(action: PolicyAction | null | undefined, allowlist?: string[]): boolean;
+/** 整包授权与全限定单动作授权取并集；仅缺少策略对象的内部调用不执行过滤。 */
+export declare function isActionAllowedByPolicy(action: PolicyAction | null | undefined, policy?: EffectiveServerPolicy): boolean;
+/** 整包能力授权，不从某个动作的授权推导配置、状态、规程或诊断权限。 */
 export declare function isPackageAllowedByPolicy(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
-/**
- * 根据生效策略统一判定配置与状态管理路由是否开启。
- *
- * @param policy 当前生效的服务端策略
- * @returns 是否允许管理操作
- */
+/** 单动作授权的包可发现必要身份信息，但不因此获得整包能力。 */
+export declare function isPackageVisibleByPolicy(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
+export declare function requiresMinimalPackageProjection(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
 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 assertActionAllowedByPolicy(action: PolicyAction, policy?: EffectiveServerPolicy): void;
 export declare function assertPackageAllowedByPolicy(packageId: string, policy?: EffectiveServerPolicy): void;
-/**
- * 构造受信任的服务端执行来源快照。
- *
- * 仅挑选 channel、viewName（默认 "default"）与 authenticated（视图配置非空有效令牌）。
- * 严禁暴露令牌原文、片段或摘要。
- */
+/** 只记录受信任的执行来源，不能包含令牌原文、片段或摘要。 */
 export declare function createServerRunOrigin(policy: Pick<EffectiveServerPolicy, "viewName" | "token">, channel: RunOrigin["channel"]): RunOrigin;