trqp-0.5.0 is not a library.

Affinidi Trust Registry

A high-performance, Rust-based implementation of a Trust Registry, fully compliant with the Trust Registry Query Protocol (TRQP) v2.0 specification. Built for scalability and reliability, it enables secure, standards-based verification of trusted entities within decentralised identity ecosystems.

Quickstart
What is Trust Registry
- Why a Trust Registry Matters
- Sample Use Cases
Key Components
Requirements
Set up Trust Registry
Run Trust Registry on Docker
Using Redis as Storage Backend
Test the API
- Recognition Query
- Authorization Query
Manage Trust Records
Environment Variables
- Profile Config Options
Additional Resources
Support & feedback
- Reporting technical issues
Contributing

Quickstart

Get the Trust Registry up and running quickly with default settings (DIDComm disabled).

Run the setup command to generate default configurations.

cargo run --bin setup-trust-registry --features="dev-tools"

Start the Trust Registry server.

ENABLE_DIDCOMM=false RUST_LOG=info cargo run --bin trust-registry

The Trust Registry will start on http://localhost:3232 using CSV file storage with sample data from ./sample-data/data.csv.

Test your Trust Registry setup.

# Query authorization
curl --location 'http://localhost:3232/authorization' \
--header 'Content-Type: application/json' \
--data '{
    "authority_id": "did:example:authority1",
    "entity_id": "did:example:entity1",
    "action": "action1",
    "resource": "resource1"
}'

For more details on how to set up and run the Trust Registry, see the Set up Trust Registry section.

What is Trust Registry

A Trust Registry is a system that maintains and provides authoritative information about which entities, such as organisations, issuers, and verifiers, are authorised to perform specific actions on defined resources within a trust framework. Each entity is identified by its Decentralised Identifier (DID), ensuring cryptographic integrity and interoperability across decentralised identity ecosystems.

Why a Trust Registry Matters

In decentralised identity and verifiable credentials, verifiers need to answer critical trust questions before accepting or validating credentials, such as:

"Is this issuer authorised to issue driver's licences?"
"Is this credential verifier recognised by the appropriate authority?"
"Can this entity perform a specific action within this trust framework?"

The Trust Registry provides a standardised, queryable database that answers these trust questions by maintaining trust records and their permitted roles within a governance framework.

Authorisation Queries: “Has Authority A authorised Entity B to take Action X on Resource Y?”

Recognition Queries: "Does Authority X recognise Entity B as an authority to authorise taking Action X on Resource Y?”

The Trust Registry links:

Entity IDs (who) - DIDs representing issuers, verifiers, or other participants.
Authority IDs (governed by whom) - DIDs of governing authorities.
Actions (what) - Operations like "issue", "verify", "revoke".
Resources (on what) - Credential types like "driverlicence", "diploma".
Context - Additional metadata for authorisation decisions.

This ensures security, compliance, and interoperability across decentralised identity systems.

Sample Use Cases

Credential Issuance Verification

Verifies whether an issuer is authorised by a government or regulatory body to issue specific credential types (e.g., driver’s licences, professional certifications).
Trust Framework Compliance

Ensures that all participants in a digital trust ecosystem, such as issuers, verifiers, and relying parties, are recognised and approved by the appropriate governance authorities.

Key Components

trust-registry: Unified server providing both RESTful API (TRQP endpoints for recognition and authorisation queries) and optional DIDComm messaging interface for CRUD admin operations.
Storage backends: Stores authoritative records about the entities for querying. It supports the following storage types:
- CSV file storage
- AWS DynamoDB
- Redis

Requirements

Install Rust on your machine.

Rust: 1.88.0 or higher
Edition: 2024
Cargo: Latest version bundled with Rust

Verify that your Rust installation meets the requirements.

rustc --version
cargo --version

Required for DIDComm-enabled. DIDComm mediator instance is required if you want to enable DIDComm for secure trust record management and querying.

To deploy and run a DIDComm mediator, see the deployment options page in the documentation.

Set up Trust Registry

Configure the environment to run Trust Registry. The setup command creates the .env file with default configurations. For testing environments, it generates .env.test or .env.pipeline files with the appropriate test configurations.

