spawnfile 0.1.14 → 0.1.18

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

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