@safekb/mcp 0.4.0 → 0.6.0

package/README.md

@@ -21,8 +21,10 @@ npx -y @safekb/mcp --setup
 ```
 
 This opens the same page, then registers the server with Claude Code for all your projects
-(`claude mcp add --scope user safekb`). What is already done is left as it is, so it can be run again.
-Needs Node 20 or newer.
+(`claude mcp add --scope user safekb -- npx -y @safekb/mcp --mcp`). What is already done is left as it
+is, so it can be run again. A registration that `--setup` of a version before 0.5.0 wrote no longer
+starts the server and is written again with `--mcp` and the arguments it had (see
+[Upgrading to 0.5.0](#upgrading-to-050)). Needs Node 20 or newer.
 
 Over SSH, or anywhere without a browser, the command prints a link instead. Open it on any device, sign
 in and approve; the terminal then shows the account and a code, and you answer `y` when they match what
@@ -31,13 +33,30 @@ your browser shows.
 ### Other MCP clients (Cursor, …)
 
 ```json
-{ "mcpServers": { "safekb": { "command": "npx", "args": ["-y", "@safekb/mcp"] } } }
+{ "mcpServers": { "safekb": { "command": "npx", "args": ["-y", "@safekb/mcp", "--mcp"] } } }
 ```
 
-Started without a token, the client serves one tool, `connect_safekb`, which opens the page and puts
+`--mcp` is what starts the MCP server. Without any argument the command prints its usage text and exits.
+
+Started with `--mcp` but without a token, the client serves one tool, `connect_safekb`, which opens the page and puts
 the SafeKB tools in its place once you have confirmed. `SAFEKB_MCP_NO_BROWSER=1` makes it show the link
 instead of opening a browser.
 
+### Upgrading to 0.5.0
+
+Until 0.4.0 the bare command started the MCP server. From 0.5.0 it prints the usage text, and the
+server is started by `--mcp`. A client configured with `"args": ["-y", "@safekb/mcp"]` therefore gets
+no tools after the upgrade:
+
+- Claude Code: run `npx -y @safekb/mcp --setup` again. What an older `--setup` registered (user scope,
+  `npx -y @safekb/mcp`, with or without `--config`) is registered again with `--mcp`. A registration
+  you made or changed yourself (other arguments, environment entries, local or project scope, a
+  pinned version, the `safekb-mcp` program) is not touched: the command stops and prints the two
+  `claude mcp` commands that add `--mcp` to it. A registration pinned to an exact version below 0.5.0
+  (`@safekb/mcp@0.4.0`) keeps working without `--mcp` and is left as it is.
+- Claude Desktop: install the current `safekb.mcpb`.
+- Other clients: add `"--mcp"` to the `args` in their MCP config.
+
 ### A self-hosted SafeKB
 
 The default server is `https://api.safekb.com`. For another one run
