@safekb/mcp 0.3.0 → 0.4.0

package/README.md

@@ -3,62 +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.
 
@@ -91,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
 
@@ -142,7 +171,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 +179,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.