@safekb/mcp 0.6.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,8 +107,9 @@ 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`. |
+| `--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. |
@@ -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
@@ -319,10 +367,14 @@ npx -y @safekb/mcp --export all.safekb --compress        # everything this token
 npx -y @safekb/mcp --export work.safekb --space <space id> --doc <document id>
 npx -y @safekb/mcp --import all.safekb                   # into the account of this token
 npx -y @safekb/mcp --import work.safekb --into-space <space id>
+npx -y @safekb/mcp --import all.safekb --keys pc-a.keys --keys pc-b.keys   # keys of locked roots
 ```
 
 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.
@@ -334,10 +386,12 @@ What an export holds:
 - Databases with columns, indexes, views, rows, row pages and the rows' files.
 - Credentials with every secret field. Each secret of a server-encrypted credential is one audited
   reveal on the server.
-- Sealed folders, documents, attachments and credentials, decrypted on this machine. Every seal root
-  in the selection must open with a secret this machine keeps or its sidecar holds
-  (`safekb-mcp --sidecar`, then `add <name or id>` for a passphrase root); otherwise the export
-  stops before it writes anything. `--skip-locked` exports without those roots and says so.
+- Sealed folders, documents, attachments and credentials of every seal root that opens with a secret
+  this machine keeps or its sidecar holds (`safekb-mcp --sidecar`, then `add <name or id>` for a
+  passphrase root), decrypted on this machine.
+- Every other seal root as the server stores it, still sealed: the machine that makes the backup needs
+  none of their keys. The export names these roots before it writes. Pending deposits in them are left
+  out. `--skip-locked` leaves such roots out entirely instead.
 - Projects, tasks, decisions, and the links between exported things.
 
 What is selected:
@@ -356,15 +410,25 @@ What an import does:
 - Every exported space becomes a new space, also where one of that name exists. `--into-space` puts
   everything into one existing space instead. A token limited to some spaces is given the spaces it
   creates (this needs a SafeKB server of October 2026 or newer).
+- A seal root the file holds still sealed is opened with its key: from a key export given with
+  `--keys <file>` (repeatable; made with `--export-keys` on any machine that keeps the key; its
+  passphrase is asked and its keys are used for this import only), or from a store of this machine.
+  A key of another account, or one replaced since by a key or passphrase change, does not open it.
+  Without a key everything in that root is left out, and the root is named with the reason; import
+  the file again with its key to restore it (that creates everything else again too).
 - Every seal root becomes a new seal root with a newly generated key, kept in the default key store
   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
   is rolled back.
 
+A file written by 0.7.0 or newer is not read by 0.6.0; 0.7.0 reads files of 0.6.0.
+
 Not in an export: version history, creation and change times and authors, shares, public links, space
 members, and the account's settings. A vault document (encrypted in the browser to its owner's vault)
 is exported as ciphertext and can only go back into the account it came from, while its id is free
@@ -377,7 +441,8 @@ there. Merged tasks are left out.
 - 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.
-- An export file: it holds sealed content under the passphrase of the file, not under its seal roots.
+- 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.
 - Metadata: existence, sizes, timestamps, tree position.