spawnfile 0.1.13 → 0.1.17

package/dist/auth/targetSecretSourceVersionRecords.js

@@ -0,0 +1,166 @@
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import { TARGET_SECRET_SOURCE_ERROR, assertOrdinaryJsonGraph, createCanonicalTargetSecretSourceJson, decodeTargetSecretSourceSecret, encodeTargetSecretSourceSecret, parseCanonicalTargetSecretSourceJson, parseTargetSecretSourceOpaqueHandle } from "./targetSecretSourceRecordCommon.js";
+export const TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION = "spawnfile.auth.target-secret.source-version.v1";
+export const TARGET_SECRET_SOURCE_ALIAS_RECORD_VERSION = "spawnfile.auth.target-secret.source-alias.v1";
+const VERSION_KEYS = ["publication_handle", "secret", "source_version_handle", "version"];
+const ALIAS_KEYS = ["publication_handle", "source_handle", "source_version_handle", "version"];
+const ALIAS_METADATA_KEYS = ["source_handle", "source_version_handle", "version"];
+const VERSION_METADATA_KEYS = ["source_version_handle", "version"];
+const PRIVATE_VERSION_METADATA_KEYS = ["publication_handle", "source_version_handle", "version"];
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const normalize = (work) => {
+    try {
+        return work();
+    }
+    catch {
+        return fail();
+    }
+};
+const defaultEntropy = () => {
+    const bytes = randomBytes(16);
+    try {
+        return Uint8Array.from(bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+};
+const freeze = (value) => Object.freeze(value);
+const opaqueHandleFromEntropy = (entropy) => normalize(() => {
+    const raw = entropy();
+    if (!(raw instanceof Uint8Array) || raw.length < 8 || raw.length > 32)
+        fail();
+    const copy = Uint8Array.from(raw);
+    const encoded = Buffer.from(copy);
+    try {
+        return parseTargetSecretSourceOpaqueHandle(`opaque_${encoded.toString("hex")}`);
+    }
+    finally {
+        encoded.fill(0);
+        copy.fill(0);
+    }
+});
+const exactRecord = (value, expected) => {
+    assertOrdinaryJsonGraph(value);
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail();
+    const record = value;
+    const keys = Object.keys(record).sort();
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index]))
+        fail();
+    return record;
+};
+const parseVersionMetadata = (value) => normalize(() => {
+    const record = exactRecord(value, VERSION_METADATA_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION)
+        fail();
+    return freeze({ source_version_handle: parseTargetSecretSourceOpaqueHandle(record.source_version_handle), version: TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION });
+});
+const parsePrivateVersionMetadata = (value) => normalize(() => {
+    const record = exactRecord(value, PRIVATE_VERSION_METADATA_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION)
+        fail();
+    const sourceVersionHandle = parseTargetSecretSourceOpaqueHandle(record.source_version_handle);
+    const publicationHandle = parseTargetSecretSourceOpaqueHandle(record.publication_handle);
+    if (sourceVersionHandle === publicationHandle)
+        fail();
+    return freeze({
+        publication_handle: publicationHandle,
+        source_version_handle: sourceVersionHandle,
+        version: TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION
+    });
+});
+const parseVersionPayload = (value) => {
+    const record = exactRecord(value, VERSION_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION || typeof record.secret !== "string")
+        fail();
+    return {
+        metadata: parsePrivateVersionMetadata({
+            publication_handle: record.publication_handle,
+            source_version_handle: record.source_version_handle,
+            version: record.version
+        }),
+        secret: record.secret
+    };
+};
+const parseAliasMetadata = (value) => {
+    const record = exactRecord(value, ALIAS_METADATA_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_ALIAS_RECORD_VERSION)
+        fail();
+    const sourceHandle = parseTargetSecretSourceOpaqueHandle(record.source_handle);
+    const sourceVersionHandle = parseTargetSecretSourceOpaqueHandle(record.source_version_handle);
+    if (sourceHandle === sourceVersionHandle)
+        fail();
+    return freeze({ source_handle: sourceHandle, source_version_handle: sourceVersionHandle, version: TARGET_SECRET_SOURCE_ALIAS_RECORD_VERSION });
+};
+const parseAlias = (value) => {
+    const record = exactRecord(value, ALIAS_KEYS);
+    const metadata = parseAliasMetadata({
+        source_handle: record.source_handle,
+        source_version_handle: record.source_version_handle,
+        version: record.version
+    });
+    const publicationHandle = parseTargetSecretSourceOpaqueHandle(record.publication_handle);
+    if (publicationHandle === metadata.source_handle || publicationHandle === metadata.source_version_handle)
+        fail();
+    return freeze({ publication_handle: publicationHandle, ...metadata });
+};
+export const createTargetSecretSourceVersionRecordBytes = (secret, options = {}) => normalize(() => {
+    const sourceVersionHandle = opaqueHandleFromEntropy(options.entropy ?? defaultEntropy);
+    const publicationHandle = opaqueHandleFromEntropy(options.publicationEntropy ?? defaultEntropy);
+    if (sourceVersionHandle === publicationHandle)
+        fail();
+    const metadata = freeze({
+        source_version_handle: sourceVersionHandle,
+        version: TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION
+    });
+    const privateMetadata = freeze({
+        publication_handle: publicationHandle,
+        ...metadata
+    });
+    const privateBytes = createCanonicalTargetSecretSourceJson({
+        publication_handle: publicationHandle,
+        secret: encodeTargetSecretSourceSecret(secret),
+        source_version_handle: sourceVersionHandle,
+        version: TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION
+    });
+    return { private_bytes: privateBytes, private_metadata: privateMetadata, metadata };
+});
+export const parseTargetSecretSourceVersionRecordBytes = (raw, expectedLeafHandle) => normalize(() => {
+    const expected = parseTargetSecretSourceOpaqueHandle(expectedLeafHandle);
+    const payload = parseVersionPayload(parseCanonicalTargetSecretSourceJson(raw));
+    if (payload.metadata.source_version_handle !== expected)
+        fail();
+    return freeze({ ...payload.metadata, secret: decodeTargetSecretSourceSecret(payload.secret) });
+});
+export const createTargetSecretSourceAliasRecordBytes = (version, options = {}) => normalize(() => {
+    const versionMetadata = parseVersionMetadata(version);
+    const sourceHandle = opaqueHandleFromEntropy(options.entropy ?? defaultEntropy);
+    const publicationHandle = opaqueHandleFromEntropy(options.publicationEntropy ?? defaultEntropy);
+    if (sourceHandle === versionMetadata.source_version_handle
+        || publicationHandle === sourceHandle
+        || publicationHandle === versionMetadata.source_version_handle)
+        fail();
+    const metadata = freeze({ source_handle: sourceHandle, source_version_handle: versionMetadata.source_version_handle, version: TARGET_SECRET_SOURCE_ALIAS_RECORD_VERSION });
+    const privateMetadata = freeze({ publication_handle: publicationHandle, ...metadata });
+    return {
+        private_bytes: createCanonicalTargetSecretSourceJson(privateMetadata),
+        private_metadata: privateMetadata,
+        metadata
+    };
+});
+export const parseTargetSecretSourceAliasRecordBytes = (raw, expectedLeafHandle) => normalize(() => {
+    const expected = parseTargetSecretSourceOpaqueHandle(expectedLeafHandle);
+    const alias = parseTargetSecretSourceAliasRecordBytesForPublication(raw);
+    if (alias.source_handle !== expected)
+        fail();
+    return alias;
+});
+export const parseTargetSecretSourceAliasRecordBytesForPublication = (raw) => normalize(() => parseAlias(parseCanonicalTargetSecretSourceJson(raw)));
+export const assertTargetSecretSourceAliasCorrelation = (alias, version) => normalize(() => {
+    const parsedAlias = parseAliasMetadata(alias);
+    const parsedVersion = parseVersionMetadata(version);
+    if (parsedAlias.source_version_handle !== parsedVersion.source_version_handle)
+        fail();
+});

