docs: Add comprehensive encryption hierarchy documentation

[FSM1]

Summary

Added detailed documentation of CipherBox's encryption architecture and security model to the README, explaining the layered zero-knowledge encryption system and how user data is protected at every level.

Changes

• Key Derivation Section: Documents two paths (Web3Auth and external wallets) that produce the same VaultKey, including the HKDF-SHA256 derivation process with EIP-712 signatures
• Full Key Hierarchy Diagram: Visual representation of the encryption tree from VaultKey down through folder and file keys, showing ECIES wrapping and AES-256-GCM encryption at each level
• Encrypted vs. Visible Data Table: Clear breakdown of what's fully encrypted (file contents, names, timestamps, keys), what's visible (CIDs, IPNS names, IVs), and what's never stored (private keys, plaintext data)
• Cryptographic Primitives Table: Reference of algorithms used (AES-256-GCM, ECIES, HKDF-SHA256, Ed25519) with their parameters
• File Upload Flow Diagram: Step-by-step visualization of the complete upload process from file selection through IPNS publication
• Defense in Depth Section: Illustrates the nested protection layers around file content
• Attacker Perspective Section: Explains what an attacker with full IPFS/server access but no private key can and cannot access

Implementation Details

• All diagrams use ASCII art for clarity and version control compatibility
• Documentation emphasizes that all encryption happens client-side before data leaves the device
• Clearly distinguishes between deterministic key derivation (VaultKey) and random key generation (file/folder keys)
• Explains why certain data must remain visible (IPFS/IPNS protocol requirements) while maintaining zero-knowledge guarantees

https://claude.ai/code/session_01F3BPoeiGAEArBqMFkKB16W

Summary by CodeRabbit

• Documentation
  • Added comprehensive "Encryption Hierarchy" documentation detailing key derivation, multi-layer file and folder encryption, data visibility controls, cryptographic primitives used, and core security architecture design decisions to help users understand data protection mechanisms.

[coderabbitai]

Walkthrough

Added a comprehensive "Encryption Hierarchy" section to README.md documenting client-side zero-knowledge encryption, key derivation flows (Web3Auth and external wallet paths), vault structure, cryptographic primitives, file upload flows, defense-in-depth mechanisms, and six key design decisions related to encryption topology.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added detailed "Encryption Hierarchy" section covering dual-path key derivation, ECIES-based wrapping, per-file/folder encryption layers, visibility rules, cryptographic primitives, E2E upload flows, attacker visibility scenarios, and design decisions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: add comprehensive environment architecture for multi-env isolation #49: Directly implements the key-management and cryptographic flows (Web3Auth/external wallet key derivation, ECIES wrapping, IPNS/TEE usage) that are now being documented.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: Add comprehensive encryption hierarchy documentation' accurately reflects the main change—adding detailed documentation about the encryption architecture to the README.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/document-encryption-hierarchy-fzYlH

---

No actionable comments were generated in the recent review. 🎉

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}