@auctra/mcp-gateway 0.1.4 → 0.1.6

package/README.md

@@ -30,6 +30,24 @@ const sendEmail = withAuctraGate({
 
 Blocked or approval-required tool calls throw `McpToolBlockedError` with the decision evidence hash when present.
 
+## NL→SQL data scope (`gateMcpSqlQuery`)
+
+Declare requested vs authorized query scope so the production gate can emit `SQL_SCOPE_EXCEEDED`:
+
+```ts
+import { gateMcpSqlQuery } from "@auctra/mcp-gateway";
+
+await gateMcpSqlQuery({
+  client,
+  agentId: "agent-uuid",
+  toolName: "customer_query",
+  requestedScope: "customers.*",
+  authorizedScope: "customers.aggregate_metrics",
+  claimedIntentId: intent.id,
+  intentAnchorToken: intent.anchor_token,
+});
+```
+
 ## Engine 15 — MCP / skill install attestation
 
 High-impact installs require `mcp_install` + HMAC `supply_chain_attestation` on the gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auctra/mcp-gateway",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "MCP gateway — gate tool calls and MCP/skill installs through Auctra action.execute",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -181,6 +181,39 @@ export async function gateMcpToolCall(input) {
     throw new McpToolBlockedError(message, result.decision, result.evidence);
   }
 
+  const requireLease = process.env.AUCTRA_REQUIRE_EXECUTION_LEASE === "1";
+  const leaseToken = result.execution_lease?.token;
+  if (requireLease || leaseToken) {
+    if (!leaseToken) {
+      throw new McpToolBlockedError(
+        "execution lease required but action.execute returned none — configure AUCTRA_EXECUTION_LEASE_SECRET",
+        "blocked",
+        result.evidence,
+      );
+    }
+    if (!input.client.executionLease?.consume) {
+      if (requireLease) {
+        throw new McpToolBlockedError(
+          "executionLease.consume client method required when AUCTRA_REQUIRE_EXECUTION_LEASE=1",
+          "blocked",
+          result.evidence,
+        );
+      }
+    } else {
+      const consumed = await input.client.executionLease.consume({
+        lease: leaseToken,
+        expectedActionType: resolveActionType(input),
+      });
+      if (!consumed.ok) {
+        throw new McpToolBlockedError(
+          consumed.error ?? "execution lease consume failed",
+          "blocked",
+          result.evidence,
+        );
+      }
+    }
+  }
+
   return result;
 }
 

package/src/index.ts

@@ -18,6 +18,12 @@ export type ExecuteActionClient = {
       decision: "allowed" | "blocked" | "require_approval";
       reason: string;
       action_request_id?: string;
+      execution_lease?: {
+        token: string;
+        expires_at: string;
+        action_request_id: string;
+        action_type: string;
+      } | null;
       evidence?: {
         format: string;
         payload_hash: string;
@@ -26,6 +32,13 @@ export type ExecuteActionClient = {
       evidence_payload?: { evidence_id?: string };
     }>;
   };
+  /** Optional — required when AUCTRA_REQUIRE_EXECUTION_LEASE=1 */
+  executionLease?: {
+    consume(input: {
+      lease: string;
+      expectedActionType?: string;
+    }): Promise<{ ok: boolean; error?: string; reason_codes?: string[] }>;
+  };
 };
 
 /** @deprecated Use ExecuteActionClient — kept as type alias for migration notes only */
@@ -314,6 +327,39 @@ export async function gateMcpToolCall(input: McpToolGateInput) {
     throw new McpToolBlockedError(message, result.decision, result.evidence);
   }
 
+  const requireLease = process.env.AUCTRA_REQUIRE_EXECUTION_LEASE === "1";
+  const leaseToken = result.execution_lease?.token;
+  if (requireLease || leaseToken) {
+    if (!leaseToken) {
+      throw new McpToolBlockedError(
+        "execution lease required but action.execute returned none — configure AUCTRA_EXECUTION_LEASE_SECRET",
+        "blocked",
+        result.evidence,
+      );
+    }
+    if (!input.client.executionLease?.consume) {
+      if (requireLease) {
+        throw new McpToolBlockedError(
+          "executionLease.consume client method required when AUCTRA_REQUIRE_EXECUTION_LEASE=1",
+          "blocked",
+          result.evidence,
+        );
+      }
+    } else {
+      const consumed = await input.client.executionLease.consume({
+        lease: leaseToken,
+        expectedActionType: resolveActionType(input),
+      });
+      if (!consumed.ok) {
+        throw new McpToolBlockedError(
+          consumed.error ?? "execution lease consume failed",
+          "blocked",
+          result.evidence,
+        );
+      }
+    }
+  }
+
   return result;
 }
 
@@ -349,3 +395,62 @@ export function withAuctraGate<TArgs extends Record<string, unknown>, TResult>(
     };
   };
 }
+
+/**
+ * Gate an NL→SQL / database tool call with declared data scope metadata.
+ * Production path: same action.execute gate companies use — requested ⊆ authorized.
+ */
+export async function gateMcpSqlQuery(input: {
+  client: ExecuteActionClient;
+  agentId: string;
+  toolName: string;
+  requestedScope: string | string[];
+  authorizedScope?: string | string[];
+  args?: Record<string, unknown>;
+  actionType?: string;
+  claimedIntentId?: string;
+  intentAnchorToken?: string;
+}) {
+  const result = await input.client.action.execute({
+    agentId: input.agentId,
+    actionType: input.actionType ?? "execute_sql",
+    claimedIntentId: input.claimedIntentId,
+    intentAnchorToken: input.intentAnchorToken,
+    payload: {
+      tool: input.toolName,
+      arguments: input.args ?? {},
+      resource: Array.isArray(input.requestedScope)
+        ? input.requestedScope[0]
+        : input.requestedScope,
+    },
+    action: {
+      target: `mcp-sql:${input.toolName}`,
+      description: `SQL/query tool ${input.toolName}`,
+      metadata: {
+        sql: {
+          requested_scope: input.requestedScope,
+          ...(input.authorizedScope != null
+            ? { authorized_scope: input.authorizedScope }
+            : {}),
+        },
+        inputs: [
+          {
+            source: `mcp:${input.toolName}:sql`,
+            source_type: "mcp_tool_response",
+            trust_level: "untrusted",
+            authority: "none",
+            claimed_influence: "privilege_escalation",
+          },
+        ],
+      },
+    },
+  });
+
+  if (result.decision !== "allowed") {
+    const evidenceId = evidenceIdFromResult(result);
+    const message = evidenceId ? `${result.reason} (evidence: ${evidenceId})` : result.reason;
+    throw new McpToolBlockedError(message, result.decision, result.evidence);
+  }
+
+  return result;
+}