spawnfile 0.1.13 → 0.1.17

package/dist/target/dockerArtifacts.js

@@ -0,0 +1,110 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseTargetResourceRequest } from "./contracts.js";
+import { DOCKER_ARTIFACT_ERROR, createDockerArtifactSpec, executeDockerArtifact, isExpectedDockerArtifact, parseDockerArtifactMappings } from "./dockerArtifactsProvider.js";
+import { selectTarget } from "./dockerTarget.js";
+import { createTargetReceiptDigest } from "./handles.js";
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => { throw new SpawnfileError("runtime_error", DOCKER_ARTIFACT_ERROR); };
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const exactContext = (value) => CONTEXT_PATTERN.exec(value)?.[0] === value;
+const validOptions = (raw) => {
+    try {
+        if (typeof raw.context !== "string" || !exactContext(raw.context)
+            || typeof raw.executor !== "function" || !raw.identityStore || typeof raw.identityStore.bind !== "function" || !raw.journal
+            || typeof raw.timeoutMs !== "undefined" && (typeof raw.timeoutMs !== "number" || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1 || raw.timeoutMs > 120_000))
+            return fail();
+        return {
+            context: raw.context, executor: raw.executor, identityStore: raw.identityStore, journal: raw.journal,
+            mappings: parseDockerArtifactMappings(raw.mappings), signal: raw.signal, timeoutMs: raw.timeoutMs ?? 10_000
+        };
+    }
+    catch {
+        return fail();
+    }
+};
+const parseRequest = (raw) => {
+    const request = parseTargetResourceRequest(raw);
+    if (request.operation !== "resolve_world_artifact")
+        return fail();
+    return request;
+};
+const mappingFor = (request, options) => options.mappings.find((mapping) => mapping.artifact_manifest_digest === request.artifact_manifest_digest) ?? fail();
+const selectedContextMatches = async (request, options) => {
+    const selected = await selectTarget({
+        context: options.context, dockerCommand: "docker",
+        execFile: async (_file, args, commandOptions) => executeDockerArtifact({ 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))
+        return fail();
+};
+const receiptFor = async (input) => {
+    const revision = (await input.journal.read()).revision + 1;
+    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: 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) };
+};
+class DockerArtifactOperationsImpl {
+    #live = new Map();
+    #options;
+    constructor(options) { this.#options = options; }
+    execute(raw) {
+        let request;
+        let mapping;
+        try {
+            request = parseRequest(raw);
+            mapping = mappingFor(request, this.#options);
+        }
+        catch {
+            return Promise.reject(new SpawnfileError("runtime_error", DOCKER_ARTIFACT_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_ARTIFACT_ERROR));
+        let resolve;
+        let reject;
+        const promise = new Promise((accept, refuse) => { resolve = accept; reject = refuse; });
+        this.#live.set(request.idempotency_key, { promise, request });
+        void this.executeOwner(request, mapping).then(resolve, reject).finally(() => {
+            if (this.#live.get(request.idempotency_key)?.promise === promise)
+                this.#live.delete(request.idempotency_key);
+        });
+        return promise;
+    }
+    async executeOwner(request, mapping) {
+        try {
+            const reservation = await this.#options.journal.reserve(request);
+            if (reservation.kind === "replay")
+                return { receipt: reservation.receipt, receiptBytes: reservation.receiptBytes };
+            const spec = createDockerArtifactSpec({
+                artifactManifestDigest: request.artifact_manifest_digest, imageDigest: mapping.image_digest,
+                imageReference: mapping.image_reference, operationHandle: reservation.claim.operationHandle,
+                requestDigest: reservation.claim.requestDigest, selectedTargetHandle: request.selected_target.handle
+            });
+            await this.#options.identityStore.bind({
+                artifactManifestDigest: request.artifact_manifest_digest, imageDigest: mapping.image_digest,
+                imageReference: mapping.image_reference, operationHandle: reservation.claim.operationHandle,
+                requestDigest: reservation.claim.requestDigest, resultHandle: spec.resultHandle,
+                selectedTargetHandle: request.selected_target.handle
+            });
+            await selectedContextMatches(request, this.#options);
+            const result = await executeDockerArtifact({
+                args: ["--context", this.#options.context, "image", "inspect", "--format", spec.inspectionFormat, spec.imageReference],
+                executor: this.#options.executor, signal: this.#options.signal, timeoutMs: this.#options.timeoutMs
+            });
+            if (!isExpectedDockerArtifact(result.stdout, spec))
+                return fail();
+            const receipt = await receiptFor({ claim: reservation.claim, journal: this.#options.journal, labels: spec.labels, request, resultHandle: spec.resultHandle });
+            return await this.#options.journal.complete(reservation.claim, receipt);
+        }
+        catch {
+            return fail();
+        }
+    }
+}
+export const createDockerArtifactOperations = (options) => new DockerArtifactOperationsImpl(validOptions(options));

package/dist/target/dockerArtifactsProvider.d.ts

@@ -0,0 +1,41 @@
+import { type OpaqueTargetHandle } from "./contracts.js";
+import type { DockerArtifactIdentityStore, DockerArtifactIdentityStoreOptions } from "./dockerArtifactIdentityTypes.js";
+export type { DockerArtifactIdentityBinding, DockerArtifactIdentityStore, DockerArtifactIdentityStoreOptions, DockerConfigArtifactIdentityBinding, DockerOciArtifactIdentityBinding } from "./dockerArtifactIdentityTypes.js";
+export declare const DOCKER_ARTIFACT_ERROR = "Docker artifact resolution failed";
+export declare const DOCKER_ARTIFACT_INSPECTION_FORMAT = "[{\"RepoDigests\":{{json .RepoDigests}}}]";
+export interface DockerArtifactExecutor {
+    (file: string, args: string[], options: {
+        signal?: AbortSignal;
+        timeout: number;
+    }): Promise<{
+        stderr: string;
+        stdout: string;
+    }>;
+}
+export declare class DockerArtifactProviderError extends Error {
+    readonly kind: "image_not_found";
+    constructor(kind: "image_not_found");
+}
+export interface DockerArtifactMapping {
+    readonly artifact_manifest_digest: string;
+    readonly image_digest: string;
+    readonly image_reference: string;
+}
+export interface DockerArtifactSpec {
+    readonly imageDigest: string;
+    readonly imageReference: string;
+    readonly inspectionFormat: typeof DOCKER_ARTIFACT_INSPECTION_FORMAT;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly resultHandle: OpaqueTargetHandle;
+}
+export interface DockerConfigArtifactSpec {
+    readonly configId: string;
+    readonly imageDigest: string;
+    readonly imageReference: string;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly resultHandle: OpaqueTargetHandle;
+}
+export declare const isImmutableDockerImageReference: (value: unknown) => value is string;
+export declare const parseDockerArtifactMappings: (raw: unknown) => readonly DockerArtifactMapping[];
+export declare const initializeDockerArtifactIdentityStore: (root: unknown, options?: DockerArtifactIdentityStoreOptions) => Promise<DockerArtifactIdentityStore>;
+export { createDockerArtifactSpec, createDockerConfigArtifactSpec, executeDockerArtifact, isExpectedDockerArtifact } from "./dockerArtifactInspection.js";

package/dist/target/dockerArtifactsProvider.js

@@ -0,0 +1,476 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, link, lstat, mkdir, open, unlink } from "node:fs/promises";
+import path from "node:path";
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle } from "./contracts.js";
+export const DOCKER_ARTIFACT_ERROR = "Docker artifact resolution failed";
+export const DOCKER_ARTIFACT_INSPECTION_FORMAT = "[{\"RepoDigests\":{{json .RepoDigests}}}]";
+const MAX_OUTPUT_BYTES = 32_768;
+const MAX_REPOSITORY_BYTES = 255;
+const MAX_REFERENCE_BYTES = MAX_REPOSITORY_BYTES + 72;
+const MAX_IDENTITY_BYTES = 262_144;
+const IDENTITY_RETRY_ATTEMPTS = 64;
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const PORT_PATTERN = /^[1-9][0-9]{0,4}$/u;
+const NAME_COMPONENT_PATTERN = /^[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*$/u;
+const DOMAIN_COMPONENT_PATTERN = /^(?:[a-z0-9]|[a-z0-9][a-z0-9-]{0,61}[a-z0-9])$/u;
+export class DockerArtifactProviderError extends Error {
+    kind;
+    constructor(kind) {
+        super(DOCKER_ARTIFACT_ERROR);
+        this.kind = kind;
+    }
+}
+const fail = () => { throw new Error(DOCKER_ARTIFACT_ERROR); };
+const bytes = (value) => Buffer.byteLength(value, "utf8");
+const exactMatch = (pattern, value) => pattern.exec(value)?.[0] === value;
+const digest = (domain, value) => createHash("sha256")
+    .update(`spawnfile.target-artifact.${domain}.v1\0`, "utf8").update(value, "utf8").digest("hex");
+const label = (prefix, value) => `${prefix}${digest("label", value).slice(0, 63)}`;
+const isDigest = (value) => typeof value === "string" && exactMatch(DIGEST_PATTERN, value);
+const isRegistry = (value) => {
+    const colon = value.lastIndexOf(":");
+    const host = colon < 0 ? value : value.slice(0, colon);
+    const port = colon < 0 ? null : value.slice(colon + 1);
+    if (host.length < 1 || host.length > 253 || host.includes(":"))
+        return false;
+    if (port !== null && (!exactMatch(PORT_PATTERN, port) || Number(port) > 65_535))
+        return false;
+    return host.split(".").every((part) => exactMatch(DOMAIN_COMPONENT_PATTERN, part));
+};
+const isRepository = (value) => {
+    const parts = value.split("/");
+    if (parts.some((part) => part.length === 0))
+        return false;
+    if (parts.length > 1 && (parts[0] === "localhost" || parts[0].includes(".") || parts[0].includes(":"))) {
+        if (!isRegistry(parts.shift()))
+            return false;
+    }
+    return parts.length > 0 && parts.every((part) => exactMatch(NAME_COMPONENT_PATTERN, part));
+};
+export const isImmutableDockerImageReference = (value) => {
+    if (typeof value !== "string" || bytes(value) > MAX_REFERENCE_BYTES || value !== value.toLowerCase())
+        return false;
+    const separator = value.indexOf("@");
+    if (separator < 1 || separator !== value.lastIndexOf("@"))
+        return false;
+    const repository = value.slice(0, separator);
+    return bytes(repository) <= MAX_REPOSITORY_BYTES && isRepository(repository) && isDigest(value.slice(separator + 1));
+};
+export const parseDockerArtifactMappings = (raw) => {
+    try {
+        assertOrdinaryJsonGraph(raw);
+        if (!Array.isArray(raw) || raw.length < 1 || raw.length > 32)
+            return fail();
+        const manifests = new Set();
+        const imageDigests = new Set();
+        const references = new Set();
+        const mappings = raw.map((value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return fail();
+            const record = value;
+            if (Object.keys(record).sort().join("\0") !== "artifact_manifest_digest\0image_digest\0image_reference")
+                return fail();
+            const manifest = record.artifact_manifest_digest;
+            const imageDigest = record.image_digest;
+            const reference = record.image_reference;
+            if (!isDigest(manifest) || !isDigest(imageDigest)
+                || !isImmutableDockerImageReference(reference) || !reference.endsWith(`@${imageDigest}`)
+                || manifests.has(manifest) || imageDigests.has(imageDigest) || references.has(reference))
+                return fail();
+            manifests.add(manifest);
+            imageDigests.add(imageDigest);
+            references.add(reference);
+            return Object.freeze({ artifact_manifest_digest: manifest, image_digest: imageDigest, image_reference: reference });
+        });
+        return Object.freeze(mappings);
+    }
+    catch {
+        return fail();
+    }
+};
+const identityBase = (input) => {
+    const operationHandle = parseOpaqueTargetHandle(input.operationHandle);
+    const resultHandle = parseOpaqueTargetHandle(input.resultHandle);
+    const selectedTargetHandle = parseOpaqueTargetHandle(input.selectedTargetHandle);
+    if (!isDigest(input.requestDigest) || !isDigest(input.artifactManifestDigest))
+        return fail();
+    return Object.freeze({ artifact_manifest_digest: input.artifactManifestDigest,
+        operation_handle: operationHandle, request_digest: input.requestDigest,
+        result_handle: resultHandle, selected_target_handle: selectedTargetHandle });
+};
+const bindingBytes = (input) => {
+    try {
+        if (!input || typeof input !== "object" || Array.isArray(input)
+            || Object.getPrototypeOf(input) !== Object.prototype)
+            return fail();
+        const descriptors = Object.getOwnPropertyDescriptors(input);
+        if (Object.values(descriptors).some((descriptor) => !("value" in descriptor)))
+            return fail();
+        const keys = Object.keys(input).sort().join("\0");
+        const oci = "artifactManifestDigest\0imageDigest\0imageReference\0operationHandle\0requestDigest\0resultHandle\0selectedTargetHandle";
+        const ociTagged = `${oci}\0identityKind`.split("\0").sort().join("\0");
+        const config = "archiveDigest\0artifactManifestDigest\0baseImageConfigDigest\0buildPolicyDigest\0bundleDigest\0configId\0daemonEpoch\0entrypoint\0gcTag\0identityKind\0launcherDigest\0networkAlias\0operationHandle\0platform\0platformDigest\0preparedOperationHandle\0preparedRequestDigest\0requestDigest\0resultHandle\0selectedTargetHandle";
+        if ((input.identityKind === "docker_image_config_digest" && keys !== config)
+            || (input.identityKind !== "docker_image_config_digest" && keys !== oci && keys !== ociTagged))
+            return fail();
+        if (input.identityKind === "oci_image_manifest" && descriptors.identityKind?.enumerable === false
+            && keys !== oci)
+            return fail();
+    }
+    catch {
+        return fail();
+    }
+    const base = identityBase(input);
+    if (input.identityKind === "docker_image_config_digest") {
+        if (!isDigest(input.archiveDigest) || !isDigest(input.baseImageConfigDigest)
+            || !isDigest(input.buildPolicyDigest) || !isDigest(input.bundleDigest) || !isDigest(input.configId)
+            || !isDigest(input.daemonEpoch) || !isDigest(input.launcherDigest) || !isDigest(input.platformDigest)
+            || !isDigest(input.preparedRequestDigest)
+            || typeof input.gcTag !== "string" || !/^spfb_[a-f0-9]{58}$/u.test(input.gcTag)
+            || typeof input.entrypoint !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,239}$/u.test(input.entrypoint)
+            || input.entrypoint.includes("//") || input.entrypoint.split("/").some((part) => part === "." || part === "..")
+            || typeof input.networkAlias !== "string" || !/^[a-z][a-z0-9-]{0,62}$/u.test(input.networkAlias)
+            || !input.platform || (input.platform.architecture !== "amd64" && input.platform.architecture !== "arm64")
+            || input.platform.os !== "linux")
+            return fail();
+        const preparedOperationHandle = parseOpaqueTargetHandle(input.preparedOperationHandle);
+        return JSON.stringify({
+            ...base, archive_digest: input.archiveDigest, base_image_config_digest: input.baseImageConfigDigest,
+            build_policy_digest: input.buildPolicyDigest, bundle_digest: input.bundleDigest, config_id: input.configId,
+            daemon_epoch: input.daemonEpoch, entrypoint: input.entrypoint, gc_tag: input.gcTag,
+            identity_kind: input.identityKind,
+            launcher_digest: input.launcherDigest, network_alias: input.networkAlias,
+            platform: input.platform, platform_digest: input.platformDigest,
+            prepared_operation_handle: preparedOperationHandle,
+            prepared_request_digest: input.preparedRequestDigest,
+            version: "spawnfile.target-artifact.identity.v3"
+        });
+    }
+    if (input.identityKind !== undefined && input.identityKind !== "oci_image_manifest")
+        return fail();
+    const [mapping] = parseDockerArtifactMappings([{
+            artifact_manifest_digest: input.artifactManifestDigest,
+            image_digest: input.imageDigest,
+            image_reference: input.imageReference
+        }]);
+    if (!mapping)
+        return fail();
+    return JSON.stringify({
+        ...base, artifact_manifest_digest: mapping.artifact_manifest_digest,
+        identity_kind: "oci_image_manifest", image_digest: mapping.image_digest,
+        image_reference: mapping.image_reference,
+        version: "spawnfile.target-artifact.identity.v2"
+    });
+};
+const parseBinding = (text) => {
+    try {
+        const value = JSON.parse(text);
+        if (value.version !== "spawnfile.target-artifact.identity.v2"
+            && value.version !== "spawnfile.target-artifact.identity.v3")
+            return fail();
+        let parsed;
+        if (value.identity_kind === "oci_image_manifest"
+            && Object.keys(value).sort().join("\0") === "artifact_manifest_digest\0identity_kind\0image_digest\0image_reference\0operation_handle\0request_digest\0result_handle\0selected_target_handle\0version") {
+            const oci = {
+                artifactManifestDigest: value.artifact_manifest_digest,
+                imageDigest: value.image_digest, imageReference: value.image_reference,
+                operationHandle: parseOpaqueTargetHandle(value.operation_handle), requestDigest: value.request_digest,
+                resultHandle: parseOpaqueTargetHandle(value.result_handle), selectedTargetHandle: parseOpaqueTargetHandle(value.selected_target_handle)
+            };
+            Object.defineProperty(oci, "identityKind", { enumerable: false, value: "oci_image_manifest" });
+            parsed = Object.freeze(oci);
+        }
+        else if (value.version === "spawnfile.target-artifact.identity.v3"
+            && value.identity_kind === "docker_image_config_digest"
+            && Object.keys(value).sort().join("\0") === "archive_digest\0artifact_manifest_digest\0base_image_config_digest\0build_policy_digest\0bundle_digest\0config_id\0daemon_epoch\0entrypoint\0gc_tag\0identity_kind\0launcher_digest\0network_alias\0operation_handle\0platform\0platform_digest\0prepared_operation_handle\0prepared_request_digest\0request_digest\0result_handle\0selected_target_handle\0version") {
+            parsed = Object.freeze({
+                archiveDigest: value.archive_digest, artifactManifestDigest: value.artifact_manifest_digest,
+                baseImageConfigDigest: value.base_image_config_digest,
+                buildPolicyDigest: value.build_policy_digest, bundleDigest: value.bundle_digest,
+                configId: value.config_id, daemonEpoch: value.daemon_epoch,
+                entrypoint: value.entrypoint, gcTag: value.gc_tag, identityKind: "docker_image_config_digest",
+                launcherDigest: value.launcher_digest, networkAlias: value.network_alias,
+                operationHandle: parseOpaqueTargetHandle(value.operation_handle), requestDigest: value.request_digest,
+                preparedOperationHandle: parseOpaqueTargetHandle(value.prepared_operation_handle),
+                preparedRequestDigest: value.prepared_request_digest,
+                resultHandle: parseOpaqueTargetHandle(value.result_handle), selectedTargetHandle: parseOpaqueTargetHandle(value.selected_target_handle),
+                platform: value.platform, platformDigest: value.platform_digest
+            });
+        }
+        else
+            return fail();
+        if (bindingBytes(parsed) !== text)
+            return fail();
+        return parsed;
+    }
+    catch {
+        return fail();
+    }
+};
+const OWNER = process.getuid?.() ?? -1;
+const checkIdentityRoot = async (raw) => {
+    if (typeof raw !== "string" || raw.length < 1 || bytes(raw) > 4_096)
+        return fail();
+    const root = path.resolve(raw);
+    const parsed = path.parse(root);
+    /* Never treat the platform filesystem root as a private Spawnfile boundary. */
+    if (root === parsed.root)
+        return fail();
+    let current = parsed.root;
+    let createdRoot = false;
+    for (const part of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        let stats;
+        let created = false;
+        try {
+            stats = await lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return fail();
+            try {
+                await mkdir(current, { mode: 0o700 });
+                created = true;
+            }
+            catch (mkdirError) {
+                if (mkdirError.code !== "EEXIST")
+                    return fail();
+            }
+            stats = await lstat(current).catch(fail);
+        }
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            return fail();
+        if (current === root) {
+            createdRoot = created;
+            if (!createdRoot && (stats.uid !== OWNER || (stats.mode & 0o777) !== 0o700))
+                return fail();
+        }
+    }
+    if (createdRoot)
+        await chmod(root, 0o700).catch(fail);
+    const final = await lstat(root).catch(fail);
+    if (!final.isDirectory() || final.isSymbolicLink() || final.uid !== OWNER || (final.mode & 0o777) !== 0o700)
+        return fail();
+    return root;
+};
+const secureIdentity = (stats) => {
+    if (!stats.isFile() || stats.uid !== OWNER || stats.size > MAX_IDENTITY_BYTES || (stats.mode & 0o777) !== 0o600)
+        fail();
+};
+const openSecureIdentity = async (filePath) => {
+    let handle;
+    try {
+        handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        return fail();
+    }
+    try {
+        const current = await handle.stat();
+        secureIdentity(current);
+        return { bytes: await handle.readFile({ encoding: "utf8" }), dev: current.dev, ino: current.ino, nlink: current.nlink };
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+const openIdentity = async (filePath, links) => {
+    const value = await openSecureIdentity(filePath);
+    if (value === null || value.nlink === 0)
+        return null;
+    if (!links.includes(value.nlink))
+        return fail();
+    return value;
+};
+const syncDirectory = async (directory) => {
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const retryTurn = (attempt) => new Promise((resolve) => {
+    if ((attempt + 1) % 8 === 0)
+        setTimeout(resolve, 1);
+    else
+        setImmediate(resolve);
+});
+/* One canonical immutable record exists for one exact operation/request pair. */
+const keyPath = (root, operationHandle, requestDigest) => path.join(root, `${digest("identity-operation", `${operationHandle}\0${requestDigest}`)}.identity.json`);
+const pendingPath = (file) => path.join(path.dirname(file), `.${path.basename(file)}.pending`);
+const sameInode = (left, right) => left.dev === right.dev && left.ino === right.ino;
+/*
+ * The two names below live in a root owned exclusively by the Spawnfile uid and
+ * checked mode-0700 on every store construction.  We defend each operation
+ * boundary against malformed, linked, wrong-mode, wrong-owner, or symlinked
+ * records.  A malicious concurrent process with that same uid is out of scope:
+ * it already controls Spawnfile state and code.  That narrow trust boundary is
+ * what makes unlink-after-same-inode-proof safe here.
+ */
+const reconcilePublishedIdentity = async (root, file, expected) => {
+    for (let attempt = 0; attempt < IDENTITY_RETRY_ATTEMPTS; attempt += 1) {
+        const final = await openIdentity(file, [1, 2]);
+        if (!final || final.bytes !== expected)
+            return fail();
+        const pending = await openIdentity(pendingPath(file), [1, 2]);
+        if (final.nlink === 1) {
+            if (pending === null)
+                return;
+            if (pending.bytes !== expected) {
+                if (pending.nlink === 1 && expected.startsWith(pending.bytes)) {
+                    await retryTurn(attempt);
+                    continue;
+                }
+                return fail();
+            }
+            if (pending.nlink !== 1) {
+                await retryTurn(attempt);
+                continue;
+            }
+        }
+        else {
+            /* A concurrent unlink can make a just-read two-link final become one-link. */
+            if (pending === null || pending.nlink !== 2) {
+                await retryTurn(attempt);
+                continue;
+            }
+            if (!sameInode(final, pending) || pending.bytes !== expected)
+                return fail();
+        }
+        /* Safe only under the trusted-root boundary documented above. */
+        await unlink(pendingPath(file)).catch((error) => { if (error.code !== "ENOENT")
+            fail(); });
+        await syncDirectory(root);
+        const repaired = await openIdentity(file, [1]);
+        if (!repaired || repaired.bytes !== expected)
+            return fail();
+        if (await openIdentity(pendingPath(file), [1]) === null)
+            return;
+        await retryTurn(attempt);
+    }
+    return fail();
+};
+const readPublishedIdentity = async (root, file) => {
+    const final = await openIdentity(file, [1, 2]);
+    if (final === null)
+        return null;
+    await reconcilePublishedIdentity(root, file, final.bytes);
+    return final.bytes;
+};
+const exactPublishedIdentity = async (root, file, content) => {
+    const prior = await readPublishedIdentity(root, file);
+    if (prior === null)
+        return false;
+    if (prior !== content)
+        return fail();
+    return true;
+};
+const publishIdentity = async (root, file, content, options) => {
+    const pending = pendingPath(file);
+    for (let attempt = 0; attempt < IDENTITY_RETRY_ATTEMPTS; attempt += 1) {
+        if (await exactPublishedIdentity(root, file, content))
+            return;
+        let created = false;
+        let handle;
+        try {
+            handle = await open(pending, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            created = true;
+            await handle.chmod(0o600);
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await syncDirectory(root);
+        }
+        catch (error) {
+            if (handle)
+                await handle.close().catch(() => undefined);
+            if (error.code !== "EEXIST")
+                return fail();
+            await options?.afterPendingExists?.();
+        }
+        if (created)
+            await options?.beforePublish?.();
+        const pendingRecord = await openIdentity(pending, [1, 2]);
+        if (pendingRecord === null) {
+            if (await exactPublishedIdentity(root, file, content))
+                return;
+            await retryTurn(attempt);
+            continue;
+        }
+        if (pendingRecord.bytes !== content) {
+            if (pendingRecord.nlink === 1 && content.startsWith(pendingRecord.bytes)) {
+                await retryTurn(attempt);
+                continue;
+            }
+            return fail();
+        }
+        if (pendingRecord.nlink === 2) {
+            if (await exactPublishedIdentity(root, file, content))
+                return;
+            await retryTurn(attempt);
+            continue;
+        }
+        if (created)
+            await options?.beforeLink?.();
+        try {
+            await link(pending, file);
+            await syncDirectory(root);
+            await options?.afterLinkBeforePendingUnlink?.();
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST" && code !== "ENOENT")
+                return fail();
+        }
+        /* EEXIST may mean another exact binder linked first or a final vanished; retry only after an exact proof. */
+        if (await exactPublishedIdentity(root, file, content))
+            return;
+        await retryTurn(attempt);
+    }
+    return fail();
+};
+class FileDockerArtifactIdentityStore {
+    #root;
+    #options;
+    constructor(root, options) { this.#root = root; this.#options = options; }
+    async bind(input) {
+        try {
+            const binding = parseBinding(bindingBytes(input));
+            const content = bindingBytes(binding);
+            const operation = keyPath(this.#root, binding.operationHandle, binding.requestDigest);
+            await publishIdentity(this.#root, operation, content, this.#options);
+        }
+        catch {
+            return fail();
+        }
+    }
+    async resolveOperation(rawOperation, rawRequest) {
+        try {
+            const operationHandle = parseOpaqueTargetHandle(rawOperation);
+            if (!isDigest(rawRequest))
+                return fail();
+            const text = await readPublishedIdentity(this.#root, keyPath(this.#root, operationHandle, rawRequest));
+            if (text === null)
+                return null;
+            const binding = parseBinding(text);
+            if (binding.operationHandle !== operationHandle || binding.requestDigest !== rawRequest)
+                return fail();
+            return binding;
+        }
+        catch {
+            return fail();
+        }
+    }
+}
+export const initializeDockerArtifactIdentityStore = async (root, options) => new FileDockerArtifactIdentityStore(await checkIdentityRoot(root), options);
+export { createDockerArtifactSpec, createDockerConfigArtifactSpec, executeDockerArtifact, isExpectedDockerArtifact } from "./dockerArtifactInspection.js";

package/dist/target/dockerBaseImage.d.ts

@@ -0,0 +1,2 @@
+/** Strict portable image-reference grammar shared by target resolution and local helper setup. */
+export declare const parseDockerBaseImageReference: (raw: unknown) => string | null;

package/dist/target/dockerBaseImage.js

@@ -0,0 +1,11 @@
+import { parseImageReference } from "../distribution/index.js";
+const CONFIG_DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const MAX_REFERENCE_BYTES = 512;
+/** Strict portable image-reference grammar shared by target resolution and local helper setup. */
+export const parseDockerBaseImageReference = (raw) => {
+    if (typeof raw !== "string" || raw !== raw.trim() || raw.includes("\0")
+        || Buffer.byteLength(raw, "utf8") > MAX_REFERENCE_BYTES || CONFIG_DIGEST.test(raw)
+        || parseImageReference(raw) === null)
+        return null;
+    return raw;
+};