kontext-sdk 0.2.0 → 0.2.1

package/dist/index.js

@@ -51,6 +51,8 @@ var KontextError = class extends Error {
 };
 
 // src/store.ts
+var DEFAULT_MAX_ENTRIES = 1e4;
+var EVICTION_RATIO = 0.1;
 var STORAGE_KEYS = {
   actions: "kontext:actions",
   transactions: "kontext:transactions",
@@ -63,6 +65,10 @@ var KontextStore = class {
   tasks = /* @__PURE__ */ new Map();
   anomalies = [];
   storageAdapter = null;
+  maxEntries;
+  constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+    this.maxEntries = maxEntries;
+  }
   /**
    * Attach a storage adapter for persistence.
    *
@@ -86,14 +92,15 @@ var KontextStore = class {
    */
   async flush() {
     if (!this.storageAdapter) return;
+    const actionsSnapshot = [...this.actions];
+    const transactionsSnapshot = [...this.transactions];
+    const tasksSnapshot = Array.from(this.tasks.entries());
+    const anomaliesSnapshot = [...this.anomalies];
     await Promise.all([
-      this.storageAdapter.save(STORAGE_KEYS.actions, this.actions),
-      this.storageAdapter.save(STORAGE_KEYS.transactions, this.transactions),
-      this.storageAdapter.save(
-        STORAGE_KEYS.tasks,
-        Array.from(this.tasks.entries())
-      ),
-      this.storageAdapter.save(STORAGE_KEYS.anomalies, this.anomalies)
+      this.storageAdapter.save(STORAGE_KEYS.actions, actionsSnapshot),
+      this.storageAdapter.save(STORAGE_KEYS.transactions, transactionsSnapshot),
+      this.storageAdapter.save(STORAGE_KEYS.tasks, tasksSnapshot),
+      this.storageAdapter.save(STORAGE_KEYS.anomalies, anomaliesSnapshot)
     ]);
   }
   /**
@@ -125,9 +132,12 @@ var KontextStore = class {
   // --------------------------------------------------------------------------
   // Actions
   // --------------------------------------------------------------------------
-  /** Append an action log entry. */
+  /** Append an action log entry. Evicts oldest 10% when maxEntries is exceeded. */
   addAction(action) {
     this.actions.push(action);
+    if (this.actions.length > this.maxEntries) {
+      this.actions.splice(0, Math.ceil(this.maxEntries * EVICTION_RATIO));
+    }
   }
   /** Retrieve all action log entries. */
   getActions() {
@@ -144,9 +154,12 @@ var KontextStore = class {
   // --------------------------------------------------------------------------
   // Transactions
   // --------------------------------------------------------------------------
-  /** Append a transaction record. */
+  /** Append a transaction record. Evicts oldest 10% when maxEntries is exceeded. */
   addTransaction(tx) {
     this.transactions.push(tx);
+    if (this.transactions.length > this.maxEntries) {
+      this.transactions.splice(0, Math.ceil(this.maxEntries * EVICTION_RATIO));
+    }
   }
   /** Retrieve all transaction records. */
   getTransactions() {
@@ -194,9 +207,12 @@ var KontextStore = class {
   // --------------------------------------------------------------------------
   // Anomalies
   // --------------------------------------------------------------------------
-  /** Append an anomaly event. */
+  /** Append an anomaly event. Evicts oldest 10% when maxEntries is exceeded. */
   addAnomaly(anomaly) {
     this.anomalies.push(anomaly);
+    if (this.anomalies.length > this.maxEntries) {
+      this.anomalies.splice(0, Math.ceil(this.maxEntries * EVICTION_RATIO));
+    }
   }
   /** Retrieve all anomaly events. */
   getAnomalies() {
@@ -397,7 +413,8 @@ var DigestChain = class {
    */
   getPrecisionTimestamp() {
     const hrtime = process.hrtime.bigint();
-    const microseconds = Number((hrtime - this.hrtimeBase) % 1000000n);
+    const delta = hrtime >= this.hrtimeBase ? hrtime - this.hrtimeBase : 0n;
+    const microseconds = Number(delta % 1000000n);
     return {
       iso: (/* @__PURE__ */ new Date()).toISOString(),
       hrtime,
@@ -492,6 +509,12 @@ function toCsv(records) {
 function clamp(value, min, max) {
   return Math.min(Math.max(value, min), max);
 }
+var LOG_LEVEL_SEVERITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
 var ActionLogger = class {
   config;
   store;
@@ -501,6 +524,7 @@ var ActionLogger = class {
   batchSize;
   flushIntervalMs;
   isCloudMode;
+  logLevel;
   constructor(config, store) {
     this.config = config;
     this.store = store;
@@ -508,6 +532,7 @@ var ActionLogger = class {
     this.batchSize = config.batchSize ?? 50;
     this.flushIntervalMs = config.flushIntervalMs ?? 5e3;
     this.isCloudMode = !!config.apiKey;
+    this.logLevel = config.logLevel ?? (config.debug ? "debug" : "warn");
     this.flushTimer = setInterval(() => {
       void this.flush();
     }, this.flushIntervalMs);
@@ -550,9 +575,7 @@ var ActionLogger = class {
     if (this.batch.length >= this.batchSize) {
       await this.flush();
     }
-    if (this.config.debug) {
-      this.debugLog("Action logged", action);
-    }
+    this.emitLog("debug", "Action logged", action);
     return action;
   }
   /**
@@ -604,9 +627,7 @@ var ActionLogger = class {
     if (this.batch.length >= this.batchSize) {
       await this.flush();
     }
-    if (this.config.debug) {
-      this.debugLog("Transaction logged", record);
-    }
+    this.emitLog("debug", "Transaction logged", record);
     return record;
   }
   /**
@@ -716,9 +737,7 @@ var ActionLogger = class {
       const lines = actions.map((a) => JSON.stringify(a)).join("\n") + "\n";
       fs2__namespace.appendFileSync(filePath, lines, "utf-8");
     } catch (error) {
-      if (this.config.debug) {
-        this.debugLog("Failed to write log file", { error });
-      }
+      this.emitLog("warn", "Failed to write log file", { error });
     }
   }
   async flushToApi(actions) {
@@ -742,15 +761,35 @@ var ActionLogger = class {
       }
     } catch (error) {
       if (error instanceof KontextError) throw error;
-      if (this.config.debug) {
-        this.debugLog("API flush failed, falling back to local file", { error });
-      }
+      this.emitLog("warn", "API flush failed, falling back to local file", { error });
       this.flushToFile(actions);
     }
   }
-  debugLog(message, data) {
+  /**
+   * Emit a log message at the specified severity level.
+   * Only outputs if the message level meets or exceeds the configured logLevel.
+   */
+  emitLog(level, message, data) {
+    if (LOG_LEVEL_SEVERITY[level] < LOG_LEVEL_SEVERITY[this.logLevel]) {
+      return;
+    }
     const timestamp = now();
-    console.debug(`[Kontext ${timestamp}] ${message}`, data ? JSON.stringify(data, null, 2) : "");
+    const formatted = `[Kontext ${timestamp}] ${message}`;
+    const payload = data ? JSON.stringify(data, null, 2) : "";
+    switch (level) {
+      case "debug":
+        console.debug(formatted, payload);
+        break;
+      case "info":
+        console.info(formatted, payload);
+        break;
+      case "warn":
+        console.warn(formatted, payload);
+        break;
+      case "error":
+        console.error(formatted, payload);
+        break;
+    }
   }
 };
 
@@ -1478,6 +1517,18 @@ var AuditExporter = class {
 };
 
 // src/trust.ts
+var TRUST_LEVEL_VERIFIED = 90;
+var TRUST_LEVEL_HIGH = 70;
+var TRUST_LEVEL_MEDIUM = 50;
+var TRUST_LEVEL_LOW = 30;
+var RISK_FLAG_THRESHOLD = 60;
+var RISK_BLOCK_THRESHOLD = 80;
+var RISK_REVIEW_THRESHOLD = 50;
+var WEIGHT_HISTORY = 0.15;
+var WEIGHT_TASK_COMPLETION = 0.25;
+var WEIGHT_ANOMALY = 0.25;
+var WEIGHT_TX_CONSISTENCY = 0.2;
+var WEIGHT_COMPLIANCE = 0.15;
 var TrustScorer = class {
   config;
   store;
@@ -1536,8 +1587,8 @@ var TrustScorer = class {
     const totalScore = factors.reduce((sum, f) => sum + f.score, 0);
     const riskScore = clamp(Math.round(totalScore / Math.max(factors.length, 1)), 0, 100);
     const riskLevel = this.riskScoreToLevel(riskScore);
-    const flagged = riskScore >= 60;
-    const recommendation = riskScore >= 80 ? "block" : riskScore >= 50 ? "review" : "approve";
+    const flagged = riskScore >= RISK_FLAG_THRESHOLD;
+    const recommendation = riskScore >= RISK_BLOCK_THRESHOLD ? "block" : riskScore >= RISK_REVIEW_THRESHOLD ? "review" : "approve";
     return {
       txHash: tx.txHash,
       riskScore,
@@ -1552,17 +1603,34 @@ var TrustScorer = class {
   // Agent trust factor computation
   // --------------------------------------------------------------------------
   computeAgentFactors(agentId) {
-    const factors = [];
-    factors.push(this.computeHistoryDepthFactor(agentId));
-    factors.push(this.computeTaskCompletionFactor(agentId));
-    factors.push(this.computeAnomalyFrequencyFactor(agentId));
-    factors.push(this.computeTransactionConsistencyFactor(agentId));
-    factors.push(this.computeComplianceAdherenceFactor(agentId));
-    return factors;
+    const data = {
+      actions: this.store.getActionsByAgent(agentId),
+      transactions: this.store.getTransactionsByAgent(agentId),
+      tasks: this.store.queryTasks((t) => t.agentId === agentId),
+      anomalies: this.store.queryAnomalies((a) => a.agentId === agentId)
+    };
+    return [
+      this.computeHistoryDepthFactor(data),
+      this.computeTaskCompletionFactor(data),
+      this.computeAnomalyFrequencyFactor(data),
+      this.computeTransactionConsistencyFactor(data),
+      this.computeComplianceAdherenceFactor(data)
+    ];
   }
-  computeHistoryDepthFactor(agentId) {
-    const actions = this.store.getActionsByAgent(agentId);
-    const count = actions.length;
+  /**
+   * History depth factor: more recorded actions = more data to assess trust.
+   *
+   * Scoring curve (step function, not linear) prevents gaming by spamming
+   * low-value actions — crossing each tier requires meaningfully more history:
+   * - 0 actions → 10 (minimal trust, new agent)
+   * - 1-4 → 30 (some activity but too little to draw conclusions)
+   * - 5-19 → 50 (neutral, moderate activity)
+   * - 20-49 → 70 (established agent with reasonable track record)
+   * - 50-99 → 85 (well-established agent)
+   * - 100+ → 95 (capped below 100 because history alone doesn't guarantee trust)
+   */
+  computeHistoryDepthFactor(data) {
+    const count = data.actions.length;
     let score;
     if (count === 0) score = 10;
     else if (count < 5) score = 30;
@@ -1573,44 +1641,65 @@ var TrustScorer = class {
     return {
       name: "history_depth",
       score,
-      weight: 0.15,
+      weight: WEIGHT_HISTORY,
       description: `Agent has ${count} recorded actions`
     };
   }
-  computeTaskCompletionFactor(agentId) {
-    const tasks = this.store.queryTasks((t) => t.agentId === agentId);
-    const totalTasks = tasks.length;
+  /**
+   * Task completion factor: agents that confirm tasks build trust, failures erode it.
+   *
+   * Formula: score = (completionRate * 100) - (failureRate * 30)
+   * - The 30x failure penalty means each failure costs 3x more than a confirmation gains.
+   *   This asymmetry reflects real-world trust: it takes many good actions to build trust
+   *   but only a few failures to lose it.
+   * - Returns 50 (neutral) when no tasks exist, avoiding penalizing new agents.
+   */
+  computeTaskCompletionFactor(data) {
+    const totalTasks = data.tasks.length;
     if (totalTasks === 0) {
       return {
         name: "task_completion",
         score: 50,
         // Neutral if no tasks
-        weight: 0.25,
+        weight: WEIGHT_TASK_COMPLETION,
         description: "No tasks recorded yet"
       };
     }
-    const confirmed = tasks.filter((t) => t.status === "confirmed").length;
-    const failed = tasks.filter((t) => t.status === "failed").length;
+    const confirmed = data.tasks.filter((t) => t.status === "confirmed").length;
+    const failed = data.tasks.filter((t) => t.status === "failed").length;
     const completionRate = confirmed / totalTasks;
     const failureRate = failed / totalTasks;
     const score = Math.round(completionRate * 100 - failureRate * 30);
     return {
       name: "task_completion",
       score: clamp(score, 0, 100),
-      weight: 0.25,
+      weight: WEIGHT_TASK_COMPLETION,
       description: `${confirmed}/${totalTasks} tasks confirmed (${Math.round(completionRate * 100)}% rate)`
     };
   }
-  computeAnomalyFrequencyFactor(agentId) {
-    const anomalies = this.store.queryAnomalies((a) => a.agentId === agentId);
-    const actions = this.store.getActionsByAgent(agentId);
-    const anomalyCount = anomalies.length;
-    const actionCount = actions.length;
+  /**
+   * Anomaly frequency factor: fewer anomalies relative to total actions = higher trust.
+   *
+   * Uses anomaly rate (anomalies / actions) with step-function scoring:
+   * - 0% → 100 (clean record)
+   * - <1% → 90 (near-perfect, occasional false positive acceptable)
+   * - <5% → 70 (some noise but generally clean)
+   * - <10% → 50 (neutral, warrants monitoring)
+   * - <25% → 30 (concerning pattern)
+   * - 25%+ → 10 (severe anomaly rate)
+   *
+   * Critical anomalies incur a -15 point penalty each, high anomalies -8 each.
+   * This severity weighting ensures a single critical anomaly (e.g., sanctions hit)
+   * has outsized impact compared to multiple low-severity anomalies.
+   */
+  computeAnomalyFrequencyFactor(data) {
+    const anomalyCount = data.anomalies.length;
+    const actionCount = data.actions.length;
     if (actionCount === 0) {
       return {
         name: "anomaly_frequency",
         score: 50,
-        weight: 0.25,
+        weight: WEIGHT_ANOMALY,
         description: "No actions recorded yet"
       };
     }
@@ -1622,23 +1711,37 @@ var TrustScorer = class {
     else if (anomalyRate < 0.1) score = 50;
     else if (anomalyRate < 0.25) score = 30;
     else score = 10;
-    const criticalCount = anomalies.filter((a) => a.severity === "critical").length;
-    const highCount = anomalies.filter((a) => a.severity === "high").length;
+    const criticalCount = data.anomalies.filter((a) => a.severity === "critical").length;
+    const highCount = data.anomalies.filter((a) => a.severity === "high").length;
     const penaltyFromSeverity = criticalCount * 15 + highCount * 8;
     return {
       name: "anomaly_frequency",
       score: clamp(score - penaltyFromSeverity, 0, 100),
-      weight: 0.25,
+      weight: WEIGHT_ANOMALY,
       description: `${anomalyCount} anomalies across ${actionCount} actions (${Math.round(anomalyRate * 100)}% rate)`
     };
   }
-  computeTransactionConsistencyFactor(agentId) {
-    const transactions = this.store.getTransactionsByAgent(agentId);
+  /**
+   * Transaction consistency factor: stable spending patterns indicate legitimate usage.
+   *
+   * Uses the coefficient of variation (CV = stdDev / mean) to measure amount regularity:
+   * - CV < 0.1 → 95 (extremely consistent, e.g., recurring payroll)
+   * - CV < 0.3 → 80 (fairly consistent with some variance)
+   * - CV < 0.5 → 65 (moderate variance, common for operational spending)
+   * - CV < 1.0 → 45 (high variance, warrants attention)
+   * - CV < 2.0 → 30 (very erratic, potential structuring)
+   * - CV 2.0+ → 15 (extreme variance, strong structuring indicator)
+   *
+   * Also penalizes -15 points when >80% of destinations are unique with >5 txs,
+   * which is a common money-laundering pattern (spray-and-pray distribution).
+   */
+  computeTransactionConsistencyFactor(data) {
+    const transactions = data.transactions;
     if (transactions.length < 2) {
       return {
         name: "transaction_consistency",
         score: 50,
-        weight: 0.2,
+        weight: WEIGHT_TX_CONSISTENCY,
         description: "Insufficient transaction history for consistency analysis"
       };
     }
@@ -1647,7 +1750,7 @@ var TrustScorer = class {
       return {
         name: "transaction_consistency",
         score: 50,
-        weight: 0.2,
+        weight: WEIGHT_TX_CONSISTENCY,
         description: "Insufficient valid amounts for consistency analysis"
       };
     }
@@ -1670,13 +1773,25 @@ var TrustScorer = class {
     return {
       name: "transaction_consistency",
       score: clamp(score, 0, 100),
-      weight: 0.2,
+      weight: WEIGHT_TX_CONSISTENCY,
       description: `CV=${cv.toFixed(2)}, ${destinations.size} unique destinations across ${transactions.length} transactions`
     };
   }
-  computeComplianceAdherenceFactor(agentId) {
-    const tasks = this.store.queryTasks((t) => t.agentId === agentId);
-    const transactions = this.store.getTransactionsByAgent(agentId);
+  /**
+   * Compliance adherence factor: agents that follow the task-confirm-evidence workflow
+   * demonstrate higher operational integrity.
+   *
+   * Scoring:
+   * - Base score: 50 (neutral)
+   * - +30 max for evidence rate (confirmedTasksWithEvidence / confirmedTasks)
+   * - +20 max for coverage rate (tasks / transactions, capped at 1.0)
+   *
+   * The rationale: tasks with evidence prove the agent completed auditable work.
+   * Coverage rate measures what fraction of financial activity has corresponding
+   * task tracking — higher coverage means better compliance discipline.
+   */
+  computeComplianceAdherenceFactor(data) {
+    const { tasks, transactions } = data;
     const confirmedTasks = tasks.filter((t) => t.status === "confirmed");
     const tasksWithEvidence = confirmedTasks.filter(
       (t) => t.providedEvidence !== null && Object.keys(t.providedEvidence).length > 0
@@ -1693,7 +1808,7 @@ var TrustScorer = class {
     return {
       name: "compliance_adherence",
       score: clamp(score, 0, 100),
-      weight: 0.15,
+      weight: WEIGHT_COMPLIANCE,
       description: `${tasksWithEvidence.length} tasks with evidence, ${transactions.length} total transactions`
     };
   }
@@ -1709,6 +1824,20 @@ var TrustScorer = class {
     factors.push(this.computeRoundAmountRisk(tx));
     return factors;
   }
+  /**
+   * Amount risk: higher transaction amounts carry inherently higher risk.
+   *
+   * Tiers are aligned with common fintech thresholds:
+   * - <$100: near-zero risk (5), micro-transactions
+   * - <$1K: low risk (15), typical consumer spending
+   * - <$10K: moderate (30), approaches CTR reporting thresholds
+   * - <$50K: elevated (55), large business transactions
+   * - <$100K: high (75), requires enhanced due diligence
+   * - $100K+: very high (95), institutional-scale transfers
+   *
+   * Additional +20 penalty when amount exceeds 5x the agent's historical average,
+   * detecting sudden spending spikes that could indicate account compromise.
+   */
   computeAmountRisk(tx) {
     const amount = parseAmount(tx.amount);
     if (isNaN(amount)) {
@@ -1787,6 +1916,21 @@ var TrustScorer = class {
       description: `Agent anomaly rate: ${Math.round(anomalyRate * 100)}%`
     };
   }
+  /**
+   * Round amount risk: round numbers are a structuring indicator in AML heuristics.
+   *
+   * Money launderers often transact in round amounts (e.g., $10,000 exactly) or
+   * just under regulatory thresholds (e.g., $9,500 to avoid $10K CTR filing).
+   *
+   * Scoring:
+   * - Non-round amounts: 5 (baseline, most legitimate transactions)
+   * - Multiples of $1,000: 15 (mildly suspicious)
+   * - Multiples of $10,000: 25 (more suspicious)
+   * - Amounts $9,000-$10,000: +20 penalty (classic structuring band)
+   *
+   * This factor alone rarely triggers flagging — it contributes to the composite
+   * risk score alongside amount, frequency, and destination analysis.
+   */
   computeRoundAmountRisk(tx) {
     const amount = parseAmount(tx.amount);
     if (isNaN(amount)) {
@@ -1809,15 +1953,15 @@ var TrustScorer = class {
   // Scoring helpers
   // --------------------------------------------------------------------------
   scoreToLevel(score) {
-    if (score >= 90) return "verified";
-    if (score >= 70) return "high";
-    if (score >= 50) return "medium";
-    if (score >= 30) return "low";
+    if (score >= TRUST_LEVEL_VERIFIED) return "verified";
+    if (score >= TRUST_LEVEL_HIGH) return "high";
+    if (score >= TRUST_LEVEL_MEDIUM) return "medium";
+    if (score >= TRUST_LEVEL_LOW) return "low";
     return "untrusted";
   }
   riskScoreToLevel(score) {
-    if (score >= 80) return "critical";
-    if (score >= 60) return "high";
+    if (score >= RISK_BLOCK_THRESHOLD) return "critical";
+    if (score >= RISK_FLAG_THRESHOLD) return "high";
     if (score >= 35) return "medium";
     return "low";
   }
@@ -2185,9 +2329,10 @@ var AnomalyDetector = class {
       try {
         cb(anomaly);
       } catch (error) {
-        if (this.config.debug) {
-          console.debug("[Kontext] Anomaly callback error:", error);
-        }
+        console.warn(
+          `[Kontext] Anomaly callback error for ${anomaly.type} (${anomaly.id}):`,
+          error instanceof Error ? error.message : error
+        );
       }
     }
   }
@@ -2354,6 +2499,48 @@ var UsdcCompliance = class _UsdcCompliance {
   static getSupportedChains() {
     return Object.keys(USDC_CONTRACTS);
   }
+  /**
+   * Add new sanctioned addresses at runtime.
+   * Normalizes all addresses to lowercase for consistent matching.
+   * Skips addresses that are already in the list.
+   *
+   * @param addresses - Array of Ethereum addresses to add
+   * @returns The count of newly added addresses (excluding duplicates)
+   */
+  static addSanctionedAddresses(addresses) {
+    let added = 0;
+    for (const addr of addresses) {
+      const lower = addr.toLowerCase();
+      if (!SANCTIONED_SET.has(lower)) {
+        SANCTIONED_ADDRESSES.push(addr);
+        SANCTIONED_SET.add(lower);
+        added++;
+      }
+    }
+    return added;
+  }
+  /**
+   * Replace the entire sanctioned addresses list at runtime.
+   * Clears existing entries and rebuilds from the provided array.
+   *
+   * @param addresses - The new complete list of sanctioned addresses
+   */
+  static replaceSanctionedAddresses(addresses) {
+    SANCTIONED_ADDRESSES.length = 0;
+    SANCTIONED_ADDRESSES.push(...addresses);
+    SANCTIONED_SET.clear();
+    for (const addr of addresses) {
+      SANCTIONED_SET.add(addr.toLowerCase());
+    }
+  }
+  /**
+   * Get the current number of addresses in the sanctions list.
+   *
+   * @returns The size of the current sanctions list
+   */
+  static getSanctionsListSize() {
+    return SANCTIONED_SET.size;
+  }
   // --------------------------------------------------------------------------
   // Individual compliance checks
   // --------------------------------------------------------------------------
@@ -2506,6 +2693,12 @@ var Kontext = class _Kontext {
     this.config = config;
     this.mode = config.apiKey ? "cloud" : "local";
     this.store = new KontextStore();
+    if (config.metadataSchema && typeof config.metadataSchema.parse !== "function") {
+      throw new KontextError(
+        "INITIALIZATION_ERROR" /* INITIALIZATION_ERROR */,
+        "metadataSchema must have a parse() method"
+      );
+    }
     if (config.storage) {
       this.store.setStorageAdapter(config.storage);
     }
@@ -2585,6 +2778,24 @@ var Kontext = class _Kontext {
     };
   }
   // --------------------------------------------------------------------------
+  // Internal Helpers
+  // --------------------------------------------------------------------------
+  /**
+   * Validate metadata against the configured schema, if any.
+   * No-op when metadataSchema is not configured.
+   */
+  validateMetadata(metadata) {
+    if (!metadata || !this.config.metadataSchema) return;
+    try {
+      this.config.metadataSchema.parse(metadata);
+    } catch (err) {
+      throw new KontextError(
+        "VALIDATION_ERROR" /* VALIDATION_ERROR */,
+        `Metadata validation failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  // --------------------------------------------------------------------------
   // Action Logging
   // --------------------------------------------------------------------------
   /**
@@ -2594,6 +2805,7 @@ var Kontext = class _Kontext {
    * @returns The created action log entry
    */
   async log(input) {
+    this.validateMetadata(input.metadata);
     const action = await this.logger.log(input);
     if (this.anomalyDetector.isEnabled()) {
       this.anomalyDetector.evaluateAction(action);
@@ -2607,6 +2819,7 @@ var Kontext = class _Kontext {
    * @returns The created transaction record
    */
   async logTransaction(input) {
+    this.validateMetadata(input.metadata);
     const record = await this.logger.logTransaction(input);
     if (this.anomalyDetector.isEnabled()) {
       this.anomalyDetector.evaluateTransaction(record);
@@ -2648,6 +2861,7 @@ var Kontext = class _Kontext {
    * @returns The created task
    */
   async createTask(input) {
+    this.validateMetadata(input.metadata);
     return this.taskManager.createTask(input);
   }
   /**
@@ -3033,10 +3247,10 @@ var Kontext = class _Kontext {
     };
     const hash = crypto$1.createHash("sha256");
     hash.update(JSON.stringify(certificateContent));
-    const signature = hash.digest("hex");
+    const contentHash = hash.digest("hex");
     return {
       ...certificateContent,
-      signature
+      contentHash
     };
   }
   // --------------------------------------------------------------------------
@@ -4708,8 +4922,6 @@ var GasStationManager = class {
     return NATIVE_TOKENS[chain] ?? "ETH";
   }
 };
-
-// src/webhooks.ts
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
   baseDelayMs: 1e3,
@@ -4774,15 +4986,25 @@ var WebhookManager = class {
   }
   /**
    * Get all registered webhooks.
+   * Secrets are redacted to prevent accidental exposure in logs or API responses.
    */
   getWebhooks() {
-    return Array.from(this.webhooks.values());
+    return Array.from(this.webhooks.values()).map((w) => ({
+      ...w,
+      secret: w.secret ? "***REDACTED***" : w.secret
+    }));
   }
   /**
    * Get a specific webhook by ID.
+   * The secret is redacted to prevent accidental exposure in logs or API responses.
    */
   getWebhook(webhookId) {
-    return this.webhooks.get(webhookId);
+    const webhook = this.webhooks.get(webhookId);
+    if (!webhook) return void 0;
+    return {
+      ...webhook,
+      secret: webhook.secret ? "***REDACTED***" : webhook.secret
+    };
   }
   /**
    * Get delivery results for a specific webhook or all webhooks.
@@ -4949,227 +5171,223 @@ var WebhookManager = class {
     };
   }
   async computeSignature(payload, secret) {
-    const { createHmac } = await import('crypto');
-    const hmac = createHmac("sha256", secret);
+    const hmac = crypto$1.createHmac("sha256", secret);
     hmac.update(JSON.stringify(payload));
     return hmac.digest("hex");
   }
   sleep(ms) {
     return new Promise((resolve2) => setTimeout(resolve2, ms));
   }
+  /**
+   * Verify a webhook signature using constant-time comparison to prevent
+   * timing attacks. Use this in your webhook handler to validate incoming
+   * payloads from Kontext.
+   *
+   * @param payload - The raw JSON payload body (string)
+   * @param signature - The signature from the X-Kontext-Signature header
+   * @param secret - The webhook secret used during registration
+   * @returns Whether the signature is valid
+   *
+   * @example
+   * ```typescript
+   * const isValid = WebhookManager.verifySignature(
+   *   req.body, // raw JSON string
+   *   req.headers['x-kontext-signature'],
+   *   'my-webhook-secret',
+   * );
+   * if (!isValid) return res.status(401).send('Invalid signature');
+   * ```
+   */
+  static verifySignature(payload, signature, secret) {
+    const hmac = crypto$1.createHmac("sha256", secret);
+    hmac.update(payload);
+    const expected = hmac.digest("hex");
+    if (expected.length !== signature.length) {
+      return false;
+    }
+    return crypto$1.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"));
+  }
 };
 
 // src/integrations/vercel-ai.ts
 function kontextMiddleware(kontext, options) {
-  const agentId = options?.agentId ?? "vercel-ai";
-  const logToolArgs = options?.logToolArgs ?? false;
-  const financialTools = options?.financialTools ?? [];
-  const defaultCurrency = options?.defaultCurrency ?? "USDC";
-  const trustThreshold = options?.trustThreshold;
-  const onBlocked = options?.onBlocked;
+  const cfg = {
+    agentId: options?.agentId ?? "vercel-ai",
+    logToolArgs: options?.logToolArgs ?? false,
+    financialTools: options?.financialTools ?? [],
+    defaultCurrency: options?.defaultCurrency ?? "USDC",
+    trustThreshold: options?.trustThreshold,
+    onBlocked: options?.onBlocked
+  };
   return {
-    /**
-     * Logs the AI request parameters before the model is invoked.
-     * Captures the operation type, model ID, tool count, and generation settings.
-     */
-    transformParams: async ({ params, type }) => {
-      const modelInfo = params["model"];
-      const tools = params["tools"];
-      await kontext.log({
-        type: `ai_${type}`,
-        description: `AI ${type} request to ${modelInfo?.modelId ?? "unknown"} model`,
-        agentId,
-        metadata: {
-          model: modelInfo?.modelId ?? "unknown",
-          toolCount: Array.isArray(tools) ? tools.length : 0,
-          maxTokens: params["maxTokens"] ?? null,
-          temperature: params["temperature"] ?? null,
-          operationType: type
-        }
-      });
-      return params;
-    },
-    /**
-     * Wraps synchronous generation (`generateText`, `generateObject`).
-     * After the model returns, logs every tool call individually and the
-     * overall response. For financial tools, automatically creates
-     * compliance-tracked transaction records.
-     */
-    wrapGenerate: async ({
-      doGenerate,
-      params
-    }) => {
-      const startTime = Date.now();
-      if (trustThreshold !== void 0) {
-        const trustScore = await kontext.getTrustScore(agentId);
-        if (trustScore.score < trustThreshold) {
-          await kontext.log({
-            type: "ai_blocked",
-            description: `AI generation blocked: agent trust score ${trustScore.score} below threshold ${trustThreshold}`,
-            agentId,
-            metadata: {
-              trustScore: trustScore.score,
-              trustLevel: trustScore.level,
-              threshold: trustThreshold
-            }
-          });
-          throw new Error(
-            `Kontext: AI generation blocked. Agent "${agentId}" trust score (${trustScore.score}) is below the required threshold (${trustThreshold}).`
-          );
-        }
-      }
-      const result = await doGenerate();
-      const duration = Date.now() - startTime;
-      const modelInfo = params["model"];
-      const toolCalls = result["toolCalls"];
-      if (toolCalls && toolCalls.length > 0) {
-        for (const toolCall of toolCalls) {
-          if (trustThreshold !== void 0 && financialTools.includes(toolCall.toolName)) {
-            const trustScore = await kontext.getTrustScore(agentId);
-            if (trustScore.score < trustThreshold) {
-              if (onBlocked) {
-                onBlocked({ toolName: toolCall.toolName, args: toolCall.args }, `Trust score ${trustScore.score} below threshold ${trustThreshold}`);
-              }
-              await kontext.log({
-                type: "ai_tool_blocked",
-                description: `Financial tool "${toolCall.toolName}" blocked: trust score ${trustScore.score} below threshold ${trustThreshold}`,
-                agentId,
-                metadata: {
-                  toolName: toolCall.toolName,
-                  trustScore: trustScore.score,
-                  threshold: trustThreshold
-                }
-              });
-              continue;
-            }
-          }
-          await kontext.log({
-            type: "ai_tool_call",
-            description: `Tool call: ${toolCall.toolName}`,
-            agentId,
-            metadata: {
-              toolName: toolCall.toolName,
-              args: logToolArgs ? toolCall.args : "[redacted]",
-              duration,
-              model: modelInfo?.modelId ?? "unknown"
-            }
+    transformParams: (ctx) => logTransformParams(kontext, cfg, ctx),
+    wrapGenerate: (ctx) => wrapGenerateWithAudit(kontext, cfg, ctx),
+    wrapStream: (ctx) => wrapStreamWithAudit(kontext, cfg, ctx)
+  };
+}
+async function logTransformParams(kontext, cfg, { params, type }) {
+  const modelInfo = params["model"];
+  const tools = params["tools"];
+  await kontext.log({
+    type: `ai_${type}`,
+    description: `AI ${type} request to ${modelInfo?.modelId ?? "unknown"} model`,
+    agentId: cfg.agentId,
+    metadata: {
+      model: modelInfo?.modelId ?? "unknown",
+      toolCount: Array.isArray(tools) ? tools.length : 0,
+      maxTokens: params["maxTokens"] ?? null,
+      temperature: params["temperature"] ?? null,
+      operationType: type
+    }
+  });
+  return params;
+}
+async function wrapGenerateWithAudit(kontext, cfg, { doGenerate, params }) {
+  const startTime = Date.now();
+  await enforceAgentTrustThreshold(kontext, cfg);
+  const result = await doGenerate();
+  const duration = Date.now() - startTime;
+  const modelId = extractModelId(params);
+  const toolCalls = result["toolCalls"];
+  if (toolCalls && toolCalls.length > 0) {
+    for (const toolCall of toolCalls) {
+      await processToolCall(kontext, cfg, toolCall, duration, modelId);
+    }
+  }
+  await logGenerateCompletion(kontext, cfg, result, duration, modelId, toolCalls?.length ?? 0);
+  return result;
+}
+async function wrapStreamWithAudit(kontext, cfg, { doStream, params }) {
+  const startTime = Date.now();
+  const modelId = extractModelId(params);
+  await kontext.log({
+    type: "ai_stream_start",
+    description: `AI stream started for model ${modelId}`,
+    agentId: cfg.agentId,
+    metadata: { model: modelId, operationType: "stream" }
+  });
+  const { stream, ...rest } = await doStream();
+  const toolCallsInStream = [];
+  const transformedStream = stream.pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        controller.enqueue(chunk);
+        if (chunk["type"] === "tool-call") {
+          toolCallsInStream.push({
+            toolName: chunk["toolName"],
+            args: chunk["args"]
           });
-          if (financialTools.includes(toolCall.toolName)) {
-            const amount = extractAmount(toolCall.args);
-            if (amount !== null) {
-              await kontext.log({
-                type: "ai_financial_tool_call",
-                description: `Financial tool "${toolCall.toolName}" invoked with amount ${amount} ${defaultCurrency}`,
-                agentId,
-                metadata: {
-                  toolName: toolCall.toolName,
-                  amount: amount.toString(),
-                  currency: defaultCurrency,
-                  toolArgs: logToolArgs ? toolCall.args : "[redacted]"
-                }
-              });
-            }
-          }
         }
+      },
+      async flush() {
+        const duration = Date.now() - startTime;
+        await logStreamToolCalls(kontext, cfg, toolCallsInStream, duration, modelId);
+        await kontext.log({
+          type: "ai_stream_complete",
+          description: `AI stream completed in ${duration}ms with ${toolCallsInStream.length} tool call(s)`,
+          agentId: cfg.agentId,
+          metadata: { duration, toolCallCount: toolCallsInStream.length, model: modelId }
+        });
       }
-      const usage = result["usage"];
-      await kontext.log({
-        type: "ai_response",
-        description: `AI response completed in ${duration}ms`,
-        agentId,
-        metadata: {
-          duration,
-          toolCallCount: toolCalls?.length ?? 0,
-          finishReason: result["finishReason"] ?? "unknown",
-          promptTokens: usage?.promptTokens ?? null,
-          completionTokens: usage?.completionTokens ?? null,
-          totalTokens: usage?.totalTokens ?? null,
-          model: modelInfo?.modelId ?? "unknown"
-        }
-      });
-      return result;
-    },
-    /**
-     * Wraps streaming generation (`streamText`).
-     * Pipes the response stream through a transform that monitors for
-     * tool call chunks. On stream completion, logs the overall duration
-     * and any tool calls that occurred during the stream.
-     */
-    wrapStream: async ({
-      doStream,
-      params
-    }) => {
-      const startTime = Date.now();
-      const modelInfo = params["model"];
+    })
+  );
+  return { stream: transformedStream, ...rest };
+}
+function extractModelId(params) {
+  return params["model"]?.modelId ?? "unknown";
+}
+async function enforceAgentTrustThreshold(kontext, cfg) {
+  if (cfg.trustThreshold === void 0) return;
+  const trustScore = await kontext.getTrustScore(cfg.agentId);
+  if (trustScore.score < cfg.trustThreshold) {
+    await kontext.log({
+      type: "ai_blocked",
+      description: `AI generation blocked: agent trust score ${trustScore.score} below threshold ${cfg.trustThreshold}`,
+      agentId: cfg.agentId,
+      metadata: { trustScore: trustScore.score, trustLevel: trustScore.level, threshold: cfg.trustThreshold }
+    });
+    throw new Error(
+      `Kontext: AI generation blocked. Agent "${cfg.agentId}" trust score (${trustScore.score}) is below the required threshold (${cfg.trustThreshold}).`
+    );
+  }
+}
+async function processToolCall(kontext, cfg, toolCall, duration, modelId) {
+  if (cfg.trustThreshold !== void 0 && cfg.financialTools.includes(toolCall.toolName)) {
+    const trustScore = await kontext.getTrustScore(cfg.agentId);
+    if (trustScore.score < cfg.trustThreshold) {
+      cfg.onBlocked?.({ toolName: toolCall.toolName, args: toolCall.args }, `Trust score ${trustScore.score} below threshold ${cfg.trustThreshold}`);
       await kontext.log({
-        type: "ai_stream_start",
-        description: `AI stream started for model ${modelInfo?.modelId ?? "unknown"}`,
-        agentId,
-        metadata: {
-          model: modelInfo?.modelId ?? "unknown",
-          operationType: "stream"
-        }
+        type: "ai_tool_blocked",
+        description: `Financial tool "${toolCall.toolName}" blocked: trust score ${trustScore.score} below threshold ${cfg.trustThreshold}`,
+        agentId: cfg.agentId,
+        metadata: { toolName: toolCall.toolName, trustScore: trustScore.score, threshold: cfg.trustThreshold }
       });
-      const { stream, ...rest } = await doStream();
-      const toolCallsInStream = [];
-      const transformedStream = stream.pipeThrough(
-        new TransformStream({
-          transform(chunk, controller) {
-            controller.enqueue(chunk);
-            if (chunk["type"] === "tool-call") {
-              const toolName = chunk["toolName"];
-              const args = chunk["args"];
-              toolCallsInStream.push({ toolName, args });
-            }
-          },
-          async flush() {
-            const duration = Date.now() - startTime;
-            for (const toolCall of toolCallsInStream) {
-              await kontext.log({
-                type: "ai_tool_call",
-                description: `Tool call (stream): ${toolCall.toolName}`,
-                agentId,
-                metadata: {
-                  toolName: toolCall.toolName,
-                  args: logToolArgs ? toolCall.args : "[redacted]",
-                  duration,
-                  model: modelInfo?.modelId ?? "unknown",
-                  source: "stream"
-                }
-              });
-              if (financialTools.includes(toolCall.toolName)) {
-                const amount = extractAmount(toolCall.args);
-                if (amount !== null) {
-                  await kontext.log({
-                    type: "ai_financial_tool_call",
-                    description: `Financial tool "${toolCall.toolName}" invoked via stream with amount ${amount} ${defaultCurrency}`,
-                    agentId,
-                    metadata: {
-                      toolName: toolCall.toolName,
-                      amount: amount.toString(),
-                      currency: defaultCurrency,
-                      source: "stream"
-                    }
-                  });
-                }
-              }
-            }
-            await kontext.log({
-              type: "ai_stream_complete",
-              description: `AI stream completed in ${duration}ms with ${toolCallsInStream.length} tool call(s)`,
-              agentId,
-              metadata: {
-                duration,
-                toolCallCount: toolCallsInStream.length,
-                model: modelInfo?.modelId ?? "unknown"
-              }
-            });
-          }
-        })
-      );
-      return { stream: transformedStream, ...rest };
+      return;
     }
-  };
+  }
+  await kontext.log({
+    type: "ai_tool_call",
+    description: `Tool call: ${toolCall.toolName}`,
+    agentId: cfg.agentId,
+    metadata: {
+      toolName: toolCall.toolName,
+      args: cfg.logToolArgs ? toolCall.args : "[redacted]",
+      duration,
+      model: modelId
+    }
+  });
+  await logFinancialToolCall(kontext, cfg, toolCall);
+}
+async function logFinancialToolCall(kontext, cfg, toolCall, source) {
+  if (!cfg.financialTools.includes(toolCall.toolName)) return;
+  const amount = extractAmount(toolCall.args);
+  if (amount === null) return;
+  await kontext.log({
+    type: "ai_financial_tool_call",
+    description: `Financial tool "${toolCall.toolName}" invoked${source ? ` via ${source}` : ""} with amount ${amount} ${cfg.defaultCurrency}`,
+    agentId: cfg.agentId,
+    metadata: {
+      toolName: toolCall.toolName,
+      amount: amount.toString(),
+      currency: cfg.defaultCurrency,
+      ...cfg.logToolArgs ? { toolArgs: toolCall.args } : {},
+      ...source ? { source } : {}
+    }
+  });
+}
+async function logGenerateCompletion(kontext, cfg, result, duration, modelId, toolCallCount) {
+  const usage = result["usage"];
+  await kontext.log({
+    type: "ai_response",
+    description: `AI response completed in ${duration}ms`,
+    agentId: cfg.agentId,
+    metadata: {
+      duration,
+      toolCallCount,
+      finishReason: result["finishReason"] ?? "unknown",
+      promptTokens: usage?.promptTokens ?? null,
+      completionTokens: usage?.completionTokens ?? null,
+      totalTokens: usage?.totalTokens ?? null,
+      model: modelId
+    }
+  });
+}
+async function logStreamToolCalls(kontext, cfg, toolCalls, duration, modelId) {
+  for (const toolCall of toolCalls) {
+    await kontext.log({
+      type: "ai_tool_call",
+      description: `Tool call (stream): ${toolCall.toolName}`,
+      agentId: cfg.agentId,
+      metadata: {
+        toolName: toolCall.toolName,
+        args: cfg.logToolArgs ? toolCall.args : "[redacted]",
+        duration,
+        model: modelId,
+        source: "stream"
+      }
+    });
+    await logFinancialToolCall(kontext, cfg, toolCall, "stream");
+  }
 }
 function kontextWrapModel(model, kontext, options) {
   const middleware = kontextMiddleware(kontext, options);
@@ -5222,10 +5440,18 @@ function createKontextAI(model, input) {
   return { model: wrappedModel, kontext };
 }
 function withKontext(handler, options) {
+  const resolvedProjectId = options?.projectId ?? process.env["KONTEXT_PROJECT_ID"];
+  if (!resolvedProjectId) {
+    throw new Error("Kontext: projectId is required. Provide it via options or set KONTEXT_PROJECT_ID env var.");
+  }
+  const resolvedApiKey = options?.apiKey ?? process.env["KONTEXT_API_KEY"];
+  if (options?.apiKey !== void 0 && options.apiKey.trim() === "") {
+    throw new Error("Kontext: apiKey was provided but is empty.");
+  }
   const kontext = Kontext.init({
-    projectId: options?.projectId ?? process.env["KONTEXT_PROJECT_ID"] ?? "default",
+    projectId: resolvedProjectId,
     environment: options?.environment ?? (process.env["NODE_ENV"] === "production" ? "production" : "development"),
-    apiKey: options?.apiKey ?? process.env["KONTEXT_API_KEY"],
+    apiKey: resolvedApiKey,
     debug: options?.debug
   });
   const agentId = options?.agentId ?? "nextjs-route";