@astrasyncai/verification-gateway 3.0.0 → 3.1.0

package/dist/adapters/mcp.d.mts

@@ -1,5 +1,5 @@
 import { Request, Response, RequestHandler } from 'express';
-import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-B3USs-Kx.mjs';
+import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-Cuh7ELfr.mjs';
 
 /**
  * MCP server-side helpers — companion to `transport/mcp.ts` (which handles the
@@ -137,7 +137,7 @@ interface McpPdlssMapping {
     action: string;
     resource: string;
     purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
-    actionSource: 'header' | 'meta' | 'tool_argument' | 'transport_layer';
+    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer';
 }
 /**
  * v2.5.0 — PDLSS field derivation for MCP requests.
@@ -149,14 +149,18 @@ interface McpPdlssMapping {
  * Resource precedence:
  *   - `toolGate.resource` if provided, else `requestPath`.
  *
- * Action precedence (unchanged from v2.4.14):
- *   - header → body `_meta` → body `arguments` → bare tool name / method.
+ * Action precedence (3.1.0, Bug 14 §4.6 — toolGate override added for
+ * symmetry with purpose):
+ *   - `toolGate.action` authoritative → header → body `_meta` → body
+ *     `arguments` → bare tool name / method (transport_layer, unchanged —
+ *     bare tool names are legitimate enumerated actions, never aliased).
  *
  * @param requestPath  The HTTP request path (e.g. '/mcp'). Required.
  * @param toolGate     Resolved per-tool config from `toolGates`, if present.
  */
 declare function mcpToPdlss(parsed: ParsedMcpRequest, requestPath: string, headerPurpose?: string, headerAction?: string, toolGate?: {
     purpose?: string;
+    action?: string;
     resource?: string;
 }): McpPdlssMapping;
 /**
@@ -234,18 +238,25 @@ declare global {
     }
 }
 /**
- * Extended per-tool gate with optional PDLSS purpose + resource overrides.
+ * Extended per-tool gate with optional PDLSS purpose + action + resource
+ * overrides.
  *
  * When `purpose` is set, it is authoritative for that tool — the agent's
  * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
  * semantic purpose each tool fulfils rather than trusting agent self-declaration.
  *
+ * When `action` is set (Bug 14, §4.6 — symmetric with `purpose`), it is
+ * authoritative over `X-Astra-Action` / body declarations, letting the
+ * merchant pin a dotted-verb action (e.g. `shopping.search`) for a tool
+ * whose callers would otherwise fall to the bare tool-name transport default.
+ *
  * When `resource` is set, it overrides the default (`req.path`) for that
  * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
  */
 interface ToolGateConfig {
     minAccessLevel: AccessLevel;
     purpose?: string;
+    action?: string;
     resource?: string;
 }
 interface McpMiddlewareOptions extends GatewayConfig {
@@ -258,10 +269,12 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * toolGates: {
      *   browse_catalog: 'read-only',                // shorthand
      *   list_products:  { minAccessLevel: 'none',    // full shape
-     *                     purpose: 'shopping.search',
+     *                     purpose: 'shopping',
+     *                     action: 'shopping.search',
      *                     resource: '/api/catalog' },
      *   start_checkout: { minAccessLevel: 'standard',
-     *                     purpose: 'shopping.purchase',
+     *                     purpose: 'shopping',
+     *                     action: 'shopping.purchase',
      *                     resource: '/api/checkout/*' },
      * }
      * ```

package/dist/adapters/mcp.d.ts

@@ -1,5 +1,5 @@
 import { Request, Response, RequestHandler } from 'express';
-import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-B3USs-Kx.js';
+import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-Cuh7ELfr.js';
 
 /**
  * MCP server-side helpers — companion to `transport/mcp.ts` (which handles the
@@ -137,7 +137,7 @@ interface McpPdlssMapping {
     action: string;
     resource: string;
     purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
-    actionSource: 'header' | 'meta' | 'tool_argument' | 'transport_layer';
+    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer';
 }
 /**
  * v2.5.0 — PDLSS field derivation for MCP requests.
@@ -149,14 +149,18 @@ interface McpPdlssMapping {
  * Resource precedence:
  *   - `toolGate.resource` if provided, else `requestPath`.
  *
- * Action precedence (unchanged from v2.4.14):
- *   - header → body `_meta` → body `arguments` → bare tool name / method.
+ * Action precedence (3.1.0, Bug 14 §4.6 — toolGate override added for
+ * symmetry with purpose):
+ *   - `toolGate.action` authoritative → header → body `_meta` → body
+ *     `arguments` → bare tool name / method (transport_layer, unchanged —
+ *     bare tool names are legitimate enumerated actions, never aliased).
  *
  * @param requestPath  The HTTP request path (e.g. '/mcp'). Required.
  * @param toolGate     Resolved per-tool config from `toolGates`, if present.
  */
 declare function mcpToPdlss(parsed: ParsedMcpRequest, requestPath: string, headerPurpose?: string, headerAction?: string, toolGate?: {
     purpose?: string;
+    action?: string;
     resource?: string;
 }): McpPdlssMapping;
 /**
@@ -234,18 +238,25 @@ declare global {
     }
 }
 /**
- * Extended per-tool gate with optional PDLSS purpose + resource overrides.
+ * Extended per-tool gate with optional PDLSS purpose + action + resource
+ * overrides.
  *
  * When `purpose` is set, it is authoritative for that tool — the agent's
  * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
  * semantic purpose each tool fulfils rather than trusting agent self-declaration.
  *
+ * When `action` is set (Bug 14, §4.6 — symmetric with `purpose`), it is
+ * authoritative over `X-Astra-Action` / body declarations, letting the
+ * merchant pin a dotted-verb action (e.g. `shopping.search`) for a tool
+ * whose callers would otherwise fall to the bare tool-name transport default.
+ *
  * When `resource` is set, it overrides the default (`req.path`) for that
  * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
  */
 interface ToolGateConfig {
     minAccessLevel: AccessLevel;
     purpose?: string;
+    action?: string;
     resource?: string;
 }
 interface McpMiddlewareOptions extends GatewayConfig {
@@ -258,10 +269,12 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * toolGates: {
      *   browse_catalog: 'read-only',                // shorthand
      *   list_products:  { minAccessLevel: 'none',    // full shape
-     *                     purpose: 'shopping.search',
+     *                     purpose: 'shopping',
+     *                     action: 'shopping.search',
      *                     resource: '/api/catalog' },
      *   start_checkout: { minAccessLevel: 'standard',
-     *                     purpose: 'shopping.purchase',
+     *                     purpose: 'shopping',
+     *                     action: 'shopping.purchase',
      *                     resource: '/api/checkout/*' },
      * }
      * ```

package/dist/adapters/mcp.js

@@ -51,7 +51,7 @@ function hasMinimumAccess(actual, required) {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.0.0";
+var SDK_VERSION = "3.1.0";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -677,7 +677,10 @@ function mcpToPdlss(parsed, requestPath, headerPurpose, headerAction, toolGate)
   }
   let action;
   let actionSource;
-  if (headerAction) {
+  if (toolGate?.action !== void 0) {
+    action = toolGate.action;
+    actionSource = "tool_gate";
+  } else if (headerAction) {
     action = headerAction;
     actionSource = "header";
   } else if (parsed.actionFromBody && parsed.actionSourceFromBody) {
@@ -851,7 +854,7 @@ function createMcpMiddleware(options) {
         req.path,
         headerPurpose,
         headerAction,
-        gate ? { purpose: gate.purpose, resource: gate.resource } : void 0
+        gate ? { purpose: gate.purpose, action: gate.action, resource: gate.resource } : void 0
       );
       if (config.debug) {
         console.debug("[mcp-middleware] pdlss resolved", {