@kya-os/checkpoint-shared 1.3.0 → 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 (52) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/dist/beacon-types/index.d.mts +3 -1
  3. package/dist/beacon-types/index.d.ts +3 -1
  4. package/dist/beacon-types/index.js +15 -2
  5. package/dist/beacon-types/index.mjs +15 -2
  6. package/dist/browser-posture-report.d.mts +85 -0
  7. package/dist/browser-posture-report.d.ts +85 -0
  8. package/dist/browser-posture-report.js +1 -0
  9. package/dist/browser-posture-report.mjs +1 -0
  10. package/dist/browser-posture.d.mts +114 -0
  11. package/dist/browser-posture.d.ts +114 -0
  12. package/dist/browser-posture.js +4204 -0
  13. package/dist/browser-posture.mjs +4187 -0
  14. package/dist/browser.d.mts +30 -1
  15. package/dist/browser.d.ts +30 -1
  16. package/dist/browser.js +1 -1
  17. package/dist/browser.mjs +1 -1
  18. package/dist/errors/index.d.mts +104 -0
  19. package/dist/errors/index.d.ts +104 -0
  20. package/dist/errors/index.js +338 -0
  21. package/dist/errors/index.mjs +333 -0
  22. package/dist/gateway/index.d.mts +6 -1
  23. package/dist/gateway/index.d.ts +6 -1
  24. package/dist/gateway/index.js +4 -0
  25. package/dist/gateway/index.mjs +4 -1
  26. package/dist/index.d.mts +769 -146
  27. package/dist/index.d.ts +769 -146
  28. package/dist/index.js +926 -282
  29. package/dist/index.mjs +903 -283
  30. package/dist/signals/index.d.mts +1 -1
  31. package/dist/signals/index.d.ts +1 -1
  32. package/dist/signals/index.js +95 -2
  33. package/dist/signals/index.mjs +95 -2
  34. package/fixtures/client-ip-resolution.json +103 -0
  35. package/fixtures/detection/reason-codes.json +35 -0
  36. package/fixtures/detection/signal-exposure-example.json +62 -0
  37. package/fixtures/kya-http/README.md +112 -0
  38. package/fixtures/kya-http/challenge-proof.canonical.json +25 -0
  39. package/fixtures/kya-http/challenge.approval-quorum.json +37 -0
  40. package/fixtures/kya-http/challenge.delegation.fetcher-200.json +55 -0
  41. package/fixtures/kya-http/challenge.delegation.full.json +81 -0
  42. package/fixtures/kya-http/challenge.delegation.minimal.json +57 -0
  43. package/fixtures/kya-http/error-codes.json +35 -0
  44. package/fixtures/kya-http/fetcher-200-predicate.vectors.json +72 -0
  45. package/fixtures/kya-http/negative.challenges.json +54 -0
  46. package/fixtures/kya-http/pickup.transcript.json +96 -0
  47. package/fixtures/kya-http/pickup.transcript.quorum.json +156 -0
  48. package/fixtures/kya-http/protected-resource-metadata.full.json +30 -0
  49. package/fixtures/kya-http/protected-resource-metadata.global.json +28 -0
  50. package/fixtures/kya-http/registration.request.json +33 -0
  51. package/fixtures/kya-http/registration.response.json +32 -0
  52. package/package.json +20 -2
@@ -51,7 +51,7 @@ declare function checkSensitiveAttributeCompliance(signal: SignalDefinition): {
51
51
  };
52
52
  declare function findSignalsNeedingReevaluation(signals: SignalDefinition[], currentVersion?: SensitiveRejectionListVersion): SignalDefinition[];
53
53
 
54
- declare const REGISTRY_VERSIONS: readonly ["v1", "v2"];
54
+ declare const REGISTRY_VERSIONS: readonly ["v1", "v2", "v3"];
55
55
  type RegistryVersion = (typeof REGISTRY_VERSIONS)[number];
56
56
  declare const CURRENT_REGISTRY_VERSION: RegistryVersion;
57
57
  type StabilityTier = 'high' | 'medium' | 'low';
@@ -51,7 +51,7 @@ declare function checkSensitiveAttributeCompliance(signal: SignalDefinition): {
51
51
  };
