@kya-os/checkpoint

Base SDK for AI agent detection, formerly published as @kya-os/agentshield. Provides the shared analyzer surface (PatternAnalyzer, BehaviorAnalyzer, ScoringEngine) consumed by @kya-os/checkpoint-nextjs, @kya-os/checkpoint-express, and @kya-os/checkpoint-beacon.

Most production integrations should use the engine-backed @kya-os/checkpoint-wasm-runtime instead — it wraps the Rust kya-os-engine (Tier 1 RFC 9421 signatures + Tier 2 vendor IP+UA cross-match + Tier 3 UA patterns) behind a single engineVerify call.

Installation

npm install @kya-os/checkpoint

Quick Start

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

const result = await detectAgent({
  userAgent: req.headers['user-agent'],
  ip: req.ip,
  headers: req.headers,
  url: req.url,
  method: req.method,
});

if (result.isAgent) {
  console.log(`Agent detected with ${result.confidence} confidence`);
  console.log('Reasons:', result.reasons);
}

For engine-backed verification (preferred) see @kya-os/checkpoint-wasm-runtime or the framework wrappers:

• @kya-os/checkpoint-nextjs — withCheckpoint HOC + middleware
• @kya-os/checkpoint-express — Express middleware

Lower-level analyzers

import { PatternAnalyzer, BehaviorAnalyzer, ScoringEngine } from '@kya-os/checkpoint';

const patterns = new PatternAnalyzer();
const behavior = new BehaviorAnalyzer();
const scoring = new ScoringEngine();

const patternResult = patterns.analyze(context);
const behaviorResult = behavior.analyze(context);
const score = scoring.score([patternResult, behaviorResult]);

Types

import type {
  DetectionDetail,
  DetectionResult,
  RequestContext,
  AgentShieldConfig,
} from '@kya-os/checkpoint';

All public types re-export from @kya-os/checkpoint-shared — import from whichever entry is more convenient.

License

MIT OR Apache-2.0