warpmetal 0.8.7 → 0.8.9

package/README.md

@@ -103,6 +103,19 @@ key does not encode a login username: use `root@<server-ip>` for an owner shell
 and `--ssh-user root` for runtime installation, not a distribution convention
 such as `ubuntu`.
 
+Starting in CLI 0.8.8, `runtime install --confirm INSTALL` establishes managed
+SSH host trust without requiring access to the VPS provider. For a server trust
+epoch with no pin, the CLI runs only a harmless `ssh true` using the exact owner
+key, trusts the first observed Ed25519 host key, stores it under the private
+WarpMetal state directory, and immediately reconnects with strict checking. It
+requests the Runtime bootstrap only after that strict replay succeeds. Every
+later SSH and SCP operation must match the same pin; a changed key is never
+silently accepted or overwritten.
+
+The private WarpMetal state directory is the local trust domain. Back it up
+with the owner key: deleting it also deletes the durable pin, so the next
+install is a new first-use decision rather than a verified continuation.
+
 Pass `--json` for structured, secret-redacted output. Use
 `WARPMETAL_API_URL` for an alternate API origin and `WARPMETAL_HOME` for an
 alternate state directory.
@@ -143,11 +156,15 @@ receipt finality while provisioning or renewal proceeds.
 
 For an interactive initial purchase, `checkout challenge` may also return a
 short-lived `humanCheckout` object. Its `url` and `qrPayload` are the same
-`https://pay.x402api.com/c/...` bearer capability for the exact charge; encode
-that URL as the QR, never the WarpMetal recipient address. The buyer connects
-their own wallet and needs only the advertised USDC/USDT balance because
-x402api sponsors the native gas. This is an alternative to the agent-wallet
-workflow, not a second payment. After browser payment, run the exact
+`https://pay.x402api.com/c/...` bearer capability for the exact charge.
+Present the exact URL as a clickable x402api handoff. If a QR is useful for
+another device, encode only the identical `qrPayload` and explain that
+scanning opens the hosted checkout without authorizing payment. x402api owns
+any wallet selection or wallet-specific opening QR inside that page; never
+synthesize a wallet link or encode the WarpMetal recipient address. The buyer
+needs only the advertised USDC/USDT balance because x402api sponsors the native
+gas. This is an alternative to the agent-wallet workflow, not a second
+payment. After browser payment, run the exact
 `humanCheckout.afterPayment.argv` status command. When the ready result asks
 for `ask_human_for_notification_email`, ask the owner and add the optional
 lifecycle-notification address they provide. Autonomous purchases and renewals
@@ -300,8 +317,9 @@ compatible external signer.
   Wallet key management and signing remain outside this package.
 - Destructive or state-changing commands require explicit confirmations and
   generate idempotency keys by default.
-- Runtime bootstrap credentials remain memory-only. Signed supervisor bundles
-  are checksum- and signature-verified before OpenSSH uploads them.
+- Runtime bootstrap credentials remain memory-only and are requested only after
+  the first host key has been pinned and strictly reverified. Signed supervisor
+  bundles are checksum- and signature-verified before OpenSSH uploads them.
 - Each agent gets a distinct SSH key forced into exactly one sandbox. Token-free
   connection profiles pin the VPS host key and contain no owner credential or
   private-key material.
@@ -315,10 +333,10 @@ compatible external signer.
   the observed digest and generation both match the accepted target.
 - Guarded reload powers the server off first. Runtime-enabled reload requires a
   second acknowledgment, after which the CLI guides supervisor reinstall and
-  pinned connection-profile refresh. Post-reload owner SSH host keys must be
-  independently verified because the provider may rotate or preserve them;
-  update `known_hosts` only when the verified key changed. Erased workspaces
-  are never described as recoverable.
+  pinned connection-profile refresh. Only a locally recorded reload operation
+  that succeeds and reports an owner-host-key refresh opens one new managed
+  trust epoch; failed or ambiguous reloads retain the old pin and never permit
+  replacement. Erased workspaces are never described as recoverable.
 
 ## Agent Runtime example
 
@@ -349,6 +367,13 @@ warpmetal sandbox access keygen \
   --json
 ```
 
+On the first install in a server trust epoch, JSON output includes
+`hostKeyTrust.state: "trusted_first_use"` and the safe Ed25519 fingerprint.
+Later installs report `"matched"`. First-use trust protects continuity after
+that observation, but it cannot detect an active attacker on the first
+connection. Provider-console host-key pre-enrollment remains an optional
+higher-assurance alternative when it is available.
+
 WarpMetal CLI v0.8.7 with Agent Runtime v0.1.25 or newer can enable the narrowly
 scoped AppArmor exception required by a verified workload that creates an inner
 Bubblewrap PID namespace and private `/proc`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "check": "node --check bin/warpmetal.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/connection.js && node --check src/errors.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/payment.js && node --check src/runtime.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js",
+    "check": "node --check bin/warpmetal.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/connection.js && node --check src/errors.js && node --check src/host-trust.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/payment.js && node --check src/runtime.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js",
     "plugin:check": "node --test test/plugin.test.js",
     "test": "node --test",
     "prepack": "npm run check && npm test"

package/skills/warpmetal/SKILL.md

@@ -90,11 +90,14 @@ open either file.
 
 In an interactive initial purchase, the result may also contain
 `humanCheckout`. Offer it as an alternative to the local agent wallet. Show
-`humanCheckout.url` as clickable text and render only the identical
-`humanCheckout.qrPayload` URL as the purchase QR; never render the recipient
-address as this QR. The URL is an expiring bearer capability, so do not log,
-save, or send it anywhere except to the buyer who requested this purchase. If
-the buyer uses it, do not authorize or submit through the agent wallet. Run the
+`humanCheckout.url` as clickable x402api text. If another-device acquisition
+is useful, render only the identical `humanCheckout.qrPayload` URL as a QR and
+explain that scanning opens the hosted checkout without authorizing payment.
+x402api owns any wallet selection and wallet-specific opening QR inside that
+page; never synthesize a wallet link or render the recipient address as this
+QR. The URL is an expiring bearer capability, so do not log, save, or send it
+anywhere except to the buyer who requested this purchase. If the buyer uses it,
+do not authorize or submit through the agent wallet. Run the
 exact `humanCheckout.afterPayment.argv` command, wait for the server to become
 ready, then follow `ask_human_for_notification_email`: ask the owner for the
 optional lifecycle-notification address and add only the address they provide.
@@ -266,11 +269,13 @@ warpmetal server reload \
 ```
 
 The CLI requires the recovery owner credential so it can keep polling after
