spawnfile 0.1.13 → 0.1.17

package/dist/target/containerBundle.js

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { Buffer } from "node:buffer";
+import { parseContainerBundleArchive, validateContainerBundleEnvelope } from "./containerBundleArchive.js";
+import { createTargetLocalBundleReceiptDigest, createTargetLocalBundleRequestDigest, parseTargetLocalBundlePrepareRequest } from "./containerBundleContracts.js";
+import { parseOpaqueTargetHandle } from "./contracts.js";
+export const TARGET_LOCAL_CONTAINER_BUNDLE_ERROR = "Target-local container bundle preparation failed";
+const fail = () => { throw new Error(TARGET_LOCAL_CONTAINER_BUNDLE_ERROR); };
+export const targetLocalBundleGcTag = (requestDigest) => `spfb_${createHash("sha256")
+    .update("spawnfile.target-local-container-bundle.gc-tag.v1\0", "utf8").update(requestDigest).digest("hex").slice(0, 58)}`;
+export const targetLocalBundleLabels = (plan, daemonEpoch, requestDigest) => Object.freeze({
+    spawnfile_target_bundle_v1_archive: plan.archive_digest,
+    spawnfile_target_bundle_v1_alias: plan.network_alias,
+    spawnfile_target_bundle_v1_artifact: plan.artifact_digest,
+    spawnfile_target_bundle_v1_base: plan.base_image_config_digest,
+    spawnfile_target_bundle_v1_bundle: plan.bundle_digest,
+    spawnfile_target_bundle_v1_daemon: daemonEpoch,
+    spawnfile_target_bundle_v1_entrypoint: plan.entrypoint,
+    spawnfile_target_bundle_v1_launcher: plan.launcher_digest,
+    spawnfile_target_bundle_v1_platform: plan.platform_digest,
+    spawnfile_target_bundle_v1_policy: plan.build_policy_digest,
+    spawnfile_target_bundle_v1_request: requestDigest,
+    spawnfile_target_bundle_v1_version: "v1"
+});
+const exactLabels = (actual, expected) => Object.keys(actual).length === Object.keys(expected).length && Object.entries(expected).every(([key, value]) => actual[key] === value);
+const receipt = (request, requestDigest, operation, mapping) => {
+    const raw = { archive_digest: request.archive_digest, artifact_digest: request.artifact_digest,
+        build_policy_digest: request.build_policy_digest, bundle_digest: request.bundle_digest,
+        launcher_digest: request.launcher_digest, mapping_handle: mapping, network_alias: request.network_alias,
+        operation_handle: operation, platform: request.platform, platform_digest: request.platform_digest,
+        receipt_digest: `sha256:${"0".repeat(64)}`, request_digest: requestDigest,
+        selected_target: request.selected_target, version: "spawnfile.target-local-container-bundle.prepare-receipt.v1" };
+    return { ...raw, mapping_handle: parseOpaqueTargetHandle(mapping),
+        operation_handle: parseOpaqueTargetHandle(operation), receipt_digest: createTargetLocalBundleReceiptDigest(raw) };
+};
+const mappingHandle = (operation, requestDigest) => `opaque_${createHash("sha256")
+    .update("spawnfile.target-local-container-bundle.mapping.v1\0", "utf8").update(`${operation}\0${requestDigest}`, "utf8").digest("hex")}`;
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const mapping = (plan, request, daemonEpoch, reservation, configId) => ({
+    archive_digest: plan.archive_digest, artifact_digest: plan.artifact_digest,
+    base_image_config_digest: plan.base_image_config_digest, build_policy_digest: plan.build_policy_digest,
+    bundle_digest: plan.bundle_digest, config_id: configId, daemon_epoch: daemonEpoch,
+    entrypoint: plan.entrypoint, gc_tag: targetLocalBundleGcTag(reservation.request_digest), identity_kind: "docker_image_config_digest",
+    launcher_digest: plan.launcher_digest, network_alias: plan.network_alias,
+    operation_handle: reservation.operation_handle, platform: plan.platform, platform_digest: plan.platform_digest,
+    request_digest: reservation.request_digest, selected_target: request.selected_target
+});
+const compatibleMapping = (value, plan, request, requestDigest) => value.request_digest === requestDigest && value.archive_digest === plan.archive_digest && value.artifact_digest === plan.artifact_digest
+    && value.base_image_config_digest === plan.base_image_config_digest && value.build_policy_digest === plan.build_policy_digest
+    && value.bundle_digest === plan.bundle_digest && value.entrypoint === plan.entrypoint && value.launcher_digest === plan.launcher_digest
+    && value.network_alias === plan.network_alias && value.platform_digest === plan.platform_digest
+    && same(value.platform, plan.platform) && same(value.selected_target, request.selected_target);
+/** Re-attests the exact private anchor before an image config becomes usable. */
+export const attestTargetLocalBundleMapping = async (builder, value) => {
+    if (value.gc_tag !== targetLocalBundleGcTag(value.request_digest))
+        fail();
+    const first = await builder.attestTarget({ selected_target: value.selected_target });
+    if (!first || first.daemon_epoch !== value.daemon_epoch)
+        fail();
+    const expected = targetLocalBundleLabels(value, value.daemon_epoch, value.request_digest);
+    const inspected = await builder.inspect({ config_id: value.config_id, gc_tag: value.gc_tag, labels: expected, platform: value.platform });
+    if (!inspected || inspected.config_id !== value.config_id || !exactLabels(inspected.labels, expected)
+        || !same(inspected.platform, value.platform))
+        fail();
+    const second = await builder.attestTarget({ selected_target: value.selected_target });
+    if (!second || second.daemon_epoch !== value.daemon_epoch)
+        fail();
+};
+export const createTargetLocalContainerBundleOperations = (input) => {
+    if (!input?.authority || typeof input.authority.authorize !== "function" || !input.builder || !input.store)
+        fail();
+    const attest = async (request) => {
+        const result = await input.builder.attestTarget({ selected_target: request.selected_target });
+        if (!result || !/^sha256:[a-f0-9]{64}$/u.test(result.daemon_epoch))
+            fail();
+        return result.daemon_epoch;
+    };
+    const withHeartbeat = async (lease, action) => {
+        let current = lease;
+        let failure;
+        let renewing = Promise.resolve();
+        const beat = () => { renewing = renewing.then(async () => { try {
+            current = await input.store.renew({ lease: current });
+        }
+        catch (error) {
+            failure = error;
+        } }); };
+        const timer = setInterval(beat, 5_000);
+        try {
+            const value = await action();
+            await renewing;
+            if (failure)
+                fail();
+            return { lease: current, value };
+        }
+        finally {
+            clearInterval(timer);
+        }
+    };
+    const replayAnchor = async (value, plan, request) => {
+        const privateMapping = value.mapping;
+        if (!compatibleMapping(privateMapping, plan, request, value.receipt.request_digest)
+            || privateMapping.operation_handle !== value.receipt.operation_handle
+            || privateMapping.gc_tag !== targetLocalBundleGcTag(privateMapping.request_digest))
+            fail();
+        const first = await input.builder.attestTarget({ selected_target: privateMapping.selected_target });
+        if (!first || first.daemon_epoch !== privateMapping.daemon_epoch)
+            fail();
+        const expected = targetLocalBundleLabels(privateMapping, privateMapping.daemon_epoch, privateMapping.request_digest);
+        const inspected = await input.builder.inspectAnchor({ gc_tag: privateMapping.gc_tag, labels: expected, platform: privateMapping.platform });
+        const second = await input.builder.attestTarget({ selected_target: privateMapping.selected_target });
+        if (!second || second.daemon_epoch !== privateMapping.daemon_epoch)
+            fail();
+        if (inspected === "missing")
+            return "missing";
+        if (!inspected || inspected.config_id !== privateMapping.config_id || !exactLabels(inspected.labels, expected)
+            || !same(inspected.platform, privateMapping.platform))
+            fail();
+        return "intact";
+    };
+    const reserveAttested = async (request, plan, joinPending) => {
+        let reservation = await input.store.reserve(request);
+        let mayJoin = joinPending;
+        for (let attempt = 0; attempt < 4; attempt += 1) {
+            if (reservation.kind === "replay") {
+                if (await replayAnchor(reservation, plan, request) === "intact")
+                    return reservation;
+                reservation = await input.store.retryMissingCompleted({ generation: reservation.generation,
+                    operation_handle: reservation.receipt.operation_handle, request_digest: reservation.receipt.request_digest });
+                mayJoin = true;
+                continue;
+            }
+            if (reservation.kind === "pending" && mayJoin) {
+                const waited = await input.store.awaitReplay({ idempotency_key: request.idempotency_key,
+                    maximum_wait_ms: 30_000, request_digest: createTargetLocalBundleRequestDigest(request) });
+                if (waited.status !== "completed")
+                    return reservation;
+                reservation = await input.store.reserve(request);
+                continue;
+            }
+            return reservation;
+        }
+        return fail();
+    };
+    const buildOwner = async (request, plan, owner) => {
+        const archive = parseContainerBundleArchive(Buffer.from(request.archive_base64, "base64"), request.archive_entries, request.archive_digest);
+        validateContainerBundleEnvelope(archive, plan);
+        let buildLease = await input.store.beginBuild({ lease: owner.lease });
+        const daemonEpoch = await attest(request);
+        const expected = targetLocalBundleLabels(plan, daemonEpoch, owner.request_digest);
+        buildLease = await input.store.renew({ lease: buildLease });
+        const heartbeated = await withHeartbeat(buildLease, () => input.builder.build({ archive, base_image_config_digest: plan.base_image_config_digest,
+            entrypoint: plan.entrypoint, gc_tag: targetLocalBundleGcTag(owner.request_digest), labels: expected, platform: plan.platform }));
+        buildLease = heartbeated.lease;
+        const built = heartbeated.value;
+        buildLease = await input.store.renew({ lease: buildLease });
+        if (!/^sha256:[a-f0-9]{64}$/u.test(built.config_id) || !exactLabels(built.labels, expected) || !same(built.platform, plan.platform)
+            || await attest(request) !== daemonEpoch) {
+            await input.store.markIncomplete({ lease: buildLease, operation_handle: owner.operation_handle, request_digest: owner.request_digest });
+            fail();
+        }
+        const privateMapping = mapping(plan, request, daemonEpoch, owner, built.config_id);
+        const postbuildLease = await input.store.stagePostbuild({ lease: buildLease, mapping: privateMapping });
+        try {
+            await attestTargetLocalBundleMapping(input.builder, privateMapping);
+        }
+        catch {
+            await input.store.markIncomplete({ lease: postbuildLease, operation_handle: owner.operation_handle, request_digest: owner.request_digest });
+            fail();
+        }
+        return input.store.complete({ lease: postbuildLease, mapping: privateMapping,
+            receipt: receipt(request, owner.request_digest, owner.operation_handle, mappingHandle(owner.operation_handle, owner.request_digest)) });
+    };
+    const completePostbuild = async (request, plan, owner) => {
+        const recovered = owner.mapping;
+        if (recovered === undefined || owner.state !== "postbuild")
+            return fail();
+        const daemonEpoch = await attest(request);
+        if (!compatibleMapping(recovered, plan, request, owner.request_digest) || recovered.daemon_epoch !== daemonEpoch)
+            fail();
+        await attestTargetLocalBundleMapping(input.builder, recovered);
+        return input.store.complete({ lease: owner.lease, mapping: recovered,
+            receipt: receipt(request, owner.request_digest, owner.operation_handle, mappingHandle(owner.operation_handle, owner.request_digest)) });
+    };
+    const recover = async (raw) => {
+        const request = parseTargetLocalBundlePrepareRequest(raw);
+        const plan = input.authority.authorize(request);
+        const reservation = await reserveAttested(request, plan, false);
+        if (reservation.kind === "replay")
+            return reservation.receipt;
+        if (reservation.kind !== "owner")
+            fail();
+        const owner = reservation;
+        if (owner.state === "prebuild")
+            return buildOwner(request, plan, owner);
+        const recovered = owner.mapping;
+        if (owner.state === "inflight" && recovered === undefined) {
+            const daemonEpoch = await attest(request);
+            const expected = targetLocalBundleLabels(plan, daemonEpoch, owner.request_digest);
+            const anchor = await input.builder.inspectAnchor({ gc_tag: targetLocalBundleGcTag(owner.request_digest), labels: expected, platform: plan.platform });
+            if (anchor && anchor !== "missing") {
+                const adopted = mapping(plan, request, daemonEpoch, owner, anchor.config_id);
+                const postbuild = await input.store.stagePostbuild({ lease: owner.lease, mapping: adopted });
+                await attestTargetLocalBundleMapping(input.builder, adopted);
+                return input.store.complete({ lease: postbuild, mapping: adopted,
+                    receipt: receipt(request, owner.request_digest, owner.operation_handle, mappingHandle(owner.operation_handle, owner.request_digest)) });
+            }
+            if (anchor !== "missing")
+                fail(); // Existing but non-exact is ambiguous drift, never a retry.
+            const retryLease = await input.store.retryPrebuild({ lease: owner.lease });
+            return buildOwner(request, plan, { ...owner, lease: retryLease, state: "prebuild" });
+        }
+        return completePostbuild(request, plan, owner);
+    };
+    const prepare = async (raw) => {
+        const request = parseTargetLocalBundlePrepareRequest(raw);
+        const plan = input.authority.authorize(request);
+        const reservation = await reserveAttested(request, plan, true);
+        if (reservation.kind === "replay")
+            return reservation.receipt;
+        if (reservation.kind !== "owner")
+            fail();
+        const owner = reservation;
+        if (owner.state === "postbuild")
+            return completePostbuild(request, plan, owner);
+        /* An expired/reclaimed inflight record is ambiguous; never erase it from a fresh caller. */
+        if (owner.state !== "prebuild")
+            fail();
+        return buildOwner(request, plan, owner);
+    };
+    /* Join only byte-identical work inside this process; the durable store remains the authority across restarts. */
+    const active = new Map();
+    const joinedPrepare = async (raw) => {
+        const key = createTargetLocalBundleRequestDigest(parseTargetLocalBundlePrepareRequest(raw));
+        const prior = active.get(key);
+        if (prior)
+            return prior;
+        const task = prepare(raw).finally(() => { if (active.get(key) === task)
+            active.delete(key); });
+        active.set(key, task);
+        return task;
+    };
+    return Object.freeze({ lookup: (value) => input.store.lookup(value), prepare: joinedPrepare, recover });
+};

