m2m-sentinel-sdk 1.0.2 → 1.1.0

package/README.md

@@ -1,43 +1,71 @@
-# m2m-sentinel-sdk
-
-> Official Client SDK for M2M Sentinel: Autonomous Machine-to-Machine Web3 Security & AI Intelligence Engine.
-
-[![npm version](https://img.shields.io/npm/v/m2m-sentinel-sdk.svg)](https://www.npmjs.com/package/m2m-sentinel-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Installation
-
-```bash
-npm install m2m-sentinel-sdk
-```
-
-## Quickstart
-
-```javascript
-const { M2MSentinelClient } = require('m2m-sentinel-sdk');
-
-const client = new M2MSentinelClient();
-
-async function run() {
-  // Audit a Smart Contract
-  const audit = await client.auditContract('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
-  console.log('Contract Risk Audit:', audit);
-
-  // Fetch Real-Time Whale Transfer Alerts
-  const whales = await client.getWhaleSignals();
-  console.log('Whale Signals:', whales);
-}
-
-run();
-```
-
-## Features
-- **Smart Contract Risk Auditor** (`/v1/audit/:address`)
-- **Real-Time Whale Signals** (`/v1/whales/signals`)
-- **DEX Liquidity Depth & Spreads** (`/v1/dex/metrics`)
-- **AI Web Search Intelligence** (`/v1/search`)
-
-## Documentation & Portals
-- **Live Portal**: [https://m2msentinel.vercel.app](https://m2msentinel.vercel.app)
-- **API Docs**: [https://m2msentinel.vercel.app/docs.html](https://m2msentinel.vercel.app/docs.html)
-- **OpenAPI Spec**: [https://m2msentinel.vercel.app/openapi.json](https://m2msentinel.vercel.app/openapi.json)
+# 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.

package/agent_adapter.js

@@ -0,0 +1,30 @@
+// UNSUPPORTED / COMMUNITY PREVIEW — not covered by the supported-SDK guarantee; verify against /openapi.json before production use.
+
+const { M2MSentinelClient } = require('./index.js');
+
+class M2MSentinelAgentTool {
+  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
+    });
+  }
+
+  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
+      };
+    }
+  }
+}
+
+module.exports = { M2MSentinelAgentTool };

package/eliza_plugin.js

