@kya-os/agentshield-nextjs 0.1.7

package/README.md

@@ -0,0 +1,392 @@
+# @kya-os/agentshield-nextjs
+
+Next.js middleware and React hooks for AgentShield AI agent detection and protection.
+
+## Features
+
+- 🚀 **Next.js Middleware**: Edge-compatible middleware for all routes
+- ⚛️ **React Hooks**: Client-side detection and monitoring
+- 🎯 **Flexible Actions**: Block, redirect, rewrite, or log detected agents
+- 🛡️ **Edge Runtime**: Optimized for Vercel Edge Functions
+- 📊 **Built-in Analytics**: Track detection patterns and statistics
+
+## Installation
+
+```bash
+npm install @kya-os/agentshield-nextjs
+```
+
+## Quick Start
+
+### Middleware Setup
+
+Create `middleware.js` (or `middleware.ts`) in your project root:
+
+```javascript
+import { agentShield } from '@kya-os/agentshield-nextjs';
+
+export default agentShield({
+  onAgentDetected: 'block',
+  confidenceThreshold: 0.8,
+});
+
+export const config = {
+  matcher: [
+    '/((?!api|_next/static|_next/image|favicon.ico).*)',
+  ],
+};
+```
+
+### React Hooks
+
+```javascript
+'use client';
+
+import { useAgentDetection } from '@kya-os/agentshield-nextjs';
+
+export default function SecurityMonitor() {
+  const { detect, isDetecting, lastResult } = useAgentDetection({
+    confidenceThreshold: 0.7,
+  });
+
+  const handleCheck = async () => {
+    const result = await detect();
+    if (result.isAgent) {
+      alert('Agent detected!');
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleCheck} disabled={isDetecting}>
+        {isDetecting ? 'Checking...' : 'Check for Agents'}
+      </button>
+      
+      {lastResult && (
+        <div>
+          <p>Is Agent: {lastResult.isAgent ? 'Yes' : 'No'}</p>
+          <p>Confidence: {(lastResult.confidence * 100).toFixed(1)}%</p>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Middleware Configuration
+
+```javascript
+import { agentShield } from '@kya-os/agentshield-nextjs';
+
+export default agentShield({
+  // Core detection options
+  confidenceThreshold: 0.7,
+  enablePatternMatching: true,
+  enableBehaviorAnalysis: true,
+  
+  // Action when agent is detected
+  onAgentDetected: 'block', // 'block' | 'redirect' | 'rewrite' | 'allow' | 'log'
+  
+  // Skip detection for paths
+  skipPaths: ['/api/webhooks', /^\/admin/],
+  
+  // Custom responses
+  blockedResponse: {
+    status: 403,
+    message: 'Access denied',
+  },
+  redirectUrl: '/blocked',
+  rewriteUrl: '/blocked',
+  
+  // Custom handler
+  onDetection: async (request, result) => {
+    console.log('Agent detected:', result);
+    // Return custom NextResponse or void
+  },
+});
+```
+
+## Actions
+
+### Block Agents
+
+```javascript
+export default agentShield({
+  onAgentDetected: 'block',
+  blockedResponse: {
+    status: 403,
+    message: 'Automated access not allowed',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Robots-Tag': 'noindex',
+    },
+  },
+});
+```
+
+### Redirect Agents
+
+```javascript
+export default agentShield({
+  onAgentDetected: 'redirect',
+  redirectUrl: '/blocked',
+  confidenceThreshold: 0.8,
+});
+```
+
+### Rewrite Requests
+
+```javascript
+export default agentShield({
+  onAgentDetected: 'rewrite',
+  rewriteUrl: '/bot-content',
+  confidenceThreshold: 0.6,
+});
+```
+
+### Custom Logic
+
+```javascript
+export default agentShield({
+  onDetection: async (request, result) => {
+    if (result.confidence > 0.9) {
+      // High confidence - block
+      return NextResponse.json(
+        { error: 'Blocked' },
+        { status: 403 }
+      );
+    } else if (result.confidence > 0.5) {
+      // Medium confidence - redirect to captcha
+      return NextResponse.redirect(
+        new URL('/verify', request.url)
+      );
+    }
+    // Low confidence - continue
+  },
+});
+```
+
+## React Hooks
+
+### useAgentDetection
+
+Client-side agent detection:
+
+```javascript
+import { useAgentDetection } from '@kya-os/agentshield-nextjs';
+
+function SecurityComponent() {
+  const { detect, isDetecting, lastResult, detector } = useAgentDetection({
+    confidenceThreshold: 0.7,
+  });
+
+  useEffect(() => {
+    // Auto-detect on component mount
+    detect();
+  }, [detect]);
+
+  return (
+    <div>
+      {lastResult?.isAgent && (
+        <div className="alert">
+          Agent detected with {lastResult.confidence} confidence
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### useDetectionMonitor
+
+Monitor and track detection events:
+
+```javascript
+import { useDetectionMonitor } from '@kya-os/agentshield-nextjs';
+
+function AnalyticsDashboard() {
+  const { detectionHistory, getStats, clearHistory } = useDetectionMonitor(
+    (context) => {
+      // Handle each detection
+      console.log('Detection event:', context);
+    }
+  );
+
+  const stats = getStats();
+
+  return (
+    <div>
+      <h2>Detection Statistics</h2>
+      <p>Total Requests: {stats.total}</p>
+      <p>Agents Detected: {stats.detected}</p>
+      <p>Detection Rate: {(stats.detectionRate * 100).toFixed(1)}%</p>
+      <p>Average Confidence: {(stats.avgConfidence * 100).toFixed(1)}%</p>
+      
+      <button onClick={clearHistory}>Clear History</button>
+    </div>
+  );
+}
+```
+
+## API Routes Integration
+
+Protect API routes with server-side detection:
+
+```javascript
+// pages/api/protected.js or app/api/protected/route.js
+import { AgentDetector } from '@kya-os/agentshield';
+
+const detector = new AgentDetector();
+
+export async function GET(request) {
+  const context = {
+    userAgent: request.headers.get('user-agent'),
+    ip: request.ip,
+    headers: Object.fromEntries(request.headers.entries()),
+  };
+
+  const result = await detector.analyze(context);
+
+  if (result.isAgent && result.confidence > 0.7) {
+    return NextResponse.json(
+      { error: 'Automated access detected' },
+      { status: 403 }
+    );
+  }
+
+  return NextResponse.json({ data: 'Protected content' });
+}
+```
+
+## Advanced Usage
+
+### Path-Specific Configuration
+
+```javascript
+import { NextRequest, NextResponse } from 'next/server';
+import { AgentDetector } from '@kya-os/agentshield';
+
+const detector = new AgentDetector();
+
+export async function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Different thresholds for different paths
+  let threshold = 0.7;
+  if (pathname.startsWith('/api/')) {
+    threshold = 0.5; // More sensitive for API
+  } else if (pathname.startsWith('/admin/')) {
+    threshold = 0.9; // Less sensitive for admin (humans expected)
+  }
+
+  const context = {
+    userAgent: request.headers.get('user-agent') ?? undefined,
+    ip: request.ip,
+    headers: Object.fromEntries(request.headers.entries()),
+    url: request.url,
+  };
+
+  const result = await detector.analyze(context);
+
+  if (result.isAgent && result.confidence >= threshold) {
+    return NextResponse.json(
+      { error: 'Access denied' },
+      { status: 403 }
+    );
+  }
+
+  return NextResponse.next();
+}
+```
+
+### Server Components
+
+Use detection results in Server Components:
+
+```javascript
+// app/dashboard/page.tsx
+import { headers } from 'next/headers';
+import { AgentDetector } from '@kya-os/agentshield';
+
+export default async function Dashboard() {
+  const headersList = headers();
+  const detector = new AgentDetector();
+
+  const result = await detector.analyze({
+    userAgent: headersList.get('user-agent') ?? undefined,
+    headers: Object.fromEntries(headersList.entries()),
+  });
+
+  if (result.isAgent) {
+    return <div>Automated access detected</div>;
+  }
+
+  return <div>Welcome to the dashboard!</div>;
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with proper types:
+
+```typescript
+import { NextRequest } from 'next/server';
+import { agentShield, NextJSMiddlewareConfig } from '@kya-os/agentshield-nextjs';
+
+const config: NextJSMiddlewareConfig = {
+  onAgentDetected: 'block',
+  confidenceThreshold: 0.8,
+  onDetection: async (request: NextRequest, result) => {
+    // Fully typed parameters
+    console.log(result.confidence);
+  },
+};
+
+export default agentShield(config);
+```
+
+## Examples
+
+### E-commerce Protection
+
+```javascript
+// Protect product pages from scrapers
+export default agentShield({
+  onAgentDetected: 'redirect',
+  redirectUrl: '/captcha',
+  confidenceThreshold: 0.6,
+  skipPaths: ['/api/webhooks', '/health'],
+});
+
+export const config = {
+  matcher: ['/products/:path*', '/search/:path*'],
+};
+```
+
+### Content Publishing
+
+```javascript
+// Allow search engines, block other bots
+export default agentShield({
+  onDetection: async (request, result) => {
+    const userAgent = request.headers.get('user-agent') || '';
+    
+    // Allow known search engines
+    if (/googlebot|bingbot|slurp/i.test(userAgent)) {
+      return; // Continue
+    }
+    
+    // Block other agents
+    if (result.isAgent && result.confidence > 0.5) {
+      return NextResponse.json(
+        { error: 'Bot access restricted' },
+        { status: 403 }
+      );
+    }
+  },
+});
+```
+
+## License
+
+MIT OR Apache-2.0

package/dist/index.d.mts

@@ -0,0 +1,87 @@
+import { D as DetectionContext } from './middleware-OvcbG6s2.mjs';
+export { N as NextJSMiddlewareConfig, a as agentShield, c as createAgentShieldMiddleware } from './middleware-OvcbG6s2.mjs';
+import { AgentShieldConfig, AgentDetector, DetectionResult } from '@kya-os/agentshield';
+import 'next/server';
+
+/**
+ * React hooks for AgentShield in Next.js applications
+ */
+
+/**
+ * Hook for client-side agent detection
+ */
+declare function useAgentDetection(config?: Partial<AgentShieldConfig>): {
+    detect: () => Promise<{
+        isAgent: boolean;
+        confidence: number;
+        reasons: string[];
+        timestamp: Date;
+        confidenceLevel?: "low" | "medium" | "high" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        detectedAgent?: {
+            type: string;
+            name: string;
+        } | undefined;
+        verificationMethod?: string | undefined;
+        riskLevel?: string | undefined;
+        forgeabilityRisk?: "low" | "medium" | "high" | undefined;
+    }>;
+    isDetecting: boolean;
+    lastResult: {
+        isAgent: boolean;
+        confidence: number;
+        reasons: string[];
+        timestamp: Date;
+        confidenceLevel?: "low" | "medium" | "high" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        detectedAgent?: {
+            type: string;
+            name: string;
+        } | undefined;
+        verificationMethod?: string | undefined;
+        riskLevel?: string | undefined;
+        forgeabilityRisk?: "low" | "medium" | "high" | undefined;
+    } | null;
+    detector: AgentDetector;
+};
+/**
+ * Hook for monitoring detection results
+ */
+declare function useDetectionMonitor(onDetection?: (context: DetectionContext) => void): {
+    detectionHistory: {
+        isAgent: boolean;
+        confidence: number;
+        reasons: string[];
+        timestamp: Date;
+        confidenceLevel?: "low" | "medium" | "high" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        detectedAgent?: {
+            type: string;
+            name: string;
+        } | undefined;
+        verificationMethod?: string | undefined;
+        riskLevel?: string | undefined;
+        forgeabilityRisk?: "low" | "medium" | "high" | undefined;
+    }[];
+    addDetection: (result: DetectionResult, request?: any) => void;
+    clearHistory: () => void;
+    getStats: () => {
+        total: number;
+        detected: number;
+        avgConfidence: number;
+        detectionRate: number;
+    };
+};
+
+/**
+ * @fileoverview AgentShield Next.js Integration
+ * @version 0.1.0
+ * @license MIT OR Apache-2.0
+ */
+
+/**
+ * Library version
+ */
+declare const VERSION = "0.1.0";
+
+export { DetectionContext, VERSION, useAgentDetection, useDetectionMonitor };

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+import { D as DetectionContext } from './middleware-OvcbG6s2.js';
+export { N as NextJSMiddlewareConfig, a as agentShield, c as createAgentShieldMiddleware } from './middleware-OvcbG6s2.js';
+import { AgentShieldConfig, AgentDetector, DetectionResult } from '@kya-os/agentshield';
+import 'next/server';
+
+/**
+ * React hooks for AgentShield in Next.js applications
+ */
+
+/**
+ * Hook for client-side agent detection
+ */
+declare function useAgentDetection(config?: Partial<AgentShieldConfig>): {
+    detect: () => Promise<{
+        isAgent: boolean;
+        confidence: number;
+        reasons: string[];
+        timestamp: Date;
+        confidenceLevel?: "low" | "medium" | "high" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        detectedAgent?: {
+            type: string;
+            name: string;
+        } | undefined;
+        verificationMethod?: string | undefined;
+        riskLevel?: string | undefined;
+        forgeabilityRisk?: "low" | "medium" | "high" | undefined;
+    }>;
+    isDetecting: boolean;
+    lastResult: {
+        isAgent: boolean;
+        confidence: number;
+        reasons: string[];
+        timestamp: Date;
+        confidenceLevel?: "low" | "medium" | "high" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        detectedAgent?: {
+            type: string;
+            name: string;
+        } | undefined;
+        verificationMethod?: string | undefined;
+        riskLevel?: string | undefined;
+        forgeabilityRisk?: "low" | "medium" | "high" | undefined;
+    } | null;
+    detector: AgentDetector;
+};
+/**
+ * Hook for monitoring detection results
+ */
+declare function useDetectionMonitor(onDetection?: (context: DetectionContext) => void): {
+    detectionHistory: {
+        isAgent: boolean;
+        confidence: number;
+        reasons: string[];
+        timestamp: Date;
+        confidenceLevel?: "low" | "medium" | "high" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        detectedAgent?: {
+            type: string;
+            name: string;
+        } | undefined;
+        verificationMethod?: string | undefined;
+        riskLevel?: string | undefined;
+        forgeabilityRisk?: "low" | "medium" | "high" | undefined;
+    }[];
+    addDetection: (result: DetectionResult, request?: any) => void;
+    clearHistory: () => void;
+    getStats: () => {
+        total: number;
+        detected: number;
+        avgConfidence: number;
+        detectionRate: number;
+    };
+};
+
+/**
+ * @fileoverview AgentShield Next.js Integration
+ * @version 0.1.0
+ * @license MIT OR Apache-2.0
+ */
+
+/**
+ * Library version
+ */
+declare const VERSION = "0.1.0";
+
+export { DetectionContext, VERSION, useAgentDetection, useDetectionMonitor };