@actiondock/core 2.19.0 → 2.20.0

package/dist/server/routes/runs.js

@@ -3,7 +3,66 @@ import { isTerminalRunStatus } from "../../storage/types.js";
 import { createAbortError } from "../../ipc/service.js";
 import { parseDuration } from "../../utils/index.js";
 import { readJsonBody } from "../body.js";
-import { getSubPath, isActionAllowedByPolicy, isPackageAllowedByPolicy, jsonResponse } from "./common.js";
+import { parseActionRef } from "../../catalog/resolve-action.js";
+import { getSubPath, isActionAllowedByPolicy, isFullAccessGranted, isPackageAllowedByPolicy, isPackageVisibleByPolicy, jsonResponse } from "./common.js";
+/** 清理范围必须落在整包或精确动作授权内，全局清理必须显式拥有全部授权。 */
+function resolveRunCleanupScope(packageId, actionId, policy) {
+    if (isFullAccessGranted(policy)) {
+        if (packageId && !isPackageVisibleByPolicy(packageId, policy)) {
+            return {
+                ok: false,
+                reason: `Package '${packageId}' is not in the allowed package list`,
+            };
+        }
+        return { ok: true, filter: { packageId, actionId } };
+    }
+    // 单动作清理必须解析出完整身份，避免鉴权与实际清理范围不一致。
+    if (actionId) {
+        let parsed;
+        try {
+            parsed = parseActionRef(actionId);
+        }
+        catch {
+            return { ok: false, reason: `Invalid action reference '${actionId}'` };
+        }
+        // 全限定引用与显式 packageId 归一化后不一致必须拒绝，防止鉴权与过滤范围错位
+        if (parsed.packageId && packageId && parsed.packageId !== packageId) {
+            return {
+                ok: false,
+                reason: `Action reference '${parsed.packageId}/${parsed.actionId}' does not match the requested package scope '${packageId}'`,
+            };
+        }
+        const targetPkgId = parsed.packageId || packageId;
+        if (!targetPkgId) {
+            return {
+                ok: false,
+                reason: "Restricted access policy requires a fully qualified 'packageId/actionId' action reference for run cleanup",
+            };
+        }
+        if (!isActionAllowedByPolicy({ packageId: targetPkgId, actionId: parsed.actionId }, policy)) {
+            return {
+                ok: false,
+                reason: `Action '${targetPkgId}/${parsed.actionId}' is not in the allowed action list`,
+            };
+        }
+        // 以归一化完整引用传递，确保底层过滤范围与鉴权引用一致且不扩大
+        return { ok: true, filter: { packageId: targetPkgId, actionId: parsed.actionId } };
+    }
+    // 无 actionId：必须有明确包范围，且该范围必须是整包授权
+    if (!packageId) {
+        return {
+            ok: false,
+            reason: "Restricted access policy requires an explicit 'packageId' or fully qualified 'actionId' scope for run cleanup",
+        };
+    }
+    if (!isPackageAllowedByPolicy(packageId, policy)) {
+        return {
+            ok: false,
+            reason: `Package '${packageId}' is not fully granted; run cleanup requires a fully granted package or an explicitly granted 'packageId/actionId' reference`,
+        };
+    }
+    return { ok: true, filter: { packageId } };
+}
 /**
  * 处理历史运行记录查询、清理、详情及 SSE 流式日志接口。
  */
@@ -54,7 +113,7 @@ export async function handleRunsRoutes(ctx) {
                     limit = Math.min(Math.max(parsedLimit, 1), 500);
                 }
             }
