1. Scope and Interpretation

1.1 Purpose

This document defines the BIP Conformance Test Suite for implementations claiming BIP conformance under yona:ruleset:v1.0.

This document provides:

• a normative conformance matrix
• parameterized invalid-case families
• byte-exact hashing fixtures for request_jws_sha256
• deterministic REJECT versus NO_RESPONSE decision tables
• transport, discovery, parsing, signature, replay, and binding test requirements

This document adds no new protocol requirements beyond the ruleset and the companion BIP. It exists only to verify conformance to those documents.

1.2 Relationship to companion documents

If this test suite appears to conflict with the ruleset or the companion BIP, the ruleset controls first, then the companion BIP, and this test suite MUST be interpreted accordingly.

1.3 What this suite verifies

This suite verifies the technical conditions needed for BIP conformance under yona:ruleset:v1.0, including:

• did:web resolution for VASP DID documents
• required DID service discovery
• HTTPS POST
• Content-Type: application/jose and Accept: application/jose
• JWS Compact request and response bodies
• deterministic validation-gating behavior
• byte-exact request/response binding via request_jws_sha256
• endpoint-specific success, failure, and no-response handling

1.4 Pilot mapping

A push-payment-only pilot is a restricted subset of this suite.

Such a pilot:

• MAY validate useful interoperability behavior for pilot deployments
• MAY validate useful interoperability behavior for early interoperability experiments
• MAY validate useful interoperability behavior for restricted environments
• MUST NOT claim full BIP conformance

For a push-payment-only pilot, the applicable cases are limited to push-payment authorization and general authorization-endpoint BIP behavior.

The following are out of scope for that pilot:

• retrieval cases
• YonaPaymentIntentService
• yona.retrieve_intent
• yona.payment_intent
• pull-specific embedded_payment_intent binding cases

2. Conformance Claim Semantics

2.1 What a BIP conformance claim requires

This subsection defines the minimum basis for making a BIP conformance claim under yona:ruleset:v1.0.

A BIP conformance claim for yona:ruleset:v1.0 MUST NOT be made unless the implementation:

1. satisfies all applicable normative requirements in YONA Ruleset 1.0;
2. satisfies all applicable normative requirements in the companion Base Interoperability Profile (BIP); and
3. passes all applicable normative test cases in this BIP Conformance Test Suite.

A conformant implementation MUST produce deterministic outcomes for repeated executions of the same test vectors under the same configuration.

If a conformance report is produced, it SHOULD state:

• which role or roles were tested;
• the tested interaction scope (pull, push, or both);
• the tested ruleset_id; and
• any configuration inputs that materially affect validation, timeout handling, replay handling, caching, or repeated-request behavior.

2.2 Issuance and publication of conformance claims

This test suite defines only the technical verification conditions for making a BIP conformance claim under yona:ruleset:v1.0.

This suite does not define or require:

• a specific issuer
• a publication venue
• a display method
• a registry
• a trust framework
• a credential format

Passing this suite does not require review, approval, issuance, publication, registration, contract, or purchase of services from YONA LLC, from any future YONA successor body, or from any other specific party.

A self-asserted statement or third-party attestation MAY be accompanied by or expressed through a report, certificate, registry entry, or Verifiable Credential (VC), but those mechanisms are outside the scope of this test suite.

Any claim of technical conformance MUST be based on the applicable normative requirements of the ruleset and the companion BIP and on passing the applicable BIP Conformance Test Suite.

The presence, absence, or format of a conformance claim, attestation, report, certificate, registry entry, or credential does not alter the underlying technical pass/fail result for the implementation under test.

3. Test Harness Conventions

3.1 Roles under test

A conformance report MUST state which role or roles were tested.

3.2 Clock control and timeout testing

The harness MUST be able to control or simulate time sufficiently to test:

Time-dependent behavior

• valid exp
• expired exp
• the 60-second authorization no-response cutoff
• late terminal authorization response handling