Run with DIDComm Enabled

Prerequisites: You must have a running and accessible DIDComm mediator instance before proceeding. The mediator provides the messaging layer for secure communication between administrators, verifiers, and the Trust Registry.

If you don't have a mediator yet, see deployment options.

To enable DIDComm for managing and querying trust records, run the following command with your mediator's DID:

cargo run --bin setup-trust-registry --features="dev-tools" -- \
 --mediator-did=<MEDIATOR_DID>

The command generates the following:

Creates a Decentralised Identifier (DID) for the Trust Registry using the did:peer method.
Creates Decentralised Identifiers (DIDs) for test users (Trust Registry and Admin) using the did:peer method.
Configures the appropriate DIDComm mediator ACLs for the Trust Registry and test user DIDs.
Populates the environment variables with default values, such as Storage Backend (csv) and audit log format (json).

Run with DIDComm Enabled In Private Mode

By default, the Trust Registry runs in public mode (ACL_MODE=ExplicitDeny), which accepts messages from any DID. To enable private mode where only pre-authorized DIDs can send messages to the Trust Registry, use the --acl-mode=ExplicitAllow option:

cargo run --bin setup-trust-registry --features="dev-tools" -- \
 --mediator-did=<MEDIATOR_DID> \
 --acl-mode=ExplicitAllow

With this setup command:

Sets the Trust Registry ACL mode to ExplicitAllow (private mode).
Only DIDs in the mediator's allow list for the Trust Registry can send messages (configured via the mediator ACLs during setup).
Denies all other DIDs, enhancing security for sensitive deployments.

Use cases for private mode:

Production environments that require strict access control.
Scenarios where only specific administrators should manage trust records.
Compliance requirements that demand explicit authorisation.

After successful setup, it displays the command to run the Trust Registry.

RUST_LOG=info cargo run --bin trust-registry

Run with DIDComm Disabled

To configure the Trust Registry without integration with DIDComm, run the following command:

cargo run --bin setup-trust-registry --features="dev-tools"

The command generates the following:

Populates the environment variables with default values, such as Storage Backend (csv) and audit log format (json).
Sets DIDComm-related environment variables to empty values.

After successful setup, it displays the command to run the Trust Registry.

ENABLE_DIDCOMM=false RUST_LOG=info cargo run --bin trust-registry

For more details on setting up the Trust Registry, refer to the setup guide document.

Run Trust Registry on Docker

After setting up the Trust Registry, review the Docker settings in ./docker-compose.yaml. Start the containers using the following command:

docker compose up --build

The Trust Registry will be available at http://localhost:3232.

Note: The sample-data folder is mounted as a volume to synchronise the changes from data.csv to the container automatically. If you have configured a different path for the data using CSV as the storage backend, configure the Docker settings accordingly.

Using Redis as Storage Backend

Redis is a high-performance, in-memory data store that can be used as a storage backend for Trust Registry. Redis provides fast read/write operations and is ideal for production deployments requiring low-latency access to trust records.

Prerequisites

Redis server 5.0 or higher
Network access to the Redis instance from the Trust Registry

Setup Redis Storage

Install Redis (if not already available)

# macOS
brew install redis

# Ubuntu/Debian
sudo apt-get install redis-server

# Docker
docker run -d -p 6379:6379 redis:7-alpine

Start Redis (if installed locally)
```
redis-server
```

Configure Trust Registry to use Redis

Set the following environment variables:

TR_STORAGE_BACKEND=redis
REDIS_URL="redis://localhost:6379"

For Redis with authentication:

REDIS_URL="redis://username:password@localhost:6379"

For Redis with a specific database:

REDIS_URL="redis://localhost:6379/0"

Run Trust Registry

ENABLE_DIDCOMM=false RUST_LOG=info cargo run --bin trust-registry

Redis Storage Features

Fast Operations: In-memory storage provides sub-millisecond response times
Persistence: Redis can be configured for data persistence using RDB snapshots or AOF (Append Only File)
Scalability: Supports clustering and replication for high availability
Data Structure: Trust records are stored as JSON strings with keys formatted as entity_id|authority_id|action|resource

Production Considerations