-reload revokes SSH-derived access tokens. On success, reinstall Agent Runtime
-only after verifying the post-reload owner-facing SSH host-key fingerprint
-through a trusted provider or console channel. The provider may rotate or
-preserve the key; update `known_hosts` only when the verified key changed and
-never bypass a mismatch. Then wait for grants to become applied and refresh
+reload revokes SSH-derived access tokens. CLI 0.8.8 records a new SSH trust
+epoch only when that exact local reload operation succeeds and reports that the
+owner host key needs refresh. The next Runtime install may trust the first
+observed Ed25519 host key once in that epoch, then must reconnect strictly
+before requesting bootstrap. Failed or ambiguous reloads retain the prior pin;
+never bypass a mismatch or delete a pin to force a retry. A provider-console
+pre-seed is the optional higher-assurance path. Then wait for grants to become applied and refresh
 every connection profile with `sandbox access refresh --confirm REFRESH`
 before connecting. Do not fall back to raw API calls for deletion, networking,
 or another unsupported mutation.
@@ -283,6 +288,14 @@ sizes. Use `--runtime-file` to include sandbox intent in an unpaid order, or
 `warpmetal runtime enable` after the VPS is ready. Supervisor installation is
 separate and requires approval plus `--confirm INSTALL`.
 
+With CLI 0.8.8, that confirmation also authorizes managed trust on first use
+when the exact server trust epoch has no pin. The CLI performs only an owner-
+key-authenticated `ssh true`, pins the first observed Ed25519 key, immediately
+reconnects strictly, and requests bootstrap only afterward. Later connections
+must match. Explain that TOFU cannot detect an active attacker on the first
+connection; never use `ssh-keyscan`, accept a mismatch, or expose a generic pin
+reset.
+
 For any verified workload that creates an inner Bubblewrap PID namespace and
 private `/proc`, CLI 0.8.7 with Runtime 0.1.25 or newer may add
 `--nested-private-procfs enable` to the approved Runtime install. Planning with

package/skills/warpmetal/references/cli-reference.md

@@ -75,8 +75,11 @@ workflow.
 For interactive initial purchases, the response may additionally include
 `humanCheckout.url`, the identical `qrPayload`, `expiresAt`, and an exact
 `afterPayment.argv` command. The URL is a short-lived bearer capability for the
-same charge, not a recipient address. If the buyer pays in the hosted checkout,
-do not submit an agent-wallet artifact; run the returned status command and,
+same charge, not a recipient address. Present the URL as a clickable x402api
+handoff. An optional QR contains that exact web link for another-device
+acquisition; scanning it does not authorize payment, and x402api owns any
+wallet-specific choices inside the hosted page. If the buyer pays there, do not
+submit an agent-wallet artifact; run the returned status command and,
 after ready, follow `ask_human_for_notification_email` to offer lifecycle
 notices. The CLI does not persist the hosted URL. Renewal commands never expose
 or use this interactive option.
@@ -232,6 +235,16 @@ warpmetal sandbox delete \
   --server <serverId> --sandbox <sandboxId> --confirm DELETE [--wait] --json
 ```
 
+CLI 0.8.8 manages owner-facing VPS host trust during `runtime install`. With no
+pin for the exact server trust epoch, the confirmed install performs one
+harmless owner-key-authenticated SSH connection, trusts the first observed
+Ed25519 host key, atomically pins it, and immediately reconnects strictly before
+requesting bootstrap. JSON reports `hostKeyTrust.state` as
+`trusted_first_use` or `matched` plus the safe fingerprint. Every later SSH and
+SCP operation is strict; changed keys, malformed pins, and failed or ambiguous
+reloads never replace trust. This TOFU step cannot detect an active attacker on
+the first connection. Provider-console pre-enrollment is optional and stronger.
+
 The nested-private-procfs action requires CLI 0.8.7 and Runtime 0.1.25 or
 newer. It defaults to `preserve`. `enable` is a host-level opt-in for any
 verified workload that creates an inner Bubblewrap PID namespace and private

package/skills/warpmetal/references/payments.md

@@ -125,9 +125,13 @@ argv arrays returned under `paymentWorkflow`:
 
 For an interactive initial purchase, an optional `humanCheckout` object offers
 a second presentation path for the same charge. Its `url` and `qrPayload` must
-be identical hosted-checkout URLs; render that URL as the QR and copyable link,
-never a recipient address. If the buyer completes this path, skip agent-wallet
-authorization and run `humanCheckout.afterPayment.argv`. Continue bounded
+be identical hosted-checkout URLs. Present `url` as the clickable x402api
+handoff. If a QR is useful for another device, render only the exact
+`qrPayload` and explain that scanning opens the checkout without authorizing
+payment. x402api owns wallet selection and any wallet-specific opening QR
+inside that page; never synthesize a wallet link or render a recipient address.
+If the buyer completes this path, skip agent-wallet authorization and run
+`humanCheckout.afterPayment.argv`. Continue bounded
 status polling until ready, then ask for the optional lifecycle-notification
 email when the result returns `ask_human_for_notification_email`. The hosted
 URL expires at `humanCheckout.expiresAt`, is not persisted by the CLI, and is

package/skills/warpmetal/references/runtime.md

@@ -65,9 +65,21 @@ warpmetal runtime get --server <serverId> --wait --json
 ```
 
 Ask before installation. Pass the owner key path without reading the file.
