@atbash/sdk 0.1.2

package/LICENSE

@@ -0,0 +1,28 @@
+Atbash CLI — Proprietary Software License
+
+Copyright (c) 2026 Atbash,
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies,
+either expressed or implied, Atbash.

package/README.md

@@ -0,0 +1,296 @@
+# @atbash/sdk
+
+TypeScript SDK for the Atbash judge and risk-engine APIs. Evaluate agent actions against operator-defined policy before execution — programmatically, from any Node.js backend.
+
+## Installation
+
+```bash
+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.
+
+## Quickstart
+
+```ts
+import { createAgent, judgeAction } from "@atbash/sdk";
+
+// 1. Load your agent identity — paste the private key from the Atbash
+//    dashboard (https://atbash.ai/risk-engine/agents). createAgent()
+//    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
+const result = await judgeAction(
+  "Transfer $50,000 to external wallet 0xabc",
+  "Outbound AML check — new recipient, over threshold",
+  agent,
+);
+
+// 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.tool_call_id);
+    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](https://atbash.ai/) — assigned to an org, with a policy pack attached, and the org tier set to Audit+ or Enforcement.
+
+### Don't have an agent yet?
+
+Generate one programmatically for local development:
+
+```ts
+import { generateKeyPair, createAgent } from "@atbash/sdk";
+
+const { privKey } = generateKeyPair();
+console.log("Save this private key somewhere safe:", privKey);
+const agent = createAgent(privKey);
+```
+
+For production, always create agents in the dashboard so operators can attach policy packs and manage tier / jail state.
+
+### Secret storage
+
+The private key authenticates every call. 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`.
+- If a key leaks, revoke the agent and create a new one in the [Atbash dashboard](https://atbash.ai/risk-engine/agents).
+- The SDK is **server-side only** — the key must never ship to a browser bundle.
+
+## 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 |
+
+## API
+
+### Judge
+
+```ts
+judgeAction(
+  action: string,
+  context: string,
+  auth: AgentAuth,
+  opts?: JudgeOptions,
+): Promise<JudgeResult>
+```
+
+Submit an action for judgment before execution. 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
+}
+
+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
+  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
+}
+
+interface JudgeResult {
+  verdict: string;       // "ALLOW", "HOLD", or "BLOCK"
+  action_type: string;   // "allow", "hold_for_user_confirm", or "block"
+  reason: string;        // Human-readable explanation
+  confidence: number;    // 0–1
+  provider: string;      // Which provider evaluated the action
+  latency_ms: number;    // Inference time
+  tool_call_id: string;  // Unique ID for this judgment
+  on_chain: boolean;     // Whether the record was written on-chain
+}
+```
+
+### Poll judgment status
+
+```ts
+getJudgmentStatus(judgmentId: string, opts?: ClientOpts): Promise<JudgmentStatus>
+```
+
+Check whether a held action has been approved or rejected by an operator.
+
+```ts
+interface JudgmentStatus {
+  status: "pending" | "answered" | "error";
+  verdict: string;
+  reason: string;
+  judgmentId: string;
+  onChain?: boolean;
+  cached?: boolean;
+  responseTimeMs?: number;
+}
+```
+
+### Agent identity
+
+```ts
+createAgent(privkey: string): AgentAuth
+generateKeyPair(): { privKey: string; pubKey: string }
+derivePublicKey(privKeyHex: string): string
+isValidPrivateKey(hex: string): boolean
+toPubkeyHex(val: unknown): string
+```
+
+`createAgent(privkey)` is the canonical loader — pass in the private key from the dashboard, get back `{ pubkey, privkey }` ready for `judgeAction`. It accepts `0x`-prefixed, padded, or mixed-case input and throws on malformed keys. Use `generateKeyPair()` only for local development; for production, create agents in the dashboard so operators can attach policies.
+
+### Query APIs
+
+Read from the Atbash audit trail and operator queues:
+
+```ts
+// Tool call history
+getToolCalls(maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>
+getOrgToolCalls(orgName: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>
+getAgentToolCalls(agentPubkey: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>
+getToolCallCount(opts?: ClientOpts): Promise<number>
+getToolCallFull(toolCallId: string, opts?: ClientOpts): Promise<ToolCallFull | null>
+
+// 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 }>
+
+// Operator review queue
+getPendingHeldActions(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldAction[]>
+getHeldActionReviews(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldActionReview[]>
+
+// Chain-wide stats
+getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>
+```
+
+All query functions accept an optional `ClientOpts` to override the endpoint:
+
+```ts
+interface ClientOpts {
+  endpoint?: string;  // Default: https://atbash.ai
+  timeout?: number;
+}
+```
+
+## Configuration
+
+The SDK reads no environment variables and has no global state. Pass configuration explicitly:
+
+```ts
+// Custom endpoint
+const result = await judgeAction(action, context, auth, {
+  endpoint: "https://your-instance.example.com",
+});
+
+// Custom provider
+const result = await judgeAction(action, context, auth, {
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY,
+  model: "gpt-4o",
+});
+```
+
+## Integration patterns
+
+### Pre-execution gate
+
+```ts
+async function safeExecute(action: string, context: string, execute: () => Promise<void>) {
+  const result = await judgeAction(action, context, auth);
+  if (result.verdict === "BLOCK") throw new Error(`Blocked: ${result.reason}`);
+  if (result.verdict === "HOLD") throw new Error(`Held for review: ${result.tool_call_id}`);
+  await execute();
+}
+```
+
+### Polling a held action
+
+```ts
+async function waitForApproval(toolCallId: string): Promise<string> {
+  while (true) {
+    const status = await getJudgmentStatus(toolCallId);
+    if (status.status === "answered") return status.verdict;
+    if (status.status === "error") throw new Error(status.reason);
+    await new Promise((r) => setTimeout(r, 5000));
+  }
+}
+```
+
+### Checking agent jail status before a batch
+
+```ts
+const policy = await getAgentPolicy(pubKey);
+if (policy.is_jailed) {
+  console.error("Agent is jailed — unjail via dashboard before retrying.");
+  process.exit(1);
+}
+```
+
+## Error handling
+
+The SDK throws standard `Error` objects. Known failure modes are enriched with a pointer to the relevant dashboard page, so the error message tells you where to fix the problem:
+
+```
+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](https://atbash.ai/risk-engine/agents) |
+| `API error 400: Agent has no policy` | No policy attached to agent | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
+| `Agent is jailed` | BLOCK verdict triggered auto-jail (Enforcement tier) | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
+| `Org tier does not support verdicts` | Org is on Audit tier | [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) |
+| `API error 400: action is required` | Empty action string | Fix caller |
+| `API error 502: Incorrect API key` | Invalid provider API key | Check `apiKey` in `JudgeOptions` |
+
+```ts
+try {
+  const result = await judgeAction(action, context, auth);
+} catch (err) {
+  if (err.message.includes("Agent not registered")) {
+    // Point the user at https://atbash.ai/risk-engine/agents to onboard.
+  }
+}
+```
+
+## SDK vs CLI
+
+| | `@atbash/sdk` | `@atbash/cli` |
+|---|---|---|
+| Use case | Backend services, agents, pipelines | Terminal, operator review, interactive use |
+| Programmatic control | Full | Shell commands |
+| Install | `npm install @atbash/sdk` | `npm install -g @atbash/cli` |
+| Policy authoring | No (dashboard only) | No (dashboard only) |
+
+The CLI is built on top of the SDK. Both talk to the same APIs, the same policy engine, and the same on-chain audit trail.
+
+## Design
+
+- **Zero runtime dependencies** — uses only `node:crypto` and global `fetch`
+- **TypeScript-first** — full type definitions for all inputs and outputs
+- **No global state** — every function takes explicit arguments
+- **No browser support** — private keys in request bodies are not safe for client-side use
+
+## Dashboard
+
+Policy authoring, operator reviews, and agent management happen at [atbash.ai](https://atbash.ai/). The SDK is the programmatic interface; the dashboard is the operator interface.
+
+## License
+
+Proprietary — all rights reserved. See [LICENSE](./LICENSE).

package/dist/index.cjs

@@ -0,0 +1,309 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
+  createAgent: () => createAgent,
+  derivePublicKey: () => derivePublicKey,
+  generateKeyPair: () => generateKeyPair,
+  getAgentDetail: () => getAgentDetail,
+  getAgentPolicy: () => getAgentPolicy,
+  getAgentToolCalls: () => getAgentToolCalls,
+  getHeldActionReviews: () => getHeldActionReviews,
+  getJudgmentStatus: () => getJudgmentStatus,
+  getOrgTierInfo: () => getOrgTierInfo,
+  getOrgToolCalls: () => getOrgToolCalls,
+  getPendingHeldActions: () => getPendingHeldActions,
+  getSafetyStats: () => getSafetyStats,
+  getToolCallCount: () => getToolCallCount,
+  getToolCallFull: () => getToolCallFull,
+  getToolCalls: () => getToolCalls,
+  isValidPrivateKey: () => isValidPrivateKey,
+  judgeAction: () => judgeAction,
+  toPubkeyHex: () => toPubkeyHex
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_crypto = require("crypto");
+var DEFAULT_ENDPOINT = "https://atbash.ai";
+function isValidPrivateKey(hex) {
+  return /^[0-9a-fA-F]{64}$/.test(hex);
+}
+function derivePublicKey(privKeyHex) {
+  const ecdh = (0, import_crypto.createECDH)("secp256k1");
+  ecdh.setPrivateKey(Buffer.from(privKeyHex, "hex"));
+  return ecdh.getPublicKey("hex", "compressed");
+}
+function generateKeyPair() {
+  const ecdh = (0, import_crypto.createECDH)("secp256k1");
+  ecdh.generateKeys();
+  return {
+    privKey: ecdh.getPrivateKey("hex"),
+    pubKey: ecdh.getPublicKey("hex", "compressed")
+  };
+}
+function createAgent(privkey) {
+  const clean = privkey.replace(/^0x/, "").trim().toLowerCase();
+  if (!isValidPrivateKey(clean)) {
+    throw new Error(
+      "Invalid private key \u2014 must be 64 hex characters (secp256k1)."
+    );
+  }
+  return { privkey: clean, pubkey: derivePublicKey(clean) };
+}
+function hasDataArray(val) {
+  return typeof val === "object" && val !== null && "data" in val && Array.isArray(val.data);
+}
+function toPubkeyHex(val) {
+  if (!val) return "";
+  if (typeof val === "string") return val;
+  if (Buffer.isBuffer(val)) return val.toString("hex");
+  if (hasDataArray(val)) return Buffer.from(val.data).toString("hex");
+  return "";
+}
+function baseUrl(opts) {
+  return opts?.endpoint || DEFAULT_ENDPOINT;
+}
+function normalizeVerdict(raw) {
+  const v = String(raw || "").toUpperCase();
+  if (v === "ALLOW" || v === "GREEN") return "ALLOW";
+  if (v === "HOLD" || v === "YELLOW") return "HOLD";
+  if (v === "BLOCK" || v === "RED") return "BLOCK";
+  return "BLOCK";
+}
+function normalizeStatus(raw) {
+  const s = String(raw || "").toLowerCase();
+  if (s === "pending" || s === "answered" || s === "error") return s;
+  return "error";
+}
+function enrichError(status, body, statusText, opts) {
+  const dashboard = (opts?.endpoint || DEFAULT_ENDPOINT).replace(/\/$/, "");
+  let message = `API error ${status}: ${body || statusText}`;
+  if (/Agent not registered/i.test(body)) {
+    message += `
+  \u2192 Onboard the agent at ${dashboard}/risk-engine/agents`;
+  } else if (/Agent has no policy|no policy configured/i.test(body)) {
+    message += `
+  \u2192 Attach a policy at ${dashboard}/risk-engine/agents`;
+  } else if (/Agent is jailed|agent.*jailed/i.test(body)) {
+    message += `
+  \u2192 Unjail the agent at ${dashboard}/risk-engine/agents`;
+  } else if (/audit tier|verdict.*(disabled|not supported)/i.test(body)) {
+    message += `
+  \u2192 Upgrade the org tier at ${dashboard}/risk-engine/settings`;
+  } else if (status >= 400 && status < 500) {
+    message += `
+  \u2192 Dashboard: ${dashboard}/risk-engine/feed`;
+  }
+  return new Error(message);
+}
+async function postJson(url, body, opts) {
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: opts?.timeout ? AbortSignal.timeout(opts.timeout) : void 0
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw enrichError(resp.status, text, resp.statusText, opts);
+  }
+  const ct = resp.headers.get("content-type") || "";
+  return ct.includes("application/json") ? resp.json() : {};
+}
+async function getJson(url, opts) {
+  const resp = await fetch(url, {
+    method: "GET",
+    signal: opts?.timeout ? AbortSignal.timeout(opts.timeout) : void 0
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw enrichError(resp.status, text, resp.statusText, opts);
+  }
+  return resp.json();
+}
+async function judgeAction(action, context, auth, opts) {
+  const url = `${baseUrl(opts)}/api/v1/judge`;
+  const data = await postJson(
+    url,
+    {
+      provider: opts?.provider || "",
+      action,
+      context: context || "",
+      agent_pubkey: auth.pubkey,
+      agent_privkey: auth.privkey,
+      tool_name: opts?.toolName || "",
+      tool_args_json: opts?.toolArgsJson || "",
+      api_key: opts?.apiKey || "",
+      endpoint_url: opts?.providerEndpoint || "",
+      model: opts?.model || ""
+    },
+    opts
+  );
+  return {
+    verdict: normalizeVerdict(data.verdict),
+    action_type: String(data.action_type || ""),
+    reason: String(data.reason || ""),
+    confidence: Number(data.confidence ?? 0),
+    provider: String(data.provider || ""),
+    latency_ms: Number(data.latency_ms ?? 0),
+    tool_call_id: String(data.tool_call_id || ""),
+    on_chain: Boolean(data.on_chain)
+  };
+}
+async function getJudgmentStatus(judgmentId, opts) {
+  const url = `${baseUrl(opts)}/api/v1/judge?tool_call_id=${encodeURIComponent(judgmentId)}`;
+  const data = await getJson(url, opts);
+  return {
+    status: normalizeStatus(data.status),
+    verdict: normalizeVerdict(data.verdict),
+    reason: String(data.reason || ""),
+    judgmentId: String(data.judgmentId || judgmentId),
+    onChain: Boolean(data.onChain),
+    cached: Boolean(data.cached),
+    responseTimeMs: Number(data.responseTimeMs ?? 0)
+  };
+}
+function riskEngineUrl(action, params, opts) {
+  const url = new URL(`${baseUrl(opts)}/api/risk-engine`);
+  url.searchParams.set("action", action);
+  for (const [k, v] of Object.entries(params)) {
+    if (v) url.searchParams.set(k, v);
+  }
+  return url.toString();
+}
+async function getToolCalls(maxCount, opts) {
+  return getJson(
+    riskEngineUrl("tool-calls", { limit: String(maxCount) }, opts),
+    opts
+  );
+}
+async function getOrgToolCalls(orgName, maxCount, opts) {
+  return getJson(
+    riskEngineUrl(
+      "org-tool-calls",
+      { org: orgName, limit: String(maxCount) },
+      opts
+    ),
+    opts
+  );
+}
+async function getAgentToolCalls(agentPubkey, maxCount, opts) {
+  return getJson(
+    riskEngineUrl(
+      "agent-tool-calls",
+      { agent: agentPubkey, limit: String(maxCount) },
+      opts
+    ),
+    opts
+  );
+}
+async function getToolCallCount(opts) {
+  const result = await getJson(
+    riskEngineUrl("tool-call-count", {}, opts),
+    opts
+  );
+  return typeof result === "number" ? result : Number(result ?? 0);
+}
+async function getToolCallFull(toolCallId, opts) {
+  return getJson(
+    riskEngineUrl("tool-call-full", { tool_call_id: toolCallId }, opts),
+    opts
+  );
+}
+async function getOrgTierInfo(orgName, opts) {
+  return getJson(
+    riskEngineUrl("org-tier-info", { org: orgName }, opts),
+    opts
+  );
+}
+async function getPendingHeldActions(orgName, maxCount, opts) {
+  const raw = await getJson(
+    riskEngineUrl(
+      "pending-held-actions",
+      { org: orgName, limit: String(maxCount) },
+      opts
+    ),
+    opts
+  );
+  return raw.map((h) => ({ ...h, verdict: normalizeVerdict(h.verdict) }));
+}
+async function getHeldActionReviews(orgName, maxCount, opts) {
+  return getJson(
+    riskEngineUrl(
+      "held-action-reviews",
+      { org: orgName, limit: String(maxCount) },
+      opts
+    ),
+    opts
+  );
+}
+function riskEnginePostUrl(opts) {
+  return `${baseUrl(opts)}/api/risk-engine`;
+}
+async function getAgentDetail(agentPubkey, opts) {
+  return postJson(
+    riskEnginePostUrl(opts),
+    {
+      action: "agent-detail-batch",
+      agent: agentPubkey
+    },
+    opts
+  );
+}
+async function getAgentPolicy(agentPubkey, opts) {
+  return postJson(
+    riskEnginePostUrl(opts),
+    {
+      action: "agent-policy-batch",
+      agent: agentPubkey
+    },
+    opts
+  );
+}
+async function getSafetyStats(opts) {
+  const url = `${baseUrl(opts)}/api/insurance?action=safety-stats`;
+  const result = await getJson(url, opts);
+  return result?.data || result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_ENDPOINT,
+  createAgent,
+  derivePublicKey,
+  generateKeyPair,
+  getAgentDetail,
+  getAgentPolicy,
+  getAgentToolCalls,
+  getHeldActionReviews,
+  getJudgmentStatus,
+  getOrgTierInfo,
+  getOrgToolCalls,
+  getPendingHeldActions,
+  getSafetyStats,
+  getToolCallCount,
+  getToolCallFull,
+  getToolCalls,
+  isValidPrivateKey,
+  judgeAction,
+  toPubkeyHex
+});

package/dist/index.d.cts

@@ -0,0 +1,123 @@
+declare const DEFAULT_ENDPOINT = "https://atbash.ai";
+type Verdict = "ALLOW" | "HOLD" | "BLOCK";
+type Provider = "atbash" | "openai" | "google" | "microsoft" | "custom" | (string & {});
+type Tier = "audit" | "audit_plus" | "enforcement" | (string & {});
+type ActionType = "allow" | "hold_for_user_confirm" | "block" | (string & {});
+type PubkeyValue = string | Buffer | {
+    data: number[];
+};
+type JudgmentStatusState = "pending" | "answered" | "error";
+declare function isValidPrivateKey(hex: string): boolean;
+declare function derivePublicKey(privKeyHex: string): string;
+declare function generateKeyPair(): {
+    privKey: string;
+    pubKey: string;
+};
+interface AgentAuth {
+    pubkey: string;
+    privkey: string;
+}
+declare function createAgent(privkey: string): AgentAuth;
+declare function toPubkeyHex(val: unknown): string;
+interface ClientOpts {
+    endpoint?: string;
+    timeout?: number;
+}
+interface JudgeResult {
+    verdict: Verdict;
+    action_type: ActionType;
+    reason: string;
+    confidence: number;
+    provider: Provider;
+    latency_ms: number;
+    tool_call_id: string;
+    on_chain: boolean;
+}
+interface TierInfo {
+    org_name: string;
+    tier: Tier;
+    verdict_enabled: boolean;
+    enforcement_enabled: boolean;
+}
+interface ToolCallRecord {
+    tool_call_id: string;
+    agent_pubkey: PubkeyValue;
+    tool_name: string;
+    command_text: string;
+    tool_args_json: string;
+    context_text: string;
+    org_name: string;
+    rowid: number;
+}
+interface ToolCallFull {
+    tool_call_id: string;
+    agent_pubkey: PubkeyValue;
+    tool_name: string;
+    command_text: string;
+    context_text: string;
+    tool_args_json?: string;
+    org_name: string;
+    created_at?: number;
+    action_type?: ActionType;
+    result_status?: string;
+    verdict_color?: string;
+    verdict_reason?: string;
+    verdict_source?: string;
+    verdict_response_time_ms?: number;
+}
+interface HeldAction {
+    judgment_id: string;
+    agent_pubkey: PubkeyValue;
+    action_text: string;
+    action_context: string;
+    verdict: Verdict;
+    reason: string;
+    created_at: number;
+}
+interface HeldActionReview {
+    judgment_id: string;
+    action_text: string;
+    status: string;
+    review_note: string;
+    reviewed_by: PubkeyValue | null;
+    reviewed_at: number;
+    created_at: number;
+}
+interface JudgmentStatus {
+    status: JudgmentStatusState;
+    verdict: Verdict;
+    reason: string;
+    judgmentId: string;
+    onChain?: boolean;
+    cached?: boolean;
+    responseTimeMs?: number;
+}
+interface JudgeOptions extends ClientOpts {
+    provider?: Provider;
+    apiKey?: string;
+    providerEndpoint?: string;
+    model?: string;
+    toolName?: string;
+    toolArgsJson?: string;
+}
+interface AgentPolicy {
+    policy: string;
+    is_jailed: boolean;
+    is_custom: boolean;
+    default_policy: string;
+}
+declare function judgeAction(action: string, context: string, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
+declare function getJudgmentStatus(judgmentId: string, opts?: ClientOpts): Promise<JudgmentStatus>;
+declare function getToolCalls(maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
+declare function getOrgToolCalls(orgName: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
+declare function getAgentToolCalls(agentPubkey: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
+declare function getToolCallCount(opts?: ClientOpts): Promise<number>;
+declare function getToolCallFull(toolCallId: string, opts?: ClientOpts): Promise<ToolCallFull | null>;
+declare function getOrgTierInfo(orgName: string, opts?: ClientOpts): Promise<TierInfo | null>;
+declare function getPendingHeldActions(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldAction[]>;
+declare function getHeldActionReviews(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldActionReview[]>;
+declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise<Record<string, unknown>>;
+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 };

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+declare const DEFAULT_ENDPOINT = "https://atbash.ai";
+type Verdict = "ALLOW" | "HOLD" | "BLOCK";
+type Provider = "atbash" | "openai" | "google" | "microsoft" | "custom" | (string & {});
+type Tier = "audit" | "audit_plus" | "enforcement" | (string & {});
+type ActionType = "allow" | "hold_for_user_confirm" | "block" | (string & {});
+type PubkeyValue = string | Buffer | {
+    data: number[];
+};
+type JudgmentStatusState = "pending" | "answered" | "error";
+declare function isValidPrivateKey(hex: string): boolean;
+declare function derivePublicKey(privKeyHex: string): string;
+declare function generateKeyPair(): {
+    privKey: string;
+    pubKey: string;
+};
+interface AgentAuth {
+    pubkey: string;
+    privkey: string;
+}
+declare function createAgent(privkey: string): AgentAuth;
+declare function toPubkeyHex(val: unknown): string;
+interface ClientOpts {
+    endpoint?: string;
+    timeout?: number;
+}
+interface JudgeResult {
+    verdict: Verdict;
+    action_type: ActionType;
+    reason: string;
+    confidence: number;
+    provider: Provider;
+    latency_ms: number;
+    tool_call_id: string;
+    on_chain: boolean;
+}
+interface TierInfo {
+    org_name: string;
+    tier: Tier;
+    verdict_enabled: boolean;
+    enforcement_enabled: boolean;
+}
+interface ToolCallRecord {
+    tool_call_id: string;
+    agent_pubkey: PubkeyValue;
+    tool_name: string;
+    command_text: string;
+    tool_args_json: string;
+    context_text: string;
+    org_name: string;
+    rowid: number;
+}
+interface ToolCallFull {
+    tool_call_id: string;
+    agent_pubkey: PubkeyValue;
+    tool_name: string;
+    command_text: string;
+    context_text: string;
+    tool_args_json?: string;
+    org_name: string;
+    created_at?: number;
+    action_type?: ActionType;
+    result_status?: string;
+    verdict_color?: string;
+    verdict_reason?: string;
+    verdict_source?: string;
+    verdict_response_time_ms?: number;
+}
+interface HeldAction {
+    judgment_id: string;
+    agent_pubkey: PubkeyValue;
+    action_text: string;
+    action_context: string;
+    verdict: Verdict;
+    reason: string;
+    created_at: number;
+}
+interface HeldActionReview {
+    judgment_id: string;
+    action_text: string;
+    status: string;
+    review_note: string;
+    reviewed_by: PubkeyValue | null;
+    reviewed_at: number;
+    created_at: number;
+}
+interface JudgmentStatus {
+    status: JudgmentStatusState;
+    verdict: Verdict;
+    reason: string;
+    judgmentId: string;
+    onChain?: boolean;
+    cached?: boolean;
+    responseTimeMs?: number;
+}
+interface JudgeOptions extends ClientOpts {
+    provider?: Provider;
+    apiKey?: string;
+    providerEndpoint?: string;
+    model?: string;
+    toolName?: string;
+    toolArgsJson?: string;
+}
+interface AgentPolicy {
+    policy: string;
+    is_jailed: boolean;
+    is_custom: boolean;
+    default_policy: string;
+}
+declare function judgeAction(action: string, context: string, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
+declare function getJudgmentStatus(judgmentId: string, opts?: ClientOpts): Promise<JudgmentStatus>;
+declare function getToolCalls(maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
+declare function getOrgToolCalls(orgName: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
+declare function getAgentToolCalls(agentPubkey: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
+declare function getToolCallCount(opts?: ClientOpts): Promise<number>;
+declare function getToolCallFull(toolCallId: string, opts?: ClientOpts): Promise<ToolCallFull | null>;
+declare function getOrgTierInfo(orgName: string, opts?: ClientOpts): Promise<TierInfo | null>;
+declare function getPendingHeldActions(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldAction[]>;
+declare function getHeldActionReviews(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldActionReview[]>;
+declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise<Record<string, unknown>>;
+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 };

package/dist/index.js

@@ -0,0 +1,264 @@
+// src/client.ts
+import { createECDH } from "crypto";
+var DEFAULT_ENDPOINT = "https://atbash.ai";
+function isValidPrivateKey(hex) {
+  return /^[0-9a-fA-F]{64}$/.test(hex);
+}
+function derivePublicKey(privKeyHex) {
+  const ecdh = createECDH("secp256k1");
+  ecdh.setPrivateKey(Buffer.from(privKeyHex, "hex"));
+  return ecdh.getPublicKey("hex", "compressed");
+}
+function generateKeyPair() {
+  const ecdh = createECDH("secp256k1");
+  ecdh.generateKeys();
+  return {
+    privKey: ecdh.getPrivateKey("hex"),
+    pubKey: ecdh.getPublicKey("hex", "compressed")
+  };
+}
+function createAgent(privkey) {
+  const clean = privkey.replace(/^0x/, "").trim().toLowerCase();
+  if (!isValidPrivateKey(clean)) {
+    throw new Error(
+      "Invalid private key \u2014 must be 64 hex characters (secp256k1)."
+    );
+  }
+  return { privkey: clean, pubkey: derivePublicKey(clean) };
+}
+function hasDataArray(val) {
+  return typeof val === "object" && val !== null && "data" in val && Array.isArray(val.data);
+}
+function toPubkeyHex(val) {
+  if (!val) return "";
+  if (typeof val === "string") return val;
+  if (Buffer.isBuffer(val)) return val.toString("hex");
+  if (hasDataArray(val)) return Buffer.from(val.data).toString("hex");
+  return "";
+}
+function baseUrl(opts) {
+  return opts?.endpoint || DEFAULT_ENDPOINT;
+}
+function normalizeVerdict(raw) {
+  const v = String(raw || "").toUpperCase();
+  if (v === "ALLOW" || v === "GREEN") return "ALLOW";
+  if (v === "HOLD" || v === "YELLOW") return "HOLD";
+  if (v === "BLOCK" || v === "RED") return "BLOCK";
+  return "BLOCK";
+}
+function normalizeStatus(raw) {
+  const s = String(raw || "").toLowerCase();
+  if (s === "pending" || s === "answered" || s === "error") return s;
+  return "error";
+}
+function enrichError(status, body, statusText, opts) {
+  const dashboard = (opts?.endpoint || DEFAULT_ENDPOINT).replace(/\/$/, "");
+  let message = `API error ${status}: ${body || statusText}`;
+  if (/Agent not registered/i.test(body)) {
+    message += `
+  \u2192 Onboard the agent at ${dashboard}/risk-engine/agents`;
+  } else if (/Agent has no policy|no policy configured/i.test(body)) {
+    message += `
+  \u2192 Attach a policy at ${dashboard}/risk-engine/agents`;
+  } else if (/Agent is jailed|agent.*jailed/i.test(body)) {
+    message += `
+  \u2192 Unjail the agent at ${dashboard}/risk-engine/agents`;
+  } else if (/audit tier|verdict.*(disabled|not supported)/i.test(body)) {
+    message += `
+  \u2192 Upgrade the org tier at ${dashboard}/risk-engine/settings`;
+  } else if (status >= 400 && status < 500) {
+    message += `
+  \u2192 Dashboard: ${dashboard}/risk-engine/feed`;
+  }
+  return new Error(message);
+}
+async function postJson(url, body, opts) {
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: opts?.timeout ? AbortSignal.timeout(opts.timeout) : void 0
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw enrichError(resp.status, text, resp.statusText, opts);
+  }
+  const ct = resp.headers.get("content-type") || "";
+  return ct.includes("application/json") ? resp.json() : {};
+}
+async function getJson(url, opts) {
+  const resp = await fetch(url, {
+    method: "GET",
+    signal: opts?.timeout ? AbortSignal.timeout(opts.timeout) : void 0
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw enrichError(resp.status, text, resp.statusText, opts);
+  }
+  return resp.json();
+}
+async function judgeAction(action, context, auth, opts) {
+  const url = `${baseUrl(opts)}/api/v1/judge`;
+  const data = await postJson(
+    url,
+    {
+      provider: opts?.provider || "",
+      action,
+      context: context || "",
+      agent_pubkey: auth.pubkey,
+      agent_privkey: auth.privkey,
+      tool_name: opts?.toolName || "",
+      tool_args_json: opts?.toolArgsJson || "",
+      api_key: opts?.apiKey || "",
+      endpoint_url: opts?.providerEndpoint || "",
+      model: opts?.model || ""
+    },
+    opts
+  );
+  return {
+    verdict: normalizeVerdict(data.verdict),
+    action_type: String(data.action_type || ""),
+    reason: String(data.reason || ""),
+    confidence: Number(data.confidence ?? 0),
+    provider: String(data.provider || ""),
+    latency_ms: Number(data.latency_ms ?? 0),
+    tool_call_id: String(data.tool_call_id || ""),
+    on_chain: Boolean(data.on_chain)
+  };
+}
+async function getJudgmentStatus(judgmentId, opts) {
+  const url = `${baseUrl(opts)}/api/v1/judge?tool_call_id=${encodeURIComponent(judgmentId)}`;
+  const data = await getJson(url, opts);
+  return {
+    status: normalizeStatus(data.status),
+    verdict: normalizeVerdict(data.verdict),
+    reason: String(data.reason || ""),
+    judgmentId: String(data.judgmentId || judgmentId),
+    onChain: Boolean(data.onChain),
+    cached: Boolean(data.cached),
+    responseTimeMs: Number(data.responseTimeMs ?? 0)
+  };
+}
+function riskEngineUrl(action, params, opts) {
+  const url = new URL(`${baseUrl(opts)}/api/risk-engine`);
+  url.searchParams.set("action", action);
+  for (const [k, v] of Object.entries(params)) {
+    if (v) url.searchParams.set(k, v);
+  }
+  return url.toString();
+}
+async function getToolCalls(maxCount, opts) {
+  return getJson(
+    riskEngineUrl("tool-calls", { limit: String(maxCount) }, opts),
+    opts
+  );
+}
+async function getOrgToolCalls(orgName, maxCount, opts) {
+  return getJson(
+    riskEngineUrl(
+      "org-tool-calls",
+      { org: orgName, limit: String(maxCount) },
+      opts
+    ),
+    opts
+  );
+}
+async function getAgentToolCalls(agentPubkey, maxCount, opts) {
+  return getJson(
+    riskEngineUrl(
+      "agent-tool-calls",
+      { agent: agentPubkey, limit: String(maxCount) },
+      opts
+    ),
+    opts
+  );
+}
+async function getToolCallCount(opts) {
+  const result = await getJson(
+    riskEngineUrl("tool-call-count", {}, opts),
+    opts
+  );
+  return typeof result === "number" ? result : Number(result ?? 0);
+}
+async function getToolCallFull(toolCallId, opts) {
+  return getJson(
+    riskEngineUrl("tool-call-full", { tool_call_id: toolCallId }, opts),
+    opts
+  );
+}
+async function getOrgTierInfo(orgName, opts) {
+  return getJson(
+    riskEngineUrl("org-tier-info", { org: orgName }, opts),
+    opts
+  );
+}
+async function getPendingHeldActions(orgName, maxCount, opts) {
+  const raw = await getJson(
+    riskEngineUrl(
+      "pending-held-actions",
+      { org: orgName, limit: String(maxCount) },
+      opts
+    ),
+    opts
+  );
+  return raw.map((h) => ({ ...h, verdict: normalizeVerdict(h.verdict) }));
+}
+async function getHeldActionReviews(orgName, maxCount, opts) {
+  return getJson(
+    riskEngineUrl(
+      "held-action-reviews",
+      { org: orgName, limit: String(maxCount) },
+      opts
+    ),
+    opts
+  );
+}
+function riskEnginePostUrl(opts) {
+  return `${baseUrl(opts)}/api/risk-engine`;
+}
+async function getAgentDetail(agentPubkey, opts) {
+  return postJson(
+    riskEnginePostUrl(opts),
+    {
+      action: "agent-detail-batch",
+      agent: agentPubkey
+    },
+    opts
+  );
+}
+async function getAgentPolicy(agentPubkey, opts) {
+  return postJson(
+    riskEnginePostUrl(opts),
+    {
+      action: "agent-policy-batch",
+      agent: agentPubkey
+    },
+    opts
+  );
+}
+async function getSafetyStats(opts) {
+  const url = `${baseUrl(opts)}/api/insurance?action=safety-stats`;
+  const result = await getJson(url, opts);
+  return result?.data || result;
+}
+export {
+  DEFAULT_ENDPOINT,
+  createAgent,
+  derivePublicKey,
+  generateKeyPair,
+  getAgentDetail,
+  getAgentPolicy,
+  getAgentToolCalls,
+  getHeldActionReviews,
+  getJudgmentStatus,
+  getOrgTierInfo,
+  getOrgToolCalls,
+  getPendingHeldActions,
+  getSafetyStats,
+  getToolCallCount,
+  getToolCallFull,
+  getToolCalls,
+  isValidPrivateKey,
+  judgeAction,
+  toPubkeyHex
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@atbash/sdk",
+  "version": "0.1.2",
+  "description": "TypeScript SDK for the Atbash risk-engine / judge API",
+  "homepage": "https://atbash.ai",
+  "author": "Atbash",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build",
+    "release": "npm version patch --no-git-tag-version && npm run build && npx npm@10 publish --access public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.39",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "atbash",
+    "risk-engine",
+    "agent-safety",
+    "ai-safety"
+  ]
+}