52
52
  declare function findSignalsNeedingReevaluation(signals: SignalDefinition[], currentVersion?: SensitiveRejectionListVersion): SignalDefinition[];
53
53
 
54
- declare const REGISTRY_VERSIONS: readonly ["v1", "v2"];
54
+ declare const REGISTRY_VERSIONS: readonly ["v1", "v2", "v3"];
55
55
  type RegistryVersion = (typeof REGISTRY_VERSIONS)[number];
56
56
  declare const CURRENT_REGISTRY_VERSION: RegistryVersion;
57
57
  type StabilityTier = 'high' | 'medium' | 'low';
@@ -4,7 +4,7 @@ var sha2_js = require('@noble/hashes/sha2.js');
4
4
  var utils_js = require('@noble/hashes/utils.js');
5
5
 
6
6
  // src/signals/types.ts
7
- var REGISTRY_VERSIONS = ["v1", "v2"];
7
+ var REGISTRY_VERSIONS = ["v1", "v2", "v3"];
8
8
  var CURRENT_REGISTRY_VERSION = REGISTRY_VERSIONS[REGISTRY_VERSIONS.length - 1];
9
9
  var FROZEN_FIELDS = ["id", "addedVersion", "denoise", "mode", "plane", "group"];
10
10
  var TIER_LOCKED_FIELDS = ["tier"];
@@ -292,6 +292,73 @@ function compliantReview() {
292
292
  rationale: "Raw device/browser entropy read; no plausible link to a Sensitive Data Inference category, individually or via a known composition-risk rule."
293
293
  };
294
294
  }
