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

package/dist/browser.d.mts

@@ -281,6 +281,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;
@@ -332,6 +342,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
@@ -360,6 +372,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 {
@@ -377,6 +391,8 @@ 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;
     private readonly logger;
@@ -1051,11 +1067,163 @@ 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.
+ */
+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`.
+ */
+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.
+ *
+ * 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.
+ */
+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";
+};
+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;
+
 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;
@@ -1065,4 +1233,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 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 };