Crate saorsa_core 

Saorsa Core

A next-generation peer-to-peer networking foundation built in Rust.

Features

• QUIC-based transport with NAT traversal
• IPv4-first with simple addressing
• Kademlia DHT for distributed routing
• Four-word human-readable addresses

Example

use saorsa_core::{P2PNode, NodeConfig, NetworkAddress};
use std::str::FromStr;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let addr = "127.0.0.1:9000".parse::<NetworkAddress>()?;
    let node = P2PNode::builder()
        .listen_on(addr)
        .with_mcp_server()
        .build()
        .await?;

    node.run().await?;
    Ok(())
}

Re-exports

pub use api::GroupKeyPair;

pub use api::MemberRef;

pub use api::clear_dht_client;

pub use api::get_data;

pub use api::get_identity;

pub use api::get_presence;

pub use api::group_identity_canonical_sign_bytes;

pub use api::group_identity_create;

pub use api::group_identity_fetch;

pub use api::group_identity_publish;

pub use api::group_identity_update_members_signed;

pub use api::identity_fetch;

pub use api::register_headless;

pub use api::register_identity;

pub use api::register_presence;

pub use api::set_active_device;

pub use api::set_dht_client;

pub use api::store_data;

pub use api::store_dyad;

pub use api::store_with_fec;

pub use address::AddressBook;

pub use address::NetworkAddress;

pub use address_book::address_book;

pub use address_book::get_user_by_four_words;

pub use address_book::get_user_four_words;

pub use address_book::register_user_address;

pub use identity::FourWordAddress;

pub use auth::DelegatedWriteAuth;

pub use auth::MlsWriteAuth;

pub use auth::PubKey;

pub use auth::Sig;

pub use auth::SingleWriteAuth;

pub use auth::ThresholdWriteAuth;

pub use auth::WriteAuth;

pub use bootstrap::BootstrapConfig;

pub use bootstrap::BootstrapManager;

pub use bootstrap::CacheConfig;

pub use bootstrap::ContactEntry;

pub use bootstrap::QualityMetrics;

pub use dht::Key;

pub use dht::Record;

pub use dht_network_manager::BootstrapNode;

pub use dht_network_manager::DhtNetworkConfig;

pub use dht_network_manager::DhtNetworkEvent;

pub use dht_network_manager::DhtNetworkManager;

pub use dht_network_manager::DhtNetworkOperation;

pub use dht_network_manager::DhtNetworkResult;

pub use dht_network_manager::DhtPeerInfo;

pub use encrypted_key_storage::Argon2Config;

pub use encrypted_key_storage::DerivationPriority as KeyDerivationPriority;

pub use encrypted_key_storage::EncryptedKeyStorageManager;

pub use encrypted_key_storage::KeyMetadata;

pub use encrypted_key_storage::PasswordValidation;

pub use encrypted_key_storage::SecurityLevel;

pub use encrypted_key_storage::StorageStats;

pub use error::P2PError;

pub use error::P2pResult as Result;

pub use events::Subscription;

pub use events::TopologyEvent;

pub use events::device_subscribe;

pub use events::dht_watch;

pub use events::subscribe_topology;

pub use fwid::FourWordsV1;

pub use fwid::Key as FwKey;

pub use fwid::fw_check;

pub use fwid::fw_to_key;

pub use health::ComponentChecker;

pub use health::ComponentHealth;

pub use health::HealthEndpoints;

pub use health::HealthManager;

pub use health::HealthResponse;

pub use health::HealthServer;

pub use health::HealthStatus;

pub use health::PrometheusExporter;

pub use key_derivation::BatchDerivationRequest;

pub use key_derivation::BatchDerivationResult;

pub use key_derivation::DerivationPath;

pub use key_derivation::DerivationPriority;

pub use key_derivation::DerivationStats;

pub use key_derivation::DerivedKey;

pub use key_derivation::HierarchicalKeyDerivation;

pub use key_derivation::MasterSeed;

pub use monotonic_counter::BatchUpdateRequest;

pub use monotonic_counter::BatchUpdateResult;

pub use monotonic_counter::CounterStats;