The test harness MUST simulate the case where the client sends an authorization request and gets no usable response at all until the timeout is reached.

3.3 Replay and repeated-request window

Because replay-protection windows and repeated-request retention periods are implementation-defined, this suite verifies the following within the active test session:

• immediate signed-message replay handling
• repeated-request handling for yona.authorization_request within the same (iss, intent_id) scope

This suite does not assert behavior after the implementation's retention window expires.

3.4 Fixture bytes are authoritative

For tests involving request_jws_sha256, the fixture's exact JWS Compact Serialization is authoritative.

The following are not equivalent for hashing or comparison:

• reconstructed JSON
• reserialized JSON
• trimmed strings
• normalized strings
• re-encoded JOSE parts

3.5 Endpoint-specific interpretation

The harness MUST preserve the distinction between:

A retrieval failure MUST NOT be treated as ACCEPT, REJECT, or authorization NO_RESPONSE.

4. BIP Transport and Message-Handling Requirements Under Test

4.1 HTTP request requirements (client-side)

For BIP requests, the originator client MUST:

Client requirement

• send HTTPS POST to the serviceEndpoint resolved via did:web
• send a signed YONA request message in JWS Compact Serialization form
• send Content-Type: application/jose
• send Accept: application/jose

For request bodies:

Request body requirement

• the HTTP request body MUST consist solely of the JWS Compact Serialization of the YONA request
• the decoded JWS payload MUST contain all required members for the declared message_type and ruleset_id
• any required objects or fields, such as intent_locator, payment_terms, or intended_asset_type, MUST be carried inside the JWS payload JSON and MUST NOT be sent as standalone HTTP bodies

4.2 HTTP response requirements (server-side, authorization endpoint)

When a bound terminal authorization response can be formed, the beneficiary server MUST return:

Server-side authorization response requirement

• HTTP 200
• Content-Type: application/jose
• an HTTP response body that is the byte-exact JWS Compact Serialization of a yona.authorization_response

If a bound terminal response cannot be formed, the server MUST NOT return a YONA response message.

Examples of outcomes that are not YONA response messages include:

Not a YONA response message

• non-200 status
• non-JOSE body
• malformed JOSE body
• connection close
• timeout
• no response

4.3 Authorization no-response mapping (client-side)

For authorization requests:

In all cases, the implementation MUST NOT proceed to post-ACCEPT steps without a valid, verified terminal ACCEPT.

4.4 Retrieval failure behavior (client-side)

For payment-intent retrieval:

5. BIP Conformance Test Matrix

5.1 Matrix structure

Each applicable test case in this matrix MUST be executed for a BIP conformance claim unless this suite expressly marks the case not applicable to the implementation, endpoint, role, or interaction scope under test.

The matrix contains:

• explicit named test cases
• parameterized case families that MUST be instantiated for each required field, binding rule, parsing rule, or protected-header rule

Each test case defines:

Test case elements

• input
• expected role behavior
• pass/fail criteria

For each applicable case, the implementation under test MUST produce the expected result shown.

5.2 Core valid-path cases

6. Parameterized Required-Field Invalid-Case Families

6.1 Family rule

For each required defined field listed in the message-specific subsections below, the harness MUST instantiate the following cases unless marked not applicable:

Expected result:

This family rule applies only to defined required fields.

A non-duplicate unknown additional field is not invalid by itself and MUST NOT change validation, binding, timeouts, or outcomes. The harness SHOULD include at least one non-failing tolerance case for this rule in request and response directions relevant to the tested role.

6.2 yona.retrieve_intent request (beneficiary server receives)

BAD_VALUE examples that MUST be covered:

• message_type != yona.retrieve_intent
• ruleset_id != yona:ruleset:v1.0
• aud != intent_locator.beneficiary_vasp_did
• intent_locator.type invalid
• intent_locator.beneficiary_intent_id violates ASCII-restricted identifier rules
• non-integer iat or exp
• expired exp
• replayed jti

