@astrasyncai/verification-gateway 4.5.0 → 4.5.1

package/dist/adapters/mcp.d.mts

@@ -1,395 +1,4 @@
-import { Request, Response, RequestHandler } from 'express';
-import { a as AccessLevel, G as GatewayConfig, x as VerificationResult } from '../types-C0zfSXMB.mjs';
+import 'express';
+import '../types-C0zfSXMB.mjs';
+export { M as MCP_VERIFIED_HOP_HEADER, b as McpMiddlewareOptions, P as ParsedMcpRequest, T as ToolGateConfig, c as createMcpMiddleware, i as isVerifiedHopValidFor, m as mcpRiskTier, d as mcpToPdlss, p as parseMcpJsonRpc, e as parseVerifiedHop, s as serializeVerifiedHop } from '../mcp-BgBJu4Jl.mjs';
 import '../metadata-capture.mjs';
-
-/**
- * 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.
- *   - `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, type McpMiddlewareOptions, type ParsedMcpRequest, type ToolGateConfig, createMcpMiddleware, isVerifiedHopValidFor, mcpRiskTier, mcpToPdlss, parseMcpJsonRpc, parseVerifiedHop, serializeVerifiedHop };