@safekb/mcp 0.9.1 → 0.10.0

package/README.md

@@ -107,10 +107,8 @@ every tool that keeps a key this way; see [Where secrets are kept](#where-secret
 | `--rotate-key <ref>` | | Replace a seal root's secret with a new generated key; takes `--store`. |
 | `--move-key <ref>` | | Move a seal root's current key to `--store system\|file`. |
 | `--delete-key <ref>` | | Remove a seal root's keys from this machine, after a typed confirmation. |
-| `--auto-unlock <ref>\|all` | | With `--set on\|off`: let the sealed tools unlock this root (or every root) by themselves. See [Unlocking automatically](#unlocking-automatically). |
 | `--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_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. |
 
@@ -134,15 +132,17 @@ Its secret is a generated key or a passphrase.
 - `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`,
+- There is no unlock step. Every sealed tool opens the seal root it needs by itself, with the secret
+  the one local store that has it keeps (system keyring, key file directory, or the sidecar), and the
+  root's keys stay in the client's memory until the process ends. **Any session on this machine that
+  uses these key stores can read every root whose secret is kept here.** See
+  [Opening seal roots](#opening-seal-roots).
+- `search_sealed`, `list_sealed`, `read_sealed_document`, `get_sealed_section`,
   `update_sealed_document`, `replace_in_sealed_document`, and the move, archive, delete,
   attachment and deposit tools.
 - `seal_document` and `unseal_document` move a document between hosted and sealed form; see
   [Moving documents in and out of a seal root](#moving-documents-in-and-out-of-a-seal-root).
   `unseal_document` is not a backup: see [Export and import](#export-and-import).
-- `lock_sealed`, the idle timeout, or the end of the process forget the keys.
 - `change_seal_password` replaces the root's secret. Once the server has taken the new one, the
   superseded key is removed from the store that kept it (the system keyring, or any key file in the
   key file directory). A superseded passphrase, or a key file you had written elsewhere with
@@ -188,8 +188,9 @@ conversation.
 ## 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`.
+side: a sealed tool asks each store and uses the one that has the secret. If two have it, the tool
+fails and names them: `provide_seal_secret` with `store` says which one to use, `move_seal_key` leaves
+one copy.
 
 | `store` | What is kept | Where | At rest |
 | --- | --- | --- | --- |
@@ -207,6 +208,14 @@ Secret Service (GNOME Keyring, KWallet, KeePassXC); the kernel keyring is never
 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).
 
+A locked keyring does not answer until it is unlocked. On Linux it waits for an unlock dialog on the
+machine's own screen, which nobody sees over SSH or after an autologin that typed no password. Every
+keyring call is therefore given up after 10 seconds. When the choice is being made, that counts as no
+keyring: keys go to files, and you are told why. Later, the call that waited fails with "The system
+keyring did not answer". Unlock the keyring at the machine (log in at the desktop, or unlock it in
+your keyring manager) and try again; after unlocking, `--configure` can choose the system keyring
+again.
+
 ### The sidecar
 
 The sidecar keeps passphrases out of files, out of the keyring and out of the conversation. Run it in
