@kya-os/checkpoint-shared 1.7.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (277) hide show
  1. package/CHANGELOG.md +159 -9
  2. package/README.md +24 -7
  3. package/dist/agent-catalog.d.mts +12 -0
  4. package/dist/agent-catalog.d.mts.map +1 -0
  5. package/dist/agent-catalog.d.ts +12 -0
  6. package/dist/agent-catalog.d.ts.map +1 -0
  7. package/dist/agent-catalog.js +105 -0
  8. package/dist/agent-catalog.mjs +105 -0
  9. package/dist/agent-catalog.mjs.map +1 -0
  10. package/dist/beacon-nonce/index.d.mts +1 -0
  11. package/dist/beacon-nonce/index.d.mts.map +1 -1
  12. package/dist/beacon-nonce/index.d.ts +1 -0
  13. package/dist/beacon-nonce/index.d.ts.map +1 -1
  14. package/dist/beacon-nonce/index.js +9 -3
  15. package/dist/beacon-nonce/index.mjs +9 -4
  16. package/dist/beacon-nonce/index.mjs.map +1 -1
  17. package/dist/beacon-types/index.d.mts +41 -1
  18. package/dist/beacon-types/index.d.mts.map +1 -1
  19. package/dist/beacon-types/index.d.ts +41 -1
  20. package/dist/beacon-types/index.d.ts.map +1 -1
  21. package/dist/beacon-types/index.js +153 -4
  22. package/dist/beacon-types/index.mjs +139 -4
  23. package/dist/beacon-types/index.mjs.map +1 -1
  24. package/dist/{browser-posture-BLhw-MON.d.mts → browser-posture-5fPrsxx7.d.mts} +6 -6
  25. package/dist/{browser-posture-BLhw-MON.d.mts.map → browser-posture-5fPrsxx7.d.mts.map} +1 -1
  26. package/dist/{browser-posture-B8YiPa5c.d.ts → browser-posture-CCR1kh5e.d.ts} +6 -6
  27. package/dist/{browser-posture-B8YiPa5c.d.ts.map → browser-posture-CCR1kh5e.d.ts.map} +1 -1
  28. package/dist/browser-posture-cookie.js +1 -1
  29. package/dist/browser-posture-cookie.mjs +1 -1
  30. package/dist/browser-posture-cookie.mjs.map +1 -1
  31. package/dist/browser-posture-proof-verifier-DvsOmFrM.js +202 -0
  32. package/dist/browser-posture-proof-verifier-I0HP2Ics.mjs +180 -0
  33. package/dist/browser-posture-proof-verifier-I0HP2Ics.mjs.map +1 -0
  34. package/dist/browser-posture-proof-verifier.d.mts +25 -0
  35. package/dist/browser-posture-proof-verifier.d.mts.map +1 -0
  36. package/dist/browser-posture-proof-verifier.d.ts +25 -0
  37. package/dist/browser-posture-proof-verifier.d.ts.map +1 -0
  38. package/dist/browser-posture-proof-verifier.js +7 -0
  39. package/dist/browser-posture-proof-verifier.mjs +3 -0
  40. package/dist/browser-posture-proof.d.mts +4 -5
  41. package/dist/browser-posture-proof.d.mts.map +1 -1
  42. package/dist/browser-posture-proof.d.ts +4 -5
  43. package/dist/browser-posture-proof.d.ts.map +1 -1
  44. package/dist/browser-posture-proof.js +10 -79
  45. package/dist/browser-posture-proof.mjs +6 -77
  46. package/dist/browser-posture-proof.mjs.map +1 -1
  47. package/dist/browser-posture.d.mts +1 -1
  48. package/dist/browser-posture.d.ts +1 -1
  49. package/dist/browser-posture.js +6 -5
  50. package/dist/browser-posture.mjs +4 -3
  51. package/dist/browser-posture.mjs.map +1 -1
  52. package/dist/browser.d.mts +25 -286
  53. package/dist/browser.d.mts.map +1 -1
  54. package/dist/browser.d.ts +25 -286
  55. package/dist/browser.d.ts.map +1 -1
  56. package/dist/browser.js +1 -1
  57. package/dist/browser.mjs +1 -1
  58. package/dist/browser.mjs.map +1 -1
  59. package/dist/canonical-signer/index.js +30 -28
  60. package/dist/canonical-signer/index.mjs +31 -1
  61. package/dist/canonical-signer/index.mjs.map +1 -1
  62. package/dist/clearance.d.mts +1 -1
  63. package/dist/clearance.d.ts +1 -1
  64. package/dist/clearance.js +2 -2
  65. package/dist/clearance.mjs +2 -2
  66. package/dist/client-ip-B7w-uHfS.d.mts +55 -0
  67. package/dist/client-ip-B7w-uHfS.d.mts.map +1 -0
  68. package/dist/client-ip-B7w-uHfS.d.ts +55 -0
  69. package/dist/client-ip-B7w-uHfS.d.ts.map +1 -0
  70. package/dist/{client-ip-CW6pRyLf.js → client-ip-B8wFzJ5f.js} +117 -7
  71. package/dist/{client-ip-B2Xeo-GK.mjs → client-ip-DIJyr6px.mjs} +113 -9
  72. package/dist/client-ip-DIJyr6px.mjs.map +1 -0
  73. package/dist/client-ip.d.mts +2 -2
  74. package/dist/client-ip.d.ts +2 -2
  75. package/dist/client-ip.js +3 -2
  76. package/dist/client-ip.mjs +2 -2
  77. package/dist/consent-handoff.d.mts +0 -3
  78. package/dist/consent-handoff.d.mts.map +1 -1
  79. package/dist/consent-handoff.d.ts +0 -3
  80. package/dist/consent-handoff.d.ts.map +1 -1
  81. package/dist/consent-handoff.mjs.map +1 -1
  82. package/dist/default-sign-in-host.d.mts +10 -0
  83. package/dist/default-sign-in-host.d.mts.map +1 -0
  84. package/dist/default-sign-in-host.d.ts +10 -0
  85. package/dist/default-sign-in-host.d.ts.map +1 -0
  86. package/dist/default-sign-in-host.js +72 -0
  87. package/dist/default-sign-in-host.mjs +66 -0
  88. package/dist/default-sign-in-host.mjs.map +1 -0
  89. package/dist/detection-reason-mapping-B9RSkOs8.js +277 -0
  90. package/dist/detection-reason-mapping-BGymWIPl.mjs +249 -0
  91. package/dist/detection-reason-mapping-BGymWIPl.mjs.map +1 -0
  92. package/dist/detection-reason-mapping-CQexNvR7.d.mts +52 -0
  93. package/dist/detection-reason-mapping-CQexNvR7.d.mts.map +1 -0
  94. package/dist/detection-reason-mapping-CQexNvR7.d.ts +52 -0
  95. package/dist/detection-reason-mapping-CQexNvR7.d.ts.map +1 -0
  96. package/dist/engine-enforcing-AYEcgNsb.js +39 -0
  97. package/dist/engine-enforcing-B5eNfCpG.mjs +29 -0
  98. package/dist/engine-enforcing-B5eNfCpG.mjs.map +1 -0
  99. package/dist/engine-enforcing-DiOclGqf.d.mts +11 -0
  100. package/dist/engine-enforcing-DiOclGqf.d.mts.map +1 -0
  101. package/dist/engine-enforcing-DiOclGqf.d.ts +11 -0
  102. package/dist/engine-enforcing-DiOclGqf.d.ts.map +1 -0
  103. package/dist/engine-info.d.mts +2 -0
  104. package/dist/engine-info.d.ts +2 -0
  105. package/dist/engine-info.js +4 -0
  106. package/dist/engine-info.mjs +3 -0
  107. package/dist/errors/index.d.mts +6 -0
  108. package/dist/errors/index.d.mts.map +1 -1
  109. package/dist/errors/index.d.ts +6 -0
  110. package/dist/errors/index.d.ts.map +1 -1
  111. package/dist/errors/index.js +28 -6
  112. package/dist/errors/index.mjs +28 -6
  113. package/dist/errors/index.mjs.map +1 -1
  114. package/dist/{external-B7WI9FyQ.d.ts → external-m3Kmafwj.d.mts} +2 -2
  115. package/dist/{external-B7WI9FyQ.d.mts.map → external-m3Kmafwj.d.mts.map} +1 -1
  116. package/dist/{external-B7WI9FyQ.d.mts → external-m3Kmafwj.d.ts} +2 -2
  117. package/dist/{external-B7WI9FyQ.d.ts.map → external-m3Kmafwj.d.ts.map} +1 -1
  118. package/dist/fetcher-C8qvwdnA.d.ts +44 -0
  119. package/dist/fetcher-C8qvwdnA.d.ts.map +1 -0
  120. package/dist/fetcher-D2vjr7jB.d.mts +44 -0
  121. package/dist/fetcher-D2vjr7jB.d.mts.map +1 -0
  122. package/dist/gateway-client-ip.d.mts +1 -3
  123. package/dist/gateway-client-ip.d.mts.map +1 -1
  124. package/dist/gateway-client-ip.d.ts +1 -3
  125. package/dist/gateway-client-ip.d.ts.map +1 -1
  126. package/dist/gateway-client-ip.js +2 -2
  127. package/dist/gateway-client-ip.mjs +2 -2
  128. package/dist/gateway-client-ip.mjs.map +1 -1
  129. package/dist/host-adapter/index.d.mts +2 -2
  130. package/dist/host-adapter/index.d.ts +2 -2
  131. package/dist/host-adapter/index.js +2 -1
  132. package/dist/host-adapter/index.mjs +2 -2
  133. package/dist/{host-adapter-C-4IxmqM.mjs → host-adapter-BKdQHwbi.mjs} +56 -3
  134. package/dist/{host-adapter-C-4IxmqM.mjs.map → host-adapter-BKdQHwbi.mjs.map} +1 -1
  135. package/dist/{host-adapter-CwW9YB0U.js → host-adapter-bWftXA9T.js} +60 -1
  136. package/dist/index-DnFsmr_o.d.ts +156 -0
  137. package/dist/index-DnFsmr_o.d.ts.map +1 -0
  138. package/dist/index-rvw5Bz-r.d.mts +156 -0
  139. package/dist/index-rvw5Bz-r.d.mts.map +1 -0
  140. package/dist/index.d.mts +6681 -11335
  141. package/dist/index.d.mts.map +1 -1
  142. package/dist/index.d.ts +6681 -11335
  143. package/dist/index.d.ts.map +1 -1
  144. package/dist/index.js +2322 -6900
  145. package/dist/index.mjs +2236 -6574
  146. package/dist/index.mjs.map +1 -1
  147. package/dist/{kya-http-error-codes-UYb1zpGM.js → kya-http-error-codes-B4rUmUEI.js} +2 -0
  148. package/dist/{kya-http-error-codes-7ewV5RuK.d.ts → kya-http-error-codes-C14E4gi3.d.mts} +2 -1
  149. package/dist/kya-http-error-codes-C14E4gi3.d.mts.map +1 -0
  150. package/dist/{kya-http-error-codes-7ewV5RuK.d.mts → kya-http-error-codes-C14E4gi3.d.ts} +2 -1
  151. package/dist/kya-http-error-codes-C14E4gi3.d.ts.map +1 -0
  152. package/dist/{kya-http-error-codes-C2JiWPsi.mjs → kya-http-error-codes-DSBrxNry.mjs} +3 -1
  153. package/dist/kya-http-error-codes-DSBrxNry.mjs.map +1 -0
  154. package/dist/kya-http.d.mts +3 -3
  155. package/dist/kya-http.d.ts +3 -3
  156. package/dist/kya-http.js +10 -2
  157. package/dist/kya-http.mjs +4 -3
  158. package/dist/mcpi/dashboard-config/index.d.mts.map +1 -1
  159. package/dist/mcpi/dashboard-config/index.d.ts.map +1 -1
  160. package/dist/mcpi/dashboard-config/index.mjs.map +1 -1
  161. package/dist/mcpi/status-list/index.d.mts +72 -0
  162. package/dist/mcpi/status-list/index.d.mts.map +1 -0
  163. package/dist/mcpi/status-list/index.d.ts +72 -0
  164. package/dist/mcpi/status-list/index.d.ts.map +1 -0
  165. package/dist/mcpi/status-list/index.js +703 -0
  166. package/dist/mcpi/status-list/index.mjs +684 -0
  167. package/dist/mcpi/status-list/index.mjs.map +1 -0
  168. package/dist/patterns-Bp40cwh2.d.mts +110 -0
  169. package/dist/patterns-Bp40cwh2.d.mts.map +1 -0
  170. package/dist/patterns-Bp40cwh2.d.ts +110 -0
  171. package/dist/patterns-Bp40cwh2.d.ts.map +1 -0
  172. package/dist/patterns-CiMpbdAF.js +243 -0
  173. package/dist/patterns-D4OAsNQY.mjs +173 -0
  174. package/dist/patterns-D4OAsNQY.mjs.map +1 -0
  175. package/dist/patterns.d.mts +2 -0
  176. package/dist/patterns.d.ts +2 -0
  177. package/dist/patterns.js +15 -0
  178. package/dist/patterns.mjs +3 -0
  179. package/dist/policy/enforcement.d.mts +3 -2
  180. package/dist/policy/enforcement.d.ts +3 -2
  181. package/dist/policy/enforcement.js +8 -2
  182. package/dist/policy/enforcement.mjs +3 -2
  183. package/dist/policy/fetcher.d.mts +2 -0
  184. package/dist/policy/fetcher.d.ts +2 -0
  185. package/dist/policy/fetcher.js +240 -0
  186. package/dist/policy/fetcher.mjs +238 -0
  187. package/dist/policy/fetcher.mjs.map +1 -0
  188. package/dist/policy/schemas.d.mts +3 -0
  189. package/dist/policy/schemas.d.ts +3 -0
  190. package/dist/policy/schemas.js +27 -0
  191. package/dist/policy/schemas.mjs +4 -0
  192. package/dist/{posture-origins-Ba83O0cD.mjs → posture-origins-Ci6k4Zh1.js} +24 -173
  193. package/dist/{posture-origins-CdVOdiMT.js → posture-origins-DGyS4Vuk.mjs} +2 -267
  194. package/dist/posture-origins-DGyS4Vuk.mjs.map +1 -0
  195. package/dist/{project-verification-key-BccT12tQ.js → project-verification-key-B-L3D2nC.js} +1 -1
  196. package/dist/{project-verification-key-66N4edKn.mjs → project-verification-key-CWXdu3-n.mjs} +2 -2
  197. package/dist/{project-verification-key-66N4edKn.mjs.map → project-verification-key-CWXdu3-n.mjs.map} +1 -1
  198. package/dist/provider-registry.d.mts +2 -0
  199. package/dist/provider-registry.d.ts +2 -0
  200. package/dist/provider-registry.js +51 -0
  201. package/dist/provider-registry.mjs +3 -0
  202. package/dist/reason-codes.d.mts +2 -0
  203. package/dist/reason-codes.d.ts +2 -0
  204. package/dist/reason-codes.js +8 -0
  205. package/dist/reason-codes.mjs +3 -0
  206. package/dist/{registered-sid-hUl-bvM5.mjs → registered-sid-26hNxp6t.mjs} +11 -2
  207. package/dist/registered-sid-26hNxp6t.mjs.map +1 -0
  208. package/dist/registered-sid-D6KCaT1E.d.mts +33 -0
  209. package/dist/registered-sid-D6KCaT1E.d.mts.map +1 -0
  210. package/dist/registered-sid-D6KCaT1E.d.ts +33 -0
  211. package/dist/registered-sid-D6KCaT1E.d.ts.map +1 -0
  212. package/dist/{registered-sid-eLCNZvIF.js → registered-sid-DVGTSH0L.js} +15 -0
  213. package/dist/ruleset-hash-Cmv8MSO5.js +34 -0
  214. package/dist/ruleset-hash-IRN5eI9H.d.mts +5 -0
  215. package/dist/ruleset-hash-IRN5eI9H.d.mts.map +1 -0
  216. package/dist/ruleset-hash-IRN5eI9H.d.ts +5 -0
  217. package/dist/ruleset-hash-IRN5eI9H.d.ts.map +1 -0
  218. package/dist/ruleset-hash-QQIaLuPi.mjs +30 -0
  219. package/dist/ruleset-hash-QQIaLuPi.mjs.map +1 -0
  220. package/dist/{schemas-YhagYDx_.js → schemas-BlScS1it.js} +0 -20
  221. package/dist/{index-HaqfPtaL.d.ts → schemas-CGKHzcMV.d.ts} +23 -195
  222. package/dist/schemas-CGKHzcMV.d.ts.map +1 -0
  223. package/dist/schemas-Cm4C4Z5G.js +703 -0
  224. package/dist/schemas-DPIT8usF.mjs +525 -0
  225. package/dist/schemas-DPIT8usF.mjs.map +1 -0
  226. package/dist/{schemas-7qodsG-Z.mjs → schemas-IHAhH3gV.mjs} +2 -16
  227. package/dist/schemas-IHAhH3gV.mjs.map +1 -0
  228. package/dist/{index-B7rTovHa.d.mts → schemas-m-GqyfyO.d.mts} +23 -195
  229. package/dist/schemas-m-GqyfyO.d.mts.map +1 -0
  230. package/dist/{step-up-COlmWJN8.mjs → step-up-BK0oBi11.mjs} +91 -41
  231. package/dist/step-up-BK0oBi11.mjs.map +1 -0
  232. package/dist/{step-up-C2d8C20x.js → step-up-Bp8RAQwv.js} +117 -55
  233. package/dist/{step-up-BjP--hG-.d.mts → step-up-Bz12gYKT.d.mts} +28 -12
  234. package/dist/step-up-Bz12gYKT.d.mts.map +1 -0
  235. package/dist/{step-up-BjP--hG-.d.ts → step-up-Bz12gYKT.d.ts} +28 -12
  236. package/dist/step-up-Bz12gYKT.d.ts.map +1 -0
  237. package/dist/test-fixtures/index.d.mts +4 -4
  238. package/dist/test-fixtures/index.d.mts.map +1 -1
  239. package/dist/test-fixtures/index.d.ts +4 -4
  240. package/dist/test-fixtures/index.d.ts.map +1 -1
  241. package/dist/test-fixtures/index.js +4 -4
  242. package/dist/test-fixtures/index.mjs +4 -4
  243. package/dist/test-fixtures/index.mjs.map +1 -1
  244. package/dist/tool-protection/index.d.mts +12 -0
  245. package/dist/tool-protection/index.d.mts.map +1 -1
  246. package/dist/tool-protection/index.d.ts +12 -0
  247. package/dist/tool-protection/index.d.ts.map +1 -1
  248. package/dist/tool-protection/index.js +46 -0
  249. package/dist/tool-protection/index.mjs +44 -1
  250. package/dist/tool-protection/index.mjs.map +1 -1
  251. package/dist/verification-BAw9N8Pt.js +181 -0
  252. package/dist/verification-Cvvv86TT.mjs +123 -0
  253. package/dist/verification-Cvvv86TT.mjs.map +1 -0
  254. package/fixtures/client-ip-resolution.n01.json +101 -0
  255. package/fixtures/kya-http/error-codes.json +2 -1
  256. package/fixtures/reviewer-grant-revocation.v1.json +53 -81
  257. package/package.json +55 -4
  258. package/dist/client-ip-B2Xeo-GK.mjs.map +0 -1
  259. package/dist/client-ip-DFamiNoz.d.mts +0 -34
  260. package/dist/client-ip-DFamiNoz.d.mts.map +0 -1
  261. package/dist/client-ip-DFamiNoz.d.ts +0 -34
  262. package/dist/client-ip-DFamiNoz.d.ts.map +0 -1
  263. package/dist/index-B7rTovHa.d.mts.map +0 -1
  264. package/dist/index-HaqfPtaL.d.ts.map +0 -1
  265. package/dist/kya-http-error-codes-7ewV5RuK.d.mts.map +0 -1
  266. package/dist/kya-http-error-codes-7ewV5RuK.d.ts.map +0 -1
  267. package/dist/kya-http-error-codes-C2JiWPsi.mjs.map +0 -1
  268. package/dist/posture-origins-Ba83O0cD.mjs.map +0 -1
  269. package/dist/registered-sid-D3g-gZQF.d.mts +0 -11
  270. package/dist/registered-sid-D3g-gZQF.d.mts.map +0 -1
  271. package/dist/registered-sid-D3g-gZQF.d.ts +0 -11
  272. package/dist/registered-sid-D3g-gZQF.d.ts.map +0 -1
  273. package/dist/registered-sid-hUl-bvM5.mjs.map +0 -1
  274. package/dist/schemas-7qodsG-Z.mjs.map +0 -1
  275. package/dist/step-up-BjP--hG-.d.mts.map +0 -1
  276. package/dist/step-up-BjP--hG-.d.ts.map +0 -1
  277. package/dist/step-up-COlmWJN8.mjs.map +0 -1
@@ -0,0 +1,277 @@
1
+ const require_verification = require('./verification-BAw9N8Pt.js');
2
+
3
+ //#region src/core/detection-reason-codes.ts
4
+ /**
5
+ * Detection reason code registry — machine-readable "why" behind a
6
+ * `kya-confidence` verdict (companion to the `kya-http-error-codes.ts` /
7
+ * `bespoke-policy.ts` registries; same `as const satisfies` + namespaced
8
+ * string-literal convention).
9
+ *
10
+ * The engine already emits everything needed to derive these in structured
11
+ * form — `DetectionSignalDetail[]` (`signal_type` / `source`),
12
+ * `detection_class`, `verification_method`, and the AI-crawler flag (see
13
+ * `rust/crates/kya-os-engine/src/types.rs` + `api.rs`) — but until now the
14
+ * only wire-level "why" was `reasons[]`, free English prose, and only ever
15
+ * on a block/claim-rejection response. Downstream dashboards, alerts, and
16
+ * customer integrations were left string-matching that prose (see
17
+ * `apps/web/app/api/v1/pixel/route.ts` `validateDetectionResult`,
18
+ * `detection-cache.service.ts`, and `agent-classification.service.ts` for
19
+ * three live examples of exactly that pattern).
20
+ *
21
+ * `detection/*` codes are a PROJECTION of the engine's own fields: see
22
+ * `mapDetectionToReasonCodes` in the sibling `detection-reason-mapping.ts`,
23
+ * the single place that turns a detection's structured facts into an
24
+ * ordered list of these codes (consumed by the gateway worker via
25
+ * `apps/web/workers/gateway/src/detection/reason-codes.ts` and by the
26
+ * `/api/v1/enforce` signal exposure, KYA-1107). This registry never
27
+ * changes a verdict; it only labels one that already happened.
28
+ *
29
+ * The golden fixture `packages/checkpoint-shared/fixtures/detection/reason-codes.json`
30
+ * is the source of truth; the parity test in
31
+ * `__tests__/detection-reason-codes.test.ts` asserts this map is byte-exact
32
+ * against it (no drift, no omissions) — same guard shape as
33
+ * `kya-http-error-codes.test.ts`.
34
+ *
35
+ * `as const satisfies Record<string, \`detection/${string}\`>` keeps the
36
+ * narrow literal value types (autocomplete + a compile error on a typo'd
37
+ * code) while proving every value is a well-formed `detection/…` string.
38
+ */
39
+ const DETECTION_REASON_CODES = {
40
+ /** `verificationMethod === 'kya-http'`: a kya-http/RFC 9421 signature verified. */
41
+ SIGNATURE_VERIFIED: "detection/signature-verified",
42
+ /** `verificationMethod === 'kya-http-delegated'`: a verified delegation credential rode the request. */
43
+ DELEGATION_VERIFIED: "detection/delegation-verified",
44
+ /** `verificationMethod === 'mcp-i' | 'kya-os'` (the wire values; `isKyaOsWireMethod`): the MCP-I/KYA-OS handshake verified. */
45
+ MCP_I_VERIFIED: "detection/mcp-i-verified",
46
+ /** `verificationMethod === 'did'`: the retired `KYA-Agent-DID` header scheme verified a signature. Historical records only; the gateway no longer emits it. */
47
+ DID_SIGNATURE_VERIFIED: "detection/did-signature-verified",
48
+ /** `verificationMethod === 'signature'`: the worker's RFC 9421 signature verifier (ChatGPT et al.) verified against the DB-refreshed key directory. */
49
+ RFC9421_SIGNATURE_VERIFIED: "detection/rfc9421-signature-verified",
50
+ /** `verificationMethod` starts with `tier1_` (e.g. `tier1_rfc9421`): the engine's Tier-1 protocol attribution verified. */
51
+ TIER1_ATTRIBUTION_VERIFIED: "detection/tier1-attribution-verified",
52
+ /** `verificationMethod === 'a2a'`: an A2A Agent Card's declared security scheme (RFC 9421 keyid, or a JWT bearer against resolved JWKS) cryptographically verified. */
53
+ A2A_VERIFIED: "detection/a2a-verified",
54
+ /** `verificationMethod === 'error'`: a presented credential was demoted/rejected during verification; see the sibling `kyaErrorCode`. */
55
+ VERIFICATION_ERROR: "detection/verification-error",
56
+ /** A `signals[]` entry with `source === 'user_agent_pattern'`: the User-Agent matched a known pattern. */
57
+ UA_PATTERN_MATCH: "detection/ua-pattern-match",
58
+ /** `source === 'header_heuristic'`: a header shape/combination heuristic matched. */
59
+ HEADER_HEURISTIC: "detection/header-heuristic",
60
+ /** `source === 'ip_heuristic'`: an IP-based heuristic matched. */
61
+ IP_HEURISTIC: "detection/ip-heuristic",
62
+ /** `source === 'vendor_ip_feed'`: the request IP matched a known vendor's published IP range. */
63
+ VENDOR_IP_CORROBORATED: "detection/vendor-ip-corroborated",
64
+ /** `source === 'ip_intelligence'`: the host's IP-intelligence provider flagged the request's true IP as a proxy/VPN/Tor/anonymization exit. */
65
+ IP_INTELLIGENCE_PROXY_SIGNAL: "detection/ip-intelligence-proxy-signal",
66
+ /** `source === 'transport.ja4'`: a TLS JA4 fingerprint was observed at the terminating proxy (emit-only observation marker; it matches no list). */
67
+ JA4_FINGERPRINT_MATCH: "detection/ja4-fingerprint-match",
68
+ /** `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. */
69
+ CLIENT_INTEGRITY_FAILURE: "detection/client-integrity-failure",
70
+ /** `source === 'ua_tls_mismatch'`: the User-Agent claims a browser but the JA4 cipher-list hash (JA4_b) belongs to known non-browser tooling. */
71
+ UA_TLS_MISMATCH: "detection/ua-tls-mismatch",
72
+ /** `source === 'client.attributes'`: a pixel/beacon-reported client attribute contributed. */
73
+ CLIENT_ATTRIBUTE_SIGNAL: "detection/client-attribute-signal",
74
+ /** `source === 'behavioural.interaction'`: a behavioral/interaction signal contributed. */
75
+ BEHAVIORAL_SIGNAL: "detection/behavioral-signal",
76
+ /** `source === 'mcp_i'`: an MCP-I header was present (evidence short of a completed handshake). */
77
+ MCP_I_SIGNAL: "detection/mcp-i-signal",
78
+ /** `source === 'kya_http_binding'`: a kya-http binding was presented (evidence short of full verification). */
79
+ KYA_HTTP_BINDING_SIGNAL: "detection/kya-http-binding-signal",
80
+ /** `source === 'kya_delegation_bearer'`: a delegation bearer credential was presented. */
81
+ KYA_DELEGATION_BEARER_SIGNAL: "detection/kya-delegation-bearer-signal",
82
+ /** A `signals[]` entry with `source === 'a2a_agent_card'`: an A2A Agent Card was presented (evidence short of, or alongside, full verification). */
83
+ A2A_CARD_SIGNAL: "detection/a2a-card-signal",
84
+ /** `source === 'scanner_misclassification_hint'`: Cloudflare's bot score contradicted a zero-evidence Human verdict, overriding it to Unknown. */
85
+ SCANNER_MISCLASSIFICATION_HINT_SIGNAL: "detection/scanner-misclassification-hint-signal",
86
+ /** `source === 'client_headless_escalation'`: the beacon disclosed `navigator.webdriver`, or reported corroborating automation evidence (CDP/plugin/WebGL consistency, a distinctive property), escalating the classification. */
87
+ CLIENT_HEADLESS_ESCALATION_SIGNAL: "detection/client-headless-escalation-signal",
88
+ /** `source === 'transport.cloudflare_bot_management'`: Cloudflare's bot-management score or verified-bot determination contributed. */
89
+ CLOUDFLARE_BOT_MANAGEMENT_SIGNAL: "detection/cloudflare-bot-management-signal",
90
+ /** `source === 'session_velocity'`: the edge-computed request-velocity heuristic contributed. */
91
+ SESSION_VELOCITY_SIGNAL: "detection/session-velocity-signal",
92
+ /** A `signals[]` entry whose `source` starts with `tier1_`: raw Tier-1 protocol evidence, short of (or alongside) full verification. */
93
+ TIER1_ATTRIBUTION_SIGNAL: "detection/tier1-attribution-signal",
94
+ /** `isAiCrawler === true`: classified as an AI training crawler (GPTBot, ClaudeBot, etc.), not an interactive agent. */
95
+ AI_CRAWLER_FLAG: "detection/ai-crawler-flag",
96
+ /** `detectionClass === 'human'` with no contributing signals and no verification: the baseline "nothing matched" human path. */
97
+ ZERO_EVIDENCE_HUMAN: "detection/zero-evidence-human",
98
+ /** `detectionClass === 'incomplete_data' | 'unknown'` (or absent): the engine could not classify confidently. */
99
+ INCOMPLETE_DATA_OVERRIDE: "detection/incomplete-data-override",
100
+ /** 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. */
101
+ CLASSIFIED_WITHOUT_SIGNAL_EVIDENCE: "detection/classified-without-signal-evidence"
102
+ };
103
+
104
+ //#endregion
105
+ //#region src/core/detection-reason-mapping.ts
106
+ /**
107
+ * Detection reason-code mapping: the single pure projection of a
108
+ * detection's structured facts onto the `DETECTION_REASON_CODES` registry
109
+ * (#4874).
110
+ *
111
+ * The engine already emits structured evidence (`signals[]` with a typed
112
+ * `source`, `verificationMethod`, `detectionClass`, `isAiCrawler`) but the
113
+ * only wire-level "why" used to be `reasons[]`, free English prose. This
114
+ * module turns that structured evidence into an ordered list of stable,
115
+ * namespaced codes, most-significant-evidence first.
116
+ *
117
+ * Consumers (all invoke this SAME pure function, so their codes can never
118
+ * diverge):
119
+ * - the gateway worker's `addDetectionHeaders` (`KYA-Reason-Codes` on
120
+ * EVERY proxied response, including allow) and `log-detection.ts`
121
+ * (persisted alongside the detection row), both via the re-export in
122
+ * `apps/web/workers/gateway/src/detection/reason-codes.ts`;
123
+ * - the `/api/v1/enforce` response's signal exposure
124
+ * (KYA-1107) via `apps/web/lib/detection/signal-exposure.ts`.
125
+ *
126
+ * This module NEVER changes a verdict; it only labels one that already
127
+ * happened (same non-negotiable as the registry doc comment).
128
+ */
129
+ /**
130
+ * `verificationMethod` → the single strongest code it proves. Keys are the
131
+ * WIRE value space; the KYA-OS handshake/delegation alias pairs are handled
132
+ * as explicit branches in `mapDetectionToReasonCodes` via the shared
133
+ * `isKyaOs*Method` predicates (the SSOT for those alias pairs; Bugbot on
134
+ * PR #4874 caught this table keyed on engine values instead, silently
135
+ * missing every verified MCP-I/KYA-OS handshake) rather than hardcoding the
136
+ * alias strings a second time in this map.
137
+ */
138
+ const VERIFICATION_METHOD_CODES = {
139
+ "kya-http-delegated": DETECTION_REASON_CODES.DELEGATION_VERIFIED,
140
+ "kya-http": DETECTION_REASON_CODES.SIGNATURE_VERIFIED,
141
+ did: DETECTION_REASON_CODES.DID_SIGNATURE_VERIFIED,
142
+ signature: DETECTION_REASON_CODES.RFC9421_SIGNATURE_VERIFIED,
143
+ a2a: DETECTION_REASON_CODES.A2A_VERIFIED,
144
+ error: DETECTION_REASON_CODES.VERIFICATION_ERROR
145
+ };
146
+ /**
147
+ * A `signals[].source` value → the code naming that raw evidence.
148
+ *
149
+ * Declaration order IS the consideration order `mapDetectionToReasonCodes`
150
+ * iterates (object key insertion order is guaranteed for string keys), NOT
151
+ * the raw `signals[]` array order, which the engine assembles differently
152
+ * per detection path (mirrors `buildVerdictEvidence`'s own doc comment on
153
+ * the same nondeterminism). Roughly the engine's own construction order in
154
+ * `api.rs` (identity/delegation evidence before UA/IP heuristics). Keeping
155
+ * one map (rather than a map plus a separate priority-order array) means a
156
+ * new signal source is added in exactly one place.
157
+ */
158
+ const SIGNAL_SOURCE_CODES = {
159
+ mcp_i: DETECTION_REASON_CODES.MCP_I_SIGNAL,
160
+ kya_http_binding: DETECTION_REASON_CODES.KYA_HTTP_BINDING_SIGNAL,
161
+ kya_delegation_bearer: DETECTION_REASON_CODES.KYA_DELEGATION_BEARER_SIGNAL,
162
+ a2a_agent_card: DETECTION_REASON_CODES.A2A_CARD_SIGNAL,
163
+ user_agent_pattern: DETECTION_REASON_CODES.UA_PATTERN_MATCH,
164
+ ua_tls_mismatch: DETECTION_REASON_CODES.UA_TLS_MISMATCH,
165
+ header_heuristic: DETECTION_REASON_CODES.HEADER_HEURISTIC,
166
+ ip_heuristic: DETECTION_REASON_CODES.IP_HEURISTIC,
167
+ scanner_misclassification_hint: DETECTION_REASON_CODES.SCANNER_MISCLASSIFICATION_HINT_SIGNAL,
168
+ client_headless_escalation: DETECTION_REASON_CODES.CLIENT_HEADLESS_ESCALATION_SIGNAL,
169
+ vendor_ip_feed: DETECTION_REASON_CODES.VENDOR_IP_CORROBORATED,
170
+ ip_intelligence: DETECTION_REASON_CODES.IP_INTELLIGENCE_PROXY_SIGNAL,
171
+ "transport.ja4": DETECTION_REASON_CODES.JA4_FINGERPRINT_MATCH,
172
+ "transport.cloudflare_bot_management": DETECTION_REASON_CODES.CLOUDFLARE_BOT_MANAGEMENT_SIGNAL,
173
+ client_integrity: DETECTION_REASON_CODES.CLIENT_INTEGRITY_FAILURE,
174
+ "client.attributes": DETECTION_REASON_CODES.CLIENT_ATTRIBUTE_SIGNAL,
175
+ "behavioural.interaction": DETECTION_REASON_CODES.BEHAVIORAL_SIGNAL,
176
+ session_velocity: DETECTION_REASON_CODES.SESSION_VELOCITY_SIGNAL
177
+ };
178
+ /**
179
+ * Maps a detection's structured facts to an ordered, deduplicated list of
180
+ * `detection/*` reason codes, most-significant-evidence first:
181
+ *
182
+ * 1. Verification-method-derived (cryptographic proof, strongest).
183
+ * 2. Signal-source-derived (raw structured evidence), one code per
184
+ * distinct source actually present, deduplicated.
185
+ * 3. The AI-crawler classification flag.
186
+ * 4. A zero-evidence fallback, ONLY when nothing above matched, so this
187
+ * function never returns an empty list. An assumed verdict (e.g. the
188
+ * baseline "no known agent indicators matched" human path) deserves a
189
+ * code saying so, in the spirit of #4800, rather than silence.
190
+ *
191
+ * Pure: no I/O, no mutation of `detail`.
192
+ */
193
+ function mapDetectionToReasonCodes(detail) {
194
+ const codes = [];
195
+ const seen = /* @__PURE__ */ new Set();
196
+ const push = (code) => {
197
+ if (code && !seen.has(code)) {
198
+ seen.add(code);
199
+ codes.push(code);
200
+ }
201
+ };
202
+ const verificationMethod = detail.verificationMethod;
203
+ if (verificationMethod) {
204
+ if (verificationMethod.startsWith("tier1_")) push(DETECTION_REASON_CODES.TIER1_ATTRIBUTION_VERIFIED);
205
+ else if (require_verification.isKyaOsWireMethod(verificationMethod) || require_verification.isKyaOsHandshakeMethod(verificationMethod)) push(DETECTION_REASON_CODES.MCP_I_VERIFIED);
206
+ else push(VERIFICATION_METHOD_CODES[verificationMethod]);
207
+ }
208
+ const presentSources = /* @__PURE__ */ new Set();
209
+ let hasTier1Signal = false;
210
+ for (const signal of detail.signals ?? []) {
211
+ presentSources.add(signal.source);
212
+ if (signal.source.startsWith("tier1_")) hasTier1Signal = true;
213
+ }
214
+ for (const source of Object.keys(SIGNAL_SOURCE_CODES)) if (presentSources.has(source)) push(SIGNAL_SOURCE_CODES[source]);
215
+ if (hasTier1Signal) push(DETECTION_REASON_CODES.TIER1_ATTRIBUTION_SIGNAL);
216
+ if (detail.isAiCrawler) push(DETECTION_REASON_CODES.AI_CRAWLER_FLAG);
217
+ if (codes.length === 0) {
218
+ if (detail.detectionClass === "human") push(DETECTION_REASON_CODES.ZERO_EVIDENCE_HUMAN);
219
+ else if (detail.detectionClass === "incomplete_data" || detail.detectionClass === "unknown" || !detail.detectionClass) push(DETECTION_REASON_CODES.INCOMPLETE_DATA_OVERRIDE);
220
+ else push(DETECTION_REASON_CODES.CLASSIFIED_WITHOUT_SIGNAL_EVIDENCE);
221
+ }
222
+ return codes;
223
+ }
224
+ /** Wire cap: at most this many codes on the `KYA-Reason-Codes` header. */
225
+ const MAX_REASON_CODES_ON_WIRE = 5;
226
+ /** Wire cap: the header's serialized UTF-8 byte budget. */
227
+ const MAX_REASON_CODES_HEADER_BYTES = 256;
228
+ const HEADER_BYTES_ENCODER = new TextEncoder();
229
+ /**
230
+ * Formats an ordered reason-code list into the `KYA-Reason-Codes` header
231
+ * value: comma-separated, capped at {@link MAX_REASON_CODES_ON_WIRE} codes,
232
+ * then trimmed from the end (never mid-string) until the UTF-8 byte length
233
+ * fits {@link MAX_REASON_CODES_HEADER_BYTES}. `codes` is assumed already
234
+ * ordered most-significant-first (mapDetectionToReasonCodes's contract);
235
+ * this function only truncates, it never reorders.
236
+ */
237
+ function formatReasonCodesHeader(codes) {
238
+ const capped = codes.slice(0, 5);
239
+ while (capped.length > 0) {
240
+ const joined = capped.join(",");
241
+ if (HEADER_BYTES_ENCODER.encode(joined).byteLength <= 256) return joined;
242
+ capped.pop();
243
+ }
244
+ return "";
245
+ }
246
+
247
+ //#endregion
248
+ Object.defineProperty(exports, 'DETECTION_REASON_CODES', {
249
+ enumerable: true,
250
+ get: function () {
251
+ return DETECTION_REASON_CODES;
252
+ }
253
+ });
254
+ Object.defineProperty(exports, 'MAX_REASON_CODES_HEADER_BYTES', {
255
+ enumerable: true,
256
+ get: function () {
257
+ return MAX_REASON_CODES_HEADER_BYTES;
258
+ }
259
+ });
260
+ Object.defineProperty(exports, 'MAX_REASON_CODES_ON_WIRE', {
261
+ enumerable: true,
262
+ get: function () {
263
+ return MAX_REASON_CODES_ON_WIRE;
264
+ }
265
+ });
266
+ Object.defineProperty(exports, 'formatReasonCodesHeader', {
267
+ enumerable: true,
268
+ get: function () {
269
+ return formatReasonCodesHeader;
270
+ }
271
+ });
272
+ Object.defineProperty(exports, 'mapDetectionToReasonCodes', {
273
+ enumerable: true,
274
+ get: function () {
275
+ return mapDetectionToReasonCodes;
276
+ }
277
+ });
@@ -0,0 +1,249 @@
1
+ import { c as isKyaOsWireMethod, s as isKyaOsHandshakeMethod } from "./verification-Cvvv86TT.mjs";
2
+
3
+ //#region src/core/detection-reason-codes.ts
4
+ /**
5
+ * Detection reason code registry — machine-readable "why" behind a
6
+ * `kya-confidence` verdict (companion to the `kya-http-error-codes.ts` /
7
+ * `bespoke-policy.ts` registries; same `as const satisfies` + namespaced
8
+ * string-literal convention).
9
+ *
10
+ * The engine already emits everything needed to derive these in structured
11
+ * form — `DetectionSignalDetail[]` (`signal_type` / `source`),
12
+ * `detection_class`, `verification_method`, and the AI-crawler flag (see
13
+ * `rust/crates/kya-os-engine/src/types.rs` + `api.rs`) — but until now the
14
+ * only wire-level "why" was `reasons[]`, free English prose, and only ever
15
+ * on a block/claim-rejection response. Downstream dashboards, alerts, and
16
+ * customer integrations were left string-matching that prose (see
17
+ * `apps/web/app/api/v1/pixel/route.ts` `validateDetectionResult`,
18
+ * `detection-cache.service.ts`, and `agent-classification.service.ts` for
19
+ * three live examples of exactly that pattern).
20
+ *
21
+ * `detection/*` codes are a PROJECTION of the engine's own fields: see
22
+ * `mapDetectionToReasonCodes` in the sibling `detection-reason-mapping.ts`,
23
+ * the single place that turns a detection's structured facts into an
24
+ * ordered list of these codes (consumed by the gateway worker via
25
+ * `apps/web/workers/gateway/src/detection/reason-codes.ts` and by the
26
+ * `/api/v1/enforce` signal exposure, KYA-1107). This registry never
27
+ * changes a verdict; it only labels one that already happened.
28
+ *
29
+ * The golden fixture `packages/checkpoint-shared/fixtures/detection/reason-codes.json`
30
+ * is the source of truth; the parity test in
31
+ * `__tests__/detection-reason-codes.test.ts` asserts this map is byte-exact
32
+ * against it (no drift, no omissions) — same guard shape as
33
+ * `kya-http-error-codes.test.ts`.
34
+ *
35
+ * `as const satisfies Record<string, \`detection/${string}\`>` keeps the
36
+ * narrow literal value types (autocomplete + a compile error on a typo'd
37
+ * code) while proving every value is a well-formed `detection/…` string.
38
+ */
39
+ const DETECTION_REASON_CODES = {
40
+ /** `verificationMethod === 'kya-http'`: a kya-http/RFC 9421 signature verified. */
41
+ SIGNATURE_VERIFIED: "detection/signature-verified",
42
+ /** `verificationMethod === 'kya-http-delegated'`: a verified delegation credential rode the request. */
43
+ DELEGATION_VERIFIED: "detection/delegation-verified",
44
+ /** `verificationMethod === 'mcp-i' | 'kya-os'` (the wire values; `isKyaOsWireMethod`): the MCP-I/KYA-OS handshake verified. */
45
+ MCP_I_VERIFIED: "detection/mcp-i-verified",
46
+ /** `verificationMethod === 'did'`: the retired `KYA-Agent-DID` header scheme verified a signature. Historical records only; the gateway no longer emits it. */
47
+ DID_SIGNATURE_VERIFIED: "detection/did-signature-verified",
48
+ /** `verificationMethod === 'signature'`: the worker's RFC 9421 signature verifier (ChatGPT et al.) verified against the DB-refreshed key directory. */
49
+ RFC9421_SIGNATURE_VERIFIED: "detection/rfc9421-signature-verified",
50
+ /** `verificationMethod` starts with `tier1_` (e.g. `tier1_rfc9421`): the engine's Tier-1 protocol attribution verified. */
51
+ TIER1_ATTRIBUTION_VERIFIED: "detection/tier1-attribution-verified",
52
+ /** `verificationMethod === 'a2a'`: an A2A Agent Card's declared security scheme (RFC 9421 keyid, or a JWT bearer against resolved JWKS) cryptographically verified. */
53
+ A2A_VERIFIED: "detection/a2a-verified",
54
+ /** `verificationMethod === 'error'`: a presented credential was demoted/rejected during verification; see the sibling `kyaErrorCode`. */
55
+ VERIFICATION_ERROR: "detection/verification-error",
56
+ /** A `signals[]` entry with `source === 'user_agent_pattern'`: the User-Agent matched a known pattern. */
57
+ UA_PATTERN_MATCH: "detection/ua-pattern-match",
58
+ /** `source === 'header_heuristic'`: a header shape/combination heuristic matched. */
59
+ HEADER_HEURISTIC: "detection/header-heuristic",
60
+ /** `source === 'ip_heuristic'`: an IP-based heuristic matched. */
61
+ IP_HEURISTIC: "detection/ip-heuristic",
62
+ /** `source === 'vendor_ip_feed'`: the request IP matched a known vendor's published IP range. */
63
+ VENDOR_IP_CORROBORATED: "detection/vendor-ip-corroborated",
64
+ /** `source === 'ip_intelligence'`: the host's IP-intelligence provider flagged the request's true IP as a proxy/VPN/Tor/anonymization exit. */
65
+ IP_INTELLIGENCE_PROXY_SIGNAL: "detection/ip-intelligence-proxy-signal",
66
+ /** `source === 'transport.ja4'`: a TLS JA4 fingerprint was observed at the terminating proxy (emit-only observation marker; it matches no list). */
67
+ JA4_FINGERPRINT_MATCH: "detection/ja4-fingerprint-match",
68
+ /** `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. */
69
+ CLIENT_INTEGRITY_FAILURE: "detection/client-integrity-failure",
70
+ /** `source === 'ua_tls_mismatch'`: the User-Agent claims a browser but the JA4 cipher-list hash (JA4_b) belongs to known non-browser tooling. */
71
+ UA_TLS_MISMATCH: "detection/ua-tls-mismatch",
72
+ /** `source === 'client.attributes'`: a pixel/beacon-reported client attribute contributed. */
73
+ CLIENT_ATTRIBUTE_SIGNAL: "detection/client-attribute-signal",
74
+ /** `source === 'behavioural.interaction'`: a behavioral/interaction signal contributed. */
75
+ BEHAVIORAL_SIGNAL: "detection/behavioral-signal",
76
+ /** `source === 'mcp_i'`: an MCP-I header was present (evidence short of a completed handshake). */
77
+ MCP_I_SIGNAL: "detection/mcp-i-signal",
78
+ /** `source === 'kya_http_binding'`: a kya-http binding was presented (evidence short of full verification). */
79
+ KYA_HTTP_BINDING_SIGNAL: "detection/kya-http-binding-signal",
80
+ /** `source === 'kya_delegation_bearer'`: a delegation bearer credential was presented. */
81
+ KYA_DELEGATION_BEARER_SIGNAL: "detection/kya-delegation-bearer-signal",
82
+ /** A `signals[]` entry with `source === 'a2a_agent_card'`: an A2A Agent Card was presented (evidence short of, or alongside, full verification). */
83
+ A2A_CARD_SIGNAL: "detection/a2a-card-signal",
84
+ /** `source === 'scanner_misclassification_hint'`: Cloudflare's bot score contradicted a zero-evidence Human verdict, overriding it to Unknown. */
85
+ SCANNER_MISCLASSIFICATION_HINT_SIGNAL: "detection/scanner-misclassification-hint-signal",
86
+ /** `source === 'client_headless_escalation'`: the beacon disclosed `navigator.webdriver`, or reported corroborating automation evidence (CDP/plugin/WebGL consistency, a distinctive property), escalating the classification. */
87
+ CLIENT_HEADLESS_ESCALATION_SIGNAL: "detection/client-headless-escalation-signal",
88
+ /** `source === 'transport.cloudflare_bot_management'`: Cloudflare's bot-management score or verified-bot determination contributed. */
89
+ CLOUDFLARE_BOT_MANAGEMENT_SIGNAL: "detection/cloudflare-bot-management-signal",
90
+ /** `source === 'session_velocity'`: the edge-computed request-velocity heuristic contributed. */
91
+ SESSION_VELOCITY_SIGNAL: "detection/session-velocity-signal",
92
+ /** A `signals[]` entry whose `source` starts with `tier1_`: raw Tier-1 protocol evidence, short of (or alongside) full verification. */
93
+ TIER1_ATTRIBUTION_SIGNAL: "detection/tier1-attribution-signal",
94
+ /** `isAiCrawler === true`: classified as an AI training crawler (GPTBot, ClaudeBot, etc.), not an interactive agent. */
95
+ AI_CRAWLER_FLAG: "detection/ai-crawler-flag",
96
+ /** `detectionClass === 'human'` with no contributing signals and no verification: the baseline "nothing matched" human path. */
97
+ ZERO_EVIDENCE_HUMAN: "detection/zero-evidence-human",
98
+ /** `detectionClass === 'incomplete_data' | 'unknown'` (or absent): the engine could not classify confidently. */
99
+ INCOMPLETE_DATA_OVERRIDE: "detection/incomplete-data-override",
100
+ /** 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. */
101
+ CLASSIFIED_WITHOUT_SIGNAL_EVIDENCE: "detection/classified-without-signal-evidence"
102
+ };
103
+
104
+ //#endregion
105
+ //#region src/core/detection-reason-mapping.ts
106
+ /**
107
+ * Detection reason-code mapping: the single pure projection of a
108
+ * detection's structured facts onto the `DETECTION_REASON_CODES` registry
109
+ * (#4874).
110
+ *
111
+ * The engine already emits structured evidence (`signals[]` with a typed
112
+ * `source`, `verificationMethod`, `detectionClass`, `isAiCrawler`) but the
113
+ * only wire-level "why" used to be `reasons[]`, free English prose. This
114
+ * module turns that structured evidence into an ordered list of stable,
115
+ * namespaced codes, most-significant-evidence first.
116
+ *
117
+ * Consumers (all invoke this SAME pure function, so their codes can never
118
+ * diverge):
119
+ * - the gateway worker's `addDetectionHeaders` (`KYA-Reason-Codes` on
120
+ * EVERY proxied response, including allow) and `log-detection.ts`
121
+ * (persisted alongside the detection row), both via the re-export in
122
+ * `apps/web/workers/gateway/src/detection/reason-codes.ts`;
123
+ * - the `/api/v1/enforce` response's signal exposure
124
+ * (KYA-1107) via `apps/web/lib/detection/signal-exposure.ts`.
125
+ *
126
+ * This module NEVER changes a verdict; it only labels one that already
127
+ * happened (same non-negotiable as the registry doc comment).
128
+ */
129
+ /**
130
+ * `verificationMethod` → the single strongest code it proves. Keys are the
131
+ * WIRE value space; the KYA-OS handshake/delegation alias pairs are handled
132
+ * as explicit branches in `mapDetectionToReasonCodes` via the shared
133
+ * `isKyaOs*Method` predicates (the SSOT for those alias pairs; Bugbot on
134
+ * PR #4874 caught this table keyed on engine values instead, silently
135
+ * missing every verified MCP-I/KYA-OS handshake) rather than hardcoding the
136
+ * alias strings a second time in this map.
137
+ */
138
+ const VERIFICATION_METHOD_CODES = {
139
+ "kya-http-delegated": DETECTION_REASON_CODES.DELEGATION_VERIFIED,
140
+ "kya-http": DETECTION_REASON_CODES.SIGNATURE_VERIFIED,
141
+ did: DETECTION_REASON_CODES.DID_SIGNATURE_VERIFIED,
142
+ signature: DETECTION_REASON_CODES.RFC9421_SIGNATURE_VERIFIED,
143
+ a2a: DETECTION_REASON_CODES.A2A_VERIFIED,
144
+ error: DETECTION_REASON_CODES.VERIFICATION_ERROR
145
+ };
146
+ /**
147
+ * A `signals[].source` value → the code naming that raw evidence.
148
+ *
149
+ * Declaration order IS the consideration order `mapDetectionToReasonCodes`
150
+ * iterates (object key insertion order is guaranteed for string keys), NOT
151
+ * the raw `signals[]` array order, which the engine assembles differently
152
+ * per detection path (mirrors `buildVerdictEvidence`'s own doc comment on
153
+ * the same nondeterminism). Roughly the engine's own construction order in
154
+ * `api.rs` (identity/delegation evidence before UA/IP heuristics). Keeping
155
+ * one map (rather than a map plus a separate priority-order array) means a
156
+ * new signal source is added in exactly one place.
157
+ */
158
+ const SIGNAL_SOURCE_CODES = {
159
+ mcp_i: DETECTION_REASON_CODES.MCP_I_SIGNAL,
160
+ kya_http_binding: DETECTION_REASON_CODES.KYA_HTTP_BINDING_SIGNAL,
161
+ kya_delegation_bearer: DETECTION_REASON_CODES.KYA_DELEGATION_BEARER_SIGNAL,
162
+ a2a_agent_card: DETECTION_REASON_CODES.A2A_CARD_SIGNAL,
163
+ user_agent_pattern: DETECTION_REASON_CODES.UA_PATTERN_MATCH,
164
+ ua_tls_mismatch: DETECTION_REASON_CODES.UA_TLS_MISMATCH,
165
+ header_heuristic: DETECTION_REASON_CODES.HEADER_HEURISTIC,
166
+ ip_heuristic: DETECTION_REASON_CODES.IP_HEURISTIC,
167
+ scanner_misclassification_hint: DETECTION_REASON_CODES.SCANNER_MISCLASSIFICATION_HINT_SIGNAL,
168
+ client_headless_escalation: DETECTION_REASON_CODES.CLIENT_HEADLESS_ESCALATION_SIGNAL,
169
+ vendor_ip_feed: DETECTION_REASON_CODES.VENDOR_IP_CORROBORATED,
170
+ ip_intelligence: DETECTION_REASON_CODES.IP_INTELLIGENCE_PROXY_SIGNAL,
171
+ "transport.ja4": DETECTION_REASON_CODES.JA4_FINGERPRINT_MATCH,
172
+ "transport.cloudflare_bot_management": DETECTION_REASON_CODES.CLOUDFLARE_BOT_MANAGEMENT_SIGNAL,
173
+ client_integrity: DETECTION_REASON_CODES.CLIENT_INTEGRITY_FAILURE,
174
+ "client.attributes": DETECTION_REASON_CODES.CLIENT_ATTRIBUTE_SIGNAL,
175
+ "behavioural.interaction": DETECTION_REASON_CODES.BEHAVIORAL_SIGNAL,
176
+ session_velocity: DETECTION_REASON_CODES.SESSION_VELOCITY_SIGNAL
177
+ };
178
+ /**
179
+ * Maps a detection's structured facts to an ordered, deduplicated list of
180
+ * `detection/*` reason codes, most-significant-evidence first:
181
+ *
182
+ * 1. Verification-method-derived (cryptographic proof, strongest).
183
+ * 2. Signal-source-derived (raw structured evidence), one code per
184
+ * distinct source actually present, deduplicated.
185
+ * 3. The AI-crawler classification flag.
186
+ * 4. A zero-evidence fallback, ONLY when nothing above matched, so this
187
+ * function never returns an empty list. An assumed verdict (e.g. the
188
+ * baseline "no known agent indicators matched" human path) deserves a
189
+ * code saying so, in the spirit of #4800, rather than silence.
190
+ *
191
+ * Pure: no I/O, no mutation of `detail`.
192
+ */
193
+ function mapDetectionToReasonCodes(detail) {
194
+ const codes = [];
195
+ const seen = /* @__PURE__ */ new Set();
196
+ const push = (code) => {
197
+ if (code && !seen.has(code)) {
198
+ seen.add(code);
199
+ codes.push(code);
200
+ }
201
+ };
202
+ const verificationMethod = detail.verificationMethod;
203
+ if (verificationMethod) {
204
+ if (verificationMethod.startsWith("tier1_")) push(DETECTION_REASON_CODES.TIER1_ATTRIBUTION_VERIFIED);
205
+ else if (isKyaOsWireMethod(verificationMethod) || isKyaOsHandshakeMethod(verificationMethod)) push(DETECTION_REASON_CODES.MCP_I_VERIFIED);
206
+ else push(VERIFICATION_METHOD_CODES[verificationMethod]);
207
+ }
208
+ const presentSources = /* @__PURE__ */ new Set();
209
+ let hasTier1Signal = false;
210
+ for (const signal of detail.signals ?? []) {
211
+ presentSources.add(signal.source);
212
+ if (signal.source.startsWith("tier1_")) hasTier1Signal = true;
213
+ }
214
+ for (const source of Object.keys(SIGNAL_SOURCE_CODES)) if (presentSources.has(source)) push(SIGNAL_SOURCE_CODES[source]);
215
+ if (hasTier1Signal) push(DETECTION_REASON_CODES.TIER1_ATTRIBUTION_SIGNAL);
216
+ if (detail.isAiCrawler) push(DETECTION_REASON_CODES.AI_CRAWLER_FLAG);
217
+ if (codes.length === 0) {
218
+ if (detail.detectionClass === "human") push(DETECTION_REASON_CODES.ZERO_EVIDENCE_HUMAN);
219
+ else if (detail.detectionClass === "incomplete_data" || detail.detectionClass === "unknown" || !detail.detectionClass) push(DETECTION_REASON_CODES.INCOMPLETE_DATA_OVERRIDE);
220
+ else push(DETECTION_REASON_CODES.CLASSIFIED_WITHOUT_SIGNAL_EVIDENCE);
221
+ }
222
+ return codes;
223
+ }
224
+ /** Wire cap: at most this many codes on the `KYA-Reason-Codes` header. */
225
+ const MAX_REASON_CODES_ON_WIRE = 5;
226
+ /** Wire cap: the header's serialized UTF-8 byte budget. */
227
+ const MAX_REASON_CODES_HEADER_BYTES = 256;
228
+ const HEADER_BYTES_ENCODER = new TextEncoder();
229
+ /**
230
+ * Formats an ordered reason-code list into the `KYA-Reason-Codes` header
231
+ * value: comma-separated, capped at {@link MAX_REASON_CODES_ON_WIRE} codes,
232
+ * then trimmed from the end (never mid-string) until the UTF-8 byte length
233
+ * fits {@link MAX_REASON_CODES_HEADER_BYTES}. `codes` is assumed already
234
+ * ordered most-significant-first (mapDetectionToReasonCodes's contract);
235
+ * this function only truncates, it never reorders.
236
+ */
237
+ function formatReasonCodesHeader(codes) {
238
+ const capped = codes.slice(0, 5);
239
+ while (capped.length > 0) {
240
+ const joined = capped.join(",");
241
+ if (HEADER_BYTES_ENCODER.encode(joined).byteLength <= 256) return joined;
242
+ capped.pop();
243
+ }
244
+ return "";
245
+ }
246
+
247
+ //#endregion
248
+ export { DETECTION_REASON_CODES as a, mapDetectionToReasonCodes as i, MAX_REASON_CODES_ON_WIRE as n, formatReasonCodesHeader as r, MAX_REASON_CODES_HEADER_BYTES as t };
249
+ //# sourceMappingURL=detection-reason-mapping-BGymWIPl.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"detection-reason-mapping-BGymWIPl.mjs","names":[],"sources":["../src/core/detection-reason-codes.ts","../src/core/detection-reason-mapping.ts"],"sourcesContent":["/**\n * Detection reason code registry — machine-readable \"why\" behind a\n * `kya-confidence` verdict (companion to the `kya-http-error-codes.ts` /\n * `bespoke-policy.ts` registries; same `as const satisfies` + namespaced\n * string-literal convention).\n *\n * The engine already emits everything needed to derive these in structured\n * form — `DetectionSignalDetail[]` (`signal_type` / `source`),\n * `detection_class`, `verification_method`, and the AI-crawler flag (see\n * `rust/crates/kya-os-engine/src/types.rs` + `api.rs`) — but until now the\n * only wire-level \"why\" was `reasons[]`, free English prose, and only ever\n * on a block/claim-rejection response. Downstream dashboards, alerts, and\n * customer integrations were left string-matching that prose (see\n * `apps/web/app/api/v1/pixel/route.ts` `validateDetectionResult`,\n * `detection-cache.service.ts`, and `agent-classification.service.ts` for\n * three live examples of exactly that pattern).\n *\n * `detection/*` codes are a PROJECTION of the engine's own fields: see\n * `mapDetectionToReasonCodes` in the sibling `detection-reason-mapping.ts`,\n * the single place that turns a detection's structured facts into an\n * ordered list of these codes (consumed by the gateway worker via\n * `apps/web/workers/gateway/src/detection/reason-codes.ts` and by the\n * `/api/v1/enforce` signal exposure, KYA-1107). This registry never\n * changes a verdict; it only labels one that already happened.\n *\n * The golden fixture `packages/checkpoint-shared/fixtures/detection/reason-codes.json`\n * is the source of truth; the parity test in\n * `__tests__/detection-reason-codes.test.ts` asserts this map is byte-exact\n * against it (no drift, no omissions) — same guard shape as\n * `kya-http-error-codes.test.ts`.\n *\n * `as const satisfies Record<string, \\`detection/${string}\\`>` keeps the\n * narrow literal value types (autocomplete + a compile error on a typo'd\n * code) while proving every value is a well-formed `detection/…` string.\n */\nexport const DETECTION_REASON_CODES = {\n // ── Cryptographic / verified attribution (strongest evidence, first) ────\n /** `verificationMethod === 'kya-http'`: a kya-http/RFC 9421 signature verified. */\n SIGNATURE_VERIFIED: 'detection/signature-verified',\n /** `verificationMethod === 'kya-http-delegated'`: a verified delegation credential rode the request. */\n DELEGATION_VERIFIED: 'detection/delegation-verified',\n /** `verificationMethod === 'mcp-i' | 'kya-os'` (the wire values; `isKyaOsWireMethod`): the MCP-I/KYA-OS handshake verified. */\n MCP_I_VERIFIED: 'detection/mcp-i-verified',\n /** `verificationMethod === 'did'`: the retired `KYA-Agent-DID` header scheme verified a signature. Historical records only; the gateway no longer emits it. */\n DID_SIGNATURE_VERIFIED: 'detection/did-signature-verified',\n /** `verificationMethod === 'signature'`: the worker's RFC 9421 signature verifier (ChatGPT et al.) verified against the DB-refreshed key directory. */\n RFC9421_SIGNATURE_VERIFIED: 'detection/rfc9421-signature-verified',\n /** `verificationMethod` starts with `tier1_` (e.g. `tier1_rfc9421`): the engine's Tier-1 protocol attribution verified. */\n TIER1_ATTRIBUTION_VERIFIED: 'detection/tier1-attribution-verified',\n /** `verificationMethod === 'a2a'`: an A2A Agent Card's declared security scheme (RFC 9421 keyid, or a JWT bearer against resolved JWKS) cryptographically verified. */\n A2A_VERIFIED: 'detection/a2a-verified',\n /** `verificationMethod === 'error'`: a presented credential was demoted/rejected during verification; see the sibling `kyaErrorCode`. */\n VERIFICATION_ERROR: 'detection/verification-error',\n\n // ── Structured evidence signals (one per distinct `signals[].source`) ───\n /** A `signals[]` entry with `source === 'user_agent_pattern'`: the User-Agent matched a known pattern. */\n UA_PATTERN_MATCH: 'detection/ua-pattern-match',\n /** `source === 'header_heuristic'`: a header shape/combination heuristic matched. */\n HEADER_HEURISTIC: 'detection/header-heuristic',\n /** `source === 'ip_heuristic'`: an IP-based heuristic matched. */\n IP_HEURISTIC: 'detection/ip-heuristic',\n /** `source === 'vendor_ip_feed'`: the request IP matched a known vendor's published IP range. */\n VENDOR_IP_CORROBORATED: 'detection/vendor-ip-corroborated',\n /** `source === 'ip_intelligence'`: the host's IP-intelligence provider flagged the request's true IP as a proxy/VPN/Tor/anonymization exit. */\n IP_INTELLIGENCE_PROXY_SIGNAL: 'detection/ip-intelligence-proxy-signal',\n /** `source === 'transport.ja4'`: a TLS JA4 fingerprint was observed at the terminating proxy (emit-only observation marker; it matches no list). */\n JA4_FINGERPRINT_MATCH: 'detection/ja4-fingerprint-match',\n /** `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. */\n CLIENT_INTEGRITY_FAILURE: 'detection/client-integrity-failure',\n /** `source === 'ua_tls_mismatch'`: the User-Agent claims a browser but the JA4 cipher-list hash (JA4_b) belongs to known non-browser tooling. */\n UA_TLS_MISMATCH: 'detection/ua-tls-mismatch',\n /** `source === 'client.attributes'`: a pixel/beacon-reported client attribute contributed. */\n CLIENT_ATTRIBUTE_SIGNAL: 'detection/client-attribute-signal',\n /** `source === 'behavioural.interaction'`: a behavioral/interaction signal contributed. */\n BEHAVIORAL_SIGNAL: 'detection/behavioral-signal',\n /** `source === 'mcp_i'`: an MCP-I header was present (evidence short of a completed handshake). */\n MCP_I_SIGNAL: 'detection/mcp-i-signal',\n /** `source === 'kya_http_binding'`: a kya-http binding was presented (evidence short of full verification). */\n KYA_HTTP_BINDING_SIGNAL: 'detection/kya-http-binding-signal',\n /** `source === 'kya_delegation_bearer'`: a delegation bearer credential was presented. */\n KYA_DELEGATION_BEARER_SIGNAL: 'detection/kya-delegation-bearer-signal',\n /** A `signals[]` entry with `source === 'a2a_agent_card'`: an A2A Agent Card was presented (evidence short of, or alongside, full verification). */\n A2A_CARD_SIGNAL: 'detection/a2a-card-signal',\n /** `source === 'scanner_misclassification_hint'`: Cloudflare's bot score contradicted a zero-evidence Human verdict, overriding it to Unknown. */\n SCANNER_MISCLASSIFICATION_HINT_SIGNAL: 'detection/scanner-misclassification-hint-signal',\n /** `source === 'client_headless_escalation'`: the beacon disclosed `navigator.webdriver`, or reported corroborating automation evidence (CDP/plugin/WebGL consistency, a distinctive property), escalating the classification. */\n CLIENT_HEADLESS_ESCALATION_SIGNAL: 'detection/client-headless-escalation-signal',\n /** `source === 'transport.cloudflare_bot_management'`: Cloudflare's bot-management score or verified-bot determination contributed. */\n CLOUDFLARE_BOT_MANAGEMENT_SIGNAL: 'detection/cloudflare-bot-management-signal',\n /** `source === 'session_velocity'`: the edge-computed request-velocity heuristic contributed. */\n SESSION_VELOCITY_SIGNAL: 'detection/session-velocity-signal',\n /** A `signals[]` entry whose `source` starts with `tier1_`: raw Tier-1 protocol evidence, short of (or alongside) full verification. */\n TIER1_ATTRIBUTION_SIGNAL: 'detection/tier1-attribution-signal',\n\n // ── Classification flags ─────────────────────────────────────────────────\n /** `isAiCrawler === true`: classified as an AI training crawler (GPTBot, ClaudeBot, etc.), not an interactive agent. */\n AI_CRAWLER_FLAG: 'detection/ai-crawler-flag',\n\n // ── Zero-evidence fallbacks — an assumed verdict deserves a code saying so\n // (in the spirit of #4800): these fire ONLY when nothing above matched,\n // so the mapping never returns an empty list. ───────────────────────────\n /** `detectionClass === 'human'` with no contributing signals and no verification: the baseline \"nothing matched\" human path. */\n ZERO_EVIDENCE_HUMAN: 'detection/zero-evidence-human',\n /** `detectionClass === 'incomplete_data' | 'unknown'` (or absent): the engine could not classify confidently. */\n INCOMPLETE_DATA_OVERRIDE: 'detection/incomplete-data-override',\n /** 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. */\n CLASSIFIED_WITHOUT_SIGNAL_EVIDENCE: 'detection/classified-without-signal-evidence',\n} as const satisfies Record<string, `detection/${string}`>;\n\n/** A `detection/*` registry code (the value side of {@link DETECTION_REASON_CODES}). */\nexport type DetectionReasonCode =\n (typeof DETECTION_REASON_CODES)[keyof typeof DETECTION_REASON_CODES];\n","/**\n * Detection reason-code mapping: the single pure projection of a\n * detection's structured facts onto the `DETECTION_REASON_CODES` registry\n * (#4874).\n *\n * The engine already emits structured evidence (`signals[]` with a typed\n * `source`, `verificationMethod`, `detectionClass`, `isAiCrawler`) but the\n * only wire-level \"why\" used to be `reasons[]`, free English prose. This\n * module turns that structured evidence into an ordered list of stable,\n * namespaced codes, most-significant-evidence first.\n *\n * Consumers (all invoke this SAME pure function, so their codes can never\n * diverge):\n * - the gateway worker's `addDetectionHeaders` (`KYA-Reason-Codes` on\n * EVERY proxied response, including allow) and `log-detection.ts`\n * (persisted alongside the detection row), both via the re-export in\n * `apps/web/workers/gateway/src/detection/reason-codes.ts`;\n * - the `/api/v1/enforce` response's signal exposure\n * (KYA-1107) via `apps/web/lib/detection/signal-exposure.ts`.\n *\n * This module NEVER changes a verdict; it only labels one that already\n * happened (same non-negotiable as the registry doc comment).\n */\nimport { DETECTION_REASON_CODES, type DetectionReasonCode } from './detection-reason-codes';\nimport { isKyaOsHandshakeMethod, isKyaOsWireMethod } from '../utils/verification';\n\n/**\n * The structural subset of a detection detail the mapping actually reads.\n * Both the gateway's `GatewayDetectionDetail` (wire value space) and the\n * enforce route's engine-refined detail (engine value space) are assignable\n * since the mapping dual-accepts both value spaces where they differ (see the\n * handshake branch below).\n */\nexport interface ReasonCodeDetectionFacts {\n /** Verification method: WIRE (`mcp-i`/`kya-os`, `kya-http`, …) or ENGINE (`mcp_i_handshake`, …) value space. */\n verificationMethod?: string | null;\n /** The engine's per-signal evidence breakdown; only each entry's `source` is read. */\n signals?: ReadonlyArray<{ source: string }> | null;\n /** The engine's AI-training-crawler classification flag. */\n isAiCrawler?: boolean | null;\n /** Flat wire-form detection class (`human` | `ai_agent` | `bot` | `automation` | `incomplete_data` | `unknown`). */\n detectionClass?: string | null;\n}\n\n/**\n * `verificationMethod` → the single strongest code it proves. Keys are the\n * WIRE value space; the KYA-OS handshake/delegation alias pairs are handled\n * as explicit branches in `mapDetectionToReasonCodes` via the shared\n * `isKyaOs*Method` predicates (the SSOT for those alias pairs; Bugbot on\n * PR #4874 caught this table keyed on engine values instead, silently\n * missing every verified MCP-I/KYA-OS handshake) rather than hardcoding the\n * alias strings a second time in this map.\n */\nconst VERIFICATION_METHOD_CODES: Readonly<Record<string, DetectionReasonCode>> = {\n 'kya-http-delegated': DETECTION_REASON_CODES.DELEGATION_VERIFIED,\n 'kya-http': DETECTION_REASON_CODES.SIGNATURE_VERIFIED,\n did: DETECTION_REASON_CODES.DID_SIGNATURE_VERIFIED,\n signature: DETECTION_REASON_CODES.RFC9421_SIGNATURE_VERIFIED,\n a2a: DETECTION_REASON_CODES.A2A_VERIFIED,\n error: DETECTION_REASON_CODES.VERIFICATION_ERROR,\n};\n\n/**\n * A `signals[].source` value → the code naming that raw evidence.\n *\n * Declaration order IS the consideration order `mapDetectionToReasonCodes`\n * iterates (object key insertion order is guaranteed for string keys), NOT\n * the raw `signals[]` array order, which the engine assembles differently\n * per detection path (mirrors `buildVerdictEvidence`'s own doc comment on\n * the same nondeterminism). Roughly the engine's own construction order in\n * `api.rs` (identity/delegation evidence before UA/IP heuristics). Keeping\n * one map (rather than a map plus a separate priority-order array) means a\n * new signal source is added in exactly one place.\n */\nconst SIGNAL_SOURCE_CODES: Readonly<Record<string, DetectionReasonCode>> = {\n mcp_i: DETECTION_REASON_CODES.MCP_I_SIGNAL,\n kya_http_binding: DETECTION_REASON_CODES.KYA_HTTP_BINDING_SIGNAL,\n kya_delegation_bearer: DETECTION_REASON_CODES.KYA_DELEGATION_BEARER_SIGNAL,\n a2a_agent_card: DETECTION_REASON_CODES.A2A_CARD_SIGNAL,\n user_agent_pattern: DETECTION_REASON_CODES.UA_PATTERN_MATCH,\n ua_tls_mismatch: DETECTION_REASON_CODES.UA_TLS_MISMATCH,\n header_heuristic: DETECTION_REASON_CODES.HEADER_HEURISTIC,\n ip_heuristic: DETECTION_REASON_CODES.IP_HEURISTIC,\n scanner_misclassification_hint: DETECTION_REASON_CODES.SCANNER_MISCLASSIFICATION_HINT_SIGNAL,\n client_headless_escalation: DETECTION_REASON_CODES.CLIENT_HEADLESS_ESCALATION_SIGNAL,\n vendor_ip_feed: DETECTION_REASON_CODES.VENDOR_IP_CORROBORATED,\n ip_intelligence: DETECTION_REASON_CODES.IP_INTELLIGENCE_PROXY_SIGNAL,\n 'transport.ja4': DETECTION_REASON_CODES.JA4_FINGERPRINT_MATCH,\n 'transport.cloudflare_bot_management': DETECTION_REASON_CODES.CLOUDFLARE_BOT_MANAGEMENT_SIGNAL,\n client_integrity: DETECTION_REASON_CODES.CLIENT_INTEGRITY_FAILURE,\n 'client.attributes': DETECTION_REASON_CODES.CLIENT_ATTRIBUTE_SIGNAL,\n 'behavioural.interaction': DETECTION_REASON_CODES.BEHAVIORAL_SIGNAL,\n session_velocity: DETECTION_REASON_CODES.SESSION_VELOCITY_SIGNAL,\n};\n\n/**\n * Maps a detection's structured facts to an ordered, deduplicated list of\n * `detection/*` reason codes, most-significant-evidence first:\n *\n * 1. Verification-method-derived (cryptographic proof, strongest).\n * 2. Signal-source-derived (raw structured evidence), one code per\n * distinct source actually present, deduplicated.\n * 3. The AI-crawler classification flag.\n * 4. A zero-evidence fallback, ONLY when nothing above matched, so this\n * function never returns an empty list. An assumed verdict (e.g. the\n * baseline \"no known agent indicators matched\" human path) deserves a\n * code saying so, in the spirit of #4800, rather than silence.\n *\n * Pure: no I/O, no mutation of `detail`.\n */\nexport function mapDetectionToReasonCodes(detail: ReasonCodeDetectionFacts): DetectionReasonCode[] {\n const codes: DetectionReasonCode[] = [];\n const seen = new Set<DetectionReasonCode>();\n const push = (code: DetectionReasonCode | undefined): void => {\n if (code && !seen.has(code)) {\n seen.add(code);\n codes.push(code);\n }\n };\n\n // 1. Verification method.\n const verificationMethod = detail.verificationMethod;\n if (verificationMethod) {\n if (verificationMethod.startsWith('tier1_')) {\n push(DETECTION_REASON_CODES.TIER1_ATTRIBUTION_VERIFIED);\n } else if (\n // Dual-accept BOTH value spaces for the KYA-OS handshake: the gateway\n // worker normalizes to the WIRE values (`mcp-i`/`kya-os`) before\n // calling in, while the enforce route's engine-refined detail carries\n // the ENGINE values (`mcp_i_handshake`/`kyaos_handshake`). Routing\n // both through the shared predicates keeps the alias pairs in exactly\n // one place and closes the exact single-value-space gap Bugbot\n // caught on PR #4874.\n isKyaOsWireMethod(verificationMethod) ||\n isKyaOsHandshakeMethod(verificationMethod)\n ) {\n push(DETECTION_REASON_CODES.MCP_I_VERIFIED);\n } else {\n push(VERIFICATION_METHOD_CODES[verificationMethod]);\n }\n }\n\n // 2. Signal sources: one pass over detail.signals builds the dedup Set\n // AND detects a tier1_* source, rather than a second scan/spread over the\n // Set afterward. Then a fixed-order pass over SIGNAL_SOURCE_CODES's own\n // declaration order (the consideration order) pushes each present source's\n // code.\n const presentSources = new Set<string>();\n let hasTier1Signal = false;\n for (const signal of detail.signals ?? []) {\n presentSources.add(signal.source);\n if (signal.source.startsWith('tier1_')) hasTier1Signal = true;\n }\n for (const source of Object.keys(SIGNAL_SOURCE_CODES)) {\n if (presentSources.has(source)) push(SIGNAL_SOURCE_CODES[source]);\n }\n if (hasTier1Signal) {\n push(DETECTION_REASON_CODES.TIER1_ATTRIBUTION_SIGNAL);\n }\n\n // 3. AI-crawler flag: additive, independent of the codes above.\n if (detail.isAiCrawler) {\n push(DETECTION_REASON_CODES.AI_CRAWLER_FLAG);\n }\n\n // 4. Zero-evidence fallback: only when nothing above fired.\n if (codes.length === 0) {\n if (detail.detectionClass === 'human') {\n push(DETECTION_REASON_CODES.ZERO_EVIDENCE_HUMAN);\n } else if (\n detail.detectionClass === 'incomplete_data' ||\n detail.detectionClass === 'unknown' ||\n !detail.detectionClass\n ) {\n push(DETECTION_REASON_CODES.INCOMPLETE_DATA_OVERRIDE);\n } else {\n push(DETECTION_REASON_CODES.CLASSIFIED_WITHOUT_SIGNAL_EVIDENCE);\n }\n }\n\n return codes;\n}\n\n/** Wire cap: at most this many codes on the `KYA-Reason-Codes` header. */\nexport const MAX_REASON_CODES_ON_WIRE = 5;\n/** Wire cap: the header's serialized UTF-8 byte budget. */\nexport const MAX_REASON_CODES_HEADER_BYTES = 256;\n\nconst HEADER_BYTES_ENCODER = new TextEncoder();\n\n/**\n * Formats an ordered reason-code list into the `KYA-Reason-Codes` header\n * value: comma-separated, capped at {@link MAX_REASON_CODES_ON_WIRE} codes,\n * then trimmed from the end (never mid-string) until the UTF-8 byte length\n * fits {@link MAX_REASON_CODES_HEADER_BYTES}. `codes` is assumed already\n * ordered most-significant-first (mapDetectionToReasonCodes's contract);\n * this function only truncates, it never reorders.\n */\nexport function formatReasonCodesHeader(codes: readonly DetectionReasonCode[]): string {\n const capped = codes.slice(0, MAX_REASON_CODES_ON_WIRE);\n while (capped.length > 0) {\n const joined = capped.join(',');\n if (HEADER_BYTES_ENCODER.encode(joined).byteLength <= MAX_REASON_CODES_HEADER_BYTES) {\n return joined;\n }\n capped.pop();\n }\n return '';\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAa,yBAAyB;;CAGpC,oBAAoB;;CAEpB,qBAAqB;;CAErB,gBAAgB;;CAEhB,wBAAwB;;CAExB,4BAA4B;;CAE5B,4BAA4B;;CAE5B,cAAc;;CAEd,oBAAoB;;CAIpB,kBAAkB;;CAElB,kBAAkB;;CAElB,cAAc;;CAEd,wBAAwB;;CAExB,8BAA8B;;CAE9B,uBAAuB;;CAEvB,0BAA0B;;CAE1B,iBAAiB;;CAEjB,yBAAyB;;CAEzB,mBAAmB;;CAEnB,cAAc;;CAEd,yBAAyB;;CAEzB,8BAA8B;;CAE9B,iBAAiB;;CAEjB,uCAAuC;;CAEvC,mCAAmC;;CAEnC,kCAAkC;;CAElC,yBAAyB;;CAEzB,0BAA0B;;CAI1B,iBAAiB;;CAMjB,qBAAqB;;CAErB,0BAA0B;;CAE1B,oCAAoC;AACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACtDA,MAAM,4BAA2E;CAC/E,sBAAsB,uBAAuB;CAC7C,YAAY,uBAAuB;CACnC,KAAK,uBAAuB;CAC5B,WAAW,uBAAuB;CAClC,KAAK,uBAAuB;CAC5B,OAAO,uBAAuB;AAChC;;;;;;;;;;;;;AAcA,MAAM,sBAAqE;CACzE,OAAO,uBAAuB;CAC9B,kBAAkB,uBAAuB;CACzC,uBAAuB,uBAAuB;CAC9C,gBAAgB,uBAAuB;CACvC,oBAAoB,uBAAuB;CAC3C,iBAAiB,uBAAuB;CACxC,kBAAkB,uBAAuB;CACzC,cAAc,uBAAuB;CACrC,gCAAgC,uBAAuB;CACvD,4BAA4B,uBAAuB;CACnD,gBAAgB,uBAAuB;CACvC,iBAAiB,uBAAuB;CACxC,iBAAiB,uBAAuB;CACxC,uCAAuC,uBAAuB;CAC9D,kBAAkB,uBAAuB;CACzC,qBAAqB,uBAAuB;CAC5C,2BAA2B,uBAAuB;CAClD,kBAAkB,uBAAuB;AAC3C;;;;;;;;;;;;;;;;AAiBA,SAAgB,0BAA0B,QAAyD;CACjG,MAAM,QAA+B,CAAC;CACtC,MAAM,uBAAO,IAAI,IAAyB;CAC1C,MAAM,QAAQ,SAAgD;EAC5D,IAAI,QAAQ,CAAC,KAAK,IAAI,IAAI,GAAG;GAC3B,KAAK,IAAI,IAAI;GACb,MAAM,KAAK,IAAI;EACjB;CACF;CAGA,MAAM,qBAAqB,OAAO;CAClC,IAAI,oBAAoB;EACtB,IAAI,mBAAmB,WAAW,QAAQ,GACxC,KAAK,uBAAuB,0BAA0B;OACjD,IAQL,kBAAkB,kBAAkB,KACpC,uBAAuB,kBAAkB,GAEzC,KAAK,uBAAuB,cAAc;OAE1C,KAAK,0BAA0B,mBAAmB;CAEtD;CAOA,MAAM,iCAAiB,IAAI,IAAY;CACvC,IAAI,iBAAiB;CACrB,KAAK,MAAM,UAAU,OAAO,WAAW,CAAC,GAAG;EACzC,eAAe,IAAI,OAAO,MAAM;EAChC,IAAI,OAAO,OAAO,WAAW,QAAQ,GAAG,iBAAiB;CAC3D;CACA,KAAK,MAAM,UAAU,OAAO,KAAK,mBAAmB,GAClD,IAAI,eAAe,IAAI,MAAM,GAAG,KAAK,oBAAoB,OAAO;CAElE,IAAI,gBACF,KAAK,uBAAuB,wBAAwB;CAItD,IAAI,OAAO,aACT,KAAK,uBAAuB,eAAe;CAI7C,IAAI,MAAM,WAAW,GAAG;EACtB,IAAI,OAAO,mBAAmB,SAC5B,KAAK,uBAAuB,mBAAmB;OAC1C,IACL,OAAO,mBAAmB,qBAC1B,OAAO,mBAAmB,aAC1B,CAAC,OAAO,gBAER,KAAK,uBAAuB,wBAAwB;OAEpD,KAAK,uBAAuB,kCAAkC;CAElE;CAEA,OAAO;AACT;;AAGA,MAAa,2BAA2B;;AAExC,MAAa,gCAAgC;AAE7C,MAAM,uBAAuB,IAAI,YAAY;;;;;;;;;AAU7C,SAAgB,wBAAwB,OAA+C;CACrF,MAAM,SAAS,MAAM,MAAM,IAA2B;CACtD,OAAO,OAAO,SAAS,GAAG;EACxB,MAAM,SAAS,OAAO,KAAK,GAAG;EAC9B,IAAI,qBAAqB,OAAO,MAAM,CAAC,CAAC,mBACtC,OAAO;EAET,OAAO,IAAI;CACb;CACA,OAAO;AACT"}
@@ -0,0 +1,52 @@
1
+ //#region src/core/detection-reason-codes.d.ts
2
+ declare const DETECTION_REASON_CODES: {
3
+ readonly SIGNATURE_VERIFIED: "detection/signature-verified";
4
+ readonly DELEGATION_VERIFIED: "detection/delegation-verified";
5
+ readonly MCP_I_VERIFIED: "detection/mcp-i-verified";
6
+ readonly DID_SIGNATURE_VERIFIED: "detection/did-signature-verified";
7
+ readonly RFC9421_SIGNATURE_VERIFIED: "detection/rfc9421-signature-verified";
8
+ readonly TIER1_ATTRIBUTION_VERIFIED: "detection/tier1-attribution-verified";
9
+ readonly A2A_VERIFIED: "detection/a2a-verified";
10
+ readonly VERIFICATION_ERROR: "detection/verification-error";
11
+ readonly UA_PATTERN_MATCH: "detection/ua-pattern-match";
12
+ readonly HEADER_HEURISTIC: "detection/header-heuristic";
13
+ readonly IP_HEURISTIC: "detection/ip-heuristic";
14
+ readonly VENDOR_IP_CORROBORATED: "detection/vendor-ip-corroborated";
15
+ readonly IP_INTELLIGENCE_PROXY_SIGNAL: "detection/ip-intelligence-proxy-signal";
16
+ readonly JA4_FINGERPRINT_MATCH: "detection/ja4-fingerprint-match";
17
+ readonly CLIENT_INTEGRITY_FAILURE: "detection/client-integrity-failure";
18
+ readonly UA_TLS_MISMATCH: "detection/ua-tls-mismatch";
19
+ readonly CLIENT_ATTRIBUTE_SIGNAL: "detection/client-attribute-signal";
20
+ readonly BEHAVIORAL_SIGNAL: "detection/behavioral-signal";
21
+ readonly MCP_I_SIGNAL: "detection/mcp-i-signal";
22
+ readonly KYA_HTTP_BINDING_SIGNAL: "detection/kya-http-binding-signal";
23
+ readonly KYA_DELEGATION_BEARER_SIGNAL: "detection/kya-delegation-bearer-signal";
24
+ readonly A2A_CARD_SIGNAL: "detection/a2a-card-signal";
25
+ readonly SCANNER_MISCLASSIFICATION_HINT_SIGNAL: "detection/scanner-misclassification-hint-signal";
26
+ readonly CLIENT_HEADLESS_ESCALATION_SIGNAL: "detection/client-headless-escalation-signal";
27
+ readonly CLOUDFLARE_BOT_MANAGEMENT_SIGNAL: "detection/cloudflare-bot-management-signal";
28
+ readonly SESSION_VELOCITY_SIGNAL: "detection/session-velocity-signal";
29
+ readonly TIER1_ATTRIBUTION_SIGNAL: "detection/tier1-attribution-signal";
30
+ readonly AI_CRAWLER_FLAG: "detection/ai-crawler-flag";
31
+ readonly ZERO_EVIDENCE_HUMAN: "detection/zero-evidence-human";
32
+ readonly INCOMPLETE_DATA_OVERRIDE: "detection/incomplete-data-override";
33
+ readonly CLASSIFIED_WITHOUT_SIGNAL_EVIDENCE: "detection/classified-without-signal-evidence";
34
+ };
35
+ type DetectionReasonCode = (typeof DETECTION_REASON_CODES)[keyof typeof DETECTION_REASON_CODES];
36
+ //#endregion
37
+ //#region src/core/detection-reason-mapping.d.ts
38
+ interface ReasonCodeDetectionFacts {
39
+ verificationMethod?: string | null;
40
+ signals?: ReadonlyArray<{
41
+ source: string;
42
+ }> | null;
43
+ isAiCrawler?: boolean | null;
44
+ detectionClass?: string | null;
45
+ }
46
+ declare function mapDetectionToReasonCodes(detail: ReasonCodeDetectionFacts): DetectionReasonCode[];
47
+ declare const MAX_REASON_CODES_ON_WIRE = 5;
48
+ declare const MAX_REASON_CODES_HEADER_BYTES = 256;
49
+ declare function formatReasonCodesHeader(codes: readonly DetectionReasonCode[]): string;
50
+ //#endregion
51
+ export { mapDetectionToReasonCodes as a, formatReasonCodesHeader as i, MAX_REASON_CODES_ON_WIRE as n, DETECTION_REASON_CODES as o, ReasonCodeDetectionFacts as r, DetectionReasonCode as s, MAX_REASON_CODES_HEADER_BYTES as t };
52
+ //# sourceMappingURL=detection-reason-mapping-CQexNvR7.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"detection-reason-mapping-CQexNvR7.d.mts","names":[],"sources":["../src/core/detection-reason-codes.ts","../src/core/detection-reason-mapping.ts"],"mappings":";cAmCa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2ED,8BACF,qCAAqC;;;UC9E9B;EAEf;EAEA,UAAU;IAAgB;;EAE1B;EAEA;;iBAqEc,0BAA0B,QAAQ,2BAA2B;cA0EhE;cAEA;iBAYG,wBAAwB,gBAAgB"}