@safekb/mcp 0.3.0 → 0.5.0

package/README.md

@@ -3,62 +3,120 @@
 Local MCP client for SafeKB (stdio). It proxies the hosted SafeKB tools and adds **sealed** documents
 and folders: content is encrypted on your machine, and the server stores only ciphertext.
 
-Needs Node 20 or newer.
-
 ## Setup
 
-```sh
-npx -y @safekb/mcp --authorize --url <your SafeKB API URL>
-```
-
-This opens the browser and prints a **pairing code**. Sign in on the page, choose the spaces, type the
-pairing code, and the client saves a service-account token to `~/.config/safekb/mcp.json` (mode 0600).
-It then prints the account it was authorized as; check that it is yours. There is no default URL.
+### Claude Desktop
 
-Last, it chooses where this machine keeps the keys of new seal roots (see [Where secrets are kept](#where-secrets-are-kept)).
-With a system keyring that is the choice. Without one, as on most servers, it warns and asks before it
-uses key files. `npx -y @safekb/mcp --configure` makes the same choice again without re-authorizing.
-A client authorized before this choice existed makes it by itself on its next start when the system
-keyring works; only key files need `--configure`, because they need your agreement.
+1. Download [`safekb.mcpb`](https://safekb.com/download/safekb.mcpb) and open it (or Settings →
+   Extensions → Advanced settings → Install Extension…), then click **Install**.
+2. A SafeKB page opens in your browser. Sign in, choose the spaces, check that the page shows the same
+   code as Claude, and click **Confirm**.
 
-How the token gets to the client: the page never sees it. The page hands the client a single-use code
-(valid for two minutes), and the client redeems that code itself, proving with a secret it never wrote
-anywhere that it is the process that started the flow. The URL in the browser launcher's arguments is
-readable by other users of the machine, so it holds nothing that completes the flow; the pairing code
-is what ties your sign-in to your terminal. Every authorization creates its own token: authorizing
-again never changes the token or the spaces of another client. Revoke one under Settings → service
-accounts.
+The tools appear in Claude without a restart. Nothing else is needed: no Node, no config file.
 
-Claude Code:
+### Claude Code
 
 ```sh
-claude mcp add safekb -- npx -y @safekb/mcp
+npx -y @safekb/mcp --setup
 ```
 
-Claude Desktop and Cursor (`mcpServers` in their MCP config file):
+This opens the same page, then registers the server with Claude Code for all your projects
+(`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
+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"] } } }
 ```
 
+`--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
+`npx -y @safekb/mcp --setup --url <your API URL>` first; the Desktop extension then uses the token that
+command saved.
+
+### How the authorization is protected
+
+- The page never sees the token. The client keeps a random secret, the link carries only its SHA-256,
+  and the client collects the token itself by presenting the secret to the server it was pointed at.
+- Whoever sees the link could approve it for *their* account, to make your client write into it. So an
+  approval is taken only when it is tied to you: it carries the pairing code, or you confirmed it in
+  your terminal.
+- The pairing code reaches the page in a file only your user can read (mode 0600), which the browser is
+  started with. The browser launcher's arguments, which other users of the machine can read, hold only
+  that file's path. This is why you check the code instead of typing it. When the page was opened by
+  hand in a client without a terminal, you type the code.
+- Every authorization creates its own token: authorizing again never changes the token or the spaces of
+  another client. Revoke one under Settings → service accounts. The token is saved to
+  `~/.config/safekb/mcp.json` (mode 0600).
+
+### Where keys go
+
+The keys of new seal roots go to the system keyring. On a machine without one (most servers) they are
+kept as files, and the client says so in plain words on the page, in the terminal and in the result of
+every tool that keeps a key this way; see [Where secrets are kept](#where-secrets-are-kept).
+`npx -y @safekb/mcp --configure` makes the choice again, for example after a keyring was installed.
+
 ## Options
 
 | Flag | Environment | Meaning |
 | --- | --- | --- |
-| `--url <api url>` | `KB_API_URL` | API base URL. Otherwise the URL saved by `--authorize`. When serving, it must have the origin the token was issued for: the token is never sent anywhere else. |
+| `--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. |
-| `--keyring <dir>` | `SAFEKB_SEALED_KEYRING` | Directory of sealed key files (`*.json`). Otherwise the one `--configure` chose, if any. |
+| `--keyring <dir>` | `SAFEKB_SEALED_KEYRING` | Directory of sealed key files (`*.json`). Otherwise the one in the store settings, if any. |
 | `--sealed-only` | | Expose only the sealed tools; the hosted tools are not proxied. |
-| `--authorize` | | Authorize in the browser and write the token file, then choose the key store. |
-| `--configure` | | Choose where new sealed keys are kept. Writes `stores.json` next to the token file. |
+| `--authorize` | | Authorize again in the browser and replace the token file. |
+| `--configure` | | Choose again 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. |
+| `--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. |
 | | `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. |
 
-The client refuses to start when the token file or a keyring file is readable by group or others,
+Exactly one mode is given: `--mcp`, `--setup`, `--authorize`, `--configure`, `--sidecar`, 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.
 
@@ -79,6 +137,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
 
@@ -91,14 +157,16 @@ have it, it stops and asks for `store`.
 | `system` | a generated key | the operating system's keyring: Keychain (macOS), Credential Manager (Windows), Secret Service (Linux) | encrypted by the system |
 | `file` | a generated key | a file (mode 0600) in the keyring directory | not encrypted |
 | `sidecar` | a passphrase you type | the memory of a separate process, for a time you choose | nowhere |
-| `default` | | whichever of `system` and `file` `--configure` chose | |
+| `default` | | `system` where the system keyring works, otherwise `file` | |
 
 `key_out_path` still writes a key file to a path of your choice, and `passphrase` still takes one as
 text (which then is in the conversation transcript).
 
-The system keyring is used only where `--configure` found it working. On Linux that means a running
+The choice is made once, on the first start or by `--setup`, and saved in `stores.json`; `--configure`
+makes it again. The system keyring is used only where it was found working. On Linux that means a running
 Secret Service (GNOME Keyring, KWallet, KeePassXC); the kernel keyring is never used, because it
-forgets its content at logout. Keys are kept there with [`@napi-rs/keyring`](https://github.com/Brooooooklyn/keyring-node).
+forgets its content at logout. Where it does not work, keys are kept as files in `keys/` next to the
+token file: readable only by your user, but not encrypted on disk. The client tells you when it does this. Keys are kept there with [`@napi-rs/keyring`](https://github.com/Brooooooklyn/keyring-node).
 
 ### The sidecar
 
@@ -126,14 +194,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
 
@@ -142,7 +261,7 @@ 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
+npx -y @safekb/mcp --import-keys keys.safekb   # on the other machine, after --setup there
 ```
 
 - Export asks for a passphrase (typed twice, not shown; 12 or more characters are recommended, a
@@ -150,7 +269,7 @@ npx -y @safekb/mcp --import-keys keys.safekb   # on the other machine, after --a
   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
+- Import asks for that passphrase and keeps the keys in the default store of 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.