spawnfile 0.1.12 → 0.1.14

package/dist/target/organizationAttachment.d.ts

@@ -0,0 +1,23 @@
+import { type TargetResourceReceipt } from "./contracts.js";
+import { type TargetJournalStore } from "./journal.js";
+import { type OrganizationAttachmentResolver } from "./organizationAttachmentAuthority.js";
+import { type DockerOrganizationAttachmentExecutor } from "./organizationAttachmentProvider.js";
+import { type OrganizationAttachmentAuthorityStore } from "./organizationAttachmentStore.js";
+type OperationResult = {
+    readonly receipt: TargetResourceReceipt;
+    readonly receiptBytes: string;
+};
+export interface DockerOrganizationAttachmentOperationsOptions {
+    readonly authorityStore: OrganizationAttachmentAuthorityStore;
+    readonly context: unknown;
+    readonly executor: DockerOrganizationAttachmentExecutor;
+    readonly journal: TargetJournalStore;
+    readonly resolver: OrganizationAttachmentResolver;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: unknown;
+}
+export interface DockerOrganizationAttachmentOperations {
+    execute(raw: unknown): Promise<OperationResult>;
+}
+export declare const createDockerOrganizationAttachmentOperations: (options: DockerOrganizationAttachmentOperationsOptions) => DockerOrganizationAttachmentOperations;
+export {};

package/dist/target/organizationAttachment.js

