spawnfile 0.1.13 → 0.1.17

package/dist/evidenceExportHelper/preparedAuthority.js

@@ -0,0 +1,228 @@
+import { createHash, randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, realpath, unlink } from "node:fs/promises";
+import path from "node:path";
+import { types as nodeTypes } from "node:util";
+import { parseOpaqueTargetHandle } from "../target/contracts.js";
+export const PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION = "spawnfile.target-evidence-export-helper.prepared.v1";
+export const PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION = "spawnfile.target-evidence-export-helper.private.v3";
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const HANDLE = /^opaque_[a-f0-9]{64}$/u;
+const CONTEXT = /^[a-z][a-z0-9_-]{0,63}$/u;
+const ERROR = "Prepared evidence-export helper failed";
+const OWNER = process.getuid?.();
+const fail = () => { throw new Error(ERROR); };
+const hash = (domain, value) => `sha256:${createHash("sha256").update(`spawnfile.evidence-helper.${domain}.v1\0`).update(value).digest("hex")}`;
+const exact = (raw, keys) => raw !== null && typeof raw === "object" && !Array.isArray(raw)
+    && !nodeTypes.isProxy(raw) && Object.getPrototypeOf(raw) === Object.prototype
+    && Reflect.ownKeys(raw).every((key) => typeof key === "string")
+    && Object.keys(raw).sort().join("\0") === [...keys].sort().join("\0")
+    && Object.values(Object.getOwnPropertyDescriptors(raw)).every((item) => item.enumerable && "value" in item);
+const digest = (raw) => typeof raw === "string" && DIGEST.test(raw) ? raw : fail();
+const text = (raw, maximum) => typeof raw === "string" && raw === raw.trim() && !raw.includes("\0")
+    && Buffer.byteLength(raw, "utf8") > 0 && Buffer.byteLength(raw, "utf8") <= maximum ? raw : fail();
+export const parsePreparedEvidenceHelperReceipt = (raw) => {
+    if (!exact(raw, ["digest", "handle", "version"])
+        || raw.version !== PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION
+        || typeof raw.handle !== "string" || !HANDLE.test(raw.handle))
+        return fail();
+    return Object.freeze({ digest: digest(raw.digest), handle: parseOpaqueTargetHandle(raw.handle),
+        version: PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION });
+};
+export const createPreparedEvidenceHelperReceiptBytes = (raw) => JSON.stringify(parsePreparedEvidenceHelperReceipt(raw));
+export const pendingDigest = (raw) => hash("pending", createPreparedEvidenceHelperPendingBytes(raw));
+export const createPreparedEvidenceHelperReceipt = (input) => {
+    const config = digest(input.configDigest);
+    const pending = digest(input.pendingDigest);
+    const handle = parseOpaqueTargetHandle(`opaque_${hash("prepared-handle", `${pending}\0${config}`).slice(7)}`);
+    return Object.freeze({ digest: hash("prepared-receipt", `${PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION}\0${handle}\0${pending}\0${config}`),
+        handle, version: PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION });
+};
+export const parsePreparedEvidenceHelperPendingRecord = (raw) => {
+    if (!exact(raw, ["base_config_digest", "base_image", "context", "daemon_digest", "endpoint_digest",
+        "platform", "recipe_digest", "version"])
+        || raw.version !== PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION
+        || !exact(raw.platform, ["architecture", "os"])
+        || raw.platform.os !== "linux"
+        || raw.platform.architecture !== "amd64" && raw.platform.architecture !== "arm64")
+        return fail();
+    const context = text(raw.context, 64);
+    if (!CONTEXT.test(context))
+        return fail();
+    return Object.freeze({ base_config_digest: digest(raw.base_config_digest), base_image: text(raw.base_image, 512),
+        context, daemon_digest: digest(raw.daemon_digest), endpoint_digest: digest(raw.endpoint_digest),
+        platform: Object.freeze({ architecture: raw.platform.architecture, os: "linux" }),
+        recipe_digest: digest(raw.recipe_digest),
+        version: PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION });
+};
+export const createPreparedEvidenceHelperPendingBytes = (raw) => JSON.stringify(parsePreparedEvidenceHelperPendingRecord(raw));
+export const parsePreparedEvidenceHelperCompletionRecord = (raw) => {
+    if (!exact(raw, ["accepted_image_config_digest", "pending_digest", "receipt", "version"])
+        || raw.version !== PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION)
+        return fail();
+    const accepted = digest(raw.accepted_image_config_digest);
+    const pending = digest(raw.pending_digest);
+    const receipt = parsePreparedEvidenceHelperReceipt(raw.receipt);
+    const expected = createPreparedEvidenceHelperReceipt({ configDigest: accepted, pendingDigest: pending });
+    if (receipt.handle !== expected.handle || receipt.digest !== expected.digest)
+        return fail();
+    return Object.freeze({ accepted_image_config_digest: accepted, pending_digest: pending, receipt,
+        version: PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION });
+};
+export const createPreparedEvidenceHelperCompletionBytes = (raw) => JSON.stringify(parsePreparedEvidenceHelperCompletionRecord(raw));
+export const createPreparedEvidenceHelperKey = (input) => hash("private-record", [input.context, input.endpointDigest, input.daemonDigest,
+    input.platform.os, input.platform.architecture, input.baseConfigDigest, input.recipeDigest].join("\0")).slice(7);
+export const newPreparedEvidenceHelperPendingRecord = (input) => parsePreparedEvidenceHelperPendingRecord({ ...input, version: PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION });
+export const newPreparedEvidenceHelperCompletionRecord = (pending, configDigest) => {
+    const pendingRecord = parsePreparedEvidenceHelperPendingRecord(pending);
+    const pendingHash = pendingDigest(pendingRecord);
+    const accepted = digest(configDigest);
+    return parsePreparedEvidenceHelperCompletionRecord({ accepted_image_config_digest: accepted, pending_digest: pendingHash,
+        receipt: createPreparedEvidenceHelperReceipt({ configDigest: accepted, pendingDigest: pendingHash }),
+        version: PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION });
+};
+const root = async (raw) => {
+    if (typeof raw !== "string" || !path.isAbsolute(raw) || path.normalize(raw) !== raw
+        || raw === path.parse(raw).root)
+        return fail();
+    let existed = true;
+    try {
+        await lstat(raw);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            return fail();
+        existed = false;
+    }
+    try {
+        await mkdir(raw, { mode: 0o700, recursive: true });
+    }
+    catch {
+        return fail();
+    }
+    const info = await lstat(raw).catch(fail);
+    if (!info.isDirectory() || info.isSymbolicLink() || (info.mode & 0o777) !== 0o700
+        || OWNER !== undefined && info.uid !== OWNER || await realpath(raw).catch(fail) !== raw)
+        return fail();
+    await syncRoot(raw);
+    if (!existed)
+        await syncRoot(path.dirname(raw));
+    return raw;
+};
+const readFile = async (file, links = [1]) => {
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        return fail();
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || !links.includes(info.nlink) || info.size < 1 || info.size > 16_384
+            || (info.mode & 0o777) !== 0o600 || OWNER !== undefined && info.uid !== OWNER)
+            return fail();
+        return await handle.readFile({ encoding: "utf8" });
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+const syncRoot = async (directory) => {
+    const handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW).catch(fail);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+/** Immutable, fsynced pending/completion authority records keyed by exact target facts. */
+export class PreparedEvidenceHelperAuthorityStore {
+    #root;
+    constructor(privateRoot) { this.#root = privateRoot; }
+    async load(key) {
+        const pending = await this.#read(key, "pending", parsePreparedEvidenceHelperPendingRecord);
+        if (!pending)
+            return null;
+        // A writer fsyncs before and after publication.  A racing reader may observe
+        // the link before that writer reaches its directory fsync, so it must make
+        // the accepted transaction durable before proceeding to a Docker mutation.
+        await syncRoot(this.#root);
+        const completion = await this.#read(key, "complete", parsePreparedEvidenceHelperCompletionRecord);
+        if (completion)
+            await syncRoot(this.#root);
+        if (completion && completion.pending_digest !== pendingDigest(pending))
+            return fail();
+        return Object.freeze({ completion, pending });
+    }
+    async reserve(key, raw) {
+        const record = parsePreparedEvidenceHelperPendingRecord(raw);
+        return this.#publish(key, "pending", record, createPreparedEvidenceHelperPendingBytes, parsePreparedEvidenceHelperPendingRecord);
+    }
+    async complete(key, raw) {
+        const pending = await this.#read(key, "pending", parsePreparedEvidenceHelperPendingRecord);
+        if (!pending)
+            return fail();
+        const record = parsePreparedEvidenceHelperCompletionRecord(raw);
+        if (record.pending_digest !== pendingDigest(pending))
+            return fail();
+        return this.#publish(key, "complete", record, createPreparedEvidenceHelperCompletionBytes, parsePreparedEvidenceHelperCompletionRecord);
+    }
+    async #read(key, phase, parser) {
+        if (!/^[a-f0-9]{64}$/u.test(key))
+            return fail();
+        const file = path.join(this.#root, `${key}.${phase}.json`);
+        const complete = await readFile(file, [1, 2]);
+        if (complete === null)
+            return null;
+        try {
+            return parser(JSON.parse(complete));
+        }
+        catch {
+            return fail();
+        }
+    }
+    async #publish(key, phase, raw, bytesFor, parser) {
+        if (!/^[a-f0-9]{64}$/u.test(key))
+            return fail();
+        const bytes = bytesFor(raw);
+        const existing = await this.#read(key, phase, parser);
+        if (existing) {
+            await syncRoot(this.#root);
+            return bytesFor(existing) === bytes ? existing : fail();
+        }
+        const file = path.join(this.#root, `${key}.${phase}.json`);
+        const stage = path.join(this.#root, `.${key}.${phase}.${randomBytes(12).toString("hex")}.stage`);
+        let handle;
+        try {
+            handle = await open(stage, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            await handle.writeFile(bytes, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await syncRoot(this.#root);
+            await link(stage, file);
+            await syncRoot(this.#root);
+            await unlink(stage);
+            await syncRoot(this.#root);
+        }
+        catch {
+            await handle?.close().catch(() => undefined);
+            const published = await this.#read(key, phase, parser);
+            if (!published || bytesFor(published) !== bytes)
+                return fail();
+            await syncRoot(this.#root);
+        }
+        finally {
+            await unlink(stage).catch(() => undefined);
+        }
+        return (await this.#read(key, phase, parser)) ?? fail();
+    }
+}
+export const initializePreparedEvidenceHelperAuthorityStore = async (privateRoot) => new PreparedEvidenceHelperAuthorityStore(await root(privateRoot));

package/dist/evidenceExportHelper/preparedBuilder.d.ts

@@ -0,0 +1,10 @@
+import { type PreparedEvidenceHelperReceipt } from "./preparedAuthority.js";
+import type { PrepareEvidenceHelperInput } from "./preparedBuilderTypes.js";
+export type { PrepareEvidenceHelperInput } from "./preparedBuilderTypes.js";
+/** Re-attests a completion-bound local config identity or rebuilds an absent exact config. */
+export declare const prepareEvidenceExportHelper: (input: PrepareEvidenceHelperInput) => Promise<PreparedEvidenceHelperReceipt>;
+/** Private target lowering resolves the config digest only after receipt-correlated reattestation. */
+export declare const resolvePreparedEvidenceHelperImage: (input: PrepareEvidenceHelperInput, receipt: PreparedEvidenceHelperReceipt) => Promise<{
+    readonly configDigest: `sha256:${string}`;
+    readonly imageReference: string;
+}>;

package/dist/evidenceExportHelper/preparedBuilder.js

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+import { parseDockerBaseImageReference } from "../target/dockerBaseImage.js";
+import { DockerArtifactProviderError, } from "../target/dockerArtifactsProvider.js";
+import { EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL, EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION, EVIDENCE_EXPORT_HELPER_ENTRYPOINT, EVIDENCE_EXPORT_HELPER_ENV, EVIDENCE_EXPORT_HELPER_USER, } from "../target/evidenceExportProvider.js";
+import { createPreparedEvidenceHelperKey, initializePreparedEvidenceHelperAuthorityStore, newPreparedEvidenceHelperCompletionRecord, newPreparedEvidenceHelperPendingRecord, } from "./preparedAuthority.js";
+import { loadLocalEvidenceHelperRecipe } from "./recipe.js";
+const ERROR = "Prepared evidence-export helper failed";
+const CONTEXT = /^[a-z][a-z0-9_-]{0,63}$/u;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const BUILD_ID = /^(sha256:[a-f0-9]{64})(?:\r?\n)?$/u;
+const MAX_OUTPUT = 65_536;
+const BASE_FORMAT = "[{\"Architecture\":{{json .Architecture}},\"Id\":{{json .Id}},\"Os\":{{json .Os}}}]";
+const IMAGE_FORMAT = "[{\"Architecture\":{{json .Architecture}},\"Config\":{\"Cmd\":{{json (index .Config \"Cmd\")}},\"Entrypoint\":{{json (index .Config \"Entrypoint\")}},\"Env\":{{json (index .Config \"Env\")}},\"ExposedPorts\":{{json (index .Config \"ExposedPorts\")}},\"Healthcheck\":{{json (index .Config \"Healthcheck\")}},\"Labels\":{{json (index .Config \"Labels\")}},\"User\":{{json (index .Config \"User\")}},\"Volumes\":{{json (index .Config \"Volumes\")}}},\"Id\":{{json .Id}},\"Os\":{{json .Os}}}]";
+const live = new Map();
+const fail = () => { throw new Error(ERROR); };
+const hash = (domain, value) => `sha256:${createHash("sha256").update(`spawnfile.evidence-helper.${domain}.v1\0`).update(value).digest("hex")}`;
+const exact = (raw, keys) => raw !== null && typeof raw === "object" && !Array.isArray(raw)
+    && Object.getPrototypeOf(raw) === Object.prototype
+    && Object.keys(raw).sort().join("\0") === [...keys].sort().join("\0");
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const digest = (raw) => typeof raw === "string" && DIGEST.test(raw) ? raw : fail();
+const timeout = (raw) => raw === undefined ? 120_000
+    : typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1 && raw <= 120_000 ? raw : fail();
+const parse = (raw) => { try {
+    return JSON.parse(raw);
+}
+catch {
+    return fail();
+} };
+const hook = async (value) => { if (value)
+    await value(); };
+const execution = (input, value) => {
+    if (!CONTEXT.test(input.context) || typeof input.executor !== "function")
+        return fail();
+    const run = async (args, stdin) => {
+        const result = await input.executor("docker", ["--context", input.context, ...args], {
+            ...(input.signal ? { signal: input.signal } : {}), timeout: value, ...(stdin ? { stdin } : {}),
+        });
+        if (!result || typeof result.stdout !== "string" || typeof result.stderr !== "string"
+            || Buffer.byteLength(result.stdout, "utf8") > MAX_OUTPUT || Buffer.byteLength(result.stderr, "utf8") > MAX_OUTPUT)
+            return fail();
+        return result.stdout;
+    };
+    return Object.freeze({ run });
+};
+const localFacts = async (run, context, baseImage) => {
+    const endpoint = parse((await run([
+        "context", "inspect", context, "--format", "{{json .Endpoints.docker.Host}}",
+    ])).trim());
+    if (typeof endpoint !== "string" || !/^(?:fd|npipe|unix):\/\/[^\s]+$/u.test(endpoint))
+        return fail();
+    const daemon = parse(await run(["info", "--format", "{\"Architecture\":{{json .Architecture}},\"DockerRootDir\":{{json .DockerRootDir}},\"OSType\":{{json .OSType}},\"ServerVersion\":{{json .ServerVersion}}}"]));
+    if (!exact(daemon, ["Architecture", "DockerRootDir", "OSType", "ServerVersion"])
+        || daemon.OSType !== "linux" || typeof daemon.DockerRootDir !== "string" || typeof daemon.ServerVersion !== "string")
+        return fail();
+    const architecture = ["amd64", "x64", "x86_64"].includes(daemon.Architecture) ? "amd64"
+        : ["arm64", "aarch64"].includes(daemon.Architecture) ? "arm64" : fail();
+    const image = parse(await run(["image", "inspect", baseImage, "--format", BASE_FORMAT]));
+    if (!Array.isArray(image) || image.length !== 1 || !exact(image[0], ["Architecture", "Id", "Os"])
+        || image[0].Os !== "linux" || image[0].Architecture !== architecture)
+        return fail();
+    return Object.freeze({ baseConfig: digest(image[0].Id), daemonDigest: hash("daemon", JSON.stringify(daemon)),
+        endpointDigest: hash("endpoint", endpoint), platform: Object.freeze({ architecture, os: "linux" }) });
+};
+const inspectHelper = async (run, reference, facts) => {
+    const image = parse(await run(["image", "inspect", reference, "--format", IMAGE_FORMAT]));
+    if (!Array.isArray(image) || image.length !== 1 || !exact(image[0], ["Architecture", "Config", "Id", "Os"])
+        || image[0].Architecture !== facts.platform.architecture || image[0].Os !== "linux"
+        || !exact(image[0].Config, ["Cmd", "Entrypoint", "Env", "ExposedPorts", "Healthcheck", "Labels", "User", "Volumes"]))
+        return fail();
+    const config = image[0].Config;
+    if (!same(config.Entrypoint, EVIDENCE_EXPORT_HELPER_ENTRYPOINT)
+        || config.Cmd !== null && !same(config.Cmd, []) || !same(config.Env, EVIDENCE_EXPORT_HELPER_ENV)
+        || config.ExposedPorts !== null
+        || config.Healthcheck !== null || config.Volumes !== null || config.User !== EVIDENCE_EXPORT_HELPER_USER
+        || !exact(config.Labels, [EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL])
+        || config.Labels[EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL] !== EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION)
+        return fail();
+    return digest(image[0].Id);
+};
+const inspectMaybe = async (run, reference, facts) => {
+    try {
+        return await inspectHelper(run, reference, facts);
+    }
+    catch (error) {
+        if (error instanceof DockerArtifactProviderError && error.kind === "image_not_found")
+            return null;
+        throw error;
+    }
+};
+const matching = (record, baseImage, facts, recipe) => record.base_image === baseImage && record.base_config_digest === facts.baseConfig && record.daemon_digest === facts.daemonDigest
+    && record.endpoint_digest === facts.endpointDigest && same(record.platform, facts.platform)
+    && record.recipe_digest === recipe.recipeDigest;
+const build = async (input, run, facts, recipe) => {
+    await hook(input.testHooks?.beforeBuild);
+    const output = await run(["build", "--quiet", "--pull=false", "--network=none", "--platform",
+        `${facts.platform.os}/${facts.platform.architecture}`, "--build-arg", `SPAWNFILE_HELPER_BASE=${facts.baseConfig}`,
+        "-"], recipe.context);
+    const produced = BUILD_ID.exec(output)?.[1];
+    if (!produced)
+        return fail();
+    await hook(input.testHooks?.afterBuild);
+    // Docker's quiet build result is the image config ID produced by this exact
+    // invocation. Re-attest that immutable ID, never a mutable tag.
+    const inspected = await inspectHelper(run, produced, facts);
+    return inspected === produced ? inspected : fail();
+};
+const receiptOwner = async (input, baseImage, facts, recipe, key, run) => {
+    const store = await initializePreparedEvidenceHelperAuthorityStore(input.privateRoot);
+    await hook(input.testHooks?.beforeReserve);
+    const pending = await store.reserve(key, newPreparedEvidenceHelperPendingRecord({
+        base_config_digest: facts.baseConfig, base_image: baseImage, context: input.context,
+        daemon_digest: facts.daemonDigest, endpoint_digest: facts.endpointDigest, platform: facts.platform,
+        recipe_digest: recipe.recipeDigest
+    }));
+    await hook(input.testHooks?.afterReserve);
+    if (!matching(pending, baseImage, facts, recipe))
+        return fail();
+    const authority = await store.load(key);
+    if (!authority)
+        return fail();
+    if (authority.completion) {
+        let observed = await inspectMaybe(run, authority.completion.accepted_image_config_digest, facts);
+        if (observed === null)
+            observed = await build(input, run, facts, recipe);
+        if (observed !== authority.completion.accepted_image_config_digest)
+            return fail();
+        await hook(input.testHooks?.beforeReceipt);
+        return authority.completion.receipt;
+    }
+    const produced = await build(input, run, facts, recipe);
+    await hook(input.testHooks?.beforeComplete);
+    const completion = await store.complete(key, newPreparedEvidenceHelperCompletionRecord(pending, produced));
+    await hook(input.testHooks?.afterComplete);
+    if (completion.accepted_image_config_digest !== produced)
+        return fail();
+    await hook(input.testHooks?.beforeReceipt);
+    return completion.receipt;
+};
+/** Re-attests a completion-bound local config identity or rebuilds an absent exact config. */
+export const prepareEvidenceExportHelper = async (input) => {
+    const targetTimeout = timeout(input.timeoutMs);
+    const baseImage = parseDockerBaseImageReference(input.baseImage) ?? fail();
+    const run = execution(input, targetTimeout).run;
+    const recipe = await loadLocalEvidenceHelperRecipe();
+    const facts = await localFacts(run, input.context, baseImage);
+    const key = createPreparedEvidenceHelperKey({ baseConfigDigest: facts.baseConfig, context: input.context,
+        daemonDigest: facts.daemonDigest, endpointDigest: facts.endpointDigest, platform: facts.platform,
+        recipeDigest: recipe.recipeDigest });
+    const mapKey = `${input.privateRoot}\0${key}`;
+    const joined = live.get(mapKey);
+    if (joined)
+        return joined;
+    const promise = receiptOwner(input, baseImage, facts, recipe, key, run);
+    live.set(mapKey, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        if (live.get(mapKey) === promise)
+            live.delete(mapKey);
+    }
+};
+/** Private target lowering resolves the config digest only after receipt-correlated reattestation. */
+export const resolvePreparedEvidenceHelperImage = async (input, receipt) => {
+    const actual = await prepareEvidenceExportHelper(input);
+    if (actual.handle !== receipt.handle || actual.digest !== receipt.digest)
+        return fail();
+    const baseImage = parseDockerBaseImageReference(input.baseImage) ?? fail();
+    const run = execution(input, timeout(input.timeoutMs)).run;
+    const facts = await localFacts(run, input.context, baseImage);
+    const recipe = await loadLocalEvidenceHelperRecipe();
+    const store = await initializePreparedEvidenceHelperAuthorityStore(input.privateRoot);
+    const key = createPreparedEvidenceHelperKey({ baseConfigDigest: facts.baseConfig, context: input.context,
+        daemonDigest: facts.daemonDigest, endpointDigest: facts.endpointDigest, platform: facts.platform,
+        recipeDigest: recipe.recipeDigest });
+    const authority = await store.load(key);
+    if (!authority?.completion || authority.completion.receipt.handle !== receipt.handle
+        || authority.completion.receipt.digest !== receipt.digest)
+        return fail();
+    return Object.freeze({ configDigest: authority.completion.accepted_image_config_digest,
+        imageReference: authority.completion.accepted_image_config_digest });
+};

package/dist/evidenceExportHelper/preparedBuilderTypes.d.ts

@@ -0,0 +1,19 @@
+import type { DockerArtifactExecutor } from "../target/dockerArtifactsProvider.js";
+export interface PrepareEvidenceHelperInput {
+    readonly baseImage: string;
+    readonly context: string;
+    readonly executor: DockerArtifactExecutor;
+    readonly privateRoot: string;
+    readonly signal?: AbortSignal;
+    /** Test-only fault injection at durable/mutation/receipt boundaries. */
+    readonly testHooks?: {
+        readonly afterBuild?: () => Promise<void> | void;
+        readonly afterComplete?: () => Promise<void> | void;
+        readonly afterReserve?: () => Promise<void> | void;
+        readonly beforeBuild?: () => Promise<void> | void;
+        readonly beforeComplete?: () => Promise<void> | void;
+        readonly beforeReceipt?: () => Promise<void> | void;
+        readonly beforeReserve?: () => Promise<void> | void;
+    };
+    readonly timeoutMs?: number;
+}

package/dist/evidenceExportHelper/preparedBuilderTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/evidenceExportHelper/recipe.d.ts

@@ -0,0 +1,7 @@
+export declare const LOCAL_EVIDENCE_HELPER_RECIPE_VERSION: "spawnfile.local-evidence-export-helper.recipe.v1";
+export interface LocalEvidenceHelperRecipe {
+    readonly artifactManifestDigest: `sha256:${string}`;
+    readonly context: Uint8Array;
+    readonly recipeDigest: `sha256:${string}`;
+}
+export declare const loadLocalEvidenceHelperRecipe: () => Promise<LocalEvidenceHelperRecipe>;

package/dist/evidenceExportHelper/recipe.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { EVIDENCE_EXPORT_HELPER_PATH } from "../target/evidenceExportProvider.js";
+export const LOCAL_EVIDENCE_HELPER_RECIPE_VERSION = "spawnfile.local-evidence-export-helper.recipe.v1";
+const BLOCK = 512;
+const MAX_SOURCE_BYTES = 65_536;
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const fail = () => { throw new Error("Local evidence-export helper recipe failed"); };
+const octal = (value, width) => {
+    const raw = value.toString(8);
+    if (!Number.isSafeInteger(value) || value < 0 || raw.length > width - 1)
+        return fail();
+    return Buffer.from(`${raw.padStart(width - 1, "0")}\0`, "ascii");
+};
+const checksum = (header) => {
+    header.fill(0x20, 148, 156);
+    let sum = 0;
+    for (const byte of header)
+        sum += byte;
+    if (sum > 0o777777)
+        return fail();
+    header.set(Buffer.from(`${sum.toString(8).padStart(6, "0")}\0 `, "ascii"), 148);
+};
+const archive = (entries) => {
+    const output = [];
+    for (const entry of [...entries].sort((left, right) => Buffer.compare(Buffer.from(left.path), Buffer.from(right.path)))) {
+        const name = Buffer.from(entry.path, "utf8");
+        if (name.byteLength < 1 || name.byteLength > 100
+            || entry.mode !== 0o444 && entry.mode !== 0o555)
+            return fail();
+        const header = Buffer.alloc(BLOCK);
+        header.set(name, 0);
+        header.set(octal(entry.mode, 8), 100);
+        header.set(octal(0, 8), 108);
+        header.set(octal(0, 8), 116);
+        header.set(octal(entry.bytes.byteLength, 12), 124);
+        header.set(octal(0, 12), 136);
+        header[156] = 48;
+        header.set(Buffer.from("ustar\0", "ascii"), 257);
+        header.set(Buffer.from("00", "ascii"), 263);
+        header.set(octal(0, 8), 329);
+        header.set(octal(0, 8), 337);
+        checksum(header);
+        output.push(header, Buffer.from(entry.bytes));
+        const padding = (BLOCK - entry.bytes.byteLength % BLOCK) % BLOCK;
+        if (padding > 0)
+            output.push(Buffer.alloc(padding));
+    }
+    output.push(Buffer.alloc(BLOCK), Buffer.alloc(BLOCK));
+    return Buffer.concat(output);
+};
+const dockerfile = Buffer.from([
+    "ARG SPAWNFILE_HELPER_BASE",
+    "FROM ${SPAWNFILE_HELPER_BASE} AS runtime",
+    "FROM scratch",
+    "COPY --from=runtime / /",
+    "COPY helperProgram.mjs /bin/spawnfile-export-helper",
+    "LABEL spawnfile.target.evidence-export.helper-contract=\"v1\"",
+    `ENV PATH=${EVIDENCE_EXPORT_HELPER_PATH}`,
+    "USER 65534:65534",
+    "ENTRYPOINT [\"/bin/spawnfile-export-helper\"]",
+    "CMD []",
+    "",
+].join("\n"), "utf8");
+const digest = (domain, bytes) => `sha256:${createHash("sha256")
+    .update(`spawnfile.local-evidence-export-helper.${domain}.v1\0`, "utf8")
+    .update(bytes)
+    .digest("hex")}`;
+export const loadLocalEvidenceHelperRecipe = async () => {
+    const source = await readFile(new URL("./helperProgram.mjs", import.meta.url));
+    if (source.byteLength < 1 || source.byteLength > MAX_SOURCE_BYTES
+        || !source.subarray(0, 22).toString("utf8").startsWith("#!/usr/local/bin/node"))
+        return fail();
+    const context = archive([
+        { bytes: dockerfile, mode: 0o444, path: "Dockerfile" },
+        { bytes: source, mode: 0o555, path: "helperProgram.mjs" },
+    ]);
+    const recipeDigest = digest("recipe", context);
+    const artifactManifestDigest = digest("artifact-manifest", recipeDigest);
+    if (!DIGEST.test(recipeDigest) || !DIGEST.test(artifactManifestDigest))
+        return fail();
+    return Object.freeze({ artifactManifestDigest, context, recipeDigest });
+};

package/dist/filesystem/io.d.ts

@@ -3,9 +3,11 @@ export interface CopyDirectoryOptions {
 }
 export declare const copyDirectory: (sourcePath: string, destinationPath: string, options?: CopyDirectoryOptions) => Promise<void>;
 export declare const ensureDirectory: (directoryPath: string) => Promise<void>;
+export declare const ensurePrivateDirectory: (directoryPath: string) => Promise<void>;
 export declare const fileExists: (filePath: string) => Promise<boolean>;
 export declare const isSymlink: (filePath: string) => Promise<boolean>;
 export declare const readUtf8File: (filePath: string) => Promise<string>;
 export declare const ensureGitignoreEntry: (directoryPath: string, entry: string) => Promise<boolean>;
 export declare const removeDirectory: (directoryPath: string) => Promise<void>;
 export declare const writeUtf8File: (filePath: string, content: string) => Promise<void>;
+export declare const writePrivateUtf8File: (filePath: string, content: string) => Promise<void>;

package/dist/filesystem/io.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { cp, mkdir, lstat, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, cp, mkdir, lstat, open, readFile, rm, stat, writeFile } from "node:fs/promises";
 export const copyDirectory = async (sourcePath, destinationPath, options = {}) => {
     await cp(sourcePath, destinationPath, {
         filter: options.filter,
@@ -10,6 +10,10 @@ export const copyDirectory = async (sourcePath, destinationPath, options = {}) =
 export const ensureDirectory = async (directoryPath) => {
     await mkdir(directoryPath, { recursive: true });
 };
+export const ensurePrivateDirectory = async (directoryPath) => {
+    await mkdir(directoryPath, { recursive: true, mode: 0o700 });
+    await chmod(directoryPath, 0o700);
+};
 export const fileExists = async (filePath) => {
     try {
         await stat(filePath);
@@ -55,3 +59,14 @@ export const removeDirectory = async (directoryPath) => {
 export const writeUtf8File = async (filePath, content) => {
     await writeFile(filePath, content, "utf8");
 };
+export const writePrivateUtf8File = async (filePath, content) => {
+    const handle = await open(filePath, "w", 0o600);
+    try {
+        // Creation mode does not change an existing file's permissions.
+        await handle.chmod(0o600);
+        await handle.writeFile(content, "utf8");
+    }
+    finally {
+        await handle.close();
+    }
+};

package/dist/filesystem/paths.js

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import path from "node:path";
 import { SpawnfileError } from "../shared/index.js";
 export const assertPortableRelativePath = (inputPath) => {
@@ -9,7 +10,15 @@ export const assertPortableRelativePath = (inputPath) => {
     }
 };
 export const getCanonicalManifestPath = (filePath) => path.resolve(filePath);
-export const getManifestPath = (inputPath) => path.basename(inputPath) === "Spawnfile"
+const isExistingFile = (inputPath) => {
+    try {
+        return statSync(inputPath).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+export const getManifestPath = (inputPath) => path.basename(inputPath) === "Spawnfile" || isExistingFile(inputPath)
     ? path.resolve(inputPath)
     : path.resolve(inputPath, "Spawnfile");
 export const getProjectRoot = (manifestPath) => path.dirname(manifestPath);

package/dist/ledger/causalConformanceCli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ledger/causalConformanceCli.js

@@ -0,0 +1,41 @@
+import { runRealConformance } from "./conformance.js";
+/**
+ * `npm run test:causal-conformance` entry point (B92). Runs the four real
+ * sibling causal fixture emitters (simfile, mneme, daimon, moltnet — see
+ * emitters.ts) by path, validates every record against the schema and
+ * payload minimums, stitches them into one interaction chain, and
+ * reconciles it. Prints per-source counts, any issues, and the
+ * reconstructed chain edges; exits 1 when the report is not ok.
+ *
+ * This is a hermetic-suite exception: it spawns real processes (a `go run`
+ * compile, three tsx processes), so it is its own npm script rather than a
+ * vitest test — `npm test` stays fully in-process (see emitters.test.ts and
+ * realConformance.test.ts for the injected-exec unit coverage of this same
+ * logic).
+ */
+const main = async () => {
+    const report = await runRealConformance();
+    console.log(`causal conformance: ${report.ok ? "OK" : "FAILED"} (events=${report.eventCount})`);
+    console.log("per-source counts:");
+    for (const { count, source } of report.sourceCounts) {
+        console.log(`  - ${source}: ${count}`);
+    }
+    if (report.issues.length > 0) {
+        console.log("issues:");
+        for (const issue of report.issues) {
+            const line = issue.line !== undefined ? ` (line ${issue.line})` : "";
+            console.log(`  - [${issue.source}]${line} ${issue.message}`);
+        }
+    }
+    console.log(`chain: ${report.chain.stitchedEventCount} stitched events, ${report.chain.edges.length} backward edges`);
+    for (const edge of report.chain.edges) {
+        console.log(`  - ${edge.from} -> ${edge.to}`);
+    }
+    if (!report.ok) {
+        process.exitCode = 1;
+    }
+};
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});