sealkeep 0.5.0

package/dist/src/managed-chunks.d.ts

@@ -0,0 +1,55 @@
+import { type ChunkStoreClient } from "./chunk-store.js";
+/**
+ * Managed chunk folders, Paul's way: no chunk support in the control plane at
+ * all. The client already chunks — every sealed chunk is an ordinary file of
+ * known length — so each one is DELIVERED as an ordinary file, through the
+ * same upload lease, the same completion metering, the same download lease,
+ * and the same delete that a whole archive uses today. The plane never learns
+ * a new concept; it signs file PUTs, which is the one thing it always did.
+ *
+ * The mapping is mechanical. Chunk storage addresses objects as
+ * `<folder>/<name>`; for a managed vault the folder IS the archive id, and
+ * the object's cloud reference is `<archiveId>.<name>`:
+ *
+ *   f0be…12af/chunk-000000   →  vault_ref  f0be…12af.chunk-000000
+ *   f0be…12af/envelope.vlmeta →  vault_ref  f0be…12af.envelope.vlmeta
+ *
+ * Deterministic both ways, so any machine of the vault re-derives every
+ * reference from the archive id and the chunk count — no listing, no state.
+ * What the plane sees is the grouping it already had (one archive's rows sum
+ * to the same bytes one object used to), and never a name: project, date and
+ * session live only in the sealed sidecar, exactly as on an own bucket.
+ *
+ * Presence and size are proven against STORAGE (`statCiphertext`'s one-byte
+ * ranged read), not against the plane's rows — a lease that was minted but
+ * whose PUT never landed answers "absent", which is precisely what resume
+ * must see so it re-sends the same bytes under the same nonce (identical
+ * ciphertext; the invariant holds).
+ */
+export declare function managedRefForKey(key: string): string;
+/** Every cloud reference an archive's chunk folder occupies, re-derived from the record. */
+export declare function managedChunkRefs(archiveId: string, chunkCount: number): {
+    chunks: string[];
+    envelope: string;
+};
+export type CloudRowLike = {
+    vault_ref: string;
+    bytes?: number | string;
+} & Record<string, unknown>;
+/**
+ * Folds chunk-family rows into one synthetic row per archive for listings:
+ * the family's reference is the archive id, its bytes are the chunk sum (the
+ * envelope sidecar is bookkeeping, not payload — same accounting as BYO).
+ * Rows that are not family members pass through untouched.
+ */
+export declare function collapseCloudRows<T extends CloudRowLike>(rows: T[]): (T & {
+    chunked?: true;
+    members?: string[];
+})[];
+/**
+ * The four chunk-store verbs, spoken over the managed account. One upload
+ * lease per object — request, PUT, complete — is the entire write path;
+ * `pullCiphertext` hash-checks every read against the digest recorded at
+ * upload before handing it back.
+ */
+export declare function managedChunkClient(dataDir: string): ChunkStoreClient;