package/dist/target/containerBundleArchive.d.ts

@@ -0,0 +1,31 @@
+export interface ContainerBundleArchiveEntry {
+    readonly bytes: Uint8Array;
+    readonly path: string;
+}
+export interface ParsedContainerBundleArchive {
+    readonly bytes: Uint8Array;
+    readonly entries: readonly ContainerBundleArchiveEntry[];
+}
+export interface ContainerBundleEnvelopeClaims {
+    readonly artifact_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;
+}
+/** Validates an uncompressed canonical USTAR bundle before Docker ever receives it. */
+export declare const parseContainerBundleArchive: (raw: unknown, allowedPaths: readonly string[], expectedDigest: string) => ParsedContainerBundleArchive;
+/**
+ * The versioned preparation request is the sealed deployment envelope.
+ * The archive digest already commits every byte. The artifact digest is an
+ * owner-defined semantic identity (for example, a manifest digest), while the
+ * launcher is the one generic executable role whose raw bytes Spawnfile can
+ * and must verify without interpreting provider-private contents.
+ */
+export declare const validateContainerBundleEnvelope: (archive: ParsedContainerBundleArchive, claims: ContainerBundleEnvelopeClaims) => void;

package/dist/target/containerBundleArchive.js

@@ -0,0 +1,140 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+const BLOCK = 512;
+const MAX_BYTES = 4_194_304;
+const fail = () => { throw new Error("Container bundle archive failed"); };
+const zero = (value) => value.every((byte) => byte === 0);
+const text = (value) => {
+    const nul = value.indexOf(0);
+    const end = nul < 0 ? value.length : nul;
+    if (nul >= 0 && !zero(value.subarray(nul)))
+        return fail();
+    const result = Buffer.from(value.subarray(0, end)).toString("utf8");
+    if (!Buffer.from(result, "utf8").equals(Buffer.from(value.subarray(0, end))))
+        return fail();
+    return result;
+};
+const rawSha = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const octal = (value) => {
+    if (value.at(-1) !== 0 || value.subarray(0, -1).some((byte) => byte < 48 || byte > 55))
+        return fail();
+    const parsed = Number.parseInt(Buffer.from(value.subarray(0, -1)).toString("ascii"), 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        return fail();
+    return parsed;
+};
+const canonicalOctal = (value) => {
+    const parsed = octal(value);
+    if (!Buffer.from(`${parsed.toString(8).padStart(value.byteLength - 1, "0")}\0`, "ascii").equals(Buffer.from(value)))
+        return fail();
+    return parsed;
+};
+const checksum = (header) => {
+    const field = header.subarray(148, 156);
+    /* POSIX USTAR permits both its traditional six-digit NUL-space spelling
+     * and a seven-digit NUL-terminated field. Accept neither padding nor any
+     * other checksum representation. */
+    const traditional = field[6] === 0 && field[7] === 0x20 && field.subarray(0, 6).every((byte) => byte >= 48 && byte <= 55);
+    const nulTerminated = field[7] === 0 && field.subarray(0, 7).every((byte) => byte >= 48 && byte <= 55);
+    if (!traditional && !nulTerminated)
+        return fail();
+    const claimed = Number.parseInt(Buffer.from(field.subarray(0, traditional ? 6 : 7)).toString("ascii"), 8);
+    let actual = 0;
+    for (let index = 0; index < BLOCK; index += 1)
+        actual += index >= 148 && index < 156 ? 0x20 : header[index];
+    if (claimed !== actual)
+        return fail();
+    return claimed;
+};
+const safePath = (raw) => {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/u.test(raw) || raw.includes("//")
+        || raw.split("/").some((part) => part === "." || part === ".."))
+        return fail();
+    return raw;
+};
+const canonicalPath = (name, prefix) => {
+    if (name.length === 0 || prefix.endsWith("/"))
+        return fail();
+    const joined = safePath(prefix ? `${prefix}/${name}` : name);
+    if (joined.length <= 100) {
+        if (prefix || name !== joined)
+            return fail();
+        return joined;
+    }
+    const split = joined.lastIndexOf("/");
+    if (split < 1 || joined.slice(0, split) !== prefix || joined.slice(split + 1) !== name
+        || Buffer.byteLength(prefix, "utf8") > 155 || Buffer.byteLength(name, "utf8") > 100)
+        return fail();
+    return joined;
+};
+const canonicalAllowed = (paths) => {
+    if (paths.length < 1 || paths.length > 32)
+        return fail();
+    const normalized = paths.map(safePath);
+    if (normalized.some((value, index) => index > 0 && normalized[index - 1] >= value))
+        return fail();
+    return normalized;
+};
+/** Validates an uncompressed canonical USTAR bundle before Docker ever receives it. */
+export const parseContainerBundleArchive = (raw, allowedPaths, expectedDigest) => {
+    if (!(raw instanceof Uint8Array) || raw.byteLength < BLOCK * 2 || raw.byteLength > MAX_BYTES || raw.byteLength % BLOCK !== 0
+        || !/^sha256:[a-f0-9]{64}$/u.test(expectedDigest)
+        || `sha256:${createHash("sha256").update(raw).digest("hex")}` !== expectedDigest)
+        return fail();
+    const expected = canonicalAllowed(allowedPaths);
+    const entries = [];
+    let offset = 0;
+    while (offset < raw.byteLength) {
+        const header = raw.subarray(offset, offset + BLOCK);
+        offset += BLOCK;
+        if (zero(header)) {
+            if (entries.length === 0 || offset + BLOCK !== raw.byteLength || !zero(raw.subarray(offset, offset + BLOCK)))
+                return fail();
+            if (entries.length !== expected.length)
+                return fail();
+            return Object.freeze({ bytes: new Uint8Array(raw), entries: Object.freeze(entries) });
+        }
+        if (!Buffer.from(header.subarray(257, 263)).equals(Buffer.from("ustar\0", "ascii"))
+            || !Buffer.from(header.subarray(263, 265)).equals(Buffer.from("00", "ascii"))
+            || !zero(header.subarray(157, 257)) || !zero(header.subarray(500, 512)))
+            return fail();
+        checksum(header);
+        if (canonicalOctal(header.subarray(100, 108)) !== 0o644 || canonicalOctal(header.subarray(108, 116)) !== 0
+            || canonicalOctal(header.subarray(116, 124)) !== 0 || canonicalOctal(header.subarray(136, 148)) !== 0
+            || !zero(header.subarray(329, 345)) || header[156] !== 48
+            || text(header.subarray(265, 297)) !== "" || text(header.subarray(297, 329)) !== "")
+            return fail();
+        const name = text(header.subarray(0, 100));
+        const prefix = text(header.subarray(345, 500));
+        const path = canonicalPath(name, prefix);
+        if (path !== expected[entries.length])
+            return fail();
+        const size = canonicalOctal(header.subarray(124, 136));
+        const end = offset + size;
+        const padded = Math.ceil(size / BLOCK) * BLOCK;
+        if (end > raw.byteLength || offset + padded > raw.byteLength || !zero(raw.subarray(end, offset + padded)))
+            return fail();
+        entries.push(Object.freeze({ bytes: new Uint8Array(raw.subarray(offset, end)), path }));
+        offset += padded;
+    }
+    return fail();
+};
+/**
+ * The versioned preparation request is the sealed deployment envelope.
+ * The archive digest already commits every byte. The artifact digest is an
+ * owner-defined semantic identity (for example, a manifest digest), while the
+ * launcher is the one generic executable role whose raw bytes Spawnfile can
+ * and must verify without interpreting provider-private contents.
+ */
+export const validateContainerBundleEnvelope = (archive, claims) => {
+    try {
+        const launcher = archive.entries.find((item) => item.path === claims.entrypoint);
+        if (!launcher || rawSha(launcher.bytes) !== claims.launcher_digest
+            || !/^sha256:[a-f0-9]{64}$/u.test(claims.artifact_digest)
+            || claims.artifact_digest === claims.launcher_digest)
+            return fail();
+    }
+    catch {
+        return fail();
+    }
+};

