@financedistrict/fdx 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,148 @@
+# Architecture
+
+FDX is a three-layer system that gives AI agents secure access to blockchain wallets without managing private keys.
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          AI Agent                                   │
+│  (Asks: "What's my wallet balance?")                                │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                                 │ invokes
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       FDX npm Package                               │
+│                   (@financedistrict/fdx)                   │
+│                                                                     │
+│  ┌─────────────────┐                                               │
+│  │  CLI Commands   │                                               │
+│  │                 │                                               │
+│  │  • fdx setup    │                                               │
+│  │  • fdx status   │                                               │
+│  │  • fdx call     │                                               │
+│  │    <method>     │                                               │
+│  └─────────────────┘                                               │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │              WalletClient (SDK)                              │  │
+│  │  • OAuth 2.1 + DCR + PKCE authentication                    │  │
+│  │  • JSON-RPC 2.0 MCP protocol client                         │  │
+│  │  • High-level methods for wallet/DeFi operations             │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                                 │ HTTPS + OAuth 2.1
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    Finance District MCP Server                      │
+│                      (https://mcp.fd.xyz)                           │
+│                                                                     │
+│  • User authentication via OAuth 2.1                                │
+│  • Smart Account management (EVM + Solana)                          │
+│  • Multi-chain token transfers                                      │
+│  • DEX aggregation for swaps                                        │
+│  • DeFi yield strategy integration (Aave, Compound, Yearn)          │
+│  • X-402 payment protocol support                                   │
+│                                                                     │
+│  Supported Chains:                                                  │
+│  • Ethereum (1)                                                     │
+│  • BNB Smart Chain (56)                                             │
+│  • Arbitrum One (42161)                                             │
+│  • Base (8453)                                                      │
+│  • Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)                │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Key Components
+
+### 1. npm Package (`@financedistrict/fdx`)
+
+The npm package includes:
+
+- **CLI Tool** (`bin/fdx.js`): Command-line interface for setup, status checks, and method invocation
+- **SDK** (`src/wallet-client.js`): High-level JavaScript API with typed methods for each MCP tool
+- **OAuth Client** (`src/mcp-auth.js`): RFC 7591 Dynamic Client Registration with PKCE
+- **MCP Client** (`src/mcp-client.js`): JSON-RPC 2.0 protocol handler with SSE response format
+
+### 2. Finance District MCP Server
+
+The remote server (hosted at fd.xyz) provides:
+
+- **Authentication**: OAuth 2.1 with Microsoft Entra ID (no local keys)
+- **Smart Accounts**: EVM account abstraction via ERC-4337, deterministic Solana addresses
+- **Multi-Chain Support**: Single interface for ETH, BSC, ARB, BASE, SOL
+- **DeFi Integration**: Swap tokens via DEX aggregators, earn yield via Aave/Compound/Yearn
+- **Payment Protocol**: X-402 payment authorization for premium API access
+
+## Data Flow
+
+### Example: Agent Checks Wallet Balance
+
+1. **User asks agent**: _"What's my ETH balance?"_
+2. **Agent invokes CLI**: `fdx call getWalletOverview --chainKey ethereum`
+3. **CLI loads SDK**: `bin/commands/call.js` → `src/wallet-client.js` → `getWalletOverview()`
+4. **SDK authenticates**: Reads OAuth tokens from `~/.fdx/auth.json`
+5. **SDK calls MCP**: HTTPS request to `mcp.fd.xyz` with JSON-RPC 2.0 payload
+6. **Server queries chain**: Fetches balances from Ethereum RPC nodes
+7. **Response flows back**: JSON → SDK → CLI → stdout → Agent reads JSON
+8. **Agent formats answer**: _"You have 0.42 ETH in your Ethereum wallet (0xABC...)"_
+
+## Authentication Flow
+
+### First-Time Setup (`fdx setup`)
+
+1. **Generate PKCE challenge**: `S256(random_verifier)` → code_challenge
+2. **Register OAuth client**: POST to `/oauth/register` (RFC 7591 DCR)
+3. **Open browser**: User grants consent via Microsoft Entra ID
+4. **Exchange code**: Authorization code + verifier → access_token + refresh_token
+5. **Store tokens**: Save to `~/.fdx/auth.json`
+
+### Subsequent Requests
+
+1. **Load tokens**: Read from `~/.fdx/auth.json`
+2. **Check expiry**: If `access_token` expired, use `refresh_token` to get new token
+3. **Attach header**: `Authorization: Bearer <access_token>`
+4. **Make request**: HTTPS + JSON-RPC to MCP server
+
+No private keys, no seed phrases. All wallet operations are server-side with user consent via OAuth.
+
+## Security Model
+
+- **No Local Keys**: Agent never touches private keys. Wallets are managed server-side.
+- **OAuth 2.1**: Industry-standard authentication with PKCE protection.
+- **Consent-Based**: User authorizes agent via web browser on first setup.
+- **Token Refresh**: Long-lived refresh tokens minimize re-authentication.
+- **Smart Accounts**: ERC-4337 account abstraction allows multi-signature, recovery, upgradability.
+- **Audit Trail**: All transactions are recorded on-chain with transparent history.
+
+## Multi-Chain Support
+
+FDX abstracts chain differences behind a single API:
+
+| Chain    | Chain ID | Network Key | Address Format |
+| -------- | -------- | ----------- | -------------- |
+| Ethereum | 1        | ethereum    | 0x...          |
+| BSC      | 56       | bsc         | 0x...          |
+| Arbitrum | 42161    | arbitrum    | 0x...          |
+| Base     | 8453     | base        | 0x...          |
+| Solana   | (CAIP-2) | solana      | base58         |
+
+## DeFi Integration
+
+The MCP server integrates with DeFi protocols:
+
+- **DEX Aggregation**: 1inch, 0x, Jupiter (Solana) for best swap routes
+- **Yield Strategies**: Aave (lending), Compound (lending), Yearn (vaults)
+- **Smart Routing**: Policy-driven swap execution (BestExecution, LowGas, MevProtected)
+
+Agents can discover strategies, deposit tokens, and withdraw yield — all through `fdx call`.
+
+## Development & Testing
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for running from source.
+
+## License
+
+MIT

package/docs/DEVELOPMENT.md

@@ -0,0 +1,147 @@
+# Development Guide
+
+Step-by-step instructions to set up FDX for local development on any machine.
+
+---
+
+## Prerequisites
+
+- Node.js >= 18
+- Git
+- A browser for the OAuth consent flow
+
+---
+
+## 1. Clone the repo
+
+```bash
+git clone https://github.com/financedistrict-platform/fd-agent-wallet-cli.git
+cd fd-agent-wallet-cli
+```
+
+## 2. Install dependencies and link the CLI
+
+```bash
+npm install
+npm link
+```
+
+Verify the `fdx` command is available:
+
+```bash
+fdx
+```
+
+Should print usage info with `setup`, `status`, `call` commands.
+
+## 3. Run setup
+
+```bash
+fdx setup
+```
+
+This will:
+
+- Discover the OAuth server
+- Register a client dynamically (first time only)
+- Print an authorization URL — open it in your browser
+- Wait for the OAuth callback on `localhost:6260`
+- Exchange the code for tokens
+- Write tokens to `~/.fdx/auth.json`
+
+If the machine is headless and you can't open a browser, run `fdx setup` on your local machine instead, then copy the token file:
+
+```bash
+# From local machine
+scp ~/.fdx/auth.json user@server:~/.fdx/auth.json
+ssh user@server "chmod 600 ~/.fdx/auth.json"
+```
+
+## 4. Verify the CLI works
+
+```bash
+fdx status
+fdx call getMyInfo
+fdx call getAppVersion
+```
+
+All three should return data. If `fdx call` fails with auth errors, run `fdx setup` again.
+
+## 5. Environment Variables
+
+| Variable           | Description        | Default                                |
+| ------------------ | ------------------ | -------------------------------------- |
+| `FDX_MCP_SERVER`   | MCP server URL     | `https://mcp.fd.xyz`                   |
+| `FDX_REDIRECT_URI` | OAuth callback URI | `http://localhost:6260/oauth/callback` |
+| `FDX_STORE_PATH`   | Token store path   | `~/.fdx/auth.json`                     |
+| `FDX_LOG_PATH`     | Log file path      | `~/.fdx/fdx.log`                       |
+| `FDX_LOG_LEVEL`    | Log verbosity (`debug`\|`info`\|`warn`\|`error`\|`off`) | `info` |
+
+You can set these inline before a command, as persistent shell exports, or via a `.env` file in the working directory (see `.env.example`). The `.env` file is gitignored so values never end up in the repository.
+
+## 6. Testing against a non-production environment
+
+The CLI defaults to the production server. To point it at a different environment, override `FDX_MCP_SERVER` — the test server address is shared privately with the test team and must never be committed to the repository.
+
+**Option A — inline (one command):**
+
+```bash
+FDX_MCP_SERVER=https://... fdx setup --device
+FDX_MCP_SERVER=https://... fdx call getMyInfo
+```
+
+**Option B — shell export (current session):**
+
+```bash
+export FDX_MCP_SERVER=https://...
+fdx setup --device
+fdx call getMyInfo
+```
+
+**Option C — `.env` file (persistent, local only):**
+
+```bash
+cp .env.example .env
+# edit .env and uncomment FDX_MCP_SERVER=https://...
+fdx setup --device
+```
+
+The `.env` file is loaded automatically when the `fdx` binary starts. It is gitignored — do not commit it.
+
+---
+
+## Updating after code changes
+
+When changes are pushed to the repo:
+
+```bash
+cd fd-agent-wallet-cli
+git pull
+npm install
+npm link
+```
+
+---
+
+## Running Tests
+
+```bash
+npm test
+```
+
+## Linting
+
+```bash
+npm run lint
+npm run lint:fix  # auto-fix
+```
+
+---
+
+## Troubleshooting
+
+| Problem                   | Fix                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------- |
+| `fdx: command not found`  | Run `npm link` in the repo directory                                          |
+| Auth errors on `fdx call` | Run `fdx setup` to re-authenticate                                            |
+| Token expired             | Auto-refreshes via refresh token. If that also expired, run `fdx setup` again |

