spawnfile 0.1.13 → 0.1.17

package/dist/distribution/distributionReportSchema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { SpawnfileError } from "../shared/index.js";
-import { DISTRIBUTION_REPORT_VERSION } from "./types.js";
+import { DISTRIBUTION_ENGINE_KINDS, DISTRIBUTION_REPORT_VERSION, WORLD_BINDINGS_IMAGE_PATH } from "./types.js";
 const secretEntrySchema = z.object({
     generated: z.boolean(),
     name: z.string().min(1),
@@ -32,6 +32,7 @@ const instanceIdSchema = z
 });
 const runtimeInstanceSchema = z.object({
     config_path: containerPathSchema,
+    engine_by_node_id: z.record(z.string().min(1), z.enum(DISTRIBUTION_ENGINE_KINDS)).optional(),
     home_path: containerPathSchema.nullable(),
     id: instanceIdSchema,
     internal_port: portSchema.nullable(),
@@ -69,11 +70,23 @@ export const distributionReportSchema = z.object({
         }).strict())
     }).strict(),
     persistent_mounts: z.array(z.object({
+        // Used verbatim as a docker volume name by `consumeImage`, so it is
+        // constrained to docker's own volume-name charset here (defence in depth,
+        // exactly as `id` is).
+        declared_volume_name: z
+            .string()
+            .min(1)
+            .max(255)
+            .refine((value) => /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value) && !value.includes(".."), {
+            message: "must be a docker volume name (letters, digits, '_', '.', '-'; no '/', ':', whitespace, or '..')"
+        })
+            .optional(),
         durability: z.literal("persistent"),
         // Sanitized by deriveVolumeName before use, but constrained here too so the
         // schema alone keeps the volume-name source clean (defense in depth).
         id: instanceIdSchema,
         kind: z.literal("volume"),
+        lifecycle: z.literal("exclusive-reattach").optional(),
         target: containerPathSchema
     }).strict()),
     port_mappings: z.array(z.object({
@@ -83,7 +96,7 @@ export const distributionReportSchema = z.object({
     ports: z.array(portSchema),
     resources: z.array(z.object({
         id: z.string().min(1),
-        kind: z.union([z.literal("git"), z.literal("volume")]),
+        kind: z.union([z.literal("bundle"), z.literal("git"), z.literal("volume")]),
         link_path: z.string(),
         mode: z.union([z.literal("mutable"), z.literal("readonly")]),
         mount: z.string(),
@@ -96,7 +109,12 @@ export const distributionReportSchema = z.object({
         runtime: z.array(secretEntrySchema),
         surface: z.array(secretEntrySchema)
     }).strict(),
-    version: z.literal(DISTRIBUTION_REPORT_VERSION)
+    version: z.literal(DISTRIBUTION_REPORT_VERSION),
+    world_bindings: z.object({
+        artifact_path: z.literal(WORLD_BINDINGS_IMAGE_PATH),
+        digest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+        schema: z.literal("simfile.world-bindings.v1")
+    }).strict().optional()
 }).strict();
 export const parseDistributionReport = (source, sourceLabel = "distribution report") => {
     const parsed = distributionReportSchema.safeParse(source);

package/dist/distribution/dockerRunner.d.ts

@@ -1,5 +1,10 @@
 export interface DockerCommandRunner {
     /** Runs docker with args; resolves stdout as a Buffer. Rejects on non-zero exit. */
-    (args: string[]): Promise<Buffer>;
+    (args: string[], options?: DockerCommandOptions): Promise<Buffer>;
+}
+export interface DockerCommandOptions {
+    captureStderr?: boolean;
+    maxOutputBytes?: number;
+    timeoutMs?: number;
 }
 export declare const createConsumerDockerRunner: (dockerCommand: string, baseArgs: string[]) => DockerCommandRunner;

package/dist/distribution/dockerRunner.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { SpawnfileError } from "../shared/index.js";
-export const createConsumerDockerRunner = (dockerCommand, baseArgs) => async (args) => new Promise((resolve, reject) => {
+export const createConsumerDockerRunner = (dockerCommand, baseArgs) => async (args, options = {}) => new Promise((resolve, reject) => {
     const finalArgs = [...baseArgs, ...args];
     const child = spawn(dockerCommand, finalArgs, {
         env: { ...process.env },
@@ -8,10 +8,37 @@ export const createConsumerDockerRunner = (dockerCommand, baseArgs) => async (ar
     });
     const stdout = [];
     const stderr = [];
-    child.stdout.on("data", (chunk) => stdout.push(chunk));
-    child.stderr.on("data", (chunk) => stderr.push(String(chunk)));
-    child.on("error", reject);
+    let bytes = 0;
+    let stopped = false;
+    const stop = (reason) => {
+        stopped = true;
+        child.kill("SIGKILL");
+        reject(new SpawnfileError("runtime_error", reason));
+    };
+    const timer = options.timeoutMs === undefined ? undefined
+        : setTimeout(() => stop("Docker diagnostic command timed out"), options.timeoutMs);
+    const clearTimer = () => { if (timer)
+        clearTimeout(timer); };
+    const collect = (chunk, isStderr) => {
+        if (stopped)
+            return;
+        bytes += chunk.length;
+        if (options.maxOutputBytes !== undefined && bytes > options.maxOutputBytes) {
+            stop("Docker diagnostic output exceeded its byte limit");
+            return;
+        }
+        if (isStderr)
+            stderr.push(chunk.toString("utf8"));
+        if (!isStderr || options.captureStderr)
+            stdout.push(chunk);
+    };
+    child.stdout.on("data", (chunk) => collect(chunk, false));
+    child.stderr.on("data", (chunk) => collect(chunk, true));
+    child.on("error", (error) => { clearTimer(); reject(error); });
     child.on("close", (code) => {
+        clearTimer();
+        if (stopped)
+            return;
         if (code === 0) {
             resolve(Buffer.concat(stdout));
             return;

package/dist/distribution/imageRuntimeAuth.d.ts

@@ -1,14 +1,22 @@
 import type { ResolvedAuthProfile } from "../auth/index.js";
 import type { DistributionReport } from "./types.js";
 export interface ImageRuntimeAuthInput {
-    authProfile: ResolvedAuthProfile;
+    authProfile: ResolvedAuthProfile | null;
+    /**
+     * The uid the deployed Daimon image reads its credential leaves as. Defaults
+     * to the compiled image's organization uid; only override it against an image
+     * known to run under a different identity.
+     */
+    daimonContainerCredentialUid?: number;
     report: DistributionReport;
+    sourceEnvironment?: Record<string, string | undefined>;
     tempRoot: string;
 }
 export interface ImageRuntimeAuthResult {
     coveredModelSecrets: Set<string>;
     mountArgs: string[];
 }
+export declare const prepareDaimonImageAuthMounts: (instance: DistributionReport["runtime_instances"][number], environment: Record<string, string | undefined>, authProfile: ResolvedAuthProfile | null, containerCredentialUid?: number) => Promise<string[]>;
 /**
  * Builds the credential mounts for a sourceless image deployment that uses
  * import-based model auth. The OAuth-mode config is already baked into the

package/dist/distribution/imageRuntimeAuth.js

@@ -2,8 +2,71 @@ import path from "node:path";
 import { loadImportedClaudeCodeCredential, loadImportedCodexCredential } from "../auth/index.js";
 import { fileExists } from "../filesystem/index.js";
 import { getRuntimeAdapter } from "../runtime/index.js";
+import { DAIMON_AGY_SUBSCRIPTION_REALM, DAIMON_ENGINE_CREDENTIALS, DAIMON_GROK_SUBSCRIPTION_REALM } from "../runtime/daimon/contractManifest.js";
+import { assertDaimonCredentialContainerOwner, assertSafeDaimonSourceFile, DAIMON_AGY_UNLOCK_SOURCE_ENV, DAIMON_CREDENTIAL_CONTAINER_UID, daimonSourcePathForEngine } from "../runtime/daimon/runAuth.js";
 import { SpawnfileError } from "../shared/index.js";
 const importMountTargetName = (kind) => kind === "claude-code" ? ".claude" : ".codex";
+const daimonNodeSlug = (nodeId) => nodeId.replace(/^agent:/u, "").toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");
+const daimonInstanceRoot = (instance) => {
+    const root = path.posix.join("/var/lib/spawnfile/instances/daimon", instance.id);
+    if (instance.config_path !== path.posix.join(root, "daimon/daimon-organization-runtime.json")
+        || instance.workspace_path !== path.posix.join(root, "workspace")) {
+        throw new SpawnfileError("validation_error", "Daimon image runtime paths are not canonical");
+    }
+    return root;
+};
+export const prepareDaimonImageAuthMounts = async (instance, environment, authProfile, containerCredentialUid = DAIMON_CREDENTIAL_CONTAINER_UID) => {
+    const engines = Object.entries(instance.engine_by_node_id ?? {}).sort(([left], [right]) => left.localeCompare(right));
+    if (engines.length === 0) {
+        throw new SpawnfileError("validation_error", "Daimon image report is missing its engine map");
+    }
+    const engineNodeIds = engines.map(([nodeId]) => nodeId);
+    if (JSON.stringify(engineNodeIds) !== JSON.stringify([...instance.node_ids].sort())) {
+        throw new SpawnfileError("validation_error", "Daimon image engine map does not match its declared agents");
+    }
+    if (engines.some(([, engine]) => engine !== "agy" && engine !== "codex" && engine !== "grok")) {
+        throw new SpawnfileError("validation_error", "Daimon image report declares an unsupported engine");
+    }
+    const root = daimonInstanceRoot(instance);
+    const mounts = [];
+    const slugs = new Map();
+    for (const [nodeId] of engines) {
+        const slug = daimonNodeSlug(nodeId);
+        if (!slug || slugs.has(slug))
+            throw new SpawnfileError("validation_error", "Daimon image report has an unsafe agent id");
+        slugs.set(slug, nodeId);
+    }
+    const codexSource = engines.some(([, engine]) => engine === "codex")
+        ? daimonSourcePathForEngine("codex", environment, authProfile) : null;
+    if (codexSource) {
+        const ownerUid = await assertSafeDaimonSourceFile(codexSource, "codex", 64 * 1024, "codex");
+        assertDaimonCredentialContainerOwner(ownerUid, "codex", containerCredentialUid);
+    }
+    for (const [nodeId, engine] of engines) {
+        if (engine !== "codex")
+            continue;
+        const slug = daimonNodeSlug(nodeId);
+        const target = path.posix.join(root, "runtime-homes", slug, DAIMON_ENGINE_CREDENTIALS.codex.sourceRelativePath);
+        mounts.push("-v", `${codexSource}:${target}:ro`);
+    }
+    // The Grok bootstrap leaf is deliberately exempt from the container-owner
+    // assertion; see the matching note in runAuth.ts.
+    if (engines.some(([, engine]) => engine === "grok")) {
+        const source = daimonSourcePathForEngine("grok", environment);
+        await assertSafeDaimonSourceFile(source, "grok", DAIMON_GROK_SUBSCRIPTION_REALM.maxCredentialBytes, "grok");
+        mounts.push("-v", `${source}:${DAIMON_GROK_SUBSCRIPTION_REALM.bootstrapMountPath}:ro`);
+    }
+    if (engines.some(([, engine]) => engine === "agy")) {
+        const source = environment[DAIMON_AGY_UNLOCK_SOURCE_ENV]?.trim();
+        if (!source)
+            throw new SpawnfileError("validation_error", "Daimon runtime auth is missing the operator-authorized AGY realm unlock artifact");
+        const ownerUid = await assertSafeDaimonSourceFile(source, "AGY realm unlock", DAIMON_AGY_SUBSCRIPTION_REALM.maxUnlockBytes);
+        assertDaimonCredentialContainerOwner(ownerUid, "AGY realm unlock", containerCredentialUid);
+        mounts.push("-v", `${source}:${DAIMON_AGY_SUBSCRIPTION_REALM.unlockMountPath}:ro`);
+    }
+    return mounts;
+};
 /**
  * Builds the credential mounts for a sourceless image deployment that uses
  * import-based model auth. The OAuth-mode config is already baked into the
@@ -19,6 +82,12 @@ export const prepareImageRuntimeAuthMounts = async (input) => {
         if (instance.home_path) {
             runtimeHomes.add(instance.home_path);
         }
+        if (instance.runtime === "daimon") {
+            mountArgs.push(...await prepareDaimonImageAuthMounts(instance, input.sourceEnvironment ?? process.env, input.authProfile, input.daimonContainerCredentialUid ?? DAIMON_CREDENTIAL_CONTAINER_UID));
+            continue;
+        }
+        if (!input.authProfile)
+            continue;
         const adapter = getRuntimeAdapter(instance.runtime);
         if (!adapter.prepareRuntimeAuth) {
             continue;
@@ -45,7 +114,7 @@ export const prepareImageRuntimeAuthMounts = async (input) => {
     // Mount the raw credential import directories into each runtime home so the
     // runtime's OAuth client can read them (e.g. ~/.claude, ~/.codex).
     for (const kind of ["claude-code", "codex"]) {
-        const entry = input.authProfile.imports[kind];
+        const entry = input.authProfile?.imports[kind];
         if (!entry) {
             continue;
         }

package/dist/distribution/index.d.ts

@@ -6,7 +6,7 @@ export type { DockerCommandRunner, ExtractImageOptions, ImageInspection } from "
 export { parseDistributionReport } from "./distributionReportSchema.js";
 export { consumeImageUp } from "./consumeImage.js";
 export type { ConsumeImageUpOptions, ConsumeImageUpResult } from "./consumeImage.js";
-export { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+export { deriveDeploymentName, derivePersistentMountVolumeName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
 export { createConsumerDockerRunner } from "./dockerRunner.js";
 export { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
 export { runImagePreflight } from "./preflight.js";
@@ -20,5 +20,5 @@ export { extractSingleFileFromTar } from "./tarReader.js";
 export { hasRegistryComponent, parseImageReference, parseImplicitImageReference } from "./imageRef.js";
 export type { ParsedImageReference } from "./imageRef.js";
 export { normalizeProjectLabelSlug } from "./projectName.js";
-export { DISTRIBUTION_REPORT_IMAGE_PATH, DISTRIBUTION_REPORT_OUTPUT_FILE, DISTRIBUTION_REPORT_VERSION, IMAGE_CONTRACT_VERSION } from "./types.js";
-export type { DistributionAgentSummary, DistributionImageLabels, DistributionMoltnetNetwork, DistributionOrganizationSummary, DistributionPersistentMount, DistributionPortMapping, DistributionReport, DistributionRuntimeInstance, DistributionSecretCategory, DistributionSecretEntry, DistributionTeamSummary, DistributionWorkspaceResource } from "./types.js";
+export { DISTRIBUTION_REPORT_IMAGE_PATH, DISTRIBUTION_REPORT_OUTPUT_FILE, DISTRIBUTION_REPORT_VERSION, IMAGE_CONTRACT_VERSION, WORLD_BINDINGS_IMAGE_PATH } from "./types.js";
+export type { DistributionAgentSummary, DistributionImageLabels, DistributionMoltnetNetwork, DistributionOrganizationSummary, DistributionPersistentMount, DistributionPortMapping, DistributionReport, DistributionRuntimeInstance, DistributionSecretCategory, DistributionSecretEntry, DistributionTeamSummary, DistributionWorkspaceResource, DistributionWorldBindingsEvidence } from "./types.js";

package/dist/distribution/index.js

@@ -3,7 +3,7 @@ export { createDistributionFingerprint } from "./fingerprint.js";
 export { extractImageReport, resolveDockerBaseArgs } from "./extractImage.js";
 export { parseDistributionReport } from "./distributionReportSchema.js";
 export { consumeImageUp } from "./consumeImage.js";
-export { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+export { deriveDeploymentName, derivePersistentMountVolumeName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
 export { createConsumerDockerRunner } from "./dockerRunner.js";
 export { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
 export { runImagePreflight } from "./preflight.js";
@@ -13,4 +13,4 @@ export { buildImageInterfaceSummary, renderImageInterface } from "./renderImageI
 export { extractSingleFileFromTar } from "./tarReader.js";
 export { hasRegistryComponent, parseImageReference, parseImplicitImageReference } from "./imageRef.js";
 export { normalizeProjectLabelSlug } from "./projectName.js";
-export { DISTRIBUTION_REPORT_IMAGE_PATH, DISTRIBUTION_REPORT_OUTPUT_FILE, DISTRIBUTION_REPORT_VERSION, IMAGE_CONTRACT_VERSION } from "./types.js";
+export { DISTRIBUTION_REPORT_IMAGE_PATH, DISTRIBUTION_REPORT_OUTPUT_FILE, DISTRIBUTION_REPORT_VERSION, IMAGE_CONTRACT_VERSION, WORLD_BINDINGS_IMAGE_PATH } from "./types.js";

package/dist/distribution/preflight.js

@@ -1,5 +1,9 @@
 import { SpawnfileError } from "../shared/index.js";
 const ENV_BASED_AUTH_METHODS = new Set(["api_key", "none"]);
+// Satisfied by the runtime's own credential slot (the Daimon Grok broker's
+// bootstrap realm, checked by `imageRuntimeAuth.ts`), never by an env value
+// or a host CLI import.
+const RUNTIME_OWNED_AUTH_METHODS = new Set(["grok"]);
 // Import-based auth methods are satisfiable sourceless when the consumer has the
 // matching local credential import (their logged-in Claude Code / Codex session).
 const IMPORT_AUTH_METHOD_KINDS = {
@@ -10,7 +14,7 @@ const collectUnsupportedAuth = (report, availableImports) => {
     const unsupported = [];
     for (const instance of report.runtime_instances) {
         for (const [provider, method] of Object.entries(instance.model_auth_methods)) {
-            if (ENV_BASED_AUTH_METHODS.has(method)) {
+            if (ENV_BASED_AUTH_METHODS.has(method) || RUNTIME_OWNED_AUTH_METHODS.has(method)) {
                 continue;
             }
             const importKind = IMPORT_AUTH_METHOD_KINDS[method];

package/dist/distribution/types.d.ts

@@ -22,14 +22,24 @@ export interface DistributionOrganizationSummary {
     teams: DistributionTeamSummary[];
 }
 export interface DistributionPersistentMount {
+    /**
+     * The author's own volume name for this mount, when the manifest declared
+     * one. The report never carries a compiler-DERIVED name — that encodes the
+     * creator's plan root and deployment lineage and stays private to that host
+     * — but a declared name belongs to the published declaration and a consumer
+     * honours it verbatim, so an operator who pre-created that volume attaches
+     * it instead of silently getting an empty one.
+     */
+    declared_volume_name?: string;
     durability: "persistent";
     id: string;
     kind: "volume";
+    lifecycle?: "exclusive-reattach";
     target: string;
 }
 export interface DistributionWorkspaceResource {
     id: string;
-    kind: "git" | "volume";
+    kind: "bundle" | "git" | "volume";
     link_path: string;
     mode: "mutable" | "readonly";
     mount: string;
@@ -37,6 +47,7 @@ export interface DistributionWorkspaceResource {
 }
 export interface DistributionRuntimeInstance {
     config_path: string;
+    engine_by_node_id?: Record<string, string>;
     home_path: string | null;
     id: string;
     internal_port: number | null;
@@ -47,6 +58,8 @@ export interface DistributionRuntimeInstance {
     runtime: string;
     workspace_path: string;
 }
+export declare const DISTRIBUTION_ENGINE_KINDS: readonly ["agy", "claude", "codex", "grok", "pi", "scripted"];
+export type DistributionEngineKind = typeof DISTRIBUTION_ENGINE_KINDS[number];
 export interface DistributionMoltnetNetwork {
     binding: "env";
     id: string;
@@ -56,6 +69,11 @@ export interface DistributionPortMapping {
     internal_port: number;
     published_port: number;
 }
+export interface DistributionWorldBindingsEvidence {
+    artifact_path: typeof WORLD_BINDINGS_IMAGE_PATH;
+    digest: string;
+    schema: "simfile.world-bindings.v1";
+}
 export interface DistributionReport {
     compile_fingerprint: string;
     generated_at: string;
@@ -72,9 +90,11 @@ export interface DistributionReport {
     runtime_instances: DistributionRuntimeInstance[];
     secrets: Record<DistributionSecretCategory, DistributionSecretEntry[]>;
     version: "spawnfile.distribution-report.v1";
+    world_bindings?: DistributionWorldBindingsEvidence;
 }
 export declare const DISTRIBUTION_REPORT_VERSION = "spawnfile.distribution-report.v1";
 export declare const DISTRIBUTION_REPORT_IMAGE_PATH = "/spawnfile/spawnfile-report.json";
 export declare const DISTRIBUTION_REPORT_OUTPUT_FILE = "distribution-report.json";
 export declare const IMAGE_CONTRACT_VERSION = "spawnfile.image.v1";
+export declare const WORLD_BINDINGS_IMAGE_PATH = "/spawnfile/world-bindings.json";
 export type DistributionImageLabels = Record<"com.spawnfile.compile_fingerprint" | "com.spawnfile.image_contract" | "com.spawnfile.project" | "com.spawnfile.report", string> & Record<string, string>;

package/dist/distribution/types.js

@@ -1,4 +1,8 @@
+export const DISTRIBUTION_ENGINE_KINDS = [
+    "agy", "claude", "codex", "grok", "pi", "scripted"
+];
 export const DISTRIBUTION_REPORT_VERSION = "spawnfile.distribution-report.v1";
 export const DISTRIBUTION_REPORT_IMAGE_PATH = "/spawnfile/spawnfile-report.json";
 export const DISTRIBUTION_REPORT_OUTPUT_FILE = "distribution-report.json";
 export const IMAGE_CONTRACT_VERSION = "spawnfile.image.v1";
+export const WORLD_BINDINGS_IMAGE_PATH = "/spawnfile/world-bindings.json";

package/dist/evidenceExportHelper/boundedExecutor.d.ts

@@ -0,0 +1,3 @@
+import { type DockerArtifactExecutor } from "../target/dockerArtifactsProvider.js";
+/** Tree-safe private Docker executor used at every local-helper boundary. */
+export declare const createPreparedEvidenceHelperExecutor: (dockerCommand: string) => DockerArtifactExecutor;

package/dist/evidenceExportHelper/boundedExecutor.js

@@ -0,0 +1,33 @@
+import { DockerArtifactProviderError, } from "../target/dockerArtifactsProvider.js";
+import { createBoundedDockerTargetExecFile, DockerTargetCommandFailure, } from "../target/dockerTargetExecFile.js";
+const missingExactImage = (args, error) => {
+    if (!(error instanceof DockerTargetCommandFailure))
+        return false;
+    const command = args[0] === "--context" ? args.slice(2) : args;
+    if (command.length !== 5 || command[0] !== "image" || command[1] !== "inspect"
+        || command[3] !== "--format")
+        return false;
+    const match = /^(?:Error response from daemon: )?No such image: ([A-Za-z0-9_.:@/-]+)$/u
+        .exec(error.stderr.trim());
+    return match?.[1] === command[2];
+};
+/** Tree-safe private Docker executor used at every local-helper boundary. */
+export const createPreparedEvidenceHelperExecutor = (dockerCommand) => {
+    const execute = createBoundedDockerTargetExecFile();
+    return async (file, args, options) => {
+        if (file !== "docker")
+            throw new Error("Prepared evidence-export helper failed");
+        try {
+            return await execute(dockerCommand, args, {
+                signal: options.signal,
+                stdin: options.stdin,
+                timeout: options.timeout,
+            });
+        }
+        catch (error) {
+            if (missingExactImage(args, error))
+                throw new DockerArtifactProviderError("image_not_found");
+            throw error;
+        }
+    };
+};

package/dist/evidenceExportHelper/helperProgram.mjs

@@ -0,0 +1,156 @@
+#!/usr/local/bin/node
+
+import { constants } from "node:fs";
+import { lstat, open, opendir } from "node:fs/promises";
+import path from "node:path";
+
+const ROOT = "/spawnfile/evidence";
+const BLOCK = 512;
+const MAX_BYTES = 67_108_864;
+const MAX_ENTRIES = 10_000;
+const MAX_DEPTH = 32;
+const MAX_PATH_BYTES = 255;
+
+const fail = () => { throw new Error("Evidence export helper failed"); };
+const pad = (size) => Math.ceil(size / BLOCK) * BLOCK;
+const same = (left, right) => left.dev === right.dev && left.ino === right.ino
+  && left.size === right.size && left.mode === right.mode;
+
+const safePath = (value) => {
+  const bytes = Buffer.from(value, "utf8");
+  if (value.length < 1 || bytes.toString("utf8") !== value
+    || bytes.byteLength > MAX_PATH_BYTES || value.startsWith("/")
+    || value.includes("\\") || value.includes("\0") || value.includes("//")) fail();
+  const parts = value.split("/");
+  if (parts.length > MAX_DEPTH || parts.some((part) => part === "" || part === "." || part === "..")) fail();
+  for (const part of parts) {
+    for (let index = 0; index < part.length; index += 1) {
+      const code = part.charCodeAt(index);
+      if (code < 0x20 || code === 0x7f) fail();
+    }
+  }
+  return value;
+};
+
+const comparePaths = (left, right) => Buffer.compare(
+  Buffer.from(left.path, "utf8"),
+  Buffer.from(right.path, "utf8"),
+);
+
+const collect = async (directory, prefix, entries) => {
+  const before = await lstat(directory);
+  if (!before.isDirectory() || before.isSymbolicLink()) fail();
+  const handle = await opendir(directory);
+  const names = [];
+  try {
+    for await (const item of handle) names.push(item.name);
+  } finally {
+    await handle.close().catch(() => undefined);
+  }
+  names.sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+  for (const name of names) {
+    const relative = safePath(prefix ? `${prefix}/${name}` : name);
+    const absolute = path.join(directory, name);
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink()) fail();
+    if (info.isDirectory()) {
+      entries.push({ info, path: relative, type: "directory" });
+      await collect(absolute, relative, entries);
+    } else if (info.isFile()) {
+      entries.push({ info, path: relative, type: "file" });
+    } else fail();
+    if (entries.length > MAX_ENTRIES) fail();
+  }
+  const after = await lstat(directory);
+  if (!same(before, after)) fail();
+};
+
+const octal = (value, width) => {
+  const raw = value.toString(8);
+  if (!Number.isSafeInteger(value) || value < 0 || raw.length > width - 1) fail();
+  return Buffer.from(`${raw.padStart(width - 1, "0")}\0`, "ascii");
+};
+
+const storedPath = (entry) => entry.type === "directory" ? `${entry.path}/` : entry.path;
+const splitPath = (stored) => {
+  const bytes = Buffer.from(stored, "utf8");
+  if (bytes.byteLength <= 100) return { name: bytes, prefix: Buffer.alloc(0) };
+  for (let split = stored.lastIndexOf("/"); split > 0; split = stored.lastIndexOf("/", split - 1)) {
+    const prefix = Buffer.from(stored.slice(0, split), "utf8");
+    const name = Buffer.from(stored.slice(split + 1), "utf8");
+    if (prefix.byteLength <= 155 && name.byteLength > 0 && name.byteLength <= 100) {
+      return { name, prefix };
+    }
+  }
+  return fail();
+};
+
+const header = (entry) => {
+  const stored = storedPath(entry);
+  const { name, prefix } = splitPath(stored);
+  const output = Buffer.alloc(BLOCK);
+  output.set(name, 0);
+  output.set(octal(entry.type === "directory" ? 0o755 : 0o644, 8), 100);
+  output.set(octal(0, 8), 108);
+  output.set(octal(0, 8), 116);
+  output.set(octal(entry.type === "file" ? entry.info.size : 0, 12), 124);
+  output.set(octal(0, 12), 136);
+  output[156] = entry.type === "directory" ? 53 : 48;
+  output.set(Buffer.from("ustar\0", "ascii"), 257);
+  output.set(Buffer.from("00", "ascii"), 263);
+  output.set(octal(0, 8), 329);
+  output.set(octal(0, 8), 337);
+  output.set(prefix, 345);
+  output.fill(0x20, 148, 156);
+  let sum = 0;
+  for (const byte of output) sum += byte;
+  if (sum > 0o777777) fail();
+  output.set(Buffer.from(`${sum.toString(8).padStart(6, "0")}\0 `, "ascii"), 148);
+  return output;
+};
+
+const write = async (bytes) => {
+  if (process.stdout.write(bytes)) return;
+  await new Promise((resolve, reject) => {
+    process.stdout.once("drain", resolve);
+    process.stdout.once("error", reject);
+  });
+};
+
+const main = async () => {
+  const root = await lstat(ROOT);
+  if (!root.isDirectory() || root.isSymbolicLink()) fail();
+  const entries = [];
+  await collect(ROOT, "", entries);
+  entries.sort(comparePaths);
+  if (entries.length < 1) fail();
+  let total = BLOCK * 2;
+  for (const entry of entries) {
+    total += BLOCK + (entry.type === "file" ? pad(entry.info.size) : 0);
+    if (!Number.isSafeInteger(total) || total > MAX_BYTES) fail();
+  }
+  for (const entry of entries) {
+    await write(header(entry));
+    if (entry.type !== "file") continue;
+    const absolute = path.join(ROOT, entry.path);
+    const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const before = await file.stat();
+      if (!before.isFile() || !same(before, entry.info)) fail();
+      const bytes = await file.readFile();
+      const after = await file.stat();
+      if (!same(before, after) || bytes.byteLength !== before.size) fail();
+      await write(bytes);
+      const padding = pad(bytes.byteLength) - bytes.byteLength;
+      if (padding > 0) await write(Buffer.alloc(padding));
+    } finally {
+      await file.close().catch(() => undefined);
+    }
+  }
+  await write(Buffer.alloc(BLOCK * 2));
+};
+
+main().catch(() => {
+  process.stderr.write("Evidence export helper failed\n");
+  process.exitCode = 1;
+});

package/dist/evidenceExportHelper/index.d.ts

@@ -0,0 +1,4 @@
+export { createPreparedEvidenceHelperExecutor } from "./boundedExecutor.js";
+export * from "./preparedAuthority.js";
+export * from "./preparedBuilder.js";
+export * from "./recipe.js";

package/dist/evidenceExportHelper/index.js

@@ -0,0 +1,4 @@
+export { createPreparedEvidenceHelperExecutor } from "./boundedExecutor.js";
+export * from "./preparedAuthority.js";
+export * from "./preparedBuilder.js";
+export * from "./recipe.js";

package/dist/evidenceExportHelper/preparedAuthority.d.ts

@@ -0,0 +1,64 @@
+import { type OpaqueTargetHandle } from "../target/contracts.js";
+export declare const PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION: "spawnfile.target-evidence-export-helper.prepared.v1";
+export declare const PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION: "spawnfile.target-evidence-export-helper.private.v3";
+export interface PreparedEvidenceHelperReceipt {
+    readonly digest: `sha256:${string}`;
+    readonly handle: OpaqueTargetHandle;
+    readonly version: typeof PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION;
+}
+export interface PreparedEvidenceHelperPendingRecord {
+    readonly base_config_digest: `sha256:${string}`;
+    readonly base_image: string;
+    readonly context: string;
+    readonly daemon_digest: `sha256:${string}`;
+    readonly endpoint_digest: `sha256:${string}`;
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+    readonly recipe_digest: `sha256:${string}`;
+    readonly version: typeof PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION;
+}
+export interface PreparedEvidenceHelperCompletionRecord {
+    readonly accepted_image_config_digest: `sha256:${string}`;
+    readonly pending_digest: `sha256:${string}`;
+    readonly receipt: PreparedEvidenceHelperReceipt;
+    readonly version: typeof PREPARED_EVIDENCE_HELPER_PRIVATE_VERSION;
+}
+export interface PreparedEvidenceHelperAuthority {
+    readonly completion: PreparedEvidenceHelperCompletionRecord | null;
+    readonly pending: PreparedEvidenceHelperPendingRecord;
+}
+export declare const parsePreparedEvidenceHelperReceipt: (raw: unknown) => PreparedEvidenceHelperReceipt;
+export declare const createPreparedEvidenceHelperReceiptBytes: (raw: unknown) => string;
+export declare const pendingDigest: (raw: unknown) => `sha256:${string}`;
+export declare const createPreparedEvidenceHelperReceipt: (input: {
+    readonly configDigest: unknown;
+    readonly pendingDigest: unknown;
+}) => PreparedEvidenceHelperReceipt;
+export declare const parsePreparedEvidenceHelperPendingRecord: (raw: unknown) => PreparedEvidenceHelperPendingRecord;
+export declare const createPreparedEvidenceHelperPendingBytes: (raw: unknown) => string;
+export declare const parsePreparedEvidenceHelperCompletionRecord: (raw: unknown) => PreparedEvidenceHelperCompletionRecord;
+export declare const createPreparedEvidenceHelperCompletionBytes: (raw: unknown) => string;
+export declare const createPreparedEvidenceHelperKey: (input: {
+    readonly baseConfigDigest: string;
+    readonly context: string;
+    readonly daemonDigest: string;
+    readonly endpointDigest: string;
+    readonly platform: {
+        readonly architecture: string;
+        readonly os: string;
+    };
+    readonly recipeDigest: string;
+}) => string;
+export declare const newPreparedEvidenceHelperPendingRecord: (input: Omit<PreparedEvidenceHelperPendingRecord, "version">) => PreparedEvidenceHelperPendingRecord;
+export declare const newPreparedEvidenceHelperCompletionRecord: (pending: unknown, configDigest: unknown) => PreparedEvidenceHelperCompletionRecord;
+/** Immutable, fsynced pending/completion authority records keyed by exact target facts. */
+export declare class PreparedEvidenceHelperAuthorityStore {
+    #private;
+    constructor(privateRoot: string);
+    load(key: string): Promise<PreparedEvidenceHelperAuthority | null>;
+    reserve(key: string, raw: unknown): Promise<PreparedEvidenceHelperPendingRecord>;
+    complete(key: string, raw: unknown): Promise<PreparedEvidenceHelperCompletionRecord>;
+}
+export declare const initializePreparedEvidenceHelperAuthorityStore: (privateRoot: unknown) => Promise<PreparedEvidenceHelperAuthorityStore>;