eidetica/auth/types/

keys.rs

//! Key management types for authentication
//!
//! This module defines types related to authentication keys, signatures,
//! and key resolution.

use serde::{Deserialize, Serialize};

use super::permissions::{KeyStatus, Permission};
use crate::auth::crypto::PublicKey;
use crate::crdt::{CRDTError, Doc, doc::Value};
use crate::entry::ID;

/// Authentication key configuration stored in _settings.auth
///
/// Keys are indexed by pubkey in AuthSettings. The name field is optional
/// metadata that can be used as a hint in signatures.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AuthKey {
    /// Optional human-readable name for this key
    /// Multiple keys can share the same name (aliases)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Permission level for this key
    permissions: Permission,
    /// Current status of the key
    status: KeyStatus,
}

impl AuthKey {
    /// Create a new AuthKey with validation
    ///
    /// # Arguments
    /// * `name` - Optional human-readable name for this key
    /// * `permissions` - Permission level for this key
    /// * `status` - Current status of the key
    ///
    /// # Examples
    /// ```
    /// use eidetica::auth::types::{AuthKey, Permission, KeyStatus};
    ///
    /// let key = AuthKey::new(
    ///     Some("alice_laptop"),
    ///     Permission::Write(10),
    ///     KeyStatus::Active
    /// );
    /// ```
    pub fn new(name: Option<&str>, permissions: Permission, status: KeyStatus) -> Self {
        Self {
            name: name.map(|n| n.to_owned()),
            permissions,
            status,
        }
    }

    /// Create a new active AuthKey (common case)
    ///
    /// # Arguments
    /// * `name` - Optional human-readable name for this key
    /// * `permissions` - Permission level for this key
    ///
    /// # Examples
    /// ```
    /// use eidetica::auth::types::{AuthKey, Permission};
    ///
    /// let key = AuthKey::active(
    ///     Some("alice_laptop"),
    ///     Permission::Admin(1)
    /// );
    /// ```
    pub fn active(name: Option<&str>, permissions: Permission) -> Self {
        Self::new(name, permissions, KeyStatus::Active)
    }

    /// Get the optional name
    pub fn name(&self) -> Option<&str> {
        self.name.as_deref()
    }

    /// Get the permissions
    pub fn permissions(&self) -> &Permission {
        &self.permissions
    }

    /// Get the status
    pub fn status(&self) -> &KeyStatus {
        &self.status
    }

    /// Whether this key currently grants access.
    ///
    /// The single definition of "usable key" at the settings layer — mirror of
    /// [`ResolvedAuth::grants_access`]. Callers deciding access must gate on
    /// this rather than re-checking `status` inline, so revocation is honoured
    /// identically on every path.
    pub fn is_active(&self) -> bool {
        self.status == KeyStatus::Active
    }

    /// Set the status (e.g., for revocation)
    pub fn set_status(&mut self, status: KeyStatus) {
        self.status = status;
    }

    /// Set the permissions (e.g., for updates)
    pub fn set_permissions(&mut self, permissions: Permission) {
        self.permissions = permissions;
    }

    /// Set the name
    pub fn set_name(&mut self, name: Option<&str>) {
        self.name = name.map(|s| s.to_owned());
    }
}

// ==================== Doc Conversions ====================

impl From<AuthKey> for Value {
    fn from(key: AuthKey) -> Value {
        Value::Doc(Doc::from(key))
    }
}

impl From<AuthKey> for Doc {
    fn from(key: AuthKey) -> Doc {
        // An AuthKey needs to be atomic, no partial merging.
        let mut doc = Doc::atomic();
        if let Some(name) = key.name {
            doc.set("name", name);
        }
        doc.set("permissions", key.permissions);
        let status_str = match key.status {
            KeyStatus::Active => "Active",
            KeyStatus::Revoked => "Revoked",
        };
        doc.set("status", status_str);
        doc
    }
}

impl TryFrom<&Doc> for AuthKey {
    type Error = crate::Error;

