Affinidi Messaging - Mediator Service

A mediator & relay service based on DIDComm v2 specification for handling connections, permissions, and messages sent over the network.

Table of Contents

• Prerequisites
• Running Mediator Service
• Supported Access Control Lists (ACLs)
  • Mediator-level ACLs
  • DID-level ACLs
• Common Mediator Operating Modes
  • Private Mediator - Closed Network
  • Private Mediator - Open Network
  • Public Mediator - Closed Network
  • Public Mediator - Open Network
  • Public Mediator - Mixed Mode
• Examples

Prerequisites

To build and run this project, you need to set up the following:

1. Install Rust (1.85.0 2024 Edition) on your machine if you haven't installed it yet using this guide.

2. Install Docker on your machine if you haven't installed it yet using this guide. We will need this to run Redis instance for the mediator.

Running Mediator Service

1. Run the Redis docker container using the command below:

   docker run --name=redis-local --publish=6379:6379 --hostname=redis --restart=on-failure --detach redis:latest
   

   The latest supported version of Redis is version 8.0.

2. Run setup_environment to configure the mediator with all the required information to run locally.

   You must run the following from the top-level directory of affinidi-messaging.

   cargo run --bin setup_environment
   

   This will generate:

   • Mediator DID and secrets.
   • Administration DID and secrets.
   • SSL Certificates for local development/testing.
   • Optionally, different users with their DIDs for testing.

3. Start affinidi-messaging-mediator service via:

   cd affinidi-messaging-mediator
   export REDIS_URL=redis://@localhost:6379
   cargo run
   

Supported Access Control Lists (ACLs)

The mediator service provides a granular set of access control lists to allow administrators to have greater control over who can send and receive messages within the network.

Mediator-level ACLs

DID-level ACLs

DID-level ACLs are permissions attached to a specific DID present in the mediator. These ACLs provide access control to whether a DID can store, send, or receive messages in the mediator.

The ACLs configured in the mediator's configuration apply by default to any DID added to the mediator.

Send and Receive Messages

The following ACL flags provide granular access control to users whether their DID can send or receive messages.

Self-change Flags

Self-change flags allow the users to update the Access Control List (ACLs) of their own DID instead of the mediator's administrator to have sole control of the ACLs.

This flag is useful if you want to provide a level of control for the user to update their ACL when needed - for example, in the Public Mediator - Open Network operating mode.

Common Mediator Operating Modes

Using the Access Control Lists (ACLs) available, as an administrator, you can configure the mediator to a different operating mode depending on how they want the mediator to handle the access and messages sent over the network.

Refer to the different mediator configurations that you can configure in the mediator.toml file for various operating modes.

Private Mediator – Closed Network

The strictest and most controlled mediator configuration.

A private messaging network that only allows users to communicate with specific users they are authorised with by the administrator using the ACLs. The administrator needs to add the user's DID to the mediator to establish each user's relationship and permission.

For example, a business may want to run a private messaging network only for select staff working on a merger deal that is private within the organisation - staff named Alice and Bob can only communicate with their manager. Still, Alice and Bob can't communicate with each other.

### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_allow}

### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:DENY_ALL,LOCAL,SEND_MESSAGES,RECEIVE_MESSAGES}

### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:true}"

Private Mediator – Open Network

An internal messaging network where users can openly communicate with each other within the company's private network, and the user's DID must be explicitly allowed by the administrator in the mediator.

### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_allow}

### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:ALLOW_ALL}

### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:true}"

Public Mediator – Closed Network

A recommended operating mode for most mediators is one in which any user can connect to the mediator unless the administrator explicitly denies them. However, for users to be able to send messages to another user, the recipient must explicitly allow the sender's DID for the messages to be delivered — e.g., you must have permission or consent from the recipient to receive your messages.

This mode protects the users against unknown senders spamming and/or sending unsolicited messages.

It requires the forwarding mechanism for all message delivery, which provides a level of abstraction to the routing and destination of the messages sent over the network.

### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_deny}

### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:ALLOW_ALL,MODE_EXPLICIT_ALLOW}

### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:false}"

Public Mediator – Open Network

The most open mediator configuration.

It allows any user to connect, send, and receive messages, whether local or remote. This mediator configuration doesn't have any restrictions unless the user updates their own ACLs if permitted by the administrator (self-change flags).

In this mode, the message handling for spam and unsolicited messages must be handled by the client app or DIDComm agent since the mediator simply relays messages.

### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_deny}

### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:ALLOW_ALL}

### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:false}"

Public Mediator – Mixed Mode

The mixed mode allows the mediator to operate on open and closed networks.

It allows the mediator to accept unknown messages to enable discovery and initiate connections between users using an ephemeral DID. Once the connection is established, users switch to private DIDs to start communicating with each other. The private DIDs are added to the Access Control Lists (ACLs), which will allow message delivery between users.

### Mediator ACL
mediator_acl_mode = ${GLOBAL_DEFAULT_ACL:explicit_deny}

### Global Default DID ACL
global_acl_default = ${GLOBAL_DEFAULT_ACL:ALLOW_ALL,MODE_EXPLICIT_ALLOW}

### Message Delivery ACL
local_direct_delivery_allowed = "${LOCAL_DIRECT_DELIVERY_ALLOWED:false}"

In the case of Out-Of-Band (OOB) discovery, it uses two different DIDs to facilitate discovery:

1. An ephemeral DID that is published in the OOB Invitation. It must be open to the world.

2. A private channel DID that is closed to the world, except for the DID discovered through the OOB discovery protocol.

The ephemeral DID would change its ACL flags to the following:

• acl_flags: ALLOW_ALL (which also forces MODE_EXPLICIT_DENY)

The private channel DID follow the existing global_acl_default.

Examples

_**NOTE | _ Ensure Mediator is configured and running before using the following examples.

Mediator Specific Examples

1. Mediator Administration

You can add/remove/list administration accounts easily using the mediator_administration example

cargo run --bin mediator_administration

Affinidi Messaging Examples

Refer to the affinidi-messaging-helpers examples.