@atbash/sdk 0.1.5 → 0.2.1

package/README.md

@@ -8,7 +8,7 @@ TypeScript SDK for the Atbash judge and risk-engine APIs. Evaluate agent actions
 npm install @atbash/sdk
 ```
 
-Requires Node.js 18 or higher. Server-side only — private keys are sent in request bodies and must never be exposed to browsers.
+Requires Node.js 18 or higher. Server-side only — private keys are used for local signing and must never be exposed to browsers.
 
 ## Quickstart
 
@@ -20,7 +20,9 @@ import { createAgent, judgeAction } from "@atbash/sdk";
 //    validates the key and derives the matching public key for you.
 const agent = createAgent(process.env.ATBASH_AGENT_PRIVKEY!);
 
-// 2. Submit an action for judgment, before executing it
+// 2. Submit an action for judgment, before executing it.
+//    The SDK signs and broadcasts log_tool_call to the Chromia chain
+//    (private key stays local), then requests a verdict from the judge API.
 const result = await judgeAction(
   "Transfer $50,000 to external wallet 0xabc",
   "Outbound AML check — new recipient, over threshold",
@@ -44,6 +46,15 @@ switch (result.verdict) {
 
 Before this works, the agent must be onboarded at [atbash.ai](https://atbash.ai/) — assigned to an org, with a policy pack attached, and the org tier set to Audit+ or Enforcement.
 
+### How it works
+
+`judgeAction()` performs a two-step flow:
+
+1. **Sign on-chain** — signs and broadcasts a `log_tool_call` transaction to the Chromia blockchain using the agent's private key. The key never leaves your machine.
+2. **Request verdict** — sends the resulting `tool_call_id` and `agent_pubkey` to the Atbash judge API. No private key is transmitted over HTTP.
+
+If you need finer control, you can call `logToolCall()` and the judge API separately.
+
 ### Don't have an agent yet?
 
 Generate one programmatically for local development:
@@ -60,7 +71,7 @@ For production, always create agents in the dashboard so operators can attach po
 
 ### Secret storage
 
-The private key authenticates every call. Treat it like any other long-lived credential:
+The private key is used to sign on-chain transactions locally. Treat it like any other long-lived credential:
 
 - Load it from an environment variable (`ATBASH_AGENT_PRIVKEY`) or a secret manager (AWS Secrets Manager, HashiCorp Vault, 1Password, etc.) — never hardcode it.
 - Never commit `.env` files containing the key. Add them to `.gitignore`.
@@ -90,23 +101,29 @@ judgeAction(
 ): Promise<JudgeResult>
 ```
 
-Submit an action for judgment before execution. Returns the verdict, reason, confidence, provider, latency, and tool call ID.
+Submit an action for judgment before execution. Signs `log_tool_call` on-chain, then requests a verdict. Returns the verdict, reason, confidence, provider, latency, and tool call ID.
 
 ```ts
 interface AgentAuth {
   pubkey: string;   // 66-char hex, secp256k1 compressed public key
-  privkey: string;  // 64-char hex private key
+  privkey: string;  // 64-char hex private key (used for local signing only)
 }
 
 interface JudgeOptions {
   endpoint?: string;          // API base URL (default: https://atbash.ai)
   timeout?: number;           // Request timeout in ms
-  provider?: string;          // "atbash" | "openai" | "google" | "microsoft" | "custom"
-  apiKey?: string;            // API key for non-atbash providers
+  provider?: string;          // "openai" | "google" | "microsoft" | "custom"
+  apiKey?: string;            // API key for the AI provider
   providerEndpoint?: string;  // Endpoint for microsoft/custom providers
   model?: string;             // Model override (e.g. "gpt-4o-mini")
   toolName?: string;          // Tool name for audit trail
   toolArgsJson?: string;      // Tool arguments JSON for audit trail
+  chainOpts?: ChainOpts;      // Override Chromia chain connection
+}
+
+interface ChainOpts {
+  nodeUrls?: string[];        // Chromia node URLs (defaults to testnet)
+  blockchainRid?: string;     // Blockchain RID (defaults to testnet)
 }
 
 interface JudgeResult {
@@ -121,6 +138,20 @@ interface JudgeResult {
 }
 ```
 
