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

Check the latest version on the pub.dev registry or view the source on GitHub.

Classes and Methods

MeetingPlaceMediatorSDK

The MeetingPlaceMediatorSDK 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 MeetingPlaceMediatorSDK, use its generative constructor.

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

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 DidManager Required
The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.
mediatorDid String Optional
Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.
forceNewSession bool Optional
When true, creates a new authenticated session even if a cached session exists for this DID and mediator combination. Defaults to false.

Example

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

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

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

// Authenticate with the mediator using the DID manager.
final MediatorClient 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 DidManager Required
The DidManager instance representing the owner whose ACL should be updated.
acl AclBody Required
The ACL payload containing the permission changes to apply. Supported action types: AccessListAdd (grants new permissions) and AccessListRemove (revokes existing permissions).
mediatorDid String Optional
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 MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK 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 Required
Responsible for managing out-of-band (OOB) DID exchanges.
mediatorDid String Optional
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 MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK 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 DidManager Required
The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.
oobUrl Uri Required
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 MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK 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 DidManager Required
The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.
mediatorDid String Optional
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 DidManager Required
The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.
mediatorDid String Optional
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.

sendMessage

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

Parameters

recipientDidDocument DidDocument Required
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 DidManager Required
The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.
mediatorDid String Optional
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 MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK 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 DidDocument Required
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 DidManager Required
The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.
mediatorDid String Optional
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 MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK 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 DidManager Required
The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.
mediatorDid String Optional
Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.
deleteOnRetrieve Boolean Required
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 MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK 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 DidManager Required
The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.
messageHashes List<String> Required
List of cryptographic hashes representing stored messages, used to verify and track messages without exposing their content.
mediatorDid String Optional
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 MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK 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 Required
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);