@kya-os/mcp-i-core 1.3.12 → 1.3.14

package/src/services/access-control.service.ts

@@ -1,990 +0,0 @@
-/**
- * Access Control API Service
- *
- * Brand-neutral service for interacting with access-control APIs
- * (currently AgentShield/bouncer, but designed to be provider-agnostic).
- *
- * This service provides:
- * - Delegation verification
- * - Configuration fetching
- * - Proof submission
- *
- * @package @kya-os/mcp-i-core
- */
-
-import type {
-  VerifyDelegationRequest,
-  VerifyDelegationAPIResponse,
-  ToolProtectionConfigAPIResponse,
-  ProofSubmissionRequest,
-  ProofSubmissionResponse,
-} from "@kya-os/contracts/agentshield-api";
-import {
-  verifyDelegationRequestSchema,
-  verifyDelegationAPIResponseSchema,
-  toolProtectionConfigAPIResponseSchema,
-  proofSubmissionRequestSchema,
-  proofSubmissionResponseSchema,
-} from "@kya-os/contracts/agentshield-api";
-import { AgentShieldAPIError } from "@kya-os/contracts/agentshield-api";
-import type { FetchProvider } from "../providers/base";
-
-// Type for error response
-type AgentShieldAPIErrorResponse = {
-  code: string;
-  message: string;
-  details?: Record<string, unknown>;
-};
-
-export interface AccessControlApiServiceConfig {
-  /** Base URL for the access-control API (e.g., "https://kya.vouched.id") */
-  baseUrl: string;
-
-  /** API key for authentication */
-  apiKey: string;
-
-  /** Fetch provider for making HTTP requests */
-  fetchProvider: FetchProvider;
-
-  /** Optional logger callback for diagnostics */
-  logger?: (message: string, data?: unknown) => void;
-
-  /** Optional retry configuration */
-  retryConfig?: {
-    maxRetries?: number;
-    initialDelayMs?: number;
-    maxDelayMs?: number;
-  };
-
-  /** Optional sleep function for delays (platform-agnostic) */
-  sleepProvider?: (ms: number) => Promise<void>;
-}
-
-export interface AccessControlApiServiceMetrics {
-  /** Number of successful requests */
-  successCount: number;
-
-  /** Number of failed requests */
-  errorCount: number;
-
-  /** Number of retries performed */
-  retryCount: number;
-}
-
-/**
- * Internal type with all required properties
- */
-type RequiredAccessControlApiServiceConfig = Required<
-  Omit<AccessControlApiServiceConfig, "retryConfig" | "sleepProvider">
-> & {
-  retryConfig: Required<
-    NonNullable<AccessControlApiServiceConfig["retryConfig"]>
-  >;
-  sleepProvider: NonNullable<AccessControlApiServiceConfig["sleepProvider"]>;
-};
-
-/**
- * Generate correlation ID for request tracking
- */
-function generateCorrelationId(): string {
-  // Use crypto.randomUUID() if available (Node.js 14.17+, Cloudflare Workers)
-  if (typeof crypto !== "undefined" && crypto.randomUUID) {
-    return crypto.randomUUID();
-  }
-  // Fallback for older environments
-  return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
-}
-
-/**
- * Access Control API Service
- *
- * Handles all interactions with the access-control API (AgentShield/bouncer).
- * Designed to be brand-neutral and work with any access-control provider.
- */
-export class AccessControlApiService {
-  private config: RequiredAccessControlApiServiceConfig;
-  private metrics: AccessControlApiServiceMetrics;
-
-  constructor(config: AccessControlApiServiceConfig) {
-    const retryConfig = config.retryConfig || {};
-    this.config = {
-      retryConfig: {
-        maxRetries: retryConfig.maxRetries ?? 3,
-        initialDelayMs: retryConfig.initialDelayMs ?? 100,
-        maxDelayMs: retryConfig.maxDelayMs ?? 5000,
-      },
-      logger: config.logger || (() => {}),
-      baseUrl: config.baseUrl,
-      apiKey: config.apiKey,
-      fetchProvider: config.fetchProvider,
-      sleepProvider:
-        config.sleepProvider ||
-        ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms))),
-    };
-
-    this.metrics = {
-      successCount: 0,
-      errorCount: 0,
-      retryCount: 0,
-    };
-  }
-
-  /**
-   * Fetch tool protection configuration for an agent
-   *
-   * GET /api/v1/bouncer/config?agent_did={agentDid}
-   */
-  async fetchConfig(options: {
-    agentDid: string;
-  }): Promise<ToolProtectionConfigAPIResponse> {
-    return this.retryWithBackoff(async () => {
-      const correlationId = generateCorrelationId();
-      const url = `${this.config.baseUrl}/api/v1/bouncer/config?agent_did=${encodeURIComponent(options.agentDid)}`;
-
-      this.config.logger(
-        `[AccessControl] Fetching config for agent: ${options.agentDid}`,
-        {
-          correlationId,
-          url,
-        }
-      );
-
-      const response = await this.config.fetchProvider.fetch(url, {
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`,
-          "Content-Type": "application/json",
-          "X-Request-ID": correlationId,
-        },
-      });
-
-      const responseText = await response.text();
-      const responseData = this.parseResponseJSON(response, responseText);
-
-      // Handle error responses
-      if (!response.ok) {
-        this.handleErrorResponse(response, responseData);
-      }
-
-      // Validate and parse success response
-      const parsed =
-        toolProtectionConfigAPIResponseSchema.safeParse(responseData);
-      if (!parsed.success) {
-        throw new AgentShieldAPIError(
-          "invalid_response",
-          "Response validation failed",
-          { zodErrors: parsed.error.errors }
-        );
-      }
-
-      this.config.logger(`[AccessControl] Config fetched successfully`, {
-        correlationId,
-        agentDid: options.agentDid,
-      });
-
-      return parsed.data;
-    });
-  }
-
-  /**
-   * Verify a delegation token
-   *
-   * POST /api/v1/bouncer/delegations/verify
-   */
-  async verifyDelegation(
-    request: VerifyDelegationRequest,
-    context?: {
-      delegationToken?: string;
-      credentialJwt?: string;
-    }
-  ): Promise<VerifyDelegationAPIResponse> {
-    return this.retryWithBackoff(async () => {
-      const correlationId = generateCorrelationId();
-      const url = `${this.config.baseUrl}/api/v1/bouncer/delegations/verify`;
-
-      // Build request body dynamically to handle optional fields
-      const requestBody: Partial<VerifyDelegationRequest> & {
-        agent_did: string;
-      } = {
-        agent_did: request.agent_did,
-      };
-
-      // Add optional fields only if they exist
-      if (request.scopes !== undefined) {
-        requestBody.scopes = request.scopes;
-      }
-
-      // Handle credential_jwt: prefer request, fallback to context
-      if (request.credential_jwt !== undefined) {
-        requestBody.credential_jwt = request.credential_jwt;
-      } else if (context?.credentialJwt) {
-        requestBody.credential_jwt = context.credentialJwt;
-      }
-
-      // Handle delegation_token: prefer request, fallback to context
-      if (request.delegation_token !== undefined) {
-        requestBody.delegation_token = request.delegation_token;
-      } else if (context?.delegationToken) {
-        requestBody.delegation_token = context.delegationToken;
-      }
-
-      if (request.timestamp !== undefined) {
-        requestBody.timestamp = request.timestamp;
-      }
-
-      if (request.client_info) {
-        requestBody.client_info = request.client_info;
-      }
-
-      // Remove undefined values to ensure Zod validation passes (optional fields should be omitted, not undefined)
-      const cleanedRequestBody = Object.fromEntries(
-        Object.entries(requestBody).filter(([_, value]) => value !== undefined)
-      );
-
-      // Validate the cleaned request body
-      // Note: Workaround for Zod schema issue where .optional() doesn't properly handle omitted fields
-      // See AGENTSHIELD_MCPI_COMPLIANCE_REVIEW.md for details
-      const validationResult =
-        verifyDelegationRequestSchema.safeParse(cleanedRequestBody);
-      if (!validationResult.success) {
-        // Check if the error is specifically about scopes being required when it's omitted
-        const scopesError = validationResult.error.errors.find(
-          (e) => e.path.includes("scopes") && e.message === "Required"
-        );
-        if (scopesError && !("scopes" in cleanedRequestBody)) {
-          // This is a known Zod schema issue in AgentShield - scopes is optional but Zod treats it as required
-          // Skip validation for this case since the field is correctly omitted
-          // TODO: Remove this workaround once AgentShield fixes their schema
-        } else {
-          this.config.logger(`[AccessControl] Validation failed:`, {
-            errors: validationResult.error.errors,
-            requestBody: requestBody,
-          });
-          throw new AgentShieldAPIError(
-            "validation_error",
-            "Request validation failed",
-            { zodErrors: validationResult.error.errors }
-          );
-        }
-      }
-
-      this.config.logger(
-        `[AccessControl] Verifying delegation for agent: ${request.agent_did}`,
-        {
-          correlationId,
-          url,
-          hasScopes: (request.scopes?.length || 0) > 0,
-        }
-      );
-
-      const response = await this.config.fetchProvider.fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`,
-          "Content-Type": "application/json",
-          "X-Request-ID": correlationId,
-        },
-        // Use cleanedRequestBody directly instead of validated data
-        // because Zod seems to strip optional fields in some cases
-        body: JSON.stringify(cleanedRequestBody),
-      });
-
-      const responseText = await response.text();
-      const responseData = this.parseResponseJSON(response, responseText);
-
-      // Handle error responses
-      if (!response.ok) {
-        this.handleErrorResponse(response, responseData);
-      }
-
-      // Validate and parse success response
-      const parsed = verifyDelegationAPIResponseSchema.safeParse(responseData);
-      if (!parsed.success) {
-        throw new AgentShieldAPIError(
-          "invalid_response",
-          "Response validation failed",
-          { zodErrors: parsed.error.errors }
-        );
-      }
-
-      this.config.logger(`[AccessControl] Delegation verified`, {
-        correlationId,
-        agentDid: request.agent_did,
-        valid: parsed.data.data.valid,
-      });
-
-      return parsed.data;
-    });
-  }
-
-  /**
-   * Submit proofs for audit and verification
-   *
-   * POST /api/v1/bouncer/proofs
-   */
-  async submitProofs(
-    request: ProofSubmissionRequest
-  ): Promise<ProofSubmissionResponse> {
-    return this.retryWithBackoff(async () => {
-      // Validate request directly - Zod's .nullish() should handle null/undefined correctly
-      const validationResult = proofSubmissionRequestSchema.safeParse(request);
-      if (!validationResult.success) {
-        // Log validation errors for debugging
-        const errorDetails = JSON.stringify(
-          validationResult.error.errors,
-          null,
-          2
-        );
-        this.config.logger(
-          `[AccessControl] Proof submission validation failed:`,
-          {
-            errors: validationResult.error.errors,
-            request: JSON.stringify(request, null, 2),
-          }
-        );
-        throw new AgentShieldAPIError(
-          "validation_error",
-          `Request validation failed: ${errorDetails}`,
-          { zodErrors: validationResult.error.errors }
-        );
-      }
-
-      // Use validated request for the API call
-      const validatedRequest = validationResult.data;
-
-      const correlationId = generateCorrelationId();
-      const url = `${this.config.baseUrl}/api/v1/bouncer/proofs`;
-
-      this.config.logger(
-        `[AccessControl] Submitting ${request.proofs.length} proof(s)`,
-        {
-          correlationId,
-          url,
-          sessionId: request.session_id,
-          delegationId: request.delegation_id,
-        }
-      );
-
-      const httpResponse = await this.config.fetchProvider.fetch(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${this.config.apiKey}`,
-          "Content-Type": "application/json",
-          "X-Request-ID": correlationId,
-        },
-        body: JSON.stringify(validatedRequest),
-      });
-
-      const responseText = await httpResponse.text();
-
-      // CRITICAL: Log raw response IMMEDIATELY before parsing/validation
-      // This will help us debug validation failures
-      console.error(`[AccessControl] 🔍 RAW API RESPONSE (before parsing):`, {
-        correlationId,
-        status: httpResponse.status,
-        statusText: httpResponse.statusText,
-        headers: Object.fromEntries(httpResponse.headers.entries()),
-        responseTextLength: responseText.length,
-        responseTextPreview: responseText.substring(0, 500),
-        fullResponseText: responseText, // Full response for debugging
-      });
-
-      const responseData = this.parseResponseJSON(httpResponse, responseText);
-
-      // Log parsed response immediately after parsing
-      console.error(`[AccessControl] 🔍 PARSED RESPONSE DATA:`, {
-        correlationId,
-        status: httpResponse.status,
-        responseDataType: typeof responseData,
-        responseDataKeys: Object.keys(
-          (responseData as Record<string, unknown>) || {}
-        ),
-        responseData: JSON.stringify(responseData, null, 2),
-      });
-
-      // Handle error responses
-      if (!httpResponse.ok) {
-        const errorData = responseData as {
-          success?: boolean;
-          error?: AgentShieldAPIErrorResponse;
-        };
-
-        if (errorData.error) {
-          const errorCode = errorData.error.code || "api_error";
-
-          // Special handling for all_proofs_rejected - return response instead of throwing
-          if (
-            errorCode === "all_proofs_rejected" &&
-            httpResponse.status === 400
-          ) {
-            // Parse the error details to extract accepted/rejected counts
-            const errorDetails = errorData.error.details as
-              | { rejected?: number; errors?: unknown[] }
-              | undefined;
-            // Create response matching ProofSubmissionResponse interface
-            // Validate structure with Zod to ensure type safety
-            const errorResponseData = {
-              success: false, // ProofSubmissionResponse has a success field
-              accepted: 0,
-              rejected: errorDetails?.rejected || request.proofs.length,
-              outcomes: {
-                success: 0,
-                failed: 0,
-                blocked: 0,
-                error: errorDetails?.rejected || request.proofs.length,
-              },
-              errors: errorDetails?.errors,
-            };
-
-            // Validate with Zod schema to ensure type safety
-            const validated =
-              proofSubmissionResponseSchema.safeParse(errorResponseData);
-            if (validated.success) {
-              return validated.data;
-            }
-
-            // If validation fails, log and throw error
-            throw new AgentShieldAPIError(
-              "invalid_response",
-              "Error response validation failed",
-              { zodErrors: validated.error.errors }
-            );
-          }
-
-          // Ensure error details include status code for retry detection
-          const errorDetails = {
-            ...(errorData.error.details || {}),
-            status: httpResponse.status,
-          };
-          throw new AgentShieldAPIError(
-            errorCode,
-            errorData.error.message || `API error: ${httpResponse.status}`,
-            errorDetails
-          );
-        }
-
-        // Map status codes to error codes
-        let errorCode = "api_error";
-        if (httpResponse.status === 400) {
-          errorCode = "validation_error";
-        } else if (httpResponse.status === 404) {
-          errorCode = httpResponse.statusText.includes("delegation")
-            ? "delegation_not_found"
-            : "session_not_found";
-        }
-
-        throw new AgentShieldAPIError(
-          errorCode,
-          `API request failed: ${httpResponse.status} ${httpResponse.statusText}`,
-          { status: httpResponse.status, responseData }
-        );
-      }
-
-      // Try to handle wrapped response format first
-      const wrappedResponse = responseData as {
-        success?: boolean;
-        data?: unknown;
-        metadata?: unknown;
-      };
-
-      // Log raw response for debugging (always log full response on first submission)
-      const rawResponseLog = {
-        correlationId,
-        hasSuccess: wrappedResponse.success !== undefined,
-        hasData: wrappedResponse.data !== undefined,
-        responseType: typeof responseData,
-        responseKeys: Object.keys(
-          (responseData as Record<string, unknown>) || {}
-        ),
-        responseData: JSON.stringify(responseData, null, 2).substring(0, 2000), // Increased limit for debugging
-      };
-      this.config.logger(
-        `[AccessControl] Raw response received`,
-        rawResponseLog
-      );
-      // Also log to console.error for visibility (especially for first proof submission errors)
-      console.error(
-        `[AccessControl] Raw response received:`,
-        JSON.stringify(responseData, null, 2)
-      );
-
-      if (wrappedResponse.success !== undefined && wrappedResponse.data) {
-        // Response is wrapped in { success, data }
-        // Extract data and add success field if missing (for schema validation)
-        // CRITICAL: Use JSON.parse(JSON.stringify()) to create a clean object
-        // This handles edge cases in Cloudflare Workers where response.json()
-        // might return objects with proxy/getter issues that prevent property access
-        let dataToValidate: Record<string, unknown>;
-
-        try {
-          // Deep clone via JSON to ensure we have a plain JavaScript object
-          // This is the most reliable way to handle potential proxy/getter issues
-          const rawData = wrappedResponse.data;
-          const clonedData = JSON.parse(JSON.stringify(rawData));
-
-          if (typeof clonedData !== "object" || clonedData === null) {
-            throw new AgentShieldAPIError(
-              "invalid_response",
-              "Response data is not an object after cloning",
-              {
-                originalType: typeof rawData,
-                clonedType: typeof clonedData,
-                clonedValue: clonedData,
-              }
-            );
-          }
-
-          dataToValidate = clonedData as Record<string, unknown>;
-        } catch (cloneError) {
-          if (cloneError instanceof AgentShieldAPIError) {
-            throw cloneError;
-          }
-          throw new AgentShieldAPIError(
-            "invalid_response",
-            "Failed to clone response data",
-            {
-              error:
-                cloneError instanceof Error
-                  ? cloneError.message
-                  : String(cloneError),
-              dataType: typeof wrappedResponse.data,
-            }
-          );
-        }
-
-        // CRITICAL: Log the actual data structure for debugging
-        console.error(`[AccessControl] 🔍 DATA OBJECT STRUCTURE (after deep clone):`, {
-          correlationId,
-          dataKeys: Object.keys(dataToValidate),
-          hasAccepted: "accepted" in dataToValidate,
-          hasRejected: "rejected" in dataToValidate,
-          hasOutcomes: "outcomes" in dataToValidate,
-          hasErrors: "errors" in dataToValidate,
-          acceptedType: typeof dataToValidate.accepted,
-          acceptedValue: dataToValidate.accepted,
-          rejectedType: typeof dataToValidate.rejected,
-          rejectedValue: dataToValidate.rejected,
-          outcomesType: typeof dataToValidate.outcomes,
-          outcomesValue: dataToValidate.outcomes,
-          errorsType: typeof dataToValidate.errors,
-          errorsIsArray: Array.isArray(dataToValidate.errors),
-          fullData: JSON.stringify(dataToValidate, null, 2),
-        });
-
-        // Ensure success field is present (required by schema)
-        // wrappedResponse.success should be true since we checked it exists
-        // CRITICAL: Construct from the cloned data to ensure all fields are present
-        const dataWithSuccess: Record<string, unknown> = {
-          success: wrappedResponse.success === true,
-          accepted: dataToValidate.accepted,
-          rejected: dataToValidate.rejected,
-        };
-
-        // Add optional fields if present
-        if (
-          "outcomes" in dataToValidate &&
-          dataToValidate.outcomes !== undefined
-        ) {
-          dataWithSuccess.outcomes = dataToValidate.outcomes;
-        }
-        if ("errors" in dataToValidate && dataToValidate.errors !== undefined) {
-          dataWithSuccess.errors = dataToValidate.errors;
-        }
-
-        // CRITICAL: Log what we're validating
-        console.error(`[AccessControl] 🔍 VALIDATING DATA WITH SUCCESS:`, {
-          correlationId,
-          dataWithSuccessKeys: Object.keys(dataWithSuccess),
-          hasSuccess: "success" in dataWithSuccess,
-          successValue: dataWithSuccess.success,
-          hasAccepted: "accepted" in dataWithSuccess,
-          acceptedValue: dataWithSuccess.accepted,
-          hasRejected: "rejected" in dataWithSuccess,
-          rejectedValue: dataWithSuccess.rejected,
-          hasOutcomes: "outcomes" in dataWithSuccess,
-          outcomesValue: dataWithSuccess.outcomes,
-          fullDataWithSuccess: JSON.stringify(dataWithSuccess, null, 2),
-        });
-
-        // CRITICAL: Ensure all required fields are present before validation
-        if (
-          typeof dataWithSuccess.accepted !== "number" ||
-          typeof dataWithSuccess.rejected !== "number"
-        ) {
-          console.error(
-            `[AccessControl] ❌ MISSING REQUIRED FIELDS AFTER CONSTRUCTION:`,
-            {
-              correlationId,
-              hasAccepted: "accepted" in dataWithSuccess,
-              acceptedType: typeof dataWithSuccess.accepted,
-              acceptedValue: dataWithSuccess.accepted,
-              hasRejected: "rejected" in dataWithSuccess,
-              rejectedType: typeof dataWithSuccess.rejected,
-              rejectedValue: dataWithSuccess.rejected,
-              dataWithSuccessKeys: Object.keys(dataWithSuccess),
-              fullDataWithSuccess: JSON.stringify(dataWithSuccess, null, 2),
-              dataToValidateKeys: Object.keys(dataToValidate),
-              fullDataToValidate: JSON.stringify(dataToValidate, null, 2),
-              originalResponseData: JSON.stringify(responseData, null, 2),
-            }
-          );
-          throw new AgentShieldAPIError(
-            "invalid_response",
-            "Response data missing required fields (accepted/rejected)",
-            {
-              responseData,
-              dataToValidate,
-              dataWithSuccess,
-            }
-          );
-        }
-
-        const dataParsed =
-          proofSubmissionResponseSchema.safeParse(dataWithSuccess);
-        if (dataParsed.success) {
-          this.config.logger(
-            `[AccessControl] Proofs submitted successfully (wrapped)`,
-            {
-              correlationId,
-              accepted: dataParsed.data.accepted,
-              rejected: dataParsed.data.rejected,
-            }
-          );
-          return dataParsed.data;
-        } else {
-          // Log validation errors for wrapped response (always log errors)
-          const validationErrorLog = {
-            correlationId,
-            zodErrors: dataParsed.error.errors,
-            zodErrorDetails: JSON.stringify(dataParsed.error.errors, null, 2),
-            dataToValidate: JSON.stringify(dataToValidate, null, 2).substring(
-              0,
-              2000
-            ),
-            dataWithSuccess: JSON.stringify(dataWithSuccess, null, 2).substring(
-              0,
-              2000
-            ),
-            dataKeys: Object.keys(dataToValidate),
-            dataWithSuccessKeys: Object.keys(dataWithSuccess),
-            originalResponse: JSON.stringify(responseData, null, 2).substring(
-              0,
-              2000
-            ),
-          };
-          this.config.logger(
-            `[AccessControl] Wrapped response validation failed`,
-            validationErrorLog
-          );
-          // Also log to console.error for visibility in production
-          console.error(
-            `[AccessControl] Wrapped response validation failed`,
-            validationErrorLog
-          );
-          console.error(
-            `[AccessControl] Original wrapped response:`,
-            JSON.stringify(responseData, null, 2)
-          );
-
-          // CRITICAL: Log each zod error individually for easier debugging
-          console.error(
-            `[AccessControl] ❌ ZOD VALIDATION FAILED - ${dataParsed.error.errors.length} error(s):`
-          );
-          dataParsed.error.errors.forEach((err, idx) => {
-            const errorDetails: Record<string, unknown> = {
-              path: err.path.join(".") || "(root)",
-              message: err.message,
-              code: err.code,
-            };
-            // Only include properties that exist on specific error types
-            if ("received" in err) errorDetails.received = err.received;
-            if ("expected" in err) errorDetails.expected = err.expected;
-            if ("input" in err) errorDetails.input = err.input;
-            console.error(
-              `[AccessControl] Error ${idx + 1}:`,
-              JSON.stringify(errorDetails, null, 2)
-            );
-          });
-          console.error(
-            `[AccessControl] ❌ Full ZOD errors JSON:`,
-            JSON.stringify(dataParsed.error.errors, null, 2)
-          );
-          // CRITICAL: Throw error instead of falling through to direct parsing
-          // The response is wrapped, so direct parsing will also fail
-          throw new AgentShieldAPIError(
-            "invalid_response",
-            "Response validation failed",
-            { zodErrors: dataParsed.error.errors, responseData }
-          );
-        }
-      }
-
-      // Try parsing as direct ProofSubmissionResponse
-      const parsed = proofSubmissionResponseSchema.safeParse(responseData);
-      if (!parsed.success) {
-        // Log detailed validation errors (always log errors)
-        const validationErrorLog = {
-          correlationId,
-          zodErrors: parsed.error.errors,
-          zodErrorDetails: JSON.stringify(parsed.error.errors, null, 2),
-          responseData: JSON.stringify(responseData, null, 2),
-          responseDataType: typeof responseData,
-          responseKeys: Object.keys(
-            (responseData as Record<string, unknown>) || {}
-          ),
-          httpStatus: httpResponse.status,
-          httpStatusText: httpResponse.statusText,
-        };
-        this.config.logger(
-          `[AccessControl] Response validation failed`,
-          validationErrorLog
-        );
-        // CRITICAL: Log to console.error with full details for debugging
-        // This format matches test expectations: single call with message and error object
-        // This log must include 'Response validation failed' in the message for test compatibility
-        console.error(`[AccessControl] Response validation failed`, {
-          zodErrors: parsed.error.errors,
-          responseData: responseData,
-        });
-        // Additional detailed logging for debugging
-        console.error(
-          `[AccessControl] Response validation failed`,
-          validationErrorLog
-        );
-
-        // CRITICAL: Log each zod error individually for easier debugging
-        console.error(
-          `[AccessControl] ❌ ZOD VALIDATION FAILED (direct) - ${parsed.error.errors.length} error(s):`
-        );
-        parsed.error.errors.forEach((err, idx) => {
-          const errorDetails: Record<string, unknown> = {
-            path: err.path.join(".") || "(root)",
-            message: err.message,
-            code: err.code,
-          };
-          // Only include properties that exist on specific error types
-          if ("received" in err) errorDetails.received = err.received;
-          if ("expected" in err) errorDetails.expected = err.expected;
-          if ("input" in err) errorDetails.input = err.input;
-          console.error(`[AccessControl] Error ${idx + 1}:`, errorDetails);
-        });
-        console.error(
-          `[AccessControl] ❌ Full ZOD errors JSON:`,
-          JSON.stringify(parsed.error.errors, null, 2)
-        );
-        console.error(
-          `[AccessControl] ❌ ACTUAL RESPONSE DATA:`,
-          JSON.stringify(responseData, null, 2)
-        );
-        throw new AgentShieldAPIError(
-          "invalid_response",
-          "Response validation failed",
-          { zodErrors: parsed.error.errors, responseData }
-        );
-      }
-
-      this.config.logger(`[AccessControl] Proofs submitted successfully`, {
-        correlationId,
-        accepted: parsed.data.accepted,
-        rejected: parsed.data.rejected,
-      });
-
-      return parsed.data;
-    });
-  }
-
-  /**
-   * Get current metrics
-   */
-  getMetrics(): AccessControlApiServiceMetrics {
-    return { ...this.metrics };
-  }
-
-  /**
-   * Reset metrics
-   */
-  resetMetrics(): void {
-    this.metrics = {
-      successCount: 0,
-      errorCount: 0,
-      retryCount: 0,
-    };
-  }
-
-  /**
-   * Retry logic with exponential backoff
-   *
-   * @internal
-   */
-  private async retryWithBackoff<T>(
-    operation: () => Promise<T>,
-    retryCount = 0
-  ): Promise<T> {
-    try {
-      const result = await operation();
-      this.metrics.successCount++;
-      return result;
-    } catch (error: unknown) {
-      // Check if error is retryable (5xx status codes)
-      const isRetryable = this.isRetryableError(error);
-      const { maxRetries, initialDelayMs, maxDelayMs } =
-        this.config.retryConfig;
-
-      if (isRetryable && retryCount < maxRetries) {
-        const delay = Math.min(
-          initialDelayMs * Math.pow(2, retryCount),
-          maxDelayMs
-        );
-
-        this.metrics.retryCount++;
-        this.config.logger(
-          `Retrying after ${delay}ms (attempt ${retryCount + 1}/${maxRetries})`
-        );
-
-        await this.sleep(delay);
-        return this.retryWithBackoff(operation, retryCount + 1);
-      }
-
-      this.metrics.errorCount++;
-      throw error;
-    }
-  }
-
-  /**
-   * Check if an error is retryable (5xx status codes)
-   *
-   * @internal
-   */
-  private isRetryableError(error: unknown): boolean {
-    // Network errors (fetch failures) are retryable
-    if (error instanceof TypeError && error.message.includes("fetch")) {
-      return true;
-    }
-
-    // AgentShieldAPIError with 5xx status codes are retryable
-    if (error instanceof AgentShieldAPIError) {
-      // Check error code for server errors
-      if (error.code === "server_error") {
-        return true;
-      }
-
-      // Check if error details contain status code
-      const status = (error.details as { status?: number } | undefined)?.status;
-      if (status && status >= 500 && status < 600) {
-        return true;
-      }
-      // Rate limiting (429) is also retryable
-      if (status === 429) {
-        return true;
-      }
-    }
-
-    // Check for timeout errors
-    if (error instanceof Error) {
-      const message = error.message.toLowerCase();
-      if (message.includes("timeout") || message.includes("timed out")) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Sleep utility for retry delays
-   * Uses platform-agnostic sleep provider
-   *
-   * @internal
-   */
-  private sleep(ms: number): Promise<void> {
-    return this.config.sleepProvider(ms);
-  }
-
-  /**
-   * Parse response text to JSON with error handling
-   *
-   * @internal
-   */
-  private parseResponseJSON(response: Response, responseText: string): unknown {
-    try {
-      return JSON.parse(responseText);
-    } catch (error) {
-      // Handle non-JSON error responses (e.g., plain text "Internal Server Error")
-      if (!response.ok) {
-        const errorCode = this.mapStatusToErrorCode(response.status);
-        throw new AgentShieldAPIError(
-          errorCode,
-          `API request failed: ${response.status} ${response.statusText}`,
-          {
-            status: response.status,
-            responseText: responseText.substring(0, 500),
-          }
-        );
-      }
-      // For success responses that aren't JSON, throw invalid_response error
-      throw new AgentShieldAPIError(
-        "invalid_response",
-        `Failed to parse response: ${error instanceof Error ? error.message : String(error)}`,
-        { responseText: responseText.substring(0, 500) }
-      );
-    }
-  }
-
-  /**
-   * Map HTTP status codes to error codes
-   *
-   * @internal
-   */
-  private mapStatusToErrorCode(status: number, statusText = ""): string {
-    if (status === 400) {
-      return "validation_error";
-    } else if (status === 401 || status === 403) {
-      return "authentication_failed";
-    } else if (status === 404) {
-      return "config_not_found";
-    } else if (status >= 500) {
-      return "server_error";
-    }
-    return "api_error";
-  }
-
-  /**
-   * Handle error responses and throw appropriate AgentShieldAPIError
-   *
-   * @internal
-   */
-  private handleErrorResponse(
-    response: Response,
-    responseData: unknown
-  ): never {
-    const errorData = responseData as {
-      success?: boolean;
-      error?: AgentShieldAPIErrorResponse;
-    };
-
-    if (errorData.error) {
-      const errorCode = errorData.error.code || "api_error";
-      // Ensure error details include status code for retry detection
-      const errorDetails = {
-        ...(errorData.error.details || {}),
-        status: response.status,
-      };
-      throw new AgentShieldAPIError(
-        errorCode,
-        errorData.error.message || `API error: ${response.status}`,
-        errorDetails
-      );
-    }
-
-    // Map status codes to error codes
-    const errorCode = this.mapStatusToErrorCode(
-      response.status,
-      response.statusText
-    );
-    throw new AgentShieldAPIError(
-      errorCode,
-      `API request failed: ${response.status} ${response.statusText}`,
-      { status: response.status, responseData }
-    );
-  }
-}