@kya-os/checkpoint-shared 1.2.1 → 1.3.1

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 (68) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +1 -1
  3. package/dist/beacon-types/index.d.mts +13 -2
  4. package/dist/beacon-types/index.d.ts +13 -2
  5. package/dist/beacon-types/index.js +35 -3
  6. package/dist/beacon-types/index.mjs +35 -4
  7. package/dist/browser-posture-report.d.mts +85 -0
  8. package/dist/browser-posture-report.d.ts +85 -0
  9. package/dist/browser-posture-report.js +1 -0
  10. package/dist/browser-posture-report.mjs +1 -0
  11. package/dist/browser-posture.d.mts +114 -0
  12. package/dist/browser-posture.d.ts +114 -0
  13. package/dist/browser-posture.js +4204 -0
  14. package/dist/browser-posture.mjs +4187 -0
  15. package/dist/browser.d.mts +35 -1
  16. package/dist/browser.d.ts +35 -1
  17. package/dist/browser.js +1 -1
  18. package/dist/browser.mjs +1 -1
  19. package/dist/canonical-signer/index.js +31 -2
  20. package/dist/canonical-signer/index.mjs +31 -2
  21. package/dist/deploy/index.d.mts +449 -2
  22. package/dist/deploy/index.d.ts +449 -2
  23. package/dist/deploy/index.js +238 -1
  24. package/dist/deploy/index.mjs +228 -2
  25. package/dist/errors/index.d.mts +104 -0
  26. package/dist/errors/index.d.ts +104 -0
  27. package/dist/errors/index.js +338 -0
  28. package/dist/errors/index.mjs +333 -0
  29. package/dist/gateway/index.d.mts +6 -1
  30. package/dist/gateway/index.d.ts +6 -1
  31. package/dist/gateway/index.js +4 -0
  32. package/dist/gateway/index.mjs +4 -1
  33. package/dist/index.d.mts +2388 -851
  34. package/dist/index.d.ts +2388 -851
  35. package/dist/index.js +2684 -686
  36. package/dist/index.mjs +2575 -669
  37. package/dist/mcpi/multibase-ed25519.d.mts +8 -0
  38. package/dist/mcpi/multibase-ed25519.d.ts +8 -0
  39. package/dist/mcpi/multibase-ed25519.js +125 -0
  40. package/dist/mcpi/multibase-ed25519.mjs +119 -0
  41. package/dist/signals/index.d.mts +158 -0
  42. package/dist/signals/index.d.ts +158 -0
  43. package/dist/signals/index.js +1667 -0
  44. package/dist/signals/index.mjs +1637 -0
  45. package/dist/test-fixtures/index.d.mts +37 -1
  46. package/dist/test-fixtures/index.d.ts +37 -1
  47. package/dist/test-fixtures/index.js +92 -1
  48. package/dist/test-fixtures/index.mjs +87 -2
  49. package/fixtures/client-ip-resolution.json +103 -0
  50. package/fixtures/detection/reason-codes.json +35 -0
  51. package/fixtures/detection/signal-exposure-example.json +62 -0
  52. package/fixtures/kya-http/README.md +112 -0
  53. package/fixtures/kya-http/challenge-proof.canonical.json +25 -0
  54. package/fixtures/kya-http/challenge.approval-quorum.json +37 -0
  55. package/fixtures/kya-http/challenge.delegation.fetcher-200.json +55 -0
  56. package/fixtures/kya-http/challenge.delegation.full.json +81 -0
  57. package/fixtures/kya-http/challenge.delegation.minimal.json +57 -0
  58. package/fixtures/kya-http/error-codes.json +35 -0
  59. package/fixtures/kya-http/fetcher-200-predicate.vectors.json +72 -0
  60. package/fixtures/kya-http/negative.challenges.json +54 -0
  61. package/fixtures/kya-http/pickup.transcript.json +96 -0
  62. package/fixtures/kya-http/pickup.transcript.quorum.json +156 -0
  63. package/fixtures/kya-http/protected-resource-metadata.full.json +30 -0
  64. package/fixtures/kya-http/protected-resource-metadata.global.json +28 -0
  65. package/fixtures/kya-http/registration.request.json +33 -0
  66. package/fixtures/kya-http/registration.response.json +32 -0
  67. package/package.json +42 -9
  68. package/src/data/compiled/merged-rules.json +8 -2
