@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

$3

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).*)'],
};
`

$3

`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 (


`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 (


`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 (


`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

`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 });
}
},
});
``

License

MIT OR Apache-2.0