@astrasyncai/verification-gateway 2.3.4 → 2.3.7

package/dist/adapters/mcp.mjs

@@ -0,0 +1,555 @@
+// src/access-levels.ts
+var ACCESS_LEVEL_HIERARCHY = {
+  none: 0,
+  guidance: 1,
+  "read-only": 2,
+  standard: 3,
+  full: 4,
+  internal: 5
+};
+function getTrustLevel(score) {
+  if (score >= 80) return "PLATINUM";
+  if (score >= 60) return "GOLD";
+  if (score >= 40) return "SILVER";
+  return "BRONZE";
+}
+function hasMinimumAccess(actual, required) {
+  return ACCESS_LEVEL_HIERARCHY[actual] >= ACCESS_LEVEL_HIERARCHY[required];
+}
+
+// src/verify.ts
+var DEFAULT_CONFIG = {
+  apiBaseUrl: "https://astrasync.ai/api",
+  defaultAccessLevel: "guidance",
+  // minTrustScore + minTrustScoreForFull deprecated in v2.3.0 — server decides.
+  cacheTtl: 300,
+  // 5 minutes
+  debug: false
+};
+var initCheckPerformed = false;
+var deprecationWarningShown = false;
+async function performInitCheck(apiBaseUrl, debug) {
+  initCheckPerformed = true;
+  try {
+    const probeUrl = `${apiBaseUrl}/agents/verify-access`;
+    const response = await fetch(probeUrl, { method: "HEAD" });
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.startsWith("text/html")) {
+      console.warn(
+        `[VerificationGateway] apiBaseUrl '${apiBaseUrl}' returned HTML (content-type: ${contentType}). This usually means apiBaseUrl is pointing at a marketing site instead of the API. Expected: 'https://astrasync.ai/api' (prod) or 'https://staging.astrasync.ai/api' (staging). Set disableInitChecks: true on GatewayConfig to silence this warning.`
+      );
+    } else if (debug) {
+      console.log(
+        `[VerificationGateway] init check passed for ${apiBaseUrl} (content-type: ${contentType})`
+      );
+    }
+  } catch (err) {
+    if (debug) {
+      console.log(`[VerificationGateway] init check failed (non-blocking): ${String(err)}`);
+    }
+  }
+}
+var verificationCache = /* @__PURE__ */ new Map();
+function getCacheKey(credentials) {
+  return `${credentials.astraId || ""}-${credentials.apiKey || ""}-${credentials.jwt || ""}`;
+}
+function getCachedResult(credentials) {
+  const key = getCacheKey(credentials);
+  const cached = verificationCache.get(key);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.result;
+  }
+  if (cached) {
+    verificationCache.delete(key);
+  }
+  return null;
+}
+function cacheResult(credentials, result, ttlSeconds) {
+  const key = getCacheKey(credentials);
+  verificationCache.set(key, {
+    result,
+    expiresAt: Date.now() + ttlSeconds * 1e3
+  });
+}
+function extractCredentials(headers, query) {
+  const credentials = {};
+  const astraIdHeader = headers["x-astra-id"] || headers["X-Astra-Id"] || headers["X-ASTRA-ID"] || headers["x-astra-agentid"] || headers["X-Astra-AgentId"] || headers["x-astra-agent-id"] || headers["X-Astra-Agent-Id"] || headers["X-ASTRA-AGENT-ID"];
+  if (astraIdHeader) {
+    credentials.astraId = Array.isArray(astraIdHeader) ? astraIdHeader[0] : astraIdHeader;
+  }
+  const apiKeyHeader = headers["x-api-key"] || headers["X-Api-Key"] || headers["X-API-KEY"];
+  if (apiKeyHeader) {
+    credentials.apiKey = Array.isArray(apiKeyHeader) ? apiKeyHeader[0] : apiKeyHeader;
+  }
+  const authHeader = headers["authorization"] || headers["Authorization"];
+  if (authHeader) {
+    const authValue = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+    credentials.authorizationHeader = authValue;
+    if (authValue.startsWith("Bearer ")) {
+      credentials.jwt = authValue.slice(7);
+    }
+  }
+  if (query) {
+    if (query.astraId && !credentials.astraId) {
+      credentials.astraId = query.astraId;
+    }
+    if (query.apiKey && !credentials.apiKey) {
+      credentials.apiKey = query.apiKey;
+    }
+  }
+  return credentials;
+}
+function createGuidanceResponse(config, reason) {
+  const guidance = {
+    message: "This service verifies AI agents before granting access. Please register your agent with AstraSync.",
+    registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/register`,
+    documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
+    steps: [
+      "Register for an AstraSync account",
+      "Create and register your agent",
+      "Add your ASTRA-ID to request headers",
+      "Retry your request"
+    ]
+  };
+  return {
+    verified: false,
+    accessLevel: "guidance",
+    guidance,
+    denialReasons: reason ? [reason] : ["No valid agent credentials provided"],
+    verifiedAt: /* @__PURE__ */ new Date()
+  };
+}
+async function callVerifyAccessAPI(config, request) {
+  const { credentials, ...requestData } = request;
+  const body = {
+    ...credentials.astraId && { agentId: credentials.astraId },
+    purpose: requestData.purpose || "general"
+  };
+  if (requestData.action) body.action = requestData.action;
+  if (requestData.resourceType) body.resourceType = requestData.resourceType;
+  if (requestData.resource) body.resource = requestData.resource;
+  if (requestData.jurisdiction) body.jurisdiction = requestData.jurisdiction;
+  if (requestData.transactionValue) body.transactionValue = requestData.transactionValue;
+  if (requestData.currency) body.currency = requestData.currency;
+  if (requestData.isSubAgentRequest) body.isSubAgentRequest = requestData.isSubAgentRequest;
+  if (requestData.parentAgentId) body.parentAgentId = requestData.parentAgentId;
+  if (requestData.subAgentDepth !== void 0) body.subAgentDepth = requestData.subAgentDepth;
+  if (requestData.enableRuntimeChallenge)
+    body.enableRuntimeChallenge = requestData.enableRuntimeChallenge;
+  if (requestData.createSession) body.createSession = requestData.createSession;
+  if (requestData.durationRequired) body.durationRequired = requestData.durationRequired;
+  if (requestData.counterpartyType) body.counterpartyType = requestData.counterpartyType;
+  if (requestData.counterpartyUrl) body.counterpartyUrl = requestData.counterpartyUrl;
+  if (config.counterpartyId) body.counterpartyId = config.counterpartyId;
+  if (requestData.runtimeChallengeOptions)
+    body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
+  if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
+    const meta = {
+      ...requestData.clientIp && { sourceIp: requestData.clientIp },
+      ...requestData.userAgent && { userAgent: requestData.userAgent },
+      ...requestData.callerMetadata
+    };
+    if (Object.keys(meta).length > 0) body.callerMetadata = meta;
+  }
+  const headers = {
+    "Content-Type": "application/json",
+    ...config.customHeaders
+  };
+  if (credentials.authorizationHeader) {
+    headers["Authorization"] = credentials.authorizationHeader;
+  } else if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+  }
+  if (config.apiKey) {
+    headers["X-API-Key"] = config.apiKey;
+  }
+  try {
+    const response = await fetch(`${config.apiBaseUrl}/agents/verify-access`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      return {
+        success: false,
+        error: data.message || data.error || `API returned ${response.status}`
+      };
+    }
+    return data;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return {
+      success: false,
+      error: `Failed to call verify-access API: ${message}`
+    };
+  }
+}
+async function verify(config, request) {
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
+    void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug);
+  }
+  if (!deprecationWarningShown && (config.minTrustScore !== void 0 || config.minTrustScoreForFull !== void 0)) {
+    deprecationWarningShown = true;
+    console.warn(
+      "[VerificationGateway] minTrustScore / minTrustScoreForFull are deprecated in v2.3.0 and have no effect. Server is now the single source of truth for access-level decisions (the SDK reads access.accessLevel from the verify-access response). To gate access to an endpoint, configure the endpoint's trust_score_requirement server-side."
+    );
+  }
+  if (mergedConfig.cacheTtl && mergedConfig.cacheTtl > 0) {
+    const cached = getCachedResult(request.credentials);
+    if (cached) {
+      if (mergedConfig.debug) {
+        console.log("[VerificationGateway] Returning cached result");
+      }
+      return cached;
+    }
+  }
+  const enrichedRequest = { ...request };
+  if (!enrichedRequest.counterpartyUrl && mergedConfig.counterpartyUrl) {
+    enrichedRequest.counterpartyUrl = mergedConfig.counterpartyUrl;
+  }
+  if (!enrichedRequest.counterpartyType && mergedConfig.counterpartyType) {
+    enrichedRequest.counterpartyType = mergedConfig.counterpartyType;
+  }
+  if (mergedConfig.debug) {
+    console.log("[VerificationGateway] Calling verify-access API");
+  }
+  const apiResponse = await callVerifyAccessAPI(mergedConfig, enrichedRequest);
+  if (!apiResponse.success) {
+    return createGuidanceResponse(mergedConfig, apiResponse.error);
+  }
+  if (!apiResponse.access?.allowed) {
+    const aggregatedFailures = apiResponse.access?.failures;
+    const result2 = {
+      verified: false,
+      accessLevel: "guidance",
+      denialReasons: aggregatedFailures && aggregatedFailures.length > 0 ? aggregatedFailures.map((f) => f.message) : apiResponse.access?.reason ? [apiResponse.access.reason] : ["Access denied"],
+      failures: aggregatedFailures,
+      requiresStepUp: apiResponse.access?.requiresStepUp,
+      requiresApproval: apiResponse.access?.requiresApproval,
+      guidance: {
+        message: apiResponse.access?.reason || "Access denied by PDLSS policy",
+        registrationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/register`,
+        documentationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/docs/pdlss`
+      },
+      verifiedAt: /* @__PURE__ */ new Date(),
+      // Extract sessionId so decisions can be recorded for denials too
+      sessionId: apiResponse.sessionId,
+      recommendation: apiResponse.recommendation,
+      recommendationReasons: apiResponse.recommendationReasons
+    };
+    return result2;
+  }
+  const agent = apiResponse.agent ? {
+    astraId: apiResponse.agent.astraId,
+    name: apiResponse.agent.name,
+    trustScore: apiResponse.agent.trustScore,
+    trustLevel: getTrustLevel(apiResponse.agent.trustScore),
+    blockchainVerified: apiResponse.agent.blockchainStatus === "verified",
+    status: apiResponse.agent.agentStatus
+  } : void 0;
+  const developer = apiResponse.developer ? {
+    astradId: apiResponse.developer.kyaOwnerId,
+    name: apiResponse.developer.fullName,
+    trustScore: apiResponse.developer.trustScore || 0,
+    verified: apiResponse.developer.identityVerified
+  } : void 0;
+  const organization = apiResponse.organization ? {
+    name: apiResponse.organization.name,
+    verified: apiResponse.organization.verified,
+    trustScore: apiResponse.organization.trustScore
+  } : void 0;
+  const verificationContext = apiResponse.verificationContext;
+  const accessLevel = apiResponse.access?.accessLevel ?? "standard";
+  const result = {
+    verified: true,
+    accessLevel,
+    agent,
+    developer,
+    organization,
+    appliedPolicy: apiResponse.access?.appliedPolicy,
+    verificationContext,
+    requiresStepUp: apiResponse.access?.requiresStepUp,
+    requiresApproval: apiResponse.access?.requiresApproval,
+    verifiedAt: /* @__PURE__ */ new Date(),
+    cacheTtl: mergedConfig.cacheTtl,
+    // Handshake Protocol v10 enhanced fields (present when backend returns them)
+    sessionId: apiResponse.sessionId,
+    runtimeChallenge: apiResponse.runtimeChallenge,
+    tokenGuidance: apiResponse.tokenGuidance,
+    recommendation: apiResponse.recommendation,
+    recommendationReasons: apiResponse.recommendationReasons
+  };
+  if (result.recommendation === "deny") {
+    result.verified = false;
+    result.accessLevel = "none";
+    result.denialReasons = result.recommendationReasons || [
+      "Access denied by AstraSync recommendation"
+    ];
+    if (result.runtimeChallenge) {
+      result.guidance = {
+        message: `Verification failed: ${result.runtimeChallenge.reason || "runtime challenge failed"}`,
+        registrationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/register`,
+        documentationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/docs/runtime-challenge`
+      };
+    }
+  } else if (result.recommendation === "step_up_required") {
+    result.requiresStepUp = true;
+    if (ACCESS_LEVEL_HIERARCHY[result.accessLevel] > ACCESS_LEVEL_HIERARCHY["read-only"]) {
+      result.accessLevel = "read-only";
+    }
+    result.denialReasons = result.recommendationReasons || ["Step-up verification required"];
+  }
+  if (mergedConfig.cacheTtl && mergedConfig.cacheTtl > 0 && result.recommendation !== "deny") {
+    cacheResult(request.credentials, result, mergedConfig.cacheTtl);
+  }
+  return result;
+}
+async function recordDecision(config, sessionId, decision, reason) {
+  const headers = { "Content-Type": "application/json" };
+  if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+    headers["X-API-Key"] = config.apiKey;
+  }
+  await fetch(`${config.apiBaseUrl}/agents/verify-access/${sessionId}/decision`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ decision, reason })
+  }).catch(() => {
+  });
+}
+
+// src/transport/mcp-server.ts
+var MCP_VERIFIED_HOP_HEADER = "X-Astra-Verified-Hop";
+var MCP_VERIFIED_HOP_MAX_AGE_MS = 6e4;
+function serializeVerifiedHop(marker) {
+  return `${marker.astraId};${marker.sessionId ?? ""};${marker.checkedAt}`;
+}
+function parseVerifiedHop(value) {
+  if (!value) return null;
+  const parts = value.split(";");
+  if (parts.length !== 3) return null;
+  const [astraId, sessionId, checkedAtRaw] = parts;
+  if (!astraId) return null;
+  const checkedAt = Number(checkedAtRaw);
+  if (!Number.isFinite(checkedAt) || checkedAt <= 0) return null;
+  return {
+    astraId,
+    ...sessionId ? { sessionId } : {},
+    checkedAt
+  };
+}
+function isVerifiedHopValidFor(marker, expectedAstraId, opts = {}) {
+  if (!marker) return false;
+  if (marker.astraId !== expectedAstraId) return false;
+  const maxAge = opts.maxAgeMs ?? MCP_VERIFIED_HOP_MAX_AGE_MS;
+  const now = opts.now ?? Date.now();
+  return now - marker.checkedAt <= maxAge && now >= marker.checkedAt;
+}
+function parseMcpJsonRpc(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const obj = body;
+  if (obj.jsonrpc !== "2.0" && obj.jsonrpc !== "1.0") return null;
+  const method = typeof obj.method === "string" ? obj.method : null;
+  if (!method) return null;
+  const params = obj.params;
+  let toolName;
+  if (method === "tools/call" && params && typeof params.name === "string") {
+    toolName = params.name;
+  }
+  let protocolVersion;
+  if (method === "initialize" && params && typeof params.protocolVersion === "string") {
+    protocolVersion = params.protocolVersion;
+  }
+  let agentIdFromBody;
+  const meta = params?._meta;
+  const astrasyncMeta = meta?.astrasync;
+  if (astrasyncMeta && typeof astrasyncMeta.agentId === "string") {
+    agentIdFromBody = astrasyncMeta.agentId;
+  } else {
+    const args = params?.arguments;
+    if (args && typeof args.agent_id === "string") agentIdFromBody = args.agent_id;
+  }
+  const isInitialize = method === "initialize";
+  const isToolCall = method === "tools/call";
+  const isIntrospection = method === "tools/list" || method === "prompts/list" || method === "resources/list" || method === "ping" || method === "notifications/initialized";
+  return {
+    method,
+    ...toolName ? { toolName } : {},
+    ...protocolVersion ? { protocolVersion } : {},
+    ...agentIdFromBody ? { agentIdFromBody } : {},
+    isInitialize,
+    isToolCall,
+    isIntrospection
+  };
+}
+function mcpToPdlss(parsed) {
+  const action = parsed.toolName ? `${parsed.method}:${parsed.toolName}` : parsed.method;
+  const resource = parsed.toolName ? `mcp:tool/${parsed.toolName}` : `mcp:method/${parsed.method}`;
+  return {
+    purpose: "mcp_invoke",
+    action,
+    resource
+  };
+}
+function mcpRiskTier(parsed) {
+  if (parsed.isInitialize || parsed.method === "notifications/initialized") return "none";
+  if (parsed.isIntrospection) return "none";
+  if (parsed.method === "resources/read") return "read-only";
+  if (parsed.isToolCall) return "standard";
+  return "standard";
+}
+
+// src/adapters/mcp.ts
+function defaultMcpDenied(result, req, res) {
+  const id = req.body?.id ?? null;
+  const status = result.verified ? 403 : 401;
+  res.status(status).json({
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: result.verified ? -32001 : -32e3,
+      message: result.denialReasons?.[0] ?? "Access denied",
+      data: {
+        accessLevel: result.accessLevel,
+        guidance: result.guidance
+      }
+    }
+  });
+}
+function resolveMinAccessLevel(parsed, opts) {
+  if (parsed.toolName && opts.toolGates && opts.toolGates[parsed.toolName] !== void 0) {
+    return opts.toolGates[parsed.toolName];
+  }
+  if (opts.methodGates && opts.methodGates[parsed.method] !== void 0) {
+    return opts.methodGates[parsed.method];
+  }
+  return mcpRiskTier(parsed);
+}
+function createMcpMiddleware(options) {
+  const {
+    toolGates,
+    methodGates,
+    onAgentIdMismatch = "reject",
+    skip = false,
+    onDenied = defaultMcpDenied,
+    trustVerifiedHop = true,
+    verifiedHopMaxAgeMs,
+    recordDecisions,
+    enableRuntimeChallenge = true,
+    ...config
+  } = options;
+  return async (req, res, next) => {
+    try {
+      if (skip) return next();
+      const parsed = parseMcpJsonRpc(req.body);
+      if (!parsed) {
+        return next();
+      }
+      req.mcpRequest = parsed;
+      const headerRaw = req.headers["x-astra-id"] ?? req.headers["x-astra-agentid"];
+      const headerAstraId = typeof headerRaw === "string" ? headerRaw : Array.isArray(headerRaw) ? headerRaw[0] : void 0;
+      const bodyAstraId = parsed.agentIdFromBody;
+      let effectiveAstraId;
+      if (headerAstraId && bodyAstraId && headerAstraId !== bodyAstraId) {
+        if (onAgentIdMismatch === "reject") {
+          const id = req.body?.id ?? null;
+          res.status(400).json({
+            jsonrpc: "2.0",
+            id,
+            error: {
+              code: -32602,
+              message: "AGENT_ID_MISMATCH",
+              data: {
+                detail: "The agent id in the X-Astra-Id header disagrees with params._meta.astrasync.agentId / params.arguments.agent_id. Reconcile before calling the tool \u2014 see https://astrasync.ai/docs/mcp-integration#identity-reconciliation.",
+                headerAstraId,
+                bodyAstraId
+              }
+            }
+          });
+          return;
+        }
+        effectiveAstraId = onAgentIdMismatch === "prefer-header" ? headerAstraId : bodyAstraId;
+      } else {
+        effectiveAstraId = headerAstraId ?? bodyAstraId;
+      }
+      if (trustVerifiedHop && effectiveAstraId) {
+        const hopRaw = req.headers[MCP_VERIFIED_HOP_HEADER.toLowerCase()];
+        const hopValue = typeof hopRaw === "string" ? hopRaw : Array.isArray(hopRaw) ? hopRaw[0] : void 0;
+        const marker = parseVerifiedHop(hopValue);
+        if (isVerifiedHopValidFor(marker, effectiveAstraId, {
+          ...verifiedHopMaxAgeMs !== void 0 ? { maxAgeMs: verifiedHopMaxAgeMs } : {}
+        })) {
+          return next();
+        }
+      }
+      const minAccessLevel = resolveMinAccessLevel(parsed, { toolGates, methodGates });
+      if (minAccessLevel === "none") {
+        return next();
+      }
+      const credentials = extractCredentials(
+        req.headers,
+        req.query
+      );
+      if (effectiveAstraId) credentials.astraId = effectiveAstraId;
+      const pdlss = mcpToPdlss(parsed);
+      const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}${req.path}`;
+      const shouldRecordDecisions = recordDecisions !== false;
+      const result = await verify(config, {
+        credentials,
+        purpose: pdlss.purpose,
+        action: pdlss.action,
+        resource: pdlss.resource,
+        createSession: shouldRecordDecisions,
+        counterpartyUrl,
+        counterpartyType: config.counterpartyType || "mcp_server",
+        enableRuntimeChallenge,
+        callerMetadata: {
+          sourceIp: req.ip,
+          userAgent: req.headers["user-agent"],
+          host: req.headers.host
+        }
+      });
+      req.agentVerification = result;
+      const sessionId = result.sessionId;
+      if (!hasMinimumAccess(result.accessLevel, minAccessLevel)) {
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          });
+        }
+        onDenied(result, req, res);
+        return;
+      }
+      if (effectiveAstraId) {
+        res.setHeader(
+          MCP_VERIFIED_HOP_HEADER,
+          serializeVerifiedHop({
+            astraId: effectiveAstraId,
+            ...sessionId ? { sessionId } : {},
+            checkedAt: Date.now()
+          })
+        );
+      }
+      if (shouldRecordDecisions && sessionId) {
+        recordDecision(config, sessionId, "granted").catch(() => {
+        });
+      }
+      next();
+    } catch (error) {
+      console.error("[VerificationGateway/MCP] Middleware error:", error);
+      next();
+    }
+  };
+}
+export {
+  MCP_VERIFIED_HOP_HEADER,
+  createMcpMiddleware,
+  isVerifiedHopValidFor,
+  mcpRiskTier,
+  mcpToPdlss,
+  parseMcpJsonRpc,
+  parseVerifiedHop,
+  serializeVerifiedHop
+};
+//# sourceMappingURL=mcp.mjs.map