@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
@@ -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
+ }
@@ -0,0 +1,72 @@
1
+ [
2
+ {
3
+ "description": "opt-in header present, non-agent detection → 200 (header is the primary signal)",
4
+ "headers": { "kya-accept-challenge": "delegation" },
5
+ "detectionClass": "human",
6
+ "isAgent": false,
7
+ "expected": true
8
+ },
9
+ {
10
+ "description": "opt-in header present, detection absent → 200",
11
+ "headers": { "kya-accept-challenge": "delegation" },
12
+ "detectionClass": null,
13
+ "isAgent": false,
14
+ "expected": true
15
+ },
16
+ {
17
+ "description": "detected ai_agent (isAgent agrees), no opt-in → 200 (transitional UA heuristic)",
18
+ "headers": {},
19
+ "detectionClass": "ai_agent",
20
+ "isAgent": true,
21
+ "expected": true
22
+ },
23
+ {
24
+ "description": "Accept: text/html on a detected agent → 200 (Accept MUST NOT branch the body)",
25
+ "headers": { "accept": "text/markdown, text/html, */*" },
26
+ "detectionClass": "ai_agent",
27
+ "isAgent": true,
28
+ "expected": true
29
+ },
30
+ {
31
+ "description": "ai_agent class but isAgent=false (signals disagree) → 401 (require both, matches .NET + worker)",
32
+ "headers": {},
33
+ "detectionClass": "ai_agent",
34
+ "isAgent": false,
35
+ "expected": false
36
+ },
37
+ {
38
+ "description": "human, no opt-in → 401 (spec path)",
39
+ "headers": {},
40
+ "detectionClass": "human",
41
+ "isAgent": false,
42
+ "expected": false
43
+ },
44
+ {
45
+ "description": "bot, no opt-in → 401 (non-cooperative / spoofer lands on spec path)",
46
+ "headers": {},
47
+ "detectionClass": "bot",
48
+ "isAgent": false,
49
+ "expected": false
50
+ },
51
+ {
52
+ "description": "incomplete_data, no opt-in → 401",
53
+ "headers": {},
54
+ "detectionClass": "incomplete_data",
55
+ "isAgent": false,
56
+ "expected": false
57
+ },
58
+ {
59
+ "description": "no signals at all → 401",
60
+ "headers": {},
61
+ "detectionClass": null,
62
+ "isAgent": false,
63
+ "expected": false
64
+ },
65
+ {
66
+ "description": "empty opt-in value is ignored, human → 401",
67
+ "headers": { "kya-accept-challenge": "" },
68
+ "detectionClass": "human",
69
+ "isAgent": false,
70
+ "expected": false
71
+ }
72
+ ]
@@ -0,0 +1,54 @@
1
+ {
2
+ "$fixture": "kya-http/negative.challenges",
3
+ "$spec": "draft-kya-http-02 §8.1 + §12 (ABNF)",
4
+ "description": "Emitter-side: a conforming PEP must NEVER produce the reject cases. Client/validator-side: reject cases fail validation; tolerate cases MUST pass (forward compatibility).",
5
+ "reject": [
6
+ {
7
+ "name": "missing-sid",
8
+ "header": "Delegation realm=\"api.merchant.com\", consent_uri=\"https://auth.merchant.com/consent\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/x\", kind=\"delegation\"",
9
+ "reason": "sid is REQUIRED"
10
+ },
11
+ {
12
+ "name": "missing-kind",
13
+ "header": "Delegation realm=\"api.merchant.com\", sid=\"kya-1\", consent_uri=\"https://auth.merchant.com/consent?sid=kya-1\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/kya-1\"",
14
+ "reason": "kind is REQUIRED"
15
+ },
16
+ {
17
+ "name": "http-consent-uri",
18
+ "header": "Delegation realm=\"api.merchant.com\", sid=\"kya-1\", consent_uri=\"http://auth.merchant.com/consent?sid=kya-1\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/kya-1\", kind=\"delegation\"",
19
+ "reason": "consent_uri/pickup_uri MUST be absolute https URIs"
20
+ },
21
+ {
22
+ "name": "unquoted-param",
23
+ "header": "Delegation realm=api.merchant.com, sid=\"kya-1\", consent_uri=\"https://auth.merchant.com/consent?sid=kya-1\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/kya-1\", kind=\"delegation\"",
24
+ "reason": "all values are quoted-strings"
25
+ },
26
+ {
27
+ "name": "invalid-min-assurance",
28
+ "header": "Delegation realm=\"api.merchant.com\", sid=\"kya-1\", consent_uri=\"https://auth.merchant.com/consent?sid=kya-1\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/kya-1\", min_assurance=\"platinum\", kind=\"delegation\"",
29
+ "reason": "min_assurance enum: anonymous|attested-bearer|key-bound|registered|delegated"
30
+ },
31
+ {
32
+ "name": "missing-instructions-element",
33
+ "body_mutation": "instructions omits the pinning requirement (element 3)",
34
+ "reason": "the four §8.1 instructions elements are REQUIRED"
35
+ }
36
+ ],
37
+ "tolerate": [
38
+ {
39
+ "name": "unknown-param-ignored",
40
+ "header": "Delegation realm=\"api.merchant.com\", sid=\"kya-1\", consent_uri=\"https://auth.merchant.com/consent?sid=kya-1\", pickup_uri=\"https://auth.merchant.com/api/delegation/pickup/kya-1\", kind=\"delegation\", x_future_param=\"x\"",
41
+ "reason": "unrecognized params MUST be ignored"
42
+ },
43
+ {
44
+ "name": "extra-body-members-ignored",
45
+ "body_mutation": "kyaos object carries additional unknown members",
46
+ "reason": "forward compatibility"
47
+ },
48
+ {
49
+ "name": "coexisting-bearer-challenge",
50
+ "note": "second WWW-Authenticate (Bearer resource_metadata=...) present",
51
+ "reason": "RFC 7235 multiple challenges; REQUIRED to tolerate, SHOULD emit"
52
+ }
53
+ ]
54
+ }
@@ -0,0 +1,96 @@
1
+ {
2
+ "$fixture": "kya-http/pickup.transcript",
3
+ "$spec": "draft-kya-http-02 §8.2 + §13 (anchor state machine)",
4
+ "description": "Poll sequences against GET /api/delegation/pickup/kya-9f4e7c2a8b1d4e6f. Token path shown; key path differs only in that polls are RFC 9421-signed and the pin is the keyid (or set at challenge time for signed callers). All responses carry Cache-Control: no-store.",
5
+ "pinned_token": "X-KYA-Pickup-Token: 5f4dcc3b5aa765d61d8327deb882cf995f4dcc3b5aa765d61d8327deb882cf99",
6
+ "sequences": {
7
+ "happy_path_with_redelivery": [
8
+ {
9
+ "step": 1,
10
+ "poll": "token A (first poll — PENDING→PINNED)",
11
+ "status": 202,
12
+ "body": { "status": "pending" }
13
+ },
14
+ {
15
+ "step": 2,
16
+ "poll": "token A (consent not yet granted)",
17
+ "status": 202,
18
+ "body": { "status": "pending" }
19
+ },
20
+ {
21
+ "step": 3,
22
+ "note": "human approves on consent surface — PINNED→APPROVED, credential minted and parked"
23
+ },
24
+ {
25
+ "step": 4,
26
+ "poll": "token A",
27
+ "status": 200,
28
+ "body": {
29
+ "status": "ready",
30
+ "token_type": "Bearer",
31
+ "delegation": "TEST-DELEGATION-VC-JWT",
32
+ "expires_in": 900
33
+ }
34
+ },
35
+ {
36
+ "step": 5,
37
+ "poll": "token A (simulated dropped 200 — RE-DELIVERY, same credential)",
38
+ "status": 200,
39
+ "body": {
40
+ "status": "ready",
41
+ "token_type": "Bearer",
42
+ "delegation": "TEST-DELEGATION-VC-JWT",
43
+ "expires_in": 900
44
+ }
45
+ },
46
+ { "step": 6, "note": "anchor TTL (≤600s) elapses — APPROVED→EXPIRED" },
47
+ { "step": 7, "poll": "token A", "status": 410, "body": { "error": "kyaos/pickup-expired" } }
48
+ ],
49
+ "pinning_race": [
50
+ {
51
+ "step": 1,
52
+ "poll": "token A and token B race the first poll",
53
+ "note": "atomic compare-and-set: exactly one pins"
54
+ },
55
+ { "step": 2, "poll": "winner (token A)", "status": 202, "body": { "status": "pending" } },
56
+ {
57
+ "step": 3,
58
+ "poll": "loser (token B)",
59
+ "status": 403,
60
+ "body": { "error": "kyaos/pickup-pinned" }
61
+ }
62
+ ],
63
+ "non_pinned_after_approval": [
64
+ {
65
+ "step": 1,
66
+ "poll": "token B (anchor pinned to A, credential parked)",
67
+ "status": 403,
68
+ "body": { "error": "kyaos/pickup-pinned" },
69
+ "note": "legitimate-agent 403s SHOULD be surfaced to the org audit stream as a compromise indicator (spec §10)"
70
+ }
71
+ ],
72
+ "unknown_anchor": [
73
+ {
74
+ "step": 1,
75
+ "poll": "any token, sid=kya-DOES-NOT-EXIST",
76
+ "status": 404,
77
+ "body": { "error": "kyaos/invalid-session" }
78
+ }
79
+ ],
80
+ "over_rate": [
81
+ {
82
+ "step": 1,
83
+ "poll": "token A at >1/interval",
84
+ "status": 429,
85
+ "headers": [["Retry-After", "3"]]
86
+ }
87
+ ]
88
+ },
89
+ "invariants": [
90
+ "pin is set at challenge time when the challenged request carried a valid Layer 1 signature (no first-poll race for signed callers)",
91
+ "pinned secret never appears in any URL, log line, or redirect",
92
+ "200 is repeatable for the pinned holder until anchor expiry (no consume-on-read)",
93
+ "consent on an EXPIRED anchor MUST fail",
94
+ "all pickup responses: Cache-Control: no-store"
95
+ ]
96
+ }