sealkeep 0.5.0

package/dist/src/share.js

@@ -0,0 +1,68 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { fail } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { isV2 } from "./types.js";
+import { listArchives, readConfig } from "./vault.js";
+import { frameObject, unframeObject } from "./cloud.js";
+import { openArchiveToFile, rewrapArchive } from "../packages/vaultline-crypto/src/index.js";
+import { materialiseArchive } from "./offload.js";
+import { randomInt } from "node:crypto";
+import { WORDS } from "./mnemonic.js";
+const PASSCODE_WORDS = 6;
+export function generateSharePasscode() {
+    return Array.from({ length: PASSCODE_WORDS }, () => WORDS[randomInt(WORDS.length)]).join(" ");
+}
+export async function createShareBundle(dataDir, archiveId, bundlePath, options = { vaultPhrase: "" }) {
+    const record = (await listArchives(dataDir)).find((item) => item.id === archiveId);
+    if (!record)
+        fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
+    if (!isV2(record))
+        fail("invalid_argument", `Archive ${archiveId} uses format v1. Run: sealkeep migrate`, { archiveId });
+    const config = await readConfig(dataDir);
+    if (config.storageMode === "plain")
+        fail("invalid_argument", "A plain vault's archives are ordinary readable files — send the file itself; a bundle would only pretend to add protection.");
+    const passcode = options.passcode ?? generateSharePasscode();
+    // Replace, never add: the bundle's one wrap is the passcode's. The vault
+    // phrase opening a bundle would mean every shared file doubles as an oracle
+    // for the vault.
+    const shared = rewrapArchive(record.envelope, { phrase: canonicalPhrase(options.vaultPhrase) }, [{ kind: "phrase", phrase: canonicalPhrase(passcode) }], { mode: "replace" });
+    // The ciphertext may live locally or be offloaded to the bucket — either
+    // way the bundle carries the same bytes the archive is made of.
+    const materialised = await materialiseArchive(dataDir, record);
+    try {
+        const ciphertext = await readFile(materialised.path);
+        const bundle = frameObject(shared, ciphertext);
+        await writeFile(bundlePath, bundle, { mode: 0o600 });
+        await recordAudit(dataDir, "archive.share", "allowed", { archiveId, bytes: bundle.length });
+        return { bundlePath, passcode, bytes: bundle.length, archiveId };
+    }
+    finally {
+        await materialised.release();
+    }
+}
+/**
+ * Opens a bundle anywhere — no vault, no account, no config. The passcode is
+ * the whole key, which is exactly the promise made to the person receiving it.
+ */
+export async function openShareBundle(bundlePath, destination, passcode) {
+    const blob = await readFile(bundlePath);
+    const { envelope, ciphertext } = unframeObject(blob);
+    if (!envelope)
+        fail("invalid_argument", `${bundlePath} is not a Sealkeep share bundle.`);
+    // openArchiveToFile reads the ciphertext from a path; the bundle's payload
+    // is written beside the destination momentarily, then removed.
+    const { mkdtemp, rm, writeFile: write } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const scratch = await mkdtemp(join(tmpdir(), "vaultline-share-"));
+    const payload = join(scratch, "payload");
+    try {
+        await write(payload, ciphertext, { mode: 0o600 });
+        const opened = await openArchiveToFile(envelope, payload, destination, { phrase: canonicalPhrase(passcode) });
+        return { bytes: opened.bytes };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}

package/dist/src/spool.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The spool: journals for in-flight streamed seals.
+ *
+ * A streamed seal writes ciphertext straight into a provider session and keeps
+ * nothing locally, so a crash mid-object used to mean starting the whole
+ * upload over. A spool journal records everything a *later process* needs to
+ * finish the object instead: which chunks the provider already holds, where
+ * the chunk numbering and the whole-object hashes stood, and the provider's
+ * own session state (an S3 uploadId and its parts, a GCS session URI).
+ *
+ * The journal never holds plaintext key material. The archive key is wrapped
+ * with the same recipients machinery envelopes use — the same array shape, the
+ * same unwrap — so resuming demands the vault phrase or a device key exactly
+ * as restoring does, and a stolen journal is worth no more than a stolen
+ * envelope. The file is still 0600: wrapped keys plus provider session state
+ * are nobody else's business.
+ *
+ * Every write is temp-then-rename, because a resume that reads a torn journal
+ * would re-seal from the wrong chunk index and corrupt the object it was
+ * trying to save. Rename is atomic on one filesystem, so a concurrent reader
+ * sees the old journal or the new one, never a mixture.
+ */
+import { type ChunkHeader, type Suite, type Unlock, type WrappedKey } from "../packages/vaultline-crypto/src/index.js";
+export declare const SPOOL_VERSION = 1;
+export type SpoolJournal = {
+    version: typeof SPOOL_VERSION;
+    archiveId: string;
+    suite: Suite;
+    provider: string;
+    bucket: string;
+    objectKey: string;
+    source: {
+        path: string;
+        totalBytes: number;
+        chunkBytes: number;
+    };
+    /** The archive key, wrapped for the vault's recipients — the same array shape envelopes carry. Never the raw key. */
+    wrappedKeys: WrappedKey[];
+    noncePrefixB64: string;
+    /** Chunks FULLY handed to the provider; resume re-seals from here. */
+    nextChunkIndex: number;
+    /** Hex SHA-256 of source bytes `[0, nextChunkIndex * chunkBytes)`, so a resume can prove the source has not changed under the finished chunks. */
+    consumedPrefixSha256: string;
+    /** Headers for chunks already sent, in order — the front half of the final envelope's chunk list. */
+    chunkHeaders: ChunkHeader[];
+    /** `StreamingSha256.exportState()` strings for the whole-object plaintext and stored hashes. */
+    hashState: {
+        plaintext: string;
+        stored: string;
+    };
+    /** Opaque JSON the provider layer owns: S3 uploadId and parts, or a GCS session URI. */
+    providerState: unknown;
+    createdAt: string;
+    updatedAt: string;
+};
+/** What a caller supplies; `version` and the timestamps are stamped here so they cannot be wrong. */
+export type SpoolDraft = Omit<SpoolJournal, "version" | "createdAt" | "updatedAt">;
+/** Identity and origin are fixed at creation; everything else may move as chunks land. */
+export type SpoolPatch = Partial<Omit<SpoolJournal, "version" | "archiveId" | "createdAt" | "updatedAt">>;
+export declare function createSpool(dataDir: string, draft: SpoolDraft, options?: {
+    now?: number;
+}): Promise<SpoolJournal>;
+export declare function loadSpool(dataDir: string, archiveId: string): Promise<SpoolJournal>;
+export declare function updateSpool(dataDir: string, archiveId: string, patch: SpoolPatch, options?: {
+    now?: number;
+}): Promise<SpoolJournal>;
+/**
+ * The newest journal for a source file, or null. Newest by `updatedAt` because
+ * that tracks actual upload progress; `createdAt` breaks ties. Unreadable or
+ * foreign files in the spool directory are skipped, not fatal — one stray temp
+ * or hand-dropped file must not block resuming a good upload.
+ */
+export declare function findSpoolForSource(dataDir: string, sourcePath: string): Promise<SpoolJournal | null>;
+/**
+ * Removes a journal for good. No overwrite pass: the file holds only wrapped
+ * keys and provider session state, both worthless without a vault secret. The
+ * unlink itself must be sure, though — `force` only forgives a journal that is
+ * already gone (shred is a cleanup path and runs twice sometimes); any other
+ * failure surfaces, because a journal that lingers would later present a dead
+ * provider session as resumable.
+ */
+/**
+ * One resume per journal, across processes. Two processes continuing the same
+ * journal would drive the same multipart/session — racing part numbers, and
+ * (worse) widening the nonce-reuse window if the source changes between them.
+ * The lock is an O_EXCL sentinel beside the journal: cheap, crash-tolerant
+ * (a holder that died leaves a stale file, taken over after 30 minutes), and
+ * refused with a sentence rather than queued.
+ */
+export declare function acquireSpoolLock(dataDir: string, archiveId: string, options?: {
+    now?: number;
+}): Promise<{
+    release: () => Promise<void>;
+}>;
+export declare function shredSpool(dataDir: string, archiveId: string): Promise<void>;
+/** Opens the journal's wrapped archive key. The caller owns the returned bytes and zeroizes them. */
+export declare function unwrapSpoolKey(journal: SpoolJournal, unlock: Unlock): Buffer;

package/dist/src/spool.js

@@ -0,0 +1,213 @@
+/**
+ * The spool: journals for in-flight streamed seals.
+ *
+ * A streamed seal writes ciphertext straight into a provider session and keeps
+ * nothing locally, so a crash mid-object used to mean starting the whole
+ * upload over. A spool journal records everything a *later process* needs to
+ * finish the object instead: which chunks the provider already holds, where
+ * the chunk numbering and the whole-object hashes stood, and the provider's
+ * own session state (an S3 uploadId and its parts, a GCS session URI).
+ *
+ * The journal never holds plaintext key material. The archive key is wrapped
+ * with the same recipients machinery envelopes use — the same array shape, the
+ * same unwrap — so resuming demands the vault phrase or a device key exactly
+ * as restoring does, and a stolen journal is worth no more than a stolen
+ * envelope. The file is still 0600: wrapped keys plus provider session state
+ * are nobody else's business.
+ *
+ * Every write is temp-then-rename, because a resume that reads a torn journal
+ * would re-seal from the wrong chunk index and corrupt the object it was
+ * trying to save. Rename is atomic on one filesystem, so a concurrent reader
+ * sees the old journal or the new one, never a mixture.
+ */
+import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { CryptoError, KEY_BYTES, unwrapArchiveKey, zeroize } from "../packages/vaultline-crypto/src/index.js";
+import { fail } from "./errors.js";
+export const SPOOL_VERSION = 1;
+const spoolDir = (dataDir) => join(dataDir, "spool");
+const journalPath = (dataDir, archiveId) => join(spoolDir(dataDir), `${archiveId}.json`);
+/**
+ * The single writer every journal byte goes through: full contents to a
+ * temporary name, then rename onto the journal path. 0600 from birth — the
+ * temp file is the journal for a moment, so it gets the journal's mode.
+ */
+async function writeJournal(path, journal) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temp, JSON.stringify(journal, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, path);
+}
+/**
+ * Structural gate before anything trusts a journal. Deliberately checks the
+ * fields a resume would act on, not every byte: a journal that passes here can
+ * still fail its unwrap or its hash-state import, and those failures carry
+ * their own, better messages.
+ */
+function parseJournal(raw, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return fail("invalid_argument", `The spool journal at ${path} is not valid JSON, so it cannot drive a resume. Shred it and start the upload over.`, { path });
+    }
+    const journal = parsed;
+    if (journal?.version !== SPOOL_VERSION) {
+        fail("config_unsupported_version", `Spool journal version ${String(parsed?.version)} is not supported by this build (expected ${SPOOL_VERSION})`, { path });
+    }
+    const shaped = typeof journal.archiveId === "string" && journal.archiveId.length > 0
+        && typeof journal.suite === "string"
+        && typeof journal.source?.path === "string"
+        && Array.isArray(journal.wrappedKeys) && journal.wrappedKeys.length > 0
+        && typeof journal.noncePrefixB64 === "string"
+        && Number.isInteger(journal.nextChunkIndex) && journal.nextChunkIndex >= 0
+        && typeof journal.consumedPrefixSha256 === "string"
+        && Array.isArray(journal.chunkHeaders)
+        && typeof journal.hashState?.plaintext === "string"
+        && typeof journal.hashState?.stored === "string";
+    if (!shaped)
+        fail("invalid_argument", `The spool journal at ${path} is missing fields a resume depends on; refusing to act on it. Shred it and start the upload over.`, { path });
+    return journal;
+}
+export async function createSpool(dataDir, draft, options = {}) {
+    const stamp = new Date(options.now ?? Date.now()).toISOString();
+    const journal = { ...draft, version: SPOOL_VERSION, createdAt: stamp, updatedAt: stamp };
+    await mkdir(spoolDir(dataDir), { recursive: true });
+    await writeJournal(journalPath(dataDir, journal.archiveId), journal);
+    return journal;
+}
+export async function loadSpool(dataDir, archiveId) {
+    const path = journalPath(dataDir, archiveId);
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return fail("archive_not_found", `No in-flight upload journal for archive ${archiveId}. The upload either finished or was never started on this machine.`, { archiveId });
+    }
+    return parseJournal(raw, path);
+}
+/**
+ * Atomic read-modify-write. The merge is shallow on purpose: a patch replaces
+ * whole fields (`chunkHeaders`, `hashState`, `providerState`) rather than
+ * deep-merging into them, so what lands on disk is exactly what the caller
+ * computed and not a splice of two generations.
+ */
+/**
+ * One writer at a time per journal, in-process. Two writers race a streamed
+ * seal by design — the sink journals each chunk header at emission while the
+ * provider's onState journals confirmation — and unserialised read-modify-write
+ * let the slower reader clobber the faster writer's fields (a header written a
+ * millisecond earlier vanished under an onState that had read before it). The
+ * chain makes every update read what the previous update wrote.
+ */
+const updateChains = new Map();
+export async function updateSpool(dataDir, archiveId, patch, options = {}) {
+    const key = `${resolve(dataDir)}::${archiveId}`;
+    const run = async () => {
+        const current = await loadSpool(dataDir, archiveId);
+        const next = {
+            ...current, ...patch,
+            // Pinned regardless of what a loosely typed caller put in the patch:
+            // identity and origin never move, and updatedAt is this write's own stamp.
+            version: SPOOL_VERSION, archiveId: current.archiveId, createdAt: current.createdAt,
+            updatedAt: new Date(options.now ?? Date.now()).toISOString()
+        };
+        await writeJournal(journalPath(dataDir, archiveId), next);
+        return next;
+    };
+    const chained = (updateChains.get(key) ?? Promise.resolve()).then(run, run);
+    // The chain must survive a failed link (a shredded journal mid-sequence),
+    // or every later update would re-throw the same stale error.
+    updateChains.set(key, chained.catch(() => undefined));
+    return chained;
+}
+/**
+ * The newest journal for a source file, or null. Newest by `updatedAt` because
+ * that tracks actual upload progress; `createdAt` breaks ties. Unreadable or
+ * foreign files in the spool directory are skipped, not fatal — one stray temp
+ * or hand-dropped file must not block resuming a good upload.
+ */
+export async function findSpoolForSource(dataDir, sourcePath) {
+    const absolute = resolve(sourcePath);
+    let files;
+    try {
+        files = await readdir(spoolDir(dataDir));
+    }
+    catch {
+        return null;
+    }
+    let newest = null;
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        let journal;
+        try {
+            journal = parseJournal(await readFile(join(spoolDir(dataDir), file), "utf8"), join(spoolDir(dataDir), file));
+        }
+        catch {
+            continue;
+        }
+        if (resolve(journal.source.path) !== absolute)
+            continue;
+        // ISO-8601 UTC timestamps order lexicographically, same as listArchives.
+        if (!newest || journal.updatedAt > newest.updatedAt || (journal.updatedAt === newest.updatedAt && journal.createdAt > newest.createdAt))
+            newest = journal;
+    }
+    return newest;
+}
+/**
+ * Removes a journal for good. No overwrite pass: the file holds only wrapped
+ * keys and provider session state, both worthless without a vault secret. The
+ * unlink itself must be sure, though — `force` only forgives a journal that is
+ * already gone (shred is a cleanup path and runs twice sometimes); any other
+ * failure surfaces, because a journal that lingers would later present a dead
+ * provider session as resumable.
+ */
+/**
+ * One resume per journal, across processes. Two processes continuing the same
+ * journal would drive the same multipart/session — racing part numbers, and
+ * (worse) widening the nonce-reuse window if the source changes between them.
+ * The lock is an O_EXCL sentinel beside the journal: cheap, crash-tolerant
+ * (a holder that died leaves a stale file, taken over after 30 minutes), and
+ * refused with a sentence rather than queued.
+ */
+export async function acquireSpoolLock(dataDir, archiveId, options = {}) {
+    const dir = join(dataDir, "spool");
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, `${archiveId}.lock`);
+    const now = options.now ?? Date.now();
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const handle = await open(path, "wx", 0o600);
+            await handle.writeFile(JSON.stringify({ pid: process.pid, at: new Date(now).toISOString() }));
+            await handle.close();
+            return { release: async () => { await rm(path, { force: true }); } };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const holder = await stat(path).catch(() => null);
+            if (holder && now - holder.mtimeMs > 30 * 60_000) {
+                // The holder died half an hour ago; its upload is not moving. Take over.
+                await rm(path, { force: true });
+                continue;
+            }
+            fail("invalid_argument", "Another process is already working on this upload. Let it finish, or if it crashed, try again in half an hour (its claim expires on its own).", { archiveId });
+        }
+    }
+    fail("internal", "Could not claim the upload lock.", { archiveId });
+}
+export async function shredSpool(dataDir, archiveId) {
+    await rm(journalPath(dataDir, archiveId), { force: true });
+}
+/** Opens the journal's wrapped archive key. The caller owns the returned bytes and zeroizes them. */
+export function unwrapSpoolKey(journal, unlock) {
+    const archiveKey = unwrapArchiveKey(journal.wrappedKeys, journal.suite, journal.archiveId, unlock);
+    if (archiveKey.length !== KEY_BYTES) {
+        zeroize(archiveKey);
+        throw new CryptoError("key_malformed", "Unwrapped archive key has the wrong length");
+    }
+    return archiveKey;
+}

