@auctra/mcp-gateway 0.1.11 → 0.1.13

package/README.md

@@ -4,6 +4,8 @@ Stage 0 MCP gateway adapter. Wrap MCP tool calls **and installs** with Auctra **
 
 **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.
 
+**Before the gateway:** register the agent with a sponsor, issue authority for the tool's action type, and `createIntent`. Pass `claimedIntentId` and `intentAnchorToken`. A payment-shaped tool also needs provenance on the execute metadata. The full field list is `docs/onboarding/quick-start.md`. ALLOW still does not run the tool until the lease is consumed.
+
 ```ts
 import { Auctra } from "@auctra/sdk";
 import {
@@ -21,6 +23,8 @@ await gateMcpToolCall({
   agentId: "agent-uuid",
   toolName: "send_email",
   args: { to: "vendor@example.com" },
+  claimedIntentId: "intent-uuid",
+  intentAnchorToken: "anchor-token-from-createIntent",
 });
 
 const sendEmail = withAuctraGate({

package/package.json

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

package/src/index.js

@@ -29,6 +29,55 @@ function resolveActionType(input) {
   return input.actionType ?? input.actionTypeMap?.[input.toolName] ?? "execute_tool";
 }
 
+function isSupportedProductionConfig() {
+  if (process.env.NODE_ENV === "production") return true;
+  return Boolean(process.env.AUCTRA_EXECUTION_LEASE_SECRET?.trim());
+}
+
+/**
+ * Lab/dev escape only. Ignored when NODE_ENV=production or
+ * AUCTRA_EXECUTION_LEASE_SECRET is set — those are supported production signals.
+ */
+export function allowMcpWithoutLease() {
+  if (isSupportedProductionConfig()) return false;
+  const v = process.env.AUCTRA_ALLOW_MCP_WITHOUT_LEASE?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
+async function assertConsumedExecutionLease(input, result) {
+  if (allowMcpWithoutLease()) return;
+  const leaseToken = result.execution_lease?.token;
+  if (!leaseToken) {
+    throw new McpToolBlockedError(
+      "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) {
+    throw new McpToolBlockedError(
+      "executionLease.consume client method required after ALLOW",
+      "blocked",
+      result.evidence,
+      result.action_decision ?? null,
+    );
+  }
+  const consumed = await input.client.executionLease.consume({
+    lease: leaseToken,
+    expectedActionType: resolveActionType(input),
+    expectedRequestFingerprint: result.execution_lease?.request_fingerprint,
+  });
+  if (!consumed.ok) {
+    throw new McpToolBlockedError(
+      consumed.error ?? "execution lease consume failed",
+      "blocked",
+      result.evidence,
+      result.action_decision ?? null,
+    );
+  }
+}
+
 function evidenceIdFromResult(result) {
   return result.evidence_payload?.evidence_id ?? result.action_request_id ?? null;
 }
@@ -199,45 +248,9 @@ export async function gateMcpToolCall(input) {
     throw new McpToolBlockedError(message, result.decision, result.evidence, result.action_decision ?? null);
   }
 
-  const requireLease =
-    process.env.AUCTRA_REQUIRE_EXECUTION_LEASE === "1" ||
-    (process.env.NODE_ENV === "production" &&
-      Boolean(process.env.AUCTRA_EXECUTION_LEASE_SECRET?.trim()));
-  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,
-        result.action_decision ?? null,
-      );
-    }
-    if (!input.client.executionLease?.consume) {
-      if (requireLease) {
-        throw new McpToolBlockedError(
-          "executionLease.consume client method required when AUCTRA_REQUIRE_EXECUTION_LEASE=1",
-          "blocked",
-          result.evidence,
-          result.action_decision ?? null,
-        );
-      }
-    } else {
-      const consumed = await input.client.executionLease.consume({
-        lease: leaseToken,
-        expectedActionType: resolveActionType(input),
-        expectedRequestFingerprint: result.execution_lease?.request_fingerprint,
-      });
-      if (!consumed.ok) {
-        throw new McpToolBlockedError(
-          consumed.error ?? "execution lease consume failed",
-          "blocked",
-          result.evidence,
-          result.action_decision ?? null,
-        );
-      }
-    }
-  }
+  // Default fail-closed (P5-F-007). AUCTRA_REQUIRE_EXECUTION_LEASE remains a
+  // recognized alias; AUCTRA_ALLOW_MCP_WITHOUT_LEASE=1 is the only opt-out.
+  await assertConsumedExecutionLease(input, result);
 
   return result;
 }

package/src/index.ts

@@ -52,7 +52,7 @@ export type ExecuteActionClient = {
       evidence_payload?: { evidence_id?: string };
     }>;
   };
-  /** Optional — required when AUCTRA_REQUIRE_EXECUTION_LEASE=1 */
+  /** Required after ALLOW. Lab opt-out is ignored in supported production configs. */
   executionLease?: {
     consume(input: {
       lease: string;
@@ -123,6 +123,55 @@ function resolveActionType(input: McpToolGateInput) {
   return input.actionType ?? input.actionTypeMap?.[input.toolName] ?? "execute_tool";
 }
 
+function isSupportedProductionConfig(): boolean {
+  if (process.env.NODE_ENV === "production") return true;
+  return Boolean(process.env.AUCTRA_EXECUTION_LEASE_SECRET?.trim());
+}
+
+/**
+ * Lab/dev escape only. Ignored when NODE_ENV=production or
+ * AUCTRA_EXECUTION_LEASE_SECRET is set — those are supported production signals.
+ */
+export function allowMcpWithoutLease(): boolean {
+  if (isSupportedProductionConfig()) return false;
+  const v = process.env.AUCTRA_ALLOW_MCP_WITHOUT_LEASE?.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
+async function assertConsumedExecutionLease(
+  input: McpToolGateInput,
+  result: Awaited<ReturnType<ExecuteActionClient["action"]["execute"]>>,
+) {
+  if (allowMcpWithoutLease()) return;
+  const leaseToken = result.execution_lease?.token;
+  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) {
+    throw new McpToolBlockedError(
+      "executionLease.consume client method required after ALLOW",
+      "blocked",
+      result.evidence,
+    );
+  }
+  const consumed = await input.client.executionLease.consume({
+    lease: leaseToken,
+    expectedActionType: resolveActionType(input),
+    expectedRequestFingerprint: result.execution_lease?.request_fingerprint,
+  });
+  if (!consumed.ok) {
+    throw new McpToolBlockedError(
+      consumed.error ?? "execution lease consume failed",
+      "blocked",
+      result.evidence,
+    );
+  }
+}
+
 function evidenceIdFromResult(
   result: Awaited<ReturnType<ExecuteActionClient["action"]["execute"]>>,
 ) {
@@ -353,42 +402,9 @@ export async function gateMcpToolCall(input: McpToolGateInput) {
     throw new McpToolBlockedError(message, result.decision, result.evidence);
   }
 
-  const requireLease =
-    process.env.AUCTRA_REQUIRE_EXECUTION_LEASE === "1" ||
-    (process.env.NODE_ENV === "production" &&
-      Boolean(process.env.AUCTRA_EXECUTION_LEASE_SECRET?.trim()));
-  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),
-        expectedRequestFingerprint: result.execution_lease?.request_fingerprint,
-      });
-      if (!consumed.ok) {
-        throw new McpToolBlockedError(
-          consumed.error ?? "execution lease consume failed",
-          "blocked",
-          result.evidence,
-        );
-      }
-    }
-  }
+  // Default fail-closed (P5-F-007). AUCTRA_REQUIRE_EXECUTION_LEASE remains a
+  // recognized alias; AUCTRA_ALLOW_MCP_WITHOUT_LEASE=1 is the only opt-out.
+  await assertConsumedExecutionLease(input, result);
 
   return result;
 }