sealkeep 0.5.0

package/dist/src/retention.js

@@ -0,0 +1,446 @@
+import { readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isSourceActive } from "./activity.js";
+import { fail, isVaultlineError } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { moveToTrash } from "./trash.js";
+import { isV2 } from "./types.js";
+import { listArchives, readConfig, writeConfig, writeRecord } from "./vault.js";
+/** For blocker text a person reads. Whole numbers below 10 units, one decimal above. */
+function humanBytes(value) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let size = value, unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? size : size < 10 ? size.toFixed(1) : Math.round(size)} ${units[unit]}`;
+}
+export const DEFAULT_RETENTION = {
+    policy: "local-only", olderThanDays: 30, graceDays: 7, deleteAfterDays: null,
+    sourceIdleDays: null, minSourceBytes: null
+};
+export const POLICIES = ["local-only", "sync-only", "archive-and-reclaim", "manual-approval"];
+export function retentionSettings(config, overrides = {}) {
+    return { ...DEFAULT_RETENTION, ...config.retention, ...overrides };
+}
+const approvalsPath = (dataDir) => join(dataDir, "retention-approvals.json");
+export async function readApprovals(dataDir) {
+    try {
+        return JSON.parse(await readFile(approvalsPath(dataDir), "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+/** Manual-approval policy: an operator names the archives whose sources may be reclaimed. */
+export async function approveReclamation(dataDir, archiveIds) {
+    const known = new Set((await listArchives(dataDir)).map((record) => record.id));
+    for (const id of archiveIds)
+        if (!known.has(id))
+            fail("archive_not_found", `Archive not found: ${id}`, { archiveId: id });
+    const merged = [...new Set([...(await readApprovals(dataDir)), ...archiveIds])];
+    await writeFile(approvalsPath(dataDir), JSON.stringify(merged, null, 2) + "\n", { mode: 0o600 });
+    await recordAudit(dataDir, "retention.approve", "allowed", { approved: archiveIds.length, total: merged.length });
+    return merged;
+}
+/**
+ * Decides, per archive, whether its local source may be reclaimed.
+ *
+ * Every gate is evaluated and all failures are reported, so an operator sees the
+ * complete reason a file is protected rather than the first one that matched.
+ */
+export async function evaluateRetention(dataDir, options = {}) {
+    const config = await readConfig(dataDir);
+    const settings = retentionSettings(config, { ...options.settings, ...(options.olderThanDays === undefined ? {} : { olderThanDays: options.olderThanDays }) });
+    if (!Number.isFinite(settings.olderThanDays) || settings.olderThanDays < 0)
+        fail("invalid_argument", "olderThanDays must be a non-negative number");
+    if (settings.sourceIdleDays !== null && (!Number.isFinite(settings.sourceIdleDays) || settings.sourceIdleDays < 0))
+        fail("invalid_argument", "sourceIdleDays must be a non-negative number of days, or null to ignore how long a session has been idle");
+    if (settings.minSourceBytes !== null && (!Number.isFinite(settings.minSourceBytes) || settings.minSourceBytes < 0))
+        fail("invalid_argument", "minSourceBytes must be a non-negative number of bytes, or null to reclaim any size");
+    const now = options.now ?? Date.now();
+    const approvals = new Set(await readApprovals(dataDir));
+    const candidates = [];
+    // Whether this vault is on the managed tier, which has no remoteStorage of
+    // its own. Best effort and cheap: any archive that has been verified into
+    // managed storage proves it, and a fresh vault with none reads as unmanaged,
+    // which only changes wording.
+    const allRecords = await listArchives(dataDir);
+    const managed = allRecords.some((item) => isV2(item) && item.remote?.provider === "vaultline");
+    for (const record of allRecords) {
+        const current = await stat(record.source.path).catch(() => null);
+        if (!current)
+            continue;
+        if (isV2(record) && record.reclaimed)
+            continue;
+        const blockers = [];
+        // The archive covers the bytes that existed when it was written. A session
+        // that kept being appended to has content in no archive at all, and
+        // reclaiming it would delete exactly that content — so refuse, and say so
+        // in terms that name the fix. Size is compared rather than hashed because
+        // agent transcripts grow by appending and this runs over every record.
+        if (current.size !== record.source.bytes)
+            blockers.push(`source changed since it was archived (${record.source.bytes} bytes archived, ${current.size} now); re-archive it first`);
+        // These render straight into a dashboard table cell, so they are sentences
+        // a customer reads, not slugs a maintainer greps. The retention page already
+        // names the four policies in plain words; the same words are used here.
+        //
+        // Order matters: `reason` is the first of these, and it is what the table
+        // shows in a narrow column. The one a person can act on leads — "no
+        // storage is set up" is a thing to go and change, while "set to keep
+        // everything" is quite possibly what they meant.
+        const remote = isV2(record) ? record.remote : undefined;
+        // A managed-tier vault has no `remoteStorage` of its own — the bucket is
+        // ours — so "no remote target configured" was told to paying customers about
+        // storage they were paying for. The honest state is the same either way:
+        // this archive has not been uploaded and verified yet.
+        if (!remote?.verifiedAt)
+            blockers.push(config.remoteStorage || managed ? "not yet uploaded and verified" : "no storage is set up, so there is no second copy to reclaim against");
+        // A delta archive restores through its whole chain, so "there is a second
+        // copy" must be true of every link, not just this head. One unverified
+        // base and reclaiming the source deletes bytes only this disk holds.
+        if (remote?.verifiedAt) {
+            const { deltaOf, resolveDeltaChain } = await import("./vault.js");
+            if (deltaOf(record)) {
+                try {
+                    const chain = resolveDeltaChain(allRecords, record);
+                    const unverified = chain.filter((link) => !(isV2(link) && link.remote?.verifiedAt)).length;
+                    if (unverified > 0)
+                        blockers.push(`this snapshot builds on ${chain.length - 1} earlier ${chain.length === 2 ? "archive" : "archives"}, and ${unverified} of the chain ${unverified === 1 ? "is" : "are"} not uploaded and verified yet`);
+                }
+                catch {
+                    blockers.push("this snapshot builds on an earlier archive that is missing, so the transcript cannot be restored from the cloud alone");
+                }
+            }
+        }
+        if (settings.policy === "local-only")
+            blockers.push("retention is set to keep everything");
+        if (settings.policy === "sync-only")
+            blockers.push("retention is set to upload but keep the original");
+        if (!isV2(record))
+            blockers.push("this archive is in an older format and needs updating before its source can be reclaimed");
+        const ageMs = now - Date.parse(record.createdAt);
+        if (ageMs < settings.olderThanDays * 86_400_000)
+            blockers.push(`archived ${Math.floor(ageMs / 86_400_000)} days ago, younger than the ${settings.olderThanDays}-day threshold`);
+        // The source's own age, read from the file rather than from our records, so
+        // "I have not touched this in months" is answerable without trusting that
+        // we archived it at a useful moment.
+        if (settings.sourceIdleDays !== null) {
+            const idleDays = (now - current.mtimeMs) / 86_400_000;
+            if (idleDays < settings.sourceIdleDays)
+                blockers.push(`last modified ${Math.floor(idleDays)} days ago, sooner than the ${settings.sourceIdleDays}-day idle threshold`);
+        }
+        if (settings.minSourceBytes !== null && current.size < settings.minSourceBytes)
+            blockers.push(`${humanBytes(current.size)} is under your ${humanBytes(settings.minSourceBytes)} floor`);
+        if (remote?.verifiedAt) {
+            const graceRemainingMs = settings.graceDays * 86_400_000 - (now - Date.parse(remote.verifiedAt));
+            // Days, because that is the unit the person set it in; "168h" for a
+            // seven-day grace period is a conversion nobody asked for.
+            if (graceRemainingMs > 0) {
+                const hours = Math.ceil(graceRemainingMs / 3_600_000);
+                blockers.push(hours < 48 ? `grace period ends in ${hours}h` : `grace period ends in ${Math.ceil(hours / 24)} days`);
+            }
+        }
+        // The activity probe shells out to lsof, so it is the one expensive gate —
+        // and it only changes the outcome when every other gate already passed.
+        // Probing unconditionally put ~90ms × every archive inside each evaluation,
+        // which every /v1/status call awaited: 49 archives made the dashboard's
+        // first paint 4 seconds, and a big library would make it a minute.
+        if (blockers.length === 0) {
+            const activity = await isSourceActive(record.source.path, { ...options.activity, now });
+            if (activity.active)
+                blockers.push(`source looks active: ${activity.reason}`);
+        }
+        if (settings.policy === "manual-approval" && !approvals.has(record.id))
+            blockers.push("awaiting manual approval");
+        // Two gates can reach the same conclusion in the same words; a cell that
+        // reads "no storage set up · no storage set up" looks like a bug, not a
+        // reason.
+        const distinct = [...new Set(blockers)];
+        candidates.push({
+            id: record.id, agent: record.source.agent, path: record.source.path, bytes: record.source.bytes, createdAt: record.createdAt,
+            eligible: distinct.length === 0, blockers: distinct, reason: distinct[0] ?? "eligible for reclamation",
+            remote: remote?.verifiedAt ? { provider: remote.provider, verifiedAt: remote.verifiedAt } : null
+        });
+    }
+    const reclaimableBytes = candidates.filter((candidate) => candidate.eligible).reduce((total, candidate) => total + candidate.bytes, 0);
+    return {
+        mode: "preview", policy: settings.policy, olderThanDays: settings.olderThanDays, graceDays: settings.graceDays,
+        sourceIdleDays: settings.sourceIdleDays, minSourceBytes: settings.minSourceBytes,
+        // Returned so the page that sets it can show what is set. Without it the
+        // field rendered blank on every load, which read as "not configured" even
+        // when it was.
+        deleteAfterDays: settings.deleteAfterDays,
+        reclaimableBytes, candidates
+    };
+}
+/**
+ * Reclaims eligible sources. Dry-run is the default: without `confirm`, nothing on
+ * disk changes. Reclaimed files go to the OS trash, never to `unlink`.
+ */
+export async function applyRetention(dataDir, options = {}) {
+    const config = await readConfig(dataDir);
+    const evaluation = await evaluateRetention(dataDir, options);
+    const eligible = evaluation.candidates.filter((candidate) => candidate.eligible);
+    if (!options.confirm) {
+        return { mode: "dry-run", policy: evaluation.policy, wouldReclaim: eligible.length, wouldFreeBytes: evaluation.reclaimableBytes, candidates: evaluation.candidates };
+    }
+    const records = new Map((await listArchives(dataDir)).map((record) => [record.id, record]));
+    const reclaimed = [];
+    const failed = [];
+    for (const candidate of eligible) {
+        try {
+            const result = await moveToTrash(candidate.path, { dataDir, home: options.home, strategy: options.strategy });
+            const record = records.get(candidate.id);
+            if (isV2(record)) {
+                const next = { ...record, reclaimed: { at: new Date(options.now ?? Date.now()).toISOString(), trashPath: result.movedTo, strategy: result.strategy } };
+                await writeRecord(config.storage.root, next);
+            }
+            await recordAudit(dataDir, "source.reclaim", "allowed", { archiveId: candidate.id, path: candidate.path, bytes: candidate.bytes, movedTo: result.movedTo, strategy: result.strategy });
+            reclaimed.push({ id: candidate.id, path: candidate.path, bytes: candidate.bytes, movedTo: result.movedTo, strategy: result.strategy });
+        }
+        catch (error) {
+            await recordAudit(dataDir, "source.reclaim", "denied", { archiveId: candidate.id, path: candidate.path });
+            failed.push({ id: candidate.id, error: error instanceof Error ? error.message : "reclamation failed" });
+        }
+    }
+    return { mode: "apply", policy: evaluation.policy, reclaimed, failed, freedBytes: reclaimed.reduce((total, item) => total + item.bytes, 0), protected: evaluation.candidates.length - eligible.length };
+}
+/**
+ * Reclaims ONE source, because a person pointed at it.
+ *
+ * The automatic pass (`applyRetention`) obeys every rule: policy, age, grace,
+ * idle, size floor, manual approval. Those rules exist so the machine acting
+ * on its own is conservative. A person clicking one row after checking its
+ * cloud copy IS the approval — so this path keeps only the gates that protect
+ * against actual data loss, and says which one refused when it refuses:
+ *
+ *  - the archive must have a verified remote copy (and a delta head's whole
+ *    chain must be verified — one unverified base and the cloud cannot
+ *    reproduce the file this is about to trash);
+ *  - the source must be byte-for-byte the file that was archived — a session
+ *    that grew since has content in no archive at all;
+ *  - nothing may have the file open right now.
+ *
+ * Policy, age and grace are deliberately not consulted. Trash, never unlink,
+ * same as everywhere.
+ */
+export async function reclaimOne(dataDir, archiveId, options = {}) {
+    const config = await readConfig(dataDir);
+    const archives = await listArchives(dataDir);
+    const record = archives.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 });
+    if (record.reclaimed)
+        fail("invalid_argument", "This source was already reclaimed — it is in your trash, not on this list.");
+    const current = await stat(record.source.path).catch(() => null);
+    if (!current)
+        fail("source_unreadable", "The source file is no longer at its recorded path, so there is nothing to reclaim.", { path: record.source.path });
+    if (current.size !== record.source.bytes) {
+        fail("invalid_argument", `The session changed since it was archived (${record.source.bytes} bytes archived, ${current.size} now) — re-archive it first, or reclaiming would delete exactly the part no archive holds.`, { archiveId });
+    }
+    if (!record.remote?.verifiedAt) {
+        fail("invalid_argument", "No verified cloud copy exists for this archive, so this disk holds the only bytes. Upload it first.", { archiveId });
+    }
+    const { deltaOf, resolveDeltaChain } = await import("./vault.js");
+    if (deltaOf(record)) {
+        try {
+            const chain = resolveDeltaChain(archives, record);
+            const unverified = chain.filter((link) => !(isV2(link) && link.remote?.verifiedAt)).length;
+            if (unverified > 0)
+                fail("invalid_argument", `This snapshot builds on earlier archives and ${unverified} of the chain ${unverified === 1 ? "is" : "are"} not verified in the cloud yet — the cloud cannot reproduce this file without them.`, { archiveId });
+        }
+        catch (error) {
+            if (isVaultlineError(error))
+                throw error;
+            fail("invalid_argument", "This snapshot builds on an earlier archive that is missing, so the cloud cannot reproduce the file. Keep the source.", { archiveId });
+        }
+    }
+    const activity = await isSourceActive(record.source.path, { ...options.activity, now: options.now ?? Date.now() });
+    if (activity.active)
+        fail("invalid_argument", `The file looks in use right now: ${activity.reason}. Close it and try again.`, { archiveId });
+    if (!options.confirm)
+        fail("invalid_argument", "Pass confirm to move this source to the trash.");
+    const result = await moveToTrash(record.source.path, { dataDir, home: options.home, strategy: options.strategy });
+    const next = { ...record, reclaimed: { at: new Date(options.now ?? Date.now()).toISOString(), trashPath: result.movedTo, strategy: result.strategy } };
+    await writeRecord(config.storage.root, next);
+    await recordAudit(dataDir, "source.reclaim", "allowed", { archiveId, path: record.source.path, bytes: record.source.bytes, movedTo: result.movedTo, strategy: result.strategy, manual: true });
+    return { id: archiveId, path: record.source.path, bytes: record.source.bytes, movedTo: result.movedTo, strategy: result.strategy };
+}
+/**
+ * `reclaimOne` over a selection. Each row passes or is kept with its reason —
+ * one refusal never blocks the rest, and the reasons come back in the same
+ * sentences the single path speaks.
+ */
+export async function reclaimBatch(dataDir, ids, options = {}) {
+    const reclaimed = [];
+    const kept = [];
+    for (const id of ids) {
+        try {
+            reclaimed.push(await reclaimOne(dataDir, id, options));
+        }
+        catch (error) {
+            kept.push({ id, reason: error instanceof Error ? error.message : "could not reclaim" });
+        }
+    }
+    return { reclaimed, kept, freedBytes: reclaimed.reduce((total, item) => total + item.bytes, 0) };
+}
+export async function setRetentionPolicy(dataDir, settings) {
+    if (settings.policy && !POLICIES.includes(settings.policy))
+        fail("invalid_argument", `Policy must be one of: ${POLICIES.join(", ")}`);
+    for (const key of ["olderThanDays", "graceDays"]) {
+        const value = settings[key];
+        if (value !== undefined && (!Number.isFinite(value) || value < 0))
+            fail("invalid_argument", `${key} must be a non-negative number`);
+    }
+    // These two are nullable — null is "do not consider this at all", which is a
+    // different statement from zero, and zero would mean "reclaim everything".
+    for (const key of ["sourceIdleDays", "minSourceBytes", "deleteAfterDays"]) {
+        const value = settings[key];
+        if (value !== undefined && value !== null && (!Number.isFinite(value) || value < 0))
+            fail("invalid_argument", `${key} must be a non-negative number, or null to ignore it`);
+    }
+    const config = await readConfig(dataDir);
+    const next = { ...config, retention: retentionSettings(config, settings) };
+    await writeConfig(dataDir, next);
+    return next;
+}
+/**
+ * Snapshots whose every byte is already inside a newer archive of the same file.
+ *
+ * Agent transcripts are append-only, so a session archived while it was still
+ * growing leaves a trail: a 1 GB snapshot, then a 2 GB one, then the finished
+ * 3.8 GB. Each is complete and standalone — that is what makes them safe — but
+ * it also makes the earlier ones pure duplication, because the newest archive
+ * already reproduces every byte they hold. `supersedes` recorded this from the
+ * beginning and nothing ever read it, so the trail was kept forever and, on
+ * metered storage, paid for forever.
+ *
+ * Nothing is deleted here. Deleting an archive is the one action that cannot be
+ * undone from somewhere else, and the product's promise is that it reports what
+ * could go and never acts alone. Two conditions are required before a snapshot
+ * is even *offered*: the superseding archive's object must still exist, and,
+ * where remote storage is configured, it must be verified there. A redundant
+ * copy is only redundant while the copy that replaced it is real.
+ */
+export async function redundantArchives(dataDir) {
+    const { readConfig, listArchives } = await import("./vault.js");
+    const config = await readConfig(dataDir);
+    const archives = await listArchives(dataDir);
+    const byId = new Map(archives.map((record) => [record.id, record]));
+    // Which archives are pointed at as a base, and by whom. Only the *newest*
+    // claimant matters, but any claimant proves the bytes live on elsewhere.
+    const supersededBy = new Map();
+    for (const record of archives) {
+        if (!isV2(record) || !record.supersedes)
+            continue;
+        supersededBy.set(record.supersedes.archiveId, record.id);
+    }
+    // Delta archives NEED their base: a delta holds only the appended tail, so
+    // every link under a live delta is load-bearing. Deltas deliberately write
+    // no `supersedes`, which keeps the common path safe — this set closes the
+    // contrived one, a full snapshot superseding an archive that some other
+    // delta still bases on.
+    const { deltaOf } = await import("./vault.js");
+    const deltaBases = new Set();
+    for (const record of archives) {
+        let base = deltaOf(record)?.baseArchiveId;
+        for (let hops = 0; base && hops < archives.length; hops += 1) {
+            deltaBases.add(base);
+            const next = byId.get(base);
+            base = next ? deltaOf(next)?.baseArchiveId : undefined;
+        }
+    }
+    const redundant = [];
+    for (const record of archives) {
+        if (deltaBases.has(record.id))
+            continue;
+        const heirId = supersededBy.get(record.id);
+        if (!heirId)
+            continue;
+        const heir = byId.get(heirId);
+        if (!heir)
+            continue;
+        // The heir has to actually be there. An archive whose replacement has been
+        // deleted is not redundant, it is the only copy left.
+        const heirObject = await stat(heir.objectPath).catch(() => null);
+        if (!heirObject)
+            continue;
+        if (config.remoteStorage && !(isV2(heir) && heir.remote?.verifiedAt))
+            continue;
+        const own = await stat(record.objectPath).catch(() => null);
+        if (!own)
+            continue;
+        redundant.push({
+            id: record.id, agent: record.source.agent, path: record.source.path,
+            storedBytes: own.size, createdAt: record.createdAt, supersededBy: heirId, objectPath: record.objectPath
+        });
+    }
+    return {
+        redundant,
+        reclaimableBytes: redundant.reduce((total, item) => total + item.storedBytes, 0),
+        kept: archives.length - redundant.length
+    };
+}
+/**
+ * Removes snapshots that `redundantArchives` has already proved duplicate.
+ *
+ * A dry run unless confirmed, like every other destructive path here. The list
+ * is recomputed rather than accepted from a caller, so a stale page cannot ask
+ * for the deletion of something that has since become the last copy.
+ */
+export async function pruneRedundantArchives(dataDir, options = {}) {
+    const { redundant, reclaimableBytes } = await redundantArchives(dataDir);
+    if (!options.confirm)
+        return { mode: "preview", removed: [], wouldRemove: redundant, freedBytes: reclaimableBytes };
+    const removed = [];
+    const failed = [];
+    for (const item of redundant) {
+        try {
+            await rm(item.objectPath, { force: true });
+            await rm(join(dataDir, "archives", `${item.id}.json`), { force: true });
+            await recordAudit(dataDir, "archive.prune", "allowed", { archiveId: item.id, supersededBy: item.supersededBy, storedBytes: item.storedBytes });
+            removed.push(item);
+        }
+        catch (error) {
+            await recordAudit(dataDir, "archive.prune", "denied", { archiveId: item.id });
+            failed.push({ id: item.id, error: error instanceof Error ? error.message : "could not remove" });
+        }
+    }
+    return { mode: "apply", removed, failed, freedBytes: removed.reduce((total, item) => total + item.storedBytes, 0) };
+}
+/**
+ * Archives whose retention period has run out.
+ *
+ * This only ever *reports*. Deleting an archive is the one action in Sealkeep
+ * that cannot be undone by restoring from somewhere else — the archive is the
+ * last copy once the source has been reclaimed — so the decision to act on this
+ * list stays with an explicit command, and `deleteAfterDays: null` (never) is
+ * the default.
+ */
+export async function expiredArchives(dataDir, options = {}) {
+    const { readConfig, listArchives } = await import("./vault.js");
+    const config = await readConfig(dataDir);
+    const settings = retentionSettings(config, options.settings);
+    const now = options.now ?? Date.now();
+    const archives = await listArchives(dataDir);
+    if (settings.deleteAfterDays === null)
+        return { settings, expired: [], keptForever: archives.length };
+    if (!Number.isFinite(settings.deleteAfterDays) || settings.deleteAfterDays < 0) {
+        fail("invalid_argument", "deleteAfterDays must be a non-negative number of days, or null for never");
+    }
+    const expired = archives.flatMap((archive) => {
+        const ageDays = (now - Date.parse(archive.createdAt)) / 86_400_000;
+        if (!(ageDays >= settings.deleteAfterDays))
+            return [];
+        return [{
+                id: archive.id, agent: archive.source.agent, path: archive.source.path,
+                bytes: archive.source.bytes, createdAt: archive.createdAt,
+                ageDays: Math.floor(ageDays), objectPath: archive.objectPath
+            }];
+    });
+    return { settings, expired, keptForever: 0 };
+}

package/dist/src/rotate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Rotates the vault's recovery phrase without re-encrypting a single byte of
+ * content. Every archive's DEK gains a wrap under the NEW phrase while keeping
+ * its existing wraps — both phrases open everything locally until the old
+ * slots are retired, so there is no moment where a crash strands data behind
+ * a phrase nobody holds.
+ *
+ * What rotation can and cannot do, said plainly because it is the whole point:
+ * it protects every archive an attacker holding the old phrase has NOT copied,
+ * and everything sealed from now on. It cannot un-leak an object someone
+ * already downloaded while the old phrase was theirs — that is mathematics,
+ * not a product gap. And a copy in cloud storage embeds the envelope it was
+ * pushed with: until it is pushed again, the CLOUD copy opens only with the
+ * wraps it left with. The report names how many such copies exist, and the
+ * standard upload path re-pushes rewrapped envelopes as archives change.
+ */
+export type RotationReport = {
+    vaultId: string;
+    rewrapped: number;
+    skipped: {
+        id: string;
+        reason: string;
+    }[];
+    /** Cloud copies whose embedded envelope predates this rotation — they still honor the old phrase until re-pushed. */
+    staleCloudCopies: number;
+    keystoreUpdated: boolean;
+    passwordLockRewrapped: boolean;
+    phraseFile: string | null;
+};
+export declare function rotateVaultPhrase(dataDir: string, options: {
+    /** The current phrase, already resolved by the caller (keystore, flag, or prompt). */
+    currentPhrase: string;
+    /** Where the NEW phrase is written (0600). Deliberately a file: a phrase printed to a terminal lands in scrollback, transcripts, and logs — which is how the last one burned. */
+    phraseFile?: string;
+    /** The vault password when a password lock exists, so it can be re-pointed at the new phrase. */
+    password?: string;
+}): Promise<{
+    report: RotationReport;
+    newPhrase: string;
+}>;
+/**
+ * Changes the vault password. The phrase never changes and never appears:
+ * the old password proves itself by unwrapping phrase.lock, and the same
+ * phrase is wrapped again under the new one. Instant, no archives touched.
+ */
+export declare function changeVaultPassword(dataDir: string, currentPassword: string, newPassword: string): Promise<void>;
+export declare const rotatedPhrasePath: (dataDir: string) => string;

package/dist/src/rotate.js

@@ -0,0 +1,95 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { equalHex, phraseCheck } from "./crypto.js";
+import { fail } from "./errors.js";
+import { canonicalPhrase, generateRecoveryPhrase } from "./mnemonic.js";
+import { recordAudit } from "./audit.js";
+import { hasPasswordLock, unwrapPhrase, wrapPhrase } from "./password-lock.js";
+import { rememberRecoveryPhrase } from "./secrets.js";
+import { isV2 } from "./types.js";
+import { configuredRecipients, listArchives, readConfig, writeConfig, writeRecord } from "./vault.js";
+import { rewrapArchive } from "../packages/vaultline-crypto/src/index.js";
+export async function rotateVaultPhrase(dataDir, options) {
+    const config = await readConfig(dataDir);
+    const current = canonicalPhrase(options.currentPhrase);
+    if (!equalHex(config.recovery.phraseCheck, phraseCheck(current))) {
+        fail("recovery_phrase_mismatch", "The current recovery phrase does not match this vault. Nothing has changed.");
+    }
+    if (config.storageMode === "plain") {
+        fail("invalid_argument", "This vault stores archives unencrypted; there is no phrase to rotate.");
+    }
+    const passwordLocked = await hasPasswordLock(dataDir);
+    if (passwordLocked && !options.password) {
+        fail("invalid_argument", "This vault opens with a password. Provide it (--password or the prompt) so the lock can be re-pointed at the new phrase. Nothing has changed.");
+    }
+    if (passwordLocked) {
+        const held = await unwrapPhrase(dataDir, options.password);
+        if (held === null)
+            fail("recovery_phrase_mismatch", "That password does not open this vault. Nothing has changed.");
+    }
+    const newPhrase = generateRecoveryPhrase();
+    // Rewrap every record's key slots FIRST, under both phrases. Only after the
+    // last record carries the new wrap do the vault-level pointers move — a
+    // crash mid-loop leaves a vault that still opens exactly as before.
+    const rewrapped = [];
+    const skipped = [];
+    let staleCloudCopies = 0;
+    const records = await listArchives(dataDir);
+    for (const record of records) {
+        if (!isV2(record)) {
+            skipped.push({ id: record.id, reason: "v1 archive; run `sealkeep migrate` first" });
+            continue;
+        }
+        const next = {
+            ...record,
+            envelope: rewrapArchive(record.envelope, { phrase: current }, configuredRecipients(config, newPhrase), { mode: "add" })
+        };
+        await writeRecord(config.storage.root, next);
+        rewrapped.push(record.id);
+        if (record.remote?.verifiedAt || record.offloaded)
+            staleCloudCopies += 1;
+    }
+    // The pointers move together, new phrase last-writer-wins everywhere a
+    // machine looks for it: the check that verifies typed phrases, the keystore
+    // that lets archiving run unattended, and the password lock if one exists.
+    await writeConfig(dataDir, { ...config, recovery: { ...config.recovery, phraseCheck: phraseCheck(canonicalPhrase(newPhrase)) } });
+    await rememberRecoveryPhrase(dataDir, config.vaultId, newPhrase);
+    if (passwordLocked)
+        await wrapPhrase(dataDir, newPhrase, options.password);
+    let phraseFile = null;
+    if (options.phraseFile) {
+        phraseFile = options.phraseFile;
+        await writeFile(phraseFile, `${newPhrase}\n`, { mode: 0o600 });
+    }
+    await recordAudit(dataDir, "phrase.rotate", "allowed", { rewrapped: rewrapped.length, skipped: skipped.length, staleCloudCopies });
+    return {
+        newPhrase,
+        report: {
+            vaultId: config.vaultId,
+            rewrapped: rewrapped.length,
+            skipped,
+            staleCloudCopies,
+            keystoreUpdated: true,
+            passwordLockRewrapped: passwordLocked,
+            phraseFile
+        }
+    };
+}
+/**
+ * Changes the vault password. The phrase never changes and never appears:
+ * the old password proves itself by unwrapping phrase.lock, and the same
+ * phrase is wrapped again under the new one. Instant, no archives touched.
+ */
+export async function changeVaultPassword(dataDir, currentPassword, newPassword) {
+    if (!(await hasPasswordLock(dataDir))) {
+        fail("invalid_argument", "This vault has no password lock. `sealkeep setup --password` creates one.");
+    }
+    if (newPassword.length < 12)
+        fail("invalid_argument", "A vault password needs at least 12 characters.");
+    const phrase = await unwrapPhrase(dataDir, currentPassword);
+    if (phrase === null)
+        fail("recovery_phrase_mismatch", "That password does not open this vault. Nothing has changed.");
+    await wrapPhrase(dataDir, phrase, newPassword);
+    await recordAudit(dataDir, "password.change", "allowed", {});
+}
+export const rotatedPhrasePath = (dataDir) => join(dataDir, "rotated-phrase.txt");