spawnfile 0.1.13 → 0.1.17

package/dist/target/cleanupRun.d.ts

@@ -0,0 +1,41 @@
+import { type OpaqueTargetHandle, type TargetResourceReceipt, type TargetResourceRequest } from "./contracts.js";
+import { type TargetJournalClaim, type TargetJournalStore } from "./journal.js";
+type CleanupRequest = Extract<TargetResourceRequest, {
+    operation: "cleanup_run";
+}>;
+export interface CleanupRunResource {
+    readonly authority: unknown;
+    readonly handle: OpaqueTargetHandle;
+}
+export interface CleanupRunPlan {
+    readonly attachment: CleanupRunResource | null;
+    readonly cleanupPolicy: CleanupRequest["cleanup_policy"];
+    readonly dataNetwork: CleanupRunResource | null;
+    readonly evidence: CleanupRunResource | null;
+    readonly exportState: "exported" | "incomplete" | "not_requested";
+    readonly secrets: CleanupRunResource | null;
+    readonly world: CleanupRunResource | null;
+}
+export interface CleanupRunOperationsOptions {
+    readonly journal: TargetJournalStore;
+    readonly prepare: (input: {
+        readonly claim: TargetJournalClaim;
+        readonly request: CleanupRequest;
+    }) => Promise<CleanupRunPlan>;
+    readonly steps: {
+        readonly detachAttachment: (resource: CleanupRunResource) => Promise<void>;
+        readonly preserveEvidence: (resource: CleanupRunResource) => Promise<void>;
+        readonly removeDataNetwork: (resource: CleanupRunResource) => Promise<void>;
+        readonly removeEvidence: (resource: CleanupRunResource) => Promise<void>;
+        readonly removeSecrets: (resource: CleanupRunResource) => Promise<void>;
+        readonly removeWorld: (resource: CleanupRunResource) => Promise<void>;
+    };
+}
+export interface CleanupRunOperations {
+    execute(raw: unknown): Promise<{
+        readonly receipt: TargetResourceReceipt;
+        readonly receiptBytes: string;
+    }>;
+}
+export declare const createCleanupRunOperations: (options: CleanupRunOperationsOptions) => CleanupRunOperations;
+export {};

package/dist/target/cleanupRun.js