@@ -91,8 +91,44 @@ interface FetcherEnvelopePredicateVector {
91
91
  description: string;
92
92
  headers: Record<string, string>;
93
93
  detectionClass: FetcherPredicateDetectionClass;
94
+ isAgent: boolean;
94
95
  expected: boolean;
95
96
  }
96
97
  declare const FETCHER_200_PREDICATE_VECTORS: readonly FetcherEnvelopePredicateVector[];
97
98
 
98
- export { FETCHER_200_PREDICATE_VECTORS, type FetcherEnvelopePredicateVector, type FetcherPredicateDetectionClass, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH };
99
+ type DelegationVerdictKind = 'Permit' | 'Block';
100
+ type CoarseReasonKind = 'signature' | 'claim' | 'time' | 'revocation' | 'scope' | 'resolve';
101
+ interface DelegationVerdictReason {
102
+ kind: CoarseReasonKind;
103
+ }
104
+ interface DelegationVerdict {
105
+ kind: DelegationVerdictKind;
106
+ reason: DelegationVerdictReason | null;
107
+ }
108
+ declare function toCoarseReasonKind(rawReasonKind: string): CoarseReasonKind;
109
+ declare function permitDelegationVerdict(): DelegationVerdict;
110
+ declare function blockDelegationVerdict(rawReasonKind: string): DelegationVerdict;
111
+
112
+ declare function detectionSignalFixture(overrides?: Partial<{
113
+ signalType: 'signature' | 'pattern' | 'behavioral' | 'network' | 'fingerprint';
114
+ confidence: number;
115
+ weight: number;
116
+ source: string;
117
+ explanation: string;
118
+ }>): {
119
+ signalType: "signature" | "pattern" | "behavioral" | "network" | "fingerprint";
120
+ confidence: number;
121
+ weight: number;
122
+ source: string;
123
+ explanation: string;
124
+ };
125
+ declare const TWO_SIGNAL_EVIDENCE_FIXTURE: {
126
+ signalType: "signature" | "pattern" | "behavioral" | "network" | "fingerprint";
127
+ confidence: number;
128
+ weight: number;
129
+ source: string;
130
+ explanation: string;
131
+ }[];
132
+ declare const TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = 94.78;
133
+
134
+ export { type CoarseReasonKind, type DelegationVerdict, type DelegationVerdictKind, type DelegationVerdictReason, FETCHER_200_PREDICATE_VECTORS, type FetcherEnvelopePredicateVector, type FetcherPredicateDetectionClass, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE, TWO_SIGNAL_EVIDENCE_FIXTURE, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH, blockDelegationVerdict, detectionSignalFixture, permitDelegationVerdict, toCoarseReasonKind };
@@ -91,8 +91,44 @@ interface FetcherEnvelopePredicateVector {
91
91
  description: string;
92
92
  headers: Record<string, string>;
93
93
  detectionClass: FetcherPredicateDetectionClass;
94
+ isAgent: boolean;
94
95
  expected: boolean;
95
96
  }
96
97
  declare const FETCHER_200_PREDICATE_VECTORS: readonly FetcherEnvelopePredicateVector[];
97
98
 
