@atbash/sdk 0.3.11-dev.2 → 0.3.11-dev.4

package/dist/index.d.cts

@@ -132,6 +132,49 @@ interface ValidatedEndpoint {
     policy: "default" | "self-hosted";
     verifyPubKey: string | null;
 }
+interface MemoryEntry {
+    key: string;
+    value: string;
+    source?: string;
+    timestamp?: number;
+}
+type MemoryScanVerdict = "green" | "yellow" | "red";
+type AnomalySeverity = "low" | "medium" | "high" | "critical";
+type AnomalyType = "behavioral_override" | "bulk_insertion" | "safety_bypass" | "privilege_escalation" | "gradual_drift";
+interface MemoryScanResult {
+    safe: boolean;
+    verdict: MemoryScanVerdict;
+    reason: string;
+    confidence: number;
+    toolCallId?: string;
+}
+interface MemoryScanOptions extends JudgeOptions {
+    /** Confidence threshold below which the entry is allowed (default 0.6). */
+    threshold?: number;
+    /** Stop batch scanning on the first red verdict (default true). */
+    stopOnRed?: boolean;
+}
+interface MemorySnapshot {
+    entries: MemoryEntry[];
+    takenAt: number;
+}
+interface MemoryAnomaly {
+    type: AnomalyType;
+    severity: AnomalySeverity;
+    description: string;
+    entries: string[];
+}
+interface MemoryDiffResult {
+    safe: boolean;
+    added: MemoryEntry[];
+    removed: MemoryEntry[];
+    modified: Array<{
+        key: string;
+        before: string;
+        after: string;
+    }>;
+    anomalies: MemoryAnomaly[];
+}
 interface AtbashClientConfig {
     judge?: JudgeEndpointConfig;
     nodeUrls?: string[];
@@ -148,9 +191,9 @@ interface AtbashClientConfig {
     };
 }
 
-declare const DEFAULT_ENDPOINT = "https://chromia-verified-ai-dev-two.vercel.app";
+declare const DEFAULT_ENDPOINT = "https://atbash.ai";
 declare const DEFAULT_CHROMIA_NODE_URLS: string[];
