@atbash/sdk

TypeScript SDK for Atbash — the safety layer that evaluates AI agent actions against operator-defined policies before execution.

Installation

npm install @atbash/sdk

Requires Node.js 18+. Server-side only — private keys are used for local signing and must never be exposed to browsers.

Quickstart

import { Atbash } from "@atbash/sdk";

// 1. Construct with your agent's private key.
//    The SDK validates the key and derives the matching public key.
const atbash = new Atbash(process.env.ATBASH_AGENT_KEY!, {
  orgName: "my_org",
});

// 2. Submit an action for judgment, before executing it.
//    The SDK signs the transaction locally and sends it to the judge API.
//    The private key stays on your machine — never sent over HTTP.
const result = await atbash.judgeAction(
  "Transfer $50,000 to external wallet 0xabc",
  "Outbound AML check — new recipient, over threshold",
);

// 3. Enforce the verdict
switch (result.verdict) {
  case "ALLOW":
    // Proceed with the action
    break;
  case "HOLD":
    // Held — operator must approve in the dashboard
    console.log("Held for review:", result.toolCallId);
    break;
  case "BLOCK":
    // Refused — agent is jailed in Enforcement tier
    throw new Error(`Blocked: ${result.reason}`);
}

Before this works, the agent must be onboarded at atbash.ai — assigned to an org, with a policy pack attached, and the org on an active subscription plan.

How it works

judgeAction() performs a two-step flow:

1. Sign locally — signs the request using the agent's private key. The key never leaves your machine.
2. Request verdict — sends the signed request and agent pubkey to the Atbash judge API. The server broadcasts it to the Chromia blockchain and returns a verdict.

Don't have an agent yet?

Two ways to create an agent:

1. Dashboard (recommended) — create an agent at atbash.ai/risk-engine/agents. The dashboard generates the keypair, assigns the agent to your org, and lets you attach a policy pack — all in one step.

2. Programmatic — generate a keypair locally, then onboard it via the dashboard:

   import { generateKeypair } from "@atbash/sdk";
   const { privKey, pubKey } = generateKeypair();
   console.log("Save this private key somewhere safe:", privKey);

   Paste the public key into the Onboard agent form on the dashboard, assign it to an org, and attach a policy pack before calling judgeAction.

Secret storage

• Load the private key from an environment variable (ATBASH_AGENT_KEY) or a secret manager — never hardcode it.
• Never commit .env files containing the key.
• If a key leaks, stop using it and create a new agent in the dashboard.

Verdicts

Every judgeAction call returns one of three verdicts:

| Verdict | Meaning | What your code should do | |---|---|---| | ALLOW | Action is within policy | Proceed with execution | | HOLD | Requires operator review | Pause — poll getJudgmentStatus until resolved | | BLOCK | Violates a red line | Abort — agent is jailed in Enforcement tier |

NB: If your org has no active subscription, the judge returns "No verdict" — actions are logged on-chain for the audit trail but not evaluated by an AI provider. Assign a plan at atbash.ai/risk-engine/settings for active verdicts.

API

The Atbash class is the main entry point. Construct it once with your agent's private key and (optionally) a default orgName, then call methods on it.

Operations

| Method | Use case | |---|---| | judgeAction(action, context, opts?) | Sign locally + request a verdict from the judge API |

Queries

Read-only methods that read from the Chromia blockchain and dashboard.

| Method | Use case | |---|---| | checkAgentExists(pubkey?) | Check if an agent is onboarded before signing | | getJudgmentStatus(judgmentId, pubkey) | Poll whether a held action has been approved or rejected | | getToolCalls(maxCount) | List recent tool calls across all agents | | getOrgToolCalls(orgName, maxCount) | List tool calls for a specific org | | getAgentToolCalls(pubkey, maxCount) | List tool calls for a specific agent | | getToolCallCount() | Total number of tool calls on-chain | | getToolCallFull(toolCallId) | Full details of a single tool call | | getOrgTierInfo(orgName) | Check an org's tier and whether verdicts are enabled | | getAgentDetail(pubkey) | Get agent metadata (org, status, creation date) | | getAgentPolicy(pubkey) | Check the agent's policy pack and jail status | | getPendingHeldActions(orgName, maxCount) | List actions waiting for operator approval | | getHeldActionReviews(orgName, maxCount) | List completed operator reviews | | getSafetyStats() | Chain-wide safety statistics |

Agent identity

Standalone helpers for keypair handling.

| Function | Use case | |---|---| | generateKeypair() | Generate a fresh secp256k1 keypair | | derivePublicKey(privkey) | Derive the public key from a private key | | isValidPrivateKey(hex) | Validate a private-key string | | loadAgent(privkey) | Validate the key + return { pubkey, privkey } |

Configuration

Configuration is resolved with priority: constructor arg > env var > config file (~/.config/atbash/config.json).

import { Atbash } from "@atbash/sdk";
const atbash = Atbash.fromConfig();   // reads env + config file

| Config key | Env var | |---|---| | agentKey | ATBASH_AGENT_KEY | | orgName | ATBASH_ORG_NAME | | judgeEndpoint | ATBASH_ENDPOINT | | blockchainRid | ATBASH_BLOCKCHAIN_RID | | provider | ATBASH_PROVIDER | | providerModel | ATBASH_PROVIDER_MODEL |

Persistent config helpers: saveUserConfig(config), loadUserConfig(), resolve(key, flagValue?), getConfigPath().

Error handling

The SDK throws standard Error objects. Known failure modes are enriched with a pointer to the dashboard page that fixes them:

API error 404: {"error":"Agent not registered..."}
  → Onboard the agent at https://atbash.ai/risk-engine/agents

| Error | Cause | Where to fix | |---|---|---| | API error 404: Agent not registered | Agent not onboarded | atbash.ai/risk-engine/agents | | API error 400: Agent has no policy | No policy attached to agent | atbash.ai/risk-engine/agents | | Agent is jailed | BLOCK verdict triggered auto-jail | atbash.ai/risk-engine/agents | | Verdicts are disabled | Org has no active subscription | atbash.ai/risk-engine/settings | | API error 400: action is required | Empty action string | Fix caller |

try {
  const result = await atbash.judgeAction(action, context);
} catch (err) {
  if (err.message.includes("Agent not registered")) {
    // Point the user at https://atbash.ai/risk-engine/agents to onboard.
  }
}

Dashboard

Policy authoring, operator reviews, and agent management happen at atbash.ai. The SDK is the programmatic interface; the dashboard is the operator interface.

License

Proprietary — all rights reserved. See LICENSE.