@@ -0,0 +1,84 @@
+// UNSUPPORTED / COMMUNITY PREVIEW — not covered by the supported-SDK guarantee; verify against /openapi.json before production use.
+
+const { M2MSentinelClient } = require('./index.js');
+
+function clientFor(runtime) {
+  const apiKey = runtime?.getSetting?.('M2M_SENTINEL_API_KEY') || process.env.M2M_SENTINEL_API_KEY;
+  return new M2MSentinelClient({ apiKey });
+}
+
+function errorText(err) {
+  if (err.status === 402) return 'M2M Sentinel payment required. Configure M2M_SENTINEL_API_KEY or settle the x402 challenge.';
+  if (err.status === 503 && err.body?.error === 'DATA_SOURCE_UNAVAILABLE') return 'M2M Sentinel data source unavailable; no estimated fallback value is returned.';
+  if (err.status === 429) return 'M2M Sentinel rate limited. Retry-After: ' + (err.retryAfter || 'not provided');
+  return 'M2M Sentinel API request failed: ' + err.message;
+}
+
+const m2mSentinelPlugin = {
+  name: '@elizaos/plugin-m2m-sentinel',
+  description: 'Preview ElizaOS actions for M2M Sentinel protected Web3 API routes.',
+  actions: [
+    {
+      name: 'AUDIT_CONTRACT',
+      description: 'Reports selected static capability and proxy observations for a Base contract.',
+      handler: async (runtime, message) => {
+        const address = message.content.text.match(/0x[a-fA-F0-9]{40}/)?.[0];
+        if (!address) return { text: 'Please provide a valid 42-character EVM contract address.' };
+        try {
+          const data = await clientFor(runtime).auditContract(address);
+          const audit = data.audit || {};
+          const proxy = audit.proxyResolution || {};
+          return { text: `M2M Sentinel capability analysis for ${address}: ${audit.capabilityRating || 'UNVERIFIED'}; proxy=${proxy.isProxy ? proxy.proxyType : 'NO'}; notASafetyGuarantee=true; provenance=${JSON.stringify(audit.provenance || data.provenance || null)}` };
+        } catch (err) { return { text: errorText(err) }; }
+      }
+    },
+    {
+      name: 'GET_CAPABILITY_SCORE',
+      description: 'Returns the static capability coverage index for a Base contract. The index is not a safety score.',
+      handler: async (runtime, message) => {
+        const address = message.content.text.match(/0x[a-fA-F0-9]{40}/)?.[0];
+        if (!address) return { text: 'Please provide a valid EVM contract address.' };
+        try {
+          const data = await clientFor(runtime).getCapabilityScore(address);
+          const score = data.capabilityScore === null ? 'unverified' : `${data.capabilityScore}/100 capability coverage`;
+          return { text: `M2M Sentinel static index for ${address}: ${score}; not a safety score. Provenance: ${JSON.stringify(data.provenance || null)}` };
+        } catch (err) { return { text: errorText(err) }; }
+      }
+    },
+    {
+      name: 'GET_DEX_METRICS',
+      description: 'Fetches Base DEX metrics.',
+      handler: async (runtime) => {
+        try { return { text: JSON.stringify(await clientFor(runtime).getDexMetrics()) }; }
+        catch (err) { return { text: errorText(err) }; }
+      }
+    },
+    {
+      name: 'GET_TOKEN_PRICE',
+      description: 'Queries a tracked Base token price.',
+      handler: async (runtime, message) => {
+        const symbol = (message.content.text.match(/price of ([a-zA-Z0-9]+)/i)?.[1] || 'USDC').toUpperCase();
+        try { return { text: JSON.stringify(await clientFor(runtime).getTokenPrice(symbol)) }; }
+        catch (err) { return { text: errorText(err) }; }
+      }
+    },
+    {
+      name: 'GET_GAS_FEES',
+      description: 'Fetches live Base gas fees.',
+      handler: async (runtime) => {
+        try { return { text: JSON.stringify(await clientFor(runtime).getGasFees()) }; }
+        catch (err) { return { text: errorText(err) }; }
+      }
+    },
+    {
+      name: 'GET_WHALE_SIGNALS',
+      description: 'Fetches whale signals.',
+      handler: async (runtime) => {
+        try { return { text: JSON.stringify(await clientFor(runtime).getWhaleSignals()) }; }
+        catch (err) { return { text: errorText(err) }; }
+      }
+    }
+  ]
+};
+
+module.exports = { m2mSentinelPlugin };

package/index.d.ts

