kontext-sdk 0.5.0 → 0.6.0

package/README.md

@@ -1,98 +1,207 @@
 # kontext-sdk
 
-Trust and compliance layer for agentic crypto workflows.
+Compliance audit trail CLI and SDK for AI agents making stablecoin payments on Base.
 
-Kontext provides structured action logging, tamper-evident audit trails, trust scoring, anomaly detection, and compliance tooling for AI agents operating in crypto and stablecoin ecosystems.
+**USDC** · **USDT** · **DAI** · **EURC** · **USDP** · **USDG** · **x402** · **Circle Programmable Wallets**
+
+---
+
+## 30-Second Demo
+
+```bash
+npx kontext-sdk check 0xAgentWallet 0xMerchant --amount 5000 --token USDC
+```
+
+```
+OFAC Sanctions:  CLEAR
+Travel Rule:     TRIGGERED ($5,000 >= $3,000 EDD threshold)
+CTR Threshold:   CLEAR ($5,000 < $10,000)
+Large TX Alert:  CLEAR ($5,000 < $50,000)
+Risk Level:      medium
+```
+
+No install. No config. No API key. One command.
 
 ## Install
 
 ```bash
-npm install kontext-sdk
+npm install -g kontext-sdk
 ```
 
-## Quick Start
+Then run `kontext` from anywhere. Or use `npx kontext-sdk` for one-off checks.
 
-```typescript
-import { Kontext } from 'kontext-sdk';
+## Claude Code / Cursor / Windsurf
 
-// Initialize in local mode (no API key needed)
-const kontext = Kontext.init({
-  projectId: 'my-project',
-  environment: 'development',
-});
+```json
+{
+  "mcpServers": {
+    "kontext": {
+      "command": "npx",
+      "args": ["-y", "kontext-sdk", "mcp"]
+    }
+  }
+}
+```
+
+Then ask: *"verify this USDC transaction for compliance"*
+
+## CLI Commands
+
+### `kontext check <from> <to>` — stateless compliance check
+
+```bash
+npx kontext-sdk check 0xSender 0xReceiver --amount 5000 --token USDC
+```
+
+Instant OFAC screening + threshold checks. No state, no persistence.
+
+### `kontext verify` — log + check + digest proof
 
-// Log an agent action
-await kontext.log({
-  type: 'transfer',
-  description: 'Agent initiated USDC transfer',
-  agentId: 'payment-agent-1',
+```bash
+npx kontext-sdk verify --tx 0xabc123 --amount 5000 --token USDC \
+  --from 0xAgent --to 0xMerchant --agent my-bot
+```
+
+Runs compliance checks, logs the transaction, appends to the tamper-evident digest chain. Persists to `.kontext/` in the current directory.
+
+### `kontext reason` — log agent reasoning
+
+```bash
+npx kontext-sdk reason "API returned data I need. Price within budget." \
+  --agent my-bot --session sess_abc --step 1
+```
+
+### `kontext cert` — export compliance certificate
+
+```bash
+npx kontext-sdk cert --agent my-bot --output cert.json
+```
+
+### `kontext audit` — verify digest chain integrity
+
+```bash
+npx kontext-sdk audit --verify
+```
+
+### `kontext mcp` — MCP server mode
+
+```bash
+npx kontext-sdk mcp
+```
+
+Starts an MCP server on stdio for Claude Code, Cursor, and Windsurf.
+
+### Flags
+
+- `--json` on any command outputs structured JSON
+- `--amount <number>` transaction amount in token units
+- `--token <symbol>` one of USDC, USDT, DAI, EURC, USDP, USDG
+
+## SDK — Programmatic Usage
+
+For tighter integration, use the SDK directly:
+
+```typescript
+import { Kontext, FileStorage } from 'kontext-sdk';
+
+const ctx = Kontext.init({
+  projectId: 'my-agent',
+  environment: 'production',
+  storage: new FileStorage('.kontext'),
 });
 