package/dist/src/managed-chunks.js

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { fail, isVaultlineError } from "./errors.js";
+import { chunkObjectName, ENVELOPE_OBJECT } from "./chunk-store.js";
+import { completeUpload, deleteCloudArchive, pullCiphertext, putCiphertext, requestUpload, statCiphertext } from "./cloud.js";
+/**
+ * Managed chunk folders, Paul's way: no chunk support in the control plane at
+ * all. The client already chunks — every sealed chunk is an ordinary file of
+ * known length — so each one is DELIVERED as an ordinary file, through the
+ * same upload lease, the same completion metering, the same download lease,
+ * and the same delete that a whole archive uses today. The plane never learns
+ * a new concept; it signs file PUTs, which is the one thing it always did.
+ *
+ * The mapping is mechanical. Chunk storage addresses objects as
+ * `<folder>/<name>`; for a managed vault the folder IS the archive id, and
+ * the object's cloud reference is `<archiveId>.<name>`:
+ *
+ *   f0be…12af/chunk-000000   →  vault_ref  f0be…12af.chunk-000000
+ *   f0be…12af/envelope.vlmeta →  vault_ref  f0be…12af.envelope.vlmeta
+ *
+ * Deterministic both ways, so any machine of the vault re-derives every
+ * reference from the archive id and the chunk count — no listing, no state.
+ * What the plane sees is the grouping it already had (one archive's rows sum
+ * to the same bytes one object used to), and never a name: project, date and
+ * session live only in the sealed sidecar, exactly as on an own bucket.
+ *
+ * Presence and size are proven against STORAGE (`statCiphertext`'s one-byte
+ * ranged read), not against the plane's rows — a lease that was minted but
+ * whose PUT never landed answers "absent", which is precisely what resume
+ * must see so it re-sends the same bytes under the same nonce (identical
+ * ciphertext; the invariant holds).
+ */
+export function managedRefForKey(key) {
+    const slash = key.indexOf("/");
+    if (slash <= 0 || slash === key.length - 1 || key.indexOf("/", slash + 1) !== -1) {
+        return fail("invalid_argument", `Not a managed chunk key (expected <archiveId>/<object>): ${key}`);
+    }
+    return `${key.slice(0, slash)}.${key.slice(slash + 1)}`;
+}
+/** Every cloud reference an archive's chunk folder occupies, re-derived from the record. */
+export function managedChunkRefs(archiveId, chunkCount) {
+    return {
+        chunks: Array.from({ length: chunkCount }, (_, index) => managedRefForKey(`${archiveId}/${chunkObjectName(index)}`)),
+        envelope: managedRefForKey(`${archiveId}/${ENVELOPE_OBJECT}`)
+    };
+}
+/** Recognises a cloud row that is one member of a chunk family, by its reference alone. */
+const FAMILY_REF = /^(.+)\.(chunk-\d{6}|envelope\.vlmeta)$/;
+/**
+ * Folds chunk-family rows into one synthetic row per archive for listings:
+ * the family's reference is the archive id, its bytes are the chunk sum (the
+ * envelope sidecar is bookkeeping, not payload — same accounting as BYO).
+ * Rows that are not family members pass through untouched.
+ */
+export function collapseCloudRows(rows) {
+    const families = new Map();
+    const plain = [];
+    for (const row of rows) {
+        const match = FAMILY_REF.exec(row.vault_ref);
+        if (!match) {
+            plain.push(row);
+            continue;
+        }
+        const family = families.get(match[1]) ?? { rows: [], chunkBytes: 0, members: [] };
+        family.rows.push(row);
+        family.members.push(row.vault_ref);
+        if (match[2].startsWith("chunk-"))
+            family.chunkBytes += Number(row.bytes) || 0;
+        families.set(match[1], family);
+    }
+    const folded = [...families.entries()].map(([id, family]) => ({
+        ...family.rows[0], vault_ref: id, bytes: family.chunkBytes, chunked: true, members: family.members
+    }));
+    return [...plain, ...folded];
+}
+/**
+ * The four chunk-store verbs, spoken over the managed account. One upload
+ * lease per object — request, PUT, complete — is the entire write path;
+ * `pullCiphertext` hash-checks every read against the digest recorded at
+ * upload before handing it back.
+ */
+export function managedChunkClient(dataDir) {
+    return {
+        async putObject(key, body) {
+            const ref = managedRefForKey(key);
+            const digest = createHash("sha256").update(body).digest("hex");
+            const lease = await requestUpload(dataDir, { vaultRef: ref, ciphertextSha256: digest, bytes: body.length });
+            await putCiphertext(lease, body);
+            await completeUpload(dataDir, lease.lease_id, body.length);
+            return { checksum: digest };
+        },
+        async headObject(key) {
+            return statCiphertext(dataDir, managedRefForKey(key));
+        },
+        async getObject(key) {
+            return (await pullCiphertext(dataDir, managedRefForKey(key))).ciphertext;
+        },
+        async deleteObject(key) {
+            try {
+                await deleteCloudArchive(dataDir, managedRefForKey(key));
+            }
+            catch (error) {
+                if (isVaultlineError(error) && (error.code === "archive_not_found" || /returned 404|not[ _-]?found/i.test(error.message)))
+                    return;
+                throw error;
+            }
+        }
+    };
+}

package/dist/src/mcp-install.d.ts

