@atbash/atbash-mcp 0.0.12 → 0.0.13-dev.0

package/README.md

@@ -1,4 +1,4 @@
-# `@atbash/mcp`
+# `@atbash/atbash-mcp`
 
 Expose Atbash as a standalone MCP server.
 
@@ -7,7 +7,7 @@ This package starts an MCP server process that loads one Atbash agent identity a
 ## Installation
 
 ```bash
-npm install @atbash/mcp
+npm install @atbash/atbash-mcp@0.0.12-dev.3
 ```
 
 ## When To Use It
@@ -31,7 +31,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "atbash": {
       "command": "npx",
-      "args": ["-y", "@atbash/mcp"],
+      "args": ["-y", "@atbash/atbash-mcp@0.0.12-dev.3"],
       "env": {
         "ATBASH_AGENT_PRIVKEY": "your_agent_private_key_here",
         "ATBASH_ORG_NAME": "your_org_name"
@@ -48,7 +48,7 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 
 const transport = new StdioClientTransport({
   command: "npx",
-  args: ["-y", "@atbash/mcp"],
+  args: ["-y", "@atbash/atbash-mcp@0.0.12-dev.3"],
   env: {
     ...process.env,
     ATBASH_AGENT_PRIVKEY: process.env.ATBASH_AGENT_PRIVKEY,
@@ -64,6 +64,7 @@ const transport = new StdioClientTransport({
 | `ATBASH_AGENT_PRIVKEY` | Yes | Your Atbash agent private key |
 | `ATBASH_ORG_NAME` | Recommended | Your organization name. The SDK resolves the correct chain from it; without it, calls fall back to the default public chain. |
 | `ATBASH_ENDPOINT` | No | Override the default Atbash endpoint (`https://atbash.ai`) |
+| `ATBASH_FAIL_CLOSED` | — | Has no effect. The MCP server is unconditionally fail-closed — judge errors always block, regardless of this variable. |
 
 ## Tools
 
@@ -80,11 +81,18 @@ Submit an action for safety judgment before executing it.
 | `tool_name` | string | No | Name of the tool being called |
 | `tool_args_json` | string | No | JSON string of tool arguments |
 
-Returns: `{ verdict, allow, reason, tool_call_id }`
+Returns: `{ verdict, allow, reason, toolCallId }`
 
 #### `atbash_log`
 
-Log a tool call on-chain without requesting a verdict.
+Submit a tool call through Atbash's redacting safety-judgment path. The judge
+logs/broadcasts the call and returns the same fail-closed decision contract as
+`atbash_judge`: `{ verdict, allow, reason, toolCallId }`.
+
+Despite its legacy name, this is not a distinct non-judging log operation. The
+pinned SDK has no server-broadcasting audit-only API; its `logToolCall()` method
+only creates a local signed transaction, so this MCP tool deliberately does not
+use or expose that local-only result as proof of persistence.
 
 | Input | Type | Required |
 |---|---|---|
@@ -130,10 +138,53 @@ Poll the status of a previously submitted judgment.
 
 | Verdict | Meaning | What To Do |
 |---|---|---|
-| `ALLOW` | Safe to proceed | Execute the real tool |
-| `HOLD` | Logged for async review | Execution is allowed; the action is flagged for operator review in the background — keep `tool_call_id` to poll status later |
+| `ALLOW` | Safe to proceed | Execute the real tool only when `allow` is also exactly `true` |
+| `HOLD` | Pending operator review | Do not proceed; keep `tool_call_id` to poll status later |
 | `BLOCK` | Policy violation | Stop; show `reason` to operator |
-| `ERROR` | Judge unreachable | Fail closed |
+| `ERROR` | Judge unreachable | Fail closed — do not proceed |
+
+Unknown or missing verdicts, and `ALLOW` responses carrying `allow: false`, are
+also returned with `allow: false`.
+
+### Enforcement is advisory in MCP
+
+An MCP server exposes tools; it cannot intercept the *other* tools your client
+calls. So this package can tell you an action is unsafe, but it cannot stop the
+client from running it — the model has to honour the verdict. If a verdict is
+unreachable, both `atbash_judge` and `atbash_log` return
+`{"verdict": "ERROR", "allow": false}` with an explicit instruction not to
+proceed, rather than a bare transport error that is easy to mistake for a
+broken tool.
+
+For enforcement that a compromised or prompt-injected agent cannot talk its way
+past, use a plugin that wraps the tool-call boundary itself — for example
+`@atbash/atbash-langchain`, `@atbash/atbash-langgraph`, the OpenClaw plugin, or
+the Codex/ChatGPT hook, all of which refuse the call before the tool executes.
+
+An `ALLOW` also has to have a verdict behind it. Prior SDK versions (e.g. 0.5.3-dev.0) treated a judge response body with no `verdict` field as an audit-tier pass — this plugin guards against that at any SDK version — synthesizing `{"allow": true, "verdict": "ALLOW"}` from it — including for a body
+that goes on to say `"action_type": "block"`. The shipped configuration points
+at an allowlisted endpoint, for which the SDK sets no `verifyPubKey` and so
+skips response-signature verification entirely, which leaves schema drift, a
+truncated response and a rewriting proxy all arriving as permission. This
+package therefore re-checks every allow against the `JudgeResult` the SDK parsed
+that body into, and refuses it with `{"verdict": "ERROR", "allow": false}`
+unless the judge sent a verdict and an `action_type` of exactly `allow`.
+
+Be precise about what that inspects, because it is one layer above the HTTP
+body: `action_type` is the response body's value verbatim, whereas the verdict
+has already been case-folded and aliased by the SDK. So `"verdict": "green"`
+is honoured as an `ALLOW` — `GREEN` is the judge's own alias, not drift — while
+an absent verdict is refused. An organization on a logging-only tier therefore
+sees denials rather than passes; that is deliberate, since absence of a verdict
+is not a verdict.
+
+The judge endpoint is resolved through `Atbash.fromConfig`, which validates
+`ATBASH_ENDPOINT` against the SDK's trusted allowlist / self-hosted policy. The
+plain `new Atbash(privkey, { endpoint })` constructor performs no such check,
+so an injected endpoint would be trusted outright. Startup also requires the
+endpoint-validation and fail-closed audit capabilities of the pinned
+`@atbash/sdk`; the process refuses to start if they are absent, rather than
+running with an inert safety gate.
 
 ## Sending Better Inputs
 

package/dist/index.js

@@ -16,10 +16,10 @@ function registerSafetyPrompt(server2) {
     "atbash_safety_check",
     {
       description: "Prepare a consistent pre-execution Atbash safety review request.",
-      inputSchema: z.object({
+      argsSchema: {
         action: z.string().describe("Action to evaluate"),
         context: z.string().describe("Why the action is being taken")
-      })
+      }
     },
     async ({ action, context }) => ({
       messages: [
@@ -46,6 +46,86 @@ function registerPolicyResource(server2, client2) {
   void client2;
 }
 
+// src/startup.ts
+function assertMcpSdkCapabilities(sdk) {
+  const missing = [
+    typeof sdk.fromConfig === "function" ? null : "fromConfig",
+    typeof sdk.prototype?.auditToolCall === "function" ? null : "auditToolCall"
+  ].filter((name) => name !== null);
+  if (missing.length > 0) {
+    throw new Error(
+      `Incompatible @atbash/sdk: missing required MCP capabilities: ${missing.join(", ")}. Refusing to start without an active safety gate.`
+    );
+  }
+}
+var DECISION_VERDICTS = [
+  "ALLOW",
+  "HOLD",
+  "BLOCK",
+  "ERROR"
+];
+function isDecisionShaped(value) {
+  const decision = value;
+  return typeof decision === "object" && decision !== null && typeof decision.allow === "boolean" && DECISION_VERDICTS.includes(decision.verdict);
+}
+function hardenJudgeClient(client2) {
+  const sdkAudit = client2.auditToolCall;
+  const sdkJudge = client2.judgeAction;
+  async function guardedAuditToolCall(input) {
+    let wire;
+    const shadow = Object.create(client2);
+    Object.defineProperty(shadow, "judgeAction", {
+      value: async (...args) => {
+        const result = await sdkJudge.apply(client2, args);
+        wire = result;
+        return result;
+      }
+    });
+    const decision = await sdkAudit.call(shadow, input);
+    if (!isDecisionShaped(decision)) {
+      throw new Error(
+        "judge decision is not verdict-shaped and cannot be trusted"
+      );
+    }
+    if (decision.verdict !== "ALLOW" || decision.allow !== true) {
+      return { ...decision, allow: false };
+    }
+    if (wire === void 0) {
+      throw new Error(
+        "judge returned an allow without a judge response to back it"
+      );
+    }
+    if (wire.verdict !== "ALLOW" || wire.actionType !== "allow") {
+      throw new Error(
+        `judge response body does not carry an allow (verdict ${JSON.stringify(wire.verdict)}, action_type ${JSON.stringify(wire.actionType)})`
+      );
+    }
+    return decision;
+  }
+  Object.defineProperty(client2, "auditToolCall", {
+    value: guardedAuditToolCall,
+    writable: true,
+    configurable: true
+  });
+  return client2;
+}
+function createAtbashClient(env, sdk) {
+  assertMcpSdkCapabilities(sdk);
+  const agentKey = env.ATBASH_AGENT_PRIVKEY;
+  if (!agentKey) {
+    throw new Error("ATBASH_AGENT_PRIVKEY env var is required");
+  }
+  const endpoint = env.ATBASH_ENDPOINT?.trim();
+  const orgName = env.ATBASH_ORG_NAME?.trim();
+  return hardenJudgeClient(
+    sdk.fromConfig({
+      agentKey,
+      ...endpoint ? { judge: { endpoint } } : {},
+      ...orgName ? { orgName } : {}
+    })
+  );
+}
+
 // src/tools/judge.ts
 import { z as z2 } from "zod";
 
@@ -66,6 +146,28 @@ function toErrorContent(error) {
 }
 
 // src/tools/judge.ts
+function toJudgeFailureContent(error, toolName = "atbash_judge") {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          {
+            verdict: "ERROR",
+            allow: false,
+            reason: `Atbash judge unavailable \u2014 treat this as BLOCK and do NOT proceed with the action (fail-closed). Retry ${toolName} once the service is reachable. Cause: ${safeErrorMessage(error)}`
+          },
+          null,
+          2
+        )
+      }
+    ],
+    isError: true
+  };
+}
+function denyUnlessExplicitlyAllowed(decision) {
+  return decision.verdict === "ALLOW" && decision.allow === true ? decision : { ...decision, allow: false };
+}
 function registerJudgeTools(server2, client2) {
   server2.registerTool(
     "atbash_judge",
@@ -88,11 +190,17 @@ function registerJudgeTools(server2, client2) {
             parsedArgs = tool_args_json;
           }
         }
-        const decision = await client2.auditToolCall({
+        const rawDecision = await client2.auditToolCall({
           toolName: tool_name ?? "mcp_judge",
           args: parsedArgs ?? { action },
           context: `${action} \u2014 ${context}`
         });
+        const decision = denyUnlessExplicitlyAllowed(rawDecision);
+        if (decision.verdict === "ERROR") {
+          return toJudgeFailureContent(
+            new Error(decision.reason ?? "judge returned an error verdict")
+          );
+        }
         if (decision.verdict === "HOLD") {
           const holdParts = [
             "Action held for operator review. The agent will not be jailed \u2014 please approve or reject this request from the Atbash dashboard, then ask the agent to try again.",
@@ -103,14 +211,14 @@ function registerJudgeTools(server2, client2) {
         }
         return toJsonContent(decision);
       } catch (error) {
-        return toErrorContent(error);
+        return toJudgeFailureContent(error);
       }
     }
   );
   server2.registerTool(
     "atbash_log",
     {
-      description: "Log a tool call on-chain without requesting a verdict.",
+      description: "Submit a tool call for Atbash safety judgment and logging. Returns ALLOW, HOLD, BLOCK, or ERROR.",
       inputSchema: z2.object({
         action: z2.string().describe("Action description"),
         context: z2.string().describe("Action context"),
@@ -128,22 +236,29 @@ function registerJudgeTools(server2, client2) {
             parsedArgs = tool_args_json;
           }
         }
-        const result = await client2.auditToolCall({
+        const rawDecision = await client2.auditToolCall({
           toolName: tool_name ?? "mcp_log",
           args: parsedArgs ?? { action },
           context: `${action} \u2014 ${context}`
         });
-        if (result.verdict === "HOLD") {
+        const decision = denyUnlessExplicitlyAllowed(rawDecision);
+        if (decision.verdict === "ERROR") {
+          return toJudgeFailureContent(
+            new Error(decision.reason ?? "judge returned an error verdict"),
+            "atbash_log"
+          );
+        }
+        if (decision.verdict === "HOLD") {
           const holdParts = [
             "Action held for operator review. The agent will not be jailed \u2014 please approve or reject this request from the Atbash dashboard, then ask the agent to try again.",
-            `Reason: ${result.reason ?? ""}`
+            `Reason: ${decision.reason ?? ""}`
           ];
-          if (result.toolCallId) holdParts.push(`Tool Call ID: ${result.toolCallId}`);
-          return toJsonContent({ ...result, allow: false, reason: holdParts.join("\n") });
+          if (decision.toolCallId) holdParts.push(`Tool Call ID: ${decision.toolCallId}`);
+          return toJsonContent({ ...decision, allow: false, reason: holdParts.join("\n") });
         }
-        return toJsonContent(result);
+        return toJsonContent(decision);
       } catch (error) {
-        return toErrorContent(error);
+        return toJudgeFailureContent(error, "atbash_log");
       }
     }
   );
@@ -379,21 +494,11 @@ function registerStatusTools(server2, client2) {
 }
 
 // src/index.ts
-var privkey = process.env.ATBASH_AGENT_PRIVKEY;
-if (!privkey) {
-  console.error("ATBASH_AGENT_PRIVKEY env var is required");
-  process.exit(1);
-}
-var endpoint = process.env.ATBASH_ENDPOINT;
-var orgName = process.env.ATBASH_ORG_NAME;
+var client = createAtbashClient(process.env, Atbash);
 setupTelemetry({ enabled: true, source: "plugin:mcp" });
 process.once("beforeExit", () => shutdownTelemetry());
 process.once("SIGINT", () => shutdownTelemetry().finally(() => process.exit(0)));
 process.once("SIGTERM", () => shutdownTelemetry().finally(() => process.exit(0)));
-var clientOpts = {};
-if (endpoint) clientOpts.endpoint = endpoint;
-if (orgName) clientOpts.orgName = orgName;
-var client = new Atbash(privkey, clientOpts);
 var server = new McpServer({
   name: "atbash-safety",
   version: "1.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atbash/atbash-mcp",
-  "version": "0.0.12",
+  "version": "0.0.13-dev.0",
   "description": "Atbash safety judge exposed as a standalone MCP server",
   "type": "module",
   "main": "dist/index.js",
@@ -39,13 +39,16 @@
   },
   "scripts": {
     "build": "node scripts/clean.mjs && tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:compile": "tsc -p tsconfig.json --outDir dist --declaration false --sourceMap false",
+    "test": "vitest run && npm run test:compile && node --test tests/*.test.mjs",
     "example": "npm run build && npm install --prefix examples/mcp-runtime-agent && node examples/mcp-runtime-agent/client.mjs",
     "verify:package": "node scripts/release.mjs --verify-current",
     "release": "node scripts/release.mjs --channel latest",
     "release:dev": "node scripts/release.mjs --channel dev"
   },
   "dependencies": {
-    "@atbash/sdk": "0.7.1",
+    "@atbash/sdk": "0.15.0-dev.0",
     "@modelcontextprotocol/sdk": "^1.12.3",
     "zod": "^3.25.76"
   },
@@ -53,6 +56,7 @@
     "@types/node": "^25.7.0",
     "semver": "7.8.5",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.6"
   }
 }