@@ -0,0 +1,139 @@
+import { SpawnfileError } from "../shared/index.js";
+import { TARGET_RESOURCE_RECEIPT_VERSION, parseOpaqueTargetHandle, parseTargetResourceRequest } from "./contracts.js";
+import { createTargetReceiptDigest } from "./handles.js";
+const CLEANUP_ERROR = "Target cleanup failed";
+const fail = () => { throw new SpawnfileError("runtime_error", CLEANUP_ERROR); };
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const exactKeys = (value, expected) => {
+    const keys = Object.keys(value).sort();
+    return keys.length === expected.length && keys.every((key, index) => key === expected[index]);
+};
+const request = (raw) => {
+    const value = parseTargetResourceRequest(raw);
+    if (value.operation !== "cleanup_run"
+        || value.cleanup_policy === "preserve_evidence" && value.evidence_volume_handle === undefined)
+        return fail();
+    return value;
+};
+const resource = (raw, expected) => {
+    if (!record(raw) || !Object.isFrozen(raw) || !exactKeys(raw, ["authority", "handle"]))
+        return fail();
+    const handle = parseOpaqueTargetHandle(raw.handle);
+    if (expected !== undefined && handle !== expected)
+        return fail();
+    return raw;
+};
+const optionalResource = (raw, expected) => {
+    if (expected === undefined) {
+        if (raw !== null)
+            return fail();
+        return null;
+    }
+    return resource(raw, expected);
+};
+const plan = (raw, value) => {
+    if (!record(raw) || !Object.isFrozen(raw) || !exactKeys(raw, [
+        "attachment", "cleanupPolicy", "dataNetwork", "evidence", "exportState", "secrets", "world"
+    ]) || raw.cleanupPolicy !== value.cleanup_policy
+        || raw.exportState !== "exported" && raw.exportState !== "incomplete"
+            && raw.exportState !== "not_requested")
+        return fail();
+    const attachment = optionalResource(raw.attachment, value.organization_attachment_handle);
+    const dataNetwork = raw.dataNetwork === null ? null : resource(raw.dataNetwork);
+    const evidence = optionalResource(raw.evidence, value.evidence_volume_handle);
+    const world = optionalResource(raw.world, value.world_service_handle);
+    if ((evidence === null) !== (raw.exportState === "not_requested")
+        || dataNetwork === null && (world !== null || attachment !== null))
+        return fail();
+    return Object.freeze({
+        attachment,
+        cleanupPolicy: value.cleanup_policy,
+        dataNetwork,
+        evidence,
+        exportState: raw.exportState,
+        secrets: optionalResource(raw.secrets, value.secret_bindings_handle),
+        world
+    });
+};
+const receipt = (value, claim, prepared) => {
+    const raw = {
+        cleanup_state: value.cleanup_policy === "preserve_evidence" ? "preserved" : "removed",
+        descriptor_digest: value.descriptor_digest,
+        export_state: prepared.exportState,
+        labels: [],
+        operation: value.operation,
+        operation_handle: claim.operationHandle,
+        receipt_digest: `sha256:${"0".repeat(64)}`,
+        request_digest: claim.requestDigest,
+        result_handle: value.cleanup_policy === "preserve_evidence"
+            ? prepared.evidence.handle : null,
+        resulting_revision: value.expected_revision + 1,
+        run_id: value.run_id,
+        selected_target: value.selected_target,
+        version: TARGET_RESOURCE_RECEIPT_VERSION
+    };
+    return { ...raw, receipt_digest: createTargetReceiptDigest(raw) };
+};
+class Operations {
+    #live = new Map();
+    #options;
+    constructor(options) { this.#options = options; }
+    execute(raw) {
+        let value;
+        try {
+            value = request(raw);
+        }
+        catch {
+            return Promise.reject(new SpawnfileError("runtime_error", CLEANUP_ERROR));
+        }
+        const active = this.#live.get(value.idempotency_key);
+        if (active)
+            return same(active.request, value) ? active.promise
+                : Promise.reject(new SpawnfileError("runtime_error", CLEANUP_ERROR));
+        const promise = this.#owner(value).finally(() => {
+            if (this.#live.get(value.idempotency_key)?.promise === promise) {
+                this.#live.delete(value.idempotency_key);
+            }
+        });
+        this.#live.set(value.idempotency_key, { promise, request: value });
+        return promise;
+    }
+    async #owner(value) {
+        try {
+            const reservation = await this.#options.journal.reserve(value);
+            if (reservation.kind === "replay") {
+                return { receipt: reservation.receipt, receiptBytes: reservation.receiptBytes };
+            }
+            const prepared = plan(await this.#options.prepare({ claim: reservation.claim, request: value }), value);
+            if (prepared.world)
+                await this.#options.steps.removeWorld(prepared.world);
+            if (prepared.attachment)
+                await this.#options.steps.detachAttachment(prepared.attachment);
+            if (prepared.secrets)
+                await this.#options.steps.removeSecrets(prepared.secrets);
+            if (prepared.evidence) {
+                if (prepared.cleanupPolicy === "preserve_evidence") {
+                    await this.#options.steps.preserveEvidence(prepared.evidence);
+                }
+                else {
+                    await this.#options.steps.removeEvidence(prepared.evidence);
+                }
+            }
+            if (prepared.dataNetwork) {
+                await this.#options.steps.removeDataNetwork(prepared.dataNetwork);
+            }
+            return await this.#options.journal.complete(reservation.claim, receipt(value, reservation.claim, prepared));
+        }
+        catch {
+            return fail();
+        }
+    }
+}
+export const createCleanupRunOperations = (options) => {
+    if (!options?.journal || typeof options.journal.reserve !== "function"
+        || typeof options.journal.complete !== "function" || typeof options.prepare !== "function"
+        || !options.steps || Object.values(options.steps).some((step) => typeof step !== "function"))
+        return fail();
+    return new Operations(options);
+};

