Proposal for AT Protocol Instant Messenger

[rudyfraser]

Atproto Instant Messenger (AtprotoIM) Architecture Overview

Overview

This document outlines the architectural decisions, cryptographic considerations, and key management strategies for building a decentralized instant messaging app called Atproto Instant Messenger (AtprotoIM), leveraging AT Protocol, OpenMLS, Iroh Gossip, and a custom App-view backend for persistence.

Clients (OpenMLS Encryption)
   │   ▲
   │   │ (encrypted MLS ciphertext)
   ▼   │
Iroh Gossip (Real-time E2EE transport)
   │
   │ (If recipient offline, encrypted messages stored temporarily)
   ▼
App-view Backend (Persistent encrypted MLS ciphertext)
   │
   │ Discovery and storage of public KeyPackages
   ▼
AT Protocol (Identity & Discovery via DID)

Architectural Components

1. AT Protocol (DID Identity & Discovery)

• Record: online.atproto.actor.package
• Purpose: Publish user cryptographic KeyPackages.
• Example Record:

  {
    "$type": "online.atproto.actor.package",
    "keypackage": "<MLS KeyPackage serialized as base64>",
    "createdAt": "2025-03-11T00:00:00Z"
  }

2. OpenMLS (End-to-End Encryption)

• Manages cryptographic keys and message encryption.
• Ensures forward secrecy, authentication, deniability.
• Handles direct messaging and group messaging uniformly.

MLS Client-Server Architecture

MLS specifies cryptographic operations clients must perform to securely manage messaging. But MLS itself doesn’t define networking or storage directly. Instead, it explicitly depends on an external Delivery Service for practical communication. The architecture typically looks like this:

┌───────────────┐              ┌───────────────┐
│               │◀───MLS──────▶│               │
│   Client A    │              │   Client B    │
│(MLS endpoint) │              │(MLS endpoint) │
└───────────────┘              └───────────────┘
        ▲                             ▲
        │                             │
        │                             │
        ▼                             ▼
┌─────────────────────────────────────────────┐
│                                             │
│              Delivery Service               │
│      (server, handles MLS messages)         │
│                                             │
└─────────────────────────────────────────────┘

3. Iroh Gossip (Real-time Decentralized Transport)

• Provides peer-to-peer communication.
• Real-time message distribution (MLS ciphertext only).
• NAT traversal, efficient and decentralized.
• App-view backend subscribes directly to Iroh Gossip for ciphertext persistence.

┌───────────────┐              ┌───────────────┐
│               │              │               │
│   Client A    │◀──OpenMLS───▶│   Client B    │
│(MLS endpoint) │              │(MLS endpoint) │
└───────────────┘              └───────────────┘
        ▲                             ▲
        │                             │
        ▼                             ▼
┌─────────────────────────────────────────────┐
│                                             │
│           Iroh Gossip P2P network           │
│ (Decentralized Delivery Service alternative)│
│                                             │
└─────────────────────────────────────────────┘
        ▲
        │ Discovery (DIDs, KeyPackages)
        ▼
┌───────────────────────┐
│    AT Protocol (PDS)  │
│  (Identity, Discovery)│
└───────────────────────┘

4. App-view Backend (Persistent Storage & Retrieval)

• Stores user KeyPackages persistently for long-term discovery.
• Stores encrypted MLS ciphertext messages for offline synchronization.
• Implements minimal XRPC endpoints for fetching and storing ciphertext.

XRPC Endpoints

Endpoint: online.atproto.actor.getPackage

• Purpose: Retrieve KeyPackages by DID.
• Response:

  {
    keypackage: string (base64),
    createdAt: datetime
  }

Endpoint: online.atproto.chat.getMessages

• Purpose: Retrieve missed encrypted messages.
• Response:

  {
    messages: [{
      ciphertext: string (base64),
      senderDid: string,
      createdAt: datetime
    }]
  }

Endpoint: online.atproto.chat.writeMessages (Optional)

• Purpose: Explicit ciphertext storage by clients (alternative approach if not using Iroh direct subscription).
• Request:

  {
    chatId: string,
    messages: [{
      ciphertext: string (base64),
      senderDid: string,
      createdAt: datetime
    }]
  }

Recommended Key Management

