dsfx/docs/adr/0008-p2p-node-connectivity-and-security.md

ADR-0008: P2P Node Connectivity and Security

Status

Proposed

Context

Our system facilitates secure file sharing and replication across self-hosted nodes. However, rather than relying on automatic node discovery, each user will explicitly configure which nodes to connect to. In our design, a user's network is built organically—a personal web of trusted nodes—ensuring that connectivity remains fully under the control of the user. This design supports our goal of maintaining strict privacy and security (FR-4, FR-5, NFR-1) while also accommodating deterministic testing of network conditions (NFR-2, NFR-6).

User-configured connections mean that nodes will only establish connectivity with explicitly defined peers rather than automatically searching for or connecting to unknown nodes. This approach is in line with our mission to provide full user control over their digital networks and minimizes external dependencies and unexpected interactions.

Decision

We will implement a P2P node connectivity framework that emphasizes explicit user control and secure, manually configured connections with the following key features:

• Explicit Node Configuration: The user will be responsible for configuring the list of nodes with which to connect. No automatic node discovery or unsolicited connection attempts will occur. Users can build and maintain personalized networks, similar to managing a social graph, where connections reflect direct trust and controlled relationships.

• Mutual Authentication Using IP Address and Public Keys: Connections between nodes will be established only after mutual authentication using predefined IP addresses and associated public keys. This ensures that nodes connect only to explicitly authorized peers, safeguarding against unauthorized access and bolstering our overall security posture (FR-4, NFR-1).

• Encrypted Communication Channels: All inter-node communications will be secured via encryption. Our custom binary protocol, used exclusively for inter-node messaging, will incorporate strong encryption practices similar to TLS, ensuring data confidentiality and integrity across all explicitly configured connections.

• Deterministic Simulation Support: The connectivity framework will be designed to support deterministic simulation testing, allowing us to validate performance and reliability under various simulated network conditions—including latency, intermittent connectivity, and failure scenarios—while preserving the explicit configuration model (NFR-2, NFR-6).

Consequences

• Advantages:

  • Enhanced User Control: Users maintain complete authority over which nodes are part of their network, reinforcing the principle of self-ownership and ensuring that network growth is deliberate and trusted.
  • Increased Security: By connecting only to user-approved nodes, the potential attack surface is reduced. Mutual authentication using IP addresses and public keys further ensures that only verified entities participate in the user's network (NFR-1).
  • Predictable Behavior: A manually configured network is easier to simulate and test deterministically, as the connection topology is fixed and known, enhancing reliability and performance under controlled test conditions (NFR-2, NFR-6).

• Trade-offs:

  • Limited Network Growth: Without automatic discovery, users must manually add each node, potentially limiting the organic expansion of their network. However, this aligns with our emphasis on explicit trust relationships and user control.
  • Increased Configuration Effort: Users or administrators are responsible for setting up and maintaining node configurations, which may increase the initial setup effort. This complexity is acceptable given the benefits of enhanced privacy and security.
  • Maintenance Overhead: Changes to network configurations must be managed manually, requiring additional processes for updating and revoking node connections as trust relationships evolve.

References to Requirements

• Functional Requirements:

  • FR-4: Peer-to-Peer Node Interaction – Connectivity is critically important for file sharing and replication, and connecting only to explicitly configured nodes enhances trusted operations.
  • FR-5: Replication and Redundancy Management – Reliance on user-configured nodes ensures replication occurs only among trusted peers, maintaining data integrity and availability.

• Non-Functional Requirements:

  • NFR-1: Security & Privacy – Explicit node configuration, mutual authentication, and encrypted communications all contribute to a secure, user-controlled environment.
  • NFR-2: Performance & Responsiveness – Fixed, user-defined connectivity simplifies deterministic simulation testing, ensuring that the system performs reliably under varying conditions.
  • NFR-6: Deployability & Maintainability – The lack of automatic node discovery reduces dependency on external systems and minimizes unexpected dynamic behavior, aiding in straightforward deployment and predictable maintenance.

Conclusion

The decision to use explicit, user-configured node connectivity supports our secure, privacy-focused design by ensuring that only trusted nodes participate in a user's network. By employing mutual authentication, encrypted communication channels, and integrating deterministic simulation testing into our custom protocol, this approach meets our functional and non-functional requirements while keeping network growth and connection management fully under the user's control.