@atbash/atbash-mcp 0.1.2 → 0.19.1-dev.0

package/dist/startup.js

@@ -0,0 +1,124 @@
+export 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.");
+    }
+}
+const 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));
+}
+/**
+ * `auditToolCall` collapses the judge's response body into a Decision, and one
+ * of its branches is affirmative on absence: a 200 body carrying no `verdict`
+ * key becomes `{allow: true, verdict: "ALLOW"}` even when that same body says
+ * `action_type: "block"` (@atbash/sdk 0.10.5-dev.0, dist/index.mjs:3589+). The
+ * body's own reason is forwarded verbatim, so nothing downstream can tell that
+ * synthesized allow apart from a real one — and the shipped MCP configuration
+ * talks to an allowlisted endpoint, for which the SDK sets no `verifyPubKey`
+ * and therefore skips response-signature verification entirely. Schema drift, a
+ * truncated body and a rewriting proxy all land in that branch and read as
+ * permission.
+ *
+ * So bind the allow to the `JudgeResult` the SDK collapsed from: an allow is an
+ * allow only when the judge positively said so.
+ *
+ * Precisely what that inspects, since it is one layer above the HTTP body:
+ * `JudgeResult` is built directly from the parsed response
+ * (@atbash/sdk 0.10.5-dev.0, dist/index.mjs:3455+), so `actionType` is
+ * `String(body.action_type ?? "")` — verbatim, and the check below demands
+ * exactly lowercase `"allow"`. `verdict`, however, has been through
+ * `normalizeVerdict` (dist/index.mjs:3289+), which upper-cases and aliases:
+ * `GREEN`→`ALLOW`, `YELLOW`→`HOLD`, `RED`→`BLOCK`, any other string→`HOLD`,
+ * and — the case this guard exists for — `null`/absent→`"No verdict"`. So a
+ * judge body of `{"verdict": "green", "action_type": "allow"}` is honoured as
+ * an allow, deliberately: `GREEN` is the judge's own alias, not drift. What
+ * cannot pass is an allow with no verdict behind it, or one whose
+ * `action_type` is anything but `allow`.
+ *
+ * A non-allow decision is returned with `allow` forced to `false` rather than
+ * passed through: the SDK's `fail()` emits `{verdict: "ERROR", allow: true}`
+ * when `failClosed` is false (dist/index.mjs:3654+), and this function is
+ * exported as a defence-in-depth layer that should not depend on a caller
+ * re-checking it. Everything else throws, which the judge tools turn into the
+ * explicit verdict-shaped refusal in `toJudgeFailureContent` rather than a
+ * silent pass.
+ */
+export function hardenJudgeClient(client) {
+    const sdkAudit = client.auditToolCall;
+    const sdkJudge = client.judgeAction;
+    async function guardedAuditToolCall(input) {
+        let wire;
+        // `auditToolCall` reads its redaction and org config off `this` and calls
+        // `this.judgeAction` exactly once. A per-call prototype shadow captures that
+        // raw result without mutating the shared client, so two MCP tool calls in
+        // flight at the same time cannot observe each other's verdict.
+        const shadow = Object.create(client);
+        Object.defineProperty(shadow, "judgeAction", {
+            value: async (...args) => {
+                const result = await sdkJudge.apply(client, 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 === undefined) {
+            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(client, "auditToolCall", {
+        value: guardedAuditToolCall,
+        writable: true,
+        configurable: true,
+    });
+    return client;
+}
+/**
+ * Build the MCP server's Atbash client.
+ *
+ * `Atbash.fromConfig` is used rather than `new Atbash(privkey, {endpoint})`
+ * because only `fromConfig` runs `validateJudgeEndpoint` — the direct
+ * constructor accepts any `ATBASH_ENDPOINT` unchecked and with no response
+ * signature verification, so an operator-supplied (or environment-injected)
+ * judge URL would be trusted outright. The endpoint is passed under `judge`,
+ * which is the key `fromConfig` actually reads; passing it at the top level
+ * silently drops it and falls back to the default endpoint.
+ */
+export 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 } : {}),
+    }));
+}

