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
onResultcallback - 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.
withCheckpointneedsexpress.json()mounted ahead of it (see Quick Setup below) so it can parse the KYA-OS envelope.
Installation
npm install @kya-os/checkpoint-expressQuick 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_hereapiKey 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
// 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 beforewithCheckpoint(required for KYA-OS envelope parsing) - Ensure the middleware is mounted before your routes (
app.usebeforeapp.get) - Enable
debug: trueto surface reporter and policy telemetry
Detections not showing in the dashboard
- Set
apiKey: without it, verdicts are computed locally but never reported - Enable
debug: trueand watch for reporter warnings to confirmapiKey/baseUrlrouting
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
- Middleware Enforcement: Complete middleware documentation with all features
- Express Observability: Record verdicts and read them in routes
- Policies: Configure enforcement rules
- Next.js Integration: Edge-optimized middleware for Next.js
- Choose Your Integration: Compare all integration options