Package Exports

@atbash-plugin/sdk
@atbash-plugin/sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@atbash-plugin/sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@atbash-plugin/sdk

Framework-agnostic TypeScript SDK that gates AI-agent tool calls against the ATBASH policy API. Use it from any Node.js host — LangChain, Vercel AI SDK, MCP, custom agents, scripts, Lambdas — to get a yes/no decision per tool call.

The SDK is the entire ATBASH audit pipeline as a library: load key, sign log_tool_call + judge_action locally with your agent's secp256k1 private key, POST the signed bytes to the judge (the server forwards them to Chromia), verify the response signature, return a verdict.

The agent's private key never leaves the machine. Only the signed transaction bytes plus your public key are transmitted.

Install

npm install @atbash-plugin/sdk

Requires Node.js 18+ (uses the global fetch). Pulls in one runtime dependency: postchain-client.

Quickstart

import { createAtbashClient } from "@atbash-plugin/sdk";

const client = createAtbashClient();

const decision = await client.auditToolCall({
  toolName: "shell.exec",
  args: { cmd: "rm -rf /tmp/staging" },
  context: "deployment cleanup",
});

if (!decision.allow) {
  console.error(`atbash blocked: ${decision.reason}`);
  return;
}

runTheTool();

createAtbashClient() reads your agent key from ~/.config/atbash/guard-client-key by default. Get one from the ATBASH dashboard or contact the team.

Decision shape

type Decision = {
  allow: boolean;
  verdict: "ALLOW" | "HOLD" | "BLOCK" | "ERROR";
  reason?: string;
  toolCallId?: string;
};

Verdict	`allow`	What it means
`ALLOW`	`true`	Judge approved.
`HOLD`	`true`	Judge wants user confirmation. The SDK still permits — your UI should ask.
`BLOCK`	`false`	Judge denied. Do not run the tool.
`ERROR`	`false` (when `failClosed`)	Audit failed (network, key, signature). Fails closed by default.

Configuration

type AtbashClientConfig = {
  judge?:
    | { policy?: "default"; endpoint?: string }
    | { policy: "self-hosted"; endpoint: string; verifyPubKey: string };
  nodeUrls?: string[];
  blockchainRid?: string;
  keyPath?: string;
  keyPair?: { privKey: string; pubKey: string };
  failClosed?: boolean;
  logger?: { info?: Function; warn?: Function };
};

Default judge

If you pass nothing, the SDK uses https://atbash.ai/api/v1/judge. The hostname allowlist is sealed: only atbash.ai and www.atbash.ai are accepted under the default policy. Any other endpoint throws at construction time (F-003).

Self-hosted judge

If you run your own copy of chromia-verified-ai, opt in explicitly:

createAtbashClient({
  judge: {
    policy: "self-hosted",
    endpoint: "https://my-judge.example.com/api/v1/judge",
    verifyPubKey: "03aabb...your-66-hex-pubkey",
  },
});

Both fields are required. The SDK rejects every response that isn't signed with the matching key — that prevents a compromised judge from returning {"verdict":"ALLOW"} for everything.

In-memory key

createAtbashClient({
  keyPair: {
    privKey: process.env.ATBASH_PRIVKEY!,
    pubKey:  process.env.ATBASH_PUBKEY!,
  },
});

Useful for serverless or container deployments where mounting a file is awkward.

Fail-closed behaviour

By default, every error in the audit pipeline returns { allow: false, verdict: "ERROR", reason }:

Failure	`reason` excerpt
Key file missing or unreadable	`key load failed, blocking for safety`
Local meta-tx signing failure	`meta-tx signing failed, blocking for safety`
Judge HTTP non-2xx	`judge API error (NNN), blocking for safety`
Judge unreachable	`judge API unreachable (...), blocking for safety`
Self-hosted: missing/bad signature	`self-hosted judge response signature invalid (...)`
Judge returned non-JSON	`judge API returned non-JSON, blocking for safety`

Set failClosed: false to convert errors into { allow: true } instead. Real BLOCK verdicts still block — failClosed only affects error paths.

Configuration mistakes (invalid endpoint URL, hostname not on allowlist, self-hosted without a verifyPubKey) throw at createAtbashClient time. Wrap construction in try/catch if you want to surface them.