package/dist/auth/trainingAuth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Grok is deliberately absent. `spawnfile.training-container.v3` holds the one
+ * dedicated training Grok login in a broker-owned realm volume seeded from a
+ * read-only bootstrap leaf, and judges spend it through short inference grants
+ * (D2). Staging a Grok credential into a shared runtime home would put a
+ * rotating login where the evaluator and the image both reach it.
+ */
+export type TrainingAuthProvider = "codex" | "claude";
+export interface TrainingAuthStageOptions {
+    /** Caller-provisioned, existing private runtime home; never a host home mount. */
+    home: string;
+    provider: TrainingAuthProvider;
+    /** Explicit provisioned leaf; default is the fixed training ingress. */
+    source?: string;
+}
+/** Stages opaque credential bytes once. Never imports configuration, logs bytes, or overwrites renewed auth. */
+export declare const stageTrainingAuth: (options: TrainingAuthStageOptions) => Promise<{
+    version: "spawnfile.training-auth-stage.v1";
+    provider: TrainingAuthProvider;
+    destination: string;
+}>;

package/dist/auth/trainingAuth.js

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, realpath, unlink } from "node:fs/promises";
+import path from "node:path";
+const targets = {
+    codex: [".daimon-inbound", "codex-auth"],
+    claude: [".claude", ".credentials.json"]
+};
+/** Stages opaque credential bytes once. Never imports configuration, logs bytes, or overwrites renewed auth. */
+export const stageTrainingAuth = async (options) => {
+    if (!Object.hasOwn(targets, options.provider))
+        throw Error("Unsupported training auth provider");
+    const home = path.resolve(options.home), source = options.source ?? `/run/paideia-auth/${options.provider}`;
+    if (!path.isAbsolute(options.home) || await realpath(home) !== home || !(await lstat(home)).isDirectory())
+        throw Error("Training home must be a canonical existing directory");
+    if (!path.isAbsolute(source) || await realpath(source) !== path.resolve(source))
+        throw Error("Training auth source must be a canonical regular leaf");
+    const input = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await input.stat({ bigint: true });
+        if (!before.isFile() || before.size < 1n || before.size > 1048576n)
+            throw Error("Training auth source must be a bounded nonempty regular leaf");
+        const [folder, leaf] = targets[options.provider];
+        const directory = path.join(home, folder);
+        try {
+            await mkdir(directory, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const existing = await lstat(directory);
+        if (!existing.isDirectory() || existing.isSymbolicLink() || existing.mode % 512 !== 0o700 || await realpath(directory) !== directory)
+            throw Error("Training auth directory must be private and canonical");
+        const bytes = Buffer.alloc(Number(before.size) + 1);
+        let primary;
+        const destination = path.join(directory, leaf), temporary = path.join(directory, `.stage-${randomUUID()}`);
+        try {
+            let length = 0;
+            while (length < bytes.length) {
+                const read = await input.read(bytes, length, bytes.length - length, null);
+                if (read.bytesRead === 0)
+                    break;
+                length += read.bytesRead;
+            }
+            const after = await input.stat({ bigint: true });
+            if (BigInt(length) !== before.size || after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs || after.ino !== before.ino || after.dev !== before.dev || after.birthtimeNs !== before.birthtimeNs)
+                throw Error("Training auth source changed during staging");
+            const output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                await output.writeFile(bytes.subarray(0, length));
+                await output.sync();
+            }
+            finally {
+                await output.close();
+            }
+            // Exclusive publication preserves renewed credentials and never exposes a partial leaf.
+            try {
+                await link(temporary, destination);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    throw Error("Training auth already present; renewed credential preserved");
+                throw error;
+            }
+        }
+        catch (error) {
+            primary = error;
+            throw error;
+        }
+        finally {
+            bytes.fill(0);
+            await unlink(temporary).catch((error) => {
+                if (error.code === "ENOENT")
+                    return;
+                if (primary)
+                    throw new AggregateError([primary, error], "Training auth staging failed and temporary cleanup is incomplete");
+                throw error;
+            });
+        }
+        return { version: "spawnfile.training-auth-stage.v1", provider: options.provider, destination };
+    }
+    finally {
+        await input.close();
+    }
+};

