spawnfile 0.1.14 → 0.1.18

package/dist/target/dockerPublicArtifactSnapshot.js

@@ -1,5 +1,6 @@
 import { SpawnfileError } from "../shared/index.js";
-import { createTargetPublicArtifactSnapshot, parseTargetPublicArtifactSnapshotRequest } from "./publicArtifactSnapshot.js";
+import { createPublicArtifactReadCommand, DockerPublicArtifactNotPresentError } from "./dockerCommandExecutor.js";
+import { createTargetPublicArtifactSnapshot, createTargetPublicArtifactSnapshotNotPresent, parseTargetPublicArtifactSnapshotRequest } from "./publicArtifactSnapshot.js";
 import { inspectDockerWorldService, sameWorldServiceValue, worldServiceSpecForBinding } from "./dockerWorldServiceLifecycle.js";
 export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_ERROR = "Target public artifact snapshot failed";
 const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
@@ -29,45 +30,26 @@ const exactBinding = async (request, options) => {
     return binding;
 };
 const readPublicArtifact = async (containerId, request, options) => {
+    let result;
     try {
-        const resolved = await options.contentExecutor("docker", [
-            "--context", options.context,
-            "container", "exec",
+        result = await options.contentExecutor("docker", createPublicArtifactReadCommand({
             containerId,
-            "/usr/bin/readlink",
-            "-e",
-            request.artifact.path
-        ], {
+            context: options.context,
+            path: request.artifact.path
+        }), {
             signal: options.signal,
             timeout: options.timeoutMs
         });
-        if (!resolved || !(resolved.bytes instanceof Uint8Array))
-            return fail();
-        const resolvedPath = new TextDecoder("utf-8", { fatal: true })
-            .decode(resolved.bytes);
-        // Reject the final file and every parent alias. The world may publish only
-        // the exact regular path that its descriptor declared, never a symlink
-        // into private evidence, credentials, or another runtime surface.
-        if (resolvedPath !== `${request.artifact.path}\n`)
-            return fail();
-        const result = await options.contentExecutor("docker", [
-            "--context", options.context,
-            "container", "exec",
-            containerId,
-            "/bin/cat",
-            request.artifact.path
-        ], {
-            signal: options.signal,
-            timeout: options.timeoutMs
-        });
-        if (!result || !(result.bytes instanceof Uint8Array)
-            || result.bytes.byteLength > request.artifact.max_bytes)
-            return fail();
-        return Uint8Array.from(result.bytes);
     }
-    catch {
+    catch (error) {
+        if (error instanceof DockerPublicArtifactNotPresentError)
+            return null;
         return fail();
     }
+    if (!result || !(result.bytes instanceof Uint8Array)
+        || result.bytes.byteLength > request.artifact.max_bytes)
+        return fail();
+    return Uint8Array.from(result.bytes);
 };
 class DockerPublicArtifactSnapshotReader {
     #options;
@@ -93,7 +75,9 @@ class DockerPublicArtifactSnapshotReader {
         if (!after || after.containerId !== before.containerId
             || after.status !== "running")
             return fail();
-        return createTargetPublicArtifactSnapshot({ content, request });
+        return content === null
+            ? createTargetPublicArtifactSnapshotNotPresent(request)
+            : createTargetPublicArtifactSnapshot({ content, request });
     }
 }
 export const createDockerPublicArtifactSnapshotReader = (options) => new DockerPublicArtifactSnapshotReader(options);

package/dist/target/dockerTarget.d.ts

@@ -12,6 +12,7 @@ export type DockerDeploymentTarget = {
 };
 export type DockerTargetExecFile = (file: string, args: string[], options: {
     signal?: AbortSignal;
+    stdin?: Uint8Array;
     timeout: number;
 }) => Promise<{
     stderr: string;

package/dist/target/dockerTargetBinding.d.ts

@@ -1,7 +1,6 @@
-import { execFile as execFileCallback } from "node:child_process";
 import { type SelectedTargetReceipt } from "./contracts.js";
 import type { ResolveDockerDeploymentTargetOptions, SelectTargetOptions } from "./dockerTarget.js";
-export declare const defaultDockerTargetExecFile: typeof execFileCallback.__promisify__;
+export { defaultDockerTargetExecFile } from "./dockerTargetExecFile.js";
 /** Private owner-only endpoint binding. Never export this module through the target barrel. */
 export interface ResolvedSelectedTargetBinding {
     readonly endpoint: string;

package/dist/target/dockerTargetBinding.js

@@ -1,10 +1,9 @@
-import { execFile as execFileCallback } from "node:child_process";
 import { createHash } from "node:crypto";
-import { promisify } from "node:util";
 import { SpawnfileError } from "../shared/index.js";
 import { SELECTED_TARGET_VERSION, parseOpaqueTargetHandle, parseSelectedTargetReceipt } from "./contracts.js";
 import { createEndpointFingerprint } from "./dockerEndpointFingerprint.js";
-export const defaultDockerTargetExecFile = promisify(execFileCallback);
+import { defaultDockerTargetExecFile } from "./dockerTargetExecFile.js";
+export { defaultDockerTargetExecFile } from "./dockerTargetExecFile.js";
 const TARGET_SELECTION_ERROR = "Target selection failed";
 const DOCKER_CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
 const MAX_RAW_EXECUTOR_STDOUT_BYTES = 4_096;
@@ -51,7 +50,8 @@ const selectTargetContext = (input) => {
 const isDockerContextEndpoint = (endpoint) => endpoint.length <= 4_096
     && /^(?:npipe|ssh|tcp|unix|fd|http|https):\/\/[^\s]+$/u.test(endpoint);
 const selectTargetOptions = (input) => {
-    if (input.dockerCommand !== undefined && (typeof input.dockerCommand !== "string" || input.dockerCommand.length === 0 || input.dockerCommand.length > 128)) {
+    if (input.dockerCommand !== undefined && (typeof input.dockerCommand !== "string" || input.dockerCommand.length === 0
+        || input.dockerCommand.includes("\0") || Buffer.byteLength(input.dockerCommand, "utf8") > 1_024)) {
         return selectionFailure("validation_error");
     }
     if (input.timeoutMs !== undefined && (typeof input.timeoutMs !== "number" || !Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > 120_000)) {

package/dist/target/dockerTargetExecFile.d.ts

@@ -0,0 +1,19 @@
+import type { DockerTargetExecFile } from "./dockerTarget.js";
+export type DockerTargetExecutionFailureKind = "aborted" | "cleanup_failed" | "failed" | "timeout";
+export declare class DockerTargetExecutionError extends Error {
+    readonly kind: DockerTargetExecutionFailureKind;
+    constructor(kind: DockerTargetExecutionFailureKind);
+}
+export declare class DockerTargetCommandFailure extends DockerTargetExecutionError {
+    readonly code: number;
+    readonly stderr: string;
+    readonly stdoutBytes: number;
+    constructor(code: number, stderr: string, stdoutBytes: number);
+}
+/**
+ * Docker target probe/build transport with exact stdin and bounded tree teardown.
+ * POSIX children lead a private process group so timeout/abort cannot strand a
+ * buildx descendant that inherited the CLI's stdio handles.
+ */
+export declare const createBoundedDockerTargetExecFile: () => DockerTargetExecFile;
+export declare const defaultDockerTargetExecFile: DockerTargetExecFile;

package/dist/target/dockerTargetExecFile.js

@@ -0,0 +1,194 @@
+import { spawn } from "node:child_process";
+const ERROR = "Docker target command failed";
+const OUTPUT_CAP = 65_536;
+const TERM_GRACE_MS = 50;
+const KILL_GRACE_MS = 250;
+export class DockerTargetExecutionError extends Error {
+    kind;
+    constructor(kind) {
+        super(ERROR);
+        this.name = "DockerTargetExecutionError";
+        this.kind = kind;
+    }
+}
+export class DockerTargetCommandFailure extends DockerTargetExecutionError {
+    code;
+    stderr;
+    stdoutBytes;
+    constructor(code, stderr, stdoutBytes) {
+        super("failed");
+        this.name = "DockerTargetCommandFailure";
+        this.code = code;
+        this.stderr = stderr;
+        this.stdoutBytes = stdoutBytes;
+    }
+}
+const decode = (chunks) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new DockerTargetExecutionError("failed");
+    }
+};
+/**
+ * Docker target probe/build transport with exact stdin and bounded tree teardown.
+ * POSIX children lead a private process group so timeout/abort cannot strand a
+ * buildx descendant that inherited the CLI's stdio handles.
+ */
+export const createBoundedDockerTargetExecFile = () => (file, args, options) => {
+    if (typeof file !== "string" || file.length < 1 || file.includes("\0")
+        || !Array.isArray(args) || args.some((arg) => typeof arg !== "string" || arg.includes("\0"))
+        || !options || !Number.isSafeInteger(options.timeout) || options.timeout < 1
+        || options.timeout > 120_000
+        || options.signal !== undefined && !(options.signal instanceof AbortSignal)
+        || options.stdin !== undefined && !(options.stdin instanceof Uint8Array)) {
+        return Promise.reject(new DockerTargetExecutionError("failed"));
+    }
+    if (options.signal?.aborted) {
+        return Promise.reject(new DockerTargetExecutionError("aborted"));
+    }
+    return new Promise((resolve, reject) => {
+        const grouped = process.platform !== "win32";
+        let child;
+        try {
+            child = spawn(file, args, {
+                detached: grouped,
+                shell: false,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch {
+            reject(new DockerTargetExecutionError("failed"));
+            return;
+        }
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let terminal;
+        let settled = false;
+        let termTimer;
+        let killTimer;
+        const groupAbsent = () => {
+            if (!grouped || !child.pid)
+                return false;
+            try {
+                process.kill(-child.pid, 0);
+                return false;
+            }
+            catch (error) {
+                return error.code === "ESRCH";
+            }
+        };
+        const signalTree = (signal) => {
+            try {
+                if (grouped && child.pid)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch { /* only a later ESRCH liveness probe proves quiescence */ }
+        };
+        const destroyPipes = () => {
+            child.stdin.on("error", () => undefined);
+            child.stdout.on("error", () => undefined);
+            child.stderr.on("error", () => undefined);
+            child.stdin.destroy();
+            child.stdout.destroy();
+            child.stderr.destroy();
+        };
+        const cleanup = () => {
+            clearTimeout(timeoutTimer);
+            if (termTimer)
+                clearTimeout(termTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            options.signal?.removeEventListener("abort", onAbort);
+        };
+        const finish = (error, unresolved = false) => {
+            if (settled || !unresolved && !groupAbsent())
+                return;
+            settled = true;
+            cleanup();
+            destroyPipes();
+            reject(error);
+        };
+        const terminate = (kind) => {
+            if (terminal || settled)
+                return;
+            terminal = new DockerTargetExecutionError(kind);
+            signalTree("SIGTERM");
+            termTimer = setTimeout(() => {
+                signalTree("SIGKILL");
+                destroyPipes();
+                const started = Date.now();
+                const poll = () => {
+                    if (!terminal || settled)
+                        return;
+                    if (groupAbsent()) {
+                        finish(terminal);
+                        return;
+                    }
+                    signalTree("SIGKILL");
+                    if (Date.now() - started >= KILL_GRACE_MS) {
+                        finish(new DockerTargetExecutionError("cleanup_failed"), true);
+                        return;
+                    }
+                    killTimer = setTimeout(poll, 10);
+                };
+                poll();
+            }, TERM_GRACE_MS);
+        };
+        const append = (target, chunk, output) => {
+            const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (output === "stdout")
+                stdoutBytes += value.byteLength;
+            else
+                stderrBytes += value.byteLength;
+            if (stdoutBytes > OUTPUT_CAP || stderrBytes > OUTPUT_CAP) {
+                terminate("failed");
+                return;
+            }
+            target.push(Buffer.from(value));
+        };
+        function onAbort() { terminate("aborted"); }
+        child.stdout.on("data", (chunk) => append(stdout, chunk, "stdout"));
+        child.stderr.on("data", (chunk) => append(stderr, chunk, "stderr"));
+        child.stdin.on("error", () => terminate("failed"));
+        child.on("error", () => terminate("failed"));
+        child.on("close", (code) => {
+            if (terminal || settled)
+                return;
+            settled = true;
+            cleanup();
+            try {
+                const stderrText = decode(stderr);
+                const stdoutText = decode(stdout);
+                if (code !== 0) {
+                    reject(new DockerTargetCommandFailure(code ?? -1, stderrText, Buffer.byteLength(stdoutText, "utf8")));
+                    return;
+                }
+                resolve({ stderr: stderrText, stdout: stdoutText });
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const timeoutTimer = setTimeout(() => terminate("timeout"), options.timeout);
+        if (options.signal?.aborted) {
+            terminate("aborted");
+            return;
+        }
+        try {
+            const input = options.stdin === undefined ? undefined
+                : Buffer.from(options.stdin.buffer, options.stdin.byteOffset, options.stdin.byteLength);
+            child.stdin.end(input);
+        }
+        catch {
+            terminate("failed");
+        }
+    });
+};
+export const defaultDockerTargetExecFile = createBoundedDockerTargetExecFile();

package/dist/target/dockerWorldServiceProvider.d.ts

@@ -5,6 +5,10 @@ export declare const WORLD_RUNTIME_TMPFS: Readonly<{
     path: "/tmp";
     options: "rw,noexec,nosuid,nodev,size=1m,mode=1777";
 }>;
+export declare const WORLD_PUBLIC_ARTIFACT_TMPFS: Readonly<{
+    path: "/tmp/spawnfile-public";
+    options: "rw,noexec,nosuid,nodev,size=1m,mode=1777";
+}>;
 export type DockerWorldServiceFailureKind = "collision" | "not_found";
 export interface DockerWorldServiceExecutor {
     (file: string, args: string[], options: {

package/dist/target/dockerWorldServiceProvider.js

@@ -9,6 +9,16 @@ export const WORLD_RUNTIME_TMPFS = Object.freeze({
     path: "/tmp",
     options: "rw,noexec,nosuid,nodev,size=1m,mode=1777"
 });
+/*
+ * A distinct mount point is a confinement boundary, not merely a convenient
+ * directory.  The public-artifact reader opens one direct child with
+ * O_NOFOLLOW; this mount prevents that child from being hard-linked or
+ * replaced with a path from the world root, secrets, or evidence mounts.
+ */
+export const WORLD_PUBLIC_ARTIFACT_TMPFS = Object.freeze({
+    path: "/tmp/spawnfile-public",
+    options: "rw,noexec,nosuid,nodev,size=1m,mode=1777"
+});
 const MAX_OUTPUT_BYTES = 32_768;
 const MAX_NAME_LENGTH = 63;
 const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
@@ -183,6 +193,7 @@ export const createDockerWorldServiceSpec = (input) => {
             "--cap-drop", "ALL", "--security-opt", "no-new-privileges=true",
             "--ipc", "none", "--cgroupns", "private",
             "--tmpfs", `${WORLD_RUNTIME_TMPFS.path}:${WORLD_RUNTIME_TMPFS.options}`,
+            "--tmpfs", `${WORLD_PUBLIC_ARTIFACT_TMPFS.path}:${WORLD_PUBLIC_ARTIFACT_TMPFS.options}`,
             ...labelArgs,
             "--mount", `type=volume,src=${evidence.name},dst=${evidenceMountPath},volume-nocopy`,
             "--mount", `type=volume,src=${secrets.name},dst=${WORLD_SECRETS_PATH},readonly,volume-nocopy`,
@@ -304,8 +315,9 @@ export const parseExpectedDockerWorldService = (stdout, spec) => {
         && value.PidMode === "" && value.IpcMode === "none" && value.UTSMode === ""
         && value.UsernsMode === "" && value.CgroupnsMode === "private"
         && exactRecord(value.Tmpfs)
-        && exactKeys(value.Tmpfs, [WORLD_RUNTIME_TMPFS.path])
+        && exactKeys(value.Tmpfs, [WORLD_RUNTIME_TMPFS.path, WORLD_PUBLIC_ARTIFACT_TMPFS.path])
         && value.Tmpfs[WORLD_RUNTIME_TMPFS.path] === WORLD_RUNTIME_TMPFS.options
+        && value.Tmpfs[WORLD_PUBLIC_ARTIFACT_TMPFS.path] === WORLD_PUBLIC_ARTIFACT_TMPFS.options
         && value.ReadonlyRootfs === true
         && JSON.stringify(value.SecurityOpt) === JSON.stringify(["no-new-privileges=true"])
         && value.LogType === "none" && value.RestartPolicyName === "no"

package/dist/target/evidenceExport.d.ts

@@ -16,7 +16,9 @@ export interface EvidenceExportOperationsOptions {
     readonly context: unknown;
     readonly executor: DockerResourceExecutor;
     readonly exportExecutor: DockerEvidenceExportExecutor;
-    readonly helperArtifactBundle: unknown;
+    readonly helperArtifactBundle?: unknown;
+    /** Spawnfile-owned local config identity. Never a public provider field. */
+    readonly localHelper?: unknown;
     readonly helperArtifactManifestDigest: unknown;
     readonly helperArtifactContract: unknown;
     readonly artifactIdentityStore: DockerArtifactIdentityStore;

package/dist/target/evidenceExport.js

@@ -35,14 +35,21 @@ const options = (raw) => {
         return fail();
     const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : 10_000;
     try {
+        if (typeof raw.helperArtifactManifestDigest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(raw.helperArtifactManifestDigest) || raw.helperArtifactContract !== EVIDENCE_EXPORT_HELPER_CONTRACT)
+            return fail();
+        const source = raw.localHelper;
+        const localHelper = source === undefined ? undefined : createEvidenceExportHelper({ artifactManifestDigest: source.artifactManifestDigest, imageDigest: source.image_digest, imageReference: source.image_reference, resultHandle: source.result_handle });
+        if (localHelper) {
+            if (raw.helperArtifactBundle !== undefined || localHelper.artifactManifestDigest !== raw.helperArtifactManifestDigest)
+                return fail();
+            return { authorityStore: raw.authorityStore, context: raw.context, executor: raw.executor, exportExecutor: raw.exportExecutor, localHelper, helperArtifactManifestDigest: raw.helperArtifactManifestDigest, helperArtifactContract: EVIDENCE_EXPORT_HELPER_CONTRACT, artifactIdentityStore: raw.artifactIdentityStore, journal: raw.journal, signal: raw.signal, timeoutMs, testHooks: raw.testHooks };
+        }
         const rawBundle = raw.helperArtifactBundle;
         if (!rawBundle || typeof rawBundle !== "object" || Array.isArray(rawBundle) || Object.keys(rawBundle).sort().join("\0") !== "operation_handle\0request_digest\0result_handle")
             return fail();
         const bundle = rawBundle;
         const helperArtifactBundle = Object.freeze({ operationHandle: parseOpaqueTargetHandle(bundle.operation_handle), requestDigest: (() => { if (typeof bundle.request_digest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(bundle.request_digest))
                 return fail(); return bundle.request_digest; })(), resultHandle: parseOpaqueTargetHandle(bundle.result_handle) });
-        if (typeof raw.helperArtifactManifestDigest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(raw.helperArtifactManifestDigest) || raw.helperArtifactContract !== EVIDENCE_EXPORT_HELPER_CONTRACT)
-            return fail();
         return { authorityStore: raw.authorityStore, context: raw.context, executor: raw.executor, exportExecutor: raw.exportExecutor, helperArtifactBundle, helperArtifactManifestDigest: raw.helperArtifactManifestDigest, helperArtifactContract: EVIDENCE_EXPORT_HELPER_CONTRACT, artifactIdentityStore: raw.artifactIdentityStore, journal: raw.journal, signal: raw.signal, timeoutMs, testHooks: raw.testHooks };
     }
     catch {
@@ -78,7 +85,9 @@ const inspectAuthority = async (authority, input) => {
         return fail();
 };
 const helperFor = async (value, input) => {
-    const bundle = input.helperArtifactBundle;
+    if (input.localHelper)
+        return input.localHelper;
+    const bundle = input.helperArtifactBundle ?? fail();
     const binding = await input.artifactIdentityStore.resolveOperation(bundle.operationHandle, bundle.requestDigest);
     const journal = await input.journal.read();
     const completed = binding ? await input.journal.resolveCompletedReceipt({ operationHandle: binding.operationHandle, requestDigest: binding.requestDigest }) : null;

package/dist/target/evidenceExportOperationsTestKit.js

@@ -1,7 +1,7 @@
 import { mkdtemp, realpath, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { EVIDENCE_EXPORT_MOUNT, EVIDENCE_EXPORT_HELPER_CMD, EVIDENCE_EXPORT_HELPER_CONTRACT, EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL, EVIDENCE_EXPORT_HELPER_ENTRYPOINT, EVIDENCE_EXPORT_HELPER_USER, createEvidenceExportHelper, parseEvidenceVolumeAuthority } from "./evidenceExportProvider.js";
+import { EVIDENCE_EXPORT_MOUNT, EVIDENCE_EXPORT_HELPER_CMD, EVIDENCE_EXPORT_HELPER_CONTRACT, EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL, EVIDENCE_EXPORT_HELPER_ENTRYPOINT, EVIDENCE_EXPORT_HELPER_ENV, EVIDENCE_EXPORT_HELPER_USER, createEvidenceExportHelper, parseEvidenceVolumeAuthority } from "./evidenceExportProvider.js";
 import { createDockerArtifactSpec, initializeDockerArtifactIdentityStore } from "./dockerArtifactsProvider.js";
 import { initializeEvidenceExportAuthorityStore } from "./evidenceExportStore.js";
 import { createDockerResourceSpec } from "./dockerResourcesProvider.js";
@@ -92,7 +92,7 @@ export const runLifecycleExport = async (input = {}) => {
                 Entrypoint: EVIDENCE_EXPORT_HELPER_ENTRYPOINT,
                 Cmd: EVIDENCE_EXPORT_HELPER_CMD,
                 Labels: { [EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL]: "v1" },
-                Env: null,
+                Env: ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
                 ExposedPorts: null,
                 Healthcheck: null,
                 User: EVIDENCE_EXPORT_HELPER_USER,
@@ -268,7 +268,7 @@ export const helperProjection = (args, volumeName, imageLabels, mutate) => {
         Config: {
             Entrypoint: EVIDENCE_EXPORT_HELPER_ENTRYPOINT,
             Cmd: EVIDENCE_EXPORT_HELPER_CMD,
-            Env: null,
+            Env: EVIDENCE_EXPORT_HELPER_ENV,
             ExposedPorts: null,
             Healthcheck: null,
             Image: image,

package/dist/target/evidenceExportProvider.d.ts

@@ -6,6 +6,8 @@ export declare const EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION: "v1";
 export declare const EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL: "spawnfile.target.evidence-export.helper-contract";
 export declare const EVIDENCE_EXPORT_HELPER_ENTRYPOINT: readonly string[];
 export declare const EVIDENCE_EXPORT_HELPER_CMD: readonly string[];
+export declare const EVIDENCE_EXPORT_HELPER_PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export declare const EVIDENCE_EXPORT_HELPER_ENV: readonly string[];
 export declare const EVIDENCE_EXPORT_HELPER_USER: "65534:65534";
 export interface DockerEvidenceExportExecutor {
     (file: string, args: readonly string[], options: {

package/dist/target/evidenceExportProvider.js

@@ -10,6 +10,10 @@ export const EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION = "v1";
 export const EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL = "spawnfile.target.evidence-export.helper-contract";
 export const EVIDENCE_EXPORT_HELPER_ENTRYPOINT = Object.freeze(["/bin/spawnfile-export-helper"]);
 export const EVIDENCE_EXPORT_HELPER_CMD = Object.freeze([]);
+export const EVIDENCE_EXPORT_HELPER_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export const EVIDENCE_EXPORT_HELPER_ENV = Object.freeze([
+    `PATH=${EVIDENCE_EXPORT_HELPER_PATH}`,
+]);
 export const EVIDENCE_EXPORT_HELPER_USER = "65534:65534";
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const NAME = /^spfe_[a-f0-9]{58}$/u;
@@ -37,8 +41,11 @@ const json = (raw) => { if (!utf8(raw))
 catch {
     return fail();
 } };
+const exactHelperEnv = (raw) => Array.isArray(raw)
+    && raw.length === 1 && raw[0] === EVIDENCE_EXPORT_HELPER_ENV[0];
 export const createEvidenceExportHelper = (raw) => {
-    if (typeof raw.artifactManifestDigest !== "string" || !DIGEST.test(raw.artifactManifestDigest) || typeof raw.imageDigest !== "string" || !DIGEST.test(raw.imageDigest) || typeof raw.imageReference !== "string" || !isImmutableDockerImageReference(raw.imageReference) || !raw.imageReference.endsWith(`@${raw.imageDigest}`))
+    const localConfig = raw.imageReference === raw.imageDigest;
+    if (typeof raw.artifactManifestDigest !== "string" || !DIGEST.test(raw.artifactManifestDigest) || typeof raw.imageDigest !== "string" || !DIGEST.test(raw.imageDigest) || typeof raw.imageReference !== "string" || !localConfig && (!isImmutableDockerImageReference(raw.imageReference) || !raw.imageReference.endsWith(`@${raw.imageDigest}`)))
         return fail();
     return Object.freeze({ artifactManifestDigest: raw.artifactManifestDigest, image_digest: raw.imageDigest, image_reference: raw.imageReference, result_handle: parseOpaqueTargetHandle(raw.resultHandle) });
 };
@@ -91,7 +98,8 @@ export const parseEvidenceExportImageInspection = (stdout, helper) => {
     if (!Array.isArray(value) || value.length !== 1 || !exact(value[0], ["Config", "RepoDigests"]))
         return fail();
     const image = value[0];
-    if (!Array.isArray(image.RepoDigests) || image.RepoDigests.length < 1 || image.RepoDigests.length > 32 || image.RepoDigests.some((value) => !isImmutableDockerImageReference(value)))
+    const localConfig = prepared.image_reference === prepared.image_digest;
+    if (!localConfig && (!Array.isArray(image.RepoDigests) || image.RepoDigests.length < 1 || image.RepoDigests.length > 32 || image.RepoDigests.some((value) => !isImmutableDockerImageReference(value))))
         return fail();
     if (!exact(image.Config, ["Cmd", "Entrypoint", "Env", "ExposedPorts", "Healthcheck", "Labels", "User", "Volumes"]))
         return fail();
@@ -105,9 +113,10 @@ export const parseEvidenceExportImageInspection = (stdout, helper) => {
         return fail();
     if (config.User !== EVIDENCE_EXPORT_HELPER_USER)
         return fail();
-    if (config.Env !== null || config.ExposedPorts !== null || config.Healthcheck !== null || config.Volumes !== null)
+    if (!exactHelperEnv(config.Env)
+        || config.ExposedPorts !== null || config.Healthcheck !== null || config.Volumes !== null)
         return fail();
-    if (!image.RepoDigests.includes(prepared.image_reference))
+    if (!localConfig && !image.RepoDigests.includes(prepared.image_reference))
         return fail();
     return { labels: Object.freeze({ ...labels }) };
 };
@@ -140,7 +149,8 @@ export const isExpectedEvidenceExportHelper = (stdout, spec) => {
         return item.Name === `/${spec.containerName}` && config.Image === spec.imageReference
             && JSON.stringify(config.Entrypoint) === JSON.stringify(EVIDENCE_EXPORT_HELPER_ENTRYPOINT)
             && (cmd === null || (Array.isArray(cmd) && cmd.length === 0))
-            && config.Env === null && config.ExposedPorts === null && config.Healthcheck === null && config.Volumes === null
+            && exactHelperEnv(config.Env)
+            && config.ExposedPorts === null && config.Healthcheck === null && config.Volumes === null
             && config.User === EVIDENCE_EXPORT_HELPER_USER
             && exact(config.Labels, Object.keys(expectedLabels))
             && Object.entries(expectedLabels).every(([key, value]) => config.Labels !== null && config.Labels[key] === value)

package/dist/target/publicArtifactSnapshot.d.ts

@@ -1,8 +1,10 @@
 import { z } from "zod";
 export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION: "spawnfile.target-public-artifact-snapshot.request.v1";
 export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION: "spawnfile.target-public-artifact-snapshot.v1";
+export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION: "spawnfile.target-public-artifact-snapshot.not-present.v1";
 export declare const TARGET_PUBLIC_ARTIFACT_ROOT: "/tmp/spawnfile-public";
 export declare const MAX_TARGET_PUBLIC_ARTIFACT_BYTES = 131072;
+export declare const isTargetPublicArtifactPath: (value: unknown) => value is string;
 export declare const targetPublicArtifactSnapshotRequestSchema: z.ZodObject<{
     artifact: z.ZodObject<{
         id: z.ZodString;
@@ -29,13 +31,42 @@ export declare const targetPublicArtifactSnapshotSchema: z.ZodObject<{
     size_bytes: z.ZodNumber;
     version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.v1">;
 }, z.core.$strict>;
+export declare const targetPublicArtifactSnapshotNotPresentSchema: z.ZodObject<{
+    artifact_id: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    status: z.ZodLiteral<"not_present">;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.not-present.v1">;
+}, z.core.$strict>;
+export declare const targetPublicArtifactSnapshotResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    artifact_id: z.ZodString;
+    content_base64: z.ZodString;
+    content_digest: z.ZodString;
+    media_type: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    size_bytes: z.ZodNumber;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.v1">;
+}, z.core.$strict>, z.ZodObject<{
+    artifact_id: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    status: z.ZodLiteral<"not_present">;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.not-present.v1">;
+}, z.core.$strict>]>;
 export type TargetPublicArtifactSnapshotRequest = z.infer<typeof targetPublicArtifactSnapshotRequestSchema>;
 export type TargetPublicArtifactSnapshot = z.infer<typeof targetPublicArtifactSnapshotSchema>;
+export type TargetPublicArtifactSnapshotNotPresent = z.infer<typeof targetPublicArtifactSnapshotNotPresentSchema>;
+export type TargetPublicArtifactSnapshotResult = z.infer<typeof targetPublicArtifactSnapshotResultSchema>;
 export declare const parseTargetPublicArtifactSnapshotRequest: (raw: unknown) => TargetPublicArtifactSnapshotRequest;
 export declare const parseTargetPublicArtifactSnapshot: (raw: unknown) => TargetPublicArtifactSnapshot;
+export declare const parseTargetPublicArtifactSnapshotNotPresent: (raw: unknown) => TargetPublicArtifactSnapshotNotPresent;
+export declare const parseTargetPublicArtifactSnapshotResult: (raw: unknown) => TargetPublicArtifactSnapshotResult;
 export declare const createTargetPublicArtifactSnapshotRequestDigest: (raw: unknown) => `sha256:${string}`;
 export declare const createTargetPublicArtifactSnapshot: (input: {
     readonly content: Uint8Array;
     readonly request: TargetPublicArtifactSnapshotRequest;
 }) => TargetPublicArtifactSnapshot;
+export declare const createTargetPublicArtifactSnapshotNotPresent: (raw: unknown) => TargetPublicArtifactSnapshotNotPresent;
 export declare const createCanonicalTargetPublicArtifactSnapshotBytes: (raw: unknown) => string;
+export declare const createCanonicalTargetPublicArtifactSnapshotResultBytes: (raw: unknown) => string;