@kya-os/checkpoint-shared 1.3.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/CHANGELOG.md +112 -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 +49 -0
  7. package/dist/browser-posture-report.d.ts +49 -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 +78 -0
  11. package/dist/browser-posture.d.ts +78 -0
  12. package/dist/browser-posture.js +19017 -0
  13. package/dist/browser-posture.mjs +19000 -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/deploy/index.d.mts +268 -703
  19. package/dist/deploy/index.d.ts +268 -703
  20. package/dist/errors/index.d.mts +104 -0
  21. package/dist/errors/index.d.ts +104 -0
  22. package/dist/errors/index.js +338 -0
  23. package/dist/errors/index.mjs +333 -0
  24. package/dist/gateway/index.d.mts +69 -466
  25. package/dist/gateway/index.d.ts +69 -466
  26. package/dist/gateway/index.js +4 -0
  27. package/dist/gateway/index.mjs +4 -1
  28. package/dist/index.d.mts +5442 -28919
  29. package/dist/index.d.ts +5442 -28919
  30. package/dist/index.js +19552 -4142
  31. package/dist/index.mjs +19523 -4135
  32. package/dist/mcpi/dashboard-config/index.d.mts +1295 -12820
  33. package/dist/mcpi/dashboard-config/index.d.ts +1295 -12820
  34. package/dist/signals/index.d.mts +1 -1
  35. package/dist/signals/index.d.ts +1 -1
  36. package/dist/signals/index.js +95 -2
  37. package/dist/signals/index.mjs +95 -2
  38. package/dist/tool-protection/index.d.mts +135 -834
  39. package/dist/tool-protection/index.d.ts +135 -834
  40. package/fixtures/client-ip-resolution.json +103 -0
  41. package/fixtures/detection/reason-codes.json +35 -0
  42. package/fixtures/detection/signal-exposure-example.json +62 -0
  43. package/fixtures/kya-http/README.md +112 -0
  44. package/fixtures/kya-http/challenge-proof.canonical.json +25 -0
  45. package/fixtures/kya-http/challenge.approval-quorum.json +37 -0
  46. package/fixtures/kya-http/challenge.delegation.fetcher-200.json +55 -0
  47. package/fixtures/kya-http/challenge.delegation.full.json +81 -0
  48. package/fixtures/kya-http/challenge.delegation.minimal.json +57 -0
  49. package/fixtures/kya-http/error-codes.json +35 -0
  50. package/fixtures/kya-http/fetcher-200-predicate.vectors.json +72 -0
  51. package/fixtures/kya-http/negative.challenges.json +54 -0
  52. package/fixtures/kya-http/pickup.transcript.json +96 -0
  53. package/fixtures/kya-http/pickup.transcript.quorum.json +156 -0
  54. package/fixtures/kya-http/protected-resource-metadata.full.json +30 -0
  55. package/fixtures/kya-http/protected-resource-metadata.global.json +28 -0
  56. package/fixtures/kya-http/registration.request.json +33 -0
  57. package/fixtures/kya-http/registration.response.json +32 -0
  58. package/package.json +21 -3
