Scoped unlock: restrict vault access to specific MCP clients

[jfomhover]

Problem

Currently, �ault unlock grants access to any MCP client that connects to the server. In environments where multiple agents or tools share a machine, there's no way to say "only allow Claude Desktop to read my vault" or "block all other clients while I'm working with Cursor."

This is a meaningful security boundary — users should be able to control which agents have access to their decrypted files.

Proposal

Two complementary approaches, building on identity signals available in the MCP protocol.

Option 1: Client-name allowlist (stdio-compatible)

During the MCP initialize handshake, clients send a clientInfo object with
ame and �ersion fields (e.g., "claude-desktop", "cursor"). The server can read this via server.getClientVersion() after connection.

UX:
`�ash

Unlock for a specific client only

vault unlock --only claude-desktop

Unlock for multiple clients

vault unlock --only claude-desktop --only cursor

Current behavior (no restriction)

vault unlock
`

Implementation sketch:

• Session file gains an optional �llowedClients: string[] field
• MCP server checks clientInfo.name against the allowlist on each tool call
• If not in the list → return a clear error: "Vault access restricted. This client is not authorized."
• �ault status shows which clients are allowed
• Audit log records clientInfo.name on every MCP operation

Tradeoffs:

• ✅ Works with stdio transport (the common case today)
• ✅ Zero friction for the connecting agent — no extra auth step
• ⚠️ clientInfo.name is self-reported by the client, so this is a trust boundary, not a cryptographic one

Option 2: Session token authentication

�ault unlock generates a unique session token. The MCP client must present this token to gain access, either via an environment variable or by calling a �ault_authenticate tool.

UX:
`�ash
vault unlock --token

Output: Session token: wv_abc123...

Set WORKSPACE_VAULT_TOKEN=wv_abc123... in your MCP client config

`

Or the agent calls �ault_authenticate with the token as its first action:
json { "tool": "vault_authenticate", "arguments": { "token": "wv_abc123..." } }

Implementation sketch:

• �ault unlock --token writes a token to the session file alongside the master key
• MCP server exposes �ault_authenticate tool or reads WORKSPACE_VAULT_TOKEN from env
• Unauthenticated tool calls return an error prompting authentication
• Token is scoped to the session TTL

Tradeoffs:

• ✅ Stronger guarantee — possession of token proves explicit authorization
• ✅ Works with any transport
• ⚠️ Requires the user to pass the token to the MCP client config (extra setup step)
• ⚠️ Agents need to handle the auth flow (call �ault_authenticate or have the token in env)

Additional context

Both options should include audit logging of the caller identity (clientInfo.name or token ID) on every operation, regardless of which approach is used.

These options are not mutually exclusive — Option 1 could ship first as a lightweight default, with Option 2 available for higher-security use cases.

References

• MCP spec lifecycle / initialize handshake: https://modelcontextprotocol.io/specification/2025-03-26/basic/lifecycle
• clientInfo sends Implementation type with
  ame, �ersion, optional itle
• RequestHandlerExtra in the SDK provides sessionId and �uthInfo per-request