98
- export { FETCHER_200_PREDICATE_VECTORS, type FetcherEnvelopePredicateVector, type FetcherPredicateDetectionClass, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH };
99
+ type DelegationVerdictKind = 'Permit' | 'Block';
100
+ type CoarseReasonKind = 'signature' | 'claim' | 'time' | 'revocation' | 'scope' | 'resolve';
101
+ interface DelegationVerdictReason {
102
+ kind: CoarseReasonKind;
103
+ }
104
+ interface DelegationVerdict {
105
+ kind: DelegationVerdictKind;
106
+ reason: DelegationVerdictReason | null;
107
+ }
108
+ declare function toCoarseReasonKind(rawReasonKind: string): CoarseReasonKind;
109
+ declare function permitDelegationVerdict(): DelegationVerdict;
110
+ declare function blockDelegationVerdict(rawReasonKind: string): DelegationVerdict;
111
+
112
+ declare function detectionSignalFixture(overrides?: Partial<{
113
+ signalType: 'signature' | 'pattern' | 'behavioral' | 'network' | 'fingerprint';
114
+ confidence: number;
115
+ weight: number;
116
+ source: string;
117
+ explanation: string;
118
+ }>): {
119
+ signalType: "signature" | "pattern" | "behavioral" | "network" | "fingerprint";
120
+ confidence: number;
121
+ weight: number;
122
+ source: string;
123
+ explanation: string;
124
+ };
125
+ declare const TWO_SIGNAL_EVIDENCE_FIXTURE: {
126
+ signalType: "signature" | "pattern" | "behavioral" | "network" | "fingerprint";
127
+ confidence: number;
128
+ weight: number;
129
+ source: string;
130
+ explanation: string;
131
+ }[];
132
+ declare const TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = 94.78;
133
+
134
+ export { type CoarseReasonKind, type DelegationVerdict, type DelegationVerdictKind, type DelegationVerdictReason, FETCHER_200_PREDICATE_VECTORS, type FetcherEnvelopePredicateVector, type FetcherPredicateDetectionClass, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE, TWO_SIGNAL_EVIDENCE_FIXTURE, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH, blockDelegationVerdict, detectionSignalFixture, permitDelegationVerdict, toCoarseReasonKind };
@@ -110,58 +110,143 @@ var FETCHER_200_PREDICATE_VECTORS = [
110
110
  description: "opt-in header present, non-agent detection \u2192 200 (header is the primary signal)",
111
111
  headers: { "kya-accept-challenge": "delegation" },
112
112
  detectionClass: "human",
113
+ isAgent: false,
113
114
  expected: true
114
115
  },
115
116
  {
116
117
  description: "opt-in header present, detection absent \u2192 200",
117
118
  headers: { "kya-accept-challenge": "delegation" },
118
119
  detectionClass: null,
120
+ isAgent: false,
119
121
  expected: true
120
122
  },
121
123
  {
122
- description: "detected ai_agent, no opt-in \u2192 200 (transitional UA heuristic)",
124
+ description: "detected ai_agent (isAgent agrees), no opt-in \u2192 200 (transitional UA heuristic)",
123
125
  headers: {},
124
126
  detectionClass: "ai_agent",
127
+ isAgent: true,
125
128
  expected: true
126
129
  },
127
130
  {
128
131
  description: "Accept: text/html on a detected agent \u2192 200 (Accept MUST NOT branch the body)",
129
132
  headers: { accept: "text/markdown, text/html, */*" },
130
133
  detectionClass: "ai_agent",
134
+ isAgent: true,
131
135
  expected: true
132
136
  },
137
+ {
138
+ description: "ai_agent class but isAgent=false (signals disagree) \u2192 401 (require both, matches .NET + worker)",
139
+ headers: {},
140
+ detectionClass: "ai_agent",
141
+ isAgent: false,
142
+ expected: false
143
+ },
133
144
  {
134
145
  description: "human, no opt-in \u2192 401 (spec path)",
135
146
  headers: {},
136
147
  detectionClass: "human",
148
+ isAgent: false,
137
149
  expected: false
138
150
  },
139
151
  {
140
152
  description: "bot, no opt-in \u2192 401 (non-cooperative / spoofer lands on spec path)",
141
153
  headers: {},
142
154
  detectionClass: "bot",
155
+ isAgent: false,
143
156
  expected: false
144
157
  },
145
158
  {
146
159
  description: "incomplete_data, no opt-in \u2192 401",
147
160
  headers: {},
148
161
  detectionClass: "incomplete_data",
162
+ isAgent: false,
149
163
  expected: false
150
164
  },
151
165
  {
152
166
  description: "no signals at all \u2192 401",
153
167
  headers: {},
154
168
  detectionClass: null,
169
+ isAgent: false,
155
170
  expected: false
156
171
  },
157
172
  {
158
173
  description: "empty opt-in value is ignored, human \u2192 401",
159
174
  headers: { "kya-accept-challenge": "" },
160
175
  detectionClass: "human",
176
+ isAgent: false,
161
177
  expected: false
162
178
  }
163
179
  ];
164
180
 
181
+ // src/mcpi/delegation-verdict.ts
182
+ var REASON_KIND_MAP = {
183
+ // --- gateway: apps/gateway/src/lib/mcpi-auth-resolver.ts ---
184
+ missing_bearer_token: "claim",
185
+ parse_error: "claim",
186
+ did_resolve_failed: "resolve",
187
+ signature_invalid: "signature",
188
+ audience_mismatch: "claim",
189
+ expired: "time",
190
+ not_yet_valid: "time",
191
+ revoked: "revocation",
192
+ delegation_inactive: "revocation",
193
+ missing_claim: "claim",
194
+ claim_invalid: "claim",
195
+ // --- gateway: apps/gateway/src/lib/dashboard-delegation-verifier.ts ---
196
+ not_configured: "claim",
197
+ header_missing: "claim",
198
+ claim_mismatch: "claim",
199
+ malformed: "claim",
200
+ // --- engine-rust: rust/crates/kya-os-engine/src/types.rs BlockReason ---
201
+ Revoked: "revocation",
202
+ InvalidSignature: "signature",
203
+ Unauthenticated: "claim",
204
+ Expired: "time",
205
+ OutOfScope: "scope"
206
+ };
207
+ function toCoarseReasonKind(rawReasonKind) {
208
+ const coarse = REASON_KIND_MAP[rawReasonKind];
209
+ if (!coarse) {
210
+ throw new Error(
211
+ `toCoarseReasonKind: unrecognized raw reason kind ${JSON.stringify(rawReasonKind)} \u2014 add it to REASON_KIND_MAP in delegation-verdict.ts with a deliberate coarse classification`
212
+ );
213
+ }
214
+ return coarse;
215
+ }
216
+ function permitDelegationVerdict() {
217
+ return { kind: "Permit", reason: null };
218
+ }
219
+ function blockDelegationVerdict(rawReasonKind) {
220
+ return { kind: "Block", reason: { kind: toCoarseReasonKind(rawReasonKind) } };
221
+ }
222
+
223
+ // src/test-fixtures/verdict-evidence-fixture.ts
224
+ function detectionSignalFixture(overrides = {}) {
225
+ return {
226
+ signalType: "pattern",
227
+ confidence: 80,
228
+ weight: 0.4,
229
+ source: "tier3_ua_pattern",
230
+ explanation: "Matches a known agent UA pattern",
231
+ ...overrides
232
+ };
233
+ }
234
+ var TWO_SIGNAL_EVIDENCE_FIXTURE = [
235
+ detectionSignalFixture({
236
+ source: "known_scraper_ua",
237
+ signalType: "pattern",
238
+ weight: 1,
239
+ confidence: 90
240
+ }),
241
+ detectionSignalFixture({
242
+ source: "datacenter_ip",
243
+ signalType: "network",
244
+ weight: 0.6,
245
+ confidence: 70
246
+ })
247
+ ];
248
+ var TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = 94.78;
249
+
165
250
  exports.FETCHER_200_PREDICATE_VECTORS = FETCHER_200_PREDICATE_VECTORS;
166
251
  exports.MCPI_DELEGATION_AGENT_DID = MCPI_DELEGATION_AGENT_DID;
167
252
  exports.MCPI_DELEGATION_AUDIENCE = MCPI_DELEGATION_AUDIENCE;
@@ -173,9 +258,15 @@ exports.MCPI_DELEGATION_ISSUER_KID = MCPI_DELEGATION_ISSUER_KID;
173
258
  exports.MCPI_DELEGATION_STATUS_LIST_URL = MCPI_DELEGATION_STATUS_LIST_URL;
174
259
  exports.MCPI_DELEGATION_TEST_KEYPAIR = MCPI_DELEGATION_TEST_KEYPAIR;
175
260
  exports.MCPI_DELEGATION_USER_DID = MCPI_DELEGATION_USER_DID;
261
+ exports.TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE;
262
+ exports.TWO_SIGNAL_EVIDENCE_FIXTURE = TWO_SIGNAL_EVIDENCE_FIXTURE;
176
263
  exports.VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD = VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD;
177
264
  exports.VAULT_WIRE_CONTRACT_EXPECTED_HEADER = VAULT_WIRE_CONTRACT_EXPECTED_HEADER;
178
265
  exports.VAULT_WIRE_CONTRACT_EXPECTED_JWT = VAULT_WIRE_CONTRACT_EXPECTED_JWT;
179
266
  exports.VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY = VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY;
180
267
  exports.VAULT_WIRE_CONTRACT_TEST_KEYPAIR = VAULT_WIRE_CONTRACT_TEST_KEYPAIR;
181
268
  exports.VAULT_WIRE_CONTRACT_URL_PATH = VAULT_WIRE_CONTRACT_URL_PATH;
269
+ exports.blockDelegationVerdict = blockDelegationVerdict;
270
+ exports.detectionSignalFixture = detectionSignalFixture;
271
+ exports.permitDelegationVerdict = permitDelegationVerdict;
272
+ exports.toCoarseReasonKind = toCoarseReasonKind;
@@ -108,56 +108,141 @@ var FETCHER_200_PREDICATE_VECTORS = [
108
108
  description: "opt-in header present, non-agent detection \u2192 200 (header is the primary signal)",
109
109
  headers: { "kya-accept-challenge": "delegation" },
110
110
  detectionClass: "human",
111
+ isAgent: false,
111
112
  expected: true
112
113
  },
113
114
  {
114
115
  description: "opt-in header present, detection absent \u2192 200",
115
116
  headers: { "kya-accept-challenge": "delegation" },
116
117
  detectionClass: null,
118
+ isAgent: false,
117
119
  expected: true
118
120
  },
119
121
  {
120
- description: "detected ai_agent, no opt-in \u2192 200 (transitional UA heuristic)",
122
+ description: "detected ai_agent (isAgent agrees), no opt-in \u2192 200 (transitional UA heuristic)",
121
123
  headers: {},
122
124
  detectionClass: "ai_agent",
125
+ isAgent: true,
123
126
  expected: true
124
127
  },
125
128
  {
126
129
  description: "Accept: text/html on a detected agent \u2192 200 (Accept MUST NOT branch the body)",
127
130
  headers: { accept: "text/markdown, text/html, */*" },
128
131
  detectionClass: "ai_agent",
132
+ isAgent: true,
129
133
  expected: true
130
134
  },
135
+ {
136
+ description: "ai_agent class but isAgent=false (signals disagree) \u2192 401 (require both, matches .NET + worker)",
137
+ headers: {},
138
+ detectionClass: "ai_agent",
139
+ isAgent: false,
140
+ expected: false
141
+ },
131
142
  {
132
143
  description: "human, no opt-in \u2192 401 (spec path)",
133
144
  headers: {},
134
145
  detectionClass: "human",
146
+ isAgent: false,
135
147
  expected: false
136
148
  },
137
149
  {
138
150
  description: "bot, no opt-in \u2192 401 (non-cooperative / spoofer lands on spec path)",
139
151
  headers: {},
140
152
  detectionClass: "bot",
153
+ isAgent: false,
141
154
  expected: false
142
155
  },
143
156
  {
144
157
  description: "incomplete_data, no opt-in \u2192 401",
145
158
  headers: {},
146
159
  detectionClass: "incomplete_data",
160
+ isAgent: false,
147
161
  expected: false
148
162
  },
149
163
  {
150
164
  description: "no signals at all \u2192 401",
151
165
  headers: {},
152
166
  detectionClass: null,
167
+ isAgent: false,
153
168
  expected: false
154
169
  },
155
170
  {
156
171
  description: "empty opt-in value is ignored, human \u2192 401",
157
172
  headers: { "kya-accept-challenge": "" },
158
173
  detectionClass: "human",
174
+ isAgent: false,
159
175
  expected: false
160
176
  }
161
177
  ];
162
178
 
