@atbash/sdk 0.5.8-dev.0 → 0.6.0

package/dist/browser.d.mts

@@ -68,6 +68,38 @@ interface MemoryDiffResult {
     modified: ModifiedEntry[];
     anomalies: MemoryAnomaly[];
 }
+/** AES-256-GCM output from `encryptMemoryContent`. */
+interface EncryptedMemory {
+    ciphertext: Buffer;
+    nonce: Buffer;
+}
+/** Memory scanner verdict — matches the judge-response colour taxonomy. */
+type MemoryScanVerdict = "green" | "yellow" | "red";
+/** Result of `scanMemory` (regex pre-filter and/or LLM judge). */
+interface MemoryScanResult {
+    safe: boolean;
+    verdict: MemoryScanVerdict;
+    reason: string;
+    confidence: number;
+    /** Severity 1 (poisonous) → 10 (benign). LLM sets it; falls back to red=2/yellow=5/green=8 when the LLM omits the SCORE prefix or the regex pre-filter short-circuits. */
+    score: number;
+    toolCallId?: string;
+}
+/** Options for `scanMemory`. Passed through to `judgeAction`. */
+interface MemoryScanOptions {
+    /** Threshold for LLM confidence to escalate a green verdict to yellow. Default: 0.6 */
+    threshold?: number;
+    /** Judge endpoint override. Same shape as ClientOpts.endpoint. */
+    endpoint?: string;
+    /** Self-hosted judge response-signing pubkey. */
+    verifyPubKey?: string;
+    /** Org name for chain resolution. */
+    orgName?: string;
+    /** Tool name for on-chain audit log. */
+    toolName?: string;
+    /** JSON-serialized tool args for on-chain audit log. */
+    toolArgsJson?: string;
+}
 /**
  * Which Atbash chain an action runs against. `public` is the shared
  * testnet (Free plan); `private` is reserved for Private / Swarm /
@@ -310,6 +342,8 @@ interface JudgeOptions {
      * use `judgeAction` directly without going through `auditToolCall`.
      */
     resolved?: Record<string, unknown>;
+    /** Alternate flow: "memory-scan" tells the dashboard to use `context` as trusted policy and skip AGT/OPA/chain writes. Set by `scanMemory`; usually not needed at the call site. */
+    mode?: "memory-scan";
 }
 /** Options accepted by `logToolCall`. */
 interface LogToolCallOptions {
@@ -526,6 +560,271 @@ declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHe
     reason?: string;
 };
 
