spawnfile 0.1.13 → 0.1.17

package/dist/target/dockerSecrets.js

@@ -0,0 +1,249 @@
+import { Buffer } from "node:buffer";
+import { SpawnfileError } from "../shared/index.js";
+import { parseOpaqueTargetHandle, parseTargetResourceRequest } from "./contracts.js";
+import { selectTarget } from "./dockerTarget.js";
+import { createTargetReceiptDigest } from "./handles.js";
+import { createTargetSecretSourceAuthorization, parseTargetSecretSourceAuthorization } from "./dockerSecretsAuthority.js";
+import { DOCKER_SECRET_ERROR, DockerSecretProviderError, createDockerSecretArchive, createExistingDockerSecretSpec, createPreparedDockerSecretSpec } from "./dockerSecretsProvider.js";
+import { cleanupExactDockerSecretBindings, executeSecretLifecycleCommand, inspectExactSecretVolume, inspectExactSecretWriter } from "./dockerSecretsLifecycle.js";
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => { throw new SpawnfileError("runtime_error", DOCKER_SECRET_ERROR); };
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const validOptions = (raw) => {
+    if (!raw.authorityStore || typeof raw.authorityStore.bind !== "function"
+        || typeof raw.context !== "string" || !CONTEXT_PATTERN.test(raw.context)
+        || typeof raw.executor !== "function" || !raw.journal || !raw.resolver || typeof raw.resolver.resolve !== "function"
+        || typeof raw.timeoutMs !== "undefined" && (typeof raw.timeoutMs !== "number" || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs < 1 || raw.timeoutMs > 120_000))
+        fail();
+    return {
+        authorityStore: raw.authorityStore, context: raw.context, executor: raw.executor, journal: raw.journal,
+        resolver: raw.resolver, signal: raw.signal, timeoutMs: (raw.timeoutMs ?? 30_000)
+    };
+};
+const parseSecretRequest = (raw) => {
+    const request = parseTargetResourceRequest(raw);
+    if (request.operation !== "prepare_secret_bindings" && request.operation !== "revoke_secret_bindings")
+        fail();
+    if (request.operation === "prepare_secret_bindings") {
+        const keys = request.bindings.map((binding) => `${binding.scope}\0${binding.name}`);
+        const sources = request.bindings.map((binding) => binding.source_handle);
+        if (new Set(keys).size !== keys.length || new Set(sources).size !== sources.length)
+            fail();
+    }
+    return request;
+};
+const command = async (args, options, input) => executeSecretLifecycleCommand(args, options, input);
+const selectedContextMatches = async (request, options) => {
+    const selected = await selectTarget({
+        context: options.context,
+        dockerCommand: "docker",
+        execFile: async (_file, args, commandOptions) => command(args, { ...options, 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 inspectVolume = (spec, options) => inspectExactSecretVolume(spec, options);
+const createVolume = async (spec, options) => {
+    const labels = Object.entries(spec.labels).flatMap(([key, value]) => ["--label", `${key}=${value}`]);
+    const result = await command(["--context", options.context, "volume", "create", "--driver", "local", ...labels, spec.volumeName], options);
+    if (result.stderr !== "" || result.stdout.trim() !== spec.volumeName || await inspectVolume(spec, options) !== "present")
+        fail();
+};
+const inspectWriter = (spec, options) => inspectExactSecretWriter(spec, options);
+const removePrepareWriter = async (spec, options) => {
+    try {
+        const result = await command(["--context", options.context, "container", "rm", "--force", spec.writerName], options);
+        if (result.stderr !== "" || result.stdout.trim() !== spec.writerName)
+            fail();
+    }
+    catch (error) {
+        if (!(error instanceof DockerSecretProviderError) || error.kind !== "not_found")
+            throw error;
+    }
+};
+const waitWriter = async (spec, options) => {
+    try {
+        const result = await command(["--context", options.context, "container", "wait", spec.writerName], options);
+        if (result.stderr !== "" || !/^[0-9]{1,3}\n?$/u.test(result.stdout))
+            fail();
+        return Number(result.stdout.trim()) === 0;
+    }
+    catch (error) {
+        if (error instanceof DockerSecretProviderError && error.kind === "not_found")
+            return false;
+        throw error;
+    }
+};
+const recoverWriter = async (spec, options) => {
+    const state = await inspectWriter(spec, options);
+    if (state === "absent")
+        return false;
+    if (state.status === "running" && await waitWriter(spec, options))
+        return true;
+    await removePrepareWriter(spec, options);
+    return false;
+};
+const runWriter = async (spec, archive, options) => {
+    try {
+        await command(["--context", options.context, ...spec.writerRunArgs], options, { requireSilent: true, stdin: archive });
+    }
+    catch (error) {
+        if (!(error instanceof DockerSecretProviderError) || error.kind !== "collision")
+            throw error;
+        if (await recoverWriter(spec, options))
+            return;
+        await command(["--context", options.context, ...spec.writerRunArgs], options, { requireSilent: true, stdin: archive });
+    }
+};
+const exactResolution = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)
+        || Object.getPrototypeOf(raw) !== Object.prototype)
+        return fail();
+    const keys = Reflect.ownKeys(raw);
+    if (keys.length !== 3
+        || !["authorization", "sourceVersionHandle", "value"].every((key) => keys.includes(key)))
+        return fail();
+    const record = raw;
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(raw, key);
+        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+            return fail();
+    }
+    if (!(record.value instanceof Uint8Array))
+        return fail();
+    return {
+        authorization: parseTargetSecretSourceAuthorization(record.authorization),
+        sourceVersionHandle: parseOpaqueTargetHandle(record.sourceVersionHandle),
+        value: record.value
+    };
+};
+const resolveArchive = async (request, claim, options) => {
+    const resolved = [];
+    const versions = [];
+    try {
+        const sorted = [...request.bindings].sort((left, right) => left.scope.localeCompare(right.scope) || left.name.localeCompare(right.name));
+        for (const binding of sorted) {
+            let source;
+            try {
+                const authorization = createTargetSecretSourceAuthorization({
+                    descriptorDigest: request.descriptor_digest, name: binding.name,
+                    operationHandle: claim.operationHandle, requestDigest: claim.requestDigest, runId: request.run_id,
+                    scope: binding.scope, selectedTarget: request.selected_target, sourceHandle: binding.source_handle
+                });
+                const rawResolution = await options.resolver.resolve({ authorization, signal: options.signal });
+                if (rawResolution && typeof rawResolution === "object") {
+                    const value = Object.getOwnPropertyDescriptor(rawResolution, "value");
+                    if (value && "value" in value && value.value instanceof Uint8Array)
+                        source = value.value;
+                }
+                const resolution = exactResolution(rawResolution);
+                if (!same(resolution.authorization, authorization))
+                    fail();
+                source = resolution.value;
+                versions.push({ authorization, sourceVersionHandle: resolution.sourceVersionHandle });
+                resolved.push({ name: binding.name, scope: binding.scope, value: Buffer.from(source) });
+            }
+            finally {
+                if (source instanceof Uint8Array)
+                    source.fill(0);
+            }
+        }
+        await options.authorityStore.bind(versions);
+        return createDockerSecretArchive(resolved);
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        for (const binding of resolved)
+            binding.value.fill(0);
+    }
+};
+const receiptFor = (input) => {
+    const labels = Object.entries(input.spec.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: input.request.expected_revision + 1,
+        run_id: input.request.run_id, selected_target: input.request.selected_target,
+        version: "spawnfile.target-resource.receipt.v1"
+    };
+    return { ...raw, receipt_digest: createTargetReceiptDigest(raw) };
+};
+class DockerSecretOperationsImpl {
+    #options;
+    #live = new Map();
+    constructor(options) { this.#options = options; }
+    execute(raw) {
+        let request;
+        try {
+            request = parseSecretRequest(raw);
+        }
+        catch {
+            return Promise.reject(new SpawnfileError("runtime_error", DOCKER_SECRET_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_SECRET_ERROR));
+        const promise = this.executeOwner(request);
+        this.#live.set(request.idempotency_key, { promise, request });
+        void promise.finally(() => { if (this.#live.get(request.idempotency_key)?.promise === promise)
+            this.#live.delete(request.idempotency_key); }).catch(() => undefined);
+        return promise;
+    }
+    async executeOwner(request) {
+        try {
+            const reservation = await this.#options.journal.reserve(request);
+            if (reservation.kind === "replay")
+                return { receipt: reservation.receipt, receiptBytes: reservation.receiptBytes };
+            await selectedContextMatches(request, this.#options);
+            if (request.operation === "prepare_secret_bindings")
+                return await this.prepare(request, reservation, reservation.claim);
+            return await this.revoke(request, reservation.claim);
+        }
+        catch {
+            return fail();
+        }
+    }
+    async prepare(request, reservation, claim) {
+        const spec = createPreparedDockerSecretSpec({ operationHandle: claim.operationHandle, requestDigest: claim.requestDigest, runId: request.run_id, selectedTargetHandle: request.selected_target.handle });
+        const archive = await resolveArchive(request, claim, this.#options);
+        try {
+            const volumeState = await inspectVolume(spec, this.#options);
+            const writerState = await inspectWriter(spec, this.#options);
+            if (reservation.kind === "owner" && writerState !== "absent")
+                fail();
+            if (writerState !== "absent") {
+                if (volumeState !== "present")
+                    fail();
+                if (await recoverWriter(spec, this.#options)) {
+                    const receipt = receiptFor({ claim, request, resultHandle: spec.resultHandle, spec });
+                    return await this.#options.journal.complete(claim, receipt);
+                }
+            }
+            if (volumeState === "absent")
+                await createVolume(spec, this.#options);
+            await runWriter(spec, archive, this.#options);
+        }
+        finally {
+            archive.fill(0);
+        }
+        const receipt = receiptFor({ claim, request, resultHandle: spec.resultHandle, spec });
+        return await this.#options.journal.complete(claim, receipt);
+    }
+    async revoke(request, claim) {
+        const spec = createExistingDockerSecretSpec({ bindingsHandle: request.secret_bindings_handle, runId: request.run_id, selectedTargetHandle: request.selected_target.handle });
+        await cleanupExactDockerSecretBindings({
+            bindingsHandle: request.secret_bindings_handle,
+            runId: request.run_id,
+            selectedTargetHandle: request.selected_target.handle
+        }, this.#options);
+        const receipt = receiptFor({ claim, request, resultHandle: null, spec });
+        return await this.#options.journal.complete(claim, receipt);
+    }
+}
+export const createDockerSecretOperations = (options) => new DockerSecretOperationsImpl(validOptions(options));
+export const createDockerSecrets = createDockerSecretOperations;

package/dist/target/dockerSecretsAuthority.d.ts

@@ -0,0 +1,26 @@
+import { type OpaqueTargetHandle } from "./contracts.js";
+export declare const TARGET_SECRET_SOURCE_AUTHORIZATION_VERSION: "spawnfile.target-secret-source.authorization.v1";
+export interface TargetSecretSourceAuthorization {
+    readonly descriptorDigest: string;
+    readonly name: string;
+    readonly operationHandle: OpaqueTargetHandle;
+    readonly requestDigest: string;
+    readonly runId: string;
+    readonly scope: string;
+    readonly selectedTarget: {
+        readonly fingerprint: string;
+        readonly handle: OpaqueTargetHandle;
+    };
+    readonly sourceHandle: OpaqueTargetHandle;
+    readonly version: typeof TARGET_SECRET_SOURCE_AUTHORIZATION_VERSION;
+}
+export interface TargetSecretVersionBinding {
+    readonly authorization: TargetSecretSourceAuthorization;
+    readonly sourceVersionHandle: OpaqueTargetHandle;
+}
+export interface TargetSecretVersionAuthorityStore {
+    bind(bindings: readonly TargetSecretVersionBinding[]): Promise<void>;
+}
+export declare const parseTargetSecretSourceAuthorization: (raw: unknown) => TargetSecretSourceAuthorization;
+export declare const createTargetSecretSourceAuthorization: (raw: Omit<TargetSecretSourceAuthorization, "version">) => TargetSecretSourceAuthorization;
+export declare const initializeTargetSecretVersionAuthorityStore: (root: unknown) => Promise<TargetSecretVersionAuthorityStore>;

package/dist/target/dockerSecretsAuthority.js

@@ -0,0 +1,216 @@
+import { Buffer } from "node:buffer";
+import { createHash, randomUUID } 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, parseRunId } from "./contracts.js";
+import { DOCKER_SECRET_ERROR } from "./dockerSecretsProvider.js";
+export const TARGET_SECRET_SOURCE_AUTHORIZATION_VERSION = "spawnfile.target-secret-source.authorization.v1";
+const TARGET_SECRET_VERSION_STORE = "spawnfile.target-secret-source.private-version-store.v1";
+const TARGET_SECRET_SOURCE_BINDING = "spawnfile.target-secret-source.private-binding.v1";
+const MAX_RECORD_BYTES = 32_768;
+const IDENTIFIER_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{32}$/u;
+const fail = () => { throw new Error(DOCKER_SECRET_ERROR); };
+const bytes = (value) => Buffer.byteLength(value, "utf8");
+const digest = (domain, value) => createHash("sha256")
+    .update(`spawnfile.target-secret-authority.${domain}.v1\0`, "utf8").update(value, "utf8").digest("hex");
+const exactKeys = (value, keys) => {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+};
+export const parseTargetSecretSourceAuthorization = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return fail();
+    const value = raw;
+    if (!exactKeys(value, [
+        "descriptorDigest", "name", "operationHandle", "requestDigest", "runId", "scope",
+        "selectedTarget", "sourceHandle", "version"
+    ]) || value.version !== TARGET_SECRET_SOURCE_AUTHORIZATION_VERSION
+        || typeof value.descriptorDigest !== "string" || !DIGEST_PATTERN.test(value.descriptorDigest)
+        || typeof value.requestDigest !== "string" || !DIGEST_PATTERN.test(value.requestDigest)
+        || typeof value.name !== "string" || !IDENTIFIER_PATTERN.test(value.name)
+        || typeof value.scope !== "string" || !IDENTIFIER_PATTERN.test(value.scope))
+        return fail();
+    const selected = value.selectedTarget;
+    if (!selected || typeof selected !== "object" || Array.isArray(selected)
+        || !exactKeys(selected, ["fingerprint", "handle"]))
+        return fail();
+    const target = selected;
+    if (typeof target.fingerprint !== "string" || !FINGERPRINT_PATTERN.test(target.fingerprint))
+        return fail();
+    return Object.freeze({
+        descriptorDigest: value.descriptorDigest, name: value.name,
+        operationHandle: parseOpaqueTargetHandle(value.operationHandle), requestDigest: value.requestDigest,
+        runId: parseRunId(value.runId), scope: value.scope,
+        selectedTarget: Object.freeze({ fingerprint: target.fingerprint, handle: parseOpaqueTargetHandle(target.handle) }),
+        sourceHandle: parseOpaqueTargetHandle(value.sourceHandle), version: TARGET_SECRET_SOURCE_AUTHORIZATION_VERSION
+    });
+};
+export const createTargetSecretSourceAuthorization = (raw) => {
+    assertOrdinaryJsonGraph(raw);
+    return parseTargetSecretSourceAuthorization({ ...raw, version: TARGET_SECRET_SOURCE_AUTHORIZATION_VERSION });
+};
+const bindingBytes = (raw) => {
+    if (!Array.isArray(raw) || raw.length < 1 || raw.length > 32)
+        return fail();
+    const bindings = raw.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            return fail();
+        const authorization = parseTargetSecretSourceAuthorization(entry.authorization);
+        return Object.freeze({ authorization, sourceVersionHandle: parseOpaqueTargetHandle(entry.sourceVersionHandle) });
+    }).sort((left, right) => left.authorization.scope.localeCompare(right.authorization.scope)
+        || left.authorization.name.localeCompare(right.authorization.name));
+    const first = bindings[0].authorization;
+    const destinations = new Set();
+    const sources = new Set();
+    for (const binding of bindings) {
+        const authorization = binding.authorization;
+        if (authorization.operationHandle !== first.operationHandle || authorization.requestDigest !== first.requestDigest
+            || authorization.runId !== first.runId || authorization.descriptorDigest !== first.descriptorDigest
+            || authorization.selectedTarget.fingerprint !== first.selectedTarget.fingerprint
+            || authorization.selectedTarget.handle !== first.selectedTarget.handle)
+            return fail();
+        const destination = `${authorization.scope}\0${authorization.name}`;
+        if (destinations.has(destination) || sources.has(authorization.sourceHandle))
+            return fail();
+        destinations.add(destination);
+        sources.add(authorization.sourceHandle);
+    }
+    const content = JSON.stringify({ bindings, version: TARGET_SECRET_VERSION_STORE });
+    if (bytes(content) > MAX_RECORD_BYTES)
+        return fail();
+    const sourcesRecords = bindings.map((binding) => {
+        const sourceContent = JSON.stringify({ ...binding, version: TARGET_SECRET_SOURCE_BINDING });
+        if (bytes(sourceContent) > MAX_RECORD_BYTES)
+            return fail();
+        return { content: sourceContent, key: digest("source-file", binding.authorization.sourceHandle) };
+    });
+    return {
+        claim: { content, key: digest("claim-file", `${first.operationHandle}\0${first.requestDigest}`) },
+        sources: sourcesRecords
+    };
+};
+const checkRoot = 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);
+    let current = parsed.root;
+    for (const part of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        let stats;
+        try {
+            stats = await lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return fail();
+            await mkdir(current, { mode: 0o700 }).catch((mkdirError) => {
+                if (mkdirError.code !== "EEXIST")
+                    return fail();
+            });
+            stats = await lstat(current).catch(fail);
+        }
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            return fail();
+    }
+    await chmod(root, 0o700).catch(fail);
+    return root;
+};
+const readRecord = async (filePath) => {
+    let stats;
+    try {
+        stats = await lstat(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        return fail();
+    }
+    if (!stats.isFile() || stats.isSymbolicLink() || stats.size > MAX_RECORD_BYTES || (stats.mode & 0o077) !== 0)
+        return fail();
+    let handle;
+    try {
+        handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return fail();
+    }
+    try {
+        const current = await handle.stat();
+        if (!current.isFile() || current.size > MAX_RECORD_BYTES || (current.mode & 0o077) !== 0)
+            return fail();
+        return await handle.readFile({ encoding: "utf8" });
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+const syncDirectory = async (directory) => {
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+class FileTargetSecretVersionAuthorityStore {
+    #root;
+    constructor(root) { this.#root = root; }
+    async bindRecord(record) {
+        const finalPath = path.join(this.#root, `${record.key}.json`);
+        const existing = await readRecord(finalPath);
+        if (existing !== null) {
+            if (existing !== record.content)
+                return fail();
+            return;
+        }
+        const temporaryPath = path.join(this.#root, `.${record.key}.${process.pid}.${randomUUID()}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporaryPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            await handle.chmod(0o600);
+            await handle.writeFile(record.content, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            try {
+                await link(temporaryPath, finalPath);
+                await syncDirectory(this.#root);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        finally {
+            if (handle)
+                await handle.close().catch(() => undefined);
+            await unlink(temporaryPath).catch((error) => { if (error.code !== "ENOENT")
+                throw error; });
+            await syncDirectory(this.#root);
+        }
+        if (await readRecord(finalPath) !== record.content)
+            return fail();
+    }
+    async bind(bindings) {
+        try {
+            const records = bindingBytes(bindings);
+            for (const source of records.sources)
+                await this.bindRecord(source);
+            await this.bindRecord(records.claim);
+        }
+        catch {
+            return fail();
+        }
+    }
+}
+export const initializeTargetSecretVersionAuthorityStore = async (root) => new FileTargetSecretVersionAuthorityStore(await checkRoot(root));

package/dist/target/dockerSecretsLifecycle.d.ts

@@ -0,0 +1,25 @@
+import { type OpaqueTargetHandle } from "./contracts.js";
+import { type DockerSecretExecutor, type DockerSecretSpec, type DockerSecretWriterState } from "./dockerSecretsProvider.js";
+export interface DockerSecretLifecycleOptions {
+    readonly context: string;
+    readonly executor: DockerSecretExecutor;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+}
+export interface DockerSecretCleanupAuthority {
+    readonly bindingsHandle: OpaqueTargetHandle;
+    readonly runId: string;
+    readonly selectedTargetHandle: OpaqueTargetHandle;
+}
+export declare const validateDockerSecretLifecycleOptions: (raw: DockerSecretLifecycleOptions) => DockerSecretLifecycleOptions;
+export declare const executeSecretLifecycleCommand: (args: string[], options: DockerSecretLifecycleOptions, input?: {
+    readonly requireSilent?: boolean;
+    readonly stdin?: Uint8Array;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export declare const inspectExactSecretVolume: (spec: DockerSecretSpec, options: DockerSecretLifecycleOptions) => Promise<"absent" | "present">;
+export declare const inspectExactSecretWriter: (spec: DockerSecretSpec, options: DockerSecretLifecycleOptions) => Promise<"absent" | DockerSecretWriterState>;
+/** Journal-free exact cleanup for one already-authorized secret binding. */
+export declare const cleanupExactDockerSecretBindings: (rawAuthority: unknown, rawOptions: DockerSecretLifecycleOptions) => Promise<void>;

package/dist/target/dockerSecretsLifecycle.js

@@ -0,0 +1,133 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseOpaqueTargetHandle, parseRunId } from "./contracts.js";
+import { DOCKER_SECRET_ERROR, DockerSecretProviderError, createExistingDockerSecretSpec, executeDockerSecretCommand, isExpectedDockerSecretVolume, parseExpectedDockerSecretWriter } from "./dockerSecretsProvider.js";
+const CONTEXT_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/u;
+const fail = () => { throw new SpawnfileError("runtime_error", DOCKER_SECRET_ERROR); };
+const exactOrdinary = (raw, keys) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)
+        || Object.getPrototypeOf(raw) !== Object.prototype)
+        return false;
+    const actual = Reflect.ownKeys(raw);
+    if (actual.length !== keys.length || actual.some((key) => typeof key !== "string" || !keys.includes(key)))
+        return false;
+    return actual.every((key) => {
+        const descriptor = Object.getOwnPropertyDescriptor(raw, key);
+        return descriptor !== undefined && "value" in descriptor && descriptor.enumerable;
+    });
+};
+const parseAuthority = (raw) => {
+    if (!exactOrdinary(raw, ["bindingsHandle", "runId", "selectedTargetHandle"]))
+        return fail();
+    return {
+        bindingsHandle: parseOpaqueTargetHandle(raw.bindingsHandle),
+        runId: parseRunId(raw.runId),
+        selectedTargetHandle: parseOpaqueTargetHandle(raw.selectedTargetHandle)
+    };
+};
+export const validateDockerSecretLifecycleOptions = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)
+        || typeof raw.context !== "string" || !CONTEXT_PATTERN.test(raw.context)
+        || typeof raw.executor !== "function" || !Number.isSafeInteger(raw.timeoutMs)
+        || raw.timeoutMs < 1 || raw.timeoutMs > 120_000
+        || raw.signal !== undefined && !(raw.signal instanceof AbortSignal))
+        return fail();
+    return raw;
+};
+export const executeSecretLifecycleCommand = (args, options, input) => executeDockerSecretCommand({
+    args,
+    executor: options.executor,
+    requireSilent: input?.requireSilent,
+    signal: options.signal,
+    stdin: input?.stdin,
+    timeoutMs: options.timeoutMs
+});
+export const inspectExactSecretVolume = async (spec, options) => {
+    try {
+        const result = await executeSecretLifecycleCommand([
+            "--context", options.context, "volume", "inspect", "--format",
+            spec.volumeInspectionFormat, spec.volumeName
+        ], options);
+        if (result.stderr !== "" || !isExpectedDockerSecretVolume(result.stdout, spec))
+            return fail();
+        return "present";
+    }
+    catch (error) {
+        if (error instanceof DockerSecretProviderError && error.kind === "not_found")
+            return "absent";
+        throw error;
+    }
+};
+export const inspectExactSecretWriter = async (spec, options) => {
+    try {
+        const result = await executeSecretLifecycleCommand([
+            "--context", options.context, "container", "inspect", "--format",
+            spec.writerInspectionFormat, spec.writerName
+        ], options);
+        const state = parseExpectedDockerSecretWriter(result.stdout, spec);
+        if (result.stderr !== "" || state === null)
+            return fail();
+        return state;
+    }
+    catch (error) {
+        if (error instanceof DockerSecretProviderError && error.kind === "not_found")
+            return "absent";
+        throw error;
+    }
+};
+const acknowledged = (result, name) => {
+    if (result.stderr !== "" || result.stdout !== `${name}\n`)
+        fail();
+};
+const mutateAndReconcile = async (args, name, proveAbsent, options) => {
+    let result;
+    let error;
+    try {
+        result = await executeSecretLifecycleCommand(args, options);
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (result)
+        acknowledged(result, name);
+    if (!await proveAbsent()) {
+        if (error)
+            throw error;
+        fail();
+    }
+};
+/** Journal-free exact cleanup for one already-authorized secret binding. */
+export const cleanupExactDockerSecretBindings = async (rawAuthority, rawOptions) => {
+    try {
+        // Parse every caller-controlled value before the first provider call.
+        const authority = parseAuthority(rawAuthority);
+        const options = validateDockerSecretLifecycleOptions(rawOptions);
+        const spec = createExistingDockerSecretSpec(authority);
+        const writer = await inspectExactSecretWriter(spec, options);
+        const initialVolume = await inspectExactSecretVolume(spec, options);
+        if (writer !== "absent") {
+            if (writer.status === "running" || writer.status === "paused" || writer.status === "restarting") {
+                await mutateAndReconcile([
+                    "--context", options.context, "container", "stop",
+                    "--timeout", "10", spec.writerName
+                ], spec.writerName, async () => {
+                    const state = await inspectExactSecretWriter(spec, options);
+                    return state === "absent" || !["running", "paused", "restarting"].includes(state.status);
+                }, options);
+            }
+            else if (writer.status === "removing")
+                return fail();
+            if (await inspectExactSecretWriter(spec, options) !== "absent") {
+                await mutateAndReconcile(["--context", options.context, "container", "rm", spec.writerName], spec.writerName, async () => await inspectExactSecretWriter(spec, options) === "absent", options);
+            }
+        }
+        const volumeBeforeRemoval = writer === "absent"
+            ? initialVolume
+            : await inspectExactSecretVolume(spec, options);
+        if (volumeBeforeRemoval === "absent")
+            return;
+        await mutateAndReconcile(["--context", options.context, "volume", "rm", spec.volumeName], spec.volumeName, async () => await inspectExactSecretVolume(spec, options) === "absent", options);
+    }
+    catch {
+        return fail();
+    }
+};