package/dist/target/cleanupRunDocker.d.ts

@@ -0,0 +1,16 @@
+import { type CleanupRunOperations } from "./cleanupRun.js";
+import { type DockerCleanupRunPreflightOptions } from "./cleanupRunDockerPreflight.js";
+import { type DockerSecretExecutor } from "./dockerSecretsProvider.js";
+import { type DockerResourceExecutor } from "./dockerResourcesProvider.js";
+import { type DockerWorldServiceExecutor } from "./dockerWorldServiceProvider.js";
+import { type DockerOrganizationAttachmentExecutor } from "./organizationAttachmentProvider.js";
+export interface DockerCleanupRunOptions extends DockerCleanupRunPreflightOptions {
+    readonly attachmentExecutor: DockerOrganizationAttachmentExecutor;
+    readonly context: string;
+    readonly resourceExecutor: DockerResourceExecutor;
+    readonly secretExecutor: DockerSecretExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+    readonly worldExecutor: DockerWorldServiceExecutor;
+}
+export declare const createDockerCleanupRunOperations: (rawOptions: DockerCleanupRunOptions) => CleanupRunOperations;

package/dist/target/cleanupRunDocker.js

@@ -0,0 +1,66 @@
+import { SpawnfileError } from "../shared/index.js";
+import { createCleanupRunOperations } from "./cleanupRun.js";
+import { prepareDockerCleanupRun } from "./cleanupRunDockerPreflight.js";
+import { cleanupExactDockerSecretBindings } from "./dockerSecretsLifecycle.js";
+import { proveExactDockerResourcePresent, removeExactDockerResource } from "./dockerResources.js";
+import { removeExactDockerWorldService } from "./dockerWorldServiceLifecycle.js";
+import { detachExactOrganizationAttachment } from "./organizationAttachmentLifecycle.js";
+const CLEANUP_ERROR = "Target cleanup failed";
+const CONTEXT = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => {
+    throw new SpawnfileError("runtime_error", CLEANUP_ERROR);
+};
+const validateOptions = (raw) => {
+    if (!raw || typeof raw.context !== "string" || !CONTEXT.test(raw.context)
+        || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1
+        || raw.timeoutMs > 120_000 || typeof raw.attachmentExecutor !== "function"
+        || typeof raw.resourceExecutor !== "function"
+        || typeof raw.secretExecutor !== "function"
+        || typeof raw.worldExecutor !== "function" || !raw.journal
+        || typeof raw.journal.read !== "function"
+        || typeof raw.journal.resolveCompletedReceipt !== "function"
+        || !raw.attachmentStore
+        || typeof raw.attachmentStore.loadAttachment !== "function"
+        || !raw.worldStore || typeof raw.worldStore.loadService !== "function"
+        || !raw.evidenceExportStore
+        || typeof raw.evidenceExportStore.loadAdmission !== "function"
+        || typeof raw.evidenceExportStore.loadIndex !== "function")
+        return fail();
+    return raw;
+};
+export const createDockerCleanupRunOperations = (rawOptions) => {
+    const options = validateOptions(rawOptions);
+    const resourceOptions = {
+        context: options.context,
+        executor: options.resourceExecutor,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs
+    };
+    return createCleanupRunOperations({
+        journal: options.journal,
+        prepare: async ({ request }) => prepareDockerCleanupRun(request, options),
+        steps: {
+            detachAttachment: async ({ authority }) => detachExactOrganizationAttachment(authority, {
+                context: options.context,
+                executor: options.attachmentExecutor,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs
+            }),
+            preserveEvidence: async ({ authority }) => proveExactDockerResourcePresent(authority, resourceOptions),
+            removeDataNetwork: async ({ authority }) => removeExactDockerResource(authority, resourceOptions),
+            removeEvidence: async ({ authority }) => removeExactDockerResource(authority, resourceOptions),
+            removeSecrets: async ({ authority }) => cleanupExactDockerSecretBindings(authority, {
+                context: options.context,
+                executor: options.secretExecutor,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs
+            }),
+            removeWorld: async ({ authority }) => removeExactDockerWorldService(authority, {
+                context: options.context,
+                executor: options.worldExecutor,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs
+            })
+        }
+    });
+};

