IntegrationsExpress

Express Integration

Server-side AI agent detection for Express and Node.js applications

Overview

The Vouched KYA Express integration provides server-side AI agent detection and enforcement for Node.js applications. Mount one middleware factory (withCheckpoint) and every request flows through the in-process WASM engine: UA pattern detection, KYA-OS signature verification, scope evaluation, single-hop delegation verification, and policy evaluation.

  • In-process WASM engine: No per-request network hop
  • Enforce or Observe modes: Active enforcement or log-only dry runs
  • Cedar policy enforcement: Enforces your deployed dashboard policy in-process, byte-for-byte the same as the DNS Gateway
  • Route-level control: Protect specific endpoints
  • Observability: Every verdict through the onResult callback
  • TypeScript: Full type definitions included

Prerequisites

  • A Vouched KYA project: get your Project ID and API key from Installations in the dashboard.
  • An existing Express app. withCheckpoint needs express.json() mounted ahead of it (see Quick Setup below) so it can parse the KYA-OS envelope.

Installation

npm install @kya-os/checkpoint-express

Quick Setup

const express = require('express');
const { withCheckpoint } = require('@kya-os/checkpoint-express');

const app = express();
app.use(express.json()); // body-parser: required for KYA-OS envelope parsing

app.use(
  withCheckpoint({
    apiKey: process.env.CHECKPOINT_API_KEY, // enables dashboard reporting
  })
);

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

app.listen(3000);

The legacy createEnhancedAgentShieldMiddleware was removed in @kya-os/checkpoint-express@1.3.0. Record verdicts from the onResult callback instead: see Express Observability.

Read the browser posture outcome

With browser posture configured, withCheckpoint verifies the posture token once per request. A route handler reads that outcome with getCheckpointPostureOutcome instead of verifying the token again:

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

const app = express();

app.use(
  withCheckpoint({
    apiKey: process.env.CHECKPOINT_API_KEY,
    projectId: '<lowercase project UUID>',
    browserPosture: {
      origin: 'https://www.shop.example',
      keyId: process.env.CHECKPOINT_POSTURE_KEY_ID!,
      publicKey: JSON.parse(process.env.CHECKPOINT_POSTURE_PUBLIC_JWK!),
    },
  })
);

app.post('/checkout', (req, res) => {
  const outcome = getCheckpointPostureOutcome(req);

  if (outcome === undefined) {
    res.json({ posture: 'unknown' });
    return;
  }

  res.json({ posture: outcome.status, reason: outcome.reason, verdict: outcome.posture?.verdict });
});

The result is { status, reason?, posture? }. status is verified, absent, or rejected, reason names why a token was rejected, and posture holds the verified claims only when the status is verified. The outcome is held in memory against the request object, so a client cannot set it. A verified token that carries the beacon's agent or bot verdict (posture.detection), or discloses automation, also reclassifies a request the engine called human or incomplete data.

undefined means unknown: browserPosture is not configured, or the middleware did not run for this request. It is not the same as { status: 'absent' }, so a handler gating an action must treat undefined as unknown.

Configuration

The most common withCheckpoint options:

withCheckpoint({
  // Dashboard integration
  apiKey?: string,                 // Project API key: required for dashboard reporting
  projectId?: string,              // Apply this project's deployed Cedar policy in-process; needs apiKey
  baseUrl?: string,                // Dashboard base URL (default: https://kya.vouched.id)

  // Behavior
  enforcementMode?: 'enforce' | 'observe',  // Default: 'enforce'
  policyCacheTtlSeconds?: number,  // Policy-fetch cache TTL (default: 300)

  // Observability
  onResult?: (result, req) => void, // Fires after every verification with the full VerifyResult
  debug?: boolean,                  // Surface reporter + policy telemetry via console.warn
});

