nervepay 1.4.1 → 1.4.5

package/README.md

@@ -1,86 +1,60 @@
-# NervePay Plugin for OpenClaw
+# NervePay
 
-**Self-sovereign identity layer for AI agents.** Provides W3C DIDs, Ed25519 cryptographic authentication, secure vault, and multi-agent orchestration.
+Self-sovereign identity for AI agents. W3C DIDs, Ed25519 cryptographic authentication, encrypted secrets vault, and multi-agent orchestration.
 
-## Features
-
-- **🆔 Identity Management**: W3C DID registration with Ed25519 signatures
-- **🔐 Vault**: AES-256-GCM encrypted secrets management
-- **🔗 Gateway Pairing**: Connect OpenClaw gateways to NervePay Mission Control
-- **🤖 Orchestration**: Multi-agent task decomposition and management
-- **✅ Reputation**: Cross-platform agent reputation tracking
-
-## Installation
-
-### Quick Start (Recommended)
+## Quick Install
 
 ```bash
-# 1. Install plugin
-openclaw plugins install nervepay
-
-# 2. Run interactive setup wizard
-openclaw nervepay setup
-
-# That's it! The wizard handles:
-# ✅ Identity registration (W3C DID + Ed25519 keys)
-# ✅ Human claim flow (optional)
-# ✅ Gateway pairing (optional)
-# ✅ Auto-configuration of OpenClaw
-# ✅ Credentials backup
+npx nervepay setup
 ```
 
-The setup wizard is **fully interactive** and takes ~2 minutes. It configures everything automatically!
-
-### Manual Installation (from source)
+**Alternatives:**
 
 ```bash
-git clone https://github.com/nervepay/nervepay-plugin
-cd nervepay-plugin
-npm install
-npm run build
-openclaw plugins install .
-openclaw nervepay setup  # Still use the wizard!
+bunx nervepay setup          # Bun
+pnpm dlx nervepay setup      # pnpm
+openclaw plugins install nervepay && openclaw nervepay setup  # OpenClaw plugin
 ```
 
-### Local Development
+## What Happens
 
-```bash
-openclaw plugins install -l ./nervepay-plugin
-openclaw nervepay setup
-```
+**1. Setup** — Creates your agent identity (W3C DID + Ed25519 keys), generates a BIP39 recovery phrase, and opens a claim URL to link the agent to your dashboard account.
 
-## Configuration
+**2. Pair** — Connects your OpenClaw gateway via the device node protocol (WebSocket challenge-response). Run `nervepay pair` if you skipped pairing during setup, then approve with `openclaw devices approve`.
 
-**✨ The setup wizard configures everything automatically!** Just run:
+## CLI Commands
 
-```bash
-openclaw nervepay setup
-```
+| Command | Description |
+|---------|-------------|
+| `nervepay setup` | Create identity, claim agent, pair gateway |
+| `nervepay pair` | Connect gateway via device node protocol |
+| `nervepay whoami` | Show current agent identity and reputation |
+| `nervepay gateways` | List connected gateways |
+| `nervepay secrets` | List vault secrets (metadata only) |
+| `nervepay status` | Show config and connection status |
+
+All commands work with `npx`, `bunx`, or `pnpm dlx` prefixes.
+
+## Configuration
 
-It will:
-1. Register your agent identity
-2. Show claim URL (optional, improves trust)
-3. Optionally pair your gateway
-4. Auto-update your OpenClaw config
-5. Save credentials securely to `~/.nervepay/credentials.json`
+Setup auto-configures everything. Credentials are stored in:
 
-### Manual Configuration (if needed)
+- **OpenClaw config:** `~/.openclaw/openclaw.json` (plugin section)
+- **Backup:** `~/.nervepay/credentials.json`
 
-If you prefer to configure manually or already have credentials:
+<details>
+<summary>Manual configuration (advanced)</summary>
 
