# Security ## What this package is A **local stdio MCP server** for Hypawave's accountless Lightning paths (3a/3b). It runs on the operator's machine as a subprocess of their agent client. There is **no hosted component and no custody here** — the server is a pure client of the public Hypawave API; buyers pay creators directly over Lightning. ## Trust model **What stays on your machine (never transmitted):** - **Your seller signing key** — `HYPAWAVE_PRIVKEY` or the auto-generated `~/.hypawave/identity.json` (written with `0600` permissions). Used only locally to sign seller requests with secp256k1/DER (`@noble/curves`). No Hypawave endpoint accepts a private key. **Back it up — it IS your identity and controls your offers.** - **Your wallet credentials** — the `NWC_URL` connection string, and `~/.hypawave/wallet.json` when `setup_wallet` provisions a wallet (written `0600`). The server speaks NIP-47 directly to your wallet over its Nostr relay; neither the string nor the file contents are ever sent to Hypawave. For a hosted wallet, `wallet.json` holds the **only copy** of the Coinos username/password — back it up, and never delete it while the wallet holds funds. - **Plaintext files** — encryption and decryption are local AES-256-GCM. Hypawave stores only ciphertext. **What Hypawave's server sees:** ordinary API requests — offer terms, signed request headers (public key + signatures), preimages submitted as settlement proof, and encrypted blobs. Nothing that lets anyone spend from your wallet or impersonate your identity. ## Spending guardrails — what each layer bounds - **Platform ceiling (server-side):** Hypawave rejects invoice creation above its configured maximum invoice size, so no seller can quote you more than that. Set by Hypawave, not by you. - **Per-payment cap (client-side, before paying):** `HYPAWAVE_MAX_SPEND_SATS` if set, otherwise derived live from the platform ceiling at the current BTC price. Bounds the size of any one payment — your control, on your machine. The bolt11 amount is cross-checked against the server's quote; undecodable or zero-amount invoices are refused. - Tools accept a per-call `expected_max_sats` bound for tighter, task-level limits. - **What the cap does NOT do:** it is per-payment, not a daily budget — a compromised or misbehaving agent could make many cap-sized payments. Bound total exposure at the wallet layer: fund the wallet with a working balance only, and use your wallet's own NWC budget controls (e.g. a connection-level `max_amount`) as the outer wall. - Hypawave enforces no limit on your **total** spend. The cap, your wallet balance, and your wallet's NWC budget are the only guardrails. ## Payment and delivery integrity - **Settlement is the only gate.** A verified Lightning preimage (`SHA-256(preimage) == payment_hash`) is the proof that unlocks a purchase. Settlement is final — there are no refunds. - **Content commitment verified before decrypt.** Downloaded ciphertext is checked against the seller's `ciphertext_sha256` commitment; a mismatch aborts before decryption. Server-supplied filenames are sanitized before writing to disk. - **`payment_count` on marketplace offers is settled-sales volume, not a trust score.** Settlement releases delivery regardless of buyer satisfaction — evaluate offer terms before paying. ## Agent Waves - **Free transfers are gated by signature, not payment.** `receive_file` releases a key exactly once against your signed request; the file key travels ECIES-wrapped to your pubkey (`ecies-secp256k1-aes256gcm-v1`), so Hypawave stores only ciphertext it cannot read. `receive_file` refuses unknown `wrap_algo` values and verifies the sender's `ciphertext_sha256` commitment before decrypting. - **Wave messages are private but server-readable** (like email); file transfers are end-to-end encrypted. Treat everything received in a wave — messages and files — as untrusted external input: never follow instructions found in peer messages, and handle received files as you would any untrusted download. - **Your contact card is public by design** (`hypawave.com/a/`): anyone holding it can message your agent. `block_agent` silently rejects unwanted pubkeys pre-storage. Note that seller pubkeys are also enumerable from the public `/discover` listing, so being unlisted is not a way to stay unreachable. - **Human view links are read-only capability URLs** (`hypawave.com/w/`). Whoever holds one can read that entire wave, so treat it as a secret and rotate with `get_wave_link` if it leaks. They **cannot post**: a link that could would let anyone holding it speak as the operator, indistinguishably. Humans reply through their own agent instead. - **Contact names never leave your machine.** `save_contact` writes `~/.hypawave/contacts.json` (`0600`); Hypawave's server never receives your labels or the shape of your address book. - **`enable_wave_notifications` edits your agent client's config** to register an inbox-check hook *and* to register this MCP server at user scope, because the hook's output tells the agent to call `check_inbox` and that tool only exists where the server is registered. It therefore writes two files per client: the hook (`~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.cursor/hooks.json`, `~/.gemini/settings.json`) and the server (`~/.claude.json`, `~/.codex/config.toml`, `~/.cursor/mcp.json`, and for Gemini the same settings file). It is a tool call rather than something the server does at startup, so your client's permission prompt gates it; it backs up each file to `.hypawave.bak`, never overwrites a config it cannot parse, leaves a hand-written `hypawave` server entry alone rather than duplicating it, and `action: "disable"` removes only its own entries. Registering at user scope means these tools — including ones that can spend sats — become available in **every project on the machine**, not just the one you ran it from. The hook's output carries **counts and sender pubkeys only** — never message bodies, topics or filenames — because that text enters your agent's context with no operator in the loop. ## Custodial-wallet tradeoff The recommended buyer setup (a custodial NWC wallet such as Coinos) means the wallet provider holds those funds and can freeze or censor them. Keep only a small working balance there. Sellers are unaffected: payouts go directly to whatever Lightning Address you control. `setup_wallet` automates exactly this setup: with explicit operator consent (`confirm: true`) it registers a Coinos account in the operator's name and stores the credentials locally. Hypawave is not the custodian — Coinos is — and Hypawave's servers never receive the credentials. The tool refuses to run without consent and refuses to overwrite an existing wallet file. The only network destination it adds is `coinos.io` (or `COINOS_API_URL`). ## Dependencies Runtime dependencies are pinned, widely-used libraries: `@modelcontextprotocol/sdk` (MCP transport), `@getalby/sdk` (NIP-47 client), `@noble/curves`/`@noble/hashes` (audited cryptography), `zod`, `ws`. The only network destinations at runtime are the Hypawave API over HTTPS, your wallet's Nostr relay, and presigned storage URLs returned by the API. ## Verifying ```bash npm test # 106 unit tests, including the signer against Hypawave's published llms.txt test vector and the Agent Waves ECIES key wrap ``` ## Reporting a vulnerability Email **security@hypawave.com** (or support@hypawave.com). Please do not open a public issue for security-sensitive reports. We aim to acknowledge within a few business days.