spawnfile 0.1.14 → 0.1.17

package/dist/cli/targetConfigPreparedPlan.js

@@ -0,0 +1,74 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { parseTargetPreparedArtifactMappings, } from "./targetDefaultConfig.js";
+export const TARGET_CONFIG_PREPARED_PLAN_VERSION = "spawnfile.target-config-prepared-plan.v1";
+const MAX_PATH_BYTES = 4_096;
+const MAX_PREPARED_PLAN_BYTES = 128 * 1_024;
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+const planPath = (value) => {
+    if (typeof value !== "string" || value.includes("\0")
+        || Buffer.byteLength(value, "utf8") > MAX_PATH_BYTES
+        || !path.isAbsolute(value) || path.normalize(value) !== value) {
+        return fail("Prepared target plan path must be absolute and normalized");
+    }
+    return value;
+};
+export const readTargetConfigPreparedPlan = async (rawPath, evidenceDestination) => {
+    if (rawPath === undefined)
+        return undefined;
+    const resolved = planPath(rawPath);
+    const owner = process.getuid?.();
+    let handle;
+    try {
+        const before = await lstat(resolved);
+        if (!before.isFile() || before.isSymbolicLink() || before.size < 1
+            || before.size > MAX_PREPARED_PLAN_BYTES || (before.mode & 0o777) !== 0o600
+            || owner !== undefined && before.uid !== owner) {
+            return fail("Prepared target plan must be a private bounded regular file");
+        }
+        handle = await open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const bytes = await handle.readFile();
+        const after = await handle.stat();
+        if (after.dev !== before.dev || after.ino !== before.ino || after.size !== bytes.byteLength) {
+            return fail("Prepared target plan changed while it was read");
+        }
+        let source;
+        try {
+            source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        }
+        catch {
+            return fail("Prepared target plan must be UTF-8 JSON");
+        }
+        const parsed = JSON.parse(source);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+            || Object.keys(parsed).sort().join("\0")
+                !== "evidence_destination\0prepared_artifact_mapping\0version") {
+            return fail("Prepared target plan has an invalid shape");
+        }
+        const value = parsed;
+        if (value.version !== TARGET_CONFIG_PREPARED_PLAN_VERSION) {
+            return fail("Prepared target plan version is invalid");
+        }
+        if (value.evidence_destination !== evidenceDestination) {
+            return fail("Prepared target plan evidence destination does not match");
+        }
+        try {
+            return parseTargetPreparedArtifactMappings([value.prepared_artifact_mapping]);
+        }
+        catch {
+            return fail("Prepared target plan artifact mapping is invalid");
+        }
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        return fail("Prepared target plan is unavailable");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};

package/dist/cli/targetConfigResolver.d.ts

@@ -0,0 +1,3 @@
+import { type ResolveTargetConfigDependencies, type ResolveTargetConfigInput, type TargetConfigResolution } from "./targetConfigResolverContracts.js";
+export { createCanonicalTargetConfigBytes, createTargetConfigDigest, createTargetConfigResolutionBytes, STANDARD_WORLD_BASE_IMAGE, TARGET_CONFIG_DIGEST_VERSION, TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION, type ResolveTargetConfigDependencies, type ResolveTargetConfigInput, type TargetConfigResolution, } from "./targetConfigResolverContracts.js";
+export declare const resolveTargetConfig: (input: ResolveTargetConfigInput, dependencies?: ResolveTargetConfigDependencies) => Promise<TargetConfigResolution>;

package/dist/cli/targetConfigResolver.js

