@auctra/mcp-gateway 0.1.4 → 0.1.5

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.5",
   "description": "MCP gateway — gate tool calls and MCP/skill installs through Auctra action.execute",
   "type": "module",
   "main": "./src/index.js",

package/src/index.ts

@@ -349,3 +349,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;
+}