@safekb/mcp 0.7.0 → 0.8.0

package/README.md

@@ -94,7 +94,7 @@ every tool that keeps a key this way; see [Where secrets are kept](#where-secret
 | `--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 in the store settings, if any. |
-| `--sealed-only` | | Expose only the sealed tools; the hosted tools are not proxied. |
+| `--sealed-only` | | Expose only the sealed and key tools; the hosted tools are not proxied, and `export_backup` and `import_backup` are not offered. |
 | `--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. |
@@ -107,6 +107,7 @@ 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). |
@@ -136,14 +137,16 @@ Its secret is a generated key or a passphrase.
 - `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,
+  `update_sealed_document`, `replace_in_sealed_document`, and the move, archive, delete,
   attachment and deposit tools.
+- `unseal_document` turns a sealed document into a plain, unencrypted one (a new document the server
+  can read) and deletes the sealed original. It 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
   `key_out_path`, is yours to remove.
-- Deleting a seal root (`delete_sealed_document`, or `export_sealed_document` of a standalone sealed
+- Deleting a seal root (`delete_sealed_document`, or `unseal_document` of a standalone sealed
   document) also removes its keys and its name from this machine.
 - A tool parameter that names a seal root (`root_id`, `new_root_id`) takes its id or its
   [name](#names-of-seal-roots). Documents and folders inside a root are named by id.
@@ -187,6 +190,10 @@ npx -y @safekb/mcp --sidecar
 - 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.
+- 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 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
 socket only your user can open; it is not available on Windows. Any program running as you can still
@@ -256,6 +263,44 @@ 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
+
+```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 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.
+
+### 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
+`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
+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.
+
 ### 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
@@ -273,20 +318,22 @@ npx -y @safekb/mcp --import-keys keys.safekb   # on the other machine, after --s
   Without the passphrase the file opens for nobody.
 - 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.
+- Both need a terminal, or the sidecar for `export_seal_keys` and `import_seal_keys`: 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
+A sealed credential belongs to a seal root and is kept in that root's space. Its password, TOTP seed, `sealed_notes` and the values of
 sealed custom fields are encrypted on your machine; its title, username, url, tags, `notes`, visible
 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; both roots must be unlocked.
+- `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
+  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.
 - Visible fields can be edited without the secret. Such an edit is flagged (`visible_tampered`) with the
@@ -294,7 +341,8 @@ custom fields and the key name of every custom field (sealed ones too) stay read
 
 ### Migrating server-encrypted credentials
 
-`migrate_credentials_to_sealed` turns every credential the token can see into a sealed one. It is
+`migrate_credentials_to_sealed` turns every credential the token can see in the root's space into a
+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
@@ -323,7 +371,10 @@ npx -y @safekb/mcp --import all.safekb --keys pc-a.keys --keys pc-b.keys   # key
 ```
 
 Both need a terminal: the passphrase of the file is typed there (twice for an export) and is never an
-argument. The file is encrypted with AES-256-GCM under a key derived from the passphrase with Argon2id,
+argument. The tools `export_backup` and `import_backup` do the same, with every passphrase typed at the
+[sidecar](#the-sidecar); their result holds counts and names, never content or a secret. A large export
+runs for minutes; the tool reports progress to an MCP client that asks for it. With `--sealed-only`
+these two tools are not offered, since they reach unsealed content too. The file is encrypted with AES-256-GCM under a key derived from the passphrase with Argon2id,
 in parts that cannot be dropped, swapped or cut off unnoticed; `--compress` gzips before encrypting.
 Attachments are streamed, so the file may be large. **The file holds every secret in plaintext under
 that one passphrase**: passwords, TOTP seeds and the content of sealed documents.
@@ -369,6 +420,8 @@ What an import does:
   or the one named by `--store`; a passphrase root therefore becomes a key root. A seal root whose
   name is taken on this machine gets ` (imported)` appended. **Back the new keys up**
   (`--export-keys`).
+- A sealed credential is created in the space of its new seal root. One exported from another space
+  than its root's is placed there, and the report says so.
 - A project whose slug is taken gets a numbered one. A task keeps its assignee only in the account
   the export came from.
 - When a step fails the import stops, says at which record, and leaves what it had created; nothing