sealkeep 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 Notable changes, by published version. Sealkeep is pre-1.0: minor versions
 may change behavior, and say so here when they do.
 
+## 0.9.0 — 2026-08-20
+
+**Share a project, not the vault.** Until now a registered key opened everything
+the vault ever sealed, so sharing with a colleague meant handing over every
+session on the machine. A recipient can be tied to one project now:
+
+```sh
+sealkeep projects                                  # the names this vault knows
+sealkeep recipients add --label "Dana" --public-key <key> --project checkout
+sealkeep rewrap --project checkout                 # let them read what came before
+sealkeep space members checkout                    # who is in, and who sees everything
+```
+
+Dana opens that project's sessions with `sealkeep recover <id> --key dana.key`
+and is refused everything else. The company key added without `--project` still
+opens every project, and the phrase always does.
+
+Two fixes underneath: the ordinary (non-streamed) seal path had never learned
+about projects, so `archive --project` wrapped nobody; and `rewrap --project`
+now skips other projects instead of quietly adding or dropping people there.
+
+## 0.8.1 — 2026-08-20
+
+- **`sealkeep recover --key`** — open an archive with a registered recipient's
+  private key, no recovery phrase involved. This is how an organisation reads
+  what someone who has left sealed: register the company key once
+  (`sealkeep recipients add --public-key …`), and every archive sealed after
+  that is wrapped for it. Existing archives are brought in with
+  `sealkeep rewrap`. A key that was never a recipient opens nothing.
+
 ## 0.8.0 — 2026-08-20
 
 Fixes from a review of the screens that had never had one, and a test suite

package/dist/src/cli.js

@@ -203,11 +203,12 @@ function usage() {
             ["list", "browse archives"],
             ["search <query>", "search metadata, or contents with --content"],
             ["projects", "the project names this vault knows — the ones routing rules pin"],
+            ["space members [project]", "who can open a project, and who can open everything"],
             ["index build", "build the local content index that --content searches"],
             ["index status", "what is searchable and what is not yet indexed"],
             ["storage targets", "several storages at once, with limits, pins, and priority"],
             ["mcp install", "let your agents search this history themselves"],
-            ["recover <id> <dest>", "restore original bytes; --native puts it back where it came from"],
+            ["recover <id> <dest>", "restore original bytes; --native puts it back where it came from, --key opens it as a registered recipient"],
             ["recover <session-file>", "agent says a session file is missing? name it and it goes back where resume expects it"],
             ["tui", "the same view in the terminal"]
         ]),
