citadel_proto 0.13.0

Networking library for the Citadel Protocol
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

//! Authentication Request Types for Citadel Protocol
//!
//! This module defines the authentication request types and structures used for establishing
//! connections in the Citadel Protocol. It supports both credential-based and passwordless
//! authentication methods.
//!
//! # Features
//! - **Credential Authentication**: Username/password-based authentication
//! - **Passwordless Authentication**: Device-based transient connections
//! - **Secure Credential Handling**: Uses SecBuffer for password protection
//! - **User Identification**: Supports both CID and username-based identification
//! - **Server Address Management**: Handles server connection information
//!
//! # Usage Example
//! ```rust
//! use citadel_proto::auth::AuthenticationRequest;
//! use citadel_types::user::UserIdentifier;
//! use citadel_types::crypto::SecBuffer;
//! use std::net::SocketAddr;
//! use uuid::Uuid;
//!
//! // Credential-based authentication
//! let cred_auth = AuthenticationRequest::credentialed(
//!     UserIdentifier::from("username"),
//!     SecBuffer::from("password")
//! );
//!
//! // Passwordless authentication
//! let server_addr: SocketAddr = "127.0.0.1:8080".parse().unwrap();
//! let uuid = Uuid::new_v4();
//! let transient_auth = AuthenticationRequest::transient(uuid, server_addr);
//! ```
//!
//! # Important Notes
//! - Passwords are always handled using SecBuffer for secure memory management
//! - Transient connections use device-specific cryptographic bundles
//! - CID extraction is only available for credential-based authentication
//! - Server addresses are required for passwordless authentication
//!
//! # Related Components
//! - `citadel_types::crypto::SecBuffer`: Secure credential storage
//! - `citadel_types::user::UserIdentifier`: User identification types
//! - `proto::packet_processor::connect_packet`: Connection handling
//! - `proto::validation`: Authentication validation
//!

use citadel_types::crypto::SecBuffer;
use citadel_types::user::UserIdentifier;
use serde::{Deserialize, Serialize};
use std::net::SocketAddr;
use uuid::Uuid;

/// Arguments for connecting to a node
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum AuthenticationRequest {
    /// Credentials used for the connection
    Credentialed {
        id: UserIdentifier,
        password: SecBuffer,
    },
    /// No credentials/one-time connection
    Passwordless {
        username: String,
        server_addr: SocketAddr,
    },
}

impl AuthenticationRequest {
    /// Credentials used for connecting (registration implied to have occurred)
    pub fn credentialed<T: Into<UserIdentifier>, V: Into<SecBuffer>>(id: T, password: V) -> Self {
        Self::Credentialed {
            id: id.into(),
            password: password.into(),
        }
    }

    /// No credentials will be used for login, only a one-time device-dependent cryptographic bundle
    pub fn transient(uuid: Uuid, server_addr: SocketAddr) -> Self {
        Self::Passwordless {
            username: uuid.to_string(),
            server_addr,
        }
    }

    pub fn session_cid(&self) -> Option<u64> {
        match self {
            AuthenticationRequest::Credentialed { id, .. } => {
                if let UserIdentifier::ID(cid) = id {
                    Some(*cid)
                } else {
                    None
                }
            }
            _ => None,
        }
    }
}