@safekb/mcp 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +44 -0
  2. package/README.md +113 -2
  3. package/THIRD-PARTY-NOTICES.md +121 -0
  4. package/dist/safekb-mcp.js +22614 -0
  5. package/package.json +39 -4
package/LICENSE ADDED
@@ -0,0 +1,44 @@
1
+ SafeKB MCP Client License
2
+
3
+ Copyright (c) 2026 Mustafa Öztürk (the "Licensor"). All rights reserved.
4
+
5
+ 1. Grant. Subject to this license, the Licensor grants you a non-exclusive,
6
+ non-transferable, revocable right to install and run unmodified copies of
7
+ this software for the sole purpose of connecting to a SafeKB service that
8
+ you are authorized to use, including a SafeKB instance operated for you
9
+ under a separate written agreement with the Licensor.
10
+
11
+ 2. Restrictions. Except where applicable law does not allow this restriction,
12
+ you may not:
13
+ (a) modify the software or create derivative works of it;
14
+ (b) redistribute, sublicense, sell, rent or lease the software, or offer it
15
+ as part of another product or service;
16
+ (c) use the software, or any part of it, to build or operate a product or
17
+ service that competes with SafeKB;
18
+ (d) remove or alter any copyright, license or attribution notice.
19
+
20
+ 3. Ownership. The software is licensed, not sold. The Licensor keeps all
21
+ rights in it that this license does not expressly grant.
22
+
23
+ 4. Your keys and data. The software keeps secrets and keys on your device.
24
+ You alone are responsible for backing them up. The Licensor cannot recover
25
+ content that was sealed with a secret you no longer hold.
26
+
27
+ 5. Third-party components. The software includes open-source components that
28
+ stay under their own licenses, listed in THIRD-PARTY-NOTICES.md. Nothing in
29
+ this license limits your rights under those licenses.
30
+
31
+ 6. Termination. This license ends automatically if you breach it. When it
32
+ ends you must stop using the software and delete your copies.
33
+
34
+ 7. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
35
+ KIND, EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY,
36
+ FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
37
+
38
+ 8. Limitation of liability. TO THE EXTENT THE LAW ALLOWS, THE LICENSOR IS NOT
39
+ LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR ANY
40
+ LOSS OF DATA, KEYS, PROFITS OR BUSINESS, ARISING FROM THE SOFTWARE OR ITS
41
+ USE. A separate written agreement between you and the Licensor, where one
42
+ exists, takes precedence over sections 7 and 8.
43
+
44
+ Other uses need a commercial license from the Licensor: https://safekb.com
package/README.md CHANGED
@@ -1,3 +1,114 @@
1
- # Temporary Holding Version
1
+ # @safekb/mcp
2
2
 
