@kya-os/mcp-i-core 1.2.2-canary.25 → 1.2.2-canary.26

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

@@ -0,0 +1,877 @@
+/**
+ * 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)
+        const dataToValidate = wrappedResponse.data as Record<string, unknown>;
+        
+        // CRITICAL: Log the actual data structure for debugging
+        console.error(`[AccessControl] 🔍 DATA OBJECT STRUCTURE:`, {
+          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,
+          rejectedType: typeof dataToValidate.rejected,
+          outcomesType: typeof 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
+        const dataWithSuccess = {
+          ...dataToValidate,
+          success: wrappedResponse.success === true, // Explicitly use wrapped success value
+        };
+
+        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),
+            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}:`, errorDetails);
+          });
+          console.error(
+            `[AccessControl] ❌ Full ZOD errors JSON:`,
+            JSON.stringify(dataParsed.error.errors, null, 2)
+          );
+        }
+      }
+
+      // 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 }
+    );
+  }
+}