+### Log tool call (low-level)
+
+```ts
+logToolCall(
+  action: string,
+  context: string,
+  auth: AgentAuth,
+  chainOpts?: ChainOpts,
+  extra?: { toolName?: string; toolArgsJson?: string },
+): Promise<string>
+```
+
+Sign and broadcast `log_tool_call` to the Chromia chain. Returns the `tool_call_id`. Use this if you need to separate the on-chain logging step from the verdict request.
+
 ### Poll judgment status
 
 ```ts
@@ -168,7 +199,7 @@ getToolCallFull(toolCallId: string, opts?: ClientOpts): Promise<ToolCallFull | n
 // Org and agent info
 getOrgTierInfo(orgName: string, opts?: ClientOpts): Promise<TierInfo | null>
 getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise<Record<string, unknown>>
-getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<{ policy: string; is_jailed: boolean; is_custom: boolean; default_policy: string }>
+getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>
 
 // Operator review queue
 getPendingHeldActions(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldAction[]>
@@ -203,6 +234,13 @@ const result = await judgeAction(action, context, auth, {
   apiKey: process.env.OPENAI_API_KEY,
   model: "gpt-4o",
 });
+
+// Custom Chromia chain (e.g. production RID)
+const result = await judgeAction(action, context, auth, {
+  chainOpts: {
+    blockchainRid: "YOUR_PRODUCTION_BLOCKCHAIN_RID",
+  },
+});
 ```
 
 ## Integration patterns
@@ -231,7 +269,7 @@ async function waitForApproval(toolCallId: string): Promise<string> {
 }
 ```
 
-### Checking agent jail status before a batch
+### Checking agent jail status
 
 ```ts
 const policy = await getAgentPolicy(pubKey);

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,11 +17,21 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_BLOCKCHAIN_RID: () => DEFAULT_BLOCKCHAIN_RID,
+  DEFAULT_CHROMIA_NODE_URLS: () => DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
   createAgent: () => createAgent,
   derivePublicKey: () => derivePublicKey,
