@gjermundgaraba/clankerbox-sdk 0.18.3 → 0.20.0

package/dist/{client-DHNZ57xn.mjs → client-S3cTnrsp.mjs}

@@ -24,20 +24,31 @@ var NotFound = class extends Schema.TaggedError()("NotFound", {
 	message: Schema.String,
 	...located
 }, { httpApiStatus: 404 }) {};
-const ConflictKind = Schema.Literals(["exists", "busy"]);
-/** The name is taken (`exists`), or another action holds the resource (`busy`). */
+/** The name is taken. */
 var Conflict = class extends Schema.TaggedError()("Conflict", {
 	message: Schema.String,
-	kind: ConflictKind,
 	...located
 }, { httpApiStatus: 409 }) {};
+/**
+* A later request on the machine replaced this one before the host got there: `by` is what that
+* request asked for. The machine's own state says where it is now.
+*/
+var Superseded = class extends Schema.TaggedError()("Superseded", {
+	message: Schema.String,
+	...located,
+	by: Schema.Literals([
+		"running",
+		"stopped",
+		"deleted"
+	])
+}, { httpApiStatus: 409 }) {};
 /** No host offers `base`: the host a create names, or any in the client's list. */
 var NotOffered = class extends Schema.TaggedError()("NotOffered", {
 	message: Schema.String,
 	...located,
 	base: Schema.String
 }, { httpApiStatus: 412 }) {};
