@prismnetwork/agent-sdk 0.3.1 → 0.4.0

package/README.md

@@ -29,6 +29,16 @@ agent.endLease(lease);
 
 `image` must be an immutable digest-pinned reference (`repo@sha256:...`). `DEFAULT_IMAGE` is one; a plain tag is rejected.
 
+## Toolset
+
+`@prismnetwork/agent-sdk/toolset` exports `PrismToolset`, the framework-neutral
+tool surface the MCP server and the framework plugins (elizaOS, Virtuals GAME)
+wrap: `wallet`, `listGpus`, `leaseAndRun`, `run`, `endLease`, each returning a
+human-readable string. It holds the wallet, the open leases and the per-lease
+spending cap in one place, reads `PRISM_AGENT_KEY`/`PRISM_ESCROW` from the
+environment by default, and answers the read-only questions from the public API
+when no wallet is configured.
+
 ## Vault
 
 Cards, identity documents, API credentials and recovery codes go in the vault
@@ -65,6 +75,62 @@ ciphertext, so a service that moved an item between accounts, replayed an older
 version, or lowered its floor would produce a failed decrypt rather than a
 plausible wrong answer. See [docs/VAULT.md](../docs/VAULT.md).
 
+## Workspaces
+
+A lease destroys its machine, so training output, checkpoints and a working
+directory need somewhere that outlives it. A workspace is that place: the SDK
+archives a directory off the leased box, seals it here under a key derived from
+your wallet, and uploads the ciphertext straight to object storage. Prism
+records the version, the size and the hash, and holds nothing that opens it.
+
+```js
+await agent.workspace.unlock();
+
+const ws = await agent.workspace.create("finetune-run");
+const saved = await agent.workspace.save(lease, ws, "/root/out");
+
+// On a later lease, onto a fresh machine.
+await agent.workspace.restore(next, ws, "/root/out", { expectVersion: saved.version });
+```
+
+The workspace key comes from a different statement and a different salt than
+the vault's, so opening one does not open the other. Pass `{ passphrase }` to
+require a second factor beyond the wallet.
+
+A restore hashes the downloaded ciphertext and compares it to the digest
+recorded at save time before it decrypts anything, so bytes altered in storage
+are reported as tampering rather than as a wrong key. The account, workspace,
+version and trust floor are authenticated into the ciphertext, so a snapshot
+served for the wrong workspace, or under a floor that has been rewritten, fails
+to open rather than returning a plausible wrong answer.
+
+An older snapshot is a different case worth being precise about: its own
+associated data is genuine for its own version, so it decrypts cleanly and
+nothing in the ciphertext gives it away. A restore therefore compares the
+version it was granted against the version the record says is current, and
+refuses a rollback on that basis. Pass `expectVersion` to pin a specific one,
+and `expectTrustClass` to refuse a floor that has moved.
+
+A restore names the lease it is landing on, and Prism refuses to issue the
+download at all when that lease's trust class is below the workspace's floor.
+The check is server-side deliberately: a client-side one would be a courtesy
+that a modified client could skip.
+
+Bulk data never passes through Prism. Uploads and downloads use presigned URLs
+that live fifteen minutes, and they are used from your process, never handed to
+the leased machine. The machine only ever sees `tar` and `base64`, which is all
+this needs from it.
+
+Snapshots travel over the lease's SSH channel, which caps a single save at 64
+MiB of archive; a larger directory is refused on the machine before anything is
+transferred. New workspaces default to the `open` trust floor, unlike vault
+items: their contents are the files you are already handing to a rented box.
+Raise it at creation when they deserve more:
+
+```js
+await agent.workspace.create("model-weights", { minTrustClass: "isolated" });
+```
+
 ## Auth
 
 `authenticate()` fetches a challenge (`GET /api/agent/challenge`), signs the message with the wallet, and exchanges it for a session (`POST /api/agent/session`). The session is a bearer token used on every `/api/agent/proxy/*` call. No shared secret, no cookie. The wallet is the identity (`subject = wallet:0x...`).
