P2P Networking System

[MrScripty]

Development Proposal: Secure, Adaptive P2P Collaboration with Multi-Tiered Data Synchronization

1. Introduction & Purpose

This proposal outlines the definitive architecture for Studio-Whip's peer-to-peer (P2P) collaboration layer. This system is designed from the ground up to be secure, globally accessible, and adaptable to the needs of projects from a single creator to a full enterprise studio. It rejects traditional centralized and public discovery models in favor of a private-by-default, invite-first approach.

The architecture is founded on four non-negotiable pillars:

1. Progressive Decentralization: The project's root of trust (the "Genesis Authority") is an adaptive cryptographic scheme (Shamir's Secret Sharing) that can evolve as a team grows, starting with a secure multi-factor model for even a solo user.
2. Quantum-Resistant (QR) End-to-End Security: All communication is protected by next-generation cryptographic algorithms, ensuring long-term data confidentiality and integrity.
3. Self-Sovereign Identity & Accountable Governance: Every user action is cryptographically signed and attributable. A hybrid peer-driven and user-driven protocol allows for both immediate threat mitigation (Quarantine) and permanent, accountable key revocation within a project.
4. Multi-Tiered Data Synchronization: A sophisticated, priority-aware data sync model ensures that real-time edits, foundational project state, and large media assets are all transferred efficiently using the appropriate protocol for the job.

2. Goals & Scope

• Core Functionality:
  • Adaptive Genesis Authority: Implement a Shamir's Secret Sharing (SSS) based system for the project's root key, with a secure "Genesis Migration Ceremony" to transition authority.
  • Secure Key Storage: Store all user-generated private keys in the native OS keychain.
  • Secure Identity Portability: Implement a time-locked identity backup process protected by a strong, system-generated transport password.
  • Invite-First WAN Connectivity: The primary connection method will be a direct handshake facilitated by a cryptographic invite code, with full NAT traversal support.
  • Multi-Tiered Sync:
    • Tier 1 (Live): Use Gossipsub for real-time YRS updates and session messages.
    • Tier 2 (Foundation): Use Request-Response for initial full-state sync when a peer joins.
    • Tier 3 & 4 (Assets): Use a priority-aware Bitswap protocol for on-demand and background synchronization of large media assets.
  • Quantum-Resistant Security: Utilize QR algorithms (e.g., Kyber for KEM, Dilithium for signatures) for all cryptographic operations.
  • Quarantine & Revocation Protocol: Implement a two-tiered system for threat mitigation and key revocation.
• Out of Scope:
  • Password-based user authentication. The system is fundamentally passwordless, relying on cryptographic keys for identity and authorization.
  • DHT-based public project discovery and bootstrap nodes. The system is private-by-default.
  • Hardware security token integration. This is a logical next step after OS keychain support is mature.

3. Design Philosophy

The architecture of this system is guided by a set of core principles designed to create a trustworthy, resilient, and user-centric platform.

• User Sovereignty with Project-Level Governance: The user is the sole custodian of their master private keys. This is the foundation of their sovereignty. However, access to a specific collaborative project is a privilege governed by that project's own rules. The power to revoke a user's access is not held by Studio-Whip or any central entity, but by the project's own Genesis Authority. Crucially, any such action—like a manager-led revocation—is a transparent, cryptographically signed, and auditable event within the project's history. This replaces the opaque, arbitrary bans of centralized platforms with a system of accountable, protocol-defined governance. A user's identity cannot be "deleted"; their keys and data remain their own, and they can always use their sovereign identity to join other projects or create new ones.
• Security by Default, Not as an Option: Advanced security is not a toggle or a premium feature; it is the baseline. The use of quantum-resistant cryptography, secure key storage, and encrypted transports is mandatory and transparent, protecting users from both current and future threats without requiring them to be security experts.
• Progressive Decentralization: The system must be as secure and usable for a solo creator as it is for a large studio. The Genesis Authority model is designed to adapt, allowing a project to "level up" its security and governance structure as the team grows, without requiring a disruptive migration or a weak initial setup.
• Composable, Best-in-Class Tooling: This system does not reinvent cryptographic or networking primitives. It achieves its goals by intelligently composing robust, battle-tested, open-source libraries (libp2p, keyring-rs, oqs-rs, shamir, yrs). This strategy accelerates development, enhances security, and ensures maintainability.
• Practicality and Abstraction: The immense complexity of the underlying protocols must be abstracted away from the end-user and the application developer. The user experience should be simple and intuitive (e.g., "Create Invite Code"), and the developer API should be clean and event-driven, allowing for easy integration of collaborative features without deep networking knowledge.

4. Proposed Architecture & Design

4.1. Genesis Authority & Progressive Decentralization

The project's root of trust is managed via an adaptive Shamir's Secret Sharing (SSS) scheme, preventing any single point of failure.

• Project Creation (The Bootstrap Phase): A new project creator is guided through a Genesis Ceremony. For a solo user, a 2-of-3 SSS scheme is recommended, with shares secured across different factors: the OS Keychain, a hardware token (like a YubiKey), and a user-provided recovery passphrase. This provides true multi-factor security even for a single person. The full Genesis Private Key is never stored in its complete form.
• Project Growth (The Genesis Migration Ceremony): The current Genesis authority can initiate a secure protocol to transfer authority to a new SSS scheme (e.g., for a larger team). A GenesisUpdate message, signed by the old authority, is broadcast, allowing peers to verify and atomically update their root of trust, creating an unbroken chain of authority.

4.2. Identity & Security Protocols

• Secure Key Storage: The CryptoManager resource will use the keyring-rs crate to store the user's private identity and encryption keys in the native OS keychain, protecting them from file-based theft.
• Secure Identity Portability: To move an identity, the user exports a time-locked backup file (e.g., valid for 24 hours). This file is encrypted with a strong, system-generated transport password that is displayed to the user. On the new device, both the file and this password are required to decrypt and install the identity into the new OS keychain.
• Invite Handshake (V2): The invite code contains the host's network address and public encryption key. A joining peer generates the symmetric session key and sends it to the host, encapsulated (encrypted) by the host's public key, ensuring the session key is never transmitted in the clear.
• Quarantine & Revocation: A two-tiered protocol provides robust security:
  1. Quarantine (Peer-Driven): Any peer can propose to quarantine a misbehaving actor. Once a network-wide threshold is met, all peers will temporarily ignore the target, preventing further disruption.
  2. Revocation (User/Admin-Driven): A user can use their offline Revocation Private Key to permanently and verifiably invalidate their own compromised identity. A project "manager" (a role granted by the Genesis Authority) can also issue a revocation for a user within their project.
• Strict Introduction: Gossipsub message validation will enforce that a newly connected peer cannot participate until they have successfully broadcast a valid, signed "Introduction" message containing their public identity certificate.

4.3. Multi-Tiered Data Synchronization (SyncCoordinator)

A SyncCoordinator within the P2P plugin will manage data transfer priorities by delegating tasks to the appropriate libp2p protocol.

• Tier 1 (Live - Gossipsub): For small, frequent messages like YRS updates and cursor positions, ensuring minimal latency.
• Tier 2 (Foundation - Request-Response): For the one-time transfer of the full project state (the YRS document snapshot) to a new peer.
• Tier 3 (On-Demand Assets - Bitswap High Priority): For fetching large media assets the user is actively trying to access. Bitswap functions like a torrent, pulling blocks from multiple peers simultaneously for maximum speed.
• Tier 4 (Background Assets - Bitswap Low Priority): For using idle bandwidth to pre-fetch all other project assets over time, enabling full offline availability without impacting the user's immediate workflow.

5. Implementation Plan & Actionable Steps

1. Phase 1.0: Core Crypto & Secure Storage: Implement CryptoManager with QR algorithms and keyring-rs.
2. Phase 1.1: Genesis & SSS: Implement the SSS logic and the initial Genesis Ceremony UI.
3. Phase 1.2: Direct Connection & Foundational Sync: Implement the V2 Invite Handshake and the Tier 2 Request-Response protocol.
4. Phase 1.3: Live Sync & Asset Sync: Integrate Gossipsub for Tier 1 and Bitswap with the SyncCoordinator for Tiers 3 & 4.
5. Phase 1.4: Identity, Signing & Security Protocols: Implement the full identity certificate, signing/verification, and the Quarantine and Revocation protocols.
6. Phase 1.5: Integration & Polish: Implement the Genesis Migration Ceremony, the Identity Portability flow, and build out the necessary UI panels.

6. Future Considerations

• Remote Attestation: To cryptographically guarantee that a peer is running an unmodified, official version of the Studio-Whip client, a future version should explore hardware-based remote attestation using a Trusted Platform Module (TPM) or Secure Enclave. This is the gold standard for preventing client-side exploits.
• Mnemonic Phrase Recovery: For ultimate disaster recovery (e.g., loss of all devices), a future version could implement an identity recovery mechanism based on a 12/24-word mnemonic phrase. This would be a separate, high-security flow from the standard identity portability process and would serve as the user's final backstop against total data loss.