pub use monotonic_counter::MonotonicCounterSystem;

pub use monotonic_counter::PeerCounter;

pub use monotonic_counter::SequenceValidationResult;

pub use network::ConnectionStatus;

pub use network::NodeBuilder;

pub use network::NodeConfig;

pub use network::P2PEvent;

pub use network::P2PNode;

pub use network::PeerInfo;

pub use telemetry::Metrics;

pub use telemetry::StreamClass;

pub use telemetry::record_lookup;

pub use telemetry::record_timeout;

pub use telemetry::telemetry;

pub use config::Config;

pub use network::P2PNode as Node;

pub use peer_record::EndpointId;

pub use peer_record::NatType;

pub use peer_record::PeerDHTRecord;

pub use peer_record::PeerEndpoint;

pub use peer_record::SignatureCache;

pub use peer_record::UserId;

pub use persistent_state::FlushStrategy;

pub use persistent_state::IntegrityReport;

pub use persistent_state::PersistentStateManager;

pub use persistent_state::RecoveryMode;

pub use persistent_state::RecoveryStats;

pub use persistent_state::StateChangeEvent;

pub use persistent_state::StateConfig;

pub use persistent_state::TransactionType;

pub use persistent_state::WalEntry;

pub use production::ProductionConfig;

pub use production::ResourceManager;

pub use production::ResourceMetrics;

pub use secure_memory::PoolStats;

pub use secure_memory::SecureMemory;

pub use secure_memory::SecureMemoryPool;

pub use secure_memory::SecureString;

pub use secure_memory::SecureVec;

pub use secure_memory::allocate_secure;

pub use secure_memory::secure_string_with_capacity;

pub use secure_memory::secure_vec_with_capacity;

pub use validation::RateLimitConfig;

pub use validation::RateLimiter;

pub use validation::Sanitize;

pub use validation::Validate;

pub use validation::ValidationContext;

pub use validation::ValidationError;

pub use validation::sanitize_string;

pub use validation::validate_dht_key;

pub use validation::validate_dht_value;

pub use validation::validate_file_path;

pub use validation::validate_message_size;

pub use validation::validate_network_address;

pub use validation::validate_peer_id;

pub use rate_limit::JoinRateLimitError;

pub use rate_limit::JoinRateLimiter;

pub use rate_limit::JoinRateLimiterConfig;

pub use rate_limit::extract_ipv4_subnet_8;

pub use rate_limit::extract_ipv4_subnet_16;

pub use rate_limit::extract_ipv4_subnet_24;

pub use rate_limit::extract_ipv6_subnet_32;

pub use rate_limit::extract_ipv6_subnet_48;

pub use rate_limit::extract_ipv6_subnet_64;

pub use dht::node_age_verifier::AgeVerificationResult;

pub use dht::node_age_verifier::NodeAgeCategory;

pub use dht::node_age_verifier::NodeAgeConfig;

pub use dht::node_age_verifier::NodeAgeRecord;

pub use dht::node_age_verifier::NodeAgeStats;

pub use dht::node_age_verifier::NodeAgeVerifier;

pub use dht::node_age_verifier::OperationType;

pub use security::DiversityStats;

pub use security::GeoInfo;

pub use security::GeoProvider;

pub use security::IPAnalysis;

pub use security::IPDiversityConfig;

pub use security::IPDiversityEnforcer;

pub use security::IPv4NodeID;

pub use security::IPv6NodeID;

pub use security::NodeReputation;

pub use security::ReputationManager;

pub use security::StubGeoProvider;

pub use storage::FileChunker;

pub use storage::StorageManager;

pub use chat::Call;

pub use chat::Channel;

pub use chat::ChannelId;

pub use chat::ChannelType;

pub use chat::ChatManager;

pub use chat::Message;

pub use chat::MessageId;

pub use chat::Thread;

pub use discuss::Badge;

pub use discuss::Category;

pub use discuss::CategoryId;

pub use discuss::DiscussManager;

pub use discuss::Poll;

pub use discuss::Reply;

pub use discuss::ReplyId;

pub use discuss::Topic;

