@kya-os/checkpoint-nextjs 1.2.0 → 1.7.0

package/dist/wasm-middleware.d.ts

@@ -1,98 +0,0 @@
-import { NextRequest, NextResponse } from 'next/server';
-
-/**
- * WASM-enabled middleware for Next.js with Checkpoint.
- *
- * **Deprecation notice (AgentDetector-Deletion-1):**
- * `createWasmAgentShieldMiddleware` is deprecated as of this patch and
- * slated for removal in the next minor. It internally constructs a
- * legacy `AgentDetector` and never actually uses the WASM instance for
- * detection (the `wasmInstance` arg only bumps confidence by 15%).
- * Stage 1 detection now lives in the Rust `kya-os-engine` (PDM-1
- * #2560). Migrate to `withCheckpoint` from `@kya-os/checkpoint-nextjs`
- * — engine-backed, runs the orchestrator including envelope
- * verification.
- */
-
-/** @internal — test-only reset for the one-shot warn latch. */
-declare function __resetCreateWasmAgentShieldWarningForTests(): void;
-interface WasmDetectionResult {
-    isAgent: boolean;
-    isAiCrawler?: boolean;
-    confidence: number;
-    agent?: string | undefined;
-    verificationMethod: 'signature' | 'pattern' | 'none';
-    riskLevel: 'low' | 'medium' | 'high';
-    timestamp: string;
-}
-interface AgentShieldConfig {
-    onAgentDetected?: (result: WasmDetectionResult) => void | Promise<void>;
-    blockOnHighConfidence?: boolean;
-    confidenceThreshold?: number;
-    skipPaths?: string[];
-    blockedResponse?: {
-        status?: number;
-        message?: string;
-        headers?: Record<string, string>;
-    };
-}
-/**
- * @deprecated Wraps the legacy `AgentDetector` class. Will be removed
- * in the next minor (AgentDetector-Deletion-2). Migrate to
- * `withCheckpoint` from `@kya-os/checkpoint-nextjs` — engine-backed,
- * runs the orchestrator including envelope verification.
- *
- * Create a WASM-enabled Checkpoint middleware (**pattern-detection only**).
- *
- * **This factory runs UA/header pattern matching only.** It does NOT
- * verify MCP-I signed envelopes — no JWS verification, no DID
- * resolution, no orchestrator stages. Use it when your only enforcement
- * concern is "is this request from a known bot pattern."
- *
- * **For envelope verification, use {@link withCheckpoint} instead** —
- * exported from `@kya-os/checkpoint-nextjs` (Node runtime) or
- * `@kya-os/checkpoint-nextjs/edge` (Edge runtime). `withCheckpoint`
- * routes every request through the kya-os-engine via WASM and supports
- * both `_meta.proof.jws` body envelopes (default) and the legacy
- * `KYA-Delegation` header form (opt-in via `legacyEnvelopeFallback`).
- * See SDK-Envelope-Plumbing-1 (#2594) for the migration context.
- *
- * @example pattern-only (this factory)
- * ```typescript
- * import wasmModule from '@kya-os/checkpoint/wasm?module';
- * import { createCheckpointWasmMiddleware } from '@kya-os/checkpoint-nextjs';
- *
- * const wasmInstance = await WebAssembly.instantiate(wasmModule);
- * export const middleware = createCheckpointWasmMiddleware({
- *   wasmInstance,
- *   confidenceThreshold: 80,
- * });
- * ```
- *
- * @example envelope verification (use `withCheckpoint` instead)
- * ```typescript
- * import { withCheckpoint } from '@kya-os/checkpoint-nextjs';
- *
- * export default withCheckpoint({
- *   tenantHost: 'acme.checkpoint.example',
- *   legacyEnvelopeFallback: true, // accept `KYA-Delegation` header form
- *   // drainJsonBody defaults to true; spec-form `_meta.proof.jws` works out of the box
- * });
- * ```
- */
-declare function createWasmAgentShieldMiddleware(config: AgentShieldConfig & {
-    wasmInstance?: WebAssembly.Instance;
-}): (request: NextRequest) => Promise<NextResponse<unknown>>;
-/**
- * Helper to load and instantiate WASM module
- * This should be called at the top of your middleware.ts file
- *
- * @example
- * ```typescript
- * import wasmModule from '@kya-os/checkpoint/wasm?module';
- * const wasmInstance = await instantiateWasm(wasmModule);
- * ```
- */
-declare function instantiateWasm(wasmModule: WebAssembly.Module): Promise<WebAssembly.Instance>;
-
-export { type AgentShieldConfig, type WasmDetectionResult, __resetCreateWasmAgentShieldWarningForTests, createWasmAgentShieldMiddleware, instantiateWasm };

