@safekb/mcp 0.2.0 → 0.3.0

package/README.md

@@ -53,6 +53,8 @@ Claude Desktop and Cursor (`mcpServers` in their MCP config file):
 | `--configure` | | Choose where new sealed keys are kept. Writes `stores.json` next to the token file. |
 | `--sidecar` | | Run the sidecar in this terminal. With `--confirm` it asks before every release of a secret. |
 | `--sidecar-socket <path>` | `SAFEKB_SIDECAR_SOCKET` | The sidecar's socket. Default `sidecar.sock` next to the token file. |
+| `--export-keys <file>` | | Write every sealed key this machine keeps to a new passphrase-protected file. See [Moving keys to another machine](#moving-keys-to-another-machine). |
+| `--import-keys <file>` | | Read such a file and keep its keys on this machine. |
 | | `SAFEKB_SEALED_IDLE_TTL` | Seconds an unlocked seal root may stay idle. Default 900. `unlock_sealed` can set it per root with `idle_ttl_seconds` (60 to 3600). |
 | | `SAFEKB_HOSTED_TIMEOUT` | Seconds a hosted tool call may take. Default 300. |
 
@@ -107,9 +109,11 @@ a terminal of its own:
 npx -y @safekb/mcp --sidecar
 ```
 
-- `add <root id> [minutes]` asks for the root's secret without showing it and holds it for that long
+- `add <name or id> [minutes]` asks for the root's secret without showing it and holds it for that long
   (default 15 minutes). The time is fixed when you type the secret: use does not extend it.
-- `list`, `drop <root id>`, `drop all`, `quit`.
+- `list`, `drop <name or id>`, `drop all`, `quit`.
+- A seal root can be named by its name instead of its id (`add Tax papers`), see
+  [Names of seal roots](#names-of-seal-roots).
 - A new seal root with `store: "sidecar"` makes the sidecar ask you for a new passphrase, twice, while
   the tool call waits.
 - With `--confirm` it asks for your approval before every release of a secret.
@@ -118,6 +122,41 @@ Several roots can be held at once, each with its own passphrase and time. The si
 socket only your user can open; it is not available on Windows. Any program running as you can still
 ask it for a held secret, which is what `--confirm` is for.
 
+### Names of seal roots
+
+The server cannot read the name of a sealed folder, and an id like `6acdb031893533e0ae1f5456` is no
+name to type. So the client remembers the name of every seal root it creates or unlocks, in
+`roots.json` next to the token file (mode 0600), and follows a rename or a delete. The sidecar and
+the key export show a root as `"Tax papers" (6acd…)` and take the name wherever they take an id.
+
+- The names are in plaintext in that file: readable on this machine by programs running as you,
+  never by the server. Delete the file to forget them; they come back as roots are unlocked.
+- A name is never put into a tool result or an error, so unlocking a root does not tell the model
+  what it is called.
+- When two roots have the same name, the name stands for neither: use the id.
+
+### Moving keys to another machine
+
+A generated key lives only where it was made: in the system keyring or in a key file. To carry all of
+them to another machine, or to back them up:
+
+```sh
+npx -y @safekb/mcp --export-keys keys.safekb   # on the machine that has the keys
+npx -y @safekb/mcp --import-keys keys.safekb   # on the other machine, after --authorize there
+```
+
+- Export asks for a passphrase (typed twice, not shown; 12 or more characters are recommended, a
+  shorter one is pointed out and taken) and writes one file
+  with every key of the system keyring and of the key file directory, and the names of their roots.
+  The content is encrypted with AES-256-GCM under a key derived from the passphrase with Argon2id.
+  Without the passphrase the file opens for nobody.
+- Import asks for that passphrase and keeps the keys in the store `--configure` chose on that
+  machine. A key the machine already keeps is left as it is, so an import can be repeated.
+- Both need a terminal: the passphrase is never an argument, so it is in no shell history, no process
+  list and no conversation.
+- A root that is opened by a passphrase has no key on any machine. There is nothing to export: type
+  the passphrase at the other machine's sidecar.
+
 ## Sealed credentials
 
 A sealed credential belongs to a seal root. Its password, TOTP seed, `sealed_notes` and the values of

package/dist/safekb-mcp.js

@@ -2358,7 +2358,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // package.json
 var package_default = {
   name: "@safekb/mcp",
-  version: "0.2.0",
+  version: "0.3.0",
   description: "SafeKB local MCP client: proxies the hosted SafeKB tools and adds zero-knowledge sealed documents.",
   license: "SEE LICENSE IN LICENSE",
   author: "Mustafa Öztürk",
@@ -6524,6 +6524,8 @@ Usage:
   safekb-mcp --authorize --url <api url> [--config <path>]
   safekb-mcp --configure [--config <path>]
   safekb-mcp --sidecar [--confirm] [--config <path>]
+  safekb-mcp --export-keys <file> [--config <path>] [--keyring <dir>]
+  safekb-mcp --import-keys <file> [--config <path>] [--keyring <dir>]
 
 Options:
   --url <api url>    SafeKB API base URL. Also: KB_API_URL. Otherwise the URL saved by --authorize.
@@ -6539,6 +6541,10 @@ Options:
   --sidecar          Hold seal root secrets you type, in memory only and for a limited time, and
                      hand them to the client. Runs in its own terminal.
   --confirm          With --sidecar: ask before every release of a secret.
+  --export-keys <file>  Write every sealed key this machine keeps (system keyring and key files) to
+                     a new file, encrypted under a passphrase you type. Needs a terminal.
+  --import-keys <file>  Read such a file and keep its keys in the store chosen by --configure. A
+                     key this machine already keeps is left as it is. Needs a terminal.
   --sidecar-socket <path>  The sidecar's socket. Also: SAFEKB_SIDECAR_SOCKET. Default: sidecar.sock
                      next to the token file.
   --version, --help
@@ -6562,12 +6568,19 @@ function secondsAsMs(env, name, defaultSeconds) {
   }
   return Number(raw) * 1000;
 }
+var EXCLUSIVE_MODES = [
+  "authorize",
+  "configure",
+  "sidecar",
+  "export-keys",
+  "import-keys"
+];
 function mode(flags) {
   if (flags.help)
     return "help";
   if (flags.version)
     return "version";
-  const chosen = ["authorize", "configure", "sidecar"].filter((name) => flags[name] === true);
+  const chosen = EXCLUSIVE_MODES.filter((name) => flags[name] !== undefined);
   if (chosen.length > 1) {
     throw new StartupError(`Pass only one of ${chosen.map((name) => `--${name}`).join(", ")}`);
   }
@@ -6589,6 +6602,7 @@ ${USAGE}`);
     configPath: nonEmpty(values.config) ?? nonEmpty(env.SAFEKB_MCP_CONFIG) ?? defaultTokenConfigPath(),
     keyringDir: nonEmpty(values.keyring) ?? nonEmpty(env.SAFEKB_SEALED_KEYRING),
     sidecarSocket: nonEmpty(values["sidecar-socket"]) ?? nonEmpty(env.SAFEKB_SIDECAR_SOCKET),
