sealnet-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,7 @@
+SEAL — Proprietary License
+
+Copyright (c) 2026 SEAL. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+modification, distribution, or use of this software, via any medium,
+is strictly prohibited without express written permission.

package/README.md

@@ -0,0 +1,106 @@
+# sealnet-mcp
+
+SEAL is how agents and people hand each other large files and secrets without the content passing through the chat, the model or the SEAL server.
+
+Model Context Protocol (MCP) server for **SEAL**.
+
+## Design principle: the model never holds capability by default
+
+When an MCP-connected AI agent (Claude Desktop, Cursor, Cline, etc.) creates a SEAL via this server:
+
+- **handoff mode (default)**: the share link (the key is in its fragment, there is no password) is delivered to the human user via **system clipboard** (primary) or **0o600 local file** (fallback when clipboard is unavailable — headless, SSH, WSL without display). The `tool_result` returned to the model contains **only** an opaque handle and a human-readable receipt. The model cannot exfiltrate the link because it never sees it.
+- **forward mode (explicit opt-in)**: model receives `{ handle, share_url, expires_at, max_reads, mode }` in `tool_result`; the link opens only with the recipient's X25519 key. Requires short TTL (≤30m), `max_reads=1`, mandatory `to` (recipient pubkey). Every forward is audit-logged in the encrypted state file.
+
+## Tool surface
+
+| Tool | Purpose |
+|------|---------|
+| `seal_share(path, mode='handoff'\|'forward', expire?, max_reads?, tier?)` / `seal_share(payment)` | Create a SEAL from a local file or folder (sent as one ZIP), streamed from disk. Default: handoff; without `expire`, 5m, or 1d for a handoff over 100 MB. Over 1 GB the user pays once by card (smallest tier that fits, or `tier`): the payment page goes through URL-mode elicitation, or comes back as `payment_url` and a second call with `payment` finishes the upload into the same seal |
+| `seal_request(what, kind='any'\|'secret'\|'file', where_url?, wait=true)` / `seal_request(request)` | Ask the user for a file or a secret without it passing through the chat. On the user's computer the `seal` CLI draws the system dialog (`seal request --local --json`); otherwise the user answers at `seal.net/i/<id>`, sealed to this server's key, shown with three emoji of that key. Returns the path of a 0600 file, never the value |
+| `seal_open(url, mode='metadata'\|'file'\|'inline', dir?)` | Read metadata (default — no download, no counter consumption), save to disk (`file`: streamed, verified before it gets its name, 0600, returns paths) or inline parse (whitelisted MIMEs only, ≤100 KB, refuses secrets, HTML and binary) |
+| `seal_list()` | List SEALs created by **this MCP server only** (scope: `state.json`; never reveals user's CLI seals) |
+| `seal_revoke(handle)` | Revoke by opaque handle (model never learns raw `seal_id`) |
+
+With SEAL Pro workload credentials (`sealpro agent enroll`, or `SEALPRO_WORKLOAD_ID`, `SEALPRO_WORKLOAD_SEED` and `SEALPRO_BASE_URL`) three tools appear: `seal_pro_secret_use(secret, version?)` saves a secret your organisation granted to this agent to a 0600 file and returns its path, never the value; `seal_pro_secret_request(secret, reason, ttl_seconds?)` asks a person for one, for a while, and waits for the decision; `seal_pro_file_get(seal, file?, dir?)` saves the files of a room whose key a person granted this agent, 0600 and digest-checked, and returns their paths.
+
+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
+
+All state lives encrypted at `${XDG_CONFIG_HOME}/seal-mcp/state.json` (mode `0o600`). Envelope: Argon2id KDF → AES-256-GCM cipher. Contains:
+
+- `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.
+
+Passphrase delivery, in priority order:
+
+1. **OS keychain** (default) — `keytar` (optional dependency) reads from libsecret / macOS Keychain / wincred. 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 …`.
+
+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.
+
+## Install + configure
+
+No setup step: the first start creates the state.
+
+Add to `~/.cursor/mcp.json` (or `claude_desktop_config.json`):
+
+```json
+{
+  "seal": {
+    "command": "npx",
+    "args": ["-y", "sealnet-mcp"]
+  }
+}
+```
+
+Production defaults are baked in (backend `https://api.seal.net`, share URLs on `https://seal.net`) — no env needed. Self-hosted deployments set **both** URL knobs; they are independent origins and are never derived from each other:
+
+```json
+{
+  "seal": {
+    "command": "npx",
+    "args": ["-y", "sealnet-mcp"],
+    "env": {
+      "SEAL_MCP_BACKEND_URL": "https://api.example.com",
+      "SEAL_MCP_PUBLIC_HOST": "https://example.com"
+    }
+  }
+}
+```
+
+Environment variables consumed by the CLI:
+
+| Variable | Used by | Purpose |
+|---|---|---|
+| `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_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>`) |
+
+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)
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
+## Source of truth
+
+- `docs/security/seal_phase1_plan.md` §"Phase 3 — MCP-оболочка"
+- `shared/contracts/seal_mcp.v1.json` (tool input/output schemas)
+- All cryptographic primitives are bundled into `dist/` from internal workspace packages — no algorithm code is duplicated and no external `@`-scoped dependencies are pulled at install time.