§ Ayra TRQP Implementers Guide

State: DRAFT

This document is a non-normative guide to help a member Trust Registry expose authorization and recognition information governed by the authority or authorities it serves through the Trust Registry Query Protocol (TRQP). The resulting interface supports direct use by consumers and participation in the Ayra-operated Registry of Registries (RoR) that anchors the Ayra Trust Network (ATN). It is intended as a starting point for bridging existing trust frameworks through a standardized interface; neither the profile nor the RoR becomes the source of a member registry’s authority.

§ Core Principle

The registry informs the decision.

The relying party makes the decision.

TRQP provides authorization and recognition information. It does not make a trust, acceptance, or transaction decision. In this principle, “relying party” is shorthand for any consuming organization or system that uses the information under its own policy, including a verifier, wallet application, agent, or other service.

§ Important Pre-Reads

Before diving into implementation details, we recommend familiarizing yourself with:

• Trust Registry Query Protocol (TRQP) v2.0 Specification
• W3C DID Core – DID URI, DID method, DID controller, and DID Document definitions
• Ayra TRQP Profile
• Introduction to Ayra
• Ayra Technical Whitepaper

§ Source of Truth

This guide is non-normative. Use it for explanation, examples, and implementation patterns.

When this guide appears to conflict with a normative source, use this order:

1. TRQP v2.0 for the core protocol model, HTTPS binding, and core field names.
2. W3C DID Core for DID URI, DID method, DID controller, and DID Document semantics.
3. Ayra TRQP Profile API for the Ayra API surface, request and response schemas, parameters, and status codes.
4. Ayra TRQP Profile for Ayra conformance policy.

Practical rules to keep in mind:

• Keep TRQP field names such as entity_id and authority_id; do not rename them to _did.
• Ayra _id values are DID URI strings.
• Supported DID methods are registry- or authority-specific and discoverable through GET /lookups/didMethods.
• Ayra extension endpoints are optional; unsupported extension endpoints return HTTP 501 with Problem Details.
• JWS response signing is recommended, not mandatory, until the signing mechanism is finalized.

§ API Specifications

The canonical API specification for Ayra TRQP is maintained as a single OpenAPI file and can be browsed interactively:

• Ayra TRQP Profile API – TRQP v2.0 core endpoints (trqp-core tag) and Ayra extension endpoints (ayra-extension tag)

§ TRQP Basics: Bridging Your Ecosystem

§ Overview

The Trust Registry Query Protocol (TRQP) is not intended to replace an existing intra-trust framework (such as OpenID Federation, X.509 PKI, EBSI Trust Chains, TRAIN, etc.). Rather, it acts as a bridge across frameworks, answering critical questions about who is authorized to do what under a particular governance framework.

TRQP v2.0 uses the PARC model (Principal, Action, Resource, Context) for all queries:

TRQP defines two main query types:

1. Authorization Query (POST /authorization) – “Does Entity X have authorization to perform Action Y on Resource Z, according to Ecosystem W?”
2. Recognition Query (POST /recognition) – “Does Ecosystem A recognize Ecosystem B for Action Y on Resource Z?”

Within the Ayra Trust Network, conforming to both queries is a minimum requirement to participate.

When bridging into an ecosystem, you may need adapters tailored to that ecosystem’s internal trust framework. The diagram below shows the conceptual architecture:

You can develop or reuse any internal trust model you prefer. The profile requires you to expose the necessary TRQP endpoints so that external consumers can query the authorization and recognition information your registry is governed to provide.

§ Key Participants

§ Key Takeaways

1. The registry informs the decision; the relying party makes the decision. “Relying party” here includes any consuming organization or system. TRQP supplies authorization and recognition information; the consumer makes or automates its own trust, acceptance, or transaction decision under its applicable policy.
2. TRQP complements your systems of record, operational processes, and governance frameworks. It provides a simple, consistent way for external systems to query your system for only the answers you are willing to provide.
3. TRQP is a bridge across frameworks and is agnostic to specific internal trust methods.
4. You must handle how to map your internal trust model to TRQP’s PARC query structure.
5. TRQP answers two questions:
   • Is this entity authorized? – “Does Entity X have the right to perform Action Y on Resource Z, in the context of Ecosystem W?”
   • Do you recognize this other ecosystem? – “Does Ecosystem A recognize Ecosystem B for Action Y on Resource Z?”

§ Ayra Profile at a Glance

Ayra-conformant Trust Registries:

• MUST implement both TRQP core endpoints: POST /authorization and POST /recognition.
• MUST use TRQP-compatible _id field names, including entity_id and authority_id; these fields MUST NOT be renamed to _did.
• MUST represent all Ayra _id values as DID URI strings.
• MUST return RFC 7807 Problem Details using application/problem+json for error responses.
• MAY apply rate limits; a returned rate-limit response uses HTTP 429 and does not provide an authorization or recognition result.
• MAY implement Ayra extension endpoints for metadata, entity discovery, ecosystem discovery, and lookups.
• MUST return HTTP 501 with Problem Details when an optional Ayra extension endpoint is not implemented.
• SHOULD sign responses with JWS where supported; the signing mechanism is still being finalized.

§ Conformance Checklist

The following table maps TRQP v2.0 conformance requirements to what an Ayra implementer must provide. This is a summary; refer to the TRQP v2.0 specification and Ayra Profile for normative requirements.

§ Core Requirements for the Ayra Trust Network

To be a compatible Trust Registry for Ayra, your registry must support the Ayra TRQP Profile.

Your implementation MUST:

• Accept POST /authorization queries and return conforming Authorization Responses.
• Accept POST /recognition queries and return conforming Recognition Responses.
• Use RFC 7807 Problem Details with Content-Type: application/problem+json for all error responses.
• Return HTTP 429 with RFC 7807 Problem Details when responding because a request rate limit has been exceeded.

Your implementation SHOULD sign responses with JWS using the Trust Registry controller’s or operator’s keys where supported.

This means your ecosystem must track and provide the state of who is authorized to do what, and publish that data via a TRQP-enabled endpoint.

§ Request and Response Examples

§ Authorization Query

Request:

POST /authorization
Content-Type: application/json

{
  "entity_id":    "did:webvh:example.com:issuer-123",
  "authority_id": "did:webvh:example-ecosystem.org",
  "action":       "issue",
  "resource":     "credential:driverlicense",
  "context": {
    "time": "2026-02-17T12:00:00Z"
  }
}

Success Response (200):

{
  "entity_id":      "did:webvh:example.com:issuer-123",
  "authority_id":   "did:webvh:example-ecosystem.org",
  "action":         "issue",
  "resource":       "credential:driverlicense",
  "authorized":     true,
  "time_evaluated":  "2026-02-17T12:00:00Z",
  "time_requested":  "2026-02-17T12:00:00Z",
  "message":        "Entity is authorized to issue credential:driverlicense"
}

Error Response (404):

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type":   "https://example.com/problems/entity-not-found",
  "title":  "Entity not found",
  "status": 404,
  "detail": "Entity did:webvh:example.com:issuer-123 is not registered in this ecosystem."
}

§ Recognition Query

Request:

POST /recognition
Content-Type: application/json

{
  "entity_id":    "did:webvh:partner-ecosystem.org",
  "authority_id": "did:webvh:ayra.forum",
  "action":       "recognize",
  "resource":     "ecosystem"
}

Success Response (200):

{
  "entity_id":      "did:webvh:partner-ecosystem.org",
  "authority_id":   "did:webvh:ayra.forum",
  "action":         "recognize",
  "resource":       "ecosystem",
  "recognized":     true,
  "time_evaluated":  "2026-02-17T12:00:01Z",
  "message":        "Ecosystem is recognized by the Ayra Trust Network"
}

§ Registering Your Ecosystem with Ayra

Joining the Ayra Trust Network involves:

1. Providing a valid DID for your ecosystem.
2. Completing the Ayra Trust Network governance process (review, approval, etc.).

§ Creating an Identifier for Your Registry

1. Prepare Your Trust Registry Keys – Generate cryptographic keys for your Trust Registry identifier when the identifier method supports controller keys.

