spawnfile 0.1.14 → 0.1.17

package/dist/evidenceExportHelper/boundedExecutor.d.ts

@@ -0,0 +1,3 @@
+import { type DockerArtifactExecutor } from "../target/dockerArtifactsProvider.js";
+/** Tree-safe private Docker executor used at every local-helper boundary. */
+export declare const createPreparedEvidenceHelperExecutor: (dockerCommand: string) => DockerArtifactExecutor;

package/dist/evidenceExportHelper/boundedExecutor.js

@@ -0,0 +1,33 @@
+import { DockerArtifactProviderError, } from "../target/dockerArtifactsProvider.js";
+import { createBoundedDockerTargetExecFile, DockerTargetCommandFailure, } from "../target/dockerTargetExecFile.js";
+const missingExactImage = (args, error) => {
+    if (!(error instanceof DockerTargetCommandFailure))
+        return false;
+    const command = args[0] === "--context" ? args.slice(2) : args;
+    if (command.length !== 5 || command[0] !== "image" || command[1] !== "inspect"
+        || command[3] !== "--format")
+        return false;
+    const match = /^(?:Error response from daemon: )?No such image: ([A-Za-z0-9_.:@/-]+)$/u
+        .exec(error.stderr.trim());
+    return match?.[1] === command[2];
+};
+/** Tree-safe private Docker executor used at every local-helper boundary. */
+export const createPreparedEvidenceHelperExecutor = (dockerCommand) => {
+    const execute = createBoundedDockerTargetExecFile();
+    return async (file, args, options) => {
+        if (file !== "docker")
+            throw new Error("Prepared evidence-export helper failed");
+        try {
+            return await execute(dockerCommand, args, {
+                signal: options.signal,
+                stdin: options.stdin,
+                timeout: options.timeout,
+            });
+        }
+        catch (error) {
+            if (missingExactImage(args, error))
+                throw new DockerArtifactProviderError("image_not_found");
+            throw error;
+        }
+    };
+};

package/dist/evidenceExportHelper/helperProgram.mjs

