@kya-os/agentshield-nextjs/dist/edge/index.d.mts

Next.js middleware for AgentShield AI agent detection

import { NextRequest, NextResponse } from 'next/server';
import { DetectionResult } from '@kya-os/agentshield-shared';
export { DetectionResult } from '@kya-os/agentshield-shared';

/**
 * Edge Runtime Middleware with WASM Support
 *
 * This module provides Next.js middleware that uses the unified WASM runtime.
 * For Edge Runtime, consumers must provide a pre-compiled WASM module via static import:
 *
 * ```typescript
 * // In your middleware.ts
 * import wasmModule from '@kya-os/agentshield-wasm-runtime/wasm?module';
 * import { createEdgeMiddleware } from '@kya-os/agentshield-nextjs/edge';
 *
 * export const middleware = createEdgeMiddleware({
 *   wasmModule,
 *   apiKey: process.env.AGENTSHIELD_API_KEY,
 *   onAgentDetected: 'block',
 * });
 * ```
 *
 * When an API key is provided, the middleware will:
 * 1. Load customer policies (deny lists, allow lists, thresholds) from AgentShield API
 * 2. Automatically block agents that match deny list entries
 * 3. Cache policies for 5 minutes with background refresh
 */

/**
 * Edge middleware configuration
 */
interface EdgeMiddlewareConfig {
    /**
     * Pre-compiled WebAssembly.Module for Edge Runtime
     * Use static import: `import wasmModule from '@kya-os/agentshield-wasm-runtime/wasm?module'`
     */
    wasmModule?: WebAssembly.Module;
    /**
     * API key for loading customer policies from AgentShield dashboard
     * When provided, enables policy enforcement (deny lists, allow lists, thresholds)
     */
    apiKey?: string;
    /**
     * Custom URL for the policy API
     * @default 'https://api.agentshield.io'
     */
    policyApiUrl?: string;
    /**
     * Action to take when an agent is detected
     * @default 'log'
     */
    onAgentDetected?: 'block' | 'redirect' | 'rewrite' | 'log' | 'allow';
    /**
     * Custom handler called when an agent is detected
     * Return a NextResponse to override default behavior
     */
    onDetection?: (request: NextRequest, result: DetectionResult) => Promise<NextResponse | void> | NextResponse | void;
    /**
     * Paths to skip detection (can be string prefixes or RegExp)
     */
    skipPaths?: (string | RegExp)[];
    /**
     * Minimum confidence threshold (0-100 scale) for considering a request as agent traffic
     * @default 70
     */
    confidenceThreshold?: number;
    /**
     * Response to send when blocking agents
     */
    blockedResponse?: {
        status?: number;
        message?: string;
        headers?: Record<string, string>;
    };
    /**
     * URL to redirect to when redirecting agents
     */
    redirectUrl?: string;
    /**
     * URL to rewrite to when rewriting agent requests
     */
    rewriteUrl?: string;
    /**
     * Enable debug logging
     */
    debug?: boolean;
}
/**
 * Create Edge middleware with WASM support
 *
 * @example
 * ```typescript
 * // middleware.ts
 * import wasmModule from '@kya-os/agentshield-wasm-runtime/wasm?module';
 * import { createEdgeMiddleware } from '@kya-os/agentshield-nextjs/edge';
 *
 * export const middleware = createEdgeMiddleware({
 *   wasmModule,
 *   onAgentDetected: 'block',
 *   confidenceThreshold: 70,
 * });
 *
 * export const config = {
 *   matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
 * };
 * ```
 */
declare function createEdgeMiddleware(config?: EdgeMiddlewareConfig): (request: NextRequest) => Promise<NextResponse>;

export { type EdgeMiddlewareConfig, createEdgeMiddleware };