@kya-os/checkpoint-nextjs 1.0.0

package/dist/api-client.js

@@ -0,0 +1,206 @@
+'use strict';
+
+// src/api-client.ts
+var DEFAULT_BASE_URL = "https://kya.vouched.id";
+var EDGE_DETECT_URL = "https://detect.checkpoint-gateway.ai";
+var DEFAULT_TIMEOUT = 5e3;
+var CheckpointApiClient = class {
+  apiKey;
+  baseUrl;
+  useEdge;
+  timeout;
+  debug;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("AgentShield API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.useEdge = config.useEdge !== false;
+    this.baseUrl = config.baseUrl || (this.useEdge ? EDGE_DETECT_URL : DEFAULT_BASE_URL);
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.debug = config.debug || false;
+  }
+  /**
+   * Call the enforce API to check if a request should be allowed
+   */
+  async enforce(input) {
+    const startTime = Date.now();
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const endpoint = this.useEdge ? `${this.baseUrl}/__detect/enforce` : `${this.baseUrl}/api/v1/enforce`;
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            "X-Request-ID": input.requestId || crypto.randomUUID()
+          },
+          body: JSON.stringify(input),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        const data = await response.json();
+        if (this.debug) {
+          console.log("[AgentShield] Enforce response:", {
+            status: response.status,
+            action: data.data?.decision.action,
+            processingTimeMs: Date.now() - startTime
+          });
+        }
+        if (!response.ok) {
+          return {
+            success: false,
+            error: {
+              code: `HTTP_${response.status}`,
+              message: data.error?.message || `HTTP error: ${response.status}`
+            }
+          };
+        }
+        return data;
+      } catch (error) {
+        clearTimeout(timeoutId);
+        throw error;
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        if (this.debug) {
+          console.warn("[AgentShield] Request timed out");
+        }
+        return {
+          success: false,
+          error: {
+            code: "TIMEOUT",
+            message: `Request timed out after ${this.timeout}ms`
+          }
+        };
+      }
+      if (this.debug) {
+        console.error("[AgentShield] Request failed:", error);
+      }
+      return {
+        success: false,
+        error: {
+          code: "NETWORK_ERROR",
+          message: error instanceof Error ? error.message : "Network request failed"
+        }
+      };
+    }
+  }
+  /**
+   * Quick check - returns just the action without full response parsing
+   * Useful for very fast middleware that just needs allow/block
+   */
+  async quickCheck(input) {
+    const result = await this.enforce(input);
+    if (!result.success || !result.data) {
+      return {
+        action: "allow",
+        error: result.error?.message
+      };
+    }
+    return {
+      action: result.data.decision.action
+    };
+  }
+  /**
+   * Check if this client is using edge detection (Gateway Worker)
+   */
+  isUsingEdge() {
+    return this.useEdge;
+  }
+  /**
+   * Log a detection result to AgentShield database.
+   * Use after Gateway Worker detection to persist results.
+   * Fire-and-forget - returns immediately without waiting for DB write.
+   *
+   * @example
+   * ```typescript
+   * // After receiving Gateway response
+   * if (client.isUsingEdge() && response.data?.detection) {
+   *   client.logDetection({
+   *     detection: response.data.detection,
+   *     context: { userAgent, ipAddress, path, url, method }
+   *   }).catch(err => console.error('Log failed:', err));
+   * }
+   * ```
+   */
+  async logDetection(input) {
+    const logEndpoint = this.useEdge ? `${DEFAULT_BASE_URL}/api/v1/log-detection` : `${this.baseUrl}/api/v1/log-detection`;
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(logEndpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`
+          },
+          body: JSON.stringify({
+            detection: {
+              isAgent: input.detection.isAgent,
+              confidence: input.detection.confidence,
+              agentName: input.detection.agentName,
+              agentType: input.detection.agentType,
+              detectionClass: input.detection.detectionClass,
+              verificationMethod: input.detection.verificationMethod,
+              reasons: input.detection.reasons
+            },
+            context: input.context,
+            source: input.source || "gateway"
+          }),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok && this.debug) {
+          console.warn("[AgentShield] Log detection returned non-2xx:", response.status);
+        }
+      } catch (error) {
+        clearTimeout(timeoutId);
+        throw error;
+      }
+    } catch (error) {
+      if (this.debug) {
+        console.error("[AgentShield] Log detection failed:", error);
+      }
+      throw error;
+    }
+  }
+};
+var clientInstance = null;
+function getCheckpointApiClient(config) {
+  if (!clientInstance) {
+    const apiKey = config?.apiKey || process.env.CHECKPOINT_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "AgentShield API key is required. Set CHECKPOINT_API_KEY environment variable or pass apiKey in config."
+      );
+    }
+    clientInstance = new CheckpointApiClient({
+      apiKey,
+      baseUrl: config?.baseUrl || process.env.AGENTSHIELD_API_URL,
+      // Default to edge detection unless explicitly disabled
+      useEdge: config?.useEdge ?? process.env.AGENTSHIELD_USE_EDGE !== "false",
+      timeout: config?.timeout,
+      debug: config?.debug || process.env.AGENTSHIELD_DEBUG === "true"
+    });
+  }
+  return clientInstance;
+}
+function resetCheckpointApiClient() {
+  clientInstance = null;
+}
+var AgentShieldClient = CheckpointApiClient;
+var getAgentShieldClient = getCheckpointApiClient;
+var resetAgentShieldClient = resetCheckpointApiClient;
+
+exports.AgentShieldClient = AgentShieldClient;
+exports.CheckpointApiClient = CheckpointApiClient;
+exports.getAgentShieldClient = getAgentShieldClient;
+exports.getCheckpointApiClient = getCheckpointApiClient;
+exports.resetAgentShieldClient = resetAgentShieldClient;
+exports.resetCheckpointApiClient = resetCheckpointApiClient;
+//# sourceMappingURL=api-client.js.map
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api-client.ts"],"names":[],"mappings":"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","file":"api-client.js","sourcesContent":["/**\n * AgentShield API Client\n *\n * Lightweight client for calling the AgentShield enforce API from middleware.\n * Designed for Edge Runtime compatibility (no Node.js-specific APIs).\n */\n\nimport type { EnforcementAction } from '@kya-os/checkpoint-shared';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * API client configuration\n */\nexport interface CheckpointApiClientConfig {\n  /** API key for authentication */\n  apiKey: string;\n  /** API base URL (defaults to production) */\n  baseUrl?: string;\n  /**\n   * Use edge detection for lower latency (~30-50ms vs ~150ms) and better coverage.\n   * Edge detection can identify non-JS clients (curl, Python, Claude Code WebFetch)\n   * that the pixel cannot detect since they don't execute JavaScript.\n   * @default true\n   */\n  useEdge?: boolean;\n  /** Request timeout in milliseconds (default: 5000) */\n  timeout?: number;\n  /** Enable debug logging */\n  debug?: boolean;\n}\n\n/**\n * Enforcement action — re-exported from `@kya-os/checkpoint-shared`\n * so consumers of this package can keep importing it from the same\n * place. The canonical 6-value union is defined in\n * `packages/checkpoint-shared/src/policy/constants.ts`. `'instruct'`\n * tells the middleware to emit a 401 with an MCP-I Link header\n * pointing the agent at a connect/consent URL.\n */\nexport type { EnforcementAction };\n\n/**\n * Enforcement decision from the API\n */\nexport interface EnforcementDecision {\n  action: EnforcementAction;\n  reason: string;\n  isAgent: boolean;\n  confidence: number;\n  agentName?: string;\n  agentType?: string;\n  redirectUrl?: string;\n  message?: string;\n  metadata?: {\n    policyVersion?: string;\n    signatureVerified?: boolean;\n    denyListMatch?: {\n      clientDid?: string;\n      agentDid?: string;\n      clientName?: string;\n      reason?: string;\n    };\n  };\n}\n\n/**\n * Detection result (optional in response)\n */\nexport interface DetectionResult {\n  isAgent: boolean;\n  confidence: number;\n  agentName?: string;\n  agentType?: string;\n  /** Detection class: 'human', 'ai_agent', 'bot', 'incomplete_data' */\n  detectionClass?: string;\n  verificationMethod?: string;\n  reasons?: string[];\n  /** Detection engine used: 'wasm' or 'javascript-fallback' */\n  detectionMethod?: string;\n}\n\n/**\n * Enforce API response\n */\nexport interface EnforceResponse {\n  success: boolean;\n  data?: {\n    decision: EnforcementDecision;\n    processingTimeMs: number;\n    requestId: string;\n    detection?: DetectionResult;\n  };\n  error?: {\n    code: string;\n    message: string;\n  };\n}\n\n/**\n * Request input for enforce API\n */\nexport interface EnforceInput {\n  /** HTTP headers from the incoming request */\n  headers?: Record<string, string>;\n  /** User-Agent header */\n  userAgent?: string;\n  /** Client IP address */\n  ipAddress?: string;\n  /** Request path */\n  path?: string;\n  /** Request URL */\n  url?: string;\n  /** HTTP method */\n  method?: string;\n  /** Request ID for tracing */\n  requestId?: string;\n  /** Options */\n  options?: {\n    /** Include full detection result */\n    includeDetectionResult?: boolean;\n    /** Cache TTL override */\n    cacheTTL?: number;\n  };\n}\n\n/**\n * Input for logging a detection result\n */\nexport interface LogDetectionInput {\n  /** Detection result from Gateway */\n  detection: DetectionResult;\n  /** Request context */\n  context: {\n    userAgent?: string;\n    ipAddress?: string;\n    path?: string;\n    url?: string;\n    method?: string;\n  };\n  /** Source of the detection */\n  source?: 'gateway' | 'middleware';\n}\n\n// ============================================================================\n// Client Implementation\n// ============================================================================\n\nconst DEFAULT_BASE_URL = 'https://kya.vouched.id';\nconst EDGE_DETECT_URL = 'https://detect.checkpoint-gateway.ai';\nconst DEFAULT_TIMEOUT = 5000;\n\n/**\n * AgentShield API Client\n *\n * @example\n * ```typescript\n * const client = new CheckpointApiClient({\n *   apiKey: process.env.CHECKPOINT_API_KEY!,\n * });\n *\n * const result = await client.enforce({\n *   headers: Object.fromEntries(request.headers),\n *   path: request.nextUrl.pathname,\n *   method: request.method,\n * });\n *\n * if (result.decision.action === 'block') {\n *   return new Response('Access denied', { status: 403 });\n * }\n * ```\n */\nexport class CheckpointApiClient {\n  private apiKey: string;\n  private baseUrl: string;\n  private useEdge: boolean;\n  private timeout: number;\n  private debug: boolean;\n\n  constructor(config: CheckpointApiClientConfig) {\n    if (!config.apiKey) {\n      throw new Error('AgentShield API key is required');\n    }\n\n    this.apiKey = config.apiKey;\n    // Default to edge detection for better coverage (detects non-JS clients)\n    this.useEdge = config.useEdge !== false; // true by default\n    this.baseUrl = config.baseUrl || (this.useEdge ? EDGE_DETECT_URL : DEFAULT_BASE_URL);\n    this.timeout = config.timeout || DEFAULT_TIMEOUT;\n    this.debug = config.debug || false;\n  }\n\n  /**\n   * Call the enforce API to check if a request should be allowed\n   */\n  async enforce(input: EnforceInput): Promise<EnforceResponse> {\n    const startTime = Date.now();\n\n    try {\n      // Create abort controller for timeout\n      const controller = new AbortController();\n      const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n      try {\n        // Use edge endpoint or Vercel API based on configuration\n        const endpoint = this.useEdge\n          ? `${this.baseUrl}/__detect/enforce`\n          : `${this.baseUrl}/api/v1/enforce`;\n\n        const response = await fetch(endpoint, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${this.apiKey}`,\n            'X-Request-ID': input.requestId || crypto.randomUUID(),\n          },\n          body: JSON.stringify(input),\n          signal: controller.signal,\n        });\n\n        clearTimeout(timeoutId);\n\n        // Parse response\n        const data = (await response.json()) as EnforceResponse;\n\n        if (this.debug) {\n          console.log('[AgentShield] Enforce response:', {\n            status: response.status,\n            action: data.data?.decision.action,\n            processingTimeMs: Date.now() - startTime,\n          });\n        }\n\n        // Handle non-2xx responses\n        if (!response.ok) {\n          return {\n            success: false,\n            error: {\n              code: `HTTP_${response.status}`,\n              message: data.error?.message || `HTTP error: ${response.status}`,\n            },\n          };\n        }\n\n        return data;\n      } catch (error) {\n        clearTimeout(timeoutId);\n        throw error;\n      }\n    } catch (error) {\n      // Handle timeout\n      if (error instanceof Error && error.name === 'AbortError') {\n        if (this.debug) {\n          console.warn('[AgentShield] Request timed out');\n        }\n        return {\n          success: false,\n          error: {\n            code: 'TIMEOUT',\n            message: `Request timed out after ${this.timeout}ms`,\n          },\n        };\n      }\n\n      // Handle network errors\n      if (this.debug) {\n        console.error('[AgentShield] Request failed:', error);\n      }\n\n      return {\n        success: false,\n        error: {\n          code: 'NETWORK_ERROR',\n          message: error instanceof Error ? error.message : 'Network request failed',\n        },\n      };\n    }\n  }\n\n  /**\n   * Quick check - returns just the action without full response parsing\n   * Useful for very fast middleware that just needs allow/block\n   */\n  async quickCheck(input: EnforceInput): Promise<{\n    action: EnforcementAction;\n    error?: string;\n  }> {\n    const result = await this.enforce(input);\n\n    if (!result.success || !result.data) {\n      // On error, default to allow (fail-open)\n      return {\n        action: 'allow',\n        error: result.error?.message,\n      };\n    }\n\n    return {\n      action: result.data.decision.action,\n    };\n  }\n\n  /**\n   * Check if this client is using edge detection (Gateway Worker)\n   */\n  isUsingEdge(): boolean {\n    return this.useEdge;\n  }\n\n  /**\n   * Log a detection result to AgentShield database.\n   * Use after Gateway Worker detection to persist results.\n   * Fire-and-forget - returns immediately without waiting for DB write.\n   *\n   * @example\n   * ```typescript\n   * // After receiving Gateway response\n   * if (client.isUsingEdge() && response.data?.detection) {\n   *   client.logDetection({\n   *     detection: response.data.detection,\n   *     context: { userAgent, ipAddress, path, url, method }\n   *   }).catch(err => console.error('Log failed:', err));\n   * }\n   * ```\n   */\n  async logDetection(input: LogDetectionInput): Promise<void> {\n    // Don't await - fire and forget\n    // Use the base URL (not edge) for logging since this goes to the main API\n    const logEndpoint = this.useEdge\n      ? `${DEFAULT_BASE_URL}/api/v1/log-detection`\n      : `${this.baseUrl}/api/v1/log-detection`;\n\n    try {\n      const controller = new AbortController();\n      const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n      try {\n        const response = await fetch(logEndpoint, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${this.apiKey}`,\n          },\n          body: JSON.stringify({\n            detection: {\n              isAgent: input.detection.isAgent,\n              confidence: input.detection.confidence,\n              agentName: input.detection.agentName,\n              agentType: input.detection.agentType,\n              detectionClass: input.detection.detectionClass,\n              verificationMethod: input.detection.verificationMethod,\n              reasons: input.detection.reasons,\n            },\n            context: input.context,\n            source: input.source || 'gateway',\n          }),\n          signal: controller.signal,\n        });\n\n        clearTimeout(timeoutId);\n\n        if (!response.ok && this.debug) {\n          console.warn('[AgentShield] Log detection returned non-2xx:', response.status);\n        }\n      } catch (error) {\n        clearTimeout(timeoutId);\n        throw error;\n      }\n    } catch (error) {\n      // Silently fail for fire-and-forget, but log in debug mode\n      if (this.debug) {\n        console.error('[AgentShield] Log detection failed:', error);\n      }\n      // Re-throw so caller can catch if needed\n      throw error;\n    }\n  }\n}\n\n/**\n * Create a singleton client instance\n *\n * @example\n * ```typescript\n * // In middleware.ts\n * import { getCheckpointApiClient } from '@kya-os/checkpoint-nextjs';\n *\n * const client = getCheckpointApiClient();\n * ```\n */\nlet clientInstance: CheckpointApiClient | null = null;\n\nexport function getCheckpointApiClient(\n  config?: Partial<CheckpointApiClientConfig>\n): CheckpointApiClient {\n  if (!clientInstance) {\n    const apiKey = config?.apiKey || process.env.CHECKPOINT_API_KEY;\n\n    if (!apiKey) {\n      throw new Error(\n        'AgentShield API key is required. Set CHECKPOINT_API_KEY environment variable or pass apiKey in config.'\n      );\n    }\n\n    clientInstance = new CheckpointApiClient({\n      apiKey,\n      baseUrl: config?.baseUrl || process.env.AGENTSHIELD_API_URL,\n      // Default to edge detection unless explicitly disabled\n      useEdge: config?.useEdge ?? process.env.AGENTSHIELD_USE_EDGE !== 'false',\n      timeout: config?.timeout,\n      debug: config?.debug || process.env.AGENTSHIELD_DEBUG === 'true',\n    });\n  }\n\n  return clientInstance;\n}\n\n/**\n * Reset the singleton client (useful for testing)\n */\nexport function resetCheckpointApiClient(): void {\n  clientInstance = null;\n}\n\n// ---------------------------------------------------------------------------\n// Back-compat aliases (Phase D rename — `AgentShield*` → `CheckpointApi*`).\n//\n// The SaaS-API deployment shape is preserved post-Phase-D — it talks to\n// the Cloudflare DNS gateway and remains a supported deployment option\n// alongside the local-engine `withCheckpoint` path. The names changed\n// to align with the rest of the `checkpoint-*` packages; the old names\n// stay live as @deprecated aliases for one release.\n// ---------------------------------------------------------------------------\n\n/** @deprecated Renamed to {@link CheckpointApiClient}. The runtime is identical. */\nexport const AgentShieldClient = CheckpointApiClient;\n\n/** @deprecated Renamed to {@link CheckpointApiClientConfig}. */\nexport type AgentShieldClientConfig = CheckpointApiClientConfig;\n\n/** @deprecated Renamed to {@link getCheckpointApiClient}. */\nexport const getAgentShieldClient = getCheckpointApiClient;\n\n/** @deprecated Renamed to {@link resetCheckpointApiClient}. */\nexport const resetAgentShieldClient = resetCheckpointApiClient;\n"]}

