@atbash/sdk 0.9.0-dev.0 → 0.10.1-dev.0

package/dist/index.d.ts

@@ -608,8 +608,8 @@ declare function decryptMemoryContent(ciphertext: Buffer, nonce: Buffer, key: Bu
  * Scan a single memory entry for poisoning.
  *
  * `auth` is the agent that signs the on-chain audit log for the
- * LLM-judge call. The LLM is authoritative; unicode-evasion presence
- * is surfaced to the prompt so the LLM can weight suspicion accordingly.
+ * LLM-judge call. Unicode-evasion presence is surfaced to the prompt
+ * so the LLM can weight suspicion accordingly.
  */
 declare function scanMemory(entry: MemoryEntry, auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult>;
 /**
@@ -640,9 +640,7 @@ interface RollbackMemoryOptions {
  * 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.
+ * appropriate — this function does not gate on the verdict.
  */
 declare function commitMemoryVersion(plaintext: string, auth: AgentAuth, opts?: CommitMemoryOptions): Promise<void>;
 /**
@@ -674,35 +672,28 @@ interface MemoryRollbackEvent {
  * 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.
+ * memory-read hot path.
  */
 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
- * 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`.
+ * by the chain's `MEMORY_RECENT_WINDOW_MS`. 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.
+ * when you need every active version regardless of age.
  */
 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.
+ * 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.
+ * `is_active` state.
  */
 declare function getMemoryById(id: number, auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry>;
 /**
@@ -716,29 +707,15 @@ declare function getRollbackHistory(auth: AgentAuth, chainOpts?: ChainOpts): Pro
  */
 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.
+ * case-insensitively so OpenClaw (lowercase) and Claude API family
+ * (TitleCase) both 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.
+ * extend or override via `classifyMemoryWrite` options.
  */
 declare const DEFAULT_MEMORY_PATH_PATTERNS: ReadonlyArray<string>;
 /**
@@ -934,7 +911,7 @@ declare function createFileLogger(filePath: string, upstream?: UpstreamLogger):
 /** 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. */
+/** Dedicated memory-read tool names, matched case-insensitively. */
 declare const DEFAULT_MEMORY_READ_TOOL_NAMES: ReadonlyArray<string>;
 interface ClassifyMemoryReadOptions {
     /** Tool names that always count as memory reads. Merged with defaults. */
@@ -948,6 +925,10 @@ interface ClassifyMemoryReadOptions {
  * 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.
+ *
+ * Caller-supplied `patterns` are MERGED with the defaults (matches
+ * Node's original behavior — extending in one plugin doesn't disable
+ * standard coverage).
  */
 declare function classifyMemoryRead(event: unknown, ctx: unknown, opts?: ClassifyMemoryReadOptions): boolean;
 
@@ -1068,126 +1049,33 @@ declare function flushTelemetry(): Promise<void>;
 declare function shutdownTelemetry(): Promise<void>;
 
 /**
- * Signs `log_encrypted_tool_call` — the ciphertext-only counterpart of
- * `log_tool_call`.
- *
- * Why this is not in the Rust core like the other signing helpers: the operation
- * takes a `byte_array` argument, and the only consumer today is the dashboard,
- * which loads the browser bundle where Rust is unreachable by construction. This
- * module is plain TypeScript so the node and browser builds share one
- * implementation and cannot drift. The Rust core gets the same operation when the
- * native/Python/Go callers need it — the wire format is pinned by `crypto/ecies.ts`.
- *
- * The contract refuses plaintext once an org registers an encryption key
- * (`log_tool_call` → "Organization requires encrypted payloads"), so for those
- * orgs this is the only way to log a tool call at all.
- */
-/**
- * Commitment to the plaintext claims a caller sends alongside the ciphertext.
- *
- * The judge server reads tool_name / action / context / tool_args_json from the
- * request body and feeds them to policy evaluation, but it holds no org key, so
- * it cannot check them against content_cipher. This hash is a signed operation
- * argument, which makes it the one thing it can check them against.
- *
- * An array, not an object: key order is not part of a JSON array, so the two
- * implementations cannot drift on serialization. Must stay identical to
- * `claimHashHex` in the dashboard (`src/lib/api/judge/action-hash.ts`).
- */
-declare function claimHashHex(toolName: string, action: string, context: string, toolArgsJson: string): string;
-/** Plaintext fields of a tool call, sealed into a single ECIES payload. */
-interface ToolCallPlaintext {
-    tool_name: string;
-    action: string;
-    context: string;
-    tool_args_json: string;
-}
-/**
- * Canonical form of an action for the retry-cache hash.
- *
- * Must stay identical to `normalizeActionForHash` in the dashboard
- * (`src/lib/api/judge/on-chain.ts`): both write the same
- * `tool_call_log.normalized_action_hash` column, and `get_resolved_hold_by_action_hash`
- * matches a YELLOW hold retry against it. Diverging here silently breaks
- * hold resolution rather than failing loudly.
+ * Rust core does the work; `browser/encrypted-toolcall.ts` mirrors it for the
+ * browser and must produce the same columns.
  */
+/** Must match `column_aad` in the core — the label binds a ciphertext to its column. */
+declare function columnAad(toolCallId: string, column: string): string;
+/** Byte-identical to the dashboard's copy — diverging breaks hold-retry resolution. */
 declare function normalizeActionForHash(action: string): string;
-/**
- * Sign a `log_encrypted_tool_call` operation.
- *
- * Everything the agent did — action, context, tool name and args — goes into a
- * single ECIES payload readable only with the org's private key. Nothing
- * identifying the action is left in the operation arguments, which are permanent
- * block data.
- *
- * `actionHash` is the one exception, and it is deliberate: it is a SHA-256 over
- * the normalized action, so the chain can match a held action against its retry
- * without being able to read it.
- *
- * @returns hex-encoded signed transaction, ready to POST as `signed_log_tool_call`.
- */
+/** Lets the judge check the request body against the ciphertext without an org key. */
+declare function claimHashHex(toolName: string, action: string, context: string, toolArgsJson: string): string;
+/** @returns hex-encoded signed tx, ready to POST as `signed_log_tool_call`. */
 declare function signEncryptedToolCall(toolCallId: string, action: string, context: string, toolName: string, toolArgsJson: string, orgEncryptionPubKey: string, privkeyHex: string, blockchainRidHex: string): string;
 
 /**
- * ECIES over secp256k1 — encrypts on-chain payloads to an organization's public key.
- *
- * Only the holder of the org's private key can decrypt. Everyone else — including
- * anyone querying the Chromia node directly, and Atbash itself — sees ciphertext.
- * The recipient key is a dedicated encryption keypair the org generates in the
- * dashboard and registers via `org_set_encryption_key`; it is read back with the
- * `get_org_encryption_pubkey` query.
- *
- * ─── WIRE FORMAT (normative) ────────────────────────────────────────────────
- * This exact layout is mirrored in the Atbash dashboard
- * (`src/lib/chromia/ecies.ts`) and must stay byte-for-byte identical: the SDK
- * encrypts tool calls, the dashboard decrypts them.
- *
- *   version           1 byte   = 0x01
- *   ephemeral_pubkey  33 bytes   compressed secp256k1 point
- *   nonce             12 bytes   random, per message
- *   ciphertext+tag    N bytes    AES-256-GCM output (16-byte tag appended)
- *
- * Version 0x01 is FROZEN, not provisional. Records encrypted under it already
- * exist on the deployed chains, and the ledger is immutable — redefining 0x01
- * would make them permanently unreadable, not merely stale. Evolving the format
- * means emitting a NEW version byte and keeping a 0x01 decrypt path, in both
- * repos, forever.
- *
- * Raw bytes, not base64: the on-chain columns are `byte_array`, so encoding to
- * text would add ~33% to what are the largest columns in the schema.
- *
- * Key agreement, per message:
- *   shared_x = ECDH(ephemeral_privkey, org_pubkey).x            // 32 bytes
- *   key      = HKDF-SHA256(ikm=shared_x, salt=ephemeral_pubkey, info=domain, len=32)
- *   aad      = "<domain>|<record_id>"
- *
- * A fresh ephemeral keypair is generated for every message and its private half is
- * discarded immediately. This is what makes the scheme forward-secret with respect
- * to the *sender*: leaking an agent's long-term signing key later does not expose
- * anything it encrypted in the past. (Deriving the shared secret from the agent's
- * static key instead would let anyone recompute every past shared secret, since the
- * org's public key is public by definition.)
- *
- * Three separate bindings, each closing a different substitution:
- *   salt = ephemeral pubkey  — ties the key to this exact handshake
- *   info = domain            — a verdict payload cannot be read as a tool call
- *   aad  = domain|record_id  — a payload cannot be lifted onto another row
- */
-/**
- * Cryptographic domain per payload kind. Fed to HKDF `info`, so each kind derives
- * a different key from the same handshake — a verdict payload handed to the
- * tool-call reader fails authentication rather than decoding to an empty struct.
+ * Cryptographic domain per payload kind. Each kind derives a distinct
+ * key from the same handshake — a verdict payload handed to the
+ * tool-call reader fails authentication rather than silently decoding.
  *
- * Must match `EciesDomain` in the dashboard's src/lib/chromia/ecies.ts exactly:
- * the string is an input to key derivation, so any difference makes the two sides
- * mutually unreadable.
+ * Values here are the SHORT domain names the Rust core recognizes.
+ * The full HKDF `info` strings (`atbash:chain-encryption:v1:<kind>`)
+ * live inside the core and never surface at the API boundary.
  */
 declare const EciesDomain: {
-    readonly toolCall: "atbash:chain-encryption:v1:toolcall";
-    readonly verdict: "atbash:chain-encryption:v1:verdict";
-    readonly note: "atbash:chain-encryption:v1:note";
-    readonly policy: "atbash:chain-encryption:v1:policy";
-    readonly raw: "atbash:chain-encryption:v1:raw";
+    readonly toolCall: "toolcall";
+    readonly verdict: "verdict";
+    readonly note: "note";
+    readonly policy: "policy";
+    readonly raw: "raw";
 };
 type EciesDomain = (typeof EciesDomain)[keyof typeof EciesDomain];
 /**
@@ -1202,9 +1090,9 @@ declare function encryptForOrg(plaintext: string, orgPubKeyHex: string, aad: str
 /**
  * Decrypt a payload produced by {@link encryptForOrg}.
  *
- * Throws if the key is wrong, the `aad` does not match the one used at encrypt
- * time, or the ciphertext was tampered with — GCM authentication makes all three
- * indistinguishable by design.
+ * Throws if the key is wrong, the `aad` does not match the one used at
+ * encrypt time, or the ciphertext was tampered with — GCM authentication
+ * makes all three indistinguishable by design.
  *
  * @param payload        Value read from the on-chain `byte_array` column.
  * @param orgPrivKeyHex  Org's secp256k1 private key (32 bytes hex).
@@ -1212,12 +1100,36 @@ declare function encryptForOrg(plaintext: string, orgPubKeyHex: string, aad: str
  */
 declare function decryptForOrg(payload: Uint8Array, orgPrivKeyHex: string, aad: string, domain?: EciesDomain): string;
 /**
- * Size in bytes of the encrypted payload for a given plaintext length. Lets
- * callers check against the on-chain column cap (MAX_CONTENT_CIPHER_SIZE)
- * before submitting a transaction the contract would reject.
+ * Size in bytes of the encrypted payload for a given plaintext length.
+ * Lets callers check against the on-chain column cap
+ * (`MAX_CONTENT_CIPHER_SIZE`) before submitting a transaction the
+ * contract would reject.
  */
 declare function encryptedLength(plaintextByteLength: number): number;
 
+/**
+ *   atb1.<key-fingerprint>.<claim-hash>.<base64 ciphertext>
+ *
+ * Normative spec: `core/src/crypto_envelope.rs`. This mirrors it for the browser.
+ */
+interface Envelope {
+    /** First 8 bytes of the recipient public key, hex. May be empty. */
+    keyFingerprint: string;
+    /** Commitment to the accompanying plaintext claims. May be empty. */
+    claimHash: string;
+    /** Raw ECIES payload. */
+    payload: Uint8Array;
+}
+declare function packEnvelope(payload: Uint8Array, keyFingerprint?: string, claimHash?: string): string;
+/**
+ * Stays true for a truncated envelope that `parseEnvelope` rejects — a severed
+ * ciphertext is not plaintext, so callers must show a placeholder.
+ */
+declare function isEnvelope(value: string): boolean;
+/** Null, not a throw — pre-encryption records are plaintext. */
+declare function parseEnvelope(value: string): Envelope | null;
+declare function keyFingerprintOf(pubKeyHex: string): string;
+
 declare function isValidPrivateKey(hex: string): boolean;
 declare function derivePublicKey(privkey: string): string;
 declare function generateKeypair(): KeyPair;
@@ -1233,4 +1145,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 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, EciesDomain, 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 ToolCallPlaintext, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, claimHashHex, classifyMemoryRead, classifyMemoryWrite, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isValidPrivateKey, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeForMatching, normalizeStatus, normalizeVerdict, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, 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, EciesDomain, type EncryptedMemory, type Envelope, 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, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };