@agenticvault/agentic-vault 0.1.0

package/dist/providers/aws-kms/kms-signer-adapter.js

@@ -0,0 +1,101 @@
+import { hashTypedData, keccak256, serializeTransaction, toHex, } from 'viem';
+import { normalizeSignature, parseDerSignature, publicToAddress, resolveRecoveryParam, } from '../../evm-signer.util.js';
+export class KmsSignerAdapter {
+    keyId;
+    expectedAddress;
+    kmsClient;
+    addressPromise = null;
+    constructor(kmsClient, config) {
+        this.kmsClient = kmsClient;
+        this.keyId = config.keyId;
+        this.expectedAddress = config.expectedAddress;
+    }
+    /**
+     * Get the Ethereum address derived from the KMS public key.
+     * Uses promise memoization to avoid concurrent GetPublicKey calls during cold start.
+     */
+    getAddress() {
+        if (!this.addressPromise) {
+            this.addressPromise = this.deriveAddress();
+        }
+        return this.addressPromise;
+    }
+    /**
+     * Sign a transaction: serialize -> keccak256 -> KMS sign -> DER decode -> assemble signed tx.
+     */
+    async signTransaction(tx) {
+        const serialized = serializeTransaction(tx);
+        const digest = keccak256(serialized, 'bytes');
+        const { r, s, yParity } = await this.signDigestAndRecover(digest);
+        return serializeTransaction(tx, {
+            r: toHex(r, { size: 32 }),
+            s: toHex(s, { size: 32 }),
+            yParity,
+        });
+    }
+    /**
+     * Sign EIP-712 typed data. Returns {v, r, s} for permit-style calls.
+     * v = yParity + 27 (legacy recovery id format expected by EIP-2612 selfPermit).
+     */
+    async signTypedData(params) {
+        const hash = hashTypedData(params);
+        const digest = hexToBytes(hash);
+        const { r, s, yParity } = await this.signDigestAndRecover(digest);
+        return {
+            v: yParity + 27,
+            r: toHex(r, { size: 32 }),
+            s: toHex(s, { size: 32 }),
+        };
+    }
+    /**
+     * Health check: verify KMS key is configured correctly and address matches expectations.
+     */
+    async healthCheck() {
+        // 1. Verify key metadata
+        const metadata = await this.kmsClient.describeKey(this.keyId);
+        if (metadata.keySpec !== 'ECC_SECG_P256K1') {
+            throw new Error(`KMS key has invalid KeySpec: ${metadata.keySpec}, expected ECC_SECG_P256K1`);
+        }
+        if (metadata.keyUsage !== 'SIGN_VERIFY') {
+            throw new Error(`KMS key has invalid KeyUsage: ${metadata.keyUsage}, expected SIGN_VERIFY`);
+        }
+        if (metadata.keyState !== 'Enabled') {
+            throw new Error(`KMS key is not enabled: ${metadata.keyState}`);
+        }
+        // 2. Verify derived address matches expected address (if configured)
+        if (this.expectedAddress) {
+            const derivedAddress = await this.getAddress();
+            if (derivedAddress.toLowerCase() !== this.expectedAddress.toLowerCase()) {
+                throw new Error(`KMS derived address ${derivedAddress} does not match expected ${this.expectedAddress}`);
+            }
+        }
+    }
+    /**
+     * Internal: sign a 32-byte digest via KMS and resolve the recovery parameter.
+     */
+    async signDigestAndRecover(digest) {
+        const address = await this.getAddress();
+        const derSignature = await this.kmsClient.signDigest(this.keyId, digest);
+        const { r, s: rawS } = parseDerSignature(derSignature);
+        const { r: normalizedR, s } = normalizeSignature(r, rawS);
+        const yParity = await resolveRecoveryParam(digest, normalizedR, s, address);
+        return { r: normalizedR, s, yParity };
+    }
+    /**
+     * Internal: derive address from KMS public key.
+     */
+    async deriveAddress() {
+        const publicKey = await this.kmsClient.getPublicKey(this.keyId);
+        return publicToAddress(publicKey);
+    }
+}
+/** Convert a 0x-prefixed hex string to Uint8Array */
+function hexToBytes(hex) {
+    const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(stripped.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(stripped.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+//# sourceMappingURL=kms-signer-adapter.js.map

package/dist/providers/aws-kms/kms-signer-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kms-signer-adapter.js","sourceRoot":"","sources":["../../../src/providers/aws-kms/kms-signer-adapter.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+import type { Address, Hex, TransactionSerializable, TypedDataDefinition } from 'viem';
+export type SignatureComponents = {
+    v: number;
+    r: Hex;
+    s: Hex;
+};
+export type SignTypedDataParams = TypedDataDefinition;
+export interface SignerAdapter {
+    getAddress(): Promise<Address>;
+    signTransaction(tx: TransactionSerializable): Promise<Hex>;
+    signTypedData(params: SignTypedDataParams): Promise<SignatureComponents>;
+    healthCheck(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "@agenticvault/agentic-vault",
+  "version": "0.1.0",
+  "description": "Server-side EVM signing with AWS KMS and built-in DeFi protocol awareness. Expose your wallet to AI agents via MCP, CLI, or OpenClaw.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocols": {
+      "types": "./dist/protocols/index.d.ts",
+      "import": "./dist/protocols/index.js"
+    },
+    "./agentic": {
+      "types": "./dist/agentic/index.d.ts",
+      "import": "./dist/agentic/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "README.md",
+    "LICENSE",
+    ".claude-plugin",
+    "skills",
+    ".mcp.json.example",
+    "policy.example.json",
+    ".env.example"
+  ],
+  "bin": {
+    "agentic-vault": "./dist/cli/index.js",
+    "agentic-vault-mcp": "./dist/agentic/cli.js"
+  },
+  "packageManager": "pnpm@10.29.1",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agenticvault/agentic-vault"
+  },
+  "license": "MIT",
+  "keywords": [
+    "agentic",
+    "vault",
+    "wallet",
+    "aws",
+    "kms",
+    "cdp",
+    "ethereum",
+    "signer",
+    "evm",
+    "secp256k1",
+    "eip-712",
+    "typed-data",
+    "viem",
+    "server-wallet",
+    "mcp",
+    "ai-agent",
+    "claude-code",
+    "defi",
+    "uniswap",
+    "aave",
+    "openclaw",
+    "protocol-decoder",
+    "policy-engine"
+  ],
+  "bugs": {
+    "url": "https://github.com/agenticvault/agentic-vault/issues"
+  },
+  "homepage": "https://github.com/agenticvault/agentic-vault#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint src/ test/ --fix",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:e2e": "vitest run test/e2e",
+    "test:coverage": "vitest run test/unit --coverage",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "@aws-sdk/client-kms": "^3.985.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "viem": "^2.45.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.2.1",
+    "dotenv": "^17.2.4",
+    "eslint": "^9.39.2",
+    "tsx": "^4.19.4",
+    "typescript": "^5.9.3",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18"
+  }
+}

package/policy.example.json

@@ -0,0 +1,43 @@
+{
+  "allowedChainIds": [1, 11155111],
+  "allowedContracts": [
+    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+    "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45",
+    "0x87870bca3f3fd6335c3f4ce8392d69350b4fa4e2"
+  ],
+  "allowedSelectors": [
+    "0x095ea7b3",
+    "0xa9059cbb",
+    "0x04e45aaf",
+    "0x617ba037",
+    "0xa415bcad",
+    "0x573ade81",
+    "0x69328dec"
+  ],
+  "maxAmountWei": "1000000000000000000",
+  "maxDeadlineSeconds": 1800,
+  "protocolPolicies": {
+    "erc20": {
+      "maxAllowanceWei": "1000000000000000000",
+      "tokenAllowlist": [
+        "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+      ]
+    },
+    "uniswap_v3": {
+      "maxSlippageBps": 100,
+      "tokenAllowlist": [
+        "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+        "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
+      ],
+      "recipientAllowlist": []
+    },
+    "aave_v3": {
+      "tokenAllowlist": [
+        "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
+      ],
+      "maxInterestRateMode": 2,
+      "maxAmountWei": "1000000000000000000",
+      "recipientAllowlist": []
+    }
+  }
+}

package/skills/audit-log/SKILL.md

@@ -0,0 +1,32 @@
+# Audit Log
+
+Review and analyze audit logs from the Agentic Vault MCP server.
+
+## When to use
+
+Use this skill when the user wants to:
+- Review past signing operations
+- Check audit trail for security review
+- Analyze transaction signing history
+
+## Instructions
+
+1. Audit logs are written to stderr by the MCP server in JSON format.
+2. Each log entry contains:
+   - `timestamp`: When the operation occurred
+   - `traceId`: Unique trace identifier
+   - `service`: Always 'agentic-vault-mcp'
+   - `action`: The tool name (e.g., 'sign_swap')
+   - `who`: Caller identity
+   - `what`: Description of the operation
+   - `why`: Context/reason
+   - `result`: 'approved', 'denied', or 'error'
+   - `details`: Additional operation details
+
+3. Logs never contain private keys, secrets, or full addresses.
+
+## Example
+
+```
+Review the audit logs to show all recent signing operations and their results.
+```

package/skills/check-wallet/SKILL.md

@@ -0,0 +1,23 @@
+# Check Wallet
+
+Check the wallet address and health status through the Agentic Vault MCP server.
+
+## When to use
+
+Use this skill when the user wants to:
+- View their wallet address
+- Verify KMS key configuration
+- Check wallet health status
+
+## Instructions
+
+1. Use the `get_address` MCP tool to retrieve the wallet's Ethereum address.
+2. Use the `health_check` MCP tool to verify the KMS key configuration is valid.
+
+3. Never import or access signing keys directly. Always use the MCP tools.
+
+## Example
+
+```
+Use get_address to show the wallet address, then use health_check to verify the setup.
+```

package/skills/sign-permit/SKILL.md

@@ -0,0 +1,29 @@
+# Sign Permit
+
+Sign an EIP-2612 permit through the Agentic Vault MCP server.
+
+## When to use
+
+Use this skill when the user wants to sign a gasless token approval (EIP-2612 permit).
+
+## Instructions
+
+1. Use the `sign_permit` MCP tool with the following parameters:
+   - `chainId`: The target chain ID
+   - `token`: The ERC-20 token contract address
+   - `spender`: The approved spender address
+   - `value`: The approval amount in token units (string)
+   - `deadline`: Unix timestamp for permit expiry
+   - `domain`: The EIP-712 domain object
+   - `types`: The EIP-712 types definition
+   - `message`: The EIP-712 message object
+
+2. The tool enforces policy constraints before signing.
+
+3. Never import or access signing keys directly. Always use the MCP tool.
+
+## Example
+
+```
+Use the sign_permit tool to approve 1000 USDC for spender 0x... on chain 1
+```

package/skills/sign-swap/SKILL.md

@@ -0,0 +1,29 @@
+# Sign Swap
+
+Sign a swap transaction through the Agentic Vault MCP server.
+
+## When to use
+
+Use this skill when the user wants to sign a token swap transaction on a supported chain.
+
+## Instructions
+
+1. Use the `sign_swap` MCP tool with the following parameters:
+   - `chainId`: The target chain ID (e.g., 1 for Ethereum mainnet)
+   - `to`: The DEX router contract address
+   - `data`: The encoded swap calldata
+   - `value`: (Optional) ETH value in wei
+
+2. The tool enforces policy constraints:
+   - Chain ID must be whitelisted
+   - Contract must be whitelisted
+   - Function selector must be whitelisted
+   - Transaction value must be within limits
+
+3. Never import or access signing keys directly. Always use the MCP tool.
+
+## Example
+
+```
+Use the sign_swap tool to sign a swap on chain 1 to router 0x... with calldata 0x...
+```