description: End-to-End Encryption (E2EE) of all data in NextGraph, and encryption at rest too
layout: ../../layouts/MainLayout.astro
---
As we know, NextGraph is [local-first](/en/local-first), and synchronizes its data with other replicas (other devices running the app) when it has internet connectivity.
There exist already plenty of protocols in OSS that could be used for syncing, some of them being End-to-end encrypted (E2EE).
ActivityPub, XMPP, OpenMLS, Signal, Matrix, Nostr, ATproto/Bluesky, etc… can all be used as transport protocols for the syncing mechanism.
Why did NextGraph have to reinvent the wheel and create a special protocol, once again ?
And specially knowing that doing so, seems counter productive.
The answer is: because we didn't have the choice but to create a new protocol, because none of the existing ones had the characteristics we need for NextGraph to deliver on its promise. More details coming now.
The goal is to have a decentralized protocol that does not depend on any central authority or single point of failure.
That's easy to say… and a bit more difficult to put in practice, specially when E2EE enters into play.
Here is the breakdown of the problem.
### No more DNS, TLS nor HTTPS
DNS and TLS certificates are not fully decentralized and they both rely on some single points of failure (and domains are expensive, and hard to setup and manage for the end-user). TLS was discarded by the creator of Signal Protocol by example, because his main goal was to offer a secure and totally decentralized chat protocol. We also have to forgo DNS and TLS in our architecture, for similar reasons. That's not an easy task. Matrix, by example, that is just another iteration on the above mentioned Signal Protocol (reimplemented in permissive licensing, and with a slightly different protocol for group encryption), felt the need to wrap all the E2EE protocol within some classical REST apis with TLS and a domain name, so basically they voided the advantage that Signal had created: no need for DNS nor TLS certificates. The result is Synapse protocol and Home Server: a mix of E2EE and plain old TLS APIs. That's not what we did. In our protocol, every peer is known by its IP and a PeerID that is a public key. There is no DNS, there is no TLS certificate. We use the Noise protocol for encryption of communication between peers, which is, for now, channeled into a WebSocket, but could be transported over other protocols, including UDP or QUIC, by example.
### P2P isn't viable. we need 2-Tier network with Brokers
Pure Peer to Peer (P2P) is not practical in real life. Even though we claim NextGraph is peer-to-peer (and it is, somehow), our network topology is not exactly peer-to-peer. What we do is called “**2-tier topology**". It means that the peers/replicas do not communicate directly with each other. Instead, they send and receive their data from some tiers that we call “**Brokers**”. The broker is a server that is always up and running, and that replicas can always contact in order to sync their data. To the contrary, a truly P2P topology would imply that the replicas are connecting directly to each other. This is what HyperHyperSpace is doing by example, with WebRTC that establishes connections directly between web-browsers. Several other protocols are doing direct P2P communication. While it looks good on the paper, and is attractive because it seems at first glance as a desirable feature, it turns out that true P2P is not practical because it forces the peers/replicas that want to sync and exchange data, to be both online at the very same moment. This condition is not guaranteed at all and will impede synchronization if not met. What are the chances that any participant of a collaborative group are connected to the internet at the very same time? very low in real life cases. If I want to sync between several of my own devices, does that mean that at least 2 of my devices have to be online at the same time? this is not gonna work. For this reason, we opted for a “2-tier” topology. Peers that are intermittently connected to the internet, can still synchronize because they will talk only to a common “broker” that is always up and running and that is there specially for that. In fact each broker is connected to the other brokers in the overlay, so it doesn't matter to which broker the client is connected.
### End-to-End Encryption of everything
Now comes another problem. If the concept of a “server” is back in the picture, what about the guarantees on privacy and single point of failure (SPOF)? Well, we have thought about that. Concerns for SPOF is easy to clear if you allow many brokers to be available at the same time, if the broker can be self-hosted by anyone, and if the user can switch to failover brokers transparently. This is what we did in our protocol design. And about concerns for privacy, the solution is very simple (at least, on the paper): **End-to-End-Encryption**. The broker only receives and forwards messages that are E2E encrypted. It cannot read what is in the messages. The only thing it can see is the IP of the devices, and their PeerID (a public key). Only the replicas (the clients) can decrypt the messages. So basically, we reinvented a group E2EE protocol? yes! and why not reuse Signal protocol, Matrix protocol, OMEMO or OpenMLS that already have a very well established Double-Rachet E2EE mechanism? Well, this also could not have been done, because of the following issues.
### Group encryption is not enough
All 3 existing protocols I just mentioned, are derived from the first one: double ratchet by Moxie Marlinspike et al. This protocol is very good at one thing: enforce privacy for the participants **within the group**. And prevent any other agent that is **outside of the group**, from seeing any plaintext (the messages in clear, unencrypted form). The guarantees are simple: Or you are inside the group and you can see everything within this group. Or you are outside of the group and you cannot see anything. Very nice! Very useful. Everybody uses it on a daily basis, in WhatsApp, by example. In addition, it adds a guarantee called Perfect Forward Secrecy (PFS) which has a negative side-effect for newcomers that will join the group later on (that are invited to join after a while). hey will not be able to see the historical content of the group. That's good for paranoid people who are afraid a compromised key would let unauthorized people see all the past conversation. And it also is based on the concept that this compromised key would be detected, and the intruder would be kicked out fast enough so he doesn’t see any newer messages neither (that's Post Compromise Security), which is another problem difficult to solve. Anyway, it turns out that PFS is an anti-feature in our case, because we obviously want a joining collaborator to **have access to all the historical data** of a DAG of modification of a document. If they wouldn't have that, they wouldn't be able to reconstruct the document's content at all. This is a problem that Matrix is facing. So basically, we do not want PFS. And this problem is being addressed in a [new draft specification called MIMI](https://datatracker.ietf.org/group/mimi/about/), a working group of the IETF. But even if this is solved, I am afraid it will not be enough for our use cases.
We want the double-ratchet because we want to change epoch from time to time. Specially when we revoke the access of a specific user. In this case, the encryption keys need to be refreshed. We can also do so in a periodic manner, for extra security. Another reason why existing group E2EE protocols are not adapted for us, is that the “all or nothing“ access pattern is not what we need neither.
### A repo has editors, viewers and signers
In NextGraph, **each Document** has its own E2EE group, that we call a **Repo**. Now, a Repo has editors, obviously, and those should be inside the E2EE group. Sure thing. Then, we also have users that are only “readers”. they cannot edit the document. Should they be part of the E2EE group? how are the permissions going to be enforced? who is going to check if this specific user can edit or not, in a local-first setting? NextGraph uses the concept of capabilities (OCAP) for permissions. A user can read the content of a document if they have the capability to do so. Furthermore, the capability system that we have designed, is not a traditional OCAP mechanism where a “controller” eventually decides on what to do with an incoming action and associated capability. Instead, in NextGraph, there is no need for an almighty controller. We have designed a capability mechanism based on cryptography. If the user possesses the decryption key, then they are entitled to read the data. There is no need for a “controller” to verify the signature of the capability/delegation they hold. Instead, the user just gets some encrypted data, and if they have the correct decryption key, then it means they will be able to decrypt and read the data. if they don't, well, they will see garbage instead. About the “write” permission, it is the same. The editor needs to possess the private key of the Pub/Sub topic that is used to propagate the edits (more on the pub/sub later). So basically, if a user wants to modify the data, they can try as much as they want locally, but if they don’t have the private key of the pub/sub topic, it will not work because they will not be able to propagate their updates in the overlay (the brokers will refuse it). Again, there is no need for a “controller” here that will check a capability, or better said: the capability is included in the message. The “write” permission is just enforced with cryptography.
So, coming back to the problem of the E2EE group, we have several types of users with different types of access, that interact within the Repo. in addition to the **editors** and the **readers**, we also have **signers**. Those signers have only one task: Verify and Sign the commits, on request. They are not necessarily editors. But they do need read access in order to read what they are going to sign. So we have **3 types of access** (and a 4th type for the owners of the documents). Anyway. it starts to seem obvious that a classical E2EE group like OpenMLS or Matrix will not be enough, because we do not want the readers, by example, to see what the editors are doing. We don't even want them to see the list of editors. Are we going to create 4 different OpenMLS group? one for each access type? No. That would not work in practice, and not even on the paper.
So here we are, we designed and implemented a new E2EE group protocol, that takes into account the specific needs of Document editing, signing and sharing, together with cryptographic capabilities. And this… did not exist, as far as we know. Add to this the fact that we also do content-addressing and deduplication with convergent encryption on all the content and pub/sub messages, and you will soon understand why a novel protocol was needed.
**All this gives us a general overview of what our sync protocol can do, how it does it, and why we had to design a new protocol.**
More details about the protocol itself can be found in the Design [section below](/en/protocol).
But for now, let's move on to explore our [Wallet and what it contains](/en/wallet).
@ -54,7 +54,7 @@ Within each Identity, your data is organized into **3 different Stores**.
- the protected store : is a space where you can share data, documents, and media with other users, but they will need a special link and permission in order to access them and collaborate with you on those documents (or just read them). You can also create Groups here when you want to chat or collaborate with several users. This store also acts as your protected profile for social networks. Only your followers will be able to see this profile, as it is not public.
- the private store : this is a place where you put only private and personal information that only you has access to. This store will be accessible to all your devices, so it is useful in order to synchronize private data between them. You can put sensitive data too, as everything is encrypted. Nobody else will every see this data. it is not possible to share the documents of your private store.
- the private store : this is a place where you put only private and personal information that only you have access to. This store will be accessible to all your devices, so it is useful in order to synchronize private data between them. You can put sensitive data too, as everything is encrypted. Nobody else will ever see this data. it is not possible to share the documents of your private store.
You can also later, move documents from one store to another, if you are the owner of such document.
@ -88,7 +88,7 @@ You can read more about [Documents and Stores](/en/documents) in the correspondi
##### Document Menu
We bring your attention shortly on the Document's Menu that is accessible from the button with 3 vertical dots, at the topright corner of the screen.
We bring your attention shortly on the Document's Menu that is accessible from the button with 3 vertical dots, at the top-right corner of the screen.
Each Document has a double nature :
@ -100,13 +100,13 @@ Each Document has a double nature :
Also from this Document Menu, you always have the option to switch from the 2 different modes:
- Viewer mode
- Editor mode.
- Editor mode (if you have permission to edit the document, of course)
A document always opens in Viewer mode (read-only) and if you want to modify it, you have to go to the Document menu to select an Editor.
For now, only one editor is provided for each Document type, but in the future, you will be able to install more Editors, and also more Viewers.
If you open the same document in 2 different tabs or browser windows, or with different apps (on mobile, desktop, etc), and when you edit the Document in one of the window, it automatically updates itself in the viewer or editor that is opened in the other window(s). Try it! it works great.
If you open the same document in 2 different tabs or browser windows, or with different apps (on mobile, desktop, etc), and when you edit the Document in one of the windows, it automatically updates itself in the viewer or editor that is opened in the other window(s). Try it! it works great.
But please pay attention to the fact that by default, the **live editing** mode is not activated, and instead, you have to click on the blue mark button that appears at the top right corner of the screen, in order to **save** your changes.
@ -116,15 +116,15 @@ If you are editing a text document, please pay attention to the fact that live e
Viewers and Editors are what we call "Apps". And they can be installed from the built-in App Store (not ready yet, but will be available soon)
NextGraph comes with a set of Official Apps (listed in [Features](/en/features)) and developers can create new apps.
NextGraph comes with a set of Official Apps (listed in [Features](/en/features)) that are always available, and developers can also create new apps, that need to be installed with the App Store.
##### Attachments and Files
From the Document Menu, you will see many other options, most of them are not implemented yet, and will not do anything when clicked. They are there to tease you about the upcoming features ;)
Two menu options are implemented for now : History and "Attachments and Files".
Three menu options are implemented for now : History, "Attachments and Files" and "Tools > Signature".
The later is, as its name indicates, about adding some images or any other attachment file to the Document. Images will be useful when you want to insert some picture in a Rich-Text document (not available yet. but you can already add pictures in the Attachments and Files).
The second one is, as its name indicates, about adding some images or any other attachment file to the Document. Images will be useful when you want to insert some picture in a Rich-Text document (not available yet. but you can already add pictures in the Attachments and Files).
##### History
@ -139,7 +139,7 @@ You can try this between 2 tabs in your browser, or a browser tab and a native a
##### User Panel
The User Panel is another menu that is accessible from the logo of NextGraph at the left top corner of the screen.
The User Panel is another menu that is accessible from the logo of NextGraph at the top-left corner of the screen.
It offers some options to manage your connection to the Broker, your wallet, your account, and in the future, some settings.
@ -149,7 +149,7 @@ There is also an option to disconnect from the broker (with the blue toggle butt
If your internet connection is down, you can also see the status here ( there will be a red Offline sign ).
The App always tries to connect to the Broker every 5 seconds.
The App always tries to connect to the Broker every 5 seconds, unless you have toggled down the "Personal" connection.
##### Magic carpet
@ -157,6 +157,6 @@ You might ask yourself what the magic carpet is.
It is not functional yet, but it will be something like a "clipboard" where you can store temporary data.
But unlike the clipboard we are used to (with CMD+C and CMD+V), the Magic Carpet can keep a list of many items, not just the latest. This is useful when you want to move things around. Also the Magic Carpet is always reachable from anywhere in the app, and let's you drag and drop things.
But unlike the clipboard we are used to (with CMD+C and CMD+V), the Magic Carpet can keep a list of many items, not just the latest one. This is useful when you want to move things around. Also the Magic Carpet is always reachable from anywhere in the app, and let's you drag and drop things, and see the list visually.
Stay tuned for more features, by checking out the [roadmap](/en/roadmap).
NextGraph is an Open Source **App and a Platform** that anybody can use for free. Individuals and Organizations, SMEs and corporations will enjoy a rich set of features ranging from Document sharing, collaborative and productivity tools, to a Social Network, Smart contracts and more.
NextGraph is an Open Source **App and Platform** that anybody can use for free. Individuals and Organizations, SMEs and corporations will enjoy a rich set of features ranging from Document sharing, collaborative and productivity tools, to a Social Network, Smart contracts and more.
> NextGraph is secure, privacy-preserving, decentralized, and local-first (it can work online and offline too).
> NextGraph is secure, privacy-preserving, decentralized, and local-first
> which means it can work online and offline too, and will synchronize without conflicts.
In addition, NextGraph is also a [Framework](/en/framework) for App developers who want to adapt their existing app to NextGraph, or create new apps that will be based on the new principles that we want to foster and that will bring the advent of a New Internet, Next Generation Internet, call it Web 3.0 or Web 4.0, small web, whatever you want, as long as it is secure, privacy preserving, decentralized, interoperable, and easy to use!
In addition, NextGraph is also a [Framework](/en/framework) for App developers who want to adapt their existing app to NextGraph, or create new apps that will be based on the new principles that we want to foster and that will bring the advent of a New Internet, Next Generation Internet, call it Web 3.0 or Web 4.0, small web, Dweb, or whatever you want, as long as it is secure, privacy preserving, decentralized, interoperable, and easy to use!
We aim at becoming a serious alternative to the Big-Tech products and services, and to gather forces among the Free and Open Source communities (FOSS) in order to offer the best experience to end-users and programmers alike, with easy-to-use applications where the user regain **total control over their data, privacy and software**.
description: NextGraph is a local-first App and framework. Learn more about what is Local-First Software
layout: ../../layouts/MainLayout.astro
---
Local first means that the app works also offline, and even more, that it primarily works offline, and that the **syncing** that happens once we are back online, is transparent.
This is a **paradigm shift** from the current Cloud architecture, as most apps that are developed nowadays cannot run without internet connectivity. And the situation today is a complete reversal from the one we had at the end of the previous century, where all apps used to work only offline.
After the conversion of offline-only apps (the “.exe” apps), into SaaS (Software as a Service) apps that run in the cloud and cannot work without internet, we are now going towards apps that are capable of both: online and offline. This is what we call Local-First apps.
It is a very hot topic and the first [big conference](https://www.localfirstconf.com/) on the subject happened in Berlin at the end of May 2024.
In order to work properly, a Local First app needs to use CRDTs (Conflict-free Replicated Data types) that are a special way to encode/save the data, that stores additional metadata with each record, in order to help solving eventual conflicts at the moment of the merge/sync.
Some rules are agreed upon in advance on how to deal with the conflict, based on the metadata. And those rules lead to a deterministic and consistent conflict resolution mechanism across replicas, regardless of the order in which the updates are applied.
The best CRDTs out there are based on a DAG of dependencies, that encodes the causal past of an update/operation/commit (all synonyms).
Each operation indicates which previous operations it “sees” in its “causal past” at the moment when the operation is committed.
Other concurrent modification can happen, that might not have the same set of causal past, or that can have the exact same one. In this case, we say that a fork happened.
When the syncing/merging occurs, knowing the causal past for each commit that needs to be merged, enables the local replica to be sure that it didn't miss some previous commits. Also, this causal past is important to verify the correctness of the commit. A commit can have rules that need to be enforced. But those rules can only be checked based on the causal past that was present at the replica at the moment when the commit was created, and not including any other commit that might have happened concurrently.
On this topic, I let the reader refer to the work of Martin Kleppmann on [merging protocols](https://arxiv.org/abs/2012.00472) and preserving invariants, and to the [“keep CALM and CRDT on" paper](https://arxiv.org/abs/2210.12605).
To come back to the higher level overview, local-first apps deal well with offline and online collaboration with real-time editing.
Be it a document that is shared between the different devices of a single user, or a document that is shared among several users (and their respective many devices), the user will always be able to view and/or edit the document while being offline, and then sync with the other replicas after regaining connectivity.
This by itself, is a big paradigm shift for the developers, who is more used to calling some remote APIs for accessing the data.
Here the data is always accessed locally (in this sense, the backend sits in the “client” or in the “front-end" if you prefer).
It is the NextGraph protocol that deals transparently with the syncing mechanism. The developer does not need to deal with it. We provide access to a local API (in javascript by example) and data read and write happen on this local API.
We will come back to our [syncing protocol](/en/protocol) further down, but before that, we would like to explain our [P2P network and why everything is encrypted](/en/encryption).
description: What is the Wallet of NextGraph, what is its purpose, and to use it. What is the Pazzle and Mnemonic
layout: ../../layouts/MainLayout.astro
---
The first two things a new user has to do before being able to use NextGraph, is to create a Wallet and select a Broker (and register with it).
About the broker, we described in the [previous chapter](/en/encryption) about encryption, what a broker is.
You've heard of Wallets in the world of cryptocurrencies or in order to store new digital official identification documents.
A digital wallet is always used when we need to store some private encryption keys of the user. Those keys are too long and to hard to remember, so we store them in the wallet. Also, they can be many. But then, the Wallet has to be secure, and opening it needs to be protected by some password or something else that prevents unauthorized access. A wallet is also "local-first" by default, because it is something you keep on your device, and works without internet. Unlike SSO (single sign on) or OIDC that require a central server that stores users and credentials, a Wallet is much more decentralized and fits very well the needs of NextGraph.
We have designed a new wallet specially for our needs, and we have innovative features to show you!
A wallet should be unique to a physical human being. We cannot strictly enforce that, but we would like this rule to be respected, in order to simplify a bit the use cases. So we recommend each person to create only one Wallet for themselves.
Inside a Wallet, many Identities can coexist. A physical individual can create several identities for themselves inside the same wallet. By default, when the Wallet is created, a Personal identity is also created within it. That's the default identity. Then, the individual can add more identities, that will be untraceable back to the wallet, meaning that each identity is unique and has no link to the wallet or to other identities within it. When interacting with other Users, if distinct Identities are used, there will be no way to correlate those distinct Identities, even if they are stored in the same Wallet. By example, one can use the default Personal identity for friends and family, but then create another identity for their professional interactions. it will be impossible for their coworker or boss to find out what is their personal identity, and vis versa. the number of additional identities is unlimited. They are stored in the wallet and just grows the size of the wallet. This feature guarantees total anonymity and separation of Identities. In NextGraph terminology, an Identity is the same as a User.
Then we also have the concept of an Organization.
An Organization is another type of Identity. It has the same content as a Personal Identity. But in addition, it has member Users, which are Individual Identities that have been associated with the Organization, in a similar way as with email addresses at individual@organization .
An Organization can also have sub-organization, in a hierarchical manner. as in organization/sub-organization .
An Organization has Owners, and the ownership can be transferred to other Identities, while this is not the case for Individual Identities that cannot be transferred.
### Import and export
The wallet, once created on the first device where the user starts using NextGraph, stays there, on the device.
It is then possible to transfer this wallet to other devices that the user wants to use and login with.
This transfer (also called import and export of the wallet) can be done in 3 ways :
- by scanning a QR-code that is displayed on one or the other device (depending on which device has a camera)
- if no camera in any of the 2 devices, then we can use a TextCode, that needs to be passed from one device to another with existing means of transfer (like a messenger app)
- if not applicable (user doesn't want to use another messenger app), or if there is no internet, then the wallet can be transferred with a file. The file needs to be passed to the other device via USB key or USB cable connected to a mobile, by example. It is not recommended to upload the wallet file into a cloud service, as this could seriously compromise your security.
Once the wallet has arrived on a new device, everything works the same in the new device, and all the data is synced between those devices, transparently.
### Pazzle and mnemonic
In order to protect your wallet from unauthorized access, we have decided not to use a password, because that would be too risky. We know very well that users do not chose secure password by themselves, because they need to remember such password, so it has to be simple.
The other opposite behaviour is to create a very secure password with a password generator, by example, and then store this very complex password in a password/keys manager. This is another problem, as it just transfers the security of the whole system to that "password manager" that we know have been found insecure so many times. the question of the transfer of such complex password from one device to another is another problem... and we wouldn't have solved anything if we were to use password.
So.. here comes the Pazzle.
It is a contraction of Puzzle+password. Which means that it is like a puzzle that you need to reconstruct every time you want to login. And it is secure and randomly generated by us (and we do not let the user choose it).
The pazzle is composed of 9 images, that yo will most likely remember after several tries.
It is also important to memorize the order of all the images (which ones come first). This is a bit harder to remember, but a simple way to deal with it is to tell yourself a small story that links all the images one to the next. Like: the elephant east a banana and takes a plane to go play basketball with a fish, that eats blueberries under a palm tree ...etc. The story is your pazzle, and you will not be able to choose it, but the way you tell it to yourself, is your own creativity ;)
Until you remember the pazzle, you can write it down on a piece of paper. And we guarantee you that after few logins, you will know it by heart very well.
There is also a mnemonic "passphrase" that is an alternative way to login into your wallet. This is a more classical way (similar to a long password). And people using a cryptocurrency wallet must be used to those (called BIP39). But as everybody knows, those passphrases are not easy to memorize.
We propose this option for those we have special needs (like programmers that need to enter int he wallet very quickly).
in general, we encourage you to use the pazzle instead.
The mnemonic can also be seen as a recovery passphrase. But be very careful where you save it. Anybody that finds your mnemonic or pazzle, and also has a hold on the wallet file or on a device that has the wallet already imported, can surely enter your account and read/write all your data.
So the best is not to store those things on your device/computer/phone, but instead, to keep them offline, in a paper form.
We also help yo with that by providing a Recovery PDF file that contains all the information of your wallet, in a PDF form that you can print, and keep somewhere in your drawer or in a secret place.
In any case, we at Nextgraph cannot see your pazzle, mnemonic, or wallet file, as it always stays local. And we never see it passing (except when you transfer using QRcode or TextCode, but in those cases, it is re-encrypted again and only kept on our server for 5 minutes).
Now that you created your wallet and that you entered for the first time into the App, let's discover together what this App contains and [how it is organized](/en/documents).
