sealkeep 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 Notable changes, by published version. Sealkeep is pre-1.0: minor versions
 may change behavior, and say so here when they do.
 
+## 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

@@ -207,7 +207,7 @@ function usage() {
             ["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"]
         ]),
@@ -1117,9 +1117,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));

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

@@ -164,7 +164,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";
@@ -556,16 +556,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 +613,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.8.1",
   "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",