@kya-os/checkpoint-nextjs 1.0.0

package/README.md

@@ -0,0 +1,414 @@
+# @kya-os/checkpoint-nextjs
+
+Next.js middleware and React hooks for Checkpoint AI agent detection and enforcement.
+
+## 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
+
+## Two deployment shapes
+
+This package ships two complementary middleware factories. Pick the one that
+fits your runtime; both are first-class and supported.
+
+| Shape            | Factory             | Where verification runs                                         | Use when                                                                                                                                                                                                                                                                          |
+| ---------------- | ------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Local engine** | `withCheckpoint`    | In-process, via WASM (`kya-os-engine`)                          | You want the lowest possible latency, deterministic verdicts, no network round-trip per request, and your runtime can load the WASM artifact (Vercel Node, Vercel Edge with the bundled artifact, Cloudflare Workers with `nodejs_compat`). This is the canonical Phase D output. |
+| **SaaS gateway** | `withCheckpointApi` | Cloudflare DNS gateway (`https://detect.checkpoint-gateway.ai`) | You want centralized policy + dashboard rules without a redeploy, you're on a runtime where the WASM artifact won't load (bare-Edge, browser embedding), or you want a single HTTPS hop with cached verdicts. Trades ~30–50ms of edge latency for zero local engine state.        |
+
+Both factories return a Next.js middleware function — the request/response
+contract is identical. You can run both side-by-side in the same app on
+different routes if your policy demands it.
+
+```ts
+// middleware.ts — local engine
+import { withCheckpoint } from '@kya-os/checkpoint-nextjs';
+export default withCheckpoint({ tenantHost: 'demo.example' });
+
+// middleware.ts — SaaS gateway
+import { withCheckpointApi } from '@kya-os/checkpoint-nextjs';
+export default withCheckpointApi({
+  apiKey: process.env.CHECKPOINT_API_KEY!,
+  onBlock: 'redirect',
+  redirectUrl: '/blocked',
+});
+```
+
+> Pre-Phase-D the SaaS-gateway factory shipped as `withAgentShield`; the
+> name is preserved as a `@deprecated` alias for one release. Same for
+> `AgentShieldClient` / `AgentShieldClientConfig` → `CheckpointApiClient`
+> / `CheckpointApiClientConfig`. New code should import the
+> `Checkpoint*` names.
+
+## Installation
+
+```bash
+npm install @kya-os/checkpoint-nextjs
+```
+
+## Quick Start
+
+### Middleware Setup
+
+Create `middleware.js` (or `middleware.ts`) in your project root:
+
+```javascript
+import { agentShield } from '@kya-os/checkpoint-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).*)'],
+};
+```
+
+### React Hooks
+
+```javascript
+'use client';
+
+import { useAgentDetection } from '@kya-os/checkpoint-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/checkpoint-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/checkpoint-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/checkpoint-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/checkpoint';
+
+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/checkpoint';
+
+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/checkpoint';
+
+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/checkpoint-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