6.3 yona.payment_intent response (originator client receives)

BAD_VALUE examples that MUST be covered:

• message_type != yona.payment_intent
• ruleset_id != yona:ruleset:v1.0
• iss != retrieve_intent.aud
• aud != retrieve_intent.iss
• returned intent_locator does not match the requested locator
• payment_terms.amount non-canonical
• payment_terms.amount_units != minor
• payment_terms.currency non-canonical
• acceptable_asset_types empty where the ruleset requires at least one acceptable asset type
• acceptable_asset_types[*] invalid under CAIP-19
• expired exp
• replayed jti

6.4 yona.authorization_request (beneficiary server receives)

6.4.1 Common fields for both request forms

BAD_VALUE examples that MUST be covered:

• message_type != yona.authorization_request
• ruleset_id != yona:ruleset:v1.0
• intent_id violates ASCII-restricted identifier rules
• non-integer iat or exp
• expired exp

6.4.2 Pull-payment form

BAD_VALUE examples that MUST be covered:

• embedded_payment_intent is not a JWS Compact Serialization string
• embedded payment intent signature invalid
• embedded payment intent exp expired
• embedded payment intent jti replayed under receiver policy
• authorization_request.iss != decoded_payment_intent.aud
• authorization_request.aud != decoded_payment_intent.iss

6.4.3 Push-payment form

BAD_VALUE examples that MUST be covered:

• beneficiary_handle violates required form or constraints
• aud != DID encoded in beneficiary_handle
• payment_terms.amount non-canonical
• payment_terms.amount_units != minor
• payment_terms.currency non-canonical
• intended_asset_type invalid under CAIP-19

6.4.4 Request-form classification and mixed-field cases

The harness MUST instantiate cases showing that the receiver deterministically rejects:

Mixed-field / classification case

• a request with embedded_payment_intent present and any of beneficiary_handle, payment_terms, or intended_asset_type also present
• a request with beneficiary_handle, payment_terms, and intended_asset_type present but embedded_payment_intent also present
• a request with neither valid pull form nor valid push form
• a push-form request missing required intended_asset_type
• a push-form request that includes embedded_payment_intent
• a pull-form request that includes any disallowed push-form fields

6.5 yona.authorization_response (originator client receives)

BAD_VALUE examples that MUST be covered:

• message_type != yona.authorization_response
• ruleset_id != yona:ruleset:v1.0
• decision not equal to ACCEPT or REJECT
• iss != authorization_request.aud
• aud != authorization_request.iss
• intent_id != authorization_request.intent_id
• request_jws_sha256 mismatch
• expired exp
• replayed jti

7. Duplicate JSON Member Tests

A separate duplicate-member case MUST be instantiated for each message type:

Expected result:

• message is invalid
• receiver MUST reject
• for authorization, the receiver MUST return terminal REJECT if bindable; otherwise it MUST NOT return a YONA response message
• for retrieval, the endpoint MUST NOT produce a successful yona.payment_intent

8. DID / JOSE / Signature Profile Matrix

9. request_jws_sha256 Tests

10. Malformed JOSE Body Tests

11. Wrong-Binding Cases

12. Replay and Freshness Tests

12.1 Signed-message replay tests

For each message type other than yona.authorization_request, the harness MUST replay the exact same valid JWS within the active test session.

Replay rule:

• the implementation under test MUST apply its local replay policy to (iss, jti)
• a replayed message MUST NOT be treated as a new valid message

Repeated yona.authorization_request messages are tested under Section 12.2, not here.

12.2 Repeated yona.authorization_request tests

For yona.authorization_request, the harness MUST test repeated requests within the same (iss, intent_id) scope.

The harness MUST cover:

• a materially equivalent repeat whose non-material differences include one or more of: jti, iat, exp, kid, or signature bytes
• a materially changed repeat with one or more material authorization inputs changed
• a repeated request that receives a newly generated response bound to the repeated request bytes

