sealkeep 0.5.0

package/dist/src/vault.js

@@ -0,0 +1,812 @@
+import { mkdir, readFile, writeFile, rename, access, rm, stat } from "node:fs/promises";
+import { constants, createReadStream, createWriteStream, existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { createGzip, createGunzip, gunzipSync } from "node:zlib";
+import { pipeline } from "node:stream/promises";
+import { decryptLegacyArchive, equalHex, isLegacyPhraseCheck, phraseCheck, sha256, upgradeLegacyPhraseCheck } from "./crypto.js";
+import { canonicalPhrase, generateRecoveryPhrase } from "./mnemonic.js";
+import { decryptArchive as openEnvelope, hashFilePrefixes, hashFileRange, keyRecipientId, openArchiveToFile, sealArchiveToFile, unwrapArchiveKey, x25519PublicKeyFromRaw, zeroize } from "../packages/vaultline-crypto/src/index.js";
+import { fail, VaultlineError } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { isV2 } from "./types.js";
+/** Bumped when the adapter's preservation behaviour changes, recorded in every envelope. */
+/**
+ * Writes one archive record atomically.
+ *
+ * Written to a temporary file beside the target and renamed into place, so a
+ * crash never leaves a half-written record that would strand an archive. This
+ * lived as three byte-identical private copies in upload, migrate and
+ * retention; a fourth was about to be added for the managed push path.
+ */
+export async function writeRecord(root, record) {
+    const path = join(root, `${record.id}.json`);
+    const temp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temp, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, path);
+}
+export const ADAPTER_VERSION = "1";
+export const CONFIG_VERSION = 1;
+/**
+ * ~/.sealkeep for new vaults; an existing ~/.Sealkeep keeps working forever —
+ * the rebrand must never strand a vault that predates it.
+ */
+export const defaultDataDir = () => {
+    const home = process.env.HOME ?? ".";
+    const legacy = join(home, ".vaultline");
+    const current = join(home, ".sealkeep");
+    if (!existsSync(current) && existsSync(legacy))
+        return legacy;
+    return current;
+};
+const configPath = (dataDir) => join(dataDir, "config.json");
+const archiveDir = (dataDir) => join(dataDir, "archives");
+async function exists(path) { try {
+    await access(path, constants.F_OK);
+    return true;
+}
+catch {
+    return false;
+} }
+async function writeJson(path, value) { await mkdir(dirname(path), { recursive: true }); await writeFile(path, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 }); }
+/**
+ * Reads and version-gates the vault config. A config written by a newer build is
+ * refused rather than silently reinterpreted; migrations attach here when v2 lands.
+ */
+export async function readConfig(dataDir) {
+    let raw;
+    try {
+        raw = await readFile(configPath(dataDir), "utf8");
+    }
+    catch {
+        return fail("vault_not_initialized", `No vault at ${dataDir}. Run: sealkeep setup --data-dir ${dataDir}`, { dataDir });
+    }
+    const config = JSON.parse(raw);
+    if (config.version !== CONFIG_VERSION)
+        fail("config_unsupported_version", `Vault config version ${String(config.version)} is not supported by this build (expected ${CONFIG_VERSION})`, { found: config.version, expected: CONFIG_VERSION });
+    // Defect #49: builds before this one stored `recovery.phraseCheck` as a
+    // bare, unsalted SHA-256 -- a cheap offline oracle. upgradeLegacyPhraseCheck
+    // re-derives the cost-matched value from that stored digest alone, with no
+    // phrase needed, so every vault created before the fix is repaired the
+    // first time anything reads its config -- nobody has to run a migration or
+    // even unlock the vault first for this to happen.
+    if (isLegacyPhraseCheck(config.recovery.phraseCheck)) {
+        config.recovery = { ...config.recovery, phraseCheck: upgradeLegacyPhraseCheck(config.recovery.phraseCheck) };
+        // Best effort: an unwritable dataDir still gets the upgraded value for
+        // this call (below), and simply repeats the upgrade on its next read.
+        await writeJson(configPath(dataDir), config).catch(() => { });
+    }
+    return config;
+}
+export async function vaultStatus(dataDir) {
+    const config = await readConfig(dataDir);
+    const archives = await listArchives(dataDir);
+    // Resolved to "sealed" rather than passed through raw, so no consumer ever
+    // has to know that absence and sealed are the same thing.
+    return { vaultId: config.vaultId, provider: config.storage.provider, storageMode: config.storageMode ?? "sealed", remoteStorage: config.remoteStorage, archiveCount: archives.length, archivedBytes: archives.reduce((total, archive) => total + archive.source.bytes, 0) };
+}
+export async function configureRemoteStorage(dataDir, remoteStorage) {
+    if (!remoteStorage.bucket.trim() || !remoteStorage.prefix.trim())
+        fail("invalid_argument", "--bucket and --prefix are required");
+    const config = await readConfig(dataDir);
+    const normalized = { ...remoteStorage, bucket: remoteStorage.bucket.trim(), prefix: remoteStorage.prefix.replace(/^\/+|\/+$/g, "") };
+    if (!normalized.prefix)
+        fail("invalid_argument", "--prefix cannot be empty");
+    const next = { ...config, remoteStorage: normalized };
+    await writeJson(configPath(dataDir), next);
+    return next;
+}
+export async function initialize(dataDir, providedPhrase, opts = {}) {
+    if (await exists(configPath(dataDir)))
+        fail("vault_already_initialized", `Vault already initialized at ${dataDir}`, { dataDir });
+    const phrase = canonicalPhrase(providedPhrase ?? generateRecoveryPhrase());
+    // Defect #49: `??` only falls back to a generated phrase on null/undefined,
+    // so `setup --recovery-phrase ""` sailed through with an empty phrase and no
+    // length, word-count, or entropy check ever ran. Whitespace-only input
+    // (`"   "`) passes canonicalPhrase() unchanged too -- it only rewrites
+    // recognised word phrases -- so checking the trimmed result after
+    // canonicalizing catches both, before anything is written to disk.
+    if (!phrase.trim())
+        fail("invalid_argument", "Recovery phrase cannot be empty or whitespace. Omit --recovery-phrase to generate a secure one, or supply a non-empty phrase.");
+    // A plain vault still gets a real phrase and a real phraseCheck: the phrase
+    // names the vault across machines and is what a future re-seal would wrap
+    // to. Only "plain" is ever written — a sealed config must stay byte-for-byte
+    // what it was before this mode existed.
+    const config = {
+        version: CONFIG_VERSION, vaultId: randomUUID(), storage: { provider: "local", root: archiveDir(dataDir) },
+        ...(opts.storageMode === "plain" ? { storageMode: "plain" } : {}),
+        recovery: { phraseCheck: phraseCheck(phrase) }
+    };
+    await writeJson(configPath(dataDir), config);
+    await mkdir(config.storage.root, { recursive: true });
+    return { config, phrase };
+}
+/**
+ * Refuses a transcript larger than a ceiling the operator asked for.
+ *
+ * This used to derive a ceiling from installed RAM, because archiving read the
+ * whole transcript, gzipped it and sealed it with all three resident — 3.64x
+ * the file's size, so a 4 GB rollout wanted about 14.5 GB and the three largest
+ * sessions on a 16 GB machine were simply refused. Archiving now streams a
+ * chunk at a time, so a transcript's size no longer predicts what it costs to
+ * archive and a machine-derived refusal would only turn away sessions this
+ * build can handle. Only an explicit VAULTLINE_MAX_ARCHIVE_BYTES still refuses.
+ */
+function assertArchivable(absolute, size) {
+    const ceiling = Number(process.env.VAULTLINE_MAX_ARCHIVE_BYTES ?? "");
+    if (!Number.isFinite(ceiling) || ceiling <= 0 || size <= ceiling)
+        return;
+    const gb = (value) => `${(value / 1024 ** 3).toFixed(1)} GB`;
+    fail("source_unreadable", `${absolute} is ${gb(size)}, above the VAULTLINE_MAX_ARCHIVE_BYTES ceiling of ${gb(ceiling)}. Raise or unset VAULTLINE_MAX_ARCHIVE_BYTES to archive it.`, { sourcePath: absolute, bytes: size, ceiling });
+}
+/**
+ * The archive whose bytes are still a prefix of this source, and how many.
+ *
+ * Agent transcripts are append-only JSONL, which is the property that makes
+ * incremental archiving possible at all: if the first N bytes have not changed,
+ * everything before N is already sealed and only the tail is new. "Have not
+ * changed" is *proved* here, not assumed — the prefix is re-read and hashed
+ * against what the archive recorded, in constant memory — because a wrong
+ * answer would produce an archive that cannot reconstruct the file.
+ *
+ * The longest proven prefix wins, so a transcript archived at 1 MB and again at
+ * 3 MB reports the 3 MB archive. Nothing is returned when the file was
+ * rewritten, truncated, or has never been archived.
+ */
+export async function provenAppendOffset(archives, sourcePath, currentBytes) {
+    const candidates = archives
+        .filter((record) => record.source.path === sourcePath && record.source.bytes > 0 && record.source.bytes <= currentBytes)
+        .sort((a, b) => b.source.bytes - a.source.bytes);
+    if (candidates.length === 0)
+        return null;
+    const digests = await hashFilePrefixes(sourcePath, candidates.map((record) => record.source.bytes));
+    for (const record of candidates) {
+        const prefix = digests.get(record.source.bytes);
+        if (prefix && equalHex(prefix, record.source.sha256))
+            return { archiveId: record.id, bytes: record.source.bytes };
+    }
+    return null;
+}
+/**
+ * The delta pointer on a record, when the record is a delta archive.
+ *
+ * Defensive on purpose: the field is not in the typed record (types.ts is the
+ * wire contract and moves separately), so this is the one place its shape is
+ * checked before anything trusts it.
+ */
+export function deltaOf(record) {
+    if (!isV2(record))
+        return null;
+    const delta = record.delta;
+    if (!delta || typeof delta !== "object")
+        return null;
+    const { baseArchiveId, baseBytes } = delta;
+    if (typeof baseArchiveId !== "string" || typeof baseBytes !== "number" || !(baseBytes > 0))
+        return null;
+    return { baseArchiveId, baseBytes };
+}
+/**
+ * The plain-mode object writer: gzip, and nothing else.
+ *
+ * Both hashes are taken as the bytes stream past so the source is read exactly
+ * once, the same discipline the sealed path follows. On failure the staged file
+ * is removed for the same reason sealArchiveToFile removes its destination — a
+ * crash must never leave a .partial that could be mistaken for an archive.
+ */
+async function writePlainArchive(sourcePath, staged, onProgress) {
+    const originalHash = createHash("sha256");
+    const storedHash = createHash("sha256");
+    let originalBytes = 0;
+    let storedBytes = 0;
+    try {
+        await pipeline(createReadStream(sourcePath), async function* (chunks) {
+            for await (const piece of chunks) {
+                originalHash.update(piece);
+                originalBytes += piece.length;
+                onProgress?.(originalBytes);
+                yield piece;
+            }
+        }, createGzip({ level: 6 }), async function* (chunks) {
+            for await (const piece of chunks) {
+                storedHash.update(piece);
+                storedBytes += piece.length;
+                yield piece;
+            }
+        }, createWriteStream(staged, { mode: 0o600 }));
+    }
+    catch (error) {
+        await rm(staged, { force: true });
+        throw error;
+    }
+    return { originalBytes, originalSha256: originalHash.digest("hex"), storedBytes, storedSha256: storedHash.digest("hex") };
+}
+/**
+ * Seals one transcript, reading and writing a chunk at a time.
+ *
+ * An existing archive is returned unchanged when the same source bytes are
+ * archived again, so a duplicate lifecycle event costs a hash rather than an
+ * archive.
+ *
+ * `hooks.delta` opts in to incremental sealing: when the newest archive of
+ * this path is a *proven* prefix of the live file, only the appended range is
+ * sealed and the record carries a `delta` pointer to its base. Off by default
+ * so every existing caller keeps writing complete, standalone archives; the
+ * queue worker turns it on, because re-sealing a growing session whole on
+ * every snapshot is exactly how 4 GB of transcript became 40 GB of storage.
+ */
+export async function archiveFile(dataDir, sourcePath, rawPhrase, agent = "custom", hooks = {}) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const config = await readConfig(dataDir);
+    if (!equalHex(config.recovery.phraseCheck, phraseCheck(phrase)))
+        fail("recovery_phrase_mismatch", "Recovery phrase does not match this vault");
+    const absolute = resolve(sourcePath);
+    const source = await stat(absolute).catch(() => null);
+    if (!source?.isFile())
+        return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
+    assertArchivable(absolute, source.size);
+    // Hashing the source to answer "have I already archived exactly this?" is a
+    // whole extra read of a file that may be gigabytes, so it is only worth doing
+    // when some archive of this path already claims the same length. Anything of
+    // a different length has certainly changed.
+    const archives = await listArchives(dataDir);
+    const sameLength = archives.filter((item) => item.source.path === absolute && item.source.bytes === source.size);
+    if (sameLength.length > 0) {
+        const { sha256: digest } = await hashFileRange(absolute);
+        const existing = sameLength.find((item) => equalHex(item.source.sha256, digest));
+        if (existing)
+            return { ...existing, deduplicated: true };
+    }
+    // What this snapshot adds to the newest one that is still a prefix of the
+    // file. Recorded, not acted on: the archive below is a complete, standalone
+    // archive of the whole transcript. See the note on `supersedes` in types.ts.
+    const base = await provenAppendOffset(archives, absolute, source.size);
+    // The delta path: the caller asked for it, the prefix is proven, and there
+    // is genuinely a tail to seal. Plain vaults are excluded — a bare gzip has
+    // no ranged layout, and "portable, readable memory" should stay whole files.
+    // (base.bytes === size never reaches here: the dedupe above already returned
+    // that archive.)
+    if (hooks.delta === true && config.storageMode !== "plain" && base && base.bytes < source.size) {
+        return sealDeltaArchive(dataDir, config, absolute, agent, phrase, source.size, base, hooks);
+    }
+    const id = randomUUID();
+    const objectPath = join(config.storage.root, `${id}.vlarchive`);
+    const staged = `${objectPath}.${randomUUID()}.partial`;
+    if (config.storageMode === "plain") {
+        const plain = await writePlainArchive(absolute, staged, hooks.onProgress).catch((error) => {
+            const code = error.code;
+            if (code && ["ENOENT", "EACCES", "EPERM", "EISDIR", "EBUSY"].includes(code))
+                return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
+            throw error;
+        });
+        // The record keeps the sealed shape minus the envelope, because everything
+        // downstream — dedupe, verify, offload, push — reads `cipher` as "the
+        // stored object's summary" and never as proof of encryption. In particular
+        // `ciphertextSha256` keeps its name: it has always meant "hash of the
+        // bytes on disk", which here is the gzip, and renaming it would fork every
+        // consumer into two field names for one meaning. No envelope is written
+        // because inventing one would claim key wrapping that never happened.
+        const record = {
+            version: 2, id, createdAt: new Date().toISOString(),
+            source: { path: absolute, agent, bytes: plain.originalBytes, sha256: plain.originalSha256 },
+            cipher: { algorithm: "none", ciphertextSha256: plain.storedSha256, storedBytes: plain.storedBytes, chunks: 0 },
+            objectPath, ...(base ? { supersedes: base } : {})
+        };
+        try {
+            await rename(staged, objectPath);
+        }
+        catch (error) {
+            await rm(staged, { force: true });
+            throw error;
+        }
+        await writeJson(join(config.storage.root, `${id}.json`), record);
+        await recordAudit(dataDir, "archive.create", "allowed", { archiveId: id, agent, bytes: plain.originalBytes, recipients: 0, supersedes: base?.archiveId ?? null });
+        return { ...record, deduplicated: false };
+    }
+    // Compression happens before the seal because ciphertext is incompressible
+    // by construction. How much it buys was assumed here to be about 2x; measured
+    // on a real 1.6 GB Codex rollout it is 1.5x, because these files carry a lot
+    // of base64 and tool output that has already been compressed once. The
+    // difference matters wherever space is planned rather than merely hoped for —
+    // see spaceNeededFor in src/disk.ts, which uses the measured figure.
+    const sealed = await sealArchiveToFile({ path: absolute, end: source.size }, staged, {
+        // gzip-chunk: compression lives inside each chunk, so sealing is a single
+        // pass with no staged body — the ×2 disk window is gone — and every chunk
+        // can later be fetched and opened alone. Archives sealed under the legacy
+        // whole-body layout stay readable forever; this changes what is WRITTEN.
+        recipients: configuredRecipients(config, phrase), archiveId: id, compression: "gzip-chunk",
+        adapter: { agent, version: ADAPTER_VERSION }, scratchDir: config.storage.root,
+        ...(hooks.onProgress ? { onProgress: hooks.onProgress } : {})
+    }).catch((error) => {
+        const code = error.code;
+        if (code && ["ENOENT", "EACCES", "EPERM", "EISDIR", "EBUSY"].includes(code))
+            return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
+        throw error;
+    });
+    const record = {
+        version: 2, id, createdAt: sealed.envelope.manifest.createdAt,
+        source: { path: absolute, agent, bytes: sealed.originalBytes, sha256: sealed.originalSha256 },
+        cipher: { algorithm: sealed.envelope.suite, ciphertextSha256: sealed.ciphertextSha256, storedBytes: sealed.storedBytes, chunks: sealed.envelope.chunks.length },
+        envelope: sealed.envelope, objectPath, ...(base ? { supersedes: base } : {})
+    };
+    // The object only becomes an archive once it is whole: the manifest hashes are
+    // proved by the last chunk, so a crash mid-seal leaves a .partial nobody reads.
+    try {
+        await rename(staged, objectPath);
+    }
+    catch (error) {
+        await rm(staged, { force: true });
+        throw error;
+    }
+    await writeJson(join(config.storage.root, `${id}.json`), record);
+    await recordAudit(dataDir, "archive.create", "allowed", { archiveId: id, agent, bytes: sealed.originalBytes, recipients: sealed.envelope.wrappedKeys.length, supersedes: base?.archiveId ?? null });
+    return { ...record, deduplicated: false };
+}
+/**
+ * Seals only what an appended transcript added since its proven base archive.
+ *
+ * The stored object covers `[base.bytes, size)` of the source — the append,
+ * nothing else — which is what makes archiving a growing session cost its
+ * growth instead of its length. The *record*, though, still answers for the
+ * whole transcript: `source.bytes`/`source.sha256` describe the entire live
+ * file at seal time, exactly as a full archive's record would. That one choice
+ * keeps every consumer honest without knowing deltas exist — dedupe still
+ * recognises an unchanged file, retention's "source changed since archived"
+ * gate still compares like with like, and `provenAppendOffset` can prove the
+ * *next* append against this record and chain on top of it.
+ *
+ * Deliberately absent: `supersedes`. That field's contract is "every byte of
+ * the archive it names is inside this one", and `pruneRedundantArchives`
+ * deletes on the strength of it. A delta does not contain its base — it
+ * *needs* it — so writing `supersedes` here would offer the base for pruning
+ * and turn a storage saving into data loss.
+ */
+async function sealDeltaArchive(dataDir, config, absolute, agent, phrase, size, base, hooks) {
+    const id = randomUUID();
+    const objectPath = join(config.storage.root, `${id}.vlarchive`);
+    const staged = `${objectPath}.${randomUUID()}.partial`;
+    const sealed = await sealArchiveToFile({ path: absolute, start: base.bytes, end: size }, staged, {
+        recipients: configuredRecipients(config, phrase), archiveId: id, compression: "gzip-chunk",
+        adapter: { agent, version: ADAPTER_VERSION }, scratchDir: config.storage.root,
+        ...(hooks.onProgress ? { onProgress: hooks.onProgress } : {})
+    }).catch((error) => {
+        const code = error.code;
+        if (code && ["ENOENT", "EACCES", "EPERM", "EISDIR", "EBUSY"].includes(code))
+            return fail("source_unreadable", `Transcript is not readable: ${absolute}`, { sourcePath: absolute });
+        throw error;
+    });
+    // The whole-file identity this record answers for. Hashed after the seal so
+    // a file that grew meanwhile is still described exactly as sealed: the range
+    // ends at `size` either way. A file that *shrank* mid-seal is not an append
+    // at all — refuse rather than record a chain that cannot reproduce anything;
+    // the queued retry re-proves the prefix and archives it whole.
+    const whole = await hashFileRange(absolute, 0, size);
+    if (sealed.originalBytes !== size - base.bytes || whole.bytes !== size) {
+        await rm(staged, { force: true });
+        fail("source_unreadable", `${absolute} changed while its append was being sealed; it will re-archive whole on the next pass`, { sourcePath: absolute, bytes: size });
+    }
+    const record = {
+        version: 2, id, createdAt: sealed.envelope.manifest.createdAt,
+        source: { path: absolute, agent, bytes: size, sha256: whole.sha256 },
+        cipher: { algorithm: sealed.envelope.suite, ciphertextSha256: sealed.ciphertextSha256, storedBytes: sealed.storedBytes, chunks: sealed.envelope.chunks.length },
+        envelope: sealed.envelope, objectPath,
+        delta: { baseArchiveId: base.archiveId, baseBytes: base.bytes }
+    };
+    try {
+        await rename(staged, objectPath);
+    }
+    catch (error) {
+        await rm(staged, { force: true });
+        throw error;
+    }
+    await writeJson(join(config.storage.root, `${id}.json`), record);
+    await recordAudit(dataDir, "archive.create", "allowed", { archiveId: id, agent, bytes: size, appendedBytes: sealed.originalBytes, recipients: sealed.envelope.wrappedKeys.length, supersedes: null, deltaBase: base.archiveId });
+    return { ...record, deduplicated: false };
+}
+/**
+ * The recovery phrase always gets a recipient, so a recovery kit alone can restore.
+ * Registered device and backup keys are added alongside it.
+ */
+export function configuredRecipients(config, rawPhrase, group) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const keys = (config.recipients ?? [])
+        .filter((recipient) => !group || recipient.group === group)
+        .map((recipient) => ({ kind: "x25519", publicKey: x25519PublicKeyFromRaw(Buffer.from(recipient.publicKey, "base64")) }));
+    return [{ kind: "phrase", phrase }, ...keys];
+}
+export async function listArchives(dataDir) {
+    const config = await readConfig(dataDir);
+    const { readdir } = await import("node:fs/promises");
+    const files = await readdir(config.storage.root);
+    const records = await Promise.all(files.filter((file) => file.endsWith(".json")).map(async (file) => JSON.parse(await readFile(join(config.storage.root, file), "utf8"))));
+    return records.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+/**
+ * Registers an X25519 public key that may open future archives. Only the public
+ * key is stored; the matching private key stays on its own device.
+ */
+export async function addRecipient(dataDir, label, publicKeyBase64, group) {
+    if (!label.trim())
+        fail("invalid_argument", "A recipient label is required");
+    const raw = Buffer.from(publicKeyBase64, "base64");
+    if (raw.length !== 32)
+        fail("invalid_argument", "An X25519 public key must be 32 bytes, base64 encoded");
+    const config = await readConfig(dataDir);
+    const id = keyRecipientId(raw);
+    const recipients = (config.recipients ?? []).filter((recipient) => recipient.id !== id);
+    recipients.push({ id, label: label.trim(), publicKey: raw.toString("base64"), addedAt: new Date().toISOString(), ...(group ? { group } : {}) });
+    const next = { ...config, recipients };
+    await writeJson(configPath(dataDir), next);
+    await recordAudit(dataDir, "recipient.add", "allowed", { recipientId: id, label: label.trim(), group: group ?? null });
+    return next;
+}
+/** Removes a recipient from future archives. Run `sealkeep rewrap` to revoke it on existing ones. */
+export async function removeRecipient(dataDir, id) {
+    const config = await readConfig(dataDir);
+    const recipients = (config.recipients ?? []).filter((recipient) => recipient.id !== id);
+    if (recipients.length === (config.recipients ?? []).length)
+        fail("invalid_argument", `No recipient with id ${id}`, { recipientId: id });
+    const next = { ...config, recipients };
+    await writeJson(configPath(dataDir), next);
+    await recordAudit(dataDir, "recipient.remove", "allowed", { recipientId: id });
+    return next;
+}
+/** Persists a full config document after validation by the caller. */
+export async function writeConfig(dataDir, config) {
+    await writeJson(configPath(dataDir), config);
+}
+/** A non-mutating preview. Policy evaluation lives in `src/retention.ts`. */
+export async function previewRetention(dataDir, olderThanDays = 30) {
+    const { evaluateRetention } = await import("./retention.js");
+    return evaluateRetention(dataDir, { olderThanDays });
+}
+/** One archive by id, or a named failure. Callers that need the record before the bytes start here. */
+export async function findArchive(dataDir, id) {
+    const record = (await listArchives(dataDir)).find((item) => item.id === id);
+    return record ?? fail("archive_not_found", `Archive not found: ${id}`, { archiveId: id });
+}
+/**
+ * Proves the phrase opens this archive, before the caller creates anything for it.
+ *
+ * Restoring streams straight to disk, so by the time a chunk fails there is
+ * already a partial file — and a partial file in a directory that had to be
+ * created is worse than no restore at all. Unwrapping the archive key needs
+ * only the envelope, costs one scrypt, and catches the failure people actually
+ * hit, so `restoreArchive` does it before it touches the filesystem.
+ */
+export function assertPhraseOpens(config, record, rawPhrase) {
+    const phrase = canonicalPhrase(rawPhrase);
+    // A plain archive has no wrapped key, so the phrase proves identity the same
+    // way archiving does. This is deliberately still a refusal: the bytes are
+    // readable by anyone with the disk, but a restore under the wrong phrase is
+    // evidence of the wrong vault, and acting on it would write the wrong
+    // person's sessions somewhere they were asked for their own.
+    if (config.storageMode === "plain") {
+        if (!equalHex(config.recovery.phraseCheck, phraseCheck(phrase)))
+            fail("recovery_phrase_mismatch", "Recovery phrase does not match this vault", { archiveId: record.id });
+        return;
+    }
+    // v1 has no separable wrap to test: decryptLegacyArchive needs the ciphertext,
+    // which restoreRecordToFile reads for it a moment later.
+    if (!isV2(record))
+        return;
+    try {
+        zeroize(unwrapArchiveKey(record.envelope.wrappedKeys, record.envelope.suite, record.envelope.archiveId, { phrase }));
+    }
+    catch (error) {
+        fail("recovery_phrase_mismatch", `Unable to open archive ${record.id}: ${error instanceof Error ? error.message : "decryption failed"}`, { archiveId: record.id });
+    }
+}
+/**
+ * Says what actually went wrong when an archive would not open.
+ *
+ * Every failure here used to be reported as a recovery-phrase mismatch, which
+ * was wrong for most of them and actively harmful for one: restoring writes the
+ * decrypted bytes to a file, so a full disk surfaced as `ENOSPC`, fell through
+ * to the decompression branch, and was announced as a wrong phrase. The people
+ * this tool is for are precisely the ones whose disks are full, so the single
+ * most likely restore failure told them their vault was lost. Only a key that
+ * no recipient can unwrap is evidence about the phrase; a disk that will not
+ * take bytes and an archive that fails its own hashes are separate facts.
+ */
+function openFailure(archiveId, error) {
+    if (!(error instanceof Error))
+        return new VaultlineError("internal", `Unable to open archive ${archiveId}`, { archiveId });
+    const code = error.code;
+    const detail = { archiveId };
+    switch (code) {
+        case "destination_write_failed":
+            return new VaultlineError("destination_unwritable", error.message, detail);
+        case "chunk_auth_failed":
+        case "chunk_hash_mismatch":
+        case "envelope_malformed":
+            return new VaultlineError("ciphertext_integrity_failed", `Archive ${archiveId} is damaged: ${error.message}`, detail);
+        case "plaintext_hash_mismatch":
+        case "plaintext_length_mismatch":
+            return new VaultlineError("plaintext_integrity_failed", `Archive ${archiveId} did not reproduce the bytes it recorded: ${error.message}`, detail);
+        default:
+            return new VaultlineError("recovery_phrase_mismatch", `Unable to open archive ${archiveId}: ${error.message}`, detail);
+    }
+}
+/**
+ * Restores one archive straight to a path, holding one chunk at a time.
+ *
+ * `destination` must be a path the caller is willing to see half-written: the
+ * whole-archive hashes are only proved once the last chunk has gone past, so a
+ * rejection can leave bytes behind. `restoreArchive` renames a temporary into
+ * place for exactly this reason.
+ */
+export async function restoreRecordToFile(dataDir, record, rawPhrase, destination, 
+/** Injectable so the offloaded-archive path can be proved without a bucket. */
+options = {}) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const config = await readConfig(dataDir);
+    // A delta archive's object holds only what an append added; the bytes before
+    // it live in its base chain. Routed through the one chain-aware helper so
+    // every caller of this function — the CLI and dashboard restore included —
+    // gets the whole transcript back, not a tail pretending to be one.
+    if (deltaOf(record)) {
+        const { bytes } = await restoreDeltaChainToFile(dataDir, record, phrase, destination, options);
+        return { bytes };
+    }
+    if (config.storageMode === "plain")
+        return restorePlainRecordToFile(dataDir, config, record, phrase, destination, options);
+    if (!isV2(record)) {
+        // v1 predates chunking: there is one AEAD frame over the whole archive, so
+        // there is nothing to stream and nothing to gain by pretending otherwise.
+        const { plaintext } = await decryptRecord(dataDir, record.id, phrase);
+        await writeFile(destination, plaintext, { mode: 0o600 });
+        return { bytes: plaintext.length };
+    }
+    // An archive whose local copy was offloaded lives in the bucket now, so it is
+    // fetched to a temporary file first and removed again afterwards — the bytes
+    // are on this disk only for as long as the restore takes, which is what keeps
+    // the space saving real. An archive that was never offloaded resolves to its
+    // own path and releases to nothing.
+    const { materialiseArchive } = await import("./offload.js");
+    const source = await materialiseArchive(dataDir, record, options.client);
+    try {
+        const { sha256: stored } = await hashFileRange(source.path);
+        if (!equalHex(stored, record.cipher.ciphertextSha256))
+            fail("ciphertext_integrity_failed", "Ciphertext integrity check failed before decryption", { archiveId: record.id });
+        let opened;
+        try {
+            opened = await openArchiveToFile(record.envelope, source.path, destination, { phrase });
+        }
+        catch (error) {
+            throw openFailure(record.id, error);
+        }
+        if (!equalHex(opened.sha256, record.source.sha256))
+            fail("plaintext_integrity_failed", "Plaintext integrity check failed after decryption", { archiveId: record.id });
+        return { bytes: opened.bytes };
+    }
+    finally {
+        await source.release();
+    }
+}
+/**
+ * The records that reproduce a delta archive's transcript, oldest first:
+ * one complete base archive, then every delta in append order, ending with
+ * `target` itself. A record that is not a delta resolves to just itself.
+ *
+ * Pure and synchronous so callers that only want to *show* a chain — a
+ * dashboard, `sealkeep list` — can resolve it without touching ciphertext.
+ * Every link is checked against the next one's claim: a missing base or a
+ * base whose recorded length is not what the delta sealed from is refused
+ * here, before any restore starts writing.
+ */
+export function resolveDeltaChain(archives, target) {
+    const byId = new Map(archives.map((record) => [record.id, record]));
+    const chain = [target];
+    const seen = new Set([target.id]);
+    let cursor = target;
+    for (let delta = deltaOf(cursor); delta; delta = deltaOf(cursor)) {
+        const base = byId.get(delta.baseArchiveId)
+            ?? fail("archive_not_found", `Archive ${cursor.id} is a delta of ${delta.baseArchiveId}, which is missing — without the base, the transcript cannot be reassembled`, { archiveId: delta.baseArchiveId, deltaId: cursor.id });
+        if (seen.has(base.id))
+            fail("ciphertext_integrity_failed", `Delta chain for ${target.id} loops at ${base.id}`, { archiveId: target.id });
+        if (base.source.bytes !== delta.baseBytes) {
+            fail("ciphertext_integrity_failed", `Delta ${cursor.id} sealed from ${delta.baseBytes} base bytes, but archive ${base.id} covers ${base.source.bytes}`, { archiveId: cursor.id, baseArchiveId: base.id });
+        }
+        chain.unshift(base);
+        seen.add(base.id);
+        cursor = base;
+    }
+    return chain;
+}
+/**
+ * Restores a delta archive by reassembling its chain: the base archive first,
+ * then each delta's appended range, concatenated in order into `destination`.
+ *
+ * Like `restoreRecordToFile`, the destination is written as the chain streams
+ * past, so callers restore through a temporary path and rename into place.
+ * Each link proves itself before its bytes land — stored-object hash before
+ * decryption, the envelope's own range hash inside `openArchiveToFile` — and
+ * the finished file is then proved *whole* against the newest record's
+ * full-transcript hash. A chain that cannot reproduce the exact bytes it
+ * promised is an error, never a nearly-right transcript.
+ */
+export async function restoreDeltaChainToFile(dataDir, record, rawPhrase, destination, options = {}) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const chain = resolveDeltaChain(await listArchives(dataDir), record);
+    const [baseRecord, ...deltas] = chain;
+    // The base is a complete, standalone archive; the single-record path already
+    // knows how to restore every kind of it (v2, v1, offloaded) and starts the
+    // destination file.
+    await restoreRecordToFile(dataDir, baseRecord, phrase, destination, options);
+    const { materialiseArchive } = await import("./offload.js");
+    for (const link of deltas) {
+        if (!isV2(link))
+            fail("ciphertext_integrity_failed", `Delta ${link.id} is not a v2 archive and cannot hold a sealed range`, { archiveId: link.id });
+        const delta = deltaOf(link);
+        const scratch = join(dirname(destination), `.${basename(destination)}.${randomUUID()}.delta`);
+        const source = await materialiseArchive(dataDir, link, options.client);
+        try {
+            const { sha256: stored } = await hashFileRange(source.path);
+            if (!equalHex(stored, link.cipher.ciphertextSha256))
+                fail("ciphertext_integrity_failed", "Ciphertext integrity check failed before decryption", { archiveId: link.id });
+            let opened;
+            try {
+                opened = await openArchiveToFile(link.envelope, source.path, scratch, { phrase });
+            }
+            catch (error) {
+                throw openFailure(link.id, error);
+            }
+            if (opened.bytes !== link.source.bytes - delta.baseBytes) {
+                fail("plaintext_integrity_failed", `Delta ${link.id} reproduced ${opened.bytes} bytes where its record promises ${link.source.bytes - delta.baseBytes}`, { archiveId: link.id });
+            }
+            await pipeline(createReadStream(scratch), createWriteStream(destination, { flags: "a", mode: 0o600 }));
+        }
+        finally {
+            await rm(scratch, { force: true });
+            await source.release();
+        }
+    }
+    // The reassembled whole must be the transcript the newest record answered
+    // for — proved against the disk, not inferred from the links passing.
+    const whole = await hashFileRange(destination);
+    if (whole.bytes !== record.source.bytes || !equalHex(whole.sha256, record.source.sha256)) {
+        fail("plaintext_integrity_failed", `Archive ${record.id} did not reproduce the bytes it recorded after reassembling its ${chain.length}-link chain`, { archiveId: record.id });
+    }
+    return { bytes: whole.bytes, chain: chain.map((link) => link.id) };
+}
+/**
+ * The plain-vault restore: gunzip, with the sealed path's checks kept.
+ *
+ * Same shape as the sealed branch on purpose — materialise (so offloaded plain
+ * archives come back from the bucket the same way), prove the stored object's
+ * hash before touching it, prove the plaintext hash after — because "not
+ * encrypted" must never come to mean "not verified".
+ */
+async function restorePlainRecordToFile(dataDir, config, record, phrase, destination, options) {
+    assertPhraseOpens(config, record, phrase);
+    // Plain mode postdates v1, so a v1 record in a plain vault is a record that
+    // was copied in from somewhere else; refuse rather than guess at its bytes.
+    if (!isV2(record))
+        fail("ciphertext_integrity_failed", `Archive ${record.id} is not a plain-mode archive`, { archiveId: record.id });
+    const { materialiseArchive } = await import("./offload.js");
+    const source = await materialiseArchive(dataDir, record, options.client);
+    try {
+        const { sha256: stored } = await hashFileRange(source.path);
+        if (!equalHex(stored, record.cipher.ciphertextSha256))
+            fail("ciphertext_integrity_failed", "Stored object integrity check failed before restore", { archiveId: record.id });
+        const plaintextHash = createHash("sha256");
+        let bytes = 0;
+        try {
+            await pipeline(createReadStream(source.path), createGunzip(), async function* (chunks) {
+                for await (const piece of chunks) {
+                    plaintextHash.update(piece);
+                    bytes += piece.length;
+                    yield piece;
+                }
+            }, createWriteStream(destination, { mode: 0o600 }));
+        }
+        catch (error) {
+            // The taxonomy openFailure defends for the sealed path, kept here: a full
+            // disk is about the destination, not the archive, and must not be
+            // reported as a damaged archive.
+            const code = error?.code;
+            if (error instanceof Error && typeof code === "string" && /^E[A-Z]+$/.test(code)) {
+                fail("destination_unwritable", code === "ENOSPC" ? `Ran out of space writing to ${dirname(destination)}. The archive is intact — free some space and restore again.` : `Could not write to ${dirname(destination)} (${code}). The archive is intact.`, { archiveId: record.id });
+            }
+            fail("ciphertext_integrity_failed", `Archive ${record.id} is damaged: ${error instanceof Error ? error.message : "gunzip failed"}`, { archiveId: record.id });
+        }
+        if (!equalHex(plaintextHash.digest("hex"), record.source.sha256))
+            fail("plaintext_integrity_failed", "Plaintext integrity check failed after restore", { archiveId: record.id });
+        return { bytes };
+    }
+    finally {
+        await source.release();
+    }
+}
+/**
+ * Verifies then decrypts one archive in memory. Ciphertext integrity is checked
+ * before the key touches it, and plaintext integrity after.
+ *
+ * This holds the whole transcript at once; `restoreRecordToFile` is the
+ * constant-memory path and is what restoring uses. Callers that genuinely need
+ * the bytes in hand — indexing, the v1 migration — still come through here.
+ */
+/**
+ * The sealed bytes of a record, wherever they live. A local blob reads
+ * straight from disk; an OFFLOADED archive — sealed copy in the cloud, local
+ * blob reclaimed — is fetched hash-checked and held only for the read. Found
+ * by the live value drill: `sealkeep index build` died with ENOENT on the
+ * first offloaded legacy archive it met, because this read assumed the blob.
+ */
+async function readSealedObject(dataDir, record) {
+    const { materialiseArchive } = await import("./offload.js");
+    const materialised = await materialiseArchive(dataDir, record);
+    try {
+        return await readFile(materialised.path);
+    }
+    finally {
+        await materialised.release();
+    }
+}
+export async function decryptRecord(dataDir, id, rawPhrase) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const config = await readConfig(dataDir);
+    const record = await findArchive(dataDir, id);
+    // A delta archive decrypts as its whole transcript: base chain first, then
+    // each sealed append, concatenated and proved against the record's
+    // full-transcript hash. Without this, search and the v1 migration would
+    // decrypt a tail and correctly refuse it as not matching the record.
+    if (deltaOf(record) && config.storageMode !== "plain") {
+        const chain = resolveDeltaChain(await listArchives(dataDir), record);
+        const pieces = [(await decryptRecord(dataDir, chain[0].id, phrase)).plaintext];
+        for (const link of chain.slice(1)) {
+            if (!isV2(link))
+                fail("ciphertext_integrity_failed", `Delta ${link.id} is not a v2 archive and cannot hold a sealed range`, { archiveId: link.id });
+            const sealedRange = await readSealedObject(dataDir, link);
+            if (!equalHex(sha256(sealedRange), link.cipher.ciphertextSha256))
+                fail("ciphertext_integrity_failed", "Ciphertext integrity check failed before decryption", { archiveId: link.id });
+            try {
+                pieces.push(openEnvelope(link.envelope, sealedRange, { phrase }));
+            }
+            catch (error) {
+                fail("recovery_phrase_mismatch", `Unable to open archive ${link.id}: ${error instanceof Error ? error.message : "decryption failed"}`, { archiveId: link.id });
+            }
+        }
+        const assembled = Buffer.concat(pieces);
+        if (!equalHex(sha256(assembled), record.source.sha256))
+            fail("plaintext_integrity_failed", "Plaintext integrity check failed after decryption", { archiveId: id });
+        return { record, plaintext: assembled };
+    }
+    const ciphertext = await readSealedObject(dataDir, record);
+    if (!equalHex(sha256(ciphertext), record.cipher.ciphertextSha256))
+        fail("ciphertext_integrity_failed", "Ciphertext integrity check failed before decryption", { archiveId: id });
+    // In a plain vault the stored object is a gzip, so "decrypt" is gunzip — but
+    // the phrase and hash contracts hold either way: callers like search hand
+    // this the vault's phrase and rely on a wrong one being refused.
+    if (config.storageMode === "plain") {
+        assertPhraseOpens(config, record, phrase);
+        let unzipped;
+        try {
+            unzipped = gunzipSync(ciphertext);
+        }
+        catch (error) {
+            return fail("ciphertext_integrity_failed", `Archive ${id} is damaged: ${error instanceof Error ? error.message : "gunzip failed"}`, { archiveId: id });
+        }
+        if (!equalHex(sha256(unzipped), record.source.sha256))
+            fail("plaintext_integrity_failed", "Plaintext integrity check failed after decompression", { archiveId: id });
+        return { record, plaintext: unzipped };
+    }
+    let plaintext;
+    try {
+        plaintext = isV2(record)
+            ? openEnvelope(record.envelope, ciphertext, { phrase })
+            : decryptLegacyArchive(ciphertext, { ...record.cipher, wrappedKey: record.wrappedKey }, phrase);
+    }
+    catch (error) {
+        fail("recovery_phrase_mismatch", `Unable to open archive ${id}: ${error instanceof Error ? error.message : "decryption failed"}`, { archiveId: id });
+    }
+    if (!equalHex(sha256(plaintext), record.source.sha256))
+        fail("plaintext_integrity_failed", "Plaintext integrity check failed after decryption", { archiveId: id });
+    return { record, plaintext: plaintext };
+}
+/** Kept for callers that name their own destination. Restore policy lives in `src/restore.ts`. */
+export async function recoverArchive(dataDir, id, destination, phrase) {
+    const { restoreArchive } = await import("./restore.js");
+    const outcome = await restoreArchive(dataDir, id, phrase, { destination, overwrite: "refuse" });
+    return { record: outcome.record, output: outcome.output };
+}