157 lines
6.7 KiB
Markdown
157 lines
6.7 KiB
Markdown
# 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.**
|