@safekb/mcp 0.2.0 → 0.4.0

package/README.md

@@ -3,60 +3,89 @@
 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`). What is already done is left as it is, so it can be run again.
+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"] } } }
 ```
 
+Started 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.
+
+### 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. |
+| `--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. |
 | | `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,
+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.
 
@@ -89,14 +118,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
 
@@ -107,9 +138,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 +151,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 --setup 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 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.
+- 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