-/** `machine`'s create, fork or restore failed before it was made: it can only be deleted. */
+/** `machine` isn't made yet: its create or setup still runs, so it can't be copied or captured. */
 var NotMade = class extends Schema.TaggedError()("NotMade", {
 	message: Schema.String,
 	...located,
@@ -49,12 +60,6 @@ var Missing = class extends Schema.TaggedError()("Missing", {
 	...located,
 	machine: Schema.String
 }, { httpApiStatus: 412 }) {};
-/** `checkpoint`'s capture failed, so nothing restores from it: it can only be deleted. */
-var NotReady = class extends Schema.TaggedError()("NotReady", {
-	message: Schema.String,
-	...located,
-	checkpoint: Schema.String
-}, { httpApiStatus: 412 }) {};
 /** `checkpoint` holds RAM state saved under another runtime pin than the one the host runs. */
 var PinMismatch = class extends Schema.TaggedError()("PinMismatch", {
 	message: Schema.String,
@@ -75,12 +80,13 @@ var Unsizable = class extends Schema.TaggedError()("Unsizable", {
 }, { httpApiStatus: 422 }) {};
 /**
 * A guest script exited non-zero or ran past its timeout; the message says which, with its
-* output's tail. A failed `setup` leaves the machine unmade, a failed `preparation` made.
+* output's tail, and `script` names it: a failed `setup` deletes the machine, and a failed
+* `preparation` runs again on the next start.
 */
 var ScriptFailed = class extends Schema.TaggedError()("ScriptFailed", {
 	message: Schema.String,
 	...located,
-	script: Schema.Literals(["setup", "preparation"])
+	script: Schema.String
 }, { httpApiStatus: 422 }) {};
 /** The provider under the runtime refused the call for good, such as for its plan or API key. */
 var Refused = class extends Schema.TaggedError()("Refused", {
@@ -110,10 +116,10 @@ const hostErrors = [
 	Invalid,
 	NotFound,
 	Conflict,
+	Superseded,
 	NotOffered,
 	NotMade,
 	Missing,
-	NotReady,
 	PinMismatch,
 	WrongState,
 	Unsizable,
@@ -126,22 +132,24 @@ const HostError = Schema.Union(hostErrors);
 /**
 * Each carries, where known: `host` and `action`, which the client sets; `id`, the resource the
 * error is about, which a host sets on `NotFound` and `Conflict` and the client sets to the call's
-* subject otherwise; and `made`, the resource a create, fork, restore or capture makes, which a
-* failure may leave behind.
+* subject otherwise; and `made`, the resource a create, fork, restore or capture makes. The host
+* deletes a machine whose copy or setup fails, again at each recheck while that delete fails, and
+* keeps one whose preparation fails; a call whose answer was lost, `Unavailable`, may leave
+* `made` behind unmade.
 */
 const ClankerboxError = Schema.Union([...hostErrors, Unavailable]);
 /**
-* Whether the same call may succeed later: a busy resource or a full host may free up, and a read
-* that got no reply may get one.
+* Whether the same call may succeed later: a full host may free up, and a read that got no reply
+* may get one.
 */
 const retryable = (error) => Match.value(error).pipe(Match.tagsExhaustive({
 	Invalid: () => false,
 	NotFound: () => false,
-	Conflict: ({ kind }) => kind === "busy",
+	Conflict: () => false,
+	Superseded: () => false,
 	NotOffered: () => false,
 	NotMade: () => false,
 	Missing: () => false,
-	NotReady: () => false,
 	PinMismatch: () => false,
 	WrongState: () => false,
 	Unsizable: () => false,
@@ -196,31 +204,31 @@ const Runtime = Schema.Literals([
 	"boat"
 ]);
 const Size = Schema.Int.check(Schema.isGreaterThan(0));
-/** The contract's mutations, which record themselves on a resource's `action`. */
-const ActionName = Schema.Literals([
-	"createMachine",
-	"startMachine",
-	"stopMachine",
-	"deleteMachine",
-	"forkMachine",
-	"restoreMachine",
-	"captureCheckpoint",
-	"deleteCheckpoint"
-]);
-const ActionStatus = Schema.Literals([
+/** What the operator asked a machine to be; the host keeps moving the machine toward it. */
+const Desired = Schema.Literals([
 	"running",
+	"stopped",
+	"deleted"
+]);
+/**
+* What the host is doing about a machine. A request waits for a rest: `settled`, at rest with what
+* was asked; `failed`, after a step failed, until the next request; `lost`, one the runtime no
+* longer has, which can only be deleted; and `waiting`, one the runtime can't read, which fails the
+* request and is read again at the host's next recheck. `creating` copies the machine and runs its
+* setup, and a machine whose create or setup fails is deleted. `starting` starts the machine, also
+* when it runs already, and prepares it.
+*/
+const Phase = Schema.Literals([
+	"observing",
+	"waiting",
+	"creating",
+	"starting",
+	"stopping",
+	"deleting",
+	"settled",
 	"failed",
-	"done"
+	"lost"
 ]);
-/** A resource's last action; the next action replaces it. */
-const ActionRecord = Schema.Union([Schema.Struct({
-	name: ActionName,
-	status: Schema.Literals(["running", "done"])
-}), Schema.Struct({
-	name: ActionName,
-	status: Schema.Literal("failed"),
-	error: HostError
-})]);
 const SshEndpoint = Schema.Struct({
 	host: Schema.String,
 	port: Schema.Int.check(Schema.isBetween({
@@ -233,10 +241,30 @@ const SshLogin = Schema.Struct({
 	...SshEndpoint.fields
 });
 /**
-* `state` is `missing` when the runtime doesn't have the machine, and `unknown` when it couldn't
-* be read. Until its create, fork or restore has `made` it, a machine can only be read, stopped or
-* deleted. `ssh` is only on a running machine whose runtime gives it an endpoint, and `hostKey`,
-* `<type> <base64>`, once preparation has recorded it.
+* A running machine's place on the tailnet, as the host last checked it: `joined` once
+* `tailscaled` runs signed in, with the MagicDNS name Tailscale gave it, if any; `failed` with
+* why; or `missing` when the guest has no `tailscaled`. Kept in the host's memory only: each start
+* checks again, a joined machine is checked again every half hour or so, and a failed one sooner,
+* waiting longer after each failure.
+*/
+const TailnetStatus = Schema.Union([
+	Schema.Struct({
+		state: Schema.Literal("joined"),
+		name: Schema.optionalKey(Schema.String)
+	}),
+	Schema.Struct({
+		state: Schema.Literal("failed"),
+		error: Schema.String
+	}),
+	Schema.Struct({ state: Schema.Literal("missing") })
+]).annotate({ identifier: "TailnetStatus" });
+/**
+* `state` is what the runtime reports: `missing` when it doesn't have the machine, and `unknown`
+* when it couldn't be read. `desired` is what the last request asked for, `phase` what the host is
+* doing about it, and `error` why the last step failed, until the next request. `ssh` is only
+* on a running machine whose runtime gives it an endpoint, and `hostKey`, `<type> <base64>`, once
+* preparation has recorded it. `tailnet` is on a running machine of a host that joins its machines
+* to a tailnet, once the host has checked it.
 */
 const Machine = Schema.Struct({
 	id: Id,
@@ -253,14 +281,22 @@ const Machine = Schema.Struct({
 		"missing",
 		"unknown"
 	]),
-	made: Schema.Boolean,
-	action: ActionRecord,
+	desired: Desired,
+	phase: Phase,
+	error: Schema.optionalKey(HostError),
 	ssh: Schema.optionalKey(SshLogin),
-	hostKey: Schema.optionalKey(Schema.String)
+	hostKey: Schema.optionalKey(Schema.String),
+	tailnet: Schema.optionalKey(TailnetStatus)
 }).annotate({ identifier: "Machine" });
-/** The state as people read it: `running`, or `stopped (unmade)` for one never made. */
-const stateLabel = ({ state, made }) => made ? state : `${state} (unmade)`;
-/** `kind` is `ram` (RAM and disks) on smolvm, and `disk` on Tart and boat. */
+/**
+* The state as people read it: `running` at rest, `running (failed)` where it is but not at rest,
+* and `stopped, wants running (starting)` on the way.
+*/
+const stateLabel = ({ state, desired, phase }) => phase === "settled" ? state : state === desired ? `${state} (${phase})` : `${state}, wants ${desired} (${phase})`;
+/**
+* `kind` is `ram` (RAM and disks) on smolvm, and `disk` on Tart and boat. A checkpoint exists only
+* once its capture is done, and never changes after.
+*/
 const Checkpoint = Schema.Struct({
 	id: Id,
 	createdAt: Schema.DateTimeUtcFromString,
@@ -270,11 +306,8 @@ const Checkpoint = Schema.Struct({
 	profile: Schema.optionalKey(Schema.String),
 	cpu: Size,
 	ramMib: Size,
-	diskGib: Size,
-	action: ActionRecord
+	diskGib: Size
 }).annotate({ identifier: "Checkpoint" });
-/** A checkpoint restores once its capture is done; it never changes after. */
-const isReady = (checkpoint) => checkpoint.action.status === "done";
 /**
 * `runtimeVersion` is boat's API version on boat. `captureFrom` is the state a machine must be in
 * to be captured: Tart's is `stopped`.
@@ -316,10 +349,25 @@ const Usage = Schema.Union([Schema.Struct({
 	...usageFields,
 	unread: Schema.Array(Id)
 })]).annotate({ identifier: "Usage" });
-/** Nothing logs the script: it can carry secrets. */
+const publicKeyLine = /^(?:ssh|ecdsa|sk)-[a-z0-9@.-]+ [A-Za-z0-9+/]+={0,3}(?: .*)?$/u;
+const blankLine = /^\s*$/u;
+/**
+* Public keys, as `.pub` files hold them: each line that isn't blank is `<type> <base64>
+* [comment]`, the type an OpenSSH key's, its certificate's or a hardware key's, and at least one
+* line is. Anything else, a private key included, is refused.
+*/
+const PublicKeys = Schema.String.check(Schema.makeFilter((text) => {
+	const lines = text.split("\n").filter((line) => !blankLine.test(line));
+	return lines.length > 0 && lines.every((line) => publicKeyLine.test(line)) || "each line that isn't blank is a public key, <type> <base64> [comment], as a .pub file holds it";
+}));
+/**
+* Nothing logs the script: it can carry secrets. `authorizedKeys` is appended to the login user's
+* `~/.ssh/authorized_keys` once the script exits 0, through the guest's `sudo`.
+*/
 const Setup = Schema.Struct({
 	script: Schema.String,
-	timeoutSeconds: Schema.optionalKey(Size)
+	timeoutSeconds: Schema.optionalKey(Size),
+	authorizedKeys: Schema.optionalKey(PublicKeys)
 });
 const specFields = {
 	base: Schema.String,
@@ -336,6 +384,17 @@ const CreateRequest = Schema.Struct({
 	id: Id,
 	...specFields
 });
+/** A prebuild is the checkpoint `id` of a machine made from the spec, setup and all. */
+const PrebuildRequest = Schema.Struct({
+	id: Id,
+	...specFields,
+	setup: Setup
+});
+/** `built` is false when the host already had the checkpoint. */
+const Prebuilt = Schema.Struct({
+	checkpoint: Checkpoint,
+	built: Schema.Boolean
+});
 //#endregion
 //#region src/api.ts
 /** A host bounds its own reads of runtime state under it, so a list answers in time. */
@@ -359,20 +418,28 @@ const reading = [
 	NotFound,
 	Internal
 ];
-const changing = [
+const removing = [
 	Invalid,
 	NotFound,
-	Conflict,
 	Refused,
 	Internal
 ];
-const booting = [
-	...changing,
+const converging = [
+	Invalid,
+	NotFound,
 	NotMade,
 	Missing,
 	WrongState,
-	Capacity
+	PinMismatch,
+	Unsizable,
+	ScriptFailed,
+	Refused,
+	Capacity,
+	Superseded,
+	Internal
 ];
+const making = [...converging, Conflict];
+const creating = [...making, NotOffered];
 const Http = ActionHttp.make([
 	Action.make("listMachines", {
 		...read,
@@ -389,62 +456,42 @@ const Http = ActionHttp.make([
 	}),
 	Action.make("createMachine", {
 		...write,
-		error: [
-			Invalid,
-			Conflict,
-			NotOffered,
-			Unsizable,
-			ScriptFailed,
-			Refused,
-			Capacity,
-			Internal
-		],
-		description: "Create a machine from a base, run its setup once, and prepare it.",
+		error: creating,
+		description: "Create a machine from a base, run its setup once, and prepare it. A create or setup that fails deletes the machine, again at each recheck while that delete fails, and the error is the answer; a preparation that fails keeps it.",
 		input: CreateRequest,
 		success: Machine
 	}),
 	Action.make("startMachine", {
 		...write,
-		error: [...booting, ScriptFailed],
-		description: "Start a machine. On a running machine, run preparation again.",
+		error: converging,
+		description: "Ask for a machine to run, and wait until it does: start it and prepare it again, also when it runs already.",
 		input: ById,
 		success: Machine
 	}),
 	Action.make("stopMachine", {
 		...write,
-		error: changing,
-		description: "Stop a machine: a power-off that keeps its disk and ends its processes. A stopped machine stays stopped, and the stop is still its last action.",
+		error: converging,
+		description: "Ask for a machine to stay stopped, and wait until it is: a power-off that keeps its disk and ends its processes. A start under way is cut short; a machine still being made is made first, and its create answers Superseded.",
 		input: ById,
 		success: Machine
 	}),
 	Action.make("deleteMachine", {
 		...write,
-		error: changing,
-		description: "Delete a machine and everything native it owns.",
+		error: converging,
+		description: "Delete a machine and everything native it owns, whatever it is doing.",
 		input: ById
 	}),
 	Action.make("forkMachine", {
 		...write,
-		error: [
-			...booting,
-			Unsizable,
-			ScriptFailed
-		],
-		description: "Copy a machine to a new name on the same host.",
+		error: making,
+		description: "Copy a machine to a new name on the same host. A copy that fails deletes the new machine.",
 		input: FromMachine,
 		success: Machine
 	}),
 	Action.make("restoreMachine", {
 		...write,
-		error: [
-			...changing,
-			NotReady,
-			PinMismatch,
-			Unsizable,
-			ScriptFailed,
-			Capacity
-		],
-		description: "Create a machine on the checkpoint's host from that checkpoint.",
+		error: making,
+		description: "Create a machine on the checkpoint's host from that checkpoint. A restore that fails deletes the new machine.",
 		input: Schema.Struct({
 			checkpoint: Id,
 			name: Name
@@ -466,17 +513,34 @@ const Http = ActionHttp.make([
 	}),
 	Action.make("captureCheckpoint", {
 		...write,
-		error: booting,
+		error: [
+			Invalid,
+			NotFound,
+			Conflict,
+			NotMade,
+			Missing,
+			WrongState,
+			Refused,
+			Capacity,
+			Internal
+		],
 		description: "Capture a checkpoint of a machine. Its kind follows the runtime: ram on smolvm, which captures only a running machine, and disk on Tart and boat.",
 		input: FromMachine,
 		success: Checkpoint
 	}),
 	Action.make("deleteCheckpoint", {
 		...write,
-		error: changing,
-		description: "Delete a checkpoint.",
+		error: removing,
+		description: "Delete a checkpoint, once the restores that read it are done.",
 		input: ById
 	}),
+	Action.make("prebuildCheckpoint", {
+		...write,
+		error: creating,
+		description: "Make checkpoint id from a machine the host builds from the spec, setup and all, and deletes after. A checkpoint id that exists is the answer, and two prebuilds of one id share one build.",
+		input: PrebuildRequest,
+		success: Prebuilt
+	}),
 	Action.make("getHost", {
 		...read,
 		error: [Invalid],
@@ -498,7 +562,7 @@ const actionsByName = Action.byName(Http.actions);
 //#endregion
 //#region src/release.ts
 /** Also the version of the clankerbox CLI released with it. */
-const version = "0.18.3";
+const version = "0.20.0";
 /** major.minor: releases that share it speak the same API. */
 const release = (of) => of.split(".").slice(0, 2).join(".");
 /** A host refuses a request whose `release` differs from its own, or that has none. */
@@ -700,9 +764,10 @@ const make = (hosts, options) => Effect.gen(function* () {
 		restoreMachine: (input) => onResource("restoreMachine", input, input.name),
 		getCheckpoint: (input) => onResource("getCheckpoint", input),
 		captureCheckpoint: (input) => onResource("captureCheckpoint", input, input.name),
-		deleteCheckpoint: (input) => deleting(onResource("deleteCheckpoint", input))
+		deleteCheckpoint: (input) => deleting(onResource("deleteCheckpoint", input)),
+		prebuildCheckpoint: (input) => onResource("prebuildCheckpoint", input)
 	};
 });
 const layer = (hosts, options) => Layer.effect(Client, make(hosts, options));
 //#endregion
-export { parseId as A, NotFound as B, Usage as C, Id as D, HostId as E, ConflictKind as F, Refused as G, NotOffered as H, HostError as I, Unsizable as J, ScriptFailed as K, Internal as L, Capacity as M, ClankerboxError as N, Name as O, Conflict as P, Invalid as R, SshLogin as S, stateLabel as T, NotReady as U, NotMade as V, PinMismatch as W, hostErrors as X, WrongState as Y, retryable as Z, Machine as _, release as a, Setup as b, Http as c, ActionName as d, ActionRecord as f, Host as g, CreateRequest as h, describeIssues as i, parseName as j, formatId as k, actionsByName as l, Checkpoint as m, layer as n, version as o, ActionStatus as p, Unavailable as q, describeFileError as r, versionHeader as s, client_exports as t, readTimeout as u, MachineSpec as v, isReady as w, SshEndpoint as x, Runtime as y, Missing as z };
+export { Name as A, Missing as B, SshEndpoint as C, stateLabel as D, Usage as E, ClankerboxError as F, Refused as G, NotMade as H, Conflict as I, Unavailable as J, ScriptFailed as K, HostError as L, parseId as M, parseName as N, HostId as O, Capacity as P, retryable as Q, Internal as R, Setup as S, TailnetStatus as T, NotOffered as U, NotFound as V, PinMismatch as W, WrongState as X, Unsizable as Y, hostErrors as Z, Phase as _, release as a, PublicKeys as b, Http as c, Checkpoint as d, CreateRequest as f, MachineSpec as g, Machine as h, describeIssues as i, formatId as j, Id as k, actionsByName as l, Host as m, layer as n, version as o, Desired as p, Superseded as q, describeFileError as r, versionHeader as s, client_exports as t, readTimeout as u, PrebuildRequest as v, SshLogin as w, Runtime as x, Prebuilt as y, Invalid as z };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as ConflictKind, B as Refused, C as Declared, D as Capacity, E as readTimeout, F as NotFound, G as hostErrors, H as Unavailable, I as NotMade, K as retryable, L as NotOffered, M as Internal, N as Invalid, O as ClankerboxError, P as Missing, R as NotReady, S as stateLabel, T as actionsByName, U as Unsizable, V as ScriptFailed, W as WrongState, _ as Setup, b as Usage, c as ActionRecord, d as CreateRequest, f as Host, g as Runtime, h as Reading, i as Interface, j as HostError, k as Conflict, l as ActionStatus, m as MachineSpec, n as CreateOptions$1, o as client_d_exports, p as Machine, s as ActionName, u as Checkpoint, v as SshEndpoint, w as Http, x as isReady, y as SshLogin, z as PinMismatch } from "./client-8af586hb.mjs";
+import { A as ClankerboxError, B as Refused, C as Usage, D as actionsByName, E as Http, F as Missing, G as WrongState, H as Superseded, I as NotFound, K as hostErrors, L as NotMade, M as HostError, N as Internal, O as readTimeout, P as Invalid, R as NotOffered, S as TailnetStatus, T as Declared, U as Unavailable, V as ScriptFailed, W as Unsizable, _ as Reading, b as SshEndpoint, c as CreateRequest, d as Machine, f as MachineSpec, g as PublicKeys, h as Prebuilt, i as Interface, j as Conflict, k as Capacity, l as Desired, m as PrebuildRequest, n as CreateOptions$1, o as client_d_exports, p as Phase, q as retryable, s as Checkpoint, u as Host, v as Runtime, w as stateLabel, x as SshLogin, y as Setup, z as PinMismatch } from "./client-Dr3PcuCP.mjs";
 import { Effect, FileSystem, Path, PlatformError, Schema, Scope } from "effect";
 //#region src/ids.d.ts
 export declare const HostId: Schema.String;
@@ -15,11 +15,11 @@ export declare const parseName: (name: string) => Effect.Effect<string, Invalid>
 /** Checks both parts and the whole. */
 export declare const formatId: (host: string, name: string) => Effect.Effect<string, Invalid>;
 declare namespace prebuild_d_exports {
-  export { Built, CreateOptions, Created, build, create, nameOf };
+  export { CreateOptions, Created, build, create, nameOf };
 }
 /**
- * A digest of the spec's label, base, sizes, setup script as sent, and the host's runtime
- * version: a `ram` checkpoint restores only under the release that saved it, so after a runtime
+ * A digest of the spec's label, base, sizes, setup script as sent, authorized keys, and the host's
+ * runtime version: a `ram` checkpoint restores only under the release that saved it, so after a runtime
  * bump a create misses the old prebuild instead of failing to restore it. The setup's timeout and
  * the base's image are no part of it.
  */
@@ -34,26 +34,17 @@ interface Created {
   readonly prebuild?: Checkpoint | undefined;
 }
 /**
- * `client.create`, restoring the spec's prebuild when the host it is placed on has one whose
- * capture is done, unless `fresh`. A failed restore is the reply.
+ * `client.create`, restoring the spec's prebuild when the host it is placed on has one, unless
+ * `fresh`. A failed restore is the reply.
  */
 declare const create: (client: Interface, name: string, spec: MachineSpec, options?: CreateOptions) => Effect.Effect<Created, ClankerboxError>;
-interface Built {
-  readonly checkpoint: Checkpoint;
-  readonly built: boolean;
-  /** The builder's ID when its delete failed: it may still run, holding its RAM. */
-  readonly leftover?: string | undefined;
-}
 /**
- * Builds the spec's prebuild on the host a create of it is placed on, with a machine of its own
- * that it deletes however it ends. A prebuild that is there and done is the answer, one that
- * failed is deleted and built again, and one still running is `Conflict{busy}`, as its capture
- * holds it. Of two builds of one spec at once, the second's capture is `Conflict`, and neither
- * touches the other's machine.
+ * Asks the host a create of the spec is placed on for the spec's prebuild, which it builds with a
+ * machine of its own unless it has it. Two builds of one spec at once share the host's one build.
  */
 declare const build: (client: Interface, spec: MachineSpec & {
   readonly setup: Setup;
-}, options?: CreateOptions$1) => Effect.Effect<Built, ClankerboxError>;
+}, options?: CreateOptions$1) => Effect.Effect<Prebuilt, ClankerboxError>;
 //#endregion
 //#region src/release.d.ts
 /** Also the version of the clankerbox CLI released with it. */
@@ -96,6 +87,8 @@ export type Overrides = { readonly [K in keyof Sizes]?: Sizes[K] | undefined; }
   readonly setup?: string | undefined;
   readonly setupTimeoutSeconds?: number | undefined;
   readonly host?: string | undefined;
+  /** A public-key file, already resolved, which a setup needs and which is read only for one. */
+  readonly authorizedKeys?: string | undefined;
 };
 export interface SpecRequest {
   readonly spec: MachineSpec;
@@ -116,6 +109,11 @@ export declare const specRequest: (what: string, profile: LoadedProfile | undefi
 export declare const packRecipe: (directory: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem>;
 /** A script file's text, or a recipe directory packed into one script. */
 export declare const readSetup: (path: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem>;
+/**
+ * A public-key file's text, such as `~/.ssh/id_ed25519.pub`'s, for a setup's `authorizedKeys`, with
+ * its line endings as `\n`.
+ */
+export declare const readAuthorizedKeys: (path: string) => Effect.Effect<string, Invalid, FileSystem.FileSystem>;
 //#endregion
 //#region src/ssh.d.ts
 export interface SshTarget {
@@ -154,4 +152,4 @@ export declare const formatMib: (mib: number) => string;
 /** As a size flag takes it: `60G`. */
 export declare const formatGib: (gib: number) => string;
 //#endregion
-export { ActionName, ActionRecord, ActionStatus, Capacity, Checkpoint, ClankerboxError, client_d_exports as Client, Conflict, ConflictKind, CreateRequest, Declared, Host, HostError, Http, Internal, Invalid, Machine, MachineSpec, Missing, NotFound, NotMade, NotOffered, NotReady, PinMismatch, prebuild_d_exports as Prebuild, Reading, Refused, Runtime, ScriptFailed, Setup, SshEndpoint, SshLogin, Unavailable, Unsizable, Usage, WrongState, actionsByName, hostErrors, isReady, readTimeout, retryable, stateLabel };
+export { Capacity, Checkpoint, ClankerboxError, client_d_exports as Client, Conflict, CreateRequest, Declared, Desired, Host, HostError, Http, Internal, Invalid, Machine, MachineSpec, Missing, NotFound, NotMade, NotOffered, Phase, PinMismatch, prebuild_d_exports as Prebuild, PrebuildRequest, Prebuilt, PublicKeys, Reading, Refused, Runtime, ScriptFailed, Setup, SshEndpoint, SshLogin, Superseded, TailnetStatus, Unavailable, Unsizable, Usage, WrongState, actionsByName, hostErrors, readTimeout, retryable, stateLabel };