@@ -0,0 +1,94 @@
+export interface M2MSentinelClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  paymentSignature?: string;
+}
+
+export interface CreateSubscriptionIntentOptions extends M2MSentinelClientOptions {
+  durationDays?: 31 | 90 | 365;
+  renewExistingKey?: boolean;
+}
+
+export interface RecoveryChallengeOptions {
+  txHash?: string;
+}
+
+export interface M2MSentinelErrorOptions {
+  status?: number;
+  body?: unknown;
+  retryAfter?: string | null;
+  paymentRequired?: unknown;
+  paymentResponse?: unknown;
+}
+
+export class M2MSentinelError extends Error {
+  readonly status?: number;
+  readonly body?: unknown;
+  readonly retryAfter?: string | null;
+  readonly paymentRequired?: unknown;
+  readonly paymentResponse?: unknown;
+  constructor(message: string, options?: M2MSentinelErrorOptions);
+}
+
+export class PaymentRequiredError extends M2MSentinelError {}
+export class RateLimitedError extends M2MSentinelError {}
+export class DataSourceUnavailableError extends M2MSentinelError {}
+
+export class M2MSentinelClient {
+  constructor(options?: M2MSentinelClientOptions);
+  constructor(apiKey?: string, baseUrl?: string);
+  request(method: string, path: string, body?: unknown, options?: M2MSentinelClientOptions): Promise<any>;
+  getStatus(): Promise<any>;
+  getPublicStats(days?: number): Promise<any>;
+  /** Backward-compatible alias for getPublicStats; customer keys never reveal operator counters. */
+  getAggregateStats(days?: number): Promise<any>;
+  getOperatorAggregateStats(days: number, operatorToken: string): Promise<any>;
+  getPlans(): Promise<any>;
+  demoAudit(address: string): Promise<any>;
+  createFreeChallenge(userWallet: string): Promise<any>;
+  claimFreeTier(intentId: string, signature: string): Promise<any>;
+  createSubscriptionIntent(tier: string, userWallet: string, options?: CreateSubscriptionIntentOptions): Promise<any>;
+  claimSubscription(intentId: string, signature: string, txHash: string): Promise<any>;
+  createRecoveryChallenge(userWallet: string, options?: RecoveryChallengeOptions): Promise<any>;
+  claimRecoveredKey(intentId: string, signature: string): Promise<any>;
+  auditContract(address: string, options?: M2MSentinelClientOptions): Promise<any>;
+  getCapabilityScore(address: string, options?: M2MSentinelClientOptions): Promise<any>;
+  /** Legacy alias. The response is a capability coverage index, not a safety score. */
+  getSecurityScore(address: string, options?: M2MSentinelClientOptions): Promise<any>;
+  getGasFees(options?: M2MSentinelClientOptions): Promise<any>;
+  getDexMetrics(options?: M2MSentinelClientOptions): Promise<any>;
+  getTokenPrice(symbol: string, options?: M2MSentinelClientOptions): Promise<any>;
+  getWhaleSignals(options?: M2MSentinelClientOptions): Promise<any>;
+  getKeySelf(): Promise<any>;
+  revokeKey(confirm?: boolean): Promise<any>;
+}
+
+export type SentinelPolicy = (
+  analysis: any,
+  context: { targetAddress: string; integration: string }
+) => boolean | { allow: boolean; reason?: string } | Promise<boolean | { allow: boolean; reason?: string }>;
+
+export function enforceCallerPolicy(
+  policy: SentinelPolicy | undefined,
+  analysis: any,
+  context: { targetAddress: string; integration: string }
+): Promise<void>;
+
+export function createEthersSentinelMiddleware(
+  apiKey?: string,
+  baseUrl?: string,
+  policy?: SentinelPolicy
+): {
+  client: M2MSentinelClient;
+  verifyContractBeforeTx(targetAddress: string, policyOverride?: SentinelPolicy): Promise<any>;
+};
+
+export function createViemSentinelInterceptor(
+  apiKey?: string,
+  baseUrl?: string,
+  policy?: SentinelPolicy
+): {
+  client: M2MSentinelClient;
+  inspectSwapTarget(address: string, policyOverride?: SentinelPolicy): Promise<any>;
+};

package/index.js

