@safekb/mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,44 @@
+SafeKB MCP Client License
+
+Copyright (c) 2026 Mustafa Öztürk (the "Licensor"). All rights reserved.
+
+1. Grant. Subject to this license, the Licensor grants you a non-exclusive,
+   non-transferable, revocable right to install and run unmodified copies of
+   this software for the sole purpose of connecting to a SafeKB service that
+   you are authorized to use, including a SafeKB instance operated for you
+   under a separate written agreement with the Licensor.
+
+2. Restrictions. Except where applicable law does not allow this restriction,
+   you may not:
+   (a) modify the software or create derivative works of it;
+   (b) redistribute, sublicense, sell, rent or lease the software, or offer it
+       as part of another product or service;
+   (c) use the software, or any part of it, to build or operate a product or
+       service that competes with SafeKB;
+   (d) remove or alter any copyright, license or attribution notice.
+
+3. Ownership. The software is licensed, not sold. The Licensor keeps all
+   rights in it that this license does not expressly grant.
+
+4. Your keys and data. The software keeps secrets and keys on your device.
+   You alone are responsible for backing them up. The Licensor cannot recover
+   content that was sealed with a secret you no longer hold.
+
+5. Third-party components. The software includes open-source components that
+   stay under their own licenses, listed in THIRD-PARTY-NOTICES.md. Nothing in
+   this license limits your rights under those licenses.
+
+6. Termination. This license ends automatically if you breach it. When it
+   ends you must stop using the software and delete your copies.
+
+7. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+8. Limitation of liability. TO THE EXTENT THE LAW ALLOWS, THE LICENSOR IS NOT
+   LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR ANY
+   LOSS OF DATA, KEYS, PROFITS OR BUSINESS, ARISING FROM THE SOFTWARE OR ITS
+   USE. A separate written agreement between you and the Licensor, where one
+   exists, takes precedence over sections 7 and 8.
+
+Other uses need a commercial license from the Licensor: https://safekb.com

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# @safekb/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local MCP client for SafeKB (stdio). It proxies the hosted SafeKB tools and adds **sealed** documents
+and folders: content is encrypted on your machine, and the server stores only ciphertext.
+
+Needs Node 20 or newer.
+
+## Setup
+
+```sh
+npx -y @safekb/mcp --authorize --url <your SafeKB API URL>
+```
+
+This opens the browser and prints a **pairing code**. Sign in on the page, choose the spaces, type the
+pairing code, and the client saves a service-account token to `~/.config/safekb/mcp.json` (mode 0600).
+It then prints the account it was authorized as; check that it is yours. There is no default URL.
+
+Last, it chooses where this machine keeps the keys of new seal roots (see [Where secrets are kept](#where-secrets-are-kept)).
+With a system keyring that is the choice. Without one, as on most servers, it warns and asks before it
+uses key files. `npx -y @safekb/mcp --configure` makes the same choice again without re-authorizing.
+A client authorized before this choice existed makes it by itself on its next start when the system
+keyring works; only key files need `--configure`, because they need your agreement.
+
+How the token gets to the client: the page never sees it. The page hands the client a single-use code
+(valid for two minutes), and the client redeems that code itself, proving with a secret it never wrote
+anywhere that it is the process that started the flow. The URL in the browser launcher's arguments is
+readable by other users of the machine, so it holds nothing that completes the flow; the pairing code
+is what ties your sign-in to your terminal. Every authorization creates its own token: authorizing
+again never changes the token or the spaces of another client. Revoke one under Settings → service
+accounts.
+
+Claude Code:
+
+```sh
+claude mcp add safekb -- npx -y @safekb/mcp
+```
+
+Claude Desktop and Cursor (`mcpServers` in their MCP config file):
+
+```json
+{ "mcpServers": { "safekb": { "command": "npx", "args": ["-y", "@safekb/mcp"] } } }
+```
+
+## Options
+
+| Flag | Environment | Meaning |
+| --- | --- | --- |
+| `--url <api url>` | `KB_API_URL` | API base URL. Otherwise the URL saved by `--authorize`. 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 `--configure` chose, if any. |
+| `--sealed-only` | | Expose only the sealed tools; the hosted tools are not proxied. |
+| `--authorize` | | Authorize in the browser and write the token file, then choose the key store. |
+| `--configure` | | Choose 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. |
+| `--sidecar-socket <path>` | `SAFEKB_SIDECAR_SOCKET` | The sidecar's socket. Default `sidecar.sock` next to the token file. |
+| | `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. |
+
+The client refuses to start when the token file or a keyring file is readable by group or others,
+when `--url` names another origin than the token's, when the hosted endpoint cannot be reached, or
+when a hosted tool has the name of a sealed tool.
+
+A hosted tool call that gets no answer (timeout, connection lost) is reported as *sent but not
+confirmed*: it may have run, and it is not sent again. Check the state before repeating it.
+
+## Sealed documents
+
+A **seal root** is a sealed folder (one secret opens everything in it) or a standalone sealed document.
+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`,
+  `update_sealed_document`, `replace_in_sealed_document`, and the move, archive, delete, export,
+  attachment and deposit tools.
+- `lock_sealed`, the idle timeout, or the end of the process forget the keys.
+
+## 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`.
+
+| `store` | What is kept | Where | At rest |
+| --- | --- | --- | --- |
+| `system` | a generated key | the operating system's keyring: Keychain (macOS), Credential Manager (Windows), Secret Service (Linux) | encrypted by the system |
+| `file` | a generated key | a file (mode 0600) in the keyring directory | not encrypted |
+| `sidecar` | a passphrase you type | the memory of a separate process, for a time you choose | nowhere |
+| `default` | | whichever of `system` and `file` `--configure` chose | |
+
+`key_out_path` still writes a key file to a path of your choice, and `passphrase` still takes one as
+text (which then is in the conversation transcript).
+
+The system keyring is used only where `--configure` found it working. On Linux that means a running
+Secret Service (GNOME Keyring, KWallet, KeePassXC); the kernel keyring is never used, because it
+forgets its content at logout. Keys are kept there with [`@napi-rs/keyring`](https://github.com/Brooooooklyn/keyring-node).
+
+### The sidecar
+
+The sidecar keeps passphrases out of files, out of the keyring and out of the conversation. Run it in
+a terminal of its own:
+
+```sh
+npx -y @safekb/mcp --sidecar
+```
+
+- `add <root id> [minutes]` asks for the root's secret without showing it and holds it for that long
+  (default 15 minutes). The time is fixed when you type the secret: use does not extend it.
+- `list`, `drop <root id>`, `drop all`, `quit`.
+- 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.
+
+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.
+
+## Sealed credentials
+
+A sealed credential belongs to a seal root. 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.
+- `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
+  changed fields until a signed save accepts it (`accept_visible_changes`).
+
+### Migrating server-encrypted credentials
+
+`migrate_credentials_to_sealed` turns every credential the token can see into a sealed one. 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
+   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
+   readable by the server and searchable. Run with `dry_run: false` and
+   - `unflagged_notes: "sealed"` or `"visible"` for notes without a flag (no default), and
+   - each flagged credential in `sealed_notes_ids` or `visible_notes_ids`.
+3. Before a credential is sent, its ciphertext is opened with the root key and compared with the dry
+   run. After the run the report counts `sealed_and_verified`, `sealed_but_unverified` and
+   `not_migrated`. Only when the last two are zero is the migration finished.
+4. A run can be repeated: sealed credentials are re-verified, not rewritten, and history left behind by
+   an interrupted run is purged. A credential that changed since the dry run needs a new dry run.
+
+Old database and storage backups keep the server-encrypted copies until they age out.
+
+## What sealing does not protect
+
+- 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.
+- A compromised local machine, or a malicious server serving stale data.
+- Metadata: existence, sizes, timestamps, tree position.
+
+## License
+
+Proprietary: free to install and run for connecting to a SafeKB service you are authorized to use. See [LICENSE](LICENSE); bundled open-source components are listed in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,121 @@
+# Third-party notices
+
+The distributed file `dist/safekb-mcp.js` bundles the components below. Each stays under its own license.
+
+## @noble/curves
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+
+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.```
+
+## @noble/ed25519
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2019 Paul Miller (https://paulmillr.com)
+
+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.```
+
+## @noble/hashes
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+
+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.```
+
+## hash-wasm
+
+```
+MIT License
+
+Copyright (c) 2020 Dani Biró
+
+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.
+
+Embedded C implementations might use other, similarly permissive licenses.
+Check the beginning of the files from the /src directory.
+
+Special thank you to the authors of original C algorithms:
+- Alexander Peslyak <solar@openwall.com>
+- Aleksey Kravchenko <rhash.admin@gmail.com>
+- Colin Percival
+- Stephan Brumme <create@stephan-brumme.com>
+- Steve Reid <steve@edmweb.com>
+- Samuel Neves <sneves@dei.uc.pt>
+- Solar Designer <solar@openwall.com>
+- Project Nayuki
+- ARM Limited
+- Yanbo Li dreamfly281@gmail.com, goldboar@163.comYanbo Li
+- Mark Adler
+- Yann Collet
+```