@buildaureon/mcp 0.1.1

package/docs/auth.md

@@ -0,0 +1,349 @@
+# Authentication Guide
+
+How **`@buildaureon/mcp`** `v0.1.1` authenticates to the live AUREON API — aligned with `@buildaureon/sdk`, safe for humans and for agents that call the **34** stdio tools.
+
+Related docs: [Setup](./setup.md) · [Tools](./tools.md) · [Agent guide](./agent-guide.md) · [Architecture](./architecture.md) · [Security](./security.md) · [Package README](../README.md)
+
+---
+
+## Who this is for
+
+- **Agent operators** wiring Cursor or Claude Desktop with an issued developer key
+- **Integrators** comparing MCP auth to the typed SDK client
+- **Security reviewers** checking that private keys never enter the MCP process
+- **Agents** reading this file as context before calling `aureon_me`, restore, or vault prepare tools
+
+If you have not configured the host yet, start with [./setup.md](./setup.md), then return here for credential semantics.
+
+---
+
+## Goals of MCP auth
+
+1. Reach `https://api.aureonlabs.network` with credentials the gateway accepts.
+2. Bind control-plane actions to a wallet identity (issued key or Bearer session).
+3. Keep signing and broadcasting of on-chain vault steps **outside** MCP.
+4. Prefer a long-lived issued key for always-on agents over interactive wallet handshakes.
+
+The operator utility at [app.aureonlabs.network](https://app.aureonlabs.network) remains wallet-Bearer oriented for humans. MCP and the SDK share the issued-key path for automation.
+
+---
+
+## Credential types
+
+| Credential | Where you get it | Put it in MCP? | What it does |
+| --- | --- | --- | --- |
+| **Issued developer API key** | Developers page → create key | Yes — `AUREON_API_KEY` | Product access **and** wallet identity for control-plane tools. **Recommended.** |
+| **Bootstrap / env-style key** | Rare / special environments | Only if explicitly issued for that purpose as `AUREON_API_KEY` | Same transport header as an issued key; treat with equal secrecy. Prefer Developers-issued keys for production agents. |
+| **Wallet Bearer token** | Wallet sign-in, or `aureon_verify_wallet` | Optional — `AUREON_AUTH_TOKEN` or in-process after verify | Session for utility-style identity. **Wins** when both key and Bearer are present. |
+| **Wallet private key** | Your wallet / HSM / signing bot | **Never** in MCP env | Sign and broadcast deposit/withdraw txs **outside** MCP after prepare tools return unsigned steps. |
+
+Plain language:
+
+- **Issued key** = “this agent may call the API as my Developers-bound wallet.”
+- **Bearer** = “this process has an active wallet session.”
+- **Private key** = “this other process may move funds on chain.” MCP does not hold that.
+
+---
+
+## Environment variables (auth-focused)
+
+| Variable | Role |
+| --- | --- |
+| `AUREON_API_KEY` | Preferred. Issued developer key from [app.aureonlabs.network](https://app.aureonlabs.network) **Developers**. |
+| `AUREON_AUTH_TOKEN` | Optional Bearer. Use when you intentionally want a session without (or in addition to) a key — see conflict rules below. |
+| `AUREON_API_URL` | Defaults to `https://api.aureonlabs.network`. Leave default for public use. |
+
+Startup rule: at least one of `AUREON_API_KEY` or `AUREON_AUTH_TOKEN` must be set or the MCP process exits with a clear error.
+
+See also the setup tables in [./setup.md](./setup.md).
+
+---
+
+## Recommended path: issued developer key
+
+This is the default for Cursor, Claude, and other always-on agents.
+
+### Steps
+
+1. Open [https://app.aureonlabs.network](https://app.aureonlabs.network).
+2. Connect the wallet that should own objectives and Capital Book state.
+3. Open **Developers** and create a key (name it after the host, e.g. `cursor-mcp`).
+4. Copy the secret once into the host MCP `env` as `AUREON_API_KEY`.
+5. Do **not** set `AUREON_AUTH_TOKEN` unless you have a specific reason.
+6. Restart the host and call `aureon_ping` then `aureon_me`.
+
+Minimal env:
+
+```bash
+AUREON_API_URL=https://api.aureonlabs.network
+AUREON_API_KEY=aureon_....
+```
+
+With only the issued key, agents can sync portfolio, create objectives, fetch restore plans, restore, refresh watchdog, and manage developer keys — without an interactive signature each session.
+
+Rotate or revoke from the same Developers page if the secret is exposed. Update the host config immediately after rotation.
+
+---
+
+## Optional wallet handshake (Bearer session)
+
+Use when you need a utility-style session, when debugging auth, or when an issued key is unavailable and you already hold a Bearer.
+
+### Tools involved
+
+| Tool | Role |
+| --- | --- |
+| `aureon_get_auth_nonce` | Fetch an EIP-191 challenge message for an address |
+| `aureon_verify_wallet` | Submit address + message + signature (+ optional invite); **stores** the returned Bearer in-process |
+| `aureon_logout` | Revoke the session server-side and clear the in-process token |
+| `aureon_me` | Show the wallet for the active key or Bearer |
+| `aureon_dev_login` | Preview-only login — **not** available on the production API |
+
+### Sequence
+
+```text
+Agent → aureon_get_auth_nonce(address)
+     ← challenge message
+
+Agent → host wallet signs message (EIP-191)  [outside MCP]
+     ← signature
+
+Agent → aureon_verify_wallet(address, message, signature, inviteCode?)
+     ← token; MCP session.setToken(token)
+
+Later tools use getAccessToken() from the in-process session provider.
+```
+
+Early access may require an `inviteCode` on first verify for a new wallet.
+
+You may also seed `AUREON_AUTH_TOKEN` in the host env if you already obtained a Bearer elsewhere. That token is loaded into the same in-process session provider at startup.
+
+Prefer issued keys for unattended agents. Handshakes need a human (or separate signing host) for every new session after logout or process restart — unless the Bearer is re-injected via env.
+
+---
+
+## How MCP stores Bearer in-process
+
+On startup, `@buildaureon/mcp` builds an `@buildaureon/sdk` client with:
+
+- `apiKey` from `AUREON_API_KEY` (if set)
+- `getAccessToken` from a small session provider initialized with `AUREON_AUTH_TOKEN` (if set)
+
+When `aureon_verify_wallet` (or `aureon_dev_login` on a preview API) succeeds, the MCP layer calls `session.setToken(token)`.
+
+When `aureon_logout` succeeds, it clears the in-process token after the API revoke.
+
+Important properties:
+
+- The Bearer lives **only in the MCP process memory** (plus whatever you put in host env).
+- Restarting the host clears memory unless `AUREON_AUTH_TOKEN` is still in env.
+- MCP does not write tokens to disk and does not sync them into Cursor chat history by itself — but agents may echo tool results; treat tool output as sensitive.
+
+Issued keys do not need this session store for identity. The key header alone identifies the Developers-bound wallet.
+
+---
+
+## `aureon_me` and `aureon_logout`
+
+### `aureon_me`
+
+Returns the wallet bound to the **effective** credential the gateway sees: issued key identity, or Bearer session when a Bearer is active and winning.
+
+Use it as the first identity check after setup:
+
+- Expected address matches your Developers wallet → good.
+- Unexpected address → you likely have a stale Bearer winning over the key (see conflict rules).
+
+### `aureon_logout`
+
+Revokes the current Bearer session and clears the in-process token.
+
+It does **not** revoke your issued developer API key. Key lifecycle is managed on the Developers page (`aureon_revoke_api_key` / pause toggle tools, or the UI).
+
+After logout, if only `AUREON_API_KEY` remains, subsequent tools continue as the key-bound wallet. If you had neither key nor a remaining env Bearer, authenticated calls will fail until you configure credentials again.
+
+---
+
+## What MCP never does
+
+| Action | MCP behavior |
+| --- | --- |
+| Hold a wallet private key | Never — not in env, not in tool args, not in memory by design |
+| Sign EIP-191 auth challenges | Host / wallet signs; MCP only transports nonce and verify |
+| Sign or broadcast vault txs | `aureon_prepare_vault_*` returns **unsigned** steps only |
+| Custodialize funds | Non-custodial; settlement remains plan-driven on the API / vault |
+| Replace the operator utility | Humans still use the app; MCP is the agent adapter |
+| Enable `aureon_dev_login` on production | Production rejects it; use issued keys |
+
+If an agent asks for a private key “so MCP can deposit,” refuse and point to prepare → external sign → sync. See [./security.md](./security.md).
+
+---
+
+## Conflict rules: key + Bearer together
+
+Both credentials may be present:
+
+1. Host sets `AUREON_API_KEY` **and** `AUREON_AUTH_TOKEN`, or
+2. Host sets only the key, then the agent runs `aureon_verify_wallet` and stores a Bearer in-process.
+
+**Rule:** when both are sent on a request, the **Bearer wins** for wallet identity.
+
+Implications:
+
+- An old Bearer can mask a freshly rotated issued key’s wallet.
+- Debugging “wrong wallet on `aureon_me`” almost always means clear Bearer: call `aureon_logout`, remove `AUREON_AUTH_TOKEN` from env, restart the host.
+- For always-on agents, keep config key-only so identity is predictable across restarts.
+
+Bootstrap or special env keys still travel as `AUREON_API_KEY`. They do not change the Bearer-wins rule when a session token is also attached.
+
+---
+
+## Private key: outside MCP only
+
+Vault deposit and withdraw are two-phase:
+
+1. **MCP / SDK prepare** — `aureon_prepare_vault_deposit` or `aureon_prepare_vault_withdraw` returns unsigned calldata / steps.
+2. **External signer** — a wallet UI, hardware wallet, or a separate `@buildaureon/sdk` script with a private key broadcasts the txs.
+3. **Sync** — `aureon_sync_portfolio` / `aureon_get_vault` to refresh Capital Book state.
+
+Never paste a private key into MCP tool arguments or host env “for convenience.” That expands the blast radius of every chat that can invoke tools.
+
+---
+
+## Common errors
+
+| Error / symptom | Meaning | Fix |
+| --- | --- | --- |
+| Startup: set `AUREON_API_KEY` or `AUREON_AUTH_TOKEN` | No credential configured | Add issued key to host `env` — [./setup.md](./setup.md) |
+| `401` Unauthorized | Key revoked/paused, Bearer expired, or typo | Rotate key or re-verify wallet |
+| Wrong wallet on `aureon_me` | Bearer winning over key | `aureon_logout`; remove env Bearer; restart |
+| `aureon_verify_wallet` fails | Bad signature, stale nonce, or missing invite | New nonce; re-sign; supply `inviteCode` if required |
+| `aureon_dev_login` fails on live API | Expected | Use issued key on `https://api.aureonlabs.network` |
+| Prepare tools succeed but funds do not move | Unsigned steps not broadcast | Sign outside MCP with a real wallet |
+| Agent invents a local API URL | Misconfigured override | Reset `AUREON_API_URL` to the live default |
+
+Map structured SDK errors in tool output to the same categories; do not retry blindly on `401` without rotating credentials.
+
+---
+
+## Agent-safe practices
+
+1. **Prefer issued keys** in host config; avoid interactive Bearer for unattended loops.
+2. **Never request private keys** in chat; guide operators to prepare → external broadcast.
+3. **Do not echo full API keys or Bearers** back into long chat logs when summarizing tool results.
+4. **Call `aureon_me` once** after connect to confirm identity before write tools.
+5. **On identity mismatch**, clear Bearer before creating objectives or restoring.
+6. **Treat Developers keys like passwords** — rotate on leak; use labeled keys per host.
+7. **Keep MCP local stdio** — do not expose the process on a public port.
+8. **Read** [./agent-guide.md](./agent-guide.md) before multi-step restore or market-event rehearsals.
+9. **Respect locked objective fields** — recreate rather than fighting update errors (see tools doc).
+10. **Assume tool output may be logged** by the host; minimize secret material in responses.
+
+---
+
+## Topology (mental model)
+
+```text
+MCP host (Cursor / Claude)
+    │  stdio
+    ▼
+@buildaureon/mcp  (34 tools, no private key)
+    │
+    ▼
+@buildaureon/sdk  (HTTP, retries, types)
+    │  HTTPS + API key and/or Bearer
+    ▼
+https://api.aureonlabs.network
+    │
+    ├── control plane (objectives, portfolio, restore, …)
+    └── prepare vault steps → human/agent signs elsewhere
+```
+
+Architecture detail: [./architecture.md](./architecture.md).
+
+---
+
+## FAQ
+
+### Is an issued key enough for restore?
+
+Yes. `aureon_restore_objective` and related control-plane tools authenticate with the issued key. On-chain funding of the vault still needs external signing when deposits are required.
+
+### When should I use Bearer instead?
+
+Interactive debugging, parity with the operator utility session model, or short-lived demos. Not the default for scheduled agents.
+
+### What is a “bootstrap” key in this doc?
+
+A key supplied via environment rather than freshly minted in the UI mid-session. Operationally it still goes in `AUREON_API_KEY`. Prefer Developers-issued keys you can pause and revoke from the console.
+
+### Does logout delete my API key?
+
+No. Logout clears Bearer session state. Manage keys on the Developers page or via developer tools.
+
+### Can MCP and the SDK share the same issued key?
+
+Yes. Same live API, same key family. Revoking the key affects both surfaces.
+
+### Why does Bearer win over the key?
+
+So an explicit wallet session can override key identity when operators intentionally complete a handshake. For agents, avoid that ambiguity by not setting Bearer.
+
+### Where do I configure credentials?
+
+In the MCP host `env` block — see Cursor / Claude examples in [./setup.md](./setup.md). Primary launch remains `npx -y @buildaureon/mcp`.
+
+---
+
+## Rotating credentials safely
+
+When a key may have leaked (pasted in chat, committed to a repo, shared in a screenshot):
+
+1. Open [app.aureonlabs.network](https://app.aureonlabs.network) → **Developers**.
+2. Pause or revoke the compromised key immediately.
+3. Create a replacement key with a new label.
+4. Update every MCP host `env` that still references the old secret.
+5. Restart those hosts so in-memory clients reload.
+6. Call `aureon_me` once to confirm the bound wallet is unchanged and authorized.
+
+If a Bearer may have leaked, call `aureon_logout` from a trusted session (if still valid), remove `AUREON_AUTH_TOKEN` from env, and re-verify only if you still need a session. Prefer switching the agent to issued-key-only afterward.
+
+Do not reuse the compromised secret “temporarily.” Treat rotation as mandatory once exposure is plausible.
+
+---
+
+## Relationship to the SDK
+
+`@buildaureon/mcp` does not invent a second auth protocol. It configures `createAureonClient` from `@buildaureon/sdk` with the same headers the SDK would send in a script:
+
+- Issued key → API key header / client option
+- Bearer → access token via the session provider
+- Base URL → `https://api.aureonlabs.network` by default
+
+If a typed SDK script works with your issued key but MCP fails, compare env names (`AUREON_API_KEY` vs hard-coded client options) and confirm the host actually injects env into the stdio child process.
+
+Package version for this guide: **`@buildaureon/mcp` `v0.1.1`**.
+
+---
+
+## Quick reference checklist
+
+- [ ] Issued key from Developers page in `AUREON_API_KEY`
+- [ ] No private key anywhere in MCP config
+- [ ] `AUREON_AUTH_TOKEN` unset unless you need a session
+- [ ] `aureon_me` shows the expected wallet
+- [ ] You know Bearer wins if both are present
+- [ ] Vault moves use prepare tools + external signer
+- [ ] Leaked secrets → revoke / rotate on Developers
+- [ ] After rotation, every host env updated and restarted
+
+---
+
+## Next steps
+
+- Finish host wiring: [./setup.md](./setup.md)
+- Tool schemas: [./tools.md](./tools.md)
+- Playbooks: [./agent-guide.md](./agent-guide.md)
+- Boundaries: [./architecture.md](./architecture.md)
+- Threat model: [./security.md](./security.md)
+- Package home: [../README.md](../README.md)

package/docs/security.md

@@ -0,0 +1,335 @@
+# Security
+
+Threat model and operational guidance for running `@buildaureon/mcp` against the live AUREON API.
+
+This document is for operators configuring agent hosts and for AI agents that must respect custody and credential boundaries. It complements `architecture.md`: the adapter is thin, but the **blast radius of a leaked API key or a mis-hosted MCP process** is not.
+
+---
+
+## 1. Trust boundaries (light threat model)
+
+| Boundary | Assumption | Failure mode if broken |
+| --- | --- | --- |
+| MCP process | Local stdio child of a trusted host | Remote callers could invoke any registered tool |
+| Issued API key | Equivalent to “act as this developer / wallet scope” on the control plane | Attacker creates objectives, restores, prepares vault steps, manages keys |
+| Private key | Never enters MCP env or process | Full fund theft if combined with broadcast capability |
+| Host LLM / agent | Can call any enabled tool | Prompt injection or confused deputy may trigger writes |
+| Operator utility | Separate wallet-Bearer UI | Unrelated to MCP, but same API identity if same wallet |
+| HTTPS to API | TLS to `https://api.aureonlabs.network` | MITM only if TLS broken or base URL pointed at attacker |
+
+```mermaid
+flowchart LR
+  Host[MCP_host_and_LLM] -->|tool_calls_stdio| MCP[local_MCP_adapter]
+  MCP -->|API_key_and_optional_Bearer| API[api.aureonlabs.network]
+  MCP -.->|never_holds| PK[private_keys]
+  Human[Human_operator] -->|reviews_and_signs| Chain[Robinhood_Chain]
+  API --> Vault[Smart_Vault]
+  Vault --> Chain
+```
+
+### Assets worth protecting
+
+1. **Issued API keys** — long-lived control-plane credentials.
+2. **Bearer session tokens** — short-lived wallet sessions in process memory.
+3. **Unsigned prepare payloads** — not spendable alone, but valuable for phishing / wrong-chain tricks if altered.
+4. **Agent conversation logs** — may accidentally echo secrets if tools or prompts dump env.
+
+### Adversaries (simplified)
+
+- Malicious or compromised MCP host configuration.
+- Prompt injection that steers an agent toward write tools.
+- Leaked key material from chat logs, screenshots, or shared configs.
+- Insider with host access but without wallet keys (still dangerous for control plane).
+
+This is a **light** threat model: enough to drive defaults, not a formal audit report.
+
+---
+
+## 2. Credential handling
+
+### Issued API keys (`AUREON_API_KEY`)
+
+- Created via developer tools / utility Developers surface; **plaintext shown once** at issuance.
+- Treat as a **secret password** for the AUREON control plane.
+- Store in the host’s MCP env configuration or a secret manager — **never** commit to git, never paste into public issues, never embed in prompts as standing instructions.
+- Prefer **one key per agent host** (e.g. Cursor workspace vs Claude Desktop vs CI agent).
+- Pause or revoke immediately on suspicion of leak (`aureon_toggle_api_key`, `aureon_revoke_api_key`, or utility equivalents).
+
+### Bearer tokens (`AUREON_AUTH_TOKEN` / session)
+
+- Obtained from wallet verify flows (`aureon_get_auth_nonce` → sign off-MCP → `aureon_verify_wallet`) or optional env bootstrap.
+- Held **in-process only** by the SDK session provider; MCP does not write them to disk.
+- Clear with `aureon_logout` on shared long-lived hosts when the human session ends.
+- Do not log, print, or ask the model to “show the token.”
+
+### What travels on the wire
+
+- Issued key: `X-Aureon-Api-Key` (SDK).
+- Bearer: `Authorization` (SDK).
+- Both are composed inside the SDK HTTP client. MCP handlers should not re-implement header injection.
+
+### Private keys
+
+- **Never** place a wallet private key or seed in MCP environment variables.
+- Required only to **broadcast** transactions after prepare tools return unsigned steps.
+- Keep keys in the operator wallet, hardware wallet, or a dedicated signing service **outside** the MCP child process.
+
+---
+
+## 3. What MCP never does
+
+`@buildaureon/mcp` deliberately omits capabilities that would collapse the custody boundary:
+
+| Capability | MCP behavior |
+| --- | --- |
+| Hold private keys | Never |
+| Sign transactions | Never |
+| Broadcast to chain | Never |
+| Custodial withdraw | Never |
+| Silent auto-trade without a plan | Never — restores are explicit tool calls |
+| Persist secrets to disk | Never |
+| Expose a public HTTP MCP endpoint | Not supported / not recommended |
+| Claim `settlement: "vault"` when staged | Never — pass through API honesty fields |
+| Print API keys in tool results | Must not |
+
+If a fork or wrapper adds signing inside the MCP process, it is **no longer** the same trust model. Treat that as a different product with a different review bar.
+
+---
+
+## 4. Deposit / withdraw trust boundary
+
+Vault tools are split on purpose:
+
+1. **Read** — `aureon_get_vault`, `aureon_get_vault_status` (and related reads) show state.
+2. **Prepare** — `aureon_prepare_vault_deposit` / `aureon_prepare_vault_withdraw` return **unsigned** steps / calldata descriptions.
+3. **Sign & broadcast** — human or external signer only.
+4. **Observe** — later reads confirm chain effects.
+
+```mermaid
+sequenceDiagram
+  participant Agent
+  participant MCP
+  participant API
+  participant Signer as External_signer
+  participant Chain
+
+  Agent->>MCP: prepare_vault_withdraw
+  MCP->>API: prepare request
+  API-->>MCP: unsigned steps
+  MCP-->>Agent: JSON calldata description
+  Note over Agent,Signer: Human review required
+  Signer->>Chain: signed broadcast
+  Agent->>MCP: get_vault_status
+  MCP->>API: status
+  API-->>Agent: updated state
+```
+
+### Operator checklist for prepare flows
+
+- Confirm the **amount**, **asset**, and **destination** in the prepare payload before signing.
+- Confirm you are on the intended network (Robinhood Chain context as documented by AUREON).
+- Do not ask the agent to “just sign it” with a key the agent can access.
+- Treat unexpected prepare output (wrong recipient, odd calldata) as a stop-ship signal.
+
+Prepare without broadcast cannot move funds. Broadcast without review can. Keep the human (or a hardened signing policy engine) in that gap.
+
+---
+
+## 5. Key rotation, pause, and revoke
+
+### Rotation pattern
+
+1. Create a new issued key (`aureon_create_api_key` or utility).
+2. Update host MCP env to the new key.
+3. Restart the MCP host / child process so config reloads.
+4. Verify with a read tool (`aureon_ping`, `aureon_me`, or overview).
+5. **Revoke** or **pause** the old key.
+
+Avoid long dual-key windows on untrusted machines. Prefer short overlap only while validating the new host config.
+
+### Pause vs revoke
+
+| Action | Intent |
+| --- | --- |
+| Pause / toggle off | Temporary disable without destroying the key record |
+| Revoke | Permanent invalidation after leak or decommission |
+| Logout (Bearer) | Clear in-memory session only; does not revoke issued keys |
+
+### Least privilege habits
+
+- Separate keys for **read-heavy experimentation** vs **production agent** hosts when the product surface allows operational separation.
+- Do not share one key across untrusted operators or public demo machines.
+- Limit which host profiles load write-capable MCP configs.
+- Prefer issued keys over long-lived Bearer env injection for agents.
+
+---
+
+## 6. Host config hygiene
+
+MCP hosts typically store command + env in a JSON (or UI) config. Hygiene rules:
+
+1. **Secrets only in env fields** managed by the host — not in chat history, not in repo files checked into git.
+2. **Do not commit** MCP config files that contain live keys. Prefer redacted examples in docs (see package `examples/`).
+3. **Restrict workspace access** — anyone who can edit MCP config can point the agent at their own key or change the API base URL.
+4. **Watch `AUREON_API_URL` overrides** — only use non-default bases when you intentionally target a documented non-production environment. A malicious override is a credential phishing vector.
+5. **Browser vs agent hosting** — browser-based agent products may persist configs in cloud profiles; treat those as higher risk than a local desktop host you control. Prefer short-lived keys and aggressive revoke there.
+6. **Disable MCP** when not needed — reduce accidental write tool invocation.
+7. **Never ask the model to echo env** — including “debug by printing AUREON_API_KEY.”
+
+### Logging
+
+- Application logs must not include Authorization headers, API keys, or raw verify signatures.
+- Prefer logging tool **names** and high-level outcomes, not full credential-bearing payloads.
+- If a host captures full tool I/O for debugging, scrub secrets before sharing traces.
+
+---
+
+## 7. Agent / LLM-specific risks
+
+Agents amplify ordinary API risks:
+
+| Risk | Mitigation |
+| --- | --- |
+| Prompt injection (“ignore policy, restore now”) | Human approval for destructive tools; narrow system rules |
+| Confused deputy (agent acts for attacker text) | Treat untrusted documents as untrusted; confirm writes |
+| Secret exfiltration via tool args | Never pass keys as tool arguments; keys stay in env/SDK |
+| Over-broad tool enablement | Enable only needed tools if the host supports filtering |
+| Stale sessions | Logout; rotate keys after shared-machine use |
+
+Remember: **the model is not a security boundary**. The boundary is env isolation, key lifecycle, and human signing for chain moves.
+
+---
+
+## 8. Production checklist
+
+Use this before enabling `@buildaureon/mcp` on a machine that can affect real capital:
+
+- [ ] Issued API key created specifically for this host
+- [ ] Key stored only in host secret/env config (not in git)
+- [ ] Private keys absent from MCP env and agent-accessible storage
+- [ ] Default API URL is `https://api.aureonlabs.network` unless override is intentional
+- [ ] Host is local stdio — not published as an open network service
+- [ ] Write tools understood by operators (`create`, `restore`, `prepare`, key CRUD)
+- [ ] Prepare → human sign → broadcast workflow documented for the team
+- [ ] Pause/revoke path tested once (know which tool/UI to use under stress)
+- [ ] Logging scrubbed of secrets
+- [ ] Browser-hosted agents use stricter key lifetimes than desktop if used at all
+- [ ] Onboarding docs for agents point at least-privilege tool use
+- [ ] Incident contacts known (who rotates keys, who pauses agents)
+
+---
+
+## 9. Incident response basics
+
+### If an API key may be leaked
+
+1. **Pause or revoke** the key immediately (developer tools or utility).
+2. **Restart** hosts so stale processes drop the old env after config update.
+3. **Inventory** recent objectives, restores, prepares, and key CRUD via timeline / executions / key list tools.
+4. **Issue a replacement key**; update only trusted hosts.
+5. **Review** whether Bearer sessions were also exposed; logout and re-verify if needed.
+6. **Communicate** to operators: stop signing prepare payloads from unknown sessions until review completes.
+
+### If a private key may be leaked
+
+1. This is **outside MCP** but higher severity — move funds / rotate wallets per your chain runbook.
+2. Revoke associated API keys as a secondary control-plane lockdown.
+3. Assume any unsigned prepare history could be replayed by an attacker who also has the key.
+
+### If an agent mis-fired writes
+
+1. Pause the objective or agent host.
+2. Inspect health, timeline, and executions for settlement honesty (`vault` vs `staged`).
+3. Do not “fix forward” with more restores until intent is clear.
+4. Rotate keys if the mis-fire suggests prompt injection with data exfil attempts.
+
+### Evidence to preserve
+
+- Timestamps of tool calls (host logs, if scrubbed).
+- Objective ids and execution receipts.
+- Key ids (not secret material) involved.
+
+Do not paste live secrets into tickets.
+
+---
+
+## 10. Browser vs desktop agent hosting
+
+| Hosting style | Typical risk | Guidance |
+| --- | --- | --- |
+| Local desktop MCP (Cursor / Claude Desktop style) | Config files on disk; local malware | Disk encryption; least-privilege OS user; no shared accounts |
+| Cloud / browser agent with remote tool runner | Broader persistence and sharing surfaces | Short-lived keys; revoke often; avoid high-value wallets |
+| Shared demo machine | Key reuse across people | Unique keys; revoke after demo; no private keys nearby |
+
+In all cases: MCP remains a **local adapter pattern** conceptually. If a product remotes the stdio server, you have changed the threat model — re-validate network ACLs and auth before use.
+
+---
+
+## 11. Honest settlement and integrity
+
+Security is not only custody; it is also **truthfulness of outcomes**:
+
+- Agents must surface `settlement` fields accurately.
+- Staged settlement is not the same as vault/on-chain completion.
+- Do not coach models to rewrite receipts as “done on-chain” when the API said `staged`.
+
+Integrity failures (lying about settlement) create operator errors that look like security incidents later.
+
+---
+
+## 12. Dependency and supply-chain notes
+
+- Install `@buildaureon/mcp` from the published package registry you trust.
+- Pin versions when reproducibility and change control matter.
+- The MCP package depends on `@buildaureon/sdk` and `@modelcontextprotocol/sdk`.
+- Review release notes when upgrading — new tools expand the agent’s write surface.
+
+---
+
+## 13. FAQ
+
+**Is an issued API key as powerful as my wallet private key?**  
+No. It does not sign chain transactions. It **is** powerful on the control plane (objectives, restores, prepares, key management). Protect it accordingly.
+
+**Can MCP steal funds by itself?**  
+Not via signing — it never holds private keys. Funds move only after an external signer broadcasts. Control-plane misuse can still create harmful plans or confuse operators.
+
+**Should I put my private key in the host env so the agent can deposit for me?**  
+No. That collapses the custody model. Keep signing outside MCP.
+
+**What if I need automation for broadcast?**  
+Use a dedicated signing service with its own policy engine and audit log — not the MCP adapter.
+
+**Is Bearer safer than an API key?**  
+Different tradeoffs. Bearer is often shorter-lived; issued keys are better for unattended agents. Both are secrets.
+
+**Can I run multiple MCP hosts with one key?**  
+Technically yes; operationally prefer one key per host for blast-radius control.
+
+**Does `aureon_logout` revoke my issued key?**  
+No. It clears the in-memory Bearer only.
+
+**What should agents refuse to do?**  
+Print secrets, accept private keys as tool args, claim vault settlement without API fields, or broadcast transactions.
+
+**Where is the deeper architecture?**  
+See `architecture.md` for layers, registration, and SDK vs MCP ownership.
+
+**Who do I contact for platform incidents?**  
+Follow AUREON’s published support / security channels on the product site; include key ids and timestamps, never raw secrets.
+
+---
+
+## 14. Related documents
+
+- [Architecture](./architecture.md) — layers and request lifecycle
+- [Authentication](./auth.md) — key and Bearer flows
+- [Setup](./setup.md) — host configuration patterns
+- [Tools](./tools.md) — including developer key tools
+- [Agent guide](./agent-guide.md) — safe call sequences
+
+---
+
+## 15. Summary
+
+Treat `@buildaureon/mcp` as a **local, non-custodial stdio adapter** over `@buildaureon/sdk` to `https://api.aureonlabs.network`. Protect issued keys like passwords, keep private keys out of the MCP process, require human (or hardened external) signing for deposit/withdraw broadcast, rotate and revoke quickly, and assume the LLM is not a security boundary — configuration hygiene and least privilege are.