# FR-4: Peer-to-Peer Node Interaction ## 1. Overview This document details the requirements for establishing and maintaining secure peer-to-peer (P2P) node interactions throughout the system. The goal is to enable direct, authenticated communication between trusted nodes, thereby supporting file sharing, replication, and redundancy without relying solely on centralized servers. This requirement is critical to ensuring high availability, resilience, and user-controlled data exchange, while integrating with the overall deterministic simulation framework to test network conditions under varied scenarios. ## 2. Objectives & Scope ### 2.1 Objectives - **Secure Connectivity:** Ensure that all node-to-node communications use robust encryption and mutual authentication. - **Explicit Trust Establishment:** Require that connections between nodes are established based on user-configured trust relationships—using pre-approved IP addresses and associated public key credentials. - **Transparent and Resilient Interaction:** Maintain reliable connectivity across nodes even in scenarios with adverse network conditions (e.g., latency, intermittent connectivity, or failures). - **Support for Redundancy and Backup:** Enable efficient file replication and synchronization by leveraging direct P2P communication channels. - **Deterministic Simulation:** Facilitate testing of P2P interactions under simulated network delays, packet loss, and other disruptions to validate performance and recovery. ### 2.2 Scope - Applies to all interactions between self-hosted nodes participating in file sharing and replication. - Covers the establishment, maintenance, and teardown of direct P2P connections. - Encompasses both the initial secure connection handshake and ongoing secure data exchange. - Integrates with the deterministic simulation framework to reproduce network scenarios. ## 3. Detailed Requirements ### 3.1 Secure Connection Setup - **Mutual Authentication:** - Nodes must authenticate each other using explicit exchange of pre-configured public key credentials. - Authentication relies on a user-defined list of trusted nodes, where each node is identified by its IP address and public key fingerprint. - No automatic node discovery is permitted; connections must be initiated only with user-approved peers. - **Encryption of Data:** - All P2P communications must be secured by employing strong encryption methods (e.g., TLS or a custom binary protocol with built-in encryption features). - Encryption should ensure confidentiality and integrity of data in transit so that even if intercepted, the payload remains unusable to unauthorized entities. ### 3.2 Communication Protocols - **Custom Binary Protocol for Inter-Node Messaging:** - A custom-designed binary protocol will be used for node-to-node communication. This minimizes external dependencies and improves control over security features. - The protocol should support low-latency, high-throughput data exchange, tailored specifically for replication and synchronization tasks. - Built-in security features, such as message integrity checks and automatic retransmission for lost packets, are required. - **Fallback & Secure Transport:** - In environments where the custom protocol might be incompatible, or fallback measures are needed, nodes should be able to leverage standardized secure protocols (e.g., TLS). - The design must facilitate seamless switching between protocols without compromising security or performance. ### 3.3 Explicit Trust and Configuration - **User-Configured Node List:** - The system must provide mechanisms for users to explicitly list nodes (using IP addresses and corresponding public keys) with which to establish connections. - Nodes not on the approved list must be denied connection requests. - **Trust Management:** - A trust management module is required to verify the identity of each node during the connection handshake process. - The module must store and update trust relationships locally, ensuring that any changes (e.g., revoked access) are promptly enforced. ### 3.4 Resilience and Robustness - **Network Condition Simulation:** - The connectivity framework must integrate with the deterministic simulation system to allow controlled testing scenarios. These include: • Simulating network latency, jitter, and packet loss. • Simulating intermittent connectivity or complete node unavailability. - These tests validate that P2P communications degrade gracefully and that link recovery mechanisms work effectively. - **Error Recovery and Reconnections:** - In the event of a connection drop or node failure, the system must automatically attempt to re-establish connections with predefined backoff strategies. - When reconnections occur, the entire authentication process must be repeated to ensure continued security. ### 3.5 Monitoring and Feedback - **Status Indicators:** - Nodes shall provide real-time feedback on the status of all P2P connections, including: • Connection establishment successes and failures. • Latency and throughput metrics. • Alerts when a node is unreachable or when security credentials fail verification. - **Audit Logging:** - All connection events, including successful handshakes and failures, must be recorded in a tamper-evident log. - Logs should record details such as timestamps, node identifiers, error codes (if any), and the outcome of the authentication process. ## 4. Measurable Criteria & Test Cases ### 4.1 Automated Connection Tests - **Connection Establishment Test:** - Pre-configure a set of trusted nodes with valid IP and public key data. - Test that connections are only established between these nodes and that any connection attempts from unapproved nodes are rejected. - **Encryption Validation Test:** - Verify, by capturing network traffic in a controlled environment, that all inter-node communications are encrypted. - Ensure that no data is transmitted in plaintext. ### 4.2 Resilience Tests - **Simulated Network Adversity:** - Use the deterministic simulation framework to introduce network delays, jitter, and packet loss. - Confirm that nodes automatically reconnect upon transient failures and that connection handshakes are successfully re-initiated. - **Failure Handling Test:** - Simulate node unavailability (e.g., power cycle a node) and verify that the remaining nodes detect the failure and attempt reconnection according to the defined retry strategies. ### 4.3 Performance and Throughput - **Latency and Throughput Measurements:** - Record key metrics (latency, throughput, handshake time) during normal operations and under simulated network conditions. - Compare performance against pre-defined benchmarks to ensure that the system meets the targeted responsiveness and efficiency. ## 5. Dependencies & Integration Points - **Trust and Access Control Module:** - FR-4 relies on integration with modules managing explicit trust and public key verification (as described in ADR-0008 and ADR-0009). - **Encryption and Communication Protocols:** - The secure protocol for node communication is further defined in ADR-0007, ensuring alignment in cryptographic practices. - **Deterministic Simulation Framework:** - Integration with the simulation framework is essential to validate robustness under controlled fault injection scenarios. ## 6. Security Considerations - **Key Security:** - Public keys and associated credentials must be stored securely on each node and never transmitted insecurely. - **Man-in-the-Middle (MitM) Protection:** - The mutual authentication process and encrypted communication channels must be designed to effectively mitigate MitM attacks. - **Audit and Logging:** - All steps in the connection handshake and subsequent communication sessions need to be logged without leaking sensitive information. ## 7. Conclusion FR-4 establishes the framework for secure, resilient peer-to-peer node interactions that underpin the system’s replication and synchronization capabilities. By mandating explicit trust configurations, robust mutual authentication, and integration with deterministic simulation testing, this requirement ensures that file sharing between nodes is both secure and reliable even under adverse network conditions. This design upholds the system’s overall objectives of privacy, data availability, and user empowerment.