sealkeep 0.5.0

package/dist/src/offload.js

@@ -0,0 +1,331 @@
+import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fail } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { isV2 } from "./types.js";
+import { listArchives, readConfig, writeRecord } from "./vault.js";
+import { createActiveLease, uploadClientFromStore } from "./providers/index.js";
+import { sha256 } from "./crypto.js";
+/** Providers this build can fetch back from. GCS uploads but has no download client. */
+// Every provider with a proven read-back path. "vaultline" reads back through
+// the account (pullCiphertext, hash-checked); "gcs" through a signed GET on
+// the provider client. Both were live-proven before earning a place here —
+// this set is the safety gate that keeps "offload" from meaning "lose".
+// gdrive joined when its client grew download() — the live Drive drill hit
+// this stale gate first: uploads landed, the local copy could never leave.
+const FETCHABLE = new Set(["s3", "r2", "b2", "gcs", "gdrive", "vaultline"]);
+export async function offloadable(dataDir) {
+    const archives = await listArchives(dataDir);
+    const candidates = [];
+    const blocked = [];
+    for (const record of archives) {
+        if (!isV2(record)) {
+            blocked.push({ id: record.id, reason: "archive uses format v1; run `sealkeep migrate` first" });
+            continue;
+        }
+        if (record.offloaded)
+            continue;
+        const remote = record.remote;
+        if (!remote?.verifiedAt) {
+            blocked.push({ id: record.id, reason: "no verified remote copy, so the local one is the only copy" });
+            continue;
+        }
+        if (!FETCHABLE.has(remote.provider)) {
+            blocked.push({ id: record.id, reason: `${remote.provider} can be uploaded to but not read back by this build, so the local copy has to stay` });
+            continue;
+        }
+        const local = await stat(record.objectPath).catch(() => null);
+        if (!local) {
+            blocked.push({ id: record.id, reason: "no local archive file to remove" });
+            continue;
+        }
+        // The remote is only a copy if the sizes agree. For a provider that stores
+        // the raw ciphertext that means equality; a managed object carries the
+        // self-opening envelope frame around the same ciphertext, so it is larger
+        // by exactly that frame — equality there is structurally impossible and
+        // demanding it silently blocked every managed offload. The frame only
+        // adds, so smaller-than-local is still the same corruption signal, and
+        // the true proof either way is the fetch-and-hash below.
+        const sameSize = remote.provider === "vaultline" ? remote.bytes >= local.size : remote.bytes === local.size;
+        if (!sameSize) {
+            blocked.push({ id: record.id, reason: `the remote object is ${remote.bytes} bytes and the local one is ${local.size}; they are not the same archive` });
+            continue;
+        }
+        candidates.push({
+            id: record.id, agent: record.source.agent, path: record.source.path,
+            localBytes: local.size, provider: remote.provider, bucket: remote.bucket, objectKey: remote.objectKey
+        });
+    }
+    return { candidates, blocked, freeableBytes: candidates.reduce((total, item) => total + item.localBytes, 0) };
+}
+/**
+ * Removes local archives that a bucket has a verified copy of.
+ *
+ * A dry run unless confirmed. The candidate list is recomputed here rather than
+ * accepted from a caller, so a page held open since yesterday cannot ask for
+ * the deletion of something that has since become the only copy.
+ */
+export async function offloadArchives(dataDir, options = {}) {
+    const all = await offloadable(dataDir);
+    // `only` narrows the sweep — the upload run offloads each archive as its
+    // verify lands rather than re-walking the whole vault per item.
+    const candidates = options.only ? all.candidates.filter((candidate) => options.only.has(candidate.id)) : all.candidates;
+    const blocked = all.blocked;
+    const freeableBytes = candidates.reduce((total, item) => total + item.localBytes, 0);
+    if (!options.confirm)
+        return { mode: "preview", wouldOffload: candidates, blocked, freedBytes: freeableBytes };
+    const archives = new Map((await listArchives(dataDir)).map((record) => [record.id, record]));
+    const offloaded = [];
+    const failed = [];
+    const config = await readConfig(dataDir);
+    for (const candidate of candidates) {
+        const record = archives.get(candidate.id);
+        if (!record || !isV2(record))
+            continue;
+        try {
+            // Prove the bytes are really there, now, before removing the local ones.
+            // The verifiedAt stamp says they were there once; this asks again, because
+            // between then and now is exactly where a bucket lifecycle rule lives.
+            // The one honest exception: an archive whose verify landed seconds ago in
+            // the same run — between then and now is milliseconds, and re-downloading
+            // a gigabyte to re-prove it would double the egress of every push.
+            if (!options.freshlyVerified?.has(candidate.id)) {
+                const fetched = await fetchCiphertext(dataDir, record, options.client);
+                if (sha256(fetched) !== record.cipher.ciphertextSha256) {
+                    failed.push({ id: candidate.id, error: "what the bucket returned is not this archive; local copy kept" });
+                    continue;
+                }
+            }
+            await rm(record.objectPath, { force: true });
+            const next = {
+                ...record,
+                offloaded: { at: new Date().toISOString(), provider: candidate.provider, bucket: candidate.bucket, objectKey: candidate.objectKey }
+            };
+            await writeRecord(config.storage.root, next);
+            await recordAudit(dataDir, "archive.offload", "allowed", { archiveId: candidate.id, bytes: candidate.localBytes, bucket: candidate.bucket });
+            offloaded.push(candidate);
+        }
+        catch (error) {
+            await recordAudit(dataDir, "archive.offload", "denied", { archiveId: candidate.id });
+            failed.push({ id: candidate.id, error: error instanceof Error ? error.message : "could not offload" });
+        }
+    }
+    return { mode: "apply", offloaded, failed, blocked, freedBytes: offloaded.reduce((total, item) => total + item.localBytes, 0) };
+}
+/**
+ * Downloads an archive's ciphertext from the bucket it was offloaded to.
+ *
+ * VAULTLINE_ENABLE_SIGNER gates *uploading*, and it is off unless the installed
+ * service turns it on. Reading back an archive in order to restore it is not
+ * uploading, and refusing it on that flag would mean an offloaded archive could
+ * not be recovered by the person who owns it — which would turn a space-saving
+ * feature into data loss. The flag is set for this call only.
+ */
+async function fetchCiphertext(dataDir, record, client) {
+    const config = await readConfig(dataDir);
+    const remote = record.remote ?? record.offloaded;
+    if (!remote)
+        fail("archive_not_found", `Archive ${record.id} has no remote copy to fetch`, { archiveId: record.id });
+    // A managed copy reads back through the account, not a provider credential:
+    // pullCiphertext hash-checks what it downloads before returning it. Branch
+    // on the record's own provider — a vault can hold managed history alongside
+    // a later own-bucket configuration, and each copy fetches its own way.
+    if (remote.provider === "vaultline" && !client && record.remote?.layout?.kind !== "chunks") {
+        const { pullCiphertext, unframeObject } = await import("./cloud.js");
+        const { ciphertext: blob } = await pullCiphertext(dataDir, record.id);
+        // A managed object is envelope-framed — the self-carrying wrapper push
+        // added so a bare object can be opened anywhere. What the local record
+        // hashes is the ciphertext INSIDE the frame, so that is what this must
+        // return; handing back the framed bytes made every integrity check
+        // compare an apple to the crate it shipped in. A plain-mode object has
+        // no frame and IS the stored bytes.
+        const { envelope, ciphertext } = unframeObject(blob);
+        return envelope ? ciphertext : blob;
+    }
+    // Chunk-folder remotes fetch object by object, each hash-checked against
+    // the envelope's own chunk headers — the layout was made for exactly this.
+    // A managed folder reads back through the account's download leases; an own
+    // bucket reads through the provider's object verbs.
+    if (record.remote?.layout?.kind === "chunks") {
+        const { fetchChunkFolder } = await import("./chunk-store.js");
+        let folderClient;
+        if (client)
+            folderClient = client;
+        else if (record.remote.provider === "vaultline") {
+            folderClient = (await import("./managed-chunks.js")).managedChunkClient(dataDir);
+        }
+        else {
+            const target = config.remoteStorage ?? fail("storage_not_configured", "This vault has no storage configured, so an offloaded archive cannot be fetched back");
+            folderClient = await uploadClientFromStore(dataDir, config.vaultId, target, {}, undefined);
+        }
+        if (typeof folderClient.getObject !== "function")
+            fail("provider_unsupported", `${record.remote.provider} cannot fetch chunk folders with this build`);
+        return fetchChunkFolder(folderClient, record.remote, record.envelope);
+    }
+    // The record routes its own read: provider and bucket come from the copy
+    // itself, the prefix from its object key, and a configured target (matched
+    // by targetId, then by provider+bucket) fills in the rest. config.remoteStorage
+    // is only the last resort — a multi-target vault has none.
+    const target = await (async () => {
+        if (config.remoteStorage && config.remoteStorage.provider === remote.provider && config.remoteStorage.bucket === remote.bucket)
+            return config.remoteStorage;
+        try {
+            const { resolveTargets } = await import("./storage-targets.js");
+            const targets = await resolveTargets(dataDir);
+            const stampedId = remote.targetId;
+            const match = (stampedId ? targets.find((candidate) => candidate.id === stampedId) : undefined)
+                ?? targets.find((candidate) => candidate.provider === remote.provider && candidate.bucket === remote.bucket);
+            if (match) {
+                const derivedPrefix = remote.objectKey.split("/").slice(0, -1).join("/");
+                return { provider: match.provider, bucket: match.bucket ?? remote.bucket, prefix: match.prefix ?? (derivedPrefix || "vaultline"), region: match.region };
+            }
+        }
+        catch { /* fall through */ }
+        if (config.remoteStorage)
+            return config.remoteStorage;
+        return fail("storage_not_configured", "This vault has no storage configured, so an offloaded archive cannot be fetched back");
+    })();
+    if (target.provider === "vaultline")
+        fail("storage_not_configured", "This managed copy should have taken the managed read path");
+    const resolved = client ?? await uploadClientFromStore(dataDir, config.vaultId, target, {}, undefined);
+    const lease = createActiveLease(target, {
+        archiveId: record.id, ciphertextSha256: record.cipher.ciphertextSha256, bytes: record.cipher.storedBytes
+    }, { ...process.env, VAULTLINE_ENABLE_SIGNER: "1" });
+    const readable = resolved;
+    if (typeof readable.download !== "function") {
+        fail("provider_unsupported", `${target.provider} cannot be read back by this build, so this archive cannot be fetched`);
+    }
+    return readable.download(lease);
+}
+/**
+ * One managed record checked against the account's rows. A single-object copy
+ * is one row at the recorded size; a chunk-folder copy is its whole family —
+ * every chunk row present, the envelope sidecar present, and the chunk bytes
+ * summing to the verified total. The proof standard does not soften because
+ * the object count went up: any missing member is "do not trash the original".
+ */
+async function managedCopyCheck(dataDir, record, rows, checkedAt) {
+    const remote = record.remote;
+    if (remote.layout?.kind === "chunks") {
+        const { managedChunkRefs } = await import("./managed-chunks.js");
+        const refs = managedChunkRefs(record.id, remote.layout.chunkCount);
+        const missing = refs.chunks.filter((ref) => !rows.has(ref)).length + (rows.has(refs.envelope) ? 0 : 1);
+        if (missing > 0) {
+            await recordAudit(dataDir, "remote.check", "denied", { archiveId: record.id, reason: "absent", missing });
+            return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: `Your managed storage is missing ${missing} of this archive's ${refs.chunks.length + 1} objects. Do not trash the original — this disk may hold the only complete copy.` };
+        }
+        const bytes = refs.chunks.reduce((sum, ref) => sum + (rows.get(ref) ?? 0), 0);
+        if (bytes !== remote.bytes) {
+            await recordAudit(dataDir, "remote.check", "denied", { archiveId: record.id, reason: "size", stored: bytes });
+            return { ok: false, provider: remote.provider, bytes, checkedAt, detail: `Your storage reports ${bytes} chunk bytes; ${remote.bytes} were verified. Do not trash the original.` };
+        }
+        await recordAudit(dataDir, "remote.check", "allowed", { archiveId: record.id, bytes, chunks: refs.chunks.length });
+        return { ok: true, provider: remote.provider, bytes, checkedAt, detail: `Your managed storage confirmed all ${refs.chunks.length} chunks and the sidecar at the recorded size, just now.` };
+    }
+    const stored = rows.get(record.id);
+    if (stored === undefined) {
+        await recordAudit(dataDir, "remote.check", "denied", { archiveId: record.id, reason: "absent" });
+        return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: "Your managed storage no longer lists this archive. Do not trash the original — this disk may hold the only copy." };
+    }
+    if (stored !== remote.bytes) {
+        await recordAudit(dataDir, "remote.check", "denied", { archiveId: record.id, reason: "size", stored });
+        return { ok: false, provider: remote.provider, bytes: stored, checkedAt, detail: `Your storage reports ${stored} bytes; ${remote.bytes} were verified. Do not trash the original.` };
+    }
+    await recordAudit(dataDir, "remote.check", "allowed", { archiveId: record.id, bytes: stored });
+    return { ok: true, provider: remote.provider, bytes: stored, checkedAt, detail: "Your managed storage confirmed it holds this archive at the recorded size, just now." };
+}
+export async function checkRemoteCopy(dataDir, archiveId, client) {
+    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 remote = record.remote;
+    if (!remote?.verifiedAt)
+        fail("invalid_argument", "This archive has no verified cloud copy to check — upload it first.", { archiveId });
+    const checkedAt = new Date().toISOString();
+    if (remote.provider === "vaultline" && !client) {
+        const { listCloudArchives } = await import("./cloud.js");
+        const rows = new Map((await listCloudArchives(dataDir)).map((row) => [row.vault_ref, Number(row.bytes) || 0]));
+        return managedCopyCheck(dataDir, record, rows, checkedAt);
+    }
+    const config = await readConfig(dataDir);
+    const target = config.remoteStorage;
+    if (!target)
+        fail("storage_not_configured", "This vault has no storage configured, so the copy cannot be checked");
+    const resolved = client ?? await uploadClientFromStore(dataDir, config.vaultId, target, {}, undefined);
+    const lease = createActiveLease(target, {
+        archiveId: record.id, ciphertextSha256: record.cipher.ciphertextSha256, bytes: record.cipher.storedBytes
+    }, { ...process.env, VAULTLINE_ENABLE_SIGNER: "1" });
+    const probing = resolved;
+    if (typeof probing.head !== "function")
+        fail("provider_unsupported", `${target.provider} cannot be probed by this build`);
+    const head = await probing.head(lease);
+    if (!head.exists) {
+        await recordAudit(dataDir, "remote.check", "denied", { archiveId, reason: "absent" });
+        return { ok: false, provider: remote.provider, bytes: 0, checkedAt, detail: "The bucket no longer holds this object. Do not trash the original — this disk may hold the only copy." };
+    }
+    if (head.bytes !== remote.bytes) {
+        await recordAudit(dataDir, "remote.check", "denied", { archiveId, reason: "size", stored: head.bytes });
+        return { ok: false, provider: remote.provider, bytes: head.bytes, checkedAt, detail: `The bucket holds ${head.bytes} bytes; ${remote.bytes} were verified. Do not trash the original.` };
+    }
+    await recordAudit(dataDir, "remote.check", "allowed", { archiveId, bytes: head.bytes });
+    return { ok: true, provider: remote.provider, bytes: head.bytes, checkedAt, detail: "The bucket answered just now and holds this archive at the recorded size." };
+}
+/**
+ * The bulk form of `checkRemoteCopy`. Managed rows share ONE control-plane
+ * listing instead of asking per archive — checking a 53-row vault is one call
+ * plus a HEAD per own-bucket object, not 53 round trips.
+ */
+export async function checkRemoteCopyMany(dataDir, ids, client) {
+    const archives = await listArchives(dataDir);
+    const wanted = ids.map((id) => archives.find((item) => item.id === id));
+    const checkedAt = new Date().toISOString();
+    const results = [];
+    const managedIds = wanted.filter((record) => !!record && isV2(record) && record.remote?.provider === "vaultline").map((record) => record.id);
+    let managedRows = null;
+    if (managedIds.length > 0 && !client) {
+        const { listCloudArchives } = await import("./cloud.js");
+        managedRows = new Map((await listCloudArchives(dataDir)).map((row) => [row.vault_ref, Number(row.bytes) || 0]));
+    }
+    for (const id of ids) {
+        const record = archives.find((item) => item.id === id);
+        if (!record || !isV2(record) || !record.remote?.verifiedAt) {
+            results.push({ ok: false, provider: "none", bytes: 0, checkedAt, detail: "No verified cloud copy on record for this archive." });
+            continue;
+        }
+        if (record.remote.provider === "vaultline" && managedRows) {
+            results.push(await managedCopyCheck(dataDir, record, managedRows, checkedAt));
+            continue;
+        }
+        try {
+            results.push(await checkRemoteCopy(dataDir, id, client));
+        }
+        catch (error) {
+            results.push({ ok: false, provider: record.remote.provider, bytes: 0, checkedAt, detail: error instanceof Error ? error.message : "the check itself failed" });
+        }
+    }
+    return results;
+}
+/**
+ * Gives back a local path holding this archive's ciphertext, fetching it first
+ * if the local copy was offloaded.
+ *
+ * Restoring reads the object twice — once to hash it, once to decrypt it — so
+ * it needs a file, not a buffer. An offloaded archive is written to a temporary
+ * one and removed afterwards, which keeps the disk saving intact: the bytes are
+ * on this machine only for as long as the restore takes.
+ */
+export async function materialiseArchive(dataDir, record, client) {
+    if (!isV2(record) || !record.offloaded)
+        return { path: record.objectPath, release: async () => { } };
+    const ciphertext = await fetchCiphertext(dataDir, record, client);
+    if (sha256(ciphertext) !== record.cipher.ciphertextSha256) {
+        fail("ciphertext_integrity_failed", `The copy of archive ${record.id} in ${record.offloaded.bucket} is not the archive that was stored there`, { archiveId: record.id });
+    }
+    const scratch = await mkdtemp(join(tmpdir(), "vaultline-fetch-"));
+    const path = join(scratch, `${record.id}.vlarchive`);
+    await writeFile(path, ciphertext, { mode: 0o600 });
+    return { path, release: async () => { await rm(scratch, { recursive: true, force: true }); } };
+}

