spawnfile 0.1.12 → 0.1.14

package/dist/target/dockerContainerBundleBuilder.js

@@ -0,0 +1,256 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { DockerArtifactProviderError } from "./dockerArtifactsProvider.js";
+import { selectTarget } from "./dockerTarget.js";
+const ERROR = "Target-local container bundle preparation failed";
+const BLOCK = 512;
+const ID = /^sha256:[a-f0-9]{64}$/u;
+const BASE_LABEL = "spawnfile_target_bundle_v1_base";
+const ENTRYPOINT_LABEL = "spawnfile_target_bundle_v1_entrypoint";
+const fail = () => { throw new Error(ERROR); };
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+const exact = (left, right) => canonical(left) === canonical(right);
+const strings = (value) => Array.isArray(value) && value.every((item) => typeof item === "string") ? value : null;
+const labels = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const result = value;
+    return Object.values(result).every((item) => typeof item === "string") ? Object.freeze({ ...result }) : null;
+};
+const octal = (value, width) => Buffer.from(`${value.toString(8).padStart(width - 1, "0")}\0`, "ascii");
+const checksum = (header) => {
+    header.fill(0x20, 148, 156);
+    let sum = 0;
+    for (const byte of header)
+        sum += byte;
+    header.set(Buffer.from(`${sum.toString(8).padStart(6, "0")}\0 `, "ascii"), 148);
+};
+const ustarPath = (value) => {
+    const bytes = Buffer.from(value, "utf8");
+    if (bytes.byteLength <= 100)
+        return { name: bytes, prefix: Buffer.alloc(0) };
+    const slash = value.lastIndexOf("/");
+    if (slash < 1)
+        fail();
+    const prefix = Buffer.from(value.slice(0, slash), "utf8");
+    const name = Buffer.from(value.slice(slash + 1), "utf8");
+    if (prefix.byteLength > 155 || name.byteLength > 100)
+        fail();
+    return { name, prefix };
+};
+/** A canonical, uncompressed USTAR stream. The archive parser has already admitted the bundle paths. */
+const tar = (entries) => {
+    const output = [];
+    for (const entry of entries) {
+        const { name, prefix } = ustarPath(entry.path);
+        const header = Buffer.alloc(BLOCK);
+        header.set(name);
+        header.set(octal(0o644, 8), 100);
+        header.set(octal(0, 8), 108);
+        header.set(octal(0, 8), 116);
+        header.set(octal(entry.bytes.byteLength, 12), 124);
+        header.set(octal(0, 12), 136);
+        header[156] = 48;
+        header.set(Buffer.from("ustar\x00", "ascii"), 257);
+        header.set(Buffer.from("00", "ascii"), 263);
+        header.set(prefix, 345);
+        checksum(header);
+        output.push(header, Buffer.from(entry.bytes));
+        const pad = (BLOCK - entry.bytes.byteLength % BLOCK) % BLOCK;
+        if (pad)
+            output.push(Buffer.alloc(pad));
+    }
+    output.push(Buffer.alloc(BLOCK), Buffer.alloc(BLOCK));
+    return Buffer.concat(output);
+};
+const safeEntrypoint = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._/-]{0,239}$/u.test(value)
+    && !value.includes("//") && !value.split("/").some((part) => part === "." || part === "..");
+const dockerfile = (base, entrypoint) => {
+    if (!/^spfb_base_[a-f0-9]{53}$/u.test(base) || !safeEntrypoint(entrypoint))
+        fail();
+    return Buffer.from(`FROM ${base}\nWORKDIR /opt/bundle\nCOPY bundle/ /opt/bundle/\nENTRYPOINT ["node","/opt/bundle/${entrypoint}"]\nCMD []\n`, "utf8");
+};
+/* Docker 29 errors when a nil Labels map is dereferenced in a Go template.
+ * Project Config as one JSON value, then validate its exact security-relevant
+ * fields locally; this remains a private Docker inspection. */
+const projectionFormat = "[{\"Id\":{{json .Id}},\"Config\":{{json .Config}},\"RootFSType\":{{json .RootFS.Type}},\"RootFSLayers\":{{json .RootFS.Layers}},\"Os\":{{json .Os}},\"Architecture\":{{json .Architecture}}}]";
+const parseProjection = (raw) => {
+    try {
+        const value = JSON.parse(raw);
+        if (!Array.isArray(value) || value.length !== 1 || !value[0] || typeof value[0] !== "object")
+            return null;
+        const item = value[0];
+        if (Object.keys(item).sort().join("\0") !== "Architecture\0Config\0Id\0Os\0RootFSLayers\0RootFSType")
+            return null;
+        const config = item.Config;
+        if (!config || typeof config !== "object" || Array.isArray(config))
+            return null;
+        const source = config;
+        const itemLabels = source.Labels === undefined || source.Labels === null ? Object.freeze({}) : labels(source.Labels);
+        const entrypoint = source.Entrypoint === undefined || source.Entrypoint === null ? null : strings(source.Entrypoint);
+        const cmd = source.Cmd === undefined || source.Cmd === null ? null : strings(source.Cmd);
+        const env = source.Env === undefined || source.Env === null ? Object.freeze([]) : strings(source.Env);
+        const rootfs = strings(item.RootFSLayers);
+        if (!ID.test(item.Id) || !itemLabels || entrypoint === null && source.Entrypoint !== undefined && source.Entrypoint !== null || cmd === null && source.Cmd !== undefined && source.Cmd !== null || !env || !rootfs
+            || rootfs.length < 1 || item.RootFSType !== "layers" || (item.Architecture !== "amd64" && item.Architecture !== "arm64") || item.Os !== "linux"
+            || source.User !== undefined && source.User !== null && typeof source.User !== "string"
+            || source.WorkingDir !== undefined && source.WorkingDir !== null && typeof source.WorkingDir !== "string"
+            || source.OnBuild !== undefined && source.OnBuild !== null || source.Volumes !== undefined && source.Volumes !== null
+            || source.ExposedPorts !== undefined && source.ExposedPorts !== null || source.Healthcheck !== undefined && source.Healthcheck !== null)
+            return null;
+        return Object.freeze({ configId: item.Id, cmd, entrypoint, env, labels: itemLabels,
+            platform: Object.freeze({ architecture: item.Architecture, os: "linux" }), rootfs: Object.freeze([...rootfs]), user: source.User ?? "", workdir: source.WorkingDir ?? "" });
+    }
+    catch {
+        return null;
+    }
+};
+const isSafeBase = (value, expectedId, platform) => 
+/* Dockerfile deterministically replaces the inherited workdir, entrypoint,
+ * and command. Those base defaults therefore cannot affect the output or
+ * execute during this COPY-only build; rejecting them would exclude the
+ * reviewed node base. OnBuild remains forbidden because it can execute
+ * while building, and labels/user remain constrained because they persist. */
+value.configId === expectedId && exact(value.labels, {}) && value.user === ""
+    && exact(value.platform, platform);
+const expectedEntrypoint = (value) => {
+    const entrypoint = value[ENTRYPOINT_LABEL];
+    return safeEntrypoint(entrypoint) ? Object.freeze(["node", `/opt/bundle/${entrypoint}`]) : null;
+};
+const isOutput = (value, input) => {
+    const entrypoint = expectedEntrypoint(input.labels);
+    return (!input.configId || value.configId === input.configId) && entrypoint !== null && exact(value.labels, input.labels)
+        // Docker normalizes the explicit `CMD []` in the generated Dockerfile to
+        // a null Config.Cmd.  Null is therefore the exact no-inherited-command
+        // representation we attest on real daemons.
+        && exact(value.entrypoint, entrypoint) && exact(value.cmd, null) && exact(value.env, input.base.env)
+        && value.user === "" && value.workdir === "/opt/bundle" && exact(value.platform, input.platform)
+        && value.rootfs.length > input.base.rootfs.length && input.base.rootfs.every((layer, index) => value.rootfs[index] === layer);
+};
+const daemonEpoch = (id) => `sha256:${createHash("sha256")
+    .update("spawnfile.target-local-container-bundle.daemon-epoch.v1\0", "utf8").update(id, "utf8").digest("hex")}`;
+/* Bound to both output request and base config: no other operation can safely inherit this scratch tag. */
+const baseTag = (configId, gcTag) => `spfb_base_${createHash("sha256")
+    .update("spawnfile.target-local-container-bundle.base-tag.v2\0", "utf8").update(`${configId}\0${gcTag}`, "utf8").digest("hex").slice(0, 53)}`;
+/** Private Docker lowering. It refuses tag adoption; durable post-build recovery uses inspect() instead. */
+export const createDockerTargetLocalBundleBuilder = (input) => {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/u.test(input.context) || typeof input.executor !== "function")
+        fail();
+    const timeout = input.timeoutMs ?? 30_000;
+    const execute = async (args, stdin) => {
+        const result = await input.executor("docker", args, { timeout, ...(stdin ? { stdin } : {}) });
+        if (!result || Buffer.byteLength(result.stdout, "utf8") > 65_536 || Buffer.byteLength(result.stderr, "utf8") > 65_536)
+            fail();
+        return result.stdout;
+    };
+    const read = async (reference) => {
+        const value = parseProjection(await execute(["--context", input.context, "image", "inspect", "--format", projectionFormat, reference]));
+        return value ?? fail();
+    };
+    const readMaybe = async (reference) => {
+        try {
+            return await read(reference);
+        }
+        catch (error) {
+            if (error instanceof DockerArtifactProviderError && error.kind === "image_not_found")
+                return "missing";
+            throw error;
+        }
+    };
+    const absent = async (reference) => (await readMaybe(reference)) === "missing";
+    const base = async (configId, platform) => {
+        if (!ID.test(configId))
+            fail();
+        const result = await read(configId);
+        if (!isSafeBase(result, configId, platform))
+            fail();
+        return result;
+    };
+    const inspect = async (configId, gcTag, expected) => {
+        const baseId = expected.labels[BASE_LABEL];
+        if (!ID.test(baseId))
+            return null;
+        const baseImage = await base(baseId, expected.platform).catch(() => null);
+        if (!baseImage)
+            return null;
+        const byId = await readMaybe(configId);
+        const byTag = await readMaybe(gcTag);
+        if (byId === "missing" || byTag === "missing")
+            return null;
+        if (byId.configId !== byTag.configId || !isOutput(byId, { base: baseImage, ...(ID.test(configId) ? { configId } : {}), ...expected }))
+            return null;
+        return Object.freeze({ config_id: byId.configId, labels: Object.freeze({ ...expected.labels }), platform: expected.platform });
+    };
+    const inspectAnchor = async (gcTag, expected) => {
+        const byTag = await readMaybe(gcTag);
+        if (byTag === "missing")
+            return "missing";
+        return inspect(byTag.configId, gcTag, expected);
+    };
+    const builder = {
+        attestTarget: async ({ selected_target }) => {
+            const selected = await selectTarget({ context: input.context, execFile: async (_file, args) => ({ stderr: "", stdout: await execute(args) }), timeoutMs: timeout });
+            if (!exact({ fingerprint: selected.fingerprint, handle: selected.handle }, selected_target))
+                return null;
+            const raw = (await execute(["--context", input.context, "info", "--format", "{{json .ID}}"])).trim();
+            let id;
+            try {
+                id = JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+            return typeof id === "string" && id.length > 0 ? Object.freeze({ daemon_epoch: daemonEpoch(id) }) : null;
+        },
+        build: async ({ archive, base_image_config_digest, entrypoint, gc_tag, labels: expectedLabels, platform }) => {
+            if (!/^spfb_[a-f0-9]{58}$/u.test(gc_tag) || !safeEntrypoint(entrypoint) || expectedLabels[ENTRYPOINT_LABEL] !== entrypoint
+                || expectedLabels[BASE_LABEL] !== base_image_config_digest)
+                fail();
+            const baseImage = await base(base_image_config_digest, platform);
+            /* Any output tag, even a seemingly matching one, belongs to recovery rather than a new build. */
+            if (!await absent(gc_tag))
+                fail();
+            const scratch = baseTag(base_image_config_digest, gc_tag);
+            if (!await absent(scratch))
+                fail();
+            let ownScratch = false;
+            try {
+                const tagResult = await execute(["--context", input.context, "image", "tag", base_image_config_digest, scratch]);
+                if (tagResult.trim() !== "")
+                    fail();
+                ownScratch = true;
+                const pinned = await read(scratch);
+                if (!isSafeBase(pinned, base_image_config_digest, platform))
+                    fail();
+                const context = tar([{ path: "Dockerfile", bytes: dockerfile(scratch, entrypoint) }, ...archive.entries.map((entry) => ({ path: `bundle/${entry.path}`, bytes: entry.bytes }))]);
+                const labelArgs = Object.entries(expectedLabels).flatMap(([key, value]) => ["--label", `${key}=${value}`]);
+                await execute(["--context", input.context, "build", "--pull=false", "--network=none", "--platform", `${platform.os}/${platform.architecture}`, "--tag", gc_tag, ...labelArgs, "-"], context);
+                const result = await inspect(gc_tag, gc_tag, { labels: expectedLabels, platform });
+                if (!result)
+                    fail();
+                return result;
+            }
+            finally {
+                if (ownScratch) {
+                    const pinned = await read(scratch);
+                    if (!isSafeBase(pinned, base_image_config_digest, platform))
+                        fail();
+                    const removed = await execute(["--context", input.context, "image", "rm", scratch]);
+                    if (removed.trim().length > 4_096)
+                        fail();
+                }
+            }
+        },
+        inspect: async ({ config_id, gc_tag, labels: expectedLabels, platform }) => inspect(config_id, gc_tag, { labels: expectedLabels, platform }),
+        inspectAnchor: async ({ gc_tag, labels: expectedLabels, platform }) => inspectAnchor(gc_tag, { labels: expectedLabels, platform })
+    };
+    return Object.freeze(builder);
+};