295
+ var INTERACTION_SIGNAL_IDS = [
296
+ "interaction.keyDwellUnder5Share",
297
+ "interaction.keyGapUnder5Share",
298
+ "interaction.pressUnder10Share",
299
+ "interaction.zeroTrailClickShare",
300
+ "interaction.untrustedInputShare",
301
+ "interaction.mousePerClick"
302
+ ];
303
+ function interactionReview(id) {
304
+ return {
305
+ listVersion: CURRENT_SENSITIVE_REJECTION_LIST_VERSION,
306
+ reviewedBy: "privacy-review@kya-os.example",
307
+ reviewedAt: "2026-09-03",
308
+ combinesWith: INTERACTION_SIGNAL_IDS.filter((other) => other !== id),
309
+ derivesCategory: null,
310
+ rationale: 'A per-visit share of input events below a physical floor (or a per-visit ratio of two event counts), derived from integer counters; no per-event timing, coordinate, or key identity is collected, so the read cannot reconstruct a typing or pointer rhythm and is not a biometric identifier or a derivative of one (mode: never, so it is excluded from identity linkage regardless). It reads 0 for a person at any speed, ability, or input method, since the floors sit below any hand; it therefore carries no information about a health condition or accommodation. Its only composition is interaction_integrity, a Noisy-OR over the other interaction shares, which derives "driven by software" and nothing about the person.'
311
+ };
312
+ }
313
+ function interactionSignals() {
314
+ const entry = (id, description, notes) => ({
315
+ id,
316
+ addedVersion: "v3",
317
+ removedVersion: null,
318
+ tier: "low",
319
+ measurement: provisional(notes),
320
+ denoise: { kind: "none" },
321
+ mode: "never",
322
+ plane: "behavioural",
323
+ group: "interaction",
324
+ u: null,
325
+ supersedes: null,
326
+ description,
327
+ review: interactionReview(id)
328
+ });
329
+ return [
330
+ entry(
331
+ "interaction.keyDwellUnder5Share",
332
+ "Share of paired keystrokes (keydown to keyup) held under 5ms; IME composition, left/right modifiers, and auto-repeat are not timed, and key timing stops once a finger has touched the page.",
333
+ "Lab gauntlet, two recordings and three driver rigs against production (plan P0.5): hand minimum dwell 39ms, share 0; CDP drivers 0-1ms on every key, share 1. Playwright type({ delay }) manufactures a hand dwell and reads 0: the timing rungs raise the bar and prove nothing, which is why the ladder ends in a challenge. Seeded from that corpus, not a stability harness; finalize once P3 calibration has the trap populations (IME, dictation, on-screen keyboard, switch access)."
334
+ ),
335
+ entry(
336
+ "interaction.keyGapUnder5Share",
337
+ "Share of timed keydown-to-next-keydown gaps within 2s that were under 5ms: a whole string arriving in one tick.",
338
+ "Same corpus: hand minimum gap 26ms, share 0; CDP drivers 0ms, share 0.97 to 1. AltGr (Control then Alt back to back) is excluded by the modifier guard; a held key auto-repeats without entering the gap count. Provisional pending the trap populations."
339
+ ),
340
+ entry(
341
+ "interaction.pressUnder10Share",
342
+ "Share of primary-pointer presses (pointerdown to pointerup) under 10ms; a second finger is not a press and a cancelled press does not pair with the next release.",
343
+ "Same corpus: hand minimum press 38ms, share 0; CDP drivers 2-7ms, share 0.8 to 1. Playwright click({ delay }) holds the press and reads 0. Provisional pending the touch and switch-access populations."
344
+ ),
345
+ entry(
346
+ "interaction.zeroTrailClickShare",
347
+ "Of clicks whose own pointerType is mouse and that follow at least one observed pointer move, the share with no mousemove or wheel in the preceding 300ms: a pointer that appeared on its target.",
348
+ "Same corpus: every hand click approached, share 0; Claude-in-Chrome 8 of 12 unapproached, the cdp rig 0.7. Taps, keyboard-activated buttons, and a click before any move has been seen are outside the denominator, so a cursor already resting on a button is unknown rather than a teleport. Weaker than the timing rungs (the plan weights it 0.4) because a scroll-then-click is an ordinary thing for a hand; provisional."
349
+ ),
350
+ entry(
351
+ "interaction.untrustedInputShare",
352
+ "Share of counted input events (throttled mousemove, keydown, scroll, click, touchstart) dispatched with isTrusted false: input from a script or extension rather than the browser reacting to hardware.",
353
+ "The content-script rung (#4842). A person's input is always trusted and the flag is browser-set and read-only, so it cannot be forged upward; the content-script rig reads 0.96 with human-shaped timing, and a CDP-driven browser reads 0 because its synthetic input arrives trusted, which is what the timing rungs above are for. Human baseline 0 of 15 windows. Provisional pending the autofill and accessibility-tool populations, whose events are trusted and should read 0."
354
+ ),
355
+ entry(
356
+ "interaction.mousePerClick",
357
+ "Throttled (50ms) mouse moves per mouse click over the visit; undefined on touch traffic, which fires no mousemove.",
358
+ "The backstop (#4806): a hand cannot reach a button without dragging the pointer across the screen (measured 33 moves per click) while a driver teleports (measured 2). Noisy on short windows (human 1 to 15 on 4s windows) and undefined for touch, so it is weighted 0.2 in the composite and read only as the mouse-only kinematics reading. Provisional."
359
+ )
360
+ ];
361
+ }
295
362
  var SIGNAL_REGISTRY = [
296
363
  // --- rendering plane ---------------------------------------------------
297
364
  {
@@ -1193,7 +1260,33 @@ var SIGNAL_REGISTRY = [
1193
1260
  supersedes: null,
1194
1261
  description: "UA-CH low-entropy mobile-device flag.",
1195
1262
  review: compliantReview()
1196
- }
1263
+ },
1264
+ // --- Interaction physics, contradiction-only (agentic-session plan P1.1) --
1265
+ // The behavioural plane's first entries. Each is a per-visit SHARE derived
1266
+ // server-side from integer counters the pixel's detector and the beacon's
1267
+ // InteractionCollector accumulate (apps/web/lib/detection/timing-physics.ts
1268
+ // reads both lanes through one function). They exist to tell a driven
1269
+ // browser from a person, never to say WHICH person: mode 'never', so none
1270
+ // enters identity linkage or the Merkle tree; tier 'low', because a share
1271
+ // of a visit's events is by definition a within-session quantity.
1272
+ //
1273
+ // The reads are floor-crossings. A hand's shortest measured key dwell on the
1274
+ // lab gauntlet was 39ms, its shortest click press 38ms, its shortest
1275
+ // inter-key gap 26ms, and every one of its clicks was approached by the
1276
+ // pointer; a browser driven over CDP produced 0-1ms dwells, 2-7ms presses,
1277
+ // 0ms gaps, and clicks with no approach. The counters bucket at 5ms and 10ms,
1278
+ // below any hand, so each share reads 0 for a person whatever their speed
1279
+ // and near 1 for a driver. No timestamp, coordinate, or key identity leaves
1280
+ // the page; a counter cannot be replayed into a rhythm. The mean dwell and
1281
+ // mean press that the same counters also yield are lab-calibration display
1282
+ // only and are NOT registered here; promoting either would need its own
1283
+ // review, because "how long a hand holds a key" is a property of the hand.
1284
+ //
1285
+ // Combined downstream by `interaction_integrity` (apps/web/lib/detection/
1286
+ // interaction-integrity.ts, scorer v1, shadow-only): a Noisy-OR over the
1287
+ // keyboard, press, approach, and provenance readings. That composition is
1288
+ // declared on every entry below so the P44 combination test evaluates it.
1289
+ ...interactionSignals()
1197
1290
  ];
