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

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.