package/dist/api-client.mjs

@@ -0,0 +1,199 @@
+// src/api-client.ts
+var DEFAULT_BASE_URL = "https://kya.vouched.id";
+var EDGE_DETECT_URL = "https://detect.checkpoint-gateway.ai";
+var DEFAULT_TIMEOUT = 5e3;
+var CheckpointApiClient = class {
+  apiKey;
+  baseUrl;
+  useEdge;
+  timeout;
+  debug;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("AgentShield API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.useEdge = config.useEdge !== false;
+    this.baseUrl = config.baseUrl || (this.useEdge ? EDGE_DETECT_URL : DEFAULT_BASE_URL);
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.debug = config.debug || false;
+  }
+  /**
+   * Call the enforce API to check if a request should be allowed
+   */
+  async enforce(input) {
+    const startTime = Date.now();
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const endpoint = this.useEdge ? `${this.baseUrl}/__detect/enforce` : `${this.baseUrl}/api/v1/enforce`;
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            "X-Request-ID": input.requestId || crypto.randomUUID()
+          },
+          body: JSON.stringify(input),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        const data = await response.json();
+        if (this.debug) {
+          console.log("[AgentShield] Enforce response:", {
+            status: response.status,
+            action: data.data?.decision.action,
+            processingTimeMs: Date.now() - startTime
+          });
+        }
+        if (!response.ok) {
+          return {
+            success: false,
+            error: {
+              code: `HTTP_${response.status}`,
+              message: data.error?.message || `HTTP error: ${response.status}`
+            }
+          };
+        }
+        return data;
+      } catch (error) {
+        clearTimeout(timeoutId);
+        throw error;
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        if (this.debug) {
+          console.warn("[AgentShield] Request timed out");
+        }
+        return {
+          success: false,
+          error: {
+            code: "TIMEOUT",
+            message: `Request timed out after ${this.timeout}ms`
+          }
+        };
+      }
+      if (this.debug) {
+        console.error("[AgentShield] Request failed:", error);
+      }
+      return {
+        success: false,
+        error: {
+          code: "NETWORK_ERROR",
+          message: error instanceof Error ? error.message : "Network request failed"
+        }
+      };
+    }
+  }
+  /**
+   * Quick check - returns just the action without full response parsing
+   * Useful for very fast middleware that just needs allow/block
+   */
+  async quickCheck(input) {
+    const result = await this.enforce(input);
+    if (!result.success || !result.data) {
+      return {
+        action: "allow",
+        error: result.error?.message
+      };
+    }
+    return {
+      action: result.data.decision.action
+    };
+  }
+  /**
+   * Check if this client is using edge detection (Gateway Worker)
+   */
+  isUsingEdge() {
+    return this.useEdge;
+  }
+  /**
+   * Log a detection result to AgentShield database.
+   * Use after Gateway Worker detection to persist results.
+   * Fire-and-forget - returns immediately without waiting for DB write.
+   *
+   * @example
+   * ```typescript
+   * // After receiving Gateway response
+   * if (client.isUsingEdge() && response.data?.detection) {
+   *   client.logDetection({
+   *     detection: response.data.detection,
+   *     context: { userAgent, ipAddress, path, url, method }
+   *   }).catch(err => console.error('Log failed:', err));
+   * }
+   * ```
+   */
+  async logDetection(input) {
+    const logEndpoint = this.useEdge ? `${DEFAULT_BASE_URL}/api/v1/log-detection` : `${this.baseUrl}/api/v1/log-detection`;
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(logEndpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`
+          },
+          body: JSON.stringify({
+            detection: {
+              isAgent: input.detection.isAgent,
+              confidence: input.detection.confidence,
+              agentName: input.detection.agentName,
+              agentType: input.detection.agentType,
+              detectionClass: input.detection.detectionClass,
+              verificationMethod: input.detection.verificationMethod,
+              reasons: input.detection.reasons
+            },
+            context: input.context,
+            source: input.source || "gateway"
+          }),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok && this.debug) {
+          console.warn("[AgentShield] Log detection returned non-2xx:", response.status);
+        }
+      } catch (error) {
+        clearTimeout(timeoutId);
+        throw error;
+      }
+    } catch (error) {
+      if (this.debug) {
+        console.error("[AgentShield] Log detection failed:", error);
+      }
+      throw error;
+    }
+  }
+};
+var clientInstance = null;
+function getCheckpointApiClient(config) {
+  if (!clientInstance) {
+    const apiKey = config?.apiKey || process.env.CHECKPOINT_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "AgentShield API key is required. Set CHECKPOINT_API_KEY environment variable or pass apiKey in config."
+      );
+    }
+    clientInstance = new CheckpointApiClient({
+      apiKey,
+      baseUrl: config?.baseUrl || process.env.AGENTSHIELD_API_URL,
+      // Default to edge detection unless explicitly disabled
+      useEdge: config?.useEdge ?? process.env.AGENTSHIELD_USE_EDGE !== "false",
+      timeout: config?.timeout,
+      debug: config?.debug || process.env.AGENTSHIELD_DEBUG === "true"
+    });
+  }
+  return clientInstance;
+}
+function resetCheckpointApiClient() {
+  clientInstance = null;
+}
+var AgentShieldClient = CheckpointApiClient;
+var getAgentShieldClient = getCheckpointApiClient;
+var resetAgentShieldClient = resetCheckpointApiClient;
+
+export { AgentShieldClient, CheckpointApiClient, getAgentShieldClient, getCheckpointApiClient, resetAgentShieldClient, resetCheckpointApiClient };
+//# sourceMappingURL=api-client.mjs.map
+//# sourceMappingURL=api-client.mjs.map

package/dist/api-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api-client.ts"],"names":[],"mappings":"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","file":"api-client.mjs","sourcesContent":["/**\n * AgentShield API Client\n *\n * Lightweight client for calling the AgentShield enforce API from middleware.\n * Designed for Edge Runtime compatibility (no Node.js-specific APIs).\n */\n\nimport type { EnforcementAction } from '@kya-os/checkpoint-shared';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * API client configuration\n */\nexport interface CheckpointApiClientConfig {\n  /** API key for authentication */\n  apiKey: string;\n  /** API base URL (defaults to production) */\n  baseUrl?: string;\n  /**\n   * Use edge detection for lower latency (~30-50ms vs ~150ms) and better coverage.\n   * Edge detection can identify non-JS clients (curl, Python, Claude Code WebFetch)\n   * that the pixel cannot detect since they don't execute JavaScript.\n   * @default true\n   */\n  useEdge?: boolean;\n  /** Request timeout in milliseconds (default: 5000) */\n  timeout?: number;\n  /** Enable debug logging */\n  debug?: boolean;\n}\n\n/**\n * Enforcement action — re-exported from `@kya-os/checkpoint-shared`\n * so consumers of this package can keep importing it from the same\n * place. The canonical 6-value union is defined in\n * `packages/checkpoint-shared/src/policy/constants.ts`. `'instruct'`\n * tells the middleware to emit a 401 with an MCP-I Link header\n * pointing the agent at a connect/consent URL.\n */\nexport type { EnforcementAction };\n\n/**\n * Enforcement decision from the API\n */\nexport interface EnforcementDecision {\n  action: EnforcementAction;\n  reason: string;\n  isAgent: boolean;\n  confidence: number;\n  agentName?: string;\n  agentType?: string;\n  redirectUrl?: string;\n  message?: string;\n  metadata?: {\n    policyVersion?: string;\n    signatureVerified?: boolean;\n    denyListMatch?: {\n      clientDid?: string;\n      agentDid?: string;\n      clientName?: string;\n      reason?: string;\n    };\n  };\n}\n\n/**\n * Detection result (optional in response)\n */\nexport interface DetectionResult {\n  isAgent: boolean;\n  confidence: number;\n  agentName?: string;\n  agentType?: string;\n  /** Detection class: 'human', 'ai_agent', 'bot', 'incomplete_data' */\n  detectionClass?: string;\n  verificationMethod?: string;\n  reasons?: string[];\n  /** Detection engine used: 'wasm' or 'javascript-fallback' */\n  detectionMethod?: string;\n}\n\n/**\n * Enforce API response\n */\nexport interface EnforceResponse {\n  success: boolean;\n  data?: {\n    decision: EnforcementDecision;\n    processingTimeMs: number;\n    requestId: string;\n    detection?: DetectionResult;\n  };\n  error?: {\n    code: string;\n    message: string;\n  };\n}\n\n/**\n * Request input for enforce API\n */\nexport interface EnforceInput {\n  /** HTTP headers from the incoming request */\n  headers?: Record<string, string>;\n  /** User-Agent header */\n  userAgent?: string;\n  /** Client IP address */\n  ipAddress?: string;\n  /** Request path */\n  path?: string;\n  /** Request URL */\n  url?: string;\n  /** HTTP method */\n  method?: string;\n  /** Request ID for tracing */\n  requestId?: string;\n  /** Options */\n  options?: {\n    /** Include full detection result */\n    includeDetectionResult?: boolean;\n    /** Cache TTL override */\n    cacheTTL?: number;\n  };\n}\n\n/**\n * Input for logging a detection result\n */\nexport interface LogDetectionInput {\n  /** Detection result from Gateway */\n  detection: DetectionResult;\n  /** Request context */\n  context: {\n    userAgent?: string;\n    ipAddress?: string;\n    path?: string;\n    url?: string;\n    method?: string;\n  };\n  /** Source of the detection */\n  source?: 'gateway' | 'middleware';\n}\n\n// ============================================================================\n// Client Implementation\n// ============================================================================\n\nconst DEFAULT_BASE_URL = 'https://kya.vouched.id';\nconst EDGE_DETECT_URL = 'https://detect.checkpoint-gateway.ai';\nconst DEFAULT_TIMEOUT = 5000;\n\n/**\n * AgentShield API Client\n *\n * @example\n * ```typescript\n * const client = new CheckpointApiClient({\n *   apiKey: process.env.CHECKPOINT_API_KEY!,\n * });\n *\n * const result = await client.enforce({\n *   headers: Object.fromEntries(request.headers),\n *   path: request.nextUrl.pathname,\n *   method: request.method,\n * });\n *\n * if (result.decision.action === 'block') {\n *   return new Response('Access denied', { status: 403 });\n * }\n * ```\n */\nexport class CheckpointApiClient {\n  private apiKey: string;\n  private baseUrl: string;\n  private useEdge: boolean;\n  private timeout: number;\n  private debug: boolean;\n\n  constructor(config: CheckpointApiClientConfig) {\n    if (!config.apiKey) {\n      throw new Error('AgentShield API key is required');\n    }\n\n    this.apiKey = config.apiKey;\n    // Default to edge detection for better coverage (detects non-JS clients)\n    this.useEdge = config.useEdge !== false; // true by default\n    this.baseUrl = config.baseUrl || (this.useEdge ? EDGE_DETECT_URL : DEFAULT_BASE_URL);\n    this.timeout = config.timeout || DEFAULT_TIMEOUT;\n    this.debug = config.debug || false;\n  }\n\n  /**\n   * Call the enforce API to check if a request should be allowed\n   */\n  async enforce(input: EnforceInput): Promise<EnforceResponse> {\n    const startTime = Date.now();\n\n    try {\n      // Create abort controller for timeout\n      const controller = new AbortController();\n      const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n      try {\n        // Use edge endpoint or Vercel API based on configuration\n        const endpoint = this.useEdge\n          ? `${this.baseUrl}/__detect/enforce`\n          : `${this.baseUrl}/api/v1/enforce`;\n\n        const response = await fetch(endpoint, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${this.apiKey}`,\n            'X-Request-ID': input.requestId || crypto.randomUUID(),\n          },\n          body: JSON.stringify(input),\n          signal: controller.signal,\n        });\n\n        clearTimeout(timeoutId);\n\n        // Parse response\n        const data = (await response.json()) as EnforceResponse;\n\n        if (this.debug) {\n          console.log('[AgentShield] Enforce response:', {\n            status: response.status,\n            action: data.data?.decision.action,\n            processingTimeMs: Date.now() - startTime,\n          });\n        }\n\n        // Handle non-2xx responses\n        if (!response.ok) {\n          return {\n            success: false,\n            error: {\n              code: `HTTP_${response.status}`,\n              message: data.error?.message || `HTTP error: ${response.status}`,\n            },\n          };\n        }\n\n        return data;\n      } catch (error) {\n        clearTimeout(timeoutId);\n        throw error;\n      }\n    } catch (error) {\n      // Handle timeout\n      if (error instanceof Error && error.name === 'AbortError') {\n        if (this.debug) {\n          console.warn('[AgentShield] Request timed out');\n        }\n        return {\n          success: false,\n          error: {\n            code: 'TIMEOUT',\n            message: `Request timed out after ${this.timeout}ms`,\n          },\n        };\n      }\n\n      // Handle network errors\n      if (this.debug) {\n        console.error('[AgentShield] Request failed:', error);\n      }\n\n      return {\n        success: false,\n        error: {\n          code: 'NETWORK_ERROR',\n          message: error instanceof Error ? error.message : 'Network request failed',\n        },\n      };\n    }\n  }\n\n  /**\n   * Quick check - returns just the action without full response parsing\n   * Useful for very fast middleware that just needs allow/block\n   */\n  async quickCheck(input: EnforceInput): Promise<{\n    action: EnforcementAction;\n    error?: string;\n  }> {\n    const result = await this.enforce(input);\n\n    if (!result.success || !result.data) {\n      // On error, default to allow (fail-open)\n      return {\n        action: 'allow',\n        error: result.error?.message,\n      };\n    }\n\n    return {\n      action: result.data.decision.action,\n    };\n  }\n\n  /**\n   * Check if this client is using edge detection (Gateway Worker)\n   */\n  isUsingEdge(): boolean {\n    return this.useEdge;\n  }\n\n  /**\n   * Log a detection result to AgentShield database.\n   * Use after Gateway Worker detection to persist results.\n   * Fire-and-forget - returns immediately without waiting for DB write.\n   *\n   * @example\n   * ```typescript\n   * // After receiving Gateway response\n   * if (client.isUsingEdge() && response.data?.detection) {\n   *   client.logDetection({\n   *     detection: response.data.detection,\n   *     context: { userAgent, ipAddress, path, url, method }\n   *   }).catch(err => console.error('Log failed:', err));\n   * }\n   * ```\n   */\n  async logDetection(input: LogDetectionInput): Promise<void> {\n    // Don't await - fire and forget\n    // Use the base URL (not edge) for logging since this goes to the main API\n    const logEndpoint = this.useEdge\n      ? `${DEFAULT_BASE_URL}/api/v1/log-detection`\n      : `${this.baseUrl}/api/v1/log-detection`;\n\n    try {\n      const controller = new AbortController();\n      const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n      try {\n        const response = await fetch(logEndpoint, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${this.apiKey}`,\n          },\n          body: JSON.stringify({\n            detection: {\n              isAgent: input.detection.isAgent,\n              confidence: input.detection.confidence,\n              agentName: input.detection.agentName,\n              agentType: input.detection.agentType,\n              detectionClass: input.detection.detectionClass,\n              verificationMethod: input.detection.verificationMethod,\n              reasons: input.detection.reasons,\n            },\n            context: input.context,\n            source: input.source || 'gateway',\n          }),\n          signal: controller.signal,\n        });\n\n        clearTimeout(timeoutId);\n\n        if (!response.ok && this.debug) {\n          console.warn('[AgentShield] Log detection returned non-2xx:', response.status);\n        }\n      } catch (error) {\n        clearTimeout(timeoutId);\n        throw error;\n      }\n    } catch (error) {\n      // Silently fail for fire-and-forget, but log in debug mode\n      if (this.debug) {\n        console.error('[AgentShield] Log detection failed:', error);\n      }\n      // Re-throw so caller can catch if needed\n      throw error;\n    }\n  }\n}\n\n/**\n * Create a singleton client instance\n *\n * @example\n * ```typescript\n * // In middleware.ts\n * import { getCheckpointApiClient } from '@kya-os/checkpoint-nextjs';\n *\n * const client = getCheckpointApiClient();\n * ```\n */\nlet clientInstance: CheckpointApiClient | null = null;\n\nexport function getCheckpointApiClient(\n  config?: Partial<CheckpointApiClientConfig>\n): CheckpointApiClient {\n  if (!clientInstance) {\n    const apiKey = config?.apiKey || process.env.CHECKPOINT_API_KEY;\n\n    if (!apiKey) {\n      throw new Error(\n        'AgentShield API key is required. Set CHECKPOINT_API_KEY environment variable or pass apiKey in config.'\n      );\n    }\n\n    clientInstance = new CheckpointApiClient({\n      apiKey,\n      baseUrl: config?.baseUrl || process.env.AGENTSHIELD_API_URL,\n      // Default to edge detection unless explicitly disabled\n      useEdge: config?.useEdge ?? process.env.AGENTSHIELD_USE_EDGE !== 'false',\n      timeout: config?.timeout,\n      debug: config?.debug || process.env.AGENTSHIELD_DEBUG === 'true',\n    });\n  }\n\n  return clientInstance;\n}\n\n/**\n * Reset the singleton client (useful for testing)\n */\nexport function resetCheckpointApiClient(): void {\n  clientInstance = null;\n}\n\n// ---------------------------------------------------------------------------\n// Back-compat aliases (Phase D rename — `AgentShield*` → `CheckpointApi*`).\n//\n// The SaaS-API deployment shape is preserved post-Phase-D — it talks to\n// the Cloudflare DNS gateway and remains a supported deployment option\n// alongside the local-engine `withCheckpoint` path. The names changed\n// to align with the rest of the `checkpoint-*` packages; the old names\n// stay live as @deprecated aliases for one release.\n// ---------------------------------------------------------------------------\n\n/** @deprecated Renamed to {@link CheckpointApiClient}. The runtime is identical. */\nexport const AgentShieldClient = CheckpointApiClient;\n\n/** @deprecated Renamed to {@link CheckpointApiClientConfig}. */\nexport type AgentShieldClientConfig = CheckpointApiClientConfig;\n\n/** @deprecated Renamed to {@link getCheckpointApiClient}. */\nexport const getAgentShieldClient = getCheckpointApiClient;\n\n/** @deprecated Renamed to {@link resetCheckpointApiClient}. */\nexport const resetAgentShieldClient = resetCheckpointApiClient;\n"]}