@@ -1,26 +1,183 @@
-const axios = require('axios');
-
-class M2MSentinelClient {
-    constructor(apiKey, baseUrl = 'https://m2msentinel.vercel.app') {
-        this.apiKey = apiKey;
-        this.baseUrl = baseUrl.replace(/\/+$/, '');
-        this.client = axios.create({
-            baseURL: this.baseUrl,
-            headers: {
-                'Authorization': `Bearer ${this.apiKey}`,
-                'Content-Type': 'application/json'
-            }
-        });
-    }
-
-    async getStatus() {
-        try {
-            const response = await this.client.get('/v1/status');
-            return response.data;
-        } catch (error) {
-            throw error;
-        }
-    }
-}
-
-module.exports = { M2MSentinelClient };
+const DEFAULT_BASE_URL = 'https://m2msentinel.vercel.app';
+const DEFAULT_TIMEOUT_MS = 30000;
+
+class M2MSentinelError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.status = options.status;
+    this.body = options.body;
+    this.retryAfter = options.retryAfter || null;
+    this.paymentRequired = options.paymentRequired || null;
+    this.paymentResponse = options.paymentResponse || null;
+  }
+}
+
+class PaymentRequiredError extends M2MSentinelError {}
+class RateLimitedError extends M2MSentinelError {}
+class DataSourceUnavailableError extends M2MSentinelError {}
+
+function parseX402Header(value) {
+  if (!value) return null;
+  // x402 v2 transports protocol objects as base64 JSON. Retain raw-JSON
+  // compatibility for older M2M Sentinel deployments during upgrades.
+  try { return JSON.parse(value); } catch (_) { /* try v2 encoding */ }
+  try {
+    const normalized = String(value).replace(/-/g, '+').replace(/_/g, '/');
+    const padded = normalized + '='.repeat((4 - normalized.length % 4) % 4);
+    return JSON.parse(Buffer.from(padded, 'base64').toString('utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function normalizeOptions(optionsOrApiKey, baseUrl) {
+  if (optionsOrApiKey && typeof optionsOrApiKey === 'object') return { ...optionsOrApiKey };
+  return { apiKey: optionsOrApiKey || undefined, baseUrl: baseUrl || DEFAULT_BASE_URL };
+}
+
+class M2MSentinelClient {
+  constructor(optionsOrApiKey, baseUrl) {
+    const options = normalizeOptions(optionsOrApiKey, baseUrl);
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.apiKey = options.apiKey || undefined;
+    this.timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
+    this.paymentSignature = options.paymentSignature || undefined;
+  }
+
+  async request(method, path, body, options = {}) {
+    const headers = {
+      'Accept': 'application/json'
+    };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    const apiKey = options.apiKey || this.apiKey;
+    if (apiKey) headers['x-api-key'] = apiKey;
+    if (options.operatorToken) headers.Authorization = 'Bearer ' + options.operatorToken;
+    const paymentSignature = options.paymentSignature || this.paymentSignature;
+    if (paymentSignature) headers['PAYMENT-SIGNATURE'] = paymentSignature;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs || this.timeoutMs);
+    let response;
+    try {
+      response = await fetch(this.baseUrl + path, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err && err.name === 'AbortError') throw new M2MSentinelError('M2M Sentinel request timed out', { status: 0 });
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    const text = await response.text();
+    let data = null;
+    if (text) {
+      try { data = JSON.parse(text); } catch (_) { data = { raw: text }; }
+    }
+
+    const paymentRequired = parseX402Header(response.headers.get('PAYMENT-REQUIRED'));
+    const paymentResponse = parseX402Header(response.headers.get('PAYMENT-RESPONSE')) || response.headers.get('PAYMENT-RESPONSE');
+    if (response.ok) return data;
+
+    const details = {
+      status: response.status,
+      body: data,
+      retryAfter: response.headers.get('Retry-After'),
+      paymentRequired,
+      paymentResponse
+    };
+    const message = data && data.message ? data.message : 'M2M Sentinel HTTP ' + response.status;
+    if (response.status === 402) throw new PaymentRequiredError(message, details);
+    if (response.status === 429) throw new RateLimitedError(message, details);
+    if (response.status === 503 && data && data.error === 'DATA_SOURCE_UNAVAILABLE') throw new DataSourceUnavailableError(message, details);
+    throw new M2MSentinelError(message, details);
+  }
+
+  getStatus() { return this.request('GET', '/v1/status'); }
+  getPublicStats(days = 30) { return this.request('GET', '/v1/stats?days=' + encodeURIComponent(days)); }
+  // Backward-compatible alias. Ordinary/customer credentials still receive
+  // only the counter-free public privacy envelope.
+  getAggregateStats(days = 30) { return this.getPublicStats(days); }
+  getOperatorAggregateStats(days, operatorToken) {
+    return this.request('GET', '/v1/stats?days=' + encodeURIComponent(days || 30), undefined, { operatorToken });
+  }
+  getPlans() { return this.request('GET', '/v1/plans'); }
+  demoAudit(address) { return this.request('GET', '/v1/demo/audit/' + encodeURIComponent(address)); }
+  createFreeChallenge(userWallet) { return this.request('POST', '/v1/subscribe/free/challenge', { userWallet }); }
+  claimFreeTier(intentId, signature) { return this.request('POST', '/v1/subscribe/free/claim', { intentId, signature }); }
+  createSubscriptionIntent(tier, userWallet, options = {}) {
+    const body = { tier, userWallet };
+    if (options.durationDays !== undefined) body.durationDays = options.durationDays;
+    if (options.renewExistingKey !== undefined) body.renewExistingKey = options.renewExistingKey;
+    return this.request('POST', '/v1/subscribe/intents', body, options);
+  }
+  claimSubscription(intentId, signature, txHash) { return this.request('POST', '/v1/subscribe/crypto', { intentId, signature, txHash }); }
+  createRecoveryChallenge(userWallet, options = {}) {
+    const body = { userWallet };
+    if (options.txHash !== undefined) body.txHash = options.txHash;
+    return this.request('POST', '/v1/keys/recovery/challenge', body);
+  }
+  claimRecoveredKey(intentId, signature) {
+    return this.request('POST', '/v1/keys/recovery/claim', { intentId, signature });
+  }
+  auditContract(address, options) { return this.request('GET', '/v1/audit/' + encodeURIComponent(address), undefined, options); }
+  getCapabilityScore(address, options) { return this.request('GET', '/v1/security/score/' + encodeURIComponent(address), undefined, options); }
+  // Legacy method name; the response is a capability coverage index, not a safety score.
+  getSecurityScore(address, options) { return this.request('GET', '/v1/security/score/' + encodeURIComponent(address), undefined, options); }
+  getGasFees(options) { return this.request('GET', '/v1/gas/fees', undefined, options); }
+  getDexMetrics(options) { return this.request('GET', '/v1/dex/metrics', undefined, options); }
+  getTokenPrice(symbol, options) { return this.request('GET', '/v1/token/price/' + encodeURIComponent(symbol), undefined, options); }
+  getWhaleSignals(options) { return this.request('GET', '/v1/whales/signals', undefined, options); }
+  getKeySelf() { return this.request('GET', '/v1/keys/self'); }
+  revokeKey(confirm = true) { return this.request('POST', '/v1/keys/revoke', { confirm }); }
+}
+
+async function enforceCallerPolicy(policy, analysis, context) {
+  if (typeof policy !== 'function') {
+    throw new Error('[M2M Sentinel] A caller-defined policy function is required. Static capability observations are not a safety decision.');
+  }
+  const result = await policy(analysis, context);
+  if (result === false || (result && result.allow === false)) {
+    const reason = result && result.reason ? result.reason : 'caller-defined policy rejected the transaction';
+    throw new Error('[M2M Sentinel] Transaction blocked: ' + reason + '.');
+  }
+}
+
+function createEthersSentinelMiddleware(apiKey, baseUrl, policy) {
+  const client = new M2MSentinelClient({ apiKey, baseUrl });
+  return {
+    client,
+    verifyContractBeforeTx: async (targetAddress, policyOverride) => {
+      const audit = await client.auditContract(targetAddress);
+      await enforceCallerPolicy(policyOverride || policy, audit, { targetAddress, integration: 'ethers' });
+      return audit;
+    }
+  };
+}
+
+function createViemSentinelInterceptor(apiKey, baseUrl, policy) {
+  const client = new M2MSentinelClient({ apiKey, baseUrl });
+  return {
+    client,
+    inspectSwapTarget: async (address, policyOverride) => {
+      const analysis = await client.getCapabilityScore(address);
+      await enforceCallerPolicy(policyOverride || policy, analysis, { targetAddress: address, integration: 'viem' });
+      return analysis;
+    }
+  };
+}
+
+module.exports = {
+  M2MSentinelClient,
+  M2MSentinelError,
+  PaymentRequiredError,
+  RateLimitedError,
+  DataSourceUnavailableError,
+  enforceCallerPolicy,
+  createEthersSentinelMiddleware,
+  createViemSentinelInterceptor
+};

package/m2m_sentinel_sdk.js

@@ -1,12 +1 @@
-class M2MSentinelSDK {
-    constructor(apiKey) {
-        this.apiKey = apiKey;
-        this.baseUrl = 'https://m2msentinel.vercel.app/v1';
-    }
-
-    async getTokenPrice() {
-        const response = await fetch(`${this.baseUrl}/token/price`);
-        return response.json();
-    }
-}
-module.exports = M2MSentinelSDK;
+module.exports = require('./index.js');