@actiondock/core 2.5.1 → 2.7.0

package/dist/input/utf8.d.ts

@@ -0,0 +1,19 @@
+import type { InputValidationSource } from "./flat-errors.js";
+/**
+ * 校验并严格解码字节序列为合法 UTF-8 字符串。
+ * 使用 TextDecoder("utf-8", { fatal: true }) 拦截非法编码字节并抛出结构化 INVALID_JSON 异常。
+ *
+ * @param bytes 待解码的原始字节数据
+ * @param source 输入校验来源（默认为 full-json-inline）
+ * @returns 解码后的 UTF-8 文本
+ * @throws InputError 当包含非法 UTF-8 字节序列时抛出 INVALID_JSON 异常
+ */
+export declare function decodeUtf8Strict(bytes: Uint8Array | Buffer, source?: InputValidationSource): string;
+/**
+ * 仅剥离输入字符串起始处的恰好一个 U+FEFF BOM。
+ * 若存在双重 BOM（\uFEFF\uFEFF），仅剥离首个，第二个保留给后续 JSON 解析器以触发 SYNTAX_ERROR。
+ *
+ * @param text 原始输入文本
+ * @returns 剥离首个 BOM 后的文本
+ */
+export declare function stripBom(text: string): string;

package/dist/input/utf8.js