@@ -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
+ }
@@ -0,0 +1,37 @@
1
+ {
2
+ "$fixture": "kya-http/challenge.approval-quorum",
3
+ "$spec": "draft-kya-http-02 §8.4 (grant format: draft-kya-quorum-00, pending #3248)",
4
+ "description": "Step-up variant: kind=approval_quorum with server-issued action nonce. Challenge + pickup mechanics identical to kind=delegation EXCEPT: no RFC 9728 Bearer challenge is emitted (see conformance.bearer_challenge), and the retry presents grants via KYA-Approvals. Grant-format vectors land with #3248/#3258. NOT parity-frozen until #3248 resolves the pinned review items (anchor lifetime, pickup 200 grants body).",
5
+ "http": {
6
+ "status": 401,
7
+ "headers": [
8
+ [
9
+ "WWW-Authenticate",
10
+ "Delegation realm=\"api.merchant.com\", sid=\"kya-7a1b3c5d7e9f1a2b\", consent_uri=\"https://auth.merchant.com/consent?sid=kya-7a1b3c5d7e9f1a2b\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/kya-7a1b3c5d7e9f1a2b\", scope=\"treasury.transfer\", min_assurance=\"key-bound\", interval=\"3\", kind=\"approval_quorum\""
11
+ ],
12
+ ["Retry-After", "3"],
13
+ ["Content-Type", "application/json"],
14
+ ["Cache-Control", "no-store"]
15
+ ],
16
+ "body": {
17
+ "error": "kyaos/authorization-required",
18
+ "kyaos": {
19
+ "sid": "kya-7a1b3c5d7e9f1a2b",
20
+ "kind": "approval_quorum",
21
+ "quorum": 2,
22
+ "action_nonce": "TEST-ACTION-NONCE-4f8e2d",
23
+ "consent_uri": "https://auth.merchant.com/consent?sid=kya-7a1b3c5d7e9f1a2b",
24
+ "pickup_uri": "https://auth.merchant.com/api/delegation/pickup/kya-7a1b3c5d7e9f1a2b",
25
+ "required_scopes": ["treasury.transfer"],
26
+ "min_assurance": "key-bound",
27
+ "poll_interval_s": 3,
28
+ "challenge_proof": "TEST-DETACHED-PROOF-PENDING-H1.3"
29
+ },
30
+ "instructions": "This action requires approval from 2 human approvers. Show your user this link to begin the approval process: https://auth.merchant.com/consent?sid=kya-7a1b3c5d7e9f1a2b. Then poll https://auth.merchant.com/api/delegation/pickup/kya-7a1b3c5d7e9f1a2b every 3 seconds (sign polls with an ephemeral did:key, or send one random 32-byte X-KYA-Pickup-Token on EVERY poll). When the response status is 200, retry your original request presenting the returned grants in the KYA-Approvals header."
31
+ }
32
+ },
33
+ "conformance": {
34
+ "bearer_challenge": "INTENTIONALLY OMITTED for kind=approval_quorum: no OAuth-native path satisfies an N-of-M quorum; advertising RFC 9728 resource_metadata would route OAuth clients toward a token that cannot pass the gate. Emitters MUST NOT add it. (README rule 5; decision via PR #3264 review.)",
35
+ "notes": "Retry header for this kind is KYA-Approvals (not Authorization: Bearer). Single-admission semantics (atomic tryConsume) tested in #3258, not here. Pickup 200 grants body shape pending #3248 — see PR #3264 pinned review comment."
36
+ }
37
+ }
@@ -0,0 +1,55 @@
1
+ {
2
+ "$fixture": "kya-http/challenge.delegation.fetcher-200",
3
+ "$spec": "draft-kya-http-02 §8.1 (fetcher-compatibility 200 envelope)",
4
+ "description": "Body-readable HTTP 200 envelope of the §8.1 Delegation challenge, for AI-agent fetchers that drop 4xx bodies (e.g. Claude-User WebFetch). The body is BYTE-IDENTICAL to challenge.delegation.full.json — challenge_proof.responseHash binds the body content, not the HTTP envelope, so the same org-signed proof verifies at 200 or 401. Status 200, NO WWW-Authenticate (a 200 + WWW-Authenticate is reinterpreted as 401 by some fetchers), NO Retry-After; the consent URL is repeated in the unsigned KYA-Auth-Url + Link hint headers. Selected by the `negotiated` mode for cooperative / self-identifying agents (KYA-Accept-Challenge, or the transitional ai_agent UA heuristic); capable + discovery clients still receive the 401 (challenge.delegation.full.json). This envelope is a cooperative-UX bridge, NOT an access control — a non-cooperative client simply gets the 401.",
5
+ "verdict_input": {
6
+ "decision": "challenge",
7
+ "required_scopes": ["commerce.checkout"],
8
+ "min_assurance": "attested-bearer",
9
+ "authorization_host": "auth.merchant.com",
10
+ "realm": "api.merchant.com",
11
+ "sid": "kya-9f4e7c2a8b1d4e6f",
12
+ "poll_interval_s": 3
13
+ },
14
+ "http": {
15
+ "status": 200,
16
+ "headers": [
17
+ ["Content-Type", "application/json"],
18
+ ["Cache-Control", "no-store"],
19
+ ["KYA-Auth-Required", "true"],
20
+ ["KYA-Auth-Url", "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f"],
21
+ [
22
+ "Link",
23
+ "<https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f>; rel=\"kya-authorize\""
24
+ ],
25
+ ["KYA-Action", "challenge"]
26
+ ],
27
+ "body": {
28
+ "error": "kyaos/authorization-required",
29
+ "kyaos": {
30
+ "sid": "kya-9f4e7c2a8b1d4e6f",
31
+ "consent_uri": "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f",
32
+ "pickup_uri": "https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f",
33
+ "required_scopes": ["commerce.checkout"],
34
+ "min_assurance": "attested-bearer",
35
+ "poll_interval_s": 3,
36
+ "challenge_proof": "TEST-DETACHED-PROOF-PENDING-H1.3",
37
+ "action": {
38
+ "type": "delegation",
39
+ "consent_uri": "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f",
40
+ "pickup_uri": "https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f",
41
+ "poll_interval_s": 3,
42
+ "pin": { "header": "X-KYA-Pickup-Token" },
43
+ "retry": { "header": "Authorization", "scheme": "Bearer", "value_from": "delegation" }
44
+ }
45
+ },
46
+ "instructions": "This action requires human authorization. Show your user this link and ask them to approve: https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f. Then poll https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f every 3 seconds. If you can sign HTTP requests, sign each poll with an ephemeral did:key; otherwise generate one random 32-byte token and send it as X-KYA-Pickup-Token on EVERY poll. When the response status is 200, take the 'delegation' value and retry your original request with header 'Authorization: Bearer <delegation>'."
47
+ }
48
+ },
49
+ "conformance": {
50
+ "body_byte_identical_to": "challenge.delegation.full.json",
51
+ "no_www_authenticate": true,
52
+ "no_retry_after": true,
53
+ "authoritative_consent_target": "body.kyaos.consent_uri — the KYA-Auth-Url and Link headers are UNSIGNED hints only (the proof covers the body, not headers); a correct consumer acts on the body consent_uri"
54
+ }
55
+ }
@@ -0,0 +1,81 @@
1
+ {
2
+ "$fixture": "kya-http/challenge.delegation.full",
3
+ "$spec": "draft-kya-http-02 §8.1",
4
+ "description": "Primary parity fixture: Delegation challenge with all RECOMMENDED params. Every PEP must emit exactly this for verdict {challenge, scopes:[commerce.checkout], min_assurance:attested-bearer} at project with authorization_host=auth.merchant.com.",
5
+ "verdict_input": {
6
+ "decision": "challenge",
7
+ "required_scopes": ["commerce.checkout"],
8
+ "min_assurance": "attested-bearer",
9
+ "authorization_host": "auth.merchant.com",
10
+ "realm": "api.merchant.com",
11
+ "sid": "kya-9f4e7c2a8b1d4e6f",
12
+ "poll_interval_s": 3
13
+ },
14
+ "http": {
15
+ "status": 401,
16
+ "headers": [
17
+ [
18
+ "WWW-Authenticate",
19
+ "Delegation realm=\"api.merchant.com\", sid=\"kya-9f4e7c2a8b1d4e6f\", consent_uri=\"https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f\", scope=\"commerce.checkout\", min_assurance=\"attested-bearer\", interval=\"3\", kind=\"delegation\""
20
+ ],
21
+ [
22
+ "WWW-Authenticate",
23
+ "Bearer resource_metadata=\"https://api.merchant.com/.well-known/oauth-protected-resource\""
24
+ ],
25
+ ["Retry-After", "3"],
26
+ ["Content-Type", "application/json"],
27
+ ["Cache-Control", "no-store"],
28
+ ["KYA-Auth-Required", "true"],
29
+ ["KYA-Auth-Url", "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f"],
30
+ [
31
+ "Link",
32
+ "<https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f>; rel=\"kya-authorize\""
33
+ ],
34
+ ["KYA-Action", "challenge"]
35
+ ],
36
+ "body": {
37
+ "error": "kyaos/authorization-required",
38
+ "kyaos": {
39
+ "sid": "kya-9f4e7c2a8b1d4e6f",
40
+ "consent_uri": "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f",
41
+ "pickup_uri": "https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f",
42
+ "required_scopes": ["commerce.checkout"],
43
+ "min_assurance": "attested-bearer",
44
+ "poll_interval_s": 3,
45
+ "challenge_proof": "TEST-DETACHED-PROOF-PENDING-H1.3",
46
+ "action": {
47
+ "type": "delegation",
48
+ "consent_uri": "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f",
49
+ "pickup_uri": "https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f",
50
+ "poll_interval_s": 3,
51
+ "pin": { "header": "X-KYA-Pickup-Token" },
52
+ "retry": { "header": "Authorization", "scheme": "Bearer", "value_from": "delegation" }
53
+ }
54
+ },
55
+ "instructions": "This action requires human authorization. Show your user this link and ask them to approve: https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f. Then poll https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f every 3 seconds. If you can sign HTTP requests, sign each poll with an ephemeral did:key; otherwise generate one random 32-byte token and send it as X-KYA-Pickup-Token on EVERY poll. When the response status is 200, take the 'delegation' value and retry your original request with header 'Authorization: Bearer <delegation>'."
56
+ }
57
+ },
58
+ "retry": {
59
+ "description": "The successful retry presentation after pickup.",
60
+ "headers": [["Authorization", "Bearer TEST-DELEGATION-VC-JWT"]],
61
+ "fallback_header_when_authorization_occupied": ["KYA-Delegation", "TEST-DELEGATION-VC-JWT"]
62
+ },
63
+ "conformance": {
64
+ "param_order": [
65
+ "realm",
66
+ "sid",
67
+ "consent_uri",
68
+ "pickup_uri",
69
+ "scope",
70
+ "min_assurance",
71
+ "interval",
72
+ "kind"
73
+ ],
74
+ "instructions_elements": {
75
+ "1_consent_uri_relay": true,
76
+ "2_pickup_uri_and_interval": true,
77
+ "3_pinning_requirement": true,
78
+ "4_retry_presentation": true
79
+ }
80
+ }
81
+ }
@@ -0,0 +1,57 @@
1
+ {
2
+ "$fixture": "kya-http/challenge.delegation.minimal",
3
+ "$spec": "draft-kya-http-02 §8.1",
4
+ "description": "Delegation challenge with REQUIRED params only (realm, sid, consent_uri, pickup_uri, kind). Optional scope/min_assurance/interval omitted; Retry-After still emitted with the server default.",
5
+ "http": {
6
+ "status": 401,
7
+ "headers": [
8
+ [
9
+ "WWW-Authenticate",
10
+ "Delegation realm=\"api.merchant.com\", sid=\"kya-9f4e7c2a8b1d4e6f\", consent_uri=\"https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f\", kind=\"delegation\""
11
+ ],
12
+ [
13
+ "WWW-Authenticate",
14
+ "Bearer resource_metadata=\"https://api.merchant.com/.well-known/oauth-protected-resource\""
15
+ ],
16
+ ["Retry-After", "3"],
17
+ ["Content-Type", "application/json"],
18
+ ["Cache-Control", "no-store"],
19
+ ["KYA-Auth-Required", "true"],
20
+ ["KYA-Auth-Url", "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f"],
21
+ [
22
+ "Link",
23
+ "<https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f>; rel=\"kya-authorize\""
24
+ ],
25
+ ["KYA-Action", "challenge"]
26
+ ],
27
+ "body": {
28
+ "error": "kyaos/authorization-required",
29
+ "kyaos": {
30
+ "sid": "kya-9f4e7c2a8b1d4e6f",
31
+ "consent_uri": "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f",
32
+ "pickup_uri": "https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f",
33
+ "poll_interval_s": 3,
34
+ "challenge_proof": "TEST-DETACHED-PROOF-PENDING-H1.3",
35
+ "action": {
36
+ "type": "delegation",
37
+ "consent_uri": "https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f",
38
+ "pickup_uri": "https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f",
39
+ "poll_interval_s": 3,
40
+ "pin": { "header": "X-KYA-Pickup-Token" },
41
+ "retry": { "header": "Authorization", "scheme": "Bearer", "value_from": "delegation" }
42
+ }
43
+ },
44
+ "instructions": "This action requires human authorization. Show your user this link and ask them to approve: https://auth.merchant.com/consent?sid=kya-9f4e7c2a8b1d4e6f. Then poll https://auth.merchant.com/api/delegation/pickup/kya-9f4e7c2a8b1d4e6f every 3 seconds. If you can sign HTTP requests, sign each poll with an ephemeral did:key; otherwise generate one random 32-byte token and send it as X-KYA-Pickup-Token on EVERY poll. When the response status is 200, take the 'delegation' value and retry your original request with header 'Authorization: Bearer <delegation>'."
45
+ }
46
+ },
47
+ "conformance": {
48
+ "required_params": ["realm", "sid", "consent_uri", "pickup_uri", "kind"],
49
+ "instructions_elements": {
50
+ "1_consent_uri_relay": true,
51
+ "2_pickup_uri_and_interval": true,
52
+ "3_pinning_requirement": true,
53
+ "4_retry_presentation": true
54
+ },
55
+ "notes": "Header parity is byte-exact on each WWW-Authenticate value; body parity is structural."
56
+ }
57
+ }
@@ -0,0 +1,35 @@
1
+ {
2
+ "$fixture": "kya-http/error-codes",
3
+ "$spec": "draft-kya-http-02 §9",
4
+ "description": "The kyaos/* registry with HTTP status mapping. Emitters MUST use these exact strings; kya/* legacy names MAY be accepted by consumers for one transition cycle.",
5
+ "401": {
6
+ "kyaos/missing-signature": "No Signature-Input label 'kya' where policy requires one",
7
+ "kyaos/invalid-signature": "Signature verification failed",
8
+ "kyaos/expired": "expires < now",
9
+ "kyaos/replay": "(keyid, nonce) already seen within window",
10
+ "kyaos/did-unresolvable": "DID document fetch failed (after stale allowance)",
11
+ "kyaos/authorization-required": "Valid identity, missing/insufficient delegation (challenge follows)"
12
+ },
13
+ "403": {
14
+ "kyaos/profile-violation": "RFC 9421 ok, KYA profile failed",
15
+ "kyaos/delegation-revoked": "Status-list entry set",
16
+ "kyaos/scope-insufficient": "Granted scopes do not satisfy request",
17
+ "kyaos/chain-broken": "Delegation chain verification failed",
18
+ "kyaos/holder-mismatch": "cnf key != Layer 1 keyid",
19
+ "kyaos/audience-mismatch": "aud != this resource org's DID",
20
+ "kyaos/session-mismatch": "sid unknown to this org / scope set inconsistent",
21
+ "kyaos/pickup-pinned": "Pickup poll by a non-pinned holder",
22
+ "kyaos/assurance-insufficient": "Credential verified but achieved assurance tier is below the policy's min_assurance floor; retry with a key-bound signed request (proof-of-possession)"
23
+ },
24
+ "503": {
25
+ "kyaos/status-pending": "Credential declared a credentialStatus but its status list was not supplied / could not be fetched (cold cache, past the 300s status cap); fail-closed but RETRYABLE once the list warms"
26
+ },
27
+ "pickup": {
28
+ "202": "pending",
29
+ "200": "ready (re-deliverable to pinned holder until anchor expiry)",
30
+ "401": "kyaos/authorization-required",
31
+ "404": "kyaos/invalid-session",
32
+ "410": "kyaos/pickup-expired",
33
+ "429": "over-rate (Retry-After)"
34
+ }
35
+ }