@kya-os/agentshield-nextjs 0.3.3 → 0.3.5

package/README.md

@@ -1,380 +1,32 @@
 # @kya-os/agentshield-nextjs
 
-Next.js middleware and React hooks for AgentShield AI agent detection and protection.
+> **DEPRECATED — renamed to `@kya-os/checkpoint-nextjs`.**
 
-## Features
+See the [agent-shield repo's Phase D rename context](https://github.com/Know-That-Ai/agent-shield/issues/2483).
 
-- 🚀 **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
+## Migration
 
-## 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,
-
-  // 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/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
-  },
-});
+```diff
+- "@kya-os/agentshield-nextjs": "^0.3.4"
++ "@kya-os/checkpoint-nextjs": "^1.0.0"
 ```
 
-## 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>
-  );
-}
+```diff
+- import { withCheckpoint } from '@kya-os/agentshield-nextjs';
++ import { withCheckpoint } from '@kya-os/checkpoint-nextjs';
 ```
 
-### 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 });
-    }
-  },
-});
-```
+The new `withCheckpoint` factory ships under the renamed package.
+Every verification decision flows through the Rust `kya-os-engine`
+via WASM; the legacy TS-pattern-matching path (the 600-line
+`edge-detector-wrapper.ts`) was removed in Phase D (architect Q10
+deletion ratification).
 
-## License
+**Dual-runtime out of the box.** `withCheckpoint` works under both
+Vercel Node-runtime AND Vercel Edge runtime. Pick the runtime via the
+standard Next.js `export const config = { runtime: 'edge' | 'nodejs' }`
+pattern.
 
-MIT OR Apache-2.0
+For the `withAgentShield` API-based detection helper (a different
+product entirely — remote API rather than local engine), the export
+moved over verbatim under the new package name.

package/index.js

@@ -0,0 +1,9 @@
+'use strict';
+throw new Error(
+  '@kya-os/agentshield-nextjs is renamed to @kya-os/checkpoint-nextjs. ' +
+    'Migrate: `npm install @kya-os/checkpoint-nextjs` and replace ' +
+    "`from '@kya-os/agentshield-nextjs'` with `from '@kya-os/checkpoint-nextjs'`. " +
+    'Use the new `withCheckpoint` factory in `middleware.ts`; the legacy ' +
+    '`createAgentShieldMiddleware` path was removed in Phase D. ' +
+    'See https://github.com/Know-That-Ai/agent-shield/issues/2483 for context.'
+);

package/package.json

@@ -1,149 +1,15 @@
 {
   "name": "@kya-os/agentshield-nextjs",
-  "version": "0.3.3",
-  "description": "Next.js middleware for AgentShield AI agent detection",
-  "keywords": [
-    "nextjs",
-    "middleware",
-    "ai",
-    "agent",
-    "detection",
-    "security",
-    "react"
-  ],
+  "version": "0.3.5",
+  "description": "DEPRECATED — renamed to @kya-os/checkpoint-nextjs. Migrate by swapping the import path.",
+  "deprecated": "Renamed to @kya-os/checkpoint-nextjs. Migrate: npm install @kya-os/checkpoint-nextjs && replace 'from @kya-os/agentshield-nextjs' with 'from @kya-os/checkpoint-nextjs'. See https://github.com/Know-That-Ai/agent-shield/issues/2483.",
   "license": "MIT OR Apache-2.0",
-  "author": "KnowThat.ai",
-  "homepage": "https://github.com/Know-That-Ai/agent-shield#readme",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Know-That-Ai/agent-shield.git",
-    "directory": "packages/agentshield-nextjs"
-  },
-  "bugs": {
-    "url": "https://github.com/Know-That-Ai/agent-shield/issues"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "agentshield-setup-edge": "./bin/setup-edge-wasm.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    },
-    "./edge": {
-      "types": "./dist/edge/index.d.ts",
-      "edge-runtime": "./dist/edge/index.mjs",
-      "import": "./dist/edge/index.mjs",
-      "require": "./dist/edge/index.js"
-    },
-    "./edge-runtime-loader": {
-      "types": "./dist/edge-runtime-loader.d.ts",
-      "import": "./dist/edge-runtime-loader.mjs",
-      "require": "./dist/edge-runtime-loader.js"
-    },
-    "./middleware": {
-      "types": "./dist/middleware.d.ts",
-      "import": "./dist/middleware.mjs",
-      "require": "./dist/middleware.js"
-    },
-    "./wasm-setup": {
-      "types": "./dist/wasm-setup.d.ts",
-      "import": "./dist/wasm-setup.mjs",
-      "require": "./dist/wasm-setup.js"
-    },
-    "./wasm-middleware": {
-      "types": "./dist/wasm-middleware.d.ts",
-      "import": "./dist/wasm-middleware.mjs",
-      "require": "./dist/wasm-middleware.js"
-    },
-    "./edge-wasm-middleware": {
-      "types": "./dist/edge-wasm-middleware.d.ts",
-      "import": "./dist/edge-wasm-middleware.mjs",
-      "require": "./dist/edge-wasm-middleware.js"
-    },
-    "./api-client": {
-      "types": "./dist/api-client.d.ts",
-      "import": "./dist/api-client.mjs",
-      "require": "./dist/api-client.js"
-    },
-    "./api-middleware": {
-      "types": "./dist/api-middleware.d.ts",
-      "import": "./dist/api-middleware.mjs",
-      "require": "./dist/api-middleware.js"
-    },
-    "./policy": {
-      "types": "./dist/policy.d.ts",
-      "import": "./dist/policy.mjs",
-      "require": "./dist/policy.js"
-    },
-    "./package.json": "./package.json"
-  },
+  "main": "./index.js",
   "files": [
-    "dist",
-    "bin",
-    "wasm",
-    "wasm.d.ts",
-    "templates",
-    "README.md",
-    "CHANGELOG.md",
-    "EDGE_RUNTIME_WASM_SETUP.md"
+    "index.js",
+    "README.md"
   ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "devDependencies": {
-    "@testing-library/react": "^14.2.1",
-    "@testing-library/react-hooks": "^8.0.1",
-    "@types/node": "^20.11.24",
-    "@types/react": "^18.2.61",
-    "@vitest/coverage-v8": "^1.3.1",
-    "jsdom": "^24.0.0",
-    "next": "^16.2.2",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "rimraf": "^5.0.5",
-    "tsup": "^8.0.2",
-    "typescript": "^5.4.2",
-    "vitest": "^1.3.1"
-  },
-  "peerDependencies": {
-    "next": ">=13.0.0",
-    "react": ">=18.0.0",
-    "@upstash/redis": ">=1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@upstash/redis": {
-      "optional": true
-    }
-  },
   "publishConfig": {
     "access": "public"
-  },
-  "sideEffects": false,
-  "dependencies": {
-    "@noble/ed25519": "^2.2.3",
-    "@noble/hashes": "^2.0.1",
-    "@kya-os/agentshield-shared": "0.3.1",
-    "@kya-os/agentshield-wasm-runtime": "0.1.6",
-    "@kya-os/agentshield": "0.1.42"
-  },
-  "scripts": {
-    "build": "tsup",
-    "build:watch": "tsup --watch",
-    "predev": "pnpm --filter=@kya-os/agentshield-shared build && pnpm --filter=@kya-os/agentshield build",
-    "dev": "tsup --watch",
-    "clean": "rimraf dist .tsbuildinfo",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint src --ext .ts,.tsx",
-    "lint:fix": "eslint src --ext .ts,.tsx --fix",
-    "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
-    "format:check": "prettier --check \"src/**/*.{ts,tsx,json,md}\""
   }
-}
+}