package/dist/target/dockerContextSnapshot.d.ts

@@ -0,0 +1,21 @@
+import { rm } from "node:fs/promises";
+import type { SelectedTargetReceipt } from "./contracts.js";
+import type { DockerResourceExecutor } from "./dockerResourcesProvider.js";
+type SnapshotRemove = typeof rm;
+/** Test-only seam for deterministic cleanup failure coverage. */
+export declare const setDockerContextSnapshotRemoveForTests: (replacement: SnapshotRemove) => (() => void);
+export interface DockerContextSnapshot {
+    readonly args: readonly ["--config", string, "--context", string];
+    dispose(): Promise<void>;
+}
+/**
+ * Privately recreates one named Docker context without placing its endpoint or
+ * TLS options in argv. The synthetic config is short-lived and never exported.
+ */
+export declare const createDockerContextSnapshot: (input: {
+    readonly context: string;
+    readonly executor: DockerResourceExecutor;
+    readonly selectedTarget: Pick<SelectedTargetReceipt, "fingerprint" | "handle">;
+    readonly timeoutMs: number;
+}) => Promise<DockerContextSnapshot>;
+export {};

package/dist/target/dockerContextSnapshot.js

@@ -0,0 +1,158 @@
+import { constants } from "node:fs";
+import { lstat, mkdtemp, mkdir, open, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { SpawnfileError } from "../shared/index.js";
+import { selectedTargetForContextEndpoint } from "./dockerTargetBinding.js";
+const ERROR = "Docker context snapshot failed";
+const MAX_INSPECTION_BYTES = 32_768;
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const TLS_FILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u;
+let snapshotRemove = rm;
+/** Test-only seam for deterministic cleanup failure coverage. */
+export const setDockerContextSnapshotRemoveForTests = (replacement) => {
+    const previous = snapshotRemove;
+    snapshotRemove = replacement;
+    return () => { snapshotRemove = previous; };
+};
+const fail = () => { throw new SpawnfileError("runtime_error", ERROR); };
+const exactRecord = (raw) => raw !== null && typeof raw === "object" && !Array.isArray(raw)
+    && Object.getPrototypeOf(raw) === Object.prototype;
+const exactKeys = (value, expected) => {
+    const actual = Object.keys(value).sort();
+    const sorted = [...expected].sort();
+    return actual.length === sorted.length && actual.every((key, index) => key === sorted[index]);
+};
+const bounded = (value) => typeof value === "string"
+    && Buffer.byteLength(value, "utf8") <= MAX_INSPECTION_BYTES;
+const parseContextInspection = (stdout, context) => {
+    if (!bounded(stdout))
+        return fail();
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return fail();
+    }
+    if (!Array.isArray(raw) || raw.length !== 1 || !exactRecord(raw[0]))
+        return fail();
+    const value = raw[0];
+    if (!exactKeys(value, ["Endpoints", "Metadata", "Name", "Storage", "TLSMaterial"])
+        || value.Name !== context || !exactRecord(value.Endpoints) || !exactRecord(value.Metadata)
+        || !exactRecord(value.Storage) || !exactRecord(value.TLSMaterial)
+        || !exactKeys(value.Endpoints, ["docker"])
+        || !(exactKeys(value.TLSMaterial, []) || exactKeys(value.TLSMaterial, ["docker"]))
+        || !exactKeys(value.Storage, ["MetadataPath", "TLSPath"]))
+        return fail();
+    const endpoint = value.Endpoints.docker;
+    const tlsFiles = value.TLSMaterial.docker ?? [];
+    if (!exactRecord(endpoint) || !exactKeys(endpoint, ["Host", "SkipTLSVerify"])
+        || typeof endpoint.Host !== "string" || typeof endpoint.SkipTLSVerify !== "boolean"
+        || !Array.isArray(tlsFiles) || tlsFiles.length > 8
+        || new Set(tlsFiles).size !== tlsFiles.length
+        || tlsFiles.some((item) => typeof item !== "string" || !TLS_FILE_PATTERN.test(item)))
+        return fail();
+    const exactEndpoint = Object.freeze({ Host: endpoint.Host, SkipTLSVerify: endpoint.SkipTLSVerify });
+    const tlsPath = value.Storage.TLSPath;
+    if (tlsFiles.length === 0)
+        return Object.freeze({ endpoint: exactEndpoint, tlsFiles: Object.freeze([]), tlsPath: null });
+    if (typeof tlsPath !== "string" || tlsPath.length === 0 || Buffer.byteLength(tlsPath, "utf8") > 4_096)
+        return fail();
+    return Object.freeze({ endpoint: exactEndpoint, tlsFiles: Object.freeze([...tlsFiles]), tlsPath });
+};
+const copyStableTlsFile = async (source, destination) => {
+    let handle;
+    try {
+        handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const initial = await handle.stat();
+        if (!initial.isFile() || initial.size > 65_536)
+            return fail();
+        const bytes = await handle.readFile();
+        const current = await handle.stat();
+        if (!current.isFile() || current.size !== initial.size || bytes.length !== initial.size)
+            return fail();
+        await writeFile(destination, bytes, { encoding: undefined, flag: "wx", mode: 0o600 });
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+const requirePrivateDirectory = async (directory) => {
+    try {
+        const stats = await lstat(directory);
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            return fail();
+    }
+    catch {
+        return fail();
+    }
+};
+const removeSnapshotRoot = async (root) => {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            await snapshotRemove(root, { force: true, recursive: true });
+            return;
+        }
+        catch {
+            if (attempt === 2)
+                return fail();
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+    }
+};
+/**
+ * Privately recreates one named Docker context without placing its endpoint or
+ * TLS options in argv. The synthetic config is short-lived and never exported.
+ */
+export const createDockerContextSnapshot = async (input) => {
+    if (!CONTEXT_PATTERN.test(input.context) || !Number.isSafeInteger(input.timeoutMs)
+        || input.timeoutMs < 1 || input.timeoutMs > 120_000)
+        return fail();
+    let root;
+    try {
+        const result = await input.executor("docker", ["context", "inspect", input.context], { timeout: input.timeoutMs });
+        if (!result || result.stderr !== "" || !bounded(result.stdout))
+            return fail();
+        const source = parseContextInspection(result.stdout, input.context);
+        const selected = selectedTargetForContextEndpoint(input.context, source.endpoint.Host);
+        if (selected.fingerprint !== input.selectedTarget.fingerprint || selected.handle !== input.selectedTarget.handle)
+            return fail();
+        root = await mkdtemp(path.join(os.tmpdir(), "spawnfile-docker-context-"));
+        const synthetic = `spfn_${randomUUID().replaceAll("-", "")}`;
+        const contextId = createHash("sha256").update(synthetic, "utf8").digest("hex");
+        const metaDirectory = path.join(root, "contexts", "meta", contextId);
+        const tlsDirectory = path.join(root, "contexts", "tls", contextId, "docker");
+        await mkdir(metaDirectory, { recursive: true, mode: 0o700 });
+        await mkdir(tlsDirectory, { recursive: true, mode: 0o700 });
+        const meta = JSON.stringify({ Endpoints: { docker: source.endpoint }, Metadata: {}, Name: synthetic });
+        await writeFile(path.join(metaDirectory, "meta.json"), meta, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        if (source.tlsPath) {
+            await requirePrivateDirectory(source.tlsPath);
+            await requirePrivateDirectory(path.join(source.tlsPath, "docker"));
+            for (const file of source.tlsFiles) {
+                await copyStableTlsFile(path.join(source.tlsPath, "docker", file), path.join(tlsDirectory, file));
+            }
+        }
+        const args = Object.freeze(["--config", root, "--context", synthetic]);
+        let disposed = false;
+        return Object.freeze({
+            args,
+            dispose: async () => {
+                if (disposed)
+                    return;
+                await removeSnapshotRoot(root);
+                disposed = true;
+            }
+        });
+    }
+    catch {
+        if (root)
+            await removeSnapshotRoot(root);
+        return fail();
+    }
+};

package/dist/target/dockerEndpointFingerprint.d.ts

@@ -0,0 +1 @@
+export declare const createEndpointFingerprint: (endpoint: string) => string;

package/dist/target/dockerEndpointFingerprint.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+import { SpawnfileError } from "../shared/index.js";
+export const createEndpointFingerprint = (endpoint) => {
+    const normalized = endpoint.trim();
+    if (normalized.length === 0) {
+        throw new SpawnfileError("validation_error", "Deployment target endpoint must not be empty");
+    }
+    return `sha256:${createHash("sha256").update(normalized).digest("hex").slice(0, 32)}`;
+};

package/dist/target/dockerPreparedArtifact.d.ts

@@ -0,0 +1,48 @@
+import { type TargetResourceReceipt, type TargetResourceRequest } from "./contracts.js";
+import { type TargetLocalBundlePrivateMapping, type TargetLocalBundleStore } from "./containerBundleStore.js";
+import { type DockerTargetLocalBundleBuilder } from "./containerBundle.js";
+import { type DockerConfigArtifactIdentityBinding, type DockerArtifactIdentityStore } from "./dockerArtifactsProvider.js";
+import { type TargetJournalStore } from "./journal.js";
+export declare const DOCKER_PREPARED_ARTIFACT_ERROR = "Docker artifact resolution failed";
+type ArtifactRequest = Extract<TargetResourceRequest, {
+    operation: "resolve_world_artifact";
+}>;
+type ArtifactResult = {
+    readonly receipt: TargetResourceReceipt;
+    readonly receiptBytes: string;
+};
+export interface PreparedArtifactAuthorityMapping {
+    readonly archive_digest: string;
+    readonly artifact_manifest_digest: string;
+    readonly base_image_config_digest: string;
+    readonly build_policy_digest: string;
+    readonly bundle_digest: string;
+    readonly entrypoint: string;
+    readonly launcher_digest: string;
+    readonly network_alias: string;
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+    readonly platform_digest: string;
+}
+export interface DockerPreparedArtifactOperations {
+    execute(raw: unknown): Promise<ArtifactResult>;
+}
+/**
+ * Reconstructs the prepared-image authority without ever substituting the
+ * later resolution claim for the preparation claim that minted its GC anchor.
+ */
+export declare const attestPreparedArtifactIdentity: (builder: DockerTargetLocalBundleBuilder, binding: DockerConfigArtifactIdentityBinding, prepared: TargetLocalBundlePrivateMapping, selectedTarget: ArtifactRequest["selected_target"]) => Promise<void>;
+/**
+ * Private target-default lowering.  It admits an already prepared local image
+ * only through the bundle store's exact selected-target/correlation lookup.
+ */
+export declare const createDockerPreparedArtifactOperations: (input: {
+    readonly identityStore: DockerArtifactIdentityStore;
+    readonly builder: DockerTargetLocalBundleBuilder;
+    readonly journal: TargetJournalStore;
+    readonly mapping: PreparedArtifactAuthorityMapping;
+    readonly store: TargetLocalBundleStore;
+}) => DockerPreparedArtifactOperations;
+export {};

package/dist/target/dockerPreparedArtifact.js

@@ -0,0 +1,131 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseTargetResourceRequest } from "./contracts.js";
+import { attestTargetLocalBundleMapping } from "./containerBundle.js";
+import { createDockerConfigArtifactSpec } from "./dockerArtifactsProvider.js";
+import { createTargetReceiptDigest } from "./handles.js";
+export const DOCKER_PREPARED_ARTIFACT_ERROR = "Docker artifact resolution failed";
+const fail = () => { throw new SpawnfileError("runtime_error", DOCKER_PREPARED_ARTIFACT_ERROR); };
+/**
+ * Reconstructs the prepared-image authority without ever substituting the
+ * later resolution claim for the preparation claim that minted its GC anchor.
+ */
+export const attestPreparedArtifactIdentity = async (builder, binding, prepared, selectedTarget) => {
+    const expected = {
+        archive_digest: binding.archiveDigest,
+        artifact_digest: binding.artifactManifestDigest,
+        base_image_config_digest: binding.baseImageConfigDigest,
+        build_policy_digest: binding.buildPolicyDigest,
+        bundle_digest: binding.bundleDigest,
+        config_id: binding.configId,
+        daemon_epoch: binding.daemonEpoch,
+        entrypoint: binding.entrypoint,
+        gc_tag: binding.gcTag,
+        identity_kind: binding.identityKind,
+        launcher_digest: binding.launcherDigest,
+        network_alias: binding.networkAlias,
+        operation_handle: binding.preparedOperationHandle,
+        platform: binding.platform,
+        platform_digest: binding.platformDigest,
+        request_digest: binding.preparedRequestDigest,
+        selected_target: selectedTarget
+    };
+    if (JSON.stringify(prepared) !== JSON.stringify(expected))
+        return fail();
+    await attestTargetLocalBundleMapping(builder, prepared);
+};
+const request = (raw) => {
+    const parsed = parseTargetResourceRequest(raw);
+    if (parsed.operation !== "resolve_world_artifact")
+        return fail();
+    return parsed;
+};
+const receipt = async (input) => {
+    const raw = {
+        cleanup_state: "not_requested", descriptor_digest: input.request.descriptor_digest,
+        export_state: "not_requested", labels: Object.entries(input.labels).map(([key, value]) => ({ key, value })),
+        operation: input.request.operation, operation_handle: input.claim.operationHandle,
+        receipt_digest: `sha256:${"0".repeat(64)}`, request_digest: input.claim.requestDigest,
+        result_handle: input.resultHandle, resulting_revision: (await input.journal.read()).revision + 1,
+        run_id: input.request.run_id, selected_target: input.request.selected_target,
+        version: "spawnfile.target-resource.receipt.v1"
+    };
+    return { ...raw, receipt_digest: createTargetReceiptDigest(raw) };
+};
+/**
+ * Private target-default lowering.  It admits an already prepared local image
+ * only through the bundle store's exact selected-target/correlation lookup.
+ */
+export const createDockerPreparedArtifactOperations = (input) => {
+    if (!input?.identityStore || !input.builder || !input.journal || !input.mapping || !input.store)
+        fail();
+    const execute = async (raw) => {
+        try {
+            const value = request(raw);
+            if (value.artifact_manifest_digest !== input.mapping.artifact_manifest_digest)
+                return fail();
+            const reservation = await input.journal.reserve(value);
+            if (reservation.kind === "replay")
+                return { receipt: reservation.receipt, receiptBytes: reservation.receiptBytes };
+            const prepared = await input.store.resolvePrepared({
+                artifact_digest: value.artifact_manifest_digest,
+                build_policy_digest: input.mapping.build_policy_digest,
+                bundle_digest: input.mapping.bundle_digest,
+                selected_target: value.selected_target
+            });
+            if (!prepared || prepared.request.selected_target.handle !== value.selected_target.handle
+                || prepared.request.selected_target.fingerprint !== value.selected_target.fingerprint
+                || prepared.request.artifact_digest !== value.artifact_manifest_digest
+                || prepared.mapping.archive_digest !== input.mapping.archive_digest
+                || prepared.mapping.base_image_config_digest !== input.mapping.base_image_config_digest
+                || prepared.request.bundle_digest !== input.mapping.bundle_digest
+                || prepared.request.build_policy_digest !== input.mapping.build_policy_digest
+                || prepared.mapping.entrypoint !== input.mapping.entrypoint
+                || prepared.request.launcher_digest !== input.mapping.launcher_digest
+                || prepared.request.network_alias !== input.mapping.network_alias
+                || prepared.request.platform_digest !== input.mapping.platform_digest
+                || JSON.stringify(prepared.request.platform) !== JSON.stringify(input.mapping.platform)
+                || prepared.mapping.artifact_digest !== value.artifact_manifest_digest
+                || prepared.mapping.build_policy_digest !== input.mapping.build_policy_digest
+                || prepared.mapping.bundle_digest !== input.mapping.bundle_digest
+                || prepared.mapping.launcher_digest !== input.mapping.launcher_digest
+                || prepared.mapping.network_alias !== input.mapping.network_alias
+                || prepared.mapping.platform_digest !== input.mapping.platform_digest
+                || JSON.stringify(prepared.mapping.platform) !== JSON.stringify(input.mapping.platform))
+                return fail();
+            await attestTargetLocalBundleMapping(input.builder, prepared.mapping);
+            const spec = createDockerConfigArtifactSpec({
+                archiveDigest: input.mapping.archive_digest,
+                artifactManifestDigest: value.artifact_manifest_digest,
+                baseImageConfigDigest: input.mapping.base_image_config_digest,
+                buildPolicyDigest: input.mapping.build_policy_digest,
+                bundleDigest: input.mapping.bundle_digest, configId: prepared.mapping.config_id,
+                daemonEpoch: prepared.mapping.daemon_epoch, entrypoint: input.mapping.entrypoint,
+                launcherDigest: input.mapping.launcher_digest, networkAlias: input.mapping.network_alias,
+                operationHandle: reservation.claim.operationHandle, requestDigest: reservation.claim.requestDigest,
+                selectedTargetHandle: value.selected_target.handle, platform: input.mapping.platform,
+                platformDigest: input.mapping.platform_digest
+            });
+            await input.identityStore.bind({
+                archiveDigest: input.mapping.archive_digest,
+                artifactManifestDigest: value.artifact_manifest_digest,
+                baseImageConfigDigest: input.mapping.base_image_config_digest,
+                buildPolicyDigest: input.mapping.build_policy_digest,
+                bundleDigest: input.mapping.bundle_digest, configId: prepared.mapping.config_id,
+                daemonEpoch: prepared.mapping.daemon_epoch, entrypoint: input.mapping.entrypoint, gcTag: prepared.mapping.gc_tag,
+                identityKind: "docker_image_config_digest", operationHandle: reservation.claim.operationHandle,
+                launcherDigest: input.mapping.launcher_digest, networkAlias: input.mapping.network_alias,
+                preparedOperationHandle: prepared.mapping.operation_handle,
+                preparedRequestDigest: prepared.mapping.request_digest,
+                requestDigest: reservation.claim.requestDigest, resultHandle: spec.resultHandle,
+                selectedTargetHandle: value.selected_target.handle, platform: input.mapping.platform,
+                platformDigest: input.mapping.platform_digest
+            });
+            return input.journal.complete(reservation.claim, await receipt({ claim: reservation.claim,
+                journal: input.journal, labels: spec.labels, request: value, resultHandle: spec.resultHandle }));
+        }
+        catch {
+            return fail();
+        }
+    };
+    return Object.freeze({ execute });
+};

package/dist/target/dockerProjectionJson.d.ts

@@ -0,0 +1 @@
+export declare const parseDuplicateFreeDockerProjection: (source: string) => unknown | null;