spawnfile 0.1.13 → 0.1.17

package/dist/target/evidenceExportStorePublication.js

@@ -0,0 +1,395 @@
+import { Buffer } from "node:buffer";
+import { randomBytes, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, open, unlink } from "node:fs/promises";
+import path from "node:path";
+import { EVIDENCE_EXPORT_ERROR } from "./evidenceExportProvider.js";
+export const MAX_BYTES = 65_536;
+const fail = () => { throw new Error(EVIDENCE_EXPORT_ERROR); };
+const validDestinationKey = (value) => value !== null && /^[0-9a-f]{64}$/u.test(value);
+const unlinkOwnedTemporary = async (temporary, owned) => {
+    if (!owned)
+        return;
+    let current;
+    try {
+        current = await lstat(temporary);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        return fail();
+    }
+    if (!current.isFile() || current.isSymbolicLink() || current.dev !== owned.dev || current.ino !== owned.ino)
+        return fail();
+    try {
+        await unlink(temporary);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            return fail();
+    }
+};
+const sync = async (directory) => {
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const readDestinationKey = async (file, links, options, isPending = false, includePendingHook = true) => {
+    let info;
+    try {
+        info = await lstat(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        return fail();
+    }
+    if (!info.isFile() ||
+        info.isSymbolicLink() ||
+        !links.includes(info.nlink) ||
+        info.uid !== (process.getuid?.() ?? -1) ||
+        info.size > MAX_BYTES ||
+        (info.mode & 0o777) !== 0o600) {
+        return fail();
+    }
+    if (isPending && includePendingHook)
+        await options?.afterDestinationKeyPendingLstatBeforeOpen?.();
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isPending && error.code === "ENOENT")
+            return null;
+        return fail();
+    }
+    try {
+        const current = await handle.stat();
+        if (!current.isFile() ||
+            !links.includes(current.nlink) ||
+            current.uid !== (process.getuid?.() ?? -1) ||
+            current.size > MAX_BYTES ||
+            (current.mode & 0o777) !== 0o600 ||
+            current.dev !== info.dev ||
+            current.ino !== info.ino)
+            return fail();
+        return Object.freeze({
+            bytes: await handle.readFile({ encoding: "utf8" }),
+            dev: current.dev,
+            ino: current.ino,
+            nlink: current.nlink,
+        });
+    }
+    catch (error) {
+        if (isPending && error.code === "ENOENT")
+            return null;
+        return fail();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+export const publishImmutable = async (root, fileName, content, joinExisting = false, options) => {
+    if (Buffer.byteLength(content, "utf8") > MAX_BYTES)
+        return fail();
+    const file = path.join(root, fileName);
+    for (let attempt = 0; attempt < 24; attempt += 1) {
+        const prior = await readDestinationKey(file, [1, 2], options);
+        if (prior !== null) {
+            if (prior.bytes !== content && !joinExisting)
+                return fail();
+            if (prior.nlink === 1)
+                return;
+            if (prior.nlink === 2) {
+                if (options?.afterImmutableTransientRead)
+                    await options.afterImmutableTransientRead();
+                await sync(root);
+                continue;
+            }
+            return fail();
+        }
+        const temporary = path.join(root, `.${fileName}.${process.pid}.${randomUUID()}.tmp`);
+        let handle;
+        let owned;
+        try {
+            await options?.beforeImmutableTempOpen?.(temporary);
+            handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            const opened = await handle.stat();
+            if (!opened.isFile() || opened.isSymbolicLink())
+                return fail();
+            owned = { dev: opened.dev, ino: opened.ino };
+            await options?.afterImmutableTempIdentity?.(temporary);
+            await handle.chmod(0o600);
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+            const info = await handle.stat();
+            if (!info.isFile() || info.isSymbolicLink() || info.uid !== (process.getuid?.() ?? -1) || (info.mode & 0o777) !== 0o600 || info.dev !== owned.dev || info.ino !== owned.ino)
+                return fail();
+            await handle.close();
+            handle = undefined;
+            await sync(root);
+            await link(temporary, file);
+            await sync(root);
+            if (options?.afterImmutableFinalLinkBeforeTempUnlink)
+                await options.afterImmutableFinalLinkBeforeTempUnlink();
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "EEXIST") {
+                continue;
+            }
+            return fail();
+        }
+        finally {
+            if (handle)
+                await handle.close().catch(() => undefined);
+            await unlinkOwnedTemporary(temporary, owned);
+            await sync(root);
+        }
+    }
+    return fail();
+};
+const writeKeyPending = async (root, pending, options) => {
+    const temporary = path.join(root, `.destination-hmac.${process.pid}.${randomUUID()}.tmp`);
+    const value = randomBytes(32).toString("hex");
+    let handle;
+    let identity;
+    let owned;
+    try {
+        await options?.beforeDestinationKeyTempOpen?.(temporary);
+        handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.isSymbolicLink())
+            return fail();
+        identity = { dev: opened.dev, ino: opened.ino };
+        await options?.afterDestinationKeyTempIdentity?.(temporary);
+        await handle.chmod(0o600);
+        await handle.writeFile(value, "utf8");
+        await handle.sync();
+        const info = await handle.stat();
+        if (!info.isFile() || info.isSymbolicLink() || info.uid !== (process.getuid?.() ?? -1) || (info.mode & 0o777) !== 0o600 || info.size > MAX_BYTES || info.dev !== identity.dev || info.ino !== identity.ino)
+            return fail();
+        await handle.close();
+        handle = undefined;
+        owned = Object.freeze({ bytes: value, dev: info.dev, ino: info.ino, nlink: info.nlink });
+        await sync(root);
+        try {
+            await link(temporary, pending);
+            await sync(root);
+            await options?.afterDestinationKeyPendingLinkBeforeTempUnlink?.();
+            return owned;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                return fail();
+            return null;
+        }
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return null;
+        return fail();
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        await unlinkOwnedTemporary(temporary, identity);
+        await sync(root);
+    }
+};
+const sameDestinationSnapshot = (left, right) => {
+    return left.bytes === right.bytes && left.dev === right.dev && left.ino === right.ino;
+};
+const destination = async (root, options) => {
+    const file = path.join(root, ".destination-hmac.key");
+    const pending = path.join(root, ".destination-hmac.pending");
+    const validLinks = [1, 2, 3];
+    const finalGeneration = async () => readDestinationKey(file, validLinks, options);
+    const pendingGeneration = async () => readDestinationKey(pending, validLinks, options, true);
+    const convergentRead = async () => readDestinationKey(file, [1, 2, 3], options);
+    const unlinkExactDestinationPending = async (snapshot) => {
+        const current = await readDestinationKey(pending, validLinks, options, true, false);
+        if (current === null || !sameDestinationSnapshot(current, snapshot))
+            return false;
+        try {
+            await unlink(pending);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            fail();
+        }
+        await sync(root);
+        return true;
+    };
+    const unlinkOwnedDestinationPending = async () => {
+        if (owned === null)
+            return false;
+        const removed = await unlinkExactDestinationPending(owned);
+        if (removed)
+            owned = null;
+        return removed;
+    };
+    let owned = null;
+    for (let attempt = 0; attempt < 24; attempt += 1) {
+        const currentFinal = await finalGeneration();
+        if (currentFinal !== null) {
+            if (!validDestinationKey(currentFinal.bytes))
+                return fail();
+            if (options?.afterDestinationKeyFinalSnapshot)
+                await options.afterDestinationKeyFinalSnapshot();
+            const staged = await pendingGeneration();
+            if (staged === null) {
+                const repaired = await convergentRead();
+                if (repaired === null || !sameDestinationSnapshot(repaired, currentFinal))
+                    continue;
+                if (repaired.nlink === 1)
+                    return Buffer.from(repaired.bytes, "hex");
+                if (repaired.nlink === 2)
+                    continue;
+                return fail();
+            }
+            if (!validDestinationKey(staged.bytes))
+                return fail();
+            if (owned !== null && !sameDestinationSnapshot(owned, staged)) {
+                await unlinkExactDestinationPending(owned);
+                owned = null;
+            }
+            if (!sameDestinationSnapshot(staged, currentFinal)) {
+                const repaired = await convergentRead();
+                if (repaired === null || !sameDestinationSnapshot(repaired, currentFinal))
+                    continue;
+                if (repaired.nlink === 1) {
+                    if (owned !== null) {
+                        const removed = await unlinkExactDestinationPending(owned);
+                        if (removed)
+                            owned = null;
+                    }
+                    continue;
+                }
+                if (repaired.nlink === 2 || repaired.nlink === 3)
+                    continue;
+                return fail();
+            }
+            if (owned === null && staged.nlink !== 3)
+                owned = staged;
+            await unlinkOwnedDestinationPending();
+            const repaired = await convergentRead();
+            if (repaired === null || !sameDestinationSnapshot(repaired, currentFinal))
+                continue;
+            if (repaired.nlink === 1) {
+                await options?.afterDestinationKeyRecovered?.();
+                return Buffer.from(currentFinal.bytes, "hex");
+            }
+            if (repaired.nlink === 2 || repaired.nlink === 3) {
+                continue;
+            }
+            return fail();
+        }
+        if (options?.afterDestinationKeyInitialFinalAbsent)
+            await options.afterDestinationKeyInitialFinalAbsent();
+        let staged = await pendingGeneration();
+        if (staged === null) {
+            const created = await writeKeyPending(root, pending, options);
+            if (created === null)
+                continue;
+            owned = created;
+            staged = created;
+        }
+        else {
+            if (!validDestinationKey(staged.bytes))
+                return fail();
+            if (staged.nlink === 3) {
+                if (owned !== null) {
+                    const ownedRemoved = await unlinkExactDestinationPending(owned);
+                    if (ownedRemoved)
+                        owned = null;
+                }
+                continue;
+            }
+            if (owned === null) {
+                owned = staged;
+            }
+            else if (!sameDestinationSnapshot(owned, staged)) {
+                await unlinkExactDestinationPending(owned);
+                owned = null;
+            }
+        }
+        if (owned !== null && (staged.nlink === 1 || staged.nlink === 2)) {
+            try {
+                await options?.beforeDestinationKeyLink?.();
+            }
+            catch {
+                return fail();
+            }
+            const raced = await finalGeneration();
+            if (raced !== null) {
+                if (!validDestinationKey(raced.bytes) || !sameDestinationSnapshot(raced, owned)) {
+                    const removed = await unlinkExactDestinationPending(owned);
+                    if (removed)
+                        owned = null;
+                    continue;
+                }
+                if (raced.nlink === 1) {
+                    if (owned !== null) {
+                        const removed = await unlinkExactDestinationPending(owned);
+                        if (removed)
+                            owned = null;
+                    }
+                    return Buffer.from(raced.bytes, "hex");
+                }
+                if (raced.nlink === 2 || raced.nlink === 3)
+                    continue;
+                return fail();
+            }
+        }
+        try {
+            await link(pending, file);
+            await sync(root);
+            await options?.afterDestinationKeyPendingLink?.();
+            if (owned !== null) {
+                try {
+                    await options?.afterDestinationKeyLinkBeforePendingUnlink?.();
+                }
+                catch {
+                    return fail();
+                }
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST" && code !== "ENOENT")
+                return fail();
+            if (owned !== null) {
+                await unlinkExactDestinationPending(owned);
+                owned = null;
+            }
+            continue;
+        }
+        const healed = await convergentRead();
+        if (healed === null || !sameDestinationSnapshot(healed, staged))
+            continue;
+        if (healed.nlink === 1) {
+            if (owned !== null) {
+                const removed = await unlinkExactDestinationPending(owned);
+                if (removed)
+                    owned = null;
+            }
+            return Buffer.from(healed.bytes, "hex");
+        }
+        if (healed.nlink === 2 || healed.nlink === 3) {
+            if (owned !== null && !sameDestinationSnapshot(owned, healed)) {
+                await unlinkExactDestinationPending(owned);
+                owned = null;
+            }
+            continue;
+        }
+        return fail();
+    }
+    return fail();
+};
+export { destination as destinationKey };

package/dist/target/handles.d.ts

@@ -0,0 +1,20 @@
+import { type OpaqueTargetHandle, type SelectedTargetReceipt, type TargetResourceReceipt, type TargetResourceRequest, type TargetTopologyReceipt } from "./contracts.js";
+export type TargetDigest = `sha256:${string}`;
+export type TargetDigestDomain = "journal-identity" | "operation-handle" | "pending-receipt" | "receipt" | "request";
+export declare const createTargetRequestDigest: (raw: unknown) => TargetDigest;
+export declare const createTargetReceiptDigest: (raw: unknown) => TargetDigest;
+export declare const createTargetOperationHandle: (journalIdentity: TargetDigest, rawRequest: unknown) => OpaqueTargetHandle;
+export declare const createCanonicalTargetReceiptBytes: (raw: unknown) => string;
+export declare const createCanonicalSelectedTargetReceiptBytes: (raw: unknown) => string;
+export declare const createCanonicalTargetOperationLookupBytes: (raw: unknown) => string;
+export declare const createTargetTopologyAttestationRequestDigest: (raw: unknown) => TargetDigest;
+export declare const createTargetTopologyReceiptDigest: (raw: unknown) => TargetDigest;
+export declare const createCanonicalTargetTopologyReceiptBytes: (raw: unknown) => string;
+export declare const createTargetJournalIdentity: (input: {
+    context: unknown;
+    descriptor_digest: unknown;
+    run_id: unknown;
+    selected_target: unknown;
+}) => TargetDigest;
+export declare const createPendingReceiptDigest: (operationHandle: unknown, requestDigest: unknown) => TargetDigest;
+export type { OpaqueTargetHandle, SelectedTargetReceipt, TargetResourceReceipt, TargetResourceRequest, TargetTopologyReceipt };

package/dist/target/handles.js

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { assertOrdinaryJsonGraph, parseOpaqueTargetHandle, parseRunId, parseSelectedTargetReceipt, parseTargetOperationLookup, parseTargetResourceJournal, parseTargetResourceReceipt, parseTargetResourceRequest, parseTargetTopologyAttestationRequest, parseTargetTopologyReceipt, TARGET_JOURNAL_VERSION } from "./contracts.js";
+const canonicalJson = (value) => {
+    assertOrdinaryJsonGraph(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+const createCanonicalTargetDigest = (domain, value) => `sha256:${createHash("sha256")
+    .update(`spawnfile.target-resource.${domain}.v1\0`, "utf8").update(canonicalJson(value), "utf8").digest("hex")}`;
+/* T1 owns the digest grammar; this surrogate parses one through its journal field. */
+const parseTargetDigest = (raw) => parseTargetResourceJournal({
+    descriptor_digest: raw, entries: [], revision: 0, run_id: "a",
+    selected_target: { fingerprint: `sha256:${"0".repeat(32)}`, handle: "opaque_0000000000000000" },
+    version: TARGET_JOURNAL_VERSION
+}).descriptor_digest;
+const parseContext = (raw) => {
+    if (typeof raw !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/u.test(raw))
+        throw new TypeError("invalid target journal context");
+    return raw;
+};
+export const createTargetRequestDigest = (raw) => createCanonicalTargetDigest("request", parseTargetResourceRequest(raw));
+export const createTargetReceiptDigest = (raw) => {
+    const receipt = parseTargetResourceReceipt(raw);
+    const { receipt_digest: _receiptDigest, ...body } = receipt;
+    return createCanonicalTargetDigest("receipt", body);
+};
+export const createTargetOperationHandle = (journalIdentity, rawRequest) => {
+    const request = parseTargetResourceRequest(rawRequest);
+    const identity = parseTargetDigest(journalIdentity);
+    return parseOpaqueTargetHandle(`opaque_${createCanonicalTargetDigest("operation-handle", { journal_identity: identity, request }).slice("sha256:".length)}`);
+};
+export const createCanonicalTargetReceiptBytes = (raw) => canonicalJson(parseTargetResourceReceipt(raw));
+export const createCanonicalSelectedTargetReceiptBytes = (raw) => canonicalJson(parseSelectedTargetReceipt(raw));
+export const createCanonicalTargetOperationLookupBytes = (raw) => canonicalJson(parseTargetOperationLookup(raw));
+const createTopologyDigest = (domain, value) => `sha256:${createHash("sha256")
+    .update(`spawnfile.target-topology-${domain}.v1\0`, "utf8")
+    .update(canonicalJson(value), "utf8").digest("hex")}`;
+export const createTargetTopologyAttestationRequestDigest = (raw) => createTopologyDigest("request", parseTargetTopologyAttestationRequest(raw));
+export const createTargetTopologyReceiptDigest = (raw) => {
+    const receipt = parseTargetTopologyReceipt(raw);
+    const { receipt_digest: _receiptDigest, ...body } = receipt;
+    return createTopologyDigest("receipt", body);
+};
+export const createCanonicalTargetTopologyReceiptBytes = (raw) => canonicalJson(parseTargetTopologyReceipt(raw));
+export const createTargetJournalIdentity = (input) => createCanonicalTargetDigest("journal-identity", {
+    context: parseContext(input.context), descriptor_digest: parseTargetDigest(input.descriptor_digest),
+    run_id: parseRunId(input.run_id), selected_target: parseSelectedTargetReceipt(input.selected_target)
+});
+export const createPendingReceiptDigest = (operationHandle, requestDigest) => createCanonicalTargetDigest("pending-receipt", {
+    operation_handle: parseOpaqueTargetHandle(operationHandle), request_digest: parseTargetDigest(requestDigest)
+});

package/dist/target/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./cleanupRun.js";
+export * from "./composedPreparation.js";
+export * from "./contracts.js";
+export * from "./dockerTarget.js";
+export * from "./handles.js";
+export * from "./publicArtifactSnapshot.js";
+export * from "./topologyActivation.js";
+export * from "./worldReadiness.js";
+export * from "./worldClock.js";
+export { initializeTargetJournal, lookupTargetOperation, openExistingTargetJournal, openTargetJournal, setTargetJournalFilesystemForTests } from "./journal.js";
+export { resolveTargetJournalRoot } from "./journalRoot.js";
+export type { InitializeTargetJournalOptions, LookupTargetOperationOptions, TargetJournalClaim, TargetJournalLookupStore, TargetJournalReservation, TargetJournalStore } from "./journal.js";

package/dist/target/index.js

@@ -0,0 +1,11 @@
+export * from "./cleanupRun.js";
+export * from "./composedPreparation.js";
+export * from "./contracts.js";
+export * from "./dockerTarget.js";
+export * from "./handles.js";
+export * from "./publicArtifactSnapshot.js";
+export * from "./topologyActivation.js";
+export * from "./worldReadiness.js";
+export * from "./worldClock.js";
+export { initializeTargetJournal, lookupTargetOperation, openExistingTargetJournal, openTargetJournal, setTargetJournalFilesystemForTests } from "./journal.js";
+export { resolveTargetJournalRoot } from "./journalRoot.js";

package/dist/target/journal.d.ts

@@ -0,0 +1,59 @@
+import { type OpaqueTargetHandle, type TargetOperationLookup, type TargetResourceJournal, type TargetResourceReceipt } from "./contracts.js";
+import { type TargetDigest } from "./handles.js";
+export interface InitializeTargetJournalOptions {
+    context: unknown;
+    descriptorDigest: unknown;
+    root?: string;
+    runId: unknown;
+    selectedTarget: unknown;
+}
+export interface TargetJournalClaim {
+    readonly operationHandle: OpaqueTargetHandle;
+    readonly requestDigest: TargetDigest;
+}
+export type TargetJournalReservation = {
+    readonly kind: "owner";
+    readonly claim: TargetJournalClaim;
+} | {
+    readonly kind: "pending";
+    readonly claim: TargetJournalClaim;
+} | {
+    readonly kind: "replay";
+    readonly receipt: TargetResourceReceipt;
+    readonly receiptBytes: string;
+};
+export interface TargetJournalStore {
+    complete(claim: TargetJournalClaim, raw: unknown): Promise<{
+        readonly receipt: TargetResourceReceipt;
+        readonly receiptBytes: string;
+    }>;
+    read(): Promise<TargetResourceJournal>;
+    reserve(raw: unknown): Promise<TargetJournalReservation>;
+    resolveCompletedReceipt(claim: TargetJournalClaim): Promise<{
+        readonly receipt: TargetResourceReceipt;
+        readonly receiptBytes: string;
+    } | null>;
+    withLifecycleLease<Result>(action: () => Promise<Result>): Promise<Result>;
+}
+export interface TargetJournalLookupStore {
+    lookup(raw: unknown): Promise<TargetOperationLookup>;
+}
+export interface LookupTargetOperationOptions {
+    context: unknown;
+    request: unknown;
+    root?: string;
+}
+interface JournalFilesystem {
+    syncDirectory(directory: string): Promise<void>;
+}
+/** Test seam for observing the required post-replacement directory sync. */
+export declare const setTargetJournalFilesystemForTests: (replacement: JournalFilesystem) => (() => void);
+export declare const initializeTargetJournal: (options: InitializeTargetJournalOptions) => Promise<TargetJournalStore>;
+/** Internal full authority for target-owned lifecycle recovery. Not barrel-exported. */
+export declare const openExistingTargetJournalAuthority: (options: InitializeTargetJournalOptions) => Promise<TargetJournalStore>;
+/** Public read-only facade over one already-existing journal. */
+export declare const openExistingTargetJournal: (options: InitializeTargetJournalOptions) => Promise<TargetJournalLookupStore>;
+/** Looks up one exact original mutation without creating, locking, or modifying owner state. */
+export declare const lookupTargetOperation: (options: LookupTargetOperationOptions) => Promise<TargetOperationLookup>;
+export declare const openTargetJournal: (options: InitializeTargetJournalOptions) => Promise<TargetJournalStore>;
+export {};