@@ -0,0 +1,111 @@
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { createPreparedEvidenceHelperExecutor, parsePreparedEvidenceHelperReceipt, prepareEvidenceExportHelper, } from "../evidenceExportHelper/index.js";
+import { defaultDockerTargetExecFile, resolveDockerContextEndpoint } from "../target/dockerTargetBinding.js";
+import { createTargetConfigDigest, STANDARD_WORLD_BASE_IMAGE, TARGET_CONFIG_RESOLUTION_VERSION, } from "./targetConfigResolverContracts.js";
+import { exactJson, executeDocker, resolveCurrentDockerContext } from "./targetConfigResolverDocker.js";
+import { classifyEndpoint, normalizeArchitecture, parseBaseImage, parseContext, parseDockerCommand, parseTimeout, runtimeFailure, validateEvidenceDestination, validationFailure, } from "./targetConfigResolverValidation.js";
+import { readTargetConfigPreparedPlan } from "./targetConfigPreparedPlan.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION } from "./targetDefaultConfigStdin.js";
+export { createCanonicalTargetConfigBytes, createTargetConfigDigest, createTargetConfigResolutionBytes, STANDARD_WORLD_BASE_IMAGE, TARGET_CONFIG_DIGEST_VERSION, TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION, } from "./targetConfigResolverContracts.js";
+export const resolveTargetConfig = async (input, dependencies = {}) => {
+    const baseImage = parseBaseImage(input.baseImage ?? STANDARD_WORLD_BASE_IMAGE);
+    const dockerCommand = parseDockerCommand(input.dockerCommand ?? "docker");
+    const timeoutMs = parseTimeout(input.timeoutMs ?? 10_000);
+    const evidenceDestination = await validateEvidenceDestination(input.evidenceDestination);
+    const preparedArtifactMappings = await readTargetConfigPreparedPlan(input.preparedPlanPath, evidenceDestination);
+    const execFile = input.execFile ?? defaultDockerTargetExecFile;
+    const contextSelection = input.context === undefined ? "auto-local" : "explicit";
+    const context = input.context === undefined
+        ? await resolveCurrentDockerContext(execFile, dockerCommand, timeoutMs, input.signal)
+        : parseContext(input.context);
+    let endpointValue;
+    try {
+        endpointValue = await resolveDockerContextEndpoint(context, {
+            dockerCommand, execFile, signal: input.signal, timeoutMs,
+        });
+    }
+    catch {
+        return runtimeFailure(`Unable to inspect Docker context "${context}"`);
+    }
+    const endpoint = classifyEndpoint(endpointValue);
+    if (contextSelection === "auto-local" && endpoint.class !== "local") {
+        return validationFailure("Current Docker context is remote; pass --context explicitly to select a remote target");
+    }
+    if (input.prepareEvidenceHelper === true
+        && (contextSelection !== "explicit" || endpoint.class !== "local")) {
+        return validationFailure("Evidence helper preparation requires an explicitly selected local Docker context");
+    }
+    if (input.pull === true && endpoint.class === "remote" && input.allowRemotePull !== true) {
+        return validationFailure("Pulling on a remote Docker context requires --allow-remote-pull");
+    }
+    const infoSource = await executeDocker(execFile, dockerCommand, context, ["info", "--format", "{\"Architecture\":{{json .Architecture}},\"OSType\":{{json .OSType}}}"], timeoutMs, input.signal, "Unable to inspect Docker target platform");
+    const info = exactJson(infoSource, ["Architecture", "OSType"], "Docker target platform is invalid");
+    if (info.OSType !== "linux")
+        return runtimeFailure("Docker target operating system is unsupported");
+    const architecture = normalizeArchitecture(info.Architecture);
+    if (input.pull === true) {
+        await executeDocker(execFile, dockerCommand, context, ["image", "pull", "--quiet", baseImage], timeoutMs, input.signal, "Unable to pull the requested base image");
+    }
+    const imageSource = await executeDocker(execFile, dockerCommand, context, ["image", "inspect", baseImage, "--format",
+        "{\"Architecture\":{{json .Architecture}},\"Id\":{{json .Id}},\"Os\":{{json .Os}}}"], timeoutMs, input.signal, input.pull === true
+        ? "Unable to inspect the pulled base image"
+        : "Base image is unavailable in the Docker context; rerun with --pull to fetch it");
+    const image = exactJson(imageSource, ["Architecture", "Id", "Os"], "Docker base image inspection is invalid");
+    const imageArchitecture = normalizeArchitecture(image.Architecture);
+    if (image.Os !== "linux" || imageArchitecture !== architecture) {
+        return runtimeFailure("Docker base image platform does not match the selected target");
+    }
+    if (typeof image.Id !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(image.Id)) {
+        return runtimeFailure("Docker base image config ID is invalid");
+    }
+    let preparedEvidenceHelper;
+    if (input.prepareEvidenceHelper === true) {
+        try {
+            preparedEvidenceHelper = parsePreparedEvidenceHelperReceipt(await (dependencies.prepareEvidenceExportHelper ?? prepareEvidenceExportHelper)({
+                baseImage,
+                context,
+                executor: input.execFile === undefined
+                    ? createPreparedEvidenceHelperExecutor(dockerCommand)
+                    : async (file, args, options) => {
+                        if (file !== "docker")
+                            throw new Error("unexpected helper executable");
+                        return execFile(dockerCommand, args, {
+                            signal: options.signal,
+                            stdin: options.stdin,
+                            timeout: options.timeout,
+                        });
+                    },
+                privateRoot: path.join(resolveSpawnfileHome(), "target", "evidence-helper"),
+                signal: input.signal,
+                timeoutMs,
+            }));
+        }
+        catch {
+            return runtimeFailure("Evidence helper preparation failed for the selected local target");
+        }
+    }
+    const targetConfig = Object.freeze({
+        context, dockerCommand, evidenceDestination,
+        ...(preparedEvidenceHelper === undefined ? {} : {
+            evidenceHelperBaseImage: baseImage, preparedEvidenceHelper,
+        }),
+        ...(preparedArtifactMappings === undefined ? {} : { preparedArtifactMappings }),
+        timeoutMs,
+        version: TARGET_DEFAULT_CONFIG_STDIN_VERSION,
+    });
+    return Object.freeze({
+        base_image: Object.freeze({
+            config_digest: image.Id, reference: baseImage,
+        }),
+        context_selection: contextSelection,
+        endpoint,
+        platform: Object.freeze({ architecture, os: "linux" }),
+        ...(preparedEvidenceHelper === undefined ? {} : {
+            prepared_evidence_helper: preparedEvidenceHelper,
+        }),
+        target_config: targetConfig,
+        target_config_digest: createTargetConfigDigest(targetConfig),
+        version: TARGET_CONFIG_RESOLUTION_VERSION,
+    });
+};

