Communitas Core

Core business logic library for the Communitas P2P collaboration platform.

Overview

Communitas Core is a Rust library that provides all the essential functionality for building decentralized collaboration applications. It's used by both the desktop application and headless daemon, providing a consistent API without any UI dependencies.

Features

• Post-Quantum Cryptography: ML-DSA signatures and ML-KEM key exchange
• Four-Word Addressing: Human-readable identity system (e.g., "ocean-forest-moon-star")
• Gossip Overlay Network: Distributed P2P communication layer
• CRDT Document Sync: Conflict-free collaborative editing with Yrs
• Encrypted Storage: Platform-specific secure credential storage (keyring)
• Presence Service: Real-time user availability tracking
• Message Synchronization: Reliable message delivery with retries
• Authentication: Passkey-based authentication with platform integration
• Storage Management: Virtual disks with content addressing (BLAKE3)

Architecture

Core Components

communitas-core/
├── auth_service.rs          # Authentication and session management
├── core_context.rs          # Main application context
├── crdt.rs                  # CRDT document operations
├── doc_replicator.rs        # Document replication logic
├── encrypted_storage/       # Secure credential storage
├── gossip/                  # P2P gossip overlay
│   ├── context.rs          # Gossip network context
│   ├── coordinator.rs      # Message coordination
│   ├── crdt_sync.rs        # CRDT synchronization
│   ├── groups.rs           # Group management
│   ├── identity.rs         # Identity operations
│   ├── membership.rs       # Membership tracking
│   ├── presence.rs         # Presence detection
│   ├── pubsub.rs          # Publish-subscribe messaging
│   ├── rendezvous.rs      # Peer rendezvous
│   ├── transport.rs       # Network transport
│   └── types.rs           # Shared types
├── identity.rs             # Identity management and four-word addressing
├── keystore.rs            # Cryptographic key storage
├── local_storage.rs       # Local data persistence
├── message_sync.rs        # Message synchronization
├── presence_service.rs    # Presence tracking service
├── security/              # Security primitives
└── storage/               # Storage abstractions

Quick Start

As a Library

Add to your Cargo.toml:

[dependencies]
communitas-core = { path = "../communitas-core" }
tokio = { version = "1.39", features = ["full"] }

Basic Usage

use communitas_core::{CoreContext, AuthService, GossipContext};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize core context
    let core_ctx = CoreContext::new("./data").await?;

    // Create identity with four-word address
    let auth = AuthService::new(core_ctx.clone()).await?;
    let session = auth.register(
        "ocean-forest-moon-star",
        "Alice",
        "Desktop-01",
        "secure-password"
    ).await?;

    println!("Created identity: {}", session.four_words);
    println!("Entity ID: {}", session.entity_id);

    // Initialize gossip network
    let gossip = GossipContext::new(core_ctx).await?;
    gossip.start().await?;

    // Send message to channel
    gossip.publish(
        "channel-id",
        "Hello, World!".as_bytes(),
        vec!["recipient-four-words"]
    ).await?;

    Ok(())
}

Authentication System

Four-Word Identity

Every user, organization, and entity has a human-readable four-word identity:

use communitas_core::identity::{generate_id_words, validate_id_words};

// Generate new identity
let four_words = generate_id_words()?;
// → "ocean-forest-moon-star"

// Validate identity
let is_valid = validate_id_words(&["ocean", "forest", "moon", "star"])?;
// → true

// Connect from words to IP addresses (optional)
use communitas_core::identity::conn_from_words;
let connection_info = conn_from_words(&four_words)?;

Authentication Flow

use communitas_core::{AuthService, CoreContext};

let core_ctx = CoreContext::new("./data").await?;
let auth = AuthService::new(core_ctx).await?;

// Register new user
let session = auth.register(
    "ocean-forest-moon-star",
    "Alice",
    "Desktop-01",
    "secure-password"
).await?;

// Login existing user
let session = auth.login(
    "ocean-forest-moon-star",
    "secure-password"
).await?;

// Logout
auth.logout().await?;

Gossip Network

Network Initialization

use communitas_core::{GossipContext, CoreContext};

let core_ctx = CoreContext::new("./data").await?;
let gossip = GossipContext::new(core_ctx).await?;

// Start gossip network
gossip.start().await?;

// Join a topic
gossip.subscribe("general-chat").await?;

// Publish message
gossip.publish(
    "general-chat",
    b"Hello everyone!",
    vec![] // Empty = broadcast to all subscribers
).await?;

Peer Discovery

// Discover peers via rendezvous
let peers = gossip.discover_peers("general-chat").await?;

for peer in peers {
    println!("Found peer: {:?}", peer);
}

// Check online presence
let is_online = gossip.is_online("ocean-forest-moon-star").await?;

CRDT Document Collaboration

Collaborative Editing

use communitas_core::crdt::{CrdtDocument, CrdtOperation};

// Create shared document
let doc = CrdtDocument::new("doc-123")?;

// Apply local edit
doc.insert(0, "Hello ")?;
doc.insert(6, "World!")?;

// Get operations for sync
let ops = doc.get_operations_since(0)?;

// Apply remote operations
for op in remote_ops {
    doc.apply_operation(op)?;
}

// Get current text
let text = doc.to_string()?;

Document Replication

use communitas_core::doc_replicator::DocReplicator;

let replicator = DocReplicator::new(gossip_ctx.clone()).await?;

// Replicate document across peers
replicator.replicate_doc("doc-123").await?;

// Subscribe to document updates
replicator.subscribe_doc("doc-123", |update| {
    println!("Document updated: {:?}", update);
}).await?;

Encrypted Storage

Passkey Storage

use communitas_core::encrypted_storage::PasskeyStorage;

let storage = PasskeyStorage::new()?;

// Store passkey
storage.store_passkey(
    "user@example.com",
    "service-name",
    &passkey_bytes
).await?;

// Retrieve passkey
let passkey = storage.get_passkey(
    "user@example.com",
    "service-name"
).await?;

// Delete passkey
storage.delete_passkey(
    "user@example.com",
    "service-name"
).await?;

Platform Integration

The encrypted storage system uses platform-specific credential managers:

• macOS: Keychain
• Windows: Windows Credential Manager
• Linux: Secret Service API (libsecret)

Storage Management

Virtual Disks

use communitas_core::storage::{VirtualDisk, DiskType};

// Create virtual disk for entity
let disk = VirtualDisk::new(
    entity_id,
    DiskType::Private
).await?;

// Write file
disk.write(
    "/docs/readme.md",
    b"# Project Documentation"
).await?;

// Read file
let content = disk.read("/docs/readme.md").await?;

// List files
let files = disk.list("/docs").await?;

Content Addressing

use communitas_core::storage::ContentAddressed;

// Store content-addressed data
let hash = storage.store_content(b"Hello World!").await?;
// → BLAKE3 hash

// Retrieve by hash
let content = storage.get_content(&hash).await?;

Message Synchronization

Reliable Messaging

use communitas_core::message_sync::MessageSync;

let sync = MessageSync::new(gossip_ctx.clone()).await?;

// Send message with automatic retry
sync.send_reliable(
    "recipient-four-words",
    "channel-id",
    b"Important message"
).await?;

// Receive messages
let messages = sync.receive_since(last_timestamp).await?;

for msg in messages {
    println!("From: {}, Content: {:?}", msg.sender, msg.content);
}

Presence Service

Online Status Tracking

use communitas_core::presence_service::PresenceService;

let presence = PresenceService::new(gossip_ctx.clone()).await?;

// Set own status
presence.set_status("online", "Working on docs").await?;

// Check peer status
let status = presence.get_status("ocean-forest-moon-star").await?;
println!("Status: {:?}", status);

// Subscribe to presence changes
presence.subscribe(|event| {
    match event {
        PresenceEvent::Online(peer) => println!("{} came online", peer),
        PresenceEvent::Offline(peer) => println!("{} went offline", peer),
        PresenceEvent::StatusChange(peer, status) => {
            println!("{} changed status to {}", peer, status)
        }
    }
}).await?;