package/dist/src/onboarding.d.ts

@@ -0,0 +1,10 @@
+import { detectAgents } from "./adapters.js";
+export type SetupResult = {
+    initialized: boolean;
+    vaultId: string;
+    recoveryPhrase?: string;
+    detectedAgents: Awaited<ReturnType<typeof detectAgents>>;
+    files: string[];
+};
+/** Creates only Sealkeep-owned artifacts. Agent settings are never modified. */
+export declare function setupVault(dataDir: string, providedPhrase?: string): Promise<SetupResult>;

package/dist/src/onboarding.js

@@ -0,0 +1,44 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { detectAgents, hookConfig } from "./adapters.js";
+import { initialize, vaultStatus } from "./vault.js";
+async function exists(path) { try {
+    await access(path, constants.F_OK);
+    return true;
+}
+catch {
+    return false;
+} }
+async function writeJson(path, value) { await mkdir(join(path, ".."), { recursive: true }); await writeFile(path, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 }); }
+/** Creates only Sealkeep-owned artifacts. Agent settings are never modified. */
+export async function setupVault(dataDir, providedPhrase) {
+    const configPath = join(dataDir, "config.json");
+    let initialized = false;
+    let recoveryPhrase;
+    if (!(await exists(configPath))) {
+        const created = await initialize(dataDir, providedPhrase);
+        initialized = true;
+        recoveryPhrase = created.phrase;
+    }
+    const status = await vaultStatus(dataDir);
+    const detectedAgents = await detectAgents();
+    const integrations = join(dataDir, "integrations");
+    const files = [];
+    for (const agent of ["codex", "claude"]) {
+        const path = join(integrations, `${agent}-hooks.json`);
+        await writeJson(path, hookConfig(agent, "vaultline", dataDir));
+        files.push(path);
+    }
+    // Written by `sealkeep mcp install`, which knows how to register with each
+    // agent rather than leaving a fragment and hoping. This used to emit a JSON
+    // fragment here naming `sealkeep mcp` — a command that did not exist until
+    // that install path was built, so anyone who merged it got an agent that
+    // failed to start its server.
+    const { installMcpServer } = await import("./mcp-install.js");
+    const mcp = await installMcpServer(dataDir);
+    for (const entry of mcp.agents)
+        if (entry.fragmentPath)
+            files.push(entry.fragmentPath);
+    return { initialized, vaultId: status.vaultId, recoveryPhrase, detectedAgents, files };
+}

