@kya-os/checkpoint-shared 1.6.0 → 1.8.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.
- package/CHANGELOG.md +122 -9
- package/README.md +24 -7
- package/dist/beacon-nonce/index.d.mts +1 -0
- package/dist/beacon-nonce/index.d.mts.map +1 -1
- package/dist/beacon-nonce/index.d.ts +1 -0
- package/dist/beacon-nonce/index.d.ts.map +1 -1
- package/dist/beacon-nonce/index.js +9 -3
- package/dist/beacon-nonce/index.mjs +9 -4
- package/dist/beacon-nonce/index.mjs.map +1 -1
- package/dist/beacon-types/index.d.mts +23 -1
- package/dist/beacon-types/index.d.mts.map +1 -1
- package/dist/beacon-types/index.d.ts +23 -1
- package/dist/beacon-types/index.d.ts.map +1 -1
- package/dist/beacon-types/index.js +49 -4
- package/dist/beacon-types/index.mjs +47 -4
- package/dist/beacon-types/index.mjs.map +1 -1
- package/dist/{browser-posture-BuChqmH5.d.mts → browser-posture-5fPrsxx7.d.mts} +2 -2
- package/dist/{browser-posture-BuChqmH5.d.mts.map → browser-posture-5fPrsxx7.d.mts.map} +1 -1
- package/dist/{browser-posture-DIaVLuW3.d.ts → browser-posture-CCR1kh5e.d.ts} +2 -2
- package/dist/{browser-posture-DIaVLuW3.d.ts.map → browser-posture-CCR1kh5e.d.ts.map} +1 -1
- package/dist/browser-posture-cookie.js +1 -1
- package/dist/browser-posture-cookie.mjs +1 -1
- package/dist/browser-posture-cookie.mjs.map +1 -1
- package/dist/browser-posture-proof.d.mts +16 -2
- package/dist/browser-posture-proof.d.mts.map +1 -1
- package/dist/browser-posture-proof.d.ts +16 -2
- package/dist/browser-posture-proof.d.ts.map +1 -1
- package/dist/browser-posture-proof.js +114 -17
- package/dist/browser-posture-proof.mjs +112 -17
- package/dist/browser-posture-proof.mjs.map +1 -1
- package/dist/browser-posture.d.mts +1 -1
- package/dist/browser-posture.d.ts +1 -1
- package/dist/browser-posture.js +6 -5
- package/dist/browser-posture.mjs +4 -3
- package/dist/browser-posture.mjs.map +1 -1
- package/dist/browser.d.mts +25 -4
- package/dist/browser.d.mts.map +1 -1
- package/dist/browser.d.ts +25 -4
- package/dist/browser.d.ts.map +1 -1
- package/dist/browser.js +1 -1
- package/dist/browser.mjs +1 -1
- package/dist/browser.mjs.map +1 -1
- package/dist/canonical-signer/index.d.mts.map +1 -1
- package/dist/canonical-signer/index.d.ts.map +1 -1
- package/dist/canonical-signer/index.js +116 -79
- package/dist/canonical-signer/index.mjs +117 -52
- package/dist/canonical-signer/index.mjs.map +1 -1
- package/dist/clearance.d.mts +1 -1
- package/dist/clearance.d.ts +1 -1
- package/dist/clearance.js +2 -2
- package/dist/clearance.mjs +2 -2
- package/dist/client-ip-B7w-uHfS.d.mts +55 -0
- package/dist/client-ip-B7w-uHfS.d.mts.map +1 -0
- package/dist/client-ip-B7w-uHfS.d.ts +55 -0
- package/dist/client-ip-B7w-uHfS.d.ts.map +1 -0
- package/dist/{client-ip-CW6pRyLf.js → client-ip-B8wFzJ5f.js} +117 -7
- package/dist/{client-ip-B2Xeo-GK.mjs → client-ip-DIJyr6px.mjs} +113 -9
- package/dist/client-ip-DIJyr6px.mjs.map +1 -0
- package/dist/client-ip.d.mts +2 -0
- package/dist/client-ip.d.ts +2 -0
- package/dist/client-ip.js +8 -0
- package/dist/client-ip.mjs +3 -0
- package/dist/detection-reason-mapping-B9RSkOs8.js +277 -0
- package/dist/detection-reason-mapping-BGymWIPl.mjs +249 -0
- package/dist/detection-reason-mapping-BGymWIPl.mjs.map +1 -0
- package/dist/detection-reason-mapping-CQexNvR7.d.mts +52 -0
- package/dist/detection-reason-mapping-CQexNvR7.d.mts.map +1 -0
- package/dist/detection-reason-mapping-CQexNvR7.d.ts +52 -0
- package/dist/detection-reason-mapping-CQexNvR7.d.ts.map +1 -0
- package/dist/engine-enforcing-AYEcgNsb.js +39 -0
- package/dist/engine-enforcing-B5eNfCpG.mjs +29 -0
- package/dist/engine-enforcing-B5eNfCpG.mjs.map +1 -0
- package/dist/engine-enforcing-DiOclGqf.d.mts +11 -0
- package/dist/engine-enforcing-DiOclGqf.d.mts.map +1 -0
- package/dist/engine-enforcing-DiOclGqf.d.ts +11 -0
- package/dist/engine-enforcing-DiOclGqf.d.ts.map +1 -0
- package/dist/engine-info.d.mts +2 -0
- package/dist/engine-info.d.ts +2 -0
- package/dist/engine-info.js +4 -0
- package/dist/engine-info.mjs +3 -0
- package/dist/errors/index.d.mts +5 -0
- package/dist/errors/index.d.mts.map +1 -1
- package/dist/errors/index.d.ts +5 -0
- package/dist/errors/index.d.ts.map +1 -1
- package/dist/errors/index.js +23 -4
- package/dist/errors/index.mjs +23 -4
- package/dist/errors/index.mjs.map +1 -1
- package/dist/{external-B7WI9FyQ.d.ts → external-m3Kmafwj.d.mts} +2 -2
- package/dist/{external-B7WI9FyQ.d.mts.map → external-m3Kmafwj.d.mts.map} +1 -1
- package/dist/{external-B7WI9FyQ.d.mts → external-m3Kmafwj.d.ts} +2 -2
- package/dist/{external-B7WI9FyQ.d.ts.map → external-m3Kmafwj.d.ts.map} +1 -1
- package/dist/fetcher-CivUCbhL.d.ts +44 -0
- package/dist/fetcher-CivUCbhL.d.ts.map +1 -0
- package/dist/fetcher-cXQsbm6s.d.mts +44 -0
- package/dist/fetcher-cXQsbm6s.d.mts.map +1 -0
- package/dist/gateway-client-ip.d.mts +1 -1
- package/dist/gateway-client-ip.d.ts +1 -1
- package/dist/gateway-client-ip.js +2 -2
- package/dist/gateway-client-ip.mjs +2 -2
- package/dist/host-adapter/index.d.mts +2 -0
- package/dist/host-adapter/index.d.ts +2 -0
- package/dist/host-adapter/index.js +24 -0
- package/dist/host-adapter/index.mjs +3 -0
- package/dist/host-adapter-0F8EpbD6.js +753 -0
- package/dist/host-adapter-DHyISsIf.mjs +593 -0
- package/dist/host-adapter-DHyISsIf.mjs.map +1 -0
- package/dist/index-B3cHxr3O.d.mts +156 -0
- package/dist/index-B3cHxr3O.d.mts.map +1 -0
- package/dist/index-CXbOY7gB.d.ts +156 -0
- package/dist/index-CXbOY7gB.d.ts.map +1 -0
- package/dist/index.d.mts +6997 -12170
- package/dist/index.d.mts.map +1 -1
- package/dist/index.d.ts +6997 -12170
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2510 -8893
- package/dist/index.mjs +2366 -8534
- package/dist/index.mjs.map +1 -1
- package/dist/kya-http-error-codes-7ewV5RuK.d.mts +29 -0
- package/dist/kya-http-error-codes-7ewV5RuK.d.mts.map +1 -0
- package/dist/kya-http-error-codes-7ewV5RuK.d.ts +29 -0
- package/dist/kya-http-error-codes-7ewV5RuK.d.ts.map +1 -0
- package/dist/kya-http-error-codes-C2JiWPsi.mjs +73 -0
- package/dist/kya-http-error-codes-C2JiWPsi.mjs.map +1 -0
- package/dist/kya-http-error-codes-UYb1zpGM.js +83 -0
- package/dist/kya-http.d.mts +3 -0
- package/dist/kya-http.d.ts +3 -0
- package/dist/kya-http.js +19 -0
- package/dist/kya-http.mjs +5 -0
- package/dist/mcpi/dashboard-config/index.d.mts.map +1 -1
- package/dist/mcpi/dashboard-config/index.d.ts.map +1 -1
- package/dist/mcpi/status-list/index.d.mts +72 -0
- package/dist/mcpi/status-list/index.d.mts.map +1 -0
- package/dist/mcpi/status-list/index.d.ts +72 -0
- package/dist/mcpi/status-list/index.d.ts.map +1 -0
- package/dist/mcpi/status-list/index.js +703 -0
- package/dist/mcpi/status-list/index.mjs +684 -0
- package/dist/mcpi/status-list/index.mjs.map +1 -0
- package/dist/patterns-B2r7M9wR.js +243 -0
- package/dist/patterns-B7dQoeE3.mjs +173 -0
- package/dist/patterns-B7dQoeE3.mjs.map +1 -0
- package/dist/patterns-Bp40cwh2.d.mts +110 -0
- package/dist/patterns-Bp40cwh2.d.mts.map +1 -0
- package/dist/patterns-Bp40cwh2.d.ts +110 -0
- package/dist/patterns-Bp40cwh2.d.ts.map +1 -0
- package/dist/patterns.d.mts +2 -0
- package/dist/patterns.d.ts +2 -0
- package/dist/patterns.js +15 -0
- package/dist/patterns.mjs +3 -0
- package/dist/policy/enforcement.d.mts +3 -0
- package/dist/policy/enforcement.d.ts +3 -0
- package/dist/policy/enforcement.js +21 -0
- package/dist/policy/enforcement.mjs +4 -0
- package/dist/policy/fetcher.d.mts +2 -0
- package/dist/policy/fetcher.d.ts +2 -0
- package/dist/policy/fetcher.js +240 -0
- package/dist/policy/fetcher.mjs +238 -0
- package/dist/policy/fetcher.mjs.map +1 -0
- package/dist/policy/schemas.d.mts +3 -0
- package/dist/policy/schemas.d.ts +3 -0
- package/dist/policy/schemas.js +27 -0
- package/dist/policy/schemas.mjs +4 -0
- package/dist/{posture-origins-Pn-ii-Pp.mjs → posture-origins-Ci6k4Zh1.js} +24 -173
- package/dist/{posture-origins-LFkX80oF.js → posture-origins-DGyS4Vuk.mjs} +2 -267
- package/dist/posture-origins-DGyS4Vuk.mjs.map +1 -0
- package/dist/{project-verification-key-BccT12tQ.js → project-verification-key-B-L3D2nC.js} +1 -1
- package/dist/{project-verification-key-66N4edKn.mjs → project-verification-key-CWXdu3-n.mjs} +2 -2
- package/dist/{project-verification-key-66N4edKn.mjs.map → project-verification-key-CWXdu3-n.mjs.map} +1 -1
- package/dist/provider-registry.d.mts +2 -0
- package/dist/provider-registry.d.ts +2 -0
- package/dist/provider-registry.js +51 -0
- package/dist/provider-registry.mjs +3 -0
- package/dist/reason-codes.d.mts +2 -0
- package/dist/reason-codes.d.ts +2 -0
- package/dist/reason-codes.js +8 -0
- package/dist/reason-codes.mjs +3 -0
- package/dist/registered-sid-26hNxp6t.mjs +151 -0
- package/dist/registered-sid-26hNxp6t.mjs.map +1 -0
- package/dist/registered-sid-D6KCaT1E.d.mts +33 -0
- package/dist/registered-sid-D6KCaT1E.d.mts.map +1 -0
- package/dist/registered-sid-D6KCaT1E.d.ts +33 -0
- package/dist/registered-sid-D6KCaT1E.d.ts.map +1 -0
- package/dist/registered-sid-DVGTSH0L.js +185 -0
- package/dist/ruleset-hash-Cmv8MSO5.js +34 -0
- package/dist/ruleset-hash-IRN5eI9H.d.mts +5 -0
- package/dist/ruleset-hash-IRN5eI9H.d.mts.map +1 -0
- package/dist/ruleset-hash-IRN5eI9H.d.ts +5 -0
- package/dist/ruleset-hash-IRN5eI9H.d.ts.map +1 -0
- package/dist/ruleset-hash-QQIaLuPi.mjs +30 -0
- package/dist/ruleset-hash-QQIaLuPi.mjs.map +1 -0
- package/dist/schemas-02CI7jgm.d.mts +535 -0
- package/dist/schemas-02CI7jgm.d.mts.map +1 -0
- package/dist/{schemas-YhagYDx_.js → schemas-BlScS1it.js} +0 -20
- package/dist/schemas-C_3C72SR.d.ts +535 -0
- package/dist/schemas-C_3C72SR.d.ts.map +1 -0
- package/dist/schemas-Cm4C4Z5G.js +703 -0
- package/dist/schemas-DPIT8usF.mjs +525 -0
- package/dist/schemas-DPIT8usF.mjs.map +1 -0
- package/dist/{schemas-7qodsG-Z.mjs → schemas-IHAhH3gV.mjs} +2 -16
- package/dist/schemas-IHAhH3gV.mjs.map +1 -0
- package/dist/step-up-BK0oBi11.mjs +1563 -0
- package/dist/step-up-BK0oBi11.mjs.map +1 -0
- package/dist/step-up-Bp8RAQwv.js +1759 -0
- package/dist/step-up-Bz12gYKT.d.mts +130 -0
- package/dist/step-up-Bz12gYKT.d.mts.map +1 -0
- package/dist/step-up-Bz12gYKT.d.ts +130 -0
- package/dist/step-up-Bz12gYKT.d.ts.map +1 -0
- package/dist/test-fixtures/index.d.mts +4 -4
- package/dist/test-fixtures/index.d.mts.map +1 -1
- package/dist/test-fixtures/index.d.ts +4 -4
- package/dist/test-fixtures/index.d.ts.map +1 -1
- package/dist/test-fixtures/index.js +4 -4
- package/dist/test-fixtures/index.mjs +4 -4
- package/dist/test-fixtures/index.mjs.map +1 -1
- package/dist/verification-BAw9N8Pt.js +181 -0
- package/dist/verification-Cvvv86TT.mjs +123 -0
- package/dist/verification-Cvvv86TT.mjs.map +1 -0
- package/fixtures/client-ip-resolution.n01.json +101 -0
- package/fixtures/reviewer-grant-revocation.v1.json +53 -81
- package/package.json +59 -2
- package/dist/client-ip-B2Xeo-GK.mjs.map +0 -1
- package/dist/posture-origins-Pn-ii-Pp.mjs.map +0 -1
- package/dist/schemas-7qodsG-Z.mjs.map +0 -1
|
@@ -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"}
|
|
@@ -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.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"detection-reason-mapping-CQexNvR7.d.ts","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"}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
//#region src/policy/challenge-type.ts
|
|
2
|
+
/**
|
|
3
|
+
* Normalize a wire `challengeType` to the kind every renderer must treat it
|
|
4
|
+
* as. Absent or unrecognized (a future engine-added kind) falls closed to
|
|
5
|
+
* `'delegation'`, the pre-existing MCP-I Level 2+ handshake every renderer
|
|
6
|
+
* already understands; it is never thrown or silently dropped. Kept apart
|
|
7
|
+
* from the policy schemas (`./schemas.ts`, Zod) so request-path code can take
|
|
8
|
+
* it from the `./policy/enforcement` lean entry.
|
|
9
|
+
*/
|
|
10
|
+
function normalizeChallengeType(challengeType) {
|
|
11
|
+
return challengeType === "browser_integrity" || challengeType === "human_step_up" ? challengeType : "delegation";
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
//#endregion
|
|
15
|
+
//#region src/policy/engine-enforcing.ts
|
|
16
|
+
/**
|
|
17
|
+
* The act-gate for a composed policy: the engine acts on it only when engine
|
|
18
|
+
* enforcement is switched on and the policy is not disabled. Otherwise the
|
|
19
|
+
* composed policy is at most shadow-evaluated. Kept apart from `schemas.ts`,
|
|
20
|
+
* which builds Zod schemas when it loads, so request-time callers can use it
|
|
21
|
+
* without loading Zod.
|
|
22
|
+
*/
|
|
23
|
+
function isEngineEnforcing(flags) {
|
|
24
|
+
return flags.engineEnforcementEnabled === true && flags.enabled !== false;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
//#endregion
|
|
28
|
+
Object.defineProperty(exports, 'isEngineEnforcing', {
|
|
29
|
+
enumerable: true,
|
|
30
|
+
get: function () {
|
|
31
|
+
return isEngineEnforcing;
|
|
32
|
+
}
|
|
33
|
+
});
|
|
34
|
+
Object.defineProperty(exports, 'normalizeChallengeType', {
|
|
35
|
+
enumerable: true,
|
|
36
|
+
get: function () {
|
|
37
|
+
return normalizeChallengeType;
|
|
38
|
+
}
|
|
39
|
+
});
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
//#region src/policy/challenge-type.ts
|
|
2
|
+
/**
|
|
3
|
+
* Normalize a wire `challengeType` to the kind every renderer must treat it
|
|
4
|
+
* as. Absent or unrecognized (a future engine-added kind) falls closed to
|
|
5
|
+
* `'delegation'`, the pre-existing MCP-I Level 2+ handshake every renderer
|
|
6
|
+
* already understands; it is never thrown or silently dropped. Kept apart
|
|
7
|
+
* from the policy schemas (`./schemas.ts`, Zod) so request-path code can take
|
|
8
|
+
* it from the `./policy/enforcement` lean entry.
|
|
9
|
+
*/
|
|
10
|
+
function normalizeChallengeType(challengeType) {
|
|
11
|
+
return challengeType === "browser_integrity" || challengeType === "human_step_up" ? challengeType : "delegation";
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
//#endregion
|
|
15
|
+
//#region src/policy/engine-enforcing.ts
|
|
16
|
+
/**
|
|
17
|
+
* The act-gate for a composed policy: the engine acts on it only when engine
|
|
18
|
+
* enforcement is switched on and the policy is not disabled. Otherwise the
|
|
19
|
+
* composed policy is at most shadow-evaluated. Kept apart from `schemas.ts`,
|
|
20
|
+
* which builds Zod schemas when it loads, so request-time callers can use it
|
|
21
|
+
* without loading Zod.
|
|
22
|
+
*/
|
|
23
|
+
function isEngineEnforcing(flags) {
|
|
24
|
+
return flags.engineEnforcementEnabled === true && flags.enabled !== false;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
//#endregion
|
|
28
|
+
export { normalizeChallengeType as n, isEngineEnforcing as t };
|
|
29
|
+
//# sourceMappingURL=engine-enforcing-B5eNfCpG.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine-enforcing-B5eNfCpG.mjs","names":[],"sources":["../src/policy/challenge-type.ts","../src/policy/engine-enforcing.ts"],"sourcesContent":["/**\n * Normalize a wire `challengeType` to the kind every renderer must treat it\n * as. Absent or unrecognized (a future engine-added kind) falls closed to\n * `'delegation'`, the pre-existing MCP-I Level 2+ handshake every renderer\n * already understands; it is never thrown or silently dropped. Kept apart\n * from the policy schemas (`./schemas.ts`, Zod) so request-path code can take\n * it from the `./policy/enforcement` lean entry.\n */\nexport function normalizeChallengeType(\n challengeType: string | undefined\n): 'delegation' | 'browser_integrity' | 'human_step_up' {\n return challengeType === 'browser_integrity' || challengeType === 'human_step_up'\n ? challengeType\n : 'delegation';\n}\n","/**\n * The act-gate for a composed policy: the engine acts on it only when engine\n * enforcement is switched on and the policy is not disabled. Otherwise the\n * composed policy is at most shadow-evaluated. Kept apart from `schemas.ts`,\n * which builds Zod schemas when it loads, so request-time callers can use it\n * without loading Zod.\n */\nexport function isEngineEnforcing(flags: {\n engineEnforcementEnabled?: boolean | null;\n enabled?: boolean | null;\n}): boolean {\n return flags.engineEnforcementEnabled === true && flags.enabled !== false;\n}\n"],"mappings":";;;;;;;;;AAQA,SAAgB,uBACd,eACsD;CACtD,OAAO,kBAAkB,uBAAuB,kBAAkB,kBAC9D,gBACA;AACN;;;;;;;;;;;ACPA,SAAgB,kBAAkB,OAGtB;CACV,OAAO,MAAM,6BAA6B,QAAQ,MAAM,YAAY;AACtE"}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
//#region src/policy/challenge-type.d.ts
|
|
2
|
+
declare function normalizeChallengeType(challengeType: string | undefined): 'delegation' | 'browser_integrity' | 'human_step_up';
|
|
3
|
+
//#endregion
|
|
4
|
+
//#region src/policy/engine-enforcing.d.ts
|
|
5
|
+
declare function isEngineEnforcing(flags: {
|
|
6
|
+
engineEnforcementEnabled?: boolean | null;
|
|
7
|
+
enabled?: boolean | null;
|
|
8
|
+
}): boolean;
|
|
9
|
+
//#endregion
|
|
10
|
+
export { normalizeChallengeType as n, isEngineEnforcing as t };
|
|
11
|
+
//# sourceMappingURL=engine-enforcing-DiOclGqf.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine-enforcing-DiOclGqf.d.mts","names":[],"sources":["../src/policy/challenge-type.ts","../src/policy/engine-enforcing.ts"],"mappings":";iBAQgB,uBACd;;;iBCFc,kBAAkB;EAChC;EACA"}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
//#region src/policy/challenge-type.d.ts
|
|
2
|
+
declare function normalizeChallengeType(challengeType: string | undefined): 'delegation' | 'browser_integrity' | 'human_step_up';
|
|
3
|
+
//#endregion
|
|
4
|
+
//#region src/policy/engine-enforcing.d.ts
|
|
5
|
+
declare function isEngineEnforcing(flags: {
|
|
6
|
+
engineEnforcementEnabled?: boolean | null;
|
|
7
|
+
enabled?: boolean | null;
|
|
8
|
+
}): boolean;
|
|
9
|
+
//#endregion
|
|
10
|
+
export { normalizeChallengeType as n, isEngineEnforcing as t };
|
|
11
|
+
//# sourceMappingURL=engine-enforcing-DiOclGqf.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine-enforcing-DiOclGqf.d.ts","names":[],"sources":["../src/policy/challenge-type.ts","../src/policy/engine-enforcing.ts"],"mappings":";iBAQgB,uBACd;;;iBCFc,kBAAkB;EAChC;EACA"}
|
package/dist/errors/index.d.mts
CHANGED
|
@@ -127,10 +127,14 @@ export declare const ERROR_CODES: {
|
|
|
127
127
|
readonly LOWERCASE_PROOF_VALIDATION_ERROR: "proof_validation_error";
|
|
128
128
|
readonly LOWERCASE_INSUFFICIENT_SCOPES: "insufficient_scopes";
|
|
129
129
|
readonly LOWERCASE_DELEGATION_VALIDATION_ERROR: "delegation_validation_error";
|
|
130
|
+
readonly GRANT_PREDATES_ISSUANCE_CORE: "grant_predates_issuance_core";
|
|
130
131
|
readonly LOWERCASE_INVALID_HTTP_REGISTRATION: "invalid_http_registration";
|
|
132
|
+
readonly LOWERCASE_POLICY_REVISION_MISMATCH: "policy_revision_mismatch";
|
|
133
|
+
readonly LOWERCASE_POLICY_REVISION_GRACE_UNAVAILABLE: "policy_revision_grace_unavailable";
|
|
131
134
|
readonly LOWERCASE_AUTHORIZATION_HOST_UNAVAILABLE: "authorization_host_unavailable";
|
|
132
135
|
readonly LOWERCASE_INVALID_JSON: "invalid_json";
|
|
133
136
|
readonly LOWERCASE_VALIDATION_ERROR: "validation_error";
|
|
137
|
+
readonly LOWERCASE_INVALID_CURSOR: "invalid_cursor";
|
|
134
138
|
readonly BARE_VALIDATION_ERROR: "VALIDATION_ERROR";
|
|
135
139
|
readonly BARE_INTERNAL_ERROR: "INTERNAL_ERROR";
|
|
136
140
|
readonly BARE_INVALID_REQUEST: "INVALID_REQUEST";
|
|
@@ -165,6 +169,7 @@ export declare const ERROR_CODES: {
|
|
|
165
169
|
readonly CONTENT_TYPE_NOT_SUPPORTED: "API_CONTENT_TYPE_NOT_SUPPORTED";
|
|
166
170
|
readonly RESPONSE_TOO_LARGE: "API_RESPONSE_TOO_LARGE";
|
|
167
171
|
readonly REQUEST_TOO_LARGE: "API_REQUEST_TOO_LARGE";
|
|
172
|
+
readonly ENDPOINT_RETIRED: "API_ENDPOINT_RETIRED";
|
|
168
173
|
readonly PIXEL_NOT_FOUND: "PIXEL_NOT_FOUND";
|
|
169
174
|
readonly PIXEL_DISABLED: "PIXEL_DISABLED";
|
|
170
175
|
readonly PIXEL_CONFIGURATION_ERROR: "PIXEL_CONFIGURATION_ERROR";
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/constants/errors.ts","../../src/constants/pick-error-codes.ts"],"mappings":";
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/constants/errors.ts","../../src/constants/pick-error-codes.ts"],"mappings":";qBA8Xa;;;;;;;;;;;;;;;;;;;;;;qBA4FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BD,oBAAoB,0BAA0B;qBAK7C,gBAAgB,OAAO;qBAuVvB,oBAAoB,QAAQ,OAAO;;;KCh1BpC,4BAA4B;KAE5B,iBAAiB,mBAAmB,8BACpC,KAAK,oBAAoB,aAAa;wBAUlC,qBAAqB,mBAAmB,gBACtD,MAAM,IACL,iBAAiB"}
|
package/dist/errors/index.d.ts
CHANGED
|
@@ -127,10 +127,14 @@ export declare const ERROR_CODES: {
|
|
|
127
127
|
readonly LOWERCASE_PROOF_VALIDATION_ERROR: "proof_validation_error";
|
|
128
128
|
readonly LOWERCASE_INSUFFICIENT_SCOPES: "insufficient_scopes";
|
|
129
129
|
readonly LOWERCASE_DELEGATION_VALIDATION_ERROR: "delegation_validation_error";
|
|
130
|
+
readonly GRANT_PREDATES_ISSUANCE_CORE: "grant_predates_issuance_core";
|
|
130
131
|
readonly LOWERCASE_INVALID_HTTP_REGISTRATION: "invalid_http_registration";
|
|
132
|
+
readonly LOWERCASE_POLICY_REVISION_MISMATCH: "policy_revision_mismatch";
|
|
133
|
+
readonly LOWERCASE_POLICY_REVISION_GRACE_UNAVAILABLE: "policy_revision_grace_unavailable";
|
|
131
134
|
readonly LOWERCASE_AUTHORIZATION_HOST_UNAVAILABLE: "authorization_host_unavailable";
|
|
132
135
|
readonly LOWERCASE_INVALID_JSON: "invalid_json";
|
|
133
136
|
readonly LOWERCASE_VALIDATION_ERROR: "validation_error";
|
|
137
|
+
readonly LOWERCASE_INVALID_CURSOR: "invalid_cursor";
|
|
134
138
|
readonly BARE_VALIDATION_ERROR: "VALIDATION_ERROR";
|
|
135
139
|
readonly BARE_INTERNAL_ERROR: "INTERNAL_ERROR";
|
|
136
140
|
readonly BARE_INVALID_REQUEST: "INVALID_REQUEST";
|
|
@@ -165,6 +169,7 @@ export declare const ERROR_CODES: {
|
|
|
165
169
|
readonly CONTENT_TYPE_NOT_SUPPORTED: "API_CONTENT_TYPE_NOT_SUPPORTED";
|
|
166
170
|
readonly RESPONSE_TOO_LARGE: "API_RESPONSE_TOO_LARGE";
|
|
167
171
|
readonly REQUEST_TOO_LARGE: "API_REQUEST_TOO_LARGE";
|
|
172
|
+
readonly ENDPOINT_RETIRED: "API_ENDPOINT_RETIRED";
|
|
168
173
|
readonly PIXEL_NOT_FOUND: "PIXEL_NOT_FOUND";
|
|
169
174
|
readonly PIXEL_DISABLED: "PIXEL_DISABLED";
|
|
170
175
|
readonly PIXEL_CONFIGURATION_ERROR: "PIXEL_CONFIGURATION_ERROR";
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/constants/errors.ts","../../src/constants/pick-error-codes.ts"],"mappings":";
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/constants/errors.ts","../../src/constants/pick-error-codes.ts"],"mappings":";qBA8Xa;;;;;;;;;;;;;;;;;;;;;;qBA4FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BD,oBAAoB,0BAA0B;qBAK7C,gBAAgB,OAAO;qBAuVvB,oBAAoB,QAAQ,OAAO;;;KCh1BpC,4BAA4B;KAE5B,iBAAiB,mBAAmB,8BACpC,KAAK,oBAAoB,aAAa;wBAUlC,qBAAqB,mBAAmB,gBACtD,MAAM,IACL,iBAAiB"}
|