@@ -0,0 +1,156 @@
+#!/usr/local/bin/node
+
+import { constants } from "node:fs";
+import { lstat, open, opendir } from "node:fs/promises";
+import path from "node:path";
+
+const ROOT = "/spawnfile/evidence";
+const BLOCK = 512;
+const MAX_BYTES = 67_108_864;
+const MAX_ENTRIES = 10_000;
+const MAX_DEPTH = 32;
+const MAX_PATH_BYTES = 255;
+
+const fail = () => { throw new Error("Evidence export helper failed"); };
+const pad = (size) => Math.ceil(size / BLOCK) * BLOCK;
+const same = (left, right) => left.dev === right.dev && left.ino === right.ino
+  && left.size === right.size && left.mode === right.mode;
+
+const safePath = (value) => {
+  const bytes = Buffer.from(value, "utf8");
+  if (value.length < 1 || bytes.toString("utf8") !== value
+    || bytes.byteLength > MAX_PATH_BYTES || value.startsWith("/")
+    || value.includes("\\") || value.includes("\0") || value.includes("//")) fail();
+  const parts = value.split("/");
+  if (parts.length > MAX_DEPTH || parts.some((part) => part === "" || part === "." || part === "..")) fail();
+  for (const part of parts) {
+    for (let index = 0; index < part.length; index += 1) {
+      const code = part.charCodeAt(index);
+      if (code < 0x20 || code === 0x7f) fail();
+    }
+  }
+  return value;
+};
+
+const comparePaths = (left, right) => Buffer.compare(
+  Buffer.from(left.path, "utf8"),
+  Buffer.from(right.path, "utf8"),
+);
+
+const collect = async (directory, prefix, entries) => {
+  const before = await lstat(directory);
+  if (!before.isDirectory() || before.isSymbolicLink()) fail();
+  const handle = await opendir(directory);
+  const names = [];
+  try {
+    for await (const item of handle) names.push(item.name);
+  } finally {
+    await handle.close().catch(() => undefined);
+  }
+  names.sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+  for (const name of names) {
+    const relative = safePath(prefix ? `${prefix}/${name}` : name);
+    const absolute = path.join(directory, name);
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink()) fail();
+    if (info.isDirectory()) {
+      entries.push({ info, path: relative, type: "directory" });
+      await collect(absolute, relative, entries);
+    } else if (info.isFile()) {
+      entries.push({ info, path: relative, type: "file" });
+    } else fail();
+    if (entries.length > MAX_ENTRIES) fail();
+  }
+  const after = await lstat(directory);
+  if (!same(before, after)) fail();
+};
+
+const octal = (value, width) => {
+  const raw = value.toString(8);
+  if (!Number.isSafeInteger(value) || value < 0 || raw.length > width - 1) fail();
+  return Buffer.from(`${raw.padStart(width - 1, "0")}\0`, "ascii");
+};
+
+const storedPath = (entry) => entry.type === "directory" ? `${entry.path}/` : entry.path;
+const splitPath = (stored) => {
+  const bytes = Buffer.from(stored, "utf8");
+  if (bytes.byteLength <= 100) return { name: bytes, prefix: Buffer.alloc(0) };
+  for (let split = stored.lastIndexOf("/"); split > 0; split = stored.lastIndexOf("/", split - 1)) {
+    const prefix = Buffer.from(stored.slice(0, split), "utf8");
+    const name = Buffer.from(stored.slice(split + 1), "utf8");
+    if (prefix.byteLength <= 155 && name.byteLength > 0 && name.byteLength <= 100) {
+      return { name, prefix };
+    }
+  }
+  return fail();
+};
+
+const header = (entry) => {
+  const stored = storedPath(entry);
+  const { name, prefix } = splitPath(stored);
+  const output = Buffer.alloc(BLOCK);
+  output.set(name, 0);
+  output.set(octal(entry.type === "directory" ? 0o755 : 0o644, 8), 100);
+  output.set(octal(0, 8), 108);
+  output.set(octal(0, 8), 116);
+  output.set(octal(entry.type === "file" ? entry.info.size : 0, 12), 124);
+  output.set(octal(0, 12), 136);
+  output[156] = entry.type === "directory" ? 53 : 48;
+  output.set(Buffer.from("ustar\0", "ascii"), 257);
+  output.set(Buffer.from("00", "ascii"), 263);
+  output.set(octal(0, 8), 329);
+  output.set(octal(0, 8), 337);
+  output.set(prefix, 345);
+  output.fill(0x20, 148, 156);
+  let sum = 0;
+  for (const byte of output) sum += byte;
+  if (sum > 0o777777) fail();
+  output.set(Buffer.from(`${sum.toString(8).padStart(6, "0")}\0 `, "ascii"), 148);
+  return output;
+};
+
+const write = async (bytes) => {
+  if (process.stdout.write(bytes)) return;
+  await new Promise((resolve, reject) => {
+    process.stdout.once("drain", resolve);
+    process.stdout.once("error", reject);
+  });
+};
+
+const main = async () => {
+  const root = await lstat(ROOT);
+  if (!root.isDirectory() || root.isSymbolicLink()) fail();
+  const entries = [];
+  await collect(ROOT, "", entries);
+  entries.sort(comparePaths);
+  if (entries.length < 1) fail();
+  let total = BLOCK * 2;
+  for (const entry of entries) {
+    total += BLOCK + (entry.type === "file" ? pad(entry.info.size) : 0);
+    if (!Number.isSafeInteger(total) || total > MAX_BYTES) fail();
+  }
+  for (const entry of entries) {
+    await write(header(entry));
+    if (entry.type !== "file") continue;
+    const absolute = path.join(ROOT, entry.path);
+    const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const before = await file.stat();
+      if (!before.isFile() || !same(before, entry.info)) fail();
+      const bytes = await file.readFile();
+      const after = await file.stat();
+      if (!same(before, after) || bytes.byteLength !== before.size) fail();
+      await write(bytes);
+      const padding = pad(bytes.byteLength) - bytes.byteLength;
+      if (padding > 0) await write(Buffer.alloc(padding));
+    } finally {
+      await file.close().catch(() => undefined);
+    }
+  }
+  await write(Buffer.alloc(BLOCK * 2));
+};
+
+main().catch(() => {
+  process.stderr.write("Evidence export helper failed\n");
+  process.exitCode = 1;
+});

package/dist/evidenceExportHelper/index.d.ts