@@ -0,0 +1,52 @@
+import { execFile } from "node:child_process";
+import { type SetupAgentId } from "./adapters.js";
+declare const run: typeof execFile.__promisify__;
+/**
+ * Registering Sealkeep's MCP server with the agents on this machine.
+ *
+ * Archiving sessions and being able to *ask about* them are different products,
+ * and only the first one was wired. `src/mcp.ts` has always exposed
+ * `vaultline_search` and `vaultline_recover`, but nothing installed it and
+ * nothing told an agent it existed — a door with no sign on it. This is the
+ * sign.
+ *
+ * What is deliberately NOT here: any claim that an agent can reach archives it
+ * does not hold locally. The MCP server searches this machine's index. A
+ * cloud-wide memory needs server-side metadata search, which does not exist
+ * yet, and promising it here would be the kind of false claim this file was
+ * written to stop.
+ */
+export type McpInstallResult = {
+    agents: {
+        agent: SetupAgentId;
+        label: string;
+        installed: boolean;
+        detail: string;
+        fragmentPath?: string;
+    }[];
+};
+/** What every agent needs to start the server, in one place so the copies cannot drift. */
+export declare function mcpServerSpec(dataDir: string, executable?: string): {
+    command: string;
+    args: string[];
+    env: {
+        VAULTLINE_DATA_DIR: string;
+    };
+};
+/**
+ * Whether the command we are about to hand another program can actually be run.
+ *
+ * Registering `vaultline` when it is not on PATH — a checkout, an npx run, a
+ * shell whose PATH the agent does not inherit — writes a server the agent
+ * reports as "Failed to connect: ENOENT" forever, while this command claims
+ * success. Reporting a registration that cannot start is the same false claim
+ * as an archive that was never verified, and it is caught the same way: prove
+ * it before saying it.
+ */
+export declare function executableResolves(executable?: string, exec?: typeof execFile.__promisify__): Promise<boolean>;
+export declare function installMcpServer(dataDir: string, options?: {
+    only?: string;
+    exec?: typeof run;
+    home?: string;
+}): Promise<McpInstallResult>;
+export {};

package/dist/src/mcp-install.js