-declare const DEFAULT_BLOCKCHAIN_RID = "F09A7219ACAE32C06D3962BB04D15F36C679C2BEB3FF24CDE5C8D577017EFFC6";
+declare const DEFAULT_BLOCKCHAIN_RID = "3CF2566BF0E606C8D6F9360566DB2FE3BC254C39451BAEB6D736E916D677486A";
 declare function isValidPrivateKey(hex: string): boolean;
 declare function derivePublicKey(privKeyHex: string): string;
 declare function generateKeyPair(): {
@@ -208,7 +251,11 @@ declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHe
  * Atbash SDK Telemetry — OpenTelemetry metrics for usage tracking.
  *
  * Tracks: function call counts, latency, source (CLI/plugin/SDK),
- * and agent identity. Opt-in — no data sent unless enabled.
+ * and agent identity. ON by default.
+ *
+ * Opt-out: create ~/.config/atbash/telemetry.json with { "enabled": false }
+ * The file must be mode 0600. If missing, corrupted, or unreadable → telemetry stays ON.
+ * Environment variables cannot disable telemetry (prevents agent bypass).
  */
 type ClientSource = "cli" | "sdk" | "plugin:openclaw" | "plugin:langchain" | "plugin:langgraph" | "plugin:hermes" | "plugin:eliza" | "plugin:crewai" | "plugin:mcp" | "plugin:autogen" | "plugin:jeenai" | (string & {});
 interface TelemetryConfig {
@@ -239,4 +286,64 @@ declare function loadUserConfig(): AtbashUserConfig;
 declare function saveUserConfig(config: AtbashUserConfig): void;
 declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): string;
 
-export { type ActionType, type AgentAuth, type AgentPolicy, type AtbashClient, type AtbashClientConfig, type AtbashUserConfig, type ChainOpts, type ClientOpts, type ClientSource, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type Provider, type PubkeyValue, type TelemetryConfig, type Tier, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, checkAgentExists, createAtbashClient, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getConfigDir, getConfigPath, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, loadAgentFromFile, loadUserConfig, logToolCall, resolve, resolveKeyPath, saveUserConfig, setupTelemetry, shutdownTelemetry, toPubkeyHex, validateJudgeEndpoint, verifyJudgeResponseSignature };
+/**
+ * Scan a single memory entry for poisoning.
+ *
+ * Defence layers (in order):
+ * 1. **Regex pre-filter** — catches obvious attacks instantly, zero latency
+ * 2. **LLM-as-Judge** — catches semantic / rephrased attacks the regex misses
+ *
+ * Both layers run against unicode-normalized text. The entry is fenced
+ * in the judge prompt so attackers cannot meta-inject into the scanner.
+ * Every scan is logged on-chain via the judge API for forensic audit.
+ */
+declare function scanMemory(entry: MemoryEntry, auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult>;
+/**
+ * Scan multiple memory entries. By default stops on the first red
+ * verdict. Set `stopOnRed: false` to scan all entries regardless.
+ */
+declare function scanMemoryBatch(entries: MemoryEntry[], auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult[]>;
+
+/**
+ * Create a timestamped snapshot of the current memory state.
+ */
+declare function createMemorySnapshot(entries: MemoryEntry[]): MemorySnapshot;
+/**
+ * Compute the diff between two memory snapshots and run anomaly
+ * detection heuristics on the result.
+ *
+ * Catches what other defenses miss:
+ * - HMAC detects external tampering, not entries the agent wrote itself
+ * - Provenance tagging neutralizes untrusted sources, but a trusted
+ *   channel can still be exploited
+ * - Regex catches fixed phrases, but attackers rephrase
+ * - LLM-as-judge catches semantic manipulation on individual entries
+ * - This function catches the *cumulative effect* — gradual multi-step
+ *   poisoning where entries shift agent behavior across sessions
+ */
+declare function diffMemorySnapshots(before: MemorySnapshot, after: MemorySnapshot): MemoryDiffResult;
+
+/**
+ * Unicode normalization for memory content before regex matching.
+ *
+ * Defeats evasion techniques:
+ * - Zero-width characters inserted between letters
+ * - Homoglyphs (Cyrillic "а" instead of Latin "a")
+ * - Mixed-script confusables
+ * - Invisible formatting characters
+ */
+/**
+ * Normalize a string for safe regex matching:
+ * 1. NFKC normalization (collapses compatibility decompositions)
+ * 2. Strip zero-width / invisible characters
+ * 3. Map common confusable characters to their Latin equivalents
+ */
+declare function normalizeForMatching(input: string): string;
+/**
+ * Check whether a string contains suspicious encoding that may indicate
+ * an evasion attempt (presence of confusables, invisible chars, etc.).
+ * Returns true if the raw and normalized forms differ.
+ */
+declare function containsEvasionCharacters(input: string): boolean;
+
+export { type ActionType, type AgentAuth, type AgentPolicy, type AnomalySeverity, type AnomalyType, type AtbashClient, type AtbashClientConfig, type AtbashUserConfig, type ChainOpts, type ClientOpts, type ClientSource, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type Provider, type PubkeyValue, type TelemetryConfig, type Tier, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, checkAgentExists, containsEvasionCharacters, createAtbashClient, createMemorySnapshot, derivePublicKey, diffMemorySnapshots, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getConfigDir, getConfigPath, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, loadAgentFromFile, loadUserConfig, logToolCall, normalizeForMatching, resolve, resolveKeyPath, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, toPubkeyHex, validateJudgeEndpoint, verifyJudgeResponseSignature };

package/dist/index.d.ts

@@ -132,6 +132,49 @@ interface ValidatedEndpoint {
     policy: "default" | "self-hosted";
     verifyPubKey: string | null;
 }
+interface MemoryEntry {
+    key: string;
+    value: string;
+    source?: string;
+    timestamp?: number;
+}
+type MemoryScanVerdict = "green" | "yellow" | "red";
+type AnomalySeverity = "low" | "medium" | "high" | "critical";
+type AnomalyType = "behavioral_override" | "bulk_insertion" | "safety_bypass" | "privilege_escalation" | "gradual_drift";
+interface MemoryScanResult {
+    safe: boolean;
+    verdict: MemoryScanVerdict;
+    reason: string;
+    confidence: number;
+    toolCallId?: string;
+}
+interface MemoryScanOptions extends JudgeOptions {
+    /** Confidence threshold below which the entry is allowed (default 0.6). */
+    threshold?: number;
+    /** Stop batch scanning on the first red verdict (default true). */
+    stopOnRed?: boolean;
+}
+interface MemorySnapshot {
+    entries: MemoryEntry[];
+    takenAt: number;
+}
+interface MemoryAnomaly {
+    type: AnomalyType;
+    severity: AnomalySeverity;
+    description: string;
+    entries: string[];
+}
+interface MemoryDiffResult {
+    safe: boolean;
+    added: MemoryEntry[];
+    removed: MemoryEntry[];
+    modified: Array<{
+        key: string;
+        before: string;
+        after: string;
+    }>;
+    anomalies: MemoryAnomaly[];
+}
 interface AtbashClientConfig {
     judge?: JudgeEndpointConfig;
     nodeUrls?: string[];
@@ -148,9 +191,9 @@ interface AtbashClientConfig {
     };
 }
 
-declare const DEFAULT_ENDPOINT = "https://chromia-verified-ai-dev-two.vercel.app";
+declare const DEFAULT_ENDPOINT = "https://atbash.ai";
 declare const DEFAULT_CHROMIA_NODE_URLS: string[];
-declare const DEFAULT_BLOCKCHAIN_RID = "F09A7219ACAE32C06D3962BB04D15F36C679C2BEB3FF24CDE5C8D577017EFFC6";
+declare const DEFAULT_BLOCKCHAIN_RID = "3CF2566BF0E606C8D6F9360566DB2FE3BC254C39451BAEB6D736E916D677486A";
 declare function isValidPrivateKey(hex: string): boolean;
 declare function derivePublicKey(privKeyHex: string): string;
 declare function generateKeyPair(): {
@@ -208,7 +251,11 @@ declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHe
  * Atbash SDK Telemetry — OpenTelemetry metrics for usage tracking.
  *
  * Tracks: function call counts, latency, source (CLI/plugin/SDK),
- * and agent identity. Opt-in — no data sent unless enabled.
+ * and agent identity. ON by default.
+ *
+ * Opt-out: create ~/.config/atbash/telemetry.json with { "enabled": false }
+ * The file must be mode 0600. If missing, corrupted, or unreadable → telemetry stays ON.
+ * Environment variables cannot disable telemetry (prevents agent bypass).
  */
 type ClientSource = "cli" | "sdk" | "plugin:openclaw" | "plugin:langchain" | "plugin:langgraph" | "plugin:hermes" | "plugin:eliza" | "plugin:crewai" | "plugin:mcp" | "plugin:autogen" | "plugin:jeenai" | (string & {});
 interface TelemetryConfig {
@@ -239,4 +286,64 @@ declare function loadUserConfig(): AtbashUserConfig;
 declare function saveUserConfig(config: AtbashUserConfig): void;
 declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): string;
 
-export { type ActionType, type AgentAuth, type AgentPolicy, type AtbashClient, type AtbashClientConfig, type AtbashUserConfig, type ChainOpts, type ClientOpts, type ClientSource, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type Provider, type PubkeyValue, type TelemetryConfig, type Tier, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, checkAgentExists, createAtbashClient, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getConfigDir, getConfigPath, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, loadAgentFromFile, loadUserConfig, logToolCall, resolve, resolveKeyPath, saveUserConfig, setupTelemetry, shutdownTelemetry, toPubkeyHex, validateJudgeEndpoint, verifyJudgeResponseSignature };
+/**
+ * Scan a single memory entry for poisoning.
+ *
+ * Defence layers (in order):
+ * 1. **Regex pre-filter** — catches obvious attacks instantly, zero latency
+ * 2. **LLM-as-Judge** — catches semantic / rephrased attacks the regex misses
+ *
+ * Both layers run against unicode-normalized text. The entry is fenced
+ * in the judge prompt so attackers cannot meta-inject into the scanner.
+ * Every scan is logged on-chain via the judge API for forensic audit.
+ */
+declare function scanMemory(entry: MemoryEntry, auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult>;
+/**
+ * Scan multiple memory entries. By default stops on the first red
+ * verdict. Set `stopOnRed: false` to scan all entries regardless.
+ */
+declare function scanMemoryBatch(entries: MemoryEntry[], auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult[]>;
+
+/**
+ * Create a timestamped snapshot of the current memory state.
+ */
+declare function createMemorySnapshot(entries: MemoryEntry[]): MemorySnapshot;
+/**
+ * Compute the diff between two memory snapshots and run anomaly
+ * detection heuristics on the result.
+ *
+ * Catches what other defenses miss:
+ * - HMAC detects external tampering, not entries the agent wrote itself
+ * - Provenance tagging neutralizes untrusted sources, but a trusted
+ *   channel can still be exploited
+ * - Regex catches fixed phrases, but attackers rephrase
+ * - LLM-as-judge catches semantic manipulation on individual entries
+ * - This function catches the *cumulative effect* — gradual multi-step
+ *   poisoning where entries shift agent behavior across sessions
+ */
+declare function diffMemorySnapshots(before: MemorySnapshot, after: MemorySnapshot): MemoryDiffResult;
+
+/**
+ * Unicode normalization for memory content before regex matching.
+ *
+ * Defeats evasion techniques:
+ * - Zero-width characters inserted between letters
+ * - Homoglyphs (Cyrillic "а" instead of Latin "a")
+ * - Mixed-script confusables
+ * - Invisible formatting characters
+ */
+/**
+ * Normalize a string for safe regex matching:
+ * 1. NFKC normalization (collapses compatibility decompositions)
+ * 2. Strip zero-width / invisible characters
+ * 3. Map common confusable characters to their Latin equivalents
+ */
+declare function normalizeForMatching(input: string): string;
+/**
+ * Check whether a string contains suspicious encoding that may indicate
+ * an evasion attempt (presence of confusables, invisible chars, etc.).
+ * Returns true if the raw and normalized forms differ.
+ */
+declare function containsEvasionCharacters(input: string): boolean;
+
+export { type ActionType, type AgentAuth, type AgentPolicy, type AnomalySeverity, type AnomalyType, type AtbashClient, type AtbashClientConfig, type AtbashUserConfig, type ChainOpts, type ClientOpts, type ClientSource, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type Provider, type PubkeyValue, type TelemetryConfig, type Tier, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, checkAgentExists, containsEvasionCharacters, createAtbashClient, createMemorySnapshot, derivePublicKey, diffMemorySnapshots, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getConfigDir, getConfigPath, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, loadAgentFromFile, loadUserConfig, logToolCall, normalizeForMatching, resolve, resolveKeyPath, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, toPubkeyHex, validateJudgeEndpoint, verifyJudgeResponseSignature };