# 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):** 1. You ask to read an item. 2. The node checks the **sharing rules** (are you allowed?). 3. If allowed, the node gives you a **short‑lived “key grant”**—a small sealed packet that contains the decryption key for this item/version. 4. 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 123` has `viewer` = `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:** 1. Your app validates the item against the category’s schema. 2. It **signs** the item with your Passport. 3. The node encrypts the content, stores it, updates the sharing rules, and (if public) adds it to search. **When someone reads an item:** 1. Node checks the sharing rules. 2. If allowed, it issues a **short‑lived key grant**. 3. 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.**