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

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

Usage

$3

`typescript
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()
`

$3

`typescript
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

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

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

$3

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

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

$3

`typescript
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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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

$3

- 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