For production deployments:

Enable Persistence: Configure Redis persistence to prevent data loss

# In redis.conf
save 900 1
save 300 10
save 60 10000
appendonly yes

Use Authentication: Always enable Redis authentication in production
```
# In redis.conf
requirepass your_strong_password
```
Configure Memory Limits: Set appropriate memory limits and eviction policies
```
# In redis.conf
maxmemory 2gb
maxmemory-policy noeviction
```

Use TLS: For secure connections, use Redis with TLS

export REDIS_URL="rediss://username:password@host:6380"

Monitor Performance: Use Redis monitoring tools to track performance
```
redis-cli INFO
redis-cli MONITOR
```

Docker Compose with Redis

Example docker-compose.yaml configuration:

version: '3.8'

services:
  redis:
    image: redis:7-alpine
    command: redis-server --requirepass your_password --appendonly yes
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

  trust-registry:
    build: .
    environment:
      - TR_STORAGE_BACKEND=redis
      - REDIS_URL=redis://:your_password@redis:6379
      - ENABLE_DIDCOMM=false
      - CORS_ALLOWED_ORIGINS=http://localhost:3000
      - AUDIT_LOG_FORMAT=json
    ports:
      - "3232:3232"
    depends_on:
      - redis
    restart: unless-stopped

volumes:
  redis-data:

Migrating from CSV/DynamoDB to Redis

To migrate existing trust records to Redis:

Export records from your current storage backend
Use the DIDComm admin API to create records in Redis
Verify all records are migrated correctly
Update the TR_STORAGE_BACKEND environment variable to redis

Troubleshooting

Connection Issues:

# Test Redis connectivity
redis-cli -h localhost -p 6379 ping
# Expected output: PONG

View stored records:

# List all keys
redis-cli KEYS "*|*|*|*"

# Get a specific record
redis-cli GET "did:example:entity1|did:example:authority1|action1|resource1"

Clear all test data:

redis-cli FLUSHDB

Test the API

You can test the Trust Registry by querying the sample data stored in ./sample-data/data.csv:

Recognition Query

curl --location 'http://localhost:3232/recognition' \
--header 'Content-Type: application/json' \
--data '{
    "authority_id": "did:example:authority1",
    "entity_id": "did:example:entity1",
    "action": "action1",
    "resource": "resource1"
}'

The API will return whether the specified entity is recognised by the given authority for the requested action and resource.

To query Trust Registry using DIDComm, refer to the Trust Registry Recognition Query protocol.

Authorization Query

curl --location 'http://localhost:3232/authorization' \
--header 'Content-Type: application/json' \
--data '{
    "authority_id": "did:example:authority1",
    "entity_id": "did:example:entity1",
    "action": "action1",
    "resource": "resource1"
}'

The API will return whether the specified entity is authorised under the given authority for the requested action and resource.

To query Trust Registry using DIDComm, refer to the Trust Registry Authorization Query protocol.

Testing Tips:

Add more records to ./sample-data/data.csv to expand test coverage.
Test with both defined and undefined IDs to ensure the system correctly handles invalid or missing identifiers.
Ensure the context field contains a valid JSON object encoded in Base64. Invalid or malformed data should trigger appropriate error responses.

Manage Trust Records

Note: This section applies only when DIDComm is enabled. See Run with DIDComm Enabled for setup instructions.

You can manage trust records stored in the Trust Registry using DIDComm by sending messages to the Trust Registry's DID. DIDComm provides a secure, interoperable way to exchange messages between an administrator and the Trust Registry, making it ideal for trust record operations such as creating, updating, or querying records.

For a working reference, see the test-client implementation, which demonstrates how to build a DIDComm client and send admin operation messages.

See Trust Registry Administration section for more details.

Environment Variables

See the list of environment variables and their usage.