+    transferFile: nonEmpty(values["export-keys"]) ?? nonEmpty(values["import-keys"]),
     confirm: values.confirm === true,
     sealedOnly: values["sealed-only"] === true,
     idleTtlMs: secondsAsMs(env, "SAFEKB_SEALED_IDLE_TTL", DEFAULT_IDLE_TTL_SECONDS),
@@ -6610,12 +6624,110 @@ function parse(argv) {
       sidecar: { type: "boolean" },
       confirm: { type: "boolean" },
       "sidecar-socket": { type: "string" },
+      "export-keys": { type: "string" },
+      "import-keys": { type: "string" },
       help: { type: "boolean" },
       version: { type: "boolean" }
     }
   });
 }
 
+// src/rootNames.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { dirname as dirname2, join as join4 } from "node:path";
+var ROOT_NAMES_FILE = "roots.json";
+var ROOT_NAMES_VERSION = 1;
+var OBJECT_ID = /^[0-9a-f]{24}$/;
+function rootNamesPath(tokenConfigPath) {
+  return join4(dirname2(tokenConfigPath), ROOT_NAMES_FILE);
+}
+function assertNames(value, path) {
+  const raw = value;
+  const names = raw?.names;
+  if (raw?.v !== ROOT_NAMES_VERSION || typeof names !== "object" || names === null || Array.isArray(names) || !Object.entries(names).every(([id, name]) => OBJECT_ID.test(id) && typeof name === "string" && name.length > 0)) {
+    throw new ClientError(`Seal root names ${path} are malformed`);
+  }
+  return new Map(Object.entries(names));
+}
+
+class RootNames {
+  path;
+  changes = Promise.resolve();
+  constructor(path) {
+    this.path = path;
+  }
+  async all() {
+    if (!existsSync2(this.path))
+      return new Map;
+    const text = await readPrivateFile(this.path, "Seal root names");
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new ClientError(`Seal root names ${this.path} are not valid JSON`);
+    }
+    return assertNames(parsed, this.path);
+  }
+  async nameOf(rootId) {
+    return (await this.all()).get(rootId) ?? null;
+  }
+  async describe(rootId) {
+    const name = await this.nameOf(rootId);
+    return name === null ? rootId : `"${name}" (${rootId})`;
+  }
+  remember(rootId, name) {
+    if (name.length === 0)
+      return this.forget(rootId);
+    return this.change(async () => {
+      const names = await this.all();
+      if (names.get(rootId) === name)
+        return;
+      names.set(rootId, name);
+      await this.save(names);
+    });
+  }
+  forget(rootId) {
+    return this.change(async () => {
+      const names = await this.all();
+      if (names.delete(rootId))
+        await this.save(names);
+    });
+  }
+  change(apply) {
+    const done = this.changes.then(apply);
+    this.changes = done.catch(() => {});
+    return done;
+  }
+  async follow(done, change) {
+    try {
+      await change();
+    } catch (error) {
+      throw new ClientError(`${done}, but its name could not be updated on this machine: ${error.message}`);
+    }
+  }
+  async isName(reference) {
+    return [...(await this.all()).values()].includes(reference);
+  }
+  async resolve(reference) {
+    if (OBJECT_ID.test(reference))
+      return reference;
+    const ids = [...await this.all()].filter(([, name]) => name === reference).map(([id]) => id);
+    const [first, ...others] = ids;
+    if (first === undefined) {
+      throw new ClientError(`No seal root is known as "${reference}"; use its id`);
+    }
+    if (others.length > 0) {
+      throw new ClientError(`${ids.length} seal roots are named "${reference}" (${ids.join(", ")}); use the id`);
+    }
+    return first;
+  }
+  save(names) {
+    const sorted = Object.fromEntries([...names].sort(([a], [b]) => a.localeCompare(b)));
+    return writePrivateFile(this.path, `${JSON.stringify({ v: ROOT_NAMES_VERSION, names: sorted }, null, 2)}
+`);
+  }
+}
+
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -6823,12 +6935,12 @@ class SealedSession {
 import { connect } from "node:net";
 
 // src/sidecar/protocol.ts
-import { dirname as dirname2, join as join4 } from "node:path";
+import { dirname as dirname3, join as join5 } from "node:path";
 var SIDECAR_PROTOCOL_VERSION = 1;
 var SIDECAR_SOCKET_NAME = "sidecar.sock";
 var SIDECAR_SUPPORTED = process.platform !== "win32";
 function defaultSidecarSocket(configPath) {
-  return join4(dirname2(configPath), SIDECAR_SOCKET_NAME);
+  return join5(dirname3(configPath), SIDECAR_SOCKET_NAME);
 }
 
 // src/sidecar/client.ts
@@ -6887,17 +6999,79 @@ class SidecarClient {
   }
 }
 