package/dist/auth/types.d.ts

@@ -1,4 +1,4 @@
-export type ImportedAuthKind = "claude-code" | "codex";
+export type ImportedAuthKind = "claude-code" | "codex" | "grok";
 export interface ImportedAuthEntry {
     kind: ImportedAuthKind;
     relativePath: string;

package/dist/cli/artifactsCommands.d.ts

@@ -0,0 +1,27 @@
+import type { Command } from "commander";
+import { exportRunArtifacts, type DeploymentLifecycleCorrelation, type LifecycleInvocation } from "../deployment/index.js";
+import type { CliStreams } from "./runCli.js";
+export interface ArtifactsExportCommandOptions {
+    compiled?: string;
+    deployment?: string;
+    dockerCommand?: string;
+    includePrivate?: boolean;
+    json?: boolean;
+    lifecycleInvocation?: string;
+    out: string;
+    readerImage?: string;
+    runId?: string;
+    timeout?: string;
+}
+export interface ArtifactsCommandHandlers {
+    exportRunArtifacts: typeof exportRunArtifacts;
+}
+export declare const createArtifactsExportLifecyclePolicy: (options: ArtifactsExportCommandOptions) => {
+    destination_directory: string;
+    docker_command: string | null;
+    include_private: boolean;
+    reader_image: string | null;
+    timeout_ms: number | null;
+};
+export declare const createArtifactsExportLifecycleInvocation: (id: string, options: ArtifactsExportCommandOptions, compiled: string, correlation: DeploymentLifecycleCorrelation) => LifecycleInvocation;
+export declare const registerArtifactsCommands: (program: Command, handlers: ArtifactsCommandHandlers, streams: CliStreams) => void;

package/dist/cli/artifactsCommands.js

@@ -0,0 +1,132 @@
+import path from "node:path";
+import { findLifecycleInvocation, resolveArtifactsExportLifecycleCorrelation, } from "../deployment/index.js";
+import { resolveProjectOutputDirectory } from "../filesystem/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
+import { canonicalLifecycleJson } from "../deployment/lifecycleCompletionContracts.js";
+import { runMachineLifecycle } from "./lifecycleMachine.js";
+export const createArtifactsExportLifecyclePolicy = (options) => ({
+    destination_directory: path.resolve(options.out),
+    docker_command: options.dockerCommand ?? null,
+    include_private: options.includePrivate === true,
+    reader_image: options.readerImage ?? null,
+    timeout_ms: options.timeout ? Number(options.timeout) : null,
+});
+export const createArtifactsExportLifecycleInvocation = (id, options, compiled, correlation) => ({
+    correlation: {
+        compiled_output_directory: compiled,
+        deployment_selection: options.deployment ?? null,
+        run_id_selection: options.runId ?? null,
+        ...correlation,
+    },
+    id,
+    operation: "artifacts_export",
+    request_policy: createArtifactsExportLifecyclePolicy(options),
+    version: "spawnfile.lifecycle-invocation.v1",
+});
+const correlationFrom = (stored) => {
+    const value = stored.correlation;
+    if (typeof value.compile_fingerprint !== "string" ||
+        typeof value.deployment_instance_digest !== "string" ||
+        typeof value.deployment !== "string" ||
+        (value.run_id !== null && typeof value.run_id !== "string") ||
+        typeof value.target !== "string")
+        throw new SpawnfileError("runtime_error", "Invalid stored export correlation");
+    return {
+        compile_fingerprint: value.compile_fingerprint,
+        deployment: value.deployment,
+        deployment_instance_digest: value.deployment_instance_digest,
+        run_id: value.run_id,
+        target: value.target,
+    };
+};
+const renderJson = (result) => JSON.stringify({
+    deployment: result.deploymentName,
+    failed_files: result.failedFiles,
+    index: result.index,
+    index_path: result.indexPath,
+    missing_optional_files: result.missingOptionalFiles,
+}, null, 2);
+const renderSummary = (result) => [
+    `exported ${result.index.files.length} file(s) to ${result.indexPath.replace(/[/\\]spawnfile[/\\]export-index\.json$/, "")}`,
+    `deployment: ${result.deploymentName}`,
+    `run: ${result.index.run_id}`,
+    `index: ${result.indexPath}`,
+    ...result.missingOptionalFiles.map((file) => `skipped (not present yet): ${file}`),
+    ...result.failedFiles.map((file) => `FAILED to export: ${file}`),
+];
+export const registerArtifactsCommands = (program, handlers, streams) => {
+    program
+        .command("artifacts")
+        .description("Manage a run's durable artifacts")
+        .command("export")
+        .description("Egress a run's durable artifacts")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .requiredOption("--out <directory>", "Destination run directory")
+        .option("--deployment <name>", "Deployment record name")
+        .option("--run-id <id>", "Run id")
+        .option("--compiled <directory>", "Compile output directory")
+        .option("--docker-command <command>", "Docker command")
+        .option("--include-private", "Export unredacted private runtime training artifacts")
+        .option("--reader-image <image>", "Image used to read named volumes")
+        .option("--timeout <ms>", "Bound each Docker call in milliseconds")
+        .option("--json", "Render machine-readable JSON")
+        .option("--lifecycle-invocation <id>", "Bind this exact JSON invocation")
+        .action(async (inputPath, options) => {
+        if (options.lifecycleInvocation && !options.json)
+            throw new SpawnfileError("validation_error", "--lifecycle-invocation is only valid with --json");
+        const compiled = resolveProjectOutputDirectory(inputPath, options.compiled, DEFAULT_OUTPUT_DIRECTORY);
+        const base = {
+            compiledOutputDirectory: compiled,
+            deploymentName: options.deployment,
+            destinationDirectory: options.out,
+            dockerCommand: options.dockerCommand,
+            includePrivate: options.includePrivate,
+            readerImage: options.readerImage,
+            runId: options.runId,
+            timeoutMs: options.timeout ? Number(options.timeout) : undefined,
+        };
+        if (!options.json) {
+            for (const line of renderSummary(await handlers.exportRunArtifacts(base)))
+                streams.stdout(line);
+            return;
+        }
+        const render = async (expected) => renderJson(await handlers.exportRunArtifacts({
+            ...base,
+            ...(expected ? { expectedLifecycleCorrelation: expected } : {}),
+        }));
+        if (!options.lifecycleInvocation) {
+            streams.stdout(await render());
+            return;
+        }
+        const stored = await findLifecycleInvocation(options.lifecycleInvocation);
+        let exact;
+        let correlation;
+        if (stored) {
+            correlation = correlationFrom(stored);
+            exact = createArtifactsExportLifecycleInvocation(options.lifecycleInvocation, options, compiled, correlation);
+            if (canonicalLifecycleJson(exact) !== canonicalLifecycleJson(stored))
+                throw new SpawnfileError("runtime_error", "Lifecycle invocation id drift");
+        }
+        else {
+            correlation = await resolveArtifactsExportLifecycleCorrelation(base);
+            exact = createArtifactsExportLifecycleInvocation(options.lifecycleInvocation, options, compiled, correlation);
+        }
+        streams.stdout(await runMachineLifecycle(exact, () => render(correlation), async () => {
+            try {
+                const current = await resolveArtifactsExportLifecycleCorrelation(base);
+                return JSON.stringify(current) === JSON.stringify(correlation)
+                    ? { status: "resume_safe" }
+                    : {
+                        reason: "deployment_correlation_changed",
+                        status: "ambiguous",
+                    };
+            }
+            catch {
+                return {
+                    reason: "deployment_correlation_unavailable",
+                    status: "ambiguous",
+                };
+            }
+        }));
+    });
+};

package/dist/cli/authCommands.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+type AuthCommandHandlers = Pick<CliHandlers, "importClaudeCodeAuth" | "importCodexAuth" | "importGrokAuth" | "importEnvFile" | "initializeTargetSecretSourceLifecycle" | "provisionCredentials" | "requireAuthProfile" | "syncProjectAuth">;
+export declare const registerAuthCommands: (program: Command, handlers: AuthCommandHandlers, streams: CliStreams, stdin: AsyncIterable<unknown>) => void;
+export {};