spawnfile 0.1.13 → 0.1.14

package/dist/cli/targetLookupCommands.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from "commander";
+import { type TargetMutationRequest, type TargetOperationLookup } from "../target/contracts.js";
+export interface TargetLookupCommandStreams {
+    stderr(message: string): void;
+    stdout(message: string): void;
+}
+export type TargetOperationLookupHandler = (request: TargetMutationRequest) => Promise<TargetOperationLookup>;
+export type TargetOperationLookupLoader = (configInput: unknown) => Promise<TargetOperationLookupHandler>;
+type SetExitCode = (exitCode: 1 | 2) => void;
+export declare const registerTargetOperationLookup: (target: Command, loader: TargetOperationLookupLoader, streams: TargetLookupCommandStreams, setExitCode: SetExitCode) => void;
+export declare const createProductionTargetLookupLoader: (stdin: AsyncIterable<unknown>) => TargetOperationLookupLoader;
+export {};

package/dist/cli/targetLookupCommands.js

@@ -0,0 +1,69 @@
+import { parseTargetOperationLookup } from "../target/contracts.js";
+import { createCanonicalTargetOperationLookupBytes, createTargetReceiptDigest, createTargetRequestDigest } from "../target/handles.js";
+import { lookupTargetOperation } from "../target/journal.js";
+import { resolveTargetDefaultJournalRoot } from "../target/journalRoot.js";
+import { readTargetLookupConfigStdin } from "./targetDefaultConfigStdin.js";
+import { readTargetRequestFile } from "./targetRequestFile.js";
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const emitLookup = (raw, request, streams) => {
+    const result = parseTargetOperationLookup(raw);
+    const requestDigest = createTargetRequestDigest(request);
+    if (result.idempotency_key !== request.idempotency_key
+        || result.operation !== request.operation
+        || result.request_digest !== requestDigest)
+        throw new TypeError();
+    if (result.status === "completed"
+        && (result.receipt.receipt_digest !== createTargetReceiptDigest(result.receipt)
+            || result.receipt.descriptor_digest !== request.descriptor_digest
+            || result.receipt.run_id !== request.run_id
+            || !same(result.receipt.selected_target, request.selected_target)
+            || result.receipt.resulting_revision !== request.expected_revision + 1)) {
+        throw new TypeError();
+    }
+    streams.stdout(createCanonicalTargetOperationLookupBytes(result));
+};
+export const registerTargetOperationLookup = (target, loader, streams, setExitCode) => {
+    target.command("lookup_operation")
+        .description("Read the state of one exact target mutation")
+        .argument("<request-file>", "Original strict target-resource mutation request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            const parsed = await readTargetRequestFile(requestFile);
+            if (parsed.operation === "select_target")
+                throw new TypeError();
+            request = parsed;
+        }
+        catch {
+            streams.stderr("error: Invalid target lookup request");
+            setExitCode(2);
+            return;
+        }
+        let lookup;
+        try {
+            lookup = await loader(target.opts().config);
+        }
+        catch {
+            streams.stderr("error: Invalid target lookup configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            emitLookup(await lookup(request), request, streams);
+        }
+        catch {
+            streams.stderr("error: Target operation lookup failed");
+            setExitCode(1);
+        }
+    });
+};
+export const createProductionTargetLookupLoader = (stdin) => async (configInput) => {
+    if (configInput !== "-")
+        throw new TypeError();
+    const config = await readTargetLookupConfigStdin(stdin);
+    return (request) => lookupTargetOperation({
+        context: config.context,
+        request,
+        root: resolveTargetDefaultJournalRoot()
+    });
+};

package/dist/cli/targetOperationDispatch.d.ts