projectId needs apiKey: the project's policy is read with the project's API key. With projectId and no apiKey, enforce mode is a configuration error: withCheckpoint throws; in observe mode, requests are served on the engine's decision without the project's policy, and one warning is logged at startup. With both set, the policy is read when the middleware starts, so a refused key is logged before the first request. When the policy cannot be read, because the policy API refuses the key or is down, observe mode still serves every request and enforce mode answers 503. A refused key is logged at most about once a minute, with a message naming CHECKPOINT_API_KEY, and so are the detection reports the dashboard refuses for it. A policy outage is logged at most about every 5 seconds, and the next request reads the policy again, so one failed read refuses only the request that made it.

See Middleware Enforcement for the complete option table, response headers, and response shapes shared with the Next.js and .NET middleware.

Environment Variables

# .env
CHECKPOINT_API_KEY=your_api_key_here
CHECKPOINT_PROJECT_ID=your_project_id_here

apiKey is required for detections to land in the dashboard: without it the verdict path works locally, but the onboarding Verify connection check never passes because no detection rows are written. Get both values from Installations in the dashboard.

Enforce vs Observe Mode

ModeBehavior
enforceApplies the policy verdict: block, redirect, or challenge for consent/identity. Default.
observeClassifies every request and stamps X-Checkpoint-Would-Have-Been headers. All traffic passes through.
// Observe mode: log everything, block nothing
app.use(
  withCheckpoint({
    apiKey: process.env.CHECKPOINT_API_KEY,
    enforcementMode: 'observe',
  })
);

Start in observe, review the would-have-been decisions in the dashboard, then remove the override (or set 'enforce') when the verdicts look right.

Response Headers

The engine sets X-Checkpoint-* response headers and a __checkpoint_verdict cookie, byte-identical to the Next.js sibling package. In observe mode, X-Checkpoint-Would-Have-Been is added instead of enforcing the verdict.

See Middleware Enforcement for the complete header reference shared with Next.js and .NET.

Observability

Plain withCheckpoint attaches nothing to req: read verdicts from the onResult callback, which fires after every verification (errors thrown inside it are swallowed so observability can never break the verdict path):

app.use(
  withCheckpoint({
    apiKey: process.env.CHECKPOINT_API_KEY,
    onResult: (result, req) => {
      console.log(req.path, result.detectionDetail.detectionClass.type);
    },
  })
);

To record verdicts in your own store, or read the verdict in a route handler through res.locals, see Express Observability.

Usage Patterns

Global Protection

// Protect all routes
app.use(
  withCheckpoint({
    apiKey: process.env.CHECKPOINT_API_KEY,
  })
);

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

Route-Specific Protection

withCheckpoint returns standard Express middleware, so you can mount it per-route. Construct it once and reuse it:

const protect = withCheckpoint({
  apiKey: process.env.CHECKPOINT_API_KEY,
});

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

Testing

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

describe('Checkpoint Protection', () => {
  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);
  });

  it('should pass agents through in observe mode with a would-have-been header', async () => {
    const response = await request(app).get('/api/protected').set('User-Agent', 'GPTBot/1.0');

    // observe mode: request passes through, verdict is stamped on the response
    expect(response.status).toBe(200);
    expect(response.headers['x-checkpoint-would-have-been']).toBeDefined();
  });
});

Troubleshooting

Middleware not working

  • Ensure app.use(express.json()) runs before withCheckpoint (required for KYA-OS envelope parsing)
  • Ensure the middleware is mounted before your routes (app.use before app.get)
  • Enable debug: true to surface reporter and policy telemetry

Detections not showing in the dashboard

  • Set apiKey: without it, verdicts are computed locally but never reported
  • Enable debug: true and watch for reporter warnings to confirm apiKey / baseUrl routing

Policy changes not taking effect

  • Fetched policies are cached for policyCacheTtlSeconds (default 300s): wait out the TTL or lower it
  • Confirm the policy is deployed (not a draft) and engine enforcement is enabled for the project

Next Steps