@safekb/mcp 0.1.0 → 0.2.0

package/README.md

@@ -15,6 +15,12 @@ This opens the browser and prints a **pairing code**. Sign in on the page, choos
 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.
 
+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.
+
 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
@@ -41,10 +47,13 @@ Claude Desktop and Cursor (`mcpServers` in their MCP config file):
 | --- | --- | --- |
 | `--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. |
 | `--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`). No default. |
+| `--keyring <dir>` | `SAFEKB_SEALED_KEYRING` | Directory of sealed key files (`*.json`). Otherwise the one `--configure` chose, 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. |
-| | `SAFEKB_SEALED_IDLE_TTL` | Seconds an unlocked seal root may stay idle. Default 900. |
+| `--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. |
+| `--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. |
+| | `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. |
 
 The client refuses to start when the token file or a keyring file is readable by group or others,
@@ -57,16 +66,58 @@ confirmed*: it may have run, and it is not sent again. Check the state before re
 ## Sealed documents
 
 A **seal root** is a sealed folder (one secret opens everything in it) or a standalone sealed document.
-Its secret is a generated key (default) or a passphrase.
+Its secret is a generated key or a passphrase.
 
-- `create_sealed_folder` / `insert_sealed_document` with `key_out_path` write a key file (mode 0600).
-  The key is never returned to the model. **Back the file up: a lost secret cannot be recovered.**
-- `unlock_sealed` with `secret_file`, or with only `root_id` when the key file is in the keyring.
+- `create_sealed_folder` / `insert_sealed_document` with `store` or `key_out_path` make a new seal root
+  and keep its secret on this machine. The secret is never returned to the model.
+  **Back it up: a lost secret cannot be recovered.**
+- `unlock_sealed` with only `root_id` takes the secret from the store that has it; `secret_file` reads
+  it from a file.
 - Then `search_sealed`, `list_sealed`, `read_sealed_document`, `get_sealed_section`,
   `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.
 
+## Where secrets are kept
+
+Every seal root has its own secret, and each can be kept in a different place. All three work side by
+side: `unlock_sealed` with only `root_id` asks each store and uses the one that has the secret. If two
+have it, it stops and asks for `store`.
+
+| `store` | What is kept | Where | At rest |
+| --- | --- | --- | --- |
+| `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 | |
+
+`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
+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).
+
+### The sidecar
+
+The sidecar keeps passphrases out of files, out of the keyring and out of the conversation. Run it in
+a terminal of its own:
+
+```sh
+npx -y @safekb/mcp --sidecar
+```
+
+- `add <root 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`.
+- 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.
+
+Several roots can be held at once, each with its own passphrase and time. The sidecar listens on a Unix
+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.
+
 ## Sealed credentials
 
 A sealed credential belongs to a seal root. Its password, TOTP seed, `sealed_notes` and the values of
@@ -104,7 +155,9 @@ Old database and storage backups keep the server-encrypted copies until they age
 ## What sealing does not protect
 
 - Whatever a tool returns enters the local conversation transcript and is sent to the model provider.
-  The same holds for a secret passed as text; use `secret_file` or the keyring.
+  The same holds for a secret passed as text; use a store or `secret_file`.
+- 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.
 - A compromised local machine, or a malicious server serving stale data.
 - Metadata: existence, sizes, timestamps, tree position.