spawnfile 0.1.13 → 0.1.17

package/dist/deployment/organizationHandoffAuthorityStore.js

@@ -0,0 +1,355 @@
+import { Buffer } from "node:buffer";
+import { constants } from "node:fs";
+import { lstat, mkdir, open } from "node:fs/promises";
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { parseOpaqueTargetHandle } from "../target/index.js";
+import { ORGANIZATION_HANDOFF_AUTHORITY_ERROR, createOrganizationHandoffCapabilityPending, createOrganizationHandoffDockerObservation, createOrganizationHandoffHandle, createOrganizationHandoffRecoveryKey, parseOrganizationAttachmentAuthorizationForDeployment, parseOrganizationHandoffCapability, parseOrganizationHandoffDockerObservation } from "./organizationHandoffAuthorityTypes.js";
+import { parseOrganizationHandoff } from "./organizationHandoffTypes.js";
+import { initializeOrganizationHandoffAuthorityFsClient } from "./organizationHandoffAuthorityFsClient.js";
+const owner = typeof process.getuid === "function" ? process.getuid() : undefined;
+/**
+ * The store's public message stays uniform: it reaches CLI output and must not
+ * describe private resolution state. Diagnostics from the helper are preserved
+ * on `cause` so an operator log still shows which budget or invariant failed.
+ */
+const fail = (cause) => {
+    throw new Error(ORGANIZATION_HANDOFF_AUTHORITY_ERROR, ...(cause === undefined ? [] : [{ cause }]));
+};
+const key = (value) => Buffer.from(value, "utf8").toString("hex");
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const pendingKey = (value) => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value) ? value : fail();
+const recoveryName = (value) => `${key(createOrganizationHandoffRecoveryKey(value))}.json`;
+const closeRequest = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)
+        || Object.getPrototypeOf(value) !== Object.prototype
+        || Object.keys(value).length !== 2
+        || !Object.hasOwn(value, "expectedHandoff")
+        || !Object.hasOwn(value, "organizationHandoffHandle"))
+        return fail();
+    const input = value;
+    try {
+        return Object.freeze({
+            expectedHandoff: parseOrganizationHandoff(input.expectedHandoff),
+            organizationHandoffHandle: parseOpaqueTargetHandle(input.organizationHandoffHandle)
+        });
+    }
+    catch (error) {
+        return fail(error);
+    }
+};
+export const resolveOrganizationHandoffAuthorityRoot = () => path.join(resolveSpawnfileHome(), "deployments", "organization-handoff-authority");
+const checkDirectory = async (directory) => {
+    const home = resolveSpawnfileHome();
+    const root = path.resolve(directory);
+    if (root !== home && !root.startsWith(`${home}${path.sep}`))
+        return fail();
+    await mkdir(home, { mode: 0o700, recursive: true }).catch(fail);
+    const homeStat = await lstat(home).catch(fail);
+    if (!homeStat.isDirectory() || homeStat.isSymbolicLink() || (homeStat.mode & 0o077) !== 0
+        || owner !== undefined && homeStat.uid !== owner)
+        return fail();
+    let current = home;
+    for (const part of path.relative(home, root).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        let stat;
+        try {
+            stat = await lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return fail();
+            await mkdir(current, { mode: 0o700 }).catch((mkdirError) => {
+                if (mkdirError.code !== "EEXIST")
+                    fail();
+            });
+            stat = await lstat(current).catch(fail);
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0
+            || owner !== undefined && stat.uid !== owner)
+            return fail();
+    }
+};
+const parse = (content) => {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        return fail();
+    }
+    const parsed = parseOrganizationHandoffCapability(value);
+    if (JSON.stringify(parsed) !== content)
+        return fail();
+    return parsed;
+};
+const parseObservation = (content) => {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        return fail();
+    }
+    const parsed = parseOrganizationHandoffDockerObservation(value);
+    if (JSON.stringify(parsed) !== content)
+        return fail();
+    return parsed;
+};
+class Store {
+    #anchors;
+    #clients;
+    #disposed = false;
+    #hooks;
+    #root;
+    resolver;
+    constructor(root, anchors, clients, hooks) {
+        this.#root = root;
+        this.#anchors = anchors;
+        this.#clients = clients;
+        this.#hooks = hooks;
+        this.resolver = Object.freeze({ resolve: async (input) => this.resolve(input) });
+    }
+    async validateDirectories() {
+        if (this.#disposed)
+            return fail();
+        await Promise.all([...this.#anchors.entries()].map(async ([part, anchor]) => {
+            await checkDirectory(path.join(this.#root, part));
+            const pathStat = await lstat(path.join(this.#root, part)).catch(fail);
+            const fdStat = await anchor.handle.stat().catch(fail);
+            if (pathStat.dev !== anchor.dev || pathStat.ino !== anchor.ino || fdStat.dev !== anchor.dev || fdStat.ino !== anchor.ino)
+                fail();
+        }));
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        await Promise.all([...this.#clients.values()].map(async (client) => client.dispose()));
+        await Promise.all([...this.#anchors.values()].map(async ({ handle }) => { await handle.close().catch(() => undefined); }));
+    }
+    client(part) { return this.#clients.get(part) ?? fail(); }
+    async hook(kind) { await this.#hooks?.beforeLeafOperation?.(kind); }
+    async reserve(input) {
+        await this.validateDirectories();
+        const pending = createOrganizationHandoffCapabilityPending(input);
+        const publish = async () => this.client("pending").write(`${key(pending.pending_key)}.json`, JSON.stringify(pending));
+        if (this.#hooks?.duringLeafOperation)
+            await this.#hooks.duringLeafOperation("reserve", publish);
+        else {
+            await this.hook("reserve");
+            await this.validateDirectories();
+            await publish();
+        }
+        await this.validateDirectories();
+        return pending;
+    }
+    /**
+     * Elects the one Docker mutator before Docker is invoked. Once the durable
+     * reservation exists, an absent observed-id checkpoint is intentionally
+     * incomplete: automatic retry could create an unprovable second container.
+     */
+    async begin(input) {
+        const pending = await this.reserve(input);
+        await this.validateDirectories();
+        await this.hook("reserve");
+        await this.validateDirectories();
+        const name = recoveryName(pending.pending_key);
+        const serialized = JSON.stringify(pending);
+        const existing = await this.client("recovery-reserved").read(name);
+        if (existing !== null) {
+            const prior = parse(existing);
+            if (prior.state !== "pending" || !same(prior, pending))
+                return fail();
+            await this.validateDirectories();
+            return Object.freeze({ created: false, pending });
+        }
+        const created = await this.client("recovery-reserved").create(name, serialized);
+        if (!created) {
+            const prior = await this.client("recovery-reserved").read(name);
+            if (prior === null || !same(parse(prior), pending))
+                return fail();
+        }
+        await this.validateDirectories();
+        return Object.freeze({ created, pending });
+    }
+    async observeDockerMutation(pendingKeyRaw, container) {
+        await this.validateDirectories();
+        await this.hook("finalize");
+        await this.validateDirectories();
+        const value = pendingKey(pendingKeyRaw);
+        const reservation = await this.client("recovery-reserved").read(recoveryName(value));
+        if (reservation === null)
+            return fail();
+        const pending = parse(reservation);
+        if (pending.state !== "pending" || pending.pending_key !== value)
+            return fail();
+        const observation = createOrganizationHandoffDockerObservation({ containerId: container?.containerId,
+            deploymentLabels: container?.deploymentLabels, imageId: container?.imageId, pendingKey: value });
+        if (!same(observation.deployment_labels, pending.deployment_labels))
+            return fail();
+        const name = recoveryName(value);
+        const serialized = JSON.stringify(observation);
+        const existing = await this.client("recovery-docker-observed").read(name);
+        if (existing !== null) {
+            if (!same(parseObservation(existing), observation))
+                return fail();
+            await this.validateDirectories();
+            return observation;
+        }
+        const created = await this.client("recovery-docker-observed").create(name, serialized);
+        if (!created) {
+            const prior = await this.client("recovery-docker-observed").read(name);
+            if (prior === null || !same(parseObservation(prior), observation))
+                return fail();
+        }
+        await this.validateDirectories();
+        return observation;
+    }
+    async readDockerMutation(pendingKeyRaw) {
+        await this.validateDirectories();
+        await this.hook("finalize");
+        await this.validateDirectories();
+        const value = pendingKey(pendingKeyRaw);
+        const reservation = await this.client("recovery-reserved").read(recoveryName(value));
+        if (reservation === null)
+            return null;
+        const pending = parse(reservation);
+        if (pending.state !== "pending" || pending.pending_key !== value)
+            return fail();
+        const raw = await this.client("recovery-docker-observed").read(recoveryName(value));
+        if (raw === null)
+            return null;
+        const observation = parseObservation(raw);
+        if (observation.pending_key !== value || !same(observation.deployment_labels, pending.deployment_labels))
+            return fail();
+        await this.validateDirectories();
+        return observation;
+    }
+    async finalize(pendingKey, container) {
+        await this.validateDirectories();
+        await this.hook("finalize");
+        await this.validateDirectories();
+        if (typeof pendingKey !== "string" || !/^[a-f0-9]{64}$/u.test(pendingKey) || !container)
+            return fail();
+        const source = await this.client("pending").read(`${key(pendingKey)}.json`);
+        if (source === null)
+            return fail();
+        const pending = parse(source);
+        if (pending.state !== "pending" || pending.pending_key !== pendingKey || !same(pending.deployment_labels, container.deploymentLabels))
+            return fail();
+        // S3's begin path has a durable reservation leaf. Once that leaf exists,
+        // finalization is allowed only from the direct inspected-id checkpoint.
+        // Legacy low-level reserve/finalize callers retain their S1 behavior.
+        const reserved = await this.client("recovery-reserved").read(recoveryName(pendingKey));
+        if (reserved !== null) {
+            if (!same(parse(reserved), pending))
+                return fail();
+            const observed = await this.client("recovery-docker-observed").read(recoveryName(pendingKey));
+            if (observed === null)
+                return fail();
+            const observation = parseObservation(observed);
+            if (observation.container_id !== container.containerId || !same(observation.deployment_labels, container.deploymentLabels))
+                return fail();
+        }
+        const parsed = parseOrganizationHandoffCapability({ ...pending, container_id: container.containerId,
+            organization_handoff_handle: createOrganizationHandoffHandle(pending, container.containerId), state: "finalized" });
+        if (parsed.state !== "finalized")
+            return fail();
+        const finalized = parsed;
+        const existing = await this.client("finalized-pending").read(`${key(pending.pending_key)}.json`);
+        if (existing !== null) {
+            const prior = parse(existing);
+            if (prior.state !== "finalized" || !same(prior, finalized))
+                return fail();
+            await this.validateDirectories();
+            return finalized;
+        }
+        const bytes = JSON.stringify(finalized);
+        await this.client("finalized").write(`${key(finalized.organization_handoff_handle)}.json`, bytes);
+        await this.client("finalized-pending").write(`${key(pending.pending_key)}.json`, bytes);
+        await this.validateDirectories();
+        return finalized;
+    }
+    async close(input) {
+        await this.validateDirectories();
+        await this.hook("close");
+        await this.validateDirectories();
+        const request = closeRequest(input);
+        const content = await this.client("finalized").read(`${key(request.organizationHandoffHandle)}.json`);
+        if (content === null)
+            return fail();
+        const final = parse(content);
+        if (final.state !== "finalized"
+            || final.organization_handoff_handle !== request.organizationHandoffHandle
+            || !same(final.handoff, request.expectedHandoff))
+            return fail();
+        const closed = parseOrganizationHandoffCapability({ ...final, state: "attach_closed" });
+        await this.client("attach-closed").write(`${key(request.organizationHandoffHandle)}.json`, JSON.stringify(closed));
+        await this.validateDirectories();
+    }
+    async resolve(input) {
+        try {
+            if (input?.signal?.aborted)
+                return fail();
+            const auth = parseOrganizationAttachmentAuthorizationForDeployment(input?.authorization);
+            await this.validateDirectories();
+            await this.hook("resolve");
+            await this.validateDirectories();
+            if (await this.client("attach-closed").read(`${key(auth.organization_handoff_handle)}.json`) !== null)
+                return fail();
+            const content = await this.client("finalized").read(`${key(auth.organization_handoff_handle)}.json`);
+            if (content === null)
+                return fail();
+            const final = parse(content);
+            const pendingFinal = await this.client("finalized-pending").read(`${key(final.pending_key)}.json`);
+            if (pendingFinal === null || !same(parse(pendingFinal), final) || final.state !== "finalized" || final.organization_handoff_handle !== auth.organization_handoff_handle
+                || final.descriptor_digest !== auth.descriptor_digest || final.handoff.run_id !== auth.run_id
+                || auth.operation_handle === final.handoff.network_attachment_handle
+                || final.selected_target.handle !== auth.selected_target.handle || final.selected_target.fingerprint !== auth.selected_target.fingerprint)
+                return fail();
+            if (input.signal?.aborted)
+                return fail();
+            await this.validateDirectories();
+            return Object.freeze({ authorization: auth, descriptor_binding: Object.freeze({ binding_digest: final.binding_digest, descriptor_digest: final.descriptor_digest }),
+                handoff: final.handoff, network_attachment: Object.freeze({ container_id: final.container_id, deployment_labels: final.deployment_labels,
+                    network_attachment_handle: final.handoff.network_attachment_handle }), selected_target_binding: Object.freeze({ receipt: final.selected_target,
+                    receipt_digest: final.selected_target_receipt_digest }) });
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+}
+export const initializeOrganizationHandoffAuthorityStore = async (options = {}) => {
+    const root = resolveOrganizationHandoffAuthorityRoot();
+    const parts = ["pending", "finalized", "finalized-pending", "attach-closed", "recovery-reserved", "recovery-docker-observed"];
+    await Promise.all(parts.map(async (part) => checkDirectory(path.join(root, part))));
+    const anchors = new Map();
+    const clients = new Map();
+    try {
+        for (const part of parts) {
+            const handle = await open(path.join(root, part), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW).catch(fail);
+            // Register ownership before any operation that could throw, so the
+            // common rollback below closes even a validation-failing descriptor.
+            anchors.set(part, { handle, ino: 0, dev: 0 });
+            const stat = await handle.stat().catch(fail);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || owner !== undefined && stat.uid !== owner)
+                return fail();
+            anchors.set(part, { handle, ino: stat.ino, dev: stat.dev });
+        }
+        const initializeClient = options.testInitializeFsClient ?? initializeOrganizationHandoffAuthorityFsClient;
+        for (const [part, anchor] of anchors) {
+            const client = await initializeClient({ cwd: path.join(root, part), dev: anchor.dev, ino: anchor.ino,
+                ...(owner === undefined ? {} : { uid: owner }), ...(options.workerPath === undefined ? {} : { workerPath: options.workerPath }) });
+            // Transfer each completed helper into rollback ownership immediately.
+            clients.set(part, client);
+        }
+    }
+    catch (error) {
+        await Promise.all([...clients.values()].map(async (client) => client.dispose()));
+        await Promise.all([...anchors.values()].map(async ({ handle }) => { await handle.close().catch(() => undefined); }));
+        return fail(error);
+    }
+    return new Store(root, anchors, clients, options.testHooks);
+};

package/dist/deployment/organizationHandoffAuthorityTypes.d.ts

@@ -0,0 +1,76 @@
+import { type OpaqueTargetHandle, type SelectedTargetReceipt } from "../target/index.js";
+import { ORGANIZATION_HANDOFF_AUTHORITY_ERROR } from "./organizationHandoffAuthorityFsBudget.js";
+import { type OrganizationHandoff } from "./organizationHandoffTypes.js";
+export declare const ORGANIZATION_HANDOFF_CAPABILITY_VERSION: "spawnfile.organization-handoff-capability.private.v1";
+export declare const ORGANIZATION_HANDOFF_RECOVERY_VERSION: "spawnfile.organization-handoff-recovery.private.v1";
+export { ORGANIZATION_HANDOFF_AUTHORITY_ERROR };
+declare const labels: ("com.spawnfile.compile_fingerprint" | "com.spawnfile.project" | "com.spawnfile.deployment" | "com.spawnfile.run_id" | "com.spawnfile.unit" | "com.spawnfile.version")[];
+export type OrganizationHandoffCapabilityState = "pending" | "finalized" | "attach_closed";
+export type OrganizationHandoffDeploymentLabels = Readonly<Record<(typeof labels)[number], string>>;
+export interface OrganizationHandoffCapabilityPending {
+    readonly binding_digest: string;
+    readonly container_name: string;
+    readonly deployment_labels: OrganizationHandoffDeploymentLabels;
+    readonly descriptor_digest: string;
+    readonly handoff: OrganizationHandoff;
+    readonly pending_key: string;
+    readonly selected_target: SelectedTargetReceipt;
+    readonly selected_target_receipt_digest: string;
+    readonly state: "pending";
+    readonly version: typeof ORGANIZATION_HANDOFF_CAPABILITY_VERSION;
+}
+export interface OrganizationHandoffCapabilityFinalized extends Omit<OrganizationHandoffCapabilityPending, "state"> {
+    readonly container_id: string;
+    readonly organization_handoff_handle: OpaqueTargetHandle;
+    readonly state: "finalized";
+}
+export interface OrganizationHandoffCapabilityClosed extends Omit<OrganizationHandoffCapabilityFinalized, "state"> {
+    readonly state: "attach_closed";
+}
+export type OrganizationHandoffCapability = OrganizationHandoffCapabilityPending | OrganizationHandoffCapabilityFinalized | OrganizationHandoffCapabilityClosed;
+/**
+ * A direct, host-local checkpoint made only after Docker returned the exact
+ * container id and its inspected deployment labels.  It deliberately does not
+ * represent a new capability state: capability authority remains
+ * pending -> finalized -> attach_closed.
+ */
+export interface OrganizationHandoffDockerObservation {
+    readonly container_id: string;
+    readonly deployment_labels: OrganizationHandoffDeploymentLabels;
+    readonly image_id: string;
+    readonly pending_key: string;
+    readonly version: typeof ORGANIZATION_HANDOFF_RECOVERY_VERSION;
+}
+export declare const createOrganizationHandoffPendingKey: (input: Omit<OrganizationHandoffCapabilityPending, "pending_key" | "state" | "version">) => string;
+/** A domain-separated storage key; never use a raw capability pending key as a leaf name. */
+export declare const createOrganizationHandoffRecoveryKey: (value: unknown) => string;
+export declare const createOrganizationHandoffDockerObservation: (input: {
+    readonly containerId: unknown;
+    readonly deploymentLabels: unknown;
+    readonly imageId: unknown;
+    readonly pendingKey: unknown;
+}) => OrganizationHandoffDockerObservation;
+export declare const parseOrganizationHandoffDockerObservation: (raw: unknown) => OrganizationHandoffDockerObservation;
+export declare const createOrganizationHandoffHandle: (pending: OrganizationHandoffCapabilityPending, containerId: unknown) => OpaqueTargetHandle;
+export declare const createOrganizationHandoffCapabilityPending: (input: {
+    readonly bindingDigest: unknown;
+    readonly containerName: unknown;
+    readonly deploymentLabels: unknown;
+    readonly descriptorDigest: unknown;
+    readonly handoff: unknown;
+    readonly selectedTarget: unknown;
+    readonly selectedTargetReceiptDigest: unknown;
+}) => OrganizationHandoffCapabilityPending;
+export declare const parseOrganizationHandoffCapability: (raw: unknown) => OrganizationHandoffCapability;
+export declare const parseOrganizationAttachmentAuthorizationForDeployment: (raw: unknown) => {
+    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: "spawnfile.target-organization-attachment.authorization.v1";
+};

package/dist/deployment/organizationHandoffAuthorityTypes.js

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { assertOrdinaryJsonGraph, createCanonicalSelectedTargetReceiptBytes, parseOpaqueTargetHandle, parseRunId, parseSelectedTargetReceipt } from "../target/index.js";
+import { dockerDeploymentLabelKeys } from "./dockerLabels.js";
+import { ORGANIZATION_HANDOFF_AUTHORITY_ERROR } from "./organizationHandoffAuthorityFsBudget.js";
+import { parseOrganizationHandoff } from "./organizationHandoffTypes.js";
+export const ORGANIZATION_HANDOFF_CAPABILITY_VERSION = "spawnfile.organization-handoff-capability.private.v1";
+export const ORGANIZATION_HANDOFF_RECOVERY_VERSION = "spawnfile.organization-handoff-recovery.private.v1";
+export { ORGANIZATION_HANDOFF_AUTHORITY_ERROR };
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const CONTAINER = /^[a-f0-9]{64}$/u;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u;
+const labels = Object.values(dockerDeploymentLabelKeys).sort();
+const fail = () => { throw new Error(ORGANIZATION_HANDOFF_AUTHORITY_ERROR); };
+const exact = (value, keys) => value !== null && typeof value === "object" && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype
+    && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+const digest = (value) => typeof value === "string" && DIGEST.test(value) ? value : fail();
+const canonicalSelectedDigest = (selected) => `sha256:${createHash("sha256").update(createCanonicalSelectedTargetReceiptBytes(selected), "utf8").digest("hex")}`;
+const exactLabels = (value) => {
+    if (!exact(value, labels))
+        return fail();
+    for (const key of labels)
+        if (typeof value[key] !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u.test(value[key]))
+            fail();
+    return Object.freeze(Object.fromEntries(labels.map((key) => [key, value[key]])));
+};
+const key = (domain, value) => createHash("sha256")
+    .update(`spawnfile.organization-handoff-authority.${domain}.v1\0`, "utf8").update(value, "utf8").digest("hex");
+const pendingKey = (value) => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value) ? value : fail();
+export const createOrganizationHandoffPendingKey = (input) => key("reservation", JSON.stringify(input));
+/** A domain-separated storage key; never use a raw capability pending key as a leaf name. */
+export const createOrganizationHandoffRecoveryKey = (value) => key("recovery", pendingKey(value));
+export const createOrganizationHandoffDockerObservation = (input) => {
+    if (typeof input.containerId !== "string" || !CONTAINER.test(input.containerId)
+        || typeof input.imageId !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(input.imageId))
+        return fail();
+    return Object.freeze({
+        container_id: input.containerId,
+        deployment_labels: exactLabels(input.deploymentLabels),
+        image_id: input.imageId,
+        pending_key: pendingKey(input.pendingKey),
+        version: ORGANIZATION_HANDOFF_RECOVERY_VERSION
+    });
+};
+export const parseOrganizationHandoffDockerObservation = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+        if (!exact(raw, ["container_id", "deployment_labels", "image_id", "pending_key", "version"])
+            || raw.version !== ORGANIZATION_HANDOFF_RECOVERY_VERSION)
+            return fail();
+        const value = raw;
+        return createOrganizationHandoffDockerObservation({
+            containerId: value.container_id,
+            deploymentLabels: value.deployment_labels,
+            imageId: value.image_id,
+            pendingKey: value.pending_key
+        });
+    }
+    catch {
+        return fail();
+    }
+};
+export const createOrganizationHandoffHandle = (pending, containerId) => {
+    if (typeof containerId !== "string" || !CONTAINER.test(containerId))
+        return fail();
+    const handle = parseOpaqueTargetHandle(`opaque_${key("capability", JSON.stringify({
+        binding_digest: pending.binding_digest, container_id: containerId, container_name: pending.container_name,
+        deployment_labels: pending.deployment_labels, descriptor_digest: pending.descriptor_digest,
+        handoff: pending.handoff, pending_key: pending.pending_key, selected_target: pending.selected_target,
+        selected_target_receipt_digest: pending.selected_target_receipt_digest
+    }))}`);
+    if (handle === pending.handoff.network_attachment_handle || handle === pending.selected_target.handle)
+        return fail();
+    return handle;
+};
+export const createOrganizationHandoffCapabilityPending = (input) => {
+    const handoff = parseOrganizationHandoff(input.handoff);
+    const selected = parseSelectedTargetReceipt(input.selectedTarget);
+    const selectedDigest = digest(input.selectedTargetReceiptDigest);
+    if (selectedDigest !== canonicalSelectedDigest(selected) || handoff.selected_target_receipt_digest !== selectedDigest
+        || handoff.binding_digest !== digest(input.bindingDigest) || handoff.network_attachment_handle === selected.handle || typeof input.containerName !== "string"
+        || !NAME.test(input.containerName))
+        return fail();
+    const body = { binding_digest: handoff.binding_digest, container_name: input.containerName,
+        deployment_labels: exactLabels(input.deploymentLabels), descriptor_digest: digest(input.descriptorDigest), handoff,
+        selected_target: selected,
+        selected_target_receipt_digest: selectedDigest };
+    return Object.freeze({ ...body, pending_key: createOrganizationHandoffPendingKey(body), state: "pending",
+        version: ORGANIZATION_HANDOFF_CAPABILITY_VERSION });
+};
+export const parseOrganizationHandoffCapability = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+        if (!raw || typeof raw !== "object")
+            return fail();
+        const record = raw;
+        const state = record.state;
+        const base = ["binding_digest", "container_name", "deployment_labels", "descriptor_digest", "handoff", "pending_key", "selected_target", "selected_target_receipt_digest", "state", "version"];
+        const extra = state === "pending" ? [] : ["container_id", "organization_handoff_handle"];
+        if (!exact(raw, [...base, ...extra]) || record.version !== ORGANIZATION_HANDOFF_CAPABILITY_VERSION
+            || state !== "pending" && state !== "finalized" && state !== "attach_closed")
+            return fail();
+        const pending = createOrganizationHandoffCapabilityPending({ bindingDigest: record.binding_digest,
+            containerName: record.container_name, deploymentLabels: record.deployment_labels,
+            descriptorDigest: record.descriptor_digest, handoff: record.handoff,
+            selectedTarget: record.selected_target, selectedTargetReceiptDigest: record.selected_target_receipt_digest });
+        if (pending.pending_key !== record.pending_key)
+            return fail();
+        if (state === "pending")
+            return pending;
+        const containerId = record.container_id;
+        if (typeof containerId !== "string" || !CONTAINER.test(containerId))
+            return fail();
+        const handle = createOrganizationHandoffHandle(pending, containerId);
+        if (record.organization_handoff_handle !== handle || handle === pending.handoff.network_attachment_handle
+            || handle === pending.selected_target.handle)
+            return fail();
+        if (state === "finalized")
+            return Object.freeze({ ...pending, container_id: containerId,
+                organization_handoff_handle: handle, state: "finalized" });
+        return Object.freeze({ ...pending, container_id: containerId, organization_handoff_handle: handle,
+            state: "attach_closed" });
+    }
+    catch {
+        return fail();
+    }
+};
+export const parseOrganizationAttachmentAuthorizationForDeployment = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+        const record = raw;
+        const keys = ["descriptor_digest", "operation_handle", "organization_handoff_handle", "request_digest", "run_id", "selected_target", "version"];
+        if (!exact(raw, keys) || record.version !== "spawnfile.target-organization-attachment.authorization.v1"
+            || !exact(record.selected_target, ["fingerprint", "handle"]))
+            return fail();
+        const selected = parseSelectedTargetReceipt({ ...record.selected_target, version: "spawnfile.target-resource.selected-target.v1" });
+        const operationHandle = parseOpaqueTargetHandle(record.operation_handle);
+        const handoffHandle = parseOpaqueTargetHandle(record.organization_handoff_handle);
+        if (operationHandle === handoffHandle || operationHandle === selected.handle || handoffHandle === selected.handle)
+            return fail();
+        return Object.freeze({ descriptor_digest: digest(record.descriptor_digest), operation_handle: operationHandle,
+            organization_handoff_handle: handoffHandle, request_digest: digest(record.request_digest),
+            run_id: parseRunId(record.run_id), selected_target: Object.freeze({ fingerprint: selected.fingerprint, handle: selected.handle }),
+            version: "spawnfile.target-organization-attachment.authorization.v1" });
+    }
+    catch {
+        return fail();
+    }
+};

package/dist/deployment/organizationHandoffTypes.d.ts

@@ -0,0 +1,29 @@
+import { type OpaqueTargetHandle, type RunId } from "../target/index.js";
+export declare const ORGANIZATION_HANDOFF_VERSION: "spawnfile.organization-handoff.v1";
+declare const canonicalSha256Digest: unique symbol;
+export type CanonicalSha256Digest = string & {
+    readonly [canonicalSha256Digest]: "CanonicalSha256Digest";
+};
+export interface OrganizationHandoffInput {
+    bindingDigest: CanonicalSha256Digest;
+    networkAttachmentHandle: OpaqueTargetHandle;
+    selectedTargetReceiptDigest: CanonicalSha256Digest;
+}
+export interface OrganizationHandoff {
+    binding_digest: CanonicalSha256Digest;
+    deployment_handle: string;
+    lifecycle_receipts: {
+        down: "spawnfile.down-receipt.v1";
+        export: "spawnfile.export-index.v1";
+        up: "spawnfile.up-receipt.v1";
+    };
+    network_attachment_handle: OpaqueTargetHandle;
+    run_id: RunId;
+    selected_target_receipt_digest: CanonicalSha256Digest;
+    version: typeof ORGANIZATION_HANDOFF_VERSION;
+}
+export declare const parseCanonicalSha256Digest: (value: unknown, label?: string) => CanonicalSha256Digest;
+export declare const createOrganizationDeploymentHandle: (input: Omit<OrganizationHandoff, "deployment_handle" | "version">) => string;
+export declare const createOrganizationHandoff: (runId: unknown, input: OrganizationHandoffInput) => OrganizationHandoff;
+export declare const parseOrganizationHandoff: (value: unknown) => OrganizationHandoff;
+export {};