Expected behavior:

• a materially equivalent repeat MUST NOT be treated as a replay solely because it is a new signed message with a different jti
• a materially equivalent repeat MUST receive the same terminal decision, newly bound to the repeated request bytes
• a materially changed repeat MUST be handled according to the ruleset's repeated-request outcome rules

12.3 Freshness tests

For each message type, the harness MUST instantiate:

• valid exp
• expired exp
• boundary case where exp equals the current test time according to receiver policy

The expected boundary-case outcome MUST be documented by the implementation and MUST be consistent across runs.

13. Prohibited Content Tests

Where the ruleset requires rejection if prohibited PII, Travel Rule payload data, destination addresses, settlement instructions, or other prohibited content appears in defined YONA semantic fields, the suite MUST include explicit tests placing clearly prohibited content into:

• defined fields of push-form yona.authorization_request
• defined fields of pull-form yona.authorization_request, including embedded_payment_intent
• defined fields of yona.authorization_response

These tests MUST NOT assume any global PII detector for unknown fields.

If the suite includes unknown-field cases, it MUST enumerate those unknown field names explicitly as suite fixtures and treat them as suite-specific checks rather than protocol semantics.

14. Byte-Exact Hashing Fixtures for request_jws_sha256

This section provides exact-byte fixtures for validating request_jws_sha256 handling under yona:ruleset:v1.0.

The canonical fixture bytes for this section are the raw downloadable .jws artifacts published with this suite release. The exact JWS Compact Serialization shown below are derived from those raw artifacts and are included for inspection and cross-checking.

For hashing and comparison, implementations MUST use the exact JWS Compact Serialization of the published raw artifact. Reserialized JSON, reconstructed JOSE objects, normalized strings, trimmed strings, or reformatted document renderings are not equivalent.

14.1 Fixture publication rule

For this release, the following raw artifacts are published as companion fixtures:

• fixture-a-push-authorization-request.jws
• fixture-b-pull-authorization-request.jws
• fixture-c-authorization-response.jws
• expected.json

expected.json records the expected derived outputs for these fixtures. If a rendered HTML or PDF representation wraps lines or otherwise alters presentation, the raw artifact bytes remain authoritative.

14.2 Fixture A — Push-payment authorization request

Raw artifact: fixture-a-push-authorization-request.jws

Exact JWS Compact Serialization:

eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDp3ZWI6by5leGFtcGxlI2sxIn0.eyJpc3MiOiJkaWQ6d2ViOm8uZXhhbXBsZSIsImF1ZCI6ImRpZDp3ZWI6Yi5leGFtcGxlIiwiaWF0IjoxNzYwMDAwMDAwLCJleHAiOjE3NjAwMDAwNjAsImp0aSI6Imp0aV8wMDAxIiwibWVzc2FnZV90eXBlIjoieW9uYS5hdXRob3JpemF0aW9uX3JlcXVlc3QiLCJydWxlc2V0X2lkIjoieW9uYTpydWxlc2V0OnYxLjAiLCJpbnRlbnRfaWQiOiJpbnRlbnQwMDEiLCJiZW5lZmljaWFyeV9oYW5kbGUiOiJkaWQ9ZGlkOndlYjpiLmV4YW1wbGU7YWxpYXM9YWxpYXMwMDEiLCJwYXltZW50X3Rlcm1zIjp7ImFtb3VudCI6IjEyNTAiLCJhbW91bnRfdW5pdHMiOiJtaW5vciIsImN1cnJlbmN5IjoiVVNEIn19.AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0-Pw

Expected output

14.3 Fixture B — Pull-payment authorization request

Raw artifact: fixture-b-pull-authorization-request.jws

Exact JWS Compact Serialization:

eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDp3ZWI6by5leGFtcGxlI2sxIn0.eyJpc3MiOiJkaWQ6d2ViOm8uZXhhbXBsZSIsImF1ZCI6ImRpZDp3ZWI6Yi5leGFtcGxlIiwiaWF0IjoxNzYwMDAwMTAwLCJleHAiOjE3NjAwMDAxNjAsImp0aSI6Imp0aV8wMDAyIiwibWVzc2FnZV90eXBlIjoieW9uYS5hdXRob3JpemF0aW9uX3JlcXVlc3QiLCJydWxlc2V0X2lkIjoieW9uYTpydWxlc2V0OnYxLjAiLCJpbnRlbnRfaWQiOiJpbnRlbnQwMDIiLCJlbWJlZGRlZF9wYXltZW50X2ludGVudCI6eyJwYXltZW50X2ludGVudF9qd3MiOiJleUpoYkdjaU9pSkZaRVJUUVNKOS5leUpwYzNNaU9pSmthV1E2ZDJWaU9tSXVaWGhoYlhCc1pTSXNJbUYxWkNJNkltUnBaRHAzWldJNmJ5NWxlR0Z0Y0d4bElpd2liV1Z6YzJGblpWOTBlWEJsSWpvaWVXOXVZUzl3WVhsdFpXNTBYMmx1ZEdWdWRDSXNJbkpzWlhObGRGOXBaQ0k2SW5sdmJtRTZjbVZzWlhObGREcDJNUzR3SW4wLkFRSUQifX0.__79_Pv6-fj39vX08_Lx8O_u7ezr6uno5-bl5OPi4eDf3t3c29rZ2NfW1dTT0tHQz87NzMvKycjHxsXEw8LBwA

Expected output

14.4 Fixture C — Authorization response referencing Fixture A

Raw artifact: fixture-c-authorization-response.jws

This fixture is a terminal yona.authorization_response whose request_jws_sha256 value equals the expected request_jws_sha256 derived from Fixture A.

Exact request_jws_sha256 value embedded in response:

K6yu9XHzgfyiTt5e6UFxSVmRsEoBg-IGdjbsN5DB4KM

Exact response JWS Compact Serialization:

eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDp3ZWI6Yi5leGFtcGxlI2sxIn0.eyJpc3MiOiJkaWQ6d2ViOmIuZXhhbXBsZSIsImF1ZCI6ImRpZDp3ZWI6by5leGFtcGxlIiwiaWF0IjoxNzYwMDAwMDAxLCJleHAiOjE3NjAwMDAwNjEsImp0aSI6Imp0aV9yMDAxIiwibWVzc2FnZV90eXBlIjoieW9uYS5hdXRob3JpemF0aW9uX3Jlc3BvbnNlIiwicnVsZXNldF9pZCI6InlvbmE6cnVsZXNldDp2MS4wIiwiaW50ZW50X2lkIjoiaW50ZW50MDAxIiwiZGVjaXNpb24iOiJBQ0NFUFQiLCJyZXF1ZXN0X2p3c19zaGEyNTYiOiJLNnl1OVhIemdmeWlUdDVlNlVGeFNWbVJzRW9CZy1JR2RqYnNONURCNEtNIn0.CQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQ

Expected output

15. Deterministic REJECT vs NO_RESPONSE Decision Tables

15.1 Authorization endpoint (YonaAuthorizationService)

A beneficiary server receiving yona.authorization_request MUST apply the following logic:

Client interpretation (authorization flow):

• if no valid, verified terminal response is obtained by the cutoff, the outcome is NO_RESPONSE
• NO_RESPONSE MUST be treated as REJECT

15.2 Payment-intent retrieval endpoint (YonaPaymentIntentService)

Because yona:ruleset:v1.0 does not define a retrieval-REJECT message type, this suite does not require any signed retrieval-REJECT message.

For each applicable condition below, client and server behavior MUST match the expected outcomes shown.

16. Implementation Notes for Test Authors

Common drift points: