@astrasyncai/verification-gateway 5.4.0 → 5.4.2

package/dist/mcp-BqfTDZLh.d.mts

@@ -1,397 +0,0 @@
-import { Request, Response, RequestHandler } from 'express';
-import { G as GatewayConfig, x as VerificationResult } from './types-CD1F9fmp.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";
-/** 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.
- *   - `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;
-        }
-    }
-}
-/**
- * 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 as M, type ParsedMcpRequest as P, type ToolGate as T, type VerifiedHopMarker as V, MCP_VERIFIED_HOP_MAX_AGE_MS as a, type McpMiddlewareOptions as b, type ToolGateConfig as c, createMcpMiddleware as d, mcpToPdlss as e, parseVerifiedHop as f, isVerifiedHopValidFor as i, mcpDefaultEnforced as m, parseMcpJsonRpc as p, serializeVerifiedHop as s };