package/dist/src/packages.d.ts

@@ -0,0 +1,126 @@
+/**
+ * What a customer actually buys.
+ *
+ * A package is a number of gigabytes and nothing else. Which provider holds the
+ * bytes is our problem, not the customer's — we pick whichever of B2 or R2 is
+ * cheapest and can move between them without anyone needing to know, because
+ * the ciphertext is opaque and the envelope travels with it. A customer who
+ * wants to name their own provider, region and storage class is not buying a
+ * package at all; they point Sealkeep at their own bucket and pay their own
+ * storage bill.
+ *
+ * Prices are monthly, in US dollars, and match what the site publishes — a
+ * visitor who has already read the pricing page must not be quoted something
+ * else by the CLI.
+ *
+ * On margin, and the mistake this comment used to make: compression does *not*
+ * halve what we store per GB of quota sold. Quota is metered on ciphertext —
+ * `src/upload.ts:42` sends `bytes: ciphertext.length` and the control plane
+ * bills against exactly that — so at full fill, stored bytes equal quota 1:1.
+ * Compression buys the *customer* more sessions per GB; it buys us nothing.
+ *
+ * Costed correctly, at Backblaze B2's $0.00695/GB-mo with free egress, and
+ * noting that `GB` below is 1024^3 while B2 bills decimal GB (+7.4%):
+ * gb100 ~$0.75, gb500 ~$3.73, gb2000 ~$14.92 per month at full quota.
+ *
+ * That is comfortable on B2 and not on the alternatives: at R2 Standard's
+ * $0.015 the gb2000 tier costs ~$32 against $30 of revenue, and on the GCS
+ * that managed storage still runs on today it costs ~$43. Finishing the B2
+ * migration is what makes the top tier viable, not a cost optimisation.
+ * See STORAGE.md.
+ */
+export type PackageId = "free" | "pro_lite" | "gb100" | "gb500" | "gb2000";
+export type StoragePackage = {
+    id: PackageId;
+    name: string;
+    /** Gigabytes of managed storage. 0 means the customer runs their own bucket. */
+    gigabytes: number;
+    /** US dollars per month. 0 is free. */
+    monthly: number;
+    managed: boolean;
+    blurb: string;
+};
+export declare const PACKAGES: readonly StoragePackage[];
+export declare function findPackage(id: string): StoragePackage | undefined;
+export declare function quotaBytes(id: PackageId): number;
+/**
+ * Which package an account is on, worked out from what the control plane
+ * actually granted rather than from anything the client asked for.
+ *
+ * Quota is an entitlement: it is set server-side when a subscription is paid,
+ * never by the machine doing the uploading. This maps a granted quota back to
+ * the nearest package so the panel and the CLI can name it, and falls back to
+ * a plain byte count when a quota does not match the catalogue — a custom or
+ * grandfathered grant should be reported honestly, not rounded into a tier.
+ */
+export declare function packageForAccount(account: {
+    plan?: string;
+    quota_bytes?: number;
+}): StoragePackage | {
+    id: "custom";
+    name: string;
+    gigabytes: number;
+    monthly: null;
+    managed: true;
+    blurb: string;
+};
+/** Managed storage providers we may put a package on. Never customer-visible. */
+export type ManagedProvider = "gcs" | "b2" | "r2";
+/**
+ * Quota visibility.
+ *
+ * Today a customer who fills their package gets a bare 402 on their next
+ * upload — no warning beforehand, no dashboard number, nothing, even though
+ * `CloudAccount` has carried `quota_bytes` and `used_bytes` the whole time.
+ * This is the client-side surface for that data: where an account sits
+ * against its quota, and the plain-language line that goes with it, shared by
+ * `cloud status`, `status`, `doctor`, and the rewritten 402 so all four agree
+ * on the same numbers and the same next step.
+ *
+ * This is groundwork only. It warns and it points at `sealkeep plans`; it
+ * does not charge anyone or decide how overage should work, because that
+ * product decision has not been made yet.
+ */
+export type QuotaLevel = "ok" | "warn" | "critical" | "over";
+export type QuotaState = {
+    usedBytes: number;
+    quotaBytes: number;
+    /** Floored, and not clamped to 100 — an account genuinely over quota reads
+     *  as more than 100%, not as a suspiciously round 100. */
+    percent: number;
+    remainingBytes: number;
+    level: QuotaLevel;
+};
+/**
+ * Where an account sits against its managed-storage quota.
+ *
+ * The displayed percentage is floored, not rounded, and the level is compared
+ * against the same floored figure, so the two can never disagree — 79.6% reads
+ * as "79%" and "ok", never a "80%" that is not flagged as a warning. A quota
+ * of zero or less means there is no managed entitlement to speak of — a pure
+ * bring-your-own-bucket account — so it reads as "ok" rather than a division
+ * by zero.
+ */
+export declare function quotaState(usedBytes: number, quotaBytes: number): QuotaState;
+/**
+ * One sentence, always carrying the real numbers.
+ *
+ * A customer who hits this has no dashboard to cross-check it against — this
+ * line, wherever it is shown, is the only accounting they get. `warn` and
+ * `critical` both name what to do; `over` says plainly that uploads will fail,
+ * because at 100% they will.
+ */
+export declare function quotaMessage(state: QuotaState): string;
+/**
+ * Rewrites a bare quota rejection into something a customer can act on.
+ *
+ * `call()` in cloud.ts maps a 402 straight to a VaultlineError coded
+ * "forbidden" whose message is whatever the control plane said — historically
+ * just "Quota exceeded", with no numbers and no next step. This asks the same
+ * question `cloud status` would have answered in advance: where the account
+ * actually stands, and what to do about it.
+ */
+export declare function quotaExceededMessage(account: {
+    used_bytes: number;
+    quota_bytes: number;
+}): string;