@@ -0,0 +1,140 @@
+import { execFile } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+import { detectSetupAgents } from "./adapters.js";
+const run = promisify(execFile);
+/** What every agent needs to start the server, in one place so the copies cannot drift. */
+export function mcpServerSpec(dataDir, executable = "vaultline") {
+    return {
+        command: executable,
+        args: ["mcp"],
+        env: { VAULTLINE_DATA_DIR: dataDir }
+    };
+}
+/**
+ * Whether the command we are about to hand another program can actually be run.
+ *
+ * Registering `vaultline` when it is not on PATH — a checkout, an npx run, a
+ * shell whose PATH the agent does not inherit — writes a server the agent
+ * reports as "Failed to connect: ENOENT" forever, while this command claims
+ * success. Reporting a registration that cannot start is the same false claim
+ * as an archive that was never verified, and it is caught the same way: prove
+ * it before saying it.
+ */
+export async function executableResolves(executable = "vaultline", exec = run) {
+    try {
+        await exec(process.platform === "win32" ? "where" : "which", [executable]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Claude Code owns its own config file, so it is asked rather than edited.
+ *
+ * Writing ~/.claude.json directly is what produced a registration the Spala
+ * installer then refused as foreign — the client normalises what it stores, so
+ * a hand-written entry never matches what the client would have written.
+ */
+async function installForClaude(dataDir, exec = run) {
+    const spec = mcpServerSpec(dataDir);
+    try {
+        await exec("claude", [
+            "mcp", "add", "--transport", "stdio", "--scope", "user", "vaultline",
+            "--env", `VAULTLINE_DATA_DIR=${dataDir}`,
+            "--", spec.command, ...spec.args
+        ]);
+        return { installed: true, detail: "registered with Claude Code — ask it to search your sessions" };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "could not run the claude CLI";
+        if (/already exists/i.test(message))
+            return { installed: true, detail: "already registered with Claude Code" };
+        return { installed: false, detail: `could not register: ${message.split("\n")[0]}` };
+    }
+}
+/**
+ * Codex configures itself in TOML. This still ships no TOML *parser* — but it
+ * does not need one to APPEND safely: a `[mcp_servers.vaultline]` table at the
+ * end of the file is a new top-level table, valid TOML regardless of what
+ * precedes it, as long as that section does not already exist. So the rule is:
+ * config file present and section absent → back it up, append, registered;
+ * anything else → the reviewable fragment, exactly as before. The backup makes
+ * the edit as reversible as never having made it.
+ */
+async function installForCodex(dataDir, home) {
+    const spec = mcpServerSpec(dataDir);
+    const fragmentPath = join(dataDir, "integrations", "codex-mcp.toml");
+    const table = [
+        "[mcp_servers.vaultline]",
+        `command = ${JSON.stringify(spec.command)}`,
+        `args = ${JSON.stringify(spec.args)}`,
+        "",
+        "[mcp_servers.vaultline.env]",
+        `VAULTLINE_DATA_DIR = ${JSON.stringify(dataDir)}`,
+        ""
+    ].join("\n");
+    await mkdir(dirname(fragmentPath), { recursive: true });
+    await writeFile(fragmentPath, `# Merge into ~/.codex/config.toml to let Codex search your archived sessions.\n${table}`, { mode: 0o600 });
+    const configPath = join(home ?? homedir(), ".codex", "config.toml");
+    const current = await readFile(configPath, "utf8").catch(() => null);
+    if (current === null) {
+        return { installed: false, detail: `Codex has no config.toml yet — merge this once it exists: ${fragmentPath}`, fragmentPath };
+    }
+    if (current.includes("[mcp_servers.vaultline]")) {
+        return { installed: true, detail: "already registered in ~/.codex/config.toml", fragmentPath };
+    }
+    const backupPath = `${configPath}.vaultline-backup-${Date.now()}`;
+    await writeFile(backupPath, current, { mode: 0o600 });
+    await writeFile(configPath, `${current}${current.endsWith("\n") ? "" : "\n"}\n${table}`, { mode: 0o600 });
+    return { installed: true, detail: `registered in ~/.codex/config.toml (backup kept beside it)`, fragmentPath, backupPath };
+}
+export async function installMcpServer(dataDir, options = {}) {
+    const detected = await detectSetupAgents(options.home);
+    const agents = [];
+    /**
+     * Checked once, and it gates *writing into another program's config* — not
+     * writing a fragment into our own data directory.
+     *
+     * A registration that cannot start is worse than none: the agent shows a
+     * permanent connection error and the person has no idea Sealkeep put it
+     * there. A fragment is inert until someone merges it deliberately, so
+     * withholding it would only remove information.
+     */
+    const runnable = await executableResolves("vaultline", options.exec);
+    const notOnPath = "`vaultline` is not on PATH, so the server could not start. Install it globally (npm i -g vaultline) and run this again.";
+    for (const found of detected) {
+        if (!found.detected)
+            continue;
+        if (options.only && options.only !== found.agent)
+            continue;
+        if (found.agent === "claude") {
+            agents.push(runnable
+                ? { agent: found.agent, label: found.label, ...(await installForClaude(dataDir, options.exec)) }
+                : { agent: found.agent, label: found.label, installed: false, detail: `not registered — ${notOnPath}` });
+        }
+        else if (found.agent === "codex") {
+            // A registration that cannot start is worse than none (same rule as
+            // Claude): only a runnable `vaultline` earns the config append; without
+            // it the fragment is written and the advice says why.
+            const fragment = runnable
+                ? await installForCodex(dataDir, options.home)
+                : await installForCodex(dataDir, "/nonexistent-home-so-only-the-fragment-is-written");
+            agents.push({ ...fragment, agent: found.agent, label: found.label,
+                detail: runnable ? fragment.detail : `not registered — ${notOnPath}`, installed: runnable ? fragment.installed : false });
+        }
+        else {
+            // Detected, but Sealkeep has no adapter for its sessions, so an MCP
+            // server pointed at this vault would answer questions about history it
+            // never captured. Saying nothing is better than answering wrongly.
+            agents.push({
+                agent: found.agent, label: found.label, installed: false,
+                detail: "not registered — Sealkeep does not archive this agent's sessions yet, so it would have nothing to search"
+            });
+        }
+    }
+    return { agents };
+}

package/dist/src/mcp.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/mcp.js

@@ -0,0 +1,59 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { archiveFile, defaultDataDir, listArchives, previewRetention, vaultStatus } from "./vault.js";
+import { restoreArchive } from "./restore.js";
+import { providers } from "./control-plane.js";
+const dataDir = process.env.VAULTLINE_DATA_DIR ?? defaultDataDir();
+const phrase = process.env.VAULTLINE_RECOVERY_PHRASE;
+const server = new McpServer({ name: "vaultline", version: "0.1.0" });
+function text(value) { return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] }; }
+function requirePhrase() { if (!phrase)
+    throw new Error("VAULTLINE_RECOVERY_PHRASE is required for archive and recovery actions"); return phrase; }
+server.registerTool("vaultline_status", {
+    title: "Sealkeep status",
+    description: "Read local Sealkeep health, archive count, and encrypted storage usage. No session content is returned.",
+    inputSchema: {}
+}, async () => text(await vaultStatus(dataDir)));
+server.registerTool("vaultline_search", {
+    title: "Search archived sessions",
+    description: "Searches local encrypted archive metadata. It returns identifiers and source metadata, never decrypts transcript contents.",
+    inputSchema: { query: z.string().min(1).max(200), agent: z.string().optional() }
+}, async ({ query, agent }) => {
+    const normalized = query.toLowerCase();
+    const matches = (await listArchives(dataDir)).filter((item) => (!agent || item.source.agent === agent) && `${item.id} ${item.source.path} ${item.source.agent}`.toLowerCase().includes(normalized));
+    return text(matches.map(({ id, createdAt, source }) => ({ id, createdAt, agent: source.agent, path: source.path, bytes: source.bytes })));
+});
+server.registerTool("vaultline_prepare_archive", {
+    title: "Archive a session",
+    description: "Encrypts and queues a local transcript for archive. The transcript is encrypted before it reaches any storage provider.",
+    inputSchema: { path: z.string().min(1), agent: z.string().default("custom") },
+    annotations: { destructiveHint: false }
+}, async ({ path, agent }) => text(await archiveFile(dataDir, path, requirePhrase(), agent)));
+server.registerTool("vaultline_recover", {
+    title: "Recover an archived session",
+    description: "Decrypts one selected archive into a destination path on this device. This is a local action. It refuses to overwrite an existing file unless the caller explicitly chooses backup or replace.",
+    inputSchema: {
+        archiveId: z.string().uuid(),
+        destination: z.string().min(1).optional(),
+        native: z.boolean().default(false).describe("Restore to the adapter's original transcript path instead of a chosen destination"),
+        overwrite: z.enum(["refuse", "backup", "replace"]).default("refuse")
+    },
+    annotations: { destructiveHint: true }
+}, async ({ archiveId, destination, native, overwrite }) => {
+    const outcome = await restoreArchive(dataDir, archiveId, requirePhrase(), { destination, native, overwrite });
+    return text({ archiveId: outcome.record.id, output: outcome.output, bytes: outcome.bytes, native: outcome.native, backupPath: outcome.backupPath });
+});
+server.registerTool("vaultline_create_upload", {
+    title: "Get upload lease status",
+    description: "Reports the storage lease mechanism used by Sealkeep. In the local MVP provider, no remote URL is necessary; the future hosted control plane returns a short-lived, object-scoped signed URL.",
+    inputSchema: { provider: z.enum(["vaultline", "s3", "r2", "gcs"]).default("vaultline"), bucket: z.string().min(1), prefix: z.string().min(1), ciphertextSha256: z.string().regex(/^[a-f0-9]{64}$/), bytes: z.number().int().positive() }
+}, async ({ provider, bucket, prefix, ciphertextSha256, bytes }) => text(providers[provider].createUploadLease({ provider: provider, bucket, prefix }, { ciphertextSha256, bytes })));
+server.registerTool("vaultline_retention_preview", {
+    title: "Preview local session reclamation",
+    description: "Lists old source transcripts that could eventually be reclaimed. This is read-only and always preserves sources until a verified remote archive exists.",
+    inputSchema: { olderThanDays: z.number().min(0).default(30) },
+    annotations: { readOnlyHint: true }
+}, async ({ olderThanDays }) => text(await previewRetention(dataDir, olderThanDays)));
+const transport = new StdioServerTransport();
+server.connect(transport).catch((error) => { console.error(error); process.exit(1); });

package/dist/src/migrate.d.ts

@@ -0,0 +1,35 @@
+export type MigrationOutcome = {
+    id: string;
+    from: 1 | 2;
+    to: 2;
+    migrated: boolean;
+};
+/**
+ * Re-encrypts one v1 archive into the v2 envelope, keeping its archive id.
+ *
+ * The replacement object is written beside the original and decrypted back before
+ * anything is replaced, so a failure at any point leaves the readable v1 archive
+ * exactly as it was.
+ */
+export declare function migrateArchive(dataDir: string, id: string, rawPhrase: string): Promise<MigrationOutcome>;
+export declare function migrateVault(dataDir: string, phrase: string): Promise<{
+    total: number;
+    migrated: number;
+    alreadyCurrent: number;
+    outcomes: MigrationOutcome[];
+}>;
+/**
+ * Rewraps every v2 archive for the vault's current recipient set. This is how a
+ * removed device loses access: the archive key is re-wrapped without it, and no
+ * ciphertext is rewritten.
+ */
+export declare function rewrapVault(dataDir: string, rawPhrase: string, options?: {
+    group?: string;
+}): Promise<{
+    rewrapped: number;
+    skipped: {
+        id: string;
+        reason: string;
+    }[];
+    recipients: number;
+}>;

package/dist/src/migrate.js

@@ -0,0 +1,88 @@
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { decryptArchive as openEnvelope, encryptArchive as sealEnvelope, rewrapArchive } from "../packages/vaultline-crypto/src/index.js";
+import { equalHex, matchesPhraseCheck, sha256 } from "./crypto.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { fail } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { isV2 } from "./types.js";
+import { ADAPTER_VERSION, configuredRecipients, decryptRecord, listArchives, readConfig, writeRecord } from "./vault.js";
+/**
+ * Re-encrypts one v1 archive into the v2 envelope, keeping its archive id.
+ *
+ * The replacement object is written beside the original and decrypted back before
+ * anything is replaced, so a failure at any point leaves the readable v1 archive
+ * exactly as it was.
+ */
+export async function migrateArchive(dataDir, id, rawPhrase) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const config = await readConfig(dataDir);
+    const records = await listArchives(dataDir);
+    const record = records.find((item) => item.id === id);
+    if (!record)
+        fail("archive_not_found", `Archive not found: ${id}`, { archiveId: id });
+    if (isV2(record))
+        return { id, from: 2, to: 2, migrated: false };
+    const { plaintext } = await decryptRecord(dataDir, id, phrase);
+    // Match what vault.ts writes, so a migrated archive is shaped like a fresh one.
+    const { envelope, ciphertext } = sealEnvelope(plaintext, { recipients: configuredRecipients(config, phrase), archiveId: id, createdAt: record.createdAt, compression: "gzip", adapter: { agent: record.source.agent, version: ADAPTER_VERSION } });
+    const staged = `${record.objectPath}.v2-${randomUUID()}`;
+    try {
+        await writeFile(staged, ciphertext, { mode: 0o600 });
+        const verified = openEnvelope(envelope, await readFile(staged), { phrase });
+        if (!equalHex(sha256(verified), record.source.sha256))
+            fail("plaintext_integrity_failed", `Migrated archive ${id} did not reproduce the original bytes`, { archiveId: id });
+        const next = {
+            version: 2, id, createdAt: record.createdAt, source: record.source,
+            cipher: { algorithm: envelope.suite, ciphertextSha256: sha256(ciphertext), storedBytes: ciphertext.length, chunks: envelope.chunks.length },
+            envelope, objectPath: record.objectPath
+        };
+        await rename(staged, record.objectPath);
+        await writeRecord(config.storage.root, next);
+        await recordAudit(dataDir, "archive.migrate", "allowed", { archiveId: id, from: 1, to: 2 });
+        return { id, from: 1, to: 2, migrated: true };
+    }
+    catch (error) {
+        await rm(staged, { force: true });
+        throw error;
+    }
+}
+export async function migrateVault(dataDir, phrase) {
+    const records = await listArchives(dataDir);
+    const outcomes = [];
+    for (const record of records)
+        outcomes.push(await migrateArchive(dataDir, record.id, phrase));
+    return { total: records.length, migrated: outcomes.filter((outcome) => outcome.migrated).length, alreadyCurrent: outcomes.filter((outcome) => !outcome.migrated).length, outcomes };
+}
+/**
+ * Rewraps every v2 archive for the vault's current recipient set. This is how a
+ * removed device loses access: the archive key is re-wrapped without it, and no
+ * ciphertext is rewritten.
+ */
+export async function rewrapVault(dataDir, rawPhrase, options = {}) {
+    const phrase = canonicalPhrase(rawPhrase);
+    const config = await readConfig(dataDir);
+    // A plain vault has no envelopes to rewrap: its archives are readable files
+    // by the owner's choice at setup. Without this refusal the loop below threw
+    // an untyped error on the first record's missing envelope.
+    if (config.storageMode === "plain") {
+        fail("invalid_argument", "This vault stores archives unencrypted, so there are no keys to rewrap. Recipients only apply to sealed vaults.");
+    }
+    if (!matchesPhraseCheck(config.recovery.phraseCheck, phrase))
+        fail("recovery_phrase_mismatch", "Recovery phrase does not match this vault");
+    const recipients = configuredRecipients(config, phrase, options.group);
+    const records = await listArchives(dataDir);
+    const rewrapped = [];
+    const skipped = [];
+    for (const record of records) {
+        if (!isV2(record)) {
+            skipped.push({ id: record.id, reason: "v1 archive; run `sealkeep migrate` first" });
+            continue;
+        }
+        const envelope = rewrapArchive(record.envelope, { phrase }, recipients);
+        await writeRecord(config.storage.root, { ...record, envelope });
+        rewrapped.push(record.id);
+    }
+    await recordAudit(dataDir, "archive.rewrap", "allowed", { rewrapped: rewrapped.length, skipped: skipped.length, recipients: recipients.length, group: options.group ?? null });
+    return { rewrapped: rewrapped.length, skipped, recipients: recipients.length };
+}