package/docs/UNINSTALL.md

@@ -0,0 +1,57 @@
+# Uninstall
+
+Remove FDX and all associated data.
+
+## Steps
+
+### For npm install users
+
+```bash
+# 1. Remove auth tokens and config
+rm -rf ~/.fdx
+
+# 2. Uninstall the package globally
+npm uninstall -g @financedistrict/fdx
+```
+
+### For development users (git clone)
+
+If you installed from source:
+
+```bash
+# 1. Remove auth tokens and config
+rm -rf ~/.fdx
+
+# 2. Unlink the CLI
+npm unlink -g @financedistrict/fdx
+
+# 3. Remove the repo
+rm -rf fd-agent-wallet-cli  # or wherever you cloned it
+```
+
+### OS Credential Store Cleanup
+
+If you used FDX with an OS credential store, secrets may persist in the
+system keychain after removing `~/.fdx`. Clean them up manually:
+
+**macOS (Keychain):**
+
+```bash
+security delete-generic-password -s fdx-wallet
+```
+
+**Linux (libsecret):**
+
+```bash
+secret-tool clear service fdx-wallet
+```
+
+**Windows:** Credentials are stored via DPAPI in `~/.fdx/.cred_*` files and
+are removed when you delete the `~/.fdx` directory. No additional cleanup
+is needed.
+
+## Verify
+
+```bash
+which fdx    # should return nothing
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@financedistrict/fdx",
+  "version": "0.1.0",
+  "description": "Agent wallet CLI — a command-line interface to the Finance District MCP wallet server",
+  "main": "src/index.js",
+  "bin": {
+    "fdx": "./bin/fdx.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/financedistrict-platform/fd-agent-wallet-cli.git"
+  },
+  "keywords": [
+    "fdx",
+    "finance-district",
+    "wallet",
+    "mcp",
+    "crypto",
+    "defi",
+    "agent",
+    "cli"
+  ],
+  "author": "Finance District",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/financedistrict-platform/fd-agent-wallet-cli/issues"
+  },
+  "homepage": "https://github.com/financedistrict-platform/fd-agent-wallet-cli#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "axios": "^1.13.5",
+    "commander": "^14.0.3",
+    "dotenv": "^16.6.1",
+    "nanospinner": "^1.2.2",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/credential-store.js

@@ -0,0 +1,226 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const SERVICE = 'fdx-wallet';
+const TIMEOUT = 10000;
+
+let _supported;
+
+/**
+ * Check if the OS credential store is available on this platform.
+ *  - macOS: Keychain via `security` CLI
+ *  - Linux: libsecret via `secret-tool` CLI
+ *  - Windows: DPAPI via PowerShell
+ */
+function isSupported() {
+  if (_supported !== undefined) return _supported;
+
+  try {
+    switch (process.platform) {
+      case 'darwin':
+        execFileSync('security', ['help'], { stdio: 'pipe', timeout: TIMEOUT });
+        _supported = true;
+        break;
+      case 'linux':
+        execFileSync('secret-tool', ['--help'], { stdio: 'pipe', timeout: TIMEOUT });
+        _supported = true;
+        break;
+      case 'win32':
+        execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', '$null'], {
+          stdio: 'pipe',
+          timeout: TIMEOUT,
+        });
+        _supported = true;
+        break;
+      default:
+        _supported = false;
+    }
+  } catch {
+    _supported = false;
+  }
+
+  return _supported;
+}
+
+/**
+ * Retrieve a secret from the OS credential store.
+ * @param {string} account - Unique account identifier (e.g. MCP server host).
+ * @returns {string|null} The secret string, or null if not found / not supported.
+ */
+function getSecret(account) {
+  if (!isSupported()) return null;
+
+  try {
+    switch (process.platform) {
+      case 'darwin':
+        return execFileSync(
+          'security',
+          ['find-generic-password', '-a', account, '-s', SERVICE, '-w'],
+          { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: TIMEOUT },
+        ).trim();
+
+      case 'linux':
+        return execFileSync('secret-tool', ['lookup', 'service', SERVICE, 'account', account], {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: TIMEOUT,
+        }).trim();
+
+      case 'win32':
+        return winDecrypt(account);
+
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store a secret in the OS credential store.
+ * @param {string} account - Unique account identifier.
+ * @param {string} secret - The secret value to store.
+ * @returns {boolean} True if stored successfully, false otherwise.
+ */
+function setSecret(account, secret) {
+  if (!isSupported()) return false;
+
+  try {
+    switch (process.platform) {
+      case 'darwin':
+        // Delete existing entry first (add-generic-password -U can be unreliable)
+        try {
+          execFileSync('security', ['delete-generic-password', '-a', account, '-s', SERVICE], {
+            stdio: 'pipe',
+            timeout: TIMEOUT,
+          });
+        } catch {
+          // Entry may not exist — ignore
+        }
+        // Use -w with stdin to avoid leaking the secret in process arguments
+        execFileSync('security', ['add-generic-password', '-a', account, '-s', SERVICE, '-w'], {
+          input: secret,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: TIMEOUT,
+        });
+        return true;
+
+      case 'linux':
+        execFileSync(
+          'secret-tool',
+          ['store', '--label', `FDX (${account})`, 'service', SERVICE, 'account', account],
+          { input: secret, stdio: ['pipe', 'pipe', 'pipe'], timeout: TIMEOUT },
+        );
+        return true;
+
+      case 'win32':
+        winEncrypt(account, secret);
+        return true;
+
+      default:
+        return false;
+    }
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delete a secret from the OS credential store.
+ * @param {string} account - Unique account identifier.
+ */
+function deleteSecret(account) {
+  if (!isSupported()) return;
+
+  try {
+    switch (process.platform) {
+      case 'darwin':
+        execFileSync('security', ['delete-generic-password', '-a', account, '-s', SERVICE], {
+          stdio: 'pipe',
+          timeout: TIMEOUT,
+        });
+        break;
+
+      case 'linux':
+        execFileSync('secret-tool', ['clear', 'service', SERVICE, 'account', account], {
+          stdio: 'pipe',
+          timeout: TIMEOUT,
+        });
+        break;
+
+      case 'win32':
+        winDeleteFile(account);
+        break;
+    }
+  } catch {
+    // Credential may not exist — ignore
+  }
+}
+
+// --- Windows DPAPI helpers ---
+// Tokens are encrypted with the current user's Windows login credentials
+// and stored in a file under ~/.fdx/
+
+function dpapiPath(account) {
+  const crypto = require('crypto');
+  const os = require('os');
+  const hash = crypto.createHash('sha256').update(account).digest('hex').slice(0, 16);
+  return path.join(os.homedir(), '.fdx', `.cred_${hash}`);
+}
+
+function winEncrypt(account, plaintext) {
+  const script = [
+    'Add-Type -AssemblyName System.Security',
+    '$bytes = [Text.Encoding]::UTF8.GetBytes([Console]::In.ReadToEnd())',
+    '$enc = [Security.Cryptography.ProtectedData]::Protect(' +
+      '$bytes, $null, [Security.Cryptography.DataProtectionScope]::CurrentUser)',
+    '[Convert]::ToBase64String($enc)',
+  ].join('; ');
+
+  const encrypted = execFileSync(
+    'powershell',
+    ['-NoProfile', '-NonInteractive', '-Command', script],
+    { input: plaintext, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: TIMEOUT },
+  ).trim();
+
+  const filePath = dpapiPath(account);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(filePath, encrypted, { mode: 0o600 });
+}
+
+function winDecrypt(account) {
+  const filePath = dpapiPath(account);
+  if (!fs.existsSync(filePath)) return null;
+
+  const encrypted = fs.readFileSync(filePath, 'utf8').trim();
+  if (!encrypted) return null;
+
+  const script = [
+    'Add-Type -AssemblyName System.Security',
+    '$bytes = [Convert]::FromBase64String([Console]::In.ReadToEnd())',
+    '$dec = [Security.Cryptography.ProtectedData]::Unprotect(' +
+      '$bytes, $null, [Security.Cryptography.DataProtectionScope]::CurrentUser)',
+    '[Text.Encoding]::UTF8.GetString($dec)',
+  ].join('; ');
+
+  return execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+    input: encrypted,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: TIMEOUT,
+  }).trim();
+}
+
+function winDeleteFile(account) {
+  try {
+    fs.unlinkSync(dpapiPath(account));
+  } catch {
+    // File may not exist — ignore
+  }
+}
+
+module.exports = { isSupported, getSecret, setSecret, deleteSecret };

package/src/factory.js

@@ -0,0 +1,29 @@
+const os = require('os');
+const path = require('path');
+
+const { WalletClient } = require('./wallet-client');
+
+const DEFAULT_MCP_SERVER = 'https://mcp.fd.xyz';
+
+function createClientFromEnv() {
+  const mcpServerUrl = process.env.FDX_MCP_SERVER || DEFAULT_MCP_SERVER;
+  const redirectUri = process.env.FDX_REDIRECT_URI;
+  const storePath = process.env.FDX_STORE_PATH;
+
+  const parsed = new URL(mcpServerUrl);
+  if (
+    parsed.protocol !== 'https:' &&
+    parsed.hostname !== 'localhost' &&
+    parsed.hostname !== '127.0.0.1'
+  ) {
+    throw new Error('FDX_MCP_SERVER must use HTTPS (HTTP is only allowed for localhost)');
+  }
+
+  return new WalletClient({
+    mcpServerUrl,
+    redirectUri: redirectUri || `http://localhost:6260/oauth/callback`,
+    storePath: storePath || path.join(os.homedir(), '.fdx', 'auth.json'),
+  });
+}
+
+module.exports = { createClientFromEnv };

package/src/index.js

@@ -0,0 +1,11 @@
+const { createClientFromEnv } = require('./factory');
+const { MCPAuthClient } = require('./mcp-auth');
+const { MCPClient } = require('./mcp-client');
+const { WalletClient } = require('./wallet-client');
+
+module.exports = {
+  MCPAuthClient,
+  MCPClient,
+  WalletClient,
+  createClientFromEnv,
+};