jax-common 0.1.11

Core data structures and cryptography for JaxBucket - end-to-end encrypted P2P storage
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

//! # Principals
//!
//! Principals represent identities (public keys) with permissions on a bucket.
//!
//! Each principal has:
//! - An **identity** (Ed25519 public key)
//! - A **role** defining their access level ([`PrincipalRole`])
//!
//! ## Trust Model
//!
//! There is no cryptographic enforcement of roles. Role-based access control
//! is enforced by clients validating bucket updates against the prior state.
//! Only add principals you trust.
//!
//! ## Shares
//!
//! Principals may have an associated [`SecretShare`](crate::crypto::SecretShare)
//! allowing them to decrypt bucket content. The share is stored separately in
//! [`Share`](super::Share), not in the [`Principal`] struct itself.

use serde::{Deserialize, Serialize};

use crate::crypto::PublicKey;

/// The role of a principal on a bucket.
///
/// Roles determine what operations a principal can perform and when they
/// receive encryption access.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum PrincipalRole {
    /// Full read/write access to the bucket.
    ///
    /// Owners:
    /// - Always have an encrypted [`SecretShare`](crate::crypto::SecretShare)
    /// - Can modify bucket contents (add, remove, move files)
    /// - Can add/remove other principals
    /// - Can publish the bucket to grant mirror access
    Owner,

    /// Read-only access after publication.
    ///
    /// Mirrors:
    /// - Can sync bucket data (encrypted blobs) at any time
    /// - Cannot decrypt content until the bucket is published
    /// - Once published, read the plaintext secret from the manifest
    /// - Cannot modify bucket contents
    /// - Useful for CDN/gateway nodes that serve published content
    Mirror,
}

impl std::fmt::Display for PrincipalRole {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            PrincipalRole::Owner => write!(f, "Owner"),
            PrincipalRole::Mirror => write!(f, "Mirror"),
        }
    }
}

/// A principal identity on a bucket.
///
/// The principal struct contains the identity and role, but not the encryption
/// share. Shares are stored separately in [`Share`](super::Share) to allow
/// mirrors to exist without shares until publication.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Principal {
    /// The principal's access level.
    pub role: PrincipalRole,
    /// The principal's Ed25519 public key.
    pub identity: PublicKey,
}