package/dist/wasm-middleware.js

@@ -1,125 +0,0 @@
-'use strict';
-
-var server = require('next/server');
-var checkpoint = require('@kya-os/checkpoint');
-
-// src/wasm-middleware.ts
-
-// src/local-detection-gate.ts
-function isDetectedAgentForLocalGate(result) {
-  return result.isAgent === true;
-}
-function evaluateLocalDetectionGate(result, config) {
-  if (!isDetectedAgentForLocalGate(result)) {
-    return { action: "allow", shouldNotify: false };
-  }
-  if ((result.confidence ?? 0) >= config.confidenceThreshold) {
-    return { action: config.defaultAction, shouldNotify: true };
-  }
-  return { action: "allow", shouldNotify: false };
-}
-
-// src/wasm-middleware.ts
-var _createWasmAgentShieldWarned = false;
-function warnCreateWasmAgentShieldDeprecated() {
-  if (_createWasmAgentShieldWarned) return;
-  _createWasmAgentShieldWarned = true;
-  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") return;
-  console.warn(
-    "[Checkpoint] createWasmAgentShieldMiddleware is deprecated and will be removed in the next minor. It wraps the legacy AgentDetector class; Stage 1 detection now lives in the Rust kya-os-engine (PDM-1). Migrate to `withCheckpoint` from @kya-os/checkpoint-nextjs \u2014 engine-backed and runs envelope verification. See packages/checkpoint-nextjs/CHANGELOG.md for the recipe."
-  );
-}
-function __resetCreateWasmAgentShieldWarningForTests() {
-  _createWasmAgentShieldWarned = false;
-}
-function createWasmAgentShieldMiddleware(config) {
-  warnCreateWasmAgentShieldDeprecated();
-  const {
-    onAgentDetected,
-    blockOnHighConfidence = false,
-    confidenceThreshold = 80,
-    // Updated to 0-100 scale (was 0.8)
-    skipPaths = [],
-    blockedResponse = {
-      status: 403,
-      message: "Access denied: AI agent detected",
-      headers: { "Content-Type": "application/json" }
-    },
-    wasmInstance
-  } = config;
-  return async function middleware(request) {
-    const path = request.nextUrl.pathname;
-    if (skipPaths.some((skip) => path.startsWith(skip))) {
-      return server.NextResponse.next();
-    }
-    try {
-      const detector = new checkpoint.AgentDetector();
-      const hasWasm = !!wasmInstance;
-      const metadata = {
-        userAgent: request.headers.get("user-agent") || void 0,
-        ipAddress: request.headers.get("x-forwarded-for") || request.headers.get("x-real-ip") || void 0,
-        headers: Object.fromEntries(request.headers.entries()),
-        timestamp: /* @__PURE__ */ new Date()
-      };
-      const result = await detector.analyze(metadata);
-      const enhancedResult = {
-        isAgent: result.isAgent,
-        isAiCrawler: result.isAiCrawler,
-        confidence: hasWasm && result.confidence > 85 ? Math.min(result.confidence * 1.15, 100) : result.confidence,
-        agent: result.detectedAgent?.name || void 0,
-        verificationMethod: hasWasm && result.confidence > 85 ? "signature" : "pattern",
-        // Updated to 0-100 scale
-        riskLevel: result.confidence > 90 ? "high" : result.confidence > 70 ? "medium" : "low",
-        // Updated to 0-100 scale (was 0.7)
-        timestamp: result.timestamp instanceof Date ? result.timestamp.toISOString() : new Date(result.timestamp).toISOString()
-      };
-      const decision = evaluateLocalDetectionGate(enhancedResult, {
-        confidenceThreshold,
-        defaultAction: blockOnHighConfidence ? "block" : "allow"
-      });
-      if (onAgentDetected && isDetectedAgentForLocalGate(enhancedResult)) {
-        await onAgentDetected(enhancedResult);
-      }
-      if (decision.action === "block") {
-        return server.NextResponse.json(
-          {
-            error: blockedResponse.message,
-            agent: enhancedResult.agent,
-            confidence: Math.round(enhancedResult.confidence)
-          },
-          {
-            status: blockedResponse.status || 403,
-            headers: blockedResponse.headers || {}
-          }
-        );
-      }
-      const response = server.NextResponse.next();
-      if (enhancedResult.isAgent) {
-        response.headers.set("X-Agent-Detected", enhancedResult.agent || "unknown");
-        response.headers.set(
-          "X-Agent-Confidence",
-          String(Math.round(enhancedResult.confidence * 100))
-        );
-        response.headers.set("X-Agent-Verification", enhancedResult.verificationMethod);
-      }
-      return response;
-    } catch (error) {
-      console.error("AgentShield middleware error:", error);
-      return server.NextResponse.next();
-    }
-  };
-}
-async function instantiateWasm(wasmModule) {
-  try {
-    const instance = await WebAssembly.instantiate(wasmModule);
-    console.log("\u2705 AgentShield: WASM module loaded for cryptographic verification");
-    return instance;
-  } catch (error) {
-    console.warn("\u26A0\uFE0F AgentShield: Failed to instantiate WASM module", error);
-    throw error;
-  }
-}
-
-exports.__resetCreateWasmAgentShieldWarningForTests = __resetCreateWasmAgentShieldWarningForTests;
-exports.createWasmAgentShieldMiddleware = createWasmAgentShieldMiddleware;
-exports.instantiateWasm = instantiateWasm;

