@astrasyncai/verification-gateway 4.5.0 → 4.5.1

package/dist/mcp--DgKOwfu.d.ts

@@ -0,0 +1,396 @@
+import { Request, Response, RequestHandler } from 'express';
+import { a as AccessLevel, G as GatewayConfig, x as VerificationResult } from './types-DwSfO7Sb.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";
+/** Default acceptable age (ms) for an X-Astra-Verified-Hop header. */
+declare const MCP_VERIFIED_HOP_MAX_AGE_MS = 60000;
+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.
+ *   - `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.
+ */
+
+/**
+ * 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;
+/**
+ * Recommended minimum access level per method type. The MCP middleware uses
+ * this to split low-risk handshake / introspection traffic from high-risk
+ * tool execution.
+ *
+ *   - `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**.  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 not listed get the default tier from
+ *     // `mcpRiskTier` (`tools/call` → 'standard'). Use the object form:
+ *     // gated tools need a PDLSS purpose (and ideally an action).
+ *     toolGates: {
+ *       browse_catalog: { minAccessLevel: 'read-only', purpose: 'shopping' },
+ *       start_checkout: {
+ *         minAccessLevel: 'standard',
+ *         purpose: 'shopping',
+ *         action: 'shopping.purchase',
+ *       },
+ *     },
+ *   }),
+ *   yourMcpServerHandler,
+ * );
+ * ```
+ */
+
+declare global {
+    namespace Express {
+        interface Request {
+            mcpRequest?: ParsedMcpRequest;
+        }
+    }
+}
+/**
+ * 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 {
+    minAccessLevel: AccessLevel;
+    purpose?: string;
+    action?: string;
+    resource?: string;
+}
+interface McpMiddlewareOptions extends GatewayConfig {
+    /**
+     * Per-tool gating for `tools/call` invocations. Tools not listed inherit
+     * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`).
+     *
+     * Use the **object form** — it lets the merchant declare the PDLSS
+     * `purpose` (required for any gated tool: the backend rejects gated calls
+     * with no resolvable purpose) and pin a dotted-verb `action`:
+     * ```typescript
+     * toolGates: {
+     *   list_products:  { minAccessLevel: 'read-only',
+     *                     purpose: 'shopping',
+     *                     action: 'shopping.search',
+     *                     resource: '/api/catalog' },
+     *   start_checkout: { minAccessLevel: 'standard',
+     *                     purpose: 'shopping',
+     *                     action: 'shopping.purchase',
+     *                     resource: '/api/checkout/*' },
+     * }
+     * ```
+     *
+     * The bare access-level string shorthand (`browse_catalog: 'read-only'`)
+     * is a legacy form and a known footgun: it carries no purpose, so the call
+     * only succeeds when the AGENT declares one (an `X-Astra-Purpose` header
+     * or `params._meta.astrasync.purpose`) — otherwise it fails fast with a
+     * `PDLSS_PURPOSE_REQUIRED` 400. It also declares no action, so evaluation
+     * is purpose-only (the SDK never sends the raw tool name as the PDLSS
+     * action). `createMcpMiddleware` logs a warning at construction for every
+     * bare-string gate.
+     *
+     * When `tools/call` arrives for a tool not declared in `toolGates`, the SDK
+     * falls back to a risk-tier default based on the method classification
+     * (`mcpRiskTier`). For `tools/call` the fallback is `'standard'`. Best
+     * practice: declare every tool you expose explicitly.
+     *
+     * 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, AccessLevel | ToolGateConfig>;
+    /**
+     * 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 `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 as M, type ParsedMcpRequest as P, type ToolGateConfig as T, type VerifiedHopMarker as V, MCP_VERIFIED_HOP_MAX_AGE_MS as a, type McpMiddlewareOptions as b, createMcpMiddleware as c, mcpToPdlss as d, parseVerifiedHop as e, isVerifiedHopValidFor as i, mcpRiskTier as m, parseMcpJsonRpc as p, serializeVerifiedHop as s };