Middleware Enforcement

What is Middleware Enforcement?

Checkpoint Middleware adds AI agent detection and enforcement directly in your application code. It runs before your route handlers, classifying every request and applying the verdict from the Rust kya-os-engine (plus any composed Cedar policy you deploy).

Middleware is available for Next.js, Express, ASP.NET Core, and Java applications.

Prerequisites

• A Checkpoint project. Create one in the dashboard if you don't have one yet.
• Your project's API key (and, for the .NET and Java adapters, its Project ID). See Credentials for where to find both in the dashboard.
• tenantHost: the one required config field for the Next.js local-engine withCheckpoint and for Express: your dashboard hostname, used to look up the deployed policy. withCheckpointApi (Next.js SaaS gateway), .NET, and Java use apiKey/ProjectId instead of tenantHost. See Configuration Options below.

Installation

npm install @kya-os/checkpoint-nextjs

Basic Setup

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

export default withCheckpoint({
  // Vercel only. Self-hosted: use 'trusted-proxy' with trustedHops set to your proxy count minus one.
  clientIpPolicy: { platform: 'vercel' },
  tenantHost: 'your.tenant.example',
  apiKey: process.env.CHECKPOINT_API_KEY, // optional: enables dashboard reporting
});

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

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

export default withCheckpointApi({
  // Vercel only. Self-hosted: use 'trusted-proxy' with trustedHops set to your proxy count minus one.
  clientIpPolicy: { platform: 'vercel' },
  apiKey: process.env.CHECKPOINT_API_KEY,
});

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

Configuration Options

The Next.js local-engine (withCheckpoint) and Express middleware share the same CheckpointConfig shape (Next.js adds a couple of runtime-specific fields). The SaaS-gateway middleware (withCheckpointApi) uses a different config. See SaaS gateway config below.

Next.js withCheckpoint additionally accepts cedarWasmModule for the Edge runtime, and composedPolicyEnforcer for injecting a pre-built enforcer: both advanced-injection escapes rather than everyday configuration.

Detect-only (observe) mode

To run detection without blocking, set enforcementMode: 'observe'. Every request passes through; the engine still classifies each one and stamps X-Checkpoint-Would-Have-Been headers so you can see what enforcement would have done, and detections still report to the dashboard (when apiKey is set).

withCheckpoint({
  tenantHost: 'your.tenant.example',
  enforcementMode: 'observe', // classify + report, never block
  apiKey: process.env.CHECKPOINT_API_KEY,
});

SaaS gateway config (Next.js)

withCheckpointApi is a distinct middleware with its own configuration; it POSTs to the gateway rather than running the engine locally, so its knobs differ from CheckpointConfig:

Reading the Verdict

Plain withCheckpoint attaches nothing to req. Read the engine's verdict through the onResult(result, req) callback, which fires after every verification with the full VerifyResult:

withCheckpoint({
  tenantHost: 'your.tenant.example',
  onResult: (result, req) => {
    // result.decision.kind is the verdict: 'Permit' | 'Block' | 'Challenge' | 'Redirect' | 'Instruct'
    console.log(`[${req.method} ${req.url}] verdict=${result.decision.kind}`);
  },
});

Errors thrown inside onResult are swallowed so an observability failure can never break the verdict path.

Observability & Storage (optional)

The session-tracking and event-storage primitives from the retired "enhanced" middleware are now composable exports you wire into withCheckpoint yourself. There is no separate enhanced middleware tier. This section is Express-specific.

Storage adapters

@kya-os/checkpoint-express exports MemoryStorageAdapter, RedisStorageAdapter, and an async createStorageAdapter factory. Construct an adapter and record events from onResult:

import { withCheckpoint, createStorageAdapter } from '@kya-os/checkpoint-express';

// createStorageAdapter is async and returns a StorageAdapter.
const storage = await createStorageAdapter({
  type: 'redis',
  ttl: 86400,
  redis: {
    url: process.env.REDIS_URL!,
    token: process.env.REDIS_TOKEN!,
  },
});

app.use(
  withCheckpoint({
    tenantHost: 'your.tenant.example',
    onResult: async (result, req) => {
      await storage.storeEvent({
        eventId: crypto.randomUUID(),
        sessionId: req.headers['x-request-id']?.toString() ?? crypto.randomUUID(),
        timestamp: new Date().toISOString(),
        agentType: result.detectionDetail.detectionClass.type,
        agentName: result.detectionDetail.detectedAgent?.name ?? 'unknown',
        confidence: result.detectionDetail.confidence,
        path: req.path,
        method: req.method,
        userAgent: req.headers['user-agent'],
        detectionReasons: result.detectionDetail.reasons,
        verificationMethod: result.detectionDetail.verificationMethod,
      });
    },
  })
);

createStorageAdapter({ type: 'memory' }) (or no argument) returns an in-memory adapter (fine for development, but data is lost on restart and not shared across instances). Use Redis (Upstash) for production.

The StorageAdapter interface

Implement this interface to plug in your own backend ({ type: 'custom', custom: myAdapter }):

import type { StorageAdapter } from '@kya-os/checkpoint-express';