package/dist/target/containerBundleAuthority.d.ts

@@ -0,0 +1,25 @@
+import type { TargetLocalBundlePrepareRequest } from "./containerBundleContracts.js";
+export interface ContainerBundleAllowlistEntry {
+    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 AuthorizedContainerBundlePlan extends ContainerBundleAllowlistEntry {
+    readonly artifact_digest: string;
+}
+export interface ContainerBundlePreparationAuthority {
+    /** Returns private build inputs only after the complete semantic tuple matches. */
+    authorize(request: TargetLocalBundlePrepareRequest): AuthorizedContainerBundlePlan;
+}
+/** A target may build only a complete, reviewed, target-local plan. */
+export declare const createContainerBundlePreparationAuthority: (entries: readonly ContainerBundleAllowlistEntry[]) => ContainerBundlePreparationAuthority;

package/dist/target/containerBundleAuthority.js

@@ -0,0 +1,65 @@
+import { deriveTargetLocalContainerBundlePolicy } from "./containerBundlePolicy.js";
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const fail = () => { throw new Error("Target-local container bundle authorization failed"); };
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const entry = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.getPrototypeOf(raw) !== Object.prototype)
+        return fail();
+    const descriptors = Object.getOwnPropertyDescriptors(raw);
+    if (Object.values(descriptors).some((value) => !value.enumerable || !("value" in value)))
+        return fail();
+    const value = Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, descriptor.value]));
+    if (Object.keys(value).sort().join("\0") !== "archive_digest\0artifact_manifest_digest\0base_image_config_digest\0build_policy_digest\0bundle_digest\0entrypoint\0launcher_digest\0network_alias\0platform\0platform_digest"
+        || !Object.values(value).filter((item) => typeof item === "string").every((item) => typeof item === "string")
+        || ![value.archive_digest, value.artifact_manifest_digest, value.base_image_config_digest, value.build_policy_digest,
+            value.bundle_digest, value.launcher_digest, value.platform_digest].every((item) => typeof item === "string" && DIGEST.test(item))
+        || typeof value.entrypoint !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,239}$/u.test(value.entrypoint)
+        || value.entrypoint.includes("//") || value.entrypoint.split("/").some((part) => part === "." || part === "..")
+        || typeof value.network_alias !== "string" || !/^[a-z][a-z0-9-]{0,62}$/u.test(value.network_alias)
+        || !value.platform || typeof value.platform !== "object" || Array.isArray(value.platform)
+        || Object.getPrototypeOf(value.platform) !== Object.prototype)
+        return fail();
+    const platform = value.platform;
+    if (Object.keys(platform).sort().join("\0") !== "architecture\0os"
+        || platform.os !== "linux" || (platform.architecture !== "amd64" && platform.architecture !== "arm64"))
+        return fail();
+    return Object.freeze({ archive_digest: value.archive_digest,
+        artifact_manifest_digest: value.artifact_manifest_digest,
+        base_image_config_digest: value.base_image_config_digest,
+        build_policy_digest: value.build_policy_digest, bundle_digest: value.bundle_digest,
+        entrypoint: value.entrypoint, launcher_digest: value.launcher_digest, network_alias: value.network_alias,
+        platform: Object.freeze({ architecture: platform.architecture, os: platform.os }),
+        platform_digest: value.platform_digest });
+};
+/** A target may build only a complete, reviewed, target-local plan. */
+export const createContainerBundlePreparationAuthority = (entries) => {
+    if (!Array.isArray(entries) || entries.length > 32)
+        return fail();
+    const allowed = Object.freeze(entries.map(entry));
+    if (new Set(allowed.map((value) => value.artifact_manifest_digest)).size !== allowed.length)
+        return fail();
+    const authorize = (request) => {
+        const matches = allowed.filter((value) => value.artifact_manifest_digest === request.artifact_digest
+            && value.archive_digest === request.archive_digest && value.build_policy_digest === request.build_policy_digest
+            && value.bundle_digest === request.bundle_digest && value.entrypoint === request.entrypoint
+            && value.launcher_digest === request.launcher_digest && value.network_alias === request.network_alias
+            && value.platform_digest === request.platform_digest && same(value.platform, request.platform));
+        if (matches.length !== 1)
+            return fail();
+        const authoritative = deriveTargetLocalContainerBundlePolicy({
+            archiveDigest: request.archive_digest,
+            artifactDigest: request.artifact_digest,
+            baseImageConfigDigest: matches[0].base_image_config_digest,
+            bundleDigest: request.bundle_digest,
+            entrypoint: request.entrypoint,
+            launcherDigest: request.launcher_digest,
+            networkAlias: request.network_alias,
+            platform: request.platform
+        });
+        if (authoritative.buildPolicyDigest !== request.build_policy_digest
+            || authoritative.platformDigest !== request.platform_digest)
+            return fail();
+        return Object.freeze({ ...matches[0], artifact_digest: request.artifact_digest });
+    };
+    return Object.freeze({ authorize });
+};

