6.7 KiB
6.7 KiB
Plain-English Overview: Security, Accounts, Sharing, and Encryption
This document explains—in simple language—how the system keeps data safe, how accounts work without email, how sharing is controlled, and how encryption is used.
1) Big picture
- Every person and every node (a server that hosts data) has its own Passport.
- A Passport is just a set of cryptographic keys that prove who you are, plus a written paper backup that lets you recover if you lose your device.
- Data items live in categories (each category has its own fields).
- Each item is always encrypted at rest, and signed so others can check it hasn’t been tampered with.
- Sharing is controlled by rules (who can view/edit), and by keys (who can decrypt).
- Nodes can connect to other nodes and federate (share items between them) while still enforcing the same rules.
2) Accounts without email (Passports)
- You don’t sign up with an email address. You create a Passport on your device.
- The Passport gives you a public ID and a private key.
- The public ID is safe to share; it’s how others recognize you.
- The private key stays on your device; it lets you sign and decrypt.
- On day one you receive a 24‑word recovery phrase (your “paper backup”).
- If you lose your device, you can recreate your Passport using those 24 words.
- Keep them offline and secret (write them down).
Logging in
- When you “log in” to a node, you simply prove you control your Passport by signing a small challenge. No email codes are involved.
3) What a node is responsible for
- Storing encrypted items and their metadata.
- Checking who is allowed to access a specific item right now.
- Handing out short‑lived decryption keys to allowed users.
- Keeping audit logs of who asked for access.
- Talking to other nodes securely (mutual TLS or onion) for federation.
4) Data items and visibility
Each item has a visibility setting and sharing rules:
- Public / Discoverable: Anyone can find it and request a short‑lived key.
- Node / Group / Direct: Only the people or nodes you name can get a key.
- You can change visibility at any time (e.g., make a public item private later).
Important: If someone already saved a copy of the plaintext while it was public, you can’t make them “un‑see” it. The system prevents future viewers from getting new keys.
5) Signatures (authenticity)
- When you create or update an item, your device signs it with your Passport.
- Anyone who sees the item can check the signature and know who wrote it and that it wasn’t altered.
6) Encryption (confidentiality)
- Every item is encrypted at rest on the node. The node stores only ciphertext (unreadable without a key).
- Encryption uses a fresh data‑encryption key (DEK) per item version.
- For large items, the content is split into chunks with their own small keys and a tiny key list so that privacy updates don’t require re‑encrypting the whole file.
Key grants (how someone actually decrypts):
- You ask to read an item.
- The node checks the sharing rules (are you allowed?).
- If allowed, the node gives you a short‑lived “key grant”—a small sealed packet that contains the decryption key for this item/version.
- Your app uses that key to decrypt the ciphertext it downloads.
- Key grants expire quickly (minutes). If your access is revoked, new grants are refused.
7) Making a public item private (revocation in practice)
- Flip the item to private.
- The node rotates the key (generates a new DEK) and bumps the version.
- From that point on, only authorized people can get a new key grant.
- Search indexes and other nodes remove the item from public listings.
Anyone who already saw the plaintext keeps their old copy. Everyone else will be blocked going forward because they won’t receive a valid key for the new version.
8) Sharing and access control (who can do what)
- Sharing rules are recorded as small relations like: “
item 123hasviewer=Alice”, or “any member of Node X can view Category Y”. - The node answers questions like “Can Bob view item 123?” by walking those relations.
- Rules can include conditions like “only after this date” or “only if it’s marked discoverable”.
Two layers work together:
- Rules decide who is allowed.
- Keys make sure only allowed people can decrypt.
9) Federation between nodes
- Items can be shared across nodes.
- Private items are shared as ciphertext + a pointer to the authority node that decides access.
- A receiving node (or user) can always find where to ask for permission and a key grant.
- Nodes cache answers for a short time but don’t need to store everyone’s rules forever.
10) Transport security
- Nodes talk to each other over mutual TLS (both sides prove who they are) or via onion addresses.
- This protects against snooping and imposters on the network.
11) What happens on write vs. read
When you create or edit an item:
- Your app validates the item against the category’s schema.
- It signs the item with your Passport.
- The node encrypts the content, stores it, updates the sharing rules, and (if public) adds it to search.
When someone reads an item:
- Node checks the sharing rules.
- If allowed, it issues a short‑lived key grant.
- The client downloads the ciphertext and decrypts locally.
12) Recovery if you lose your device
- Use your 24‑word paper backup to regenerate your Passport.
- Tell the node to rotate your device key. Old devices are revoked; your identity remains the same.
13) Limits (being honest)
- The system cannot delete copies that someone already saved while they had access.
- “Public” should be treated as irreversible for people who already saw it.
- Revocation stops future first‑time viewers, not past ones.
14) Why this works on a tiny $5/mo server
- Crypto operations are fast and lightweight.
- Key grants are tiny and short‑lived.
- Most cost is disk and network I/O, which you’d have anyway.
- Everything runs as a single Rust service with an embedded database and search index.
One‑sentence summary
Sign everything, encrypt everything, decide access at read time, hand out tiny short‑lived keys only to people who are allowed, and make “public” just a policy that you can change later.