const myAdapter: StorageAdapter = {
  storeEvent: async (event) => {
    /* persist an AgentDetectionEvent */
  },
  storeSession: async (session) => {
    /* upsert an AgentSession */
  },
  getEvents: async (sessionId, limit) => {
    /* events for a session */ return [];
  },
  getSession: async (sessionId) => {
    /* one session or null */ return null;
  },
  getRecentEvents: async (limit) => {
    /* recent events */ return [];
  },
  getActiveSessions: async (limit) => {
    /* active sessions */ return [];
  },
  cleanup: async (before) => {
    /* optional: clear data older than `before` */
  },
};

Session tracking

The Express package also exports ExpressSessionTracker and withSessionTracking for cookie/header-based session continuity. withSessionTracking(middleware, { enabled: true }) wraps a middleware so a returning agent's session is attached to req.checkpoint on subsequent requests. Install and mount cookie-parser ahead of it; the tracker reads req.cookies, which is only populated once something parses the Cookie header:

import cookieParser from 'cookie-parser';
import { withCheckpoint, withSessionTracking } from '@kya-os/checkpoint-express';

app.use(cookieParser()); // required for cookie-based session continuity

const checkpoint = withCheckpoint({ tenantHost: 'your.tenant.example' });

app.use(withSessionTracking(checkpoint, { enabled: true }));

Without cookie-parser, the tracker still falls back to header-based continuity (a kya-session request header), so tracking degrades rather than breaks, but cookie continuity across requests needs it mounted.

req.checkpoint is a nested object, not a flat verdict:

req.checkpoint = {
  result: DetectionResult, // the detection/verdict payload
  skipped: boolean,
  session?: SessionData, // present only when a prior session was found on this request
};

Response Headers

The engine path (withCheckpoint, Express and Next.js) sets X-Checkpoint-* headers on the response and writes a __checkpoint_verdict cookie that is byte-identical across both runtimes (shared encodeVerdictCookie primitive). In observe mode it adds X-Checkpoint-Would-Have-Been so you can see the verdict enforcement would have applied.

The X-Checkpoint-Engine header carries the engine name. Exact header keys are produced by the engine's renderDecisionAsResponse; the SDK propagates them verbatim.

When you enable Express session tracking, ExpressSessionTracker additionally emits kya-session, kya-session-agent, and kya-session-id (and withSessionTracking sets kya-detected / kya-agent on a continued session).

Response shape (Express)

The middleware adapts the engine's Decision to one of four response shapes. Express and the Next.js local engine (withCheckpoint) share the same transport-agnostic adapter (renderDecisionAsResponse → RenderedResponse), so the shape is identical across both runtimes except for the HTML-block transport, where Next.js's Edge/Node runtime offers a rewrite primitive Express doesn't:

Nothing is attached to req / NextRequest on this path in either runtime: read the verdict from onResult (as shown above), or from the response's verdict cookie / X-Checkpoint-* headers.

Response shape (Next.js SaaS gateway)

withCheckpointApi attaches nothing to req either. Read the verdict from the response, from the onAgentDetected(request, decision) callback (fires only when decision.isAgent), or from the decision object passed into customBlockedResponse:

.NET Configuration

Configure the ASP.NET Core adapter through CheckpointOptions in AddCheckpoint(options => …). Selected options (see the .NET integration guide for the full list):

OnAgentDetected = DetectedAction.Block and EnableSessionTracking are real members of CheckpointOptions: verified against Checkpoint.Core. The .NET API deliberately keeps OnAgentDetected (an enum action) where the TS engine SDK uses composed policy + onResult; the two SDKs are configured differently by design.

Advanced Usage (Next.js)

API route protection (SaaS gateway)

withCheckpointApi(config) takes a config object and returns Next.js middleware. It is not a route-handler wrapper. To protect only your API routes, scope the middleware with the matcher config:

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

export default withCheckpointApi({
  // Vercel only. Self-hosted: use 'trusted-proxy' with trustedHops set to your proxy count minus one.
  clientIpPolicy: { platform: 'vercel' },
  apiKey: process.env.CHECKPOINT_API_KEY,
});

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

Alternatively, keep a site-wide matcher and set includePaths: ['/api/*'] in the middleware config so only API paths are enforced.

Client-side detection

The middleware packages are server-side only. They do 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.

Route Matching (Next.js)

Control which routes the middleware applies to with the Next.js matcher config:

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

Next.js's built-in matcher skip list covers _next (its own static/image-optimization paths) and favicon.ico, but not arbitrary image extensions: a /logo.png or /hero.jpg served straight out of public/ isn't under _next/ and isn't covered by that skip list, so without the trailing .*\.(?:svg|png|jpg|jpeg|gif|webp)$ alternation, requests for it flow through the middleware and get classified like any other page. Add the extension exclusion whenever your app serves images outside of next/image.

To protect only specific routes:

export const config = {
  matcher: ['/api/:path*', '/dashboard/:path*'],
};

Next Steps

• Policies: Configure enforcement rules
• Detection in Enforce Mode: How middleware detects agents
• Gateway Enforcement: Alternative: DNS-based enforcement