@auctra/mcp-gateway 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # @auctra/mcp-gateway
 
-Stage 0 MCP gateway adapter. Wrap MCP tool calls with Auctra `action.execute` before execution.
+Stage 0 MCP gateway adapter. Wrap MCP tool calls with Auctra **Authority Gate** (`action.execute`) before execution.
 
 ```ts
 import { Auctra } from "@auctra/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auctra/mcp-gateway",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Stage 0 MCP gateway adapter — gate MCP tool calls through Auctra action.execute",
   "type": "module",
   "main": "./src/index.js",
@@ -35,5 +35,8 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0"
   }
 }

package/src/index.js

@@ -1,3 +1,5 @@
+import { createHash, createHmac } from "node:crypto";
+
 export class McpToolBlockedError extends Error {
   constructor(message, decision, evidence) {
     super(message);
@@ -15,6 +17,34 @@ function evidenceIdFromResult(result) {
   return result.evidence_payload?.evidence_id ?? result.action_request_id ?? null;
 }
 
+/** Stable sha256 of a tool response body for provenance + attestation. */
+export function hashToolResponseBody(body) {
+  const payload = typeof body === "string" ? body : JSON.stringify(body ?? null);
+  return `sha256:${createHash("sha256").update(payload).digest("hex")}`;
+}
+
+/**
+ * HMAC-sign a tool response content hash (Business+).
+ * Must match Auctra gate evaluateToolAttestation.
+ */
+export function signToolResponseAttestation(input) {
+  const issuedAt = input.issuedAt ?? new Date().toISOString();
+  const contentHash = input.contentHash.trim();
+  const toolName = input.toolName.trim();
+  const key = `${input.secret}:${input.organizationId}`;
+  const signature = createHmac("sha256", key)
+    .update(`${toolName}\n${contentHash}\n${issuedAt}`)
+    .digest("hex");
+  return {
+    content_hash: contentHash,
+    tool_name: toolName,
+    issued_at: issuedAt,
+    signature,
+    alg: "hmac-sha256",
+    key_id: input.keyId ?? "org-default",
+  };
+}
+
 /** Provenance for a tool/MCP result — attach on the next consequential action.execute. */
 export function declareToolResponseInput(input) {
   return {
@@ -66,6 +96,22 @@ export async function gateMcpToolCall(input) {
 export function withAuctraGate(input) {
   return async (args) => {
     await gateMcpToolCall({ ...input, args });
-    return input.execute(args);
+    const result = await input.execute(args);
+    if (!input.attestation) return result;
+    const contentHash = hashToolResponseBody(result);
+    const tool_attestation = signToolResponseAttestation({
+      organizationId: input.attestation.organizationId,
+      toolName: input.toolName,
+      contentHash,
+      secret: input.attestation.secret,
+    });
+    return {
+      result,
+      provenance: declareToolResponseInput({
+        toolName: input.toolName,
+        contentHash,
+      }),
+      tool_attestation,
+    };
   };
 }

package/src/index.ts

@@ -1,3 +1,5 @@
+import { createHash, createHmac } from "node:crypto";
+
 export type ExecuteActionClient = {
   action: {
     execute(input: {
@@ -42,6 +44,15 @@ export type McpToolGateInput = {
   intentAnchorToken?: string;
 };
 
+export type ToolAttestation = {
+  content_hash: string;
+  tool_name: string;
+  issued_at: string;
+  signature: string;
+  alg: "hmac-sha256";
+  key_id?: string;
+};
+
 export class McpToolBlockedError extends Error {
   readonly decision: "blocked" | "require_approval";
   readonly evidence?: Awaited<ReturnType<ExecuteActionClient["action"]["execute"]>>["evidence"];
@@ -68,6 +79,42 @@ function evidenceIdFromResult(
   return result.evidence_payload?.evidence_id ?? result.action_request_id ?? null;
 }
 
+/** Stable sha256 of a tool response body for provenance + attestation. */
+export function hashToolResponseBody(body: unknown): string {
+  const payload = typeof body === "string" ? body : JSON.stringify(body ?? null);
+  return `sha256:${createHash("sha256").update(payload).digest("hex")}`;
+}
+
+/**
+ * HMAC-sign a tool response content hash (Business+).
+ * Must match Auctra gate `signToolResponseAttestation` / `evaluateToolAttestation`.
+ */
+export function signToolResponseAttestation(input: {
+  organizationId: string;
+  toolName: string;
+  contentHash: string;
+  /** Org attestation secret (same value configured as TOOL_ATTESTATION_SECRET on Auctra). */
+  secret: string;
+  issuedAt?: string;
+  keyId?: string;
+}): ToolAttestation {
+  const issuedAt = input.issuedAt ?? new Date().toISOString();
+  const contentHash = input.contentHash.trim();
+  const toolName = input.toolName.trim();
+  const key = `${input.secret}:${input.organizationId}`;
+  const signature = createHmac("sha256", key)
+    .update(`${toolName}\n${contentHash}\n${issuedAt}`)
+    .digest("hex");
+  return {
+    content_hash: contentHash,
+    tool_name: toolName,
+    issued_at: issuedAt,
+    signature,
+    alg: "hmac-sha256",
+    key_id: input.keyId ?? "org-default",
+  };
+}
+
 /**
  * Provenance for a tool/MCP result — attach on the *next* consequential
  * action.execute so Engine 03 treats the output as untrusted evidence.
@@ -128,10 +175,31 @@ export async function gateMcpToolCall(input: McpToolGateInput) {
 export function withAuctraGate<TArgs extends Record<string, unknown>, TResult>(
   input: McpToolGateInput & {
     execute: (args: TArgs) => Promise<TResult> | TResult;
+    /** When set with organizationId, HMAC-attest the tool response body (Business+). */
+    attestation?: {
+      organizationId: string;
+      secret: string;
+    };
   },
 ) {
   return async (args: TArgs) => {
     await gateMcpToolCall({ ...input, args });
-    return input.execute(args);
+    const result = await input.execute(args);
+    if (!input.attestation) return result;
+    const contentHash = hashToolResponseBody(result);
+    const tool_attestation = signToolResponseAttestation({
+      organizationId: input.attestation.organizationId,
+      toolName: input.toolName,
+      contentHash,
+      secret: input.attestation.secret,
+    });
+    return {
+      result,
+      provenance: declareToolResponseInput({
+        toolName: input.toolName,
+        contentHash,
+      }),
+      tool_attestation,
+    };
   };
 }