+/**
+ * Derive a 32-byte AES key from the agent's secp256k1 privkey (hex).
+ * Deterministic — same privkey always produces the same key, so the
+ * SDK can encrypt now and decrypt later without storing the key.
+ */
+declare function deriveMemoryKey(privkey: string): Buffer;
+/**
+ * Encrypt UTF-8 plaintext. Returns `{ ciphertext, nonce }` — ciphertext
+ * has the 16-byte GCM auth tag appended, matching the TS SDK's on-chain
+ * byte layout for cross-language parity.
+ */
+declare function encryptMemoryContent(plaintext: string, key: Buffer): {
+    ciphertext: Buffer;
+    nonce: Buffer;
+};
+/**
+ * Decrypt ciphertext produced by `encryptMemoryContent`. Throws when
+ * the GCM auth tag doesn't match (tamper detection / wrong key).
+ */
+declare function decryptMemoryContent(ciphertext: Buffer, nonce: Buffer, key: Buffer): string;
+
+/**
+ * Scan a single memory entry for poisoning.
+ *
+ * `auth` is the agent that signs the on-chain audit log for the
+ * LLM-judge call. If Layer 1 (regex pre-filter) returns red, Layer 2
+ * (LLM) is skipped.
+ */
+declare function scanMemory(entry: MemoryEntry, auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult>;
+/**
+ * Scan multiple entries. Stops on the first red verdict by default —
+ * set `stopOnRed: false` to scan every entry regardless.
+ */
+declare function scanMemoryBatch(entries: MemoryEntry[], auth: AgentAuth, opts?: MemoryScanOptions & {
+    stopOnRed?: boolean;
+}): Promise<MemoryScanResult[]>;
+
+interface CommitMemoryOptions {
+    /** Score in [1, 10]. Defaults to 5 (matches the Rell entity default). */
+    score?: number;
+    /** Org name — when set, the SDK resolves which chain the agent lives on. */
+    orgName?: string;
+    /** Atbash service endpoint for org→chain lookup. */
+    endpoint?: string;
+    chainOpts?: ChainOpts;
+}
+interface RollbackMemoryOptions {
+    orgName?: string;
+    endpoint?: string;
+    chainOpts?: ChainOpts;
+}
+/**
+ * Encrypt `plaintext` and commit it as a new memory version via
+ * `add_agent_memory`. The previous active version (if any) is
+ * deactivated on-chain.
+ *
+ * The caller is responsible for running `scanMemory` first when
+ * appropriate — this function does not gate on the verdict. The
+ * `score` parameter is the only metadata that flows in alongside
+ * the ciphertext.
+ */
+declare function commitMemoryVersion(plaintext: string, auth: AgentAuth, opts?: CommitMemoryOptions): Promise<void>;
+/**
+ * Decrypted memory entry returned by the read helpers.
+ *
+ * `content` is the plaintext recovered from on-chain ciphertext. If
+ * decryption fails (corrupted row, wrong key, etc.), `content` is
+ * empty and `decryptError` carries the reason — the SDK returns the
+ * row instead of throwing so one bad entry doesn't hide the rest.
+ */
+interface AgentMemoryEntry {
+    id: number;
+    content: string;
+    decryptError?: string;
+    score: number;
+    isActive: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Rollback event from `memory_rollback_log`. */
+interface MemoryRollbackEvent {
+    fromId: number;
+    toId: number;
+    reason: string;
+    signer: string;
+    createdAt: number;
+}
+/**
+ * Recent active memory entries — subset of active versions filtered
+ * by the chain's `MEMORY_RECENT_WINDOW_MS` (10 days at time of
+ * writing). Intended for prompt injection at agent runtime, where
+ * stale memory is worse than missing memory. For a time-unbounded
+ * view of every currently active version, use `getAllAgentMemory`.
+ */
+declare function getActiveMemory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+/**
+ * All currently-active memory entries with no time cutoff. Use this
+ * when you need every active version regardless of age — e.g., a
+ * dashboard listing, or a long-running agent whose oldest active
+ * versions may have fallen outside `getActiveMemory`'s recent window.
+ */
+declare function getAllAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+/**
+ * Full version history — active + inactive, most recent first.
+ * Used by rollback UX to choose a target version.
+ */
+declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+/**
+ * Fetch a single memory entry by version id, including its current
+ * `is_active` state. Useful for inspecting a historical version
+ * before rolling back to it.
+ */
+declare function getMemoryById(id: number, auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry>;
+/**
+ * Audit trail of rollback events for this agent, most recent first.
+ */
+declare function getRollbackHistory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<MemoryRollbackEvent[]>;
+/**
+ * Roll back to a previously-committed memory version. The target
+ * `toId` must exist and be currently inactive. `reason` is required
+ * and is recorded on-chain in `memory_rollback_log`.
+ */
+declare function rollbackMemory(toId: number, reason: string, auth: AgentAuth, opts?: RollbackMemoryOptions): Promise<void>;
+
+/**
+ * Classify a plugin tool-call event as a memory write.
+ *
+ * Plugins receive `before_tool_call` events from their host runtime
+ * (openclaw, Claude API, MCP, etc.) with varying argument shapes. This
+ * module normalizes across shapes and returns a `MemoryEntry` when the
+ * call is writing to a memory-like path, or `null` when the SDK should
+ * skip the memory-scan path entirely.
+ *
+ * `event` and `ctx` are typed `unknown` so any plugin can pass its
+ * native hook payloads without adaptation — the classifier probes
+ * common key names at runtime.
+ */
+
+/**
+ * Tool names that indicate a memory write. Lowercase — matched
+ * case-insensitively so both OpenClaw (lowercase) and Claude API
+ * family (TitleCase) hit.
+ */
+declare const DEFAULT_MEMORY_WRITE_TOOL_NAMES: ReadonlyArray<string>;
+/**
+ * File path substrings that indicate a memory-shaped target. Callers
+ * can extend or override this list via `classifyMemoryWrite` options.
+ */
+declare const DEFAULT_MEMORY_PATH_PATTERNS: ReadonlyArray<string>;
+/**
+ * Minimal shape of a `before_tool_call` context object across plugins.
+ * The classifier reads only these fields — anything else is ignored.
+ */
+interface ClassifierToolContext {
+    tool?: {
+        name?: string;
+    };
+    toolName?: string;
+    name?: string;
+    params?: unknown;
+    args?: unknown;
+    arguments?: unknown;
+}
+/**
+ * Minimal shape of a `before_tool_call` event object across plugins.
+ */
+interface ClassifierToolEvent {
+    toolName?: string;
+    params?: unknown;
+    args?: unknown;
+    arguments?: unknown;
+}
+interface ClassifyMemoryWriteOptions {
+    /** Override default memory-path patterns. */
+    patterns?: ReadonlyArray<string>;
+    /** Override default memory-write tool names. */
+    toolNames?: ReadonlyArray<string>;
+}
+/**
+ * If this tool call is writing to a memory-shaped path, return a
+ * `MemoryEntry` suitable for `scanMemory` / `guardMemoryWrite`.
+ * Otherwise return `null` — the SDK's memory path is skipped and the
+ * caller can fall through to a regular tool-call audit.
+ *
+ * Empty-content writes return `null`: they can't carry a poisoning
+ * payload, and the regular audit path still sees them.
+ */
+declare function classifyMemoryWrite(event: unknown, ctx: unknown, opts?: ClassifyMemoryWriteOptions): MemoryEntry | null;
+
+/**
+ * Plugin-agnostic memory-write guard.
+ *
+ * A single call that replaces the plugin's usual memory-write branch:
+ *   classify → scan (Layer 1 regex + Layer 2 LLM) → gate on verdict →
+ *   persist to chain (fire-and-forget when allowed) → return decision.
+ *
+ * Plugins call this from their `before_tool_call` hook. When it returns
+ * `{ handled: false }` the call wasn't a memory write and the plugin
+ * should fall through to its regular tool-call audit. When
+ * `{ handled: true }` the plugin returns `decision` directly.
+ */
+
+/**
+ * Minimal logger accepted by `guardMemoryWrite`. Plugins pass their
+ * host runtime's logger (openclaw's `api.logger`, MCP's console, etc.).
+ * Only `info` and `warn` are used — omitted methods no-op.
+ */
+interface GuardLogger {
+    info?: (message: string, meta?: unknown) => void;
+    warn?: (message: string, meta?: unknown) => void;
+}
+interface GuardMemoryWriteInput extends ClassifyMemoryWriteOptions {
+    /** The plugin's raw `before_tool_call` event. */
+    event: unknown;
+    /** The plugin's `before_tool_call` context. */
+    ctx: unknown;
+    /** Agent auth used to sign the scan's on-chain audit and the memory-commit tx. */
+    auth: AgentAuth;
+    /** Judge endpoint override (dev vs prod). */
+    endpoint?: string;
+    /** Self-hosted judge response-signing pubkey. */
+    verifyPubKey?: string;
+    /** Org name for chain resolution (public vs org-private chain). */
+    orgName?: string;
+    /** LLM confidence threshold for yellow escalation. Default 0.6. */
+    threshold?: number;
+    /** When false, red verdicts log but don't block. Default true. */
+    enforce?: boolean;
+    /** When true, emit a classifier-probe log line via `logger.info`. */
+    debug?: boolean;
+    /** Optional logger for debug probe + persist-failure warnings. */
+    logger?: GuardLogger;
+}
+/** Plugin-facing decision. Shape mirrors what plugins return from `before_tool_call`. */
+interface GuardMemoryDecision {
+    allow: boolean;
+    block?: boolean;
+    reason?: string;
+}
+interface GuardMemoryWriteResult {
+    /** True when this call was a memory write and `decision` was set. False = plugin should run its regular audit. */
+    handled: boolean;
+    /** Present when handled. Plugin returns this from its hook. */
+    decision?: GuardMemoryDecision;
+    /** Present when handled and scan ran. Absent when scan threw. */
+    scanResult?: MemoryScanResult;
+    /** Present when handled. True when a chain-commit was dispatched (fire-and-forget). */
+    committed?: boolean;
+}
+/**
+ * Guarded memory-write flow. Returns `{ handled: false }` when the tool
+ * call isn't a memory write, otherwise returns a `decision` the plugin
+ * should return from its hook.
+ *
+ * Verdict handling:
+ * - `red`  → not persisted to chain; decision blocks (unless `enforce: false`)
+ * - `yellow` → persisted with LLM score; decision allows
+ * - `green`  → persisted with LLM score; decision allows
+ *
+ * Chain commit is fire-and-forget: network errors are logged via
+ * `logger.warn` but never surfaced to the caller. This mirrors the
+ * existing plugin behaviour — chain is for audit/recovery, not gating.
+ */
+declare function guardMemoryWrite(input: GuardMemoryWriteInput): Promise<GuardMemoryWriteResult>;
+
 /**
  * Atbash SDK Telemetry — OpenTelemetry metrics for usage tracking.
  *
@@ -581,4 +880,4 @@ declare function containsSecret(text: string): boolean;
 declare function createMemorySnapshot(entries: MemoryEntry[], takenAt: number): MemorySnapshot;
 declare function diffMemorySnapshots(before: MemorySnapshot, after: MemorySnapshot): MemoryDiffResult;
 
-export { type ActionType, type AgentAuth, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, type ChainOpts, type ClientSource, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type FromConfigOptions, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, type MemorySnapshot, type ModifiedEntry, type Network, type OrgSubscription, type Provider, type PubkeyValue, type RedactResult, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, containsEvasionCharacters, containsSecret, createMemorySnapshot, derivePublicKey, diffMemorySnapshots, flushTelemetry, generateKeypair, getConfigDir, getConfigPath, isValidPrivateKey, loadAgent, loadAgentFromFile, loadUserConfig, normalizeForMatching, normalizeStatus, normalizeVerdict, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, saveUserConfig, setupTelemetry, shutdownTelemetry, signJudgeAction, signLogToolCall, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };
+export { type ActionType, type AgentAuth, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, type EncryptedMemory, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OrgSubscription, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, classifyMemoryWrite, commitMemoryVersion, containsEvasionCharacters, containsSecret, createMemorySnapshot, decryptMemoryContent, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptMemoryContent, flushTelemetry, generateKeypair, getActiveMemory, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isValidPrivateKey, loadAgent, loadAgentFromFile, loadUserConfig, normalizeForMatching, normalizeStatus, normalizeVerdict, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signJudgeAction, signLogToolCall, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };