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
| Code | When it fires |
|---|---|
detection/signature-verified | verificationMethod === 'kya-http': a kya-http/RFC 9421 signature verified. |
detection/delegation-verified | verificationMethod === 'kya-http-delegated': a verified delegation credential rode the request. |
detection/mcp-i-verified | verificationMethod === 'mcp-i' | 'kya-os' (the wire values; isKyaOsWireMethod): the MCP-I/KYA-OS handshake verified. |
detection/did-signature-verified | verificationMethod === 'did': the worker's DID-header scheme verified an Ed25519 signature against the agent's DID Document. |
detection/rfc9421-signature-verified | verificationMethod === 'signature': the worker's RFC 9421 signature verifier (ChatGPT et al.) verified against the DB-refreshed key directory. |
detection/tier1-attribution-verified | verificationMethod starts with tier1_ (e.g. tier1_rfc9421): the engine's Tier-1 protocol attribution verified. |
detection/a2a-verified | verificationMethod === 'a2a': an A2A Agent Card's declared security scheme (RFC 9421 keyid, or a JWT bearer against resolved JWKS) cryptographically verified. |
detection/verification-error | verificationMethod === 'error': a presented credential was demoted/rejected during verification; see the sibling kyaErrorCode. |
Structured evidence signals
| Code | When it fires |
|---|---|
detection/ua-pattern-match | A signals[] entry with source === 'user_agent_pattern': the User-Agent matched a known pattern. |
detection/header-heuristic | source === 'header_heuristic': a header shape/combination heuristic matched. |
detection/ip-heuristic | source === 'ip_heuristic': an IP-based heuristic matched. |
detection/vendor-ip-corroborated | source === 'vendor_ip_feed': the request IP matched a known vendor's published IP range. |
detection/ip-intelligence-proxy-signal | source === 'ip_intelligence': the host's IP-intelligence provider flagged the request's true IP as a proxy/VPN/Tor/anonymization exit. |
detection/ja4-fingerprint-match | source === 'transport.ja4': a TLS JA4 fingerprint was observed at the terminating proxy (emit-only observation marker; it matches no list). |
detection/client-integrity-failure | source === '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-mismatch | source === '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-signal | source === 'client.attributes': a pixel/beacon-reported client attribute contributed. |
detection/behavioral-signal | source === 'behavioural.interaction': a behavioral/interaction signal contributed. |
detection/mcp-i-signal | source === 'mcp_i': an MCP-I header was present (evidence short of a completed handshake). |
detection/kya-http-binding-signal | source === 'kya_http_binding': a kya-http binding was presented (evidence short of full verification). |
detection/kya-delegation-bearer-signal | source === 'kya_delegation_bearer': a delegation bearer credential was presented. |
detection/tier1-attribution-signal | A signals[] entry whose source starts with tier1_: raw Tier-1 protocol evidence, short of (or alongside) full verification. |
detection/a2a-card-signal | A signals[] entry with source === 'a2a_agent_card': an A2A Agent Card was presented (evidence short of, or alongside, full verification). |
detection/scanner-misclassification-hint-signal | source === 'scanner_misclassification_hint': Cloudflare's bot score contradicted a zero-evidence Human verdict, overriding it to Unknown. |
detection/client-headless-escalation-signal | source === 'client_headless_escalation': the beacon disclosed navigator.webdriver, or reported corroborating automation evidence (CDP/plugin/WebGL consistency, a distinctive property), escalating the classification. |
detection/cloudflare-bot-management-signal | source === 'transport.cloudflare_bot_management': Cloudflare's bot-management score or verified-bot determination contributed. |
detection/session-velocity-signal | source === 'session_velocity': the edge-computed request-velocity heuristic contributed. |
Classification flags
| Code | When it fires |
|---|---|
detection/ai-crawler-flag | isAiCrawler === true: classified as an AI training crawler (GPTBot, ClaudeBot, etc.), not an interactive agent. |
Zero-evidence fallbacks
| Code | When it fires |
|---|---|
detection/zero-evidence-human | detectionClass === 'human' with no contributing signals and no verification: the baseline "nothing matched" human path. |
detection/incomplete-data-override | detectionClass === 'incomplete_data' | 'unknown' (or absent): the engine could not classify confidently. |
detection/classified-without-signal-evidence | A non-human, non-incomplete-data class (ai_agent / bot / automation) reached with zero contributing signals and no verification: classified on prior/heuristic grounds alone. |