openmausbot 0.1.89 → 0.1.91

package/dist-server/server/cloud-home.js

@@ -0,0 +1,241 @@
+// OMB Cloud Pro home machine: the boot contract, the places it offers, the
+// Admin's signed pairing request, and the volume the machine lives on. docs/cloud-pro.md is the
+// contract of record (and openmaus-cloud docs/consumer-cloud.md its Admin
+// half); keep them in step.
+//
+// One Fly app per customer runs this server behind an edge proxy on
+// 0.0.0.0:8080 (server/cloud-home-start.ts). The server itself still binds
+// 127.0.0.1 and every request reaches it with X-Forwarded-* headers, so no
+// request from the network is ever the loopback owner.
+//
+// The Admin never holds a session on the machine. It signs a request with
+// the machine's bootstrap secret (HMAC-SHA256 over the method, path, a
+// timestamp, a nonce and the body's hash); each valid request opens one
+// ordinary pairing window (sessions.ts: single use, at most ten minutes),
+// which the Admin hands to the person's signed-in desktop app.
+//
+// Cloud Pro includes no AI. The person signs in on the machine with their own
+// Claude or ChatGPT account, or an API key, exactly as on any server; nothing
+// on a Cloud home is ever routed to a platform model gateway.
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { hostedWorkspaceConfigured } from "./enterprise.js";
+import { formatPairingCode } from "./sessions.js";
+export const CLOUD_HOME_CONTRACT_VERSION = 1;
+/** Any of these switches the server into Cloud home mode; then all are required. */
+export const CLOUD_HOME_KEYS = ["OMB_CLOUD_ROLE", "OMB_CLOUD_MACHINE_ID", "OMB_CLOUD_ADMIN_URL", "OMB_CLOUD_BOOTSTRAP_SECRET"];
+/** A platform model gateway's settings. A Cloud home never uses them: given
+ * any, it logs one warning, and neither the server nor anything it starts
+ * ever sees them. */
+export const CLOUD_IGNORED_KEYS = ["OMB_HOSTED_MODEL_URL", "OMB_HOSTED_MODEL_TOKEN", "OMB_HOSTED_MODELS"];
+export const CLOUD_PAIRING_PATH = "/api/cloud/pairing";
+export const CLOUD_PAIRING_DEFAULT_TTL_S = 300;
+export const CLOUD_PAIRING_MAX_TTL_S = 600;
+/** How far a signed request's timestamp may be from this machine's clock. */
+export const CLOUD_PAIRING_SKEW_S = 300;
+/** How long a used nonce is refused. Longer than the whole accepted window. */
+export const CLOUD_PAIRING_NONCE_MS = 10 * 60_000;
+const MAX_NONCES = 10_000;
+export const CLOUD_HOME_MARKER = ".omb-cloud-home.json";
+/** The server exits with this after a restore commits (Move to Cloud): the
+ * launcher then starts it again, and startup installs the restore. Any other
+ * exit stops the machine for Fly to restart. */
+export const CLOUD_HOME_RESTART_EXIT_CODE = 75;
+export function cloudHomeConfigured(env = process.env) {
+    return CLOUD_HOME_KEYS.some((key) => env[key] !== undefined);
+}
+function invalid(why) {
+    throw new Error(`Cloud home configuration is invalid: ${why}.`);
+}
+function exactHttpsOrigin(raw, name) {
+    let url;
+    try {
+        if (!raw || raw !== raw.trim())
+            throw new Error();
+        url = new URL(raw);
+    }
+    catch {
+        return invalid(`${name} must be an https origin`);
+    }
+    if (url.protocol !== "https:" || url.username || url.password || (raw !== url.origin && raw !== `${url.origin}/`)) {
+        invalid(`${name} must be an exact https origin with no path`);
+    }
+    return url.origin;
+}
+/** Read the boot contract. Null on any machine that is not a Cloud home;
+ * throws (so the server refuses to start) on a partial or invalid one. */
+export function cloudHomeConfiguration(env = process.env) {
+    if (!cloudHomeConfigured(env))
+        return null;
+    if (env.OMB_DESKTOP_PARENT === "1")
+        invalid("the desktop app cannot run as a Cloud home machine");
+    if (hostedWorkspaceConfigured(env))
+        invalid("a Cloud home is not a hosted team workspace; remove OMB_ADMIN_URL, OMB_ADMIN_WORKSPACE and OMB_ADMIN_MEMBERSHIP");
+    if (env.OMB_CLOUD_ROLE !== "home")
+        invalid('OMB_CLOUD_ROLE must be "home"; this image runs the home machine');
+    const machineId = env.OMB_CLOUD_MACHINE_ID ?? "";
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$/.test(machineId))
+        invalid("OMB_CLOUD_MACHINE_ID must be the Admin's machine id (letters, digits, dashes)");
+    const adminOrigin = exactHttpsOrigin(env.OMB_CLOUD_ADMIN_URL, "OMB_CLOUD_ADMIN_URL");
+    const publicOrigin = exactHttpsOrigin(env.OMB_PUBLIC_URL, "OMB_PUBLIC_URL");
+    const bootstrapSecret = env.OMB_CLOUD_BOOTSTRAP_SECRET ?? "";
+    if (!/^[A-Za-z0-9_-]{43,128}$/.test(bootstrapSecret))
+        invalid("OMB_CLOUD_BOOTSTRAP_SECRET must be at least 256 bits of base64url");
+    const warnings = [];
+    const ignored = CLOUD_IGNORED_KEYS.filter((key) => env[key] !== undefined);
+    if (ignored.length)
+        warnings.push(`ignoring ${ignored.join(", ")}: Cloud Pro includes no AI; people sign in with their own Claude or ChatGPT account, or an API key`);
+    return { machineId, adminOrigin, publicOrigin, bootstrapSecret, warnings };
+}
+/** The environment without a platform gateway's settings (CLOUD_IGNORED_KEYS). */
+export function withoutIgnoredCloudKeys(env) {
+    const kept = { ...env };
+    for (const key of CLOUD_IGNORED_KEYS)
+        delete kept[key];
+    return kept;
+}
+// The places a Cloud home offers live in shared/cloud-home.ts, so the app
+// lists exactly what the server accepts.
+export { cloudHomeOffersPlace } from "../shared/cloud-home.js";
+/** Why a Cloud home refuses a place it never offers (no "this computer" of
+ * the person's, no Local VM), in the words the person reads; undefined for a
+ * place it offers. A turn's error shows 160 characters, so each fits. */
+export function cloudHomePlaceRefusal(place) {
+    if (place === "local")
+        return "This computer isn't a place on your OMB Cloud: its bots run in the cloud. Set Works on to Auto, Cloud or Browser, or lend your Mac under Settings → OMB Cloud.";
+    if (place === "vm")
+        return "Bots on your OMB Cloud can't use a Local VM: the cloud machine has no container runtime. Set Works on to Auto, Cloud or Browser.";
+    return undefined;
+}
+/** What a turn is told when Cloud is chosen but no Boat account is set up (no
+ * key of the person's and no included Boat). A Cloud home has no Local VM to
+ * suggest instead. */
+export function boatNotConfiguredMessage(cloudHome) {
+    return `Cloud Boat is not configured — add a Boat API key or choose ${cloudHome ? "Browser" : "Local VM"}`;
+}
+/** The Admin's side of the signature (openmaus-cloud cloudPairingSignature). */
+export function cloudPairingSignature(secret, timestamp, nonce, body) {
+    const bodyHash = createHash("sha256").update(body).digest("base64url");
+    return createHmac("sha256", secret).update(`v1\n${timestamp}\n${nonce}\nPOST\n${CLOUD_PAIRING_PATH}\n${bodyHash}`).digest("base64url");
+}
+/** The Admin's signed request for one pairing window on this machine. */
+export function createCloudPairing(options) {
+    const { secret, sessions } = options;
+    const now = options.now ?? Date.now;
+    const nonces = new Map();
+    const refused = (error) => ({ status: 401, body: { error } });
+    return {
+        /** Everything is checked before anything is opened: the signature (in
+         * constant time; a bad one counts toward the pairing lockout), then the
+         * clock, then the nonce, then the body. Nothing here is ever logged. */
+        handle(input) {
+            const lock = sessions.attemptAllowed(input.source);
+            if (!lock.ok)
+                return { status: 429, body: { error: "rate_limited", retryAfterSeconds: Math.ceil(lock.retryAfterMs / 1000) } };
+            const timestamp = input.timestamp ?? "", nonce = input.nonce ?? "";
+            const presented = /^v1=([A-Za-z0-9_-]{43})$/.exec(input.signature ?? "")?.[1];
+            const expected = Buffer.from(cloudPairingSignature(secret, timestamp, nonce, input.body), "base64url");
+            const given = presented ? Buffer.from(presented, "base64url") : Buffer.alloc(expected.length);
+            const matches = given.length === expected.length && timingSafeEqual(given, expected);
+            if (!presented || !matches || !/^\d{1,12}$/.test(timestamp) || !/^[A-Za-z0-9_-]{16,128}$/.test(nonce)) {
+                sessions.noteFailure(input.source);
+                return refused("invalid_signature");
+            }
+            sessions.clearFailures(input.source);
+            const at = now();
+            if (Math.abs(at / 1000 - Number(timestamp)) > CLOUD_PAIRING_SKEW_S)
+                return refused("stale_request");
+            for (const [seen, until] of nonces)
+                if (until <= at)
+                    nonces.delete(seen);
+            if (nonces.has(nonce))
+                return refused("replayed_request");
+            if (nonces.size >= MAX_NONCES)
+                return { status: 503, body: { error: "busy" } };
+            nonces.set(nonce, at + CLOUD_PAIRING_NONCE_MS);
+            let parsed;
+            try {
+                parsed = input.body.length ? JSON.parse(input.body.toString("utf8")) : {};
+            }
+            catch {
+                return { status: 400, body: { error: "invalid_body" } };
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return { status: 400, body: { error: "invalid_body" } };
+            const { label, ttlSeconds } = parsed;
+            // oxlint-disable-next-line no-control-regex
+            if (label !== undefined && (typeof label !== "string" || label.length > 80 || /[\x00-\x1f\x7f]/.test(label)))
+                return { status: 400, body: { error: "invalid_label" } };
+            if (ttlSeconds !== undefined && (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1))
+                return { status: 400, body: { error: "invalid_ttl" } };
+            const ttl = Math.min(ttlSeconds ?? CLOUD_PAIRING_DEFAULT_TTL_S, CLOUD_PAIRING_MAX_TTL_S);
+            const opened = sessions.openPairing({
+                scopes: ["admin", "client"],
+                label: typeof label === "string" && label.trim() ? label.trim() : "OMB Cloud",
+                ttlMs: ttl * 1000,
+            });
+            return { status: 200, body: { code: formatPairingCode(opened.code), credential: opened.credential, expiresAt: opened.expiresAt } };
+        },
+    };
+}
+/** The exact bytes the Admin signed, bounded. */
+export function readSignedBody(req, limit = 4096) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0, done = false;
+        req.on("data", (chunk) => {
+            if (done)
+                return;
+            size += chunk.length;
+            if (size > limit) {
+                done = true;
+                reject(Object.assign(new Error("body too large"), { status: 413 }));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => { if (!done) {
+            done = true;
+            resolve(Buffer.concat(chunks));
+        } });
+        req.on("error", (error) => { if (!done) {
+            done = true;
+            reject(Object.assign(error, { status: 400 }));
+        } });
+    });
+}
+// The image's home directory may carry the shell files useradd seeds; a
+// fresh Fly volume carries lost+found. Anything else is someone's data.
+const ADOPTABLE = new Set(["lost+found", ".bash_logout", ".bashrc", ".profile"]);
+/** Bind the volume to this machine on first boot and refuse any other
+ * machine's volume afterwards. Never deletes or rewrites existing data. */
+export function prepareCloudHomeVolume(home, machineId) {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const marker = join(home, CLOUD_HOME_MARKER);
+    if (existsSync(marker)) {
+        const stat = lstatSync(marker);
+        let saved;
+        try {
+            if (!stat.isFile() || stat.size > 4096)
+                throw new Error();
+            saved = JSON.parse(readFileSync(marker, "utf8"));
+        }
+        catch {
+            throw new Error("This volume's Cloud marker is unreadable. No data was changed.");
+        }
+        if (saved?.machine !== machineId)
+            throw new Error("This volume belongs to another Cloud machine. No data was changed.");
+        return "existing";
+    }
+    if (readdirSync(home).some((name) => !ADOPTABLE.has(name))) {
+        throw new Error("Refusing to adopt a data volume that was not made for this Cloud machine. No data was changed.");
+    }
+    writeFileAtomic(marker, JSON.stringify({ version: 1, machine: machineId }) + "\n", { mode: 0o600 });
+    return "new";
+}
+/** What the edge proxy may answer for: the machine's own public name. */
+export function cloudHomeHost(config) {
+    return new URL(config.publicOrigin).hostname;
+}

