Group Messaging Module (@credo-ts/group-messaging)

DIDComm v2 Group Messaging Protocol with MLS (Messaging Layer Security) for Credo Framework.

Overview

This module implements the DIDComm Group Messaging v1.0 Protocol, providing end-to-end encrypted group chat using:

• MLS (RFC 9420) - Messaging Layer Security for group encryption
• DIDComm v2 - Decentralized messaging
• Signing Protocol v1.0 - Authorization artifacts, join tokens, router attestations
• HPKE (RFC 9180) - Hybrid Public Key Encryption for sealed secrets

Features

✅ End-to-End Encrypted Group Chat - MLS provides forward secrecy and post-compromise security ✅ Decentralized Identity - DIDs for rooms and participants ✅ Multi-Device Support - Members can join with multiple devices ✅ Role-Based Access Control - Owner, admin, and member roles ✅ Admin Governance - Authorization artifacts for privileged operations ✅ Replay-Proof Join Tokens - HPKE-encrypted join tokens with monotonic counters ✅ Message Deduplication - Content-based deduplication with mls_msg_id ✅ Delivery Receipts - Track message delivery status ✅ Commit Ordering - Host ensures one commit per epoch (conflict resolution) ✅ Mesh Routing - Optional router support for relay topology

Installation

pnpm add @credo-ts/group-messaging @ajna-inc/signing

Usage

1. Register the Module

import { Agent } from '@credo-ts/core'
import { GroupMessagingModule } from '@credo-ts/group-messaging'
import { SigningModule } from '@ajna-inc/signing'

const agent = new Agent({
  config: { /* ... */ },
  modules: {
    signing: new SigningModule(),
    groupMessaging: new GroupMessagingModule(),
  },
})

await agent.initialize()

2. Create a Room

const ownerDid = await agent.dids.create({ method: 'key' })

const room = await agent.modules.groupMessaging.createRoom({
  roomDid: 'did:peer:room-123',
  label: 'Project Team',
  ownerDid: ownerDid.didState.did!,
  policy: {
    join: 'invite-only',
    maxMembers: 100,
  },
  ciphersuite: 'MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519',
})

console.log('Room created:', room.id)

3. Send Encrypted Messages

const messageId = await agent.modules.groupMessaging.sendMessage(
  room.id,
  'Hello, team!',
  senderDid
)

console.log('Message sent:', messageId)

4. Get Roster

const roster = await agent.modules.groupMessaging.getRoster(room.id)

console.log('Active members:', roster.members.filter(m => m.status === 'active'))

5. Check Receipt Status

const status = await agent.modules.groupMessaging.getReceiptStatus(room.id, messageId)

console.log('Delivered to:', status.received)
console.log('Pending:', status.pending)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  Group Messaging Stack                       │
├─────────────────────────────────────────────────────────────┤
│  Application: Chat, File Sharing, Notifications             │
├─────────────────────────────────────────────────────────────┤
│  Group Messaging Protocol: Room Management, Membership       │
├─────────────────────────────────────────────────────────────┤
│  MLS (ts-mls): E2EE, Key Management, Forward Secrecy       │
├─────────────────────────────────────────────────────────────┤
│  Signing Protocol: Authorization, Join Tokens, Attestations  │
├─────────────────────────────────────────────────────────────┤
│  DIDComm v2: Routing, Mediation, Message Pickup            │
├─────────────────────────────────────────────────────────────┤
│  Transport: HTTPS, WebSocket, WebTransport                  │
└─────────────────────────────────────────────────────────────┘

Components

Core Models

• Room - Group chat room with DID, policy, MLS group ID
• Roster - Member list with roles, devices, status
• Member - DID with role (owner/admin/member), status, devices
• Device - Multi-device support with MLS leaf index

Services

• RoomService - CRUD operations for rooms
• MembershipService - Invite, join, remove, ban operations
• MLSService - MLS encryption/decryption wrapper
• GroupMessagingService - Send/receive encrypted messages
• ReceiptService - Delivery receipt tracking
• HostService - Message ordering, commit resolution, fan-out
• DeduplicationService - Prevent duplicate message processing

DIDComm Messages

• create / created - Room creation
• invite - Invite member (requires admin authz)
• join - Join room (requires join token + key package)
• moderate - Add/remove/ban (requires admin authz)
• roster-request / roster - Get member list
• msg - Encrypted application message
• delivery-receipts - Delivery acknowledgments

Protocol Roles

• Owner - Creates the room, controls the Room DID
• Admin(s) - Authorized to change membership/policy
• Member - MLS leaf participant (multi-device supported)
• Host (Delivery Service) - Orders commits, fans out messages
• Router - Optional relay for mesh topology

Security

Encryption

• MLS provides end-to-end encryption for all group messages
• Forward Secrecy - Past messages safe even if keys compromised
• Post-Compromise Security - Future messages safe after key rotation

Authorization

• Admin operations require Signing Protocol authorization artifacts
• Join operations require replay-proof join tokens with:
  • Monotonic counter (prevents replay)
  • HPKE envelope (cryptographic binding)
  • Expiry and capacity limits

Deduplication

• Messages identified by mls_msg_id (content ID)
• Seen-set tracking prevents duplicate processing
• Idempotent re-ack for duplicates

Supported MLS Ciphersuites

• MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519 (recommended)
• MLS_128_DHKEMP256_AES128GCM_SHA256_P256
• MLS_128_DHKEMX25519_CHACHA20POLY1305_SHA256_Ed25519

Dependencies

• @credo-ts/core - Credo framework core
• @ajna-inc/signing - DIDComm Signing Protocol
• ts-mls - TypeScript MLS (RFC 9420) implementation
• @hpke/core - HPKE (RFC 9180) for sealed secrets
• @noble/curves - Cryptographic curves
• @noble/ciphers - Cryptographic ciphers

Specification Compliance

This implementation follows:

• ✅ DIDComm Group Messaging v1.0
• ✅ MLS Protocol (RFC 9420)
• ✅ HPKE (RFC 9180)
• ✅ DIDComm v2
• ✅ DIDComm Signing Protocol v1.0

Implementation Status

| Phase | Component | Status | |-------|-----------|--------| | 0.1 | Authorization Artifacts | ✅ Complete | | 0.2 | Join Tokens + HPKE | ✅ Complete | | 0.3 | Router Attestation | ✅ Complete | | 1 | Room Management | ✅ Complete | | 2 | MLS Integration | ✅ Complete | | 3 | Membership Management | ✅ Complete | | 4 | Host/Delivery Service | ✅ Complete | | 5 | Messaging & Receipts | ✅ Complete | | 6 | Router Implementation | 🟡 Framework Ready | | 7 | DIDComm Transport | 🟡 Framework Ready | | 8 | Complete API | ✅ Complete | | 9 | Testing & Docs | 🟡 In Progress |

Roadmap

• [ ] Complete message handler implementations
• [ ] Router mesh topology implementation
• [ ] Full DIDComm transport integration
• [ ] Message Pickup protocol integration
• [ ] Comprehensive integration tests
• [ ] Performance benchmarks
• [ ] Production deployment guide

License

Apache-2.0

Contributing

Contributions welcome! Please see the main Credo repository for contribution guidelines.

Resources

• Group Messaging Specification
• MLS Architecture
• DIDComm v2 Specification
• Credo Framework Documentation