-            if (packageId && !isPackageAllowedByPolicy(packageId, policy)) {
+            if (packageId && !isPackageVisibleByPolicy(packageId, policy)) {
                 return jsonResponse({
                     ok: false,
                     error: {
@@ -63,7 +122,7 @@ export async function handleRunsRoutes(ctx) {
                     },
                 }, 403, corsHeaders);
             }
-            if (actionId && !isActionAllowedByPolicy({ packageId, actionId }, policy)) {
+            if (actionId && (packageId || actionId.includes("/")) && !isActionAllowedByPolicy({ packageId, actionId }, policy)) {
                 return jsonResponse({
                     ok: false,
                     error: {
@@ -72,6 +131,15 @@ export async function handleRunsRoutes(ctx) {
                     },
                 }, 403, corsHeaders);
             }
+            // 下推的是包可见性并集，仍须逐条校验动作，不能丢弃单动作授权包的记录。
+            const visiblePackageIds = new Set([
+                ...(policy.packageAllowlist || []).filter((id) => id !== "*"),
+                ...(policy.actionAllowlist || []).map((ref) => parseActionRef(ref).packageId),
+            ]);
+            const backendPackageFilter = isFullAccessGranted(policy) ? undefined : [...visiblePackageIds];
+            if (backendPackageFilter?.length === 0) {
+                return jsonResponse({ ok: true, items: [], total: 0, limit, offset }, 200, corsHeaders);
+            }
             const queryOptions = {
                 actionId,
                 status,
@@ -86,12 +154,9 @@ export async function handleRunsRoutes(ctx) {
                 intent,
                 requestIds: requestIds.length > 0 ? requestIds : undefined,
                 signal: req.signal,
-                packageAllowlist: policy.packageAllowlist && policy.packageAllowlist.length > 0
-                    ? policy.packageAllowlist
-                    : undefined,
+                packageAllowlist: backendPackageFilter,
             };
-            const hasPolicyFilter = Boolean((policy.packageAllowlist && policy.packageAllowlist.length > 0) ||
-                (policy.actionAllowlist && policy.actionAllowlist.length > 0));
+            const hasPolicyFilter = !isFullAccessGranted(policy);
             let runs;
             let total;
             if (hasPolicyFilter) {
@@ -116,7 +181,9 @@ export async function handleRunsRoutes(ctx) {
                         break;
                     }
                     for (const run of batch) {
-                        const packageAllowed = isPackageAllowedByPolicy(run.packageId, policy);
+                        // 逐条以实际 packageId/actionId 完整引用判定授权：
+                        // 包可见性拦无关包，动作授权保留单动作授权目标（如 B/read）
+                        const packageAllowed = isPackageVisibleByPolicy(run.packageId, policy);
                         const actionAllowed = isActionAllowedByPolicy({ packageId: run.packageId, actionId: run.actionId }, policy);
                         if (packageAllowed && actionAllowed) {
                             if (matchedCount >= offset && pagedRuns.length < limit) {
@@ -218,20 +285,22 @@ export async function handleRunsRoutes(ctx) {
                     keep = parsed;
                 }
             }
-            if (packageId && !isPackageAllowedByPolicy(packageId, policy)) {
+            const scopeCheck = resolveRunCleanupScope(packageId, actionId, policy);
+            if (!scopeCheck.ok) {
                 return jsonResponse({
                     ok: false,
                     error: {
                         code: PACKAGE_FORBIDDEN,
-                        message: `Package '${packageId}' is not in the allowed package list`,
+                        message: scopeCheck.reason,
                     },
                 }, 403, corsHeaders);
             }
+            const clearedScope = scopeCheck.filter;
             let clearedCount = 0;
             if (service.runs.clear) {
                 clearedCount = await service.runs.clear({
-                    packageId,
-                    actionId,
+                    packageId: clearedScope.packageId,
+                    actionId: clearedScope.actionId,
                     status,
                     olderThanMs,
                     keep,
@@ -244,7 +313,17 @@ export async function handleRunsRoutes(ctx) {
         }
     }
     // 2.1 Runs Clean Expired: POST /api/v2/runs/clean-expired, POST /runs/clean-expired
+    // 此操作无法按包或动作收窄范围，只允许显式的全部授权。
     if (subpath === "/runs/clean-expired" && req.method === "POST") {
+        if (!isFullAccessGranted(policy)) {
+            return jsonResponse({
+                ok: false,
+                error: {
+                    code: PACKAGE_FORBIDDEN,
+                    message: "Expired run cleanup cannot be scoped under a restricted access policy",
+                },
+            }, 403, corsHeaders);
+        }
         try {
             let body = {};
             if (req.headers.get("content-type")?.includes("json")) {
@@ -268,7 +347,7 @@ export async function handleRunsRoutes(ctx) {
         if (!run) {
             return jsonResponse({ ok: false, error: { code: RUN_NOT_FOUND, message: `Run '${runId}' not found` } }, 404, corsHeaders);
         }
-        if (!isPackageAllowedByPolicy(run.packageId, policy)) {
+        if (!isPackageVisibleByPolicy(run.packageId, policy)) {
             return jsonResponse({
                 ok: false,
                 error: {
@@ -443,7 +522,7 @@ export async function handleRunsRoutes(ctx) {
                 },
             }, 404, corsHeaders);
         }
-        if (!isPackageAllowedByPolicy(run.packageId, policy)) {
+        if (!isPackageVisibleByPolicy(run.packageId, policy)) {
             return jsonResponse({
                 ok: false,
                 error: {
@@ -467,11 +546,10 @@ export async function handleRunsRoutes(ctx) {
     const runCancelMatch = subpath.match(/^\/runs\/([^/]+)\/cancel$/);
     if (runCancelMatch && req.method === "POST") {
         const runId = decodeURIComponent(runCancelMatch[1]);
-        if ((policy.packageAllowlist && policy.packageAllowlist.length > 0) ||
-            (policy.actionAllowlist && policy.actionAllowlist.length > 0)) {
+        if (!isFullAccessGranted(policy)) {
             const run = await service.runs.get(runId);
             if (run) {
-                if (!isPackageAllowedByPolicy(run.packageId, policy)) {
+                if (!isPackageVisibleByPolicy(run.packageId, policy)) {
                     return jsonResponse({
                         ok: false,
                         error: {

package/dist/server/server.js

@@ -3,8 +3,8 @@ import { NodeHttpServer } from "./http-server.js";
 import { createActionDock } from "../service/factory.js";
 import { ActionDockError, ACCESS_DENIED, NOT_FOUND, SERVICE_ERROR, UNAUTHORIZED } from "../errors.js";
 import { parseActionRef } from "../catalog/resolve-action.js";
-import { findProjectRoot } from "../project/loader.js";
-import { listLinkedPackages, resolvePackageRoot } from "../registry/registry.js";
+import { findProjectRoot, loadProjectConfig } from "../project/loader.js";
+import { resolvePackageRoot } from "../registry/registry.js";
 import { handleActionsRoutes, handleConfigRoutes, handleDoctorRoute, handleHealthRoute, handleInfoRoute, handlePlaybooksRoutes, handleRunsRoutes, handleStateRoutes, jsonResponse, } from "./routes/index.js";
 import { isLoopbackHost, resolveCorsHeaders, verifyBearerToken } from "./security.js";
 import { createMcpEndpointHandler } from "./mcp-endpoint.js";
@@ -70,70 +70,42 @@ export async function startActionDockServer(arg1, arg2) {
         throw new ActionDockError(ACCESS_DENIED, "Authentication token is required when binding to a non-loopback address. Use --allow-insecure-no-auth to override.");
     }
     let serviceInstance = options.service;
-    // 若未传 service，服务端统一通过 createActionDock() 实例化，不再接受或处理外部传入的 Host 实体
+    // 包授权与单动作引用都参与自建服务的装载；外部注入服务自行负责能力装配。
     if (!serviceInstance) {
-        const scanLinkedPackages = options.scanLinkedPackages ?? !projectRoot;
+        const declaredId = projectRoot ? loadProjectConfig(projectRoot).id : undefined;
+        const referencedPackages = new Set();
+        for (const view of views.values()) {
+            for (const pkgId of view.policy.packageAllowlist || []) {
+                if (pkgId !== "*")
+                    referencedPackages.add(pkgId);
+            }
+            for (const action of view.policy.actionAllowlist || []) {
+                referencedPackages.add(parseActionRef(action).packageId);
+            }
+        }
+        const extraPackages = [];
+        for (const pkgId of referencedPackages) {
+            if (pkgId === declaredId)
+                continue;
+            const root = resolvePackageRoot(pkgId, projectRoot || undefined, customHome);
+            if (root && !extraPackages.some((pkg) => pkg.packageRoot === root)) {
+                extraPackages.push({ packageRoot: root });
+            }
+        }
         serviceInstance = await createActionDock({
             projectRoot: projectRoot || undefined,
+            packages: extraPackages.length > 0 ? extraPackages : undefined,
             customHome,
             platform: options.platform,
             dataDir: options.dataDir,
             inMemory: options.inMemory,
-            scanLinkedPackages,
+            scanLinkedPackages: options.scanLinkedPackages ?? !projectRoot,
             enableManagement: options.enableManagement,
         });
     }
     if (!serviceInstance) {
         throw new ActionDockError(SERVICE_ERROR, "Failed to initialize ActionDockService for server");
     }
-    // 2. 聚合所有 views 声明的依赖包与动作，确保依赖闭包满足
-    const roots = [];
-    if (projectRoot) {
-        roots.push(projectRoot);
-    }
-    const aggregatedPackageAllowlist = new Set();
-    const aggregatedActionAllowlist = new Set();
-    for (const v of views.values()) {
-        if (v.policy.packageAllowlist) {
-            for (const pkg of v.policy.packageAllowlist) {
-                aggregatedPackageAllowlist.add(pkg);
-            }
-        }
-        if (v.policy.actionAllowlist) {
-            for (const act of v.policy.actionAllowlist) {
-                aggregatedActionAllowlist.add(act);
-            }
-        }
-    }
-    if (aggregatedPackageAllowlist.size > 0) {
-        for (const pkgId of aggregatedPackageAllowlist) {
-            const r = resolvePackageRoot(pkgId, projectRoot || undefined, customHome);
-            if (r && !roots.includes(r)) {
-                roots.push(r);
-            }
-        }
-    }
-    else if (!projectRoot) {
-        for (const pkg of listLinkedPackages(customHome)) {
-            if (!roots.includes(pkg.path)) {
-                roots.push(pkg.path);
-            }
-        }
-    }
-    if (aggregatedActionAllowlist.size > 0) {
-        for (const actRef of aggregatedActionAllowlist) {
-            try {
-                const parsed = parseActionRef(actRef);
-                if (parsed.packageId) {
-                    const r = resolvePackageRoot(parsed.packageId, projectRoot || undefined, customHome);
-                    if (r && !roots.includes(r)) {
-                        roots.push(r);
-                    }
-                }
-            }
-            catch { }
-        }
-    }
     // 3. 为每个启用 MCP 的视图独立装配 MCP 处理器
     if (options.enableMcp !== false) {
         for (const v of views.values()) {

package/dist/server/types.d.ts

@@ -26,9 +26,9 @@ export interface ServerViewOptions {
     name?: string;
     /** 该视图独立的 Bearer Token 鉴权令牌 */
     token?: string;
-    /** 该视图允许访问执行的 Package ID 白名单列表（为空允许全部） */
+    /** 整包授权列表，与动作授权取并集；空列表不授予权限，独立 * 显式授权全部 */
     packageAllowlist?: string[];
-    /** 该视图允许访问执行的 Action 标识白名单列表（为空允许全部，支持短名或 packageId/actionId） */
+    /** 全限定 packageId/actionId 精确动作授权列表；空列表不授予权限 */
     actionAllowlist?: string[];
     /** 该视图是否开启配置与状态管理路由能力（默认关闭） */
     enableManagement?: boolean;
@@ -45,9 +45,9 @@ export interface EffectiveServerPolicy {
     viewName?: string;
     /** 当前生效的 Bearer Token 鉴权令牌 */
     token?: string;
-    /** 当前生效的 Package ID 白名单列表 */
+    /** 当前生效的整包授权列表，独立 * 代表全部 */
     packageAllowlist?: string[];
-    /** 当前生效的 Action 标识白名单列表 */
+    /** 当前生效的全限定精确动作授权列表，与整包授权取并集 */
     actionAllowlist?: string[];
     /** 当前生效的管理能力开关 */
     enableManagement?: boolean;
@@ -80,9 +80,9 @@ export interface ServerOptions {
     allowInsecureNoAuth?: boolean;
     /** 允许跨域请求的 CORS Origin 白名单列表 */
     corsOrigins?: string[];
-    /** 允许访问执行的 Package ID 白名单列表（为空允许全部） */
+    /** 整包授权列表，与动作授权取并集；空列表不授予权限，独立 * 显式授权全部 */
     packageAllowlist?: string[];
-    /** 允许访问执行的 Action 标识白名单列表（为空允许全部，支持短名或 packageId/actionId） */
+    /** 全限定 packageId/actionId 精确动作授权列表；空列表不授予权限 */
     actionAllowlist?: string[];
     /** 最大允许的请求体字节限制（默认 1MB，防 DoS） */
     maxBodyBytes?: number;

package/dist/service/factory.js

@@ -10,6 +10,7 @@ export async function createActionDock(options = {}) {
         const inMemory = options.inMemory ?? options.runtimeOptions.inMemory;
         const host = await createActionDockHost({
             packages: [options.runtimeOptions],
+            actionBindings: options.actionBindings ?? options.hostOptions?.actionBindings,
             autoLoadCurrentProject: false,
             scanLinkedPackages: false,
             inMemory,

package/dist/service/remote.js

@@ -1,7 +1,8 @@
 import { parseActionRef } from "../catalog/resolve-action.js";
+import { assertConcreteConfigKey } from "../project/config-declarations.js";
 import { ActionDockError, ACTION_CANCELLED, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, TIMEOUT, } from "../errors.js";
 import { createAbortError } from "../ipc/service.js";
-import { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../client/index.js";
+import { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteConfigItem, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../client/index.js";
 import { isRemoteStateKeyNotFound, wrapRemoteError } from "./remote-errors.js";
 import { formatTerminalRunResult, pollRunCompletion } from "./remote-polling.js";
 import { streamRemoteEvents } from "./sse-stream.js";
@@ -449,19 +450,15 @@ export class RemoteActionDockService {
                 config: {
                     async get(packageId, key) {
                         self.assertNotClosed();
+                        assertConcreteConfigKey(key);
                         try {
-                            const list = await self.management.config.list(packageId);
-                            const found = list.find((c) => c.key === key);
-                            if (found) {
-                                return found;
-                            }
-                            return {
-                                key,
-                                configured: false,
-                                secret: false,
-                                source: "default",
-                                value: undefined,
-                            };
+                            const response = await fetchRemoteConfigItem(self.serverUrl, key, self.token, packageId || undefined, {
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                            // 严格单项读取已保证恰一项且键匹配，直接消费，不伪造未命中视图掩盖契约错误。
+                            return response.items[0];
                         }
                         catch (err) {
                             wrapRemoteError(err);
@@ -469,6 +466,7 @@ export class RemoteActionDockService {
                     },
                     async set(packageId, key, value) {
                         self.assertNotClosed();
+                        assertConcreteConfigKey(key);
                         try {
                             await setRemoteConfig(self.serverUrl, key, value, self.token, packageId || undefined, {
                                 allowInsecureHttp: self.allowInsecureHttp,
@@ -482,6 +480,7 @@ export class RemoteActionDockService {
                     },
                     async delete(packageId, key) {
                         self.assertNotClosed();
+                        assertConcreteConfigKey(key);
                         try {
                             const res = await deleteRemoteConfig(self.serverUrl, key, self.token, packageId || undefined, {
                                 allowInsecureHttp: self.allowInsecureHttp,
@@ -502,22 +501,8 @@ export class RemoteActionDockService {
                                 insecure: self.insecure,
                                 dispatcher: self.dispatcher,
                             });
-                            if (Array.isArray(res))
-                                return res;
-                            if (Array.isArray(res?.items))
-                                return res.items;
-                            if (Array.isArray(res?.config))
-                                return res.config;
-                            const values = res?.values || {};
-                            const declared = res?.declared || {};
-                            const defaultSource = packageId === "global" ? "global" : "package";
-                            return Object.entries(values).map(([k, v]) => ({
-                                key: k,
-                                configured: v !== undefined,
-                                secret: Boolean(declared[k]?.secret),
-                                source: defaultSource,
-                                value: v,
-                            }));
+                            // 归一化边界已强校验完整视图，直接消费，不再叠加兜底。
+                            return res.items;
                         }
                         catch (err) {
                             wrapRemoteError(err);

package/dist/service/types.d.ts

@@ -4,6 +4,7 @@ import type { CancelResult, ExecutionTicket } from "../execution/types.js";
 import type { ActionDockHostOptions } from "../host/types.js";
 import type { RuntimePlatform } from "../platform/types.js";
 import type { StateEntry } from "../storage/types.js";
+import type { ActionBindings } from "../invocation/bindings.js";
 import { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED } from "../errors.js";
 /**
  * 公开运行控制选项（RunOptions）。
@@ -29,6 +30,16 @@ export declare const ACTIONDOCK_PROTOCOL_VERSION = "2.0";
  * 服务端/通信协议错误码常量（单一事实源引用自 errors.ts）。
  */
 export { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED };
+/**
+ * 配置来源契约（单一事实源）。
+ * 仅表达当前生效配置值的实际来源，不混入传输方式或作用域显示别名：
+ * override 为运行时固定覆盖或单次调用覆盖，package 为包级持久化，global 为全局持久化，
+ * env 为环境变量命中，default 为清单声明且真实生效的默认值。
+ * 无任何生效值时为 null，不得用 default 伪装。
+ */
+export declare const CONFIG_SOURCES: readonly ["override", "package", "global", "env", "default"];
+/** 配置来源类型；由来源元组派生，枚举值单一事实源。 */
+export type ConfigSource = (typeof CONFIG_SOURCES)[number];
 /**
  * 配置项安全视图契约。
  * 屏蔽敏感配置原文，仅暴露是否已配置、是否为秘密及实际解析来源。
@@ -36,14 +47,16 @@ export { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED };
 export interface ConfigValueView {
     /** 配置项键名 */
     key: string;
-    /** 是否已显式配置或存在有效值 */
+    /** 是否来自显式来源（override/package/global/env）；default 与未配置（source null）均为 false */
     configured: boolean;
-    /** 是否为秘密敏感配置 */
+    /** 声明含敏感字段或实际发生保守隐藏；不代表整个值不可见 */
     secret: boolean;
-    /** 配置值实际解析来源 */
-    source: string;
-    /** 非秘密配置的实际数据值 */
+    /** 配置值实际解析来源；无任何生效值时为 null */
+    source: ConfigSource | null;
+    /** 管理侧安全值；顶层敏感时不提供原值 */
     value?: JsonValue;
+    /** 标准 JSON Pointer 隐藏路径；根为 ""，未发生隐藏时为空 */
+    redactedPaths: string[];
 }
 /**
  * 状态作用域与筛选控制选项。
@@ -254,6 +267,8 @@ export interface ActionDockService {
  * 创建 ActionDock 本地服务选项。
  */
 export interface CreateActionDockOptions {
+    /** 按调用方包覆盖运行时命名绑定，不改变动作引用与 uses 声明。 */
+    actionBindings?: Readonly<Record<string, ActionBindings>>;
     /** 模式类型（可选） */
     type?: "local";
     /** 单包 PackageRuntime 初始化配置 */

package/dist/service/types.js

@@ -7,3 +7,11 @@ export const ACTIONDOCK_PROTOCOL_VERSION = "2.0";
  * 服务端/通信协议错误码常量（单一事实源引用自 errors.ts）。
  */
 export { PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, SERVICE_CLOSED };
+/**
+ * 配置来源契约（单一事实源）。
+ * 仅表达当前生效配置值的实际来源，不混入传输方式或作用域显示别名：
+ * override 为运行时固定覆盖或单次调用覆盖，package 为包级持久化，global 为全局持久化，
+ * env 为环境变量命中，default 为清单声明且真实生效的默认值。
+ * 无任何生效值时为 null，不得用 default 伪装。
+ */
+export const CONFIG_SOURCES = ["override", "package", "global", "env", "default"];

package/dist/storage/mask.d.ts

@@ -1,10 +1,8 @@
+import type { JsonValue } from "@actiondock/sdk";
 import type { ConfigItemDefinition } from "../project/types.js";
 /**
- * 检查指定配置项是否为敏感数据（密码、私钥、Token、密钥等）。
- *
- * 判定逻辑：
- * 严格依据配置项元数据属性判定：若声明了 `secret: true`，直接判定为敏感数据；否则不视为敏感数据。
- * 不进行基于正则或键名的自动探测，由开发者显式配置驱动。
+ * 检查指定配置项是否为敏感数据（顶层 secret: true 或模式中嵌套 secret: true）。
+ * 不进行基于正则或键名的自动探测，调用方若涉及模板应先解析具体声明项。
  *
  * @param _key 配置键名（保留入参以兼容契约）
  * @param declaredItem 项目中声明的配置元数据（可选）
@@ -17,9 +15,38 @@ export declare function isSecretConfigKey(_key?: string, declaredItem?: ConfigIt
  * @returns 掩码脱敏后的安全展示字符串
  */
 export declare function maskSecretValue(value: unknown): string;
+/**
+ * 配置值脱敏安全视图产物。
+ */
+export interface RedactResult {
+    /** 脱敏后的数据值（顶层敏感时为 undefined） */
+    value: JsonValue | undefined;
+    /** 是否包含敏感信息或发生了保守脱敏 */
+    secret: boolean;
+    /** 发生脱敏替换的字段路径集合（标准 JSON Pointer 格式） */
+    redactedPaths: string[];
+}
+/**
+ * 依据单项配置声明对配置值执行纯函数脱敏处理。
+ *
+ * @param value 待脱敏的配置原始数据值
+ * @param item 对应的单项配置定义元数据
+ */
+export declare function redactConfigValue(value: unknown, item?: ConfigItemDefinition): RedactResult;
+/** 根据可信隐藏路径应用幂等掩码，绝不把远端提供的路径本身当成已脱敏的证据。 */
+export declare function redactConfigValueAtPaths(value: unknown, paths: string[]): RedactResult;
+/**
+ * 依据跨包多重声明对配置值执行合并脱敏处理（取脱敏路径并集，祖先路径覆盖子路径）。
+ *
+ * @param value 待脱敏的配置原始数据值
+ * @param items 各相关包分别解析得到的配置声明集合
+ */
+export declare function redactConfigValueForDeclarations(value: unknown, items: ConfigItemDefinition[]): RedactResult;
 /**
  * 对配置定义字典进行脱敏处理：
- * 针对声明为 secret: true 的项，剥离其 default 默认值，不返回敏感默认值。
+ * - 针对外层 secret: true 或嵌套包含敏感字段的项，剥离其 default 默认值，避免敏感默认值泄露或误用于执行；
+ * - 针对模式中敏感节点的 enum 约束列表进行清洗，杜绝约束文本泄露秘密；
+ * - 仅返回安全副本，严禁修改清单原始数据。
  *
  * @param config 声明的配置定义字典
  */