@obelyzk/sdk 1.4.0 → 1.5.0

package/dist/firewall/index.d.ts

@@ -1,166 +1,272 @@
-import * as starknet from 'starknet';
+import { T as TransactionFeatures, D as Decision, A as AgentFirewallSDK } from '../client-DFxKbDns.js';
+export { a as AgentStatus, C as ClassifyResult, E as EvaluateActionResult, F as FirewallConfig, R as ResolveResult, S as SubmitActionResult } from '../client-DFxKbDns.js';
+import 'starknet';
 
 /**
- * Types for the ZKML Agent Firewall SDK.
+ * ObelyZK Agent Middleware
  *
- * These types map 1:1 to the Rust classifier and Cairo AgentFirewallZK contract.
+ * Wraps agent tool execution with automatic ZKML classification.
+ * Designed for use with the Claude Agent SDK or any tool-calling agent framework.
+ *
+ * @example
+ * ```typescript
+ * import { createPolicyEnforcer } from '@obelyzk/sdk/firewall';
+ *
+ * const enforcer = createPolicyEnforcer({
+ *   proverUrl: 'http://localhost:8080',
+ *   agentId: 'my-agent-001',
+ * });
+ *
+ * // Check before executing an on-chain action
+ * const decision = await enforcer.checkAction({
+ *   target: '0x049d...',
+ *   value: '1000000000',
+ *   selector: '0xa9059cbb',
+ * });
+ *
+ * if (decision.allowed) {
+ *   // safe to execute
+ * } else {
+ *   console.log(decision.reason); // "Blocked: threat_score=85000"
+ * }
+ *
+ * // Get MCP server config for Claude Agent SDK
+ * const mcpConfig = enforcer.getMcpServerConfig();
+ * // Pass to agent's mcpServers option
+ *
+ * // Get allowed tools list
+ * const tools = enforcer.getAllowedTools();
+ * // Pass to agent's allowedTools option
+ * ```
  */