package/dist/cli/targetConfigResolverCommand.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+import { type ResolveTargetConfigInput, type TargetConfigResolution } from "./targetConfigResolver.js";
+import type { SetTargetCommandExitCode, TargetCommandStreams } from "./targetCommands.js";
+export declare const TARGET_CONFIG_RESOLVER_COMMAND = "resolve_config";
+export type TargetConfigResolver = (input: ResolveTargetConfigInput) => Promise<TargetConfigResolution>;
+export declare const registerTargetConfigResolverCommand: (target: Command, streams: TargetCommandStreams, setExitCode: SetTargetCommandExitCode, resolver?: TargetConfigResolver) => void;

package/dist/cli/targetConfigResolverCommand.js

@@ -0,0 +1,43 @@
+import { errorExitCode, SpawnfileError } from "../shared/index.js";
+import { createTargetConfigResolutionBytes, resolveTargetConfig, } from "./targetConfigResolver.js";
+import { formatCaughtTargetCliError } from "./targetReceiptOutput.js";
+export const TARGET_CONFIG_RESOLVER_COMMAND = "resolve_config";
+const timeout = (value) => {
+    if (!/^[1-9][0-9]{0,5}$/u.test(value)) {
+        throw new SpawnfileError("validation_error", "Target timeout must be an integer from 1 to 120000 milliseconds");
+    }
+    return Number(value);
+};
+export const registerTargetConfigResolverCommand = (target, streams, setExitCode, resolver = resolveTargetConfig) => {
+    target.command(TARGET_CONFIG_RESOLVER_COMMAND)
+        .description("Resolve one explicit Docker context and base image into target configuration")
+        .option("--context <name>", "Explicit named Docker context; omitted accepts only the current local context")
+        .option("--base-image <reference>", "Portable base image reference; defaults to Spawnfile's standard world base")
+        .requiredOption("--evidence-destination <path>", "Absolute private evidence archive destination")
+        .option("--docker-command <command>", "Docker-compatible command", "docker")
+        .option("--prepare-evidence-helper", "Prepare the package-owned evidence helper on an explicitly selected local Docker context")
+        .option("--timeout-ms <milliseconds>", "Bounded Docker command timeout", "10000")
+        .option("--prepared-plan <path>", "Absolute private composed target plan containing one prepared artifact mapping")
+        .option("--pull", "Explicitly pull the base image before inspection")
+        .option("--allow-remote-pull", "Allow --pull to mutate the explicitly named remote Docker context")
+        .action(async (options) => {
+        try {
+            const resolution = await resolver({
+                allowRemotePull: options.allowRemotePull,
+                baseImage: options.baseImage,
+                context: options.context,
+                dockerCommand: options.dockerCommand,
+                evidenceDestination: options.evidenceDestination,
+                prepareEvidenceHelper: options.prepareEvidenceHelper,
+                preparedPlanPath: options.preparedPlan,
+                pull: options.pull,
+                timeoutMs: timeout(options.timeoutMs),
+            });
+            streams.stdout(createTargetConfigResolutionBytes(resolution));
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target configuration resolution failed"));
+            setExitCode(errorExitCode(error));
+        }
+    });
+};

