sealkeep 0.5.0

package/dist/src/cloud.js

@@ -0,0 +1,851 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { chooseBackend } from "./secrets.js";
+import { encryptArchive as sealEnvelope, decryptArchive as openEnvelope, x25519PrivateKeyFromRaw, x25519PublicKeyFromRaw } from "../packages/vaultline-crypto/src/index.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { fail, isVaultlineError, VaultlineError } from "./errors.js";
+import { sha256 } from "./crypto.js";
+import { listArchives, readConfig, writeRecord } from "./vault.js";
+/**
+ * Sealkeep Cloud: the managed tier.
+ *
+ * The trade for paying is that you configure nothing — no bucket, no IAM, no
+ * credentials. What you do not trade away is control of your data: this module
+ * asks the control plane for permission to write one object, then talks to
+ * storage directly. Ciphertext never passes through our servers, and the
+ * control plane is never sent a key that opens it.
+ */
+export const DEFAULT_CLOUD_URL = "https://shared.spala.ai/p04946/api";
+const cloudUrl = (env = process.env) => (env.VAULTLINE_CLOUD_URL ?? DEFAULT_CLOUD_URL).replace(/\/+$/, "");
+/**
+ * Where this vault's cloud token lives in the keystore.
+ *
+ * Keyed by vault as well as by cloud URL. Keying on the URL alone made the
+ * token machine-global: every vault on the machine inherited whichever account
+ * happened to be signed in, so a brand-new free-tier vault reported itself
+ * signed in as someone else, showed a green sealed-key check it had no claim
+ * to, and — because `resolveSyncRules` reads that account — silently applied a
+ * stranger's sync rules. On this machine that held back 659 of 662 sessions on
+ * a vault that had never logged in to anything.
+ *
+ * Exported because `enroll` stores a token at this same location. Two copies of
+ * a key format that must agree is how `access_key_id` drifted from `akid` and
+ * would have signed every managed upload with an undefined credential — one
+ * definition, imported, so a change here cannot leave the other behind.
+ */
+export function tokenRefFor(vaultId, env = process.env) {
+    return { service: "vaultline-cloud", account: `${vaultId}@${cloudUrl(env)}` };
+}
+async function tokenRef(dataDir) {
+    const { readConfig } = await import("./vault.js");
+    const { vaultId } = await readConfig(dataDir);
+    return tokenRefFor(vaultId);
+}
+/** A failed cloud call should say what the service said, not just "request failed". */
+async function call(path, init = {}, env = process.env) {
+    const { token, ...rest } = init;
+    const headers = new Headers(rest.headers);
+    if (rest.body)
+        headers.set("content-type", "application/json");
+    if (token)
+        headers.set("authorization", `Bearer ${token}`);
+    let response;
+    try {
+        response = await fetch(`${cloudUrl(env)}${path}`, { ...rest, headers });
+    }
+    catch (error) {
+        return fail("internal", `Sealkeep Cloud is unreachable: ${error instanceof Error ? error.message : "network error"}`);
+    }
+    const text = await response.text();
+    const body = text ? safeJson(text) : null;
+    if (!response.ok) {
+        const message = body?.error ?? `${response.status} ${response.statusText}`;
+        if (response.status === 401)
+            fail("unauthorized", `Sealkeep Cloud rejected the credentials: ${message}`);
+        if (response.status === 402)
+            fail("forbidden", message);
+        if (response.status === 403)
+            fail("forbidden", message);
+        if (response.status === 409)
+            fail("lease_expired", message);
+        fail("internal", `Sealkeep Cloud returned ${response.status}: ${message}`);
+    }
+    return body;
+}
+const safeJson = (text) => { try {
+    return JSON.parse(text);
+}
+catch {
+    return { error: text.slice(0, 200) };
+} };
+/* ------------------------------------------------------------------ account */
+export async function register(dataDir, input, preferred) {
+    const account = await call("/signup", { method: "POST", body: JSON.stringify(input) });
+    await login(dataDir, { email: input.email, password: input.password }, preferred);
+    return account;
+}
+/** The token lives in the OS keychain, never in a config file on disk. */
+export async function login(dataDir, input, preferred) {
+    const result = await call("/login", { method: "POST", body: JSON.stringify(input) });
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.set(await tokenRef(dataDir), result.token);
+    return result.user;
+}
+/**
+ * Sign in with a one-time code from the web panel instead of a password.
+ *
+ * An account created through Google has no password anybody knows — the server
+ * stores a bcrypt of a random string it never shows. Without this, every Google
+ * customer would have a working dashboard and an unusable CLI. The code is
+ * single-use and the server clears it on redemption.
+ */
+export async function loginWithCode(dataDir, input, preferred) {
+    // Everything local is proven before the exchange, because the exchange
+    // consumes the single-use pairing code. Running `cloud login` before `setup`
+    // used to burn the code on the way to a "no vault" error — the person then
+    // stood at a panel whose displayed code was already dead, with no hint why.
+    const backend = await chooseBackend(dataDir, preferred);
+    const ref = await tokenRef(dataDir);
+    const result = await call("/cli/exchange", { method: "POST", body: JSON.stringify(input) });
+    await backend.set(ref, result.token);
+    // Announce this machine to the account, so the panel's device list shows it
+    // and Revoke has a row to act on. The exchange endpoint itself cannot write
+    // the row (it is public; the control plane only accepts tenant writes from an
+    // authenticated caller), so the freshly minted token does it. Best-effort: a
+    // machine that fails to register is still signed in — it is merely invisible,
+    // which was previously true of every machine.
+    try {
+        const { hostname } = await import("node:os");
+        await call("/v1/cloud/devices/register", { method: "POST", token: result.token, body: JSON.stringify({ label: hostname() }) });
+    }
+    catch { /* visibility is not worth failing a successful sign-in over */ }
+    return result.user;
+}
+export async function logout(dataDir, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.delete(await tokenRef(dataDir));
+}
+export async function cloudToken(dataDir, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    const token = await backend.get(await tokenRef(dataDir));
+    if (!token)
+        fail("unauthorized", "Not signed in to Sealkeep Cloud. Run: sealkeep cloud login");
+    return token;
+}
+export async function accountStatus(dataDir, preferred) {
+    return call("/me", { token: await cloudToken(dataDir, preferred) });
+}
+/**
+ * Refuses an escrow password that is also the account password.
+ *
+ * `login` sends the account password to the control plane, where it is bcrypted
+ * — which is ordinary and fine for authentication, and fatal here. An escrow
+ * password is a key that opens the blob on its own, so if it is the same string
+ * the account is authenticated with, then we have been handed that key, and so
+ * has anyone who takes the database or compels us to produce it. The product's
+ * central claim — that we cannot open your archives — would be false, and
+ * false in a way no customer could detect.
+ *
+ * Enforced rather than documented, because a rule that only exists in prose is
+ * a rule people break by pasting the password they already use. The comparison
+ * is deliberately naive: this is a mistake-catcher, not a policy engine, and
+ * the caller is the only place both strings are ever in hand at once.
+ *
+ * The real fix is for authentication to stop sending the raw password at all —
+ * send one derivation to log in, keep another for encryption, so reuse becomes
+ * harmless instead of forbidden. That is a control-plane change; until it
+ * happens, this keeps the guarantee true.
+ */
+export function assertEscrowPasswordDistinct(accountPassword, escrowPassword) {
+    if (accountPassword.trim() && accountPassword.trim() === escrowPassword.trim()) {
+        fail("invalid_argument", "Your unlock password must be different from your account password. The account password is sent to Sealkeep when you sign in, so reusing it here would hand us a key that opens your archives — which is exactly what this product promises we do not have.");
+    }
+}
+export function sealEscrow(secretMaterial, rawPhrase, also = []) {
+    const phrase = canonicalPhrase(rawPhrase);
+    // The phrase is always a recipient and always first: every other way in can
+    // be revoked, forgotten or left on a lost laptop, and this is the one that
+    // belongs entirely to the person whose data it is.
+    const recipients = [{ kind: "phrase", phrase }];
+    for (const unlock of also) {
+        if (unlock.kind === "password") {
+            if (!unlock.password.trim())
+                fail("invalid_argument", "An escrow password cannot be empty");
+            recipients.push({ kind: "phrase", phrase: unlock.password });
+        }
+        else {
+            const raw = Buffer.from(unlock.publicKeyBase64, "base64");
+            if (raw.length !== 32)
+                fail("invalid_argument", "An X25519 escrow key must be 32 bytes, base64 encoded");
+            recipients.push({ kind: "x25519", publicKey: x25519PublicKeyFromRaw(raw) });
+        }
+    }
+    return sealEnvelope(Buffer.from(JSON.stringify(secretMaterial)), { recipients, adapter: { agent: "vaultline-escrow", version: "1" } });
+}
+export function openEscrow(envelope, ciphertext, rawPhrase) {
+    const phrase = canonicalPhrase(rawPhrase);
+    try {
+        return JSON.parse(openEnvelope(envelope, ciphertext, { phrase }).toString("utf8"));
+    }
+    catch {
+        return fail("recovery_phrase_mismatch", "That recovery phrase does not open this escrow blob");
+    }
+}
+/**
+ * Opens the blob with a password that was registered as an unlock.
+ *
+ * Separate from `openEscrow` so the two cannot be confused at a call site: this
+ * one is reached by typing something memorable, which is the convenience the
+ * paid tier is for and also the weaker of the two doors. The failure message
+ * says password rather than phrase, because being told your recovery phrase is
+ * wrong when you typed a password is how people conclude they have lost
+ * everything.
+ */
+export function openEscrowWithPassword(envelope, ciphertext, password) {
+    try {
+        return JSON.parse(openEnvelope(envelope, ciphertext, { phrase: password }).toString("utf8"));
+    }
+    catch {
+        return fail("recovery_phrase_mismatch", "That password does not open this escrow blob");
+    }
+}
+/**
+ * Opens the blob with a key: a passkey's derived identity, or an org's escrow
+ * key. The private half is never stored by us and never travels — it is
+ * re-derived from the authenticator, or held by whoever owns the org key.
+ */
+export function openEscrowWithKey(envelope, ciphertext, privateKeyRaw) {
+    try {
+        const privateKey = x25519PrivateKeyFromRaw(privateKeyRaw);
+        return JSON.parse(openEnvelope(envelope, ciphertext, { privateKey }).toString("utf8"));
+    }
+    catch {
+        return fail("recovery_phrase_mismatch", "That key does not open this escrow blob");
+    }
+}
+/**
+ * Hand the sealed blob to the control plane.
+ *
+ * What crosses the wire is ciphertext plus the envelope needed to unwrap it
+ * *given the phrase*. The phrase itself is never sent, so possession of this
+ * record — by us, or by anyone who takes the database — does not open it.
+ */
+export async function pushEscrow(dataDir, secretMaterial, rawPhrase, preferred, also = []) {
+    const { envelope, ciphertext } = sealEscrow(secretMaterial, rawPhrase, also);
+    await call("/v1/cloud/escrow", {
+        method: "PUT",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ envelope: JSON.stringify(envelope), sealed: ciphertext.toString("base64") })
+    });
+    return { stored: true };
+}
+/** Fetch and open the escrow blob. Requires the phrase; nothing else will do. */
+/** Whether a sealed copy exists, without needing the phrase to find out. */
+export async function hasSealedCopy(dataDir, preferred) {
+    const answer = await call("/v1/cloud/escrow", { token: await cloudToken(dataDir, preferred) });
+    return (Array.isArray(answer) ? answer : answer ? [answer] : []).some((row) => Boolean(row?.sealed));
+}
+export async function pullEscrow(dataDir, rawPhrase, preferred) {
+    // The control plane answers with a list, even though sealing replaces rather
+    // than appends and the list holds one row. This asked for `.sealed` on the
+    // list itself, which is always undefined, so the escrow was unreadable no
+    // matter what had been stored — the paid tier's whole safety net.
+    // Newest-first is belt and braces in case replacement ever becomes an append.
+    const answer = await call("/v1/cloud/escrow", { token: await cloudToken(dataDir, preferred) });
+    const rows = (Array.isArray(answer) ? answer : answer ? [answer] : []).filter((row) => row?.sealed);
+    const blob = rows.sort((a, b) => String(b.created_at ?? "").localeCompare(String(a.created_at ?? "")) || Number(b.id ?? 0) - Number(a.id ?? 0))[0];
+    if (!blob?.sealed)
+        fail("archive_not_found", "No sealed copy is stored for this account. Store one with `sealkeep recovery seal`.");
+    const envelope = typeof blob.envelope === "string" ? JSON.parse(blob.envelope) : blob.envelope;
+    return openEscrow(envelope, Buffer.from(blob.sealed, "base64"), rawPhrase);
+}
+/* ------------------------------------------------------------------ uploads */
+/** Asks for permission to write exactly one object. The key is chosen server-side. */
+export async function requestUpload(dataDir, input, preferred) {
+    return call("/v1/cloud/uploads", {
+        method: "POST",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ vault_ref: input.vaultRef, ciphertext_sha256: input.ciphertextSha256, bytes: input.bytes })
+    });
+}
+/**
+ * What this build can actually honor, checked at run time because a lease
+ * arrives from the network and the types above only constrain our own code.
+ *
+ * - An unknown vended provider must be refused before anything is signed:
+ *   `S3Endpoint` derives a default host when none is given, and for a provider
+ *   it does not recognise that default is the AWS endpoint — a signed request,
+ *   carrying the vended key id, sent to a host the lease never named.
+ * - An unknown presigned method, or a non-http upload URL, must be refused
+ *   before anything is fetched: a control plane speaking a newer delegation
+ *   (the CREDENTIALS contract in docs/managed-streaming-contract.md, or the
+ *   placeholder `vaultline+pending://` leases) has to surface as "update the
+ *   CLI", not as whatever fetch makes of a marker that is not an HTTP verb.
+ */
+const SIGNABLE_VENDED_PROVIDERS = new Set(["s3", "r2", "b2"]);
+const PRESIGNED_UPLOAD_METHODS = new Set(["PUT", "POST"]);
+/**
+ * A credential past its expiry signs requests the provider refuses — and a
+ * long resume can outlive a one-hour key. Refusing HERE, with the fix in the
+ * sentence, beats a 403 whose meaning the person has to reverse-engineer.
+ * A minute of skew is allowed: clocks disagree, and the provider is the
+ * judge that matters.
+ */
+function assertVendedFresh(v, lease) {
+    const fallback = lease.expires_at;
+    const expires = Date.parse(v.expires_at ?? fallback ?? "");
+    if (Number.isFinite(expires) && expires < Date.now() - 60_000) {
+        fail("invalid_argument", "The storage credential for this upload has expired. Request a new lease (re-run the upload) and it continues from where it stopped.");
+    }
+}
+function assertVendedSignable(v) {
+    if (!SIGNABLE_VENDED_PROVIDERS.has(v.provider)) {
+        fail("internal", `Sealkeep Cloud vended a credential for "${v.provider}", which this version of the CLI cannot sign requests for. Update the CLI and try again.`);
+    }
+}
+/**
+ * Straight to storage, whichever way the lease delegated.
+ *
+ * A presigned lease is obeyed verbatim — the signer chose the method and the
+ * headers, and changing either invalidates the signature. A vended lease is
+ * signed here with the same SigV4 code the bring-your-own-bucket path uses, so
+ * managed B2 and a customer's own S3 bucket travel through one tested signer
+ * rather than two. A lease naming a delegation this build does not know is
+ * refused before a single byte or signature leaves the machine.
+ */
+export async function putCiphertext(lease, ciphertext, signal) {
+    if (lease.vended) {
+        assertVendedSignable(lease.vended);
+        assertVendedFresh(lease.vended, lease);
+        const { S3UploadClient } = await import("./providers/s3.js");
+        const v = lease.vended;
+        const client = new S3UploadClient(v.provider, { provider: v.provider, region: v.region, bucket: v.bucket, host: v.host, port: v.port, protocol: v.protocol }, { accessKeyId: v.akid, secretAccessKey: v.secret_access_key, sessionToken: v.session_token });
+        await client.upload({
+            archiveId: lease.vault_ref, provider: v.provider, objectKey: lease.object_key, expiresAt: lease.expires_at,
+            method: "MULTIPART", uploadUrl: "", requiredHeaders: {}, status: "active", uploadable: true
+        }, ciphertext);
+        return;
+    }
+    if (!lease.upload_url?.url)
+        fail("internal", "Sealkeep Cloud returned a lease with nowhere to upload to");
+    const { url, method, headers } = lease.upload_url;
+    if (!PRESIGNED_UPLOAD_METHODS.has((method || "PUT").toUpperCase())) {
+        fail("internal", `Sealkeep Cloud returned an upload lease with method "${method}", which this version of the CLI does not know how to perform. Update the CLI and try again.`);
+    }
+    if (!/^https?:\/\//i.test(url)) {
+        fail("internal", "Sealkeep Cloud returned an upload address that is not an http(s) URL; refusing to send the archive anywhere else.");
+    }
+    const response = await fetch(url, { method: method || "PUT", headers, body: new Uint8Array(ciphertext), ...(signal ? { signal } : {}) });
+    if (!response.ok)
+        fail("internal", `Storage rejected the upload: ${response.status} ${(await response.text()).slice(0, 200)}`);
+}
+/**
+ * Proves managed storage is holding the bytes we sent, before we tell retention
+ * it may delete the local copy.
+ *
+ * Returns a description of the problem, or null when the object is proven.
+ *
+ * `completeUpload` alone is not proof: it is a metering call to the control
+ * plane, and a POST that returns 200 says the lease was consumed, not that any
+ * object exists. Writing `verifiedAt` on the strength of it — which is what this
+ * path used to do, under a comment claiming the opposite — meant a paying
+ * customer could push to storage that kept nothing and then have retention
+ * trash the only copy.
+ */
+async function verifyStored(dataDir, lease, object, digest, preferred) {
+    if (lease.vended) {
+        assertVendedSignable(lease.vended);
+        assertVendedFresh(lease.vended, lease);
+        // The machine holds a credential scoped to this object, so it can ask the
+        // provider directly. Cheap, and no egress.
+        const { S3UploadClient } = await import("./providers/s3.js");
+        const v = lease.vended;
+        const client = new S3UploadClient(v.provider, { provider: v.provider, region: v.region, bucket: v.bucket, host: v.host, port: v.port, protocol: v.protocol }, { accessKeyId: v.akid, secretAccessKey: v.secret_access_key, sessionToken: v.session_token });
+        const head = await client.head({
+            archiveId: lease.vault_ref, provider: v.provider, objectKey: lease.object_key, expiresAt: lease.expires_at,
+            method: "MULTIPART", uploadUrl: "", requiredHeaders: {}, status: "active", uploadable: true
+        });
+        if (!head.exists)
+            return "the provider does not report the object as present";
+        if (head.bytes !== object.length)
+            return `the provider stored ${head.bytes} bytes; ${object.length} were sent`;
+        return null;
+    }
+    // A presigned PUT URL cannot be reused for a HEAD, so the only proof
+    // available on this path is reading the object back and hashing it. That
+    // costs egress on every push, which is a real reason to finish moving
+    // managed storage onto a provider that vends credentials instead.
+    const roundTrip = await pullCiphertext(dataDir, lease.vault_ref, preferred);
+    if (roundTrip.bytes !== object.length)
+        return `storage returned ${roundTrip.bytes} bytes; ${object.length} were sent`;
+    if (sha256(roundTrip.ciphertext) !== digest)
+        return "the bytes read back do not match what was uploaded";
+    return null;
+}
+export async function completeUpload(dataDir, leaseId, bytes, preferred) {
+    return call(`/v1/cloud/uploads/${leaseId}/complete`, {
+        method: "POST",
+        token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ bytes })
+    });
+}
+/** What managed storage is holding for this account. The ref is what `sealkeep open` takes. */
+/**
+ * The managed index slot: one sealed content index per account, moved through
+ * control-plane-signed URLs exactly like archive objects — known lengths, the
+ * signer the plane already has. `kind` is "meta" (the tiny envelope, read
+ * first to decide freshness) or "blob" (the sealed index itself). The plane
+ * sees ciphertext sizes and update times; tokens never leave the machines.
+ */
+/* ------------------------------------------------------- drive via account */
+/**
+ * Drive OAuth on the account's shared Google client, Paul's way: reuse the
+ * client the backend already owns, keep its secret THERE, and let this
+ * machine hold only its own tokens. The CLI opens the consent URL, a loopback
+ * listener on the registered fixed port catches the code, and the plane —
+ * authenticated as this account — exchanges it. Nothing is stored server-side.
+ */
+export async function gdriveOauthConfig(dataDir, preferred) {
+    return call(`/v1/cloud/gdrive/config`, { token: await cloudToken(dataDir, preferred) });
+}
+export async function gdriveExchange(dataDir, input, preferred) {
+    return call(`/v1/cloud/gdrive/exchange`, {
+        method: "POST", token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ code: input.code, redirect_uri: input.redirectUri })
+    });
+}
+export async function gdriveRefresh(dataDir, refreshToken, preferred) {
+    const fresh = await call(`/v1/cloud/gdrive/refresh`, {
+        method: "POST", token: await cloudToken(dataDir, preferred),
+        body: JSON.stringify({ refresh_token: refreshToken })
+    });
+    return { accessToken: fresh.access_token, expiresIn: fresh.expires_in ?? 3600 };
+}
+export async function gdriveClaim(dataDir, state, preferred) {
+    try {
+        return await call(`/v1/cloud/gdrive/claim`, {
+            method: "POST", token: await cloudToken(dataDir, preferred),
+            body: JSON.stringify({ state })
+        });
+    }
+    catch (error) {
+        if (isVaultlineError(error) && /returned 404|No pending/i.test(error.message))
+            return null;
+        throw error;
+    }
+}
+/**
+ * The consent flow for the shared client. Two shapes, decided by the server's
+ * registered redirect: a REMOTE https callback (the plane exchanges and parks
+ * the tokens; this machine polls its one-time state — works even when the
+ * browser lives on another device), or a loopback listener that catches the
+ * code here and exchanges through the authed endpoint.
+ */
+export async function connectGdriveViaCloud(dataDir, options = {}) {
+    const { createServer } = await import("node:http");
+    const { randomBytes } = await import("node:crypto");
+    const config = await gdriveOauthConfig(dataDir, options.preferred);
+    const redirect = new URL(config.redirect_uri);
+    const state = randomBytes(16).toString("base64url");
+    if (redirect.protocol === "https:") {
+        const consent = new URL("https://accounts.google.com/o/oauth2/v2/auth");
+        consent.searchParams.set("client_id", config.client_id);
+        consent.searchParams.set("redirect_uri", config.redirect_uri);
+        consent.searchParams.set("response_type", "code");
+        consent.searchParams.set("scope", config.scope);
+        consent.searchParams.set("access_type", "offline");
+        consent.searchParams.set("prompt", "consent");
+        consent.searchParams.set("state", state);
+        options.onConsentUrl?.(consent.toString());
+        const { launchBrowser } = await import("./providers/gdrive.js");
+        await Promise.resolve((options.opener ?? launchBrowser)(consent.toString())).catch(() => undefined);
+        const deadline = Date.now() + (options.timeoutMs ?? 300_000);
+        while (Date.now() < deadline) {
+            const parcel = await gdriveClaim(dataDir, state, options.preferred);
+            if (parcel)
+                return { kind: "gdrive", refreshToken: parcel.refresh_token, clientId: config.client_id, exchange: "cloud" };
+            await new Promise((rest) => setTimeout(rest, options.pollMs ?? 2000));
+        }
+        throw new VaultlineError("unauthorized", "No consent arrived in time. Run the connect again.");
+    }
+    const server = createServer();
+    await new Promise((ready, refuse) => { server.once("error", refuse); server.listen(Number(redirect.port), "127.0.0.1", ready); });
+    let timer;
+    const code = new Promise((resolve, reject) => {
+        timer = setTimeout(() => reject(new VaultlineError("unauthorized", "No response from the browser in time. Run the connect again.")), options.timeoutMs ?? 300_000);
+        server.on("request", (request, response) => {
+            const url = new URL(request.url ?? "/", config.redirect_uri);
+            if (url.pathname !== redirect.pathname) {
+                response.writeHead(404);
+                response.end();
+                return;
+            }
+            const deny = (message) => {
+                response.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+                response.end("<p>Sealkeep could not finish connecting. Return to the terminal.</p>");
+                reject(new VaultlineError("unauthorized", message));
+            };
+            if (url.searchParams.get("error"))
+                return deny(`Google reported: ${url.searchParams.get("error")}`);
+            if (url.searchParams.get("state") !== state)
+                return deny("The browser reply did not match this connection attempt (state mismatch)");
+            const received = url.searchParams.get("code");
+            if (!received)
+                return deny("The browser reply carried no authorization code");
+            response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            response.end("<p>Sealkeep is connected to Google Drive. You can close this tab.</p>");
+            resolve(received);
+        });
+    });
+    code.catch(() => { });
+    const consent = new URL("https://accounts.google.com/o/oauth2/v2/auth");
+    consent.searchParams.set("client_id", config.client_id);
+    consent.searchParams.set("redirect_uri", config.redirect_uri);
+    consent.searchParams.set("response_type", "code");
+    consent.searchParams.set("scope", config.scope);
+    consent.searchParams.set("access_type", "offline");
+    consent.searchParams.set("prompt", "consent");
+    consent.searchParams.set("state", state);
+    try {
+        options.onConsentUrl?.(consent.toString());
+        const { launchBrowser } = await import("./providers/gdrive.js");
+        await Promise.resolve((options.opener ?? launchBrowser)(consent.toString())).catch(() => undefined);
+        const authorizationCode = await code;
+        const tokens = await gdriveExchange(dataDir, { code: authorizationCode, redirectUri: config.redirect_uri }, options.preferred);
+        return { kind: "gdrive", refreshToken: tokens.refresh_token, clientId: config.client_id, exchange: "cloud" };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        server.close();
+    }
+}
+export async function pushIndexObject(dataDir, kind, body, preferred) {
+    const token = await cloudToken(dataDir, preferred);
+    const lease = await call(`/v1/cloud/index/upload`, { method: "POST", body: JSON.stringify({ kind, bytes: body.length }), token });
+    const target = lease.upload_url ?? fail("internal", "The control plane vended no upload URL for the index slot");
+    const response = await fetch(target.url, { method: target.method || "PUT", headers: target.headers ?? {}, body: new Uint8Array(body) });
+    if (!response.ok)
+        fail("internal", `The index ${kind} upload was refused: ${response.status} ${response.statusText}`);
+}
+export async function pullIndexObject(dataDir, kind, preferred) {
+    const token = await cloudToken(dataDir, preferred);
+    const lease = await call(`/v1/cloud/index/download?kind=${kind}`, { token }).catch((error) => {
+        if (isVaultlineError(error) && /not.*found|no index/i.test(error.message))
+            return null;
+        throw error;
+    });
+    if (!lease?.download?.url)
+        return null;
+    const response = await fetch(lease.download.url);
+    if (response.status === 404)
+        return null;
+    if (!response.ok)
+        fail("internal", `The index ${kind} download was refused: ${response.status} ${response.statusText}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+export async function listCloudArchives(dataDir, preferred) {
+    const token = await cloudToken(dataDir, preferred);
+    const rows = await call("/v1/cloud/archives", { token });
+    return Array.isArray(rows) ? rows : [];
+}
+/**
+ * Really deletes one stored object from managed storage.
+ *
+ * Goes through the control plane rather than storage directly, because it is
+ * the same call the account panel's Archives section makes — one delete path,
+ * so the product and the panel cannot come to mean different things by
+ * "deleted". The control plane removes the object and its row, and billing
+ * follows the row.
+ */
+export async function deleteCloudArchive(dataDir, vaultRef, preferred) {
+    await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}`, { method: "DELETE", token: await cloudToken(dataDir, preferred) });
+}
+/**
+ * Fetches the ciphertext, whichever way the control plane delegated.
+ *
+ * Symmetrical with putCiphertext: a presigned URL is followed verbatim, and a
+ * vended credential is signed here. Providers that Spala cannot presign for —
+ * anything S3-compatible — arrive as the vended shape.
+ */
+async function fetchLeasedObject(lease) {
+    if (lease.vended) {
+        assertVendedSignable(lease.vended);
+        assertVendedFresh(lease.vended, {});
+        const { S3UploadClient } = await import("./providers/s3.js");
+        const v = lease.vended;
+        if (!lease.object_key)
+            fail("internal", "Sealkeep Cloud vended a credential but no object key");
+        const client = new S3UploadClient(v.provider, { provider: v.provider, region: v.region, bucket: v.bucket, host: v.host, port: v.port, protocol: v.protocol }, { accessKeyId: v.akid, secretAccessKey: v.secret_access_key, sessionToken: v.session_token });
+        return client.download({
+            archiveId: lease.vault_ref, provider: v.provider, objectKey: lease.object_key, expiresAt: new Date(Date.now() + 9e5).toISOString(),
+            method: "MULTIPART", uploadUrl: "", requiredHeaders: {}, status: "active", uploadable: true
+        });
+    }
+    if (!lease.download?.url)
+        fail("internal", "Sealkeep Cloud returned a lease with nowhere to download from");
+    const response = await fetch(lease.download.url, { method: lease.download.method ?? "GET", headers: lease.download.headers });
+    if (!response.ok)
+        fail("internal", `Storage refused the download: ${response.status} ${response.statusText}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+/**
+ * A byte range of a stored object, for chunk-granular reads. The whole-object
+ * hash cannot be checked on a slice — that is the point of a slice — so the
+ * caller's integrity comes from the per-chunk hashes and AEAD tags inside
+ * (see vaultline-crypto/chunk-access). Only the presigned-URL lease shape
+ * supports ranges today; a vended-credential lease falls back to whole-object.
+ */
+export async function pullCiphertextRange(dataDir, vaultRef, storedOffset, storedLength, preferred) {
+    const token = await cloudToken(dataDir, preferred);
+    const lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token });
+    if (!lease.download?.url) {
+        const whole = await fetchLeasedObject(lease);
+        return whole.subarray(storedOffset, storedOffset + storedLength);
+    }
+    const response = await fetch(lease.download.url, { headers: { range: `bytes=${storedOffset}-${storedOffset + storedLength - 1}` } });
+    if (response.status === 206)
+        return Buffer.from(await response.arrayBuffer());
+    if (response.ok) {
+        // A store that ignores Range answers 200 with everything; take the slice
+        // rather than failing a read that can still be served.
+        return Buffer.from(await response.arrayBuffer()).subarray(storedOffset, storedOffset + storedLength);
+    }
+    return fail("internal", `Storage refused the ranged read: ${response.status} ${response.statusText}`);
+}
+/**
+ * Existence and stored size of a managed object, proven against STORAGE, not
+ * the plane's row: the row is minted by metering and a metering row is not an
+ * object. A one-byte ranged GET on the download URL answers both questions
+ * for the cost of a header — the Content-Range total is the provider's own
+ * count. This is what lets chunk-folder verification and resume treat managed
+ * storage with exactly the discipline `verifyStored` demands of it.
+ */
+export async function statCiphertext(dataDir, vaultRef, preferred) {
+    const token = await cloudToken(dataDir, preferred);
+    let lease;
+    try {
+        lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token });
+    }
+    catch (error) {
+        if (isVaultlineError(error) && (error.code === "archive_not_found" || /returned 404|not[ _-]?found/i.test(error.message))) {
+            return { exists: false, bytes: 0 };
+        }
+        throw error;
+    }
+    if (!lease.download?.url)
+        return { exists: true, bytes: lease.bytes };
+    const response = await fetch(lease.download.url, { headers: { range: "bytes=0-0" } });
+    if (response.status === 404)
+        return { exists: false, bytes: 0 };
+    if (response.status === 206) {
+        const total = Number((response.headers.get("content-range") ?? "").split("/").pop());
+        await response.arrayBuffer().catch(() => undefined);
+        return { exists: true, bytes: Number.isFinite(total) && total > 0 ? total : lease.bytes };
+    }
+    if (response.ok)
+        return { exists: true, bytes: Buffer.from(await response.arrayBuffer()).length };
+    return fail("internal", `Storage refused the presence check: ${response.status} ${response.statusText}`);
+}
+export async function pullCiphertext(dataDir, vaultRef, preferred) {
+    const token = await cloudToken(dataDir, preferred);
+    const lease = await call(`/v1/cloud/archives/${encodeURIComponent(vaultRef)}/download`, { token });
+    const ciphertext = await fetchLeasedObject(lease);
+    const digest = createHash("sha256").update(ciphertext).digest("hex");
+    if (digest !== lease.ciphertext_sha256)
+        fail("internal", "Downloaded ciphertext does not match the hash recorded at upload; refusing it");
+    return { ciphertext, bytes: ciphertext.length };
+}
+/**
+ * Managed objects are self-describing.
+ *
+ * The envelope — wrapped keys, nonce prefix, chunk layout — used to live only in
+ * the local index, which meant a customer who lost the machine held ciphertext in
+ * our bucket, their identity key in escrow, and no way to put the two together.
+ * That is not a backup. So the uploaded object carries its own envelope:
+ *
+ *   "VLA1" | uint32be(envelopeJsonLength) | envelopeJson | ciphertext
+ *
+ * The envelope's archive key is already wrapped to the recovery phrase, so this
+ * adds nothing the server can read; the blob stays opaque to us end to end.
+ * Objects written before this change have no magic and unframe as legacy, which
+ * keeps them restorable from the machine that made them.
+ */
+const OBJECT_MAGIC = Buffer.from("VLA1", "ascii");
+export function frameObject(envelope, ciphertext) {
+    const meta = Buffer.from(JSON.stringify(envelope), "utf8");
+    const length = Buffer.allocUnsafe(4);
+    length.writeUInt32BE(meta.length, 0);
+    return Buffer.concat([OBJECT_MAGIC, length, meta, ciphertext]);
+}
+export function unframeObject(blob) {
+    if (blob.length < OBJECT_MAGIC.length + 4 || !blob.subarray(0, OBJECT_MAGIC.length).equals(OBJECT_MAGIC))
+        return { envelope: null, ciphertext: blob };
+    const metaLength = blob.readUInt32BE(OBJECT_MAGIC.length);
+    const start = OBJECT_MAGIC.length + 4;
+    if (metaLength > blob.length - start)
+        fail("internal", "Archive header is truncated");
+    try {
+        return { envelope: JSON.parse(blob.subarray(start, start + metaLength).toString("utf8")), ciphertext: blob.subarray(start + metaLength) };
+    }
+    catch {
+        fail("internal", "Archive header is not readable");
+    }
+}
+/**
+ * Fetch one archive and open it, on any machine.
+ *
+ * This is the whole disaster-recovery story in one call: the recovery phrase
+ * unwraps the archive key from the envelope the object carries, so a fresh
+ * laptop with nothing but the phrase can read the archive back. The plaintext
+ * hash recorded at seal time is checked inside decryptArchive, after the AEAD
+ * has authenticated every chunk.
+ */
+export async function openFromCloud(dataDir, vaultRef, destination, rawPhrase, preferred) {
+    const { ciphertext: blob } = await pullCiphertext(dataDir, vaultRef, preferred);
+    const { envelope, ciphertext } = unframeObject(blob);
+    if (!envelope) {
+        // Two very different objects arrive with no envelope: a plain-mode
+        // archive (readable by its owner's explicit choice at setup — bare gzip,
+        // recognisable by its magic bytes) and a genuinely pre-envelope legacy
+        // object. Refusing the first with advice about the second sent people
+        // hunting for a machine that does not need to exist.
+        if (blob.length > 2 && blob[0] === 0x1f && blob[1] === 0x8b) {
+            const { gunzip } = await import("node:zlib");
+            const { promisify } = await import("node:util");
+            const plain = await promisify(gunzip)(blob);
+            await writeFile(destination, plain, { mode: 0o600 });
+            return { output: destination, bytes: plain.length };
+        }
+        fail("archive_not_found", `${vaultRef} was stored before archives carried their own envelope. Restore it with \`sealkeep recover ${vaultRef} <destination>\` on the machine that archived it, then push it again.`);
+    }
+    let plaintext;
+    try {
+        plaintext = openEnvelope(envelope, ciphertext, { phrase: canonicalPhrase(rawPhrase) });
+    }
+    catch (error) {
+        fail("recovery_phrase_mismatch", `Unable to open ${vaultRef}: ${error instanceof Error ? error.message : "decryption failed"}`);
+    }
+    await writeFile(destination, plaintext, { mode: 0o600 });
+    return { output: destination, bytes: plaintext.length };
+}
+/**
+ * The judgement, kept separate from the fetching so it can be tested honestly.
+ *
+ * `recorded` is what the control plane says the archive is; `got` is what
+ * storage actually returned, or the error it failed with. A raw status code is
+ * not an explanation, so a missing object is named in words a customer can act
+ * on.
+ */
+export function classifyArchive(recorded, got) {
+    const bytes = Number(recorded.bytes) || 0;
+    if ("error" in got) {
+        return {
+            vaultRef: recorded.vault_ref, bytes, ok: false,
+            problem: /\b404\b/.test(got.error) ? "listed as stored, but there is no object behind it" : got.error
+        };
+    }
+    if (got.length !== bytes) {
+        return { vaultRef: recorded.vault_ref, bytes, ok: false, problem: `storage returned ${got.length} bytes, the record says ${bytes}` };
+    }
+    return { vaultRef: recorded.vault_ref, bytes, ok: true };
+}
+/**
+ * Proves the archives really are retrievable.
+ *
+ * A backup nobody has tested is a hope, not a backup. This fetches each durable
+ * archive back and checks it against the hash recorded at upload, so the two
+ * ways an archive can quietly rot are both caught: the object is missing from
+ * storage, or the bytes no longer match what was sealed.
+ *
+ * It deliberately re-downloads rather than trusting a HEAD. Size alone would
+ * pass an object that was truncated and re-padded, and the whole point of the
+ * exercise is to distrust the happy path.
+ */
+export async function verifyArchives(dataDir, options = {}, preferred) {
+    const rows = (await listCloudArchives(dataDir, preferred)).filter((row) => row.state === "durable");
+    const checked = typeof options.limit === "number" ? rows.slice(0, options.limit) : rows;
+    const results = [];
+    for (const row of checked) {
+        const bytes = Number(row.bytes) || 0;
+        let check;
+        try {
+            const { ciphertext } = await pullCiphertext(dataDir, row.vault_ref, preferred);
+            check = classifyArchive({ vault_ref: row.vault_ref, bytes }, ciphertext);
+        }
+        catch (error) {
+            check = classifyArchive({ vault_ref: row.vault_ref, bytes }, { error: error instanceof Error ? error.message : "unknown error" });
+        }
+        // Record what was just proved.
+        //
+        // Verification used to be write-only: it fetched every archive back,
+        // matched every hash, printed "all archives fetched back and matched", and
+        // changed nothing. So an archive whose upload succeeded but whose process
+        // died before writing the marker — a killed terminal, a closed laptop —
+        // stayed "local only" forever, and `retention` refused to reclaim its
+        // source because reclaiming requires a verified remote. The bytes were
+        // safe, the product knew they were safe, and it still would not act on it.
+        //
+        // Only ever upgrades: a record that already claims a verified remote is
+        // left alone, so this cannot overwrite a bring-your-own-bucket target with
+        // a managed one.
+        if (check.ok)
+            await recordVerified(dataDir, check.vaultRef, bytes).catch(() => undefined);
+        results.push(check);
+        options.onProgress?.(check);
+    }
+    return results;
+}
+/** Writes the verified marker for an archive this machine holds locally. */
+async function recordVerified(dataDir, vaultRef, bytes) {
+    const record = (await listArchives(dataDir)).find((item) => item.id === vaultRef);
+    if (!record || record.version !== 2 || record.remote?.verifiedAt)
+        return;
+    const stored = {
+        provider: "vaultline", bucket: "vaultline-managed", objectKey: vaultRef,
+        bytes, checksum: record.cipher.ciphertextSha256, verifiedAt: new Date().toISOString()
+    };
+    await writeRecord((await readConfig(dataDir)).storage.root, { ...record, remote: stored });
+}
+export async function pushArchive(dataDir, archiveId, preferred, options = {}) {
+    await readConfig(dataDir);
+    const record = (await listArchives(dataDir)).find((item) => item.id === archiveId);
+    if (!record)
+        fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
+    const ciphertext = await readFile(record.objectPath);
+    if (sha256(ciphertext) !== record.cipher.ciphertextSha256)
+        fail("ciphertext_integrity_failed", "Ciphertext changed on disk since it was archived", { archiveId });
+    // What we store is the envelope plus the ciphertext, so the archive can be
+    // opened by anyone holding the recovery phrase and nothing else.
+    const object = record.envelope ? frameObject(record.envelope, ciphertext) : ciphertext;
+    const digest = sha256(object);
+    const lease = await requestUpload(dataDir, { vaultRef: record.id, ciphertextSha256: digest, bytes: object.length }, preferred);
+    await putCiphertext(lease, object, options.signal);
+    try {
+        await completeUpload(dataDir, lease.lease_id, object.length, preferred);
+        // Retention reads remote.verifiedAt to decide whether a source may be
+        // reclaimed, so this is the field that authorises deleting a customer's
+        // only local copy. It is written only once storage has been made to prove
+        // it holds these exact bytes — the same discipline the bring-your-own-bucket
+        // path follows.
+        const problem = await verifyStored(dataDir, lease, object, digest, preferred);
+        if (problem) {
+            return {
+                archiveId: record.id, objectKey: lease.object_key, bytes: object.length, durable: false,
+                note: `Uploaded, but managed storage could not be proven to hold it: ${problem}. The local copy is untouched.`
+            };
+        }
+        const stored = {
+            provider: "vaultline", bucket: "vaultline-managed", objectKey: lease.object_key,
+            bytes: object.length, checksum: digest, verifiedAt: new Date().toISOString()
+        };
+        await writeRecord((await readConfig(dataDir)).storage.root, { ...record, remote: stored });
+        return { archiveId: record.id, objectKey: lease.object_key, bytes: object.length, durable: true };
+    }
+    catch (error) {
+        return {
+            archiveId: record.id, objectKey: lease.object_key, bytes: object.length, durable: false,
+            note: `Uploaded, but the control plane did not record it: ${error instanceof Error ? error.message : "unknown error"}`
+        };
+    }
+}