@@ -79,6 +145,7 @@ The wallet needs two balances on Robinhood Chain (id 4663): USDG (`0x5fc5360D040
 
 ## Requirements
 
-Node >= 20, `viem` ^2 (peer), and `ssh` + `ssh-keygen` on PATH for `run()`.
+Node >= 20, `viem` ^2 (peer), and `ssh` + `ssh-keygen` on PATH for `run()` and
+for workspace save and restore.
 
 See `example.mjs` for a full run.

package/package.json

@@ -1,20 +1,28 @@
 {
   "name": "@prismnetwork/agent-sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Headless GPU leasing and renter-encrypted storage on Prism Network for wallet-holding agents.",
   "type": "module",
   "main": "prism.mjs",
   "exports": {
     ".": "./prism.mjs",
+    "./toolset": "./toolset.mjs",
     "./vault": {
       "types": "./vault.d.ts",
       "default": "./vault.mjs"
+    },
+    "./workspace": {
+      "types": "./workspace.d.ts",
+      "default": "./workspace.mjs"
     }
   },
   "files": [
     "prism.mjs",
+    "toolset.mjs",
     "vault.mjs",
     "vault.d.ts",
+    "workspace.mjs",
+    "workspace.d.ts",
     "README.md"
   ],
   "engines": {

package/prism.mjs

@@ -15,8 +15,15 @@ import {
 } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { PrismVault } from "./vault.mjs";
+import { PrismWorkspace } from "./workspace.mjs";
 
 export { PrismVault, VaultError, DEFAULT_TRUST_FLOOR, VAULT_KEY_STATEMENT } from "./vault.mjs";
+export {
+  PrismWorkspace,
+  WorkspaceError,
+  DEFAULT_WORKSPACE_TRUST_FLOOR,
+  WORKSPACE_KEY_STATEMENT,
+} from "./workspace.mjs";
 
 export const robinhoodChain = defineChain({
   id: 4663,
@@ -108,14 +115,16 @@ export class PrismAgent {
     this.walletClient = createWalletClient({ account: this.account, chain: robinhoodChain, transport });
     this.session = null;
     this.vault = new PrismVault(this);
+    this.workspace = new PrismWorkspace(this);
   }
 
   get address() {
     return this.account.address;
   }
 
-  // The vault key is derived from this signature on the caller's machine. It is
-  // returned to the vault client and never sent anywhere.
+  // The vault and workspace keys are derived from this signature on the
+  // caller's machine. It is returned to the client that asked and never sent
+  // anywhere.
   async signVaultStatement(statement) {
     return this.account.signMessage({ message: statement });
   }
@@ -124,6 +133,10 @@ export class PrismAgent {
     return this.#proxy(method, ["vault", ...segments], { body });
   }
 
+  async workspaceRequest(method, segments, { body = null } = {}) {
+    return this.#proxy(method, ["workspaces", ...segments], { body });
+  }
+
   async authenticate() {
     const challenge = await this.#json(`/api/agent/challenge?address=${this.address}`);
     const signature = await this.account.signMessage({ message: challenge.message });
@@ -331,8 +344,9 @@ export class PrismAgent {
 
   // Run a command in the remote login shell over SSH (so pipes, redirects, and
   // $(...) all evaluate on the GPU). Retries through the host's sshd warmup, which
-  // can lag a few minutes after the box reports ready.
-  async run(lease, command, { timeoutMs = 120_000, connectRetries = 24, connectDelayMs = 10_000 } = {}) {
+  // can lag a few minutes after the box reports ready. `stdin` feeds the command
+  // its input, which keeps anything sensitive out of the remote process table.
+  async run(lease, command, { timeoutMs = 120_000, connectRetries = 24, connectDelayMs = 10_000, stdin = null } = {}) {
     if (!lease?.access?.ssh_host || !lease.access.ssh_port || !lease.keyPath) {
       throw new PrismError(400, "invalid_lease_handle");
     }
@@ -345,7 +359,7 @@ export class PrismAgent {
     };
     let last;
     for (let attempt = 0; attempt <= connectRetries; attempt++) {
-      const res = await this.#ssh(target, command, timeoutMs);
+      const res = await this.#ssh(target, command, timeoutMs, stdin);
       if (!isSshWarmup(res)) return res;
       last = res;
       if (attempt < connectRetries) await sleep(connectDelayMs);
@@ -376,7 +390,7 @@ export class PrismAgent {
     }
   }
 
-  #ssh(target, command, timeoutMs) {
+  #ssh(target, command, timeoutMs, stdin = null) {
     const args = [
       "-i", target.keyPath,
       "-p", String(target.port),
@@ -398,6 +412,12 @@ export class PrismAgent {
       }, timeoutMs);
       child.stdout.on("data", (d) => (stdout += d));
       child.stderr.on("data", (d) => (stderr += d));
+      if (stdin !== null) {
+        // A command that exits before reading its input closes the pipe, which
+        // is a normal end to the transfer and not a failure to report.
+        child.stdin.on("error", () => {});
+        child.stdin.end(stdin);
+      }
       child.on("close", (code) => {
         clearTimeout(timer);
         resolve({ code: code ?? -1, stdout: stdout.trim(), stderr: stderr.trim(), timedOut });

package/toolset.mjs

@@ -0,0 +1,108 @@
+// A framework-neutral tool surface over PrismAgent. Agent frameworks disagree
+// about how a tool is declared but agree about what one is: a named function
+// with typed arguments that returns text. PrismToolset holds the wallet, the
+// open leases, and the spending cap in one place so framework plugins stay
+// thin wrappers instead of diverging copies of the same logic.
+//
+// Without a wallet it still answers the read-only questions (capacity, prices)
+// from the public API, the same degradation the MCP server offers.
+import { DEFAULT_IMAGE, PrismAgent, TRUST_CLASSES } from "./prism.mjs";
+
+export const DEFAULT_ESCROW = "0x62C042265991bEa17B07229322A01850974626dA";
+export const PUBLIC_API = "https://api.prismnetwork.tech";
+
+const MICROS = 1_000_000;
+const usdg = (micros) => `${(Number(micros) / MICROS).toFixed(6)} USDG`;
+
+export function agentFromEnv() {
+  const privateKey = process.env.PRISM_AGENT_KEY;
+  if (!privateKey) return null;
+  return new PrismAgent({ privateKey, escrow: process.env.PRISM_ESCROW ?? DEFAULT_ESCROW });
+}
+
+const NO_WALLET =
+  "No wallet is configured, so this needs PRISM_AGENT_KEY (a funded wallet on Robinhood Chain). " +
+  "Looking at capacity and prices works without one.";
+
+export class PrismToolset {
+  #agent;
+  #leases = new Map();
+  #publicApi;
+
+  constructor({ agent, publicApi = PUBLIC_API } = {}) {
+    this.#agent = agent === undefined ? agentFromEnv() : agent;
+    this.#publicApi = publicApi;
+  }
+
+  get agent() {
+    return this.#agent;
+  }
+
+  async wallet() {
+    if (!this.#agent) return NO_WALLET;
+    const b = await this.#agent.balances();
+    return `address: ${b.address}\nusdg: ${usdg(b.usdg)}\neth: ${(Number(b.eth) / 1e18).toFixed(6)} for gas`;
+  }
+
+  async listGpus(minTrust = "open") {
+    if (!TRUST_CLASSES.includes(minTrust)) {
+      return `min_trust must be one of ${TRUST_CLASSES.join(", ")}`;
+    }
+    let offers;
+    if (this.#agent) {
+      offers = await this.#agent.offers({ minTrust });
+    } else {
+      const url = new URL("/v1/offers", this.#publicApi);
+      url.searchParams.set("min_trust", minTrust);
+      const res = await fetch(url, { headers: { accept: "application/json" } });
+      if (!res.ok) return `Prism capacity is unreachable right now (${res.status}).`;
+      offers = await res.json();
+    }
+    if (!offers.length) return "No GPUs are online to rent right now.";
+    return offers
+      .map((o) => {
+        const perHr = ((Number(o.rate_per_second) * 3600) / MICROS).toFixed(2);
+        return `${o.gpu.model} · ${o.gpu.vram_mib} MiB · $${perHr}/hr · ${o.trust_class ?? "open"}`;
+      })
+      .join("\n");
+  }
+
+  async leaseAndRun({
+    command,
+    durationSeconds = 600,
+    minVramMib = 16000,
+    image = DEFAULT_IMAGE,
+    maxUsdg = 1,
+    minTrustClass = "open",
+  }) {
+    if (!this.#agent) return NO_WALLET;
+    const lease = await this.#agent.lease({
+      image,
+      durationSeconds,
+      minVramMib,
+      maxDeposit: Math.round(maxUsdg * MICROS),
+      minTrustClass,
+    });
+    this.#leases.set(lease.leaseId, lease);
+    const res = await this.#agent.run(lease, command);
+    const out = res.stdout || res.stderr || "";
+    return `lease ${lease.leaseId} funded onchain (tx ${lease.fundingHash}), exit ${res.code}:\n${out}`;
+  }
+
+  async run(leaseId, command) {
+    if (!this.#agent) return NO_WALLET;
+    const lease = this.#leases.get(leaseId);
+    if (!lease) return `No active lease ${leaseId} in this session.`;
+    const res = await this.#agent.run(lease, command);
+    return `exit ${res.code}:\n${res.stdout || res.stderr || ""}`;
+  }
+
+  endLease(leaseId) {
+    if (!this.#agent) return NO_WALLET;
+    const lease = this.#leases.get(leaseId);
+    if (!lease) return `No active lease ${leaseId} in this session.`;
+    this.#agent.endLease(lease);
+    this.#leases.delete(leaseId);
+    return `released lease ${leaseId}`;
+  }
+}

package/workspace.d.ts

@@ -0,0 +1,101 @@
+export type TrustFloor = "open" | "isolated" | "attested" | "confidential";
+
+export type WorkspaceSnapshot = {
+  wrapped_key: string;
+  nonce: string;
+  ciphertext_digest: string;
+  size_bytes: number;
+};
+
+export type Workspace = {
+  workspace_id: string;
+  name: string;
+  version: number;
+  snapshot?: WorkspaceSnapshot;
+  min_trust_class: TrustFloor;
+  created_at: string;
+  updated_at: string;
+};
+
+/// A presigned upload, valid for fifteen minutes. `version` is the one storage
+/// will accept, and it is authenticated into the ciphertext, so the snapshot is
+/// sealed after this arrives rather than before.
+export type WorkspaceUploadGrant = {
+  url: string;
+  version: number;
+  key: string;
+};
+
+export type WorkspaceDownloadGrant = WorkspaceSnapshot & {
+  url: string;
+  version: number;
+};
+
+/// The handle an interactive `lease()` returns. `save` and `restore` reach the
+/// machine over SSH, which a batch lease has no key for.
+export type LeaseHandle = {
+  access: { ssh_host: string; ssh_port: number; ssh_user?: string };
+  keyPath: string;
+};
+
+/// What the workspace client needs from its caller: an address, a way to sign,
+/// a way to reach the control plane, and, for `save` and `restore`, a way to
+/// reach the leased machine. `signVaultStatement` is the generic "sign this
+/// statement" hook the vault also uses; the statement differs, so the keys do.
+export type WorkspaceTransport = {
+  address: string;
+  session: unknown;
+  authenticate: () => Promise<unknown>;
+  signVaultStatement: (statement: string) => Promise<string>;
+  workspaceRequest: (method: string, segments: string[], options?: { body?: unknown }) => Promise<any>;
+  run?: (
+    lease: LeaseHandle,
+    command: string,
+    options?: { timeoutMs?: number; stdin?: string | null },
+  ) => Promise<{ code: number; stdout: string; stderr: string; timedOut: boolean }>;
+};
+
+export declare const WORKSPACE_ENVELOPE_DOMAIN: string;
+export declare const WORKSPACE_KEY_STATEMENT: string;
+export declare const DEFAULT_WORKSPACE_TRUST_FLOOR: TrustFloor;
+
+export declare function workspaceAssociatedData(
+  wallet: string,
+  workspaceId: string,
+  version: number,
+  trustFloor: TrustFloor,
+): Uint8Array;
+
+export declare class PrismWorkspace {
+  constructor(transport: WorkspaceTransport);
+  readonly unlocked: boolean;
+  readonly wallet: string | null;
+  unlock(options?: { passphrase?: string | null }): Promise<this>;
+  lock(): void;
+  list(): Promise<Workspace[]>;
+  get(workspaceId: string | Workspace): Promise<Workspace>;
+  create(name: string, options?: { minTrustClass?: TrustFloor }): Promise<Workspace>;
+  remove(workspaceId: string | Workspace): Promise<null>;
+  save(
+    lease: LeaseHandle,
+    workspaceId: string | Workspace,
+    remotePath: string,
+    options?: { timeoutMs?: number },
+  ): Promise<Workspace>;
+  restore(
+    lease: LeaseHandle,
+    workspaceId: string | Workspace,
+    remotePath: string,
+    options?: {
+      expectVersion?: number | null;
+      expectTrustClass?: TrustFloor | null;
+      timeoutMs?: number;
+    },
+  ): Promise<Workspace>;
+  static permits(trustFloor: TrustFloor, leaseTrustClass: TrustFloor): boolean;
+}
+
+export declare class WorkspaceError extends Error {
+  readonly code: string;
+  readonly body?: unknown;
+}

package/workspace.mjs

@@ -0,0 +1,503 @@
+// Durable storage for a renter. A lease destroys its machine, so anything worth
+// keeping is archived off it, sealed here on the renter's own machine, and
+// pushed to object storage as ciphertext. Prism records how large a snapshot is
+// and which version it is, and holds nothing that opens it.
+//
+// The bulk path runs through this process rather than through the leased box on
+// purpose. A presigned URL is a bearer capability with a fifteen minute life;
+// handing one to a rented machine would put it in that host's process table and
+// give its operator read and write on the object for the rest of the window.
+import { vaultWallet } from "./vault.mjs";
+
+const { subtle } = globalThis.crypto;
+
+export const WORKSPACE_ENVELOPE_DOMAIN = "prism.workspace.v1\0";
+
+// A signature over this exact string is the workspace key. It is not the vault
+// statement and it does not salt the same way, so a wallet that has opened a
+// vault has not opened its workspaces, and neither signature derives the other.
+export const WORKSPACE_KEY_STATEMENT = [
+  "Prism Network workspace key",
+  "",
+  "Signing this derives the key that encrypts your Prism workspaces. It is computed",
+  "on this machine and never sent. Anyone who gets this signature can read every",
+  "snapshot you have stored, so only sign it in software you trust.",
+  "",
+  "domain: prism.workspace.kdf.v1",
+].join("\n");
+
+// A workspace holds the working files a renter is already handing to a rented
+// machine. The vault's default of a class no live capacity meets would mean a
+// workspace could never be restored, so this one starts at the floor and is
+// raised per workspace when the contents deserve it.
+export const DEFAULT_WORKSPACE_TRUST_FLOOR = "open";
+
+const TRUST_ORDER = ["open", "isolated", "attested", "confidential"];
+
+// The protocol allows 64 GiB per snapshot. This client carries the archive over
+// the lease's SSH channel and holds it in memory to seal it, so it stops well
+// short of that and says so rather than dying of a failed allocation.
+const MAX_TRANSFER_BYTES = 64 * 1024 * 1024;
+const MAX_NAME_BYTES = 64;
+
+// Matches the presigned URL's own life: a transfer that has not finished by
+// then cannot finish at all.
+const TRANSFER_TIMEOUT_MS = 900_000;
+const REMOTE_TIMEOUT_MS = 900_000;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+const encoder = new TextEncoder();
+
+// Chunked because a large archive would otherwise spread into more arguments
+// than an engine will accept in one call.
+function base64(bytes) {
+  let binary = "";
+  for (let index = 0; index < bytes.length; index += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+  }
+  return btoa(binary);
+}
+
+function b64url(bytes) {
+  return base64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// Takes both alphabets: the control plane sends base64url, and `base64` on the
+// leased machine wraps standard base64 across lines.
+function fromB64(value) {
+  const binary = atob(value.replace(/\s+/g, "").replace(/-/g, "+").replace(/_/g, "/"));
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+function fromHex(value) {
+  const digits = value.replace(/^0x/, "");
+  if (digits.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(digits)) {
+    throw new WorkspaceError("invalid_signature_encoding");
+  }
+  const bytes = new Uint8Array(digits.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(digits.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+async function sha256Hex(bytes) {
+  const digest = new Uint8Array(await subtle.digest("SHA-256", bytes));
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/// Mirrors `workspace_associated_data` in prism-protocol byte for byte. A
+/// shared test vector pins both; if they drift, stored snapshots stop opening.
+export function workspaceAssociatedData(wallet, workspaceId, version, trustFloor) {
+  return encoder.encode(
+    `${WORKSPACE_ENVELOPE_DOMAIN}${wallet}\0${workspaceId}\0${version}\0${trustFloor}\0`,
+  );
+}
+
+function assertTrustFloor(value) {
+  if (!TRUST_ORDER.includes(value)) {
+    throw new WorkspaceError("invalid_trust_floor", { expected: TRUST_ORDER });
+  }
+  return value;
+}
+
+function meetsFloor(floor, leaseClass) {
+  return TRUST_ORDER.indexOf(leaseClass) >= TRUST_ORDER.indexOf(floor);
+}
+
+// Accepts a workspace record or a bare id. Lowercased because the Rust side
+// builds the associated data from a hyphenated lowercase UUID.
+function workspaceIdOf(value) {
+  const id = typeof value === "string" ? value : value?.workspace_id;
+  if (typeof id !== "string" || !UUID.test(id.toLowerCase())) {
+    throw new WorkspaceError("invalid_workspace_id");
+  }
+  return id.toLowerCase();
+}
+
+// Single quotes so nothing in a caller's path reaches the remote shell as
+// syntax. A path containing one has no safe quoting, so it is refused.
+function quote(path) {
+  if (typeof path !== "string" || path.trim() === "" || /['\n]/.test(path)) {
+    throw new WorkspaceError("invalid_remote_path", {
+      hint: "a path without single quotes or newlines",
+    });
+  }
+  return `'${path}'`;
+}
+
+// HKDF over the wallet signature. Ethereum's ECDSA is deterministic (RFC 6979),
+// so the same wallet reproduces the same key on any machine and a workspace
+// survives a lost laptop without Prism holding an escrow copy. A passphrase,
+// when given, is mixed into the salt, so a leaked signature alone is not enough.
+async function deriveRootKey(signature, wallet, passphrase) {
+  const material = await subtle.importKey("raw", fromHex(signature), "HKDF", false, ["deriveKey"]);
+  const salt = await subtle.digest(
+    "SHA-256",
+    encoder.encode(`prism.workspace.kdf.v1\0${wallet}\0${passphrase ?? ""}`),
+  );
+  return subtle.deriveKey(
+    { name: "HKDF", hash: "SHA-256", salt: new Uint8Array(salt), info: encoder.encode("root") },
+    material,
+    { name: "AES-KW", length: 256 },
+    false,
+    ["wrapKey", "unwrapKey"],
+  );
+}
+
+// Per-snapshot data key, wrapped under the root. Storage holds the wrapped 40
+// bytes next to the object; the root key that opens it never leaves here.
+async function seal(rootKey, plaintext, aad) {
+  const dataKey = await subtle.generateKey({ name: "AES-GCM", length: 256 }, true, [
+    "encrypt",
+    "decrypt",
+  ]);
+  const nonce = globalThis.crypto.getRandomValues(new Uint8Array(12));
+  const [ciphertext, wrapped] = await Promise.all([
+    subtle.encrypt({ name: "AES-GCM", iv: nonce, additionalData: aad }, dataKey, plaintext),
+    subtle.wrapKey("raw", dataKey, rootKey, "AES-KW"),
+  ]);
+  return {
+    nonce,
+    ciphertext: new Uint8Array(ciphertext),
+    wrappedKey: new Uint8Array(wrapped),
+  };
+}
+
+async function unseal(rootKey, wrappedKey, nonce, ciphertext, aad) {
+  let dataKey;
+  try {
+    dataKey = await subtle.unwrapKey(
+      "raw",
+      wrappedKey,
+      rootKey,
+      "AES-KW",
+      { name: "AES-GCM", length: 256 },
+      false,
+      ["decrypt"],
+    );
+  } catch {
+    throw new WorkspaceError("workspace_key_mismatch", {
+      hint: "this workspace key does not open that snapshot; check the wallet and passphrase used to unlock",
+    });
+  }
+  try {
+    return new Uint8Array(
+      await subtle.decrypt({ name: "AES-GCM", iv: nonce, additionalData: aad }, dataKey, ciphertext),
+    );
+  } catch {
+    throw new WorkspaceError("workspace_authentication_failed", {
+      hint: "the stored snapshot does not match the account, workspace, version and trust floor it was sealed with",
+    });
+  }
+}
+
+// Straight between this process and storage. The URL is never logged and never
+// reported in an error, because for the next fifteen minutes it is the object.
+async function transfer(url, init, code, workspaceId) {
+  let res;
+  try {
+    res = await fetch(url, { ...init, signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS) });
+  } catch (err) {
+    // The cause code rather than the message: a fetch failure can quote the
+    // request URL back at you.
+    throw new WorkspaceError(code, {
+      workspace_id: workspaceId,
+      cause: err?.cause?.code ?? err?.name ?? "fetch_failed",
+    });
+  }
+  if (!res.ok) throw new WorkspaceError(code, { workspace_id: workspaceId, status: res.status });
+  return res;
+}
+
+export class PrismWorkspace {
+  #agent;
+  #rootKey = null;
+  #wallet = null;
+
+  constructor(agent) {
+    this.#agent = agent;
+  }
+
+  get unlocked() {
+    return this.#rootKey !== null;
+  }
+
+  /// Derives the workspace key from a wallet signature. Nothing leaves this
+  /// process; the signature itself is discarded once the key exists.
+  async unlock({ passphrase = null } = {}) {
+    if (!this.#agent.session) await this.#agent.authenticate();
+    const wallet = vaultWallet(this.#agent.address);
+    const signature = await this.#agent.signVaultStatement(WORKSPACE_KEY_STATEMENT);
+    this.#rootKey = await deriveRootKey(signature, wallet, passphrase);
+    this.#wallet = wallet;
+    return this;
+  }
+
+  /// The wallet whose workspaces are open. One wallet, one set of workspaces,
+  /// whether they are reached from a browser or from an agent.
+  get wallet() {
+    return this.#wallet;
+  }
+
+  lock() {
+    this.#rootKey = null;
+    this.#wallet = null;
+  }
+
+  /// Names, versions and sizes. The contents are ciphertext in object storage
+  /// and are not part of a listing.
+  async list() {
+    return this.#agent.workspaceRequest("GET", []);
+  }
+
+  async get(workspaceId) {
+    return this.#record(workspaceIdOf(workspaceId));
+  }
+
+  /// Creates an empty workspace. The name is stored unencrypted, like a vault
+  /// label, and is the one thing a listing discloses.
+  async create(name, { minTrustClass = DEFAULT_WORKSPACE_TRUST_FLOOR } = {}) {
+    assertTrustFloor(minTrustClass);
+    if (typeof name !== "string" || name.trim() === "" || encoder.encode(name).length > MAX_NAME_BYTES) {
+      throw new WorkspaceError("invalid_workspace_name", {
+        hint: `a name of 1 to ${MAX_NAME_BYTES} bytes`,
+      });
+    }
+    return this.#agent.workspaceRequest("POST", [], {
+      body: { name, min_trust_class: minTrustClass },
+    });
+  }
+
+  /// Drops the workspace and every snapshot stored under it.
+  async remove(workspaceId) {
+    return this.#agent.workspaceRequest("DELETE", [workspaceIdOf(workspaceId)]);
+  }
+
+  /// Archives `remotePath` on the leased machine and stores it as a new
+  /// version. The archive is sealed here before it is uploaded, so the object
+  /// storage that serves it and the control plane that indexes it both hold
+  /// ciphertext they cannot open.
+  async save(lease, workspaceId, remotePath, { timeoutMs = REMOTE_TIMEOUT_MS } = {}) {
+    this.#require();
+    const id = workspaceIdOf(workspaceId);
+    this.#requireMachine(lease);
+    const archive = await this.#archive(lease, id, remotePath, timeoutMs);
+
+    // Read rather than remembered: the floor is authenticated into the
+    // ciphertext, so sealing against a stale copy of it stores a snapshot that
+    // will not open.
+    const floor = assertTrustFloor((await this.#record(id)).min_trust_class);
+    // Storage signs the length, so the size is declared before the ciphertext
+    // exists. GCM adds a 16 byte tag and nothing else.
+    const grant = await this.#agent.workspaceRequest("POST", [id, "upload"], {
+      body: { size_bytes: archive.length + 16 },
+    });
+    if (typeof grant?.url !== "string" || !Number.isInteger(grant?.version) || grant.version < 1) {
+      throw new WorkspaceError("invalid_upload_grant");
+    }
+    const aad = workspaceAssociatedData(this.#wallet, id, grant.version, floor);
+    const { nonce, ciphertext, wrappedKey } = await seal(this.#rootKey, archive, aad);
+    const digest = await sha256Hex(ciphertext);
+
+    // Signed into the URL, so it has to be sent. It makes the object
+    // write-once: a stalled upload that lands after a retry has already
+    // committed is refused rather than replacing bytes the metadata describes.
+    await transfer(
+      grant.url,
+      { method: "PUT", body: ciphertext, headers: { "If-None-Match": "*" } },
+      "workspace_upload_failed",
+      id,
+    );
+
+    return this.#agent.workspaceRequest("POST", [id, "commit"], {
+      body: {
+        version: grant.version,
+        wrapped_key: b64url(wrappedKey),
+        nonce: b64url(nonce),
+        ciphertext_digest: digest,
+        size_bytes: ciphertext.length,
+      },
+    });
+  }
+
+  /// Fetches a snapshot, checks it hashes to what was stored, opens it here,
+  /// and unpacks it into `remotePath` on the leased machine. Pass the version
+  /// you last saved as `expectVersion` to refuse an older one.
+  async restore(
+    lease,
+    workspaceId,
+    remotePath,
+    { expectVersion = null, expectTrustClass = null, timeoutMs = REMOTE_TIMEOUT_MS } = {},
+  ) {
+    this.#require();
+    const id = workspaceIdOf(workspaceId);
+    this.#requireMachine(lease);
+    const workspace = await this.#record(id);
+    if (workspace.version < 1) {
+      throw new WorkspaceError("workspace_empty", { hint: "nothing has been saved here yet" });
+    }
+    const floor = assertTrustFloor(workspace.min_trust_class);
+    if (expectTrustClass !== null && floor !== expectTrustClass) {
+      throw new WorkspaceError("workspace_trust_floor_changed", {
+        expected: expectTrustClass,
+        served: floor,
+      });
+    }
+
+    const grant = await this.#agent.workspaceRequest("POST", [id, "download"], {
+      body: { lease_id: lease.leaseId },
+    });
+    if (typeof grant?.url !== "string" || !Number.isInteger(grant?.version)) {
+      throw new WorkspaceError("invalid_download_grant");
+    }
+    const { url, version, ...snapshot } = grant;
+    // The record said which version is current. A grant for anything else is a
+    // rollback, and it decrypts cleanly because an older snapshot's associated
+    // data is genuine for its own version, so nothing downstream would notice.
+    if (version !== workspace.version) {
+      throw new WorkspaceError("workspace_version_rollback", {
+        expected: workspace.version,
+        served: version,
+      });
+    }
+    if (expectVersion !== null && version !== expectVersion) {
+      throw new WorkspaceError("workspace_version_rollback", { expected: expectVersion, served: version });
+    }
+
+    const res = await transfer(url, { method: "GET" }, "workspace_download_failed", id);
+    const ciphertext = new Uint8Array(await res.arrayBuffer());
+    // Checked before anything is decrypted. Bytes that hash to something else
+    // were altered in storage, and that deserves a clear answer rather than an
+    // authentication failure that reads like a wrong key.
+    const digest = await sha256Hex(ciphertext);
+    if (digest !== snapshot.ciphertext_digest) {
+      throw new WorkspaceError("workspace_digest_mismatch", {
+        expected: snapshot.ciphertext_digest,
+        computed: digest,
+        expected_bytes: snapshot.size_bytes,
+        served_bytes: ciphertext.length,
+      });
+    }
+
+    const aad = workspaceAssociatedData(this.#wallet, id, version, floor);
+    const archive = await unseal(
+      this.#rootKey,
+      fromB64(snapshot.wrapped_key),
+      fromB64(snapshot.nonce),
+      ciphertext,
+      aad,
+    );
+    await this.#extract(lease, archive, remotePath, timeoutMs);
+    return { ...workspace, version, snapshot };
+  }
+
+  /// Whether a workspace at this floor may be restored onto a lease of that
+  /// trust class, without asking the control plane.
+  static permits(trustFloor, leaseTrustClass) {
+    return meetsFloor(assertTrustFloor(trustFloor), assertTrustFloor(leaseTrustClass));
+  }
+
+  #require() {
+    if (!this.#rootKey) throw new WorkspaceError("workspace_locked", { hint: "call unlock() first" });
+  }
+
+  // The control plane lists workspaces and does not serve one on its own, so
+  // this is where a single record comes from.
+  async #record(id) {
+    const workspaces = await this.#agent.workspaceRequest("GET", []);
+    const found = workspaces?.find?.((workspace) => workspace?.workspace_id?.toLowerCase() === id);
+    if (!found) throw new WorkspaceError("workspace_not_found", { workspace_id: id });
+    return found;
+  }
+
+  #requireMachine(lease) {
+    if (typeof this.#agent.run !== "function") {
+      throw new WorkspaceError("no_lease_transport", {
+        hint: "save and restore need an agent that can reach the machine over SSH",
+      });
+    }
+    // What `run` needs. A batch lease reports its output and keeps no key, so
+    // it cannot carry a workspace either way.
+    if (!lease?.access?.ssh_host || !lease.keyPath) {
+      throw new WorkspaceError("invalid_lease_handle", {
+        hint: "the handle from an interactive lease(), which a batch lease does not produce",
+      });
+    }
+  }
+
+  // tar and base64 are all this needs from the machine. The archive is staged
+  // to a file first so its size is known before it crosses the wire: storage
+  // signs the length of the upload, and a directory too large to carry should
+  // fail on the machine rather than halfway through a transfer.
+  async #archive(lease, id, remotePath, timeoutMs) {
+    const staged = `/tmp/prism-workspace-${id}.tar.gz`;
+    const res = await this.#agent.run(
+      lease,
+      [
+        "set -e",
+        `f='${staged}'`,
+        `trap 'rm -f "$f"' EXIT`,
+        // tar exits 1 for "file changed as we read it" and still writes a
+        // complete archive. A training job that has not stopped writing hits
+        // that on almost every save, and under set -e it would throw away a
+        // good snapshot. Only a fatal tar, exit 2, aborts.
+        `tar -C ${quote(remotePath)} -czf "$f" . || [ "$?" -le 1 ]`,
+        'n=$(wc -c < "$f")',
+        `[ "$n" -le ${MAX_TRANSFER_BYTES} ] || { echo "prism_snapshot_too_large:$n" >&2; exit 3; }`,
+        // Redirected rather than named: every base64 reads stdin, and not all
+        // of them take a file argument.
+        'base64 < "$f"',
+      ].join("\n"),
+      { timeoutMs },
+    );
+    if (res.code !== 0 || res.timedOut) {
+      // Some wc implementations pad their output, so the count is not
+      // necessarily flush against the marker.
+      const oversize = /prism_snapshot_too_large:\s*(\d+)/.exec(res.stderr);
+      if (oversize) {
+        throw new WorkspaceError("workspace_snapshot_too_large", {
+          bytes: Number(oversize[1]),
+          limit: MAX_TRANSFER_BYTES,
+        });
+      }
+      throw new WorkspaceError("workspace_archive_failed", {
+        code: res.code,
+        stderr: res.stderr,
+        timed_out: res.timedOut,
+      });
+    }
+    return fromB64(res.stdout);
+  }
+
+  // Over stdin rather than in the command, so the plaintext archive is not in
+  // the machine's process table or its shell history.
+  async #extract(lease, archive, remotePath, timeoutMs) {
+    const path = quote(remotePath);
+    const res = await this.#agent.run(
+      lease,
+      ["set -e", `mkdir -p ${path}`, `base64 -d | tar -C ${path} -xzf -`].join("\n"),
+      { timeoutMs, stdin: base64(archive) },
+    );
+    if (res.code !== 0 || res.timedOut) {
+      throw new WorkspaceError("workspace_extract_failed", {
+        code: res.code,
+        stderr: res.stderr,
+        timed_out: res.timedOut,
+      });
+    }
+  }
+}
+
+export class WorkspaceError extends Error {
+  constructor(code, body) {
+    super(`prism workspace: ${code}`);
+    this.code = code;
+    this.body = body;
+  }
+}