@@ -70,6 +89,7 @@ every tool that keeps a key this way; see [Where secrets are kept](#where-secret
 
 | Flag | Environment | Meaning |
 | --- | --- | --- |
+| `--mcp` | | Start the MCP server on stdio. Modified by `--url`, `--keyring`, `--sealed-only` and `--sidecar-socket`. |
 | `--setup` | | Authorize, choose the key store and register with Claude Code, in one step. Safe to repeat. |
 | `--url <api url>` | `KB_API_URL` | API base URL. Otherwise the URL in the token file, or `https://api.safekb.com` when authorizing. When serving, it must have the origin the token was issued for: the token is never sent anywhere else. |
 | `--config <path>` | `SAFEKB_MCP_CONFIG` | Token file. Default `~/.config/safekb/mcp.json`. Use one per project for per-project access. |
@@ -81,10 +101,23 @@ every tool that keeps a key this way; see [Where secrets are kept](#where-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. |
+| `--list-keys` | | Print the sealed keys this machine keeps and how each stands with the server. See [Managing keys](#managing-keys). |
+| `--create-key <name>` | | Create a sealed folder as a new seal root with a generated key. Needs `--space <space id>`; takes `--store`. |
+| `--rename-key <ref>` | | Rename a seal root to `--name <new name>`. |
+| `--rotate-key <ref>` | | Replace a seal root's secret with a new generated key; takes `--store`. |
+| `--move-key <ref>` | | Move a seal root's current key to `--store system\|file`. |
+| `--delete-key <ref>` | | Remove a seal root's keys from this machine, after a typed confirmation. |
+| `--export <file>` | | Write what this token reaches to a new passphrase-protected file. Takes `--space`, `--doc`, `--compress`, `--skip-locked`. See [Export and import](#export-and-import). |
+| `--import <file>` | | Create what such a file holds in this token's account, as new things. Takes `--into-space`, `--store`. |
 | | `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. |
 | | `SAFEKB_MCP_NO_BROWSER` | Set to anything: never start a browser, only show the authorize link. |
 
+Exactly one mode is given: `--mcp`, `--setup`, `--authorize`, `--configure`, `--sidecar`, `--export`,
+`--import`, or one of the key modes. A flag that only modifies a mode (`--sealed-only`, `--keyring`, …) without one is an error;
+it never starts the server by itself. A flag the given mode does not take is an error too, as is a
+mode without the value or the modifier it needs, and any flag given an empty value.
+
 With a token file, the client refuses to start when that file or a keyring file is readable by group or others,
 when `--url` names another origin than the token's, when the hosted endpoint cannot be reached, or
 when a hosted tool has the name of a sealed tool.
@@ -106,6 +139,14 @@ Its secret is a generated key or a passphrase.
   `update_sealed_document`, `replace_in_sealed_document`, and the move, archive, delete, export,
   attachment and deposit tools.
 - `lock_sealed`, the idle timeout, or the end of the process forget the keys.
+- `change_seal_password` replaces the root's secret. Once the server has taken the new one, the
+  superseded key is removed from the store that kept it (the system keyring, or any key file in the
+  key file directory). A superseded passphrase, or a key file you had written elsewhere with
+  `key_out_path`, is yours to remove.
+- Deleting a seal root (`delete_sealed_document`, or `export_sealed_document` of a standalone sealed
+  document) also removes its keys and its name from this machine.
+- A tool parameter that names a seal root (`root_id`, `new_root_id`) takes its id or its
+  [name](#names-of-seal-roots). Documents and folders inside a root are named by id.
 
 ## Where secrets are kept
 
@@ -155,14 +196,65 @@ ask it for a held secret, which is what `--confirm` is for.
 
 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.
+`roots.json` next to the token file (mode 0600), and follows a rename or a delete. The sidecar, the
+key export and the key modes show a root as `"Tax papers" (6acd…)`, and the name is taken wherever a
+seal root's id is: at the sidecar, in the key modes, and in the `root_id` of the MCP tools.
 
 - 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.
+- The client never puts a name into a tool result, so unlocking a root does not tell the model what
+  it is called. An error repeats only the name the caller passed.
+- A name stays a usable handle: creating or renaming a seal root is refused when the name has the
+  shape of an id (24 hex characters), or when another root known on this machine already has it.
+- Text with the shape of an id always means the root with that id. A root that got such a title
+  elsewhere is not given a name here when it is unlocked or its key is imported: use its id.
+- Two roots can still share a name when both were named elsewhere and then unlocked or imported
+  here. Such a name stands for neither and is refused as ambiguous: use the id. Such a root can
+  still be changed while its name stays the same.
+
+### Managing keys
+
+```sh
+npx -y @safekb/mcp --list-keys
+npx -y @safekb/mcp --create-key "Banking" --space <space id> [--store system|file]
+npx -y @safekb/mcp --rename-key "Banking" --name "Bank"
+npx -y @safekb/mcp --rotate-key "Bank" [--store system|file]
+npx -y @safekb/mcp --move-key "Bank" --store file
+npx -y @safekb/mcp --delete-key "Bank"
+```
+
+A seal root is given by its [name](#names-of-seal-roots) or its id.
+
+- `--list-keys` prints one line per key in the system keyring and the key file directory: the store,
+  the seal root, the key id, and its status. `current`: the root's seal expects this key.
+  `superseded`: the root exists but has a newer key. `root not found or not accessible with this
+  token`: the server knows no such root for this token (404 or 403), which may be limited to some
+  spaces. `its root id is not a seal root on the server`: the id is that of something else.
+  A key of another tenant is shown as such and is not asked about. When the server cannot be asked
+  (rejected token, server error, no network) the listing fails; a status is never guessed. It never
+  prints a key, and needs no terminal. Secrets held by the sidecar are in memory only and are not
+  listed.
+- `--create-key` makes a sealed folder at the top of the space as a new seal root and keeps its
+  generated key in the default store, or the one named by `--store`.
+- `--rename-key` changes the root's sealed title on the server and the name on this machine. The
+  root's key must be in a local store.
+- `--rotate-key` gives the root a newly generated key, in the store that kept the old one or the one
+  named by `--store`, and removes the superseded key once the server has taken the new one. Like
+  `change_seal_password`, it does not revoke what a holder of the old key already read.
+- `--move-key` puts the root's current key into the other store, reads it back from there, and only
+  then removes it from where it was. Nothing is written to the server. A move that was interrupted
+  with the key in both stores is finished by running it again, towards either store.
+- `--delete-key` removes every key of the root from this machine's key stores and forgets its name.
+  The root on the server is not touched. It shows the keys with their status and asks you to type
+  the root's name or id. It warns when a current key is among them (without another copy the root's
+  content can never be opened again), and when a key's status could not be verified with this token
+  (root not found or not accessible, another tenant, not a seal root): such a key may still be the
+  only one that opens existing content. Only keys the server says are superseded come without a
+  warning. A name left behind without any key is removed the same way. It needs a terminal, and no
+  flag skips the question.
+
+When a step after the point of no return fails (the superseded key cannot be removed after a rotation,
+the old copy cannot be removed after a move), the command fails and says where the key now is.
 
 ### Moving keys to another machine
 
@@ -220,6 +312,64 @@ irreversible per credential: the server drops its own encrypted secrets and that
 
 Old database and storage backups keep the server-encrypted copies until they age out.
 
+## Export and import
+
+```sh
+npx -y @safekb/mcp --export all.safekb --compress        # everything this token reaches
+npx -y @safekb/mcp --export work.safekb --space <space id> --doc <document id>
+npx -y @safekb/mcp --import all.safekb                   # into the account of this token
+npx -y @safekb/mcp --import work.safekb --into-space <space id>
+```
+
+Both need a terminal: the passphrase of the file is typed there (twice for an export) and is never an
+argument. The file is encrypted with AES-256-GCM under a key derived from the passphrase with Argon2id,
+in parts that cannot be dropped, swapped or cut off unnoticed; `--compress` gzips before encrypting.
+Attachments are streamed, so the file may be large. **The file holds every secret in plaintext under
+that one passphrase**: passwords, TOTP seeds and the content of sealed documents.
+
+What an export holds:
+
+- Spaces, folders, documents (Markdown, rich text and canvas blocks) with their tags, external
+  references, workflow status and due date, and their attachments.
+- Databases with columns, indexes, views, rows, row pages and the rows' files.
+- Credentials with every secret field. Each secret of a server-encrypted credential is one audited
+  reveal on the server.
+- Sealed folders, documents, attachments and credentials, decrypted on this machine. Every seal root
+  in the selection must open with a secret this machine keeps or its sidecar holds
+  (`safekb-mcp --sidecar`, then `add <name or id>` for a passphrase root); otherwise the export
+  stops before it writes anything. `--skip-locked` exports without those roots and says so.
+- Projects, tasks, decisions, and the links between exported things.
+
+What is selected:
+
+- No `--space` and no `--doc`: everything the token reaches.
+- `--space <id>` (repeatable): that space with its documents, credentials, projects and tasks.
+- `--doc <id>` (repeatable): that document, or that folder with everything in it and the credentials
+  filed in it. Its parent is not exported, so on import it is at the top of its space.
+- A link to something outside the selection is left out and counted.
+
+What an import does:
+
+- It creates new things with new ids and changes nothing that exists, so it works for a restore, for
+  another account or server, and twice in a row. References between imported things (links, relations,
+  ids in text, attachments shown in a page, the task of a checklist item) follow the new ids.
+- Every exported space becomes a new space, also where one of that name exists. `--into-space` puts
+  everything into one existing space instead. A token limited to some spaces is given the spaces it
+  creates (this needs a SafeKB server of October 2026 or newer).
+- Every seal root becomes a new seal root with a newly generated key, kept in the default key store
+  or the one named by `--store`; a passphrase root therefore becomes a key root. A seal root whose
+  name is taken on this machine gets ` (imported)` appended. **Back the new keys up**
+  (`--export-keys`).
+- A project whose slug is taken gets a numbered one. A task keeps its assignee only in the account
+  the export came from.
+- When a step fails the import stops, says at which record, and leaves what it had created; nothing
+  is rolled back.
+
+Not in an export: version history, creation and change times and authors, shares, public links, space
+members, and the account's settings. A vault document (encrypted in the browser to its owner's vault)
+is exported as ciphertext and can only go back into the account it came from, while its id is free
+there. Merged tasks are left out.
+
 ## What sealing does not protect
 
 - Whatever a tool returns enters the local conversation transcript and is sent to the model provider.
@@ -227,6 +377,7 @@ Old database and storage backups keep the server-encrypted copies until they age
 - A program running as your user can read a key file, ask the system keyring or the sidecar for a
   secret, and read the memory of this client while a root is unlocked.
 - A session that has unlocked a root can be tricked by content it reads into copying it elsewhere.
+- An export file: it holds sealed content under the passphrase of the file, not under its seal roots.
 - A compromised local machine, or a malicious server serving stale data.
 - Metadata: existence, sizes, timestamps, tree position.