kontext-sdk 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -452,6 +452,12 @@ interface KontextConfig {
      * - 'both': pre-send screening + post-send full verify
      */
     interceptorMode?: 'post-send' | 'pre-send' | 'both';
+    /**
+     * Wallet provider configuration. When provided, SDK initializes the
+     * corresponding wallet manager (Circle, Coinbase, or MetaMask) for
+     * compliance-wrapped wallet operations.
+     */
+    walletProvider?: WalletProviderConfig;
 }
 /** Screening configuration for pluggable multi-provider sanctions screening */
 interface ScreeningConfig {
@@ -500,6 +506,141 @@ interface WalletMonitoringConfig {
     /** Polling interval in ms for HTTP transports (default: 12000) */
     pollingIntervalMs?: number;
 }
+type WalletProviderType = 'none' | 'circle' | 'coinbase' | 'metamask';
+type WalletProviderConfig = WalletProviderNone | WalletProviderCircle | WalletProviderCoinbase | WalletProviderMetaMask;
+interface WalletProviderNone {
+    type: 'none';
+}
+interface WalletProviderCircle {
+    type: 'circle';
+    apiKeyEnvVar: string;
+    entitySecretEnvVar: string;
+    circleEnvironment: 'sandbox' | 'production';
+    walletSetName?: string;
+    secretsStorage: SecretsStorageConfig;
+}
+interface WalletProviderCoinbase {
+    type: 'coinbase';
+    apiKeyIdEnvVar: string;
+    apiKeySecretEnvVar: string;
+    walletSecretEnvVar: string;
+    cdpEnvironment: 'testnet' | 'mainnet';
+    secretsStorage: SecretsStorageConfig;
+}
+interface WalletProviderMetaMask {
+    type: 'metamask';
+    clientIdEnvVar: string;
+    authConnectionId: string;
+    web3AuthNetwork: 'sapphire_mainnet' | 'sapphire_devnet';
+    secretsStorage: SecretsStorageConfig;
+}
+type SecretsStorageConfig = {
+    type: 'dotenv';
+    path: string;
+} | {
+    type: 'file';
+    path: string;
+} | {
+    type: 'gcp-secret-manager';
+    project: string;
+} | {
+    type: 'aws-secrets-manager';
+    region: string;
+} | {
+    type: 'hashicorp-vault';
+    address: string;
+};
+interface CircleWalletConfig {
+    apiKey: string;
+    entitySecret: string;
+    baseUrl?: string;
+}
+interface CreateWalletSetInput {
+    name: string;
+    idempotencyKey?: string;
+}
+interface CircleWalletSet {
+    id: string;
+    name: string;
+    custodyType: string;
+    createDate: string;
+    updateDate: string;
+}
+interface CreateWalletInput {
+    walletSetId: string;
+    blockchains: Chain[];
+    count?: number;
+    accountType?: 'EOA' | 'SCA';
+    idempotencyKey?: string;
+}
+interface CircleWallet {
+    id: string;
+    state: string;
+    address: string;
+    blockchain: string;
+    walletSetId: string;
+    createDate: string;
+}
+interface CircleTransferInput {
+    walletId: string;
+    tokenAddress: string;
+    destinationAddress: string;
+    amount: string;
+    blockchain: Chain;
+    agentId?: string;
+    idempotencyKey?: string;
+}
+interface CircleTransferResult {
+    id: string;
+    state: string;
+    txHash?: string;
+    complianceResult?: VerifyResult;
+}
+interface CoinbaseWalletConfig {
+    apiKeyId: string;
+    apiKeySecret: string;
+    walletSecret: string;
+}
+interface CoinbaseAccount {
+    address: string;
+    name?: string;
+    network: string;
+}
+interface CoinbaseTransferInput {
+    fromAddress: string;
+    toAddress: string;
+    amount: string;
+    token: Token;
+    network: string;
+    agentId?: string;
+}
+interface CoinbaseTransferResult {
+    transactionHash: string;
+    status: string;
+    complianceResult?: VerifyResult;
+}
+interface MetaMaskWalletConfig {
+    clientId: string;
+    authConnectionId: string;
+    web3AuthNetwork: 'sapphire_mainnet' | 'sapphire_devnet';
+}
+interface MetaMaskAccount {
+    address: string;
+    publicKey: string;
+}
+interface MetaMaskTransferInput {
+    toAddress: string;
+    amount: string;
+    token: Token;
+    chain: Chain;
+    agentId?: string;
+    idToken: string;
+}
+interface MetaMaskTransferResult {
+    transactionHash: string;
+    status: string;
+    complianceResult?: VerifyResult;
+}
 /**
  * Interface for metadata validation. Compatible with Zod schemas and any
  * validator that implements a `parse` method.
@@ -2410,6 +2551,9 @@ declare class Kontext {
     private behavioralFingerprinter;
     private crossSessionLinker;
     private confidenceScorer;
+    private circleWalletManager;
+    private coinbaseWalletManager;
+    private metamaskWalletManager;
     private constructor();
     /**
      * Initialize the Kontext SDK.
@@ -2474,6 +2618,12 @@ declare class Kontext {
     private getCrossSessionLinker;
     /** Lazy-init KYAConfidenceScorer on first use. */
     private getConfidenceScorer;
+    /** Lazy-init CircleWalletManager from config.walletProvider */
+    private getCircleManager;
+    /** Lazy-init CoinbaseWalletManager from config.walletProvider */
+    private getCoinbaseManager;
+    /** Lazy-init MetaMaskWalletManager from config.walletProvider */
+    private getMetaMaskManager;
     /**
      * Log a generic agent action.
      *
@@ -2929,6 +3079,25 @@ declare class Kontext {
      * Get the underlying FeatureFlagManager (or null if not configured).
      */
     getFeatureFlagManager(): FeatureFlagManager | null;
+    /** Create a Circle wallet set. Enterprise plan required. */
+    createCircleWalletSet(input: CreateWalletSetInput): Promise<CircleWalletSet>;
+    /** Create Circle wallet(s) in a wallet set. Enterprise plan required. */
+    createCircleWallet(input: CreateWalletInput): Promise<CircleWallet[]>;
+    /** Transfer via Circle with auto-compliance. Enterprise plan required. */
+    circleTransferWithCompliance(input: CircleTransferInput): Promise<CircleTransferResult>;
+    /** Create a Coinbase CDP account. Enterprise plan required. */
+    createCoinbaseAccount(opts?: {
+        name?: string;
+        network?: string;
+    }): Promise<CoinbaseAccount>;
+    /** List Coinbase CDP accounts. Enterprise plan required. */
+    listCoinbaseAccounts(): Promise<CoinbaseAccount[]>;
+    /** Transfer via Coinbase CDP with auto-compliance. Enterprise plan required. */
+    coinbaseTransferWithCompliance(input: CoinbaseTransferInput): Promise<CoinbaseTransferResult>;
+    /** Connect to MetaMask Embedded Wallet for a user. Enterprise plan required. */
+    metamaskConnect(idToken: string): Promise<MetaMaskAccount>;
+    /** Transfer via MetaMask with auto-compliance. Enterprise plan required. */
+    metamaskTransferWithCompliance(input: MetaMaskTransferInput): Promise<MetaMaskTransferResult>;
     /**
      * Get the wallet monitor instance (or null if not configured).
      * Used by the viem interceptor for dedup registration.
@@ -2941,7 +3110,7 @@ declare class Kontext {
 }
 
 /** Features gated by plan tier */
-type GatedFeature = 'advanced-anomaly-rules' | 'sar-ctr-reports' | 'webhooks' | 'ofac-screening' | 'csv-export' | 'multi-chain' | 'cftc-compliance' | 'circle-wallets' | 'circle-compliance' | 'gas-station' | 'cctp-transfers' | 'approval-policies' | 'unified-screening' | 'blocklist-manager' | 'kya-identity' | 'kya-behavioral';
+type GatedFeature = 'advanced-anomaly-rules' | 'sar-ctr-reports' | 'webhooks' | 'ofac-screening' | 'csv-export' | 'multi-chain' | 'cftc-compliance' | 'circle-wallets' | 'circle-compliance' | 'gas-station' | 'cctp-transfers' | 'approval-policies' | 'unified-screening' | 'blocklist-manager' | 'kya-identity' | 'kya-behavioral' | 'coinbase-wallets' | 'metamask-wallets';
 /**
  * Check if a feature is available on the given plan.
  * Returns true if allowed, false if not.
@@ -4027,6 +4196,7 @@ interface KontextConfigFile {
         ctrAmount?: string;
     };
     apiKey?: string;
+    walletProvider?: WalletProviderConfig;
 }
 /**
  * Discover and load kontext.config.json by walking up from startDir.
@@ -4034,4 +4204,141 @@ interface KontextConfigFile {
  */
 declare function loadConfigFile(startDir?: string): KontextConfigFile | null;
 
-export { type ActionLog, type AgentCard, type AgentData, type AgentIdentity, AgentIdentityRegistry, type AgentLink, type AgentSession, type AggregatedScreeningResult, type AnchorResult, type AnchorVerification, type AnomalyCallback, type AnomalyDetectionConfig, AnomalyDetector, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type AttestationDecision, type AttestationPayload, type AttestationRequest, type AttestationResponse, type AttestationSignature, type BehavioralEmbedding, BehavioralFingerprinter, CHAIN_ID_MAP, CURRENCY_REQUIRED_LISTS, type Chain, ChainalysisFreeAPIProvider, ChainalysisOracleProvider, type CheckpointStatus, type ClusteringEvidence, type ClusteringHeuristic, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceReport, type ConfirmTaskInput, type ConsensusStrategy, ConsoleExporter, type CounterpartyAttestation, type CounterpartyConfig, type CreateCheckpointInput, type CreateSessionInput, type CreateTaskInput, CrossSessionLinker, type CrossSessionLinkerConfig, type DateRange, DigestChain, type DigestLink, type DigestVerification, type ERC8021Attribution, type ERC8021Config, type EntityStatus, type EntityType, type Environment, type EventExporter, type ExportFormat, type ExportOptions, type ExportResult, type ExporterResult, type FeatureFlag, type FeatureFlagConfig, FeatureFlagManager, FileStorage, type FinancialFeatures, type FlagPlanTargeting, type FlagScope, type FlagTargeting, type GatedFeature, type GenerateComplianceCertificateInput, type HumanAttestation, JsonFileExporter, type Jurisdiction, KONTEXT_BUILDER_CODE, type KYAConfidenceLevel, type KYAConfidenceScore, KYAConfidenceScorer, type KYAConfidenceScorerConfig, type KYAEnvelope, type KYAScoreComponent, type KYCProviderReference, type KYCStatus, Kontext, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LimitEvent, type LinkSignal, type LinkStatus, type LogActionInput, type LogLevel, type LogReasoningInput, type LogTransactionInput, type MatchType, MemoryStorage, type MetadataValidator, type NetworkFeatures, NoopExporter, OFACAddressProvider, OFACEntityProvider, type OnChainAnchorConfig, OnChainExporter, OpenSanctionsLocalProvider, OpenSanctionsProvider, type OperationalFeatures, PLAN_LIMITS, PaymentCompliance, type PlanConfig, PlanManager, type PlanTier, type PlanUsage, type PolicyConfig, type PrecisionTimestamp, type ProvenanceAction, type ProvenanceAttestor, type ProvenanceBundle, type ProvenanceBundleVerification, type ProvenanceCheckpoint, ProvenanceManager, type QueryType, type ReasoningEntry, type RegisterIdentityInput, type ReportOptions, type ReportType, type RiskFactor, STABLECOIN_CONTRACTS, type SanctionsCheckResult, type SanctionsList, ScreeningAggregator, type ScreeningAggregatorConfig, type ScreeningConfig, type ScreeningContext, type ScreeningMatch, type ScreeningProvider, type ScreeningResult, type SessionConstraints, type SessionStatus, type StorageAdapter, TOKEN_REQUIRED_LISTS, type Task, type TaskEvidence, type TaskStatus, type TemporalFeatures, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, TrustScorer, UKOFSIProvider, type UpdateIdentityInput, UsdcCompliance, type UsdcComplianceCheck, type VerificationKey, type VerifyInput, type VerifyResult, ViemComplianceError, type ViemInstrumentationOptions, type WalletClientLike, type WalletCluster, WalletClusterer, type WalletClusteringConfig, type WalletMapping, WalletMonitor, type WalletMonitoringConfig, anchorDigest, encodeERC8021Suffix, exchangeAttestation, fetchAgentCard, fetchTransactionAttribution, getAnchor, getRequiredLists, isBlockchainAddress, isCryptoTransaction, isFeatureAvailable, loadConfigFile, parseERC8021Suffix, providerSupportsQuery, requirePlan, verifyAnchor, verifyExportedChain, withKontextCompliance };
+/**
+ * CircleWalletManager wraps Circle Programmable Wallets (developer-controlled)
+ * with automatic compliance logging via Kontext.
+ *
+ * Enterprise plan-gated — plan checks enforced at the Kontext client level.
+ */
+declare class CircleWalletManager {
+    private readonly apiKey;
+    private readonly entitySecret;
+    private readonly baseUrl;
+    private kontext;
+    constructor(config: CircleWalletConfig);
+    /** Link to Kontext instance for auto-compliance logging */
+    setKontext(kontext: any): void;
+    /** Validate credentials by calling Circle's configuration endpoint */
+    validateCredentials(): Promise<boolean>;
+    /** Create a wallet set (container for wallets) */
+    createWalletSet(input: CreateWalletSetInput): Promise<CircleWalletSet>;
+    /** Create wallet(s) in a wallet set */
+    createWallet(input: CreateWalletInput): Promise<CircleWallet[]>;
+    /** List wallets, optionally filtered by wallet set */
+    listWallets(walletSetId?: string): Promise<CircleWallet[]>;
+    /** Get wallet token balances */
+    getBalance(walletId: string): Promise<{
+        token: string;
+        amount: string;
+    }[]>;
+    /** Transfer with auto-compliance: runs verify() before/after transfer */
+    transferWithCompliance(input: CircleTransferInput): Promise<CircleTransferResult>;
+    private headers;
+    private request;
+    private mapChain;
+}
+
+/**
+ * CoinbaseWalletManager wraps Coinbase Developer Platform (CDP) server wallets
+ * with automatic compliance logging via Kontext.
+ *
+ * Enterprise plan-gated — plan checks enforced at the Kontext client level.
+ *
+ * Auth model:
+ * - API requests: JWT Bearer token signed with apiKeySecret (Ed25519), 120s expiry
+ * - Wallet operations: X-Wallet-Auth header (JWT signed with walletSecret, 60s expiry)
+ */
+declare class CoinbaseWalletManager {
+    private readonly apiKeyId;
+    private readonly apiKeySecret;
+    private readonly walletSecret;
+    private readonly baseUrl;
+    private kontext;
+    constructor(config: CoinbaseWalletConfig);
+    /** Link to Kontext instance for auto-compliance logging */
+    setKontext(kontext: any): void;
+    /** Validate credentials by listing accounts */
+    validateCredentials(): Promise<boolean>;
+    /** Create an EVM account */
+    createAccount(opts?: {
+        name?: string;
+        network?: string;
+    }): Promise<CoinbaseAccount>;
+    /** List accounts */
+    listAccounts(): Promise<CoinbaseAccount[]>;
+    /** Get token balances for an address */
+    getBalances(address: string, network: string): Promise<{
+        token: string;
+        amount: string;
+    }[]>;
+    /** Transfer with auto-compliance: runs verify() before/after transfer */
+    transferWithCompliance(input: CoinbaseTransferInput): Promise<CoinbaseTransferResult>;
+    /**
+     * Build auth headers. CDP uses JWT Bearer tokens:
+     * - API auth: signed with apiKeySecret, apiKeyId as kid, 120s expiry
+     * - Wallet auth: X-Wallet-Auth header signed with walletSecret, 60s expiry
+     *
+     * Note: Full Ed25519 JWT signing requires the jose or crypto module.
+     * This implementation provides the header structure; production use
+     * should integrate with @coinbase/cdp-sdk for proper JWT signing.
+     */
+    private headers;
+    /**
+     * Build a minimal JWT structure. In production, this should use Ed25519
+     * signing via the crypto module or jose library. Here we build the
+     * structure that CDP expects.
+     */
+    private buildJwt;
+    private request;
+    private mapNetwork;
+}
+
+/**
+ * MetaMaskWalletManager wraps MetaMask Embedded Wallets (via Web3Auth Node SDK)
+ * with automatic compliance logging via Kontext.
+ *
+ * Enterprise plan-gated — plan checks enforced at the Kontext client level.
+ *
+ * Requirements:
+ * - `@web3auth/node-sdk` must be installed as a peer dependency
+ * - Stateless: each connect() call is independent (no session state)
+ * - Infura RPC access is pre-integrated (no separate key needed)
+ */
+declare class MetaMaskWalletManager {
+    private readonly clientId;
+    private readonly authConnectionId;
+    private readonly web3AuthNetwork;
+    private kontext;
+    constructor(config: MetaMaskWalletConfig);
+    /** Link to Kontext instance for auto-compliance logging */
+    setKontext(kontext: any): void;
+    /**
+     * Validate credentials by attempting to initialize Web3Auth.
+     * Returns false if @web3auth/node-sdk is not installed.
+     */
+    validateCredentials(): Promise<boolean>;
+    /**
+     * Connect and get account for a user.
+     * Requires a JWT idToken for custom auth via authConnectionId.
+     */
+    connect(idToken: string): Promise<MetaMaskAccount>;
+    /**
+     * Get the private key for an authenticated user.
+     * Use with caution — only for signing transactions server-side.
+     */
+    getPrivateKey(idToken: string): Promise<string>;
+    /** Transfer with auto-compliance: runs verify() before/after transfer */
+    transferWithCompliance(input: MetaMaskTransferInput): Promise<MetaMaskTransferResult>;
+    /**
+     * Dynamically import @web3auth/node-sdk. Returns null if not installed.
+     */
+    private loadWeb3Auth;
+    /**
+     * Require @web3auth/node-sdk — throws if not installed.
+     */
+    private requireWeb3Auth;
+    private getAccounts;
+    private requestPrivateKey;
+}
+
+export { type ActionLog, type AgentCard, type AgentData, type AgentIdentity, AgentIdentityRegistry, type AgentLink, type AgentSession, type AggregatedScreeningResult, type AnchorResult, type AnchorVerification, type AnomalyCallback, type AnomalyDetectionConfig, AnomalyDetector, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type AttestationDecision, type AttestationPayload, type AttestationRequest, type AttestationResponse, type AttestationSignature, type BehavioralEmbedding, BehavioralFingerprinter, CHAIN_ID_MAP, CURRENCY_REQUIRED_LISTS, type Chain, ChainalysisFreeAPIProvider, ChainalysisOracleProvider, type CheckpointStatus, type CircleTransferInput, type CircleTransferResult, type CircleWallet, type CircleWalletConfig, CircleWalletManager, type CircleWalletSet, type ClusteringEvidence, type ClusteringHeuristic, type CoinbaseAccount, type CoinbaseTransferInput, type CoinbaseTransferResult, type CoinbaseWalletConfig, CoinbaseWalletManager, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceReport, type ConfirmTaskInput, type ConsensusStrategy, ConsoleExporter, type CounterpartyAttestation, type CounterpartyConfig, type CreateCheckpointInput, type CreateSessionInput, type CreateTaskInput, type CreateWalletInput, type CreateWalletSetInput, CrossSessionLinker, type CrossSessionLinkerConfig, type DateRange, DigestChain, type DigestLink, type DigestVerification, type ERC8021Attribution, type ERC8021Config, type EntityStatus, type EntityType, type Environment, type EventExporter, type ExportFormat, type ExportOptions, type ExportResult, type ExporterResult, type FeatureFlag, type FeatureFlagConfig, FeatureFlagManager, FileStorage, type FinancialFeatures, type FlagPlanTargeting, type FlagScope, type FlagTargeting, type GatedFeature, type GenerateComplianceCertificateInput, type HumanAttestation, JsonFileExporter, type Jurisdiction, KONTEXT_BUILDER_CODE, type KYAConfidenceLevel, type KYAConfidenceScore, KYAConfidenceScorer, type KYAConfidenceScorerConfig, type KYAEnvelope, type KYAScoreComponent, type KYCProviderReference, type KYCStatus, Kontext, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LimitEvent, type LinkSignal, type LinkStatus, type LogActionInput, type LogLevel, type LogReasoningInput, type LogTransactionInput, type MatchType, MemoryStorage, type MetaMaskAccount, type MetaMaskTransferInput, type MetaMaskTransferResult, type MetaMaskWalletConfig, MetaMaskWalletManager, type MetadataValidator, type NetworkFeatures, NoopExporter, OFACAddressProvider, OFACEntityProvider, type OnChainAnchorConfig, OnChainExporter, OpenSanctionsLocalProvider, OpenSanctionsProvider, type OperationalFeatures, PLAN_LIMITS, PaymentCompliance, type PlanConfig, PlanManager, type PlanTier, type PlanUsage, type PolicyConfig, type PrecisionTimestamp, type ProvenanceAction, type ProvenanceAttestor, type ProvenanceBundle, type ProvenanceBundleVerification, type ProvenanceCheckpoint, ProvenanceManager, type QueryType, type ReasoningEntry, type RegisterIdentityInput, type ReportOptions, type ReportType, type RiskFactor, STABLECOIN_CONTRACTS, type SanctionsCheckResult, type SanctionsList, ScreeningAggregator, type ScreeningAggregatorConfig, type ScreeningConfig, type ScreeningContext, type ScreeningMatch, type ScreeningProvider, type ScreeningResult, type SecretsStorageConfig, type SessionConstraints, type SessionStatus, type StorageAdapter, TOKEN_REQUIRED_LISTS, type Task, type TaskEvidence, type TaskStatus, type TemporalFeatures, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, TrustScorer, UKOFSIProvider, type UpdateIdentityInput, UsdcCompliance, type UsdcComplianceCheck, type VerificationKey, type VerifyInput, type VerifyResult, ViemComplianceError, type ViemInstrumentationOptions, type WalletClientLike, type WalletCluster, WalletClusterer, type WalletClusteringConfig, type WalletMapping, WalletMonitor, type WalletMonitoringConfig, type WalletProviderCircle, type WalletProviderCoinbase, type WalletProviderConfig, type WalletProviderMetaMask, type WalletProviderNone, type WalletProviderType, anchorDigest, encodeERC8021Suffix, exchangeAttestation, fetchAgentCard, fetchTransactionAttribution, getAnchor, getRequiredLists, isBlockchainAddress, isCryptoTransaction, isFeatureAvailable, loadConfigFile, parseERC8021Suffix, providerSupportsQuery, requirePlan, verifyAnchor, verifyExportedChain, withKontextCompliance };