@aspect-warden/mcp-server 0.3.1 → 0.4.0

package/README.md

@@ -0,0 +1,152 @@
+# @aspect-warden/mcp-server
+
+MCP (Model Context Protocol) server that gives AI agents policy-enforced wallet capabilities on Sepolia. Works with Claude Desktop, OpenClaw, and any MCP-compatible client.
+
+## Install
+
+```bash
+npm install @aspect-warden/mcp-server
+```
+
+Or run directly:
+
+```bash
+npx @aspect-warden/mcp-server
+```
+
+## Setup with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "warden": {
+      "command": "npx",
+      "args": ["@aspect-warden/mcp-server"],
+      "env": {
+        "RPC_URL": "https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY",
+        "SEPOLIA_USDT_ADDRESS": "0x7169D38820dfd117C3FA1f22a697dBA58d90BA06"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The agent now has access to all Warden wallet tools.
+
+## Setup with OpenClaw
+
+Add the same config to your OpenClaw MCP settings, or install the warden-wallet skill:
+
+```bash
+npx skills add tetherto/wdk-agent-skills
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `RPC_URL` | No | `https://rpc.sepolia.org` | Sepolia RPC endpoint |
+| `POLICY_DELEGATE_ADDRESS` | No | — | Deployed PolicyDelegate contract for EIP-7702 |
+| `SEPOLIA_USDT_ADDRESS` | No | `0x7169...BA06` | USDT token address on Sepolia |
+| `ERC8004_IDENTITY_REGISTRY` | No | — | ERC-8004 identity registry address |
+| `WARDEN_STORAGE_KEY` | No | machine-scoped | Passphrase for encrypting persisted wallet state |
+
+## MCP Tools
+
+Once connected, the agent can call these tools:
+
+### Wallet Management
+
+| Tool | Description |
+|------|-------------|
+| `warden_create_wallet` | Create a new agent wallet with policy enforcement |
+| `warden_get_balance` | Check ETH and token balances |
+| `warden_transfer` | Send ERC-20 tokens (validated against policy) |
+| `warden_get_audit_log` | Fetch transaction decision history |
+
+### Policy Management
+
+| Tool | Description |
+|------|-------------|
+| `warden_setup_policy` | Configure spending policy from natural language |
+| `warden_get_policy_status` | View current spending status and limits |
+| `warden_update_policy` | Modify policy at runtime |
+
+### On-Chain Enforcement (EIP-7702)
+
+| Tool | Description |
+|------|-------------|
+| `warden_delegate_to_policy` | Delegate EOA to PolicyDelegate contract |
+| `warden_create_session_key` | Create scoped sub-agent permissions |
+| `warden_revoke_session_key` | Revoke sub-agent access |
+
+### Safety Controls
+
+| Tool | Description |
+|------|-------------|
+| `warden_freeze` | Emergency halt all operations |
+| `warden_unfreeze` | Resume after freeze |
+| `warden_register_identity` | Register agent on ERC-8004 identity registry |
+
+### Permissions (ERC-7715)
+
+| Tool | Description |
+|------|-------------|
+| `warden_grant_permissions` | Grant permissions to an agent |
+| `warden_revoke_permissions` | Revoke agent permissions |
+| `warden_get_permissions` | View agent permission grants |
+
+## Example Conversation
+
+```
+User: Create a conservative wallet. Max $50/day, USDT only.
+
+Agent: [calls warden_create_wallet with maxPerTx=10, dailyLimit=50]
+       Created wallet 0xABC...123 with conservative policy.
+       - Max per transaction: 10 USDT
+       - Daily limit: 50 USDT
+       - Anomaly detection: enabled
+
+User: Send 5 USDT to 0xDEF...456
+
+Agent: [calls warden_transfer with amount=5, recipient=0xDEF...456]
+       Transfer approved and sent.
+       - Risk score: 12/100
+       - Daily remaining: 45 USDT
+       - Tx hash: 0x789...
+
+User: Send 200 USDT to 0xDEF...456
+
+Agent: [calls warden_transfer — PolicyEngine blocks it]
+       Transfer blocked: exceeds daily limit of 50 USDT.
+       Current daily spend: 5 USDT.
+```
+
+## Wallet Persistence
+
+Wallet private keys and policy configuration are automatically saved to `~/.warden/wallet-state.enc` using AES-256-CBC encryption. When the MCP server restarts (e.g., Claude Desktop relaunch), it restores the previous wallet — no need to call `warden_create_wallet` again.
+
+- **Storage**: `~/.warden/wallet-state.enc` (encrypted, file permissions `0600`)
+- **Encryption**: AES-256-CBC with key derived from `WARDEN_STORAGE_KEY` env var (or machine-scoped default)
+- **What's persisted**: private key, agent ID, policy configuration
+- **What's NOT persisted**: spending counters, audit logs, session keys (reset on restart)
+
+To use a different wallet, simply call `warden_create_wallet` again — it overwrites the saved state.
+
+## Architecture
+
+```
+AI Agent (Claude / OpenClaw)
+    ↓ MCP Protocol (stdio)
+@aspect-warden/mcp-server
+    ↓ evaluates every tx
+@aspect-warden/policy-engine (19 rules + anomaly detection)
+    ↓ on-chain enforcement
+PolicyDelegate.sol (EIP-7702 / Sepolia)
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -5,6 +5,10 @@ import { z } from 'zod';
 import { createPublicClient, createWalletClient, http, parseAbi, encodeFunctionData, formatEther, formatUnits, parseUnits, } from 'viem';
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 import { sepolia } from 'viem/chains';
+import { createHash, createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 // ============================================================
 // Configuration from environment
 // ============================================================
@@ -34,6 +38,60 @@ const ERC8004_ABI = parseAbi([
 ]);
 // PolicyEngine and AuditLogger imported from @aspect-warden/policy-engine
 // ============================================================
+// Encrypted Wallet Persistence
+// ============================================================
+const STORAGE_DIR = join(homedir(), '.warden');
+const STATE_FILE = join(STORAGE_DIR, 'wallet-state.enc');
+// Derive a 32-byte AES key from a passphrase
+function deriveKey(passphrase) {
+    return createHash('sha256').update(passphrase).digest();
+}
+function encrypt(data, passphrase) {
+    const key = deriveKey(passphrase);
+    const iv = randomBytes(16);
+    const cipher = createCipheriv('aes-256-cbc', key, iv);
+    let encrypted = cipher.update(data, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    return iv.toString('hex') + ':' + encrypted;
+}
+function decrypt(payload, passphrase) {
+    const key = deriveKey(passphrase);
+    const [ivHex, encrypted] = payload.split(':');
+    const iv = Buffer.from(ivHex, 'hex');
+    const decipher = createDecipheriv('aes-256-cbc', key, iv);
+    let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    return decrypted;
+}
+const STORAGE_KEY = process.env.WARDEN_STORAGE_KEY || `warden-${homedir()}`;
+function saveState(state) {
+    try {
+        if (!existsSync(STORAGE_DIR)) {
+            mkdirSync(STORAGE_DIR, { recursive: true, mode: 0o700 });
+        }
+        const json = JSON.stringify(state);
+        const encrypted = encrypt(json, STORAGE_KEY);
+        writeFileSync(STATE_FILE, encrypted, { mode: 0o600 });
+        console.error('[Warden MCP] Wallet state saved to ~/.warden/wallet-state.enc');
+    }
+    catch (err) {
+        console.error('[Warden MCP] Failed to save wallet state:', err);
+    }
+}
+function loadState() {
+    try {
+        if (!existsSync(STATE_FILE))
+            return null;
+        const encrypted = readFileSync(STATE_FILE, 'utf8');
+        const json = decrypt(encrypted, STORAGE_KEY);
+        return JSON.parse(json);
+    }
+    catch (err) {
+        console.error('[Warden MCP] Failed to load wallet state (may be from different key):', err);
+        return null;
+    }
+}
+// ============================================================
 // MCP Server State
 // ============================================================
 let policyEngine = null;
@@ -114,6 +172,22 @@ server.tool('warden_create_wallet', 'Create a new policy-enforced wallet for the
     policyEngine = new PolicyEngine(policy);
     auditLogger = new AuditLogger({ maxEntries: 10000 });
     frozen = false;
+    // Persist wallet state for recovery across restarts
+    saveState({
+        privateKey: storedPrivateKey,
+        agentId,
+        policy: {
+            maxPerTx: policy.maxPerTx.toString(),
+            dailyLimit: policy.dailyLimit.toString(),
+            requireApprovalAbove: policy.requireApprovalAbove.toString(),
+            cooldownMs: policy.cooldownMs,
+            allowedTokens: policy.allowedTokens,
+            blockedTokens: policy.blockedTokens,
+            allowedRecipients: policy.allowedRecipients,
+            blockedRecipients: policy.blockedRecipients,
+            allowedChains: policy.allowedChains,
+        },
+    });
     return {
         content: [{
                 type: 'text',
@@ -1034,6 +1108,37 @@ server.tool('warden_get_permissions', 'Query current permissions granted to an A
 // Main -- stdio transport
 // ============================================================
 async function main() {
+    // Restore wallet state from previous session if available
+    const saved = loadState();
+    if (saved) {
+        try {
+            initializeClients(saved.privateKey);
+            const restoredPolicy = {
+                agentId: saved.agentId,
+                maxPerTx: BigInt(saved.policy.maxPerTx),
+                dailyLimit: BigInt(saved.policy.dailyLimit),
+                requireApprovalAbove: BigInt(saved.policy.requireApprovalAbove),
+                cooldownMs: saved.policy.cooldownMs,
+                allowedTokens: saved.policy.allowedTokens,
+                blockedTokens: saved.policy.blockedTokens,
+                allowedRecipients: saved.policy.allowedRecipients,
+                blockedRecipients: saved.policy.blockedRecipients,
+                allowedChains: saved.policy.allowedChains,
+                anomalyDetection: {
+                    maxTxPerHour: 20,
+                    maxRecipientsPerHour: 5,
+                    largeTransactionPct: 50,
+                },
+            };
+            policyEngine = new PolicyEngine(restoredPolicy);
+            auditLogger = new AuditLogger({ maxEntries: 10000 });
+            frozen = false;
+            console.error(`[Warden MCP] Restored wallet ${walletAddress} (agent: ${saved.agentId})`);
+        }
+        catch (err) {
+            console.error('[Warden MCP] Failed to restore wallet state:', err);
+        }
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error('[Warden MCP] Server running on stdio');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspect-warden/mcp-server",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "warden-mcp": "dist/index.js"