Overview

The Checkpoint Express integration provides server-side AI agent detection and enforcement for Node.js applications. With simple middleware integration, you can protect your APIs and web applications from automated access.

Features

< 2ms latency — Minimal request overhead
Detect or Enforce modes — Log-only or active enforcement
Storage Adapters — Memory or Redis session storage
Route-level control — Protect specific endpoints
Policy Engine — Local policy evaluation
TypeScript — Full type definitions included

Installation

npm install @kya-os/agentshield-express

Quick Setup

const express = require('express');
const { createEnhancedAgentShieldMiddleware } = require('@kya-os/agentshield-express');

const app = express();

app.use(
  createEnhancedAgentShieldMiddleware({
    projectId: process.env.CHECKPOINT_PROJECT_ID,
    apiKey: process.env.CHECKPOINT_API_KEY,
  })
);

app.get('/', (req, res) => {
  res.send('Protected by Checkpoint');
});

app.listen(3000);

import express from 'express';
import {
  createEnhancedAgentShieldMiddleware,
  type EnhancedMiddlewareConfig,
} from '@kya-os/agentshield-express';

const app = express();

const config: EnhancedMiddlewareConfig = {
  projectId: process.env.CHECKPOINT_PROJECT_ID!,
  apiKey: process.env.CHECKPOINT_API_KEY!,
  mode: 'enforce',
};

app.use(createEnhancedAgentShieldMiddleware(config));

app.listen(3000);

Environment Variables

# .env
CHECKPOINT_PROJECT_ID=your_project_id_here
CHECKPOINT_API_KEY=your_api_key_here

Detect vs Enforce Mode

Mode	Behavior
`detect`	Classifies requests, adds detection info to `req`. All traffic passes through.
`enforce`	Classifies requests and applies policy actions (block, redirect, rate-limit).

// Detect mode (default) — log everything, block nothing
app.use(
  createEnhancedAgentShieldMiddleware({
    projectId: process.env.CHECKPOINT_PROJECT_ID!,
    apiKey: process.env.CHECKPOINT_API_KEY!,
    mode: 'detect',
  })
);

// Enforce mode — apply policy rules
app.use(
  createEnhancedAgentShieldMiddleware({
    projectId: process.env.CHECKPOINT_PROJECT_ID!,
    apiKey: process.env.CHECKPOINT_API_KEY!,
    mode: 'enforce',
  })
);

Configuration

createEnhancedAgentShieldMiddleware({
  // Required
  projectId: string,
  apiKey: string,

  // Mode
  mode?: 'detect' | 'enforce',       // Default: 'detect'

  // Policy
  policy?: PolicyConfig,              // Custom policy rules

  // Storage
  storage?: StorageConfig,            // Session storage configuration

  // Advanced
  skipPaths?: string[],               // Paths to skip detection
  skipMethods?: string[],             // HTTP methods to skip
  debug?: boolean,                    // Debug logging
});

Storage Adapters

Checkpoint Express includes built-in storage adapters for session tracking.

import {
  createEnhancedAgentShieldMiddleware,
  MemoryStorageAdapter,
} from '@kya-os/agentshield-express';

app.use(
  createEnhancedAgentShieldMiddleware({
    projectId: process.env.CHECKPOINT_PROJECT_ID!,
    apiKey: process.env.CHECKPOINT_API_KEY!,
    storage: {
      adapter: new MemoryStorageAdapter(),
      ttl: 3600, // 1 hour
    },
  })
);

Memory storage is suitable for single-instance deployments. For multi-instance or production, use Redis.

import {
  createEnhancedAgentShieldMiddleware,
  RedisStorageAdapter,
} from '@kya-os/agentshield-express';

app.use(
  createEnhancedAgentShieldMiddleware({
    projectId: process.env.CHECKPOINT_PROJECT_ID!,
    apiKey: process.env.CHECKPOINT_API_KEY!,
    storage: {
      adapter: new RedisStorageAdapter({
        url: process.env.REDIS_URL,
      }),
      ttl: 86400, // 24 hours
    },
  })
);

You can also create custom storage adapters using createStorageAdapter:

import { createStorageAdapter } from '@kya-os/agentshield-express';

const customAdapter = createStorageAdapter({
  get: async (key) => {
    /* retrieve from your store */
  },
  set: async (key, value, ttl) => {
    /* save to your store */
  },
  delete: async (key) => {
    /* remove from your store */
  },
});

Usage Patterns

Global Protection

// Protect all routes
app.use(
  createEnhancedAgentShieldMiddleware({
    projectId: process.env.CHECKPOINT_PROJECT_ID!,
    apiKey: process.env.CHECKPOINT_API_KEY!,
    mode: 'enforce',
  })
);

app.get('/api/data', (req, res) => {
  res.json({ protected: true });
});

Route-Specific Protection

const protect = createEnhancedAgentShieldMiddleware({
  projectId: process.env.CHECKPOINT_PROJECT_ID!,
  apiKey: process.env.CHECKPOINT_API_KEY!,
  mode: 'enforce',
});

// Only protect specific routes
app.get('/api/sensitive', protect, (req, res) => {
  res.json({ sensitive: 'data' });
});

// Unprotected route
app.get('/api/public', (req, res) => {
  res.json({ public: 'data' });
});

Conditional Protection

app.use((req, res, next) => {
  // Skip protection for authenticated users
  if (req.user && req.user.authenticated) {
    return next();
  }

  // Apply Checkpoint for unauthenticated requests
  createEnhancedAgentShieldMiddleware({
    projectId: process.env.CHECKPOINT_PROJECT_ID!,
    apiKey: process.env.CHECKPOINT_API_KEY!,
    mode: 'enforce',
  })(req, res, next);
});

Error Handling

app.use(
  createEnhancedAgentShieldMiddleware({
    projectId: process.env.CHECKPOINT_PROJECT_ID!,
    apiKey: process.env.CHECKPOINT_API_KEY!,
    mode: 'enforce',
    onError: (error, req, res, next) => {
      console.error('Checkpoint error:', error);
      // Continue without protection on error
      next();
    },
  })
);

Testing

const request = require('supertest');
const app = require('./app');

describe('Checkpoint Protection', () => {
  it('should detect bot user agents', async () => {
    const response = await request(app).get('/api/protected').set('User-Agent', 'bot/1.0');

    // In detect mode, request passes through with detection data
    expect(response.status).toBe(200);
  });

  it('should allow normal browsers', async () => {
    const response = await request(app)
      .get('/api/protected')
      .set('User-Agent', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)...');

    expect(response.status).toBe(200);
  });
});

Troubleshooting

Middleware not working

Verify projectId and apiKey are set
Ensure middleware is added before routes (app.use before app.get)
Enable debug: true for detailed logs

Performance issues

Use Redis storage adapter in production
Enable skipPaths for health checks and static assets
Use skipMethods to skip OPTIONS/HEAD requests

Next Steps

Middleware Enforcement — Complete middleware documentation with all features
Policies — Configure enforcement rules
Next.js Integration — Edge-optimized middleware for Next.js
Choose Your Integration — Compare all integration options

Express Integration