package/dist/src/packages.js

@@ -0,0 +1,114 @@
+import { bytes } from "./ui.js";
+const GB = 1024 ** 3;
+export const PACKAGES = [
+    {
+        id: "free", name: "Your own bucket", gigabytes: 0, monthly: 0, managed: false,
+        blurb: "Point Sealkeep at storage you already pay for. Your provider, your region, your retention. We never hold the bytes and never see a key."
+    },
+    {
+        id: "pro_lite", name: "Pro Lite", gigabytes: 0, monthly: 2, managed: false,
+        blurb: "Your storage, our safety net: a sealed copy of your key in escrow, and every machine signed in. We still hold no bytes."
+    },
+    {
+        id: "gb100", name: "100 GB", gigabytes: 100, monthly: 6, managed: true,
+        blurb: "Enough for years of transcripts on one machine. Nothing to create, nothing to configure."
+    },
+    {
+        id: "gb500", name: "500 GB", gigabytes: 500, monthly: 12, managed: true,
+        blurb: "A whole team's history, or one machine that never deletes anything."
+    },
+    {
+        id: "gb2000", name: "2 TB", gigabytes: 2000, monthly: 30, managed: true,
+        blurb: "Every agent on every machine, kept indefinitely."
+    }
+];
+export function findPackage(id) {
+    return PACKAGES.find((item) => item.id === id);
+}
+export function quotaBytes(id) {
+    return (findPackage(id)?.gigabytes ?? 0) * GB;
+}
+/**
+ * Which package an account is on, worked out from what the control plane
+ * actually granted rather than from anything the client asked for.
+ *
+ * Quota is an entitlement: it is set server-side when a subscription is paid,
+ * never by the machine doing the uploading. This maps a granted quota back to
+ * the nearest package so the panel and the CLI can name it, and falls back to
+ * a plain byte count when a quota does not match the catalogue — a custom or
+ * grandfathered grant should be reported honestly, not rounded into a tier.
+ */
+export function packageForAccount(account) {
+    if (account.plan === "pro_lite")
+        return findPackage("pro_lite") ?? PACKAGES[0];
+    if (account.plan !== "pro")
+        return PACKAGES[0];
+    const gigabytes = Math.round((account.quota_bytes ?? 0) / GB);
+    const exact = PACKAGES.find((item) => item.managed && item.gigabytes === gigabytes);
+    if (exact)
+        return exact;
+    return {
+        id: "custom", name: `${gigabytes} GB`, gigabytes, monthly: null, managed: true,
+        blurb: "A custom allocation, not one of the standard packages."
+    };
+}
+const WARN_AT = 0.8;
+const CRITICAL_AT = 0.9;
+/**
+ * Where an account sits against its managed-storage quota.
+ *
+ * The displayed percentage is floored, not rounded, and the level is compared
+ * against the same floored figure, so the two can never disagree — 79.6% reads
+ * as "79%" and "ok", never a "80%" that is not flagged as a warning. A quota
+ * of zero or less means there is no managed entitlement to speak of — a pure
+ * bring-your-own-bucket account — so it reads as "ok" rather than a division
+ * by zero.
+ */
+export function quotaState(usedBytes, quotaBytes) {
+    const used = Math.max(0, usedBytes || 0);
+    const quota = Math.max(0, quotaBytes || 0);
+    if (quota === 0)
+        return { usedBytes: used, quotaBytes: 0, percent: 0, remainingBytes: 0, level: "ok" };
+    const percent = Math.floor((used / quota) * 100);
+    const level = percent >= 100 ? "over" : percent >= CRITICAL_AT * 100 ? "critical" : percent >= WARN_AT * 100 ? "warn" : "ok";
+    return { usedBytes: used, quotaBytes: quota, percent, remainingBytes: Math.max(0, quota - used), level };
+}
+/**
+ * One sentence, always carrying the real numbers.
+ *
+ * A customer who hits this has no dashboard to cross-check it against — this
+ * line, wherever it is shown, is the only accounting they get. `warn` and
+ * `critical` both name what to do; `over` says plainly that uploads will fail,
+ * because at 100% they will.
+ */
+export function quotaMessage(state) {
+    const used = bytes(state.usedBytes);
+    const quota = bytes(state.quotaBytes);
+    const left = bytes(state.remainingBytes);
+    switch (state.level) {
+        // No command in these. This string reaches the dashboard's Health tab
+        // through doctor, and the one place a paying customer will definitely see
+        // it is the moment their uploads stop — telling them to open a terminal to
+        // see prices, right then, is the wrong answer. The CLI adds its own hint.
+        case "over":
+            return `${used} of ${quota} used (${state.percent}%). New archives are being held on this machine until there is room — free some space, or move to a bigger package.`;
+        case "critical":
+            return `${used} of ${quota} used (${state.percent}%), ${left} left before uploads pause.`;
+        case "warn":
+            return `${used} of ${quota} used (${state.percent}%), ${left} left.`;
+        default:
+            return `${used} of ${quota} used (${state.percent}%), ${left} left.`;
+    }
+}
+/**
+ * Rewrites a bare quota rejection into something a customer can act on.
+ *
+ * `call()` in cloud.ts maps a 402 straight to a VaultlineError coded
+ * "forbidden" whose message is whatever the control plane said — historically
+ * just "Quota exceeded", with no numbers and no next step. This asks the same
+ * question `cloud status` would have answered in advance: where the account
+ * actually stands, and what to do about it.
+ */
+export function quotaExceededMessage(account) {
+    return `Quota exceeded: ${quotaMessage(quotaState(account.used_bytes, account.quota_bytes))}`;
+}

package/dist/src/passkey.d.ts

@@ -0,0 +1,26 @@
+export declare const PRF_SECRET_BYTES = 32;
+/** A fresh per-vault salt, evaluated by the authenticator to produce the secret. */
+export declare function generatePrfSalt(): string;
+/**
+ * The X25519 identity that a given passkey secret always produces.
+ *
+ * Deterministic on purpose: enrolment registers the public half, and every
+ * later unlock re-derives the private half from the same finger. If this were
+ * random, a passkey could enrol but never open anything.
+ */
+export declare function keysFromPrfSecret(secret: Buffer): {
+    publicKeyBase64: string;
+    privateKeyRaw: Buffer;
+};
+/** What a vault remembers about an enrolled passkey. Never the secret, never the key. */
+export type PasskeyRecord = {
+    /** The WebAuthn credential id, so a later unlock asks for the right passkey. */
+    credentialId: string;
+    /** The salt the authenticator evaluates. Public by design: it is useless alone. */
+    prfSalt: string;
+    label: string;
+    addedAt: string;
+    /** The recipient this passkey opens, so the two can be removed together. */
+    recipientId: string;
+};
+export declare function isPasskeyRecord(value: unknown): value is PasskeyRecord;