@auctra/mcp-gateway 0.1.8 → 0.1.10

package/README.md

@@ -2,6 +2,8 @@
 
 Stage 0 MCP gateway adapter. Wrap MCP tool calls **and installs** with Auctra **Authority Gate** (`action.execute`) before execution.
 
+**REQUIRE_MCP_GATEWAY:** Production orgs (Startup+) default `require_mcp_gateway=true`. MCP-shaped `action.execute` without this package’s stamp (`auctra_mcp_gateway`) is blocked. Set `AUCTRA_REQUIRE_MCP_GATEWAY=1` for a global fail-closed override.
+
 ```ts
 import { Auctra } from "@auctra/sdk";
 import {
@@ -9,6 +11,7 @@ import {
   gateMcpInstall,
   withAuctraGate,
   declareMcpInstallMetadata,
+  REQUIRE_MCP_GATEWAY,
 } from "@auctra/mcp-gateway";
 
 const client = new Auctra({ apiKey: process.env.AUCTRA_API_KEY! });

package/package.json

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

package/src/index.js

@@ -1,11 +1,27 @@
 import { createHash, createHmac } from "node:crypto";
 
+/** Org/env policy name (SEC-P0-002). */
+export const REQUIRE_MCP_GATEWAY = "REQUIRE_MCP_GATEWAY";
+
+export function mcpGatewayStamp() {
+  return {
+    auctra_mcp_gateway: true,
+    mcp_gateway: true,
+  };
+}
+
+export function requireMcpGateway() {
+  const v = process.env.AUCTRA_REQUIRE_MCP_GATEWAY?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
 export class McpToolBlockedError extends Error {
-  constructor(message, decision, evidence) {
+  constructor(message, decision, evidence, actionDecision = null) {
     super(message);
     this.name = "McpToolBlockedError";
     this.decision = decision;
     this.evidence = evidence;
+    this.actionDecision = actionDecision;
   }
 }
 
@@ -84,6 +100,7 @@ export function declareMcpInstallMetadata(input) {
     hashMcpPackageManifest(input.manifestBody ?? { name, version: input.install.version ?? null });
   const kind = input.install.kind ?? "mcp";
   return {
+    ...mcpGatewayStamp(),
     mcp_install: {
       name,
       ...(input.install.version ? { version: input.install.version } : {}),
@@ -130,7 +147,7 @@ export async function gateMcpInstall(input) {
   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);
+    throw new McpToolBlockedError(message, result.decision, result.evidence, result.action_decision ?? null);
   }
 
   return { ...result, metadata };
@@ -163,6 +180,7 @@ export async function gateMcpToolCall(input) {
       target: `mcp:${input.toolName}`,
       description: `MCP tool ${input.toolName}`,
       metadata: {
+        ...mcpGatewayStamp(),
         inputs: [
           {
             source: `mcp:${input.toolName}:invocation`,
@@ -178,7 +196,7 @@ export async function gateMcpToolCall(input) {
   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);
+    throw new McpToolBlockedError(message, result.decision, result.evidence, result.action_decision ?? null);
   }
 
   const requireLease =
@@ -192,6 +210,7 @@ export async function gateMcpToolCall(input) {
         "execution lease required but action.execute returned none — configure AUCTRA_EXECUTION_LEASE_SECRET",
         "blocked",
         result.evidence,
+        result.action_decision ?? null,
       );
     }
     if (!input.client.executionLease?.consume) {
@@ -200,6 +219,7 @@ export async function gateMcpToolCall(input) {
           "executionLease.consume client method required when AUCTRA_REQUIRE_EXECUTION_LEASE=1",
           "blocked",
           result.evidence,
+          result.action_decision ?? null,
         );
       }
     } else {
@@ -212,6 +232,7 @@ export async function gateMcpToolCall(input) {
           consumed.error ?? "execution lease consume failed",
           "blocked",
           result.evidence,
+          result.action_decision ?? null,
         );
       }
     }

package/src/index.ts

@@ -1,5 +1,24 @@
 import { createHash, createHmac } from "node:crypto";
 
+/**
+ * Org/env policy name — when set, MCP-shaped action.execute must carry the
+ * gateway stamp below (SEC-P0-002). Cloud also honors organization.requireMcpGateway.
+ */
+export const REQUIRE_MCP_GATEWAY = "REQUIRE_MCP_GATEWAY";
+
+/** Metadata stamp proving the call came through @auctra/mcp-gateway. */
+export function mcpGatewayStamp(): Record<string, true> {
+  return {
+    auctra_mcp_gateway: true,
+    mcp_gateway: true,
+  };
+}
+
+export function requireMcpGateway(): boolean {
+  const v = process.env.AUCTRA_REQUIRE_MCP_GATEWAY?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
 export type ExecuteActionClient = {
   action: {
     execute(input: {
@@ -194,6 +213,8 @@ export function declareMcpInstallMetadata(input: {
   issuedAt?: string;
   keyId?: string;
 }): {
+  auctra_mcp_gateway: true;
+  mcp_gateway: true;
   mcp_install: {
     name: string;
     version?: string;
@@ -208,6 +229,8 @@ export function declareMcpInstallMetadata(input: {
     hashMcpPackageManifest(input.manifestBody ?? { name, version: input.install.version ?? null });
   const kind = input.install.kind ?? "mcp";
   return {
+    auctra_mcp_gateway: true as const,
+    mcp_gateway: true as const,
     mcp_install: {
       name,
       ...(input.install.version ? { version: input.install.version } : {}),
@@ -309,6 +332,7 @@ export async function gateMcpToolCall(input: McpToolGateInput) {
       target: `mcp:${input.toolName}`,
       description: `MCP tool ${input.toolName}`,
       metadata: {
+        ...mcpGatewayStamp(),
         inputs: [
           {
             source: `mcp:${input.toolName}:invocation`,