spawnfile 0.1.13 → 0.1.17

package/dist/target/dockerProjectionJson.js

@@ -0,0 +1,80 @@
+const fail = () => { throw new Error("Invalid Docker projection JSON"); };
+const skipWhitespace = (source, index) => {
+    while (index < source.length && /[\t\n\r ]/u.test(source[index]))
+        index += 1;
+    return index;
+};
+const stringEnd = (source, start) => {
+    let index = start + 1;
+    while (index < source.length) {
+        if (source[index] === "\\") {
+            index += 2;
+            continue;
+        }
+        if (source[index] === "\"")
+            return index + 1;
+        index += 1;
+    }
+    return fail();
+};
+const duplicateFreeValue = (source, start) => {
+    let index = skipWhitespace(source, start);
+    const token = source[index];
+    if (token === "\"")
+        return stringEnd(source, index);
+    if (token === "{") {
+        index = skipWhitespace(source, index + 1);
+        const keys = new Set();
+        if (source[index] === "}")
+            return index + 1;
+        while (true) {
+            if (source[index] !== "\"")
+                return fail();
+            const end = stringEnd(source, index);
+            const key = JSON.parse(source.slice(index, end));
+            if (keys.has(key))
+                return fail();
+            keys.add(key);
+            index = skipWhitespace(source, end);
+            if (source[index] !== ":")
+                return fail();
+            index = duplicateFreeValue(source, index + 1);
+            index = skipWhitespace(source, index);
+            if (source[index] === "}")
+                return index + 1;
+            if (source[index] !== ",")
+                return fail();
+            index = skipWhitespace(source, index + 1);
+        }
+    }
+    if (token === "[") {
+        index = skipWhitespace(source, index + 1);
+        if (source[index] === "]")
+            return index + 1;
+        while (true) {
+            index = duplicateFreeValue(source, index);
+            index = skipWhitespace(source, index);
+            if (source[index] === "]")
+                return index + 1;
+            if (source[index] !== ",")
+                return fail();
+            index = skipWhitespace(source, index + 1);
+        }
+    }
+    while (index < source.length && !/[\t\n\r ,}\]]/u.test(source[index]))
+        index += 1;
+    if (index === start)
+        return fail();
+    return index;
+};
+export const parseDuplicateFreeDockerProjection = (source) => {
+    try {
+        const end = duplicateFreeValue(source, 0);
+        if (skipWhitespace(source, end) !== source.length)
+            return null;
+        return JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+};

package/dist/target/dockerPublicArtifactSnapshot.d.ts

@@ -0,0 +1,17 @@
+import { type DockerTargetExecutors } from "./dockerCommandExecutor.js";
+import { type TargetPublicArtifactSnapshotResult } from "./publicArtifactSnapshot.js";
+import { type DockerWorldServiceExecutor } from "./dockerWorldServiceProvider.js";
+import type { WorldServiceAuthorityStore } from "./dockerWorldServiceStore.js";
+export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_ERROR = "Target public artifact snapshot failed";
+export interface DockerPublicArtifactSnapshotOptions {
+    readonly authorityStore: WorldServiceAuthorityStore;
+    readonly context: string;
+    readonly contentExecutor: DockerTargetExecutors["publicArtifact"];
+    readonly executor: DockerWorldServiceExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}
+export interface PublicArtifactSnapshotReader {
+    snapshot(raw: unknown): Promise<TargetPublicArtifactSnapshotResult>;
+}
+export declare const createDockerPublicArtifactSnapshotReader: (options: DockerPublicArtifactSnapshotOptions) => PublicArtifactSnapshotReader;

package/dist/target/dockerPublicArtifactSnapshot.js

@@ -0,0 +1,83 @@
+import { SpawnfileError } from "../shared/index.js";
+import { createPublicArtifactReadCommand, DockerPublicArtifactNotPresentError } from "./dockerCommandExecutor.js";
+import { createTargetPublicArtifactSnapshot, createTargetPublicArtifactSnapshotNotPresent, parseTargetPublicArtifactSnapshotRequest } from "./publicArtifactSnapshot.js";
+import { inspectDockerWorldService, sameWorldServiceValue, worldServiceSpecForBinding } from "./dockerWorldServiceLifecycle.js";
+export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_ERROR = "Target public artifact snapshot failed";
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => {
+    throw new SpawnfileError("runtime_error", TARGET_PUBLIC_ARTIFACT_SNAPSHOT_ERROR);
+};
+const validOptions = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)
+        || typeof raw.context !== "string" || !CONTEXT_PATTERN.test(raw.context)
+        || typeof raw.contentExecutor !== "function"
+        || typeof raw.executor !== "function"
+        || !raw.authorityStore || typeof raw.authorityStore.loadService !== "function"
+        || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1
+        || raw.timeoutMs > 120_000
+        || raw.signal !== undefined && !(raw.signal instanceof AbortSignal))
+        return fail();
+    return raw;
+};
+const exactBinding = async (request, options) => {
+    const binding = await options.authorityStore.loadService(request.world_service_handle);
+    const authorization = binding.resolution.authorization;
+    if (binding.world_service_handle !== request.world_service_handle
+        || authorization.run_id !== request.run_id
+        || authorization.descriptor_digest !== request.descriptor_digest
+        || !sameWorldServiceValue(authorization.selected_target, request.selected_target))
+        return fail();
+    return binding;
+};
+const readPublicArtifact = async (containerId, request, options) => {
+    let result;
+    try {
+        result = await options.contentExecutor("docker", createPublicArtifactReadCommand({
+            containerId,
+            context: options.context,
+            path: request.artifact.path
+        }), {
+            signal: options.signal,
+            timeout: options.timeoutMs
+        });
+    }
+    catch (error) {
+        if (error instanceof DockerPublicArtifactNotPresentError)
+            return null;
+        return fail();
+    }
+    if (!result || !(result.bytes instanceof Uint8Array)
+        || result.bytes.byteLength > request.artifact.max_bytes)
+        return fail();
+    return Uint8Array.from(result.bytes);
+};
+class DockerPublicArtifactSnapshotReader {
+    #options;
+    constructor(options) {
+        this.#options = validOptions(options);
+    }
+    async snapshot(raw) {
+        let request;
+        try {
+            request = parseTargetPublicArtifactSnapshotRequest(raw);
+        }
+        catch {
+            return fail();
+        }
+        const binding = await exactBinding(request, this.#options).catch(fail);
+        const spec = worldServiceSpecForBinding(binding);
+        const before = await inspectDockerWorldService(binding.container_id, spec, this.#options).catch(fail);
+        if (!before || before.containerId !== binding.container_id
+            || before.status !== "running")
+            return fail();
+        const content = await readPublicArtifact(binding.container_id, request, this.#options);
+        const after = await inspectDockerWorldService(binding.container_id, spec, this.#options).catch(fail);
+        if (!after || after.containerId !== before.containerId
+            || after.status !== "running")
+            return fail();
+        return content === null
+            ? createTargetPublicArtifactSnapshotNotPresent(request)
+            : createTargetPublicArtifactSnapshot({ content, request });
+    }
+}
+export const createDockerPublicArtifactSnapshotReader = (options) => new DockerPublicArtifactSnapshotReader(options);

package/dist/target/dockerResources.d.ts

@@ -0,0 +1,26 @@
+import { type TargetResourceReceipt } from "./contracts.js";
+import { type TargetJournalStore } from "./journal.js";
+import { type DockerResourceExecutor, type DockerResourceSpec } from "./dockerResourcesProvider.js";
+export interface DockerResourceOperationsOptions {
+    readonly context: unknown;
+    readonly executor: DockerResourceExecutor;
+    readonly journal: TargetJournalStore;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: unknown;
+}
+export interface DockerResourceOperations {
+    execute(raw: unknown): Promise<{
+        readonly receipt: TargetResourceReceipt;
+        readonly receiptBytes: string;
+    }>;
+}
+export interface DockerResourceCleanupOptions {
+    readonly context: string;
+    readonly executor: DockerResourceExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}
+export declare const proveExactDockerResourcePresent: (spec: DockerResourceSpec, options: DockerResourceCleanupOptions) => Promise<void>;
+export declare const removeExactDockerResource: (spec: DockerResourceSpec, options: DockerResourceCleanupOptions) => Promise<void>;
+export declare const createDockerResourceOperations: (options: DockerResourceOperationsOptions) => DockerResourceOperations;
+export declare const createDockerResources: (options: DockerResourceOperationsOptions) => DockerResourceOperations;

package/dist/target/dockerResources.js

@@ -0,0 +1,162 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseTargetResourceRequest } from "./contracts.js";
+import { selectTarget } from "./dockerTarget.js";
+import { createTargetReceiptDigest } from "./handles.js";
+import { DOCKER_RESOURCE_ERROR, DockerResourceProviderError, createDockerResourceSpec, executeDockerResource, isCanonicalDockerResourceSpec, isExpectedDockerResource } from "./dockerResourcesProvider.js";
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => { throw new SpawnfileError("runtime_error", DOCKER_RESOURCE_ERROR); };
+const validOptions = (raw) => {
+    if (typeof raw.context !== "string" || !CONTEXT_PATTERN.test(raw.context)
+        || typeof raw.executor !== "function" || !raw.journal
+        || typeof raw.timeoutMs !== "undefined" && (typeof raw.timeoutMs !== "number" || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1 || raw.timeoutMs > 120_000))
+        fail();
+    return { context: raw.context, executor: raw.executor, journal: raw.journal, signal: raw.signal, timeoutMs: (raw.timeoutMs ?? 10_000) };
+};
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const parseResourceRequest = (raw) => {
+    const request = parseTargetResourceRequest(raw);
+    if (request.operation !== "create_data_network" && request.operation !== "create_evidence_volume")
+        fail();
+    return request;
+};
+const selectedContextMatches = async (request, options) => {
+    const selected = await selectTarget({
+        context: options.context, dockerCommand: "docker",
+        execFile: async (_file, args, commandOptions) => executeDockerResource({ args, executor: options.executor, signal: commandOptions.signal, timeoutMs: commandOptions.timeout }),
+        signal: options.signal, timeoutMs: options.timeoutMs
+    });
+    if (!same({ fingerprint: selected.fingerprint, handle: selected.handle }, request.selected_target))
+        fail();
+};
+const receiptFor = async (input) => {
+    const revision = (await input.journal.read()).revision + 1;
+    const labels = Object.entries(createDockerResourceSpec({
+        kind: input.kind, operationHandle: input.claim.operationHandle,
+        requestDigest: input.claim.requestDigest, runId: input.request.run_id, selectedTargetHandle: input.request.selected_target.handle
+    }).labels).map(([key, value]) => ({ key, value }));
+    const raw = {
+        cleanup_state: "not_requested", descriptor_digest: input.request.descriptor_digest, export_state: "not_requested",
+        labels, 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: revision, run_id: input.request.run_id,
+        selected_target: input.request.selected_target, version: "spawnfile.target-resource.receipt.v1"
+    };
+    return { ...raw, receipt_digest: createTargetReceiptDigest(raw) };
+};
+const inspect = async (spec, options) => {
+    try {
+        const result = await executeDockerResource({ args: ["--context", options.context, spec.kind === "data_network" ? "network" : "volume", "inspect", "--format", spec.inspectionFormat, spec.name], executor: options.executor, signal: options.signal, timeoutMs: options.timeoutMs });
+        if (!isExpectedDockerResource(result.stdout, spec))
+            fail();
+        return "present";
+    }
+    catch (error) {
+        if (error instanceof DockerResourceProviderError && error.kind === "not_found")
+            return "absent";
+        throw error;
+    }
+};
+const validateCleanupAuthority = (spec, options) => {
+    if (!isCanonicalDockerResourceSpec(spec)
+        || !options || typeof options.context !== "string" || !CONTEXT_PATTERN.test(options.context)
+        || typeof options.executor !== "function" || !Number.isSafeInteger(options.timeoutMs)
+        || options.timeoutMs < 1 || options.timeoutMs > 120_000)
+        return fail();
+};
+export const proveExactDockerResourcePresent = async (spec, options) => {
+    try {
+        validateCleanupAuthority(spec, options);
+        if (await inspect(spec, options) !== "present")
+            return fail();
+    }
+    catch {
+        return fail();
+    }
+};
+export const removeExactDockerResource = async (spec, options) => {
+    try {
+        validateCleanupAuthority(spec, options);
+        if (await inspect(spec, options) === "absent")
+            return;
+        let removalError;
+        let removalResult;
+        try {
+            removalResult = await executeDockerResource({
+                args: ["--context", options.context,
+                    spec.kind === "data_network" ? "network" : "volume", "rm", spec.name],
+                executor: options.executor,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs
+            });
+        }
+        catch (error) {
+            removalError = error;
+        }
+        if (removalResult
+            && (removalResult.stderr !== "" || removalResult.stdout !== `${spec.name}\n`))
+            return fail();
+        if (await inspect(spec, options) !== "absent") {
+            if (removalError)
+                throw removalError;
+            return fail();
+        }
+    }
+    catch {
+        return fail();
+    }
+};
+const create = async (spec, options) => {
+    try {
+        await executeDockerResource({ args: ["--context", options.context, ...spec.args], executor: options.executor, signal: options.signal, timeoutMs: options.timeoutMs });
+    }
+    catch (error) {
+        if (!(error instanceof DockerResourceProviderError) || error.kind !== "collision")
+            throw error;
+        if (await inspect(spec, options) !== "present")
+            fail();
+    }
+};
+class DockerResourceOperationsImpl {
+    #options;
+    #live = new Map();
+    constructor(options) { this.#options = options; }
+    execute(raw) {
+        let request;
+        try {
+            request = parseResourceRequest(raw);
+        }
+        catch {
+            return Promise.reject(new SpawnfileError("runtime_error", DOCKER_RESOURCE_ERROR));
+        }
+        const active = this.#live.get(request.idempotency_key);
+        if (active)
+            return same(active.request, request) ? active.promise : Promise.reject(new SpawnfileError("runtime_error", DOCKER_RESOURCE_ERROR));
+        let resolve;
+        let reject;
+        const promise = new Promise((accept, refuse) => { resolve = accept; reject = refuse; });
+        this.#live.set(request.idempotency_key, { request, promise });
+        void this.executeOwner(request).then(resolve, reject).finally(() => { if (this.#live.get(request.idempotency_key)?.promise === promise)
+            this.#live.delete(request.idempotency_key); });
+        return promise;
+    }
+    async executeOwner(request) {
+        try {
+            const kind = request.operation === "create_data_network" ? "data_network" : "evidence_volume";
+            const reservation = await this.#options.journal.reserve(request);
+            if (reservation.kind === "replay")
+                return { receipt: reservation.receipt, receiptBytes: reservation.receiptBytes };
+            await selectedContextMatches(request, this.#options);
+            const spec = createDockerResourceSpec({ kind, operationHandle: reservation.claim.operationHandle, requestDigest: reservation.claim.requestDigest, runId: request.run_id, selectedTargetHandle: request.selected_target.handle });
+            const pendingState = reservation.kind === "pending" ? await inspect(spec, this.#options) : undefined;
+            if (reservation.kind === "owner" || pendingState === "absent")
+                await create(spec, this.#options);
+            const receipt = await receiptFor({ claim: reservation.claim, kind, request, resultHandle: spec.resultHandle, journal: this.#options.journal });
+            return await this.#options.journal.complete(reservation.claim, receipt);
+        }
+        catch {
+            return fail();
+        }
+    }
+}
+export const createDockerResourceOperations = (options) => new DockerResourceOperationsImpl(validOptions(options));
+export const createDockerResources = createDockerResourceOperations;

package/dist/target/dockerResourcesProvider.d.ts

@@ -0,0 +1,44 @@
+import { type OpaqueTargetHandle } from "./contracts.js";
+export declare const DOCKER_RESOURCE_ERROR = "Docker resource mutation failed";
+export type DockerResourceKind = "data_network" | "evidence_volume";
+export type DockerResourceFailureKind = "collision" | "not_found";
+export interface DockerResourceExecutor {
+    (file: string, args: string[], options: {
+        signal?: AbortSignal;
+        timeout: number;
+    }): Promise<{
+        stderr: string;
+        stdout: string;
+    }>;
+}
+/** A safe error classification supplied by the injected provider bridge. */
+export declare class DockerResourceProviderError extends Error {
+    readonly kind: DockerResourceFailureKind;
+    constructor(kind: DockerResourceFailureKind);
+}
+export interface DockerResourceSpec {
+    readonly args: string[];
+    readonly inspectionFormat: string;
+    readonly kind: DockerResourceKind;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly name: string;
+    readonly resultHandle: OpaqueTargetHandle;
+}
+export declare const isCanonicalDockerResourceSpec: (raw: unknown) => raw is DockerResourceSpec;
+export declare const createDockerResourceSpec: (input: {
+    kind: DockerResourceKind;
+    operationHandle: OpaqueTargetHandle;
+    requestDigest: string;
+    runId: string;
+    selectedTargetHandle: OpaqueTargetHandle;
+}) => DockerResourceSpec;
+export declare const executeDockerResource: (input: {
+    args: string[];
+    executor: DockerResourceExecutor;
+    signal?: AbortSignal;
+    timeoutMs: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export declare const isExpectedDockerResource: (stdout: string, spec: DockerResourceSpec) => boolean;

package/dist/target/dockerResourcesProvider.js

@@ -0,0 +1,207 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle } from "./contracts.js";
+export const DOCKER_RESOURCE_ERROR = "Docker resource mutation failed";
+const MAX_OUTPUT_BYTES = 32_768;
+const MAX_NAME_LENGTH = 63;
+/** A safe error classification supplied by the injected provider bridge. */
+export class DockerResourceProviderError extends Error {
+    kind;
+    constructor(kind) { super(DOCKER_RESOURCE_ERROR); this.kind = kind; }
+}
+export const isCanonicalDockerResourceSpec = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+    }
+    catch {
+        return false;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)
+        || Object.getPrototypeOf(raw) !== Object.prototype)
+        return false;
+    const value = raw;
+    if (Object.keys(value).sort().join("\0")
+        !== "args\0inspectionFormat\0kind\0labels\0name\0resultHandle"
+        || value.kind !== "data_network" && value.kind !== "evidence_volume"
+        || typeof value.name !== "string"
+        || !(value.kind === "data_network" ? /^spfn_[a-f0-9]{58}$/u : /^spfv_[a-f0-9]{58}$/u)
+            .test(value.name)
+        || !value.labels || typeof value.labels !== "object" || Array.isArray(value.labels)
+        || Object.getPrototypeOf(value.labels) !== Object.prototype)
+        return false;
+    const labels = value.labels;
+    const labelKeys = [
+        "spawnfile_resource_v1_kind", "spawnfile_resource_v1_operation",
+        "spawnfile_resource_v1_run", "spawnfile_resource_v1_target",
+        "spawnfile_resource_v1_version"
+    ];
+    if (Object.keys(labels).sort().join("\0") !== [...labelKeys].sort().join("\0")
+        || labels.spawnfile_resource_v1_kind !== value.kind
+        || typeof labels.spawnfile_resource_v1_operation !== "string"
+        || !/^o[a-f0-9]{63}$/u.test(labels.spawnfile_resource_v1_operation)
+        || typeof labels.spawnfile_resource_v1_run !== "string"
+        || !/^r[a-f0-9]{63}$/u.test(labels.spawnfile_resource_v1_run)
+        || typeof labels.spawnfile_resource_v1_target !== "string"
+        || !/^t[a-f0-9]{63}$/u.test(labels.spawnfile_resource_v1_target)
+        || labels.spawnfile_resource_v1_version !== "v1")
+        return false;
+    const inspectionFormat = value.kind === "data_network"
+        ? "[{\"Name\":{{json .Name}},\"Labels\":{{json .Labels}},\"Internal\":{{json .Internal}}}]"
+        : "[{\"Name\":{{json .Name}},\"Labels\":{{json .Labels}}}]";
+    const labelArgs = labelKeys.flatMap((key) => ["--label", `${key}=${String(labels[key])}`]);
+    const args = value.kind === "data_network"
+        ? ["network", "create", "--internal", ...labelArgs, value.name]
+        : ["volume", "create", ...labelArgs, value.name];
+    try {
+        return value.inspectionFormat === inspectionFormat
+            && JSON.stringify(value.args) === JSON.stringify(args)
+            && parseOpaqueTargetHandle(value.resultHandle) === value.resultHandle;
+    }
+    catch {
+        return false;
+    }
+};
+const digest = (domain, value) => createHash("sha256")
+    .update(`spawnfile.target-resource.${domain}.v1\0`, "utf8").update(value, "utf8").digest("hex");
+const labelValue = (prefix, value) => `${prefix}${digest("docker-resource-label", value).slice(0, 63)}`;
+export const createDockerResourceSpec = (input) => {
+    const authority = `${input.kind}\0${input.operationHandle}\0${input.requestDigest}`;
+    const namePrefix = input.kind === "data_network" ? "spfn_" : "spfv_";
+    const name = `${namePrefix}${digest("docker-resource-name", authority).slice(0, MAX_NAME_LENGTH - namePrefix.length)}`;
+    const resultHandle = parseOpaqueTargetHandle(`opaque_${digest("docker-resource-result", authority)}`);
+    const labels = Object.freeze({
+        spawnfile_resource_v1_kind: input.kind,
+        spawnfile_resource_v1_operation: labelValue("o", `${input.operationHandle}\0${input.requestDigest}`),
+        spawnfile_resource_v1_run: labelValue("r", input.runId),
+        spawnfile_resource_v1_target: labelValue("t", input.selectedTargetHandle),
+        spawnfile_resource_v1_version: "v1"
+    });
+    const labelArgs = Object.entries(labels).flatMap(([key, value]) => ["--label", `${key}=${value}`]);
+    const create = input.kind === "data_network"
+        ? ["network", "create", "--internal", ...labelArgs, name]
+        : ["volume", "create", ...labelArgs, name];
+    const inspectionFormat = input.kind === "data_network"
+        ? "[{\"Name\":{{json .Name}},\"Labels\":{{json .Labels}},\"Internal\":{{json .Internal}}}]"
+        : "[{\"Name\":{{json .Name}},\"Labels\":{{json .Labels}}}]";
+    return { args: create, inspectionFormat, kind: input.kind, labels, name, resultHandle };
+};
+const isUtf8 = (value) => Buffer.from(value, "utf8").toString("utf8") === value;
+const boundedText = (value) => typeof value === "string" && isUtf8(value) && Buffer.byteLength(value, "utf8") <= MAX_OUTPUT_BYTES;
+export const executeDockerResource = async (input) => {
+    try {
+        const result = await input.executor("docker", input.args, { signal: input.signal, timeout: input.timeoutMs });
+        if (!result || !boundedText(result.stdout) || !boundedText(result.stderr))
+            throw new Error();
+        return result;
+    }
+    catch (error) {
+        if (error instanceof DockerResourceProviderError)
+            throw error;
+        throw new Error(DOCKER_RESOURCE_ERROR);
+    }
+};
+const skipWhitespace = (source, index) => {
+    while (index < source.length && /[\t\n\r ]/u.test(source[index]))
+        index += 1;
+    return index;
+};
+const stringEnd = (source, start) => {
+    let index = start + 1;
+    while (index < source.length) {
+        if (source[index] === "\\") {
+            index += 2;
+            continue;
+        }
+        if (source[index] === "\"")
+            return index + 1;
+        index += 1;
+    }
+    throw new Error();
+};
+const duplicateFreeValue = (source, start) => {
+    let index = skipWhitespace(source, start);
+    const token = source[index];
+    if (token === "\"")
+        return stringEnd(source, index);
+    if (token === "{") {
+        index = skipWhitespace(source, index + 1);
+        const keys = new Set();
+        if (source[index] === "}")
+            return index + 1;
+        while (true) {
+            if (source[index] !== "\"")
+                throw new Error();
+            const end = stringEnd(source, index);
+            const key = JSON.parse(source.slice(index, end));
+            if (keys.has(key))
+                throw new Error();
+            keys.add(key);
+            index = skipWhitespace(source, end);
+            if (source[index] !== ":")
+                throw new Error();
+            index = duplicateFreeValue(source, index + 1);
+            index = skipWhitespace(source, index);
+            if (source[index] === "}")
+                return index + 1;
+            if (source[index] !== ",")
+                throw new Error();
+            index = skipWhitespace(source, index + 1);
+        }
+    }
+    if (token === "[") {
+        index = skipWhitespace(source, index + 1);
+        if (source[index] === "]")
+            return index + 1;
+        while (true) {
+            index = duplicateFreeValue(source, index);
+            index = skipWhitespace(source, index);
+            if (source[index] === "]")
+                return index + 1;
+            if (source[index] !== ",")
+                throw new Error();
+            index = skipWhitespace(source, index + 1);
+        }
+    }
+    while (index < source.length && !/[\t\n\r ,}\]]/u.test(source[index]))
+        index += 1;
+    if (index === start)
+        throw new Error();
+    return index;
+};
+const parseInspection = (stdout) => {
+    if (!boundedText(stdout))
+        throw new Error();
+    const end = duplicateFreeValue(stdout, 0);
+    if (skipWhitespace(stdout, end) !== stdout.length)
+        throw new Error();
+    const parsed = JSON.parse(stdout);
+    assertOrdinaryJsonGraph(parsed);
+    return parsed;
+};
+const exactLabels = (actual, expected) => {
+    if (!actual || typeof actual !== "object" || Array.isArray(actual) || Object.getPrototypeOf(actual) !== Object.prototype)
+        return false;
+    const record = actual;
+    const actualKeys = Object.keys(record).sort();
+    const expectedKeys = Object.keys(expected).sort();
+    return actualKeys.length === expectedKeys.length && actualKeys.every((key, index) => key === expectedKeys[index] && record[key] === expected[key]);
+};
+export const isExpectedDockerResource = (stdout, spec) => {
+    try {
+        const parsed = parseInspection(stdout);
+        if (!Array.isArray(parsed) || parsed.length !== 1)
+            return false;
+        const resource = parsed[0];
+        if (!resource || typeof resource !== "object" || Array.isArray(resource) || Object.getPrototypeOf(resource) !== Object.prototype)
+            return false;
+        const record = resource;
+        const keys = Object.keys(record).sort();
+        const expectedKeys = spec.kind === "data_network" ? ["Internal", "Labels", "Name"] : ["Labels", "Name"];
+        return keys.length === expectedKeys.length && keys.every((key, index) => key === expectedKeys[index])
+            && record.Name === spec.name && exactLabels(record.Labels, spec.labels)
+            && (spec.kind !== "data_network" || record.Internal === true);
+    }
+    catch {
+        return false;
+    }
+};

package/dist/target/dockerSecrets.d.ts

@@ -0,0 +1,39 @@
+import { type OpaqueTargetHandle, type TargetResourceReceipt } from "./contracts.js";
+import { type TargetJournalStore } from "./journal.js";
+import { type TargetSecretSourceAuthorization, type TargetSecretVersionAuthorityStore } from "./dockerSecretsAuthority.js";
+import { type DockerSecretExecutor } from "./dockerSecretsProvider.js";
+type OperationResult = {
+    readonly receipt: TargetResourceReceipt;
+    readonly receiptBytes: string;
+};
+export interface TargetSecretSourceResolverInput {
+    readonly authorization: TargetSecretSourceAuthorization;
+    readonly signal?: AbortSignal;
+}
+export interface TargetSecretSourceResolution {
+    readonly authorization: TargetSecretSourceAuthorization;
+    readonly sourceVersionHandle: OpaqueTargetHandle;
+    readonly value: Uint8Array;
+}
+/**
+ * Trusted operator seam. Returned bytes transfer to the caller and are zeroed
+ * after the one stdin write; a source handle must resolve immutably on retry.
+ */
+export interface TargetSecretSourceResolver {
+    resolve(input: TargetSecretSourceResolverInput): Promise<TargetSecretSourceResolution>;
+}
+export interface DockerSecretOperationsOptions {
+    readonly authorityStore: TargetSecretVersionAuthorityStore;
+    readonly context: unknown;
+    readonly executor: DockerSecretExecutor;
+    readonly journal: TargetJournalStore;
+    readonly resolver: TargetSecretSourceResolver;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: unknown;
+}
+export interface DockerSecretOperations {
+    execute(raw: unknown): Promise<OperationResult>;
+}
+export declare const createDockerSecretOperations: (options: DockerSecretOperationsOptions) => DockerSecretOperations;
+export declare const createDockerSecrets: (options: DockerSecretOperationsOptions) => DockerSecretOperations;
+export {};