+// src/sidecar/lineReader.ts
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+
+class Echo extends Writable {
+  muted = false;
+  target;
+  constructor(target) {
+    super();
+    this.target = target;
+  }
+  _write(chunk, _encoding, done) {
+    if (!this.muted)
+      this.target.write(chunk);
+    done();
+  }
+}
+
+class TerminalReader {
+  echo;
+  lines;
+  output;
+  constructor(input, output) {
+    this.output = output;
+    this.echo = new Echo(output);
+    this.lines = createInterface({
+      input,
+      output: this.echo,
+      terminal: true,
+      historySize: 0
+    });
+  }
+  async read(prompt, options = {}) {
+    const { hidden = false, signal } = options;
+    if (!hidden)
+      return this.lines.question(prompt, { signal });
+    this.output.write(prompt);
+    this.echo.muted = true;
+    try {
+      return await this.lines.question("", { signal });
+    } finally {
+      this.echo.muted = false;
+      this.output.write(`
+`);
+    }
+  }
+  hasTyped() {
+    return this.lines.line.length > 0;
+  }
+  write(text) {
+    this.output.write(text);
+  }
+  onLeave(listener) {
+    this.lines.once("SIGINT", listener);
+    this.lines.once("close", listener);
+  }
+  close() {
+    this.lines.close();
+  }
+}
+
 // src/sidecar/console.ts
 var DEFAULT_HOLD_MINUTES = 15;
 var MS_PER_MINUTE = 60000;
-var OBJECT_ID = /^[0-9a-f]{24}$/;
 var WHOLE_MINUTES = /^[1-9][0-9]*$/;