3
- 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.
3
+ Local MCP client for SafeKB (stdio). It proxies the hosted SafeKB tools and adds **sealed** documents
4
+ and folders: content is encrypted on your machine, and the server stores only ciphertext.
5
+
6
+ Needs Node 20 or newer.
7
+
8
+ ## Setup
9
+
10
+ ```sh
11
+ npx -y @safekb/mcp --authorize --url <your SafeKB API URL>
12
+ ```
13
+
14
+ This opens the browser and prints a **pairing code**. Sign in on the page, choose the spaces, type the
15
+ pairing code, and the client saves a service-account token to `~/.config/safekb/mcp.json` (mode 0600).
16
+ It then prints the account it was authorized as; check that it is yours. There is no default URL.
17
+
18
+ How the token gets to the client: the page never sees it. The page hands the client a single-use code
19
+ (valid for two minutes), and the client redeems that code itself, proving with a secret it never wrote
20
+ anywhere that it is the process that started the flow. The URL in the browser launcher's arguments is
21
+ readable by other users of the machine, so it holds nothing that completes the flow; the pairing code
22
+ is what ties your sign-in to your terminal. Every authorization creates its own token: authorizing
23
+ again never changes the token or the spaces of another client. Revoke one under Settings → service
24
+ accounts.
25
+
26
+ Claude Code:
27
+
28
+ ```sh
29
+ claude mcp add safekb -- npx -y @safekb/mcp
30
+ ```
31
+
32
+ Claude Desktop and Cursor (`mcpServers` in their MCP config file):
33
+
34
+ ```json
35
+ { "mcpServers": { "safekb": { "command": "npx", "args": ["-y", "@safekb/mcp"] } } }
36
+ ```
37
+
38
+ ## Options
39
+
40
+ | Flag | Environment | Meaning |
41
+ | --- | --- | --- |
42
+ | `--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. |
43
+ | `--config <path>` | `SAFEKB_MCP_CONFIG` | Token file. Default `~/.config/safekb/mcp.json`. Use one per project for per-project access. |
44
+ | `--keyring <dir>` | `SAFEKB_SEALED_KEYRING` | Directory of sealed key files (`*.json`). No default. |
45
+ | `--sealed-only` | | Expose only the sealed tools; the hosted tools are not proxied. |
46
+ | `--authorize` | | Authorize in the browser and write the token file. |
47
+ | | `SAFEKB_SEALED_IDLE_TTL` | Seconds an unlocked seal root may stay idle. Default 900. |
48
+ | | `SAFEKB_HOSTED_TIMEOUT` | Seconds a hosted tool call may take. Default 300. |
49
+
50
+ The client refuses to start when the token file or a keyring file is readable by group or others,
51
+ when `--url` names another origin than the token's, when the hosted endpoint cannot be reached, or
52
+ when a hosted tool has the name of a sealed tool.
53
+
54
+ A hosted tool call that gets no answer (timeout, connection lost) is reported as *sent but not
55
+ confirmed*: it may have run, and it is not sent again. Check the state before repeating it.
56
+
57
+ ## Sealed documents
58
+
59
+ A **seal root** is a sealed folder (one secret opens everything in it) or a standalone sealed document.
60
+ Its secret is a generated key (default) or a passphrase.
61
+
62
+ - `create_sealed_folder` / `insert_sealed_document` with `key_out_path` write a key file (mode 0600).
63
+ The key is never returned to the model. **Back the file up: a lost secret cannot be recovered.**
64
+ - `unlock_sealed` with `secret_file`, or with only `root_id` when the key file is in the keyring.
65
+ - Then `search_sealed`, `list_sealed`, `read_sealed_document`, `get_sealed_section`,
66
+ `update_sealed_document`, `replace_in_sealed_document`, and the move, archive, delete, export,
67
+ attachment and deposit tools.
68
+ - `lock_sealed`, the idle timeout, or the end of the process forget the keys.
69
+
70
+ ## Sealed credentials
71
+
72
+ A sealed credential belongs to a seal root. Its password, TOTP seed, `sealed_notes` and the values of
73
+ sealed custom fields are encrypted on your machine; its title, username, url, tags, `notes`, visible
74
+ 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
75
+ `find_credential_duplicates` keep working. Never put a secret into `notes`.
76
+
77
+ - `insert_sealed_credential`, `update_sealed_credential`, `delete_sealed_credential`: signed by the unlocked root.
78
+ - `move_sealed_credential` hands a credential to another seal root; both roots must be unlocked.
79
+ - `reveal_sealed_credential` and `get_sealed_totp` decrypt locally. The hosted `reveal_credential` and
80
+ `get_credential_totp` cannot open a sealed credential.
81
+ - Visible fields can be edited without the secret. Such an edit is flagged (`visible_tampered`) with the
82
+ changed fields until a signed save accepts it (`accept_visible_changes`).
83
+
84
+ ### Migrating server-encrypted credentials
85
+
86
+ `migrate_credentials_to_sealed` turns every credential the token can see into a sealed one. It is
87
+ irreversible per credential: the server drops its own encrypted secrets and that credential's history.
88
+
89
+ 1. Unlock the target root, then run it with `dry_run: true` (the default). Nothing changes. It lists the
90
+ credentials, says which have notes, and flags notes that match a few secret patterns. That scan is
91
+ advisory and misses secrets.
92
+ 2. Decide every note, because today notes are encrypted and afterwards they are either sealed or
93
+ readable by the server and searchable. Run with `dry_run: false` and
94
+ - `unflagged_notes: "sealed"` or `"visible"` for notes without a flag (no default), and
95
+ - each flagged credential in `sealed_notes_ids` or `visible_notes_ids`.
96
+ 3. Before a credential is sent, its ciphertext is opened with the root key and compared with the dry
97
+ run. After the run the report counts `sealed_and_verified`, `sealed_but_unverified` and
98
+ `not_migrated`. Only when the last two are zero is the migration finished.
99
+ 4. A run can be repeated: sealed credentials are re-verified, not rewritten, and history left behind by
100
+ an interrupted run is purged. A credential that changed since the dry run needs a new dry run.
101
+
102
+ Old database and storage backups keep the server-encrypted copies until they age out.
103
+
104
+ ## What sealing does not protect
105
+
106
+ - Whatever a tool returns enters the local conversation transcript and is sent to the model provider.
107
+ The same holds for a secret passed as text; use `secret_file` or the keyring.
108
+ - A session that has unlocked a root can be tricked by content it reads into copying it elsewhere.
109
+ - A compromised local machine, or a malicious server serving stale data.
110
+ - Metadata: existence, sizes, timestamps, tree position.
111
+
112
+ ## License
113
+
114
+ 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 ADDED
@@ -0,0 +1,121 @@
1
+ # Third-party notices
2
+
3
+ The distributed file `dist/safekb-mcp.js` bundles the components below. Each stays under its own license.
4
+
5
+ ## @noble/curves
6
+
7
+ ```
8
+ The MIT License (MIT)
9
+
10
+ Copyright (c) 2022 Paul Miller (https://paulmillr.com)
11
+
12
+ Permission is hereby granted, free of charge, to any person obtaining a copy
13
+ of this software and associated documentation files (the “Software”), to deal
14
+ in the Software without restriction, including without limitation the rights
15
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
16
+ copies of the Software, and to permit persons to whom the Software is
17
+ furnished to do so, subject to the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be included in
20
+ all copies or substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
27
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
28
+ THE SOFTWARE.```
29
+
30
+ ## @noble/ed25519
31
+
32
+ ```
33
+ The MIT License (MIT)
34
+
35
+ Copyright (c) 2019 Paul Miller (https://paulmillr.com)
36
+
37
+ Permission is hereby granted, free of charge, to any person obtaining a copy
38
+ of this software and associated documentation files (the “Software”), to deal
39
+ in the Software without restriction, including without limitation the rights
40
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
41
+ copies of the Software, and to permit persons to whom the Software is
42
+ furnished to do so, subject to the following conditions:
43
+
44
+ The above copyright notice and this permission notice shall be included in
45
+ all copies or substantial portions of the Software.
46
+
47
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
48
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
49
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
50
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
51
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
52
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
53
+ THE SOFTWARE.```
54
+
55
+ ## @noble/hashes
56
+
57
+ ```
58
+ The MIT License (MIT)
59
+
60
+ Copyright (c) 2022 Paul Miller (https://paulmillr.com)
61
+
62
+ Permission is hereby granted, free of charge, to any person obtaining a copy
63
+ of this software and associated documentation files (the “Software”), to deal
64
+ in the Software without restriction, including without limitation the rights
65
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
66
+ copies of the Software, and to permit persons to whom the Software is
67
+ furnished to do so, subject to the following conditions:
68
+
69
+ The above copyright notice and this permission notice shall be included in
70
+ all copies or substantial portions of the Software.
71
+
72
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
73
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
74
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
75
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
76
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
77
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
78
+ THE SOFTWARE.```
79
+
80
+ ## hash-wasm
81
+
82
+ ```
83
+ MIT License
84
+
85
+ Copyright (c) 2020 Dani Biró
86
+
87
+ Permission is hereby granted, free of charge, to any person obtaining a copy
88
+ of this software and associated documentation files (the "Software"), to deal
89
+ in the Software without restriction, including without limitation the rights
90
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
91
+ copies of the Software, and to permit persons to whom the Software is
92
+ furnished to do so, subject to the following conditions:
93
+
94
+ The above copyright notice and this permission notice shall be included in all
95
+ copies or substantial portions of the Software.
96
+
97
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
98
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
99
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
100
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
101
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
102
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
103
+ SOFTWARE.
104
+
105
+ Embedded C implementations might use other, similarly permissive licenses.
106
+ Check the beginning of the files from the /src directory.
107
+
108
+ Special thank you to the authors of original C algorithms:
109
+ - Alexander Peslyak <solar@openwall.com>
110
+ - Aleksey Kravchenko <rhash.admin@gmail.com>
111
+ - Colin Percival
112
+ - Stephan Brumme <create@stephan-brumme.com>
113
+ - Steve Reid <steve@edmweb.com>
114
+ - Samuel Neves <sneves@dei.uc.pt>
115
+ - Solar Designer <solar@openwall.com>
116
+ - Project Nayuki
117
+ - ARM Limited
118
+ - Yanbo Li dreamfly281@gmail.com, goldboar@163.comYanbo Li
119
+ - Mark Adler
120
+ - Yann Collet
121
+ ```