    fn try_from(doc: &Doc) -> crate::Result<Self> {
        let name: Option<String> = doc.get_as::<&str>("name").map(String::from);

        let perm_doc = match doc.get("permissions") {
            Some(Value::Doc(d)) => d,
            _ => {
                return Err(CRDTError::ElementNotFound {
                    key: "permissions".to_string(),
                }
                .into());
            }
        };
        let permissions = Permission::try_from(perm_doc)?;

        let status_str =
            doc.get_as::<&str>("status")
                .ok_or_else(|| CRDTError::ElementNotFound {
                    key: "status".to_string(),
                })?;
        let status = match status_str {
            "Active" => KeyStatus::Active,
            "Revoked" => KeyStatus::Revoked,
            other => {
                return Err(CRDTError::DeserializationFailed {
                    reason: format!("unknown KeyStatus: {other}"),
                }
                .into());
            }
        };

        Ok(AuthKey {
            name,
            permissions,
            status,
        })
    }
}

/// Step in a delegation path
///
/// References a delegated tree by its root entry ID. The final signer hint is stored
/// in the parent SigKey, not in the DelegationStep.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DelegationStep {
    /// Root entry ID of the delegated tree (used to look up the delegation in AuthSettings)
    pub tree: ID,
    /// Tips of the delegated tree at time of signing
    pub tips: Vec<ID>,
}

fn is_false(v: &bool) -> bool {
    !v
}

/// Key hint for resolving the signer
///
/// Contains explicit fields for each hint type. Exactly one hint field
/// should be set. The hint is used to look up the actual public key
/// in AuthSettings for signature verification.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct KeyHint {
    /// Public key hint (e.g. Ed25519 verifying key)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pubkey: Option<PublicKey>,
    /// Name hint: "alice_laptop" - searches keys where name matches
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Whether this hint refers to the global permission
    #[serde(default, skip_serializing_if = "is_false")]
    pub is_global: bool,
    // TODO: Fingerprint hint (future): "7F8A9B3C..." - matches hash of pubkey
    // This is used in other systems and may be a better option than matching/revealing
    // the full pubkey
    // #[serde(skip_serializing_if = "Option::is_none")]
    // pub fingerprint: Option<String>,
}

impl KeyHint {
    /// Create a hint from a public key
    pub fn from_pubkey(pubkey: &PublicKey) -> Self {
        Self {
            pubkey: Some(pubkey.clone()),
            name: None,
            is_global: false,
        }
    }

    /// Create a hint from a name
    pub fn from_name(name: impl Into<String>) -> Self {
        Self {
            pubkey: None,
            name: Some(name.into()),
            is_global: false,
        }
    }

    /// Create a global permission hint with actual signer pubkey
    pub fn global(actual_pubkey: &PublicKey) -> Self {
        Self {
            pubkey: Some(actual_pubkey.clone()),
            name: None,
            is_global: true,
        }
    }

    /// Check if this is a global permission hint
    pub fn is_global(&self) -> bool {
        self.is_global
    }

    /// Check if any hint field is set
    ///
    /// Returns `true` if at least one of `pubkey`, `name`, or `is_global` is set.
    ///
    /// # Unsigned Entry Detection
    ///
    /// This method is primarily used to detect **unsigned entries** during validation.
    /// An entry is considered unsigned when:
    /// - The `SigKey` is `Direct` with an empty hint (`!hint.is_set()`)
    /// - The signature field is `None`
    ///
    /// This allows databases to operate without authentication when no auth keys are
    /// configured, supporting both authenticated and unauthenticated use cases.
    ///
    /// ```
    /// # use eidetica::auth::types::KeyHint;
    /// # use eidetica::auth::crypto::PrivateKey;
    /// // Empty hint - represents an unsigned entry when combined with no signature
    /// let empty = KeyHint::default();
    /// assert!(!empty.is_set());
    ///
    /// // Hint with pubkey - this entry requires signature verification
    /// let pubkey = PrivateKey::generate().public_key();
    /// let with_pubkey = KeyHint::from_pubkey(&pubkey);
    /// assert!(with_pubkey.is_set());
    ///
    /// // Hint with name only - also requires signature verification
    /// let with_name = KeyHint::from_name("alice_laptop");
    /// assert!(with_name.is_set());
    /// ```
    pub fn is_set(&self) -> bool {
        self.pubkey.is_some() || self.name.is_some() || (self.is_global && self.pubkey.is_some())
    }