@@ -225,8 +234,7 @@ npx -y @safekb/mcp --sidecar
   the tool call waits.
 - With `--confirm` it asks for your approval before every release of a secret.
 - The [key tools](#the-key-tools) and the backup tools ask here for the passphrase of a file, for
-  the name or id that confirms a deletion, and for the confirmation that turns auto-unlock on. Such a
-  passphrase is used for that one call and not held. An empty entry declines.
+  the name or id that confirms a deletion. Such a passphrase is used for that one call and not held. An empty entry declines.
 - The sidecar and the MCP client must be the same version of `@safekb/mcp`.
 
 Several roots can be held at once, each with its own passphrase and time. The sidecar listens on a Unix
@@ -236,20 +244,20 @@ 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
+name to type. So the client remembers the name of every seal root it creates or opens, in
 `roots.json` next to the token file (mode 0600), and follows a rename or a delete. The sidecar, the
 key export and the key modes show a root as `"Tax papers" (6acd…)`, and the name is taken wherever a
 seal root's id is: at the sidecar, in the key modes, and in the `root_id` of the MCP tools.
 
 - 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.
-- The client never puts a name into a tool result, so unlocking a root does not tell the model what
+  never by the server. Delete the file to forget them; they come back as roots are opened.
+- The client never puts a name into a tool result, so opening a root does not tell the model what
   it is called. An error repeats only the name the caller passed.
 - A name stays a usable handle: creating or renaming a seal root is refused when the name has the
   shape of an id (24 hex characters), or when another root known on this machine already has it.
 - Text with the shape of an id always means the root with that id. A root that got such a title
-  elsewhere is not given a name here when it is unlocked or its key is imported: use its id.
-- Two roots can still share a name when both were named elsewhere and then unlocked or imported
+  elsewhere is not given a name here when it is opened or its key is imported: use its id.
+- Two roots can still share a name when both were named elsewhere and then opened or imported
   here. Such a name stands for neither and is refused as ambiguous: use the id. Such a root can
   still be changed while its name stays the same.
 
@@ -297,41 +305,34 @@ A seal root is given by its [name](#names-of-seal-roots) or its id.
 When a step after the point of no return fails (the superseded key cannot be removed after a rotation,
 the old copy cannot be removed after a move), the command fails and says where the key now is.
 
-### Unlocking automatically
+### Opening seal roots
 
-```sh
-npx -y @safekb/mcp --auto-unlock "Bank" --set on    # or a root id
-npx -y @safekb/mcp --auto-unlock all --set on       # every root without a setting of its own
-npx -y @safekb/mcp --auto-unlock "Bank" --set off
-```
+A sealed tool that needs a seal root this process does not hold yet opens it from the local stores,
+and keeps its keys in memory until the process ends. Nothing is asked and nothing has to be turned on.
 
-A sealed tool that needs a locked root it is allowed to open unlocks it by itself, as `unlock_sealed`
-with only `root_id` would, with the same idle timeout, and goes on. **The trade-off: any session that
-uses this token on this machine can then read such a root without unlocking it first.**
-
-- Only a key kept in the system keyring or the key file directory is used. A root opened by a
-  passphrase never unlocks by itself: turning it on for one is refused, and with `all` such a root
-  stays locked and says so.
-- A root's own setting wins over `all`. The settings are in `auto-unlock.json` next to the token file
-  (mode 0600), read on every use: a change applies to a running client at once.
-- A failed automatic unlock (no key, a key in both stores) is the tool's error; nothing is guessed.
-  Without the setting a locked root stays the usual "call unlock_sealed first" error.
-- `--list-keys` adds `unlocks automatically` to a current key whose root does; `list_sealed`,
-  `list_seal_keys` and `get_auto_unlock` show `auto_unlock`.
-- `set_auto_unlock` turns it on only after you type the root's name or id (or `all`) at the sidecar:
-  the model cannot widen access on its own. Turning it off needs no confirmation.
+- Since 0.10.0 there is no `unlock_sealed`, `lock_sealed`, idle timeout (`SAFEKB_SEALED_IDLE_TTL`,
+  `idle_ttl_seconds`), `--auto-unlock`, `get_auto_unlock` or `set_auto_unlock`. An `auto-unlock.json`
+  left next to the token file is not read; delete it.
+- A root opened by a passphrase opens once you have typed the passphrase at the
+  [sidecar](#the-sidecar) (`add <name or id>`). The secret leaves the sidecar when its time is up,
+  but a client that already opened the root keeps it open until it ends.
+- A root whose secret no store holds fails with an error that says how to supply it: type it at the
+  sidecar and repeat the call, or give a key file or a file holding only the secret with
+  `provide_seal_secret` (`secret_file`). Nothing is guessed: a secret found in two stores is an
+  error too.
+- To stop a session from reading a root, end the client, or remove the root's key from this machine
+  (`--move-key` it elsewhere, or `--delete-key`).
 
 ### The key tools
 
 Everything above is also an MCP tool, and none of them takes or returns a secret: `list_seal_keys`,
 `rename_seal_key`, `rotate_seal_key`, `move_seal_key`, `delete_seal_key`, `export_seal_keys`,
-`import_seal_keys`, `get_auto_unlock` and `set_auto_unlock`, and for backups `export_backup` and
+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),
-the name or id that confirms `delete_seal_key`, and the confirmation that turns auto-unlock on. It
-reaches this client only, never the conversation. Without a running sidecar such a tool fails and says
+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 (`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.
 
@@ -364,9 +365,9 @@ sealed custom fields are encrypted on your machine; its title, username, url, ta
 custom fields and the key name of every custom field (sealed ones too) stay readable by the server, so the standard `search_credentials`, `list_credentials` and
 `find_credential_duplicates` keep working. Never put a secret into `notes`.
 
-- `insert_sealed_credential`, `update_sealed_credential`, `delete_sealed_credential`: signed by the unlocked root.
-- `move_sealed_credential` hands a credential to another seal root of its space; both roots must be
-  unlocked. A sealed credential changes space only with its root: moving the root's folder to another
+- `insert_sealed_credential`, `update_sealed_credential`, `delete_sealed_credential`: signed by the credential's seal root.
+- `move_sealed_credential` hands a credential to another seal root of its space; both roots must
+  open here. A sealed credential changes space only with its root: moving the root's folder to another
   space takes its credentials along (a credential's group in the old space is left behind).
 - `reveal_sealed_credential` and `get_sealed_totp` decrypt locally. The hosted `reveal_credential` and
   `get_credential_totp` cannot open a sealed credential.
@@ -379,7 +380,7 @@ custom fields and the key name of every custom field (sealed ones too) stay read
 sealed one; `in_other_spaces` counts those that need a seal root of their own space. It is
 irreversible per credential: the server drops its own encrypted secrets and that credential's history.
 
-1. Unlock the target root, then run it with `dry_run: true` (the default). Nothing changes. It lists the
+1. Run it with `dry_run: true` (the default). Nothing changes. It lists the
    credentials, says which have notes, and flags notes that match a few secret patterns. That scan is
    advisory and misses secrets.
 2. Decide every note, because today notes are encrypted and afterwards they are either sealed or
@@ -473,8 +474,10 @@ there. Merged tasks are left out.
 - 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 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.
+  secret, and read the memory of this client while it holds a root open.
+- Every session on this machine that uses these key stores can read every root whose secret is kept
+  here: there is no unlock step that would stop it.
+- A session can be tricked by content it reads into copying sealed content elsewhere.
 - An export file: it holds the sealed content of every root that opened under the passphrase of the
   file, not under its seal roots.
 - A compromised local machine, or a malicious server serving stale data.