+var TRAILING_MINUTES = /^(.*\S)\s+([1-9][0-9]*)$/s;
 var COMMAND_PROMPT = "safekb-sidecar> ";
 var HELP = `Commands:
-  add <root id> [minutes]   Type the secret of a seal root; it is held for the given minutes (default ${DEFAULT_HOLD_MINUTES}).
-  list                      Seal roots held and the time left.
-  drop <root id> | all      Forget secrets now.
-  quit                      Forget everything and stop.
+  add <name or id> [minutes]   Type the secret of a seal root; it is held for the given minutes (default ${DEFAULT_HOLD_MINUTES}).
+  list                         Seal roots held and the time left.
+  drop <name or id> | all      Forget secrets now.
+  quit                         Forget everything and stop.
+A seal root is named by its id or by its name, once this machine has created or unlocked it.
 `;
 var UNPRINTABLE = /[\p{Cc}\p{Cf}]/gu;
 function printable2(text) {
@@ -6910,12 +7084,14 @@ function minutesLeft(remainingMs) {
 class SidecarConsole {
   reader;
   holder;
+  names;
   turns = Promise.resolve();
   waiting = 0;
   emptyPrompt = null;
-  constructor(reader, holder) {
+  constructor(reader, holder, names) {
     this.reader = reader;
     this.holder = holder;
+    this.names = names;
   }
   async run() {
     while (!await this.inTurn(() => this.commandTurn())) {}
@@ -6936,7 +7112,7 @@ The MCP client asks for a new passphrase for seal root ${rootId} ("${printable2(
     return this.inTurn(async () => {
       signal.throwIfAborted();
       const answer = await this.reader.read(`
-Release the secret of seal root ${rootId} to the MCP client? [y/N] `, { signal });
+Release the secret of seal root ${await this.shown(rootId)} to the MCP client? [y/N] `, { signal });
       return answer.trim().toLowerCase() === "y";
     });
   }
@@ -6971,18 +7147,18 @@ Release the secret of seal root ${rootId} to the MCP client? [y/N] `, { signal }
     }
   }
   async execute(line) {
-    const [command = "", ...args] = line.split(/\s+/);
+    const [, command = "", rest = ""] = /^(\S*)\s*(.*)$/s.exec(line) ?? [];
     switch (command) {
       case "":
         return false;
       case "add":
-        await this.add(args);
+        await this.reportingMistakes(() => this.add(rest));
         return false;
       case "list":
-        this.list();
+        await this.list();
         return false;
       case "drop":
-        this.drop(args);
+        await this.reportingMistakes(() => this.drop(rest));
         return false;
       case "quit":
       case "exit":
@@ -6992,14 +7168,37 @@ Release the secret of seal root ${rootId} to the MCP client? [y/N] `, { signal }
         return false;
     }
   }
-  async add(args) {
-    const [rootId = "", minutes = String(DEFAULT_HOLD_MINUTES)] = args;
-    if (!OBJECT_ID.test(rootId) || !WHOLE_MINUTES.test(minutes)) {
-      this.reader.write(`Usage: add <root id> [minutes]
+  async reportingMistakes(command) {
+    try {
+      await command();
+    } catch (error) {
+      if (!(error instanceof ClientError))
+        throw error;
+      this.reader.write(`${printable2(error.message)}
+`);
+    }
+  }
+  async shown(rootId) {
+    return printable2(await this.names.describe(rootId));
+  }
+  async addTarget(typed) {
+    const [, before, minutes] = TRAILING_MINUTES.exec(typed) ?? [];
+    if (before !== undefined && minutes !== undefined && !await this.names.isName(typed)) {
+      return { rootId: await this.names.resolve(before), minutes };
+    }
+    return {
+      rootId: await this.names.resolve(typed),
+      minutes: String(DEFAULT_HOLD_MINUTES)
+    };
+  }
+  async add(typed) {
+    if (typed.length === 0) {
+      this.reader.write(`Usage: add <name or id> [minutes]
 `);
       return;
     }
-    const secret2 = await this.reader.read(`Secret of seal root ${rootId} (not shown): `, { hidden: true });
+    const { rootId, minutes } = await this.addTarget(typed);
+    const secret2 = await this.reader.read(`Secret of seal root ${await this.shown(rootId)} (not shown): `, { hidden: true });
     if (secret2.length === 0) {
       this.reader.write(`Nothing entered; nothing is held.
 `);
@@ -7009,7 +7208,7 @@ Release the secret of seal root ${rootId} to the MCP client? [y/N] `, { signal }
     this.reader.write(`Held for ${minutes} minute(s).
 `);
   }
-  list() {
+  async list() {
     const held = this.holder.summary();
     if (held.length === 0) {
       this.reader.write(`Nothing is held.
@@ -7018,24 +7217,23 @@ Release the secret of seal root ${rootId} to the MCP client? [y/N] `, { signal }
     }
     for (const { rootId, secrets, remainingMs } of held) {
       const unconfirmed = secrets > 1 ? `, ${secrets} secrets (a change is unconfirmed)` : "";
-      this.reader.write(`${rootId}  ${minutesLeft(remainingMs)} minute(s) left${unconfirmed}
+      this.reader.write(`${await this.shown(rootId)}  ${minutesLeft(remainingMs)} minute(s) left${unconfirmed}
 `);
     }
   }
-  drop(args) {
-    const [target = ""] = args;
+  async drop(target) {
     if (target === "all") {
       this.holder.dropAll();
       this.reader.write(`Everything is forgotten.
 `);
       return;
     }
-    if (!OBJECT_ID.test(target)) {
-      this.reader.write(`Usage: drop <root id> | all
+    if (target.length === 0) {
+      this.reader.write(`Usage: drop <name or id> | all
 `);
       return;
     }
-    const dropped = this.holder.dropRoot(target);
+    const dropped = this.holder.dropRoot(await this.names.resolve(target));
     this.reader.write(dropped === 0 ? `Nothing was held for it.
 ` : `Forgotten.
 `);
@@ -7145,67 +7343,6 @@ class SecretHolder {
   }
 }
 
-// src/sidecar/lineReader.ts
-import { createInterface } from "node:readline/promises";
-import { Writable } from "node:stream";
-
-class Echo extends Writable {
-  muted = false;
-  target;
-  constructor(target) {
-    super();
-    this.target = target;
-  }
-  _write(chunk, _encoding, done) {
-    if (!this.muted)
-      this.target.write(chunk);
-    done();
-  }
-}
-
-class TerminalReader {
-  echo;
-  lines;
-  output;
-  constructor(input, output) {
-    this.output = output;
-    this.echo = new Echo(output);
-    this.lines = createInterface({
-      input,
-      output: this.echo,
-      terminal: true,
-      historySize: 0
-    });
-  }
-  async read(prompt, options = {}) {
-    const { hidden = false, signal } = options;
-    if (!hidden)
-      return this.lines.question(prompt, { signal });
-    this.output.write(prompt);
-    this.echo.muted = true;
-    try {
-      return await this.lines.question("", { signal });
-    } finally {
-      this.echo.muted = false;
-      this.output.write(`
-`);
-    }
-  }
-  hasTyped() {
-    return this.lines.line.length > 0;
-  }
-  write(text) {
-    this.output.write(text);
-  }
-  onLeave(listener) {
-    this.lines.once("SIGINT", listener);
-    this.lines.once("close", listener);
-  }
-  close() {
-    this.lines.close();
-  }
-}
-
 // src/sidecar/server.ts
 import { chmod, lstat, rm as rm2 } from "node:fs/promises";
 import { connect as connect2, createServer as createServer3 } from "node:net";
@@ -7399,7 +7536,7 @@ Socket: ${settings.socketPath}
 ${approval}
 ${HELP}`;
 }
-async function runSidecar(settings) {
+async function runSidecar(settings, names) {
   if (!SIDECAR_SUPPORTED) {
     throw new StartupError("The sidecar is not available on Windows");
   }
@@ -7408,7 +7545,7 @@ async function runSidecar(settings) {
   }
   const holder = new SecretHolder;
   const reader = new TerminalReader(process.stdin, process.stdout);
-  const terminal = new SidecarConsole(reader, holder);
+  const terminal = new SidecarConsole(reader, holder, names);
   const server = new SidecarServer(holder, terminal, settings);
   try {
     await server.listen();
@@ -7445,8 +7582,8 @@ import { mkdir as mkdir2 } from "node:fs/promises";
 import { createInterface as createInterface2 } from "node:readline/promises";
 
 // src/stores/storeConfig.ts
-import { existsSync as existsSync2 } from "node:fs";
-import { dirname as dirname3, join as join5 } from "node:path";
+import { existsSync as existsSync3 } from "node:fs";
+import { dirname as dirname4, join as join6 } from "node:path";
 
 // src/stores/secretStore.ts
 var KEY_STORE_NAMES = ["system", "file"];
@@ -7459,10 +7596,10 @@ function passphraseNote(seal2) {
 var STORE_CONFIG_NAME = "stores.json";
 var DEFAULT_KEY_DIR_NAME = "keys";
 function storeConfigPath(tokenConfigPath) {
-  return join5(dirname3(tokenConfigPath), STORE_CONFIG_NAME);
+  return join6(dirname4(tokenConfigPath), STORE_CONFIG_NAME);
 }
 function defaultKeyDir(tokenConfigPath) {
-  return join5(dirname3(tokenConfigPath), DEFAULT_KEY_DIR_NAME);
+  return join6(dirname4(tokenConfigPath), DEFAULT_KEY_DIR_NAME);
 }
 function assertStoreConfig(value, path) {
   const raw = value;
@@ -7480,7 +7617,7 @@ function assertStoreConfig(value, path) {
 }
 async function loadStoreConfig(tokenConfigPath) {
   const path = storeConfigPath(tokenConfigPath);
-  if (!existsSync2(path))
+  if (!existsSync3(path))
     return null;
   let text;
   try {
@@ -7563,7 +7700,7 @@ async function agreeToKeyFiles(request) {
 
 // src/stores/fileKeyStore.ts
 import { mkdir as mkdir3, unlink } from "node:fs/promises";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 var PRIVATE_DIR_MODE3 = 448;
 
 class FileKeyStore {
@@ -7600,8 +7737,11 @@ class FileKeyStore {
       note: `Outdated key file for seal root ${seal2.rootId}: ${forRoot.map(({ path }) => path).join(", ")} (the root's key was changed)`
     };
   }
+  async all() {
+    return (await this.keyring.load()).map(({ file }) => file);
+  }
   locationOf(file) {
-    return join6(this.keyring.dir, `${file.root_id}-${file.kid}.json`);
+    return join7(this.keyring.dir, `${file.root_id}-${file.kid}.json`);
   }
   async save(file) {
     await mkdir3(this.keyring.dir, { recursive: true, mode: PRIVATE_DIR_MODE3 });
@@ -7617,6 +7757,7 @@ import { randomBytes as randomBytes4 } from "node:crypto";
 
 // src/stores/systemKeyStore.ts
 var SYSTEM_KEYRING_SERVICE = "safekb-sealed";
+var KEY_ACCOUNT = /^([^/]+)\/([0-9a-f]{24})\/([0-9a-f]{16})$/;
 function accountOf(tenant, rootId, kid) {
   return `${tenant}/${rootId}/${kid}`;
 }
@@ -7642,6 +7783,32 @@ class SystemKeyStore {
       note: `the system keyring has no current key for seal root ${seal2.rootId}`
     } : { secrets: [key], note: "" };
   }
+  async all() {
+    const files = [];
+    for (const { account, secret: secret2 } of await this.keyring.list()) {
+      const [, tenant, rootId, kid] = KEY_ACCOUNT.exec(account) ?? [];
+      if (tenant === undefined)
+        continue;
+      files.push(this.keyFileOf(account, { tenant, rootId, kid }, secret2));
+    }
+    return files;
+  }
+  keyFileOf(account, id, key) {
+    try {
+      return assertKeyFile({
+        v: KEY_FILE_VERSION,
+        kind: KEY_FILE_KIND,
+        tenant_id: id.tenant,
+        root_id: id.rootId,
+        kid: id.kid,
+        key
+      });
+    } catch (error) {
+      if (!(error instanceof FormatError))
+        throw error;
+      throw new ClientError(`The system keyring entry ${SYSTEM_KEYRING_SERVICE} / ${account} holds no sealed key: ${error.message}`);
+    }
+  }
   locationOf(file) {
     return `system keyring entry ${SYSTEM_KEYRING_SERVICE} / ${accountOf(file.tenant_id, file.root_id, file.kid)}`;
   }
@@ -7695,6 +7862,18 @@ class OsKeyring {
       throw unavailable(error);
     }
   }
+  async list() {
+    try {
+      const { findCredentialsAsync } = await import("@napi-rs/keyring");
+      const found = await findCredentialsAsync(this.service);
+      return found.map(({ account, password }) => ({
+        account,
+        secret: password
+      }));
+    } catch (error) {
+      throw unavailable(error);
+    }
+  }
   async entry(account) {
     try {
       const { AsyncEntry } = await import("@napi-rs/keyring");
@@ -7768,6 +7947,10 @@ class SecretStores {
     }
     return this.require(defaultKeyStore);
   }
+  keyStores() {
+    const { system, file } = this.set;
+    return [system, file].filter((store) => store !== null);
+  }
   sidecar() {
     return this.require("sidecar");
   }
@@ -7898,10 +8081,12 @@ class NodeAccess {
     throw new ClientError(`Sealed node ${node.id} has no wrapped key`);
   }
   async open(nodeId) {
-    const node = await this.ctx.api.getNode(nodeId);
+    return this.openNode(await this.ctx.api.getNode(nodeId));
+  }
+  async openNode(node) {
     const root = this.ctx.session.require(node.seal_root_id);
     const dek = await this.dekOf(node);
-    const meta = await decryptMeta(dek, this.nodeContext(nodeId), parseEnvelope(node.enc_meta));
+    const meta = await decryptMeta(dek, this.nodeContext(node.id), parseEnvelope(node.enc_meta));
     return { node, root, dek, meta };
   }
   async sign(message, signerRootIds) {
@@ -8268,6 +8453,7 @@ class CreateService {
       id,
       placement: await this.placement(args.space_id, args.parent_id),
       isFolder: false,
+      title: args.title,
       dek,
       encMeta: fields2.encMeta,
       encBody: fields2.encBody,
@@ -8287,6 +8473,7 @@ class CreateService {
       id,
       placement: await this.placement(args.space_id, args.parent_id),
       isFolder: true,
+      title: args.name,
       dek,
       encMeta: await sealMeta(dek, this.access.nodeContext(id), meta),
       encBody: null,
@@ -8346,22 +8533,24 @@ class CreateService {
     const sealed = await createSealRoot(ctx, secret2.secret, PASSPHRASE_KDF);
     const encDek = serializeEnvelope(await wrapDek(sealed.keys, node.id, node.dek));
     this.ctx.session.unlock(sealed.keys, sealed.seal.kid);
+    let created;
     try {
       const signers = outerRoot === null ? [node.id] : [node.id, outerRoot];
       const request = await this.signedCreate(node, node.id, encDek, sealed.sealJson, signers);
-      const created = await keeping(secret2, () => this.ctx.api.create(request)).catch((error) => {
+      created = await keeping(secret2, () => this.ctx.api.create(request)).catch((error) => {
         throw unconfirmedRoot(error, node.id, secret2);
       });
-      return {
-        ...writeResult(created),
-        new_seal_root: true,
-        key_file: secret2.keyFile,
-        secret_store: secret2.store
-      };
     } catch (error) {
       this.ctx.session.lock(node.id);
       throw error;
     }
+    await this.ctx.names.follow(`Seal root ${node.id} was created`, () => this.ctx.names.remember(node.id, node.title));
+    return {
+      ...writeResult(created),
+      new_seal_root: true,
+      key_file: secret2.keyFile,
+      secret_store: secret2.store
+    };
   }
   async signedCreate(node, sealRootId, encDek, seal2, signerRootIds) {
     const { spaceId, parentId } = node.placement;
@@ -9297,7 +9486,13 @@ class DocumentService {
     if (args.summary === undefined !== (args.summary_short === undefined)) {
       throw new ClientError("Pass summary and summary_short together");
     }
-    return open4.node.is_folder ? this.updateFolder(open4, args) : this.updateDocument(open4, args);
+    const result = await (open4.node.is_folder ? this.updateFolder(open4, args) : this.updateDocument(open4, args));
+    const { id } = open4.node;
+    const { title } = args;
+    if (title !== undefined && id === open4.node.seal_root_id) {
+      await this.ctx.names.follow(`Seal root ${id} was renamed`, () => this.ctx.names.remember(id, title));
+    }
+    return result;
   }
   async replace(args) {
     const open4 = await this.access.open(args.document_id);
@@ -9425,22 +9620,30 @@ class RootService {
     }
     const source = await this.readSource(args);
     const { rootId } = source;
-    const seal2 = sealOf(await this.ctx.api.getDocument(rootId));
+    const document = await this.ctx.api.getDocument(rootId);
+    const seal2 = sealOf(document);
     const keys = await this.open({ tenant: this.ctx.tenant, root: rootId }, seal2, await this.secretsFor(source, seal2, args.store));
     const { idleTtlMs } = this.ctx.session.unlock(keys, seal2.kid, args.idle_ttl_seconds === undefined ? undefined : args.idle_ttl_seconds * 1000);
+    const indexedDocuments = await this.readyOrLock(document);
     return {
       root_id: rootId,
       unlocked: true,
       secret_kind: seal2.secret_kind,
       idle_ttl_seconds: idleTtlMs / 1000,
-      indexed_documents: await this.indexOrLock(rootId)
+      indexed_documents: indexedDocuments
     };
   }
-  async indexOrLock(rootId) {
+  async rememberName(root) {
+    const { meta } = await this.access.openNode(toSealedNode(root));
+    await this.ctx.names.remember(root.id, meta.title);
+  }
+  async readyOrLock(root) {
     try {
-      return await this.search.sync(rootId);
+      const indexed = await this.search.sync(root.id);
+      await this.rememberName(root);
+      return indexed;
     } catch (error) {
-      this.ctx.session.lock(rootId);
+      this.ctx.session.lock(root.id);
       throw error;
     }
   }
@@ -9803,6 +10006,9 @@ class TreeService {
   }
   async signedDelete(node) {
     await this.ctx.api.delete(node.id, await this.access.signPlain("delete", node));
+    if (node.id === node.seal_root_id) {
+      await this.ctx.names.follow(`Seal root ${node.id} was deleted`, () => this.ctx.names.forget(node.id));
+    }
   }
   async export(args) {
     const open4 = await this.access.open(args.document_id);
@@ -23660,6 +23866,225 @@ function createSealedTools(ctx) {
   ];
 }
 
+// src/transfer/keyBundle.ts
+var KEY_BUNDLE_KIND = "safekb-key-export";
+var KEY_BUNDLE_VERSION = 1;
+var RECOMMENDED_EXPORT_PASSPHRASE_LENGTH = 12;
+var KEY_INFO = "safekb/key-export/v1";
+var EXPORT_KDF = MIN_KDF_PARAMS;
+var MAX_KDF = { m: 256 * 1024, t: 8, p: 4 };
+var OBJECT_ID3 = /^[0-9a-f]{24}$/;
+function malformed(why) {
+  return new ClientError(`Not a SafeKB key export: ${why}`);
+}
+function aadOf(salt, kdf) {
+  return `${KEY_INFO}|${salt}|${kdf.m}|${kdf.t}|${kdf.p}`;
+}
+async function bundleKey(passphrase, salt, kdf) {
+  return deriveKey(await derivePassphraseIkm(passphrase, salt, kdf), KEY_INFO);
+}
+function assertContent(value) {
+  const raw = value;
+  const names = raw?.names;
+  if (!Array.isArray(raw?.keys) || typeof names !== "object" || names === null || Array.isArray(names) || !Object.entries(names).every(([rootId, name]) => OBJECT_ID3.test(rootId) && typeof name === "string" && name.length > 0)) {
+    throw malformed("its content is not keys and the names of their roots");
+  }
+  return { keys: raw.keys.map(assertKeyFile), names: { ...names } };
+}
+function parseBundle(text) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw malformed("it is not valid JSON");
+  }
+  const raw = value;
+  if (raw?.kind !== KEY_BUNDLE_KIND) {
+    throw malformed(`its kind is not '${KEY_BUNDLE_KIND}'`);
+  }
+  if (raw.v !== KEY_BUNDLE_VERSION) {
+    throw malformed(`its version is not ${KEY_BUNDLE_VERSION}; use the version of @safekb/mcp that wrote it`);
+  }
+  const { kdf, salt } = raw;
+  if (typeof kdf !== "object" || kdf === null || typeof salt !== "string") {
+    throw malformed("it has no KDF parameters and salt");
+  }
+  const params = assertKdfParams(kdf);
+  if (params.m > MAX_KDF.m || params.t > MAX_KDF.t || params.p > MAX_KDF.p) {
+    throw malformed("its KDF parameters are beyond what this client runs");
+  }
+  return {
+    v: raw.v,
+    kind: raw.kind,
+    kdf: params,
+    salt,
+    sealed: assertEnvelope(raw.sealed)
+  };
+}
+async function sealKeyBundle(content, passphrase) {
+  const saltBytes = randomBytes(SALT_BYTES);
+  const salt = toBase64(saltBytes);
+  const bundle = {
+    v: KEY_BUNDLE_VERSION,
+    kind: KEY_BUNDLE_KIND,
+    kdf: { ...EXPORT_KDF },
+    salt,
+    sealed: await sealEnvelope(await bundleKey(passphrase, saltBytes, EXPORT_KDF), utf8Encode(JSON.stringify(assertContent(content))), aadOf(salt, EXPORT_KDF))
+  };
+  return `${JSON.stringify(bundle, null, 2)}
+`;
+}
+async function openKeyBundle(text, passphrase) {
+  const bundle = parseBundle(text);
+  const key = await bundleKey(passphrase, fromBase64(bundle.salt), bundle.kdf);
+  let plaintext;
+  try {
+    plaintext = await openEnvelope(key, bundle.sealed, aadOf(bundle.salt, bundle.kdf));
+  } catch (error48) {
+    if (!(error48 instanceof DecryptionError))
+      throw error48;
+    throw new ClientError("Wrong passphrase, or the export file was changed or damaged");
+  }
+  return assertContent(JSON.parse(utf8Decode(plaintext)));
+}
+
+// src/transfer/console.ts
+var UNPRINTABLE2 = /[\p{Cc}\p{Cf}]/gu;
+var STORE_LABELS = {
+  system: "the system keyring",
+  file: "the key file directory"
+};
+
+class TransferConsole {
+  reader;
+  transfer;
+  names;
+  constructor(reader, transfer, names) {
+    this.reader = reader;
+    this.transfer = transfer;
+    this.names = names;
+  }
+  async export(path) {
+    await this.transfer.exportable();
+    const keys = await this.transfer.export(path, await this.readNewPassphrase());
+    this.reader.write(`Exported ${keys.length} key(s) to ${path}:
+`);
+    await this.writeRoots(keys);
+    this.reader.write(`The file opens only with the passphrase you typed: keep both, and keep them apart.
+` + `A seal root that is opened by a passphrase has no key on this machine and is not in the file.
+`);
+  }
+  async import(path) {
+    const passphrase = await this.reader.read("Passphrase of the export file (not shown): ", { hidden: true });
+    const { imported, store, present } = await this.transfer.import(path, passphrase);
+    if (store !== null) {
+      this.reader.write(`Imported ${imported.length} key(s) into ${STORE_LABELS[store]}:
+`);
+      await this.writeRoots(imported);
+    }
+    if (present.length > 0) {
+      this.reader.write(`${present.length} key(s) were already on this machine and were left as they are:
+`);
+      await this.writeRoots(present);
+    }
+  }
+  async writeRoots(keys) {
+    for (const { root_id } of keys) {
+      const shown = (await this.names.describe(root_id)).replace(UNPRINTABLE2, "");
+      this.reader.write(`  ${shown}
+`);
+    }
+  }
+  async readNewPassphrase() {
+    for (;; ) {
+      const first = await this.reader.read(`Passphrase for the export file (not shown; ${RECOMMENDED_EXPORT_PASSPHRASE_LENGTH} or more characters recommended): `, { hidden: true });
+      if (first.length === 0) {
+        this.reader.write(`Nothing entered.
+`);
+        continue;
+      }
+      if (first.length < RECOMMENDED_EXPORT_PASSPHRASE_LENGTH) {
+        this.reader.write(`Note: shorter than the recommended ${RECOMMENDED_EXPORT_PASSPHRASE_LENGTH} characters; every key in the file is only as safe as this passphrase.
+`);
+      }
+      const second = await this.reader.read("Repeat it: ", { hidden: true });
+      if (first === second)
+        return first;
+      this.reader.write(`The two entries differ.
+`);
+    }
+  }
+}
+
+// src/transfer/keyTransfer.ts
+import { readFile } from "node:fs/promises";
+function idOf(file2) {
+  return `${file2.tenant_id}/${file2.root_id}/${file2.kid}`;
+}
+
+class KeyTransfer {
+  stores;
+  names;
+  constructor(stores, names) {
+    this.stores = stores;
+    this.names = names;
+  }
+  async exportable() {
+    const keys = [...(await this.kept()).values()];
+    if (keys.length === 0) {
+      throw new ClientError("There is no key to export: neither the system keyring nor the key file directory of this client keeps one");
+    }
+    return keys;
+  }
+  async export(path, passphrase) {
+    const keys = await this.exportable();
+    const known = await this.names.all();
+    const names = Object.fromEntries(keys.flatMap(({ root_id }) => {
+      const name = known.get(root_id);
+      return name === undefined ? [] : [[root_id, name]];
+    }));
+    await writeNewPrivateFile(path, await sealKeyBundle({ keys, names }, passphrase));
+    return keys;
+  }
+  async import(path, passphrase) {
+    const text = await readFile(path, "utf8").catch((error48) => {
+      throw fileError(error48);
+    });
+    const { keys, names } = await openKeyBundle(text, passphrase);
+    const kept = await this.kept();
+    const present = keys.filter((file2) => kept.has(idOf(file2)));
+    const imported = keys.filter((file2) => !kept.has(idOf(file2)));
+    const store = await this.saveNew(imported);
+    await this.adoptNames(keys, names);
+    return { imported, store, present };
+  }
+  async saveNew(keys) {
+    if (keys.length === 0)
+      return null;
+    const target = this.stores.keyStore("default");
+    for (const file2 of keys)
+      await target.save(file2);
+    return target.name;
+  }
+  async adoptNames(keys, names) {
+    const known = await this.names.all();
+    for (const { root_id } of keys) {
+      const name = names[root_id];
+      if (name !== undefined && !known.has(root_id)) {
+        await this.names.remember(root_id, name);
+      }
+    }
+  }
+  async kept() {
+    const kept = new Map;
+    for (const store of this.stores.keyStores()) {
+      for (const file2 of await store.all())
+        kept.set(idOf(file2), file2);
+    }
+    return kept;
+  }
+}
+
 // src/main.ts
 var VERSION = package_default.version;
 var IDLE_SWEEP_MS = 30000;
@@ -23674,6 +24099,9 @@ async function openKeyring(dir) {
   }
   return keyring;
 }
+function namesOf(options) {
+  return new RootNames(rootNamesPath(options.configPath));
+}
 function sidecarSocketOf(options) {
   return options.sidecarSocket ?? defaultSidecarSocket(options.configPath);
 }
@@ -23696,16 +24124,55 @@ async function storeConfigOf(options, systemKeyring) {
   await saveStoreConfig(options.configPath, chosen);
   return chosen;
 }
-async function openStores(options, tenant, systemKeyring) {
+async function openKeyStores(options, tenant, systemKeyring) {
   const chosen = await storeConfigOf(options, systemKeyring);
   const keyring = await openKeyring(options.keyringDir ?? chosen?.key_dir ?? null);
-  return new SecretStores({
+  return {
     system: chosen?.system_keyring === true ? new SystemKeyStore(systemKeyring, tenant) : null,
     file: keyring === null ? null : new FileKeyStore(keyring, tenant),
-    sidecar: SIDECAR_SUPPORTED ? new SidecarStore(new SidecarClient(sidecarSocketOf(options)), tenant) : null,
     defaultKeyStore: chosen?.default_store ?? null
+  };
+}
+async function openStores(options, tenant, systemKeyring) {
+  return new SecretStores({
+    ...await openKeyStores(options, tenant, systemKeyring),
+    sidecar: SIDECAR_SUPPORTED ? new SidecarStore(new SidecarClient(sidecarSocketOf(options)), tenant) : null
   });
 }
+async function transferKeys(options, reader, systemKeyring = new OsKeyring) {
+  const flag = `--${options.mode}`;
+  if (options.transferFile === null) {
+    throw new StartupError(`${flag} needs the path of the export file`);
+  }
+  const { tenant_id: tenant } = await loadTokenConfig(options.configPath);
+  const names = namesOf(options);
+  const terminal = new TransferConsole(reader, new KeyTransfer(new SecretStores({
+    ...await openKeyStores(options, tenant, systemKeyring),
+    sidecar: null
+  }), names), names);
+  await (options.mode === "export-keys" ? terminal.export(options.transferFile) : terminal.import(options.transferFile));
+}
+async function transferKeysAtTerminal(options) {
+  if (!process.stdin.isTTY) {
+    throw new StartupError(`--${options.mode} needs a terminal: the passphrase of the export file is typed into it`);
+  }
+  const reader = new TerminalReader(process.stdin, process.stdout);
+  let finished = false;
+  reader.onLeave(() => {
+    if (finished)
+      return;
+    process.stderr.write(`
+safekb-mcp: --${options.mode} was aborted
+`);
+    process.exit(130);
+  });
+  try {
+    await transferKeys(options, reader);
+  } finally {
+    finished = true;
+    reader.close();
+  }
+}
 function apiUrlFor(options, config2) {
   if (options.url === null)
     return config2.url;
@@ -23724,7 +24191,8 @@ async function serve(options, transport, systemKeyring = new OsKeyring) {
     api: new SealedApi(new HttpClient(apiUrl, config2.token)),
     session,
     tenant: config2.tenant_id,
-    stores: await openStores(options, config2.tenant_id, systemKeyring)
+    stores: await openStores(options, config2.tenant_id, systemKeyring),
+    names: namesOf(options)
   });
   const hosted = options.sealedOnly ? null : await HostedProxy.connect({
     apiUrl,
@@ -23790,10 +24258,11 @@ async function main(argv, env) {
     return;
   }
   if (options.mode === "sidecar") {
-    await runSidecar({
-      socketPath: sidecarSocketOf(options),
-      confirm: options.confirm
-    });
+    await runSidecar({ socketPath: sidecarSocketOf(options), confirm: options.confirm }, namesOf(options));
+    return;
+  }
+  if (options.mode === "export-keys" || options.mode === "import-keys") {
+    await transferKeysAtTerminal(options);
     return;
   }
   if (!HAS_POSIX_MODES)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safekb/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SafeKB local MCP client: proxies the hosted SafeKB tools and adds zero-knowledge sealed documents.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Mustafa Öztürk",