package/dist/src/mnemonic.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Transcribable recovery phrases, in the format the rest of the world already
+ * uses.
+ *
+ * A recovery phrase is written on paper by a person under stress, months before
+ * it matters, and typed back on a different machine. Base64 fails all three
+ * tests. Words do not: they survive bad handwriting, they can be read aloud,
+ * and a checksum catches the transcription mistakes people actually make.
+ *
+ * This used to be a bespoke 256-word list, which worked but left the phrase
+ * marooned in one program. BIP-39 is the same idea with an installed base:
+ * hardware wallets, steel backup plates, password managers and phone apps all
+ * know how to hold these words, and people who have done this before recognise
+ * them on sight. Twenty-four words carry 256 bits of entropy; twelve carry 128
+ * and are accepted for people who want a shorter thing to write down.
+ *
+ * What this does *not* mean is that a wallet can open an archive. A wallet is
+ * somewhere to keep the words, not a second key: Sealkeep still derives its
+ * key from the phrase with scrypt and a per-vault salt, which is deliberately
+ * slower and better salted than BIP-39's own seed derivation. Anyone claiming
+ * otherwise is selling something.
+ *
+ * The list is frozen by the specification and verified by test rather than
+ * trusted, because one altered word would produce phrases no other tool reads.
+ */
+export declare const WORDS: readonly string[];
+/** 256 bits, so twenty-four words. Twelve-word phrases are read but not issued. */
+export declare const ENTROPY_BYTES = 32;
+export declare const PHRASE_WORDS = 24;
+/** Normalizes what a person actually types: stray case, punctuation, and runs of spaces. */
+export declare function normalize(phrase: string): string[];
+export declare function entropyToPhrase(entropy: Buffer): string;
+export declare function generateRecoveryPhrase(): string;
+/** Words within one edit of the given word, so a typo gets a suggestion rather than a shrug. */
+export declare function suggestions(word: string, limit?: number): string[];
+export type PhraseCheck = {
+    valid: boolean;
+    words: string[];
+    problems: string[];
+};
+/**
+ * Explains exactly what is wrong with a phrase, because "invalid" is useless to
+ * someone holding a piece of paper. Unknown words get spelling suggestions; a
+ * checksum failure means a word is in the wrong place or was misread.
+ */
+export declare function inspectPhrase(phrase: string): PhraseCheck;
+/** True when a phrase is one this build generated. Older free-text phrases return false. */
+export declare function isMnemonic(phrase: string): boolean;
+/**
+ * The form a phrase takes before any key is derived from it.
+ *
+ * People read words off paper and type them back with different capitalisation and
+ * spacing. Deriving a key from the raw string would reject a correct phrase for
+ * cosmetic reasons — the worst possible failure for a recovery flow. A recognised
+ * word phrase is therefore reduced to canonical lowercase, single-spaced form.
+ *
+ * Anything that is not a valid word phrase passes through untouched, because vaults
+ * created before the word list hold arbitrary text whose exact bytes are the secret.
+ */
+export declare function canonicalPhrase(phrase: string): string;