Next.js middleware for AgentShield AI agent detection
npm install @kya-os/agentshield-nextjsNext.js middleware and React hooks for AgentShield AI agent detection and protection.
- 🚀 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
``bash`
npm install @kya-os/agentshield-nextjs
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,
// NEW: Session tracking (v0.1.27+)
sessionTracking: {
enabled: true, // Track continued sessions from AI agents
},
});
export const config = {
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};
`
`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 (
{lastResult && (
Is Agent: {lastResult.isAgent ? 'Yes' : 'No'}
Confidence: {(lastResult.confidence * 100).toFixed(1)}%
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
$3
`javascript
export default agentShield({
onAgentDetected: 'block',
blockedResponse: {
status: 403,
message: 'Automated access not allowed',
headers: {
'Content-Type': 'application/json',
'X-Robots-Tag': 'noindex',
},
},
});
`$3
`javascript
export default agentShield({
onAgentDetected: 'redirect',
redirectUrl: '/blocked',
confidenceThreshold: 0.8,
});
`$3
`javascript
export default agentShield({
onAgentDetected: 'rewrite',
rewriteUrl: '/bot-content',
confidenceThreshold: 0.6,
});
`$3
`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
$3
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 (
{lastResult?.isAgent && (
Agent detected with {lastResult.confidence} confidence
)}
);
}
`$3
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 (
Detection Statistics
Total Requests: {stats.total}
Agents Detected: {stats.detected}
Detection Rate: {(stats.detectionRate * 100).toFixed(1)}%
Average Confidence: {(stats.avgConfidence * 100).toFixed(1)}%
);
}
`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
$3
`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();
}
`$3
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
Automated access detected;
} return
Welcome to the dashboard!;
}
`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
$3
`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'],
};
`$3
`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 });
}
},
});
``MIT OR Apache-2.0