    /// Get the hint type as a string (for error messages)
    pub fn hint_type(&self) -> &'static str {
        if self.is_global && self.pubkey.is_some() {
            "global"
        } else if self.pubkey.is_some() {
            "pubkey"
        } else if self.name.is_some() {
            "name"
        } else {
            "none"
        }
    }
}

/// Authentication key identifier for entry signing
///
/// Represents the path to resolve the signing key, either directly or through delegation.
/// Uses explicit hint fields to point to the signer's public key.
///
/// # Serialization Format
///
/// Uses externally tagged serialization (serde default):
/// - Direct: `{"Direct": {"pubkey": "ed25519:..."}}`
/// - Delegation: `{"Delegation": {"path": [...], "hint": {...}}}`
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum SigKey {
    /// Direct reference to a key in the current tree's _settings.auth
    Direct {
        /// Key hint for resolving the signer
        hint: KeyHint,
    },
    /// Delegation path through other trees
    Delegation {
        /// Path of delegation steps (tree references)
        path: Vec<DelegationStep>,
        /// Final signer hint (resolved in last delegated tree's auth)
        hint: KeyHint,
    },
}

impl Default for SigKey {
    fn default() -> Self {
        SigKey::Direct {
            hint: KeyHint::default(),
        }
    }
}

impl SigKey {
    /// Create a direct key reference from a pubkey
    pub fn from_pubkey(pubkey: &PublicKey) -> Self {
        SigKey::Direct {
            hint: KeyHint::from_pubkey(pubkey),
        }
    }

    /// Create a direct key reference from a name
    pub fn from_name(name: impl Into<String>) -> Self {
        SigKey::Direct {
            hint: KeyHint::from_name(name),
        }
    }

    /// Create a global permission key with actual signer pubkey
    pub fn global(actual_pubkey: &PublicKey) -> Self {
        SigKey::Direct {
            hint: KeyHint::global(actual_pubkey),
        }
    }

    /// Get the key hint (for both Direct and Delegation variants)
    pub fn hint(&self) -> &KeyHint {
        match self {
            SigKey::Direct { hint } => hint,
            SigKey::Delegation { hint, .. } => hint,
        }
    }

    /// Get mutable reference to the key hint
    pub fn hint_mut(&mut self) -> &mut KeyHint {
        match self {
            SigKey::Direct { hint } => hint,
            SigKey::Delegation { hint, .. } => hint,
        }
    }

    /// Check if this is a global permission key
    pub fn is_global(&self) -> bool {
        self.hint().is_global()
    }

    /// Human-readable identifier string for display and audit trails.
    ///
    /// Returns `"*"` for global, the pubkey string for pubkey-based,
    /// the name for name-based, or `"unknown"` if no hint is set.
    pub fn display_id(&self) -> String {
        let hint = self.hint();
        if hint.is_global() {
            "*".to_string()
        } else if let Some(pubkey) = &hint.pubkey {
            pubkey.to_string()
        } else if let Some(name) = &hint.name {
            name.clone()
        } else {
            "unknown".to_string()
        }
    }

    /// Check if this SigKey uses a specific pubkey hint
    pub fn has_pubkey_hint(&self, pubkey: &PublicKey) -> bool {
        self.hint().pubkey.as_ref() == Some(pubkey)
    }

    /// Check if this SigKey uses a specific name hint
    pub fn has_name_hint(&self, name: &str) -> bool {
        self.hint().name.as_deref() == Some(name)
    }
}

/// Authentication information embedded in an entry
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct AuthInfo {
    /// Authentication signature - base64-encoded signature bytes
    /// Optional to allow for entry creation before signing
    ///
    /// Serialized as `sig` to keep the wire format, and therefore every existing
    /// entry ID, unchanged.
    #[serde(rename = "sig", skip_serializing_if = "Option::is_none")]
    pub signature: Option<String>,
    /// Key lookup hint
    pub key: SigKey,
}

impl AuthInfo {
    /// Create a new AuthInfo with a pubkey hint
    pub fn from_pubkey(pubkey: &PublicKey) -> Self {
        Self {
            signature: None,
            key: SigKey::from_pubkey(pubkey),
        }
    }

    /// Create a new AuthInfo with a name hint
    pub fn from_name(name: impl Into<String>) -> Self {
        Self {
            signature: None,
            key: SigKey::from_name(name),
        }
    }