-The CLI holds the one-time bootstrap only in memory, verifies the signed
-artifact, uploads it through OpenSSH without a shell-enabled local spawn, and
-does not print or store the bootstrap.
+CLI 0.8.8 first validates that the public half matches the server's ordering-key
+fingerprint. When that server trust epoch has no pin, it runs only an owner-key-
+authenticated `ssh true`, trusts the first observed Ed25519 host key, publishes
+it atomically under the private WarpMetal state directory, and immediately
+reconnects strictly. Only then does the CLI request the one-time bootstrap. It
+holds that bootstrap only in memory, verifies the signed artifact, uploads it
+through OpenSSH without a shell-enabled local spawn, and does not print or store
+the bootstrap. Every later SSH/SCP operation uses the same strict pin; a
+mismatch never overwrites it.
+
+First-use trust provides continuity after the first observation but cannot
+detect an active attacker on that connection. Provider-console pre-enrollment
+is an optional higher-assurance alternative, not a requirement. Only a locally
+recorded successful reload that reports an owner-host-key refresh creates one
+new operation-bound trust epoch; failed or ambiguous reloads do not.
 
 `--nested-private-procfs` is supported by `warpmetal` CLI 0.8.7 with Agent
 Runtime 0.1.25 or newer. Its default is `preserve`, which makes no AppArmor

package/skills/warpmetal/references/safety.md

@@ -99,9 +99,18 @@ the supervisor identity is revoked, desired sandboxes are recreated empty
 after reinstall, and all pinned profiles require refresh. Use only the guarded
 CLI command and stop on `manual_review`. Reload invalidates the prior
 owner-facing SSH host-key trust decision; the provider may rotate or preserve
-the key. Verify the post-reload fingerprint through a trusted provider or
-console channel, change `known_hosts` only when the verified key changed, and
-never disable host-key checking.
+the key. CLI 0.8.8 opens one new managed trust epoch only after the exact local
+reload operation succeeds and reports that refresh is required. The first
+owner-key-authenticated connection may pin the observed Ed25519 key once, then
+all connections are strict. Failed or ambiguous reloads never advance trust.
+Never use `ssh-keyscan`, disable host-key checking, accept a mismatch, or delete
+a pin as a generic reset. Provider-console pre-enrollment remains the optional
+higher-assurance alternative; TOFU cannot detect an active attacker on the
+first connection.
+
+The private WarpMetal state directory is the local trust domain. Deleting it
+removes the durable pin and makes the next install a new first-use decision;
+never present that as continuity with the prior server identity.
 
 An order preparation is unpaid but consumes a limited prepared-order slot.
 Confirm the plan, hostname, OS, and public key before preparing it.

package/src/cli.js