1198
1291
 
1199
1292
  // src/signals/resolve.ts
@@ -2,7 +2,7 @@ import { sha256 } from '@noble/hashes/sha2.js';
2
2
  import { bytesToHex } from '@noble/hashes/utils.js';
3
3
 
4
4
  // src/signals/types.ts
5
- var REGISTRY_VERSIONS = ["v1", "v2"];
5
+ var REGISTRY_VERSIONS = ["v1", "v2", "v3"];
6
6
  var CURRENT_REGISTRY_VERSION = REGISTRY_VERSIONS[REGISTRY_VERSIONS.length - 1];
7
7
  var FROZEN_FIELDS = ["id", "addedVersion", "denoise", "mode", "plane", "group"];
8
8
  var TIER_LOCKED_FIELDS = ["tier"];
@@ -290,6 +290,73 @@ function compliantReview() {
290
290
  rationale: "Raw device/browser entropy read; no plausible link to a Sensitive Data Inference category, individually or via a known composition-risk rule."
291
291
  };
292
292
  }
293
+ var INTERACTION_SIGNAL_IDS = [
294
+ "interaction.keyDwellUnder5Share",
295
+ "interaction.keyGapUnder5Share",
296
+ "interaction.pressUnder10Share",
297
+ "interaction.zeroTrailClickShare",
298
+ "interaction.untrustedInputShare",
299
+ "interaction.mousePerClick"
300
+ ];
301
+ function interactionReview(id) {
302
+ return {
303
+ listVersion: CURRENT_SENSITIVE_REJECTION_LIST_VERSION,
304
+ reviewedBy: "privacy-review@kya-os.example",
305
+ reviewedAt: "2026-09-03",
306
+ combinesWith: INTERACTION_SIGNAL_IDS.filter((other) => other !== id),
307
+ derivesCategory: null,
308
+ rationale: 'A per-visit share of input events below a physical floor (or a per-visit ratio of two event counts), derived from integer counters; no per-event timing, coordinate, or key identity is collected, so the read cannot reconstruct a typing or pointer rhythm and is not a biometric identifier or a derivative of one (mode: never, so it is excluded from identity linkage regardless). It reads 0 for a person at any speed, ability, or input method, since the floors sit below any hand; it therefore carries no information about a health condition or accommodation. Its only composition is interaction_integrity, a Noisy-OR over the other interaction shares, which derives "driven by software" and nothing about the person.'
309
+ };
310
+ }
311
+ function interactionSignals() {
312
+ const entry = (id, description, notes) => ({
313
+ id,
314
+ addedVersion: "v3",
315
+ removedVersion: null,
316
+ tier: "low",
317
+ measurement: provisional(notes),
318
+ denoise: { kind: "none" },
319
+ mode: "never",
320
+ plane: "behavioural",
321
+ group: "interaction",
322
+ u: null,
323
+ supersedes: null,
324
+ description,
325
+ review: interactionReview(id)
326
+ });
327
+ return [
328
+ entry(
329
+ "interaction.keyDwellUnder5Share",
330
+ "Share of paired keystrokes (keydown to keyup) held under 5ms; IME composition, left/right modifiers, and auto-repeat are not timed, and key timing stops once a finger has touched the page.",
331
+ "Lab gauntlet, two recordings and three driver rigs against production (plan P0.5): hand minimum dwell 39ms, share 0; CDP drivers 0-1ms on every key, share 1. Playwright type({ delay }) manufactures a hand dwell and reads 0: the timing rungs raise the bar and prove nothing, which is why the ladder ends in a challenge. Seeded from that corpus, not a stability harness; finalize once P3 calibration has the trap populations (IME, dictation, on-screen keyboard, switch access)."
332
+ ),
333
+ entry(
334
+ "interaction.keyGapUnder5Share",
335
+ "Share of timed keydown-to-next-keydown gaps within 2s that were under 5ms: a whole string arriving in one tick.",
336
+ "Same corpus: hand minimum gap 26ms, share 0; CDP drivers 0ms, share 0.97 to 1. AltGr (Control then Alt back to back) is excluded by the modifier guard; a held key auto-repeats without entering the gap count. Provisional pending the trap populations."
337
+ ),
338
+ entry(
339
+ "interaction.pressUnder10Share",
340
+ "Share of primary-pointer presses (pointerdown to pointerup) under 10ms; a second finger is not a press and a cancelled press does not pair with the next release.",
341
+ "Same corpus: hand minimum press 38ms, share 0; CDP drivers 2-7ms, share 0.8 to 1. Playwright click({ delay }) holds the press and reads 0. Provisional pending the touch and switch-access populations."
342
+ ),
343
+ entry(
344
+ "interaction.zeroTrailClickShare",
345
+ "Of clicks whose own pointerType is mouse and that follow at least one observed pointer move, the share with no mousemove or wheel in the preceding 300ms: a pointer that appeared on its target.",
346
+ "Same corpus: every hand click approached, share 0; Claude-in-Chrome 8 of 12 unapproached, the cdp rig 0.7. Taps, keyboard-activated buttons, and a click before any move has been seen are outside the denominator, so a cursor already resting on a button is unknown rather than a teleport. Weaker than the timing rungs (the plan weights it 0.4) because a scroll-then-click is an ordinary thing for a hand; provisional."
347
+ ),
348
+ entry(
349
+ "interaction.untrustedInputShare",
350
+ "Share of counted input events (throttled mousemove, keydown, scroll, click, touchstart) dispatched with isTrusted false: input from a script or extension rather than the browser reacting to hardware.",
351
+ "The content-script rung (#4842). A person's input is always trusted and the flag is browser-set and read-only, so it cannot be forged upward; the content-script rig reads 0.96 with human-shaped timing, and a CDP-driven browser reads 0 because its synthetic input arrives trusted, which is what the timing rungs above are for. Human baseline 0 of 15 windows. Provisional pending the autofill and accessibility-tool populations, whose events are trusted and should read 0."
352
+ ),
353
+ entry(
354
+ "interaction.mousePerClick",
355
+ "Throttled (50ms) mouse moves per mouse click over the visit; undefined on touch traffic, which fires no mousemove.",
356
+ "The backstop (#4806): a hand cannot reach a button without dragging the pointer across the screen (measured 33 moves per click) while a driver teleports (measured 2). Noisy on short windows (human 1 to 15 on 4s windows) and undefined for touch, so it is weighted 0.2 in the composite and read only as the mouse-only kinematics reading. Provisional."
357
+ )
358
+ ];
359
+ }
293
360
  var SIGNAL_REGISTRY = [
294
361
  // --- rendering plane ---------------------------------------------------
295
362
  {
@@ -1191,7 +1258,33 @@ var SIGNAL_REGISTRY = [
1191
1258
  supersedes: null,
1192
1259
  description: "UA-CH low-entropy mobile-device flag.",
1193
1260
  review: compliantReview()
1194
- }
1261
+ },
1262
+ // --- Interaction physics, contradiction-only (agentic-session plan P1.1) --
1263
+ // The behavioural plane's first entries. Each is a per-visit SHARE derived
1264
+ // server-side from integer counters the pixel's detector and the beacon's
1265
+ // InteractionCollector accumulate (apps/web/lib/detection/timing-physics.ts
1266
+ // reads both lanes through one function). They exist to tell a driven
1267
+ // browser from a person, never to say WHICH person: mode 'never', so none
1268
+ // enters identity linkage or the Merkle tree; tier 'low', because a share
1269
+ // of a visit's events is by definition a within-session quantity.
1270
+ //
1271
+ // The reads are floor-crossings. A hand's shortest measured key dwell on the
1272
+ // lab gauntlet was 39ms, its shortest click press 38ms, its shortest
1273
+ // inter-key gap 26ms, and every one of its clicks was approached by the
1274
+ // pointer; a browser driven over CDP produced 0-1ms dwells, 2-7ms presses,
1275
+ // 0ms gaps, and clicks with no approach. The counters bucket at 5ms and 10ms,
1276
+ // below any hand, so each share reads 0 for a person whatever their speed
1277
+ // and near 1 for a driver. No timestamp, coordinate, or key identity leaves
1278
+ // the page; a counter cannot be replayed into a rhythm. The mean dwell and
1279
+ // mean press that the same counters also yield are lab-calibration display
1280
+ // only and are NOT registered here; promoting either would need its own
1281
+ // review, because "how long a hand holds a key" is a property of the hand.
1282
+ //
1283
+ // Combined downstream by `interaction_integrity` (apps/web/lib/detection/
1284
+ // interaction-integrity.ts, scorer v1, shadow-only): a Noisy-OR over the
1285
+ // keyboard, press, approach, and provenance readings. That composition is
1286
+ // declared on every entry below so the P44 combination test evaluates it.
1287
+ ...interactionSignals()
1195
1288
  ];
