@atbash/sdk 0.6.0 → 0.6.1

package/dist/browser.d.mts

@@ -150,6 +150,8 @@ interface JudgeResult {
     latencyMs: number;
     toolCallId: string;
     onChain: boolean;
+    /** Severity 1 (poisonous) → 10 (benign). Present on memory-scan responses; absent for regular tool-call judgments. */
+    score?: number;
     /**
      * Whether the org's protection mode actually acts on a HOLD/BLOCK verdict.
      * `false` in Monitor mode (verdict is logged for observation, agent is NOT
@@ -395,8 +397,17 @@ declare class Atbash {
     static fromConfig(options?: FromConfigOptions): Atbash;
     get pubkey(): string;
     get privkey(): string;
-    /** GET /api/ai/exists?pubkey=… — defaults to this client's pubkey. */
-    checkAgentExists(pubkey?: string): Promise<boolean>;
+    /**
+     * `GET /api/ai/exists?pubkey=…[&network=…]` — defaults to this client's
+     * pubkey. Pass `opts.network` when the caller already knows which
+     * network the agent lives on (e.g. after resolving via `orgName`) so
+     * the dashboard queries that chain directly instead of falling back
+     * across public → private, which double-round-trips and can return
+     * false negatives when the fallback chain client is misconfigured.
+     */
+    checkAgentExists(pubkey?: string, opts?: {
+        network?: Network;
+    }): Promise<boolean>;
     /**
      * Pre-flight `checkAgentExists`, then sign `log_tool_call` locally and
      * return the signed tx hex. The server broadcasts to chain.
@@ -560,26 +571,15 @@ 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): {
+/** Derive the 32-byte AES key from an agent's secp256k1 privkey (hex). Deterministic — same privkey always yields the same key. */
+declare function deriveMemoryKey(privkey: string): Promise<Buffer>;
+/** Encrypt UTF-8 plaintext. `ciphertext` has the 16-byte GCM auth tag appended, matching the SDK's on-chain byte layout. */
+declare function encryptMemoryContent(plaintext: string, key: Buffer): Promise<{
     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;
+}>;
+/** Decrypt ciphertext produced by `encryptMemoryContent`. Throws on GCM tag mismatch — indicates tampered ciphertext or wrong key. */
+declare function decryptMemoryContent(ciphertext: Buffer, nonce: Buffer, key: Buffer): Promise<string>;
 
 /**
  * Scan a single memory entry for poisoning.
@@ -647,6 +647,15 @@ interface MemoryRollbackEvent {
     signer: string;
     createdAt: number;
 }
+/**
+ * Cheap version-pointer probe. Returns just the id of the current
+ * active memory (or null if none). No ciphertext is transferred — the
+ * response is a single integer, so this is safe to call on every
+ * memory-read hot path. Callers that hold a decrypted local copy can
+ * compare against a stored pointer and only refetch the full row via
+ * `getActiveMemory` when the id has changed.
+ */
+declare function getActiveMemoryId(auth: AgentAuth, chainOpts?: ChainOpts): Promise<number | null>;
 /**
  * Recent active memory entries — subset of active versions filtered
  * by the chain's `MEMORY_RECENT_WINDOW_MS` (10 days at time of
@@ -825,6 +834,175 @@ interface GuardMemoryWriteResult {
  */
 declare function guardMemoryWrite(input: GuardMemoryWriteInput): Promise<GuardMemoryWriteResult>;
 
+/**
+ * Aligns a local `MemoryPointer` with chain's active memory version
+ * via a TTL-cached pointer check. Inside the TTL window: no-op.
+ * Past it: one cheap chain query for the current active id; only on
+ * mismatch does the full row get refetched and decrypted.
+ *
+ * Fail modes:
+ *   - Chain unreachable → throws the network error verbatim; caller
+ *     serves the local copy and retries on the next check.
+ *   - Tampered ciphertext (GCM tag mismatch) → throws
+ *     `MemoryIntegrityError`. Fail-closed — never silent.
+ */
+
+/** Per-agent state the caller persists between sync calls. */
+interface MemoryPointer {
+    /** Last known chain-active memory id, or null if the agent had no active memory at the last check. */
+    activeId: number | null;
+    /** Wall-clock ms of the last successful chain check. Use 0 to force a check on the next call. */
+    checkedAt: number;
+}
+interface SyncMemoryOptions {
+    /** Trust the pointer without touching chain for this many ms since `checkedAt`. Default 30_000. */
+    ttlMs?: number;
+    /** Skip the TTL gate and force a chain check this call. Default false. */
+    force?: boolean;
+    chainOpts?: ChainOpts;
+}
+/**
+ * `drifted: false` — pointer is still valid; caller can keep serving the local copy.
+ * `drifted: true`  — active id changed on chain; `current` is the fresh decrypted row
+ *                    (or `null` if active memory was removed entirely).
+ */
+type SyncMemoryResult = {
+    drifted: false;
+    pointer: MemoryPointer;
+} | {
+    drifted: true;
+    current: AgentMemoryEntry | null;
+    pointer: MemoryPointer;
+};
+/** Thrown when a fetched active row fails its GCM integrity check. Poisoning signal — do not swallow. */
+declare class MemoryIntegrityError extends Error {
+    readonly id: number;
+    constructor(id: number, reason: string);
+}
+declare function syncLocalMemory(auth: AgentAuth, pointer: MemoryPointer, opts?: SyncMemoryOptions): Promise<SyncMemoryResult>;
+
+declare class PointerStore {
+    private readonly filePath;
+    private cache;
+    private loading;
+    constructor(filePath: string);
+    /** Resolves the pointer for `agentPubkeyHex`, or a zero-pointer that will force a sync on first use. */
+    get(agentPubkeyHex: string): Promise<MemoryPointer>;
+    /** Persists an updated pointer. Failures are swallowed to a logger callback (if provided) so sync never blocks the caller. */
+    set(agentPubkeyHex: string, pointer: MemoryPointer, onError?: (err: Error) => void): Promise<void>;
+    private ensureLoaded;
+    private loadOnce;
+    private persist;
+}
+/** Default pointer-file location — `<workspaceDir>/.atbash/memory-pointer.json`. */
+declare function defaultPointerPath(workspaceDir?: string): string;
+
+/** Small logger shape used across the memory-poisoning surface. */
+interface WrappedLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+}
+interface UpstreamLogger {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+}
+/** Writes are serialized via an internal promise queue so lines interleave in call-order under concurrency. */
+declare function createFileLogger(filePath: string, upstream?: UpstreamLogger): WrappedLogger;
+/** Default log-file location — `<workspaceDir>/.atbash/plugin.log`. */
+declare function defaultPluginLogPath(workspaceDir?: string): string;
+
+/** Dedicated memory-read tool names, matched case-insensitively. Extend via options. */
+declare const DEFAULT_MEMORY_READ_TOOL_NAMES: ReadonlyArray<string>;
+interface ClassifyMemoryReadOptions {
+    /** Tool names that always count as memory reads. Merged with defaults. */
+    readToolNames?: ReadonlyArray<string>;
+    /** Additional path substrings that mark a file as memory. Merged with defaults. */
+    patterns?: ReadonlyArray<string>;
+    /** Additional generic-read tool names whose path arg to inspect. Merged with defaults. */
+    genericReadToolNames?: ReadonlyArray<string>;
+}
+/**
+ * Returns `true` when this tool call is a memory read — either a
+ * dedicated memory-read tool from `readToolNames`, or a generic read
+ * tool (`read` / `read_file`) targeting a memory-shaped path.
+ */
+declare function classifyMemoryRead(event: unknown, ctx: unknown, opts?: ClassifyMemoryReadOptions): boolean;
+
+/** Decision the manager returns to the plugin's `before_tool_call` handler. */
+interface HookDecision {
+    allow?: boolean;
+    block?: boolean;
+    blockReason?: string;
+    reason?: string;
+}
+interface MemoryGuardManagerOptions {
+    auth: AgentAuth;
+    /** Host workspace root (used to derive default file paths). */
+    workspaceDir: string;
+    /** Absolute MEMORY.md path. Default `<workspaceDir>/MEMORY.md`. */
+    memoryFilePath?: string;
+    /** Persistent pointer file. Default `<workspaceDir>/.atbash/memory-pointer.json`. */
+    pointerFilePath?: string;
+    /** File-backed log. Default `<workspaceDir>/.atbash/plugin.log`. */
+    logFilePath?: string;
+    /** Optional host-native logger — every event mirrors here as well. */
+    hostLogger?: {
+        info: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+    };
+    /** TTL for the local-sync pointer between chain checks. Default 30_000 ms. */
+    ttlMs?: number;
+    /** Block memory reads when the chain-active version's score is below this. Default 1 (never blocks). */
+    rollbackMinScore?: number;
+    /** True → return `{block:true}` on defense triggers. False → log and return `null` (audit-only). Default true. */
+    enforce?: boolean;
+    /** Host-specific tuning of what counts as a memory read. */
+    memoryReadClassifier?: ClassifyMemoryReadOptions;
+    /** Passed through to `guardMemoryWrite`. Host memory-write tool names override. */
+    memoryWriteToolNames?: ReadonlyArray<string>;
+    /** Passed through to `guardMemoryWrite` — extra memory path substrings. */
+    memoryPathPatterns?: ReadonlyArray<string>;
+    /** Passed through to `guardMemoryWrite` — judge endpoint override (defaults to userConfig / DEFAULT_ENDPOINT). */
+    judgeEndpoint?: string;
+    /** Passed through to `guardMemoryWrite` — self-hosted judge verify pubkey. */
+    judgeVerifyPubKey?: string;
+    /** Passed through — org name for chain resolution. */
+    orgName?: string;
+    /** Debug probe in `guardMemoryWrite`. */
+    debug?: boolean;
+}
+/**
+ * Wire-once, dispatch-many factory. Plugins call once at register(),
+ * then feed every `before_tool_call` through `handleBeforeToolCall`.
+ */
+declare class MemoryGuardManager {
+    private readonly opts;
+    private readonly pointerStore;
+    private readonly logger;
+    private readonly memoryFilePath;
+    private readonly ttlMs;
+    private readonly rollbackMinScore;
+    private readonly enforce;
+    private readonly agentPubkeyHex;
+    constructor(opts: MemoryGuardManagerOptions);
+    /**
+     * One-shot chain probe at plugin registration. Refreshes MEMORY.md
+     * from chain when drifted and score passes threshold. Fire-and-forget
+     * — errors are logged, never thrown.
+     */
+    runBootProbe(): Promise<void>;
+    /**
+     * Returns a `HookDecision` when the event is a memory read or write
+     * (host returns it verbatim to its runtime). Returns `null` when the
+     * event isn't memory-related — host falls through to its own audit.
+     */
+    handleBeforeToolCall(event: unknown, ctx: unknown): Promise<HookDecision | null>;
+    private mapGuardResult;
+    private handleMemoryRead;
+    private writeMemoryAtomic;
+}
+declare function createMemoryGuardManager(opts: MemoryGuardManagerOptions): MemoryGuardManager;
+
 /**
  * Atbash SDK Telemetry — OpenTelemetry metrics for usage tracking.
  *
@@ -880,4 +1058,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 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 };
+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 ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, 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 HookDecision, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OrgSubscription, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, classifyMemoryRead, classifyMemoryWrite, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptMemoryContent, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, 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, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };