spawnfile 0.1.13 → 0.1.17

package/dist/target/evidenceExportOperationsTestKit.js

@@ -0,0 +1,312 @@
+import { mkdtemp, realpath, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { EVIDENCE_EXPORT_MOUNT, EVIDENCE_EXPORT_HELPER_CMD, EVIDENCE_EXPORT_HELPER_CONTRACT, EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL, EVIDENCE_EXPORT_HELPER_ENTRYPOINT, EVIDENCE_EXPORT_HELPER_ENV, EVIDENCE_EXPORT_HELPER_USER, createEvidenceExportHelper, parseEvidenceVolumeAuthority } from "./evidenceExportProvider.js";
+import { createDockerArtifactSpec, initializeDockerArtifactIdentityStore } from "./dockerArtifactsProvider.js";
+import { initializeEvidenceExportAuthorityStore } from "./evidenceExportStore.js";
+import { createDockerResourceSpec } from "./dockerResourcesProvider.js";
+import { createEvidenceExportOperations } from "./evidenceExport.js";
+import { initializeTargetJournal } from "./journal.js";
+import { selectTarget } from "./dockerTarget.js";
+import { createTargetReceiptDigest } from "./handles.js";
+import { parseOpaqueTargetHandle, TARGET_RESOURCE_REQUEST_VERSION } from "./contracts.js";
+const roots = [];
+export const root = async () => {
+    const value = await realpath(await mkdtemp(path.join(os.tmpdir(), "spawnfile-export-")));
+    roots.push(value);
+    return value;
+};
+export const cleanupTestRoots = async () => {
+    await Promise.all(roots.splice(0).map((value) => rm(value, { force: true, recursive: true })));
+};
+const admission = () => {
+    const selectedTargetHandle = parseOpaqueTargetHandle("opaque_dddddddddddddddd");
+    const volume = createDockerResourceSpec({ kind: "evidence_volume", operationHandle: parseOpaqueTargetHandle("opaque_eeeeeeeeeeeeeeee"), requestDigest: `sha256:${"f".repeat(64)}`, runId: "run-one", selectedTargetHandle });
+    return ({
+        descriptor_digest: `sha256:${"a".repeat(64)}`,
+        evidence_volume: parseEvidenceVolumeAuthority({ labels: volume.labels, name: volume.name, resultHandle: volume.resultHandle }),
+        helper: createEvidenceExportHelper({
+            artifactManifestDigest: `sha256:${"b".repeat(64)}`,
+            imageDigest: `sha256:${"c".repeat(64)}`,
+            imageReference: `registry.example/export@sha256:${"c".repeat(64)}`,
+            resultHandle: parseOpaqueTargetHandle("opaque_bbbbbbbbbbbbbbbb")
+        }),
+        helper_contract: EVIDENCE_EXPORT_HELPER_CONTRACT,
+        operation_handle: parseOpaqueTargetHandle("opaque_cccccccccccccccc"),
+        request_digest: `sha256:${"d".repeat(64)}`,
+        run_id: "run-one",
+        selected_target: { fingerprint: `sha256:${"e".repeat(32)}`, handle: selectedTargetHandle },
+        version: "spawnfile.target-evidence-export.private.v1"
+    });
+};
+export { admission };
+const complete = async (journal, claim, request, spec) => {
+    const raw = { cleanup_state: "not_requested", descriptor_digest: request.descriptor_digest, export_state: "not_requested", labels: Object.entries(spec.labels).map(([key, value]) => ({ key, value })), operation: request.operation, operation_handle: claim.operationHandle, receipt_digest: `sha256:${"0".repeat(64)}`, request_digest: claim.requestDigest, result_handle: spec.resultHandle, resulting_revision: (await journal.read()).revision + 1, run_id: request.run_id, selected_target: request.selected_target, version: "spawnfile.target-resource.receipt.v1" };
+    await journal.complete(claim, { ...raw, receipt_digest: createTargetReceiptDigest(raw) });
+};
+export { complete };
+const octalField = (value, length) => {
+    const raw = value.toString(8);
+    if (raw.length > length - 1)
+        throw new Error("field overflow");
+    return `${raw.padStart(length - 1, "0")}\0`;
+};
+export const header = (name, data) => {
+    const out = Buffer.alloc(512);
+    out.write(name);
+    out.write(octalField(0o644, 8), 100);
+    out.write(octalField(0, 8), 108);
+    out.write(octalField(0, 8), 116);
+    out.write(octalField(data.byteLength, 12), 124);
+    out.write(octalField(0, 12), 136);
+    out.fill(32, 148, 156);
+    out.write("0", 156);
+    out.write("ustar\0", 257);
+    out.write("00", 263);
+    out.write(octalField(0, 8), 329);
+    out.write(octalField(0, 8), 337);
+    const checksum = out.reduce((sum, value) => sum + value, 0).toString(8).padStart(6, "0");
+    if (checksum.length > 6)
+        throw new Error("checksum overflow");
+    out.write(`${checksum}\0 `, 148);
+    return out;
+};
+export const runLifecycleExport = async (input = {}) => {
+    const directory = await root();
+    const context = "test_context";
+    const calls = [];
+    const descriptor = `sha256:${"a".repeat(64)}`;
+    const manifest = `sha256:${"b".repeat(64)}`;
+    const image = `sha256:${"c".repeat(64)}`;
+    const reference = `registry.example/export@${image}`;
+    const payload = input.payload ?? new Uint8Array([...header("ball", Buffer.from("kick")), ...Buffer.from("kick"), ...Buffer.alloc(508), ...Buffer.alloc(1024)]);
+    let volume;
+    let created = [];
+    let exportCalls = 0;
+    let removeCalls = 0;
+    let helperInspectionDrift = false;
+    let volumeInspectionDrift = false;
+    const projection = JSON.stringify([{
+            RepoDigests: [reference],
+            Config: {
+                Entrypoint: EVIDENCE_EXPORT_HELPER_ENTRYPOINT,
+                Cmd: EVIDENCE_EXPORT_HELPER_CMD,
+                Labels: { [EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL]: "v1" },
+                Env: ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
+                ExposedPorts: null,
+                Healthcheck: null,
+                User: EVIDENCE_EXPORT_HELPER_USER,
+                Volumes: null
+            }
+        }]);
+    const imageLabels = { [EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL]: "v1" };
+    const containerProjectionLabels = { ...imageLabels };
+    const removeCallArgs = [];
+    const executor = async (_file, args) => {
+        calls.push(args);
+        if (args[0] === "context")
+            return { stderr: "", stdout: JSON.stringify("unix:///private/test.sock") };
+        if (args[2] === "volume" && args[3] === "inspect")
+            return { stderr: "", stdout: JSON.stringify([{ Labels: volumeInspectionDrift ? { ...volume.labels, "spawnfile.target.drift": "true" } : volume.labels, Name: volume.name }]) };
+        if (args[2] === "image" && args[3] === "inspect")
+            return { stderr: "", stdout: helperInspectionDrift ? projection.replace("65534:65534", "0:0") : projection };
+        if (args[2] === "container" && args[3] === "create") {
+            created = args;
+            if (input.createShouldFail)
+                throw new Error("create transport failed");
+            return { stderr: "", stdout: "container" };
+        }
+        if (args[2] === "container" && args[3] === "inspect") {
+            if (input.foreignInspect === "transport")
+                throw new Error("inspect transport failed");
+            return {
+                stderr: "",
+                stdout: helperProjection(created, volume.name, containerProjectionLabels, input.foreignInspect === "projection"
+                    ? (projection) => { projection.Config = { ...projection.Config, User: "0:0" }; }
+                    : undefined)
+            };
+        }
+        if (args[2] === "container" && args[3] === "rm") {
+            removeCallArgs.push(args);
+            removeCalls += 1;
+            if (input.cleanupShouldFail)
+                throw new Error("rm failed");
+            return { stderr: "", stdout: "removed" };
+        }
+        throw new Error(`unexpected docker invocation: ${args.join(" ")}`);
+    };
+    const selected = await selectTarget({ context, execFile: executor });
+    const journal = await initializeTargetJournal({ context, descriptorDigest: descriptor, root: path.join(directory, "journal"), runId: "run-one", selectedTarget: selected });
+    const envelope = (expected_revision, idempotency_key) => ({ descriptor_digest: descriptor, expected_revision, idempotency_key, run_id: "run-one", selected_target: { fingerprint: selected.fingerprint, handle: selected.handle }, version: TARGET_RESOURCE_REQUEST_VERSION });
+    const artifactRequest = { ...envelope(0, "idem_aaaaaaaaaaaaaaaa"), artifact_manifest_digest: manifest, operation: "resolve_world_artifact" };
+    const artifactClaim = await journal.reserve(artifactRequest);
+    if (artifactClaim.kind !== "owner")
+        throw new Error("artifact reservation failed");
+    const artifact = createDockerArtifactSpec({ artifactManifestDigest: manifest, imageDigest: image, imageReference: reference, operationHandle: artifactClaim.claim.operationHandle, requestDigest: artifactClaim.claim.requestDigest, selectedTargetHandle: selected.handle });
+    await complete(journal, artifactClaim.claim, artifactRequest, artifact);
+    const identities = await initializeDockerArtifactIdentityStore(path.join(directory, "identities"));
+    await identities.bind({ artifactManifestDigest: manifest, imageDigest: image, imageReference: reference, operationHandle: artifactClaim.claim.operationHandle, requestDigest: artifactClaim.claim.requestDigest, resultHandle: artifact.resultHandle, selectedTargetHandle: selected.handle });
+    const volumeRequest = { ...envelope(1, "idem_bbbbbbbbbbbbbbbb"), operation: "create_evidence_volume" };
+    const volumeClaim = await journal.reserve(volumeRequest);
+    if (volumeClaim.kind !== "owner")
+        throw new Error("volume reservation failed");
+    volume = createDockerResourceSpec({ kind: "evidence_volume", operationHandle: volumeClaim.claim.operationHandle, requestDigest: volumeClaim.claim.requestDigest, runId: "run-one", selectedTargetHandle: selected.handle });
+    await complete(journal, volumeClaim.claim, volumeRequest, volume);
+    const exportRequest = { ...envelope(2, "idem_cccccccccccccccc"), evidence_volume_handle: volume.resultHandle, operation: "export_evidence_volume" };
+    const destination = path.join(directory, "match.tar");
+    const authorityStore = await initializeEvidenceExportAuthorityStore(path.join(directory, "export-store"), input.createDestinationStoreOptions);
+    const observedAuthorityStore = input.onLoadIndex ? {
+        bindAdmission: authorityStore.bindAdmission.bind(authorityStore),
+        bindDestination: authorityStore.bindDestination.bind(authorityStore),
+        bindIndex: authorityStore.bindIndex.bind(authorityStore),
+        claimExport: authorityStore.claimExport.bind(authorityStore),
+        clearStaleExportClaim: authorityStore.clearStaleExportClaim.bind(authorityStore),
+        loadAdmission: authorityStore.loadAdmission.bind(authorityStore),
+        loadIndex: async (value) => {
+            await input.onLoadIndex();
+            return authorityStore.loadIndex(value);
+        },
+        releaseExport: authorityStore.releaseExport.bind(authorityStore),
+        requireDestination: authorityStore.requireDestination.bind(authorityStore)
+    } : authorityStore;
+    const operationOptions = {
+        authorityStore: observedAuthorityStore,
+        artifactIdentityStore: identities,
+        context,
+        executor,
+        exportExecutor: async () => {
+            exportCalls += 1;
+            if (input.startShouldFail)
+                throw new Error("start failed");
+            return { bytes: payload };
+        },
+        helperArtifactBundle: { operation_handle: artifactClaim.claim.operationHandle, request_digest: artifactClaim.claim.requestDigest, result_handle: artifact.resultHandle },
+        helperArtifactManifestDigest: manifest,
+        helperArtifactContract: EVIDENCE_EXPORT_HELPER_CONTRACT,
+        journal,
+        testHooks: {
+            beforeBindAdmission: input.boundaryFailures?.beforeBindAdmission,
+            beforeBindDestination: input.boundaryFailures?.beforeBindDestination,
+            beforeIndexLoad: input.boundaryFailures?.beforeIndexLoad,
+            beforeIndexBind: input.boundaryFailures?.beforeIndexBind,
+            beforeArchive: input.boundaryFailures?.beforeArchive,
+            beforePublishTempWrite: input.boundaryFailures?.beforePublishTempWrite,
+            beforePublishTempOpen: input.boundaryFailures?.beforePublishTempOpen,
+            beforePublishTempSync: input.boundaryFailures?.beforePublishTempSync,
+            beforePublishFinalLink: input.boundaryFailures?.beforePublishFinalLink,
+            beforePublishDirectorySync: input.boundaryFailures?.beforePublishDirectorySync,
+            beforeJournalComplete: input.boundaryFailures?.beforeJournalComplete,
+            beforeRequireDestination: input.boundaryFailures?.beforeRequireDestination
+        }
+    };
+    const operations = createEvidenceExportOperations(operationOptions);
+    const execute = async (destinationValue) => operations.execute(exportRequest, destinationValue ?? destination);
+    const executeDistinct = async (destinationValue) => operations.execute({ ...exportRequest, evidence_volume_handle: artifact.resultHandle }, destinationValue ?? destination);
+    const executeReplayWithBlockedExecutors = async (destinationValue) => {
+        let dockerCalls = 0;
+        let blockedExportCalls = 0;
+        const replay = createEvidenceExportOperations({
+            ...operationOptions,
+            executor: async () => { dockerCalls += 1; throw new Error("completed replay touched Docker"); },
+            exportExecutor: async () => { blockedExportCalls += 1; throw new Error("completed replay exported evidence"); }
+        });
+        const result = await replay.execute(exportRequest, destinationValue ?? destination);
+        return { dockerCalls, exportCalls: blockedExportCalls, result };
+    };
+    const rejectReplayWithWrongHelperRequest = async (destinationValue) => {
+        let dockerCalls = 0;
+        let blockedExportCalls = 0;
+        const replay = createEvidenceExportOperations({
+            ...operationOptions,
+            executor: async () => { dockerCalls += 1; throw new Error("completed replay touched Docker"); },
+            exportExecutor: async () => { blockedExportCalls += 1; throw new Error("completed replay exported evidence"); },
+            helperArtifactBundle: { ...operationOptions.helperArtifactBundle, request_digest: `sha256:${"f".repeat(64)}` }
+        });
+        let error;
+        try {
+            await replay.execute(exportRequest, destinationValue ?? destination);
+        }
+        catch (caught) {
+            error = caught;
+        }
+        return { dockerCalls, error, exportCalls: blockedExportCalls };
+    };
+    const pendingExport = async () => {
+        const entry = (await journal.read()).entries.find((value) => value.operation === "export_evidence_volume" && value.state === "pending");
+        if (!entry)
+            throw new Error("pending export missing");
+        return entry;
+    };
+    const recoveryRequest = async (distinct = false) => {
+        const entry = await pendingExport();
+        return { ...envelope((await journal.read()).revision, distinct ? "idem_eeeeeeeeeeeeeeee" : "idem_dddddddddddddddd"), operation: "recover_operation", operation_handle: entry.operation_handle };
+    };
+    const recover = async (destinationValue) => operations.recover(await recoveryRequest(), destinationValue ?? destination);
+    const recoverDistinct = async (destinationValue) => operations.recover(await recoveryRequest(true), destinationValue ?? destination);
+    const recoverPeer = async (destinationValue) => createEvidenceExportOperations(operationOptions).recover(await recoveryRequest(), destinationValue ?? destination);
+    const seedStaleExportClaim = async () => {
+        const entry = await pendingExport();
+        const admission = await authorityStore.loadAdmission(entry.operation_handle);
+        if (await authorityStore.claimExport(admission) === null)
+            throw new Error("export claim unavailable");
+    };
+    const getContainerName = () => {
+        const create = calls.find((args) => args[2] === "container" && args[3] === "create");
+        if (!create)
+            return undefined;
+        const name = create[create.indexOf("--name") + 1];
+        return typeof name === "string" ? name : undefined;
+    };
+    return { calls, directory, execute, executeDistinct, executeReplayWithBlockedExecutors, rejectReplayWithWrongHelperRequest, recover, recoverDistinct, recoverPeer, seedStaleExportClaim, setHelperInspectionDrift: (value) => { helperInspectionDrift = value; }, setVolumeInspectionDrift: (value) => { volumeInspectionDrift = value; }, getContainerName, getExportCalls: () => exportCalls, getRemoveCalls: () => removeCalls, getRemoveArgs: () => [...removeCallArgs], getExportStorePath: () => path.join(directory, "export-store"), readJournalRevision: async () => (await journal.read()).revision };
+};
+export const helperProjection = (args, volumeName, imageLabels, mutate) => {
+    const image = args[args.length - 1];
+    const containerName = args[args.indexOf("--name") + 1];
+    const labels = Object.fromEntries(args.filter((_, index) => args[index - 1] === "--label").map((value) => value.split("=", 2)));
+    const projection = {
+        Name: `/${containerName}`,
+        Config: {
+            Entrypoint: EVIDENCE_EXPORT_HELPER_ENTRYPOINT,
+            Cmd: EVIDENCE_EXPORT_HELPER_CMD,
+            Env: EVIDENCE_EXPORT_HELPER_ENV,
+            ExposedPorts: null,
+            Healthcheck: null,
+            Image: image,
+            Labels: { ...imageLabels, ...labels },
+            User: EVIDENCE_EXPORT_HELPER_USER,
+            Volumes: null
+        },
+        HostConfig: {
+            AutoRemove: false,
+            NetworkMode: "none",
+            ReadonlyRootfs: true,
+            Privileged: false,
+            CapAdd: null,
+            CapDrop: ["ALL"],
+            SecurityOpt: ["no-new-privileges=true"],
+            PidsLimit: 64,
+            Memory: 134217728,
+            NanoCpus: 250000000,
+            IpcMode: "none",
+            PidMode: "",
+            UTSMode: "",
+            UsernsMode: "",
+            CgroupnsMode: "private",
+            Binds: null,
+            VolumesFrom: null,
+            ExtraHosts: null,
+            Dns: null,
+            Links: null,
+            GroupAdd: null,
+            Devices: null,
+            DeviceRequests: null,
+            PortBindings: null,
+            PublishAllPorts: false,
+            RestartPolicy: { Name: "no", MaximumRetryCount: 0 },
+            LogConfig: { Type: "none", Config: {} }
+        },
+        Mounts: [{ Type: "volume", Name: volumeName, Destination: EVIDENCE_EXPORT_MOUNT, RW: false }]
+    };
+    mutate?.(projection);
+    return JSON.stringify([projection]);
+};

package/dist/target/evidenceExportProvider.d.ts

@@ -0,0 +1,87 @@
+import { type OpaqueTargetHandle } from "./contracts.js";
+export declare const EVIDENCE_EXPORT_ERROR = "Evidence-volume export failed";
+export declare const EVIDENCE_EXPORT_MOUNT: "/spawnfile/evidence";
+export declare const EVIDENCE_EXPORT_HELPER_CONTRACT: "spawnfile.target-evidence-export.helper.v1";
+export declare const EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION: "v1";
+export declare const EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL: "spawnfile.target.evidence-export.helper-contract";
+export declare const EVIDENCE_EXPORT_HELPER_ENTRYPOINT: readonly string[];
+export declare const EVIDENCE_EXPORT_HELPER_CMD: readonly string[];
+export declare const EVIDENCE_EXPORT_HELPER_PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export declare const EVIDENCE_EXPORT_HELPER_ENV: readonly string[];
+export declare const EVIDENCE_EXPORT_HELPER_USER: "65534:65534";
+export interface DockerEvidenceExportExecutor {
+    (file: string, args: readonly string[], options: {
+        readonly signal?: AbortSignal;
+        readonly timeout: number;
+    }): Promise<{
+        readonly bytes: Uint8Array;
+    }>;
+}
+export interface DockerEvidenceInspectionExecutor {
+    (file: string, args: string[], options: {
+        readonly signal?: AbortSignal;
+        readonly timeout: number;
+    }): Promise<{
+        readonly stderr: string;
+        readonly stdout: string;
+    }>;
+}
+export interface EvidenceVolumeAuthority {
+    readonly labels: Readonly<Record<string, string>>;
+    readonly name: string;
+    readonly resultHandle: OpaqueTargetHandle;
+}
+/** Resolved only from B91's private immutable artifact identity store. */
+export interface EvidenceExportHelper {
+    readonly artifactManifestDigest: string;
+    readonly image_digest: string;
+    readonly image_reference: string;
+    readonly result_handle: OpaqueTargetHandle;
+}
+export interface EvidenceExportHelperImageInspection {
+    readonly labels: Readonly<Record<string, string>>;
+}
+export interface EvidenceExportHelperSpec {
+    readonly containerName: string;
+    readonly createArgs: readonly string[];
+    readonly imageLabels: Readonly<Record<string, string>>;
+    readonly imageReference: string;
+    readonly inspectionFormat: string;
+}
+export declare const createEvidenceExportHelper: (raw: {
+    artifactManifestDigest: unknown;
+    imageDigest: unknown;
+    imageReference: unknown;
+    resultHandle: unknown;
+}) => EvidenceExportHelper;
+export declare const parseEvidenceVolumeAuthority: (raw: unknown) => EvidenceVolumeAuthority;
+export declare const createEvidenceExportHandle: (input: {
+    readonly evidenceVolumeHandle: unknown;
+    readonly operationHandle: unknown;
+    readonly requestDigest: unknown;
+}) => OpaqueTargetHandle;
+export declare const evidenceDigest: (bytes: Uint8Array) => `sha256:${string}`;
+export declare const evidenceReceiptLabels: (authority: EvidenceVolumeAuthority) => Array<{
+    key: string;
+    value: string;
+}>;
+export declare const assertExportRun: (authority: EvidenceVolumeAuthority, input: {
+    readonly runId: unknown;
+    readonly selectedTargetHandle: unknown;
+}) => void;
+export declare const createEvidenceExportHelperSpec: (input: {
+    readonly authority: EvidenceVolumeAuthority;
+    readonly helper: EvidenceExportHelper;
+    readonly imageLabels: Readonly<Record<string, string>>;
+    readonly operationHandle: OpaqueTargetHandle;
+    readonly requestDigest: string;
+}) => EvidenceExportHelperSpec;
+export declare const parseEvidenceExportImageInspection: (stdout: string, helper: EvidenceExportHelper) => EvidenceExportHelperImageInspection;
+export declare const isExpectedEvidenceExportImage: (stdout: string, helper: EvidenceExportHelper) => boolean;
+export declare const isExpectedEvidenceExportHelper: (stdout: string, spec: EvidenceExportHelperSpec) => boolean;
+export declare const executeEvidenceExport: (input: {
+    readonly args: readonly string[];
+    readonly executor: DockerEvidenceExportExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}) => Promise<Uint8Array>;

package/dist/target/evidenceExportProvider.js

@@ -0,0 +1,197 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { parseOpaqueTargetHandle, parseRunId } from "./contracts.js";
+import { isImmutableDockerImageReference } from "./dockerArtifactsProvider.js";
+import { boundedRedactedText } from "../shared/index.js";
+export const EVIDENCE_EXPORT_ERROR = "Evidence-volume export failed";
+export const EVIDENCE_EXPORT_MOUNT = "/spawnfile/evidence";
+export const EVIDENCE_EXPORT_HELPER_CONTRACT = "spawnfile.target-evidence-export.helper.v1";
+export const EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION = "v1";
+export const EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL = "spawnfile.target.evidence-export.helper-contract";
+export const EVIDENCE_EXPORT_HELPER_ENTRYPOINT = Object.freeze(["/bin/spawnfile-export-helper"]);
+export const EVIDENCE_EXPORT_HELPER_CMD = Object.freeze([]);
+export const EVIDENCE_EXPORT_HELPER_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export const EVIDENCE_EXPORT_HELPER_ENV = Object.freeze([
+    `PATH=${EVIDENCE_EXPORT_HELPER_PATH}`,
+]);
+export const EVIDENCE_EXPORT_HELPER_USER = "65534:65534";
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const NAME = /^spfe_[a-f0-9]{58}$/u;
+const MAX_OUTPUT_BYTES = 67_108_864;
+const fail = (reason) => { throw new Error(`${EVIDENCE_EXPORT_ERROR}${reason === undefined ? "" : ` (${reason})`}`); };
+const hash = (domain, value) => createHash("sha256").update(`spawnfile.target-evidence-export.${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 record = (raw) => {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw) || Object.getPrototypeOf(raw) !== Object.prototype)
+        return fail();
+    const value = raw;
+    const out = {};
+    for (const [key, candidate] of Object.entries(value)) {
+        if (!utf8(key) || typeof candidate !== "string" || !utf8(candidate))
+            return fail();
+        out[key] = candidate;
+    }
+    return Object.freeze(out);
+};
+const utf8 = (value) => typeof value === "string" && Buffer.from(value, "utf8").toString("utf8") === value && Buffer.byteLength(value, "utf8") <= 32_768;
+const json = (raw) => { if (!utf8(raw))
+    return fail(); try {
+    return JSON.parse(raw);
+}
+catch {
+    return fail();
+} };
+const exactHelperEnv = (raw) => Array.isArray(raw)
+    && raw.length === 1 && raw[0] === EVIDENCE_EXPORT_HELPER_ENV[0];
+export const createEvidenceExportHelper = (raw) => {
+    const localConfig = raw.imageReference === raw.imageDigest;
+    if (typeof raw.artifactManifestDigest !== "string" || !DIGEST.test(raw.artifactManifestDigest) || typeof raw.imageDigest !== "string" || !DIGEST.test(raw.imageDigest) || typeof raw.imageReference !== "string" || !localConfig && (!isImmutableDockerImageReference(raw.imageReference) || !raw.imageReference.endsWith(`@${raw.imageDigest}`)))
+        return fail();
+    return Object.freeze({ artifactManifestDigest: raw.artifactManifestDigest, image_digest: raw.imageDigest, image_reference: raw.imageReference, result_handle: parseOpaqueTargetHandle(raw.resultHandle) });
+};
+export const parseEvidenceVolumeAuthority = (raw) => {
+    if (!exact(raw, ["labels", "name", "resultHandle"]) || typeof raw.name !== "string" || !/^spfv_[a-f0-9]{58}$/u.test(raw.name) || !exact(raw.labels, ["spawnfile_resource_v1_kind", "spawnfile_resource_v1_operation", "spawnfile_resource_v1_run", "spawnfile_resource_v1_target", "spawnfile_resource_v1_version"]))
+        return fail();
+    const labels = raw.labels;
+    if (labels.spawnfile_resource_v1_kind !== "evidence_volume" || labels.spawnfile_resource_v1_version !== "v1" || Object.values(labels).some((value) => typeof value !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/u.test(value)))
+        return fail();
+    return Object.freeze({ labels: Object.freeze({ ...labels }), name: raw.name, resultHandle: parseOpaqueTargetHandle(raw.resultHandle) });
+};
+export const createEvidenceExportHandle = (input) => {
+    if (typeof input.requestDigest !== "string" || !DIGEST.test(input.requestDigest))
+        return fail();
+    return parseOpaqueTargetHandle(`opaque_${hash("result", `${parseOpaqueTargetHandle(input.evidenceVolumeHandle)}\0${parseOpaqueTargetHandle(input.operationHandle)}\0${input.requestDigest}`)}`);
+};
+export const evidenceDigest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+export const evidenceReceiptLabels = (authority) => Object.entries(parseEvidenceVolumeAuthority(authority).labels).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, value]) => ({ key, value }));
+export const assertExportRun = (authority, input) => {
+    const parsed = parseEvidenceVolumeAuthority(authority);
+    const label = (prefix, value) => `${prefix}${createHash("sha256").update("spawnfile.target-resource.docker-resource-label.v1\0").update(value).digest("hex").slice(0, 63)}`;
+    if (parsed.labels.spawnfile_resource_v1_run !== label("r", parseRunId(input.runId)) || parsed.labels.spawnfile_resource_v1_target !== label("t", parseOpaqueTargetHandle(input.selectedTargetHandle)))
+        return fail();
+};
+export const createEvidenceExportHelperSpec = (input) => {
+    const authority = parseEvidenceVolumeAuthority(input.authority);
+    const helper = createEvidenceExportHelper({ artifactManifestDigest: input.helper.artifactManifestDigest, imageDigest: input.helper.image_digest, imageReference: input.helper.image_reference, resultHandle: input.helper.result_handle });
+    const imageLabels = record(input.imageLabels);
+    if (!exact(imageLabels, [EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL]))
+        return fail();
+    if (imageLabels[EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL] !== EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION)
+        return fail();
+    if (!DIGEST.test(input.requestDigest))
+        return fail();
+    const containerName = `spfe_${hash("container", `${helper.result_handle}\0${input.operationHandle}\0${input.requestDigest}`).slice(0, 58)}`;
+    if (!NAME.test(containerName))
+        return fail();
+    const labels = [`spawnfile_evidence_export_v1_helper=${hash("label", helper.result_handle).slice(0, 63)}`, `spawnfile_evidence_export_v1_operation=${hash("label", `${input.operationHandle}\0${input.requestDigest}`).slice(0, 63)}`, "spawnfile_evidence_export_v1_version=v1"];
+    return Object.freeze({
+        containerName,
+        imageReference: helper.image_reference,
+        imageLabels,
+        inspectionFormat: "[{\"Name\":{{json .Name}},\"Config\":{\"Env\":{{json .Config.Env}},\"Entrypoint\":{{json .Config.Entrypoint}},\"Cmd\":{{json .Config.Cmd}},\"ExposedPorts\":{{json (index .Config \"ExposedPorts\")}},\"Healthcheck\":{{json (index .Config \"Healthcheck\")}},\"Image\":{{json .Config.Image}},\"Labels\":{{json .Config.Labels}},\"User\":{{json .Config.User}},\"Volumes\":{{json .Config.Volumes}}},\"HostConfig\":{\"AutoRemove\":{{json .HostConfig.AutoRemove}},\"NetworkMode\":{{json .HostConfig.NetworkMode}},\"ReadonlyRootfs\":{{json .HostConfig.ReadonlyRootfs}},\"Privileged\":{{json .HostConfig.Privileged}},\"CapAdd\":{{json .HostConfig.CapAdd}},\"CapDrop\":{{json .HostConfig.CapDrop}},\"SecurityOpt\":{{json .HostConfig.SecurityOpt}},\"PidsLimit\":{{json .HostConfig.PidsLimit}},\"Memory\":{{json .HostConfig.Memory}},\"NanoCpus\":{{json .HostConfig.NanoCpus}},\"IpcMode\":{{json .HostConfig.IpcMode}},\"PidMode\":{{json .HostConfig.PidMode}},\"UTSMode\":{{json .HostConfig.UTSMode}},\"UsernsMode\":{{json .HostConfig.UsernsMode}},\"CgroupnsMode\":{{json .HostConfig.CgroupnsMode}},\"Binds\":{{json .HostConfig.Binds}},\"VolumesFrom\":{{json .HostConfig.VolumesFrom}},\"ExtraHosts\":{{json .HostConfig.ExtraHosts}},\"Dns\":{{json .HostConfig.Dns}},\"Links\":{{json .HostConfig.Links}},\"GroupAdd\":{{json .HostConfig.GroupAdd}},\"Devices\":{{json .HostConfig.Devices}},\"DeviceRequests\":{{json .HostConfig.DeviceRequests}},\"PortBindings\":{{json .HostConfig.PortBindings}},\"PublishAllPorts\":{{json .HostConfig.PublishAllPorts}},\"RestartPolicy\":{{json .HostConfig.RestartPolicy}},\"LogConfig\":{{json .HostConfig.LogConfig}}},\"Mounts\":[{{range $index,$mount := .Mounts}}{{if $index}},{{end}}{\"Destination\":{{json $mount.Destination}},\"Name\":{{json $mount.Name}},\"RW\":{{json $mount.RW}},\"Type\":{{json $mount.Type}}}{{end}}]}]",
+        createArgs: Object.freeze(["container", "create", "--pull", "never", "--name", containerName, "--network", "none", "--restart", "no", "--privileged=false", "--log-driver", "none", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges=true", "--pids-limit", "64", "--memory", "128m", "--cpus", "0.25", "--ipc", "none", "--cgroupns", "private", "--label", labels[0], "--label", labels[1], "--label", labels[2], "--mount", `type=volume,src=${authority.name},dst=${EVIDENCE_EXPORT_MOUNT},readonly,volume-nocopy`, helper.image_reference])
+    });
+};
+export const parseEvidenceExportImageInspection = (stdout, helper) => {
+    const value = json(stdout);
+    const prepared = createEvidenceExportHelper({ artifactManifestDigest: helper.artifactManifestDigest, imageDigest: helper.image_digest, imageReference: helper.image_reference, resultHandle: helper.result_handle });
+    if (!Array.isArray(value) || value.length !== 1 || !exact(value[0], ["Config", "RepoDigests"]))
+        return fail();
+    const image = value[0];
+    const localConfig = prepared.image_reference === prepared.image_digest;
+    if (!localConfig && (!Array.isArray(image.RepoDigests) || image.RepoDigests.length < 1 || image.RepoDigests.length > 32 || image.RepoDigests.some((value) => !isImmutableDockerImageReference(value))))
+        return fail();
+    if (!exact(image.Config, ["Cmd", "Entrypoint", "Env", "ExposedPorts", "Healthcheck", "Labels", "User", "Volumes"]))
+        return fail();
+    const config = image.Config;
+    const labels = record(config.Labels);
+    if (!exact(labels, [EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL]) || labels[EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL] !== EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION)
+        return fail();
+    if (!Array.isArray(config.Entrypoint) || JSON.stringify(config.Entrypoint) !== JSON.stringify(EVIDENCE_EXPORT_HELPER_ENTRYPOINT))
+        return fail();
+    if (config.Cmd !== null && !(Array.isArray(config.Cmd) && config.Cmd.length === 0))
+        return fail();
+    if (config.User !== EVIDENCE_EXPORT_HELPER_USER)
+        return fail();
+    if (!exactHelperEnv(config.Env)
+        || config.ExposedPorts !== null || config.Healthcheck !== null || config.Volumes !== null)
+        return fail();
+    if (!localConfig && !image.RepoDigests.includes(prepared.image_reference))
+        return fail();
+    return { labels: Object.freeze({ ...labels }) };
+};
+export const isExpectedEvidenceExportImage = (stdout, helper) => {
+    try {
+        parseEvidenceExportImageInspection(stdout, helper);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const isExpectedEvidenceExportHelper = (stdout, spec) => {
+    try {
+        const value = json(stdout);
+        if (!Array.isArray(value) || value.length !== 1 || !exact(value[0], ["Config", "HostConfig", "Mounts", "Name"]))
+            return false;
+        const item = value[0];
+        const config = item.Config;
+        const host = item.HostConfig;
+        const mounts = item.Mounts;
+        if (!exact(config, ["Cmd", "Entrypoint", "Env", "ExposedPorts", "Healthcheck", "Image", "Labels", "User", "Volumes"]) || !exact(host, ["AutoRemove", "Binds", "CapAdd", "CapDrop", "CgroupnsMode", "DeviceRequests", "Devices", "Dns", "ExtraHosts", "GroupAdd", "IpcMode", "Links", "LogConfig", "Memory", "NanoCpus", "NetworkMode", "PidMode", "PidsLimit", "PortBindings", "Privileged", "PublishAllPorts", "ReadonlyRootfs", "RestartPolicy", "SecurityOpt", "UTSMode", "UsernsMode", "VolumesFrom"]) || !Array.isArray(mounts) || mounts.length !== 1 || !exact(mounts[0], ["Destination", "Name", "RW", "Type"]))
+            return false;
+        const labels = spec.createArgs.filter((value, index) => spec.createArgs[index - 1] === "--label").map((value) => value.split("=", 2));
+        const runtimeLabels = Object.fromEntries(labels);
+        const expectedLabels = { ...spec.imageLabels, ...runtimeLabels };
+        const mounted = mounts[0];
+        const command = spec.createArgs[spec.createArgs.indexOf(spec.imageReference) + 1];
+        const cmd = config.Cmd;
+        return item.Name === `/${spec.containerName}` && config.Image === spec.imageReference
+            && JSON.stringify(config.Entrypoint) === JSON.stringify(EVIDENCE_EXPORT_HELPER_ENTRYPOINT)
+            && (cmd === null || (Array.isArray(cmd) && cmd.length === 0))
+            && exactHelperEnv(config.Env)
+            && config.ExposedPorts === null && config.Healthcheck === null && config.Volumes === null
+            && config.User === EVIDENCE_EXPORT_HELPER_USER
+            && exact(config.Labels, Object.keys(expectedLabels))
+            && Object.entries(expectedLabels).every(([key, value]) => config.Labels !== null && config.Labels[key] === value)
+            && command === undefined
+            && host.AutoRemove === false && host.NetworkMode === "none" && host.ReadonlyRootfs === true
+            && host.Privileged === false && JSON.stringify(host.CapAdd) === JSON.stringify(null)
+            && JSON.stringify(host.CapDrop) === JSON.stringify(["ALL"]) && JSON.stringify(host.SecurityOpt) === JSON.stringify(["no-new-privileges=true"])
+            && host.PidsLimit === 64 && host.Memory === 134217728 && host.NanoCpus === 250_000_000
+            && host.IpcMode === "none" && host.PidMode === "" && host.UTSMode === ""
+            && host.UsernsMode === "" && host.CgroupnsMode === "private"
+            && [host.Binds, host.VolumesFrom, host.ExtraHosts, host.Dns, host.Links, host.GroupAdd, host.DeviceRequests].every((value) => value === null)
+            && (host.Devices === null || Array.isArray(host.Devices) && host.Devices.length === 0)
+            && (host.PortBindings === null || exact(host.PortBindings, []))
+            && host.PublishAllPorts === false && exact(host.RestartPolicy, ["MaximumRetryCount", "Name"]) && host.RestartPolicy.Name === "no"
+            && host.RestartPolicy.MaximumRetryCount === 0
+            && exact(host.LogConfig, ["Config", "Type"]) && host.LogConfig.Type === "none"
+            && JSON.stringify(host.LogConfig.Config) === JSON.stringify({})
+            && mounted.Type === "volume" && mounted.Destination === EVIDENCE_EXPORT_MOUNT && mounted.RW === false
+            && typeof mounted.Name === "string" && mounted.Name.length > 0
+            && spec.createArgs.some((arg) => arg.startsWith(`type=volume,src=${mounted.Name},`));
+    }
+    catch {
+        return false;
+    }
+};
+export const executeEvidenceExport = async (input) => {
+    const argv = boundedRedactedText(input.args.join(" "));
+    let output;
+    try {
+        output = await input.executor("docker", input.args, { signal: input.signal, timeout: input.timeoutMs });
+    }
+    catch (error) {
+        const name = error instanceof Error ? error.name : typeof error;
+        const message = error instanceof Error ? error.message : String(error);
+        return fail(`thrown failure: ${name}: ${boundedRedactedText(message)}; docker argv: ${argv}`);
+    }
+    if (!output)
+        return fail(`shape failure: missing output; docker argv: ${argv}`);
+    if (!(output.bytes instanceof Uint8Array))
+        return fail(`shape failure: output.bytes is not a Uint8Array; docker argv: ${argv}`);
+    if (output.bytes.byteLength > MAX_OUTPUT_BYTES)
+        return fail(`shape failure: output.bytes exceeds MAX_OUTPUT_BYTES (${output.bytes.byteLength} bytes); docker argv: ${argv}`);
+    return new Uint8Array(output.bytes);
+};

package/dist/target/evidenceExportPublicationTypes.d.ts

@@ -0,0 +1,16 @@
+export interface EvidenceExportPublicationOptions {
+    readonly beforeImmutableTempOpen?: (temporary: string) => Promise<void>;
+    readonly afterImmutableTempIdentity?: (temporary: string) => Promise<void>;
+    readonly afterImmutableFinalLinkBeforeTempUnlink?: () => Promise<void>;
+    readonly beforeDestinationKeyTempOpen?: (temporary: string) => Promise<void>;
+    readonly afterDestinationKeyTempIdentity?: (temporary: string) => Promise<void>;
+    readonly afterImmutableTransientRead?: () => Promise<void>;
+    readonly beforeDestinationKeyLink?: () => Promise<void>;
+    readonly afterDestinationKeyInitialFinalAbsent?: () => Promise<void>;
+    readonly afterDestinationKeyLinkBeforePendingUnlink?: () => Promise<void>;
+    readonly afterDestinationKeyPendingLinkBeforeTempUnlink?: () => Promise<void>;
+    readonly afterDestinationKeyPendingLstatBeforeOpen?: () => Promise<void>;
+    readonly afterDestinationKeyPendingLink?: () => Promise<void>;
+    readonly afterDestinationKeyRecovered?: () => Promise<void>;
+    readonly afterDestinationKeyFinalSnapshot?: () => Promise<void>;
+}

package/dist/target/evidenceExportPublicationTypes.js

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