package/dist/cli/targetConfigResolverContracts.d.ts

@@ -0,0 +1,56 @@
+import type { PreparedEvidenceHelperReceipt, PrepareEvidenceHelperInput } from "../evidenceExportHelper/index.js";
+import type { DockerTargetExecFile } from "../target/dockerTarget.js";
+import type { PreparedArtifactMapping } from "./targetDefaultConfig.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION } from "./targetDefaultConfigStdin.js";
+export declare const TARGET_CONFIG_RESOLUTION_VERSION: "spawnfile.target-config-resolution.v1";
+export declare const TARGET_CONFIG_DIGEST_VERSION: "spawnfile.target-config-digest.v1";
+/** Exact version for the strict `resolve_config --prepared-plan` document. */
+export declare const TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION: "spawnfile.target-config-prepared-plan.v1";
+export declare const STANDARD_WORLD_BASE_IMAGE = "node:22-bookworm-slim";
+export interface ResolveTargetConfigInput {
+    readonly allowRemotePull?: boolean;
+    readonly baseImage?: string;
+    readonly context?: string;
+    readonly dockerCommand?: string;
+    readonly evidenceDestination: string;
+    readonly prepareEvidenceHelper?: boolean;
+    readonly execFile?: DockerTargetExecFile;
+    readonly preparedPlanPath?: string;
+    readonly pull?: boolean;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+export interface TargetConfigResolution {
+    readonly base_image: {
+        readonly config_digest: `sha256:${string}`;
+        readonly reference: string;
+    };
+    readonly endpoint: {
+        readonly class: "local" | "remote";
+        readonly transport: "fd" | "http" | "https" | "npipe" | "ssh" | "tcp" | "unix";
+    };
+    readonly context_selection: "auto-local" | "explicit";
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+    readonly prepared_evidence_helper?: PreparedEvidenceHelperReceipt;
+    readonly target_config: {
+        readonly context: string;
+        readonly dockerCommand: string;
+        readonly evidenceDestination: string;
+        readonly evidenceHelperBaseImage?: string;
+        readonly preparedEvidenceHelper?: PreparedEvidenceHelperReceipt;
+        readonly preparedArtifactMappings?: readonly PreparedArtifactMapping[];
+        readonly timeoutMs: number;
+        readonly version: typeof TARGET_DEFAULT_CONFIG_STDIN_VERSION;
+    };
+    readonly target_config_digest: `sha256:${string}`;
+    readonly version: typeof TARGET_CONFIG_RESOLUTION_VERSION;
+}
+export interface ResolveTargetConfigDependencies {
+    readonly prepareEvidenceExportHelper?: (input: PrepareEvidenceHelperInput) => Promise<PreparedEvidenceHelperReceipt>;
+}
+export declare const createCanonicalTargetConfigBytes: (targetConfig: TargetConfigResolution["target_config"]) => string;
+export declare const createTargetConfigDigest: (targetConfig: TargetConfigResolution["target_config"]) => `sha256:${string}`;
+export declare const createTargetConfigResolutionBytes: (resolution: TargetConfigResolution) => string;

package/dist/cli/targetConfigResolverContracts.js

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+import { TARGET_CONFIG_PREPARED_PLAN_VERSION } from "./targetConfigPreparedPlan.js";
+export const TARGET_CONFIG_RESOLUTION_VERSION = "spawnfile.target-config-resolution.v1";
+export const TARGET_CONFIG_DIGEST_VERSION = "spawnfile.target-config-digest.v1";
+/** Exact version for the strict `resolve_config --prepared-plan` document. */
+export const TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION = TARGET_CONFIG_PREPARED_PLAN_VERSION;
+export const STANDARD_WORLD_BASE_IMAGE = "node:22-bookworm-slim";
+const canonicalJson = (value) => {
+    if (value === null)
+        return "null";
+    if (typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("Target configuration is not JSON");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value !== "object")
+        throw new TypeError("Target configuration is not JSON");
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+};
+export const createCanonicalTargetConfigBytes = (targetConfig) => canonicalJson(targetConfig);
+export const createTargetConfigDigest = (targetConfig) => `sha256:${createHash("sha256")
+    .update(`${TARGET_CONFIG_DIGEST_VERSION}\0`, "utf8")
+    .update(createCanonicalTargetConfigBytes(targetConfig), "utf8")
+    .digest("hex")}`;
+export const createTargetConfigResolutionBytes = (resolution) => JSON.stringify(resolution);

package/dist/cli/targetConfigResolverDocker.d.ts

@@ -0,0 +1,4 @@
+import type { DockerTargetExecFile } from "../target/dockerTarget.js";
+export declare const exactJson: (source: string, keys: readonly string[], failureMessage: string) => Record<string, unknown>;
+export declare const executeDocker: (execFile: DockerTargetExecFile, command: string, context: string, args: string[], timeout: number, signal: AbortSignal | undefined, failureMessage: string) => Promise<string>;
+export declare const resolveCurrentDockerContext: (execFile: DockerTargetExecFile, dockerCommand: string, timeoutMs: number, signal: AbortSignal | undefined) => Promise<string>;

package/dist/cli/targetConfigResolverDocker.js

@@ -0,0 +1,47 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseContext, runtimeFailure } from "./targetConfigResolverValidation.js";
+const MAX_DOCKER_OUTPUT_BYTES = 64 * 1_024;
+export const exactJson = (source, keys, failureMessage) => {
+    if (Buffer.byteLength(source, "utf8") > MAX_DOCKER_OUTPUT_BYTES) {
+        return runtimeFailure(failureMessage);
+    }
+    try {
+        const parsed = JSON.parse(source);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+            || Object.keys(parsed).sort().join("\0") !== [...keys].sort().join("\0")) {
+            return runtimeFailure(failureMessage);
+        }
+        return parsed;
+    }
+    catch {
+        return runtimeFailure(failureMessage);
+    }
+};
+export const executeDocker = async (execFile, command, context, args, timeout, signal, failureMessage) => {
+    try {
+        const result = await execFile(command, ["--context", context, ...args], { signal, timeout });
+        if (Buffer.byteLength(result.stdout, "utf8") > MAX_DOCKER_OUTPUT_BYTES) {
+            return runtimeFailure(failureMessage);
+        }
+        return result.stdout;
+    }
+    catch {
+        return runtimeFailure(failureMessage);
+    }
+};
+export const resolveCurrentDockerContext = async (execFile, dockerCommand, timeoutMs, signal) => {
+    try {
+        const result = await execFile(dockerCommand, ["context", "show"], {
+            signal, timeout: timeoutMs,
+        });
+        if (Buffer.byteLength(result.stdout, "utf8") > 4_096) {
+            return runtimeFailure("Current Docker context is invalid");
+        }
+        return parseContext(result.stdout.trim());
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        return runtimeFailure("Unable to resolve the current Docker context");
+    }
+};