package/dist-server/server/cloud-lending.js

@@ -0,0 +1,103 @@
+// Who may use a Mac lent to an OMB Cloud home (docs/cloud-pro.md, "Let my
+// Cloud use this Mac"). A Cloud home is one person's server, but not every
+// turn on it is theirs: a guest the owner paired, a webhook's payload, or a
+// line someone else slipped into a running turn must never reach the Mac.
+//
+// A turn may use the lent Mac only when the harness can prove it acts for the
+// owner:
+// - a conversation the owner started from one of their own devices (a live
+//   session with admin scope), or
+// - a scheduled run of a routine whose instructions the owner wrote (created
+//   or edited from one of those devices), or a run the owner started by hand;
+// and the conversation holds nobody else's words, ever: a resumed session
+// carries everything said in it, so one line (or card answer) from a guest,
+// a teammate bot or a local process, before or during the turn, takes that
+// conversation out of lending. The owner starts a new one to lend again.
+// Webhook runs, guests, rooms, a bot's delegated or peer turn, and anything
+// unprovable never can.
+// Everything here is pure; server/index.ts supplies the records.
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { z } from "zod";
+import { writeFileAtomic } from "./atomic.js";
+const personOf = (line) => line?.role === "user" && !line.peerAsk ? line.sender?.id : undefined;
+export function cloudHomeTurnMayLend(turn) {
+    return cloudHomeLendingRefusal(turn) === null;
+}
+export function cloudHomeLendingRefusal(turn) {
+    const { request } = turn;
+    if (!request?.messageId || request.stopped || !request.generations.has(turn.generation))
+        return "unproven";
+    const index = turn.thread.findIndex(line => line.id === request.messageId);
+    if (index < 0)
+        return "unproven";
+    let owner;
+    if (request.automation === undefined) {
+        owner = turn.ownerPerson(personOf(turn.thread[index]));
+    }
+    else {
+        const run = turn.routineRun();
+        owner = request.automation !== "webhook" && Boolean(run) && run.triggerSource !== "webhook" &&
+            run.ownerAuthored && (run.triggerSource !== "manual" || run.ownerStarted);
+    }
+    if (!owner)
+        return "not-owner";
+    // Nothing anyone else wrote (a guest, a teammate bot, a local process) may
+    // be anywhere in this conversation, before or after the request, as a line
+    // (sent, queued, steered or handed in) or as the answer to a card. A
+    // routine's own prompt line names nobody; its provenance was proven above.
+    const clean = turn.thread.every((line, at) => (line.role !== "user" || (at === index && request.automation !== undefined) || turn.ownerPerson(personOf(line))) &&
+        (!answeredByPerson(line.card) || turn.ownerPerson(turn.cardAnswerer(line.card))));
+    return clean ? null : "someone-else";
+}
+/** A card someone answered: a person's verdict or words. The harness's own
+ * settlements (automatic approvals, a turn that ended) are marked dismissed
+ * or unavailable and carry nobody's words. */
+function answeredByPerson(card) {
+    if (!card)
+        return false;
+    return (Boolean(card.answered) && card.answered !== "unavailable" && card.dismissed !== true) || Boolean(card.answeredText);
+}
+/** What a routine run does and when, reduced to what its author decides:
+ * the instructions, where and on what it runs, and its schedule. The
+ * scheduler never rewrites these (it does rewrite a routine's results thread
+ * on each run, so that is guarded by who edits the routine instead: see the
+ * routines PATCH route). An edit by anyone else changes the fingerprint. */
+export function routineFingerprint(routine) {
+    const attachments = (routine.attachments ?? []).map(attachment => [attachment.id, attachment.path]);
+    return createHash("sha256").update(JSON.stringify([
+        routine.prompt ?? "", routine.target ?? null, routine.botId ?? "", routine.groupId ?? null, attachments,
+        routine.schedule ?? null, routine.runOn ?? null,
+    ])).digest("hex");
+}
+const authorsFile = z.object({ version: z.literal(1), routines: z.record(z.string().max(128), z.string().regex(/^[a-f0-9]{64}$/)) }).strict();
+/** Which routines the owner wrote, as the fingerprint of what they wrote.
+ * Persisted beside the routines (owner-only). A missing or damaged file
+ * means none: it never grants anything by being absent. */
+export function createCloudRoutineAuthors(file) {
+    let routines = {};
+    try {
+        if (existsSync(file)) {
+            const stat = lstatSync(file);
+            if (stat.isFile() && !stat.isSymbolicLink() && stat.size <= 1_000_000)
+                routines = authorsFile.parse(JSON.parse(readFileSync(file, "utf8"))).routines;
+        }
+    }
+    catch {
+        routines = {};
+    }
+    const save = () => writeFileAtomic(file, JSON.stringify({ version: 1, routines }), { mode: 0o600 });
+    return {
+        /** The owner wrote this routine as it stands now. */
+        record(id, routine) { routines = { ...routines, [id]: routineFingerprint(routine) }; save(); },
+        forget(id) { if (Object.hasOwn(routines, id)) {
+            const next = { ...routines };
+            delete next[id];
+            routines = next;
+            save();
+        } },
+        /** Whether this routine, as it stands (or as a run snapshotted it), is
+         * exactly what the owner wrote. */
+        authored(id, routine) { return Object.hasOwn(routines, id) && routines[id] === routineFingerprint(routine); },
+    };
+}

