Upload files to "/"

security_accounts_sharing_encryption_plain_english.md

@@ -0,0 +1,157 @@
+# 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.**