Key Type	Description	Persistence
ATproto Identity Key	User identity & publishing (PDS)	Long-term (highly secure)
MLS KeyPackage	MLS cryptographic identity	Medium-term (~weeks/months)
Iroh Gossip Node Key	Transport peer identity	Semi-stable (client-side stored)

Message Flow (Complete)

Step 1: Publish KeyPackage

• User generates MLS KeyPackage locally.
• Publishes to AT Protocol (online.atproto.actor.package).

Step 2: Real-time Messaging (Encrypted via MLS)

• Messages sent peer-to-peer using Iroh Gossip.
• App-view subscribes and persists encrypted ciphertext messages.

Clients ───(Iroh Gossip ciphertext)───► App-view (persist ciphertext)
Clients ───(Iroh Gossip ciphertext)───► Other online Clients (real-time)

Step 3: Offline Message Recovery

• User fetches encrypted messages from app-view (online.atproto.chat.getMessages) upon reconnect.
• MLS decrypts ciphertext locally using stored state.

Updated Example Implementation Code (Rust)

Publishing KeyPackage

async fn publish_keypackage(client: &AtprotoClient, keypackage: &KeyPackage) -> anyhow::Result<()> {
    let serialized_keypackage = keypackage.tls_serialize_detached()?;
    let encoded = base64::encode(serialized_keypackage);

    client.publish_record("online.atproto.actor.package", "self", json!({
        "keypackage": encoded,
        "createdAt": chrono::Utc::now().to_rfc3339(),
    })).await?;

    Ok(())
}

Receiving and Persisting Ciphertext (App-view backend)

async fn persist_ciphertext(mls_ciphertext: &[u8], sender_did: &str, chat_id: &str) -> anyhow::Result<()> {
    db.insert("online.atproto.chat.message", ChatMessage {
        ciphertext: base64::encode(mls_ciphertext),
        sender_did: sender_did.to_string(),
        chat_id: chat_id.to_string(),
        created_at: chrono::Utc::now(),
    }).await?;

    Ok(())
}

Client Fetching Missed Messages

async fn fetch_missed_messages(client: &AppViewClient, chat_id: &str, since: DateTime<Utc>) -> anyhow::Result<()> {
    let response = client.get_messages(chat_id, since).await?;

    for msg in response.messages {
        let ciphertext_bytes = base64::decode(msg.ciphertext)?;
        let mls_msg_in = MlsMessageIn::tls_deserialize(&mut &ciphertext_bytes[..])?;
        group.process_message(&crypto, mls_msg_in)?;
    }

    Ok(())
}

Technical Considerations and Risks

• MLS commits must be stored and retrieved like ciphertext.
• Iroh node keys should be semi-persistent to optimize peer connections.
• Ciphertexts must never be published via firehose.
• Offline synchronization must reliably capture all ciphertexts.

Conclusion

The outlined architecture ensures robust security, decentralization, scalability, and usability for AtprotoIM, leveraging the strengths of AT Protocol, OpenMLS encryption, and Iroh Gossip transport, supported by a minimal persistent App-view backend.

[maxfzz]

Inspiring! A point of consideration I'd like to bring up would be weighing the pros and cons between iroh-gossip and Libp2p as the transport layer. Libp2p has a similar gossip protocol and hails from Protocol Labs, the team responsible for development on IPFS.

[zicklag]

I recommend Iroh.

Iroh is a stripped down, more opinionated version of libp2p that tends to be much more reliable for hole punching, will fall back to end-to-end encrypted relays if it doesn't work, also tends to be much nicer to use from a code perspective.

I've hung out on the Iroh Discord for a while, used it a bit, have a game project that uses it for networking, and talked with the authors a bit and everything they're doing just seems really solid.

[mishmosh]

Iroh has some shared history with IPFS and Protocol Labs as well. That said, I recommend choosing a transport layer based on how it meets your project's needs. IMO history and lineage is mainly useful in understanding design decisions.

[LemmaEOF]

If you can figure this out, this might be usable for getting Bsky's DMs onto the protocol as well! Honestly huge.

[d3ol-dev]

This is a great proposal! Would it be out of scope to consider key recovery processes? Additionally, is there a way to verify DIDs before starting a new chat/continuing a chat?

[mikedegeofroy]

I was just thinking about this! I would love to live in a world where it no longer matters what IM app you use.