-```json5
+```json
 {
   "plugins": {
-    "enabled": true,
     "entries": {
       "nervepay": {
         "enabled": true,
         "config": {
           "apiUrl": "https://api.nervepay.xyz",
           "agentDid": "did:nervepay:agent:...",
-          "privateKey": "ed25519:...",
-          "enableOrchestration": false,
-          "enableAnalytics": true
+          "privateKey": "ed25519:..."
         }
       }
     }
@@ -88,445 +62,37 @@ If you prefer to configure manually or already have credentials:
 }
 ```
 
-Then restart gateway: `openclaw gateway restart`
-
-### Configuration Options
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `apiUrl` | string | No | NervePay API URL (default: https://api.nervepay.xyz) |
-| `agentDid` | string | No* | Agent DID (auto-configured by setup wizard) |
-| `privateKey` | string | No* | Ed25519 private key (auto-configured by setup wizard) |
-| `enableOrchestration` | boolean | No | Enable multi-agent orchestration (default: false) |
-| `enableAnalytics` | boolean | No | Enable analytics tracking (default: true) |
-
-*Required for authenticated operations (vault, gateway, orchestration)
-
-## Quick Start
-
-### 🚀 The Easy Way (Interactive Setup)
-
-```bash
-# 1. Install
-openclaw plugins install nervepay
-
-# 2. Run setup wizard
-openclaw nervepay setup
-```
-
-The wizard will ask you a few questions and configure everything automatically:
-
-```
-🔐 NervePay Setup Wizard
-
-📋 Step 1: Agent Information
-   Agent name: My Research Bot
-   Agent description: Helps with literature reviews
-
-🆔 Step 2: Registering Identity...
-   ✅ Identity created!
-   DID: did:nervepay:agent:abc123...
-
-👤 Step 3: Link to Human Owner
-   Link this agent to your NervePay account? [Y/n] y
-   Open this URL in your browser:
-   https://nervepay.xyz/claim/session-xyz
-
-   ✅ Agent claimed successfully!
-
-🔗 Step 4: Gateway Pairing
-   Connect this gateway to NervePay Mission Control? [y/N] y
-   Gateway name: Home Lab Gateway
-   Gateway URL: http://127.0.0.1:18789
-
-   ✅ Gateway paired successfully!
-
-⚙️  Step 5: Additional Features
-   Enable multi-agent orchestration? [y/N] n
-   Enable analytics tracking? [Y/n] y
-
-✅ Setup Complete!
-
-🔄 Next Steps:
-   1. Restart your OpenClaw gateway:
-      openclaw gateway restart
-
-   2. Test authentication:
-      openclaw nervepay whoami
-```
-
-### 🛠️ The Manual Way (Programmatic)
-
-If you prefer to use tools directly:
-
-```javascript
-// 1. Register identity
-const result = await nervepay_register_identity({
-  name: "My AI Agent",
-  description: "Purpose of this agent"
-});
-
-// 2. Save credentials (shown once only!)
-console.log("DID:", result.did);
-console.log("Private Key:", result.private_key);
-console.log("Mnemonic:", result.mnemonic);
-
-// 3. Update OpenClaw config with credentials
-// 4. Restart gateway
-// 5. Test authentication
-const info = await nervepay_whoami();
-```
-
-**⚠️ Setup wizard is recommended!** It handles all the tedious configuration automatically.
-
-## Available Tools
-
-### Identity Tools
-
-#### `nervepay_register_identity`
-
-Register a new agent identity with W3C DID and Ed25519 keys.
-
-**Parameters:**
-- `name` (string, required): Agent display name
-- `description` (string, optional): Agent description/purpose
-
-**Returns:**
-```typescript
-{
-  did: string;              // did:nervepay:agent:...
-  private_key: string;      // ed25519:...
-  public_key: string;       // Base58-encoded
-  mnemonic: string;         // 12-word BIP39 recovery phrase
-  session_id: string;       // For claim status polling
-  claim_url: string;        // Give to human owner (optional)
-}
-```
-
-#### `nervepay_whoami`
-
-Test authentication and get current agent info.
-
-**Returns:**
-```typescript
-{
-  agent_did: string;
-  name: string;
-  public_key: string;
-  capabilities: {
-    max_spending_limit_usd?: number;
-    allowed_operations?: string[];
-  };
-  reputation_score: number;  // 0-100
-  created_at: string;
-}
-```
-
-#### `nervepay_verify_agent`
-
-Verify another agent's identity (public endpoint, no auth required).
-
-**Parameters:**
-- `did` (string): Agent DID to verify
-
-#### `nervepay_resolve_did`
-
-Resolve W3C DID document.
-
-**Parameters:**
-- `did` (string): DID to resolve
-
-### Gateway Tools
-
-#### `nervepay_pair_gateway`
-
-Connect OpenClaw gateway to NervePay. Sends pairing request that requires human approval.
-
-**Parameters:**
-- `gateway_name` (string): Gateway display name
-- `gateway_url` (string): Gateway URL (must be reachable by NervePay)
-- `max_concurrent_agents` (number, optional): Max concurrent sub-agents (default: 8)
-- `default_timeout_seconds` (number, optional): Default task timeout (default: 3600)
-
-#### `nervepay_list_gateways`
-
-List all connected gateways.
-
-#### `nervepay_gateway_health`
-
-Check gateway health.
-
-**Parameters:**
-- `gateway_id` (string): Gateway ID
-
-### Vault Tools
-
-#### `nervepay_list_secrets`
-
-List all secrets (metadata only, no values).
-
-**Returns:**
-```typescript
-{
-  secrets: Array<{
-    id: string;
-    name: string;
-    description?: string;
-    created_at: string;
-    updated_at: string;
-  }>;
-}
-```
-
-#### `nervepay_get_secret`
-
-Get decrypted secret value by name.
-
-**Parameters:**
-- `secret_name` (string): Secret name
-
-**Returns:**
-```typescript
-{
-  secret: {
-    id: string;
-    name: string;
-    value: string;  // Decrypted value
-    description?: string;
-    created_at: string;
-    updated_at: string;
-  }
-}
-```
-
-#### `nervepay_get_secrets`
-
-Get multiple secrets at once.
-
-**Parameters:**
-- `secret_names` (string[]): Array of secret names
-
-**Returns:**
-```typescript
-Record<string, string>  // { name: value, ... }
-```
-
-### Orchestration Tools
-
-(Available when `enableOrchestration: true`)
-
-#### `nervepay_create_orchestration`
-
-Create multi-agent orchestration from PRD (Product Requirements Document).
-
-**Parameters:**
-- `gateway_id` (string): Gateway ID to spawn agents on
-- `name` (string): Orchestration name
-- `prd` (string): Product Requirements Document (JSON or text)
-- `context` (object, optional): Additional context data
-
-#### `nervepay_start_orchestration`
-
-Start orchestration (decomposes PRD and spawns sub-agent tasks).
-
-**Parameters:**
-- `orchestration_id` (string): Orchestration ID
-
-#### `nervepay_get_orchestration`
-
-Get orchestration status and progress.
-
-**Parameters:**
-- `orchestration_id` (string): Orchestration ID
-
-#### `nervepay_list_tasks`
-
-List tasks for an orchestration.
-
-**Parameters:**
-- `orchestration_id` (string): Orchestration ID
-- `status` (string, optional): Filter by status (pending/running/completed/failed/blocked)
-
-## CLI Commands
-
-```bash
-# Interactive setup wizard (⭐ recommended for first-time setup)
-openclaw nervepay setup
-
-# Show agent identity
-openclaw nervepay whoami
-
-# List connected gateways
-openclaw nervepay gateways
-
-# List secrets
-openclaw nervepay secrets
-```
-
-The `setup` command is **fully interactive** and handles everything automatically:
-- Identity registration
-- Human claim flow
-- Gateway pairing
-- OpenClaw config updates
-- Credentials backup
+Restart gateway after changes: `openclaw gateway restart`
 
-## Gateway RPC Methods
-
-```javascript
-// Health check
-gateway.rpc('nervepay.health');
-// => { status: 'ok', plugin: 'nervepay', version: '1.0.0' }
-
-// Get agent identity
-gateway.rpc('nervepay.whoami');
-// => { agent_did: '...', name: '...', ... }
-```
-
-## Auto-Reply Commands
-
-```
-/nervepay-status
-```
-
-Shows plugin status and configuration in chat.
+</details>
 
 ## Security
 
-### Authentication
-
-All authenticated requests use Ed25519 signatures with:
-- **Replay protection**: One-time nonces + 5-minute timestamp window
-- **Integrity**: Signature covers method, path, query, body hash
-- **Non-repudiation**: Only agent with private key can sign
-
-### Vault Encryption
-
-Secrets use AES-256-GCM envelope encryption:
-- Per-secret Data Encryption Keys (DEK)
-- Master Key Encryption Key (KEK) derived via HKDF-SHA256
-- Random 12-byte nonces per encryption
-- Comprehensive audit logging
-
-### Private Key Storage
-
-**DO NOT** commit private keys to git or share them. Store them in:
-- Environment variables
-- OpenClaw config (local only)
-- Hardware security modules (HSM)
-- Secure secret managers
-
-**BIP39 Mnemonic**: Backup the 12-word recovery phrase offline. It can regenerate the same Ed25519 keypair deterministically.
-
-## Use Cases
-
-### 1. Secure API Key Management
+**Authentication:** All requests signed with Ed25519 — replay protection via one-time nonces + 5-minute timestamp window. Signatures cover method, path, query, and body hash.
 
-Stop leaking API keys in OpenClaw skills! Store them in NervePay Vault:
-
-```javascript
-// Instead of this (insecure):
-const apiKey = "sk-proj-..."; // Leaked in skill code!
-
-// Do this:
-const { secret } = await nervepay_get_secret({
-  secret_name: "openai_api_key"
-});
-const apiKey = secret.value;
-```
-
-**Snyk found 280+ OpenClaw skills leaking API keys.** NervePay Vault fixes this with encrypted storage and audit logs.
-
-### 2. Cross-Platform Reputation
-
-Your agent's DID carries reputation across all 30+ OpenClaw channels:
-
-```javascript
-// Verify agent before trusting
-const { verified, agent } = await nervepay_verify_agent({
-  did: "did:nervepay:agent:abc123..."
-});
-
-if (verified && agent.reputation_score > 80) {
-  // High reputation, proceed with request
-}
-```
+**Vault:** AES-256-GCM envelope encryption with per-secret DEKs wrapped by a master KEK (HKDF-SHA256). All access audit-logged.
 
-### 3. Multi-Agent Orchestration
-
-Decompose complex PRDs into sub-agent tasks:
-
-```javascript
-// Create orchestration
-const orch = await nervepay_create_orchestration({
-  gateway_id: "gateway-123",
-  name: "Build User Dashboard",
-  prd: JSON.stringify({
-    title: "User Dashboard",
-    requirements: [
-      "Design landing page layout",
-      "Implement authentication",
-      "Create user profile page",
-      "Add analytics charts"
-    ]
-  })
-});
-
-// Start execution
-await nervepay_start_orchestration({
-  orchestration_id: orch.id
-});
-
-// Monitor progress
-const status = await nervepay_get_orchestration({
-  orchestration_id: orch.id
-});
-console.log(`Progress: ${status.progress_percentage}%`);
-```
-
-### 4. Agent-to-Agent Commerce
-
-Coming soon: x402 protocol integration for pay-per-request API monetization.
+**Key Storage:** Private keys live in local config only. BIP39 mnemonic shown once during setup — back it up offline for recovery.
 
 ## Development
 
-### Build
-
 ```bash
 npm install
 npm run build
-```
-
-### Test
-
-```bash
 npm test
-```
-
-### Watch mode
-
-```bash
-npm run dev
+npm run dev    # watch mode
 ```
 
 ## Links
 
-- **Website**: https://nervepay.xyz
-- **Dashboard**: https://nervepay.xyz/dashboard
-- **Docs**: https://nervepay.xyz/docs
-- **API Reference**: https://nervepay.xyz/docs/api
-- **GitHub**: https://github.com/nervepay/nervepay-plugin
-- **OpenClaw Docs**: https://docs.openclaw.ai/tools/plugin
-
-## Support
-
-- **Issues**: https://github.com/nervepay/nervepay-plugin/issues
-- **Discord**: https://discord.gg/nervepay
-- **Email**: hello@nervepay.xyz
+- [Website](https://nervepay.xyz)
+- [Dashboard](https://nervepay.xyz/dashboard)
+- [Docs](https://nervepay.xyz/docs)
+- [API Reference](https://nervepay.xyz/docs/api)
+- [GitHub](https://github.com/nervepay/nervepay-plugin)
+- [Issues](https://github.com/nervepay/nervepay-plugin/issues)
+- [Discord](https://discord.gg/nervepay)
 
 ## License
 
-MIT © NervePay
-
----
-
-**Built with ❤️ for the AI agent ecosystem**
+MIT