-// Log a transaction with full chain details
-await kontext.logTransaction({
+// One-call: compliance check + transaction log + digest proof
+const result = await ctx.verify({
   txHash: '0xabc...',
   chain: 'base',
-  amount: '100',
+  amount: '5000',
   token: 'USDC',
-  from: '0xSender...',
-  to: '0xReceiver...',
-  agentId: 'payment-agent-1',
+  from: '0xAgent...',
+  to: '0xMerchant...',
+  agentId: 'payment-agent',
 });
 
-// Get trust score for an agent
-const score = await kontext.getTrustScore('payment-agent-1');
-console.log(`Trust: ${score.score}/100 (${score.level})`);
+// result.compliant = true/false
+// result.checks = [{ name: 'OFAC Sanctions', passed: true }, ...]
+// result.riskLevel = 'low' | 'medium' | 'high' | 'critical'
+// result.digestProof = 'sha256:a1b2c3...'
+```
 
-// Export audit data
-const audit = await kontext.export({ format: 'json' });
+### Log Reasoning
 
-// Verify digest chain integrity
-const verification = kontext.verifyDigestChain();
-console.log(`Chain valid: ${verification.valid}`);
+```typescript
+await ctx.logReasoning({
+  agentId: 'payment-agent',
+  action: 'approve-transfer',
+  reasoning: 'Price within budget. Merchant verified.',
+  confidence: 0.95,
+});
 ```
 
-## Features
+### Compliance Certificate
 
-- **Action Logging** -- Structured logging for all agent actions with timestamps, correlation IDs, and metadata.
-- **Transaction Tracking** -- Full chain details for crypto transactions across Base, Ethereum, Polygon, Arbitrum, and Optimism.
-- **Tamper-Evident Digest Chain** -- Patented cryptographic digest chain that detects any modification to the audit trail.
-- **Trust Scoring** -- Rule-based trust scores for agents based on history, task completion, anomaly rate, and consistency.
-- **Anomaly Detection** -- Configurable rules for unusual amounts, frequency spikes, new destinations, off-hours activity, rapid succession, and round amounts.
-- **Task Confirmation** -- Evidence-based task tracking with required proof for completion.
-- **USDC Compliance** -- Pre-built compliance checks aligned with stablecoin regulatory requirements across all supported chains.
-- **CCTP Integration** -- Cross-chain transfer tracking for Circle's Cross-Chain Transfer Protocol with full lifecycle management.
-- **Webhook Notifications** -- Event-driven webhooks for anomalies, task updates, and trust score changes with retry logic.
-- **Audit Export** -- JSON and CSV export with date range and entity filtering.
-- **SAR/CTR Templates** -- Structured report templates for suspicious activity and currency transaction reporting.
+```typescript
+const cert = await ctx.generateComplianceCertificate({
+  agentId: 'payment-agent',
+  includeReasoning: true,
+});
+```
+
+### Trust Score
 
-## Supported Chains
+```typescript
+const score = await ctx.getTrustScore('payment-agent');
+// score.score = 87, score.level = 'high'
+```
 
-| Chain    | USDC Contract | CCTP Domain |
-|----------|---------------|-------------|
-| Ethereum | 0xA0b8...eB48 | 0           |
-| Base     | 0x8335...2913 | 6           |
-| Polygon  | 0x3c49...3359 | 7           |
-| Arbitrum | 0xaf88...5831 | 3           |
-| Optimism | 0x0b2C...Ff85 | 2           |
+### Verify Digest Chain
 
-## Operating Modes
+```typescript
+const chain = ctx.verifyDigestChain();
+console.log(chain.valid); // true — no tampering
+```
 
-- **Local mode** (no API key): All data stored in-memory and optionally written to local JSON files. Suitable for development and open-source usage.
-- **Cloud mode** (with API key): Data synced to Kontext API for persistent storage and advanced features.
+### Persist Across Restarts
 
 ```typescript
-// Cloud mode
-const kontext = Kontext.init({
-  apiKey: 'sk_live_...',
-  projectId: 'my-project',
+import { FileStorage } from 'kontext-sdk';
+
+const ctx = Kontext.init({
+  projectId: 'my-agent',
   environment: 'production',
+  storage: new FileStorage('.kontext'),
 });
+
+// Data persists to .kontext/ directory
+// Call ctx.flush() to write, ctx.restore() to reload
 ```
 
-## Documentation
+## Compliance Thresholds
+
+| Threshold | Amount | Trigger |
+|-----------|--------|---------|
+| **EDD / Travel Rule** | $3,000 | Enhanced Due Diligence required |
+| **CTR** | $10,000 | Currency Transaction Report |
+| **Large TX Alert** | $50,000 | Large Transaction Alert |
+
+OFAC sanctions screening uses the built-in SDN list. No API key required.
 
-For full documentation, visit [getkontext.com](https://getkontext.com).
+## What's Included
+
+- Tamper-evident audit trail (patented digest chain)
+- OFAC sanctions screening (SDN list, no API key)
+- Compliance certificates with SHA-256 proof
+- Agent reasoning logs
+- Trust scoring and anomaly detection
+- MCP server mode for AI coding tools
+- Zero runtime dependencies
 
 ## License
 
-MIT -- see [LICENSE](./LICENSE) for details.
+MIT
+
+---
+
+Kontext provides compliance logging tools. Regulatory responsibility remains with the operator. This software does not constitute legal advice and does not guarantee regulatory compliance. Consult qualified legal counsel for your specific obligations.
+
+Built by [Legaci Labs](https://www.getkontext.com)

package/dist/index.d.mts

@@ -178,7 +178,7 @@ declare class FileStorage implements StorageAdapter {
 /** Supported blockchain networks */
 type Chain = 'ethereum' | 'base' | 'polygon' | 'arbitrum' | 'optimism' | 'arc' | 'avalanche' | 'solana';
 /** Supported stablecoin tokens */
-type Token = 'USDC' | 'USDT' | 'DAI' | 'EURC';
+type Token = 'USDC' | 'USDT' | 'DAI' | 'EURC' | 'USDP' | 'USDG';
 /** SDK operating mode */
 type KontextMode = 'local' | 'cloud';
 /** Log level for the SDK logger */
@@ -373,19 +373,19 @@ interface LogActionInput {
     /** Arbitrary metadata */
     metadata?: Record<string, unknown>;
 }
-/** Input for logging a cryptocurrency transaction */
+/** Input for logging a transaction (crypto or general payment) */
 interface LogTransactionInput {
-    /** On-chain transaction hash */
-    txHash: string;
-    /** Blockchain network */
-    chain: Chain;
+    /** On-chain transaction hash (required for crypto, optional for general payments) */
+    txHash?: string;
+    /** Blockchain network (required for crypto, optional for general payments) */
+    chain?: Chain;
     /** Transaction amount (string to preserve decimal precision) */
     amount: string;
-    /** Token being transferred */
-    token: Token;
-    /** Sender address */
+    /** Token being transferred (required for crypto, optional for general payments) */
+    token?: Token;
+    /** Sender address or entity name */
     from: string;
-    /** Recipient address */
+    /** Recipient address or entity name */
     to: string;
     /** ID of the agent initiating the transaction */
     agentId: string;
@@ -395,17 +395,28 @@ interface LogTransactionInput {
     correlationId?: string;
     /** Additional transaction metadata */
     metadata?: Record<string, unknown>;
+    /** Currency code for general payments (e.g., 'USD', 'EUR'). Inferred from token for crypto. */
+    currency?: string;
+    /** Payment method (e.g., 'wire', 'ach', 'card', 'crypto') */
+    paymentMethod?: string;
+    /** External payment reference (invoice ID, wire reference, etc.) */
+    paymentReference?: string;
 }
 /** Stored transaction record */
 interface TransactionRecord extends ActionLog {
     type: 'transaction';
-    txHash: string;
-    chain: Chain;
+    txHash?: string;
+    chain?: Chain;
     amount: string;
-    token: Token;
+    token?: Token;
     from: string;
     to: string;
+    currency?: string;
+    paymentMethod?: string;
+    paymentReference?: string;
 }
+/** Check whether a transaction input has all crypto-specific fields */
+declare function isCryptoTransaction(input: LogTransactionInput): boolean;
 /** Input for creating a new tracked task */
 interface CreateTaskInput {
     /** Human-readable task description */
@@ -612,8 +623,8 @@ interface TrustFactor {
 }
 /** Transaction evaluation result */
 interface TransactionEvaluation {
-    /** Transaction hash */
-    txHash: string;
+    /** Transaction hash (present for crypto transactions) */
+    txHash?: string;
     /** Risk score (0-100, higher = more risky) */
     riskScore: number;
     /** Risk level */
@@ -946,6 +957,16 @@ declare class DigestChain {
      * This can be embedded in outgoing messages as proof of the entire action history.
      */
     getTerminalDigest(): string;
+    /**
+     * Restore the terminal digest from persisted state.
+     * Called after loading actions from storage so that new actions
+     * chain correctly from the last stored digest instead of genesis.
+     *
+     * Does NOT reconstruct the links array — in-memory verification
+     * via verify() will not work after restore. Use the stored action
+     * digest/priorDigest fields for cross-process chain verification.
+     */
+    restoreTerminalDigest(digest: string): void;
     /**
      * Get the number of links in the chain.
      */
@@ -1346,6 +1367,8 @@ declare class Kontext {
     /**
      * Restore state from the attached storage adapter.
      * Loads previously persisted actions, transactions, tasks, and anomalies.
+     * Also restores the digest chain's terminal digest so that new actions
+     * chain correctly across process boundaries.
      * No-op if no storage adapter is configured.
      */
     restore(): Promise<void>;
@@ -1581,7 +1604,7 @@ declare class Kontext {
      * and cryptographically verifies the digest chain integrity.
      *
      * The certificate includes: action/transaction/reasoning counts, digest chain
-     * verification status (Patent US 12,463,819 B1), the agent's current trust
+     * verification status (patented), the agent's current trust
      * score, and an overall compliance status. A SHA-256 content hash of the
      * certificate itself is included for tamper-evidence.
      *
@@ -1665,148 +1688,6 @@ declare class Kontext {
     destroy(): Promise<void>;
 }
 
-interface FirestoreStorageConfig {
-    /** GCP project ID — use "Kontext" for the Kontext production project */
-    gcpProjectId: string;
-    /**
-     * The user/tenant ID that owns these logs. Required for data isolation.
-     * Use a stable identifier: Stripe customer ID, your auth system's user ID,
-     * or a deterministic hash of the API key.
-     */
-    userId: string;
-    /**
-     * OAuth2 access token for the Firestore REST API.
-     * On GCP (Cloud Run, GCE, GKE): omit — the adapter will fetch a token
-     * from the GCP metadata server automatically.
-     * For local dev or other environments: pass a token from Application Default
-     * Credentials (`gcloud auth print-access-token`).
-     */
-    accessToken?: string;
-    /**
-     * Firestore database ID. Defaults to '(default)'.
-     * Change only if you created a named database in the GCP console.
-     */
-    databaseId?: string;
-    /**
-     * Whether to write each record as an individual Firestore document
-     * in addition to the bulk flush writes. Enables real-time querying
-     * per-action, per-session, per-agent.
-     * @default true
-     */
-    writeDocumentsIndividually?: boolean;
-    /**
-     * Custom Firestore REST base URL. Override for testing or emulator use.
-     * @default 'https://firestore.googleapis.com'
-     */
-    firestoreBaseUrl?: string;
-}
-/**
- * Persistent, hierarchical Firestore storage adapter for Kontext audit logs.
- *
- * Stores compliance logs by user → project → agent → session, enabling
- * regulatory-grade queries: "show me all transactions agent X made in
- * session Y" or "export all logs for user Z".
- *
- * Works as a drop-in replacement for FileStorage:
- *
- * @example
- * ```typescript
- * import { Kontext, FirestoreStorageAdapter } from 'kontext-sdk';
- *
- * const ctx = Kontext.init({
- *   projectId: 'treasury-agent',
- *   environment: 'production',
- *   storage: new FirestoreStorageAdapter({
- *     gcpProjectId: 'Kontext',
- *     userId: 'user-abc123',
- *   }),
- * });
- *
- * // After this, all verify(), log(), logReasoning() calls are
- * // persisted to Firestore at:
- * // users/user-abc123/projects/treasury-agent/agents/{agentId}/sessions/{sessionId}/...
- * ```
- */
-declare class FirestoreStorageAdapter implements StorageAdapter {
-    private readonly config;
-    /** In-memory cache for load() — avoids re-fetching on every store.restore() */
-    private cache;
-    /** Token cache: avoid metadata server round-trips on every write */
-    private cachedToken;
-    private tokenExpiresAt;
-    constructor(config: FirestoreStorageConfig);
-    /**
-     * Save data under a Kontext storage key.
-     *
-     * The flat key space (kontext:actions, kontext:transactions, etc.) is mapped
-     * to structured Firestore paths. List data (actions, transactions) is written
-     * as individual documents under sub-collections for queryability.
-     */
-    save(key: string, data: unknown): Promise<void>;
-    /**
-     * Load data for a Kontext storage key.
-     * Returns cached data if available (populated by save()).
-     * Falls back to Firestore fetch for cold starts.
-     */
-    load(key: string): Promise<unknown | null>;
-    delete(key: string): Promise<void>;
-    list(prefix?: string): Promise<string[]>;
-    /**
-     * Write a single action log to its canonical Firestore path.
-     * Called by the SDK when `writeDocumentsIndividually` is true.
-     *
-     * Path: users/{userId}/projects/{projectId}/agents/{agentId}/sessions/{sessionId}/actions/{actionId}
-     */
-    writeAction(action: ActionLog): Promise<void>;
-    /**
-     * Write a single transaction record to its canonical Firestore path.
-     *
-     * Path: users/{userId}/projects/{projectId}/agents/{agentId}/sessions/{sessionId}/transactions/{txId}
-     */
-    writeTransaction(tx: TransactionRecord): Promise<void>;
-    /**
-     * Write a single task to its canonical Firestore path.
-     *
-     * Path: users/{userId}/projects/{projectId}/tasks/{taskId}
-     */
-    writeTask(task: Task): Promise<void>;
-    private get basePath();
-    private actionPath;
-    private transactionPath;
-    private taskPath;
-    private anomalyPath;
-    private keyToPath;
-    private saveActionList;
-    private saveTransactionList;
-    private saveTaskList;
-    private saveAnomalyList;
-    private loadActionList;
-    private loadTransactionList;
-    private loadTaskList;
-    private loadAnomalyList;
-    private firestoreBase;
-    /** Save an arbitrary JS object as a Firestore document at the given path. */
-    private saveDocument;
-    /** Load a document at the given Firestore path. Returns null if not found. */
-    private loadDocument;
-    /** Delete a document at the given Firestore path. */
-    private deleteDocument;
-    /**
-     * List all documents in a collection and deserialize them.
-     * Used for tasks (simple flat collection).
-     */
-    private queryCollection;
-    /**
-     * Run a Firestore collection group query to fetch documents across all
-     * nested sub-collections with the given name (e.g., 'actions' across all
-     * agents and sessions).
-     *
-     * Scoped to the user's project root to prevent cross-tenant reads.
-     */
-    private queryCollectionGroup;
-    private getToken;
-}
-
 /** 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';
 /**
@@ -1941,6 +1822,21 @@ declare class UsdcCompliance {
     private static generateRecommendations;
 }
 
+declare class PaymentCompliance {
+    /**
+     * Run compliance checks on a general payment.
+     *
+     * @param input - Payment to evaluate
+     * @returns UsdcComplianceCheck with pass/fail results and recommendations
+     */
+    static checkPayment(input: LogTransactionInput): UsdcComplianceCheck;
+    private static checkAmountValid;
+    private static checkEntityScreening;
+    private static checkEnhancedDueDiligence;
+    private static checkReportingThreshold;
+    private static generateRecommendations;
+}
+
 /**
  * In-memory data store for the Kontext SDK.
  * Holds all action logs, transactions, tasks, and anomaly events.
@@ -2286,4 +2182,4 @@ declare class AnomalyDetector {
     private notifyCallbacks;
 }
 
-export { type ActionLog, type AgentData, type AnomalyCallback, type AnomalyDetectionConfig, AnomalyDetector, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type Chain, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceReport, type ConfirmTaskInput, ConsoleExporter, type CreateTaskInput, type DateRange, DigestChain, type DigestLink, type DigestVerification, type Environment, type EventExporter, type ExportFormat, type ExportOptions, type ExportResult, type ExporterResult, type FeatureFlag, type FeatureFlagConfig, FeatureFlagManager, FileStorage, FirestoreStorageAdapter, type FirestoreStorageConfig, type FlagPlanTargeting, type FlagScope, type FlagTargeting, type GatedFeature, type GenerateComplianceCertificateInput, JsonFileExporter, Kontext, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LimitEvent, type LogActionInput, type LogLevel, type LogReasoningInput, type LogTransactionInput, MemoryStorage, type MetadataValidator, NoopExporter, PLAN_LIMITS, type PlanConfig, PlanManager, type PlanTier, type PlanUsage, type PrecisionTimestamp, type ReasoningEntry, type ReportOptions, type ReportType, type RiskFactor, type SanctionsCheckResult, type StorageAdapter, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, TrustScorer, UsdcCompliance, type UsdcComplianceCheck, type VerifyInput, type VerifyResult, isFeatureAvailable, requirePlan, verifyExportedChain };
+export { type ActionLog, type AgentData, type AnomalyCallback, type AnomalyDetectionConfig, AnomalyDetector, type AnomalyEvent, type AnomalyRuleType, type AnomalySeverity, type AnomalyThresholds, type Chain, type ComplianceCertificate, type ComplianceCheckResult, type ComplianceReport, type ConfirmTaskInput, ConsoleExporter, type CreateTaskInput, type DateRange, DigestChain, type DigestLink, type DigestVerification, type Environment, type EventExporter, type ExportFormat, type ExportOptions, type ExportResult, type ExporterResult, type FeatureFlag, type FeatureFlagConfig, FeatureFlagManager, FileStorage, type FlagPlanTargeting, type FlagScope, type FlagTargeting, type GatedFeature, type GenerateComplianceCertificateInput, JsonFileExporter, Kontext, type KontextConfig, KontextError, KontextErrorCode, type KontextMode, type LimitEvent, type LogActionInput, type LogLevel, type LogReasoningInput, type LogTransactionInput, MemoryStorage, type MetadataValidator, NoopExporter, PLAN_LIMITS, PaymentCompliance, type PlanConfig, PlanManager, type PlanTier, type PlanUsage, type PrecisionTimestamp, type ReasoningEntry, type ReportOptions, type ReportType, type RiskFactor, type SanctionsCheckResult, type StorageAdapter, type Task, type TaskEvidence, type TaskStatus, type Token, type TransactionEvaluation, type TransactionRecord, type TrustFactor, type TrustScore, TrustScorer, UsdcCompliance, type UsdcComplianceCheck, type VerifyInput, type VerifyResult, isCryptoTransaction, isFeatureAvailable, requirePlan, verifyExportedChain };