-/** Transaction features sent to the classifier. */
-interface TransactionFeatures {
-    /** Target contract address (hex, 0x-prefixed). */
-    target: string;
-    /** Transaction value (decimal string, u256). */
-    value?: string;
-    /** Function selector (hex, 4 bytes, 0x-prefixed). */
-    selector?: string;
-    /** Calldata (hex, after selector, 0x-prefixed). */
-    calldata?: string;
-    /** Agent's current trust score (0-100000). */
-    agentTrustScore?: number;
-    /** Agent's current strike count. */
-    agentStrikes?: number;
-    /** Agent age in blocks since registration. */
-    agentAgeBlocks?: number;
-    /** Target contract metadata. */
-    targetVerified?: boolean;
-    targetIsProxy?: boolean;
-    targetHasSource?: boolean;
-    targetInteractionCount?: number;
-    /** Behavioral features. */
-    txFrequency?: number;
-    uniqueTargets24h?: number;
-    avgValue24h?: number;
-    maxValue24h?: number;
+
+/** Policy enforcer configuration. */
+interface PolicyEnforcerConfig {
+    /** Prove-server base URL. */
+    proverUrl: string;
+    /** Agent ID for firewall registration. */
+    agentId?: string;
+    /** Starknet RPC URL (for on-chain queries). */
+    rpcUrl?: string;
+    /** Firewall contract address (for on-chain queries). */
+    firewallContract?: string;
+    /** Verifier contract address. */
+    verifierContract?: string;
+    /** API key for prove-server. */
+    apiKey?: string;
+    /** Threat score threshold for blocking (default: 70000). */
+    blockThreshold?: number;
+    /** Threat score threshold for escalation (default: 40000). */
+    escalateThreshold?: number;
+    /** Path to MCP server entry point (for getMcpServerConfig). */
+    mcpServerPath?: string;
 }
-/** Classifier decision. */
-type Decision = "approve" | "escalate" | "block";
-/** Result from evaluating a transaction through the ZKML classifier. */
-interface ClassifyResult {
-    /** Unique request ID. */
-    requestId: string;
+/** Result from checking an action. */
+interface ActionCheck {
+    /** Whether the action is allowed to proceed. */
+    allowed: boolean;
     /** Classifier decision. */
     decision: Decision;
     /** Threat score (0-100000). */
     threatScore: number;
-    /** Raw output scores: [safe, suspicious, malicious]. */
-    scores: [number, number, number];
-    /** IO commitment (Poseidon hash of classifier input + output). */
+    /** Human-readable reason for the decision. */
+    reason: string;
+    /** IO commitment from the proof (for audit trail). */
     ioCommitment: string;
-    /** Policy commitment (strict policy hash). */
+    /** Policy commitment hash. */
     policyCommitment: string;
     /** Proving time in milliseconds. */
     proveTimeMs: number;
 }
-/** Result from submitting an action to the firewall contract. */
-interface SubmitActionResult {
-    /** Action ID assigned by the contract. */
-    actionId: number;
-    /** Transaction hash. */
-    txHash: string;
-}
-/** Result from resolving an action with a verified proof. */
-interface ResolveResult {
-    /** Final decision after proof verification. */
-    decision: Decision;
-    /** Threat score applied to the agent. */
-    threatScore: number;
-    /** Transaction hash. */
-    txHash: string;
-}
-/** Agent trust status. */
-interface AgentStatus {
-    /** Whether the agent is registered. */
-    registered: boolean;
-    /** Whether the agent is active (not frozen). */
-    active: boolean;
-    /** Current trust score (0-100000, EMA smoothed). */
-    trustScore: number;
-    /** Current strike count. */
-    strikes: number;
-    /** Whether the agent is trusted (active + score < threshold + strikes < max). */
-    trusted: boolean;
-}
-/** Firewall SDK configuration. */
-interface FirewallConfig {
-    /** Prover server URL (for /api/v1/classify). */
-    proverUrl: string;
-    /** AgentFirewallZK contract address on Starknet. */
-    firewallContract: string;
-    /** ObelyskVerifier contract address on Starknet. */
-    verifierContract: string;
-    /** Starknet RPC URL. */
-    rpcUrl: string;
-    /** Starknet account for signing transactions. */
-    account?: starknet.Account;
-    /** API key for the prover server (optional). */
-    apiKey?: string;
+/**
+ * Create a policy enforcer for programmatic agent use.
+ *
+ * The enforcer wraps the AgentFirewallSDK and provides a simplified API
+ * for checking actions, getting MCP server configs, and building
+ * allowedTools lists for the Claude Agent SDK.
+ */
+declare function createPolicyEnforcer(config: PolicyEnforcerConfig): PolicyEnforcer;
+declare class PolicyEnforcer {
+    private sdk;
+    private config;
+    private blockThreshold;
+    private escalateThreshold;
+    constructor(config: PolicyEnforcerConfig);
+    /**
+     * Check whether an action should be allowed.
+     * Calls the ZKML classifier and returns a structured decision.
+     */
+    checkAction(tx: TransactionFeatures): Promise<ActionCheck>;
+    /**
+     * Check if a Bash command contains an on-chain transaction pattern.
+     * Returns the target address if found, null otherwise.
+     */
+    extractTarget(command: string): string | null;
+    /**
+     * Build a canUseTool callback for the Claude Agent SDK.
+     *
+     * Returns an async function that:
+     * - Auto-allows ObelyZK policy tools
+     * - Auto-allows safe read-only tools (Read, Glob, Grep)
+     * - Classifies Bash commands containing on-chain transactions
+     * - Blocks everything else
+     */
+    buildCanUseTool(): (tool: string, input: Record<string, unknown>) => Promise<{
+        approved: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Get the MCP server configuration for .claude/settings.json
+     * or Claude Agent SDK's mcpServers option.
+     */
+    getMcpServerConfig(): Record<string, unknown>;
+    /**
+     * Get the list of allowed tools for Claude Agent SDK.
+     * Includes safe read-only tools and all ObelyZK policy tools.
+     */
+    getAllowedTools(): string[];
+    /** Get the underlying AgentFirewallSDK for advanced use. */
+    getSDK(): AgentFirewallSDK;
 }
 
 /**
- * AgentFirewallSDK — ZKML-powered transaction guardrails for AI agents.
+ * CIRO Intelligence Client — Runtime Enrichment
  *
- * Wraps the full flow:
- *   1. Classify transaction via prove-server (/api/v1/classify)
- *   2. Submit action to AgentFirewallZK contract
- *   3. Submit ZKML proof to ObelyskVerifier (streaming or recursive)
- *   4. Resolve action with proven threat score
- *   5. Query approval status
+ * Fetches real-time address risk, transaction enrichment, and alerts
+ * from CIRO's blockchain data lake. Used by the classifier to augment
+ * the 48-feature input with on-chain intelligence before classification.
  *
  * @example
  * ```typescript
- * import { AgentFirewallSDK } from '@obelyzk/sdk/firewall';
+ * import { CiroClient } from '@obelyzk/sdk/firewall';
  *
- * const firewall = new AgentFirewallSDK({
- *   proverUrl: 'https://prover.bitsage.network',
- *   firewallContract: '0x...',
- *   verifierContract: '0x...',
- *   rpcUrl: process.env.STARKNET_RPC!,
- *   account: myAccount,
+ * const ciro = new CiroClient({
+ *   baseUrl: 'https://ciro.bitsage.network',
+ *   apiKey: process.env.CIRO_API_KEY!,
  * });
  *
- * const result = await firewall.evaluateAction({
- *   target: '0x1234...',
+ * // Enrich a transaction before classification
+ * const enrichment = await ciro.enrichTransaction({
+ *   target: '0x049d...',
  *   value: '1000000000',
  *   selector: '0xa9059cbb',
  * });
  *
- * if (result.decision === 'approve') {
- *   // safe to execute
- * }
+ * // Check address risk
+ * const risk = await ciro.getAddressRisk('0x049d...');
+ * console.log(risk.riskLevel, risk.riskScore); // "LOW", 12
+ *
+ * // Get recent alerts
+ * const alerts = await ciro.getRecentAlerts({ severity: 'CRITICAL' });
  * ```
  */
-
-declare class AgentFirewallSDK {
-    private config;
-    private provider;
-    constructor(config: FirewallConfig);
+/** CIRO client configuration. */
+interface CiroConfig {
+    /** CIRO Intelligence API base URL. */
+    baseUrl: string;
+    /** API key for authentication. */
+    apiKey: string;
+    /** Organization slug (default: "obelyzk"). */
+    org?: string;
+    /** Request timeout in ms (default: 10000). */
+    timeout?: number;
+}
+/** Address risk level. */
+type RiskLevel = "clean" | "low" | "medium" | "high" | "critical" | "unknown";
+/** Enrichment response from CIRO. */
+interface EnrichmentResult {
+    targetRisk: RiskLevel;
+    targetRiskScore: number;
+    targetVerified: boolean;
+    targetIsProxy: boolean;
+    targetHasSource: boolean;
+    targetInteractionCount: number;
+    targetUniqueCallers: number;
+    targetFirstSeenBlocksAgo: number;
+    isSanctioned: boolean;
+    sanctionLists: string[];
+    fortaAlerts24h: number;
+    fortaSeverityMax: string | null;
+    senderTxFrequency: number;
+    senderUniqueTargets24h: number;
+    senderAvgValue24h: number;
+    senderMaxValue24h: number;
+    senderAgeBlocks: number;
+    dataFreshnessS: number;
+    enrichmentTimeMs: number;
+}
+/** Address risk assessment. */
+interface AddressRisk {
+    address: string;
+    chain: string;
+    riskLevel: RiskLevel;
+    riskScore: number;
+    isContract: boolean;
+    isVerified: boolean;
+    isProxy: boolean;
+    isSanctioned: boolean;
+    sanctionLists: string[];
+    fortaAlertsCount: number;
+    knownExploitInvolvement: boolean;
+    exploitNames: string[];
+    totalTxCount: number;
+    clusterSize: number;
+}
+/** Alert from CIRO's detection pipeline. */
+interface CiroAlert {
+    alertId: string;
+    source: string;
+    severity: string;
+    chain: string;
+    timestamp: string;
+    addresses: string[];
+    txHash: string | null;
+    name: string;
+    description: string;
+}
+/** Data lake statistics. */
+interface DataLakeStats {
+    totalTransactions: number;
+    labeledTransactions: number;
+    labelDistribution: Record<string, number>;
+    lastUpdated: string;
+    fortaBotsActive: number;
+    addressesIndexed: number;
+    sanctionedAddresses: number;
+}
+declare class CiroClient {
+    private baseUrl;
+    private apiKey;
+    private org;
+    private timeout;
+    constructor(config: CiroConfig);
+    private get apiBase();
+    private request;
     /**
-     * Classify a transaction through the ZKML classifier.
-     *
-     * Sends the transaction features to the prove-server, which runs
-     * the MLP classifier and generates a GKR+STARK proof. Returns the
-     * proven threat score and decision.
-     *
-     * Does NOT submit anything on-chain — use `evaluateAction()` for
-     * the full flow including on-chain submission.
+     * Enrich a transaction with CIRO intelligence.
+     * Returns target risk, sanctions status, Forta alerts, and behavioral context.
+     */
+    enrichTransaction(params: {
+        target: string;
+        sender?: string;
+        value?: string;
+        selector?: string;
+    }): Promise<EnrichmentResult>;
+    /**
+     * Get risk assessment for a specific address.
+     */
+    getAddressRisk(address: string): Promise<AddressRisk>;
+    /**
+     * Get recent alerts from CIRO's detection pipeline.
      */
-    classify(tx: TransactionFeatures): Promise<ClassifyResult>;
+    getRecentAlerts(params?: {
+        severity?: string;
+        limit?: number;
+    }): Promise<CiroAlert[]>;
     /**
-     * Register a new agent on the firewall contract.
-     * The calling account becomes the agent owner.
+     * Get data lake statistics.
      */
-    registerAgent(agentId: string): Promise<string>;
-    /** Deactivate an agent (owner or contract admin). */
-    deactivateAgent(agentId: string): Promise<string>;
-    /** Reactivate an agent and reset strikes (agent owner only). */
-    reactivateAgent(agentId: string): Promise<string>;
-    /** Get the full status of an agent. */
-    getAgentStatus(agentId: string): Promise<AgentStatus>;
-    /** Check if a specific action has been approved. */
-    isActionApproved(actionId: number): Promise<boolean>;
-    /** Check if an agent is trusted. */
-    isAgentTrusted(agentId: string): Promise<boolean>;
-    private requireAccount;
+    getStats(): Promise<DataLakeStats>;
 }
 
-export { AgentFirewallSDK, type AgentStatus, type ClassifyResult, type Decision, type FirewallConfig, type ResolveResult, type SubmitActionResult, type TransactionFeatures };
+export { type ActionCheck, type AddressRisk, AgentFirewallSDK, type CiroAlert, CiroClient, type CiroConfig, type DataLakeStats, Decision, type EnrichmentResult, PolicyEnforcer, type PolicyEnforcerConfig, type RiskLevel, TransactionFeatures, createPolicyEnforcer };