package/dist/src/start-tui.d.ts

@@ -0,0 +1,17 @@
+import { type StartChoice } from "./start.js";
+/**
+ * Interactive onboarding.
+ *
+ * Arrow keys and enter, the way people already expect a CLI to behave. It
+ * degrades on purpose: without a TTY there is nothing to arrow around, so the
+ * caller falls back to flags rather than hanging waiting for a keypress that
+ * cannot arrive.
+ */
+export declare const interactive: (stream?: NodeJS.ReadStream) => boolean;
+/** A one-of-N picker. Returns the chosen index. */
+export declare function select(title: string, items: {
+    label: string;
+    hint?: string;
+}[], out?: NodeJS.WriteStream, input?: NodeJS.ReadStream): Promise<number>;
+/** Walks the whole first-run choice and returns what `start` needs. */
+export declare function onboard(): Promise<StartChoice>;

package/dist/src/start-tui.js

@@ -0,0 +1,113 @@
+import { createInterface } from "node:readline/promises";
+import { emitKeypressEvents } from "node:readline";
+import { modeOptions } from "./start.js";
+import { bold, dim, blue, green } from "./ui.js";
+/**
+ * Interactive onboarding.
+ *
+ * Arrow keys and enter, the way people already expect a CLI to behave. It
+ * degrades on purpose: without a TTY there is nothing to arrow around, so the
+ * caller falls back to flags rather than hanging waiting for a keypress that
+ * cannot arrive.
+ */
+export const interactive = (stream = process.stdin) => Boolean(stream.isTTY);
+/** A one-of-N picker. Returns the chosen index. */
+export async function select(title, items, out = process.stdout, input = process.stdin) {
+    let index = 0;
+    const height = items.length + 2;
+    const draw = (first) => {
+        if (!first)
+            out.write(`\x1b[${height}A`);
+        out.write(`\r\x1b[J${bold(title)}\n\n`);
+        items.forEach((item, position) => {
+            const active = position === index;
+            const marker = active ? blue("❯") : " ";
+            const label = active ? bold(item.label) : item.label;
+            out.write(`${marker} ${label}${item.hint ? `  ${dim(item.hint)}` : ""}\n`);
+        });
+    };
+    emitKeypressEvents(input);
+    const wasRaw = input.isRaw === true;
+    if (input.isTTY)
+        input.setRawMode(true);
+    input.resume();
+    draw(true);
+    try {
+        return await new Promise((resolve, reject) => {
+            const onKey = (_, key) => {
+                if (key?.ctrl && key.name === "c") {
+                    cleanup();
+                    reject(new Error("cancelled"));
+                    return;
+                }
+                if (key?.name === "up" || key?.name === "k") {
+                    index = (index - 1 + items.length) % items.length;
+                    draw(false);
+                    return;
+                }
+                if (key?.name === "down" || key?.name === "j") {
+                    index = (index + 1) % items.length;
+                    draw(false);
+                    return;
+                }
+                if (key?.name === "return" || key?.name === "enter") {
+                    cleanup();
+                    resolve(index);
+                }
+            };
+            const cleanup = () => { input.off("keypress", onKey); if (input.isTTY)
+                input.setRawMode(wasRaw); input.pause(); out.write("\n"); };
+            input.on("keypress", onKey);
+        });
+    }
+    catch (error) {
+        if (input.isTTY)
+            input.setRawMode(wasRaw);
+        throw error;
+    }
+}
+async function ask(question, fallback = "") {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${question}${fallback ? dim(` (${fallback})`) : ""}: `)).trim();
+        return answer || fallback;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Walks the whole first-run choice and returns what `start` needs. */
+export async function onboard() {
+    const options = modeOptions();
+    const chosen = await select("How should your archives be stored?", options.map((option) => ({
+        label: option.title,
+        hint: option.mode === "free" ? "you own the bucket" : "we own the bucket, from $6/mo for 100 GB"
+    })));
+    const mode = options[chosen].mode;
+    process.stdout.write(`\n${green("✓")} ${bold(options[chosen].title)}\n`);
+    for (const line of options[chosen].weProvide)
+        process.stdout.write(`  ${dim("·")} ${dim(line)}\n`);
+    process.stdout.write("\n");
+    if (mode === "paid") {
+        return {
+            mode: "paid",
+            email: await ask("Email"),
+            label: await ask("Name for this machine", "this machine"),
+            password: ""
+        };
+    }
+    const providerIndex = await select("Where is your bucket?", [
+        { label: "Google Cloud Storage", hint: "gcs" },
+        { label: "Amazon S3", hint: "s3" },
+        { label: "Cloudflare R2", hint: "r2, no egress fees" }
+    ]);
+    const provider = ["gcs", "s3", "r2"][providerIndex];
+    return {
+        mode: "free", provider,
+        bucket: await ask("Bucket name"),
+        prefix: await ask("Prefix", "vaultline"),
+        project: provider === "gcs" ? await ask("Google Cloud project") : undefined,
+        region: provider === "s3" ? await ask("Region", "us-east-1") : undefined,
+        accountId: provider === "r2" ? await ask("Cloudflare account id") : undefined
+    };
+}

package/dist/src/start.d.ts

@@ -0,0 +1,75 @@
+import { type CloudAccount } from "./cloud.js";
+import { type SetupPlan } from "./storage-setup.js";
+import type { ProviderKind } from "./control-plane.js";
+/**
+ * First run.
+ *
+ * One command decides everything a person has to know: which tier they are on,
+ * where their bytes go, and the phrase that is the only way back into their
+ * vault. Both tiers encrypt on this machine. The tier only changes who runs the
+ * bucket.
+ */
+export type Mode = "free" | "paid";
+export type FreeChoice = {
+    mode: "free";
+    provider: ProviderKind;
+    bucket: string;
+    prefix: string;
+    region?: string;
+    accountId?: string;
+    project?: string;
+};
+export type PaidChoice = {
+    mode: "paid";
+    email: string;
+    password: string;
+    label: string;
+};
+export type StartChoice = FreeChoice | PaidChoice;
+export type StartResult = {
+    mode: Mode;
+    vaultId: string;
+    /** Shown once. Never written to disk by us, never sent anywhere. */
+    phrase: string;
+    recoveryKit: string;
+    /** Free tier only: the bucket and credential steps to follow. */
+    storageSetup?: SetupPlan;
+    /** Paid tier only. */
+    account?: CloudAccount;
+    /** Paid tier only: sealed with the phrase, safe to hand to the server. */
+    escrow?: {
+        envelope: unknown;
+        ciphertext: Buffer;
+    };
+    nextSteps: string[];
+};
+/** An X25519 keypair for this machine. The private half never leaves it unsealed. */
+export declare function generateDeviceKeys(): {
+    publicKeyBase64: string;
+    privateKeyBase64: string;
+};
+/**
+ * Free tier: the vault is local and the bucket is theirs.
+ *
+ * We do not ask for cloud credentials and we cannot see their data. The reward
+ * for that is that they do the bucket setup — so we generate the exact console
+ * links, commands, and least-privilege policy rather than leaving them to guess.
+ */
+export declare function startFree(dataDir: string, choice: FreeChoice): Promise<StartResult>;
+/**
+ * Paid tier: they configure nothing.
+ *
+ * We hold the bucket and the bill; they hold the only key that opens the data.
+ * The escrow blob makes a lost machine survivable without making us able to
+ * read anything — it is sealed with the phrase before it leaves here.
+ */
+export declare function startPaid(dataDir: string, choice: PaidChoice): Promise<StartResult>;
+export declare function start(dataDir: string, choice: StartChoice): Promise<StartResult>;
+/** What the first-run UI offers, before anything is created. */
+export declare function modeOptions(): {
+    mode: Mode;
+    title: string;
+    summary: string;
+    youProvide: string[];
+    weProvide: string[];
+}[];