163
- export { FETCHER_200_PREDICATE_VECTORS, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH };
179
+ // src/mcpi/delegation-verdict.ts
180
+ var REASON_KIND_MAP = {
181
+ // --- gateway: apps/gateway/src/lib/mcpi-auth-resolver.ts ---
182
+ missing_bearer_token: "claim",
183
+ parse_error: "claim",
184
+ did_resolve_failed: "resolve",
185
+ signature_invalid: "signature",
186
+ audience_mismatch: "claim",
187
+ expired: "time",
188
+ not_yet_valid: "time",
189
+ revoked: "revocation",
190
+ delegation_inactive: "revocation",
191
+ missing_claim: "claim",
192
+ claim_invalid: "claim",
193
+ // --- gateway: apps/gateway/src/lib/dashboard-delegation-verifier.ts ---
194
+ not_configured: "claim",
195
+ header_missing: "claim",
196
+ claim_mismatch: "claim",
197
+ malformed: "claim",
198
+ // --- engine-rust: rust/crates/kya-os-engine/src/types.rs BlockReason ---
199
+ Revoked: "revocation",
200
+ InvalidSignature: "signature",
201
+ Unauthenticated: "claim",
202
+ Expired: "time",
203
+ OutOfScope: "scope"
204
+ };
205
+ function toCoarseReasonKind(rawReasonKind) {
206
+ const coarse = REASON_KIND_MAP[rawReasonKind];
207
+ if (!coarse) {
208
+ throw new Error(
209
+ `toCoarseReasonKind: unrecognized raw reason kind ${JSON.stringify(rawReasonKind)} \u2014 add it to REASON_KIND_MAP in delegation-verdict.ts with a deliberate coarse classification`
210
+ );
211
+ }
212
+ return coarse;
213
+ }
214
+ function permitDelegationVerdict() {
215
+ return { kind: "Permit", reason: null };
216
+ }
217
+ function blockDelegationVerdict(rawReasonKind) {
218
+ return { kind: "Block", reason: { kind: toCoarseReasonKind(rawReasonKind) } };
219
+ }
220
+
221
+ // src/test-fixtures/verdict-evidence-fixture.ts
222
+ function detectionSignalFixture(overrides = {}) {
223
+ return {
224
+ signalType: "pattern",
225
+ confidence: 80,
226
+ weight: 0.4,
227
+ source: "tier3_ua_pattern",
228
+ explanation: "Matches a known agent UA pattern",
229
+ ...overrides
230
+ };
231
+ }
232
+ var TWO_SIGNAL_EVIDENCE_FIXTURE = [
233
+ detectionSignalFixture({
234
+ source: "known_scraper_ua",
235
+ signalType: "pattern",
236
+ weight: 1,
237
+ confidence: 90
238
+ }),
239
+ detectionSignalFixture({
240
+ source: "datacenter_ip",
241
+ signalType: "network",
242
+ weight: 0.6,
243
+ confidence: 70
244
+ })
245
+ ];
246
+ var TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = 94.78;
247
+
248
+ export { FETCHER_200_PREDICATE_VECTORS, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE, TWO_SIGNAL_EVIDENCE_FIXTURE, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH, blockDelegationVerdict, detectionSignalFixture, permitDelegationVerdict, toCoarseReasonKind };
@@ -0,0 +1,103 @@
1
+ [
2
+ {
3
+ "name": "vercel platform header wins over caller-set headers",
4
+ "headers": {
5
+ "x-vercel-forwarded-for": "203.0.113.9",
6
+ "x-forwarded-for": "6.6.6.6",
7
+ "x-real-ip": "198.51.100.4"
8
+ },
9
+ "policy": { "platform": "vercel" },
10
+ "expected": { "ip": "203.0.113.9", "source": "x-vercel-forwarded-for", "trusted": true }
11
+ },
12
+ {
13
+ "name": "vercel uses its overwritten XFF when the platform-specific header is absent",
14
+ "headers": { "x-forwarded-for": "203.0.113.10, 192.0.2.4" },
15
+ "policy": { "platform": "vercel" },
16
+ "expected": { "ip": "203.0.113.10", "source": "x-forwarded-for", "trusted": true }
17
+ },
18
+ {
19
+ "name": "vercel marks X-Real-IP observational when platform values are absent",
20
+ "headers": { "x-real-ip": "198.51.100.4" },
21
+ "policy": { "platform": "vercel" },
22
+ "expected": { "ip": "198.51.100.4", "source": "x-real-ip", "trusted": false }
23
+ },
24
+ {
25
+ "name": "cloudflare CF-Connecting-IP wins and ignores spoofed XFF",
26
+ "headers": { "cf-connecting-ip": "203.0.113.11", "x-forwarded-for": "6.6.6.6" },
27
+ "policy": { "platform": "cloudflare" },
28
+ "expected": { "ip": "203.0.113.11", "source": "cf-connecting-ip", "trusted": true }
29
+ },
30
+ {
31
+ "name": "cloudflare falls back to the worker socket",
32
+ "headers": { "x-forwarded-for": "6.6.6.6" },
33
+ "directAddress": "192.0.2.10",
34
+ "policy": { "platform": "cloudflare" },
35
+ "expected": { "ip": "192.0.2.10", "source": "socket", "trusted": true }
36
+ },
37
+ {
38
+ "name": "cloudflare observational fallback is untrusted",
39
+ "headers": { "x-forwarded-for": "6.6.6.6" },
40
+ "policy": { "platform": "cloudflare" },
41
+ "expected": { "ip": "6.6.6.6", "source": "x-forwarded-for", "trusted": false }
42
+ },
43
+ {
44
+ "name": "trusted proxy selects the first untrusted hop from the trusted side",
45
+ "headers": { "x-forwarded-for": "203.0.113.12, 198.51.100.10, 192.0.2.10" },
46
+ "policy": { "platform": "trusted-proxy", "trustedHops": 2 },
47
+ "expected": { "ip": "203.0.113.12", "source": "x-forwarded-for", "trusted": true }
48
+ },
49
+ {
50
+ "name": "trusted proxy does not shift around an invalid token",
51
+ "headers": { "x-forwarded-for": "203.0.113.13, invalid, 192.0.2.10" },
52
+ "frameworkAddress": "192.0.2.20",
53
+ "policy": { "platform": "trusted-proxy", "trustedHops": 2 },
54
+ "expected": { "ip": "192.0.2.20", "source": "framework", "trusted": true }
55
+ },
56
+ {
57
+ "name": "direct ignores all forwarding headers",
58
+ "headers": { "x-forwarded-for": "6.6.6.6", "cf-connecting-ip": "203.0.113.14" },
59
+ "directAddress": "192.0.2.30",
60
+ "policy": { "platform": "direct" },
61
+ "expected": { "ip": "192.0.2.30", "source": "socket", "trusted": true }
62
+ },
63
+ {
64
+ "name": "authenticated explicit address wins",
65
+ "headers": { "x-forwarded-for": "6.6.6.6" },
66
+ "explicitAddress": "[2001:db8::1]:443",
67
+ "explicitAddressTrusted": true,
68
+ "policy": { "platform": "direct" },
69
+ "expected": { "ip": "2001:db8::1", "source": "explicit", "trusted": true }
70
+ },
71
+ {
72
+ "name": "unauthenticated explicit address is not honored",
73
+ "headers": {},
74
+ "explicitAddress": "203.0.113.15",
75
+ "policy": { "platform": "direct" },
76
+ "expected": { "ip": null, "source": "none", "trusted": false }
77
+ },
78
+ {
79
+ "name": "IPv4 port is removed",
80
+ "headers": { "x-real-ip": " 203.0.113.16:8443 " },
81
+ "policy": { "platform": "direct" },
82
+ "expected": { "ip": null, "source": "none", "trusted": false }
83
+ },
84
+ {
85
+ "name": "IPv6 is compressed and unbracketed",
86
+ "headers": { "x-real-ip": "[2001:0db8:0:0:0:0:0:1]:443" },
87
+ "frameworkAddress": "2001:db8::2",
88
+ "policy": { "platform": "vercel" },
89
+ "expected": { "ip": "2001:db8::1", "source": "x-real-ip", "trusted": false }
90
+ },
91
+ {
92
+ "name": "IPv4-mapped IPv6 is normalized",
93
+ "headers": { "x-real-ip": "::ffff:192.0.2.1" },
94
+ "policy": { "platform": "vercel" },
95
+ "expected": { "ip": "::ffff:c000:201", "source": "x-real-ip", "trusted": false }
96
+ },
97
+ {
98
+ "name": "control characters are rejected",
99
+ "headers": { "x-real-ip": "203.0.113.17\r\nX-Admin: true" },
100
+ "policy": { "platform": "vercel" },
101
+ "expected": { "ip": null, "source": "none", "trusted": false }
102
+ }
103
+ ]
@@ -0,0 +1,35 @@
1
+ {
2
+ "$fixture": "detection/reason-codes",
3
+ "$spec": "GODPROMPTS/detection-reason-codes — detection reason codes on the wire",
4
+ "description": "The detection/* reason-code registry: a worker-side machine-readable projection of the engine's structured detection evidence (signals[], verificationMethod, detectionClass, isAiCrawler) onto the KYA-Reason-Codes wire header and persisted detection metadata. Emitters MUST use these exact strings.",
5
+ "verified": {
6
+ "detection/signature-verified": "verificationMethod === 'kya-http'",
7
+ "detection/delegation-verified": "verificationMethod === 'kya-http-delegated'",
8
+ "detection/mcp-i-verified": "verificationMethod === 'mcp-i' | 'kya-os' (wire values; isKyaOsWireMethod)",
9
+ "detection/did-signature-verified": "verificationMethod === 'did'",
10
+ "detection/rfc9421-signature-verified": "verificationMethod === 'signature'",
11
+ "detection/tier1-attribution-verified": "verificationMethod starts with 'tier1_'",
12
+ "detection/verification-error": "verificationMethod === 'error'"
13
+ },
14
+ "signal": {
15
+ "detection/ua-pattern-match": "a signals[] entry with source === 'user_agent_pattern'",
16
+ "detection/header-heuristic": "source === 'header_heuristic'",
17
+ "detection/ip-heuristic": "source === 'ip_heuristic'",
18
+ "detection/vendor-ip-corroborated": "source === 'vendor_ip_feed'",
19
+ "detection/ja4-fingerprint-match": "source === 'transport.ja4'",
20
+ "detection/client-attribute-signal": "source === 'client.attributes'",
21
+ "detection/behavioral-signal": "source === 'behavioural.interaction'",
22
+ "detection/mcp-i-signal": "source === 'mcp_i'",
23
+ "detection/kya-http-binding-signal": "source === 'kya_http_binding'",
24
+ "detection/kya-delegation-bearer-signal": "source === 'kya_delegation_bearer'",
25
+ "detection/tier1-attribution-signal": "a signals[] entry whose source starts with 'tier1_'"
26
+ },
27
+ "flag": {
28
+ "detection/ai-crawler-flag": "isAiCrawler === true"
29
+ },
30
+ "fallback": {
31
+ "detection/zero-evidence-human": "detectionClass === 'human' with no contributing signals and no verification",
32
+ "detection/incomplete-data-override": "detectionClass === 'incomplete_data' | 'unknown' (or absent)",
33
+ "detection/classified-without-signal-evidence": "a non-human, non-incomplete-data class reached with zero contributing signals and no verification"
34
+ }
35
+ }
@@ -0,0 +1,62 @@
1
+ {
2
+ "$fixture": "detection/signal-exposure-example",
3
+ "$spec": "KYA-1107: one full POST /api/v1/enforce response showing the always-on signal exposure (the Adobe Golden Snapshot example). Captured verbatim from the route-level test (signal-exposure.test.ts) against the deterministic GPTBot engine mock, whose signals mirror the engine's real emission shapes (api.rs signal_detail / vendor_feed_signal_detail).",
4
+ "description": "The detection object's signals/reasonCodes/confidenceLevel/isAiCrawler fields are the exposure block carried on every detection payload; __tests__/signal-exposure.test.ts parses them against DetectionSignalExposureSchema, and generate-signal-exposure-docs.ts embeds this response verbatim in the generated reference, so example, schema, and docs stay in lockstep.",
5
+ "response": {
6
+ "success": true,
7
+ "data": {
8
+ "decision": {
9
+ "action": "allow",
10
+ "reason": "enforcement_disabled",
11
+ "isAgent": true,
12
+ "confidence": 96
13
+ },
14
+ "processingTimeMs": 0,
15
+ "requestId": "req_golden_1",
16
+ "detection": {
17
+ "isAgent": true,
18
+ "confidence": 96,
19
+ "detectionClass": "bot",
20
+ "agentName": "GPTBot",
21
+ "agentType": "GPTBot",
22
+ "verificationMethod": "pattern",
23
+ "reasons": ["Tier3UAMatch"],
24
+ "signals": [
25
+ {
26
+ "signalType": "pattern",
27
+ "confidence": 96,
28
+ "weight": 1,
29
+ "source": "user_agent_pattern",
30
+ "explanation": "User-Agent matched known agent pattern: GPTBot"
31
+ },
32
+ {
33
+ "signalType": "pattern",
34
+ "confidence": 60,
35
+ "weight": 0.4,
36
+ "source": "header_heuristic",
37
+ "explanation": "Header heuristic fired: missing_accept_language"
38
+ },
39
+ {
40
+ "signalType": "network",
41
+ "confidence": 92,
42
+ "weight": 1,
43
+ "source": "vendor_ip_feed",
44
+ "explanation": "Vendor IP + User-Agent cross-match: OpenAI",
45
+ "metadata": {
46
+ "vendor_id": "openai",
47
+ "tier": 2
48
+ }
49
+ }
50
+ ],
51
+ "reasonCodes": [
52
+ "detection/ua-pattern-match",
53
+ "detection/header-heuristic",
54
+ "detection/vendor-ip-corroborated",
55
+ "detection/ai-crawler-flag"
56
+ ],
57
+ "confidenceLevel": "very_high",
58
+ "isAiCrawler": true
59
+ }
60
+ }
61
+ }
62
+ }