Federated Security Architecture

Decentralized, zero-knowledge messaging infrastructure powered by federated servers

Architecture Overview

Taps.IM operates on a federated network architecture where independent servers communicate using our custom TapsIM Federation Protocol. This ensures no single point of failure while maintaining end-to-end encryption and zero-knowledge privacy.

🌐 Distributed Network

Each organization runs their own Taps.IM server, creating a peer-to-peer network with no central authority or single point of failure.

🔐 Zero-Knowledge Design

Servers only handle encrypted ciphertext. Message content remains encrypted end-to-end with keys never leaving client devices.

Federation Protocol

The TapsIM Federation Protocol implements HTTP/2 streaming with NDJSON frame codec for real-time message exchange between federated servers.

GET /_taps/federation/caps - Server capabilities

GET /_taps/federation/keys/current - Federation keys

POST /_taps/federation/encrypted-groups/{groupId}/stream - Bidirectional streaming

POST /_taps/federation/encrypted-groups/{groupId}/send - Event sending

Frame Types

Connection Frames

HELLO - Establish connection
PING/PONG - Keepalive mechanism

Message Frames

EVENT - Message transmission
ACK - Message acknowledgment
CREDIT - Flow control

Zero-Knowledge Implementation

🔒 Server-Side Encryption Handling

Servers process encrypted content as opaque ciphertext bytes. All cryptographic operations happen client-side, ensuring servers cannot decrypt message content under any circumstances.

type Event struct {

EventID string

Content []byte

ContentHash string

Signature string

}

Encryption Flow

Client Encryption

Messages encrypted client-side using NaCl secretbox with group-specific keys

Server Transport

Servers relay encrypted bytes without decryption, maintaining message integrity

Federation Relay

Encrypted content propagated across federated servers using EVENT frames

Client Decryption

Receiving clients decrypt content using shared group keys

Server Implementation

The Taps.IM Go server implements a production-ready federation stack with comprehensive observability, chaos resilience, and enterprise-grade security features.

🚀 Performance

HTTP/2 streaming with h2c
Concurrent processing
SQLite persistent storage
Connection pooling

📊 Observability

OpenTelemetry tracing
Prometheus metrics
Structured logging
Health monitoring

🛡️ Resilience

Chaos engineering
Auto-retry mechanisms
Circuit breakers
Graceful degradation

Milestone Implementation

The server follows a milestone-driven development approach from P0 to P9:

✅ Completed Milestones

P0: Hello Federation - Basic server communication
P1: Basic Reliability - Persistent storage, retries
P2: Todos on Wire - Room-native todo integration
P3: Digest & Checkpoint - Anti-entropy mechanisms
P4: Merkle State & Proofs - Cryptographic verification
P5: State Resolution - Conflict resolution algorithms

✅ Advanced Features

P7: Key Management - Advanced signing & rotation
P8: Abuse Controls - Rate limiting & quarantine
P9: Observability - Tracing, metrics, chaos testing
P10: Production-Ready - Performance tuning & SLOs

Network Topology

Peer-to-Peer Federation Model

Server Roles

• Each server is both client and server
• Automatic peer discovery and connection
• Redundant message routing
• Load balancing across peers

Message Flow

• Direct peer-to-peer communication
• Multi-hop message delivery
• Conflict-free replicated data types
• Eventually consistent state

🏢 ↔️ 🏢 ↔️ 🏢

Organization A ↔️ Organization B ↔️ Organization C

Each organization runs their own server, connected in a peer-to-peer federation network