@@ -0,0 +1,263 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseTargetResourceRequest } from "./contracts.js";
+import { createDockerResourceSpec } from "./dockerResourcesProvider.js";
+import { selectTarget } from "./dockerTarget.js";
+import { createTargetReceiptDigest } from "./handles.js";
+import { createOrganizationAttachmentAuthorization, parseOrganizationAttachmentResolution } from "./organizationAttachmentAuthority.js";
+import { ORGANIZATION_ATTACHMENT_ERROR, createDockerOrganizationAttachmentSpec } from "./organizationAttachmentProvider.js";
+import { executeOrganizationAttachmentCommand, inspectContainer, inspectNetwork, mutate } from "./organizationAttachmentLifecycle.js";
+import { createOrganizationAttachmentBinding, createOrganizationAttachmentMutationAdmission } from "./organizationAttachmentStore.js";
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => {
+    throw new SpawnfileError("runtime_error", ORGANIZATION_ATTACHMENT_ERROR);
+};
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const validOptions = (raw) => {
+    if (!raw.authorityStore
+        || typeof raw.authorityStore.bindAttachment !== "function"
+        || typeof raw.authorityStore.bindMutationAdmission !== "function"
+        || typeof raw.authorityStore.bindResolution !== "function"
+        || typeof raw.authorityStore.loadAttachment !== "function"
+        || typeof raw.authorityStore.requireMutationAdmission !== "function"
+        || typeof raw.context !== "string" || !CONTEXT_PATTERN.test(raw.context)
+        || typeof raw.executor !== "function" || !raw.journal
+        || !raw.resolver || typeof raw.resolver.resolve !== "function"
+        || raw.timeoutMs !== undefined && (typeof raw.timeoutMs !== "number"
+            || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1
+            || raw.timeoutMs > 120_000))
+        return fail();
+    return {
+        authorityStore: raw.authorityStore,
+        context: raw.context,
+        executor: raw.executor,
+        journal: raw.journal,
+        resolver: raw.resolver,
+        signal: raw.signal,
+        timeoutMs: raw.timeoutMs ?? 10_000
+    };
+};
+const parseRequest = (raw) => {
+    const request = parseTargetResourceRequest(raw);
+    if (request.operation !== "attach_organization"
+        && request.operation !== "detach_organization")
+        return fail();
+    return request;
+};
+const selectedContextMatches = async (request, options) => {
+    const selected = await selectTarget({
+        context: options.context,
+        dockerCommand: "docker",
+        execFile: async (_file, args, execution) => executeOrganizationAttachmentCommand(args, {
+            ...options,
+            signal: execution.signal,
+            timeoutMs: execution.timeout
+        }),
+        signal: options.signal,
+        timeoutMs: options.timeoutMs
+    });
+    if (!same({ fingerprint: selected.fingerprint, handle: selected.handle }, request.selected_target))
+        return fail();
+};
+const dataNetworkClaim = async (request, options) => {
+    const journal = await options.journal.read();
+    const matches = journal.entries
+        .filter((entry) => entry.operation === "create_data_network" && entry.state === "completed")
+        .filter((entry) => createDockerResourceSpec({
+        kind: "data_network",
+        operationHandle: entry.operation_handle,
+        requestDigest: entry.request_digest,
+        runId: request.run_id,
+        selectedTargetHandle: request.selected_target.handle
+    }).resultHandle === request.data_network_handle);
+    if (matches.length !== 1)
+        return fail();
+    return {
+        operationHandle: matches[0].operation_handle,
+        requestDigest: matches[0].request_digest
+    };
+};
+const resolveAttach = async (request, claim, options) => {
+    const authorization = createOrganizationAttachmentAuthorization({
+        descriptorDigest: request.descriptor_digest,
+        operationHandle: claim.operationHandle,
+        organizationHandoffHandle: request.organization_handoff_handle,
+        requestDigest: claim.requestDigest,
+        runId: request.run_id,
+        selectedTarget: request.selected_target
+    });
+    const resolution = parseOrganizationAttachmentResolution(await options.resolver.resolve({ authorization, signal: options.signal }));
+    if (!same(resolution.authorization, authorization))
+        return fail();
+    await options.authorityStore.bindResolution(resolution);
+    return resolution;
+};
+const receiptFor = (input) => {
+    const raw = {
+        cleanup_state: "not_requested",
+        descriptor_digest: input.request.descriptor_digest,
+        export_state: "not_requested",
+        labels: Object.entries(input.labels).map(([key, value]) => ({ key, value })),
+        operation: input.request.operation,
+        operation_handle: input.claim.operationHandle,
+        receipt_digest: `sha256:${"0".repeat(64)}`,
+        request_digest: input.claim.requestDigest,
+        result_handle: input.resultHandle,
+        resulting_revision: input.request.expected_revision + 1,
+        run_id: input.request.run_id,
+        selected_target: input.request.selected_target,
+        version: "spawnfile.target-resource.receipt.v1"
+    };
+    return { ...raw, receipt_digest: createTargetReceiptDigest(raw) };
+};
+class DockerOrganizationAttachmentOperationsImpl {
+    #live = new Map();
+    #options;
+    constructor(options) { this.#options = options; }
+    execute(raw) {
+        let request;
+        try {
+            request = parseRequest(raw);
+        }
+        catch {
+            return Promise.reject(new SpawnfileError("runtime_error", ORGANIZATION_ATTACHMENT_ERROR));
+        }
+        const active = this.#live.get(request.idempotency_key);
+        if (active)
+            return same(active.request, request)
+                ? active.promise
+                : Promise.reject(new SpawnfileError("runtime_error", ORGANIZATION_ATTACHMENT_ERROR));
+        const promise = this.executeOwner(request);
+        this.#live.set(request.idempotency_key, { promise, request });
+        void promise.finally(() => {
+            if (this.#live.get(request.idempotency_key)?.promise === promise) {
+                this.#live.delete(request.idempotency_key);
+            }
+        }).catch(() => undefined);
+        return promise;
+    }
+    async executeOwner(request) {
+        try {
+            const reservation = await this.#options.journal.reserve(request);
+            if (reservation.kind === "replay") {
+                return { receipt: reservation.receipt, receiptBytes: reservation.receiptBytes };
+            }
+            if (request.operation === "attach_organization") {
+                return await this.attach(request, reservation.kind, reservation.claim);
+            }
+            return await this.detach(request, reservation.kind, reservation.claim);
+        }
+        catch {
+            return fail();
+        }
+    }
+    async attach(request, reservation, claim) {
+        const networkClaim = await dataNetworkClaim(request, this.#options);
+        const resolution = await resolveAttach(request, claim, this.#options);
+        await selectedContextMatches(request, this.#options);
+        const spec = createDockerOrganizationAttachmentSpec({
+            containerId: resolution.network_attachment.container_id,
+            dataNetworkOperationHandle: networkClaim.operationHandle,
+            dataNetworkRequestDigest: networkClaim.requestDigest,
+            deploymentLabels: resolution.network_attachment.deployment_labels,
+            operationHandle: claim.operationHandle,
+            organizationHandoffHandle: request.organization_handoff_handle,
+            requestDigest: claim.requestDigest,
+            runId: request.run_id,
+            selectedTargetHandle: request.selected_target.handle
+        });
+        if (spec.network.resultHandle !== request.data_network_handle)
+            return fail();
+        const networkId = await inspectNetwork(spec, this.#options);
+        const binding = createOrganizationAttachmentBinding({
+            dataNetworkOperationHandle: networkClaim.operationHandle,
+            dataNetworkRequestDigest: networkClaim.requestDigest,
+            networkId,
+            resolution,
+            spec
+        });
+        await this.#options.authorityStore.bindAttachment(binding);
+        const admission = createOrganizationAttachmentMutationAdmission({
+            binding, operation: request.operation,
+            operationHandle: claim.operationHandle, requestDigest: claim.requestDigest
+        });
+        if (reservation === "pending")
+            await this.#options.authorityStore
+                .requireMutationAdmission(admission);
+        const before = await inspectContainer(spec, this.#options);
+        if (reservation === "owner" && before.attached)
+            return fail();
+        if (reservation === "owner")
+            await this.#options.authorityStore
+                .bindMutationAdmission(admission);
+        if (!before.attached) {
+            await mutate("connect", binding.data_network.id, spec.containerId, this.#options);
+        }
+        if (!(await inspectContainer(spec, this.#options)).attached)
+            return fail();
+        if (await inspectNetwork(spec, this.#options) !== binding.data_network.id)
+            return fail();
+        const receipt = receiptFor({
+            claim,
+            labels: binding.receipt_labels,
+            request,
+            resultHandle: binding.attachment_handle
+        });
+        return await this.#options.journal.complete(claim, receipt);
+    }
+    async detach(request, reservation, claim) {
+        const binding = await this.#options.authorityStore.loadAttachment(request.organization_attachment_handle);
+        if (binding.attachment_handle !== request.organization_attachment_handle
+            || binding.data_network.handle !== request.data_network_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))
+            return fail();
+        const networkClaim = await dataNetworkClaim(request, this.#options);
+        if (networkClaim.operationHandle !== binding.data_network.operation_handle
+            || networkClaim.requestDigest !== binding.data_network.request_digest)
+            return fail();
+        await selectedContextMatches(request, this.#options);
+        const spec = createDockerOrganizationAttachmentSpec({
+            containerId: binding.resolution.network_attachment.container_id,
+            dataNetworkOperationHandle: networkClaim.operationHandle,
+            dataNetworkRequestDigest: networkClaim.requestDigest,
+            deploymentLabels: binding.resolution.network_attachment.deployment_labels,
+            operationHandle: binding.resolution.authorization.operation_handle,
+            organizationHandoffHandle: binding.resolution.authorization.organization_handoff_handle,
+            requestDigest: binding.resolution.authorization.request_digest,
+            runId: binding.resolution.authorization.run_id,
+            selectedTargetHandle: binding.resolution.authorization.selected_target.handle
+        });
+        if (spec.resultHandle !== binding.attachment_handle
+            || await inspectNetwork(spec, this.#options) !== binding.data_network.id)
+            return fail();
+        const admission = createOrganizationAttachmentMutationAdmission({
+            binding, operation: request.operation,
+            operationHandle: claim.operationHandle, requestDigest: claim.requestDigest
+        });
+        if (reservation === "pending")
+            await this.#options.authorityStore
+                .requireMutationAdmission(admission);
+        const before = await inspectContainer(spec, this.#options);
+        if (reservation === "owner" && !before.attached)
+            return fail();
+        if (reservation === "owner")
+            await this.#options.authorityStore
+                .bindMutationAdmission(admission);
+        if (before.attached) {
+            await mutate("disconnect", binding.data_network.id, spec.containerId, this.#options);
+        }
+        if ((await inspectContainer(spec, this.#options)).attached)
+            return fail();
+        if (await inspectNetwork(spec, this.#options) !== binding.data_network.id)
+            return fail();
+        const receipt = receiptFor({
+            claim,
+            labels: binding.receipt_labels,
+            request,
+            resultHandle: null
+        });
+        return await this.#options.journal.complete(claim, receipt);
+    }
+}
+export const createDockerOrganizationAttachmentOperations = (options) => new DockerOrganizationAttachmentOperationsImpl(validOptions(options));

package/dist/target/organizationAttachmentAuthority.d.ts

@@ -0,0 +1,65 @@
+import { type OpaqueTargetHandle, type SelectedTargetReceipt } from "./contracts.js";
+import { type OrganizationDeploymentLabels } from "./organizationAttachmentProvider.js";
+export declare const ORGANIZATION_ATTACHMENT_AUTHORIZATION_VERSION: "spawnfile.target-organization-attachment.authorization.v1";
+export declare const ORGANIZATION_HANDOFF_VERSION: "spawnfile.organization-handoff.v1";
+export interface OrganizationAttachmentAuthorization {
+    readonly descriptor_digest: string;
+    readonly operation_handle: OpaqueTargetHandle;
+    readonly organization_handoff_handle: OpaqueTargetHandle;
+    readonly request_digest: string;
+    readonly run_id: string;
+    readonly selected_target: {
+        readonly fingerprint: string;
+        readonly handle: OpaqueTargetHandle;
+    };
+    readonly version: typeof ORGANIZATION_ATTACHMENT_AUTHORIZATION_VERSION;
+}
+export interface ResolvedOrganizationHandoff {
+    readonly binding_digest: string;
+    readonly deployment_handle: string;
+    readonly lifecycle_receipts: {
+        readonly down: "spawnfile.down-receipt.v1";
+        readonly export: "spawnfile.export-index.v1";
+        readonly up: "spawnfile.up-receipt.v1";
+    };
+    readonly network_attachment_handle: OpaqueTargetHandle;
+    readonly run_id: string;
+    readonly selected_target_receipt_digest: string;
+    readonly version: typeof ORGANIZATION_HANDOFF_VERSION;
+}
+export interface OrganizationAttachmentResolution {
+    readonly authorization: OrganizationAttachmentAuthorization;
+    readonly descriptor_binding: {
+        readonly binding_digest: string;
+        readonly descriptor_digest: string;
+    };
+    readonly handoff: ResolvedOrganizationHandoff;
+    readonly network_attachment: {
+        readonly container_id: string;
+        readonly deployment_labels: OrganizationDeploymentLabels;
+        readonly network_attachment_handle: OpaqueTargetHandle;
+    };
+    readonly selected_target_binding: {
+        readonly receipt: SelectedTargetReceipt;
+        readonly receipt_digest: string;
+    };
+}
+export interface OrganizationAttachmentResolverInput {
+    readonly authorization: OrganizationAttachmentAuthorization;
+    readonly signal?: AbortSignal;
+}
+/** Trusted operator seam from one opaque handoff capability to exact private identity. */
+export interface OrganizationAttachmentResolver {
+    resolve(input: OrganizationAttachmentResolverInput): Promise<unknown>;
+}
+export declare const createOrganizationAttachmentAuthorization: (input: {
+    readonly descriptorDigest: unknown;
+    readonly operationHandle: unknown;
+    readonly organizationHandoffHandle: unknown;
+    readonly requestDigest: unknown;
+    readonly runId: unknown;
+    readonly selectedTarget: unknown;
+}) => OrganizationAttachmentAuthorization;
+export declare const parseOrganizationAttachmentAuthorization: (raw: unknown) => OrganizationAttachmentAuthorization;
+export declare const parseResolvedOrganizationHandoff: (raw: unknown) => ResolvedOrganizationHandoff;
+export declare const parseOrganizationAttachmentResolution: (raw: unknown) => OrganizationAttachmentResolution;

package/dist/target/organizationAttachmentAuthority.js

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle, parseRunId, parseSelectedTargetReceipt } from "./contracts.js";
+import { ORGANIZATION_ATTACHMENT_ERROR, parseOrganizationContainerId, parseOrganizationDeploymentLabels } from "./organizationAttachmentProvider.js";
+export const ORGANIZATION_ATTACHMENT_AUTHORIZATION_VERSION = "spawnfile.target-organization-attachment.authorization.v1";
+export const ORGANIZATION_HANDOFF_VERSION = "spawnfile.organization-handoff.v1";
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{32}$/u;
+const DEPLOYMENT_HANDLE_PATTERN = /^sf-oh1-[a-f0-9]{64}$/u;
+const fail = () => { throw new Error(ORGANIZATION_ATTACHMENT_ERROR); };
+const ordinary = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+    }
+    catch {
+        return fail();
+    }
+};
+const exactRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+const exactKeys = (value, expected) => {
+    const actual = Object.keys(value).sort();
+    const sorted = [...expected].sort();
+    return actual.length === sorted.length
+        && actual.every((key, index) => key === sorted[index]);
+};
+const digest = (value) => {
+    if (typeof value !== "string" || !DIGEST_PATTERN.test(value))
+        return fail();
+    return value;
+};
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+export const createOrganizationAttachmentAuthorization = (input) => {
+    const selected = parseSelectedTargetReceipt({
+        ...(exactRecord(input.selectedTarget) ? input.selectedTarget : {}),
+        version: "spawnfile.target-resource.selected-target.v1"
+    });
+    return Object.freeze({
+        descriptor_digest: digest(input.descriptorDigest),
+        operation_handle: parseOpaqueTargetHandle(input.operationHandle),
+        organization_handoff_handle: parseOpaqueTargetHandle(input.organizationHandoffHandle),
+        request_digest: digest(input.requestDigest),
+        run_id: parseRunId(input.runId),
+        selected_target: Object.freeze({ fingerprint: selected.fingerprint, handle: selected.handle }),
+        version: ORGANIZATION_ATTACHMENT_AUTHORIZATION_VERSION
+    });
+};
+export const parseOrganizationAttachmentAuthorization = (raw) => {
+    ordinary(raw);
+    if (!exactRecord(raw) || !exactKeys(raw, [
+        "descriptor_digest", "operation_handle", "organization_handoff_handle",
+        "request_digest", "run_id", "selected_target", "version"
+    ]) || raw.version !== ORGANIZATION_ATTACHMENT_AUTHORIZATION_VERSION
+        || !exactRecord(raw.selected_target)
+        || !exactKeys(raw.selected_target, ["fingerprint", "handle"])
+        || typeof raw.selected_target.fingerprint !== "string"
+        || !FINGERPRINT_PATTERN.test(raw.selected_target.fingerprint))
+        return fail();
+    return createOrganizationAttachmentAuthorization({
+        descriptorDigest: raw.descriptor_digest,
+        operationHandle: raw.operation_handle,
+        organizationHandoffHandle: raw.organization_handoff_handle,
+        requestDigest: raw.request_digest,
+        runId: raw.run_id,
+        selectedTarget: raw.selected_target
+    });
+};
+const handoffHandle = (input) => {
+    const canonical = [
+        "spawnfile.organization-handoff.v1\0",
+        input.run_id,
+        input.selected_target_receipt_digest,
+        input.network_attachment_handle,
+        input.binding_digest,
+        input.lifecycle_receipts.up,
+        input.lifecycle_receipts.export,
+        input.lifecycle_receipts.down
+    ].join("\n");
+    return `sf-oh1-${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+};
+export const parseResolvedOrganizationHandoff = (raw) => {
+    ordinary(raw);
+    if (!exactRecord(raw) || !exactKeys(raw, [
+        "binding_digest", "deployment_handle", "lifecycle_receipts",
+        "network_attachment_handle", "run_id", "selected_target_receipt_digest", "version"
+    ]) || raw.version !== ORGANIZATION_HANDOFF_VERSION
+        || typeof raw.deployment_handle !== "string"
+        || !DEPLOYMENT_HANDLE_PATTERN.test(raw.deployment_handle)
+        || !exactRecord(raw.lifecycle_receipts)
+        || !exactKeys(raw.lifecycle_receipts, ["down", "export", "up"])
+        || raw.lifecycle_receipts.down !== "spawnfile.down-receipt.v1"
+        || raw.lifecycle_receipts.export !== "spawnfile.export-index.v1"
+        || raw.lifecycle_receipts.up !== "spawnfile.up-receipt.v1")
+        return fail();
+    const body = {
+        binding_digest: digest(raw.binding_digest),
+        lifecycle_receipts: Object.freeze({
+            down: "spawnfile.down-receipt.v1",
+            export: "spawnfile.export-index.v1",
+            up: "spawnfile.up-receipt.v1"
+        }),
+        network_attachment_handle: parseOpaqueTargetHandle(raw.network_attachment_handle),
+        run_id: parseRunId(raw.run_id),
+        selected_target_receipt_digest: digest(raw.selected_target_receipt_digest)
+    };
+    if (raw.deployment_handle !== handoffHandle(body))
+        return fail();
+    return Object.freeze({
+        ...body,
+        deployment_handle: raw.deployment_handle,
+        version: ORGANIZATION_HANDOFF_VERSION
+    });
+};
+export const parseOrganizationAttachmentResolution = (raw) => {
+    ordinary(raw);
+    if (!exactRecord(raw) || !exactKeys(raw, [
+        "authorization", "descriptor_binding", "handoff",
+        "network_attachment", "selected_target_binding"
+    ]) || !exactRecord(raw.descriptor_binding)
+        || !exactKeys(raw.descriptor_binding, ["binding_digest", "descriptor_digest"])
+        || !exactRecord(raw.network_attachment)
+        || !exactKeys(raw.network_attachment, [
+            "container_id", "deployment_labels", "network_attachment_handle"
+        ]) || !exactRecord(raw.selected_target_binding)
+        || !exactKeys(raw.selected_target_binding, ["receipt", "receipt_digest"]))
+        return fail();
+    const authorization = parseOrganizationAttachmentAuthorization(raw.authorization);
+    const handoff = parseResolvedOrganizationHandoff(raw.handoff);
+    const receipt = parseSelectedTargetReceipt(raw.selected_target_binding.receipt);
+    const resolution = Object.freeze({
+        authorization,
+        descriptor_binding: Object.freeze({
+            binding_digest: digest(raw.descriptor_binding.binding_digest),
+            descriptor_digest: digest(raw.descriptor_binding.descriptor_digest)
+        }),
+        handoff,
+        network_attachment: Object.freeze({
+            container_id: parseOrganizationContainerId(raw.network_attachment.container_id),
+            deployment_labels: parseOrganizationDeploymentLabels(raw.network_attachment.deployment_labels),
+            network_attachment_handle: parseOpaqueTargetHandle(raw.network_attachment.network_attachment_handle)
+        }),
+        selected_target_binding: Object.freeze({
+            receipt,
+            receipt_digest: digest(raw.selected_target_binding.receipt_digest)
+        })
+    });
+    if (resolution.descriptor_binding.descriptor_digest !== authorization.descriptor_digest
+        || resolution.descriptor_binding.binding_digest !== handoff.binding_digest
+        || handoff.run_id !== authorization.run_id
+        || resolution.network_attachment.network_attachment_handle
+            !== handoff.network_attachment_handle
+        || resolution.network_attachment.deployment_labels["com.spawnfile.run_id"]
+            !== authorization.run_id
+        || resolution.selected_target_binding.receipt_digest
+            !== handoff.selected_target_receipt_digest
+        || !same({
+            fingerprint: resolution.selected_target_binding.receipt.fingerprint,
+            handle: resolution.selected_target_binding.receipt.handle
+        }, authorization.selected_target))
+        return fail();
+    return resolution;
+};

package/dist/target/organizationAttachmentLifecycle.d.ts

@@ -0,0 +1,17 @@
+import { type DockerOrganizationAttachmentExecutor, type DockerOrganizationAttachmentSpec } from "./organizationAttachmentProvider.js";
+export interface OrganizationAttachmentLifecycleOptions {
+    readonly context: string;
+    readonly executor: DockerOrganizationAttachmentExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}
+export declare const executeOrganizationAttachmentCommand: (args: string[], options: OrganizationAttachmentLifecycleOptions) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export declare const inspectNetwork: (spec: DockerOrganizationAttachmentSpec, options: OrganizationAttachmentLifecycleOptions) => Promise<string>;
+export declare const inspectContainer: (spec: DockerOrganizationAttachmentSpec, options: OrganizationAttachmentLifecycleOptions) => Promise<{
+    readonly attached: boolean;
+}>;
+export declare const mutate: (operation: "connect" | "disconnect", networkId: string, containerId: string, options: OrganizationAttachmentLifecycleOptions) => Promise<void>;
+export declare const detachExactOrganizationAttachment: (rawBinding: unknown, options: OrganizationAttachmentLifecycleOptions) => Promise<void>;

package/dist/target/organizationAttachmentLifecycle.js

@@ -0,0 +1,101 @@
+import { SpawnfileError } from "../shared/index.js";
+import { ORGANIZATION_ATTACHMENT_ERROR, ORGANIZATION_NETWORK_INSPECTION_FORMAT, DockerOrganizationAttachmentProviderError, createDockerOrganizationAttachmentSpec, executeDockerOrganizationAttachment, parseExpectedOrganizationContainer, parseExpectedOrganizationNetwork } from "./organizationAttachmentProvider.js";
+import { parseOrganizationAttachmentBinding } from "./organizationAttachmentStore.js";
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => {
+    throw new SpawnfileError("runtime_error", ORGANIZATION_ATTACHMENT_ERROR);
+};
+const validOptions = (raw) => {
+    if (!raw || typeof raw.context !== "string" || !CONTEXT_PATTERN.test(raw.context)
+        || typeof raw.executor !== "function" || typeof raw.timeoutMs !== "number"
+        || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1
+        || raw.timeoutMs > 120_000)
+        return fail();
+    return raw;
+};
+export const executeOrganizationAttachmentCommand = async (args, options) => executeDockerOrganizationAttachment({
+    args,
+    executor: options.executor,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs
+});
+export const inspectNetwork = async (spec, options) => {
+    const result = await executeOrganizationAttachmentCommand([
+        "--context", options.context, "network", "inspect", "--format",
+        ORGANIZATION_NETWORK_INSPECTION_FORMAT, spec.network.name
+    ], options);
+    const id = parseExpectedOrganizationNetwork(result.stdout, spec);
+    if (result.stderr !== "" || id === null)
+        return fail();
+    return id;
+};
+export const inspectContainer = async (spec, options) => {
+    const result = await executeOrganizationAttachmentCommand([
+        "--context", options.context, "container", "inspect", "--format",
+        spec.containerInspectionFormat, spec.containerId
+    ], options);
+    const inspection = parseExpectedOrganizationContainer(result.stdout, spec);
+    if (result.stderr !== "" || inspection === null)
+        return fail();
+    return inspection;
+};
+const networkMutation = (operation, networkId, containerId, options) => executeOrganizationAttachmentCommand([
+    "--context", options.context, "network", operation, networkId, containerId
+], options);
+export const mutate = async (operation, networkId, containerId, options) => {
+    const result = await networkMutation(operation, networkId, containerId, options);
+    if (result.stdout !== "" || result.stderr !== "")
+        return fail();
+};
+const specFor = (binding) => createDockerOrganizationAttachmentSpec({
+    containerId: binding.resolution.network_attachment.container_id,
+    dataNetworkOperationHandle: binding.data_network.operation_handle,
+    dataNetworkRequestDigest: binding.data_network.request_digest,
+    deploymentLabels: binding.resolution.network_attachment.deployment_labels,
+    operationHandle: binding.resolution.authorization.operation_handle,
+    organizationHandoffHandle: binding.resolution.authorization.organization_handoff_handle,
+    requestDigest: binding.resolution.authorization.request_digest,
+    runId: binding.resolution.authorization.run_id,
+    selectedTargetHandle: binding.resolution.authorization.selected_target.handle
+});
+const inspectContainerOrAbsent = async (spec, options) => {
+    try {
+        return await inspectContainer(spec, options);
+    }
+    catch (error) {
+        if (error instanceof DockerOrganizationAttachmentProviderError
+            && error.kind === "not_found")
+            return null;
+        throw error;
+    }
+};
+const proveNetwork = async (binding, spec, options) => {
+    if (await inspectNetwork(spec, options) !== binding.data_network.id)
+        return fail();
+};
+export const detachExactOrganizationAttachment = async (rawBinding, options) => {
+    // Parse the complete immutable authority record before any provider call.
+    const binding = parseOrganizationAttachmentBinding(rawBinding);
+    const checkedOptions = validOptions(options);
+    const spec = specFor(binding);
+    if (spec.resultHandle !== binding.attachment_handle)
+        return fail();
+    await proveNetwork(binding, spec, checkedOptions);
+    const before = await inspectContainerOrAbsent(spec, checkedOptions);
+    if (before === null || !before.attached)
+        return;
+    let mutationResult;
+    try {
+        mutationResult = await networkMutation("disconnect", binding.data_network.id, spec.containerId, checkedOptions);
+    }
+    catch {
+        // A thrown mutation is ambiguous. Reconciliation below is the only retry-like action.
+    }
+    if (mutationResult
+        && (mutationResult.stdout !== "" || mutationResult.stderr !== ""))
+        return fail();
+    const after = await inspectContainerOrAbsent(spec, checkedOptions);
+    if (after?.attached === true)
+        return fail();
+    await proveNetwork(binding, spec, checkedOptions);
+};