@atbash/sdk 0.3.6 → 0.3.8

package/README.md

@@ -21,8 +21,8 @@ import { loadAgent, judgeAction } from "@atbash/sdk";
 const agent = loadAgent(process.env.ATBASH_AGENT_PRIVKEY!);
 
 // 2. Submit an action for judgment, before executing it.
-//    The SDK signs and broadcasts log_tool_call to the Chromia chain
-//    (private key stays local), then requests a verdict from the judge API.
+//    The SDK signs the transaction locally and sends it to the judge API.
+//    Private key stays on your machine — never sent over HTTP.
 const result = await judgeAction(
   "Transfer $50,000 to external wallet 0xabc",
   "Outbound AML check — new recipient, over threshold",
@@ -50,10 +50,9 @@ Before this works, the agent must be onboarded at [atbash.ai](https://atbash.ai/
 
 `judgeAction()` performs a two-step flow:
 
-1. **Sign on-chain** — signs and broadcasts a `log_tool_call` transaction to the Chromia blockchain using the agent's private key. The key never leaves your machine.
-2. **Request verdict** — sends the resulting `tool_call_id` and `agent_pubkey` to the Atbash judge API. No private key is transmitted over HTTP.
+1. **Sign locally** — signs the transaction using the agent's private key. The key never leaves your machine.
+2. **Request verdict** — sends the signed transaction, `tool_call_id`, and `agent_pubkey` to the Atbash judge API. The server broadcasts it to the Chromia blockchain and returns a verdict.
 
-If you need finer control, you can call `logToolCall()` and the judge API separately.
 
 ### Don't have an agent yet?
 
@@ -75,12 +74,9 @@ const agent = loadAgent(privKey);
 
 ### Secret storage
 
-The private key is used to sign on-chain transactions locally. 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.
+- 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](https://atbash.ai/risk-engine/agents).
 
 ## Verdicts
 
@@ -107,7 +103,7 @@ judgeAction(
 ): Promise<JudgeResult>
 ```
 
-Submit an action for judgment before execution. Signs `log_tool_call` on-chain, then requests a verdict. Returns the verdict, reason, confidence, provider, latency, and tool call ID.
+Submit an action for judgment before execution. Signs the transaction locally and sends it to the judge API for a verdict.
 
 ```ts
 interface AgentAuth {
@@ -154,12 +150,12 @@ logToolCall(
 ): Promise<LogToolCallResult>
 ```
 
-Sign `log_tool_call` on the Chromia chain. Returns `{ success, toolCallId, error? }`. Use this if you need to separate the on-chain logging step from the verdict request.
+Sign the transaction locally. Returns `{ success, toolCallId, signedHex?, error? }`. Use this if you need to separate the signing step from the verdict request.
 
 ### Poll judgment status
 
 ```ts
-getJudgmentStatus(judgmentId: string, opts?: ClientOpts): Promise<JudgmentStatus>
+getJudgmentStatus(judgmentId: string, agentPubkey: string, opts?: ClientOpts): Promise<JudgmentStatus>
 ```
 
 Check whether a held action has been approved or rejected by an operator.
@@ -194,15 +190,15 @@ Functions that sign transactions and write to the Chromia blockchain.
 
 | Function | Use case |
 |----------|----------|
-| `judgeAction(action, context, auth, opts?)` | Sign `log_tool_call` on-chain + request a verdict from the judge API |
-| `logToolCall(action, context, auth, ...)` | Sign and broadcast `log_tool_call` to chain without requesting a verdict |
+| `judgeAction(action, context, auth, opts?)` | Sign locally + request a verdict from the judge API |
+| `logToolCall(action, context, auth, ...)` | Sign the transaction locally without requesting a verdict |
 
 ### Queries
 
 | Function | Use case |
 |----------|----------|
 | `checkAgentExists(pubkey, opts?)` | Check if an agent is onboarded before signing |
-| `getJudgmentStatus(judgmentId, opts?)` | Poll whether a held action has been approved or rejected |
+| `getJudgmentStatus(judgmentId, agentPubkey, opts?)` | 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 |
@@ -217,24 +213,78 @@ Functions that sign transactions and write to the Chromia blockchain.
 
 ## Configuration
 
-The SDK reads no environment variables and has no global state. Pass configuration explicitly:
+You can pass configuration inline or use the built-in config module that reads from `~/.config/atbash/config.json`.
+
+### Inline
 
 ```ts
-// Custom endpoint
 const result = await judgeAction(action, context, auth, {
   endpoint: "https://your-instance.example.com",
+  provider: "openai",
+  model: "gpt-4o",
 });
+```
 
-// Custom provider (API keys are saved in the dashboard, not passed here)
-const result = await judgeAction(action, context, auth, {
+### Persistent config
+
+Save configuration once — the SDK resolves values with priority: **flag > env var > config file**.
+
+```ts
+import { saveUserConfig, resolve, loadAgent, judgeAction } from "@atbash/sdk";
+
+// Save once
+saveUserConfig({
+  agentKey: "9cd07a...",
+  orgName: "my_org",
   provider: "openai",
-  model: "gpt-4o",
 });
 
+// Then use resolve() anywhere
+const agent = loadAgent(resolve("agentKey"));
+const result = await judgeAction("Transfer $500", "finance", agent, {
+  provider: resolve("provider"), // omit to use the on-chain ATBASH judge
+});
 ```
 
+Config file location: `~/.config/atbash/config.json`
+
+| Function | Purpose |
+|----------|---------|
+| `saveUserConfig(config)` | Write config to disk |
+| `loadUserConfig()` | Read config from disk |
+| `resolve(key, flagValue?)` | Resolve a value: flag > env > file > `""` |
+| `getConfigPath()` | Returns the config file path |
+
+| 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` |
+
 > **Advanced:** The SDK connects to the default Atbash Chromia chain. To use a different chain, pass `chainOpts` with custom `nodeUrls` and `blockchainRid` in `JudgeOptions`.
 
+## Secret redaction
+
+Before each `auditToolCall` signs anything, the SDK scans `args` and `context` for secret-shaped values (API keys, tokens, JWTs, PEM blocks, etc.) and replaces matches with `[REDACTED:<kind>]`. Redaction happens **before signing**, so secrets never reach the signed bytes, the request body, the on-chain log, or the prompt sent to the AI provider.
+
+When the redactor fires, you'll see a warning via the configured `logger`:
+
+```
+[atbash] redacted secrets before judge call { tool: "exec", count: 2, kinds: ["anthropic", "generic_token"] }
+```
+
+Common `kinds`:
+
+- `anthropic`, `openai`, `github`, `google`, `aws_access_key`, `stripe`, `slack`, `jwt`, `private_key_pem` — high-confidence vendor patterns; if you see these, a real secret was almost certainly in your input
+- `context_secret` — a value next to a label like `api_key=`, `token:`, `password=`, etc.
+- `generic_token` — long random-looking strings (32+ alphanumeric chars). Catches unknown-vendor secrets, but can also match UUIDs, content hashes, and other opaque identifiers. The judge sees `[REDACTED:generic_token]` instead of the original; for verdict purposes the shape of the action matters more than the exact ID, so this is generally safe — but worth knowing if you see it unexpectedly.
+- `base64` — long base64-encoded values; can match legitimate image/file data
+
+Redaction is silent at the consumer level — the SDK's caller still has the original arguments. Only what's sent to the judge (and persisted on chain via the verdict log) is scrubbed.
+
 ## Integration patterns
 
 ### Pre-execution gate
@@ -253,7 +303,7 @@ async function safeExecute(action: string, context: string, execute: () => Promi
 ```ts
 async function waitForApproval(toolCallId: string): Promise<string> {
   while (true) {
-    const status = await getJudgmentStatus(toolCallId);
+    const status = await getJudgmentStatus(toolCallId, auth.pubkey);
     if (status.status === "answered") return status.verdict;
     if (status.status === "error") throw new Error(status.reason);
     await new Promise((r) => setTimeout(r, 5000));

package/dist/index.cjs

@@ -34,11 +34,14 @@ __export(index_exports, {
   DEFAULT_CHROMIA_NODE_URLS: () => DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
   checkAgentExists: () => checkAgentExists,
+  createAtbashClient: () => createAtbashClient,
   derivePublicKey: () => derivePublicKey,
   generateKeyPair: () => generateKeyPair,
   getAgentDetail: () => getAgentDetail,
   getAgentPolicy: () => getAgentPolicy,
   getAgentToolCalls: () => getAgentToolCalls,
+  getConfigDir: () => getConfigDir,
+  getConfigPath: () => getConfigPath,
   getHeldActionReviews: () => getHeldActionReviews,
   getJudgmentStatus: () => getJudgmentStatus,
   getOrgTierInfo: () => getOrgTierInfo,
@@ -51,15 +54,50 @@ __export(index_exports, {
   isValidPrivateKey: () => isValidPrivateKey,
   judgeAction: () => judgeAction,
   loadAgent: () => loadAgent,
+  loadAgentFromFile: () => loadAgentFromFile,
+  loadUserConfig: () => loadUserConfig,
   logToolCall: () => logToolCall,
-  toPubkeyHex: () => toPubkeyHex
+  resolve: () => resolve,
+  resolveKeyPath: () => resolveKeyPath,
+  saveUserConfig: () => saveUserConfig,
+  toPubkeyHex: () => toPubkeyHex,
+  validateJudgeEndpoint: () => validateJudgeEndpoint,
+  verifyJudgeResponseSignature: () => verifyJudgeResponseSignature
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
 var import_crypto = require("crypto");
+var import_postchain_client2 = __toESM(require("postchain-client"), 1);
+
+// src/signature.ts
 var import_postchain_client = __toESM(require("postchain-client"), 1);
-var { createClient, encryption, newSignatureProvider } = import_postchain_client.default;
+var { encryption } = import_postchain_client.default;
+function verifyJudgeResponseSignature(bodyBytes, signatureHex, pubKeyHex) {
+  if (!signatureHex) {
+    return { ok: false, reason: "missing X-Atbash-Signature header" };
+  }
+  const sigClean = signatureHex.trim().toLowerCase().replace(/^0x/, "");
+  if (!/^[0-9a-f]+$/.test(sigClean) || sigClean.length < 64 || sigClean.length > 256) {
+    return { ok: false, reason: "malformed signature header" };
+  }
+  let isValid = false;
+  try {
+    const digest = encryption.sha256(Buffer.from(bodyBytes));
+    const pubKeyBytes = Buffer.from(pubKeyHex.replace(/^0x/, ""), "hex");
+    const sigBytes = Buffer.from(sigClean, "hex");
+    isValid = encryption.checkDigestSignature(digest, pubKeyBytes, sigBytes);
+  } catch (err) {
+    const message = String(
+      err?.message ?? err ?? ""
+    );
+    return { ok: false, reason: `signature verification threw: ${message}` };
+  }
+  return isValid ? { ok: true } : { ok: false, reason: "signature does not verify against configured verifyPubKey" };
+}
+
+// src/client.ts
+var { createClient, encryption: encryption2, newSignatureProvider } = import_postchain_client2.default;
 var DEFAULT_ENDPOINT = "https://atbash.ai";
 var DEFAULT_CHROMIA_NODE_URLS = [
   "https://node6.testnet.chromia.com:7740",
@@ -115,7 +153,7 @@ async function buildSignedTx(opName, args, auth, chainOpts) {
   const blockchainRid = chainOpts?.blockchainRid ?? DEFAULT_BLOCKCHAIN_RID;
   const client = await createClient({ nodeUrlPool: nodeUrls, blockchainRid });
   const privKeyBuf = Buffer.from(auth.privkey, "hex");
-  const keyPair = encryption.makeKeyPair(privKeyBuf);
+  const keyPair = encryption2.makeKeyPair(privKeyBuf);
   const sigProvider = newSignatureProvider({
     privKey: keyPair.privKey,
     pubKey: keyPair.pubKey
@@ -226,6 +264,31 @@ async function getJson(url, opts) {
   }
   return resp.json();
 }
+async function postJudgeRequest(url, body, opts) {
+  if (!opts?.verifyPubKey) {
+    return 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 buf = new Uint8Array(await resp.arrayBuffer());
+  const verdict = verifyJudgeResponseSignature(
+    buf,
+    resp.headers.get("X-Atbash-Signature"),
+    opts.verifyPubKey
+  );
+  if (!verdict.ok) {
+    throw new Error(`signature verification failed: ${verdict.reason}`);
+  }
+  return JSON.parse(new TextDecoder().decode(buf));
+}
 async function judgeAction(action, context = "", auth, opts) {
   if (!action || !action.trim()) {
     throw new Error("action is required and cannot be empty.");
@@ -263,7 +326,7 @@ async function judgeAction(action, context = "", auth, opts) {
     ...opts?.toolName && { tool_name: opts.toolName },
     ...opts?.model && { model: opts.model }
   };
-  const data = await postJson(url, body, opts);
+  const data = await postJudgeRequest(url, body, opts);
   return {
     verdict: normalizeVerdict(data.verdict),
     action_type: String(data.action_type || ""),
@@ -275,8 +338,8 @@ async function judgeAction(action, context = "", auth, opts) {
     on_chain: Boolean(data.on_chain)
   };
 }
-async function getJudgmentStatus(judgmentId, opts) {
-  const url = `${baseUrl(opts)}/api/v1/judge?tool_call_id=${encodeURIComponent(judgmentId)}`;
+async function getJudgmentStatus(judgmentId, agentPubkey, opts) {
+  const url = `${baseUrl(opts)}/api/v1/judge?tool_call_id=${encodeURIComponent(judgmentId)}&agent_pubkey=${encodeURIComponent(agentPubkey)}`;
   const data = await getJson(url, opts);
   return {
     status: normalizeStatus(data.status),
@@ -390,17 +453,355 @@ async function getSafetyStats(opts) {
   const result = await getJson(url, opts);
   return result?.data || result;
 }
+
+// src/config.ts
+var ALLOWED_JUDGE_HOSTS = /* @__PURE__ */ new Set([
+  "atbash.ai",
+  "www.atbash.ai"
+]);
+function validateJudgeEndpoint(judge) {
+  const policy = judge?.policy === "self-hosted" ? "self-hosted" : "default";
+  const candidate = judge?.endpoint?.trim() || DEFAULT_ENDPOINT;
+  let parsed;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    throw new Error(
+      `[atbash] invalid judge endpoint URL: ${candidate}. Refusing to load \u2014 fix the URL or omit it to use the default (${DEFAULT_ENDPOINT}).`
+    );
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(
+      `[atbash] judge endpoint must use https:// (got "${parsed.protocol}"). Refusing to load \u2014 plaintext endpoints leak verdicts and enable trivial MITM bypass.`
+    );
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error(
+      `[atbash] judge endpoint must not contain credentials (user:pass@host). Refusing to load \u2014 credentials embedded in URLs leak to logs and process listings.`
+    );
+  }
+  const normalisedUrl = parsed.origin;
+  if (policy === "self-hosted") {
+    const verifyPubKey = judge?.verifyPubKey;
+    const key = verifyPubKey?.trim().toLowerCase();
+    if (!key || !/^[0-9a-f]{66}$/.test(key)) {
+      throw new Error(
+        `[atbash] judge endpoint policy "self-hosted" requires verifyPubKey to be a 66-hex-char compressed secp256k1 pubkey. Refusing to load \u2014 self-hosted judges must produce signed responses so the SDK can detect a malicious or compromised judge.`
+      );
+    }
+    return { url: normalisedUrl, policy, verifyPubKey: key };
+  }
+  if (!ALLOWED_JUDGE_HOSTS.has(parsed.hostname.toLowerCase())) {
+    throw new Error(
+      `[atbash] judge endpoint hostname "${parsed.hostname}" is not in the trusted allowlist. Allowed: ${[...ALLOWED_JUDGE_HOSTS].join(", ")}. To use a self-hosted judge, set BOTH policy="self-hosted" AND verifyPubKey to the 66-hex pubkey of your judge's response-signing key. Refusing to load \u2014 silent endpoint redirection is a known attack vector (F-003).`
+    );
+  }
+  return { url: normalisedUrl, policy, verifyPubKey: null };
+}
+
+// src/key-loader.ts
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var DEFAULT_KEY_PATH_REL = ".config/atbash/guard-client-key";
+function resolveKeyPath(input) {
+  if (input) return expandHome(input);
+  const home = process.env.HOME || (0, import_node_os.homedir)() || "";
+  return (0, import_node_path.join)(home, DEFAULT_KEY_PATH_REL);
+}
+function expandHome(p) {
+  if (!p.startsWith("~/")) return p;
+  const home = process.env.HOME || (0, import_node_os.homedir)() || "";
+  return (0, import_node_path.join)(home, p.slice(2));
+}
+function readKeyFile(keyPath) {
+  const content = String((0, import_node_fs.readFileSync)(keyPath, "utf8") || "").trim();
+  let privKey = "";
+  let pubKey = "";
+  if (content.startsWith("{")) {
+    const creds = JSON.parse(content);
+    privKey = String(
+      creds.privKey || creds.privkey || creds.privateKey || ""
+    ).trim();
+    pubKey = String(
+      creds.pubKey || creds.pubkey || creds.publicKey || ""
+    ).trim();
+  } else {
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+      if (line.startsWith("privkey=")) privKey = line.slice("privkey=".length).trim();
+      if (line.startsWith("pubkey=")) pubKey = line.slice("pubkey=".length).trim();
+    }
+  }
+  if (!privKey || !pubKey) {
+    throw new Error(`atbash key file missing priv/pub key fields: ${keyPath}`);
+  }
+  privKey = privKey.replace(/^0x/, "");
+  return { privKey, pubKey };
+}
+function loadAgentFromFile(keyPath) {
+  const resolved = resolveKeyPath(keyPath);
+  const { privKey } = readKeyFile(resolved);
+  return loadAgent(privKey);
+}
+
+// src/redact-secrets.ts
+var PATTERNS = [
+  { kind: "anthropic", re: /\bsk-ant-[A-Za-z0-9_-]{20,}/g },
+  { kind: "openai_project", re: /\bsk-proj-[A-Za-z0-9_-]{20,}/g },
+  { kind: "openai", re: /\bsk-[A-Za-z0-9]{20,}/g },
+  { kind: "github", re: /\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{30,}/g },
+  { kind: "google", re: /\bAIza[0-9A-Za-z_-]{35}/g },
+  { kind: "google_oauth", re: /\bya29\.[0-9A-Za-z_-]{20,}/g },
+  {
+    kind: "aws_access_key",
+    re: /\b(?:AKIA|ASIA|AGPA|AROA|ANPA|ANVA|ASCA|AIDA|AIPA)[0-9A-Z]{16}\b/g
+  },
+  { kind: "stripe", re: /\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{20,}/g },
+  { kind: "slack", re: /\bxox[abprseo]-[A-Za-z0-9-]{10,}/g },
+  {
+    kind: "slack_webhook",
+    re: /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9]+\/B[A-Za-z0-9]+\/[A-Za-z0-9]{20,}/g
+  },
+  { kind: "sendgrid", re: /\bSG\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}/g },
+  { kind: "twilio_sid", re: /\bAC[0-9a-fA-F]{32}\b/g },
+  { kind: "mailgun", re: /\bkey-[0-9a-f]{32}\b/g },
+  { kind: "npm_token", re: /\bnpm_[A-Za-z0-9]{36,}\b/g },
+  { kind: "jwt", re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g },
+  {
+    kind: "private_key_pem",
+    re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g
+  },
+  {
+    kind: "aws_secret_key",
+    re: /(?:aws[_-]?secret|secret[_-]?access[_-]?key)["'\s:=]{1,10}[A-Za-z0-9/+=]{40}/gi
+  },
+  {
+    kind: "generic_token",
+    re: /\b(?=[A-Za-z0-9_-]*[0-9])(?=[A-Za-z0-9_-]*[A-Za-z])(?![0-9a-fA-F]+$)[A-Za-z0-9_-]{32,}\b/g
+  },
+  {
+    kind: "base64",
+    re: /(?<![A-Za-z0-9+/])(?=[A-Za-z0-9+/]*[+/])(?=[A-Za-z0-9+/]*[0-9])(?=[A-Za-z0-9+/]*[A-Za-z])[A-Za-z0-9+/]{40,}={0,2}(?![A-Za-z0-9+/=])/g
+  },
+  {
+    kind: "context_secret",
+    re: /(?<![A-Za-z0-9_])(?:api[_-]?key|api[_-]?secret|access[_-]?token|refresh[_-]?token|auth[_-]?token|client[_-]?secret|password|passwd|pwd|secret|token|credential|private[_-]?key)["']?\s*[:=]\s*["']?([A-Za-z0-9+/=._-]{12,})(?=["'\s,;)\]}>]|$)/gi,
+    groupOnly: true
+  },
+  {
+    kind: "bearer",
+    re: /(?<![A-Za-z0-9_])Bearer\s+([A-Za-z0-9._-]{20,})\b/gi,
+    groupOnly: true
+  }
+];
+function redactSecrets(input) {
+  if (!input) return { redacted: input ?? "", found: [] };
+  const found = [];
+  let working = input;
+  for (const { kind, re, groupOnly } of PATTERNS) {
+    if (groupOnly) {
+      working = working.replace(re, (full, value) => {
+        if (typeof value !== "string" || !value) return full;
+        found.push({ kind, length: value.length });
+        return full.replace(value, `[REDACTED:${kind}]`);
+      });
+    } else {
+      working = working.replace(re, (m) => {
+        found.push({ kind, length: m.length });
+        return `[REDACTED:${kind}]`;
+      });
+    }
+  }
+  return { redacted: working, found };
+}
+
+// src/factory.ts
+function createAtbashClient(config = {}) {
+  const validated = validateJudgeEndpoint(config.judge);
+  const failClosed = config.failClosed !== false;
+  const logger = config.logger ?? {};
+  const inlineKeyPair = config.keyPair;
+  const keyPath = inlineKeyPair ? null : config.keyPath;
+  if (validated.url !== DEFAULT_ENDPOINT) {
+    logger.warn?.("[atbash] running on non-default judge endpoint", {
+      endpoint: validated.url,
+      policy: validated.policy,
+      verifying: validated.verifyPubKey ? "with response-signature pubkey configured" : "without signature verification"
+    });
+  }
+  let cachedAgent = inlineKeyPair ? loadAgent(inlineKeyPair.privKey) : null;
+  function loadAgentOnce() {
+    if (cachedAgent) return cachedAgent;
+    cachedAgent = loadAgentFromFile(keyPath ?? void 0);
+    return cachedAgent;
+  }
+  function fail(reason, toolCallId) {
+    return { allow: !failClosed, verdict: "ERROR", reason, toolCallId };
+  }
+  return {
+    async auditToolCall(input) {
+      let agent;
+      try {
+        agent = loadAgentOnce();
+      } catch (err) {
+        const message = String(err?.message ?? err ?? "");
+        logger.warn?.("[atbash] failed to load key pair, blocking for safety", {
+          error: message
+        });
+        return fail("key load failed, blocking for safety");
+      }
+      const toolName = input.toolName || "unknown";
+      const argsRedaction = redactSecrets(stringifyArgs(input.args));
+      const ctxRedaction = redactSecrets(input.context ?? toolName);
+      const argsJson = argsRedaction.redacted;
+      const actionText = truncate(argsJson);
+      const contextText = ctxRedaction.redacted;
+      const totalRedactions = argsRedaction.found.length + ctxRedaction.found.length;
+      if (totalRedactions > 0) {
+        const kinds = [.../* @__PURE__ */ new Set([
+          ...argsRedaction.found.map((f) => f.kind),
+          ...ctxRedaction.found.map((f) => f.kind)
+        ])];
+        logger.warn?.("[atbash] redacted secrets before judge call", {
+          tool: toolName,
+          count: totalRedactions,
+          kinds
+        });
+      }
+      try {
+        logger.info?.("[atbash] judge API called", { tool: toolName });
+        const result = await judgeAction(actionText, contextText, agent, {
+          endpoint: validated.url,
+          verifyPubKey: validated.verifyPubKey ?? void 0,
+          toolName,
+          toolArgsJson: argsJson,
+          chainOpts: {
+            nodeUrls: config.nodeUrls,
+            blockchainRid: config.blockchainRid
+          }
+        });
+        if (result.verdict === "No verdict") {
+          return {
+            allow: true,
+            verdict: "ALLOW",
+            reason: result.reason || "audit tier \u2014 request logged on-chain, no AI enforcement",
+            toolCallId: result.tool_call_id
+          };
+        }
+        const action = result.action_type;
+        if (action === "block") {
+          return {
+            allow: false,
+            verdict: "BLOCK",
+            reason: result.reason,
+            toolCallId: result.tool_call_id
+          };
+        }
+        if (action === "hold_for_user_confirm") {
+          return {
+            allow: false,
+            verdict: "HOLD",
+            reason: result.reason || "held for human confirmation",
+            toolCallId: result.tool_call_id
+          };
+        }
+        if (action === "allow") {
+          const surfacedVerdict = result.verdict === "ALLOW" || result.verdict === "HOLD" || result.verdict === "BLOCK" ? result.verdict : "ALLOW";
+          return {
+            allow: true,
+            verdict: surfacedVerdict,
+            reason: result.reason,
+            toolCallId: result.tool_call_id
+          };
+        }
+        return fail("unrecognized action_type from judge", result.tool_call_id);
+      } catch (err) {
+        const message = String(err?.message ?? err ?? "");
+        logger.warn?.("[atbash] judge API failed", { reason: message });
+        return fail(message);
+      }
+    }
+  };
+}
+function stringifyArgs(args) {
+  if (args == null) return "";
+  if (typeof args === "string") return args;
+  try {
+    return JSON.stringify(args);
+  } catch {
+    return String(args);
+  }
+}
+var MAX_ACTION_LEN = 4e3;
+function truncate(text) {
+  if (text.length <= MAX_ACTION_LEN) return text;
+  return text.slice(0, MAX_ACTION_LEN) + "\u2026";
+}
+
+// src/user-config.ts
+var import_node_fs2 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var ENV_MAP = {
+  agentKey: "ATBASH_AGENT_KEY",
+  orgName: "ATBASH_ORG_NAME",
+  judgeEndpoint: "ATBASH_ENDPOINT",
+  blockchainRid: "ATBASH_BLOCKCHAIN_RID",
+  provider: "ATBASH_PROVIDER",
+  providerModel: "ATBASH_PROVIDER_MODEL"
+};
+function getConfigDir() {
+  const home = process.env.HOME || (0, import_node_os2.homedir)() || "";
+  return (0, import_node_path2.join)(home, ".config", "atbash");
+}
+function getConfigPath() {
+  return (0, import_node_path2.join)(getConfigDir(), "config.json");
+}
+function loadUserConfig() {
+  try {
+    const p = getConfigPath();
+    if (!(0, import_node_fs2.existsSync)(p)) return {};
+    const raw = (0, import_node_fs2.readFileSync)(p, "utf-8").trim();
+    if (!raw) return {};
+    return JSON.parse(raw);
+  } catch (err) {
+    console.error("Failed to load config file", err);
+    return {};
+  }
+}
+function saveUserConfig(config) {
+  const dir = getConfigDir();
+  if (!(0, import_node_fs2.existsSync)(dir)) {
+    (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
+  }
+  (0, import_node_fs2.writeFileSync)(getConfigPath(), JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function resolve(key, flagValue) {
+  if (flagValue) return flagValue;
+  const envName = ENV_MAP[key];
+  if (envName) {
+    const envVal = process.env[envName];
+    if (envVal) return envVal;
+  }
+  const fileVal = loadUserConfig()[key];
+  if (fileVal != null) return String(fileVal);
+  return "";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_BLOCKCHAIN_RID,
   DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT,
   checkAgentExists,
+  createAtbashClient,
   derivePublicKey,
   generateKeyPair,
   getAgentDetail,
   getAgentPolicy,
   getAgentToolCalls,
+  getConfigDir,
+  getConfigPath,
   getHeldActionReviews,
   getJudgmentStatus,
   getOrgTierInfo,
@@ -413,6 +814,13 @@ async function getSafetyStats(opts) {
   isValidPrivateKey,
   judgeAction,
   loadAgent,
+  loadAgentFromFile,
+  loadUserConfig,
   logToolCall,
-  toPubkeyHex
+  resolve,
+  resolveKeyPath,
+  saveUserConfig,
+  toPubkeyHex,
+  validateJudgeEndpoint,
+  verifyJudgeResponseSignature
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 type Verdict = "ALLOW" | "HOLD" | "BLOCK" | "No verdict";
-type Provider = "atbash" | "openai" | "google" | "microsoft" | "custom" | (string & {});
+type Provider = "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 | {
@@ -40,6 +40,7 @@ interface JudgeOptions extends ClientOpts {
     toolName?: string;
     toolArgsJson?: string;
     chainOpts?: ChainOpts;
+    verifyPubKey?: string;
 }
 interface JudgmentStatus {
     status: JudgmentStatusState;
@@ -106,6 +107,46 @@ interface AgentPolicy {
     is_custom: boolean;
     default_policy: string;
 }
+type DecisionVerdict = "ALLOW" | "HOLD" | "BLOCK" | "ERROR";
+interface Decision {
+    allow: boolean;
+    verdict: DecisionVerdict;
+    reason?: string;
+    toolCallId?: string;
+}
+interface ToolCallInput {
+    toolName: string;
+    args?: unknown;
+    context?: string;
+}
+type JudgeEndpointConfig = {
+    policy?: "default";
+    endpoint?: string;
+} | {
+    policy: "self-hosted";
+    endpoint: string;
+    verifyPubKey: string;
+};
+interface ValidatedEndpoint {
+    url: string;
+    policy: "default" | "self-hosted";
+    verifyPubKey: string | null;
+}
+interface AtbashClientConfig {
+    judge?: JudgeEndpointConfig;
+    nodeUrls?: string[];
+    blockchainRid?: string;
+    keyPath?: string;
+    keyPair?: {
+        privKey: string;
+        pubKey: string;
+    };
+    failClosed?: boolean;
+    logger?: {
+        info?(...a: unknown[]): void;
+        warn?(...a: unknown[]): void;
+    };
+}
 
 declare const DEFAULT_ENDPOINT = "https://atbash.ai";
 declare const DEFAULT_CHROMIA_NODE_URLS: string[];
@@ -135,7 +176,7 @@ declare function logToolCall(action: string, context: string, auth: AgentAuth, c
     toolArgsJson?: string;
 }, clientOpts?: ClientOpts): Promise<LogToolCallResult>;
 declare function judgeAction(action: string, context: string | undefined, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
-declare function getJudgmentStatus(judgmentId: string, opts?: ClientOpts): Promise<JudgmentStatus>;
+declare function getJudgmentStatus(judgmentId: string, agentPubkey: 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[]>;
@@ -148,4 +189,33 @@ declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise
 declare function getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>;
 declare function getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>;
 
-export { type ActionType, type AgentAuth, type AgentPolicy, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type Provider, type PubkeyValue, type Tier, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, checkAgentExists, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, logToolCall, toPubkeyHex };
+interface AtbashClient {
+    auditToolCall(input: ToolCallInput): Promise<Decision>;
+}
+declare function createAtbashClient(config?: AtbashClientConfig): AtbashClient;
+
+declare function validateJudgeEndpoint(judge?: JudgeEndpointConfig): ValidatedEndpoint;
+
+declare function resolveKeyPath(input?: string): string;
+declare function loadAgentFromFile(keyPath?: string): AgentAuth;
+
+declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHex: string | null, pubKeyHex: string): {
+    ok: boolean;
+    reason?: string;
+};
+
+interface AtbashUserConfig {
+    agentKey?: string;
+    orgName?: string;
+    judgeEndpoint?: string;
+    blockchainRid?: string;
+    provider?: string;
+    providerModel?: string;
+}
+declare function getConfigDir(): string;
+declare function getConfigPath(): string;
+declare function loadUserConfig(): AtbashUserConfig;
+declare function saveUserConfig(config: AtbashUserConfig): void;
+declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): string;
+
+export { type ActionType, type AgentAuth, type AgentPolicy, type AtbashClient, type AtbashClientConfig, type AtbashUserConfig, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type Provider, type PubkeyValue, type Tier, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, checkAgentExists, createAtbashClient, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getConfigDir, getConfigPath, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, loadAgentFromFile, loadUserConfig, logToolCall, resolve, resolveKeyPath, saveUserConfig, toPubkeyHex, validateJudgeEndpoint, verifyJudgeResponseSignature };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 type Verdict = "ALLOW" | "HOLD" | "BLOCK" | "No verdict";
-type Provider = "atbash" | "openai" | "google" | "microsoft" | "custom" | (string & {});
+type Provider = "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 | {
@@ -40,6 +40,7 @@ interface JudgeOptions extends ClientOpts {
     toolName?: string;
     toolArgsJson?: string;
     chainOpts?: ChainOpts;
+    verifyPubKey?: string;
 }
 interface JudgmentStatus {
     status: JudgmentStatusState;
@@ -106,6 +107,46 @@ interface AgentPolicy {
     is_custom: boolean;
     default_policy: string;
 }
+type DecisionVerdict = "ALLOW" | "HOLD" | "BLOCK" | "ERROR";
+interface Decision {
+    allow: boolean;
+    verdict: DecisionVerdict;
+    reason?: string;
+    toolCallId?: string;
+}
+interface ToolCallInput {
+    toolName: string;
+    args?: unknown;
+    context?: string;
+}
+type JudgeEndpointConfig = {
+    policy?: "default";
+    endpoint?: string;
+} | {
+    policy: "self-hosted";
+    endpoint: string;
+    verifyPubKey: string;
+};
+interface ValidatedEndpoint {
+    url: string;
+    policy: "default" | "self-hosted";
+    verifyPubKey: string | null;
+}
+interface AtbashClientConfig {
+    judge?: JudgeEndpointConfig;
+    nodeUrls?: string[];
+    blockchainRid?: string;
+    keyPath?: string;
+    keyPair?: {
+        privKey: string;
+        pubKey: string;
+    };
+    failClosed?: boolean;
+    logger?: {
+        info?(...a: unknown[]): void;
+        warn?(...a: unknown[]): void;
+    };
+}
 
 declare const DEFAULT_ENDPOINT = "https://atbash.ai";
 declare const DEFAULT_CHROMIA_NODE_URLS: string[];
@@ -135,7 +176,7 @@ declare function logToolCall(action: string, context: string, auth: AgentAuth, c
     toolArgsJson?: string;
 }, clientOpts?: ClientOpts): Promise<LogToolCallResult>;
 declare function judgeAction(action: string, context: string | undefined, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
-declare function getJudgmentStatus(judgmentId: string, opts?: ClientOpts): Promise<JudgmentStatus>;
+declare function getJudgmentStatus(judgmentId: string, agentPubkey: 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[]>;
@@ -148,4 +189,33 @@ declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise
 declare function getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>;
 declare function getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>;
 
-export { type ActionType, type AgentAuth, type AgentPolicy, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type HeldAction, type HeldActionReview, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type Provider, type PubkeyValue, type Tier, type TierInfo, type ToolCallFull, type ToolCallRecord, type Verdict, checkAgentExists, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, logToolCall, toPubkeyHex };
+interface AtbashClient {
+    auditToolCall(input: ToolCallInput): Promise<Decision>;
+}
+declare function createAtbashClient(config?: AtbashClientConfig): AtbashClient;
+
+declare function validateJudgeEndpoint(judge?: JudgeEndpointConfig): ValidatedEndpoint;
+
+declare function resolveKeyPath(input?: string): string;
+declare function loadAgentFromFile(keyPath?: string): AgentAuth;
+
+declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHex: string | null, pubKeyHex: string): {
+    ok: boolean;
+    reason?: string;
+};
+
+interface AtbashUserConfig {
+    agentKey?: string;
+    orgName?: string;
+    judgeEndpoint?: string;
+    blockchainRid?: string;
+    provider?: string;
+    providerModel?: string;
+}
+declare function getConfigDir(): string;
+declare function getConfigPath(): string;
+declare function loadUserConfig(): AtbashUserConfig;
+declare function saveUserConfig(config: AtbashUserConfig): void;
+declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): string;
+
+export { type ActionType, type AgentAuth, type AgentPolicy, type AtbashClient, type AtbashClientConfig, type AtbashUserConfig, type ChainOpts, type ClientOpts, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type LogToolCallResult, type Provider, type PubkeyValue, type Tier, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, checkAgentExists, createAtbashClient, derivePublicKey, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getConfigDir, getConfigPath, getHeldActionReviews, getJudgmentStatus, getOrgTierInfo, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, loadAgentFromFile, loadUserConfig, logToolCall, resolve, resolveKeyPath, saveUserConfig, toPubkeyHex, validateJudgeEndpoint, verifyJudgeResponseSignature };

package/dist/index.js

@@ -1,7 +1,35 @@
 // src/client.ts
 import { createECDH, randomBytes } from "crypto";
+import postchain2 from "postchain-client";
+
+// src/signature.ts
 import postchain from "postchain-client";
-var { createClient, encryption, newSignatureProvider } = postchain;
+var { encryption } = postchain;
+function verifyJudgeResponseSignature(bodyBytes, signatureHex, pubKeyHex) {
+  if (!signatureHex) {
+    return { ok: false, reason: "missing X-Atbash-Signature header" };
+  }
+  const sigClean = signatureHex.trim().toLowerCase().replace(/^0x/, "");
+  if (!/^[0-9a-f]+$/.test(sigClean) || sigClean.length < 64 || sigClean.length > 256) {
+    return { ok: false, reason: "malformed signature header" };
+  }
+  let isValid = false;
+  try {
+    const digest = encryption.sha256(Buffer.from(bodyBytes));
+    const pubKeyBytes = Buffer.from(pubKeyHex.replace(/^0x/, ""), "hex");
+    const sigBytes = Buffer.from(sigClean, "hex");
+    isValid = encryption.checkDigestSignature(digest, pubKeyBytes, sigBytes);
+  } catch (err) {
+    const message = String(
+      err?.message ?? err ?? ""
+    );
+    return { ok: false, reason: `signature verification threw: ${message}` };
+  }
+  return isValid ? { ok: true } : { ok: false, reason: "signature does not verify against configured verifyPubKey" };
+}
+
+// src/client.ts
+var { createClient, encryption: encryption2, newSignatureProvider } = postchain2;
 var DEFAULT_ENDPOINT = "https://atbash.ai";
 var DEFAULT_CHROMIA_NODE_URLS = [
   "https://node6.testnet.chromia.com:7740",
@@ -57,7 +85,7 @@ async function buildSignedTx(opName, args, auth, chainOpts) {
   const blockchainRid = chainOpts?.blockchainRid ?? DEFAULT_BLOCKCHAIN_RID;
   const client = await createClient({ nodeUrlPool: nodeUrls, blockchainRid });
   const privKeyBuf = Buffer.from(auth.privkey, "hex");
-  const keyPair = encryption.makeKeyPair(privKeyBuf);
+  const keyPair = encryption2.makeKeyPair(privKeyBuf);
   const sigProvider = newSignatureProvider({
     privKey: keyPair.privKey,
     pubKey: keyPair.pubKey
@@ -168,6 +196,31 @@ async function getJson(url, opts) {
   }
   return resp.json();
 }
+async function postJudgeRequest(url, body, opts) {
+  if (!opts?.verifyPubKey) {
+    return 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 buf = new Uint8Array(await resp.arrayBuffer());
+  const verdict = verifyJudgeResponseSignature(
+    buf,
+    resp.headers.get("X-Atbash-Signature"),
+    opts.verifyPubKey
+  );
+  if (!verdict.ok) {
+    throw new Error(`signature verification failed: ${verdict.reason}`);
+  }
+  return JSON.parse(new TextDecoder().decode(buf));
+}
 async function judgeAction(action, context = "", auth, opts) {
   if (!action || !action.trim()) {
     throw new Error("action is required and cannot be empty.");
@@ -205,7 +258,7 @@ async function judgeAction(action, context = "", auth, opts) {
     ...opts?.toolName && { tool_name: opts.toolName },
     ...opts?.model && { model: opts.model }
   };
-  const data = await postJson(url, body, opts);
+  const data = await postJudgeRequest(url, body, opts);
   return {
     verdict: normalizeVerdict(data.verdict),
     action_type: String(data.action_type || ""),
@@ -217,8 +270,8 @@ async function judgeAction(action, context = "", auth, opts) {
     on_chain: Boolean(data.on_chain)
   };
 }
-async function getJudgmentStatus(judgmentId, opts) {
-  const url = `${baseUrl(opts)}/api/v1/judge?tool_call_id=${encodeURIComponent(judgmentId)}`;
+async function getJudgmentStatus(judgmentId, agentPubkey, opts) {
+  const url = `${baseUrl(opts)}/api/v1/judge?tool_call_id=${encodeURIComponent(judgmentId)}&agent_pubkey=${encodeURIComponent(agentPubkey)}`;
   const data = await getJson(url, opts);
   return {
     status: normalizeStatus(data.status),
@@ -332,16 +385,354 @@ async function getSafetyStats(opts) {
   const result = await getJson(url, opts);
   return result?.data || result;
 }
+
+// src/config.ts
+var ALLOWED_JUDGE_HOSTS = /* @__PURE__ */ new Set([
+  "atbash.ai",
+  "www.atbash.ai"
+]);
+function validateJudgeEndpoint(judge) {
+  const policy = judge?.policy === "self-hosted" ? "self-hosted" : "default";
+  const candidate = judge?.endpoint?.trim() || DEFAULT_ENDPOINT;
+  let parsed;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    throw new Error(
+      `[atbash] invalid judge endpoint URL: ${candidate}. Refusing to load \u2014 fix the URL or omit it to use the default (${DEFAULT_ENDPOINT}).`
+    );
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(
+      `[atbash] judge endpoint must use https:// (got "${parsed.protocol}"). Refusing to load \u2014 plaintext endpoints leak verdicts and enable trivial MITM bypass.`
+    );
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error(
+      `[atbash] judge endpoint must not contain credentials (user:pass@host). Refusing to load \u2014 credentials embedded in URLs leak to logs and process listings.`
+    );
+  }
+  const normalisedUrl = parsed.origin;
+  if (policy === "self-hosted") {
+    const verifyPubKey = judge?.verifyPubKey;
+    const key = verifyPubKey?.trim().toLowerCase();
+    if (!key || !/^[0-9a-f]{66}$/.test(key)) {
+      throw new Error(
+        `[atbash] judge endpoint policy "self-hosted" requires verifyPubKey to be a 66-hex-char compressed secp256k1 pubkey. Refusing to load \u2014 self-hosted judges must produce signed responses so the SDK can detect a malicious or compromised judge.`
+      );
+    }
+    return { url: normalisedUrl, policy, verifyPubKey: key };
+  }
+  if (!ALLOWED_JUDGE_HOSTS.has(parsed.hostname.toLowerCase())) {
+    throw new Error(
+      `[atbash] judge endpoint hostname "${parsed.hostname}" is not in the trusted allowlist. Allowed: ${[...ALLOWED_JUDGE_HOSTS].join(", ")}. To use a self-hosted judge, set BOTH policy="self-hosted" AND verifyPubKey to the 66-hex pubkey of your judge's response-signing key. Refusing to load \u2014 silent endpoint redirection is a known attack vector (F-003).`
+    );
+  }
+  return { url: normalisedUrl, policy, verifyPubKey: null };
+}
+
+// src/key-loader.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULT_KEY_PATH_REL = ".config/atbash/guard-client-key";
+function resolveKeyPath(input) {
+  if (input) return expandHome(input);
+  const home = process.env.HOME || homedir() || "";
+  return join(home, DEFAULT_KEY_PATH_REL);
+}
+function expandHome(p) {
+  if (!p.startsWith("~/")) return p;
+  const home = process.env.HOME || homedir() || "";
+  return join(home, p.slice(2));
+}
+function readKeyFile(keyPath) {
+  const content = String(readFileSync(keyPath, "utf8") || "").trim();
+  let privKey = "";
+  let pubKey = "";
+  if (content.startsWith("{")) {
+    const creds = JSON.parse(content);
+    privKey = String(
+      creds.privKey || creds.privkey || creds.privateKey || ""
+    ).trim();
+    pubKey = String(
+      creds.pubKey || creds.pubkey || creds.publicKey || ""
+    ).trim();
+  } else {
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+      if (line.startsWith("privkey=")) privKey = line.slice("privkey=".length).trim();
+      if (line.startsWith("pubkey=")) pubKey = line.slice("pubkey=".length).trim();
+    }
+  }
+  if (!privKey || !pubKey) {
+    throw new Error(`atbash key file missing priv/pub key fields: ${keyPath}`);
+  }
+  privKey = privKey.replace(/^0x/, "");
+  return { privKey, pubKey };
+}
+function loadAgentFromFile(keyPath) {
+  const resolved = resolveKeyPath(keyPath);
+  const { privKey } = readKeyFile(resolved);
+  return loadAgent(privKey);
+}
+
+// src/redact-secrets.ts
+var PATTERNS = [
+  { kind: "anthropic", re: /\bsk-ant-[A-Za-z0-9_-]{20,}/g },
+  { kind: "openai_project", re: /\bsk-proj-[A-Za-z0-9_-]{20,}/g },
+  { kind: "openai", re: /\bsk-[A-Za-z0-9]{20,}/g },
+  { kind: "github", re: /\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{30,}/g },
+  { kind: "google", re: /\bAIza[0-9A-Za-z_-]{35}/g },
+  { kind: "google_oauth", re: /\bya29\.[0-9A-Za-z_-]{20,}/g },
+  {
+    kind: "aws_access_key",
+    re: /\b(?:AKIA|ASIA|AGPA|AROA|ANPA|ANVA|ASCA|AIDA|AIPA)[0-9A-Z]{16}\b/g
+  },
+  { kind: "stripe", re: /\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{20,}/g },
+  { kind: "slack", re: /\bxox[abprseo]-[A-Za-z0-9-]{10,}/g },
+  {
+    kind: "slack_webhook",
+    re: /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9]+\/B[A-Za-z0-9]+\/[A-Za-z0-9]{20,}/g
+  },
+  { kind: "sendgrid", re: /\bSG\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}/g },
+  { kind: "twilio_sid", re: /\bAC[0-9a-fA-F]{32}\b/g },
+  { kind: "mailgun", re: /\bkey-[0-9a-f]{32}\b/g },
+  { kind: "npm_token", re: /\bnpm_[A-Za-z0-9]{36,}\b/g },
+  { kind: "jwt", re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g },
+  {
+    kind: "private_key_pem",
+    re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g
+  },
+  {
+    kind: "aws_secret_key",
+    re: /(?:aws[_-]?secret|secret[_-]?access[_-]?key)["'\s:=]{1,10}[A-Za-z0-9/+=]{40}/gi
+  },
+  {
+    kind: "generic_token",
+    re: /\b(?=[A-Za-z0-9_-]*[0-9])(?=[A-Za-z0-9_-]*[A-Za-z])(?![0-9a-fA-F]+$)[A-Za-z0-9_-]{32,}\b/g
+  },
+  {
+    kind: "base64",
+    re: /(?<![A-Za-z0-9+/])(?=[A-Za-z0-9+/]*[+/])(?=[A-Za-z0-9+/]*[0-9])(?=[A-Za-z0-9+/]*[A-Za-z])[A-Za-z0-9+/]{40,}={0,2}(?![A-Za-z0-9+/=])/g
+  },
+  {
+    kind: "context_secret",
+    re: /(?<![A-Za-z0-9_])(?:api[_-]?key|api[_-]?secret|access[_-]?token|refresh[_-]?token|auth[_-]?token|client[_-]?secret|password|passwd|pwd|secret|token|credential|private[_-]?key)["']?\s*[:=]\s*["']?([A-Za-z0-9+/=._-]{12,})(?=["'\s,;)\]}>]|$)/gi,
+    groupOnly: true
+  },
+  {
+    kind: "bearer",
+    re: /(?<![A-Za-z0-9_])Bearer\s+([A-Za-z0-9._-]{20,})\b/gi,
+    groupOnly: true
+  }
+];
+function redactSecrets(input) {
+  if (!input) return { redacted: input ?? "", found: [] };
+  const found = [];
+  let working = input;
+  for (const { kind, re, groupOnly } of PATTERNS) {
+    if (groupOnly) {
+      working = working.replace(re, (full, value) => {
+        if (typeof value !== "string" || !value) return full;
+        found.push({ kind, length: value.length });
+        return full.replace(value, `[REDACTED:${kind}]`);
+      });
+    } else {
+      working = working.replace(re, (m) => {
+        found.push({ kind, length: m.length });
+        return `[REDACTED:${kind}]`;
+      });
+    }
+  }
+  return { redacted: working, found };
+}
+
+// src/factory.ts
+function createAtbashClient(config = {}) {
+  const validated = validateJudgeEndpoint(config.judge);
+  const failClosed = config.failClosed !== false;
+  const logger = config.logger ?? {};
+  const inlineKeyPair = config.keyPair;
+  const keyPath = inlineKeyPair ? null : config.keyPath;
+  if (validated.url !== DEFAULT_ENDPOINT) {
+    logger.warn?.("[atbash] running on non-default judge endpoint", {
+      endpoint: validated.url,
+      policy: validated.policy,
+      verifying: validated.verifyPubKey ? "with response-signature pubkey configured" : "without signature verification"
+    });
+  }
+  let cachedAgent = inlineKeyPair ? loadAgent(inlineKeyPair.privKey) : null;
+  function loadAgentOnce() {
+    if (cachedAgent) return cachedAgent;
+    cachedAgent = loadAgentFromFile(keyPath ?? void 0);
+    return cachedAgent;
+  }
+  function fail(reason, toolCallId) {
+    return { allow: !failClosed, verdict: "ERROR", reason, toolCallId };
+  }
+  return {
+    async auditToolCall(input) {
+      let agent;
+      try {
+        agent = loadAgentOnce();
+      } catch (err) {
+        const message = String(err?.message ?? err ?? "");
+        logger.warn?.("[atbash] failed to load key pair, blocking for safety", {
+          error: message
+        });
+        return fail("key load failed, blocking for safety");
+      }
+      const toolName = input.toolName || "unknown";
+      const argsRedaction = redactSecrets(stringifyArgs(input.args));
+      const ctxRedaction = redactSecrets(input.context ?? toolName);
+      const argsJson = argsRedaction.redacted;
+      const actionText = truncate(argsJson);
+      const contextText = ctxRedaction.redacted;
+      const totalRedactions = argsRedaction.found.length + ctxRedaction.found.length;
+      if (totalRedactions > 0) {
+        const kinds = [.../* @__PURE__ */ new Set([
+          ...argsRedaction.found.map((f) => f.kind),
+          ...ctxRedaction.found.map((f) => f.kind)
+        ])];
+        logger.warn?.("[atbash] redacted secrets before judge call", {
+          tool: toolName,
+          count: totalRedactions,
+          kinds
+        });
+      }
+      try {
+        logger.info?.("[atbash] judge API called", { tool: toolName });
+        const result = await judgeAction(actionText, contextText, agent, {
+          endpoint: validated.url,
+          verifyPubKey: validated.verifyPubKey ?? void 0,
+          toolName,
+          toolArgsJson: argsJson,
+          chainOpts: {
+            nodeUrls: config.nodeUrls,
+            blockchainRid: config.blockchainRid
+          }
+        });
+        if (result.verdict === "No verdict") {
+          return {
+            allow: true,
+            verdict: "ALLOW",
+            reason: result.reason || "audit tier \u2014 request logged on-chain, no AI enforcement",
+            toolCallId: result.tool_call_id
+          };
+        }
+        const action = result.action_type;
+        if (action === "block") {
+          return {
+            allow: false,
+            verdict: "BLOCK",
+            reason: result.reason,
+            toolCallId: result.tool_call_id
+          };
+        }
+        if (action === "hold_for_user_confirm") {
+          return {
+            allow: false,
+            verdict: "HOLD",
+            reason: result.reason || "held for human confirmation",
+            toolCallId: result.tool_call_id
+          };
+        }
+        if (action === "allow") {
+          const surfacedVerdict = result.verdict === "ALLOW" || result.verdict === "HOLD" || result.verdict === "BLOCK" ? result.verdict : "ALLOW";
+          return {
+            allow: true,
+            verdict: surfacedVerdict,
+            reason: result.reason,
+            toolCallId: result.tool_call_id
+          };
+        }
+        return fail("unrecognized action_type from judge", result.tool_call_id);
+      } catch (err) {
+        const message = String(err?.message ?? err ?? "");
+        logger.warn?.("[atbash] judge API failed", { reason: message });
+        return fail(message);
+      }
+    }
+  };
+}
+function stringifyArgs(args) {
+  if (args == null) return "";
+  if (typeof args === "string") return args;
+  try {
+    return JSON.stringify(args);
+  } catch {
+    return String(args);
+  }
+}
+var MAX_ACTION_LEN = 4e3;
+function truncate(text) {
+  if (text.length <= MAX_ACTION_LEN) return text;
+  return text.slice(0, MAX_ACTION_LEN) + "\u2026";
+}
+
+// src/user-config.ts
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync, existsSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+var ENV_MAP = {
+  agentKey: "ATBASH_AGENT_KEY",
+  orgName: "ATBASH_ORG_NAME",
+  judgeEndpoint: "ATBASH_ENDPOINT",
+  blockchainRid: "ATBASH_BLOCKCHAIN_RID",
+  provider: "ATBASH_PROVIDER",
+  providerModel: "ATBASH_PROVIDER_MODEL"
+};
+function getConfigDir() {
+  const home = process.env.HOME || homedir2() || "";
+  return join2(home, ".config", "atbash");
+}
+function getConfigPath() {
+  return join2(getConfigDir(), "config.json");
+}
+function loadUserConfig() {
+  try {
+    const p = getConfigPath();
+    if (!existsSync(p)) return {};
+    const raw = readFileSync2(p, "utf-8").trim();
+    if (!raw) return {};
+    return JSON.parse(raw);
+  } catch (err) {
+    console.error("Failed to load config file", err);
+    return {};
+  }
+}
+function saveUserConfig(config) {
+  const dir = getConfigDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function resolve(key, flagValue) {
+  if (flagValue) return flagValue;
+  const envName = ENV_MAP[key];
+  if (envName) {
+    const envVal = process.env[envName];
+    if (envVal) return envVal;
+  }
+  const fileVal = loadUserConfig()[key];
+  if (fileVal != null) return String(fileVal);
+  return "";
+}
 export {
   DEFAULT_BLOCKCHAIN_RID,
   DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT,
   checkAgentExists,
+  createAtbashClient,
   derivePublicKey,
   generateKeyPair,
   getAgentDetail,
   getAgentPolicy,
   getAgentToolCalls,
+  getConfigDir,
+  getConfigPath,
   getHeldActionReviews,
   getJudgmentStatus,
   getOrgTierInfo,
@@ -354,6 +745,13 @@ export {
   isValidPrivateKey,
   judgeAction,
   loadAgent,
+  loadAgentFromFile,
+  loadUserConfig,
   logToolCall,
-  toPubkeyHex
+  resolve,
+  resolveKeyPath,
+  saveUserConfig,
+  toPubkeyHex,
+  validateJudgeEndpoint,
+  verifyJudgeResponseSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atbash/sdk",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Atbash SDK — control boundary before the last irreversible step in an agent workflow",
   "homepage": "https://atbash.ai",
   "author": "Atbash",