    /// Create a new AuthInfo for global permission
    pub fn global(actual_pubkey: &PublicKey) -> Self {
        Self {
            signature: None,
            key: SigKey::global(actual_pubkey),
        }
    }

    /// Check if this is a global permission signature
    pub fn is_global(&self) -> bool {
        self.key.is_global()
    }

    /// Get the key hint
    pub fn hint(&self) -> &KeyHint {
        self.key.hint()
    }

    /// Create a new AuthInfoBuilder for constructing AuthInfo instances
    pub fn builder() -> AuthInfoBuilder {
        AuthInfoBuilder::new()
    }

    /// Check if this represents an unsigned/unauthenticated entry.
    ///
    /// An entry is unsigned when `AuthInfo` is in its default state:
    /// - Direct SigKey (not Delegation)
    /// - Empty KeyHint (no pubkey, no name)
    /// - No signature
    pub fn is_unsigned(&self) -> bool {
        matches!(self.key, SigKey::Direct { ref hint } if !hint.is_set())
            && self.signature.is_none()
    }

    /// Check if this represents a malformed/inconsistent signature state.
    ///
    /// Returns `Some(reason)` if malformed, `None` if valid.
    ///
    /// Malformed states:
    /// - Direct with hint but no signature (can't verify without signature)
    /// - Direct with signature but no hint (can't verify without knowing which key)
    /// - Delegation with no signature (delegation always requires signature)
    pub fn malformed_reason(&self) -> Option<&'static str> {
        match &self.key {
            SigKey::Direct { hint } => {
                if hint.is_set() && self.signature.is_none() {
                    Some("entry has key hint but no signature")
                } else if !hint.is_set() && self.signature.is_some() {
                    Some("entry has signature but no key hint")
                } else {
                    None
                }
            }
            SigKey::Delegation { .. } => {
                if self.signature.is_none() {
                    Some("delegation entry requires a signature")
                } else {
                    None
                }
            }
        }
    }
}

/// Builder for constructing AuthInfo instances
///
/// This builder provides a fluent interface for creating AuthInfo objects.
#[derive(Debug, Clone, Default)]
pub struct AuthInfoBuilder {
    signature: Option<String>,
    key: Option<SigKey>,
}

impl AuthInfoBuilder {
    /// Create a new empty AuthInfoBuilder
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the signature (base64-encoded signature bytes)
    pub fn signature(mut self, signature: impl Into<String>) -> Self {
        self.signature = Some(signature.into());
        self
    }

    /// Set the authentication key reference
    pub fn key(mut self, key: SigKey) -> Self {
        self.key = Some(key);
        self
    }

    /// Set a pubkey hint
    pub fn pubkey_hint(mut self, pubkey: &PublicKey) -> Self {
        self.key = Some(SigKey::from_pubkey(pubkey));
        self
    }

    /// Set a name hint
    pub fn name_hint(mut self, name: impl Into<String>) -> Self {
        self.key = Some(SigKey::from_name(name));
        self
    }

    /// Set a global permission hint with actual signer pubkey
    pub fn global_hint(mut self, actual_pubkey: &PublicKey) -> Self {
        self.key = Some(SigKey::global(actual_pubkey));
        self
    }

    /// Build the final AuthInfo instance
    ///
    /// # Panics
    /// Panics if key is not set, as it's a required field.
    pub fn build(self) -> AuthInfo {
        AuthInfo {
            signature: self.signature,
            key: self.key.expect("key is required for AuthInfo"),
        }
    }
}

/// Resolved authentication information after validation
#[derive(Debug, Clone)]
pub struct ResolvedAuth {
    /// The actual public key used for signing
    pub public_key: PublicKey,
    /// Effective permission after clamping
    pub effective_permission: Permission,
    /// Current status of the key
    pub key_status: KeyStatus,
}

impl ResolvedAuth {
    /// Whether this resolved key may currently be used to authorize access.
    ///
    /// The single definition of "usable key" for every auth path — resolvers
    /// return candidates regardless of status, so each consumer that turns
    /// candidates into an access decision must gate on this, not re-check
    /// `key_status` inline.
    pub fn grants_access(&self) -> bool {
        self.key_status == KeyStatus::Active
    }
}