package/dist/target/containerBundleContracts.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+export declare const TARGET_LOCAL_BUNDLE_PREPARE_REQUEST_VERSION: "spawnfile.target-local-container-bundle.prepare-request.v1";
+export declare const TARGET_LOCAL_BUNDLE_PREPARE_RECEIPT_VERSION: "spawnfile.target-local-container-bundle.prepare-receipt.v1";
+export declare const TARGET_LOCAL_BUNDLE_LOOKUP_VERSION: "spawnfile.target-local-container-bundle.lookup.v1";
+export declare const targetLocalBundlePrepareRequestSchema: z.ZodObject<{
+    archive_base64: z.ZodString;
+    archive_digest: z.ZodString;
+    archive_entries: z.ZodArray<z.ZodString>;
+    artifact_digest: z.ZodString;
+    build_policy_digest: z.ZodString;
+    bundle_digest: z.ZodString;
+    entrypoint: z.ZodString;
+    idempotency_key: z.ZodString;
+    launcher_digest: z.ZodString;
+    network_alias: z.ZodString;
+    platform: z.ZodObject<{
+        architecture: z.ZodEnum<{
+            amd64: "amd64";
+            arm64: "arm64";
+        }>;
+        os: z.ZodLiteral<"linux">;
+    }, z.core.$strict>;
+    platform_digest: z.ZodString;
+    selected_target: z.ZodObject<{
+        fingerprint: z.ZodString;
+        handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.target-local-container-bundle.prepare-request.v1">;
+}, z.core.$strict>;
+export declare const targetLocalBundlePrepareReceiptSchema: z.ZodObject<{
+    archive_digest: z.ZodString;
+    artifact_digest: z.ZodString;
+    build_policy_digest: z.ZodString;
+    bundle_digest: z.ZodString;
+    launcher_digest: z.ZodString;
+    mapping_handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+    network_alias: z.ZodString;
+    operation_handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+    platform: z.ZodObject<{
+        architecture: z.ZodEnum<{
+            amd64: "amd64";
+            arm64: "arm64";
+        }>;
+        os: z.ZodLiteral<"linux">;
+    }, z.core.$strict>;
+    platform_digest: z.ZodString;
+    receipt_digest: z.ZodString;
+    request_digest: z.ZodString;
+    selected_target: z.ZodObject<{
+        fingerprint: z.ZodString;
+        handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.target-local-container-bundle.prepare-receipt.v1">;
+}, z.core.$strict>;
+export declare const targetLocalBundleLookupSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"not_applied">;
+    idempotency_key: z.ZodString;
+    request_digest: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.target-local-container-bundle.lookup.v1">;
+}, z.core.$strict>, z.ZodObject<{
+    operation_handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+    status: z.ZodLiteral<"pending">;
+    idempotency_key: z.ZodString;
+    request_digest: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.target-local-container-bundle.lookup.v1">;
+}, z.core.$strict>, z.ZodObject<{
+    operation_handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+    receipt: z.ZodObject<{
+        archive_digest: z.ZodString;
+        artifact_digest: z.ZodString;
+        build_policy_digest: z.ZodString;
+        bundle_digest: z.ZodString;
+        launcher_digest: z.ZodString;
+        mapping_handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+        network_alias: z.ZodString;
+        operation_handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+        platform: z.ZodObject<{
+            architecture: z.ZodEnum<{
+                amd64: "amd64";
+                arm64: "arm64";
+            }>;
+            os: z.ZodLiteral<"linux">;
+        }, z.core.$strict>;
+        platform_digest: z.ZodString;
+        receipt_digest: z.ZodString;
+        request_digest: z.ZodString;
+        selected_target: z.ZodObject<{
+            fingerprint: z.ZodString;
+            handle: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").OpaqueTargetHandle, string>>;
+        }, z.core.$strict>;
+        version: z.ZodLiteral<"spawnfile.target-local-container-bundle.prepare-receipt.v1">;
+    }, z.core.$strict>;
+    status: z.ZodLiteral<"completed">;
+    idempotency_key: z.ZodString;
+    request_digest: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.target-local-container-bundle.lookup.v1">;
+}, z.core.$strict>], "status">;
+export declare const targetLocalBundleLookupRequestSchema: z.ZodObject<{
+    idempotency_key: z.ZodString;
+    request_digest: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.target-local-container-bundle.lookup.v1">;
+}, z.core.$strict>;
+export type TargetLocalBundlePrepareRequest = z.infer<typeof targetLocalBundlePrepareRequestSchema>;
+export type TargetLocalBundlePrepareReceipt = z.infer<typeof targetLocalBundlePrepareReceiptSchema>;
+export type TargetLocalBundleLookup = z.infer<typeof targetLocalBundleLookupSchema>;
+export type TargetLocalBundleLookupRequest = z.infer<typeof targetLocalBundleLookupRequestSchema>;
+export declare const parseTargetLocalBundlePrepareRequest: (raw: unknown) => TargetLocalBundlePrepareRequest;
+export declare const parseTargetLocalBundlePrepareReceipt: (raw: unknown) => TargetLocalBundlePrepareReceipt;
+export declare const parseTargetLocalBundleLookup: (raw: unknown) => TargetLocalBundleLookup;
+export declare const parseTargetLocalBundleLookupRequest: (raw: unknown) => TargetLocalBundleLookupRequest;
+export declare const createTargetLocalBundleRequestDigest: (raw: unknown) => `sha256:${string}`;
+export declare const createTargetLocalBundleReceiptDigest: (raw: unknown) => `sha256:${string}`;
+export declare const createCanonicalTargetLocalBundleReceiptBytes: (raw: unknown) => string;
+export declare const createCanonicalTargetLocalBundleLookupBytes: (raw: unknown) => string;