package/dist/api-middleware.d.mts

@@ -0,0 +1,156 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { EnforcementDecision } from './api-client.mjs';
+import '@kya-os/checkpoint-shared';
+
+/**
+ * API-based AgentShield Middleware for Next.js
+ *
+ * This middleware uses the AgentShield API for detection and enforcement,
+ * instead of running detection locally. This approach:
+ *
+ * 1. Works reliably in Edge Runtime (no WASM loading issues)
+ * 2. Ensures consistent detection across all platforms
+ * 3. Applies centralized policies from the dashboard
+ * 4. Supports deny lists, thresholds, and path rules
+ *
+ * @example
+ * ```typescript
+ * // middleware.ts
+ * import { withCheckpointApi } from '@kya-os/checkpoint-nextjs/api-middleware';
+ *
+ * export default withCheckpointApi({
+ *   apiKey: process.env.CHECKPOINT_API_KEY!,
+ *   // Optional overrides:
+ *   onBlock: 'redirect', // 'block' | 'redirect' | 'challenge'
+ *   redirectUrl: '/blocked',
+ *   skipPaths: ['/api/health', '/_next/*'],
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next/static|favicon.ico).*)'],
+ * };
+ * ```
+ */
+
+/**
+ * Middleware configuration
+ */
+interface CheckpointApiMiddlewareConfig {
+    /** API key (or use CHECKPOINT_API_KEY env var) */
+    apiKey?: string;
+    /** API base URL (defaults to production) */
+    apiUrl?: string;
+    /**
+     * Use edge detection for lower latency (~30-50ms vs ~150ms) and better coverage.
+     * Edge detection can identify non-JS clients (curl, Python, Claude Code WebFetch)
+     * that the pixel cannot detect since they don't execute JavaScript.
+     * Set to false to use the Vercel API instead.
+     * @default true
+     */
+    useEdge?: boolean;
+    /** Request timeout in ms (default: 5000) */
+    timeout?: number;
+    /**
+     * Action to take when an agent should be blocked
+     * - 'block': Return 403 response
+     * - 'redirect': Redirect to redirectUrl
+     * - 'challenge': Show a challenge page (future)
+     * Default: uses policy from dashboard
+     */
+    onBlock?: 'block' | 'redirect' | 'challenge';
+    /**
+     * URL to redirect to when blocking (if onBlock is 'redirect')
+     * Default: uses redirectUrl from dashboard policy
+     */
+    redirectUrl?: string;
+    /**
+     * How the middleware handles a `redirect` / `instruct` action.
+     *
+     * - `'instruct'` (default): return HTTP 401 with an MCP-I Link header + JSON
+     *   body pointing the agent at the redirect URL. LLMs surface the URL as a
+     *   clickable link for the user. Matches the Cloudflare Gateway contract.
+     * - `'http'`: legacy behavior — return HTTP 302 with `Location`. Most LLM
+     *   fetchers won't follow the redirect, so this is only useful when your
+     *   traffic is real browsers.
+     *
+     * @default 'instruct'
+     */
+    redirectMode?: 'instruct' | 'http';
+    /**
+     * Custom blocked response
+     */
+    blockedResponse?: {
+        status?: number;
+        message?: string;
+        headers?: Record<string, string>;
+    };
+    /**
+     * Paths to skip (in addition to dashboard policy)
+     * Supports glob patterns: '/api/*', '/_next/*'
+     */
+    skipPaths?: string[];
+    /**
+     * Only enforce on these paths (overrides dashboard policy)
+     */
+    includePaths?: string[];
+    /**
+     * Callback when an agent is detected
+     */
+    onAgentDetected?: (request: NextRequest, decision: EnforcementDecision) => void | Promise<void>;
+    /**
+     * Callback to customize the blocked response
+     */
+    customBlockedResponse?: (request: NextRequest, decision: EnforcementDecision) => NextResponse | Promise<NextResponse>;
+    /**
+     * Whether to fail open (allow) on API errors
+     * Default: true (recommended for production)
+     */
+    failOpen?: boolean;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * Create AgentShield middleware with API-based detection
+ *
+ * @example
+ * ```typescript
+ * // middleware.ts
+ * import { withCheckpointApi } from '@kya-os/checkpoint-nextjs/api-middleware';
+ *
+ * export default withCheckpointApi({
+ *   onBlock: 'block',
+ *   skipPaths: ['/api/health'],
+ * });
+ * ```
+ */
+declare function withCheckpointApi(config?: CheckpointApiMiddlewareConfig): (request: NextRequest) => Promise<NextResponse>;
+/** @deprecated Renamed to {@link withCheckpointApi}. The behaviour is identical. */
+declare const withAgentShield: typeof withCheckpointApi;
+/** @deprecated Renamed to {@link CheckpointApiMiddlewareConfig}. */
+type AgentShieldMiddlewareConfig = CheckpointApiMiddlewareConfig;
+/**
+ * @deprecated Module-load-time invocation of the legacy `withAgentShield()`.
+ * Construct the middleware explicitly via `withCheckpointApi({ apiKey })`
+ * instead of relying on a default-constructed singleton at import time.
+ */
+declare function agentShieldMiddleware(_request: NextRequest): Promise<NextResponse>;
+/**
+ * @deprecated The "enhanced middleware" combined detection + storage +
+ * enforcement into a single legacy path that no longer exists. Migrate
+ * to `withCheckpoint` (local-engine) or `withCheckpointApi` (SaaS-gateway).
+ */
+declare function createEnhancedAgentShieldMiddleware(_config?: EnhancedMiddlewareConfig): (request: NextRequest) => Promise<NextResponse>;
+/** @deprecated The enhanced-middleware path is gone. Use `CheckpointConfig` (local-engine) or `CheckpointApiMiddlewareConfig` (SaaS). */
+type EnhancedMiddlewareConfig = Record<string, unknown>;
+/** @deprecated Storage was tied to the legacy enhanced-middleware path. */
+type StorageAdapter = Record<string, unknown>;
+/** @deprecated Storage was tied to the legacy enhanced-middleware path. */
+type StorageConfig = Record<string, unknown>;
+/** @deprecated Detection events now flow through the engine; the legacy event shape no longer applies. */
+type AgentDetectionEvent = Record<string, unknown>;
+/** @deprecated Use `EdgeSessionTracker` / `StatelessSessionChecker` from `./session-tracker`. */
+type AgentSession = Record<string, unknown>;
+
+export { type AgentDetectionEvent, type AgentSession, type AgentShieldMiddlewareConfig, type CheckpointApiMiddlewareConfig, type EnhancedMiddlewareConfig, type StorageAdapter, type StorageConfig, agentShieldMiddleware, createEnhancedAgentShieldMiddleware, withAgentShield, withCheckpointApi };