2. Create Your Trust Registry ID – Use a globally unique DID for the registry. The DID method you choose may affect the assurance level the registry can claim. did:webvh is preferred and may be required for higher assurance levels, while other DID methods may be acceptable according to authority policy. The DID Document should include at least one service endpoint referencing a TRQP profile at https://ayra.forum/profiles/trqp/tr/v2.

§ Creating an Identifier for Your Ecosystem

1. Prepare Ecosystem Keys – Generate cryptographic keys for your ecosystem identifier when the identifier method supports controller keys.

2. Generate Your Ecosystem/Authority ID – The ecosystem DID is normally used as the TRQP authority_id. The DID Document should make the ecosystem governance framework and authoritative Trust Registry endpoint(s) discoverable.

3. Provide Your Ecosystem/Authority ID to Ayra – Complete the governance review and register your ecosystem identifier with Ayra.

§ Performing Authority Queries as a Verifier

Below is a step-by-step process for how a verifier would make TRQP queries.

§ Step 1: Check Ecosystem Recognition

1. Resolve Ayra’s DID – Retrieve Ayra’s DID document (did:webvh:ayra.forum) to find its TRQP endpoints.

2. Query the Ayra Trust Network for Recognition:

POST /recognition
Content-Type: application/json

{
  "entity_id":    "{target_ecosystem_id}",
  "authority_id": "did:webvh:ayra.forum",
  "action":       "recognize",
  "resource":     "ecosystem"
}

If the target ecosystem is recognized, the response indicates recognized: true.

§ Step 2: Check Entity Authorization

1. Resolve the Target Ecosystem’s DID – Extract the TRQP endpoint from the ecosystem DID’s service endpoints.

2. Query the Ecosystem’s Trust Registry:

POST /authorization
Content-Type: application/json

{
  "entity_id":    "{entity_id}",
  "authority_id": "{target_ecosystem_id}",
  "action":       "issue",
  "resource":     "credential:driverlicense"
}

The response indicates whether the entity is authorized: true or authorized: false.

§ Full Verification Flow

§ Bridge Case Studies

Detailed bridge case studies demonstrating how to connect specific trust frameworks to TRQP are planned for a future iteration. Target frameworks include:

• OpenID Federation – Bridging OpenID Federation trust chains to TRQP authorization queries
• ETSI Trust Lists – Mapping ETSI Trusted Lists to TRQP recognition and authorization
• TRAIN – Integrating TRAIN trust infrastructure with TRQP endpoints
• cheqd – Bridging cheqd accreditation trust chains to TRQP

§ Ayra Extension Endpoints

The Ayra Trust Network defines additional endpoints on top of TRQP core. These endpoints enable discovery of ecosystem-specific data beyond basic authorization and recognition. They are optional. Registries that do not implement an extension endpoint return HTTP 501 with a Problem Details response.

See the Ayra TRQP Profile API for full details on request parameters, response schemas, and error codes.

§ Error Handling

All error responses MUST conform to RFC 7807 Problem Details and use Content-Type: application/problem+json. The OpenAPI specification defines the status codes for each endpoint. The most common statuses are:

RFC 7807 remains the applicable requirement because this Ayra profile targets TRQP v2.0. RFC 9457 has obsoleted RFC 7807 at the IETF level, but it is only a forward-compatibility consideration for Ayra unless a future TRQP version and corresponding Ayra profile version expressly adopt it. Both versions use application/problem+json; clients cannot infer the governing RFC from the media type or the core Problem Details members.

§ Rate Limiting

Registries may apply rate limits to any core or extension endpoint. If a registry returns a response because a rate limit was exceeded, it uses HTTP 429 with an RFC 7807 Problem Details body:

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
Cache-Control: no-store

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "The request rate limit has been exceeded."
}

Retry-After should be included when useful retry timing is available. A consumer should honor it; if it is absent, use bounded exponential backoff with jitter according to local policy. Do not parse title or detail for retry timing.

The about:blank type is sufficient for the standard HTTP 429 meaning. A registry may instead use a stable, documented problem type URI and may add extensions such as documentation or contact. Consumers must ignore extensions they do not recognize.

A 429 response means that the registry did not answer the authorization or recognition question. Never interpret it as authorized: false or recognized: false, and never store it as a negative result. Responses with status 429 must not be stored by a cache.

