spawnfile 0.1.13 → 0.1.17

package/dist/cli/targetEvidenceHelperResolution.js

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+import { parseTargetResourceRequest, } from "../target/contracts.js";
+/**
+ * Derives the target-owned helper admission immediately preceding an evidence
+ * export. The public export revision therefore names the second mutation in
+ * this aggregate operation; recovery reuses the completed admission.
+ */
+export const createTargetEvidenceHelperResolutionRequest = (request, artifactManifestDigest) => {
+    if (request.expected_revision < 1)
+        throw new Error("Target operation mismatch");
+    return parseTargetResourceRequest({
+        artifact_manifest_digest: artifactManifestDigest,
+        descriptor_digest: request.descriptor_digest,
+        expected_revision: request.expected_revision - 1,
+        idempotency_key: `idem_${createHash("sha256")
+            .update("spawnfile.target-evidence-helper-resolution.v1\0", "utf8")
+            .update(request.idempotency_key, "utf8").digest("hex").slice(0, 32)}`,
+        operation: "resolve_world_artifact",
+        run_id: request.run_id,
+        selected_target: request.selected_target,
+        version: "spawnfile.target-resource.request.v1",
+    });
+};

package/dist/cli/targetLookupCli.d.ts

@@ -0,0 +1,3 @@
+import { type TargetLookupCommandStreams } from "./targetLookupCommands.js";
+/** Minimal production entry point for lookup; it loads no mutation/provider defaults. */
+export declare const runTargetLookupCli: (argv: string[], stdin?: AsyncIterable<unknown>, streams?: TargetLookupCommandStreams) => Promise<number>;

package/dist/cli/targetLookupCli.js

@@ -0,0 +1,31 @@
+import { Command } from "commander";
+import { createProductionTargetLookupLoader, registerTargetOperationLookup } from "./targetLookupCommands.js";
+const defaultStreams = () => ({
+    stderr: (message) => process.stderr.write(`${message}\n`),
+    stdout: (message) => process.stdout.write(`${message}\n`)
+});
+const commanderError = (error) => typeof error === "object" && error !== null
+    && typeof error.exitCode === "number";
+/** Minimal production entry point for lookup; it loads no mutation/provider defaults. */
+export const runTargetLookupCli = async (argv, stdin = process.stdin, streams = defaultStreams()) => {
+    let exitCode = 0;
+    const program = new Command();
+    program.exitOverride();
+    program.configureOutput({ writeErr: () => undefined, writeOut: () => undefined });
+    const target = program.command("target").description("Execute target-resource operations");
+    target.requiredOption("--config <config-input>", "Strict target configuration JSON stdin; use -");
+    registerTargetOperationLookup(target, createProductionTargetLookupLoader(stdin), streams, (code) => { exitCode = code; });
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return exitCode;
+    }
+    catch (error) {
+        if (commanderError(error)) {
+            if (error.exitCode !== 0)
+                streams.stderr("error: Invalid target command");
+            return error.exitCode === 0 ? 0 : 2;
+        }
+        streams.stderr("error: Target operation lookup failed");
+        return 1;
+    }
+};

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/targetProductionCommands.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { TargetDefaultConfig } from "./targetDefaultConfig.js";
+import { type SetTargetCommandExitCode, type TargetCommandHandlerSession, type TargetCommandStreams } from "./targetCommands.js";
+export declare const createProductionTargetCommandSession: (config: TargetDefaultConfig) => TargetCommandHandlerSession;
+export declare const registerProductionTargetCommands: (program: Command, streams: TargetCommandStreams, stdin: AsyncIterable<unknown>, setExitCode: SetTargetCommandExitCode) => void;

package/dist/cli/targetProductionCommands.js

@@ -0,0 +1,45 @@
+import { registerContainerBundleCommand } from "./containerBundleCommand.js";
+import { readTargetDefaultConfigStdin, readTargetWorldReadinessConfigStdin, } from "./targetDefaultConfigStdin.js";
+import { createProductionTargetWorldQuerySession } from "./targetDefaultWorldQueries.js";
+import { registerTargetConfigResolverCommand, TARGET_CONFIG_RESOLVER_COMMAND, } from "./targetConfigResolverCommand.js";
+import { createProductionTargetLookupLoader } from "./targetLookupCommands.js";
+import { registerTargetCommands, } from "./targetCommands.js";
+export const createProductionTargetCommandSession = (config) => Object.freeze({
+    activateTopology: async (request) => {
+        const { activateTargetDefaultTopology } = await import("./targetDefaultHandlers.js");
+        return activateTargetDefaultTopology(config, request);
+    },
+    run: async (invokeHandlers) => {
+        const { withTargetDefaultHandlerSession } = await import("./targetDefaultHandlers.js");
+        return withTargetDefaultHandlerSession(config, invokeHandlers);
+    },
+    attestTopology: async (request) => {
+        const { attestTargetDefaultTopology } = await import("./targetDefaultHandlers.js");
+        return attestTargetDefaultTopology(config, request);
+    },
+    queryWorldReadiness: async (request) => {
+        const { queryTargetDefaultWorldReadiness } = await import("./targetDefaultWorldReadiness.js");
+        return queryTargetDefaultWorldReadiness(config, request);
+    },
+    queryWorldClock: async (request) => {
+        const { queryTargetDefaultWorldClock } = await import("./targetDefaultWorldClock.js");
+        return queryTargetDefaultWorldClock(config, request);
+    },
+    snapshotPublicArtifact: async (request) => {
+        const { snapshotTargetDefaultPublicArtifact } = await import("./targetDefaultHandlers.js");
+        return snapshotTargetDefaultPublicArtifact(config, request);
+    },
+});
+export const registerProductionTargetCommands = (program, streams, stdin, setExitCode) => {
+    const target = registerTargetCommands(program, async (configInput) => {
+        if (configInput !== "-")
+            throw new TypeError("Invalid target configuration");
+        return createProductionTargetCommandSession(await readTargetDefaultConfigStdin(stdin));
+    }, streams, setExitCode, createProductionTargetLookupLoader(stdin), async (configInput) => {
+        if (configInput !== "-")
+            throw new TypeError("Invalid target configuration");
+        return createProductionTargetWorldQuerySession(await readTargetWorldReadinessConfigStdin(stdin));
+    }, [TARGET_CONFIG_RESOLVER_COMMAND]);
+    registerContainerBundleCommand(target, stdin, streams, setExitCode);
+    registerTargetConfigResolverCommand(target, streams, setExitCode);
+};

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/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;