@shieldfive/mcp 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to `@shieldfive/mcp` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.0 — unreleased
+
+Vault tools. The server can now work on a ShieldFive vault through an **agent
+grant**: a connection the user creates in ShieldFive → Settings → AI
+assistants, limited to chosen folders and permissions, expiring (at most 90
+days), revocable, audited, and enforced by the server on every request.
+
+### Added
+
+- `vault_list_files`, `vault_search_files`, `vault_storage_stats`,
+  `vault_find_duplicates` and `vault_read_file` (read), and `vault_rename`,
+  `vault_move`, `vault_create_folder` and `vault_trash` (organize). They are
+  registered only when a connection is configured.
+- `npx @shieldfive/mcp login | logout | status`. The connection string is
+  stored in the OS keychain through `@napi-rs/keyring`, with `SHIELDFIVE_GRANT`
+  as the fallback for headless use.
+- Decryption of all three vault formats (post-quantum hybrid, AES-GCM v1 and
+  legacy v0) in memory, through `@shieldfive/crypto`. Names are decrypted on a
+  worker pool and cached in memory.
+- Progress notifications for name decryption and duplicate hashing.
+- Every vault result is marked as data rather than instructions. File contents
+  are fenced with a random marker the file cannot close.
+
+### Changed
+
+- **The security boundary is restated, not removed.** 0.2.0 held no credential
+  and made no network request. That still holds for the local tools, which
+  import nothing from the vault half, so a server with no connection behaves as
+  before. The vault half talks to one https origin with one scoped credential.
+  `test/boundary.test.mjs` asserts the new lines: network access only in
+  `vault/api.mjs`, no filesystem access in any vault module, no cipher outside
+  `@shieldfive/crypto`, no account credential anywhere.
+- A server started with a connection and no roots registers only the vault
+  tools.
+
 ## Unreleased
 
 ## 0.2.0 - 2026-09-16

package/README.md

@@ -1,28 +1,156 @@
 # @shieldfive/mcp
 
-A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an
-AI assistant manage files on your own machine: find duplicates by content, find
-what is large or stale, and move, rename or trash them.
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets
+Claude, ChatGPT, Cursor or a local model tidy two things:
 
-It holds no ShieldFive credential, makes no network request, and does not import
-`@shieldfive/crypto`. Those are not gaps to be filled in a later version. They
-are the security boundary, and the section below explains what they cost you.
+- **your ShieldFive vault**: find duplicates, see what takes the space, rename,
+  move, and move to the Bin. It works on the folders you grant, decrypts on your
+  machine, and every change can be undone;
+- **folders on your own disk**: the same jobs, with no network access at all.
 