@@ -38,13 +50,22 @@ __export(index_exports, {
   getToolCalls: () => getToolCalls,
   isValidPrivateKey: () => isValidPrivateKey,
   judgeAction: () => judgeAction,
+  logToolCall: () => logToolCall,
   toPubkeyHex: () => toPubkeyHex
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
 var import_crypto = require("crypto");
+var import_postchain_client = __toESM(require("postchain-client"), 1);
+var { createClient, encryption, newSignatureProvider } = import_postchain_client.default;
 var DEFAULT_ENDPOINT = "https://atbash.ai";
+var DEFAULT_CHROMIA_NODE_URLS = [
+  "https://node6.testnet.chromia.com:7740",
+  "https://node7.testnet.chromia.com:7740",
+  "https://node8.testnet.chromia.com:7740"
+];
+var DEFAULT_BLOCKCHAIN_RID = "25B41DF620C489349C54944496FF5C6E58CFCEFED0C51658780B67299D40E8ED";
 function isValidPrivateKey(hex) {
   return /^[0-9a-fA-F]{64}$/.test(hex);
 }
@@ -83,6 +104,40 @@ function toPubkeyHex(val) {
 function baseUrl(opts) {
   return opts?.endpoint || DEFAULT_ENDPOINT;
 }
+function generateToolCallId() {
+  const ts = Date.now();
+  const rand = (0, import_crypto.randomBytes)(4).toString("hex");
+  return `tc-${ts}-${rand}`;
+}
+async function logToolCall(action, context, auth, chainOpts, extra) {
+  const nodeUrls = chainOpts?.nodeUrls ?? DEFAULT_CHROMIA_NODE_URLS;
+  const blockchainRid = chainOpts?.blockchainRid ?? DEFAULT_BLOCKCHAIN_RID;
+  const client = await createClient({
+    nodeUrlPool: nodeUrls,
+    blockchainRid
+  });
+  const privKeyBuf = Buffer.from(auth.privkey, "hex");
+  const keyPair = encryption.makeKeyPair(privKeyBuf);
+  const sigProvider = newSignatureProvider({
+    privKey: keyPair.privKey,
+    pubKey: keyPair.pubKey
+  });
+  const toolCallId = generateToolCallId();
+  await client.signAndSendUniqueTransaction(
+    {
+      name: "log_tool_call",
+      args: [
+        toolCallId,
+        action,
+        context || "",
+        extra?.toolName || "",
+        extra?.toolArgsJson || ""
+      ]
+    },
+    sigProvider
+  );
+  return toolCallId;
+}
 function normalizeVerdict(raw) {
   const v = String(raw || "").toUpperCase();
   if (v === "ALLOW" || v === "GREEN") return "ALLOW";
@@ -142,17 +197,23 @@ async function getJson(url, opts) {
   return resp.json();
 }
 async function judgeAction(action, context, auth, opts) {
+  const toolCallId = await logToolCall(
+    action,
+    context,
+    auth,
+    opts?.chainOpts,
+    { toolName: opts?.toolName, toolArgsJson: opts?.toolArgsJson }
+  );
   const url = `${baseUrl(opts)}/api/v1/judge`;
   const data = await postJson(
     url,
     {
-      provider: opts?.provider || "",
+      tool_call_id: toolCallId,
+      agent_pubkey: auth.pubkey,
       action,
       context: context || "",
-      agent_pubkey: auth.pubkey,
-      agent_privkey: auth.privkey,
+      provider: opts?.provider || "",
       tool_name: opts?.toolName || "",
-      tool_args_json: opts?.toolArgsJson || "",
       api_key: opts?.apiKey || "",
       endpoint_url: opts?.providerEndpoint || "",
       model: opts?.model || ""
@@ -166,7 +227,7 @@ async function judgeAction(action, context, auth, opts) {
     confidence: Number(data.confidence ?? 0),
     provider: String(data.provider || ""),
     latency_ms: Number(data.latency_ms ?? 0),
-    tool_call_id: String(data.tool_call_id || ""),
+    tool_call_id: String(data.tool_call_id || toolCallId),
     on_chain: Boolean(data.on_chain)
   };
 }
@@ -287,6 +348,8 @@ async function getSafetyStats(opts) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_BLOCKCHAIN_RID,
+  DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT,
   createAgent,
   derivePublicKey,
@@ -305,5 +368,6 @@ async function getSafetyStats(opts) {
   getToolCalls,
   isValidPrivateKey,
   judgeAction,
+  logToolCall,
   toPubkeyHex
 });

package/dist/index.d.cts

@@ -1,4 +1,6 @@
 declare const DEFAULT_ENDPOINT = "https://atbash.ai";
+declare const DEFAULT_CHROMIA_NODE_URLS: string[];
+declare const DEFAULT_BLOCKCHAIN_RID = "25B41DF620C489349C54944496FF5C6E58CFCEFED0C51658780B67299D40E8ED";
 type Verdict = "ALLOW" | "HOLD" | "BLOCK";
 type Provider = "atbash" | "openai" | "google" | "microsoft" | "custom" | (string & {});
 type Tier = "audit" | "audit_plus" | "enforcement" | (string & {});
@@ -23,6 +25,20 @@ interface ClientOpts {
     endpoint?: string;
     timeout?: number;
 }
+interface ChainOpts {
+    nodeUrls?: string[];
+    blockchainRid?: string;
+}
+/**
+ * Sign and broadcast `log_tool_call` to the Chromia chain.
+ *
+ * The agent's private key is used to sign the transaction locally —
+ * it is never sent over the network. Returns the tool_call_id.
+ */
+declare function logToolCall(action: string, context: string, auth: AgentAuth, chainOpts?: ChainOpts, extra?: {
+    toolName?: string;
+    toolArgsJson?: string;
+}): Promise<string>;
 interface JudgeResult {
     verdict: Verdict;
     action_type: ActionType;
@@ -99,6 +115,7 @@ interface JudgeOptions extends ClientOpts {
     model?: string;
     toolName?: string;
     toolArgsJson?: string;
+    chainOpts?: ChainOpts;
 }
 interface AgentPolicy {
     policy: string;
@@ -120,4 +137,4 @@ declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise
 declare function getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>;
 declare function getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>;
 
-export { type AgentAuth, type ClientOpts, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, createAgent, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, toPubkeyHex };
+export { type AgentAuth, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, createAgent, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, logToolCall, toPubkeyHex };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 declare const DEFAULT_ENDPOINT = "https://atbash.ai";
+declare const DEFAULT_CHROMIA_NODE_URLS: string[];
+declare const DEFAULT_BLOCKCHAIN_RID = "25B41DF620C489349C54944496FF5C6E58CFCEFED0C51658780B67299D40E8ED";
 type Verdict = "ALLOW" | "HOLD" | "BLOCK";
 type Provider = "atbash" | "openai" | "google" | "microsoft" | "custom" | (string & {});
 type Tier = "audit" | "audit_plus" | "enforcement" | (string & {});
@@ -23,6 +25,20 @@ interface ClientOpts {
     endpoint?: string;
     timeout?: number;
 }
+interface ChainOpts {
+    nodeUrls?: string[];
+    blockchainRid?: string;
+}
+/**
+ * Sign and broadcast `log_tool_call` to the Chromia chain.
+ *
+ * The agent's private key is used to sign the transaction locally —
+ * it is never sent over the network. Returns the tool_call_id.
+ */
+declare function logToolCall(action: string, context: string, auth: AgentAuth, chainOpts?: ChainOpts, extra?: {
+    toolName?: string;
+    toolArgsJson?: string;
+}): Promise<string>;
 interface JudgeResult {
     verdict: Verdict;
     action_type: ActionType;
@@ -99,6 +115,7 @@ interface JudgeOptions extends ClientOpts {
     model?: string;
     toolName?: string;
     toolArgsJson?: string;
+    chainOpts?: ChainOpts;
 }
 interface AgentPolicy {
     policy: string;
@@ -120,4 +137,4 @@ declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise
 declare function getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>;
 declare function getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>;
 
-export { type AgentAuth, type ClientOpts, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, createAgent, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, toPubkeyHex };
+export { type AgentAuth, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, createAgent, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, logToolCall, toPubkeyHex };

package/dist/index.js

@@ -1,6 +1,14 @@
 // src/client.ts
-import { createECDH } from "crypto";
+import { createECDH, randomBytes } from "crypto";
+import postchain from "postchain-client";
+var { createClient, encryption, newSignatureProvider } = postchain;
 var DEFAULT_ENDPOINT = "https://atbash.ai";
+var DEFAULT_CHROMIA_NODE_URLS = [
+  "https://node6.testnet.chromia.com:7740",
+  "https://node7.testnet.chromia.com:7740",
+  "https://node8.testnet.chromia.com:7740"
+];
+var DEFAULT_BLOCKCHAIN_RID = "25B41DF620C489349C54944496FF5C6E58CFCEFED0C51658780B67299D40E8ED";
 function isValidPrivateKey(hex) {
   return /^[0-9a-fA-F]{64}$/.test(hex);
 }
@@ -39,6 +47,40 @@ function toPubkeyHex(val) {
 function baseUrl(opts) {
   return opts?.endpoint || DEFAULT_ENDPOINT;
 }
+function generateToolCallId() {
+  const ts = Date.now();
+  const rand = randomBytes(4).toString("hex");
+  return `tc-${ts}-${rand}`;
+}
+async function logToolCall(action, context, auth, chainOpts, extra) {
+  const nodeUrls = chainOpts?.nodeUrls ?? DEFAULT_CHROMIA_NODE_URLS;
+  const blockchainRid = chainOpts?.blockchainRid ?? DEFAULT_BLOCKCHAIN_RID;
+  const client = await createClient({
+    nodeUrlPool: nodeUrls,
+    blockchainRid
+  });
+  const privKeyBuf = Buffer.from(auth.privkey, "hex");
+  const keyPair = encryption.makeKeyPair(privKeyBuf);
+  const sigProvider = newSignatureProvider({
+    privKey: keyPair.privKey,
+    pubKey: keyPair.pubKey
+  });
+  const toolCallId = generateToolCallId();
+  await client.signAndSendUniqueTransaction(
+    {
+      name: "log_tool_call",
+      args: [
+        toolCallId,
+        action,
+        context || "",
+        extra?.toolName || "",
+        extra?.toolArgsJson || ""
+      ]
+    },
+    sigProvider
+  );
+  return toolCallId;
+}
 function normalizeVerdict(raw) {
   const v = String(raw || "").toUpperCase();
   if (v === "ALLOW" || v === "GREEN") return "ALLOW";
@@ -98,17 +140,23 @@ async function getJson(url, opts) {
   return resp.json();
 }
 async function judgeAction(action, context, auth, opts) {
+  const toolCallId = await logToolCall(
+    action,
+    context,
+    auth,
+    opts?.chainOpts,
+    { toolName: opts?.toolName, toolArgsJson: opts?.toolArgsJson }
+  );
   const url = `${baseUrl(opts)}/api/v1/judge`;
   const data = await postJson(
     url,
     {
-      provider: opts?.provider || "",
+      tool_call_id: toolCallId,
+      agent_pubkey: auth.pubkey,
       action,
       context: context || "",
-      agent_pubkey: auth.pubkey,
-      agent_privkey: auth.privkey,
+      provider: opts?.provider || "",
       tool_name: opts?.toolName || "",
-      tool_args_json: opts?.toolArgsJson || "",
       api_key: opts?.apiKey || "",
       endpoint_url: opts?.providerEndpoint || "",
       model: opts?.model || ""
@@ -122,7 +170,7 @@ async function judgeAction(action, context, auth, opts) {
     confidence: Number(data.confidence ?? 0),
     provider: String(data.provider || ""),
     latency_ms: Number(data.latency_ms ?? 0),
-    tool_call_id: String(data.tool_call_id || ""),
+    tool_call_id: String(data.tool_call_id || toolCallId),
     on_chain: Boolean(data.on_chain)
   };
 }
@@ -242,6 +290,8 @@ async function getSafetyStats(opts) {
   return result?.data || result;
 }
 export {
+  DEFAULT_BLOCKCHAIN_RID,
+  DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT,
   createAgent,
   derivePublicKey,
@@ -260,5 +310,6 @@ export {
   getToolCalls,
   isValidPrivateKey,
   judgeAction,
+  logToolCall,
   toPubkeyHex
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atbash/sdk",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "TypeScript SDK for the Atbash risk-engine / judge API",
   "homepage": "https://atbash.ai",
   "author": "Atbash",
@@ -38,5 +38,8 @@
     "risk-engine",
     "agent-safety",
     "ai-safety"
-  ]
+  ],
+  "dependencies": {
+    "postchain-client": "^2.1.5"
+  }
 }