package/dist/wasm-middleware.mjs

@@ -1,121 +0,0 @@
-import { NextResponse } from 'next/server';
-import { AgentDetector } from '@kya-os/checkpoint';
-
-// src/wasm-middleware.ts
-
-// src/local-detection-gate.ts
-function isDetectedAgentForLocalGate(result) {
-  return result.isAgent === true;
-}
-function evaluateLocalDetectionGate(result, config) {
-  if (!isDetectedAgentForLocalGate(result)) {
-    return { action: "allow", shouldNotify: false };
-  }
-  if ((result.confidence ?? 0) >= config.confidenceThreshold) {
-    return { action: config.defaultAction, shouldNotify: true };
-  }
-  return { action: "allow", shouldNotify: false };
-}
-
-// src/wasm-middleware.ts
-var _createWasmAgentShieldWarned = false;
-function warnCreateWasmAgentShieldDeprecated() {
-  if (_createWasmAgentShieldWarned) return;
-  _createWasmAgentShieldWarned = true;
-  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") return;
-  console.warn(
-    "[Checkpoint] createWasmAgentShieldMiddleware is deprecated and will be removed in the next minor. It wraps the legacy AgentDetector class; Stage 1 detection now lives in the Rust kya-os-engine (PDM-1). Migrate to `withCheckpoint` from @kya-os/checkpoint-nextjs \u2014 engine-backed and runs envelope verification. See packages/checkpoint-nextjs/CHANGELOG.md for the recipe."
-  );
-}
-function __resetCreateWasmAgentShieldWarningForTests() {
-  _createWasmAgentShieldWarned = false;
-}
-function createWasmAgentShieldMiddleware(config) {
-  warnCreateWasmAgentShieldDeprecated();
-  const {
-    onAgentDetected,
-    blockOnHighConfidence = false,
-    confidenceThreshold = 80,
-    // Updated to 0-100 scale (was 0.8)
-    skipPaths = [],
-    blockedResponse = {
-      status: 403,
-      message: "Access denied: AI agent detected",
-      headers: { "Content-Type": "application/json" }
-    },
-    wasmInstance
-  } = config;
-  return async function middleware(request) {
-    const path = request.nextUrl.pathname;
-    if (skipPaths.some((skip) => path.startsWith(skip))) {
-      return NextResponse.next();
-    }
-    try {
-      const detector = new AgentDetector();
-      const hasWasm = !!wasmInstance;
-      const metadata = {
-        userAgent: request.headers.get("user-agent") || void 0,
-        ipAddress: request.headers.get("x-forwarded-for") || request.headers.get("x-real-ip") || void 0,
-        headers: Object.fromEntries(request.headers.entries()),
-        timestamp: /* @__PURE__ */ new Date()
-      };
-      const result = await detector.analyze(metadata);
-      const enhancedResult = {
-        isAgent: result.isAgent,
-        isAiCrawler: result.isAiCrawler,
-        confidence: hasWasm && result.confidence > 85 ? Math.min(result.confidence * 1.15, 100) : result.confidence,
-        agent: result.detectedAgent?.name || void 0,
-        verificationMethod: hasWasm && result.confidence > 85 ? "signature" : "pattern",
-        // Updated to 0-100 scale
-        riskLevel: result.confidence > 90 ? "high" : result.confidence > 70 ? "medium" : "low",
-        // Updated to 0-100 scale (was 0.7)
-        timestamp: result.timestamp instanceof Date ? result.timestamp.toISOString() : new Date(result.timestamp).toISOString()
-      };
-      const decision = evaluateLocalDetectionGate(enhancedResult, {
-        confidenceThreshold,
-        defaultAction: blockOnHighConfidence ? "block" : "allow"
-      });
-      if (onAgentDetected && isDetectedAgentForLocalGate(enhancedResult)) {
-        await onAgentDetected(enhancedResult);
-      }
-      if (decision.action === "block") {
-        return NextResponse.json(
-          {
-            error: blockedResponse.message,
-            agent: enhancedResult.agent,
-            confidence: Math.round(enhancedResult.confidence)
-          },
-          {
-            status: blockedResponse.status || 403,
-            headers: blockedResponse.headers || {}
-          }
-        );
-      }
-      const response = NextResponse.next();
-      if (enhancedResult.isAgent) {
-        response.headers.set("X-Agent-Detected", enhancedResult.agent || "unknown");
-        response.headers.set(
-          "X-Agent-Confidence",
-          String(Math.round(enhancedResult.confidence * 100))
-        );
-        response.headers.set("X-Agent-Verification", enhancedResult.verificationMethod);
-      }
-      return response;
-    } catch (error) {
-      console.error("AgentShield middleware error:", error);
-      return NextResponse.next();
-    }
-  };
-}
-async function instantiateWasm(wasmModule) {
-  try {
-    const instance = await WebAssembly.instantiate(wasmModule);
-    console.log("\u2705 AgentShield: WASM module loaded for cryptographic verification");
-    return instance;
-  } catch (error) {
-    console.warn("\u26A0\uFE0F AgentShield: Failed to instantiate WASM module", error);
-    throw error;
-  }
-}
-
-export { __resetCreateWasmAgentShieldWarningForTests, createWasmAgentShieldMiddleware, instantiateWasm };

