@kya-os/checkpoint-nextjs 1.0.0

package/dist/api-middleware.d.ts

@@ -0,0 +1,156 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { EnforcementDecision } from './api-client.js';
+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 };

package/dist/api-middleware.js

@@ -0,0 +1,510 @@
+'use strict';
+
+var server = require('next/server');
+var checkpointShared = require('@kya-os/checkpoint-shared');
+
+// src/api-middleware.ts
+
+// 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;
+}
+
+// src/utils.ts
+function getClientIp(request) {
+  const forwardedFor = request.headers.get("x-forwarded-for");
+  if (forwardedFor) {
+    const ip = forwardedFor.split(",")[0]?.trim();
+    if (ip) return ip;
+  }
+  const realIp = request.headers.get("x-real-ip");
+  if (realIp) return realIp;
+  const cfIp = request.headers.get("cf-connecting-ip");
+  if (cfIp) return cfIp;
+  const clientIp = request.headers.get("x-client-ip");
+  if (clientIp) return clientIp;
+  return void 0;
+}
+function safeHostname(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return "this site";
+  }
+}
+
+// src/responses/agent-instruction.ts
+var MCP_I_DOCS_URL = "https://docs.knowthat.ai/mcp-i/getting-started";
+var DEFAULT_CONNECT_PATH = "/connect";
+function buildAgentInstructionResponse(request, decision, redirectUrl) {
+  const resolved = resolveUrl(redirectUrl ?? DEFAULT_CONNECT_PATH, request.url);
+  const agentName = decision.agentName || decision.agentType || "unknown";
+  if (!resolved.searchParams.has("agent")) {
+    resolved.searchParams.set("agent", agentName.toLowerCase());
+  }
+  const authUrl = resolved.toString();
+  const hostname = safeHostname(request.url);
+  const body = {
+    // Markdown-formatted so clients that render markdown (Claude Desktop,
+    // ChatGPT web) surface the URL as a clickable link. Tone mirrors the
+    // gateway response so messaging stays consistent across platforms.
+    message: `I can't access ${hostname} yet \u2014 this site checks AI assistants at the front door.
+
+**To give me access, open this link:**
+[Connect securely to ${hostname}](${authUrl})
+
+It only takes a moment and you won't need to do it again. Once you're done, ask me to try again and I'll connect through the verified channel automatically.`,
+    user_action_required: {
+      action: `Connect securely to ${hostname}`,
+      url: authUrl,
+      reason: `${hostname} checks AI assistants before they connect. Open the link to give your assistant a verified key.`
+    },
+    mcp_i: {
+      version: "1.0",
+      action: "authenticate",
+      authorization_url: authUrl,
+      flow: {
+        type: "oauth2_delegation",
+        steps: [
+          "1. Direct your user to the authorization_url",
+          "2. User reviews requested scopes and grants consent",
+          "3. Receive delegation credential (JWT)",
+          "4. Include credential in KYA-Delegation header",
+          "5. Retry this request with the proof"
+        ]
+      },
+      retry_instructions: {
+        header: "KYA-Delegation",
+        format: "JWT delegation credential from authorization flow"
+      },
+      documentation: MCP_I_DOCS_URL
+    },
+    error: "mcp_authentication_required",
+    code: "AGENT_REQUIRES_DELEGATION",
+    detection: {
+      agent_type: decision.agentType || "ai_agent",
+      agent_name: decision.agentName || "Unknown Agent",
+      confidence: decision.confidence
+    }
+  };
+  const response = server.NextResponse.json(body, { status: 401 });
+  response.headers.set("WWW-Authenticate", `KYA realm="api", authorization_uri="${authUrl}"`);
+  response.headers.set(
+    "Link",
+    `<${authUrl}>; rel="kya-authorize", <${MCP_I_DOCS_URL}>; rel="help"`
+  );
+  response.headers.set("KYA-Auth-Required", "true");
+  response.headers.set("KYA-Auth-Url", authUrl);
+  response.headers.set("KYA-Action", "instruct");
+  response.headers.set("KYA-Detected-Agent", agentName);
+  response.headers.set("KYA-Confidence", decision.confidence.toString());
+  response.headers.set("Cache-Control", "no-store");
+  return response;
+}
+function resolveUrl(target, baseUrl) {
+  try {
+    return new URL(target, baseUrl);
+  } catch {
+    return new URL(DEFAULT_CONNECT_PATH, baseUrl);
+  }
+}
+
+// src/api-middleware.ts
+function shouldSkipPath(path, skipPaths) {
+  return skipPaths.some((pattern) => checkpointShared.matchPath(path, pattern));
+}
+function shouldIncludePath(path, includePaths) {
+  if (!includePaths || includePaths.length === 0) return true;
+  return includePaths.some((pattern) => checkpointShared.matchPath(path, pattern));
+}
+function buildBlockedResponse(request, decision, config) {
+  const status = config.blockedResponse?.status ?? 403;
+  const message = config.blockedResponse?.message ?? decision.message ?? "Access denied";
+  const recoveryUrl = resolveRecoveryUrl(request, config.redirectUrl || decision.redirectUrl);
+  const body = {
+    error: message,
+    code: "AGENT_BLOCKED",
+    reason: decision.reason,
+    agentType: decision.agentType
+  };
+  if (recoveryUrl) {
+    const hostname = safeHostname(request.url);
+    body.user_action_required = {
+      action: `Connect securely to ${hostname}`,
+      url: recoveryUrl,
+      reason: `${hostname} blocks unverified AI assistants. Open the link to give your assistant a verified key and try again.`
+    };
+    body.message = `I can't access ${hostname} \u2014 this site blocks unverified AI assistants.
+
+**To give me access, open this link:**
+[Connect securely to ${hostname}](${recoveryUrl})
+
+Once you're done, ask me to try again.`;
+  }
+  const response = server.NextResponse.json(body, { status });
+  if (config.blockedResponse?.headers) {
+    for (const [key, value] of Object.entries(config.blockedResponse.headers)) {
+      response.headers.set(key, value);
+    }
+  }
+  if (recoveryUrl) {
+    response.headers.set("Link", `<${recoveryUrl}>; rel="kya-authorize"`);
+    response.headers.set("KYA-Auth-Url", recoveryUrl);
+  }
+  response.headers.set("KYA-Action", decision.action);
+  response.headers.set("KYA-Reason", decision.reason);
+  return response;
+}
+function resolveRecoveryUrl(request, target) {
+  if (!target) return void 0;
+  try {
+    return new URL(target, request.url).toString();
+  } catch {
+    return void 0;
+  }
+}
+function buildRedirectResponse(request, decision, config) {
+  const redirectUrl = config.redirectUrl || decision.redirectUrl || "/blocked";
+  const url = new URL(redirectUrl, request.url);
+  url.searchParams.set("reason", decision.reason);
+  if (decision.agentType) {
+    url.searchParams.set("agent", decision.agentType);
+  }
+  return server.NextResponse.redirect(url);
+}
+function withCheckpointApi(config = {}) {
+  let client = null;
+  const getClient = () => {
+    if (!client) {
+      client = getCheckpointApiClient({
+        apiKey: config.apiKey,
+        baseUrl: config.apiUrl,
+        useEdge: config.useEdge,
+        timeout: config.timeout,
+        debug: config.debug
+      });
+    }
+    return client;
+  };
+  const defaultSkipPaths = [
+    "/_next/static/**",
+    "/_next/image/**",
+    "/favicon.ico",
+    "/robots.txt",
+    "/sitemap.xml"
+  ];
+  const skipPaths = [...defaultSkipPaths, ...config.skipPaths || []];
+  const failOpen = config.failOpen ?? true;
+  return async function middleware(request) {
+    const path = request.nextUrl.pathname;
+    const startTime = Date.now();
+    if (shouldSkipPath(path, skipPaths)) {
+      return server.NextResponse.next();
+    }
+    if (!shouldIncludePath(path, config.includePaths)) {
+      return server.NextResponse.next();
+    }
+    try {
+      const client2 = getClient();
+      const userAgent = request.headers.get("user-agent") || void 0;
+      const ipAddress = getClientIp(request);
+      const result = await client2.enforce({
+        headers: Object.fromEntries(request.headers.entries()),
+        userAgent,
+        ipAddress,
+        path,
+        url: request.url,
+        method: request.method,
+        requestId: request.headers.get("x-request-id") || void 0,
+        options: {
+          // Always include detection results for logging (needed when using edge)
+          includeDetectionResult: true
+        }
+      });
+      if (!result.success || !result.data) {
+        if (config.debug) {
+          console.warn("[AgentShield] API error:", result.error);
+        }
+        if (failOpen) {
+          return server.NextResponse.next();
+        }
+        return server.NextResponse.json(
+          { error: "Security check failed", code: "API_ERROR" },
+          { status: 503 }
+        );
+      }
+      const decision = result.data.decision;
+      if (config.debug) {
+        console.log("[AgentShield] Decision:", {
+          path,
+          action: decision.action,
+          isAgent: decision.isAgent,
+          confidence: decision.confidence,
+          agentName: decision.agentName,
+          detectionMethod: result.data.detection?.detectionMethod || "not-included",
+          processingTimeMs: Date.now() - startTime
+        });
+      }
+      if (client2.isUsingEdge() && result.data.detection) {
+        client2.logDetection({
+          detection: result.data.detection,
+          context: { userAgent, ipAddress, path, url: request.url, method: request.method }
+        }).catch((err) => {
+          if (config.debug) {
+            console.error("[AgentShield] Log detection failed:", err);
+          }
+        });
+      }
+      if (decision.isAgent && config.onAgentDetected) {
+        await config.onAgentDetected(request, decision);
+      }
+      const redirectMode = config.redirectMode ?? "instruct";
+      switch (decision.action) {
+        case "block": {
+          if (config.customBlockedResponse) {
+            return await config.customBlockedResponse(request, decision);
+          }
+          if (config.onBlock === "redirect") {
+            return buildRedirectResponse(request, decision, config);
+          }
+          return buildBlockedResponse(request, decision, config);
+        }
+        case "redirect":
+        case "instruct": {
+          if (redirectMode === "http" && decision.action === "redirect") {
+            return buildRedirectResponse(request, decision, config);
+          }
+          const targetUrl = config.redirectUrl || decision.redirectUrl;
+          return buildAgentInstructionResponse(request, decision, targetUrl);
+        }
+        case "challenge": {
+          return buildRedirectResponse(request, decision, config);
+        }
+        case "log":
+        case "allow":
+        default: {
+          const response = server.NextResponse.next();
+          if (decision.isAgent) {
+            response.headers.set("KYA-Detected", "true");
+            response.headers.set("KYA-Confidence", decision.confidence.toString());
+            if (decision.agentName) {
+              response.headers.set("KYA-Agent", decision.agentName);
+            }
+          }
+          return response;
+        }
+      }
+    } catch (error) {
+      if (config.debug) {
+        console.error("[AgentShield] Middleware error:", error);
+      }
+      if (failOpen) {
+        return server.NextResponse.next();
+      }
+      return server.NextResponse.json(
+        { error: "Security check failed", code: "MIDDLEWARE_ERROR" },
+        { status: 503 }
+      );
+    }
+  };
+}
+var withAgentShield = withCheckpointApi;
+var LEGACY_MIGRATION_ERROR = "This export was removed in Phase D. Migrate to `withCheckpoint` (local-engine deployment) or `withCheckpointApi` (SaaS-gateway deployment) from `@kya-os/checkpoint-nextjs`. See packages/checkpoint-nextjs/README.md (Two deployment shapes) for which one fits your runtime.";
+function agentShieldMiddleware(_request) {
+  throw new Error(LEGACY_MIGRATION_ERROR);
+}
+function createEnhancedAgentShieldMiddleware(_config = {}) {
+  throw new Error(LEGACY_MIGRATION_ERROR);
+}
+
+exports.agentShieldMiddleware = agentShieldMiddleware;
+exports.createEnhancedAgentShieldMiddleware = createEnhancedAgentShieldMiddleware;
+exports.withAgentShield = withAgentShield;
+exports.withCheckpointApi = withCheckpointApi;
+//# sourceMappingURL=api-middleware.js.map
+//# sourceMappingURL=api-middleware.js.map