Security

Post-Quantum Cryptography

All cryptographic operations use post-quantum algorithms:

use communitas_core::security::{PqcSigner, PqcVerifier};

// Create ML-DSA signer
let signer = PqcSigner::new()?;

// Sign data
let signature = signer.sign(b"data to sign")?;

// Verify signature
let verifier = PqcVerifier::from_public_key(&public_key)?;
let is_valid = verifier.verify(b"data to sign", &signature)?;

Key Exchange

use communitas_core::security::{PqcKeyExchange, SharedSecret};

// Alice generates keypair
let alice_kex = PqcKeyExchange::new()?;
let alice_public = alice_kex.public_key();

// Bob generates keypair and creates shared secret
let bob_kex = PqcKeyExchange::new()?;
let bob_public = bob_kex.public_key();
let bob_shared = bob_kex.derive_shared_secret(&alice_public)?;

// Alice creates shared secret
let alice_shared = alice_kex.derive_shared_secret(&bob_public)?;

assert_eq!(alice_shared, bob_shared);

Development

Building

cargo build -p communitas-core
cargo build -p communitas-core --release

Testing

# Run all tests
cargo test -p communitas-core

# Run with logging
RUST_LOG=debug cargo test -p communitas-core

# Run specific test
cargo test -p communitas-core --test integration_test

# Run property-based tests
cargo test -p communitas-core --features proptest

Linting

# Strict linting (enforces no panics in production)
cargo clippy -p communitas-core --all-features -- \
  -D clippy::panic \
  -D clippy::unwrap_used \
  -D clippy::expect_used

# Format code
cargo fmt -p communitas-core

Configuration

Environment Variables

Configuration File

Core can be configured via TOML:

[identity]
four_words = "ocean-forest-moon-star"
display_name = "Alice"
device_name = "Desktop-01"

[network]
bootstrap_nodes = ["bootstrap.communitas.network:8080"]
enable_mdns = true
port = 8080

[storage]
data_dir = "~/.communitas"
cache_size_mb = 500

[security]
enable_pqc = true
key_rotation_days = 90

[logging]
level = "info"
format = "json"

API Documentation

Full API documentation is available via rustdoc:

cargo doc -p communitas-core --open

Performance Characteristics

• Message Latency: <100ms local, <500ms remote
• Storage Operations: <100ms for content-addressed reads
• CRDT Sync: <200ms for typical document operations
• Memory Usage: ~50MB baseline, scales with active documents
• CPU Usage: <5% idle, scales with network activity

Security Considerations

1. Zero-Panics Policy: Production code forbids unwrap(), expect(), and panic!
2. Post-Quantum Ready: All cryptography uses ML-DSA and ML-KEM
3. Secure Storage: Platform-specific credential managers
4. End-to-End Encryption: All messages encrypted by default
5. Forward Secrecy: Perfect forward secrecy for all sessions
6. No Trusted Third Parties: Fully decentralized architecture

Troubleshooting

Common Issues

Identity Generation Fails

# Check four-word-networking dictionary
cargo test -p communitas-core -- identity::tests

Gossip Network Won't Start

# Check port availability
lsof -i :8080

# Enable debug logging
RUST_LOG=communitas_core::gossip=debug cargo run

Storage Errors

# Check permissions
ls -la ~/.communitas/

# Reset storage (development only)
rm -rf ~/.communitas/

Authentication Issues

# Check keyring access
cargo test -p communitas-core -- auth_service::tests

# Clear credentials (macOS)
security delete-generic-password -s "communitas"

Contributing

See ../../docs/development/contributing.md

License

Dual-licensed under AGPL-3.0-or-later and commercial license.

See Also

• Communitas Desktop - Desktop application using this core
• Communitas Headless - Headless daemon using this core
• Architecture Documentation - System architecture details
• API Reference - Complete API documentation