@atbash-plugin/sdk

TypeScript SDK that gates AI-agent tool calls against the ATBASH policy service. 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 agent's private key never leaves the machine. Only signed transaction bytes plus the corresponding public key are transmitted.

Install

npm install @atbash-plugin/sdk

Requires Node.js 18+.

Quickstart

A complete, runnable example. Save as quickstart.mjs and run with node quickstart.mjs:

import { createAtbashClient } from "@atbash-plugin/sdk";
import { execSync } from "node:child_process";

const client = createAtbashClient();

const toolName = "shell.exec";
const args = { cmd: "ls /tmp" };

const decision = await client.auditToolCall({
  toolName,
  args,
  context: "quickstart smoke test",
});

console.log(`Verdict: ${decision.verdict}  (allow=${decision.allow})`);
console.log(`Reason:  ${decision.reason ?? "—"}`);

if (!decision.allow) {
  process.exit(1);
}

const output = execSync(args.cmd, { encoding: "utf8" });
console.log("---");
console.log(output);

Expected output on an ALLOW:

Verdict: ALLOW  (allow=true)
Reason:  ALLOW: ...
---
file1
file2
...

createAtbashClient() reads your agent key from ~/.config/atbash/guard-client-key by default. Contact the ATBASH team to register an agent and obtain a key pair.

Get an agent key

Place the agent key pair at ~/.config/atbash/guard-client-key (the default path). The file accepts either JSON:

{
  "privKey": "your-hex-private-key-64-chars",
  "pubKey":  "your-hex-public-key-66-chars"
}

…or key=value:

privkey=your-hex-private-key-64-chars
pubkey=your-hex-public-key-66-chars

Lengths must be exact: privKey is 64 hex chars (32 bytes), pubKey is 66 hex chars (33 bytes — the compressed secp256k1 form, prefixed with 02 or 03). A short or malformed key will be rejected by the judge service with a 400.

To use a different path, pass keyPath:

createAtbashClient({ keyPath: "/etc/atbash/agent-key.json" });

For environments without a writable filesystem (Lambda, container without a mounted secret), pass the key pair inline — see In-memory key below.

Decision shape

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

| Verdict | allow | What it means | |---|---|---| | ALLOW | true | Approved. | | HOLD | true | Approved with advisory: your UI should ask for confirmation. | | BLOCK | false | Denied. Do not run the tool. | | ERROR | false (when failClosed) | Audit failed. Fails closed by default. |

Configuration

type AtbashClientConfig = {
  keyPath?: string;
  keyPair?: { privKey: string; pubKey: string };
  failClosed?: boolean;
  logger?: { info?: Function; warn?: Function };
};

| Field | Default | Notes | |---|---|---| | keyPath | ~/.config/atbash/guard-client-key | Path to the agent key file. Supports ~/. | | keyPair | — | Provide the key pair inline instead of reading from disk. Useful for serverless / containerised deployments. | | failClosed | true | When true, errors return { allow: false }. When false, errors return { allow: true }. Real BLOCK verdicts always block — failClosed only affects error paths. | | logger | — | Optional { info, warn } sink for telemetry. |

In-memory key

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

Fail-closed behaviour

By default, every error in the audit pipeline returns { allow: false, verdict: "ERROR", reason } so the caller can skip the tool safely. Configuration mistakes throw at createAtbashClient time — wrap construction in try/catch if you want to surface them programmatically.

License

Proprietary — all rights reserved. See LICENSE. Commercial licensing inquiries: contact the Atbash team.