@@ -0,0 +1,58 @@
+import type { TargetResourceRequest } from "../target/contracts.js";
+export type TargetOperation = TargetResourceRequest["operation"];
+export type TargetMutationOperation = Exclude<TargetOperation, "select_target">;
+export interface TargetSelectionDispatch {
+    readonly kind: "selection";
+    readonly operation: "select_target";
+}
+export interface TargetMutationDispatch {
+    readonly kind: "mutation";
+    readonly operation: TargetMutationOperation;
+}
+export type TargetOperationDispatch = TargetSelectionDispatch | TargetMutationDispatch;
+export declare const TARGET_OPERATION_DISPATCH: Readonly<{
+    attach_organization: TargetMutationDispatch & {
+        readonly operation: "attach_organization";
+    };
+    cleanup_run: TargetMutationDispatch & {
+        readonly operation: "cleanup_run";
+    };
+    create_data_network: TargetMutationDispatch & {
+        readonly operation: "create_data_network";
+    };
+    create_evidence_volume: TargetMutationDispatch & {
+        readonly operation: "create_evidence_volume";
+    };
+    create_world_service: TargetMutationDispatch & {
+        readonly operation: "create_world_service";
+    };
+    detach_organization: TargetMutationDispatch & {
+        readonly operation: "detach_organization";
+    };
+    export_evidence_volume: TargetMutationDispatch & {
+        readonly operation: "export_evidence_volume";
+    };
+    prepare_secret_bindings: TargetMutationDispatch & {
+        readonly operation: "prepare_secret_bindings";
+    };
+    recover_operation: TargetMutationDispatch & {
+        readonly operation: "recover_operation";
+    };
+    resolve_world_artifact: TargetMutationDispatch & {
+        readonly operation: "resolve_world_artifact";
+    };
+    revoke_secret_bindings: TargetMutationDispatch & {
+        readonly operation: "revoke_secret_bindings";
+    };
+    select_target: {
+        kind: "selection";
+        operation: "select_target";
+    };
+    start_world_service: TargetMutationDispatch & {
+        readonly operation: "start_world_service";
+    };
+    stop_world_service: TargetMutationDispatch & {
+        readonly operation: "stop_world_service";
+    };
+}>;
+export declare const targetOperationDispatch: (request: TargetResourceRequest) => TargetOperationDispatch;

package/dist/cli/targetOperationDispatch.js

@@ -0,0 +1,21 @@
+const mutation = (operation) => ({
+    kind: "mutation",
+    operation
+});
+export const TARGET_OPERATION_DISPATCH = Object.freeze({
+    attach_organization: mutation("attach_organization"),
+    cleanup_run: mutation("cleanup_run"),
+    create_data_network: mutation("create_data_network"),
+    create_evidence_volume: mutation("create_evidence_volume"),
+    create_world_service: mutation("create_world_service"),
+    detach_organization: mutation("detach_organization"),
+    export_evidence_volume: mutation("export_evidence_volume"),
+    prepare_secret_bindings: mutation("prepare_secret_bindings"),
+    recover_operation: mutation("recover_operation"),
+    resolve_world_artifact: mutation("resolve_world_artifact"),
+    revoke_secret_bindings: mutation("revoke_secret_bindings"),
+    select_target: { kind: "selection", operation: "select_target" },
+    start_world_service: mutation("start_world_service"),
+    stop_world_service: mutation("stop_world_service")
+});
+export const targetOperationDispatch = (request) => TARGET_OPERATION_DISPATCH[request.operation];

package/dist/cli/targetReceiptOutput.d.ts

@@ -0,0 +1,14 @@
+import { type TargetResourceReceipt } from "../target/contracts.js";
+export interface TargetMutationResult {
+    readonly receipt: unknown;
+    readonly receiptBytes: unknown;
+}
+export interface CanonicalTargetMutationReceipt {
+    readonly bytes: string;
+    readonly receipt: TargetResourceReceipt;
+}
+export type TargetCliErrorPhase = "operation" | "request";
+export declare const formatTargetCliError: (phase: TargetCliErrorPhase) => string;
+export declare const formatCaughtTargetCliError: (error: unknown, crashMessage: string) => string;
+export declare const validateCanonicalTargetMutationReceipt: (raw: TargetMutationResult) => CanonicalTargetMutationReceipt;
+export declare const emitCanonicalTargetMutationReceipt: (raw: TargetMutationResult, write: (receiptBytes: string) => void) => TargetResourceReceipt;

package/dist/cli/targetReceiptOutput.js

@@ -0,0 +1,21 @@
+import { createCanonicalTargetReceiptBytes, createTargetReceiptDigest } from "../target/handles.js";
+import { parseTargetResourceReceipt } from "../target/contracts.js";
+import { isSpawnfileError } from "../shared/index.js";
+export const formatTargetCliError = (phase) => phase === "request" ? "error: Invalid target request" : "error: Target operation failed";
+export const formatCaughtTargetCliError = (error, crashMessage) => isSpawnfileError(error)
+    ? `error: ${error.message}`
+    : `error: ${crashMessage}`;
+export const validateCanonicalTargetMutationReceipt = (raw) => {
+    const receipt = parseTargetResourceReceipt(raw.receipt);
+    const bytes = createCanonicalTargetReceiptBytes(receipt);
+    if (receipt.receipt_digest !== createTargetReceiptDigest(receipt)
+        || typeof raw.receiptBytes !== "string" || raw.receiptBytes !== bytes) {
+        throw new TypeError("Target operation returned a non-canonical receipt");
+    }
+    return Object.freeze({ bytes, receipt });
+};
+export const emitCanonicalTargetMutationReceipt = (raw, write) => {
+    const validated = validateCanonicalTargetMutationReceipt(raw);
+    write(validated.bytes);
+    return validated.receipt;
+};

