@astrasyncai/verification-gateway 2.3.4 → 2.3.7

package/dist/adapters/mcp.d.ts

@@ -0,0 +1,245 @@
+import { Request, Response, RequestHandler } from 'express';
+import { a as AccessLevel, G as GatewayConfig, V as VerificationResult } from '../types-Bxqj1sKY.js';
+
+/**
+ * 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.
+ *   - `mcpRiskTier(parsed)`      — recommended `minAccessLevel` per method
+ *                                   so a single MCP middleware can split
+ *                                   `initialize` / `tools/list` (low gate)
+ *                                   from `tools/call` (high gate).
+ *   - `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.
+ */
+
+/**
+ * Header carrying upstream verify-access proof so an inner-hop REST endpoint
+ * can dedupe (skip verify-access when the same ASTRA-id was already verified
+ * a few ms earlier). 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 a dedupe
+ * advisory. 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;
+/**
+ * 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;
+    /** 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. Doc-stable so
+ * dashboards and audits can correlate consistently across cohort-3 partners.
+ *
+ * Rules:
+ *   - `purpose` is always `mcp_invoke` for MCP traffic — sets the high-level
+ *     PDLSS bucket.
+ *   - `action` is the JSON-RPC method, optionally `:tool_name` suffixed for
+ *     `tools/call`. Lets PDLSS allowlist specific tools.
+ *   - `resource` is `mcp:tool/<name>` for `tools/call`, `mcp:method/<method>`
+ *     otherwise. Lets PDLSS scope on tool identity.
+ */
+interface McpPdlssMapping {
+    purpose: string;
+    action: string;
+    resource: string;
+}
+declare function mcpToPdlss(parsed: ParsedMcpRequest): McpPdlssMapping;
+/**
+ * Recommended minimum access level per method type. The MCP middleware uses
+ * this to split low-risk handshake / introspection traffic from high-risk
+ * tool execution — defect (a) from the cohort-3 review.
+ *
+ *   - `initialize` / `notifications/initialized`        → `none`     (handshake must work for unregistered probes)
+ *   - `tools/list` / `prompts/list` / `resources/list`  → `none`     (introspection is public-surface)
+ *   - `ping`                                            → `none`
+ *   - `resources/read`                                  → `read-only`
+ *   - `tools/call`                                      → `standard` (default — overridable per-tool)
+ *   - everything else                                   → `standard` (least-privilege fallback)
+ */
+declare function mcpRiskTier(parsed: ParsedMcpRequest): AccessLevel;
+
+/**
+ * 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**.  Forwards `purpose=mcp_invoke`,
+ *       `action=method[:tool]`, `resource=mcp:tool/<name>` so audit traces
+ *       are stable across cohort-3 partners. See `transport/mcp-server.ts`
+ *       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,
+ *     // Optional per-tool overrides — tools not listed get the default tier
+ *     // from `mcpRiskTier` (`tools/call` → 'standard').
+ *     toolGates: {
+ *       start_checkout: 'standard',
+ *       confirm_purchase: 'full',
+ *       browse_catalog: 'read-only',
+ *     },
+ *   }),
+ *   yourMcpServerHandler,
+ * );
+ * ```
+ */
+
+declare global {
+    namespace Express {
+        interface Request {
+            mcpRequest?: ParsedMcpRequest;
+        }
+    }
+}
+interface McpMiddlewareOptions extends GatewayConfig {
+    /**
+     * Per-tool override for the minimum access level. Tools not listed inherit
+     * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`). Use
+     * for high-risk tools that demand `'full'` or low-risk read-only tools.
+     */
+    toolGates?: Record<string, AccessLevel>;
+    /**
+     * Per-method override (e.g. tighten `tools/list` to `'read-only'` if you
+     * don't want unregistered probes seeing your tool catalogue). Matches by
+     * exact JSON-RPC method string.
+     */
+    methodGates?: Record<string, AccessLevel>;
+    /**
+     * 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 `false`, don't trust an inbound `X-Astra-Verified-Hop` header (always
+     * call verify-access). Default `true` — recommended for inner-hop endpoints
+     * called by your own MCP tools.
+     */
+    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;
+}
+/**
+ * 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, createMcpMiddleware, isVerifiedHopValidFor, mcpRiskTier, mcpToPdlss, parseMcpJsonRpc, parseVerifiedHop, serializeVerifiedHop };