sealnet-mcp 0.5.0 → 0.6.0

package/README.md

@@ -8,15 +8,17 @@ Model Context Protocol (MCP) server for **SEAL**.
 
 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 link is never written into the conversation; on the file channel the receipt names the file, and an agent that can read files on that machine can read it.
+- **inbox mode (default once connected)**: after `seal_pair` (or with `SEAL_OWNER` set to the address of the user's inbox) the file lands in the user's SEAL inbox on box.seal.net. Nothing is copied anywhere; the model gets a handle and a receipt. Every seal this server creates, in any mode, also appears there, where the user can manage and revoke it.
+- **handoff mode (default otherwise)**: 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 link is never written into the conversation; on the file channel the receipt names the file, and an agent that can read files on that machine can read it.
 - **forward mode (explicit opt-in)**: model receives `{ handle, share_url, expires_at, max_reads, mode, delivered }` in `tool_result`; the link opens only with the recipient's X25519 key and also lands in the recipient's inbox (`seal_inbox`). Requires short TTL (≤30m), `max_reads=1`, mandatory `to` (recipient address). 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_share(path, mode='inbox'\|'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: inbox once connected, else handoff; without `expire`, 1d in the inbox, 5m for a handoff, or 1d for one 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, from?)` / `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; once connected the request also waits in the user's inbox (`from=owner`, or `from=anyone` for a plain link). Returns the path of a 0600 file, never the value |
+| `seal_pair(name?, wait=true)` | Connect this agent to the user's SEAL inbox, once: the user opens a page, compares three emoji and connects; the chat then shows the inbox's three emoji. After it `seal_share` sends to the inbox by default |
 | `seal_open(url\|item, 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). `item` is an inbox handle instead of a link |
 | `seal_inbox(wait?)` | Seals other agents or people sent to this server's key (its address): handles, the sender's three emoji and name, never a link. `seal_share mode=forward to=<address>` puts a link there; `wait` (0 to 300 s) waits for something new |
 | `seal_run(command, secrets, cwd?, timeout?)` | Run a program with secrets from links or inbox items in its environment, through the `seal` CLI (`seal run --redact`): every value is replaced with `[sealed:NAME]` in the output that comes back, and none enters this server. Needs `seal` on PATH (`run_cli_missing` otherwise). Not a sandbox: a program that prints a value transformed escapes the redaction |
@@ -25,7 +27,7 @@ When an MCP-connected AI agent (Claude Desktop, Cursor, Cline, etc.) creates a S
 
 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.
+Large transfers report `notifications/progress` when the host sends a `progressToken`. Where the host supports URL-mode elicitation, `seal_request` and `seal_pair` show the page link through it and wait in one call; otherwise they return the link and a second call waits.
 
 ## The agent's key and state
 
@@ -38,6 +40,7 @@ The agent has one key: a 32-byte X25519 secret whose public half is its address
 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:
 
 - `identity` — the key itself, for incoming targeted seals
+- `owner` — the user's inbox this agent is connected to (`seal_pair`): its address and name
 - `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.
 
@@ -78,6 +81,7 @@ 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_OWNER` | `serve` | The address of the user's inbox, instead of `seal_pair`: for a cloud session with nowhere to open the page |
 | `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` | Read once, to move a state of version 0.2 |