Who can read what
This page explains which peers can read and write each kind of data on your server, and what you, as the operator, can see of it.
Identity behind every check
Section titled “Identity behind every check”Every connection is authenticated by the Noise handshake, so the server knows which peer ID is on the other end. Every access check uses that peer ID. Nothing in a request can claim to be another peer.
The model
Section titled “The model”Every store but the directory uses the same three levels of visibility:
- private: only the owner can read it.
- shared: the owner and the peers on its reader list can read it.
- public: any peer can read it.
Writes belong to the owner, with the exceptions in the table.
| Store | Default | Readable by | Writable by |
|---|---|---|---|
| Mailboxes | private | Private: owner only. Shared: owner and peers on the ACL. Public: any peer. | Private: any peer can deliver to it. Shared and public: the owner, and peers with a write grant on the ACL. |
| Documents | private | Per document, with every stored version | Owner only |
| Feeds | public | Per feed, with every entry | Owner only, except that any peer may append to a feed its owner made collaborative |
| Collections | private | Per collection, with every item and query result | Owner only |
| Directory | public | Any peer can browse and search every listing | Each peer joins, updates and leaves only its own listing |
Mailboxes
Section titled “Mailboxes”A private mailbox is an open inbox: any peer that knows the owner’s peer ID and the folder name can deliver to it, and only the owner can read it. A message to a folder that does not exist yet creates it as a private mailbox. Shared and public mailboxes check the sender against the ACL; a sender without a write grant is refused.
A mailbox’s type is fixed when it is created and never changes. Reading never creates a mailbox: a peer reading a folder that does not exist and is not its own gets a 404.
Since identities are free, anyone can fill an open inbox up to its message cap. Where that matters, use a shared mailbox with an ACL. See Storage, quotas & retention for the caps and Mailboxes & ACLs for the client side.
Documents, feeds and collections
Section titled “Documents, feeds and collections”Visibility is set when the resource is created and changed later by its owner. A grant to a reader is kept while the resource is private and applies once it is shared, as with a mailbox ACL.
Visibility applies to the resource as a whole. Making a document public publishes its retained history too. Making a feed private hides entries a peer has already read.
A listing shows a caller only what it may read. A refused read is a 403, like a refused write, so a peer that guesses a path learns that it exists and nothing more.
What the server can see
Section titled “What the server can see”Documents, feeds, collections and the directory
Section titled “Documents, feeds, collections and the directory”The server stores these exactly as sent and never encrypts them. Visibility is enforced by the server’s checks, not by a key. Anyone with access to the database, or to a stolen copy of its volume, can read everything.
If your deployment needs protection at rest, encrypt the database volume or use PostgreSQL transparent data encryption. A client that must keep a document from the server itself has to encrypt it before storing it; the path, size, content type and version count still stay visible.
Messages
Section titled “Messages”Clients can encrypt message payloads end to end with NaCl box (X25519 key agreement derived from the Ed25519 identity keys, XSalsa20-Poly1305). Encryption is the client’s choice, per message. When a client uses it:
- The payload is unreadable to the server and the network. Only the recipient’s identity key opens it.
- The envelope is not encrypted. Sender, recipient, folder path, timestamps, priority and flags are visible to the server and stored in the database in the clear.
- There is no forward secrecy. The keys are the long-term identity keys. A later compromise of either party’s key decrypts everything they exchanged. Applications that need forward secrecy run a ratcheting protocol over these messages.
- Placement is bound. The ciphertext is bound to the recipient, folder and message ID, so it cannot be replayed into another folder or under another ID. A verbatim replay of the same message is not detected.
- It is deniable, not signed. The recipient knows who sent a message but cannot prove it to a third party.
The server’s own identity key plays no part in payload encryption. See Encryption & compression for the client side.
What you see through the ops view
Section titled “What you see through the ops view”The /ops/* endpoints list mailboxes by owner peer ID, with message counts and byte totals. They do not return
payloads, but they disclose who stores how much. Keep the ops listener on loopback. See
Metrics & the ops view.
Restricting who can connect
Section titled “Restricting who can connect”The model above governs what a connected peer can do. To control who can connect at all, turn on authentication and list the allowed peers. See Trusted peers.