package/dist/tools/judge.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { toErrorContent, toJsonContent, safeErrorMessage } from "../utils.js";
+// MCP is judge-as-a-tool — the host cannot intercept OTHER tools, so
+// enforcement here is advisory and the model itself acts on this payload. A
+// judge outage therefore must not come back as a generic "Error: fetch
+// failed" (easy for the model to shrug off as a broken tool); it comes back
+// as an explicit verdict-shaped refusal that instructs the model not to
+// proceed. Only the safety-gate tools use this — diagnostics keep the
+// generic toErrorContent.
+function toJudgeFailureContent(error, toolName = "atbash_judge") {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    verdict: "ERROR",
+                    allow: false,
+                    reason: `Atbash judge unavailable — 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,
+    };
+}
+// Permission requires a positive match: verdict exactly "ALLOW" AND the SDK's
+// boolean allow exactly true. Anything else — HOLD, BLOCK, ERROR, an
+// unrecognised verdict, a missing verdict, or an "ALLOW" that carries
+// allow:false — is handed to the model with allow:false.
+function denyUnlessExplicitlyAllowed(decision) {
+    return decision.verdict === "ALLOW" && decision.allow === true
+        ? decision
+        : { ...decision, allow: false };
+}
+export function registerJudgeTools(server, client) {
+    server.registerTool("atbash_judge", {
+        description: "Submit an action for safety judgment before executing it. Returns ALLOW, HOLD, BLOCK, or ERROR.",
+        inputSchema: z.object({
+            action: z.string().describe("Plain text description of the action to judge"),
+            context: z.string().describe("Why this action is being taken"),
+            tool_name: z.string().optional().describe("Name of the tool being called"),
+            tool_args_json: z.string().optional().describe("JSON string of tool arguments"),
+        }),
+    }, async ({ action, context, tool_name, tool_args_json }) => {
+        try {
+            let parsedArgs = undefined;
+            if (tool_args_json) {
+                try {
+                    parsedArgs = JSON.parse(tool_args_json);
+                }
+                catch {
+                    parsedArgs = tool_args_json;
+                }
+            }
+            const rawDecision = await client.auditToolCall({
+                toolName: tool_name ?? "mcp_judge",
+                args: parsedArgs ?? { action },
+                context: `${action} — ${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 — please approve or reject this request from the Atbash dashboard, then ask the agent to try again.",
+                    `Reason: ${decision.reason ?? ""}`,
+                ];
+                if (decision.toolCallId)
+                    holdParts.push(`Tool Call ID: ${decision.toolCallId}`);
+                return toJsonContent({ ...decision, allow: false, reason: holdParts.join("\n") });
+            }
+            return toJsonContent(decision);
+        }
+        catch (error) {
+            return toJudgeFailureContent(error);
+        }
+    });
+    server.registerTool("atbash_log", {
+        description: "Submit a tool call for Atbash safety judgment and logging. Returns ALLOW, HOLD, BLOCK, or ERROR.",
+        inputSchema: z.object({
+            action: z.string().describe("Action description"),
+            context: z.string().describe("Action context"),
+            tool_name: z.string().optional().describe("Tool name"),
+            tool_args_json: z.string().optional().describe("Tool arguments JSON"),
+        }),
+    }, async ({ action, context, tool_name, tool_args_json }) => {
+        try {
+            let parsedArgs = undefined;
+            if (tool_args_json) {
+                try {
+                    parsedArgs = JSON.parse(tool_args_json);
+                }
+                catch {
+                    parsedArgs = tool_args_json;
+                }
+            }
+            const rawDecision = await client.auditToolCall({
+                toolName: tool_name ?? "mcp_log",
+                args: parsedArgs ?? { action },
+                context: `${action} — ${context}`,
+            });
+            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 — please approve or reject this request from the Atbash dashboard, then ask the agent to try again.",
+                    `Reason: ${decision.reason ?? ""}`,
+                ];
+                if (decision.toolCallId)
+                    holdParts.push(`Tool Call ID: ${decision.toolCallId}`);
+                return toJsonContent({ ...decision, allow: false, reason: holdParts.join("\n") });
+            }
+            return toJsonContent(decision);
+        }
+        catch (error) {
+            return toJudgeFailureContent(error, "atbash_log");
+        }
+    });
+    server.registerTool("atbash_check_agent", {
+        description: "Check whether an agent is registered on the Atbash platform.",
+        inputSchema: z.object({
+            pubkey: z.string().optional().describe("Agent public key, defaults to this server agent"),
+        }),
+    }, async ({ pubkey }) => {
+        try {
+            const selectedPubkey = pubkey ?? client.pubkey;
+            const registered = await client.checkAgentExists(selectedPubkey);
+            return toJsonContent({ registered, pubkey: selectedPubkey });
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+}

package/dist/tools/judge.test.js

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi } from "vitest";
+import { registerJudgeTools } from "./judge.js";
+function makeFakeServer() {
+    const handlers = new Map();
+    return {
+        handlers,
+        registerTool: vi.fn((name, _config, handler) => {
+            handlers.set(name, handler);
+        }),
+    };
+}
+function makeClient(decision) {
+    return {
+        auditToolCall: vi.fn().mockResolvedValue(decision),
+        checkAgentExists: vi.fn(),
+        pubkey: "server-agent-pubkey",
+    };
+}
+describe("registerJudgeTools", () => {
+    it("registers exactly atbash_judge, atbash_log, atbash_check_agent", () => {
+        const server = makeFakeServer();
+        registerJudgeTools(server, makeClient({ verdict: "ALLOW" }));
+        expect([...server.handlers.keys()].sort()).toEqual([
+            "atbash_check_agent",
+            "atbash_judge",
+            "atbash_log",
+        ]);
+    });
+    describe("atbash_judge", () => {
+        it("passes ALLOW through unchanged", async () => {
+            const decision = { verdict: "ALLOW", allow: true, reason: "fine", toolCallId: "tc-1" };
+            const client = makeClient(decision);
+            const server = makeFakeServer();
+            registerJudgeTools(server, client);
+            const result = await server.handlers.get("atbash_judge")({
+                action: "wire $5000",
+                context: "customer request",
+                tool_name: "wire_transfer",
+                tool_args_json: JSON.stringify({ to: "0xabc" }),
+            });
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed).toEqual(decision);
+            expect(client.auditToolCall).toHaveBeenCalledWith({
+                toolName: "wire_transfer",
+                args: { to: "0xabc" },
+                context: "wire $5000 — customer request",
+            });
+        });
+        it("reformats HOLD with allow:false and the tool_call_id reference", async () => {
+            const decision = {
+                verdict: "HOLD",
+                reason: "needs operator review",
+                toolCallId: "tc-2",
+            };
+            const server = makeFakeServer();
+            registerJudgeTools(server, makeClient(decision));
+            const result = await server.handlers.get("atbash_judge")({
+                action: "wire $999999",
+                context: "customer request",
+            });
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.verdict).toBe("HOLD");
+            expect(parsed.allow).toBe(false);
+            expect(parsed.reason).toContain("held for operator review");
+            expect(parsed.reason).toContain("Tool Call ID: tc-2");
+        });
+        it("falls back to a bare {action} payload when tool_args_json is absent", async () => {
+            const client = makeClient({ verdict: "ALLOW" });
+            const server = makeFakeServer();
+            registerJudgeTools(server, client);
+            await server.handlers.get("atbash_judge")({ action: "list files", context: "audit" });
+            expect(client.auditToolCall).toHaveBeenCalledWith({
+                toolName: "mcp_judge",
+                args: { action: "list files" },
+                context: "list files — audit",
+            });
+        });
+        it("returns an error content block instead of throwing when the judge is unavailable", async () => {
+            const client = {
+                auditToolCall: vi.fn().mockRejectedValue(new Error("judge unreachable")),
+            };
+            const server = makeFakeServer();
+            registerJudgeTools(server, client);
+            const result = await server.handlers.get("atbash_judge")({
+                action: "x",
+                context: "y",
+            });
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("judge unreachable");
+        });
+    });
+    describe("atbash_check_agent", () => {
+        it("defaults to the server agent's own pubkey when none is given", async () => {
+            const client = makeClient({ verdict: "ALLOW" });
+            client.checkAgentExists.mockResolvedValue(true);
+            const server = makeFakeServer();
+            registerJudgeTools(server, client);
+            const result = await server.handlers.get("atbash_check_agent")({});
+            expect(client.checkAgentExists).toHaveBeenCalledWith("server-agent-pubkey");
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed).toEqual({ registered: true, pubkey: "server-agent-pubkey" });
+        });
+    });
+});

