@safekb/mcp 0.1.0 → 0.3.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,15 @@ 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. |
+| `--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. |
 
 The client refuses to start when the token file or a keyring file is readable by group or others,
@@ -57,16 +68,95 @@ 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 <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 <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.
+
+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.
+
+### 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 --authorize 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 store `--configure` chose on 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
@@ -104,7 +194,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.