spawnfile 0.1.13 → 0.1.14

package/dist/target/containerBundleFilesystemStore.js

@@ -0,0 +1,247 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { Buffer } from "node:buffer";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { createMemoryTargetLocalBundleStore } from "./containerBundleStore.js";
+const ERROR = "Target-local container bundle store failed";
+const OWNER = process.getuid?.() ?? -1;
+const MAX_RECORD_BYTES = 4_194_304;
+const STALE_LOCK_MS = 60_000;
+const fail = () => { throw new Error(ERROR); };
+const replayInput = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return fail();
+    const value = raw;
+    if (Object.keys(value).sort().join("\0") !== "idempotency_key\0maximum_wait_ms\0request_digest"
+        || typeof value.idempotency_key !== "string" || !/^idem_[a-z0-9]{16,64}$/u.test(value.idempotency_key)
+        || typeof value.request_digest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(value.request_digest)
+        || !Number.isSafeInteger(value.maximum_wait_ms) || value.maximum_wait_ms < 0 || value.maximum_wait_ms > 30_000)
+        return fail();
+    return Object.freeze({ idempotency_key: value.idempotency_key, maximum_wait_ms: value.maximum_wait_ms, request_digest: value.request_digest });
+};
+const secureDirectory = async (raw) => {
+    if (typeof raw !== "string" || !path.isAbsolute(raw) || path.parse(raw).root === raw || raw.length > 4096 || path.normalize(raw) !== raw)
+        fail();
+    /* Resolve pre-existing platform aliases once, then retain physical ancestor
+       identities. Subsequent alias/root swaps cannot redirect a state operation. */
+    const requested = raw;
+    const root = path.join(await realpath(path.dirname(requested)).catch(fail), path.basename(requested));
+    const parsed = path.parse(root);
+    let current = parsed.root;
+    const identities = [];
+    for (const part of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                fail();
+            await mkdir(current, { mode: 0o700 });
+            info = await lstat(current).catch(fail);
+        }
+        if (!info.isDirectory() || info.isSymbolicLink())
+            fail();
+        identities.push(Object.freeze({ dev: info.dev, ino: info.ino, path: current }));
+    }
+    await chmod(root, 0o700).catch(fail);
+    const final = await lstat(root).catch(fail);
+    const rootIdentity = identities.at(-1);
+    if (!rootIdentity || final.dev !== rootIdentity.dev || final.ino !== rootIdentity.ino
+        || final.uid !== OWNER || (final.mode & 0o777) !== 0o700)
+        fail();
+    return Object.freeze({ identities: Object.freeze(identities), path: root });
+};
+const assertSecureDirectory = async (directory) => {
+    for (const expected of directory.identities) {
+        const current = await lstat(expected.path).catch(fail);
+        if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== expected.dev || current.ino !== expected.ino)
+            fail();
+    }
+    const root = await lstat(directory.path).catch(fail);
+    if (root.uid !== OWNER || (root.mode & 0o777) !== 0o700)
+        fail();
+};
+const read = async (directory, file, maximum = MAX_RECORD_BYTES) => {
+    await assertSecureDirectory(directory);
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            await assertSecureDirectory(directory);
+            return null;
+        }
+        fail();
+    }
+    try {
+        const opened = handle;
+        const stat = await opened.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== OWNER || (stat.mode & 0o777) !== 0o600 || stat.size > maximum)
+            fail();
+        const bytes = await opened.readFile();
+        await assertSecureDirectory(directory);
+        return bytes;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};
+const syncDirectory = async (directory) => { const handle = await open(directory, constants.O_RDONLY); try {
+    await handle.sync();
+}
+finally {
+    await handle.close();
+} };
+const write = async (directory, file, content) => {
+    await assertSecureDirectory(directory);
+    const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    let handle;
+    try {
+        handle = await open(temp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(content);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await assertSecureDirectory(directory);
+        await rename(temp, file);
+        await syncDirectory(path.dirname(file));
+        await assertSecureDirectory(directory);
+    }
+    catch {
+        await handle?.close().catch(() => undefined);
+        fail();
+    }
+};
+const acquire = async (directory, lock) => {
+    for (let attempt = 0; attempt < 600; attempt += 1) {
+        await assertSecureDirectory(directory);
+        try {
+            const handle = await open(lock, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            await handle.close();
+            await assertSecureDirectory(directory);
+            return async () => { await assertSecureDirectory(directory); await unlink(lock).catch(fail); await assertSecureDirectory(directory); };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                fail();
+            const current = await lstat(lock).catch(() => null);
+            if (!current)
+                continue;
+            if (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1 || current.uid !== OWNER || (current.mode & 0o777) !== 0o600)
+                fail();
+            if (Date.now() - current.mtimeMs > STALE_LOCK_MS) {
+                await unlink(lock).catch(() => undefined);
+                continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    return fail();
+};
+/** Secure single-file persistence around the strict exact-key store. */
+export const initializeFilesystemTargetLocalBundleStore = async (root) => {
+    const directory = await secureDirectory(root);
+    const archives = await secureDirectory(path.join(directory.path, "archives"));
+    const file = path.join(directory.path, "container-bundles.json");
+    const lock = `${file}.lock`;
+    const archive = async (digest) => {
+        if (typeof digest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(digest))
+            fail();
+        const exactDigest = digest;
+        const bytes = await read(archives, path.join(archives.path, exactDigest.slice(7)), 4_194_304);
+        if (!bytes || bytes.byteLength > 4_194_304 || `sha256:${createHash("sha256").update(bytes).digest("hex")}` !== exactDigest)
+            fail();
+        return bytes;
+    };
+    const writeArchive = async (request) => {
+        const bytes = Buffer.from(request.archive_base64, "base64");
+        if (bytes.byteLength > 4_194_304 || `sha256:${createHash("sha256").update(bytes).digest("hex")}` !== request.archive_digest)
+            fail();
+        const target = path.join(archives.path, request.archive_digest.slice(7));
+        const current = await read(archives, target, 4_194_304);
+        if (current && !current.equals(bytes))
+            fail();
+        else if (!current)
+            await write(archives, target, bytes);
+    };
+    const load = async () => {
+        await assertSecureDirectory(directory);
+        await assertSecureDirectory(archives);
+        const store = createMemoryTargetLocalBundleStore();
+        const text = await read(directory, file);
+        if (!text)
+            return store;
+        let state;
+        try {
+            state = JSON.parse(text.toString("utf8"));
+        }
+        catch {
+            fail();
+        }
+        if (!state || typeof state !== "object" || Array.isArray(state))
+            fail();
+        const value = state;
+        const records = value.records;
+        if (!Array.isArray(records) || Object.keys(value).sort().join("\0") !== "records\0version"
+            || value.version !== "spawnfile.target-local-container-bundle.private.v2")
+            fail();
+        const hydrated = await Promise.all(records.map(async (raw) => {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                fail();
+            const record = raw;
+            if (!record.request || typeof record.request !== "object" || Array.isArray(record.request))
+                fail();
+            const request = record.request;
+            if (Object.keys(request).includes("archive_base64") || typeof request.archive_digest !== "string")
+                fail();
+            return { ...record, request: { ...request, archive_base64: (await archive(request.archive_digest)).toString("base64") } };
+        }));
+        store.restore(hydrated);
+        return store;
+    };
+    const save = async (store) => {
+        const records = store.snapshot();
+        await Promise.all(records.map((record) => writeArchive(record.request)));
+        const privateRecords = records.map(({ request, ...record }) => { const { archive_base64: _archive, ...metadata } = request; return { ...record, request: metadata }; });
+        await write(directory, file, JSON.stringify({ records: privateRecords, version: "spawnfile.target-local-container-bundle.private.v2" }));
+    };
+    const mutate = async (action) => { const release = await acquire(directory, lock); try {
+        const store = await load();
+        const result = await action(store);
+        await save(store);
+        return result;
+    }
+    finally {
+        await release();
+    } };
+    /* The production adapter persists its exact mapping separately; this store keeps
+       admissions strict and intentionally exposes no scan/list primitive. */
+    const store = {
+        awaitReplay: async (raw) => {
+            const value = replayInput(raw);
+            const deadline = Date.now() + value.maximum_wait_ms;
+            for (;;) {
+                const result = await load().then((memory) => memory.lookup(value));
+                if (result.status !== "pending" || Date.now() >= deadline)
+                    return result;
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+        },
+        beginBuild: (value) => mutate((memory) => memory.beginBuild(value)),
+        reserve: (raw) => mutate((memory) => memory.reserve(raw)),
+        renew: (value) => mutate((memory) => memory.renew(value)),
+        retryMissingCompleted: (value) => mutate((memory) => memory.retryMissingCompleted(value)),
+        retryPrebuild: (value) => mutate((memory) => memory.retryPrebuild(value)),
+        complete: (value) => mutate((memory) => memory.complete(value)),
+        markIncomplete: (value) => mutate((memory) => memory.markIncomplete(value)),
+        resolve: (value) => load().then((memory) => memory.resolve(value)),
+        resolvePrepared: (value) => load().then((memory) => memory.resolvePrepared(value)),
+        stagePostbuild: (value) => mutate((memory) => memory.stagePostbuild(value)),
+        lookup: (value) => load().then((memory) => memory.lookup(value))
+    };
+    return Object.freeze(store);
+};

package/dist/target/containerBundlePolicy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Private policy derivation for a target-local Docker bundle build. This
+ * intentionally produces only commitment digests; the base-image config ID
+ * remains an operator-side configuration input and is never a public receipt
+ * field.
+ */
+export declare const TARGET_LOCAL_CONTAINER_BUNDLE_POLICY: Readonly<{
+    builder: Readonly<{
+        dockerfile: "FROM pinned-config; WORKDIR /opt/bundle; COPY bundle; ENTRYPOINT node /opt/bundle/<entrypoint>; CMD []";
+        network: "none";
+        pull: false;
+        version: "spawnfile.target-local-container-bundle.builder.v1";
+    }>;
+    version: "spawnfile.target-local-container-bundle-policy.v1";
+}>;
+export interface TargetLocalContainerBundlePolicyInput {
+    readonly archiveDigest: string;
+    readonly artifactDigest: string;
+    readonly baseImageConfigDigest: string;
+    readonly bundleDigest: string;
+    readonly entrypoint: string;
+    readonly launcherDigest: string;
+    readonly networkAlias: string;
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+}
+/** One frozen derivation binds immutable bundle claims to the generic builder. */
+export declare const deriveTargetLocalContainerBundlePolicy: (raw: TargetLocalContainerBundlePolicyInput) => Readonly<{
+    readonly buildPolicyDigest: `sha256:${string}`;
+    readonly platformDigest: `sha256:${string}`;
+}>;

package/dist/target/containerBundlePolicy.js

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto";
+/**
+ * Private policy derivation for a target-local Docker bundle build. This
+ * intentionally produces only commitment digests; the base-image config ID
+ * remains an operator-side configuration input and is never a public receipt
+ * field.
+ */
+export const TARGET_LOCAL_CONTAINER_BUNDLE_POLICY = Object.freeze({
+    builder: Object.freeze({
+        dockerfile: "FROM pinned-config; WORKDIR /opt/bundle; COPY bundle; ENTRYPOINT node /opt/bundle/<entrypoint>; CMD []",
+        network: "none",
+        pull: false,
+        version: "spawnfile.target-local-container-bundle.builder.v1"
+    }),
+    version: "spawnfile.target-local-container-bundle-policy.v1"
+});
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ENTRYPOINT = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,239}$/u;
+const ALIAS = /^[a-z][a-z0-9-]{0,62}$/u;
+const fail = () => {
+    throw new Error("Target-local container bundle policy failed");
+};
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const entry = value;
+        return `{${Object.keys(entry).sort().map((key) => `${JSON.stringify(key)}:${canonical(entry[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+const digest = (domain, value) => `sha256:${createHash("sha256")
+    .update(`spawnfile.target-local-container-bundle.${domain}.v1\0`, "utf8")
+    .update(canonical(value), "utf8").digest("hex")}`;
+/** One frozen derivation binds immutable bundle claims to the generic builder. */
+export const deriveTargetLocalContainerBundlePolicy = (raw) => {
+    if (!raw || typeof raw !== "object"
+        || ![raw.archiveDigest, raw.artifactDigest, raw.baseImageConfigDigest, raw.bundleDigest, raw.launcherDigest]
+            .every((value) => typeof value === "string" && DIGEST.test(value))
+        || typeof raw.entrypoint !== "string" || !ENTRYPOINT.test(raw.entrypoint)
+        || raw.entrypoint.includes("//") || raw.entrypoint.split("/").some((part) => part === "." || part === "..")
+        || typeof raw.networkAlias !== "string" || !ALIAS.test(raw.networkAlias)
+        || !raw.platform || raw.platform.os !== "linux"
+        || (raw.platform.architecture !== "amd64" && raw.platform.architecture !== "arm64"))
+        fail();
+    const platform = Object.freeze({ architecture: raw.platform.architecture, os: "linux" });
+    const platformDigest = digest("platform", platform);
+    const buildPolicyDigest = digest("build-policy", {
+        builder: TARGET_LOCAL_CONTAINER_BUNDLE_POLICY.builder,
+        claims: {
+            archive_digest: raw.archiveDigest,
+            artifact_digest: raw.artifactDigest,
+            base_image_config_digest: raw.baseImageConfigDigest,
+            bundle_digest: raw.bundleDigest,
+            entrypoint: raw.entrypoint,
+            launcher_digest: raw.launcherDigest,
+            network_alias: raw.networkAlias,
+            platform,
+            platform_digest: platformDigest
+        },
+        version: TARGET_LOCAL_CONTAINER_BUNDLE_POLICY.version
+    });
+    return Object.freeze({ buildPolicyDigest, platformDigest });
+};

package/dist/target/containerBundleStore.d.ts

@@ -0,0 +1,127 @@
+import { type TargetLocalBundleLookup, type TargetLocalBundlePrepareReceipt, type TargetLocalBundlePrepareRequest } from "./containerBundleContracts.js";
+import { type OpaqueTargetHandle } from "./contracts.js";
+export interface TargetLocalBundlePrivateMapping {
+    readonly archive_digest: string;
+    readonly artifact_digest: string;
+    readonly base_image_config_digest: string;
+    readonly build_policy_digest: string;
+    readonly bundle_digest: string;
+    readonly config_id: string;
+    readonly daemon_epoch: string;
+    readonly entrypoint: string;
+    readonly gc_tag: string;
+    readonly identity_kind: "docker_image_config_digest";
+    readonly launcher_digest: string;
+    readonly network_alias: string;
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+    readonly platform_digest: string;
+    readonly request_digest: string;
+    readonly selected_target: TargetLocalBundlePrepareRequest["selected_target"];
+}
+export interface TargetLocalBundleLease {
+    readonly generation: number;
+    readonly lease_id: string;
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly request_digest: string;
+}
+export type TargetLocalBundleWorkState = "prebuild" | "inflight" | "postbuild";
+export type TargetLocalBundleReservation = {
+    readonly kind: "owner";
+    readonly lease: TargetLocalBundleLease;
+    readonly mapping?: TargetLocalBundlePrivateMapping;
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly request_digest: string;
+    readonly state: TargetLocalBundleWorkState;
+} | {
+    readonly generation: number;
+    readonly kind: "replay";
+    readonly mapping: TargetLocalBundlePrivateMapping;
+    readonly receipt: TargetLocalBundlePrepareReceipt;
+} | {
+    readonly kind: "pending";
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly request_digest: string;
+    readonly state: TargetLocalBundleWorkState;
+} | {
+    readonly kind: "incomplete";
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly request_digest: string;
+};
+export interface TargetLocalBundleStore {
+    /** Read-only, bounded join for another durable owner. It never reserves or recovers work. */
+    awaitReplay(input: {
+        readonly idempotency_key: unknown;
+        readonly maximum_wait_ms: unknown;
+        readonly request_digest: unknown;
+    }): Promise<TargetLocalBundleLookup>;
+    beginBuild(input: {
+        readonly lease: unknown;
+    }): Promise<TargetLocalBundleLease>;
+    complete(input: {
+        readonly lease: unknown;
+        readonly mapping: TargetLocalBundlePrivateMapping;
+        readonly receipt: unknown;
+    }): Promise<TargetLocalBundlePrepareReceipt>;
+    lookup(input: {
+        readonly idempotency_key: unknown;
+        readonly request_digest: unknown;
+    }): Promise<TargetLocalBundleLookup>;
+    markIncomplete(input: {
+        readonly lease: unknown;
+        readonly operation_handle: unknown;
+        readonly request_digest: unknown;
+    }): Promise<void>;
+    reserve(raw: unknown): Promise<TargetLocalBundleReservation>;
+    renew(input: {
+        readonly lease: unknown;
+    }): Promise<TargetLocalBundleLease>;
+    /** Atomically reclaims only the completed generation whose exact anchor was proven absent. */
+    retryMissingCompleted(input: {
+        readonly generation: unknown;
+        readonly operation_handle: unknown;
+        readonly request_digest: unknown;
+    }): Promise<TargetLocalBundleReservation>;
+    /** A reclaimed owner may retry only a proven absent pre-effect. */
+    retryPrebuild(input: {
+        readonly lease: unknown;
+    }): Promise<TargetLocalBundleLease>;
+    resolve(input: {
+        readonly operation_handle: unknown;
+        readonly request_digest: unknown;
+    }): Promise<TargetLocalBundlePrivateMapping | null>;
+    resolvePrepared(input: {
+        readonly artifact_digest: unknown;
+        readonly build_policy_digest: unknown;
+        readonly bundle_digest: unknown;
+        readonly selected_target: unknown;
+    }): Promise<{
+        readonly mapping: TargetLocalBundlePrivateMapping;
+        readonly request: TargetLocalBundlePrepareRequest;
+    } | null>;
+    stagePostbuild(input: {
+        readonly lease: unknown;
+        readonly mapping: TargetLocalBundlePrivateMapping;
+    }): Promise<TargetLocalBundleLease>;
+}
+export interface TargetLocalBundleStoredRecord {
+    readonly generation: number;
+    readonly idempotency_key: string;
+    readonly lease_expires_at: number | null;
+    readonly lease_id: string | null;
+    readonly mapping?: TargetLocalBundlePrivateMapping;
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly receipt?: TargetLocalBundlePrepareReceipt;
+    readonly request: TargetLocalBundlePrepareRequest;
+    readonly request_digest: string;
+    readonly state: TargetLocalBundleWorkState | "completed" | "incomplete";
+}
+export interface TargetLocalBundleMemoryStore extends TargetLocalBundleStore {
+    restore(records: readonly unknown[]): void;
+    snapshot(): readonly TargetLocalBundleStoredRecord[];
+}
+/** Exact-key private store. It never enumerates Docker state or admits inverse config-ID lookup. */
+export declare const createMemoryTargetLocalBundleStore: () => TargetLocalBundleMemoryStore;