@astrasyncai/verification-gateway 5.4.0 → 5.4.2

package/dist/adapters/mcp.d.ts

@@ -1,4 +1,396 @@
-import 'express';
-import '../types-76TB0fxW.js';
-export { M as MCP_VERIFIED_HOP_HEADER, b as McpMiddlewareOptions, P as ParsedMcpRequest, T as ToolGate, c as ToolGateConfig, d as createMcpMiddleware, i as isVerifiedHopValidFor, m as mcpDefaultEnforced, e as mcpToPdlss, p as parseMcpJsonRpc, f as parseVerifiedHop, s as serializeVerifiedHop } from '../mcp-OrVOrH-s.js';
-import '../metadata-capture.js';
+import { Request, Response, RequestHandler } from 'express';
+import { d as VerificationResult, G as GatewayConfig } from '../types-BU04qAAR.js';
+
+/**
+ * X-Astra-Verified-Hop — cross-hop verify-access dedupe marker.
+ *
+ * Header carrying upstream verify-access proof so an inner-hop endpoint can
+ * dedupe (skip verify-access when the same ASTRA-id was already verified a
+ * few ms earlier). Emitted by the MCP adapter toward tool fetches and by the
+ * edge gateway toward the origin at authenticate/authorize depth. Value
+ * format:
+ *
+ *   {astraId};{sessionId};{checkedAt-ms}
+ *
+ * Receivers MUST validate that `checkedAt` is recent (≤ 60s window
+ * recommended) and that `astraId` matches the agent identity claimed on the
+ * inner hop. The header alone is NOT proof-of-identity — it's an UNSIGNED
+ * dedupe advisory: trust it (`trustVerifiedHop`) only where every network
+ * path to the inner hop crosses a stripping gateway or an equivalent trusted
+ * boundary, exactly like the unsigned X-AstraSync-* attestation headers.
+ * Pair with the existing X-Astra-Id auth.
+ */
+declare const MCP_VERIFIED_HOP_HEADER = "X-Astra-Verified-Hop";
+interface VerifiedHopMarker {
+    astraId: string;
+    sessionId?: string;
+    checkedAt: number;
+}
+declare function serializeVerifiedHop(marker: VerifiedHopMarker): string;
+declare function parseVerifiedHop(value: string | undefined | null): VerifiedHopMarker | null;
+/**
+ * Returns true when `marker.astraId` matches the inner-hop's claimed
+ * ASTRA-id AND the marker is recent enough. Inner-hop middleware uses this
+ * to skip a duplicate verify-access call.
+ */
+declare function isVerifiedHopValidFor(marker: VerifiedHopMarker | null, expectedAstraId: string, opts?: {
+    maxAgeMs?: number;
+    now?: number;
+}): boolean;
+
+/**
+ * MCP server-side helpers — companion to `transport/mcp.ts` (which handles the
+ * agent-side `_meta.astrasync` block).
+ *
+ * Surfaces a body-aware policy hook the existing `createMiddleware` couldn't
+ * provide — MCP traffic is JSON-RPC over a single endpoint (`/mcp`), so the
+ * default route-pattern gating is too coarse: every request looks the same
+ * URL-wise, but `initialize` is low-risk handshake while `tools/call` of a
+ * payment tool is high-risk. Cohort-3 beta merchants flagged this 🟡 in the
+ * v2.9.5 round.
+ *
+ * What lives here:
+ *   - `parseMcpJsonRpc(body)`    — peels JSON-RPC method + tool name + agent
+ *                                   id without committing to a particular MCP
+ *                                   server framework.
+ *   - `mcpToPdlss(parsed)`       — canonical mapping JSON-RPC method → PDLSS
+ *                                   purpose / action / resource. Doc-stable
+ *                                   so audits can correlate.
+ *   - `mcpDefaultEnforced(parsed)` — whether a method is enforced by default
+ *                                   so a single MCP middleware can split
+ *                                   `initialize` / `tools/list` (pass-through)
+ *                                   from `tools/call` (enforced).
+ *   - `MCP_VERIFIED_HOP_HEADER`   — header convention for the dedupe pattern
+ *                                   when an MCP tool calls an inner REST hop.
+ *   - `serialize/parseVerifiedHop` helpers.
+ *
+ * The Express MCP adapter is in `adapters/mcp.ts` and consumes these.
+ */
+
+/**
+ * Output of `parseMcpJsonRpc`. Self-describing so the middleware doesn't have
+ * to re-introspect the body to figure out gating.
+ */
+interface ParsedMcpRequest {
+    /** JSON-RPC method (e.g. `tools/call`, `initialize`, `tools/list`). */
+    method: string;
+    /** Set when method === 'tools/call'; the tool name from `params.name`. */
+    toolName?: string;
+    /** Initialize-specific protocolVersion handshake info, when present. */
+    protocolVersion?: string;
+    /**
+     * Agent id read from the body, in priority order:
+     *   1. `params._meta.astrasync.agentId` (the canonical SDK location, see
+     *      `transport/mcp.ts → setMcpMeta`)
+     *   2. `params.arguments.agent_id` (legacy / hand-written tool callers)
+     * Header-supplied id (X-Astra-Id) is read separately by the adapter and
+     * compared to this for the mismatch check.
+     */
+    agentIdFromBody?: string;
+    /**
+     * Purpose extracted from the MCP body
+     * with the symmetric precedence chain. Sourced from `_meta.astrasync.purpose`
+     * (canonical SDK location) OR `params.arguments.purpose` (legacy /
+     * conventional callers). The discriminator is on `purposeSourceFromBody`.
+     * Adapter combines this with the `X-Astra-Purpose` header (header wins)
+     * before mapping; final fallback at `mcpToPdlss` is `undefined`.
+     */
+    purposeFromBody?: string;
+    /** Which body location resolved `purposeFromBody`. */
+    purposeSourceFromBody?: 'meta' | 'tool_argument';
+    /**
+     * Action extracted from the MCP body with the same
+     * symmetric chain as purpose. Sourced from `_meta.astrasync.action`
+     * (canonical) OR `params.arguments.action` (legacy). Adapter combines
+     * with the `X-Astra-Action` header (header wins) before mapping; final
+     * fallback at `mcpToPdlss` is the transport-layer default
+     * (`tools/call:<toolname>` or just `<method>`).
+     */
+    actionFromBody?: string;
+    /** Which body location resolved `actionFromBody`. */
+    actionSourceFromBody?: 'meta' | 'tool_argument';
+    /** True for handshake methods that must succeed before any tool call. */
+    isInitialize: boolean;
+    /** True for `tools/call`. */
+    isToolCall: boolean;
+    /** True for low-risk introspection (`tools/list`, `prompts/list`, etc.). */
+    isIntrospection: boolean;
+}
+/**
+ * Peel the JSON-RPC envelope. Returns `null` if the body isn't a JSON-RPC
+ * request (callers can short-circuit with a 400 or treat as untyped traffic).
+ *
+ * Accepts both single-request and notification shapes. Batch requests are
+ * NOT supported here — the verify-access contract is single-agent-per-call;
+ * a batch body should be split before policy gating.
+ */
+declare function parseMcpJsonRpc(body: unknown): ParsedMcpRequest | null;
+/**
+ * PDLSS mapping for an MCP request. The platform's PDLSS taxonomy is
+ * `purpose / action / resource`; for MCP traffic the audit-useful dimensions
+ * are the JSON-RPC method and (for `tools/call`) the tool name.
+ *
+ * v2.5.0 rules:
+ *   - `resource` defaults to the HTTP request path (e.g. `/mcp`). Per-tool
+ *     overrides via `toolGates` config let merchants map tools to specific
+ *     backend resources (e.g. `/api/catalog`).
+ *   - `purpose` defaults to `undefined` (backend evaluator applies
+ *     skip-when-undefined). Per-tool overrides via `toolGates` config let
+ *     merchants declare the semantic purpose each tool fulfils.
+ *   - `action` comes only from declarations (toolGate config, header, or
+ *     body). For `tools/call` with none declared it is `undefined` —
+ *     evaluation is purpose-only, because a raw tool name is a transport
+ *     token, not a PDLSS action, and sending it as one guarantees an
+ *     action-policy mismatch. For other JSON-RPC methods the method string
+ *     is used.
+ */
+interface McpPdlssMapping {
+    purpose: string | undefined;
+    /**
+     * `undefined` when a `tools/call` request declared no action anywhere —
+     * the verify-access call then evaluates purpose-only. Tool names never
+     * travel as PDLSS actions.
+     */
+    action: string | undefined;
+    resource: string;
+    purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
+    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer' | undefined;
+}
+/**
+ * v2.5.0 — PDLSS field derivation for MCP requests.
+ *
+ * Purpose precedence:
+ *   - If `toolGate.purpose` is provided, it is authoritative (header/body ignored).
+ *   - Otherwise: header → body `_meta` → body `arguments` → `undefined`.
+ *
+ * Resource precedence:
+ *   - `toolGate.resource` if provided, else `requestPath`.
+ *
+ * Action precedence (3.1.0 — toolGate override added for
+ * symmetry with purpose; 4.1.0 — the bare-tool-name fallback for
+ * `tools/call` was removed):
+ *   - `toolGate.action` authoritative → header → body `_meta` → body
+ *     `arguments` → then: `undefined` for `tools/call` (purpose-only
+ *     evaluation — tool names are transport tokens, never PDLSS actions),
+ *     or the JSON-RPC method string for other methods (transport_layer).
+ *
+ * @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;
+/**
+ * Whether a method is enforced (calls verify-access + gates on the server
+ * decision) by default. The MCP middleware uses this to split low-risk
+ * handshake / introspection traffic (pass-through) from high-risk tool
+ * execution (enforced). Per-tool / per-method overrides win over this default.
+ *
+ *   - `initialize` / `notifications/initialized`        → false (handshake must work for unregistered probes)
+ *   - `tools/list` / `prompts/list` / `resources/list`  → false (introspection is public-surface)
+ *   - `ping`                                            → false
+ *   - `resources/read`                                  → true
+ *   - `tools/call`                                      → true  (default — overridable per-tool)
+ *   - everything else                                   → true  (least-privilege fallback)
+ */
+declare function mcpDefaultEnforced(parsed: ParsedMcpRequest): boolean;
+
+/**
+ * AstraSync Universal Verification Gateway — MCP middleware
+ *
+ * Express-shaped middleware tailored to the JSON-RPC body of an MCP
+ * (Model Context Protocol) endpoint. Closes the cohort-3 gaps the default
+ * `createMiddleware` couldn't:
+ *
+ *   (a) **Body-aware gating**.  All MCP traffic targets the same `/mcp` URL.
+ *       The default route-pattern matcher can't tell `initialize` (low risk)
+ *       from `tools/call start_checkout` (high risk). This middleware peels
+ *       the JSON-RPC body and applies a per-method risk tier.
+ *
+ *   (b) **PDLSS mapping**.  Derives purpose, action, and resource from
+ *       `toolGates` config and request context. See `transport/mcp-server.ts`
+ *       `mcpToPdlss()` for the exact mapping.
+ *
+ *   (c) **Inner-hop dedupe**.  Outbound responses set
+ *       `X-Astra-Verified-Hop` so a downstream REST endpoint that the tool
+ *       calls can skip a duplicate verify-access. The receiving REST
+ *       middleware checks `parseVerifiedHop` and skips when valid.
+ *
+ *   (d) **Header-vs-body identity precedence**.  Reads ASTRA-id from
+ *       `X-Astra-Id` first, body second. If both are present and disagree,
+ *       returns a structured 400 by default (configurable). Pre-fix,
+ *       integrators had to re-discover this on their own.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * import express from 'express';
+ * import { createMcpMiddleware } from '@astrasyncai/verification-gateway/mcp';
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * app.post(
+ *   '/mcp',
+ *   createMcpMiddleware({
+ *     apiBaseUrl: 'https://astrasync.ai/api',
+ *     apiKey: process.env.ASTRASYNC_API_KEY,
+ *     // Per-tool gates — `tools/call` is enforced by default; introspection /
+ *     // handshake pass through. A gated tool needs a PDLSS purpose (and ideally
+ *     // an action). Set a tool/method to `'observe'` to pass it through
+ *     // unenforced (still evaluated when `evaluateAlwaysIfCredentialed`).
+ *     toolGates: {
+ *       browse_catalog: { purpose: 'shopping', action: 'shopping.search' },
+ *       start_checkout: { purpose: 'shopping', action: 'shopping.purchase' },
+ *       health_check: 'observe',
+ *     },
+ *   }),
+ *   yourMcpServerHandler,
+ * );
+ * ```
+ */
+
+declare global {
+    namespace Express {
+        interface Request {
+            mcpRequest?: ParsedMcpRequest;
+            agentVerification?: VerificationResult;
+        }
+    }
+}
+/**
+ * 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 (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 leave the action undeclared (purpose-only
+ * evaluation — raw tool names never travel as PDLSS actions).
+ *
+ * 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 {
+    purpose?: string;
+    action?: string;
+    resource?: string;
+}
+/**
+ * A tool/method gate is either a {@link ToolGateConfig} (enforced — calls
+ * verify-access and gates on the server decision, using the declared PDLSS
+ * purpose/action) or the literal `'observe'` (passed through unenforced;
+ * still evaluated when `evaluateAlwaysIfCredentialed` is set). SDK 5.0.0
+ * removed the access-level band, so a gate no longer carries a tier — its
+ * only decision is enforce vs observe.
+ */
+type ToolGate = ToolGateConfig | 'observe';
+interface McpMiddlewareOptions extends GatewayConfig {
+    /**
+     * Per-tool gating for `tools/call` invocations. Tools not listed are
+     * enforced by default (`tools/call` calls verify-access and gates on the
+     * server decision).
+     *
+     * A gated tool declares its PDLSS `purpose` (required: the backend rejects
+     * gated calls with no resolvable purpose) and ideally a dotted-verb
+     * `action`:
+     * ```typescript
+     * toolGates: {
+     *   list_products:  { purpose: 'shopping',
+     *                     action: 'shopping.search',
+     *                     resource: '/api/catalog' },
+     *   start_checkout: { purpose: 'shopping',
+     *                     action: 'shopping.purchase',
+     *                     resource: '/api/checkout/*' },
+     *   health_check:   'observe',   // pass through unenforced
+     * }
+     * ```
+     *
+     * Set a tool to `'observe'` to pass it through without enforcement (it is
+     * still evaluated for the audit trail when `evaluateAlwaysIfCredentialed`
+     * is set). A gated object form with no resolvable purpose fails fast with a
+     * `PDLSS_PURPOSE_REQUIRED` 400 (the SDK never sends the raw tool name as
+     * the PDLSS action).
+     *
+     * The action axis for non-tools/call MCP methods (`tools/list`,
+     * `resources/list`, `prompts/list`, etc.) is the literal JSON-RPC method
+     * name (e.g. `'tools/list'`). Merchants gating MCP traffic by action should
+     * declare per-tool gates in `toolGates`, not endpoint-level `allowedActions`
+     * — the latter applies to REST-style action values, not MCP method strings.
+     */
+    toolGates?: Record<string, ToolGate>;
+    /**
+     * Per-method override. By default introspection / handshake methods
+     * (`tools/list`, `initialize`, `ping`, …) pass through and `tools/call` is
+     * enforced; declare a method here to enforce it (object form, with a PDLSS
+     * purpose) or set it to `'observe'` to pass it through. Matches by exact
+     * JSON-RPC method string.
+     */
+    methodGates?: Record<string, ToolGate>;
+    /**
+     * What to do when the agent id supplied in the X-Astra-Id header
+     * disagrees with the agent id in the JSON-RPC body
+     * (`params._meta.astrasync.agentId` or `params.arguments.agent_id`).
+     *
+     *   - `'reject'` (default) — return 400 `AGENT_ID_MISMATCH`. Safest.
+     *   - `'prefer-header'` — log + verify against the header value. Keeps
+     *     bodies that were authored before X-Astra-Id was the canonical
+     *     identity slot working.
+     *   - `'prefer-body'` — log + verify against the body value. Useful in
+     *     reverse-proxy setups that strip auth headers.
+     */
+    onAgentIdMismatch?: 'reject' | 'prefer-header' | 'prefer-body';
+    /** Skip verification + dedupe entirely. For testing. */
+    skip?: boolean;
+    /** Custom denied handler. Defaults to a structured JSON-RPC error response. */
+    onDenied?: (result: VerificationResult, req: Request, res: Response) => void;
+    /**
+     * If `true`, trust an inbound `X-Astra-Verified-Hop` header to skip
+     * verify-access when it carries a recent marker for the resolved agent.
+     *
+     * **DEFAULT FLIPPED TO `false` in SDK 2.4.13.** The marker
+     * is plaintext semicolon-delimited with no HMAC, so any client that sets
+     * the header (with the right format + fresh timestamp + matching ASTRA-id)
+     * skipped verify-access entirely. The per-process verify-access result
+     * cache already dedupes legitimate repeat calls — this optimization
+     * provided no additional savings, only a bypass surface.
+     *
+     * Set this to `true` ONLY if you control every upstream MCP hop that sets
+     * the header AND you trust the network path between hops (mTLS, internal
+     * VPC, etc.). For most installs, leave at the safe default.
+     *
+     * A future SDK release will either remove this option entirely OR add
+     * HMAC signing to the marker.
+     */
+    trustVerifiedHop?: boolean;
+    /** Window for accepting an upstream verified-hop marker. Default 60_000ms. */
+    verifiedHopMaxAgeMs?: number;
+    /**
+     * Automatically record grant/deny decisions for every MCP call. Default
+     * `true` — matches the express adapter.
+     */
+    recordDecisions?: boolean;
+    /** Forward runtime challenge (default `true`). */
+    enableRuntimeChallenge?: boolean;
+    /**
+     * Posture when the MCP middleware itself throws an internal error.
+     * Default `'open'` for backward compatibility in SDK 2.4.13. Shadow logs
+     * record what WOULD be denied with `failOnError: 'closed'` so merchants
+     * can grep correlationId for impact analysis during the observation
+     * window. Default flips to `'closed'` in a follow-up release.
+     */
+    failOnError?: 'open' | 'closed';
+}
+/**
+ * Create the MCP middleware. Attach AFTER `express.json()` — the body must
+ * already be a parsed object.
+ */
+declare function createMcpMiddleware(options: McpMiddlewareOptions): RequestHandler;
+
+export { MCP_VERIFIED_HOP_HEADER, type McpMiddlewareOptions, type ParsedMcpRequest, type ToolGate, type ToolGateConfig, createMcpMiddleware, isVerifiedHopValidFor, mcpDefaultEnforced, mcpToPdlss, parseMcpJsonRpc, parseVerifiedHop, serializeVerifiedHop };

package/dist/adapters/mcp.js

@@ -32,7 +32,7 @@ __export(mcp_exports, {
 module.exports = __toCommonJS(mcp_exports);
 
 // src/version.ts
-var SDK_VERSION = "5.4.0";
+var SDK_VERSION = "5.4.1";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -221,7 +221,14 @@ function getCacheKey(request, counterpartyId) {
     request.callerMetadata?.sourceIp || "",
     request.callerMetadata?.userAgent || "",
     request.callerMetadata?.forwardedFor || "",
-    request.callerMetadata?.agentCardUrl || ""
+    request.callerMetadata?.agentCardUrl || "",
+    // UAT2 Bug B (5.4.1): the commerce phase and cart identity DO affect the
+    // backend verdict — the confirm leg is the ONLY leg that may execute
+    // first-party settlement. Without these, a confirm within the cache TTL of
+    // its start_checkout quote was served the cached quote-leg grant (no
+    // settlementOutcome) and never reached the backend. Same F-A1-07 bug class.
+    request.commercePhase || "",
+    request.checkoutSessionId || ""
   ].join("|");
 }
 function getCachedResult(request, counterpartyId) {