Mediator

Enables participants to connect and authenticate with mediators, such as the DIDComm mediator, to send messages and connection offers. Mediator does not store permanently the messages and the content is not visible to the mediator.

Install Dependency

Package: meeting_place_mediator


        
dart pub add meeting_place_mediator

You can check the latest version of this module on the pub.dev or view the source code at the GitHub repository.

Classes and Methods

MediatorSDK

The MediatorSDK provides a high-level API for interacting with a DIDComm mediator in Meeting Place. It supports authenticating with a mediator, managing access control lists (ACL), creating and retrieving Out-Of-Band (OOB) invitations, sending and receiving DIDComm messages, and subscribing to message streams. The SDK abstracts DIDComm v2.1 protocol details, making it easy to build secure, privacy-preserving messaging and connection flows

To create an instance of the MediatorSDK, you can use its generative constructor.


        
final mediatorSDK = MediatorSDK(
    mediatorDid: 'did:web:mediator.example.com:.well-known',
);

authenticateWithDid

Authenticates to a mediator instance using the provided DID manager. This method establishes an authenticated session with the mediator. If a valid session already exists in the internal cache for the same DID manager and mediator combination, the cached session client will be returned instead of creating a new one.

Parameters

didManager [Class]

The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

        

final MediatorSDK mediatorSDK = /* your MediatorSDK instance */;

final DidManager didManager = /* your DidManager instance */;

// Authenticate with the mediator using the DID manager
final MediatorSessionClient session = await mediatorSDK.authenticateWithDid(
    didManager,
    mediatorDid: '<YOUR_MEDIATOR_DID>', // Optional, uses SDK default if not provided
);

updateAcl

Updates the Access Control List (ACL) for a specific owner on the mediator instance. This method modifies the ACL permissions for the specified owner’s DID by sending the provided ACL payload to the mediator. The ACL determines which entities have access to the owner’s resources and what operations they are permitted to perform.

Parameters

ownerDidManager [Class]

The DidManager instance representing the owner whose ACL should be updated.

acl [Class]

The ACL payload containing the permission changes to apply.

Supported action types include:

[AccessListAdd] - Grants new permissions to specified entities

[AccessListRemove] - Revokes existing permissions from specified entities

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

        

final MediatorSDK mediatorSDK = /* your MediatorSDK instance */;

// Prepare the owner's DID manager
final DidManager ownerDidManager = /* your DidManager instance */;

// Create an ACL body with permissions
final AclBody acl = AclBody(
    // Example: Grant access to specific entities
    // Replace with actual ACL structure from your implementation
);

// Update the ACL for the owner
await mediatorSDK.updateAcl(
    ownerDidManager: ownerDidManager,
    acl: acl
);

createOob

Allows a client to create an Out-Of-Band invitation in the mediator, resulting not only in an OOB ID but also in a complete OOB invitation URL that can be shared with other parties to initiate DIDComm interactions.

Parameters

oobDidManager [DidManager]

Responsible for managing out-of-band (OOB) DID exchanges.

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

        

final MediatorSDK mediatorSDK = /* your MediatorSDK instance */;

final DidManager oobDidManager = /* your DidManager instance */;

// Create an Out-Of-Band invitation
final Uri oobUri = await mediatorSDK.createOob(
    oobDidManager
);

getOob

Allows a client to retrieve the OOB details from the mediator. This method fetches the Out-Of-Band invitation associated with the provided OOB URL, enabling the client to process and utilize the invitation for DIDComm interactions.

Parameters

didManager [Class]

The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

oobUrl [Uri]

Carries an out-of-band invitation used to initiate DIDComm interactions outside the normal communication channel, often shared via QR code.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

        

final MediatorSDK mediatorSDK = /* your MediatorSDK instance */;

final DidManager didManager = /* your DidManager instance */;

// The OOB URL you want to retrieve (e.g., received via QR code or shared link)
final Uri oobUrl = Uri.parse('<YOUR_OOB_URL>');

// Retrieve the OOB invitation details
final OobInvitationMessage oobInvitation = await mediatorSDK.getOob(
    oobUrl,
    didManager: didManager,
);

subscribeToMessages

Subscribes to incoming messages from the mediator.

Parameters

didManager [Class]

The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

        

final DidManager didManager = /* your DidManager instance */;
final mediatorDid = '<YOUR_MEDIATOR_DID>';

final MediatorChannel channel = await mediatorSDK.subscribeToMessages(
    didManager,
    mediatorDid
);

listenForMessages

Subscribes to incoming messages from the mediator and executes registered listeners based on message type.

Parameters

didManager [Class]

The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

        

final DidManager didManager = /* your DidManager instance */;
final mediatorDid = '<YOUR_MEDIATOR_DID>';