package/dist-server/server/cloud-move-http.js

@@ -0,0 +1,268 @@
+import { z } from "zod";
+import { backupsBytes, beginUpload, CLOUD_MOVE_MAX_BYTES, CLOUD_MOVE_MAX_PART_BYTES, CLOUD_MOVE_PART_BYTES, completedUpload, discardNextPreviousCloud, discardUpload, forgetMoveRestore, freeVolumeBytes, isEmptyWorkspace, moveSpaceNeeded, noteMoveRestore, prepareNextPreviousCloud, previousCloud, previousCloudArchiveBytes, removeMoveFiles, stagePreviousCloud, tidyCloudMoveStorage, uploadStatus, validUploadDeclaration, workspaceContents, workspaceMoveSize, writeUploadPart, } from "./cloud-move.js";
+import { commitPendingWorkspaceRestore, createWorkspaceBackup, stageWorkspaceBackup } from "./workspace-backup.js";
+export const CLOUD_MOVE_PREFIX = "/api/cloud-move";
+const failure = (message, status) => Object.assign(new Error(message), { status });
+const HELD_CACHE_MS = 30_000;
+export function createCloudMoveRoutes(options) {
+    const freeBytes = options.freeBytes ?? freeVolumeBytes;
+    // A move's restore that startup has installed keeps no safety copy or
+    // staged files; an abandoned upload goes after a day.
+    if (options.cloudHome) {
+        try {
+            tidyCloudMoveStorage(options.dataDir, options.restored);
+        }
+        catch (error) {
+            console.warn(`cloud move: could not tidy backup storage (${error instanceof Error ? error.message : "unknown"})`);
+        }
+    }
+    // Staged here by a preview; restore accepts nothing else.
+    const staged = new Set();
+    let job = null;
+    let writing = false, discardPreview = false;
+    let held = null;
+    const json = (res, status, body) => {
+        res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+        res.end(JSON.stringify(body));
+    };
+    const check = (req, auth) => {
+        if (!options.authorized(req, auth))
+            throw failure("Your session changed. Start the move again.", 403);
+    };
+    const ready = () => {
+        if (job?.state === "running" || writing)
+            throw failure("Another move step is running on your Cloud. Wait for it to finish.", 409);
+        const status = options.status();
+        if (status.pendingRestore)
+            throw failure("Your Cloud is restarting to finish a restore. Try again in a minute.", 409);
+        if (status.busy)
+            throw failure("Your Cloud is busy with a backup. Try again when it finishes.", 409);
+    };
+    /** Delete what earlier previews staged and no restore took. */
+    const dropStaged = () => {
+        for (const id of staged)
+            removeMoveFiles(options.dataDir, id);
+        staged.clear();
+        if (job?.kind === "preview" && job.state === "done")
+            job = null;
+    };
+    function start(kind, work, after) {
+        const current = { kind, state: "running" };
+        job = current;
+        held = null;
+        void work().then((result) => {
+            if (job !== current)
+                return;
+            job = result;
+            after?.(result);
+        }, (error) => {
+            if (job === current)
+                job = { kind, state: "failed", error: error instanceof Error ? error.message : "The move could not finish." };
+        });
+    }
+    // A person's own page can hold the workspace gate for a moment (an ordinary
+    // request in flight); try the gate a few times before giving up.
+    const quietly = async (work) => {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await options.exclusive(work, true);
+            }
+            catch (error) {
+                if (attempt >= 4 || error.status !== 409)
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, options.gateRetryMs ?? 2_000));
+            }
+        }
+    };
+    /** Back up the workspace about to be replaced, then commit `id`. On any
+     * failure nothing is left behind: not the new backup, not the staged files. */
+    async function replaceWith(id, req, auth) {
+        noteMoveRestore(options.dataDir, id);
+        try {
+            return await quietly(async () => {
+                check(req, auth);
+                const previous = await prepareNextPreviousCloud(options.dataDir, id, (password) => createWorkspaceBackup(options.dataDir, { password, appVersion: options.appVersion }));
+                return { committed: commitPendingWorkspaceRestore(options.dataDir, id), previous };
+            });
+        }
+        catch (error) {
+            discardNextPreviousCloud(options.dataDir);
+            forgetMoveRestore(options.dataDir, id);
+            removeMoveFiles(options.dataDir, id);
+            throw error;
+        }
+        finally {
+            staged.delete(id);
+        }
+    }
+    /** Room for staging `archive` bytes and installing them, plus a backup of the
+     * workspace they replace; 507 with both numbers otherwise. */
+    const roomFor = (archive, already = 0) => {
+        const needed = moveSpaceNeeded(archive, workspaceMoveSize(options.dataDir).bytes, true) - already;
+        const free = freeBytes(options.dataDir);
+        return free >= needed ? null : { error: "Your Cloud does not have enough free space for this.", freeBytes: free, neededBytes: needed };
+    };
+    // The answer that the restore is ready goes out first; then the launcher
+    // starts the server again, and startup installs the restore before anything else loads.
+    const restartSoon = () => { setTimeout(() => options.restart(), options.restartDelayMs ?? 1_500).unref?.(); };
+    return async (req, res, path, auth) => {
+        if (path !== CLOUD_MOVE_PREFIX && !path.startsWith(`${CLOUD_MOVE_PREFIX}/`))
+            return false;
+        const method = req.method ?? "GET";
+        try {
+            if (!auth.scopes.includes("admin"))
+                throw failure("Only the owner can move a workspace.", 403);
+            if (method === "GET" && path === `${CLOUD_MOVE_PREFIX}/estimate`) {
+                json(res, 200, { ...workspaceContents(options.dataDir), ...workspaceMoveSize(options.dataDir), maxBytes: CLOUD_MOVE_MAX_BYTES });
+                return true;
+            }
+            if (!options.cloudHome)
+                throw failure("Only an OMB Cloud home receives a moved workspace.", 404);
+            if (auth.kind !== "session")
+                throw failure("Move to Cloud needs the owner's signed-in app.", 403);
+            check(req, auth);
+            if (method === "GET" && path === CLOUD_MOVE_PREFIX) {
+                const contents = workspaceContents(options.dataDir);
+                if (!held || held.at + HELD_CACHE_MS < Date.now())
+                    held = { at: Date.now(), bytes: backupsBytes(options.dataDir) };
+                json(res, 200, {
+                    contents, empty: isEmptyWorkspace(contents), freeBytes: freeBytes(options.dataDir), maxBytes: CLOUD_MOVE_MAX_BYTES,
+                    partBytes: CLOUD_MOVE_PART_BYTES, upload: uploadStatus(options.dataDir), previous: previousCloud(options.dataDir), job,
+                    // What backups and the previous Cloud hold on the volume.
+                    heldBytes: held.bytes,
+                    ...options.status(),
+                    lastRestoreId: options.restored.restored ? options.restored.id ?? null : null,
+                    rolledBackId: options.restored.rolledBack ? options.restored.id ?? null : null,
+                });
+                return true;
+            }
+            if (method === "POST" && path === `${CLOUD_MOVE_PREFIX}/upload`) {
+                const declared = validUploadDeclaration(z.object({ sha256: z.unknown(), bytes: z.unknown(), files: z.unknown().optional() }).parse(await options.readBody(req, 4096)));
+                ready();
+                // A new upload ends any earlier attempt: its staged files go, and a
+                // stored part (whichever file it was) counts as space about to be freed.
+                dropStaged();
+                const refused = roomFor(declared.bytes, uploadStatus(options.dataDir)?.received ?? 0);
+                if (refused) {
+                    json(res, 507, refused);
+                    return true;
+                }
+                check(req, auth);
+                held = null;
+                json(res, 200, { ...beginUpload(options.dataDir, declared), partBytes: CLOUD_MOVE_PART_BYTES });
+                return true;
+            }
+            const part = /^\/api\/cloud-move\/upload\/([a-f0-9]{64})$/.exec(path);
+            if (method === "PUT" && part) {
+                const offset = Number(new URL(req.url ?? "/", "http://cloud-move.invalid").searchParams.get("offset"));
+                const length = Number(req.headers["content-length"]);
+                if (!Number.isSafeInteger(length) || length <= 0 || length > CLOUD_MOVE_MAX_PART_BYTES)
+                    throw failure("Send each part with its length, at most 64 MB.", 411);
+                ready();
+                writing = true;
+                let received;
+                try {
+                    received = await writeUploadPart(options.dataDir, part[1], offset, length, req.iterator({ destroyOnReturn: false }));
+                }
+                finally {
+                    writing = false;
+                }
+                json(res, 200, { received });
+                return true;
+            }
+            if (method === "POST" && path === `${CLOUD_MOVE_PREFIX}/preview`) {
+                const body = z.object({ sha256: z.string().regex(/^[a-f0-9]{64}$/), password: z.string().min(12).max(1024) }).parse(await options.readBody(req, 8192));
+                ready();
+                discardPreview = false;
+                start("preview", async () => {
+                    const file = await completedUpload(options.dataDir, body.sha256);
+                    let result;
+                    try {
+                        result = await stageWorkspaceBackup(options.dataDir, file, { password: body.password, currentAppVersion: options.appVersion });
+                    }
+                    finally {
+                        discardUpload(options.dataDir);
+                    }
+                    if (discardPreview) {
+                        removeMoveFiles(options.dataDir, result.id);
+                        throw failure("The move was stopped; what it staged was removed.", 409);
+                    }
+                    try {
+                        check(req, auth);
+                    }
+                    catch (error) {
+                        removeMoveFiles(options.dataDir, result.id);
+                        throw error;
+                    }
+                    staged.add(result.id);
+                    const { summary } = result;
+                    return { kind: "preview", state: "done", id: result.id, summary: {
+                            appVersion: summary.appVersion, files: summary.files, bytes: summary.bytes, bots: summary.bots,
+                            groups: summary.groups, threads: summary.threads, messages: summary.messages,
+                        } };
+                });
+                json(res, 202, { job });
+                return true;
+            }
+            if (method === "POST" && path === `${CLOUD_MOVE_PREFIX}/discard`) {
+                await options.readBody(req, 4096);
+                if (job?.state === "running" && job.kind !== "preview")
+                    throw failure("Your Cloud is already replacing its workspace.", 409);
+                // A preview still running removes what it stages when it ends.
+                if (job?.state === "running")
+                    discardPreview = true;
+                dropStaged();
+                held = null;
+                json(res, 200, { ok: true });
+                return true;
+            }
+            if (method === "POST" && path === `${CLOUD_MOVE_PREFIX}/restore`) {
+                const body = z.object({ id: z.string().uuid() }).parse(await options.readBody(req, 4096));
+                ready();
+                if (!staged.has(body.id))
+                    throw failure("This move is no longer ready on your Cloud. Start it again.", 404);
+                start("restore", async () => {
+                    const { committed, previous } = await replaceWith(body.id, req, auth);
+                    return { kind: "restore", state: "done", id: committed.id, previous };
+                }, restartSoon);
+                json(res, 202, { job });
+                return true;
+            }
+            if (method === "POST" && path === `${CLOUD_MOVE_PREFIX}/undo`) {
+                await options.readBody(req, 4096);
+                ready();
+                if (!previousCloud(options.dataDir))
+                    throw failure("There is no previous Cloud to restore.", 404);
+                const refused = roomFor(previousCloudArchiveBytes(options.dataDir));
+                if (refused) {
+                    json(res, 507, refused);
+                    return true;
+                }
+                dropStaged();
+                // A swap: what the Cloud has now becomes the previous Cloud, so this
+                // can be undone the same way.
+                start("undo", async () => {
+                    const prepared = await stagePreviousCloud(options.dataDir, options.appVersion);
+                    const { committed, previous } = await replaceWith(prepared.id, req, auth);
+                    return { kind: "undo", state: "done", id: committed.id, previous };
+                }, restartSoon);
+                json(res, 202, { job });
+                return true;
+            }
+            json(res, 404, { error: "Unknown move operation." });
+        }
+        catch (error) {
+            if (res.headersSent) {
+                res.destroy();
+                return true;
+            }
+            const status = error instanceof z.ZodError ? 400 : error.status ?? 400;
+            const received = error.received;
+            json(res, status, {
+                error: error instanceof z.ZodError ? "Invalid move request." : error instanceof Error ? error.message : "The move failed.",
+                ...(Number.isSafeInteger(received) ? { received } : {}),
+            });
+        }
+        return true;
+    };
+}