From 211eb72e0849108656312b73f53cfd1109a03e4e Mon Sep 17 00:00:00 2001 From: continuist Date: Wed, 20 Aug 2025 20:37:03 -0400 Subject: [PATCH] Upload files to "/" --- ...counts_sharing_encryption_plain_english.md | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 security_accounts_sharing_encryption_plain_english.md diff --git a/security_accounts_sharing_encryption_plain_english.md b/security_accounts_sharing_encryption_plain_english.md new file mode 100644 index 0000000..47fc5cc --- /dev/null +++ b/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.**