@@ -866,7 +867,7 @@ async function main() {
                 if (routed.provider === "gdrive") {
                     const { archiveFile } = await import("./vault.js");
                     const { uploadArchive } = await import("./upload.js");
-                    const record = await archiveFile(dataDir, source, phraseForSeal, agentName);
+                    const record = await archiveFile(dataDir, source, phraseForSeal, agentName, { project });
                     const uploaded = await uploadArchive(dataDir, record.id, {
                         remoteStorage: { provider: "gdrive", bucket: routed.bucket ?? "gdrive", prefix: routed.prefix ?? "vaultline", region: routed.region },
                         targetId: routed.id
@@ -898,7 +899,10 @@ async function main() {
             print(`    ${dim(`${bytes(outcome.storedBytes)} sealed and verified in the bucket; this disk held at most ${bytes(outcome.heldAtMostBytes)} of it at any moment`)}`);
             return;
         }
-        const record = await archiveFile(dataDir, source, phraseForSeal, take(args, "--agent", "custom"));
+        // A project named here decides which members are wrapped in, so an
+        // archive shared with a colleague is the one they were actually given.
+        const localProject = take(args, "--project") ?? null;
+        const record = await archiveFile(dataDir, source, phraseForSeal, take(args, "--agent", "custom"), { project: localProject });
         if (json) {
             print(JSON.stringify({ id: record.id, bytes: record.source.bytes, objectPath: record.objectPath, deduplicated: record.deduplicated }, null, 2));
             return;
@@ -1004,6 +1008,37 @@ async function main() {
         print(dim("\n  On a package we run the storage and choose the provider. Your own bucket means\n  your provider, your region, your bill. Either way we hold no key that opens an archive.\n"));
         return;
     }
+    if (command === "space") {
+        // The everyday question a shared folder answers: who is in this, and what
+        // can they reach. Membership here is a set of key wraps, so "who is in" is
+        // answerable exactly — a member either is in the envelopes or is not.
+        const [action, name] = positionals(args);
+        const config = await readConfig(dataDir);
+        const members = (config.recipients ?? []);
+        if (action === "members" || action === undefined) {
+            const scoped = name ? members.filter((m) => m.project === name) : members;
+            const vaultWide = members.filter((m) => !m.project);
+            if (json) {
+                print(JSON.stringify({ project: name ?? null, members: scoped, vaultWide: name ? vaultWide : undefined }, null, 2));
+                return;
+            }
+            print(`\n${heading(name ? `Members of ${name}` : "Everyone who can open this vault")}`);
+            print(`  ${green("always")}  ${dim("your recovery phrase")}`);
+            print(table(scoped, [
+                { header: "member", get: (m) => m.label },
+                { header: "scope", get: (m) => (m.project ? m.project : dim("whole vault")) },
+                { header: "added", get: (m) => relativeTime(m.addedAt) },
+                { header: "id", get: (m) => dim(m.id.slice(0, 8)) }
+            ], name ? `nobody has been added to ${name} yet` : "no keys besides the phrase"));
+            if (name && vaultWide.length > 0) {
+                print(`\n  ${dim(`${vaultWide.length} key${vaultWide.length === 1 ? "" : "s"} can open every project, including this one: ${vaultWide.map((m) => m.label).join(", ")}`)}`);
+            }
+            print(`\n  ${hint(`${cmd("sealkeep recipients add --label \"name\" --public-key <key> --project <project>")} adds a member`)}`);
+            print(`  ${hint(`${cmd("sealkeep recipients remove <id>")} then ${cmd("sealkeep rewrap --project <project>")} removes one`)}\n`);
+            return;
+        }
+        fail("invalid_argument", "Usage: sealkeep space members [project]");
+    }
     if (command === "projects") {
         // Routing rules can pin a project to a destination, and the panel cannot
         // offer a list: project names never reach the cloud — that is the point.
@@ -1117,9 +1152,21 @@ async function main() {
             if (!json)
                 print(`  ${dim(`Matched ${newest.source.path} → archive ${newest.id}${native ? " · restoring to its original location" : ""}`)}`);
         }
-        const outcome = await restoreArchive(dataDir, id, required(await unlock(dataDir, take(args, "--recovery-phrase")), "--recovery-phrase is required"), {
+        // A recipient key is the other way in: an archive wrapped for a registered
+        // key opens with that key and no phrase, which is how an organisation reads
+        // what a departed colleague sealed. Accepts the base64 the keygen printed,
+        // or a path to a file holding it.
+        const keyArg = take(args, "--key");
+        const privateKey = keyArg
+            ? (await readFile(keyArg, "utf8").then((text) => text.trim()).catch(() => keyArg.trim()))
+            : undefined;
+        const secret = privateKey
+            ? ""
+            : required(await unlock(dataDir, take(args, "--recovery-phrase")), "--recovery-phrase is required (or pass --key with a recipient's private key)");
+        const outcome = await restoreArchive(dataDir, id, secret, {
             destination: native ? undefined : required(destination, "Destination is required unless --native is used"),
-            native, home: take(args, "--home"), overwrite: take(args, "--overwrite", "refuse")
+            native, home: take(args, "--home"), overwrite: take(args, "--overwrite", "refuse"),
+            ...(privateKey ? { privateKey } : {})
         });
         if (json) {
             print(JSON.stringify({ id, output: outcome.output, bytes: outcome.bytes, native: outcome.native, backupPath: outcome.backupPath }, null, 2));
@@ -1640,7 +1687,7 @@ async function main() {
     }
     if (command === "rewrap") {
         const phrase = required(await unlock(dataDir, take(args, "--recovery-phrase")), "--recovery-phrase is required (or set SEALKEEP_RECOVERY_PHRASE)");
-        const result = await rewrapVault(dataDir, phrase, { group: take(args, "--group") });
+        const result = await rewrapVault(dataDir, phrase, { group: take(args, "--group"), project: take(args, "--project") });
         if (json) {
             print(JSON.stringify(result, null, 2));
             return;
@@ -1670,13 +1717,23 @@ async function main() {
             return;
         }
         if (action === "add") {
-            const config = await addRecipient(dataDir, required(take(args, "--label"), "--label is required"), required(take(args, "--public-key"), "--public-key is required (base64 X25519)"), take(args, "--group"));
+            const project = take(args, "--project");
+            const config = await addRecipient(dataDir, required(take(args, "--label"), "--label is required"), required(take(args, "--public-key"), "--public-key is required (base64 X25519)"), take(args, "--group"), project);
             if (json) {
                 print(JSON.stringify(config.recipients, null, 2));
                 return;
             }
-            print(`  ${mark.ok()} Added. New archives include it.`);
-            print(`  ${hint(`${cmd("sealkeep rewrap")} extends access to archives you already have`)}`);
+            if (project) {
+                // Say what they can reach, because the whole point of the flag is that
+                // it is less than everything.
+                print(`  ${mark.ok()} Added to ${bold(project)}. New archives of that project include it; nothing else this vault seals does.`);
+                print(`  ${hint(`${cmd(`sealkeep rewrap --project ${project}`)} extends it to that project's existing archives`)}`);
+                print(`  ${hint(`${cmd("sealkeep projects")} lists the names this vault actually knows`)}`);
+            }
+            else {
+                print(`  ${mark.ok()} Added. New archives include it — every project.`);
+                print(`  ${hint(`${cmd("sealkeep rewrap")} extends access to archives you already have`)}`);
+            }
             return;
         }
         if (action === "remove") {

package/dist/src/migrate.d.ts

@@ -25,6 +25,7 @@ export declare function migrateVault(dataDir: string, phrase: string): Promise<{
  */
 export declare function rewrapVault(dataDir: string, rawPhrase: string, options?: {
     group?: string;
+    project?: string;
 }): Promise<{
     rewrapped: number;
     skipped: {

package/dist/src/migrate.js

@@ -70,15 +70,37 @@ export async function rewrapVault(dataDir, rawPhrase, options = {}) {
     }
     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 recipients = configuredRecipients(config, phrase, { group: options.group, project: options.project });
     const records = await listArchives(dataDir);
     const rewrapped = [];
     const skipped = [];
+    // Extending a project's membership must not touch archives of other
+    // projects: rewrapping those would either add the member (leaking work they
+    // were never given) or drop them (silently revoking elsewhere).
+    const projectOf = options.project
+        ? await (async () => {
+            const { claudeProjectFromPath, codexProjectFromRollout } = await import("./adapters.js");
+            return async (record) => {
+                try {
+                    if (record.source.agent === "claude")
+                        return claudeProjectFromPath(record.source.path).project;
+                    if (record.source.agent === "codex")
+                        return (await codexProjectFromRollout(record.source.path, record.createdAt)).project;
+                }
+                catch { /* unreadable project is not a match */ }
+                return null;
+            };
+        })()
+        : null;
     for (const record of records) {
         if (!isV2(record)) {
             skipped.push({ id: record.id, reason: "v1 archive; run `sealkeep migrate` first" });
             continue;
         }
+        if (projectOf && await projectOf(record) !== options.project) {
+            skipped.push({ id: record.id, reason: `belongs to another project` });
+            continue;
+        }
         const envelope = rewrapArchive(record.envelope, { phrase }, recipients);
         await writeRecord(config.storage.root, { ...record, envelope });
         rewrapped.push(record.id);

package/dist/src/restore.d.ts

@@ -31,4 +31,6 @@ export declare function nativeRestoreTarget(record: ArchiveRecord, home?: string
  * is refused by default; `backup` preserves it beside the restored copy and
  * `replace` is the only policy that discards it.
  */
-export declare function restoreArchive(dataDir: string, id: string, phrase: string, options?: RestoreOptions): Promise<RestoreOutcome>;
+export declare function restoreArchive(dataDir: string, id: string, phrase: string, options?: RestoreOptions & {
+    privateKey?: string;
+}): Promise<RestoreOutcome>;

package/dist/src/restore.js

@@ -42,6 +42,10 @@ export function nativeRestoreTarget(record, home = homedir()) {
  * `replace` is the only policy that discards it.
  */
 export async function restoreArchive(dataDir, id, phrase, options = {}) {
+    // A recipient key opens an archive it was wrapped for, without the phrase.
+    // That is how an organisation reads what someone who has left sealed, and
+    // how a project member reads a project they were added to.
+    const key = options.privateKey;
     const record = await findArchive(dataDir, id);
     const native = options.native === true;
     if (native && options.destination)
@@ -58,13 +62,16 @@ export async function restoreArchive(dataDir, id, phrase, options = {}) {
     // decrypts: a wrong phrase must not leave a directory or a partial file
     // behind. The config decides what "proved" means — unwrapping for a sealed
     // vault, the identity check for a plain one.
-    assertPhraseOpens(await readConfig(dataDir), record, phrase);
+    // The phrase check proves the PHRASE opens this vault; a key holder has no
+    // phrase and the wrap itself is the proof, so the unwrap below is the gate.
+    if (!key)
+        assertPhraseOpens(await readConfig(dataDir), record, phrase);
     await mkdir(dirname(output), { recursive: true });
     const temp = join(dirname(output), `.${basename(output)}.${randomUUID()}.partial`);
     let backupPath;
     let bytes;
     try {
-        ({ bytes } = await restoreRecordToFile(dataDir, record, phrase, temp));
+        ({ bytes } = await restoreRecordToFile(dataDir, record, key ? { privateKey: key } : phrase, temp));
         if (existing && policy === "backup") {
             backupPath = `${output}.vaultline-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
             await rename(output, backupPath);

package/dist/src/vault.d.ts

@@ -104,6 +104,8 @@ export declare function archiveFile(dataDir: string, sourcePath: string, rawPhra
     onProgress?: (bytesRead: number) => void;
     delta?: boolean;
     chunkBytes?: number;
+    /** Which project this session belongs to — decides which members are wrapped in. */
+    project?: string | null;
 }): Promise<ArchiveResult>;
 /**
  * The recovery phrase always gets a recipient, so a recovery kit alone can restore.
@@ -118,7 +120,15 @@ export declare function listArchives(dataDir: string): Promise<ArchiveRecord[]>;
  * 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 declare function addRecipient(dataDir: string, label: string, publicKeyBase64: string, group?: string): Promise<VaultConfig>;
+export declare function addRecipient(dataDir: string, label: string, publicKeyBase64: string, group?: string, 
+/**
+ * Tie this key to one project and it becomes a member of that project only:
+ * wrapped into that project's archives, and into nothing else this vault
+ * seals. A colleague on `checkout-rewrite` never receives the rest of your
+ * work, which is the difference between sharing a folder and handing over a
+ * drive.
+ */
+project?: string): Promise<VaultConfig>;
 /** Removes a recipient from future archives. Run `sealkeep rewrap` to revoke it on existing ones. */
 export declare function removeRecipient(dataDir: string, id: string): Promise<VaultConfig>;
 /** Persists a full config document after validation by the caller. */
@@ -164,7 +174,17 @@ export declare function assertPhraseOpens(config: VaultConfig, record: ArchiveRe
  * rejection can leave bytes behind. `restoreArchive` renames a temporary into
  * place for exactly this reason.
  */
-export declare function restoreRecordToFile(dataDir: string, record: ArchiveRecord, rawPhrase: string, destination: string, 
+export declare function restoreRecordToFile(dataDir: string, record: ArchiveRecord, 
+/**
+ * The phrase, or a recipient's private key. A key is how an organisation
+ * opens what an employee sealed: the archive was wrapped for that key when
+ * it was sealed (or by a later rewrap), and the phrase never has to be
+ * shared for it to work. Until this existed, a registered recipient could be
+ * wrapped in and still had no way to decrypt anything.
+ */
+rawPhrase: string | {
+    privateKey: string;
+}, destination: string, 
 /** Injectable so the offloaded-archive path can be proved without a bucket. */
 options?: {
     client?: import("./offload.js").FetchClient;

package/dist/src/vault.js

@@ -6,7 +6,7 @@ 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 { decryptArchive as openEnvelope, hashFilePrefixes, hashFileRange, keyRecipientId, openArchiveToFile, sealArchiveToFile, unwrapArchiveKey, x25519PublicKeyFromRaw, x25519PrivateKeyFromRaw, zeroize } from "../packages/vaultline-crypto/src/index.js";
 import { fail, VaultlineError } from "./errors.js";
 import { recordAudit } from "./audit.js";
 import { isV2 } from "./types.js";
@@ -321,7 +321,8 @@ export async function archiveFile(dataDir, sourcePath, rawPhrase, agent = "custo
         // 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",
+        // Members of this project are wrapped in; members of other projects are not.
+        recipients: configuredRecipients(config, phrase, { project: hooks.project ?? undefined }), archiveId: id, compression: "gzip-chunk",
         adapter: { agent, version: ADAPTER_VERSION }, scratchDir: config.storage.root,
         ...(chunkBytes ? { chunkBytes } : {}),
         ...(hooks.onProgress ? { onProgress: hooks.onProgress } : {})
@@ -374,7 +375,7 @@ async function sealDeltaArchive(dataDir, config, absolute, agent, phrase, size,
     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",
+        recipients: configuredRecipients(config, phrase, { project: hooks.project ?? undefined }), archiveId: id, compression: "gzip-chunk",
         adapter: { agent, version: ADAPTER_VERSION }, scratchDir: config.storage.root,
         ...(hooks.onProgress ? { onProgress: hooks.onProgress } : {})
     }).catch((error) => {
@@ -445,7 +446,15 @@ export async function listArchives(dataDir) {
  * 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) {
+export async function addRecipient(dataDir, label, publicKeyBase64, group, 
+/**
+ * Tie this key to one project and it becomes a member of that project only:
+ * wrapped into that project's archives, and into nothing else this vault
+ * seals. A colleague on `checkout-rewrite` never receives the rest of your
+ * work, which is the difference between sharing a folder and handing over a
+ * drive.
+ */
+project) {
     if (!label.trim())
         fail("invalid_argument", "A recipient label is required");
     const raw = Buffer.from(publicKeyBase64, "base64");
@@ -454,10 +463,10 @@ export async function addRecipient(dataDir, label, publicKeyBase64, group) {
     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 } : {}) });
+    recipients.push({ id, label: label.trim(), publicKey: raw.toString("base64"), addedAt: new Date().toISOString(), ...(group ? { group } : {}), ...(project ? { project } : {}) });
     const next = { ...config, recipients };
     await writeJson(configPath(dataDir), next);
-    await recordAudit(dataDir, "recipient.add", "allowed", { recipientId: id, label: label.trim(), group: group ?? null });
+    await recordAudit(dataDir, "recipient.add", "allowed", { recipientId: id, label: label.trim(), group: group ?? null, project: project ?? null });
     return next;
 }
 /** Removes a recipient from future archives. Run `sealkeep rewrap` to revoke it on existing ones. */
@@ -556,16 +565,38 @@ function openFailure(archiveId, error) {
  * rejection can leave bytes behind. `restoreArchive` renames a temporary into
  * place for exactly this reason.
  */
-export async function restoreRecordToFile(dataDir, record, rawPhrase, destination, 
+export async function restoreRecordToFile(dataDir, record, 
+/**
+ * The phrase, or a recipient's private key. A key is how an organisation
+ * opens what an employee sealed: the archive was wrapped for that key when
+ * it was sealed (or by a later rewrap), and the phrase never has to be
+ * shared for it to work. Until this existed, a registered recipient could be
+ * wrapped in and still had no way to decrypt anything.
+ */
+rawPhrase, destination, 
 /** Injectable so the offloaded-archive path can be proved without a bucket. */
 options = {}) {
-    const phrase = canonicalPhrase(rawPhrase);
+    const withKey = typeof rawPhrase === "object";
+    const phrase = withKey ? "" : canonicalPhrase(rawPhrase);
+    // The keygen prints the raw 32 bytes as base64; the crypto wants a key object
+    // (its string form is PEM). Accept either, so someone can paste what they
+    // were given rather than convert it themselves.
+    const unlock = withKey
+        ? { privateKey: /BEGIN [A-Z ]*PRIVATE KEY/.test(rawPhrase.privateKey)
+                ? rawPhrase.privateKey
+                : x25519PrivateKeyFromRaw(Buffer.from(rawPhrase.privateKey, "base64")) }
+        : { phrase };
     const config = await readConfig(dataDir);
+    if (withKey && (config.storageMode === "plain" || !isV2(record))) {
+        fail("invalid_argument", "A recipient key opens sealed v2 archives. This one predates them, or the vault stores archives unencrypted.");
+    }
     // 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)) {
+        if (withKey)
+            fail("invalid_argument", "This archive is an append onto an earlier one, and the chain is opened with the phrase. Restore it with --recovery-phrase.");
         const { bytes } = await restoreDeltaChainToFile(dataDir, record, phrase, destination, options);
         return { bytes };
     }
@@ -591,7 +622,7 @@ options = {}) {
             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 });
+            opened = await openArchiveToFile(record.envelope, source.path, destination, unlock);
         }
         catch (error) {
             throw openFailure(record.id, error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sealkeep",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Sealkeep by SPALA AI \u2014 your AI coding-agent history, sealed, searchable, and shared across your machines.",
   "license": "SEE LICENSE IN LICENSE",