package/templates/middleware-wasm-100.ts

@@ -1,161 +0,0 @@
-/**
- * Checkpoint Middleware Template — Legacy WASM Factory
- *
- * ⚠️ **DEPRECATED TEMPLATE (AgentDetector-Deletion-1):** this template
- * uses `createWasmAgentShieldMiddleware`, which is deprecated and
- * will be removed in the next minor. For new projects, use
- * `withCheckpoint` instead — it's engine-backed (PDM-1 #2560), runs
- * MCP-I envelope verification, and is the canonical Phase-D
- * replacement. See the `withCheckpoint` recipe in
- * `packages/checkpoint-nextjs/README.md`.
- *
- * This template stays in-tree for one release as a migration reference;
- * the deprecated factory still works (with a dev-only console.warn).
- *
- * Installation:
- * 1. Copy this file to your project root as `middleware.ts`
- * 2. Install packages: npm install @kya-os/checkpoint @kya-os/checkpoint-nextjs
- * 3. Deploy to Vercel for Edge Runtime support
- */
-
-import { NextResponse } from 'next/server';
-import type { NextRequest } from 'next/server';
-
-// CRITICAL: Import WASM module with ?module suffix for Edge Runtime
-// This MUST be at the top of the file, before any other AgentShield imports
-import wasmModule from '@kya-os/checkpoint/wasm?module';
-
-// Now import the middleware creator
-import {
-  createWasmAgentShieldMiddleware,
-  instantiateWasm,
-} from '@kya-os/checkpoint-nextjs/wasm-middleware';
-
-// Initialize WASM module once at startup
-let wasmInstancePromise: Promise<WebAssembly.Instance> | null = null;
-
-async function getWasmInstance() {
-  if (!wasmInstancePromise) {
-    wasmInstancePromise = instantiateWasm(wasmModule);
-  }
-  return wasmInstancePromise;
-}
-
-export async function middleware(request: NextRequest) {
-  try {
-    // Get or create WASM instance
-    const wasmInstance = await getWasmInstance();
-
-    // Create middleware with WASM support
-    const agentShieldMiddleware = createWasmAgentShieldMiddleware({
-      wasmInstance,
-
-      // Skip authentication and static assets
-      skipPaths: ['/api/auth', '/_next', '/favicon.ico', '/public'],
-
-      // What to do when agent is detected
-      onAgentDetected: async (result) => {
-        // With WASM: 95-100% confidence for cryptographically verified agents
-        console.log(`🤖 AI Agent detected:`, {
-          agent: result.agent,
-          confidence: `${Math.round(result.confidence * 100)}%`,
-          verification: result.verificationMethod, // 'signature' with WASM, 'pattern' without
-          risk: result.riskLevel,
-          timestamp: result.timestamp,
-        });
-
-        // You can add custom logic here:
-        // - Log to analytics
-        // - Send alerts
-        // - Apply rate limiting
-        // - etc.
-      },
-
-      // Set to true to block AI agents
-      blockOnHighConfidence: false, // Change to true to block agents
-
-      // Minimum confidence to trigger blocking (0.8 = 80%)
-      confidenceThreshold: 0.8,
-
-      // Custom response when blocking
-      blockedResponse: {
-        status: 403,
-        message: 'AI agent access restricted',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-Blocked-Reason': 'ai-agent-detected',
-        },
-      },
-    });
-
-    // Run AgentShield detection
-    const response = await agentShieldMiddleware(request);
-
-    // Add security headers to all responses
-    response.headers.set('X-Frame-Options', 'DENY');
-    response.headers.set('X-Content-Type-Options', 'nosniff');
-    response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
-
-    return response;
-  } catch (error) {
-    // If WASM fails to load, fall back to pattern detection (85% confidence)
-    console.warn('⚠️ WASM initialization failed, using pattern detection:', error);
-
-    // You could use the regular middleware here as fallback
-    // For now, just continue
-    return NextResponse.next();
-  }
-}
-
-// Configure which paths the middleware runs on
-export const config = {
-  matcher: [
-    /*
-     * Match all request paths except for the ones starting with:
-     * - _next/static (static files)
-     * - _next/image (image optimization files)
-     * - favicon.ico (favicon file)
-     * - public folder
-     */
-    {
-      source: '/((?!_next/static|_next/image|favicon.ico|public).*)',
-      missing: [
-        { type: 'header', key: 'next-router-prefetch' },
-        { type: 'header', key: 'purpose', value: 'prefetch' },
-      ],
-    },
-  ],
-};
-
-/**
- * TypeScript Support
- *
- * Add this to a `types/wasm.d.ts` file in your project:
- *
- * declare module '@kya-os/checkpoint/wasm?module' {
- *   const value: WebAssembly.Module;
- *   export default value;
- * }
- */
-
-/**
- * What You'll See in Logs:
- *
- * With WASM (95-100% confidence):
- * 🤖 AI Agent detected: {
- *   agent: 'ChatGPT-User',
- *   confidence: '100%',
- *   verification: 'signature',  // Cryptographically verified!
- *   risk: 'high',
- *   timestamp: '2024-01-01T00:00:00.000Z'
- * }
- *
- * Without WASM (85% confidence):
- * 🤖 AI Agent detected: {
- *   agent: 'ChatGPT-User',
- *   confidence: '85%',
- *   verification: 'pattern',    // Pattern matching only
- *   risk: 'medium',
- *   timestamp: '2024-01-01T00:00:00.000Z'
- * }
- */