@@ -0,0 +1,36 @@
+import { mapInputValidationFailure } from "./validation-mapper.js";
+/**
+ * 校验并严格解码字节序列为合法 UTF-8 字符串。
+ * 使用 TextDecoder("utf-8", { fatal: true }) 拦截非法编码字节并抛出结构化 INVALID_JSON 异常。
+ *
+ * @param bytes 待解码的原始字节数据
+ * @param source 输入校验来源（默认为 full-json-inline）
+ * @returns 解码后的 UTF-8 文本
+ * @throws InputError 当包含非法 UTF-8 字节序列时抛出 INVALID_JSON 异常
+ */
+export function decodeUtf8Strict(bytes, source = "full-json-inline") {
+    try {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        return decoder.decode(bytes);
+    }
+    catch (err) {
+        throw mapInputValidationFailure(source, {
+            valid: false,
+            code: "INVALID_UTF8",
+            reason: `Invalid UTF-8 encoding: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+}
+/**
+ * 仅剥离输入字符串起始处的恰好一个 U+FEFF BOM。
+ * 若存在双重 BOM（\uFEFF\uFEFF），仅剥离首个，第二个保留给后续 JSON 解析器以触发 SYNTAX_ERROR。
+ *
+ * @param text 原始输入文本
+ * @returns 剥离首个 BOM 后的文本
+ */
+export function stripBom(text) {
+    if (text.charCodeAt(0) === 0xfeff) {
+        return text.slice(1);
+    }
+    return text;
+}

package/dist/input/validation-mapper.d.ts

@@ -0,0 +1,27 @@
+import { InputError, type InputValidationSource } from "./flat-errors.js";
+import type { ActionInputValidationResult, JsonValueValidationResult } from "../json/value-validator.js";
+/**
+ * 校验失败结构化输入描述。
+ */
+export type ValidationFailureInput = Exclude<ActionInputValidationResult, {
+    valid: true;
+}> | Exclude<JsonValueValidationResult, {
+    valid: true;
+}> | {
+    valid: false;
+    kind?: "json-value" | "input-policy";
+    code: string;
+    reason: string;
+    path?: string;
+    property?: string;
+    [key: string]: unknown;
+};
+/**
+ * 将校验失败结果根据输入来源映射为统一结构化异常。
+ * 遵循技术设计文档第 19 节 Mapping Table 规范。
+ *
+ * @param source 输入校验来源
+ * @param result 校验失败结果对象
+ * @returns 映射后的结构化输入异常
+ */
+export declare function mapInputValidationFailure(source: InputValidationSource, result: ActionInputValidationResult | JsonValueValidationResult | ValidationFailureInput): InputError;

package/dist/input/validation-mapper.js

@@ -0,0 +1,144 @@
+import { INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, } from "../errors.js";
+import { InputError, invalidJson, invalidJsonLiteral, flatInputLimitExceeded, inputLimitExceeded, inputPolicyViolation, } from "./flat-errors.js";
+/**
+ * 将校验失败结果根据输入来源映射为统一结构化异常。
+ * 遵循技术设计文档第 19 节 Mapping Table 规范。
+ *
+ * @param source 输入校验来源
+ * @param result 校验失败结果对象
+ * @returns 映射后的结构化输入异常
+ */
+export function mapInputValidationFailure(source, result) {
+    const failure = result;
+    const code = failure.code;
+    const reason = failure.reason;
+    const path = failure.path;
+    const isPolicyViolation = failure.kind === "input-policy" || code === "FORBIDDEN_PROPERTY";
+    switch (source) {
+        case "flat-json-literal": {
+            if (code === "SYNTAX_ERROR") {
+                return invalidJsonLiteral(reason || "Invalid JSON literal syntax", {
+                    reason: "SYNTAX_ERROR",
+                    path,
+                });
+            }
+            if (code === "NON_FINITE_NUMBER") {
+                return invalidJsonLiteral(reason || "Non-finite number in JSON literal", {
+                    reason: "NON_FINITE_NUMBER",
+                    path,
+                });
+            }
+            if (code === "MAX_JSON_DEPTH") {
+                return invalidJsonLiteral(reason || "Max JSON depth limit exceeded in JSON literal", {
+                    reason: "MAX_JSON_DEPTH",
+                    path,
+                });
+            }
+            return invalidJsonLiteral(reason || "Invalid JSON literal value", {
+                reason: "INVALID_JSON_VALUE",
+                path,
+            });
+        }
+        case "full-json-inline":
+        case "full-json-file":
+        case "full-json-stdin": {
+            const cliSource = source === "full-json-inline"
+                ? "inline-json"
+                : source === "full-json-file"
+                    ? "file"
+                    : "stdin";
+            if (code === "SYNTAX_ERROR") {
+                return invalidJson(reason || "Invalid JSON syntax", {
+                    reason: "SYNTAX_ERROR",
+                    source: cliSource,
+                    path,
+                });
+            }
+            if (code === "INVALID_UTF8") {
+                return invalidJson(reason || "Invalid UTF-8 encoding in JSON input", {
+                    reason: "INVALID_UTF8",
+                    source: cliSource,
+                    path,
+                });
+            }
+            if (code === "NON_FINITE_NUMBER") {
+                return invalidJson(reason || "Number is non-finite or NaN", {
+                    reason: "NON_FINITE_NUMBER",
+                    source: cliSource,
+                    path,
+                });
+            }
+            if (code === "MAX_JSON_DEPTH") {
+                return invalidJson(reason || "Max JSON depth limit exceeded", {
+                    reason: "MAX_JSON_DEPTH",
+                    source: cliSource,
+                    path,
+                });
+            }
+            return invalidJson(reason || "Invalid JSON value", {
+                reason: "INVALID_JSON_VALUE",
+                source: cliSource,
+                path,
+            });
+        }
+        case "flat-materialized": {
+            if (code === "MAX_JSON_DEPTH") {
+                return flatInputLimitExceeded(reason || "Materialized JSON depth limit exceeded", {
+                    reason: "MAX_MATERIALIZED_JSON_DEPTH",
+                    path,
+                });
+            }
+            if (code === "MAX_MATERIALIZED_BYTES") {
+                return flatInputLimitExceeded(reason || "Materialized input size exceeds limit", {
+                    reason: "MAX_MATERIALIZED_BYTES",
+                    path,
+                });
+            }
+            return flatInputLimitExceeded(reason || "Materialized input validation failed", {
+                reason: "INVALID_JSON_VALUE",
+                path,
+            });
+        }
+        case "cli-pre-target": {
+            if (isPolicyViolation) {
+                const property = failure.property;
+                return inputPolicyViolation(reason || `Forbidden property "${property}" is not allowed in Action input`, {
+                    reason: "FORBIDDEN_PROPERTY",
+                    property,
+                    path,
+                });
+            }
+            if (code === "MAX_JSON_DEPTH") {
+                return inputLimitExceeded(reason || "Max JSON depth limit exceeded", {
+                    reason: "MAX_JSON_DEPTH",
+                    path,
+                });
+            }
+            if (code === "NON_FINITE_NUMBER") {
+                return invalidJson(reason || "Number is non-finite or NaN", {
+                    reason: "NON_FINITE_NUMBER",
+                    path,
+                });
+            }
+            return invalidJson(reason || "Invalid JSON value in Action input", {
+                reason: "INVALID_JSON_VALUE",
+                path,
+            });
+        }
+        case "runtime": {
+            if (isPolicyViolation) {
+                return new InputError(INPUT_VALIDATION_FAILED, reason || "Action input contains forbidden property", [reason || "Forbidden property in input"]);
+            }
+            return new InputError(INPUT_NOT_JSON, reason || "Input is not a valid JSON value", {
+                reason: code,
+                path,
+            });
+        }
+        default: {
+            return new InputError(INPUT_NOT_JSON, reason || "Input validation failed", {
+                reason: code,
+                path,
+            });
+        }
+    }
+}

package/dist/ipc/host.js

@@ -1,4 +1,36 @@
+import { TARGET_CAPABILITY_UNAVAILABLE } from "../target/types.js";
 import { hasIpcSignalMarker, IPC_SIGNAL_MARKER } from "./target.js";
+/**
+ * IPC 通道允许反射调用的目标方法白名单。
+ *
+ * 严格对齐 ActionDockTarget 公共接口方法名集合：白名单之外的方法一律拒绝，
+ * 防止 IPC 消息通道触达任意内部属性或危险方法（如 close 之外的私有能力）。
+ */
+const IPC_ALLOWED_METHODS = new Set([
+    "info",
+    "listPackages",
+    "listActions",
+    "describeAction",
+    "listPlaybooks",
+    "describePlaybook",
+    "runAction",
+    "startAction",
+    "listRuns",
+    "getRun",
+    "cancelRun",
+    "clearRuns",
+    "events",
+    "getConfig",
+    "setConfig",
+    "deleteConfig",
+    "listConfig",
+    "getState",
+    "setState",
+    "deleteState",
+    "listStateKeys",
+    "clearState",
+    "listStateEntries",
+]);
 /**
  * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
  *
@@ -65,6 +97,12 @@ export async function serveParentIpc(target) {
             const callMsg = msg;
             const { id, method, args } = callMsg;
             try {
+                // 白名单校验：仅允许 ActionDockTarget 公共接口方法，阻止任意方法反射调用
+                if (typeof method !== "string" || !IPC_ALLOWED_METHODS.has(method)) {
+                    const err = new Error(`Target method '${method}' is not allowed over IPC (not in ActionDockTarget public interface)`);
+                    err.code = TARGET_CAPABILITY_UNAVAILABLE;
+                    throw err;
+                }
                 const fn = target[method];
                 if (typeof fn !== "function") {
                     throw new Error(`Target method '${method}' not found`);

package/dist/json/index.d.ts

@@ -0,0 +1 @@
+export * from "./value-validator.js";

package/dist/json/index.js

@@ -0,0 +1 @@
+export * from "./value-validator.js";

package/dist/json/value-validator.d.ts

@@ -0,0 +1,88 @@
+import type { JsonValue } from "@actiondock/sdk";
+/** 默认 JSON 最大嵌套深度限制（防止恶意超深结构） */
+export declare const DEFAULT_MAX_JSON_DEPTH = 256;
+/**
+ * JSON 结构校验选项。
+ */
+export interface ValidateJsonOptions {
+    /** 最大允许嵌套深度（默认 256） */
+    maxDepth?: number;
+}
+/**
+ * Action 输入校验选项。
+ */
+export interface ValidateActionInputOptions extends ValidateJsonOptions {
+}
+/**
+ * JSON 值校验错误码类型。
+ */
+export type JsonValueValidationErrorCode = "NON_FINITE_NUMBER" | "MAX_JSON_DEPTH" | "CIRCULAR_REFERENCE" | "UNSUPPORTED_JSON_TYPE" | "INVALID_JSON_OBJECT" | "UNDEFINED_JSON_VALUE";
+/**
+ * Canonical JsonValue 校验结果。
+ */
+export type JsonValueValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    code: JsonValueValidationErrorCode;
+    reason: string;
+    path?: string;
+};
+/**
+ * Action 输入值校验结果（包含策略违规分支）。
+ */
+export type ActionInputValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    kind: "json-value";
+    code: JsonValueValidationErrorCode;
+    reason: string;
+    path?: string;
+} | {
+    valid: false;
+    kind: "input-policy";
+    code: "FORBIDDEN_PROPERTY";
+    property: string;
+    path: string;
+    reason: string;
+};
+/**
+ * 按照 RFC 6901 转义单个 JSON Pointer 路径段。
+ *
+ * @param segment 路径段（属性名或数组索引）
+ * @returns 转义后的路径段
+ */
+export declare function escapeJsonPointerSegment(segment: string | number): string;
+/**
+ * 将路径段追加到基础 RFC 6901 JSON Pointer 路径后。
+ *
+ * @param basePath 基础路径
+ * @param segment 待追加的路径段
+ * @returns 拼接后的 JSON Pointer
+ */
+export declare function appendJsonPointer(basePath: string, segment: string | number): string;
+/**
+ * 校验值是否为合法的 Canonical JSON 兼容结构。
+ *
+ * @param value 待校验的目标值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export declare function validateJsonValue(value: unknown, options?: ValidateJsonOptions): JsonValueValidationResult;
+/**
+ * 校验 Action 输入值是否满足 Canonical JsonValue 规范且符合 ActionDock 安全策略。
+ * 在遍历过程中递归检查是否存在禁止属性（__proto__、constructor、prototype）。
+ *
+ * @param value 待校验的 Action 输入值
+ * @param options 校验配置选项
+ * @returns 校验结果对象
+ */
+export declare function validateActionInputValue(value: unknown, options?: ValidateActionInputOptions): ActionInputValidationResult;
+/**
+ * 断言值必须为合法的 Canonical JSON 兼容结构，若非法则抛出 TypeError。
+ *
+ * @param value 待断言的目标值
+ * @param options 校验配置选项
+ */
+export declare function assertJsonValue(value: unknown, options?: ValidateJsonOptions): asserts value is JsonValue;