byVouched
API ReferenceBlogSign inGet started
GuidesDetectEnforceGovern

Reason codes

Machine-readable detection/* codes explaining why a verdict landed where it did

Machine-readable detection/* codes describing WHY a detection verdict landed where it did: a projection of the engine's structured evidence (signals[], verificationMethod, detectionClass, isAiCrawler) onto the KYA-Reason-Codes wire header, persisted detection metadata, and the enforce-response reasonCodes field. See packages/checkpoint-shared/src/core/detection-reason-codes.ts for the registry and packages/checkpoint-shared/src/core/detection-reason-mapping.ts for the derivation (mapDetectionToReasonCodes, consumed by the gateway worker and the /api/v1/enforce signal exposure).

Verified attribution

CodeWhen it fires
detection/signature-verifiedverificationMethod === 'kya-http' — a kya-http/RFC 9421 signature verified.
detection/delegation-verifiedverificationMethod === 'kya-http-delegated' — a verified delegation credential rode the request.
detection/mcp-i-verifiedverificationMethod === 'mcp-i' | 'kya-os' (the wire values; isKyaOsWireMethod) — the MCP-I/KYA-OS handshake verified.
detection/did-signature-verifiedverificationMethod === 'did' — the worker's DID-header scheme verified an Ed25519 signature against the agent's DID Document.
detection/rfc9421-signature-verifiedverificationMethod === 'signature' — the worker's RFC 9421 signature verifier (ChatGPT et al.) verified against the DB-refreshed key directory.
detection/tier1-attribution-verifiedverificationMethod starts with tier1_ (e.g. tier1_rfc9421) — the engine's Tier-1 protocol attribution verified.
detection/a2a-verifiedverificationMethod === 'a2a' — an A2A Agent Card's declared security scheme (RFC 9421 keyid, or a JWT bearer against resolved JWKS) cryptographically verified.
detection/verification-errorverificationMethod === 'error' — a presented credential was demoted/rejected during verification; see the sibling kyaErrorCode.

Structured evidence signals

CodeWhen it fires
detection/ua-pattern-matchA signals[] entry with source === 'user_agent_pattern' — the User-Agent matched a known pattern.
detection/header-heuristicsource === 'header_heuristic' — a header shape/combination heuristic matched.
detection/ip-heuristicsource === 'ip_heuristic' — an IP-based heuristic matched.
detection/vendor-ip-corroboratedsource === 'vendor_ip_feed' — the request IP matched a known vendor's published IP range.
detection/ip-intelligence-proxy-signalsource === 'ip_intelligence' — the host's IP-intelligence provider flagged the request's true IP as a proxy/VPN/Tor/anonymization exit.
detection/ja4-fingerprint-matchsource === 'transport.ja4' — a TLS JA4 fingerprint was observed at the terminating proxy (emit-only observation marker; it matches no list).
detection/client-integrity-failuresource === 'client_integrity' — the pixel/beacon ingest's own nonce-binding or pairwise-contradiction check flagged this request as not coming from the client it claims to.
detection/ua-tls-mismatchsource === 'ua_tls_mismatch' — the User-Agent claims a browser but the JA4 cipher-list hash (JA4_b) belongs to known non-browser tooling.
detection/client-attribute-signalsource === 'client.attributes' — a pixel/beacon-reported client attribute contributed.
detection/behavioral-signalsource === 'behavioural.interaction' — a behavioral/interaction signal contributed.
detection/mcp-i-signalsource === 'mcp_i' — an MCP-I header was present (evidence short of a completed handshake).
detection/kya-http-binding-signalsource === 'kya_http_binding' — a kya-http binding was presented (evidence short of full verification).
detection/kya-delegation-bearer-signalsource === 'kya_delegation_bearer' — a delegation bearer credential was presented.
detection/tier1-attribution-signalA signals[] entry whose source starts with tier1_ — raw Tier-1 protocol evidence, short of (or alongside) full verification.

Classification flags

CodeWhen it fires
detection/ai-crawler-flagisAiCrawler === true — classified as an AI training crawler (GPTBot, ClaudeBot, etc.), not an interactive agent.

Zero-evidence fallbacks

CodeWhen it fires
detection/zero-evidence-humandetectionClass === 'human' with no contributing signals and no verification — the baseline "nothing matched" human path.
detection/incomplete-data-overridedetectionClass === 'incomplete_data' | 'unknown' (or absent) — the engine could not classify confidently.
detection/classified-without-signal-evidenceA non-human, non-incomplete-data class (ai_agent / bot / automation) reached with zero contributing signals and no verification — classified on prior/heuristic grounds alone.

Detection in Enforce Mode

How Gateway and Middleware detect AI agents at the edge and server-side

Gateway Monitoring

Monitor Gateway health, performance, and detection metrics

On this page

Verified attributionStructured evidence signalsClassification flagsZero-evidence fallbacks