pub use discuss::TopicId;

pub use discuss::UserStats;

pub use projects::Document;

pub use projects::DocumentId;

pub use projects::Folder;

pub use projects::Project;

pub use projects::ProjectAnalytics;

pub use projects::ProjectId;

pub use projects::ProjectsManager;

pub use projects::WorkflowState;

pub use threshold::GroupMetadata;

pub use threshold::ParticipantInfo;

pub use threshold::ThresholdGroup;

pub use threshold::ThresholdGroupManager;

pub use threshold::ThresholdSignature;

pub use quantum_crypto::CryptoCapabilities;

pub use quantum_crypto::KemAlgorithm;

pub use quantum_crypto::NegotiatedAlgorithms;

pub use quantum_crypto::ProtocolVersion;

pub use quantum_crypto::QuantumCryptoError;

pub use quantum_crypto::SignatureAlgorithm;

pub use quantum_crypto::negotiate_algorithms;

pub use quantum_crypto::create_default_pqc_config;

pub use quantum_crypto::create_pqc_only_config;

pub use quantum_crypto::types::FrostCommitment;

pub use quantum_crypto::types::FrostGroupPublicKey;

pub use quantum_crypto::types::FrostKeyShare;

pub use quantum_crypto::types::FrostPublicKey;

pub use quantum_crypto::types::FrostSignature;

pub use quantum_crypto::types::GroupId;

pub use quantum_crypto::types::HandshakeParameters;

pub use quantum_crypto::types::ParticipantId;

pub use quantum_crypto::types::PeerId as QuantumPeerId;

pub use quantum_crypto::types::QuantumPeerIdentity;

pub use quantum_crypto::types::SecureSession;

pub use quantum_crypto::types::SessionId;

pub use quantum_crypto::types::SessionState;

pub use placement::AuditSystem;

pub use placement::DataPointer;

pub use placement::DhtRecord;

pub use placement::DiversityEnforcer;

pub use placement::GeographicLocation;

pub use placement::GroupBeacon;

pub use placement::NetworkRegion;

pub use placement::NodeAd;

pub use placement::PlacementConfig;

pub use placement::PlacementDecision;

pub use placement::PlacementEngine;

pub use placement::PlacementMetrics;

pub use placement::PlacementOrchestrator;

pub use placement::RegisterPointer;

pub use placement::RepairSystem;

pub use placement::StorageOrchestrator;

pub use placement::WeightedPlacementStrategy;

pub use attestation::AttestationConfig;

pub use attestation::AttestationError;

pub use attestation::AttestationResult;

pub use attestation::EnforcementMode;

pub use attestation::EntangledId;

pub use attestation::SunsetTimestamp;

pub use upgrade::ApplierConfig;

pub use upgrade::ApplyResult;

pub use upgrade::BackupMetadata;

pub use upgrade::DownloadProgress;

pub use upgrade::Downloader;

pub use upgrade::DownloaderConfig;

pub use upgrade::PinnedKey;

pub use upgrade::Platform as UpgradePlatform;

pub use upgrade::PlatformBinary;

pub use upgrade::Release;

pub use upgrade::ReleaseChannel;

pub use upgrade::RollbackManager;

pub use upgrade::SignatureVerifier;

pub use upgrade::StagedUpdate;

pub use upgrade::StagedUpdateManager;

pub use upgrade::UpdateConfig;

pub use upgrade::UpdateConfigBuilder;

pub use upgrade::UpdateInfo;

pub use upgrade::UpdateManager;

pub use upgrade::UpdateManifest;

pub use upgrade::UpdatePolicy;

pub use upgrade::UpgradeError;

pub use upgrade::UpgradeEvent;

pub use upgrade::create_applier;

Modules

adaptive

Adaptive P2P network implementation Adaptive P2P Network Implementation

address

Network address types

address_book

User directory mapping (UserId <-> FourWordAddress) AddressBook: maps UserId <-> FourWordAddress for messaging and chat.

api

Public API matching the spec Clean API implementation for saorsa-core

attestation

Entangled Attestation system for software integrity verification

auth

