@atbash/sdk 0.6.2 → 0.7.0

package/dist/browser.d.mts

@@ -11,6 +11,23 @@ interface ValidatedEndpoint {
     policy: "default" | "self-hosted";
     verifyPubKey: string | null;
 }
+/**
+ * Builds the trusted judge host set.
+ *
+ * The compiled-in default is always trusted: a `prod` build resolves it to
+ * atbash.ai, a dev build to whatever DEV_ENDPOINT was set at build time. No
+ * dev host is spelled out in source, and dev builds still validate their own
+ * default.
+ *
+ * Exported for tests only. The set is a build-time value and is deliberately
+ * never read from the process environment — an env var would let anyone widen
+ * the allowlist of an already-shipped artifact, which is the silent-redirection
+ * attack the allowlist exists to prevent (F-003). Asserting that requires
+ * calling this with the environment set, so it cannot stay module-private.
+ *
+ * @internal
+ */
+declare function buildAllowedJudgeHosts(): ReadonlySet<string>;
 declare function validateJudgeEndpoint(judge?: JudgeEndpointConfig): ValidatedEndpoint;
 
 /**
@@ -160,6 +177,13 @@ interface JudgeResult {
     enforced: boolean;
     /** Server-reported protection mode: `off`, `monitor`, or `enforce`. */
     enforcementMode: string;
+    /**
+     * Server-reported response status. The judge sets `"logged"` on the AUDIT
+     * tier, where it deliberately returns no verdict. This is the ONLY signal
+     * that distinguishes "the server chose not to enforce" from "the verdict is
+     * missing" — never infer the former from a null verdict alone.
+     */
+    status: string;
 }
 interface JudgmentStatus {
     status: JudgmentState;
@@ -274,6 +298,16 @@ interface AtbashOptions {
      * per-call `verifyPubKey` still overrides it.
      */
     verifyPubKey?: string;
+    /**
+     * Org's encryption public key (33-byte compressed secp256k1, hex). When set,
+     * tool calls are sealed to it and signed as `log_encrypted_tool_call` instead
+     * of `log_tool_call`, so the action never reaches the block in clear.
+     *
+     * Required for any org that has registered a key — the contract refuses
+     * plaintext for those. Omitted, behaviour is unchanged. A per-call
+     * `orgEncryptionPubKey` overrides this, same as `verifyPubKey`.
+     */
+    orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     failClosed?: boolean;
     logger?: AtbashLogger;
@@ -325,6 +359,8 @@ interface JudgeOptions {
     provider?: string;
     model?: string;
     verifyPubKey?: string;
+    /** Per-call override of {@link AtbashOptions.orgEncryptionPubKey}. */
+    orgEncryptionPubKey?: string;
     /**
      * Org name — when set, the SDK resolves which chain the agent lives
      * on via the off-chain `org_networks` map (authoritative) before
@@ -353,6 +389,8 @@ interface LogToolCallOptions {
     toolArgsJson?: string;
     /** Per-call chain override — same semantics as `JudgeOptions.chainOpts`. */
     chainOpts?: ChainOpts;
+    /** Per-call override of {@link AtbashOptions.orgEncryptionPubKey}. */
+    orgEncryptionPubKey?: string;
 }
 
 interface ChainConfig {
@@ -370,8 +408,12 @@ declare class Atbash {
     readonly orgName?: string;
     /** Default judge response-signing pubkey, if configured (see fromConfig). */
     readonly verifyPubKey?: string;
+    /** Default org encryption key — see {@link AtbashOptions.orgEncryptionPubKey}. */
+    readonly orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     readonly failClosed: boolean;
+    /** Org key learned from the last agent-exists check, for this agent only. */
+    private _orgKeyFromChain;
     private readonly logger;
     private readonly http;
     /**
@@ -585,8 +627,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>;
 /**
@@ -617,9 +659,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>;
 /**
@@ -651,35 +691,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>;
 /**
@@ -693,29 +726,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>;
 /**
@@ -911,7 +930,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. */
@@ -925,6 +944,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;
 
@@ -1044,11 +1067,94 @@ declare function flushTelemetry(): Promise<void>;
  */
 declare function shutdownTelemetry(): Promise<void>;
 
+/**
+ * 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;
+/** 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;
+
+/**
+ * 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.
+ *
+ * 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: "toolcall";
+    readonly verdict: "verdict";
+    readonly note: "note";
+    readonly policy: "policy";
+    readonly raw: "raw";
+};
+type EciesDomain = (typeof EciesDomain)[keyof typeof EciesDomain];
+/**
+ * Encrypt `plaintext` so that only the holder of `orgPubKeyHex` can read it.
+ *
+ * @param plaintext     UTF-8 text to protect.
+ * @param orgPubKeyHex  Org's compressed secp256k1 public key (33 bytes hex).
+ * @param aad           Context bound to the ciphertext — pass the record's id.
+ * @returns raw payload for a Rell `byte_array` column.
+ */
+declare function encryptForOrg(plaintext: string, orgPubKeyHex: string, aad: string, domain?: EciesDomain): Uint8Array;
+/**
+ * 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.
+ *
+ * @param payload        Value read from the on-chain `byte_array` column.
+ * @param orgPrivKeyHex  Org's secp256k1 private key (32 bytes hex).
+ * @param aad            Must equal the `aad` used when encrypting.
+ */
+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.
+ */
+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;
 declare function loadAgent(privkey: string): AgentAuth;
 declare function signLogToolCall(toolCallId: string, action: string, context: string, toolName: string, toolArgsJson: string, privkey: string, blockchainRid: string): string;
+
 declare function signJudgeAction(judgmentId: string, action: string, context: string, extra: string, privkey: string, blockchainRid: string): string;
 declare function verifySignature(body: Buffer, signatureHex: string, pubkeyHex: string): boolean;
 declare function normalizeForMatching(text: string): string;
@@ -1058,4 +1164,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, 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 };
+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, buildAllowedJudgeHosts, 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 };