package/dist/cli/targetRequestFile.d.ts

@@ -0,0 +1,14 @@
+import { type TargetTopologyAttestationRequest, type TargetResourceRequest } from "../target/contracts.js";
+import { type ComposedPreparationRequest } from "../target/composedPreparation.js";
+import { type TargetPublicArtifactSnapshotRequest } from "../target/publicArtifactSnapshot.js";
+import { type TargetWorldClockRequest } from "../target/worldClock.js";
+import { type TargetWorldReadinessRequest } from "../target/worldReadiness.js";
+export declare const DEFAULT_TARGET_REQUEST_FILE_BYTES = 262144;
+export declare const MAX_TARGET_REQUEST_FILE_BYTES = 1048576;
+export declare const MAX_TARGET_REQUEST_FILE_PATH_BYTES = 4096;
+export declare const readTargetRequestFile: (filePath: string, byteLimit?: number) => Promise<TargetResourceRequest>;
+export declare const readComposedPreparationRequestFile: (filePath: string, byteLimit?: number) => Promise<ComposedPreparationRequest>;
+export declare const readTargetTopologyAttestationRequestFile: (filePath: string, byteLimit?: number) => Promise<TargetTopologyAttestationRequest>;
+export declare const readTargetPublicArtifactSnapshotRequestFile: (filePath: string, byteLimit?: number) => Promise<TargetPublicArtifactSnapshotRequest>;
+export declare const readTargetWorldReadinessRequestFile: (filePath: string, byteLimit?: number) => Promise<TargetWorldReadinessRequest>;
+export declare const readTargetWorldClockRequestFile: (filePath: string, byteLimit?: number) => Promise<TargetWorldClockRequest>;

package/dist/cli/targetRequestFile.js

@@ -0,0 +1,63 @@
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { parseTargetResourceRequest, parseTargetTopologyAttestationRequest } from "../target/contracts.js";
+import { parseComposedPreparationRequest } from "../target/composedPreparation.js";
+import { parseTargetPublicArtifactSnapshotRequest } from "../target/publicArtifactSnapshot.js";
+import { parseTargetWorldClockRequest } from "../target/worldClock.js";
+import { parseTargetWorldReadinessRequest } from "../target/worldReadiness.js";
+export const DEFAULT_TARGET_REQUEST_FILE_BYTES = 262_144;
+export const MAX_TARGET_REQUEST_FILE_BYTES = 1_048_576;
+export const MAX_TARGET_REQUEST_FILE_PATH_BYTES = 4_096;
+const parseByteLimit = (raw) => {
+    if (!Number.isSafeInteger(raw) || raw < 1
+        || raw > MAX_TARGET_REQUEST_FILE_BYTES) {
+        throw new TypeError("Target request-file byte limit is invalid");
+    }
+    return raw;
+};
+const requireExactAbsolutePath = (raw) => {
+    if (typeof raw !== "string" || raw.length < 1 || raw.includes("\0")
+        || Buffer.byteLength(raw, "utf8") > MAX_TARGET_REQUEST_FILE_PATH_BYTES
+        || !path.isAbsolute(raw) || path.normalize(raw) !== raw) {
+        throw new TypeError("Target request file path is invalid");
+    }
+    return raw;
+};
+const requireObject = (raw) => {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new TypeError("Target request file must contain one JSON object");
+    }
+    return raw;
+};
+const readTargetRequestFileValue = async (filePath, byteLimit) => {
+    const limit = parseByteLimit(byteLimit);
+    const exactPath = requireExactAbsolutePath(filePath);
+    const handle = await open(exactPath, "r");
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > limit) {
+            throw new TypeError("Target request file is not a bounded regular file");
+        }
+        const bytes = Buffer.alloc(limit + 1);
+        let offset = 0;
+        while (offset <= limit) {
+            const result = await handle.read(bytes, offset, limit + 1 - offset, offset);
+            if (result.bytesRead === 0)
+                break;
+            offset += result.bytesRead;
+        }
+        if (offset > limit) {
+            throw new TypeError("Target request file exceeds the byte limit");
+        }
+        return requireObject(JSON.parse(bytes.toString("utf8", 0, offset)));
+    }
+    finally {
+        await handle.close();
+    }
+};
+export const readTargetRequestFile = async (filePath, byteLimit = DEFAULT_TARGET_REQUEST_FILE_BYTES) => parseTargetResourceRequest(await readTargetRequestFileValue(filePath, byteLimit));
+export const readComposedPreparationRequestFile = async (filePath, byteLimit = DEFAULT_TARGET_REQUEST_FILE_BYTES) => parseComposedPreparationRequest(await readTargetRequestFileValue(filePath, byteLimit));
+export const readTargetTopologyAttestationRequestFile = async (filePath, byteLimit = DEFAULT_TARGET_REQUEST_FILE_BYTES) => parseTargetTopologyAttestationRequest(await readTargetRequestFileValue(filePath, byteLimit));
+export const readTargetPublicArtifactSnapshotRequestFile = async (filePath, byteLimit = DEFAULT_TARGET_REQUEST_FILE_BYTES) => parseTargetPublicArtifactSnapshotRequest(await readTargetRequestFileValue(filePath, byteLimit));
+export const readTargetWorldReadinessRequestFile = async (filePath, byteLimit = DEFAULT_TARGET_REQUEST_FILE_BYTES) => parseTargetWorldReadinessRequest(await readTargetRequestFileValue(filePath, byteLimit));
+export const readTargetWorldClockRequestFile = async (filePath, byteLimit = DEFAULT_TARGET_REQUEST_FILE_BYTES) => parseTargetWorldClockRequest(await readTargetRequestFileValue(filePath, byteLimit));

package/dist/cli/targetSecretSourceInput.d.ts

@@ -0,0 +1,28 @@
+import { type OpaqueTargetSecretSourceHandle } from "../auth/targetSecretSourceRecordCommon.js";
+import { type TargetSecretSourceGrantCommandInput } from "../auth/targetSecretSourceGrantRecords.js";
+export declare const TARGET_SECRET_SOURCE_REQUEST_VERSION: "spawnfile.auth.target-secret.source-request.v1";
+export declare const TARGET_SECRET_SOURCE_GRANT_REQUEST_VERSION: "spawnfile.auth.target-secret.grant-request.v1";
+export declare const TARGET_SECRET_SOURCE_RECEIPT_VERSION: "spawnfile.auth.target-secret.receipt.v1";
+export declare const MAX_TARGET_SECRET_SOURCE_REQUEST_FILE_BYTES = 65536;
+export type TargetSecretSourceCommandKind = "author" | "grant" | "revoke-grant" | "revoke-version" | "rotate";
+export type TargetSecretSourceRequest = Readonly<{
+    source_handle: OpaqueTargetSecretSourceHandle;
+    version: typeof TARGET_SECRET_SOURCE_REQUEST_VERSION;
+}>;
+export type TargetSecretSourceReceipt = Readonly<{
+    kind: TargetSecretSourceCommandKind;
+    source_handle: OpaqueTargetSecretSourceHandle;
+    version: typeof TARGET_SECRET_SOURCE_RECEIPT_VERSION;
+}>;
+export declare const parseTargetSecretSourceRequestBytes: (bytes: Uint8Array) => TargetSecretSourceRequest;
+export declare const parseTargetSecretSourceGrantRequestBytes: (bytes: Uint8Array) => TargetSecretSourceGrantCommandInput;
+export interface TargetSecretSourceRequestFileOptions {
+    readonly beforeReadForTest?: () => Promise<void> | void;
+}
+export declare const readTargetSecretSourceRequestFile: (filePath: string, options?: TargetSecretSourceRequestFileOptions) => Promise<TargetSecretSourceRequest>;
+export declare const readTargetSecretSourceGrantRequestFile: (filePath: string, options?: TargetSecretSourceRequestFileOptions) => Promise<TargetSecretSourceGrantCommandInput>;
+export declare const createTargetSecretSourceReceiptBytes: (raw: Readonly<{
+    kind: TargetSecretSourceCommandKind;
+    source_handle: unknown;
+}>) => Uint8Array;
+export declare const readBoundedTargetSecretStdin: (input: AsyncIterable<unknown>, maximumBytes: number) => Promise<Uint8Array>;

package/dist/cli/targetSecretSourceInput.js

