@safekb/mcp 0.7.0 → 0.9.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,18 +137,54 @@ 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.
+- `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
   `key_out_path`, is yours to remove.
-- Deleting a seal root (`delete_sealed_document`, or `export_sealed_document` of a standalone sealed
-  document) also removes its keys and its name from this machine.
+- Deleting a seal root (`delete_sealed_document`, or `unseal_document` of a standalone sealed
+  document with `delete_original`) 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.
 
+### Moving documents in and out of a seal root
+
+`seal_document` copies a hosted (unsealed) document into a sealed folder; `unseal_document` copies a
+sealed document out as a normal one. The content is read, converted and written by the client: you pass
+ids and get ids and counts back, so nothing is retyped by the model and nothing of the text enters the
+conversation.
+
+| | `seal_document` | `unseal_document` |
+|---|---|---|
+| Takes | `document_id` of a hosted document; `parent_id` (a sealed folder of the same space, or a seal root's id), or `store` / `key_out_path` to make the copy a seal root of its own | `document_id` of a sealed document; optional plain `parent_id`; `format` |
+| Result | a sealed document with a new id | a normal document with a new id: a canvas (default), or a markdown document with `format: "markdown"` |
+| Not available | with `--sealed-only` (it reads hosted content) | |
+
+- **Canvas structure is kept.** A canvas becomes the markdown body of the sealed document in the
+  dialect of `@safekb/canvas-markdown` (headings, lists, tables, callouts, code, attachments, …) and is
+  rebuilt from it on `unseal_document`. A part the dialect cannot hold exactly is reported and stops the
+  copy. A sealed body that is not in the dialect (typed as plain markdown elsewhere) is reported too:
+  `format: "markdown"` keeps it as markdown text.
+- **Attachments move with the document**, sealed or unsealed, as streams: no file is written to disk.
+  An attachment that is a derived crop, or larger than the server accepts, stops the copy.
+- **Nothing is reported done before it was checked.** The copy is read back, decrypted where it is
+  sealed, and compared with the original: markdown byte for byte, blocks structurally, attachments by size
+  and hash. If anything differs the copy is deleted again and the original is untouched.
+- **`dry_run` is true by default**: it creates nothing and reports the format, counts, attachments,
+  target, what stands in the way (`problems`) and what is not carried. Pass `dry_run: false` to do it.
+- **`delete_original` is false by default.** With it, the original is deleted after the check, and only
+  if it was not edited meanwhile. A sealed document does not carry external refs, workflow status, due
+  date, links or version history: `delete_original` refuses while a hosted document has any, and says
+  which. Keep the original, or remove them first.
+- The sealed copy stays in the space of its seal root, so `parent_id` must be in the document's space.
+- Not atomic: a failure after the copy was made says what exists (the copy, the original, or both).
+- Since 0.9.0 `unseal_document` no longer deletes the sealed original by default and makes a canvas, not a markdown document: pass `delete_original: true` and `format: "markdown"` for the old behavior. It also moves attachments instead of refusing documents that have them.
+
 ## 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
@@ -187,6 +224,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 +297,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 +352,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 +375,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 +405,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 +454,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

package/THIRD-PARTY-NOTICES.md

@@ -119,3 +119,173 @@ Special thank you to the authors of original C algorithms:
 - Mark Adler
 - Yann Collet
 ```
+
+## entities
+
+```
+Copyright (c) Felix Böhm
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+## linkify-it
+
+```
+Copyright (c) 2015 Vitaly Puzrin.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+```
+
+## markdown-it
+
+```
+Copyright (c) 2014 Vitaly Puzrin, Alex Kocharin.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+```
+
+## mdurl
+
+```
+Copyright (c) 2015 Vitaly Puzrin, Alex Kocharin.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+.parse() is based on Joyent's node.js `url` code:
+
+Copyright Joyent, Inc. and other Node contributors. All rights reserved.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+```
+
+## punycode.js
+
+```
+Copyright Mathias Bynens <https://mathiasbynens.be/>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+## uc.micro
+
+```
+Copyright Mathias Bynens <https://mathiasbynens.be/>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```