common/bucket/mod.rs
1//! Bucket data structures and operations
2//!
3//! This module defines the core types for JaxBucket's encrypted, content-addressed file storage:
4//!
5//! - **[`Manifest`]**: Bucket metadata including ID, name, shares, and content-addressed pointers
6//! - **[`Node`]**: DAG structure representing directories and files
7//! - **[`Mount`]**: In-memory representation of a bucket with CRUD operations
8//! - **[`Pins`]**: Set of content hashes that should be kept available
9//! - **[`Principal`]**: Access control entries (peer identity + role)
10//!
11//! # Architecture
12//!
13//! ## Buckets as DAGs
14//!
15//! A bucket is a Directed Acyclic Graph (DAG) of encrypted nodes:
16//! ```text
17//! Manifest (unencrypted) --entry--> Root Node (encrypted)
18//! |
19//! +------------------+------------------+
20//! | | |
21//! File1 Dir Node File2
22//! (encrypted) (encrypted) (encrypted)
23//! |
24//! +-------+-------+
25//! | |
26//! File3 File4
27//! (encrypted) (encrypted)
28//! ```
29//!
30//! ## Content Addressing
31//!
32//! All nodes and files are content-addressed by their (post-encryption) hash.
33//! Links between nodes use [`Link`](crate::linked_data::Link), which includes:
34//! - Hash (BLAKE3)
35//! - Codec (DAG-CBOR for nodes, Raw for encrypted data)
36//! - Format (Raw blob or HashSeq)
37//!
38//! ## Encryption Model
39//!
40//! - Each node and file has its own encryption [`Secret`](crate::crypto::Secret)
41//! - Secrets are stored in the parent node's [`NodeLink`]
42//! - The root node's secret is shared with authorized peers via [`Share`](crate::crypto::Share)
43//! - This provides fine-grained access control and efficient key rotation
44
45mod manifest;
46mod maybe_mime;
47mod mount;
48mod node;
49mod pins;
50mod principal;
51
52pub use manifest::Manifest;
53pub use mount::{Mount, MountError};
54pub use node::{Node, NodeError, NodeLink};
55pub use pins::Pins;