Authentication system for multi-writer records Authentication system for multi-writer records.

bgp_geo_provider

BGP-based GeoIP provider using open-source routing data BGP-based GeoIP Provider

bootstrap

Bootstrap cache for decentralized peer discovery Bootstrap Cache System

chat

Chat system (Slack-like) Chat system (Slack-like) with channels, threads, and real-time messaging

config

Configuration management system

control

Control module for network-level control messages and handling.

dht

Distributed Hash Table implementation Distributed Hash Table implementations

dht_network_manager

DHT Network Integration Manager DHT Network Manager

discuss

Discuss system (Discourse-like) Discuss system (Discourse-like) for long-form discussions and knowledge sharing

encrypted_key_storage

Encrypted key storage with Argon2id and ChaCha20-Poly1305

error

Error types Comprehensive error handling framework for P2P Foundation

events

Async event bus for watches and state changes Async event bus for watches and topology changes.

fwid

Four-word identifier system Four-word identifier system for human-readable addressing.

geographic_enhanced_network

Geographic-aware networking enhancements for P2P routing optimization Geographic Enhanced Network Module

health

Health check system for monitoring and metrics Health check system for P2P Foundation

identity

User identity and privacy system Identity management module

key_derivation

Hierarchical key derivation system

messaging

Rich messaging system (WhatsApp/Slack-style)

mls

MLS verifier adapter and proof format

monotonic_counter

Monotonic counter system for replay attack prevention

network

Network core functionality Network module

peer_record

Peer record system for DHT-based peer discovery

persistent_state

Persistent state management with crash recovery

placement

Placement Loop & Storage Orchestration System Placement Loop & Storage Orchestration System

prelude

Prelude module for convenient imports

production

Production hardening features Production hardening features for the P2P Foundation

projects

Projects system with hierarchical organization Projects system with hierarchical organization structure

quantum_crypto

Quantum-resistant cryptography Quantum-resistant cryptography module

rate_limit

Unified rate limiting engine

secure_memory

Secure memory management for cryptographic operations

security

Security and cryptography Security module

storage

DHT-based storage for multi-device sync DHT-based storage module for multi-device synchronization

telemetry

Telemetry for metrics and health signals Telemetry module for metrics, tracing, and health signals.

threshold

Threshold cryptography for group operations Threshold cryptography module

transport

Transport layer (QUIC, TCP) Transport Layer

types

Shared simple structs

upgrade

Auto-upgrade system for cross-platform binary updates Auto-upgrade system for cross-platform binary updates.

utils

Utility functions and types Utilities module placeholder

validation

Validation framework for input sanitization and rate limiting Comprehensive input validation framework for P2P Foundation

Structs

AntMlDsaPublicKey

ML-DSA-65 public key

AntMlDsaSecretKey

ML-DSA-65 secret key

AntMlDsaSignature

ML-DSA-65 signature

ChaCha20Poly1305Cipher

ChaCha20-Poly1305 AEAD cipher for quantum-resistant symmetric encryption

EncryptedMessage

Wire format for encrypted messages

MlDsa65

ML-DSA-65 implementation using FIPS-certified algorithm

MlKem768

ML-KEM-768 implementation using FIPS-certified algorithm

MlKemCiphertext

ML-KEM-768 ciphertext

MlKemPublicKey

ML-KEM-768 public key

MlKemSecretKey

ML-KEM-768 secret key

SharedSecret

Shared secret from key encapsulation

SymmetricEncryptedMessage

A complete encrypted message containing ciphertext and nonce

SymmetricKey

A 256-bit symmetric encryption key for ChaCha20-Poly1305

Enums

PqcError

Errors that can occur during PQC operations

SymmetricError

Errors that can occur during symmetric encryption operations

Constants

VERSION

Saorsa Core version

Traits

MlDsaOperations

ML-DSA operations trait

MlKemOperations

ML-KEM operations trait

Functions

saorsa_pqc_init

Initialize the library with optimal settings

Type Aliases

Multiaddr

Network address used for peer-to-peer communication

PeerId

Peer identifier used throughout Saorsa

SaorsaPqcResult

Result type for PQC operations