@safekb/mcp 0.15.0 → 0.17.0

package/README.md

@@ -110,7 +110,7 @@ every tool that keeps a key this way; see [Where secrets are kept](#where-secret
 | `--export <file>` | | Write what this token reaches to a new passphrase-protected file. Takes `--space`, `--doc`, `--compress`, `--skip-locked`. See [Export and import](#export-and-import). |
 | `--import <file>` | | Create what such a file holds in this token's account, as new things. Takes `--into-space`, `--store`, `--keys`. |
 | | `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. |
+| | `SAFEKB_MCP_NO_BROWSER` | Set to anything: never start a browser. Authorization only shows its link; a secret a tool asks for can then only be typed at the sidecar. |
 
 Exactly one mode is given: `--mcp`, `--setup`, `--authorize`, `--configure`, `--sidecar`, `--export`,
 `--import`, or one of the key modes. A flag that only modifies a mode (`--sealed-only`, `--keyring`, …) without one is an error;
@@ -216,6 +216,29 @@ keyring did not answer". Unlock the keyring at the machine (log in at the deskto
 your keyring manager) and try again; after unlocking, `--configure` can choose the system keyring
 again.
 
+### Typing a secret: browser page or sidecar
+
+What a tool needs you to type never goes through the conversation. While the call waits:
+
+- **A credential's secret** (`typed_at_sidecar`) is asked at the [sidecar](#the-sidecar) when one is
+  running, otherwise on a page this client opens in your browser. Where neither can ask (no display, no browser launcher, or
+  `SAFEKB_MCP_NO_BROWSER` is set), the call fails and says to start the sidecar.
+- **Every passphrase** (of an export or an import) **and a typed confirmation** (`delete_seal_key`)
+  are asked only at the sidecar.
+
+The page is served by this client at `127.0.0.1` for that one question and closes after your
+answer, or after 5 minutes. The browser is sent there through a launch file in a directory only your
+user can enter, so the page's one-time address is on no command line and never in the conversation.
+The file is removed as soon as the page opens, and the address opens once: if the page says it was
+opened already, someone else got there first, so cancel the request. The form posts to a second
+secret address that exists only in that page, and only from that page's origin; no cookie is set.
+
+The agent runs as your user too, so it could reach the page before you do. That is why the browser
+is used only for a value stored in a credential, which opens nothing. A passphrase it chose for a new
+export, the passphrase of a file it made itself to import, or a deletion it confirmed itself would
+give it what only you should decide; those stay at the sidecar. If the page says it was opened
+already, it was not you who opened it: cancel the request.
+
 ### The sidecar
 
 The sidecar keeps passphrases out of files, out of the keyring and out of the conversation. Run it in
@@ -240,6 +263,8 @@ npx -y @safekb/mcp --sidecar
 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.
+The MCP tool `sidecar_status` shows an agent whether the sidecar is running and which roots it holds,
+with the minutes left; never a secret.
 
 ### Names of seal roots
 
@@ -330,11 +355,12 @@ Everything above is also an MCP tool, and none of them takes or returns a secret
 and `import_seal_keys`, and for backups `export_backup` and
 `import_backup` (see [Export and import](#export-and-import)).
 
-What you type at the terminal for the command line, you type at the [sidecar](#the-sidecar) for a
-tool, while the call waits: the passphrase of an export file or a key export (twice for a new one),
-and the name or id that confirms `delete_seal_key`. It reaches this client only, never the conversation. Without a running sidecar such a tool fails and says
-to start one (`npx -y @safekb/mcp --sidecar`); on Windows, which has no sidecar, it names the command to run
-instead. File paths given to the tools must be absolute.
+What you type at the terminal for the command line, you type for a tool while the call waits (see
+[Typing a secret](#typing-a-secret-browser-page-or-sidecar)): the passphrase of an export file or a key
+export (twice for a new one) and the name or id that confirms `delete_seal_key`, at the sidecar only. It reaches this client
+only, never the conversation. Where nothing can ask, such a tool fails and says to start the sidecar
+(`npx -y @safekb/mcp --sidecar`); on Windows, which has no sidecar, it names the command to run instead.
+File paths given to the tools must be absolute.
 
 ### Moving keys to another machine