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, and ASP.NET Core applications.

Installation

npm install @kya-os/checkpoint-nextjs

npm install @kya-os/checkpoint-express

# Metapackage — pulls Checkpoint.Core + the adapters transitively
dotnet add package KyaOs.Checkpoint

# — or reference the pieces directly —
dotnet add package Checkpoint.AspNetCore   # ASP.NET Core (net8) middleware
dotnet add package Checkpoint.Core         # engine, options, detection types
# dotnet add package Checkpoint.AspNet     # classic ASP.NET / IIS (net462) module

Basic Setup

// 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
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

// middleware.ts
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).*)'],
};

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

const app = express();
app.use(express.json()); // body-parser — required for MCP-I envelope parsing

app.use(
  withCheckpoint({
    tenantHost: 'your.tenant.example',
    apiKey: process.env.CHECKPOINT_API_KEY, // optional — enables dashboard reporting
  })
);

app.get('/', (_req, res) => {
  res.json({ message: 'Protected by Checkpoint' });
});

app.listen(3000);

// Program.cs
using Checkpoint.AspNetCore.Extensions;
using Checkpoint.Core.Configuration;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCheckpoint(options =>
{
    options.ProjectId = builder.Configuration["Checkpoint:ProjectId"]!;
    options.ApiKey = builder.Configuration["Checkpoint:ApiKey"]!;
    options.OnAgentDetected = DetectedAction.Block;
});

var app = builder.Build();

app.UseCheckpoint(); // Add early — before UseRouting()

app.UseRouting();
app.UseAuthorization();
app.MapControllers();

app.Run();

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 drainJsonBody (default true) and, for the Edge runtime, cedarWasmModule.

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' | 'redirect' | ...
    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.agentShield on subsequent requests:

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

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

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

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:

.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)

Protect individual App Router routes with withCheckpointApi:

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

export const GET = withCheckpointApi(async (req) => {
  return Response.json({ data: 'protected' });
});

Client-side hooks

For React applications, import hooks from a separate entry point:

import { useAgentDetection } from '@kya-os/checkpoint-nextjs/hooks';

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).*)',
  ],
};

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