package/dist/target/cleanupRunDockerPreflight.d.ts

@@ -0,0 +1,17 @@
+import { type TargetResourceRequest } from "./contracts.js";
+import { type CleanupRunPlan } from "./cleanupRun.js";
+import { type WorldServiceAuthorityStore } from "./dockerWorldServiceStore.js";
+import { type EvidenceExportAuthorityStore } from "./evidenceExportStore.js";
+import { type OrganizationAttachmentAuthorityStore } from "./organizationAttachmentStore.js";
+import { type TargetJournalStore } from "./journal.js";
+type CleanupRequest = Extract<TargetResourceRequest, {
+    operation: "cleanup_run";
+}>;
+export interface DockerCleanupRunPreflightOptions {
+    readonly attachmentStore: OrganizationAttachmentAuthorityStore;
+    readonly evidenceExportStore: EvidenceExportAuthorityStore;
+    readonly journal: TargetJournalStore;
+    readonly worldStore: WorldServiceAuthorityStore;
+}
+export declare const prepareDockerCleanupRun: (request: CleanupRequest, options: DockerCleanupRunPreflightOptions) => Promise<CleanupRunPlan>;
+export {};

package/dist/target/cleanupRunDockerPreflight.js

@@ -0,0 +1,224 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseTargetResourceExportIndex } from "./contracts.js";
+import { createExistingDockerSecretSpec } from "./dockerSecretsProvider.js";
+import { createDockerResourceSpec } from "./dockerResourcesProvider.js";
+import { parseWorldServiceBinding } from "./dockerWorldServiceStore.js";
+import { createEvidenceExportHandle, evidenceReceiptLabels, parseEvidenceVolumeAuthority } from "./evidenceExportProvider.js";
+import { parseOrganizationAttachmentBinding } from "./organizationAttachmentStore.js";
+const CLEANUP_ERROR = "Target cleanup failed";
+const fail = () => {
+    throw new SpawnfileError("runtime_error", CLEANUP_ERROR);
+};
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const requestDigest = (raw) => {
+    if (!/^sha256:[a-f0-9]{64}$/u.test(raw))
+        return fail();
+    return raw;
+};
+const resource = (handle, authority) => Object.freeze({ authority, handle });
+const roleFor = (operation) => {
+    switch (operation) {
+        case "attach_organization": return "attachment";
+        case "create_data_network": return "dataNetwork";
+        case "create_evidence_volume": return "evidence";
+        case "prepare_secret_bindings": return "secrets";
+        case "create_world_service": return "world";
+        default: return null;
+    }
+};
+const completedEntries = async (request, options) => {
+    const snapshot = await options.journal.read();
+    if (snapshot.run_id !== request.run_id
+        || snapshot.descriptor_digest !== request.descriptor_digest
+        || !same(snapshot.selected_target, request.selected_target))
+        return fail();
+    const completed = [];
+    for (const entry of snapshot.entries) {
+        if (entry.state !== "completed")
+            continue;
+        const digest = requestDigest(entry.request_digest);
+        const resolved = await options.journal.resolveCompletedReceipt({
+            operationHandle: entry.operation_handle,
+            requestDigest: digest
+        });
+        if (!resolved)
+            return fail();
+        const receipt = resolved.receipt;
+        if (receipt.operation !== entry.operation
+            || receipt.operation_handle !== entry.operation_handle
+            || receipt.request_digest !== entry.request_digest
+            || receipt.run_id !== request.run_id
+            || receipt.descriptor_digest !== request.descriptor_digest
+            || !same(receipt.selected_target, request.selected_target))
+            return fail();
+        completed.push({
+            entry: {
+                operation: entry.operation,
+                operation_handle: entry.operation_handle,
+                request_digest: digest
+            },
+            receipt
+        });
+    }
+    return completed;
+};
+const exactRoles = (completed) => {
+    const roles = new Map();
+    for (const item of completed) {
+        const role = roleFor(item.entry.operation);
+        if (!role)
+            continue;
+        if (roles.has(role) || item.receipt.result_handle === null)
+            return fail();
+        roles.set(role, item);
+    }
+    return roles;
+};
+const requireRole = (roles, role, supplied) => {
+    const found = roles.get(role);
+    if ((found === undefined) !== (supplied === undefined))
+        return fail();
+    if (!found)
+        return null;
+    if (found.receipt.result_handle !== supplied)
+        return fail();
+    return found;
+};
+const specFor = (kind, completed, request) => {
+    const spec = createDockerResourceSpec({
+        kind,
+        operationHandle: completed.entry.operation_handle,
+        requestDigest: completed.entry.request_digest,
+        runId: request.run_id,
+        selectedTargetHandle: request.selected_target.handle
+    });
+    if (spec.resultHandle !== completed.receipt.result_handle)
+        return fail();
+    return spec;
+};
+const matchingWorld = (binding, request, network, evidence, secretAuthority) => {
+    const secretSpec = secretAuthority
+        ? createExistingDockerSecretSpec(secretAuthority) : null;
+    if (binding.world_service_handle !== request.world_service_handle
+        || binding.resolution.authorization.run_id !== request.run_id
+        || binding.resolution.authorization.descriptor_digest !== request.descriptor_digest
+        || !same(binding.resolution.authorization.selected_target, request.selected_target)
+        || binding.resources.data_network.handle !== network.resultHandle
+        || binding.resources.data_network.name !== network.name
+        || !same(binding.resources.data_network.labels, network.labels)
+        || binding.resources.evidence_volume.handle !== evidence?.resultHandle
+        || binding.resources.evidence_volume.name !== evidence?.name
+        || !same(binding.resources.evidence_volume.labels, evidence?.labels)
+        || binding.resources.secret_bindings.handle !== secretSpec?.resultHandle
+        || binding.resources.secret_bindings.name !== secretSpec?.volumeName
+        || !same(binding.resources.secret_bindings.labels, secretSpec?.labels))
+        return fail();
+};
+const matchingAttachment = (binding, request, network) => {
+    if (binding.attachment_handle !== request.organization_attachment_handle
+        || binding.resolution.authorization.run_id !== request.run_id
+        || binding.resolution.authorization.descriptor_digest !== request.descriptor_digest
+        || !same(binding.resolution.authorization.selected_target, request.selected_target)
+        || binding.data_network.handle !== network.resultHandle
+        || binding.data_network.name !== network.name
+        || !same(binding.data_network.labels, network.labels))
+        return fail();
+};
+const exportState = async (evidence, completed, request, options) => {
+    const exports = completed.filter(({ entry }) => entry.operation === "export_evidence_volume");
+    if (!evidence) {
+        if (exports.length !== 0)
+            return fail();
+        return "not_requested";
+    }
+    if (exports.length === 0)
+        return "incomplete";
+    if (exports.length !== 1)
+        return fail();
+    const exported = exports[0];
+    if (exported.receipt.export_state !== "exported"
+        || exported.receipt.result_handle === null)
+        return fail();
+    const admission = await options.evidenceExportStore.loadAdmission(exported.entry.operation_handle);
+    const evidenceAuthority = parseEvidenceVolumeAuthority(admission.evidence_volume);
+    if (admission.operation_handle !== exported.entry.operation_handle
+        || admission.request_digest !== exported.entry.request_digest
+        || evidenceAuthority.resultHandle !== evidence.resultHandle
+        || evidenceAuthority.name !== evidence.name
+        || !same(evidenceAuthority.labels, evidence.labels)
+        || admission.run_id !== request.run_id
+        || admission.descriptor_digest !== request.descriptor_digest
+        || !same(admission.selected_target, request.selected_target))
+        return fail();
+    const loaded = await options.evidenceExportStore.loadIndex(admission);
+    if (!loaded)
+        return fail();
+    const index = parseTargetResourceExportIndex(loaded.index);
+    const expectedExportHandle = createEvidenceExportHandle({
+        evidenceVolumeHandle: evidence.resultHandle,
+        operationHandle: exported.entry.operation_handle,
+        requestDigest: exported.entry.request_digest
+    });
+    if (index.state !== "exported" || index.run_id !== request.run_id
+        || index.export_handle !== expectedExportHandle
+        || exported.receipt.result_handle !== expectedExportHandle
+        || !same(index.labels, evidenceReceiptLabels(evidenceAuthority))
+        || !same(exported.receipt.labels, index.labels))
+        return fail();
+    return "exported";
+};
+export const prepareDockerCleanupRun = async (request, options) => {
+    const completed = await completedEntries(request, options);
+    const roles = exactRoles(completed);
+    const networkCompleted = roles.get("dataNetwork");
+    const network = networkCompleted
+        ? specFor("data_network", networkCompleted, request)
+        : null;
+    const evidenceCompleted = requireRole(roles, "evidence", request.evidence_volume_handle);
+    const secretCompleted = requireRole(roles, "secrets", request.secret_bindings_handle);
+    const worldCompleted = requireRole(roles, "world", request.world_service_handle);
+    const attachmentCompleted = requireRole(roles, "attachment", request.organization_attachment_handle);
+    if (!network && (worldCompleted || attachmentCompleted))
+        return fail();
+    const evidence = evidenceCompleted
+        ? specFor("evidence_volume", evidenceCompleted, request) : null;
+    const worldBinding = worldCompleted
+        ? parseWorldServiceBinding(await options.worldStore.loadService(worldCompleted.receipt.result_handle)) : null;
+    const attachmentBinding = attachmentCompleted
+        ? parseOrganizationAttachmentBinding(await options.attachmentStore.loadAttachment(attachmentCompleted.receipt.result_handle)) : null;
+    const secretAuthority = secretCompleted
+        ? Object.freeze({
+            bindingsHandle: secretCompleted.receipt.result_handle,
+            runId: request.run_id,
+            selectedTargetHandle: request.selected_target.handle
+        }) : null;
+    if (worldBinding) {
+        matchingWorld(worldBinding, request, network, evidence, secretAuthority);
+    }
+    if (attachmentBinding)
+        matchingAttachment(attachmentBinding, request, network);
+    if (worldBinding && attachmentBinding
+        && (worldBinding.resources.data_network.handle
+            !== attachmentBinding.data_network.handle
+            || worldBinding.resources.data_network.name
+                !== attachmentBinding.data_network.name
+            || !same(worldBinding.resources.data_network.labels, attachmentBinding.data_network.labels)))
+        return fail();
+    const state = await exportState(evidence, completed, request, options);
+    if (request.cleanup_policy === "remove" && evidence && state !== "exported") {
+        return fail();
+    }
+    return Object.freeze({
+        attachment: attachmentBinding
+            ? resource(attachmentBinding.attachment_handle, attachmentBinding) : null,
+        cleanupPolicy: request.cleanup_policy,
+        dataNetwork: network
+            ? resource(network.resultHandle, Object.freeze(network)) : null,
+        evidence: evidence ? resource(evidence.resultHandle, Object.freeze(evidence)) : null,
+        exportState: state,
+        secrets: secretAuthority
+            ? resource(secretAuthority.bindingsHandle, secretAuthority) : null,
+        world: worldBinding
+            ? resource(worldBinding.world_service_handle, worldBinding) : null
+    });
+};