package/dist/cli/targetConfigResolverValidation.d.ts

@@ -0,0 +1,10 @@
+import type { TargetConfigResolution } from "./targetConfigResolverContracts.js";
+export declare const validationFailure: (message: string) => never;
+export declare const runtimeFailure: (message: string) => never;
+export declare const parseContext: (value: unknown) => string;
+export declare const parseDockerCommand: (value: unknown) => string;
+export declare const parseTimeout: (value: unknown) => number;
+export declare const parseBaseImage: (value: unknown) => string;
+export declare const validateEvidenceDestination: (value: unknown) => Promise<string>;
+export declare const classifyEndpoint: (endpoint: string) => TargetConfigResolution["endpoint"];
+export declare const normalizeArchitecture: (value: unknown) => "amd64" | "arm64";

package/dist/cli/targetConfigResolverValidation.js

@@ -0,0 +1,94 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { parseDockerBaseImageReference } from "../target/dockerBaseImage.js";
+const CONTEXT = /^[a-z][a-z0-9_-]{0,63}$/u;
+const COMMAND_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const MAX_PATH_BYTES = 4_096;
+export const validationFailure = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+export const runtimeFailure = (message) => {
+    throw new SpawnfileError("runtime_error", message);
+};
+export const parseContext = (value) => typeof value === "string" && CONTEXT.test(value)
+    ? value
+    : validationFailure("Docker context must be an explicit bounded context name");
+export const parseDockerCommand = (value) => {
+    if (typeof value !== "string" || value.includes("\0")
+        || Buffer.byteLength(value, "utf8") > 1_024) {
+        return validationFailure("Docker command is invalid");
+    }
+    if (COMMAND_NAME.test(value))
+        return value;
+    if (path.isAbsolute(value) && path.normalize(value) === value)
+        return value;
+    return validationFailure("Docker command is invalid");
+};
+export const parseTimeout = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= 120_000
+    ? value
+    : validationFailure("Target timeout must be an integer from 1 to 120000 milliseconds");
+export const parseBaseImage = (value) => parseDockerBaseImageReference(value)
+    ?? validationFailure("Base image must be an explicit portable image reference");
+export const validateEvidenceDestination = async (value) => {
+    if (typeof value !== "string" || value.includes("\0")
+        || Buffer.byteLength(value, "utf8") > MAX_PATH_BYTES
+        || !path.isAbsolute(value) || path.normalize(value) !== value) {
+        return validationFailure("Evidence destination must be an absolute normalized path");
+    }
+    const parent = path.dirname(value);
+    const owner = process.getuid?.();
+    try {
+        const parentInfo = await lstat(parent);
+        if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink()
+            || (parentInfo.mode & 0o777) !== 0o700
+            || owner !== undefined && parentInfo.uid !== owner
+            || await realpath(parent) !== parent) {
+            return validationFailure("Evidence destination parent must be a private physical directory");
+        }
+        try {
+            const destinationInfo = await lstat(value);
+            if (!destinationInfo.isFile() || destinationInfo.isSymbolicLink()
+                || (destinationInfo.mode & 0o777) !== 0o600
+                || owner !== undefined && destinationInfo.uid !== owner) {
+                return validationFailure("Existing evidence destination must be a private regular file");
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        return validationFailure("Evidence destination parent is unavailable");
+    }
+    return value;
+};
+export const classifyEndpoint = (endpoint) => {
+    if (Buffer.byteLength(endpoint, "utf8") > 4_096 || /\s/u.test(endpoint)) {
+        return runtimeFailure("Docker context returned an invalid endpoint");
+    }
+    const match = /^(fd|http|https|npipe|ssh|tcp|unix):\/\/.+$/u.exec(endpoint);
+    if (!match)
+        return runtimeFailure("Docker context returned an unsupported endpoint transport");
+    const transport = match[1];
+    return Object.freeze({
+        class: transport === "fd" || transport === "npipe" || transport === "unix"
+            ? "local" : "remote",
+        transport,
+    });
+};
+export const normalizeArchitecture = (value) => {
+    if (typeof value !== "string")
+        return runtimeFailure("Docker architecture is invalid");
+    switch (value.trim()) {
+        case "amd64":
+        case "x64":
+        case "x86_64": return "amd64";
+        case "aarch64":
+        case "arm64": return "arm64";
+        default: return runtimeFailure("Docker architecture is unsupported");
+    }
+};

package/dist/cli/targetDefaultAuthorities.d.ts

@@ -1,4 +1,5 @@
 import { type DockerArtifactIdentityBinding, type DockerArtifactIdentityStore, type DockerArtifactMapping } from "../target/dockerArtifactsProvider.js";
+import type { DockerArtifactExecutor } from "../target/dockerArtifactsProvider.js";
 import { type DockerTargetExecutors } from "../target/dockerCommandExecutor.js";
 import { type TargetSecretVersionAuthorityStore } from "../target/dockerSecretsAuthority.js";
 import { type WorldServiceResolver } from "../target/dockerWorldServiceAuthority.js";
@@ -32,6 +33,7 @@ export interface TargetDefaultAuthorities {
     readonly evidenceExportAuthorityStore: EvidenceExportAuthorityStore;
     readonly executors: DockerTargetExecutors;
     readonly handoffResolver: OrganizationAttachmentResolver;
+    readonly helperExecutor: DockerArtifactExecutor;
     /** Omitted when this invocation cannot export evidence. */
     readonly helperArtifactResolver?: HelperArtifactResolver;
     readonly journals: TargetJournalResolver;

package/dist/cli/targetDefaultAuthorities.js

@@ -1,4 +1,5 @@
 import { initializeDockerArtifactIdentityStore } from "../target/dockerArtifactsProvider.js";
+import { createPreparedEvidenceHelperExecutor } from "../evidenceExportHelper/index.js";
 import { createDockerTargetExecutors } from "../target/dockerCommandExecutor.js";
 import { initializeTargetSecretVersionAuthorityStore } from "../target/dockerSecretsAuthority.js";
 import { parseWorldServiceAuthorization, parseWorldServiceResolution } from "../target/dockerWorldServiceAuthority.js";
@@ -37,6 +38,7 @@ export const initializeTargetDefaultAuthoritySession = async (config) => {
         handoffAuthority = await initializeOrganizationHandoffAuthorityStore();
         const handoffResolver = handoffAuthority.resolver;
         const executors = createDockerTargetExecutors({ dockerCommand: config.dockerCommand });
+        const helperExecutor = createPreparedEvidenceHelperExecutor(config.dockerCommand);
         const preparedBuilder = createDockerTargetLocalBundleBuilder({ context: config.context,
             executor: executors.artifact, timeoutMs: config.timeoutMs });
         const preparedStore = await initializeFilesystemTargetLocalBundleStore(config.paths.containerBundles);
@@ -185,6 +187,7 @@ export const initializeTargetDefaultAuthoritySession = async (config) => {
             evidenceExportAuthorityStore,
             executors,
             handoffResolver,
+            helperExecutor,
             ...(helperArtifactResolver ? { helperArtifactResolver } : {}),
             journals,
             secretAuthorityStore,

package/dist/cli/targetDefaultConfig.d.ts

@@ -1,3 +1,4 @@
+import { type PreparedEvidenceHelperReceipt } from "../evidenceExportHelper/index.js";
 import { type DockerArtifactMapping } from "../target/dockerArtifactsProvider.js";
 export { resolveTargetDefaultJournalRoot } from "../target/journalRoot.js";
 export declare const TARGET_DEFAULT_CONFIG_ERROR = "Target configuration failed";
@@ -14,6 +15,8 @@ export interface TargetDefaultConfigInputs {
     readonly containerBundleStoreRoot?: string;
     readonly context: string;
     readonly dockerCommand: string;
+    readonly evidenceHelperBaseImage?: string;
+    readonly preparedEvidenceHelper?: PreparedEvidenceHelperReceipt;
     readonly evidenceDestination: string;
     readonly helperArtifactManifestDigest?: string;
     /** Local-Daemon prepared images, admitted only by manifest/bundle/policy. */
@@ -39,6 +42,8 @@ export interface TargetDefaultConfig {
     readonly artifactMappings: readonly DockerArtifactMapping[];
     readonly context: string;
     readonly dockerCommand: string;
+    readonly evidenceHelperBaseImage?: string;
+    readonly preparedEvidenceHelper?: PreparedEvidenceHelperReceipt;
     readonly evidenceDestination: string;
     /** Present only when the private evidence-export helper was configured. */
     readonly helperArtifact?: DockerArtifactMapping;
@@ -47,6 +52,7 @@ export interface TargetDefaultConfig {
         readonly artifactIdentities: string;
         readonly attachmentAuthority: string;
         readonly evidenceExport: string;
+        readonly evidenceHelper: string;
         readonly containerBundles: string;
         readonly journals: string;
         readonly root: string;
@@ -63,6 +69,7 @@ export interface TargetDefaultWorldReadinessConfig {
     };
     readonly timeoutMs: number;
 }
+export declare const parseTargetPreparedArtifactMappings: (raw: unknown) => readonly PreparedArtifactMapping[];
 export declare const loadTargetDefaultConfig: (raw: TargetDefaultConfigInputs) => Promise<TargetDefaultConfig>;
 /** Resolves only the paths required by a world-readiness query; performs no I/O. */
 export declare const resolveTargetDefaultWorldReadinessConfig: (raw: TargetDefaultConfigInputs) => TargetDefaultWorldReadinessConfig;