spawnfile 0.1.13 → 0.1.14

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;

package/dist/target/containerBundleContracts.js

@@ -0,0 +1,173 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { assertOrdinaryJsonGraph, opaqueTargetHandleSchema, selectedTargetSchema } from "./contracts.js";
+export const TARGET_LOCAL_BUNDLE_PREPARE_REQUEST_VERSION = "spawnfile.target-local-container-bundle.prepare-request.v1";
+export const TARGET_LOCAL_BUNDLE_PREPARE_RECEIPT_VERSION = "spawnfile.target-local-container-bundle.prepare-receipt.v1";
+export const TARGET_LOCAL_BUNDLE_LOOKUP_VERSION = "spawnfile.target-local-container-bundle.lookup.v1";
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const idempotency = z.string().regex(/^idem_[a-z0-9]{16,64}$/u);
+const alias = z.string().regex(/^[a-z][a-z0-9-]{0,62}$/u);
+const archivePath = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/u)
+    .refine((value) => !value.includes("//") && !value.split("/").some((part) => part === "." || part === ".."))
+    .refine((value) => {
+    if (Buffer.byteLength(value, "utf8") <= 100)
+        return true;
+    const split = value.lastIndexOf("/");
+    return split > 0 && Buffer.byteLength(value.slice(0, split), "utf8") <= 155
+        && Buffer.byteLength(value.slice(split + 1), "utf8") <= 100;
+});
+const platform = z.object({ architecture: z.enum(["amd64", "arm64"]), os: z.literal("linux") }).strict();
+const canonicalBase64 = (value) => {
+    if (value.length > 5_592_408 || value.length % 4 !== 0)
+        return false;
+    let padding = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        const equals = code === 61;
+        const ordinary = code >= 65 && code <= 90 || code >= 97 && code <= 122 || code >= 48 && code <= 57 || code === 43 || code === 47;
+        if (!equals && !ordinary || equals && index < value.length - 2)
+            return false;
+        if (equals)
+            padding += 1;
+        else if (padding > 0)
+            return false;
+    }
+    if (padding > 2 || padding === 1 && value.at(-1) !== "=" || padding === 2 && !value.endsWith("=="))
+        return false;
+    const bytes = Buffer.from(value, "base64");
+    return bytes.byteLength <= 4_194_304 && bytes.toString("base64") === value;
+};
+const archiveBytes = z.string().refine(canonicalBase64);
+const canonicalEntries = (items) => items.every((item, index) => (index === 0 || items[index - 1] < item) && archivePath.safeParse(item).success);
+export const targetLocalBundlePrepareRequestSchema = z.object({
+    archive_base64: archiveBytes,
+    archive_digest: digest,
+    archive_entries: z.array(archivePath).min(1).max(32).superRefine((items, context) => {
+        if (!canonicalEntries(items)) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "archive entries must be canonical" });
+        }
+    }),
+    artifact_digest: digest,
+    build_policy_digest: digest,
+    bundle_digest: digest,
+    entrypoint: archivePath,
+    idempotency_key: idempotency,
+    launcher_digest: digest,
+    network_alias: alias,
+    platform,
+    platform_digest: digest,
+    selected_target: selectedTargetSchema,
+    version: z.literal(TARGET_LOCAL_BUNDLE_PREPARE_REQUEST_VERSION)
+}).strict().superRefine((value, context) => {
+    if (new Set([value.archive_digest, value.artifact_digest, value.build_policy_digest,
+        value.bundle_digest, value.launcher_digest, value.platform_digest]).size !== 6) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "bundle correlations must be distinct" });
+    }
+    if (!value.archive_entries.includes(value.entrypoint)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "entrypoint must be an admitted archive entry" });
+    }
+});
+const receiptBodySchema = z.object({
+    archive_digest: digest,
+    artifact_digest: digest,
+    build_policy_digest: digest,
+    bundle_digest: digest,
+    launcher_digest: digest,
+    mapping_handle: opaqueTargetHandleSchema,
+    network_alias: alias,
+    operation_handle: opaqueTargetHandleSchema,
+    platform,
+    platform_digest: digest,
+    receipt_digest: digest,
+    request_digest: digest,
+    selected_target: selectedTargetSchema,
+    version: z.literal(TARGET_LOCAL_BUNDLE_PREPARE_RECEIPT_VERSION)
+}).strict();
+export const targetLocalBundlePrepareReceiptSchema = receiptBodySchema;
+const lookupBase = {
+    idempotency_key: idempotency,
+    request_digest: digest,
+    version: z.literal(TARGET_LOCAL_BUNDLE_LOOKUP_VERSION)
+};
+export const targetLocalBundleLookupSchema = z.discriminatedUnion("status", [
+    z.object({ ...lookupBase, status: z.literal("not_applied") }).strict(),
+    z.object({ ...lookupBase, operation_handle: opaqueTargetHandleSchema, status: z.literal("pending") }).strict(),
+    z.object({ ...lookupBase, operation_handle: opaqueTargetHandleSchema, receipt: receiptBodySchema, status: z.literal("completed") }).strict()
+]);
+export const targetLocalBundleLookupRequestSchema = z.object({
+    idempotency_key: idempotency,
+    request_digest: digest,
+    version: z.literal(TARGET_LOCAL_BUNDLE_LOOKUP_VERSION)
+}).strict();
+/* The generic JSON graph guard intentionally caps ordinary control messages at
+ * 64 KiB. A bundle request is the one bounded binary envelope: its canonical
+ * base64 may be 5,592,408 bytes for a 4 MiB archive. Clone descriptor values
+ * first, replacing only that field for graph admission, so schema parsing
+ * never invokes caller-owned accessors or proxies. */
+const safeBundleRequestGraph = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        assertOrdinaryJsonGraph(raw);
+        return raw;
+    }
+    const prototype = Object.getPrototypeOf(raw);
+    const descriptors = Object.getOwnPropertyDescriptors(raw);
+    const archive = descriptors.archive_base64;
+    if (prototype !== Object.prototype || !archive || !("value" in archive) || typeof archive.value !== "string") {
+        assertOrdinaryJsonGraph(raw);
+        return raw;
+    }
+    const admitted = Object.create(Object.prototype);
+    Object.defineProperties(admitted, descriptors);
+    Object.defineProperty(admitted, "archive_base64", { configurable: true, enumerable: true, value: "", writable: true });
+    assertOrdinaryJsonGraph(admitted);
+    Object.defineProperty(admitted, "archive_base64", { configurable: true, enumerable: true, value: archive.value, writable: true });
+    return admitted;
+};
+export const parseTargetLocalBundlePrepareRequest = (raw) => {
+    return targetLocalBundlePrepareRequestSchema.parse(safeBundleRequestGraph(raw));
+};
+export const parseTargetLocalBundlePrepareReceipt = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    const parsed = targetLocalBundlePrepareReceiptSchema.parse(raw);
+    if (parsed.receipt_digest !== createTargetLocalBundleReceiptDigest(parsed))
+        throw new Error("Container bundle receipt failed");
+    return parsed;
+};
+export const parseTargetLocalBundleLookup = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    const parsed = targetLocalBundleLookupSchema.parse(raw);
+    if (parsed.status === "completed") {
+        const receipt = parseTargetLocalBundlePrepareReceipt(parsed.receipt);
+        if (receipt.operation_handle !== parsed.operation_handle || receipt.request_digest !== parsed.request_digest) {
+            throw new Error("Container bundle lookup failed");
+        }
+    }
+    return parsed;
+};
+export const parseTargetLocalBundleLookupRequest = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    return targetLocalBundleLookupRequestSchema.parse(raw);
+};
+const canonical = (value, trusted = false) => {
+    if (!trusted)
+        assertOrdinaryJsonGraph(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonical(item, true)).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical(record[key], true)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+const hashed = (domain, value, trusted = false) => `sha256:${createHash("sha256")
+    .update(`spawnfile.target-local-container-bundle.${domain}.v1\0`, "utf8")
+    .update(canonical(value, trusted), "utf8").digest("hex")}`;
+export const createTargetLocalBundleRequestDigest = (raw) => hashed("request", parseTargetLocalBundlePrepareRequest(raw), true);
+export const createTargetLocalBundleReceiptDigest = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    const { receipt_digest: _digest, ...body } = targetLocalBundlePrepareReceiptSchema.parse(raw);
+    return hashed("receipt", body);
+};
+export const createCanonicalTargetLocalBundleReceiptBytes = (raw) => canonical(parseTargetLocalBundlePrepareReceipt(raw));
+export const createCanonicalTargetLocalBundleLookupBytes = (raw) => canonical(parseTargetLocalBundleLookup(raw));

package/dist/target/containerBundleFilesystemStore.d.ts

@@ -0,0 +1,3 @@
+import { type TargetLocalBundleStore } from "./containerBundleStore.js";
+/** Secure single-file persistence around the strict exact-key store. */
+export declare const initializeFilesystemTargetLocalBundleStore: (root: unknown) => Promise<TargetLocalBundleStore>;