Variable Name	Description	Required
`TR_STORAGE_BACKEND`	Storage backend for trust records. Options: `csv`, `ddb`, `redis`.	Yes
`FILE_STORAGE_PATH`	Path to the CSV file when using CSV as the storage backend.	Required when `TR_STORAGE_BACKEND` = `csv`
`DDB_TABLE_NAME`	DynamoDB table name for storing trust records when using DDB as the storage backend.	Required when `TR_STORAGE_BACKEND` = `ddb`
`REDIS_URL`	Redis connection URL when using Redis as the storage backend. Format: `redis://host:port` or `redis://username:password@host:port/db`.	Required when `TR_STORAGE_BACKEND` = `redis`
`CORS_ALLOWED_ORIGINS`	Comma-separated list of allowed URLs for CORS.	Yes
`AUDIT_LOG_FORMAT`	Output format for audit logs. Options: `text`, `json`.	Yes
`MEDIATOR_DID`	Decentralised Identifier (DID) of the DIDComm mediator used as a transport layer for managing trust records.	Required when DIDComm is enabled
`ADMIN_DIDS`	Comma-separated list of DIDs authorised to manage trust records in the Trust Registry.	Required when DIDComm is enabled
`PROFILE_CONFIG`	Trust Registry DID and DID secrets for DIDComm communication. See Profile Config Options for configuration formats. *Sensitive information, do not share.*	Required when DIDComm is enabled
`ACL_MODE`	ACL Mode for Trust Registry when DIDComm is enabled. ExplicitDeny - public mode, ExplicitAllow - private mode	default: `ExplicitDeny`

Profile Config Options

The PROFILE_CONFIG environment variable uses a URI-based loader that supports multiple configuration options. The loader allows you to store DID and DID secrets securely according to your deployment requirements.

Scheme	Format	Description
Direct Value	`PROFILE_CONFIG='<JSON_STRING>'`	Store the configuration directly as an inline JSON string in the environment variable. Recommended for local development.
String Protocol	`PROFILE_CONFIG='string://<JSON_STRING>'`	Explicitly specify the value as a string literal. Same functionality as the direct value option.
File System	`PROFILE_CONFIG='file://path/to/config.json'`	Load configuration from a JSON file on the local filesystem. The path must be accessible by the application.
AWS Secrets Manager	`PROFILE_CONFIG='aws_secrets://<SECRET_NAME>'`	Retrieve configuration from AWS Secrets Manager. The secret value must be stored in plaintext format as a JSON string.
AWS Parameter Store	`PROFILE_CONFIG='aws_parameter_store://<PARAMETER_NAME>'`	Load configuration from AWS Systems Manager Parameter Store. The parameter value must be a JSON string.

Expected Value:

All options must provide the Trust Registry DID and DID secrets in the following JSON structure:

{
  "alias": "Trust Registry",
  "did": "did:peer:2.VzDna...",
  "secrets": [
    {
      "id": "did:peer:2.VzDna...#key-1",
      "privateKeyJwk": {
        "crv": "P-256",
        "kty": "EC",
        "x": "RgvVBx01Mva...",
        "y": "U5pT2A5WdIkD..."
      },
      "type": "JsonWebKey2020"
    },
    {
      "id": "did:peer:2.VzDna...#key-2",
      "privateKeyJwk": {
        "crv": "secp256k1",
        "d": "...",
        "kty": "EC",
        "x": "O9pWQXY...",
        "y": "TQk8LY_BcY..."
      },
      "type": "JsonWebKey2020"
    }
  ]
}

Examples:

# Direct value (local development)
PROFILE_CONFIG='{"alias":"Trust Registry","did":"did:peer:2.VzDna...","secrets":[...]}'

# File-based configuration
PROFILE_CONFIG='file:///etc/trust-registry/config.json'

# AWS Secrets Manager
PROFILE_CONFIG='aws_secrets://prod/trust-registry/profile'

# AWS Parameter Store
PROFILE_CONFIG='aws_parameter_store:///trust-registry/profile'

Note: If no URI scheme is specified, the loader parses the value as a direct string literal by default.

Additional Resources

Support & feedback

If you face any issues or have suggestions, please don't hesitate to contact us using this link.

Reporting technical issues

If you have a technical issue with the project's codebase, you can also create an issue directly in GitHub.

Ensure the bug was not already reported by searching on GitHub under Issues.
If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behaviour that is not occurring.

Contributing

Want to contribute?

Head over to our CONTRIBUTING guidelines.

trqp 0.5.0