@@ -0,0 +1,121 @@
+import { Buffer } from "node:buffer";
+import { open } from "node:fs/promises";
+import { MAX_TARGET_SECRET_SOURCE_SECRET_BYTES, TARGET_SECRET_SOURCE_ERROR, assertOrdinaryJsonGraph, createCanonicalTargetSecretSourceJson, parseCanonicalTargetSecretSourceJson, parseTargetSecretSourceOpaqueHandle } from "../auth/targetSecretSourceRecordCommon.js";
+import { parseTargetSecretSourceGrantCommandInput } from "../auth/targetSecretSourceGrantRecords.js";
+export const TARGET_SECRET_SOURCE_REQUEST_VERSION = "spawnfile.auth.target-secret.source-request.v1";
+export const TARGET_SECRET_SOURCE_GRANT_REQUEST_VERSION = "spawnfile.auth.target-secret.grant-request.v1";
+export const TARGET_SECRET_SOURCE_RECEIPT_VERSION = "spawnfile.auth.target-secret.receipt.v1";
+export const MAX_TARGET_SECRET_SOURCE_REQUEST_FILE_BYTES = 65_536;
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const exact = (raw, keys) => {
+    assertOrdinaryJsonGraph(raw);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return fail();
+    const record = raw;
+    const actual = Object.keys(record).sort();
+    if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index]))
+        fail();
+    return record;
+};
+export const parseTargetSecretSourceRequestBytes = (bytes) => {
+    const record = exact(parseCanonicalTargetSecretSourceJson(bytes), ["source_handle", "version"]);
+    if (record.version !== TARGET_SECRET_SOURCE_REQUEST_VERSION)
+        fail();
+    return Object.freeze({
+        source_handle: parseTargetSecretSourceOpaqueHandle(record.source_handle),
+        version: TARGET_SECRET_SOURCE_REQUEST_VERSION
+    });
+};
+export const parseTargetSecretSourceGrantRequestBytes = (bytes) => {
+    const record = exact(parseCanonicalTargetSecretSourceJson(bytes), ["grant", "version"]);
+    if (record.version !== TARGET_SECRET_SOURCE_GRANT_REQUEST_VERSION)
+        fail();
+    return parseTargetSecretSourceGrantCommandInput(record.grant);
+};
+const readRequestFile = async (filePath, parse, options) => {
+    let bytes;
+    let handle;
+    try {
+        handle = await open(filePath, "r");
+        const info = await handle.stat();
+        if (!info.isFile() || info.size < 1 || info.size > MAX_TARGET_SECRET_SOURCE_REQUEST_FILE_BYTES)
+            fail();
+        await options.beforeReadForTest?.();
+        bytes = Buffer.alloc(info.size + 1);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        if (offset !== info.size)
+            fail();
+        return parse(bytes.subarray(0, offset));
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        bytes?.fill(0);
+        await handle?.close().catch(() => undefined);
+    }
+};
+export const readTargetSecretSourceRequestFile = (filePath, options = {}) => readRequestFile(filePath, parseTargetSecretSourceRequestBytes, options);
+export const readTargetSecretSourceGrantRequestFile = (filePath, options = {}) => readRequestFile(filePath, parseTargetSecretSourceGrantRequestBytes, options);
+export const createTargetSecretSourceReceiptBytes = (raw) => {
+    try {
+        const record = exact(raw, ["kind", "source_handle"]);
+        const kinds = ["author", "grant", "revoke-grant", "revoke-version", "rotate"];
+        if (!kinds.includes(record.kind))
+            fail();
+        const receipt = Object.freeze({
+            kind: record.kind,
+            source_handle: parseTargetSecretSourceOpaqueHandle(record.source_handle),
+            version: TARGET_SECRET_SOURCE_RECEIPT_VERSION
+        });
+        const canonical = createCanonicalTargetSecretSourceJson(receipt);
+        return canonical;
+    }
+    catch {
+        return fail();
+    }
+};
+export const readBoundedTargetSecretStdin = async (input, maximumBytes) => {
+    const chunks = [];
+    let total = 0;
+    try {
+        if (!input || typeof input[Symbol.asyncIterator] !== "function"
+            || !Number.isSafeInteger(maximumBytes) || maximumBytes < 1
+            || maximumBytes > MAX_TARGET_SECRET_SOURCE_SECRET_BYTES)
+            fail();
+        for await (const raw of input) {
+            if (typeof raw === "string" && Buffer.byteLength(raw, "utf8") > maximumBytes - total)
+                fail();
+            if (raw instanceof Uint8Array && raw.byteLength > maximumBytes - total)
+                fail();
+            const chunk = typeof raw === "string" ? new TextEncoder().encode(raw)
+                : raw instanceof Uint8Array ? Uint8Array.from(raw) : fail();
+            chunks.push(chunk);
+            total += chunk.length;
+            if (total > maximumBytes)
+                fail();
+        }
+        if (total === 0)
+            fail();
+        const result = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return result;
+    }
+    catch {
+        return fail();
+    }
+    finally {
+        for (const chunk of chunks)
+            chunk.fill(0);
+    }
+};

package/dist/cli/targetWorldClockCommand.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type TargetWorldClockReceipt, type TargetWorldClockRequest } from "../target/worldClock.js";
+export interface TargetWorldClockSession {
+    queryWorldClock?(request: TargetWorldClockRequest): Promise<TargetWorldClockReceipt>;
+}
+export type TargetWorldClockSessionLoader = (configInput: unknown) => Promise<TargetWorldClockSession>;
+export declare const registerTargetWorldClockCommand: (target: Command, session: TargetWorldClockSession | TargetWorldClockSessionLoader, streams: {
+    readonly stderr: (message: string) => void;
+    readonly stdout: (message: string) => void;
+}, setExitCode: (exitCode: 1 | 2) => void) => void;

package/dist/cli/targetWorldClockCommand.js

@@ -0,0 +1,42 @@
+import { createCanonicalTargetWorldClockReceiptBytes, verifyTargetWorldClockReceipt, } from "../target/worldClock.js";
+import { formatCaughtTargetCliError } from "./targetReceiptOutput.js";
+import { readTargetWorldClockRequestFile } from "./targetRequestFile.js";
+export const registerTargetWorldClockCommand = (target, session, streams, setExitCode) => {
+    target.command("query_world_clock")
+        .description("Query one exact activated world's observed public clock")
+        .argument("<request-file>", "Strict world clock request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readTargetWorldClockRequestFile(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid world clock request");
+            setExitCode(2);
+            return;
+        }
+        let active;
+        try {
+            active = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+            if (typeof active.queryWorldClock !== "function")
+                throw new TypeError();
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const receipt = verifyTargetWorldClockReceipt({
+                receipt: await active.queryWorldClock(request), request,
+            });
+            streams.stdout(createCanonicalTargetWorldClockReceiptBytes(receipt));
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target world clock query crashed"));
+            setExitCode(1);
+        }
+    });
+};

package/dist/cli/targetWorldClockCrossProcess.test-helper.d.ts

@@ -0,0 +1,13 @@
+import { type TargetWorldClockRequest } from "../target/worldClock.js";
+export type BuiltWorldClockMode = "success" | "tick-zero" | "stale" | "topology" | "activation" | "nonzero-action";
+export interface BuiltWorldClockState {
+    readonly callsPath: string;
+    readonly config: Readonly<Record<string, unknown>>;
+    readonly home: string;
+    readonly modePath: string;
+    readonly request: TargetWorldClockRequest;
+    readonly requestPath: string;
+    readonly root: string;
+}
+export declare const createBuiltWorldClockState: () => Promise<BuiltWorldClockState>;
+export declare const selectBuiltWorldClockMode: (state: BuiltWorldClockState, mode: BuiltWorldClockMode) => Promise<void>;

package/dist/cli/targetWorldClockCrossProcess.test-helper.js

