m2m-sentinel-sdk 1.1.0 → 1.1.2

package/README.md

@@ -1,71 +1,146 @@
-# M2M Sentinel SDKs
-
-Base URL: `https://m2msentinel.vercel.app`.
-
-M2M Sentinel reports selected static bytecode capabilities, common proxy
-structures, evidence quality, and sourced Base market observations. It does not
-classify a contract as safe, malicious, or exploitable. Transaction middleware
-therefore requires a caller-defined policy and has no built-in allow threshold.
-
-## Support status
-
-Supported here: JavaScript/Node (`index.js`), TypeScript source, Python source,
-and the MCP stdio server. Other language folders are community previews and
-must be checked against `/openapi.json` before production use.
-
-## Install this source build
-
-```bash
-node -e "const { M2MSentinelClient } = require('./public/sdk')"
-python -m pip install ./public/sdk/python
-```
-
-Registry publishing is intentionally separate from the production API.
-The repository does not claim that these source-installable packages are available from every language registry.
-
-## Authentication and x402
-
-Send API keys only in `x-api-key` (or `Authorization: Bearer`). Query-string
-credentials are rejected. Payable routes also support x402 v2. An unpaid call
-returns a base64 `PAYMENT-REQUIRED` challenge when the facilitator is ready; a
-successful settlement returns `PAYMENT-RESPONSE`.
-
-## Public routes
-
-- `GET /v1/status`
-- `GET /v1/stats` (public counter-free privacy envelope; exact aggregate
-  commercial counters are operator-only)
-- `GET /v1/plans`
-- `GET /v1/demo/audit/:address` for the published sample allowlist
-- free-key and subscription onboarding routes
-
-The JavaScript, TypeScript, and Python clients expose multi-period
-purchase/renewal and wallet recovery without requiring callers to hand-build
-requests:
-
-```js
-await client.createSubscriptionIntent('GROWTH', wallet, {
-  durationDays: 90,
-  renewExistingKey: true,
-  apiKey: existingPaidKey
-});
-const challenge = await client.createRecoveryChallenge(wallet, { txHash });
-await client.claimRecoveredKey(challenge.intent.id, walletSignature);
-```
-
-`getPublicStats()` returns the counter-free privacy envelope. Operator-only
-detail has a deliberately separate `getOperatorAggregateStats(days, token)`
-method and sends the operator token only as `Authorization: Bearer`. This is
-for private server/operator tooling only: never embed or bundle the operator
-token in browser, mobile, SDK-distribution, or customer code.
-
-## Protected routes
-
-- `GET /v1/audit/:address`
-- `GET /v1/security/score/:address` (legacy URL; returns a capability coverage index)
-- Base gas, DEX, token-price, and large-transfer observation routes
-- key self-service routes
-
-All live-data responses preserve provenance. Capability responses include
-`notASafetyGuarantee: true`, a limitations array, `capabilityRating`, and an
-evidence-grade flag. Do not replace `UNVERIFIED` or `null` with a default.
+# M2M Sentinel SDKs
+
+Production API Base URL: `https://api.m2msentinel.com` (with fallback `https://m2msentinel.com`).
+
+Deterministic EVM bytecode and proxy capability intelligence on Base. Factual static capability observation — not a formal reachability audit, safety guarantee, or transaction advice. Live latency depends on RPC availability and deployment geography; transaction middleware requires a caller-defined policy and has no built-in decision threshold.
+
+---
+
+## 🏗️ Recommended Defense-in-Depth Pipeline for Agents
+
+Autonomous agents handling value must never rely on a single oracle or heuristic. M2M Sentinel can supply static observations as Layer 1 of a caller-owned pipeline:
+
+```text
+[Agent Intent] 
+       │
+       ▼
+[Transaction Builder]
+       │
+       ▼
+[Stage 1: M2M Sentinel Observation] ── (Bytecode hash, proxy target, selected opcode/selector evidence)
+       │
+       ▼
+[Stage 2: Local Policy Engine]    ── (Caller-defined rules: Check spending bounds, reject DELEGATECALL, verify allowlist)
+       │
+       ▼
+[Stage 3: Execution Simulation]   ── (eth_call / Tenderly / Trace state simulation)
+       │
+       ▼
+[Stage 4: Sub-Wallet Signing]     ── (Scoped ephemeral wallet signs & broadcasts on Base)
+```
+
+---
+
+## Installation
+
+### JavaScript / TypeScript (npm)
+
+```bash
+# Scoped package (recommended)
+npm install @m2msentinel/sdk
+
+# Or unscoped package
+npm install m2m-sentinel-sdk@1.1.2
+```
+
+### Python (PyPI)
+
+```bash
+pip install m2m-sentinel==1.1.2
+```
+
+### MCP Server (Model Context Protocol)
+
+```bash
+npx -y @m2msentinel/sdk
+# or
+npx -y m2m-sentinel-sdk
+```
+
+---
+
+## Quickstart: JavaScript / TypeScript
+
+```javascript
+const { M2MSentinelClient, X402SignerClient } = require('@m2msentinel/sdk');
+
+// 1. Standard API Client (Header Authentication)
+const client = new M2MSentinelClient({
+  apiKey: process.env.M2M_SENTINEL_API_KEY,
+  baseUrl: 'https://api.m2msentinel.com'
+});
+
+// Inspect contract capabilities before transaction
+const audit = await client.auditContract('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+console.log('Contract capabilities:', audit.audit.verdict.executableCapabilities);
+console.log('Capability evidence:', audit.audit.dissection.capabilities);
+console.log('Proxy Target:', audit.audit.proxyResolution.targetAddress);
+console.log('Reachability:', audit.audit.reachability || 'NOT_ESTABLISHED');
+
+// 2. Autonomous Headless x402 Micropayments (EIP-3009 Local Signing)
+const x402Client = new X402SignerClient({
+  walletSigner: myAgentWallet, // ethers / viem signer
+  baseUrl: 'https://api.m2msentinel.com',
+  maxPriceUsd: 0.01 // Optional: strict spending limit (default $0.05)
+});
+
+const res = await x402Client.fetchWithAutoPayment('/v1/audit/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+console.log('Paid analysis result:', res.json);
+```
+
+---
+
+## 🛡️ Autonomous Wallet Policy & Security Boundaries
+
+To prevent autonomous AI agents from blindly signing arbitrary or spoofed HTTP 402 challenges from untrusted sources, `X402SignerClient` enforces **4 strict client-side invariants** locally before generating any cryptographic signature:
+
+| Client Invariant | Enforced Value | Security Protection |
+| :--- | :--- | :--- |
+| **Chain ID** | `8453` (Base Mainnet) | Rejects signing on any unapproved EVM chain. |
+| **Asset Contract** | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | Rejects signing for unapproved tokens (Base USDC only). |
+| **Payout Recipient** | `0x6d6c398390cfb88f1cd42715b84906a0bd6652aa` | Rejects signing payments to unexpected recipient addresses. |
+| **Price Ceiling** | `maxPriceUsd` (Default: `$0.05`) | Throws if remote challenge requests funds exceeding caller's authorized ceiling. |
+
+```javascript
+import { X402SignerClient } from '@m2msentinel/sdk';
+
+// Fully policy-constrained autonomous signer with immutable recipient & domain constants
+const signer = new X402SignerClient({
+  wallet: agentWallet,
+  maxPriceUsd: 0.005 // Strict spending limit: 0.5 cents max per decision (default $0.05)
+});
+```
+
+---
+
+## Authentication and x402
+
+Send API keys only in `x-api-key` (or `Authorization: Bearer`). Query-string credentials are rejected with HTTP 401. Payable routes also support x402 v2 on Base USDC. An unpaid call returns a base64 `PAYMENT-REQUIRED` challenge; a successful settlement returns `PAYMENT-RESPONSE`.
+
+---
+
+## Public Routes
+
+- `GET /v1/status`
+- `GET /v1/stats` (public privacy envelope; exact aggregate commercial counters are operator-only)
+- `GET /v1/plans`
+- `GET /v1/demo/audit/:address` for the published sample allowlist
+- `GET /v1/audit/:address` (requires API key or x402 payment)
+
+The JavaScript, TypeScript, and Python clients expose multi-period purchase/renewal and wallet recovery without requiring callers to hand-build requests:
+
+```javascript
+await client.createSubscriptionIntent('GROWTH', wallet, {
+  durationDays: 90,
+  renewExistingKey: true,
+  apiKey: existingPaidKey
+});
+const challenge = await client.createRecoveryChallenge(wallet, { txHash });
+await client.claimRecoveredKey(challenge.intent.id, walletSignature);
+```
+
+---
+
+## Disclaimer & Limitations
+
+Deterministic EVM bytecode and proxy capability intelligence on Base. Factual static capability observation — not a formal reachability audit, safety guarantee, or transaction advice. Live latency depends on RPC availability and deployment geography.

