sealnet-mcp 0.2.5 → 0.3.0

package/README.md

@@ -25,25 +25,25 @@ With SEAL Pro workload credentials (`sealpro agent enroll`, or `SEALPRO_WORKLOAD
 
 Large transfers report `notifications/progress` when the host sends a `progressToken`. Where the host supports URL-mode elicitation, `seal_request` shows the page link through it and waits in one call; otherwise it returns the link and a second call with `request` waits.
 
-## State
+## The agent's key and state
 
-All state lives encrypted at `${XDG_CONFIG_HOME}/seal-mcp/state.json` (mode `0o600`). Envelope: Argon2id KDF → AES-256-GCM cipher. Contains:
+The agent has one key: a 32-byte X25519 secret whose public half is its address (`sealnet-mcp pubkey`). It comes from, in order:
 
-- `identity` — X25519 long-term keypair for incoming targeted seals
-- `handles[]` — opaque handle → `{ seal_id, owner_token, mode, created_at }`. Each `owner_token` is full owner-capability for that seal; encrypting only `identity` and leaving tokens plain would be a security illusion.
-- `audit[]` — historical tool invocations (timestamps, handles, modes). Side-channel relevant.
+1. **`SEAL_SEED`** — how a container or a cloud session gets the same address as at home (`sealnet-mcp seed --force` prints the key to put there);
+2. **the OS keychain** — `@napi-rs/keyring` (optional dependency): Secret Service on Linux, macOS Keychain, Windows Credential Manager;
+3. **`seed`**, a 0600 file in the state directory, where there is no keychain.
 
-Passphrase delivery, in priority order:
+The first start makes the key (keychain, else the file); there is no setup step. State lives in `${XDG_CONFIG_HOME}/seal-mcp/state.json` (mode `0o600`), encrypted with a passphrase derived from the key (HKDF-SHA256 → Argon2id → AES-256-GCM). It holds:
 
-1. **OS keychain** (default) — `@napi-rs/keyring` (optional dependency) reads from the Secret Service on Linux / macOS Keychain / Windows Credential Manager. The first `serve` stores a random passphrase there itself; `sealnet-mcp init` lets you choose one instead.
-2. **`SEAL_MCP_PASSPHRASE` env var** — explicit opt-in for CI/headless. Warning logged.
-3. **Cleartext on disk** — explicit refusal even if user tries `--passphrase-file …`.
+- `identity` — the key itself, for incoming targeted seals
+- `handles[]` — opaque handle → `{ seal_id, owner_token, mode, created_at }`. Each `owner_token` is full owner-capability for that seal; encrypting only `identity` and leaving tokens plain would be a security illusion.
+- `audit[]` — historical tool invocations (timestamps, handles, modes). Side-channel relevant.
 
-With neither a keychain nor the env var (containers, CI), or with `serve --ephemeral`, the server runs **ephemeral**: identity and handles live in memory and nothing is written to disk. Handles then last until restart; seal expiry does not depend on it.
+Several MCP hosts on one machine (Claude Desktop, Claude Code, Cursor) share the key and the state: each write re-reads the file under a lock. `serve --ephemeral` (or `SEAL_MCP_EPHEMERAL=1`) keeps nothing on disk and makes a new key each start; handles then last until restart, and seal expiry does not depend on it. A state from version 0.2 moves under the key on the first start, once.
 
 ## Install + configure
 
-No setup step: the first start creates the state.
+No setup step: the first start creates the agent's key and state.
 
 Add to `~/.cursor/mcp.json` (or `claude_desktop_config.json`):
 
@@ -75,8 +75,10 @@ Environment variables consumed by the CLI:
 
 | Variable | Used by | Purpose |
 |---|---|---|
+| `SEAL_SEED` | every subcommand | The agent's key (43 base64url characters); the same address wherever it is set |
+| `SEAL_MCP_EPHEMERAL=1` | `serve` | As `--ephemeral`: a new key each start, nothing on disk |
 | `SEAL_MCP_CONFIG_DIR` | every subcommand | Override default state directory (mirrors Rust `seal-cli`'s `SEAL_CONFIG_DIR`) |
-| `SEAL_MCP_PASSPHRASE` | `serve`, `init` | Provide passphrase non-interactively (CI / headless); warning logged on every use |
+| `SEAL_MCP_PASSPHRASE` | `serve` | Read once, to move a state of version 0.2 |
 | `SEAL_MCP_BACKEND_URL` | `serve`, `doctor` | SEAL backend base URL (default `https://api.seal.net`) |
 | `SEAL_MCP_PUBLIC_HOST` | `serve`, `doctor` | Public origin for minted share URLs (default `https://seal.net`) |
 | `SEAL_MCP_DEBUG=1` | all | Include stack traces in fatal-error output (otherwise plain `error: <msg>`) |
@@ -85,10 +87,11 @@ Available subcommands:
 
 ```
 sealnet-mcp serve         # default — start the stdio MCP server (used by MCP hosts); --ephemeral keeps nothing on disk
-sealnet-mcp init          # optional: set up with a passphrase you choose
-sealnet-mcp pubkey        # print this server's X25519 public key (for senders)
-sealnet-mcp doctor        # diagnose keychain / state perms / backend reachability
-sealnet-mcp reset --force # wipe state.json + keychain entry (after passphrase loss)
+sealnet-mcp init          # optional: make the key and state without starting the server
+sealnet-mcp pubkey        # print the agent's address, its X25519 public key (for senders)
+sealnet-mcp seed --force  # print the agent's key, to set SEAL_SEED elsewhere
+sealnet-mcp doctor        # diagnose key source / keychain / file perms / backend reachability
+sealnet-mcp reset --force # wipe state.json and the key: the address is lost for good
 ```
 
 ## Development