package/dist/tools/queries.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { toErrorContent, toJsonContent } from "../utils.js";
+function defaultMaxCount(value) {
+    return value ?? 20;
+}
+export function registerQueryTools(server, client) {
+    server.registerTool("atbash_get_policy", {
+        description: "Get an agent policy configuration and jail status.",
+        inputSchema: z.object({
+            pubkey: z.string().optional().describe("Agent public key, defaults to the server agent"),
+        }),
+    }, async ({ pubkey }) => {
+        try {
+            return toJsonContent(await client.getAgentPolicy(pubkey ?? client.pubkey));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_agent_detail", {
+        description: "Get agent metadata for a public key.",
+        inputSchema: z.object({
+            pubkey: z.string().optional().describe("Agent public key, defaults to the server agent"),
+        }),
+    }, async ({ pubkey }) => {
+        try {
+            return toJsonContent(await client.getAgentDetail(pubkey ?? client.pubkey));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_tool_calls", {
+        description: "List recent tool calls across all agents.",
+        inputSchema: z.object({
+            max_count: z.number().int().positive().optional().describe("Maximum number of records"),
+        }),
+    }, async ({ max_count }) => {
+        try {
+            return toJsonContent(await client.getToolCalls(defaultMaxCount(max_count)));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_agent_tool_calls", {
+        description: "List recent tool calls for one agent.",
+        inputSchema: z.object({
+            pubkey: z.string().optional().describe("Agent public key, defaults to the server agent"),
+            max_count: z.number().int().positive().optional().describe("Maximum number of records"),
+        }),
+    }, async ({ pubkey, max_count }) => {
+        try {
+            return toJsonContent(await client.getAgentToolCalls(pubkey ?? client.pubkey, defaultMaxCount(max_count)));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_org_tool_calls", {
+        description: "List recent tool calls for an organization.",
+        inputSchema: z.object({
+            org_name: z.string().describe("Organization name"),
+            max_count: z.number().int().positive().optional().describe("Maximum number of records"),
+        }),
+    }, async ({ org_name, max_count }) => {
+        try {
+            return toJsonContent(await client.getOrgToolCalls(org_name, defaultMaxCount(max_count)));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_tool_call_full", {
+        description: "Get the full detail for a single tool call.",
+        inputSchema: z.object({
+            tool_call_id: z.string().describe("Tool call identifier"),
+        }),
+    }, async ({ tool_call_id }) => {
+        try {
+            return toJsonContent(await client.getToolCallFull(tool_call_id));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_tool_call_count", {
+        description: "Get the total number of tool calls on-chain.",
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            return toJsonContent({ count: await client.getToolCallCount() });
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_tier_info", {
+        description: "Get an organization's tier and enforcement information.",
+        inputSchema: z.object({
+            org_name: z.string().describe("Organization name"),
+        }),
+    }, async ({ org_name }) => {
+        try {
+            return toJsonContent(await client.getOrgTierInfo(org_name));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_held_actions", {
+        description: "List actions currently waiting for operator review.",
+        inputSchema: z.object({
+            org_name: z.string().describe("Organization name"),
+            max_count: z.number().int().positive().optional().describe("Maximum number of records"),
+        }),
+    }, async ({ org_name, max_count }) => {
+        try {
+            return toJsonContent(await client.getPendingHeldActions(org_name, defaultMaxCount(max_count)));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_reviews", {
+        description: "List completed operator reviews for held actions.",
+        inputSchema: z.object({
+            org_name: z.string().describe("Organization name"),
+            max_count: z.number().int().positive().optional().describe("Maximum number of records"),
+        }),
+    }, async ({ org_name, max_count }) => {
+        try {
+            return toJsonContent(await client.getHeldActionReviews(org_name, defaultMaxCount(max_count)));
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+    server.registerTool("atbash_get_safety_stats", {
+        description: "Get high-level chain-wide safety statistics.",
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            return toJsonContent(await client.getSafetyStats());
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+}

package/dist/tools/status.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { toErrorContent, toJsonContent } from "../utils.js";
+export function registerStatusTools(server, client) {
+    server.registerTool("atbash_judgment_status", {
+        description: "Poll the status of a previously submitted judgment.",
+        inputSchema: z.object({
+            tool_call_id: z.string().describe("The tool_call_id returned from atbash_judge"),
+            agent_pubkey: z
+                .string()
+                .optional()
+                .describe("Agent public key, defaults to the server agent"),
+        }),
+    }, async ({ tool_call_id, agent_pubkey }) => {
+        try {
+            const status = await client.getJudgmentStatus(tool_call_id, agent_pubkey);
+            return toJsonContent(status);
+        }
+        catch (error) {
+            return toErrorContent(error);
+        }
+    });
+}

package/dist/utils.js

@@ -0,0 +1,17 @@
+export function safeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function toJsonContent(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+export function toErrorContent(error) {
+    return {
+        content: [{ type: "text", text: `Error: ${safeErrorMessage(error)}` }],
+        isError: true,
+    };
+}
+export function truncateText(value, max = 500) {
+    return value.length <= max ? value : `${value.slice(0, max - 3)}...`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atbash/atbash-mcp",
-  "version": "0.1.2",
+  "version": "0.19.1-dev.0",
   "description": "Atbash safety judge exposed as a standalone MCP server",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -32,7 +33,7 @@
     "judge",
     "policy"
   ],
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Atbash-Ai/atbash-mcp-plugin"
@@ -47,13 +48,10 @@
     "release": "node scripts/release.mjs --channel latest",
     "release:dev": "node scripts/release.mjs --channel dev"
   },
-  "peerDependencies": {
-    "@atbash/sdk": ">=0.9.2 <1.0.0"
-  },
   "dependencies": {
-    "@atbash/sdk": ">=0.9.2 <1.0.0",
     "@modelcontextprotocol/sdk": "^1.12.3",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "@atbash/sdk": "0.19.1-dev.0"
   },
   "devDependencies": {
     "@types/node": "^25.7.0",
@@ -61,5 +59,8 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.6"
+  },
+  "peerDependencies": {
+    "@atbash/sdk": "0.19.1-dev.0"
   }
 }