-```sh
-npx @shieldfive/mcp ~/Documents ~/Downloads
-```
+ShieldFive's servers never see a file name or a byte of content in the clear,
+and that holds with this server running too. Decryption happens inside this
+process, on your computer. What the assistant then does with what it reads is a
+separate question, answered under [Security model](#security-model).
 
-## Install
+<!-- DEMO: a 40-second screen recording of a duplicate-cleanup session in Claude
+Desktop: "find duplicates in my Photos" → groups with sizes → "trash the copies"
+→ preview → confirm → the items appear in ShieldFive's Bin → one is undone from
+Settings → AI assistants. Record against a demo vault, never a real one. -->
+
+## Connect your vault in 60 seconds
 
 Requires Node 20 or newer.
 
+1. In ShieldFive, open **Settings → AI assistants → Connect an assistant**.
+   Choose the folders, *Read only* or *Read and organize*, and an expiry (1 hour
+   to 90 days). Copy the connection string. It is shown once.
+2. Store it in your system keychain:
+
+   ```sh
+   npx -y @shieldfive/mcp login
+   ```
+
+3. Add the server to your assistant. For Claude Desktop, add this to
+   `claude_desktop_config.json` (Cursor uses the same block in `~/.cursor/mcp.json`):
+
+   ```json
+   {
+     "mcpServers": {
+       "shieldfive": { "command": "npx", "args": ["-y", "@shieldfive/mcp"] }
+     }
+   }
+   ```
+
+   For Claude Code: `claude mcp add shieldfive -- npx -y @shieldfive/mcp`
+
+Restart the assistant and ask it to *find duplicates in my vault*.
+
+`npx @shieldfive/mcp status` shows which connection is configured and whether
+ShieldFive still accepts it. `npx @shieldfive/mcp logout` removes it from the
+keychain. Revoking it in ShieldFive is what cuts off access everywhere.
+
+For CI or a machine without a keychain, set `SHIELDFIVE_GRANT` to the connection
+string instead. Anything that can read the server's environment can then read
+the connection, so prefer the keychain wherever there is one.
+
+## Security model
+
+In plain terms:
+
+- **The connection string holds two things.** A *token* the server checks on
+  every request, and a *secret* that never leaves your machine. ShieldFive stores
+  only a hash of the token and has never seen the secret.
+- **The secret opens only the folders you chose.** When you create a connection,
+  your browser wraps those folders' keys under a key derived from the secret. It
+  wraps nothing else: not your vault root key, not your password, not your
+  post-quantum secret key. Subfolders open through the vault's normal folder-key
+  chain. A folder you did not choose cannot be opened with anything this server
+  holds.
+- **ShieldFive enforces scope, expiry and revocation on every request.** The
+  checks in this process only produce clearer errors; the server is the
+  boundary. Revoking a connection makes its next request fail. Nothing is
+  cached that would outlive a revocation.
+- **Decryption happens here, in memory.** No plaintext, key or ciphertext is
+  written to disk. The vault modules do not import the filesystem, and a test
+  asserts that.
+- **Nothing is deleted.** `vault_trash` moves items into a folder in your Bin
+  that belongs to the connection. There is no permanent-delete tool, and the
+  API a connection can reach has no delete route. Every rename, move and trash
+  appears in *Settings → AI assistants → Activity* with an Undo button.
+- **Every change is previewed first.** Mutating tools report a plan, and the
+  confirmed call must carry that plan's token and is refused if the items
+  changed in between.
+
+What this does not protect:
+
+- **Your AI provider sees what the assistant reads.** File names, and the
+  contents of files the assistant opens, go to the assistant, and for a cloud
+  assistant that means to its provider, like the rest of your conversation. The
+  only way to avoid that is a local model.
+- **Revoking cannot un-read.** Anything the assistant has already read stays
+  read. Nothing else survives it: file contents are streamed through
+  ShieldFive on each request, so there is no download link to outlive a
+  revocation.
+- **A connection is built from what the server shows your browser when you
+  create it.** Every later extension is checked against your own keys, so a
+  compromised server cannot widen a connection afterwards. At the moment of
+  creation, though, a compromised server could mislabel which folder you
+  picked.
+- **A copied connection string is a live key** to the folders it covers until
+  it expires or you revoke it. Keep it in the keychain.
+- **Files can contain instructions aimed at the assistant.** This server marks
+  every name and file content as data, fences file contents in a block the file
+  cannot close, caps `vault_trash` at 50 items per call, requires a preview for
+  every change, and keeps every change undoable. A model can still be talked
+  into a reversible mistake inside the folders you granted.
+
+The full design, including the threat model and the reasoning behind each
+decision, is in
+[`docs/mcp-grants-design.md`](https://github.com/shieldfive/web/blob/main/docs/mcp-grants-design.md).
+
+## Vault tools
+
+Registered only when a connection is configured. Everything below names things
+by id; paths are for people.
+
+| Tool | Needs | What it does |
+|---|---|---|
+| `vault_list_files` | read | files and folders in scope, with decrypted names, paths, sizes, dates |
+| `vault_search_files` | read | by name, path, extension, size or date, run locally over decrypted names |
+| `vault_storage_stats` | read | totals, the biggest folders and files, a breakdown by type |
+| `vault_find_duplicates` | read | same-size files decrypted in memory and compared by SHA-256; budgeted, and says when a result is a lower bound |
+| `vault_read_file` | read | text files as fenced, untrusted content (up to 1 M characters); other types return details only |
+| `vault_rename` | organize | rename a file or folder |
+| `vault_move` | organize | move into another folder in scope |
+| `vault_create_folder` | organize | create a folder in scope |
+| `vault_trash` | organize | up to 50 items into the connection's folder in the Bin |
+
+Limits a user may meet:
+
+- **Post-quantum files uploaded from a phone or the CLI** show as
+  `readable: false` until you next open ShieldFive on the web, which adds the key
+  the connection needs. Files uploaded in the web app are ready straight away.
+- **The first listing of a large vault takes a while.** Each name costs about
+  70 ms of Argon2id, spread over your CPU cores (about 20 seconds for 2,000
+  names on 8 cores). Names are cached in memory for the rest of the session.
+- **Items at the very top of a whole-vault connection** can be read and moved
+  into a folder, but not renamed in place, and nothing can be moved to the top.
+  Their names are sealed under your vault root key, which a connection never
+  holds.
+- **Uploads are not available yet.** The design allows them, but they ship
+  after the read and organize tools have been in use for a while.
+
+## Local files
+
+Every path after the package name is a **root**. The local tools can read and
+write inside those directories and nowhere else, and make no network request.
+
 ```sh
-npm install -g @shieldfive/mcp
+npx @shieldfive/mcp ~/Documents ~/Downloads
 ```
 
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
+In `claude_desktop_config.json`:
 
 ```json
 {
@@ -35,10 +163,9 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-Every path after the package name is a **root**. The server can read and write
-inside those directories and nowhere else. There is no default root and no
-override flag — a server started with no roots will refuse every call and tell
-you so.
+With a connection configured and no roots, only the vault tools are registered.
+With roots and no connection, only the local tools are, and the server behaves
+exactly as 0.2.0 did. With both, you get both.
 
 `SHIELDFIVE_MCP_ROOTS` adds roots as well — the two are combined, not
 alternatives — as a list separated by your platform's path separator (`:` on
@@ -51,7 +178,7 @@ SHIELDFIVE_MCP_ROOTS="/Users/you/Documents:/Volumes/Archive" npx @shieldfive/mcp
 Whitespace around a root is ignored. In a path given to a tool it is not: there,
 every character is part of the path.
 
-## See it work first
+### See it work first
 
 ```bash
 npm run demo
@@ -63,33 +190,19 @@ a two-year-old PDF — runs the read tools over them, previews a trash call, the
 confirms it and shows the manifest. It touches nothing outside that directory
 and removes it at the end (`--keep` leaves it in place).
 
-## What this cannot do
-
-**It cannot see your ShieldFive vault.** Not the file list, not the names, not
-the sizes. It will not tell you whether a local file is already backed up,
-because it has no way to know and it is not permitted to guess.
-
-That is a deliberate trade. The alternative was to authenticate with a full
-ShieldFive account JWT — the only credential the vault API accepts. That token
-also opens `/api/vault-key`, which returns your wrapped root key and an ML-KEM
-public key, and every content-download route, and **none of it can be scoped
-away**, because no scoped vault credential exists. A server holding that token
-would be *declining* to read your files rather than being *unable* to, with the
-difference resting on a client-side denylist and on nothing else on your machine
-reading the token file. A server holding no token cannot read them at all.
-
-When a scoped, metadata-only key exists, vault tools can be added behind it.
-Until then this is a local file manager that happens to be published by the
-people who make an encrypted vault.
-
-**It cannot stop the results from reaching your AI provider.** This server
-makes no network request, and that is worth exactly what it says and no more:
-everything it returns — paths, file names, sizes, dates, the digests it
-reports — goes back to the AI client that called it, and if that client is a
+## What the local tools cannot do
+
+**They cannot tell you whether a local file is already in your vault.** Matching
+a local name and size against a vault listing is how a tool deletes the only
+copy of something, and this server will not guess.
+
+**They cannot stop the results from reaching your AI provider.** The local
+tools make no network request, and that is worth exactly what it says and no
+more:
+everything they return — paths, file names, sizes, dates, the digests they
+report — goes back to the AI client that called it, and if that client is a
 cloud assistant, those names travel to the assistant's provider like the rest
-of your conversation. The server's silence is not the client's. Choose roots on
-that basis: point it at the folders you would be willing to describe out loud,
-and it will never see anything else.
+of your conversation. Choose roots on that basis.
 
 **It will never infer that two files are the same from their names and sizes.**
 Duplicate detection reads both files and compares a full SHA-256 of their
@@ -143,7 +256,7 @@ naming what changed. A token performs one change and expires after ten minutes.
 So a directory that grew, a destination that appeared, or a path that now points
 at a different file stops the call instead of silently widening it.
 
-## Tools
+## Local tools
 
 | Tool | Reads | Writes |
 |---|---|---|
@@ -290,7 +403,7 @@ renames, and a file created in that instant would be replaced.
 
 ## What the tests assert
 
-`npm test` runs 161 tests. The ones worth knowing about:
+`npm test` runs 183 tests. The ones worth knowing about:
 
 - A symlink pointing out of a root is refused, on both the read and the write
   side, and so is a dangling symlink on a write path.
@@ -310,18 +423,33 @@ renames, and a file created in that instant would be replaced.
   replaced.
 - A cancelled request moves nothing, and a trash batch cancelled midway says
   exactly what it moved.
-- No file under `src/` imports a networking module, calls `fetch`, spawns a
-  subprocess, or reads any environment variable other than
-  `SHIELDFIVE_MCP_ROOTS`.
-- A real MCP client over a real stdio transport sees nine tools and no vault
-  tool, including when the server is started through a symlink the way npm
-  installs it.
-
-The network assertion has a limit worth stating: it proves nothing in `src/`
-reaches the network. It does not prove the dependency tree is network-free —
-`@modelcontextprotocol/sdk` ships HTTP transports for other people's servers,
-and claiming otherwise would be false. What closes that gap is that `server.mjs`
-imports the stdio transport and no HTTP one, which is also asserted.
+- Only `src/vault/api.mjs` calls `fetch`, and only to an https ShieldFive
+  origin. No local-tool module imports anything from the vault half, no file
+  under `src/` spawns a subprocess, and the only environment variables read are
+  `SHIELDFIVE_MCP_ROOTS`, `SHIELDFIVE_GRANT` and `SHIELDFIVE_API_URL`.
+- The vault modules import no filesystem module, so decrypted data cannot be
+  written to disk. No module uses a cipher, HMAC or KDF of its own. All
+  cryptography comes from `@shieldfive/crypto`.
+- Against an in-memory ShieldFive that serves real ciphertext in all three vault
+  formats, over a real MCP client:
+  - files decrypt through the grant's keys only, and nothing outside the scope
+    is listed, read or even requested;
+  - a revoked or expired connection fails the very next call;
+  - renames and moves re-seal names and keys so the owner's own keys still
+    open them;
+  - the grant secret and token never appear in any request body or path.
+- A file whose contents tell the assistant to trash everything comes back
+  inside a fence it cannot close. Reading it issues only reads, and a 51-item
+  trash call is refused.
+- A real MCP client over a real stdio transport sees exactly the nine local
+  tools when no connection is configured, including when the server is started
+  through a symlink the way npm installs it.
+
+The network assertion has a limit worth stating: it proves what `src/` does,
+not what the dependency tree could do. `@modelcontextprotocol/sdk` ships HTTP
+transports for other people's servers. What closes that gap is that
+`server.mjs` imports the stdio transport and no HTTP one, which is also
+asserted.
 
 ## Limits
 

package/SECURITY.md

@@ -40,17 +40,21 @@ shipped the fix.
 ## Scope
 
 In scope: this package's own source — path containment, the walk, the mutating
-tools, the trash, the MCP surface, and the claims its README makes.
+tools, the trash, the vault tools and how they handle grant keys, names and
+decrypted content, the MCP surface, and the claims its README makes.
 
 Out of scope for this repository, with the right destination:
 
 - The ShieldFive vault, web application and API — `security@shieldfive.com`,
   same address, different codebase.
-- `@shieldfive/crypto` — its own repository. **This package does not depend on
-  it**, and a test asserts no `@shieldfive/*` or `@supabase/*` package is a
-  dependency.
-- `@modelcontextprotocol/sdk` and `zod`, this package's only two dependencies —
-  report upstream. A vulnerability in how *this* package uses them is in scope.
+- The agent-grant API and its enforcement (scope, expiry, revocation, the
+  audit log) — `shieldfive/web`, same address.
+- `@shieldfive/crypto` — its own repository. The vault half depends on it for
+  every cryptographic operation; a test asserts no module here implements a
+  cipher, HMAC or KDF of its own.
+- `@modelcontextprotocol/sdk`, `zod`, `libsodium-wrappers-sumo` and
+  `@napi-rs/keyring` — report upstream. A vulnerability in how *this* package
+  uses them is in scope.
 
 ## Threat model
 
@@ -76,8 +80,13 @@ has.
 | An assistant acting without the user seeing the plan | Mutating tools are inert without `confirm: true` and report what they would displace as well as what they would move | yes |
 | An oversized argument | `limit`, `max_files`, `max_files_hashed`, `paths`, path length and `new_name` are capped at the MCP schema and again in the handler; values echoed in a refusal are cut short | yes |
 | A cancelled request still changing files | Nothing starts once a request is cancelled; a trash batch stops between items and says what moved; the outcome is logged, because the SDK sends no response to a cancelled request | yes |
-| Credential exposure in this code | No credential is read or stored. `SHIELDFIVE_MCP_ROOTS` is the only environment variable read | yes |
-| Exfiltration over the network | No networking module imported, `fetch` never called; the transport is stdio | yes, for this package's source |
+| Credential exposure in this code | The only credential is an agent grant, read from `SHIELDFIVE_GRANT` or the OS keychain; never logged, never returned, never written to a file. The only environment variables read are `SHIELDFIVE_MCP_ROOTS`, `SHIELDFIVE_GRANT` and `SHIELDFIVE_API_URL`. No account password, service key or vault-key route is referenced anywhere | yes |
+| Network access | Only `vault/api.mjs` calls `fetch`, only to an https ShieldFive origin (or localhost for development). Local tools import nothing from the vault half; the transport is stdio | yes, for this package's source |
+| A grant opening more than its scope | Keys come only from the grant's own wraps (AAD-bound to grant, kind and object) and the folder chain below them. The server enforces scope on every request; local checks only produce clearer errors | yes, against an in-memory server with real ciphertext |
+| Revocation not taking effect | Every tool call re-fetches the grant and its listing; file contents are streamed through the API per request (no storage URL is ever held); nothing that would outlive a revocation is cached | yes |
+| Decrypted data reaching disk | Vault modules import no filesystem module; plaintext exists only in memory for the duration of a call; decrypted names are cached in memory only | yes |
+| Prompt injection through names or file contents | Names are stripped of control and bidi characters; every result is marked as data; file contents are fenced with a random marker the file cannot close; every change needs a preview and its plan token; `vault_trash` is capped at 50 items; nothing is ever deleted and every change is undoable by the owner | yes, with an injection fixture |
+| A write the owner cannot read back | Names are re-sealed as v6 envelopes under the destination folder key and content keys re-wrapped under it; a name that failed to decrypt is never re-sealed | yes, the owner's keys re-open every write |
 | Credential exposure via a subprocess | No subprocess is spawned at all. Spawning `sf` would inherit `SF_PASSWORD` from the environment whether or not this code named it | yes |
 
 ## Known limits
@@ -139,6 +148,16 @@ has.
   import would evade it.
 - **File paths reach the model.** If a path is itself sensitive, do not give
   this server the root it sits in.
+- **Everything the vault tools return reaches the model, and so its provider.**
+  A grant limits which folders the assistant can open; it cannot limit what the
+  assistant's provider sees of what was opened. Revocation cannot un-read.
+- **A connection string is a bearer credential plus its key.** Held by anyone,
+  it gives that connection's access until it expires or is revoked. In the
+  keychain it is protected like any other stored secret; in `SHIELDFIVE_GRANT`
+  it is readable by anything that can read the process environment.
+- **Instruction-following is the model's, not this server's.** The fencing and
+  caps above bound the damage of an injected instruction to reversible changes
+  inside the granted folders; they do not make a model ignore text.
 - **Windows is untested.** No POSIX-only API is used and paths go through
   `node:path`, but nobody has run it there, and the cross-device tests run only
   on macOS.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@shieldfive/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
-  "description": "Model Context Protocol server for local file management. Finds duplicates, large files and stale files across the drives you allow it, and reorganises them. Holds no ShieldFive credential and makes no network calls.",
+  "description": "Model Context Protocol server for your ShieldFive vault and local files: find duplicates, reclaim space and reorganise, with decryption on your machine and scoped, revocable, audited access.",
   "license": "Apache-2.0",
   "author": "Cho Garcia <security@shieldfive.com>",
   "homepage": "https://github.com/shieldfive/mcp",
@@ -14,13 +14,17 @@
     "url": "https://github.com/shieldfive/mcp/issues"
   },
   "keywords": [
-    "shieldfive",
-    "mcp",
-    "model-context-protocol",
     "claude",
-    "filesystem",
+    "disk-space",
     "duplicate-files",
-    "disk-space"
+    "encryption",
+    "end-to-end-encryption",
+    "filesystem",
+    "mcp",
+    "model-context-protocol",
+    "post-quantum",
+    "shieldfive",
+    "vault"
   ],
   "bin": {
     "shieldfive-mcp": "src/server.mjs"
@@ -29,21 +33,27 @@
     "access": "public"
   },
   "files": [
-    "src",
+    "CHANGELOG.md",
+    "LICENSE",
     "README.md",
     "SECURITY.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "server.json",
+    "src"
   ],
   "engines": {
     "node": ">=20"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "demo": "node demo/run-demo.mjs"
+    "demo": "node demo/run-demo.mjs",
+    "build:mcpb": "node scripts/build-mcpb.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "@napi-rs/keyring": "^2.1.0",
+    "@shieldfive/crypto": "1.0.0-rc.5",
+    "libsodium-wrappers-sumo": "^0.8.4",
     "zod": "^3.25.0"
-  }
+  },
+  "mcpName": "io.github.shieldfive/mcp"
 }

package/server.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.shieldfive/mcp",
+  "title": "ShieldFive",
+  "description": "Tidy your end-to-end encrypted ShieldFive vault and local folders: duplicates, space, reorganising. Decrypts on your machine; scoped, revocable access.",
+  "version": "0.3.0",
+  "repository": {
+    "url": "https://github.com/shieldfive/mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://shieldfive.com",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@shieldfive/mcp",
+      "version": "0.3.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "SHIELDFIVE_GRANT",
+          "description": "Connection string from ShieldFive → Settings → AI assistants. Optional: `npx @shieldfive/mcp login` stores it in the OS keychain instead.",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "SHIELDFIVE_MCP_ROOTS",
+          "description": "Local directories the local tools may use, separated by the platform path separator. Optional.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}