Next.js Integration

Overview

The Checkpoint Next.js integration provides AI agent detection and enforcement for Next.js applications. With edge runtime optimization and full App Router support, it delivers protection with minimal performance impact.

• Edge Runtime Compatible — Runs at the edge for ultra-low latency
• < 2ms overhead — Minimal impact on response times
• Enforce or Observe modes — Active enforcement or log-only dry runs
• Route Matching — Fine-grained control over protected paths
• Policy Engine — Local policy evaluation with configurable rules
• TypeScript — Full type definitions included

Prerequisites

• A Checkpoint project — get your Project ID and API key from Installations in the dashboard.
• A Next.js app (App Router or Pages Router).

Installation

npm install @kya-os/checkpoint-nextjs

Quick Setup

import { withCheckpointApi } from '@kya-os/checkpoint-nextjs/api-middleware';

export default withCheckpointApi({
  apiKey: process.env.CHECKPOINT_API_KEY,
});

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

# .env.local
CHECKPOINT_API_KEY=your_api_key_here

curl -sI https://your-site.example/ -A "GPTBot/1.0" | grep -i -e '^kya-' -e '^x-checkpoint'

import { withCheckpointApi } from '@kya-os/checkpoint-nextjs/api-middleware';

export default withCheckpointApi({
  apiKey: process.env.CHECKPOINT_API_KEY,
});

export const config = {
  matcher: '/:path*',
};

// pages/api/protected.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // Only requests your policy allows ever reach this point.
  res.status(200).json({ data: 'Protected data' });
}

Local Engine Middleware

The package ships two deployment shapes. withCheckpointApi (above) dispatches to the Checkpoint SaaS gateway over HTTPS. withCheckpoint runs the detection engine in-process (WASM) — lowest latency, deterministic verdicts, no per-request network hop:

// middleware.ts
import { withCheckpoint } from '@kya-os/checkpoint-nextjs';

export default withCheckpoint({
  tenantHost: 'your.tenant.example',
  apiKey: process.env.CHECKPOINT_API_KEY, // optional — enables dashboard reporting
  projectId: process.env.CHECKPOINT_PROJECT_ID, // optional — enforces your deployed Cedar policy
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
};

See Middleware Enforcement for the full config reference for both shapes.

Configuration

import { withCheckpointApi } from '@kya-os/checkpoint-nextjs/api-middleware';

export default withCheckpointApi({
  apiKey: process.env.CHECKPOINT_API_KEY, // or set the CHECKPOINT_API_KEY env var

  // Optional
  onBlock: 'block', // 'block' | 'redirect' | 'challenge' — default: dashboard policy
  redirectUrl: '/for-ai', // target when onBlock is 'redirect'
  useEdge: true, // edge detection (~30–50ms, catches non-JS clients) — default: true
  timeout: 5000, // request timeout in ms
});

See Middleware Enforcement for the complete option tables for withCheckpointApi and withCheckpoint.

Environment Variables

# .env.local
CHECKPOINT_API_KEY=your_api_key_here

Enforce vs Observe Mode

On the local-engine shape, start with withCheckpoint({ enforcementMode: 'observe', ... }) to understand your traffic, review the would-have-been decisions in the dashboard, then switch to enforce when ready. On the SaaS shape (withCheckpointApi), enforcement follows your dashboard policy — deploy the policy in observe mode instead.

Response Headers

The SaaS shape (withCheckpointApi) sets KYA-* headers (KYA-Detected, KYA-Confidence, KYA-Agent on allowed agent traffic; KYA-Action / KYA-Reason on enforcement). The local-engine shape (withCheckpoint) sets X-Checkpoint-* headers and a __checkpoint_verdict cookie, adding X-Checkpoint-Would-Have-Been in observe mode.

See Middleware Enforcement for the full header list shared with Express and .NET.

Client-Side Detection

This package is server-side middleware — it does not ship client-side detection hooks. (The legacy useAgentDetection hook was removed along with the AgentDetector class it wrapped.) For client-side detection — conditionally rendering content, tracking agent visits from the browser — use the JavaScript Beacon or the Marketing Pixel alongside the middleware.

Edge Runtime

Checkpoint middleware runs on the Next.js Edge Runtime. withCheckpointApi dispatches to the Checkpoint edge over HTTPS, and route handlers behind it need no detection code of their own — enforcement has already happened by the time they run:

// app/api/protected/route.ts
export const runtime = 'edge';

export async function GET() {
  // Only requests your policy allows ever reach this point.
  return new Response('Protected data');
}

Content Security Policy

If your site uses CSP headers and you're also using the Pixel, add the Checkpoint domain:

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: [
              "default-src 'self'",
              "script-src 'self' 'unsafe-inline' https://kya.vouched.id",
              "connect-src 'self' https://kya.vouched.id",
            ].join('; '),
          },
        ],
      },
    ];
  },
};

Troubleshooting

Middleware not running

• Ensure middleware.ts is in the project root (not inside app/ or src/)
• Check the matcher configuration
• Verify the file exports a default function

Detection not working

• Verify CHECKPOINT_API_KEY is set — without it, detections never reach the dashboard
• Check for API calls to kya.vouched.id (SaaS shape) in your server logs
• Enable debug: true for detailed logs

Performance issues

• Prefer withCheckpoint (in-process WASM engine) — no per-request network hop
• Keep useEdge: true on withCheckpointApi for the lower-latency edge path
• Scope the matcher so static assets and health checks bypass the middleware

Next Steps

• Middleware Enforcement — Complete middleware documentation with all features
• Policies — Configure enforcement rules
• Gateway — DNS-based enforcement (no code changes)
• Express Integration — Server-side middleware for Express
• Choose Your Integration — Compare all integration options