PeerVault is a peer-to-peer decentralized application used to share sensitive information with someone else identified by cryptographic keys. The Vault is yours, no server involved, 100% Open Source. Leverage from blockchain technology innovation such as libp2p and bip39 Mnemonic code for generating deterministic keys.

PeerVault Architecture & RFCs

Architecture and design Book implementation of the PeerVault.

This repository build a book available at https://peervault.github.io/architecture-rfcs.

But, Why ?

Most people share sensible passwords and documents through email and insecure messaging platform. Even in IT professional environment, it is common to exchange secrets without securing the exchange properly. Who never shared a ssh key through slack?

Values

1. Must be decentralized (act as Server and Client at same time)
2. 1st Grade Security (encryption and tutti quanti)
3. Open Source (because strong security can only be built over time by the community)
4. Clean Architecture

Contributing

If you'd like to contribute to PeerVault of new features or change that you think can improve the product, Please follow the RFC instruction

Architecture

Table of Contents

• Opening
• Table of Contents
• Glossary
• Clean Architecture
  • Service (Daemon)
  • GUI-Flutter
  • Command Line Interface

Glossary

Clean Architecture

Clean Architecture is a well-known design that promotes loosely coupled application components to have better control and flexibility over time on each part.

First, we have two main components:

1. Human Interface (GUI or CLI)
2. Business Logic (SERVICE)

It can be kind of obvious for web developers but in the world of desktop applications it is not so much popular. Split these two components gave us flexibility to choose different programming languages as well as ease the development of many Client UI without having to cope with all the complexity of business logic.

• Service (Daemon)
• GUI-Flutter
• Command Line Interface

PeerVault-Service (Daemon)

All the business logic reside in the Service.

The daemon has been write with GoLang. Mainly because the underlying library libp2p have the most advanced support with Go and was the only way to make it work the relay communication securely the for passing through NAT.

Layers

The service are build on top of 3 layers:

1. Communication

The Blue layer represent the communication, internal with the GUI or external with other Peer.

• Local API: Expose HTTP API to manipulate the Vault create or restore Owner, create or share Secret
• WebSocket Event: Instant notification to GUI when a new secret is shared by another Vault same or different Owner
• Peer LibP2P: Enable secure p2p channel with other Vault through libp2p2 Relay to pass through NAT

2. Domain

The Yellow layer represent the internal Domain abstraction

• Owner: Identity of the Vault Owner, contain Master Key, Device Key, QmPeerId.
• Secret: Secret information, can have many format, Password, Document, Certificate, Private key...
• Exposure: Expose secret publicly on the computer, when mounting SSH Private key
• Backup: Able to export Vault DB encrypted, can only be restored by holding the Owner Master Key

3. Persistence

The Red layer represent the persistent abstraction, we are using the bbolt key/value database

PeerVault-GUI-Flutter (UI)

A Nice and smooth Desktop GUI to interact with the PeerVault daemon (service business logic) in order to send command (HTTP) or receiving notifications (WEBSOCKET).

The Programming language chose are flutter because it offers a native integration where the pixel can be painted with a really nice declarative paradigm using Widget. The Desktop support is a bit young but in active development.

PeerVault-CLI (UI)

Able to communicate with the PeerVault Service API in the command line, useful for a programmatic system like a secrets manager for infrastructure as code.

Peer Protocol

Explain in detail the protocol of communication between Peer.

• Secret Sharing

Secret p2p exchange

sequenceDiagram
    Alice Vault->>+Alice: (3) Decrypt secret binary
    note over Alice,Bob: Exchange Encrypted with secio
    Alice ->>+ Bob: (1) Shared secret request
    Bob -->> Alice: (2) Accept secret
    Alice ->>+ Bob: (4) Transfert secret data binary
    Bob ->> Bob Vault: (5) encrypt secret binary

1. Alice send sharing secret request with data: KeyPath, RequestId, Expiration
2. Bob accept (and store infos in bbolt) or decline request and respond with data: RequestId, Accepted
3. Alice receive response and if Accepted use Child Key to decrypt secret from bbolt
4. Alice send secret to Bob with RequestId, Blob
5. Bob verify the RequestId has been accpeted before encrypt secret with his Child Key in bbolt

• request must have expiration delay: 5min default

• Owner Keychain

Owner keychain

When a vault is created for the first time, the Seed will be generated and owner will be able to keep the Mnemonic phrase also known as Paper key

Then a Master Key will be derivate from the Seed. And for each device, a Child Key hardened will be generated using a random Uint32 index

Child Key will be used to create an identity for each Peers announced on the network. Communication between peer will be encrypted using Child Key derivation.

The Relay will not be able to decrypt any exchange between peers.

• The Owner identification is made using Master Public Key
• The Peer Identification is made using Child Public Key

RFC / Request For Comments

RFCs are a process of documenting proposal for technical change. It help to structure project architecture around collective discussions seeking feedback from the community. RFC are represented by the form of documents that try to be speculative and precise.

This template are heavily based on the famous Rust RFC Book

Table of Contents

• Opening
• Table of Contents
• When you must NOT follow this process
• When you must follow this process
• Before creating an RFC
• How to propose a new RFC
• The RFC life-cycle

When you must NOT follow this process

• Rephrasing, reorganizing, refactoring, or otherwise "changing shape does not change meaning".
• Additions that strictly improve objective, numerical quality criteria (warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.)
• Enhancement of a feature that does not change the behavior or introduce BC break.

If you submit a pull request to implement a new feature without going through the RFC process, it may be closed with a polite request to submit an RFC first.

When you must follow this process

You need to follow this process if you intend to make substantial changes such as:

• API change that will break backward compatibility that is not a bugfix.
• New features (not enhancement)
• Removing features ( re-designed )
• Change of dependencies that impact API ( critical system library )
• Change of Standardization or Protocol (tcp to websocket, quic, cryptographic curve, hashing method...)

Before creating an RFC

An RFC process front-loads the collaborative work of major changes or additions to an open-source project. That is, instead of waiting until a pull request arrives with lines of code changes, discussion begins early. Contributors are required to put in effort up-front to help others in the project community understand their proposed changes. The project's TSC and its extended developer community are invited to provide input within the structure of the RFC.

Although there is no single way to prepare for submitting an RFC, it is generally a good idea to pursue feedback from other project developers beforehand, to ascertain that the RFC may be desirable; having a consistent impact on the project requires concerted effort toward consensus-building.

How to propose a new RFC

In order to ease the process, we have prepare a template that you can use to fill a proposal.

1. Copy the file 0000-rfc-template.md to rfcs/0000-my-feature.md (where "my-feature" is descriptive. don't assign an RFC number yet).
2. Fill in the RFC. Put care into the details: RFCs that do not present convincing motivation, demonstrate lack of understanding of the design's impact, or are disingenuous about the drawbacks or alternatives tend to be poorly-received.
3. Submit a pull request. As a pull request the RFC will receive design feedback from the larger community, and the author should be prepared to revise it in response.
4. At some point, a member of TSC (or other form of approval in this particular project) will approve or reject the proposal. It can also have a period for final comment (FCP) to notify that the process will end shortly. FCP period is quiet, and the RFC is either merged or closed. However, sometimes substantial new arguments or ideas are raised, the FCP is canceled, and the RFC goes back into development mode.

The RFC life-cycle

Once an RFC has been approved, it will be merged and automatically published on the website. Now that the RFC are active, it must be taken in the roadmap of the SDLC. In most of the case it will be implemented by the author of the RFC or any persons that seek interest to expedite the development of that RFC.

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people
• Being respectful of differing opinions, viewpoints, and experiences
• Giving and gracefully accepting constructive feedback
• Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
• Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind
• Trolling, insulting or derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others' private information, such as a physical or email address, without their explicit permission
• Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at abuse@plab.io. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Contributors

Here is a list of the contributors who participate in the PeerVault project.

• Pierre Tomasina