This response shape conforms to RFC 7807 and is also compatible with RFC 9457. Supporting it does not adopt RFC 9457 as the normative error specification for this profile.

§ Security Considerations

• Trust Anchor Hijacking – Attackers may attempt to spoof or manipulate registry data. Use strong cryptographic anchors and key rotation.
• DNS Hijacking – If domain-based endpoints are used, DNS spoofing can misdirect queries. Use DNSSEC where possible.
• Replay Attacks – Reusing valid requests or responses to gain unauthorized access. Use timestamps, nonces, and short-lived tokens.
• Data Integrity – Use JWS to sign responses where supported (recommended by the Ayra Profile).
• Denial of Service – Rate limiting, caching, or load balancing may be necessary. When returning a rate-limit response, use the profile-defined HTTP 429 behavior.
• Insufficient Data Validation – Validate all input against the TRQP JSON schemas before processing.
• Logging and Auditing – Maintain detailed access logs for attack detection and compliance.
• Protocol Downgrade Attacks – Always use the latest TRQP version; do not allow fallback.
• Privacy – Only DIDs and query parameters are transmitted. Limit personal data in requests and responses. Be aware of correlation risks from IP-level monitoring.

§ Key Security Takeaways

• Manage cryptographic keys securely and implement key rotation.
• Provide robust responses and sign them using JWS where supported.
• Retain thorough access logs.
• Validate all inputs against the TRQP schemas.

§ Smoke Testing

This repository includes a lightweight smoke test at tests/api_conformance_test.py. Use it to check that a registry exposes the expected endpoint shape and returns profile-shaped JSON for implemented endpoints.

The smoke test is not a certification suite. It does not prove full protocol, governance, credential-flow, or interoperability conformance.

Example:

python tests/api_conformance_test.py --base-url https://example-trust-registry.com

§ Q&A

§ What is an Ecosystem Governance Framework (EGF)?

An EGF is the overarching governance model for a digital trust ecosystem. It may incorporate policies, credential rules, or references to other frameworks. In practice, it is typically a set of documents published at an HTTP-resolvable URI describing how the ecosystem operates, its rules, and its participants’ obligations.

The Ayra Profile requires the EGF URI to be discoverable through the Ecosystem DID’s service endpoints.

§ How should I think about authorizations?

An authorization represents a set of privileges granted to an entity – an “official” sanction to perform a cryptographic function or other sensitive activity. (Source: NIST SP 800-57 Part 2 Rev.1)

In TRQP v2.0, an authorization is expressed as an action + resource pair (e.g. action=issue, resource=credential:driverlicense). Your internal authorization models are entirely up to you. External consumers will query with these parameters and receive a boolean authorized response.

§ What types of entries can I support?

TRQP is not prescriptive about your internal model. As long as you can map (entity_id, authority_id, action, resource) to a boolean authorization state, you can use TRQP.

• entity_id – The DID for the entity being tested (e.g. an issuer)
• authority_id – The DID for the ecosystem that governs this authorization
• action – What the entity is authorized to do (e.g. issue, verify)
• resource – What the action applies to (e.g. credential:driverlicense)

§ What is the difference between recognition and authorization?

• Recognition is a peer-level statement: one ecosystem acknowledges another ecosystem’s authority. There is no formal control relationship.
• Authorization is a hierarchical statement: an ecosystem grants specific privileges to an entity within its governance framework.

§ Does this work offline?

You can cache recognition and authorization data locally, but it may become stale. Whether you allow offline checks depends on your ecosystem’s tolerance for stale information. There are no specific requirements for caching behavior.

§ What about “phone home”?

The TRQP HTTPS binding requires real-time HTTP calls to the registry. Future bindings (e.g. DIDComm, TSP) may offer alternatives that reduce or eliminate the need for real-time connectivity.

§ Is a query to the Ayra Trust Network private?

No Personally Identifiable Information is shared when making a query. Queries are formed only using DIDs and action/resource strings. However, correlation risks exist at the network level (IP addresses combined with query patterns).

§ How does this fit with regulatory requirements?

Local ecosystems must ensure compliance with their regulatory obligations. Ayra’s governance process includes regulatory and policy alignment at the network level. Consult the Ayra governance documentation for specific requirements.