← Open Nook

How Nook works

Nook is a chat app with text, voice, camera and screen share, like Discord. Each device encrypts everything before it sends it. The servers keep and pass on data that they cannot read.

The parts

Part	What it does
The page	The app in your browser, the desktop app, or the phone home screen. All encryption happens here.
A server	It stores encrypted messages and files, and passes them on. Anybody can run one with Docker.
A cluster	Several servers that keep copies of the same spaces. If one server stops, the app moves to the next one.

Spaces and invites

A space is a group. It has text channels, voice channels, notes and people.

A space is a code, such as K7M2-9QPT-VB2W. The code is also the key that opens the messages. The invite link puts the code after the #. A browser never sends that part to a server, so the server never sees the code.

Important: anybody with the invite link can join and read the space. Give the link only to people you trust.

Features

Text channels, with replies, reactions, pins, edits, search, emoji and GIFs.
Direct messages. Home shows them from all of your spaces.
Files, pictures and videos, up to 100 MB each.
Voice channels, with mute, deafen, noise removal, and a volume for each person.
Camera in voice channels and calls.
Screen share from a voice channel, up to 1080p.
One-to-one calls from a direct message.
Levels (Owner, Admin, Moderator, Member, and your own levels) that control who can do what.
Remove and ban people.
Notes, a soundboard, and a status (Online, Idle, Do not disturb, Invisible).
Notifications, also when Nook is closed (in a browser).
Webhooks that take the same format as Discord webhooks.
Desktop app only: game activity, a window picker, and clips from game recordings.
Link a new device with a QR code, or save a backup file.

Your identity

Your device makes a secret key the first time you open Nook. This key is "you". It signs everything that you write. Every other device checks each signature. Thus a server cannot change a message or write a fake message in your name.

The key is on your devices only. If you lose all your devices and you have no backup, you lose the account.

Caution: anybody with your backup file can be you. Keep the file in a private place, and use a password.

How a message travels

You write a message.
Your device signs it with your identity key.
Your device encrypts it with the space key (AES-GCM).
The server stores the encrypted message and sends it to the others.
Each device decrypts the message and checks the signature.

What is encrypted

What	How	Who can read it
Messages, edits, reactions, names, channels	AES-GCM, with a key made from the space code	People with the invite. After a removal, only the people still in the space.
Direct messages	Also a key that only the two people share	The two people
Files	AES-GCM, a new key for each file, sent inside the message	People who can read that message
Typing, presence, call setup	The space key, and signed	People in the space
Your list of spaces, read marks, settings	A key made from your identity	Only your devices
Notifications when Nook is closed	Web Push encryption, made by the device of the sender	Only your browser
Voice, camera, screen share	DTLS-SRTP, between the browsers	The people in the call

What is not secret

The server must see some data to do its work:

Which spaces exist, and how big they are. The space ID is a hash, so it does not show the code.
How many files a space has, and the size of each file.
Who connects, from which IP address, at what time, and how much data they send.
Which links people share, if link previews are on. The server owner can set NOOK_PREVIEWS=0 to stop this.
What people search for in GIF search.
When a device gets a push notification. The server does not see the sender or the text.

Some features have limits:

Webhooks: the server reads a webhook message while it posts it. It stores only the encrypted copy.
Notes for some levels only: these notes are hidden, but they use the normal space key. A changed app in the hands of a space member can read them.
Old messages after a removal: a removed person keeps the messages that they read before. Nook cannot take those back.

Removals and bans

When an admin removes a person, the device of the admin makes a new space key at once. It sends a copy of the key to each person who stays. Nobody has to click anything. The removed person cannot read new messages.

The removed person can still join again with the old code, as a new person. A ban stops this. After a ban, a new invite needs a pass, and the old code alone does not let anybody in.

Voice, calls and screen share

Nook has no media server. Sound and video go from browser to browser with WebRTC.

Voice channel: each person connects to each other person in the channel. Each person sends their voice to every other person. One channel can hold about 48 people.
Call: a call is a private voice channel for two people. You start it with the phone button in a direct message, and it rings the other person.
Camera: in a voice channel or a call, each camera is a small tile above the chat.
Screen share: the person who shares sends one video stream to each viewer. A viewer must pick a share to see it.

The setup messages for a call are encrypted and signed. So a server cannot step into the middle of a call.

TURN relay: by default, all sound and video go through the TURN relay of the server. This hides the IP address of each person from the others. The relay cannot decrypt the media. A server owner can set NOOK_TURN_ONLY=0 to try a direct connection first.

Voice and screen share continue if the server restarts, because the media goes between the browsers.

Where data is kept

What	Where
Messages, channels, levels	Postgres on the server, and on every server of the cluster, encrypted
Files	The disk of the server, encrypted
Your identity key	Your devices only
Voice and video	Nowhere. Nook does not record calls.