@@ -0,0 +1,109 @@
+import { chmod, mkdtemp, realpath, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parseOpaqueTargetHandle } from "../target/contracts.js";
+import { createDockerArtifactSpec } from "../target/dockerArtifactsProvider.js";
+import { createDockerResourceSpec } from "../target/dockerResourcesProvider.js";
+import { createWorldServiceAuthorization, parseWorldServiceResolution } from "../target/dockerWorldServiceAuthority.js";
+import { worldServiceSpecForBinding } from "../target/dockerWorldServiceLifecycle.js";
+import { createWorldServiceBinding, initializeWorldServiceAuthorityStore, worldServiceResourceBindings, } from "../target/dockerWorldServiceStore.js";
+import { createCanonicalWorldServiceActivationBytes, createTargetTopologyActivationReceiptDigest, createWorldServiceActivationDigest, parseWorldServiceActivation, } from "../target/topologyActivation.js";
+import { parseTargetWorldClockRequest } from "../target/worldClock.js";
+const d = (value) => `sha256:${value.repeat(64).slice(0, 64)}`;
+const h = (value) => parseOpaqueTargetHandle(`opaque_${value.repeat(16)}`);
+const containerId = "c".repeat(64);
+const after = (args, flag) => args[args.indexOf(flag) + 1];
+const inspection = (spec) => ({
+    AutoRemove: false, BindCount: 0, CapAddCount: 0, CapDrop: ["ALL"], CgroupnsMode: "private", DeviceCount: 0,
+    DeviceRequestCount: 0, DnsCount: 0, Domainname: "", ExposedPortCount: 0, ExtraHostCount: 0, GroupAddCount: 0,
+    Hostname: spec.containerName, Id: containerId, Image: spec.imageReference, IpcMode: "none", Labels: spec.receiptLabels,
+    LinkCount: 0, LogType: "none", Mounts: spec.createArgs.filter((value, index, values) => values[index - 1] === "--mount")
+        .map((value) => Object.fromEntries(value.split(",").map((part) => part.split("=", 2))))
+        .map((mount) => ({ Destination: mount.dst, Name: mount.src, RW: mount.dst === spec.evidenceMountPath, Type: "volume" })),
+    Name: `/${spec.containerName}`, NetworkAliases: spec.networkAlias ? [spec.networkAlias] : null,
+    NetworkAttachmentCount: 1, NetworkAttachmentId: "b".repeat(64), NetworkAttachmentName: after(spec.createArgs, "--network"),
+    NetworkMode: after(spec.createArgs, "--network"), PidMode: "", PortBindingCount: 0, Privileged: false,
+    PublishAllPorts: false, ReadonlyRootfs: true, RestartMaximumRetryCount: 0, RestartPolicyName: "no",
+    SecurityOpt: ["no-new-privileges=true"], Status: "running", Tmpfs: { "/tmp": "rw,noexec,nosuid,nodev,size=1m,mode=1777" },
+    UTSMode: "", UsernsMode: "", VolumesFromCount: 0,
+});
+const fixture = () => {
+    const selectedTarget = { fingerprint: `sha256:${"1".repeat(32)}`, handle: h("1") };
+    const runId = "run-built-clock";
+    const dataClaim = { operationHandle: h("2"), requestDigest: d("2") };
+    const evidenceClaim = { operationHandle: h("3"), requestDigest: d("3") };
+    const data = createDockerResourceSpec({ kind: "data_network", ...dataClaim, runId, selectedTargetHandle: selectedTarget.handle });
+    const evidence = createDockerResourceSpec({ kind: "evidence_volume", ...evidenceClaim, runId, selectedTargetHandle: selectedTarget.handle });
+    const artifact = createDockerArtifactSpec({ artifactManifestDigest: d("4"), imageDigest: d("5"),
+        imageReference: `registry.example/world@${d("5")}`, operationHandle: h("4"), requestDigest: d("4"),
+        selectedTargetHandle: selectedTarget.handle });
+    const authorization = createWorldServiceAuthorization({ dataNetworkHandle: data.resultHandle, descriptorDigest: d("6"),
+        evidenceMountPath: "/run/world/evidence", evidenceVolumeHandle: evidence.resultHandle, operationHandle: h("6"),
+        requestDigest: d("6"), runId, secretBindingsHandle: h("7"), selectedTarget, worldArtifactHandle: artifact.resultHandle });
+    const resolution = parseWorldServiceResolution({ artifact: { artifact_manifest_digest: d("4"), identity_kind: "oci_image_manifest",
+            image_digest: artifact.imageDigest, image_reference: artifact.imageReference, operation_handle: h("4"),
+            request_digest: d("4"), result_handle: artifact.resultHandle }, authorization });
+    const resources = worldServiceResourceBindings({ dataNetworkClaim: dataClaim, evidenceVolumeClaim: evidenceClaim, resolution });
+    const spec = worldServiceSpecForBinding({ resolution, resources });
+    const binding = createWorldServiceBinding({ containerId, dataNetwork: resources.data_network, evidenceVolume: resources.evidence_volume,
+        resolution, secretBindings: resources.secret_bindings, spec });
+    const marker = parseWorldServiceActivation({ bundle_digest: d("8"), run_id: runId, state: "activated",
+        topology_receipt_digest: d("9"), topology_request_digest: d("a"), version: "spawnfile.world-service-activation.v1" });
+    const activationDigest = createWorldServiceActivationDigest(marker);
+    const activationReceiptDigest = createTargetTopologyActivationReceiptDigest({ activation_digest: activationDigest,
+        bundle_digest: marker.bundle_digest, receipt_digest: d("0"), run_id: runId, state: "activated",
+        topology_receipt_digest: marker.topology_receipt_digest, topology_request_digest: marker.topology_request_digest,
+        version: "spawnfile.target-topology-activation-receipt.v1" });
+    const request = parseTargetWorldClockRequest({ activation_digest: activationDigest,
+        activation_receipt_digest: activationReceiptDigest, descriptor_digest: authorization.descriptor_digest,
+        endpoint: { internal_port: 4_070, path: "/v1/world/clock" },
+        expected: { document_version: "world.clock-document.v1", world_instance_id: "world-built-clock" }, run_id: runId,
+        selected_target: selectedTarget, topology_receipt_digest: marker.topology_receipt_digest,
+        topology_request_digest: marker.topology_request_digest, version: "spawnfile.target-world-clock.request.v1",
+        world_service_handle: binding.world_service_handle });
+    return { binding, marker, request, spec };
+};
+export const createBuiltWorldClockState = async () => {
+    const root = await realpath(await mkdtemp(path.join(os.tmpdir(), "spawnfile-built-world-clock-")));
+    const home = path.join(root, "home");
+    const callsPath = path.join(root, "docker-calls.ndjson");
+    const modePath = path.join(root, "mode");
+    const scenariosPath = path.join(root, "scenarios.json");
+    const fakeDocker = path.join(root, "docker-clock");
+    const requestPath = path.join(root, "request.json");
+    const { binding, marker, request, spec } = fixture();
+    const store = await initializeWorldServiceAuthorityStore(path.join(home, "target", "world-authority"));
+    await store.bindService(binding);
+    const observation = { action_count: 0, clock: { completed_tick: 1, next_tick: 2, state: "running" },
+        run_id: request.run_id, version: request.expected.document_version, world_instance_id: request.expected.world_instance_id };
+    const topologyMarker = parseWorldServiceActivation({ ...marker, topology_receipt_digest: d("b") });
+    const activationMarker = parseWorldServiceActivation({ ...marker, bundle_digest: d("c") });
+    const scenarios = {
+        success: { marker: createCanonicalWorldServiceActivationBytes(marker), observation: JSON.stringify(observation) },
+        "tick-zero": { marker: createCanonicalWorldServiceActivationBytes(marker), observation: JSON.stringify({ ...observation,
+                clock: { completed_tick: 0, next_tick: 1, state: "running" } }) },
+        stale: { marker: createCanonicalWorldServiceActivationBytes(marker), observation: JSON.stringify({ ...observation, run_id: "run-stale-clock" }) },
+        topology: { marker: createCanonicalWorldServiceActivationBytes(topologyMarker), observation: JSON.stringify(observation) },
+        activation: { marker: createCanonicalWorldServiceActivationBytes(activationMarker), observation: JSON.stringify(observation) },
+        "nonzero-action": { marker: createCanonicalWorldServiceActivationBytes(marker), observation: JSON.stringify({ ...observation, action_count: 1 }) },
+    };
+    await writeFile(callsPath, "", { mode: 0o600 });
+    await writeFile(modePath, "success", { mode: 0o600 });
+    await writeFile(scenariosPath, JSON.stringify(scenarios), { mode: 0o600 });
+    await writeFile(requestPath, JSON.stringify(request), { mode: 0o600 });
+    await writeFile(fakeDocker, `#!${process.execPath}
+const fs=require("node:fs");const args=process.argv.slice(2);
+fs.appendFileSync(${JSON.stringify(callsPath)},JSON.stringify(args)+"\\n");
+const all=JSON.parse(fs.readFileSync(${JSON.stringify(scenariosPath)},"utf8"));
+const current=all[fs.readFileSync(${JSON.stringify(modePath)},"utf8").trim()];
+if(args[2]==="container"&&args[3]==="inspect")process.stdout.write(${JSON.stringify(JSON.stringify([inspection(spec)]))});
+else if(args[2]==="container"&&args[3]==="exec"&&args.includes("/bin/cat"))process.stdout.write(current.marker);
+else if(args[2]==="container"&&args[3]==="exec"&&args.includes("/usr/local/bin/node"))process.stdout.write(current.observation);
+else{process.stderr.write("unexpected fake Docker command\\n");process.exitCode=71;}
+`, { mode: 0o700 });
+    await chmod(fakeDocker, 0o700);
+    return { callsPath, config: { context: "built_clock", dockerCommand: fakeDocker,
+            evidenceDestination: path.join(root, "unused.tar"), timeoutMs: 10_000,
+            version: "spawnfile.target-default-config.v1" }, home, modePath, request, requestPath, root };
+};
+export const selectBuiltWorldClockMode = async (state, mode) => { await writeFile(state.modePath, mode, { mode: 0o600 }); };

package/dist/cli/targetWorldReadinessCommand.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type TargetWorldReadinessRequest, type TargetWorldReadinessReceipt } from "../target/worldReadiness.js";
+export interface TargetWorldReadinessSession {
+    queryWorldReadiness?(request: TargetWorldReadinessRequest): Promise<TargetWorldReadinessReceipt>;
+}
+export type TargetWorldReadinessSessionLoader = (configInput: unknown) => Promise<TargetWorldReadinessSession>;
+export declare const registerTargetWorldReadinessCommand: (target: Command, session: TargetWorldReadinessSession | TargetWorldReadinessSessionLoader, streams: {
+    readonly stderr: (message: string) => void;
+    readonly stdout: (message: string) => void;
+}, setExitCode: (exitCode: 1 | 2) => void) => void;