package/agent_adapter.js

@@ -1,30 +1,276 @@
-// UNSUPPORTED / COMMUNITY PREVIEW — not covered by the supported-SDK guarantee; verify against /openapi.json before production use.
+'use strict';
 
-const { M2MSentinelClient } = require('./index.js');
+/**
+ * Coinbase AgentKit Action Provider for M2M Sentinel.
+ *
+ * Exposes pre-transaction contract bytecode capability inspection, proxy resolution,
+ * and market observations to autonomous Base agents using @coinbase/agentkit.
+ */
 
-class M2MSentinelAgentTool {
+const https = require('https');
+const http = require('http');
+
+const DEFAULT_BASE_URL = process.env.M2M_SENTINEL_BASE_URL || 'https://api.m2msentinel.com';
+const DEFAULT_TIMEOUT_MS = Number(process.env.M2M_SENTINEL_TIMEOUT_MS || 30000);
+
+function summarizeAuditResponse(body, requestedAddress) {
+  const audit = body && body.audit ? body.audit : {};
+  const proxy = audit.proxyResolution || {};
+  const capabilities = Array.isArray(audit.verdict && audit.verdict.executableCapabilities)
+    ? audit.verdict.executableCapabilities
+    : (audit.dissection && Array.isArray(audit.dissection.capabilities)
+        ? audit.dissection.capabilities
+          .map((item) => typeof item === 'string' ? item : item && item.type)
+          .filter(Boolean)
+        : []);
+
+  return {
+    address: audit.address || requestedAddress,
+    isContract: Boolean(audit.dissection && audit.dissection.isValidContract),
+    isProxy: Boolean(proxy.isProxy),
+    proxyType: proxy.proxyType || 'NONE',
+    targetAddress: proxy.targetAddress || null,
+    executableCapabilities: capabilities,
+    reachability: audit.reachability || 'NOT_ESTABLISHED',
+    trustLevel: audit.provenance && audit.provenance.trustLevel
+      ? audit.provenance.trustLevel
+      : 'NOT_REPORTED'
+  };
+}
+
+class M2MSentinelActionProvider {
   constructor(options = {}) {
-    this.name = 'm2m_sentinel_capability_analysis';
-    this.description = 'Reports selected static bytecode capabilities, common proxy structures, provenance, and limitations for Base contracts.';
-    this.client = new M2MSentinelClient({
-      apiKey: options.apiKey || process.env.M2M_SENTINEL_API_KEY,
-      baseUrl: options.baseUrl
+    this.name = 'm2m_sentinel';
+    this.actionProviderName = 'm2m_sentinel';
+    this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    this.apiKey = options.apiKey || process.env.M2M_SENTINEL_API_KEY || '';
+    this.timeoutMs = Number(options.timeoutMs || DEFAULT_TIMEOUT_MS);
+  }
+
+  supportsNetwork(network) {
+    if (!network) return true;
+    const chainId = String(network.chainId || network.networkId || '');
+    const protocolFamily = String(network.protocolFamily || 'evm').toLowerCase();
+    return protocolFamily === 'evm' && (
+      chainId === '8453' ||
+      chainId === 'base' ||
+      chainId === 'base-mainnet' ||
+      chainId === 'base-sepolia' ||
+      chainId === '84532'
+    );
+  }
+
+  async _queryApi(endpointPath, options = {}) {
+    const url = new URL(endpointPath, this.baseUrl);
+    const isHttps = url.protocol === 'https:';
+    const transport = isHttps ? https : http;
+
+    const headers = {
+      Accept: 'application/json',
+      'User-Agent': 'M2MSentinel-AgentKit/1.1.2',
+      ...options.headers
+    };
+    if (this.apiKey && !headers['x-api-key']) {
+      headers['x-api-key'] = this.apiKey;
+    }
+
+    return new Promise((resolve, reject) => {
+      const req = transport.request(url, {
+        method: 'GET',
+        headers,
+        timeout: this.timeoutMs
+      }, (res) => {
+        let data = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          let body = null;
+          if (data) {
+            try { body = JSON.parse(data); } catch (_) { body = { raw: data }; }
+          }
+          resolve({
+            statusCode: res.statusCode,
+            ok: res.statusCode >= 200 && res.statusCode < 300,
+            body
+          });
+        });
+      });
+
+      req.on('timeout', () => req.destroy(new Error('M2M Sentinel request timed out')));
+      req.on('error', reject);
+      req.end();
+    });
+  }
+
+  async auditContract(args) {
+    const address = String(args.address || args.contractAddress || '').trim();
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+      return JSON.stringify({
+        status: 'ERROR',
+        error: 'INVALID_ADDRESS',
+        message: 'A valid 40-hex 0x-prefixed Base contract address is required.'
+      });
+    }
+
+    const res = await this._queryApi(`/v1/audit/${encodeURIComponent(address)}`);
+    if (!res.ok) {
+      return JSON.stringify({
+        status: 'ERROR',
+        statusCode: res.statusCode,
+        error: res.body && res.body.error ? res.body.error : 'API_ERROR',
+        message: res.body && res.body.message ? res.body.message : 'Contract audit query failed',
+        notASafetyGuarantee: true
+      });
+    }
+
+    const observation = summarizeAuditResponse(res.body, address);
+    return JSON.stringify({
+      status: 'SUCCESS',
+      data: res.body,
+      notASafetyGuarantee: true,
+      observation,
+      observationSummary: `Contract ${observation.address}: isContract=${observation.isContract}, isProxy=${observation.isProxy}, proxyTarget=${observation.targetAddress || 'UNRESOLVED'}, capabilities=${observation.executableCapabilities.join(',') || 'NONE_OBSERVED'}, reachability=${observation.reachability}`
     });
   }
 
-  async _call(address) {
-    try {
-      return await this.client.auditContract(address);
-    } catch (err) {
-      return {
-        error: err.name || 'M2MSentinelError',
-        message: err.message,
-        status: err.status,
-        paymentRequired: err.paymentRequired || null,
-        retryAfter: err.retryAfter || null
-      };
+  async getGasMetrics() {
+    const res = await this._queryApi('/v1/gas/fees');
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve gas fees' });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  async getTokenPrice(args) {
+    const symbol = String(args.symbol || args.tokenSymbol || '').trim().toUpperCase();
+    if (!symbol) {
+      return JSON.stringify({ status: 'ERROR', message: 'Token symbol is required (e.g. USDC, WETH)' });
+    }
+    const res = await this._queryApi(`/v1/token/price/${encodeURIComponent(symbol)}`);
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: `Failed to retrieve price for ${symbol}` });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  async getServiceStatus() {
+    const res = await this._queryApi('/v1/status');
+    if (!res.ok) {
+      return JSON.stringify({ status: 'UNAVAILABLE', statusCode: res.statusCode });
     }
+    return JSON.stringify(res.body);
   }
+
+  async getDexLiquidity(args = {}) {
+    const pair = String(args.pair || 'WETH-USDC').trim();
+    const res = await this._queryApi(`/v1/dex/metrics?pair=${encodeURIComponent(pair)}`);
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve DEX liquidity' });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  async getWhaleSignals(args = {}) {
+    const limit = Number(args.limit || 10);
+    const res = await this._queryApi(`/v1/whales/signals?limit=${encodeURIComponent(limit)}`);
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve whale signals' });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  getActions(_walletProvider) {
+    return [
+      {
+        name: 'm2m_audit_contract',
+        description: 'Inspect Base target contract bytecode capability observations, proxy implementation slots, and limitations before executing transactions. Returns factual evidence, not a safety guarantee.',
+        schema: {
+          type: 'object',
+          properties: {
+            address: {
+              type: 'string',
+              description: 'Target Base contract address (0x-prefixed 40-hex)'
+            }
+          },
+          required: ['address']
+        },
+        invoke: (args) => this.auditContract(args)
+      },
+      {
+        name: 'm2m_get_gas_metrics',
+        description: 'Get real-time Base network gas execution metrics and recommendations before submitting on-chain transactions.',
+        schema: {
+          type: 'object',
+          properties: {}
+        },
+        invoke: () => this.getGasMetrics()
+      },
+      {
+        name: 'm2m_get_token_price',
+        description: 'Observe real-time Base DEX token price for slippage check and valuation.',
+        schema: {
+          type: 'object',
+          properties: {
+            symbol: {
+              type: 'string',
+              description: 'Token symbol on Base (e.g. USDC, WETH)'
+            }
+          },
+          required: ['symbol']
+        },
+        invoke: (args) => this.getTokenPrice(args)
+      },
+      {
+        name: 'm2m_get_dex_liquidity',
+        description: 'Get tracked Base DEX pool reserve and liquidity metrics.',
+        schema: {
+          type: 'object',
+          properties: {
+            pair: {
+              type: 'string',
+              description: 'DEX pair identifier (e.g. WETH-USDC)'
+            }
+          }
+        },
+        invoke: (args) => this.getDexLiquidity(args)
+      },
+      {
+        name: 'm2m_get_whale_signals',
+        description: 'Get tracked Base whale transfer and concentration signals.',
+        schema: {
+          type: 'object',
+          properties: {
+            limit: {
+              type: 'number',
+              description: 'Maximum signals to retrieve (1-50)'
+            }
+          }
+        },
+        invoke: (args) => this.getWhaleSignals(args)
+      },
+      {
+        name: 'm2m_get_service_status',
+        description: 'Check operational status of M2M Sentinel upstream verification rails.',
+        schema: {
+          type: 'object',
+          properties: {}
+        },
+        invoke: () => this.getServiceStatus()
+      }
+    ];
+  }
+}
+
+function m2mSentinelActionProvider(options = {}) {
+  return new M2MSentinelActionProvider(options);
 }
 
-module.exports = { M2MSentinelAgentTool };
+// Backward compatibility alias
+class M2MSentinelAgentTool extends M2MSentinelActionProvider {}
+
+module.exports = {
+  M2MSentinelActionProvider,
+  m2mSentinelActionProvider,
+  M2MSentinelAgentTool,
+  summarizeAuditResponse
+};

package/eliza_plugin.js

@@ -1,4 +1,9 @@
-// UNSUPPORTED / COMMUNITY PREVIEW — not covered by the supported-SDK guarantee; verify against /openapi.json before production use.
+/**
+ * M2M Sentinel ElizaOS Production Adapter Plugin
+ * 
+ * Provides automated pre-transaction contract capability preflight and proxy inspection
+ * actions for autonomous agents running on the ElizaOS runtime framework.
+ */
 
 const { M2MSentinelClient } = require('./index.js');
 
@@ -81,4 +86,4 @@ const m2mSentinelPlugin = {
   ]
 };
 
-module.exports = { m2mSentinelPlugin };
+module.exports = { m2mSentinelPlugin };