1196
1289
 
1197
1290
  // src/signals/resolve.ts
@@ -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
+ }
@@ -0,0 +1,112 @@
1
+ # kya-http golden fixtures (H2.0 · #3247)
2
+
3
+ Canonical wire fixtures for the `draft-kya-http-02` Delegation challenge. These are the
4
+ source of truth for **byte-parity across PEPs**: the .NET (net462 + net8), Express,
5
+ Next.js, gateway-worker, and mcp-i-cloudflare challenge emitters must all produce output
6
+ equal to these fixtures for the same verdict. Spec: draft-kya-http-02 (see #3240 for the
7
+ published location); ABNF in spec §12; instructions conformance in spec §8.1 + Appendix A.
8
+
9
+ ## Canonical serialization rules (normative for parity tests)
10
+
11
+ 1. **`WWW-Authenticate: Delegation` is a single line** (HTTP/1.1 forbids obs-fold).
12
+ 2. **Parameter order is fixed:** `realm, sid, consent_uri, pickup_uri, scope,
13
+ min_assurance, interval, kind`. Omitted optional params leave the order of the rest
14
+ unchanged.
15
+ 3. **Separator** between params is a comma followed by exactly one space (`, `).
16
+ 4. **All parameter values are quoted-strings.**
17
+ 5. **For `kind="delegation"`:** the Delegation challenge and the RFC 9728 Bearer
18
+ challenge are emitted as **two separate `WWW-Authenticate` header fields**,
19
+ Delegation first. **For `kind="approval_quorum"`: only the Delegation challenge is
20
+ emitted** — there is no OAuth-native path that satisfies an N-of-M quorum, and
21
+ advertising `resource_metadata` would route OAuth clients toward acquiring a token
22
+ that cannot pass the gate. (Decision pinned via PR #3264 review; spec §8.4 wording
23
+ updated with #3240/#3248.)
24
+ 6. **Header byte-parity** applies to each `WWW-Authenticate` field value exactly.
25
+ **Body parity is structural** (parse JSON, compare values) — member order is not
26
+ normative, but emitters SHOULD use the fixture order for diffability.
27
+ 7. Consumers MUST ignore unrecognized challenge params (forward compatibility — see
28
+ `negative.challenges.json`, which distinguishes reject-cases from must-tolerate cases).
29
+ 8. `instructions` conformance = the four REQUIRED elements (spec §8.1) are present;
30
+ wording MAY vary; elements MUST NOT be omitted. The reference text and the element
31
+ checklist live in each challenge fixture under `conformance.instructions_elements`.
32
+
33
+ ## Files
34
+
35
+ | File | Contents |
36
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
37
+ | `challenge.delegation.minimal.json` | Required params only |
38
+ | `challenge.delegation.full.json` | All recommended params — the primary parity fixture |
39
+ | `challenge.delegation.fetcher-200.json` | Body-readable **HTTP 200** envelope of the full challenge for 4xx-body-dropping AI fetchers — body byte-identical to `full`; a cooperative-UX bridge, **not** an access control |
40
+ | `challenge.approval-quorum.json` | `kind="approval_quorum"` variant (grant format pending #3248; **not parity-frozen**) |
41
+ | `pickup.transcript.json` | Poll sequences: pending→ready→re-delivery, pinning race, 403/404/410/429 |
42
+ | `negative.challenges.json` | Malformed challenges (reject) + tolerance cases (accept) |
43
+ | `error-codes.json` | The `kyaos/*` registry (spec §9) with HTTP status mapping |
44
+ | `protected-resource-metadata.full.json` | RFC 9728 PRM document served at the URL the §8.1 Bearer challenge advertises — **per-org** (org-slug issuer + `scopes_supported`) |
45
+ | `protected-resource-metadata.global.json` | Same PRM, **global** variant — no `resource_org_did` (global issuer) and no scopes (`scopes_supported` omitted) |
46
+
47
+ ## Protected-resource metadata (RFC 9728)
48
+
49
+ `protected-resource-metadata.{full,global}.json` pin the OAuth Protected Resource Metadata
50
+ document served at `/.well-known/oauth-protected-resource` — the URL the §8.1 Delegation
51
+ challenge already advertises via `WWW-Authenticate: Bearer resource_metadata="…"`. Without a
52
+ served document that URL 404s. Each fixture has an `input` block
53
+ (`resource_host`, `resource_org_did`, `base_url`, `scopes`) and an `expected.document` block.
54
+ Parity is **structural body parity** (parse + compare values; member order non-normative, but
55
+ emitters SHOULD use the `conformance.key_order` for diffability), with byte-exactness on the
56
+ `resource` string and the `authorization_servers` issuer. Rules:
57
+
58
+ 13. **`resource` = `https://<resource_host>`**, byte-matching the host in the §8.1 Bearer URL
59
+ (the request `Host`, port-preserving).
60
+ 14. **`authorization_servers` is ALWAYS a single-element array.** With an `:orgs:` slug in
61
+ `resource_org_did` it is the PER-ORG gateway issuer (`{origin}/oauth/gateway/{slug}`, byte-
62
+ identical to the gateway-worker `perOrgIssuer`); otherwise the global issuer (the `base_url`
63
+ origin).
64
+ 15. **`scopes_supported` is emitted ONLY when `scopes` is non-empty** — never defaulted to a
65
+ scope (the `global` fixture omits it).
66
+ 16. The .NET v1 document does **not** emit the `kyaos_needs_authorization` extension the
67
+ gateway-worker adds (out of scope).
68
+
69
+ ## Placeholders
70
+
71
+ `challenge_proof` values are the literal string `"TEST-DETACHED-PROOF-PENDING-H1.3"` until
72
+ #3246 lands and a real org-signed DetachedProof example can be vectored; verification of
73
+ challenge_proof is **out of scope** for these fixtures until then. All sids, tokens, and
74
+ hosts are deterministic test values (`api.merchant.com` / `auth.merchant.com`).
75
+
76
+ ## Wiring TODO (this PR ships data only)
77
+
78
+ - [ ] TS: vitest loader in `checkpoint-shared` exporting typed fixtures; consumed by the
79
+ wasm-runtime renderer tests (#3253)
80
+ - [ ] C#: copy-to-output + xunit theory data in `checkpoint-dotnet` (#3249, #3250)
81
+ - [ ] ABNF validation step in CI against spec §12
82
+
83
+ ## Fetcher-200 envelope (body-readable delivery)
84
+
85
+ `challenge.delegation.fetcher-200.json` is the same §8.1 Delegation challenge delivered over
86
+ an HTTP **200** instead of a **401**, for AI-agent fetchers that collapse 4xx responses and
87
+ never surface the body to the LLM (e.g. Claude-User WebFetch). Rules (normative for the
88
+ fetcher-200 parity tests; the 401 fixtures' rules 1–8 above are unchanged):
89
+
90
+ 9. **Body byte-identical to the 401.** The `http.body` of the fetcher-200 fixture MUST equal
91
+ `challenge.delegation.full.json`'s `http.body` exactly. The org-signed
92
+ `challenge_proof.responseHash` binds `canonicalize(response.data)` — the body content,
93
+ NOT the HTTP status or headers — so the same proof verifies at 200 or 401. A 200 body that
94
+ diverges from the 401 body silently breaks verification for every fetcher.
95
+ 10. **No `WWW-Authenticate`.** A 200 carrying `WWW-Authenticate` is reinterpreted as a 401 by
96
+ some fetchers (and the body dropped). The 200 envelope omits it; it also omits
97
+ `Retry-After` (defined for 3xx/429/503 — the poll cadence lives in the body
98
+ `poll_interval_s`). It keeps `Content-Type: application/json` + `Cache-Control: no-store`.
99
+ 11. **Consent in unsigned hint headers.** The consent URL is repeated in `KYA-Auth-Url` and a
100
+ `Link: <consent_uri>; rel="kya-authorize"` header (plus `KYA-Auth-Required: true`,
101
+ `KYA-Action: challenge`). These are **unsigned hints** — the proof covers only the body —
102
+ so the AUTHORITATIVE consent target is `body.kyaos.consent_uri`; a header value MUST equal
103
+ it and a correct consumer acts on the body, not the header.
104
+ 12. **Not an access control.** The 200 vs 401 choice is UX (which clients can read the body),
105
+ selected per the `negotiated` mode (the `KYA-Accept-Challenge` request header, or the
106
+ transitional `ai_agent` UA heuristic). It never gates access — a non-cooperative client
107
+ simply gets the 401. `consent_uri`/`pickup_uri` MUST derive from the configured
108
+ `AuthorizationHost`, never the request `Host`.
109
+
110
+ Coverage: `packages/checkpoint-shared/src/__tests__/kya-http-fetcher-200-fixture.test.ts` (body
111
+ byte-parity + envelope shape) and `apps/web/tests/unit/lib/gateway/oauth/needs-authorization-challenge.test.ts`
112
+ (the proof verifies transport-agnostically; a divergent 200 body fails CONTENT_BINDING_MISMATCH).
@@ -0,0 +1,25 @@
1
+ {
2
+ "$fixture": "kya-http/challenge-proof.canonical",
3
+ "$spec": "draft-kya-http-02 §8 challenge_proof",
4
+ "description": "Byte-exact canonical serialization of the challenge_proof bound payload {sid, consent_uri, required_scopes} — the responseHash pre-image. The issuer (JS JSON.stringify, FIXED key order sid -> consent_uri -> required_scopes, caller scope order preserved, no whitespace, '/' and ':' left UNESCAPED) and every cross-runtime verifier (.NET H2.x) MUST reproduce these exact bytes. C# tests assert against `canonical` rather than re-deriving the serializer rules (System.Text.Json escapes '/' by default — use a non-escaping encoder).",
5
+ "cases": [
6
+ {
7
+ "name": "primary",
8
+ "payload": {
9
+ "sid": "kya-9f4e7c2a8b1d4e6f",
10
+ "consent_uri": "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f",
11
+ "required_scopes": ["commerce.checkout"]
12
+ },
13
+ "canonical": "{\"sid\":\"kya-9f4e7c2a8b1d4e6f\",\"consent_uri\":\"https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f\",\"required_scopes\":[\"commerce.checkout\"]}"
14
+ },
15
+ {
16
+ "name": "multi-scope-order-preserved",
17
+ "payload": {
18
+ "sid": "kya-abc123def456ghi789jkl",
19
+ "consent_uri": "https://authenticate.acme.com/consent?sid=kya-abc123def456ghi789jkl",
20
+ "required_scopes": ["commerce.checkout", "commerce.refund"]
21
+ },
22
+ "canonical": "{\"sid\":\"kya-abc123def456ghi789jkl\",\"consent_uri\":\"https://authenticate.acme.com/consent?sid=kya-abc123def456ghi789jkl\",\"required_scopes\":[\"commerce.checkout\",\"commerce.refund\"]}"
23
+ }
24
+ ]
25
+ }