final MediatorChannel channel = await mediatorSDK.listenForMessages(
    didManager,
    mediatorDid
);

sendMessage

Encrypts and signs the message using the sender’ s DID, then sends it to recipientDidDocument via DIDComm.

Parameters

recipientDidDocument [JsonObject]

DID document that contains the recipient agent’s public keys, service endpoints, and routing information required to securely receive, decrypt, and respond to DIDComm messages.

didManager [Class]

The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';
import 'package:didcomm/didcomm.dart';

        

final MediatorSDK mediatorSDK = /* your MediatorSDK instance */;

final DidManager senderDidManager = /* your sender DidManager instance */;
final DidDocument recipientDidDocument = /* recipient's DidDocument */;

// Create a PlainTextMessage
final PlainTextMessage message = PlainTextMessage(
    id: 'message-id-123',
    body: {'text': 'Hello, this is a test message!'},
    // ...other required fields
);

// Send the message
await mediatorSDK.sendMessage(
    message,
    senderDidManager: senderDidManager,
    recipientDidDocument: recipientDidDocument,
    mediatorDid: 'did:example:mediator', // Optional, uses SDK default if not provided
    ephemeral: false, // Optional, defaults to false
    forwardExpiryInSeconds: 3600, // Optional, 1 hour expiry
  );

queueMessage

Stores incoming DIDComm messages to manage the sending process efficiently, ensuring messages are properly handled and dispatched.

Parameters

recipientDidDocument [JsonObject]

DID document that contains the recipient agent’s public keys, service endpoints, and routing information required to securely receive, decrypt, and respond to DIDComm messages.

didManager [Class]

The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';
import 'package:didcomm/didcomm.dart';

        

final MediatorSDK mediatorSDK = /* your MediatorSDK instance */;

final DidManager senderDidManager = /* your sender DidManager instance */;
final DidDocument recipientDidDocument = /* recipient's DidDocument */;

// Create a PlainTextMessage
final PlainTextMessage message = PlainTextMessage(
    id: 'message-id-123',
    body: {'text': 'Hello, this is a test message!'},
    // ...other required fields
);

// Queue the message for later delivery
await mediatorSDK.queueMessage(
    message,
    senderDidManager: senderDidManager,
    recipientDidDocument: recipientDidDocument,
    mediatorDid: 'did:example:mediator', // Optional, uses SDK default if not provided
    ephemeral: false, // Optional, defaults to false
    forwardExpiryInSeconds: 3600, // Optional, 1 hour expiry
);

fetchMessages

Retrieves available messages from the specified mediator instance.

Parameters

didManager [Class]

The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

deleteOnRetrieve [Boolean]

Boolean flag indicating whether messages should be deleted upon retrieval.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

        

final MediatorSDK mediatorSDK = /* your MediatorSDK instance */;

final DidManager didManager = /* your DidManager instance */;

// Fetch messages from the mediator
final List<FetchMessageResult> messages = await mediatorSDK.fetchMessages(
    didManager: didManager,
    mediatorDid: 'did:example:mediator', // Optional, uses SDK default if not provided
    startFrom: DateTime.now().subtract(Duration(hours: 24)), // Optional, fetch from last 24 hours
    fetchMessagesBatchSize: 50, // Optional, limit batch size
    deleteOnRetrieve: false, // Optional, keep messages on mediator after fetch
    deleteFailedMessages: true, // Optional, delete messages that failed to process
);

deleteMessages

Deletes stored messages from the mediator’s queue, removing them permanently after they have been retrieved or are no longer needed.

Parameters

didManager [Class]

The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

messageHashes [List<String>]

List of cryptographic hashes representing stored messages, used to verify and track messages without exposing their content.

mediatorDid [String]

Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

        

final MediatorSDK mediatorSDK = /* your MediatorSDK instance */;

final DidManager didManager = /* your DidManager instance */;

// List of message hashes you want to delete
final List<String> messageHashes = [
    'hash1234567890abcdef',
    'hash0987654321fedcba',
    // Add more message hashes as needed
];

// Delete the specified messages from the mediator
await mediatorSDK.deletedMessages(
    didManager: didManager,
    messageHashes: messageHashes
);

getMediatorDidFromUrl

Fetches the Mediator DID from a mediator’s endpoint.

Parameters

mediatorEndpoint [String]

Specifies the URL or address of the mediator service used to route and manage DIDComm messages.

Example

        

import 'package:meeting_place_mediator/meeting_place_mediator.dart';

        
final mediatorEndpoint = 'https://mediator.example.com/endpoint';

final String? mediatorDid = await mediatorSDK.getMediatorDidFromUrl(mediatorEndpoint);