@@ -12,6 +12,7 @@ import {
 import { WarpMetalClient } from "./api.js";
 import { connectionProfile, writeConnectionProfile } from "./connection.js";
 import { CliError, toErrorMessage } from "./errors.js";
+import { establishHostTrust } from "./host-trust.js";
 import { installSkill } from "./install-skill.js";
 import { installRuntime } from "./installer.js";
 import {
@@ -142,6 +143,16 @@ inner Bubblewrap PID namespace and private /proc. Planning, coding, and QA are
 common examples. GitHub access, an AI CLI, and subagent delegation alone do not
 require it. The capability is host-scoped, not per-sandbox.
 
+SSH host trust (CLI 0.8.8+):
+  runtime install authenticates with the exact owner key and trusts the first
+  observed Ed25519 host key once for that server trust epoch. It pins the key
+  before requesting a Runtime bootstrap, immediately reconnects strictly, and
+  requires that same pin thereafter. A changed key is never accepted or
+  overwritten. A successful recorded server reload may create one new trust
+  epoch; failed or ambiguous reloads do not. First-use trust cannot detect an
+  active attacker on the first connection. Provider-console pre-enrollment is
+  the optional higher-assurance alternative.
+
 Credential environment variables:
   WARPMETAL_OWNER_TOKEN  Recovery/bootstrap credential for one explicit command
   WARPMETAL_ACCESS_TOKEN Short-lived SSH-derived credential for one explicit command
@@ -876,7 +887,7 @@ async function handleCheckoutChallenge(client, store, options, context) {
     stringOption(options, "request-envelope-out"),
   );
   const directCheckoutInstructions = safe.humanCheckout
-    ? `\nDirect wallet checkout (optional, expires ${safe.humanCheckout.expiresAt}): ${safe.humanCheckout.url}\nEncode only that URL as the purchase QR. After payment, continue with: ${shellCommand(safe.humanCheckout.afterPayment.argv)}. When provisioning is ready, ask the owner for the optional lifecycle-notification email before adding it.`
+    ? `\nHosted human checkout (optional, expires ${safe.humanCheckout.expiresAt}): ${safe.humanCheckout.url}\nOpen this exact x402api link. If another-device acquisition is useful, encode only the returned QR URL; scanning opens the checkout and does not authorize payment. x402api owns wallet selection and explicit approval. After payment, continue with: ${shellCommand(safe.humanCheckout.afterPayment.argv)}. When provisioning is ready, ask the owner for the optional lifecycle-notification email before adding it.`
     : "";
   const paymentInstructions = safe.paymentWorkflow
     ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\n${walletWorkflowInstructions(safe.paymentWorkflow)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize only after selecting/funding one wallet: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
@@ -1939,6 +1950,7 @@ async function applyReloadResult(
   operation,
   pendingIdentityId,
 ) {
+  await store.applyReloadHostTrust(serverId, operation);
   if (operation?.state !== "succeeded") return;
   if (pendingIdentityId) {
     await store.bindIdentity(pendingIdentityId, undefined, serverId);
@@ -2052,10 +2064,12 @@ async function handleServerReload(client, store, options, context) {
     context.json,
     `Reload operation ${operationId}: ${operation?.state}.` +
       (operation?.state === "succeeded" &&
-      operation.result?.reloadImpact?.agentRuntimeAffected
-        ? " Verify and refresh the owner SSH host key, reinstall Agent Runtime, then refresh every sandbox connection profile."
+      operation.result?.reloadImpact?.ownerKnownHostsNeedRefresh
+        ? operation.result?.reloadImpact?.agentRuntimeAffected
+          ? " The next Runtime install will establish the operation-bound owner SSH trust epoch, then reinstall Agent Runtime and refresh every sandbox connection profile."
+          : " The next Runtime install will establish the operation-bound owner SSH trust epoch before reconnecting."
         : operation?.state === "succeeded"
-          ? " Verify and refresh the owner SSH host key before reconnecting."
+          ? " WarpMetal did not report a host-key refresh; the existing managed pin remains required."
           : ""),
   );
   if (operation?.state === "manual_review") return 6;
@@ -2170,6 +2184,20 @@ async function handleRuntimeInstall(client, store, options, context) {
     serverId,
     identity,
   );
+  const server = (await client.getServer(serverId, issued.accessToken)).data
+    ?.task;
+  const trustEpoch = await store.hostTrustEpoch(serverId);
+  const hostKeyTrust = await establishHostTrust({
+    stateDirectory: store.directory,
+    serverId,
+    trustEpoch,
+    server,
+    identityPath: identity,
+    sshUser,
+    reinspectServer: async () =>
+      (await client.getServer(serverId, issued.accessToken)).data?.task,
+    spawnImpl: context.spawnImpl,
+  });
   const key =
     stringOption(options, "idempotency-key") ||
     idempotencyKey("runtime-bootstrap");
@@ -2184,11 +2212,19 @@ async function handleRuntimeInstall(client, store, options, context) {
     token: issued.accessToken,
     identity,
     sshUser,
+    knownHostsFile: hostKeyTrust.knownHostsFile,
+    trustedPublicIp: hostKeyTrust.publicIp,
     bootstrap: bootstrap.data,
     nestedPrivateProcfs,
     fetchImpl: context.fetchImpl,
     spawnImpl: context.spawnImpl,
   });
+  safe.hostKeyTrust = {
+    state: hostKeyTrust.state,
+    algorithm: hostKeyTrust.algorithm,
+    fingerprint: hostKeyTrust.fingerprint,
+    trustEpoch: hostKeyTrust.trustEpoch,
+  };
   let runtimeResult;
   if (booleanOption(options, "wait")) {
     runtimeResult = await pollRuntime(
@@ -2204,7 +2240,7 @@ async function handleRuntimeInstall(client, store, options, context) {
     context.stdout,
     safe,
     context.json,
-    `Installed Agent Runtime ${safe.supervisorVersion} on ${serverId}${safe.runtime ? `: ${safe.runtime.state}` : "."}`,
+    `Installed Agent Runtime ${safe.supervisorVersion} on ${serverId}${safe.runtime ? `: ${safe.runtime.state}` : "."} SSH host key ${safe.hostKeyTrust.state === "trusted_first_use" ? "trusted on first use" : "matched"} (${safe.hostKeyTrust.fingerprint}).`,
   );
   return safe.runtime?.state === "degraded" ? 5 : 0;
 }

package/src/host-trust.js

@@ -0,0 +1,524 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn as nodeSpawn } from "node:child_process";
+import {
+  chmod,
+  link,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  rm,
+  unlink,
+} from "node:fs/promises";
+import { isIP } from "node:net";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import { CliError } from "./errors.js";
+import { readSshPublicKey, sshFingerprint } from "./ssh.js";
+
+const SERVER_ID = /^srv_[A-Za-z0-9_-]{8,60}$/;
+const TRUST_EPOCH = /^(?:initial|reload-[A-Za-z0-9_-]{8,128})$/;
+
+function currentUid() {
+  return typeof process.getuid === "function" ? process.getuid() : undefined;
+}
+
+function exactMode(metadata) {
+  return metadata.mode & 0o777;
+}
+
+async function requirePrivateDirectory(path) {
+  const metadata = await lstat(path);
+  const uid = currentUid();
+  if (
+    !metadata.isDirectory() ||
+    metadata.isSymbolicLink() ||
+    (process.platform !== "win32" && exactMode(metadata) !== 0o700) ||
+    (uid !== undefined && metadata.uid !== uid)
+  ) {
+    throw new CliError("The managed SSH trust directory is not private.", {
+      exitCode: 4,
+      code: "host_trust_directory_unsafe",
+    });
+  }
+}
+
+async function ensurePrivateDirectory(path) {
+  let created = false;
+  try {
+    await mkdir(path, { mode: 0o700 });
+    created = true;
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+  }
+  if (created && process.platform !== "win32") await chmod(path, 0o700);
+  await requirePrivateDirectory(path);
+  if (created) await syncPath(dirname(path));
+}
+
+async function syncPath(path) {
+  const handle = await open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function requirePrivateFile(path, label) {
+  const metadata = await lstat(path);
+  const uid = currentUid();
+  if (
+    !metadata.isFile() ||
+    metadata.isSymbolicLink() ||
+    metadata.nlink !== 1 ||
+    (process.platform !== "win32" && exactMode(metadata) !== 0o600) ||
+    (uid !== undefined && metadata.uid !== uid)
+  ) {
+    throw new CliError(`${label} is not an owner-only regular file.`, {
+      exitCode: 4,
+      code: "host_trust_file_unsafe",
+    });
+  }
+}
+
+async function requireIdentity(identityPath, expectedFingerprint) {
+  const identity = resolve(identityPath);
+  await requirePrivateFile(identity, "The SSH identity");
+  const publicPath = `${identity}.pub`;
+  const publicMetadata = await lstat(publicPath);
+  const uid = currentUid();
+  if (
+    !publicMetadata.isFile() ||
+    publicMetadata.isSymbolicLink() ||
+    publicMetadata.nlink !== 1 ||
+    (uid !== undefined && publicMetadata.uid !== uid)
+  ) {
+    throw new CliError("The SSH public identity is not a safe regular file.", {
+      exitCode: 4,
+      code: "host_trust_identity_unsafe",
+    });
+  }
+  const fingerprint = sshFingerprint(await readSshPublicKey(publicPath));
+  if (fingerprint !== expectedFingerprint) {
+    throw new CliError(
+      "The local SSH identity does not match the server owner key.",
+      { exitCode: 4, code: "host_trust_identity_mismatch" },
+    );
+  }
+  return { identity, fingerprint };
+}
+
+export function hostTrustPaths(stateDirectory, serverId, trustEpoch = "initial") {
+  if (!SERVER_ID.test(serverId)) {
+    throw new CliError("The server ID is invalid.", { exitCode: 2 });
+  }
+  if (!TRUST_EPOCH.test(trustEpoch)) {
+    throw new CliError("The SSH host-trust epoch is invalid.", {
+      exitCode: 4,
+      code: "host_trust_epoch_invalid",
+    });
+  }
+  const stateRoot = resolve(stateDirectory);
+  const sshDirectory = join(stateRoot, "ssh");
+  const knownHostsDirectory = join(sshDirectory, "known-hosts");
+  const serverDirectory = join(knownHostsDirectory, serverId);
+  return {
+    stateRoot,
+    sshDirectory,
+    knownHostsDirectory,
+    serverDirectory,
+    knownHostsFile: join(serverDirectory, `${trustEpoch}.known_hosts`),
+  };
+}
+
+async function ensureTrustDirectories(paths) {
+  await requirePrivateDirectory(paths.stateRoot);
+  await ensurePrivateDirectory(paths.sshDirectory);
+  await ensurePrivateDirectory(paths.knownHostsDirectory);
+  await ensurePrivateDirectory(paths.serverDirectory);
+}
+
+function decodeEd25519(material) {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(material)) return undefined;
+  const decoded = Buffer.from(material, "base64");
+  if (decoded.toString("base64") !== material) return undefined;
+  if (decoded.length !== 51 || decoded.readUInt32BE(0) !== 11) return undefined;
+  if (decoded.subarray(4, 15).toString("utf8") !== "ssh-ed25519") {
+    return undefined;
+  }
+  if (decoded.readUInt32BE(15) !== 32) return undefined;
+  return decoded;
+}
+
+export function validateKnownHosts(content, publicIp, sshPort = 22) {
+  if (isIP(publicIp) !== 4) {
+    throw new CliError("The server returned an invalid public IP.", {
+      exitCode: 3,
+      code: "host_trust_ip_invalid",
+    });
+  }
+  if (!Number.isInteger(sshPort) || sshPort < 1 || sshPort > 65_535) {
+    throw new CliError("The SSH port is invalid.", { exitCode: 2 });
+  }
+  const expectedHost =
+    sshPort === 22 ? publicIp : `[${publicIp}]:${sshPort}`;
+  const lines = String(content).split(/\r?\n/).filter(Boolean);
+  const match = /^([^ ]+) (ssh-ed25519) ([A-Za-z0-9+/]+={0,2})$/.exec(
+    lines[0] || "",
+  );
+  const decoded = match && decodeEd25519(match[3]);
+  if (lines.length !== 1 || !match || match[1] !== expectedHost || !decoded) {
+    throw new CliError("The observed SSH host key is not a canonical Ed25519 pin.", {
+      exitCode: 4,
+      code: "host_trust_pin_invalid",
+    });
+  }
+  return {
+    content: `${match[1]} ${match[2]} ${match[3]}\n`,
+    algorithm: match[2],
+    fingerprint: `SHA256:${createHash("sha256")
+      .update(decoded)
+      .digest("base64")
+      .replace(/=+$/, "")}`,
+  };
+}
+
+export function strictSshOptions(identityPath, knownHostsFile) {
+  if (!isAbsolute(knownHostsFile)) {
+    throw new CliError("The managed SSH host pin path is invalid.", {
+      exitCode: 4,
+      code: "host_trust_path_invalid",
+    });
+  }
+  return [
+    "-F",
+    "/dev/null",
+    "-i",
+    resolve(identityPath),
+    "-o",
+    "IdentitiesOnly=yes",
+    "-o",
+    "IdentityAgent=none",
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "ConnectTimeout=10",
+    "-o",
+    "ConnectionAttempts=1",
+    "-o",
+    "ServerAliveInterval=5",
+    "-o",
+    "ServerAliveCountMax=1",
+    "-o",
+    "PubkeyAuthentication=yes",
+    "-o",
+    "PreferredAuthentications=publickey",
+    "-o",
+    "PasswordAuthentication=no",
+    "-o",
+    "KbdInteractiveAuthentication=no",
+    "-o",
+    "ChallengeResponseAuthentication=no",
+    "-o",
+    "GSSAPIAuthentication=no",
+    "-o",
+    "StrictHostKeyChecking=yes",
+    "-o",
+    `UserKnownHostsFile=${knownHostsFile}`,
+    "-o",
+    "GlobalKnownHostsFile=/dev/null",
+    "-o",
+    "HashKnownHosts=no",
+    "-o",
+    "UpdateHostKeys=no",
+    "-o",
+    "VerifyHostKeyDNS=no",
+    "-o",
+    "HostKeyAlgorithms=ssh-ed25519",
+    "-o",
+    "ForwardAgent=no",
+    "-o",
+    "ForwardX11=no",
+    "-o",
+    "ClearAllForwardings=yes",
+    "-o",
+    "PermitLocalCommand=no",
+    "-o",
+    "ProxyCommand=none",
+    "-o",
+    "RequestTTY=no",
+  ];
+}
+
+function firstUseSshOptions(identityPath, candidatePath) {
+  const args = strictSshOptions(identityPath, candidatePath);
+  const index = args.indexOf("StrictHostKeyChecking=yes");
+  args[index] = "StrictHostKeyChecking=accept-new";
+  return args;
+}
+
+async function spawnSsh(
+  args,
+  spawnImpl,
+  errorMessage,
+  diagnosticDirectory,
+  publicIp,
+  sshPort,
+) {
+  const diagnosticPath = join(
+    diagnosticDirectory,
+    `.ssh-auth.${process.pid}.${randomUUID()}.log`,
+  );
+  const diagnosticHandle = await open(diagnosticPath, "wx", 0o600);
+  await diagnosticHandle.close();
+  let result;
+  try {
+    try {
+      result = await new Promise((resolvePromise, reject) => {
+        const child = spawnImpl("ssh", ["-v", "-E", diagnosticPath, ...args], {
+          shell: false,
+          stdio: ["ignore", "ignore", "ignore"],
+        });
+        child.once("error", reject);
+        child.once("close", (status) => resolvePromise({ status }));
+      });
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        throw new CliError("OpenSSH is required to establish VPS host trust.", {
+          exitCode: 2,
+          code: "host_trust_ssh_unavailable",
+        });
+      }
+      throw error;
+    }
+    if (result.status !== 0) {
+      throw new CliError(errorMessage, {
+        exitCode: 4,
+        code: "host_trust_authentication_failed",
+      });
+    }
+    await requirePrivateFile(diagnosticPath, "The private OpenSSH diagnostic");
+    const diagnostic = await readFile(diagnosticPath, "utf8");
+    const authenticationResults = diagnostic
+      .split(/\r?\n/)
+      .filter((line) => /^Authenticated to .* using "[^"]+"\.$/.test(line));
+    const expectedResult = `Authenticated to ${publicIp} ([${publicIp}]:${sshPort}) using "publickey".`;
+    if (
+      authenticationResults.length !== 1 ||
+      authenticationResults[0] !== expectedResult
+    ) {
+      throw new CliError(
+        "SSH did not prove authentication with the exact owner public key. No runtime bootstrap was requested.",
+        { exitCode: 4, code: "host_trust_authentication_method_invalid" },
+      );
+    }
+  } finally {
+    await rm(diagnosticPath, { force: true });
+  }
+}
+
+async function strictProbe({
+  identity,
+  publicIp,
+  sshPort,
+  sshUser,
+  knownHostsFile,
+  spawnImpl,
+}) {
+  await spawnSsh(
+    [
+      ...strictSshOptions(identity, knownHostsFile),
+      ...(sshPort === 22 ? [] : ["-p", String(sshPort)]),
+      `${sshUser}@${publicIp}`,
+      "true",
+    ],
+    spawnImpl,
+    "The VPS host key or owner SSH authentication did not match the managed pin.",
+    dirname(knownHostsFile),
+    publicIp,
+    sshPort,
+  );
+}
+
+async function publishCandidate(
+  candidatePath,
+  knownHostsFile,
+  expectedContent,
+  publicIp,
+  sshPort,
+) {
+  await syncPath(candidatePath);
+  try {
+    await link(candidatePath, knownHostsFile);
+    await unlink(candidatePath);
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    const existing = validateKnownHosts(
+      await readFile(knownHostsFile, "utf8"),
+      publicIp,
+      sshPort,
+    );
+    if (existing.content !== expectedContent) {
+      throw new CliError("The VPS host key changed during first-use pinning.", {
+        exitCode: 4,
+        code: "host_trust_race_mismatch",
+      });
+    }
+    await unlink(candidatePath);
+  }
+  await requirePrivateFile(knownHostsFile, "The managed SSH host pin");
+  await syncPath(knownHostsFile);
+  await syncPath(resolve(knownHostsFile, ".."));
+}
+
+export async function establishHostTrust({
+  stateDirectory,
+  serverId,
+  trustEpoch = "initial",
+  server,
+  identityPath,
+  sshUser,
+  sshPort = 22,
+  reinspectServer,
+  spawnImpl = nodeSpawn,
+}) {
+  if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(sshUser)) {
+    throw new CliError("--ssh-user is invalid.", { exitCode: 2 });
+  }
+  if (!server || isIP(server.publicIp) !== 4) {
+    throw new CliError("The server returned an invalid public IP.", {
+      exitCode: 3,
+    });
+  }
+  if (!Number.isInteger(sshPort) || sshPort < 1 || sshPort > 65_535) {
+    throw new CliError("The SSH port is invalid.", { exitCode: 2 });
+  }
+  const activeCancellation =
+    ["cancellation_pending", "cancelled"].includes(server.state) &&
+    Number.isFinite(Date.parse(server.termEndsAt || "")) &&
+    Date.parse(server.termEndsAt) > Date.now();
+  if (
+    server.serverId !== serverId ||
+    (server.state !== "ready" && !activeCancellation)
+  ) {
+    throw new CliError(
+      "The VPS must be ready and bound to this server before SSH host trust is established.",
+      { exitCode: 5, code: "host_trust_server_unavailable" },
+    );
+  }
+  if (typeof server.sshFingerprint !== "string") {
+    throw new CliError("The server did not return its owner-key fingerprint.", {
+      exitCode: 3,
+    });
+  }
+  const { identity } = await requireIdentity(
+    identityPath,
+    server.sshFingerprint,
+  );
+  const paths = hostTrustPaths(stateDirectory, serverId, trustEpoch);
+  await ensureTrustDirectories(paths);
+
+  try {
+    await requirePrivateFile(paths.knownHostsFile, "The managed SSH host pin");
+    const pin = validateKnownHosts(
+      await readFile(paths.knownHostsFile, "utf8"),
+      server.publicIp,
+      sshPort,
+    );
+    await strictProbe({
+      identity,
+      publicIp: server.publicIp,
+      sshPort,
+      sshUser,
+      knownHostsFile: paths.knownHostsFile,
+      spawnImpl,
+    });
+    return {
+      state: "matched",
+      algorithm: pin.algorithm,
+      fingerprint: pin.fingerprint,
+      knownHostsFile: paths.knownHostsFile,
+      publicIp: server.publicIp,
+      trustEpoch,
+    };
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+
+  if (typeof reinspectServer !== "function") {
+    throw new CliError(
+      "A fresh server inspection is required before first-use SSH trust can be published.",
+      { exitCode: 4, code: "host_trust_reinspection_required" },
+    );
+  }
+
+  const candidatePath = join(
+    paths.serverDirectory,
+    `.${trustEpoch}.${process.pid}.${randomUUID()}.candidate`,
+  );
+  const handle = await open(candidatePath, "wx", 0o600);
+  await handle.close();
+  try {
+    await spawnSsh(
+      [
+        ...firstUseSshOptions(identity, candidatePath),
+        ...(sshPort === 22 ? [] : ["-p", String(sshPort)]),
+        `${sshUser}@${server.publicIp}`,
+        "true",
+      ],
+      spawnImpl,
+      "Could not authenticate the first SSH connection to the exact VPS. No runtime bootstrap was requested.",
+      paths.serverDirectory,
+      server.publicIp,
+      sshPort,
+    );
+    await requirePrivateFile(candidatePath, "The observed SSH host-key candidate");
+    const pin = validateKnownHosts(
+      await readFile(candidatePath, "utf8"),
+      server.publicIp,
+      sshPort,
+    );
+    const refreshedServer = await reinspectServer();
+    const refreshedCancellation =
+      ["cancellation_pending", "cancelled"].includes(refreshedServer?.state) &&
+      Number.isFinite(Date.parse(refreshedServer?.termEndsAt || "")) &&
+      Date.parse(refreshedServer.termEndsAt) > Date.now();
+    if (
+      refreshedServer?.serverId !== serverId ||
+      (refreshedServer.state !== "ready" && !refreshedCancellation) ||
+      refreshedServer.publicIp !== server.publicIp ||
+      refreshedServer.sshFingerprint !== server.sshFingerprint
+    ) {
+      throw new CliError(
+        "The server identity changed while first-use SSH trust was being established. No host pin or runtime bootstrap was created.",
+        { exitCode: 4, code: "host_trust_server_changed" },
+      );
+    }
+    await publishCandidate(
+      candidatePath,
+      paths.knownHostsFile,
+      pin.content,
+      server.publicIp,
+      sshPort,
+    );
+    await strictProbe({
+      identity,
+      publicIp: server.publicIp,
+      sshPort,
+      sshUser,
+      knownHostsFile: paths.knownHostsFile,
+      spawnImpl,
+    });
+    return {
+      state: "trusted_first_use",
+      algorithm: pin.algorithm,
+      fingerprint: pin.fingerprint,
+      knownHostsFile: paths.knownHostsFile,
+      publicIp: server.publicIp,
+      trustEpoch,
+    };
+  } finally {
+    await rm(candidatePath, { force: true });
+  }
+}

package/src/installer.js

@@ -10,6 +10,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
 import { CliError } from "./errors.js";
+import { strictSshOptions } from "./host-trust.js";
 
 const MAX_ARTIFACT_BYTES = 256 * 1024 * 1024;
 const BASE_REQUIRED_FILES = [
@@ -323,7 +324,7 @@ async function spawnChecked(
   return result;
 }
 
-function sshBase(identity, sshUser, host) {
+function sshBase(identity, sshUser, host, knownHostsFile) {
   if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(sshUser)) {
     throw new CliError("--ssh-user is invalid.", { exitCode: 2 });
   }
@@ -333,16 +334,7 @@ function sshBase(identity, sshUser, host) {
     });
   }
   return [
-    "-i",
-    resolve(identity),
-    "-o",
-    "IdentitiesOnly=yes",
-    "-o",
-    "StrictHostKeyChecking=yes",
-    "-o",
-    "ForwardAgent=no",
-    "-o",
-    "ClearAllForwardings=yes",
+    ...strictSshOptions(resolve(identity), knownHostsFile),
     `${sshUser}@${host}`,
   ];
 }
@@ -353,6 +345,8 @@ export async function installRuntime({
   token,
   identity,
   sshUser,
+  knownHostsFile,
+  trustedPublicIp,
   bootstrap,
   nestedPrivateProcfs = "preserve",
   fetchImpl = globalThis.fetch,
@@ -367,6 +361,12 @@ export async function installRuntime({
       exitCode: 5,
     });
   }
+  if (server.publicIp !== trustedPublicIp) {
+    throw new CliError(
+      "The server public IP changed after SSH host-key trust was established.",
+      { exitCode: 4, code: "host_trust_ip_changed" },
+    );
+  }
   const metadata = validateArtifact(bootstrap?.artifact);
   if (!new Set(["preserve", "enable", "disable"]).has(nestedPrivateProcfs)) {
     throw new CliError("The nested private procfs action is invalid.", {
@@ -400,7 +400,7 @@ export async function installRuntime({
   const remoteID = randomUUID().replaceAll("-", "");
   const remoteArchive = `/tmp/warpmetal-runtime-${remoteID}.tar.gz`;
   const remoteBundle = `/tmp/warpmetal-runtime-${remoteID}`;
-  const ssh = sshBase(identity, sshUser, server.publicIp);
+  const ssh = sshBase(identity, sshUser, server.publicIp, knownHostsFile);
   let remoteTouched = false;
   let operationFailed = false;
   try {

package/src/state.js

@@ -5,7 +5,7 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 
 import { CliError } from "./errors.js";
 
-const STATE_VERSION = 3;
+const STATE_VERSION = 4;
 const WALLET_PAYMENT_STATE_FIELDS = [
   "walletPaymentAttemptId",
   "walletBuyerPaymentIdentifier",
@@ -160,6 +160,19 @@ function migrateState(value) {
       renewals: {},
     };
   }
+  if (
+    value?.version === 3 &&
+    value.orders &&
+    value.servers &&
+    value.operations &&
+    value.runtimes &&
+    value.sandboxes &&
+    value.accessGrants &&
+    value.identities &&
+    value.renewals
+  ) {
+    return { ...value, version: STATE_VERSION };
+  }
   return value;
 }
 
@@ -597,6 +610,46 @@ export class StateStore {
         ...metadata,
         createdAt: new Date().toISOString(),
       };
+      if (kind === "reload") {
+        const server = state.servers[serverId] || { serverId };
+        server.pendingHostTrustReloadOperationId = operationId;
+        state.servers[serverId] = server;
+      }
+    });
+  }
+
+  async hostTrustEpoch(serverId) {
+    return (await this.server(serverId))?.hostTrustEpoch || "initial";
+  }
+
+  async applyReloadHostTrust(serverId, operation) {
+    const operationId = operation?.id;
+    if (
+      typeof operationId !== "string" ||
+      !["succeeded", "failed", "manual_review"].includes(operation?.state)
+    ) {
+      return;
+    }
+    await this.update((state) => {
+      const saved = state.operations[operationId];
+      const server = state.servers[serverId];
+      if (
+        !saved ||
+        saved.serverId !== serverId ||
+        saved.kind !== "reload" ||
+        !server ||
+        server.pendingHostTrustReloadOperationId !== operationId
+      ) {
+        return;
+      }
+      if (
+        operation.state === "succeeded" &&
+        operation.result?.reloadImpact?.ownerKnownHostsNeedRefresh === true
+      ) {
+        server.hostTrustEpoch = `reload-${operationId}`;
+        server.hostTrustReloadOperationId = operationId;
+      }
+      delete server.pendingHostTrustReloadOperationId;
     });
   }