@@ -0,0 +1,4 @@
+export { createPreparedEvidenceHelperExecutor } from "./boundedExecutor.js";
+export * from "./preparedAuthority.js";
+export * from "./preparedBuilder.js";
+export * from "./recipe.js";

package/dist/evidenceExportHelper/index.js

@@ -0,0 +1,4 @@
+export { createPreparedEvidenceHelperExecutor } from "./boundedExecutor.js";
+export * from "./preparedAuthority.js";
+export * from "./preparedBuilder.js";
+export * from "./recipe.js";

package/dist/evidenceExportHelper/preparedAuthority.d.ts

@@ -0,0 +1,64 @@
+import { type OpaqueTargetHandle } from "../target/contracts.js";
+export declare const PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION: "spawnfile.target-evidence-export-helper.prepared.v1";
+export declare const PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION: "spawnfile.target-evidence-export-helper.private.v3";
+export interface PreparedEvidenceHelperReceipt {
+    readonly digest: `sha256:${string}`;
+    readonly handle: OpaqueTargetHandle;
+    readonly version: typeof PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION;
+}
+export interface PreparedEvidenceHelperPendingRecord {
+    readonly base_config_digest: `sha256:${string}`;
+    readonly base_image: string;
+    readonly context: string;
+    readonly daemon_digest: `sha256:${string}`;
+    readonly endpoint_digest: `sha256:${string}`;
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+    readonly recipe_digest: `sha256:${string}`;
+    readonly version: typeof PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION;
+}
+export interface PreparedEvidenceHelperCompletionRecord {
+    readonly accepted_image_config_digest: `sha256:${string}`;
+    readonly pending_digest: `sha256:${string}`;
+    readonly receipt: PreparedEvidenceHelperReceipt;
+    readonly version: typeof PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION;
+}
+export interface PreparedEvidenceHelperAuthority {
+    readonly completion: PreparedEvidenceHelperCompletionRecord | null;
+    readonly pending: PreparedEvidenceHelperPendingRecord;
+}
+export declare const parsePreparedEvidenceHelperReceipt: (raw: unknown) => PreparedEvidenceHelperReceipt;
+export declare const createPreparedEvidenceHelperReceiptBytes: (raw: unknown) => string;
+export declare const pendingDigest: (raw: unknown) => `sha256:${string}`;
+export declare const createPreparedEvidenceHelperReceipt: (input: {
+    readonly configDigest: unknown;
+    readonly pendingDigest: unknown;
+}) => PreparedEvidenceHelperReceipt;
+export declare const parsePreparedEvidenceHelperPendingRecord: (raw: unknown) => PreparedEvidenceHelperPendingRecord;
+export declare const createPreparedEvidenceHelperPendingBytes: (raw: unknown) => string;
+export declare const parsePreparedEvidenceHelperCompletionRecord: (raw: unknown) => PreparedEvidenceHelperCompletionRecord;
+export declare const createPreparedEvidenceHelperCompletionBytes: (raw: unknown) => string;
+export declare const createPreparedEvidenceHelperKey: (input: {
+    readonly baseConfigDigest: string;
+    readonly context: string;
+    readonly daemonDigest: string;
+    readonly endpointDigest: string;
+    readonly platform: {
+        readonly architecture: string;
+        readonly os: string;
+    };
+    readonly recipeDigest: string;
+}) => string;
+export declare const newPreparedEvidenceHelperPendingRecord: (input: Omit<PreparedEvidenceHelperPendingRecord, "version">) => PreparedEvidenceHelperPendingRecord;
+export declare const newPreparedEvidenceHelperCompletionRecord: (pending: unknown, configDigest: unknown) => PreparedEvidenceHelperCompletionRecord;
+/** Immutable, fsynced pending/completion authority records keyed by exact target facts. */
+export declare class PreparedEvidenceHelperAuthorityStore {
+    #private;
+    constructor(privateRoot: string);
+    load(key: string): Promise<PreparedEvidenceHelperAuthority | null>;
+    reserve(key: string, raw: unknown): Promise<PreparedEvidenceHelperPendingRecord>;
+    complete(key: string, raw: unknown): Promise<PreparedEvidenceHelperCompletionRecord>;
+}
+export declare const initializePreparedEvidenceHelperAuthorityStore: (privateRoot: unknown) => Promise<PreparedEvidenceHelperAuthorityStore>;

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;
+}>;