si-wallet-mcp

Sovereign-identity wallet as an MCP server. Gives any MCP-capable agent a DID, owner→agent grants, and task mandates — the identity layer underneath AWAS website authentication.

Protocol: TamTunnel/sovereign-identity — DIDs, agency grants, task mandates, and the AWAS website binding this wallet implements.

Version: 0.1.0 · License: Apache-2.0

Tools

| Tool | What it does | |---|---| | wallet_onboard | Create the owner/agent identity (returns existing if present) | | wallet_did | Get the DID for a role | | issue_grant | Owner delegates scopes + USD limit to an agent DID | | mint_mandate | Agent mints a task mandate for a website audience (returns Authorization: Mandate … value). Pass subjectDid to delegate to a downstream agent with narrowed scope/amount | | verify_mandate | Website-side verification: signatures, expiry, audience, replay, grant binding, scope/amount confinement | | verify_chain | Website-side verification of a multi-hop delegation chain (Owner → … → agent): per-hop signatures, binding, attenuation, replay | | pairwise_did | Fresh pairwise DID per audience (no cross-site correlation) |

Guardrails are enforced server-side: mandates over $100 need confirmOverLimit=true (only after the owner explicitly approved), and the verifier rejects non-canonical base64url outright.

Quick start

npm install -g @tamtunnel/si-wallet-mcp   # after publish; or clone and npm install
export SI_WALLET_PASSPHRASE="your passphrase"   # required for signing
si-wallet-mcp                                # stdio mode (default)

State lives in ~/.sov-id (override with SI_WALLET_DIR). Keys are scrypt + AES-256-GCM encrypted at rest, files mode 600.

Local MCP clients (Claude Code, Hermes, OpenClaw, …)

Add to the client's MCP config:

{
  "mcpServers": {
    "si-wallet": {
      "command": "node",
      "args": ["/path/to/si-wallet-mcp/server.mjs"],
      "env": { "SI_WALLET_PASSPHRASE": "your passphrase" }
    }
  }
}

Muse (custom connector)

Muse custom connectors reach remote MCP servers over streamable HTTP — a server on your laptop is not reachable from Meta's cloud. Run:

export SI_WALLET_PASSPHRASE="your passphrase"
export SI_MCP_TOKEN="$(openssl rand -hex 32)"   # required in HTTP mode
si-wallet-mcp --http --port 8787

Expose it on a public HTTPS URL (your VPS, fly.io, Tailscale, …), then add that URL as a custom connector in Muse with Authorization: Bearer <token>. The server binds 127.0.0.1 by default; only set SI_MCP_HOST=0.0.0.0 behind TLS. Full walkthrough: DEPLOY.md.

Docker

docker build -t si-wallet-mcp .
docker run -d --name si-wallet \
  -e SI_MCP_TOKEN="$(openssl rand -hex 32)" \
  -e SI_WALLET_PASSPHRASE="your passphrase" \
  -v si-wallet-data:/data \
  -p 127.0.0.1:8787:8787 \
  si-wallet-mcp

See DEPLOY.md for fly.io, Tailscale, TLS, onboarding, backups, and connecting Meta Muse.

Delegation demo: Owner → Muse → Hermes

examples/delegation-chain/ is a runnable proof that mandates compose across agents and frameworks with no pair-specific connectors: the owner grants Muse broad authority, Muse delegates a narrowed envelope to Hermes, Hermes presents the leaf mandate to a website, and the website verifies the whole attenuated chain. Four attacks (scope escalation, amount escalation, tampering, replay) are attempted and refused.

node examples/delegation-chain/run.mjs

Who hosts this?

Each user hosts their own. That is the point. A wallet holds private keys, so there is no shared hosted instance — that would be custodial and would contradict the "sovereign" in sovereign identity.

• You, for your own use: run it on hardware you control (your Mac, a VPS you own). One command, keys never leave your machine.
• Other users: same — they run their own instance and point their agent at it. This mirrors how Hermes/OpenClaw already work (self-hosted).
• Stateless verification (verify_mandate without the replay ledger) is the only piece that could ever be shared, and even that is safer local.

Whoever can reach the server can ask it to sign. Treat the bearer token like a password and never expose the HTTP port without TLS.

Security notes

• HTTP mode refuses to start without SI_MCP_TOKEN; every request needs Authorization: Bearer <token> (401 otherwise).
• The server never logs the passphrase, keys, or tokens.
• Demo identities created with a test passphrase must be replaced before real use — the real owner onboarding is yours to run.
• This tooling has not had an independent cryptographic audit.