auth-framework 0.5.0-rc18

//! OpenID Connect Back-Channel Logout Implementation
//!
//! This module implements the "OpenID Connect Back-Channel Logout 1.0" specification,
//! which allows OpenID Providers to notify Relying Parties about logout events through
//! back-channel (server-to-server) communication using JWT-based logout tokens.
//!
//! # Features
//!
//! - Back-channel logout token generation and validation
//! - Server-to-server HTTP POST notifications
//! - JWT-based logout token with standard claims
//! - Asynchronous RP notification with retry logic
//! - Integration with front-channel and RP-initiated logout

use crate::errors::{AuthError, Result};
use crate::server::oidc::oidc_session_management::{OidcSession, SessionManager};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::time::SystemTime;
use tokio::time::Duration;
use uuid::Uuid;

/// Back-channel logout request parameters
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BackChannelLogoutRequest {
    /// Session ID being logged out
    pub session_id: String,
    /// Subject identifier
    pub sub: String,
    /// Session identifier (sid) claim value
    pub sid: Option<String>,
    /// Issuer identifier
    pub iss: String,
    /// Initiating client ID (if logout was client-initiated)
    pub initiating_client_id: Option<String>,
    /// Additional events to include in logout token
    pub additional_events: Option<HashMap<String, serde_json::Value>>,
}

/// Back-channel logout response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BackChannelLogoutResponse {
    /// Whether logout notifications were sent successfully
    pub success: bool,
    /// Number of RPs notified
    pub notified_rps: usize,
    /// List of RPs that were notified successfully
    pub successful_notifications: Vec<NotificationResult>,
    /// List of RPs that failed to be notified
    pub failed_notifications: Vec<FailedNotification>,
    /// Generated logout token (for debugging/logging)
    pub logout_token_jti: String,
}

/// Successful notification result
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NotificationResult {
    /// Client ID that was notified
    pub client_id: String,
    /// Back-channel logout URI used
    pub backchannel_logout_uri: String,
    /// Whether the notification was successful
    pub success: bool,
    /// HTTP status code received
    pub status_code: Option<u16>,
    /// Number of retry attempts made
    pub retry_attempts: u32,
    /// Response time in milliseconds
    pub response_time_ms: u64,
}

/// Failed notification information
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FailedNotification {
    /// Client ID that failed
    pub client_id: String,
    /// Back-channel logout URI that failed
    pub backchannel_logout_uri: String,
    /// Error description
    pub error: String,
    /// HTTP status code if available
    pub status_code: Option<u16>,
    /// Number of retry attempts made
    pub retry_attempts: u32,
}

/// Back-channel logout configuration
#[derive(Debug, Clone)]
pub struct BackChannelLogoutConfig {
    /// Enable back-channel logout
    pub enabled: bool,
    /// Base URL for endpoints
    pub base_url: Option<String>,
    /// Request timeout in seconds
    pub request_timeout_secs: u64,
    /// Maximum retry attempts for failed requests
    pub max_retry_attempts: u32,
    /// Retry delay in milliseconds (exponential backoff base)
    pub retry_delay_ms: u64,
    /// Maximum concurrent notifications
    pub max_concurrent_notifications: usize,
    /// Logout token expiration time in seconds
    pub logout_token_exp_secs: u64,
    /// Include additional claims in logout token
    pub include_session_claims: bool,
    /// Custom User-Agent for HTTP requests
    pub user_agent: String,
    /// Enable request/response logging
    pub enable_http_logging: bool,
    /// HMAC signing key for logout tokens (generated randomly if not provided).
    /// Used only when `rsa_private_key_pem` is `None`; in that case the JWT
    /// header algorithm is `HS256` (not `RS256`).
    pub signing_key: Option<Vec<u8>>,
    /// PEM-encoded RSA private key for signing logout tokens with RS256.
    /// When set, JWTs use `"alg": "RS256"` and are signed with this key.
    /// Falls back to `signing_key` HMAC if `None`.
    pub rsa_private_key_pem: Option<String>,
}

impl Default for BackChannelLogoutConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            base_url: None,
            request_timeout_secs: 30,
            max_retry_attempts: 3,
            retry_delay_ms: 1000, // Start with 1 second, exponential backoff
            max_concurrent_notifications: 10,
            logout_token_exp_secs: 120, // 2 minutes
            include_session_claims: true,
            user_agent: "AuthFramework-OIDC/1.0".to_string(),
            enable_http_logging: false,
            signing_key: None,
            rsa_private_key_pem: None,
        }
    }
}

/// RP back-channel logout configuration
#[derive(Debug, Clone)]
pub struct RpBackChannelConfig {
    /// Client ID
    pub client_id: String,
    /// Back-channel logout URI
    pub backchannel_logout_uri: String,
    /// Whether RP requires session_state parameter
    pub backchannel_logout_session_required: bool,
    /// Custom timeout for this RP (if different from global)
    pub custom_timeout_secs: Option<u64>,
    /// Custom retry configuration for this RP
    pub custom_max_retries: Option<u32>,
    /// Authentication method for back-channel requests (for future use)
    pub authentication_method: Option<String>,
}

/// Logout token claims
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LogoutTokenClaims {
    /// Issuer
    pub iss: String,
    /// Subject
    pub sub: Option<String>,
    /// Audience (client_id)
    pub aud: Vec<String>,
    /// Issued at
    pub iat: u64,
    /// JWT ID
    pub jti: String,
    /// Events claim
    pub events: LogoutEvents,
    /// Session ID (if available)
    pub sid: Option<String>,
    /// Expiration time
    pub exp: u64,
}

/// Logout events structure
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LogoutEvents {
    /// Back-channel logout event URI
    #[serde(
        rename = "http://schemas.openid.net/secevent/risc/event-type/account-credential-change-required"
    )]
    pub backchannel_logout: Option<serde_json::Value>,

    /// Standard logout event
    #[serde(rename = "http://schemas.openid.net/secevent/oauth/event-type/token-revocation")]
    pub token_revocation: Option<serde_json::Value>,
}

/// Back-channel logout manager
#[derive(Debug)]
pub struct BackChannelLogoutManager {
    /// Configuration
    config: BackChannelLogoutConfig,
    /// Session manager for session tracking
    session_manager: SessionManager,
    /// HTTP client for back-channel requests
    http_client: crate::server::core::common_http::HttpClient,
    /// Registered RP configurations
    rp_configs: HashMap<String, RpBackChannelConfig>,
    /// Active logout requests tracking
    active_logouts: HashMap<String, SystemTime>,
    /// HMAC signing key for logout tokens (fallback when no RSA key)
    signing_key: Vec<u8>,
    /// RSA signing key for RS256 logout tokens (preferred)
    rsa_signing_key: Option<ring::signature::RsaKeyPair>,
}

impl BackChannelLogoutManager {
    /// Create new back-channel logout manager
    pub fn new(config: BackChannelLogoutConfig, session_manager: SessionManager) -> Result<Self> {
        use crate::server::core::common_config::{EndpointConfig, SecurityConfig, TimeoutConfig};

        // Create endpoint configuration from config
        let mut endpoint_config = EndpointConfig::new(
            config
                .base_url
                .as_ref()
                .unwrap_or(&"http://localhost:8080".to_string()),
        );
        endpoint_config.timeout = TimeoutConfig {
            connect_timeout: Duration::from_secs(config.request_timeout_secs),
            read_timeout: Duration::from_secs(config.request_timeout_secs),
            write_timeout: Duration::from_secs(30),
        };
        endpoint_config.security = SecurityConfig {
            enable_tls: true,
            min_tls_version: "1.2".to_string(),
            cipher_suites: vec![
                "TLS_AES_256_GCM_SHA384".to_string(),
                "TLS_CHACHA20_POLY1305_SHA256".to_string(),
                "TLS_AES_128_GCM_SHA256".to_string(),
            ],
            cert_validation: crate::server::core::common_config::CertificateValidation::Full,
            verify_certificates: true,
            accept_invalid_certs: false,
        };
        endpoint_config
            .headers
            .insert("User-Agent".to_string(), config.user_agent.clone());

        let http_client = crate::server::core::common_http::HttpClient::new(endpoint_config)?;

        // Use provided signing key or generate a random one
        let signing_key = config.signing_key.clone().unwrap_or_else(|| {
            use ring::rand::{SecureRandom, SystemRandom};
            let rng = SystemRandom::new();
            let mut key = vec![0u8; 32];
            rng.fill(&mut key)
                .expect("AuthFramework fatal: system CSPRNG unavailable");
            key
        });

        // Parse RSA private key if provided
        let rsa_signing_key = config.rsa_private_key_pem.as_ref().and_then(|pem| {
            // Strip PEM header/footer and decode
            let der = pem
                .lines()
                .filter(|l| !l.starts_with("-----"))
                .collect::<String>();
            let der_bytes = base64::Engine::decode(
                &base64::engine::general_purpose::STANDARD,
                &der,
            ).ok()?;
            ring::signature::RsaKeyPair::from_pkcs8(&der_bytes)
                .or_else(|_| ring::signature::RsaKeyPair::from_der(&der_bytes))
                .ok()
        });

        Ok(Self {
            config,
            session_manager,
            http_client,
            rp_configs: HashMap::new(),
            active_logouts: HashMap::new(),
            signing_key,
            rsa_signing_key,
        })
    }

    /// Register RP back-channel logout configuration
    pub fn register_rp_config(&mut self, rp_config: RpBackChannelConfig) {
        self.rp_configs
            .insert(rp_config.client_id.clone(), rp_config);
    }

    /// Process back-channel logout request
    pub async fn process_backchannel_logout(
        &mut self,
        request: BackChannelLogoutRequest,
    ) -> Result<BackChannelLogoutResponse> {
        if !self.config.enabled {
            return Err(AuthError::validation("Back-channel logout is not enabled"));
        }

        // Find all sessions for the subject
        let user_sessions = self.session_manager.get_sessions_for_subject(&request.sub);

        // Determine which RPs need to be notified
        let mut rps_to_notify = Vec::new();
        for session in user_sessions {
            // Skip the session being logged out to avoid self-notification
            if session.session_id == request.session_id {
                continue;
            }

            // Check if this client has back-channel logout configured
            if let Some(rp_config) = self.rp_configs.get(&session.client_id) {
                // Skip the initiating client if this is a client-initiated logout
                if let Some(ref initiating_client) = request.initiating_client_id
                    && &session.client_id == initiating_client
                {
                    continue;
                }

                rps_to_notify.push((session.clone(), rp_config.clone()));
            }
        }

        // Generate proper JWT logout token according to OIDC Back-Channel Logout spec
        let logout_token_jti = Uuid::new_v4().to_string();
        let logout_token = self
            .generate_logout_token(&request, &logout_token_jti)
            .map_err(|e| {
                AuthError::validation(format!("Failed to generate logout token: {}", e))
            })?;

        // Send notifications to all RPs concurrently (with concurrency limit)
        let mut successful_notifications = Vec::new();
        let mut failed_notifications = Vec::new();

        // Process notifications in batches to respect concurrency limits
        let chunk_size = self.config.max_concurrent_notifications;
        for chunk in rps_to_notify.chunks(chunk_size) {
            let mut tasks = Vec::new();

            for (session, rp_config) in chunk {
                let logout_token_clone = logout_token.clone();
                let rp_config_clone = rp_config.clone();
                let session_clone = session.clone();
                let client_clone = self.http_client.clone();
                let config_clone = self.config.clone();

                let task = tokio::spawn(async move {
                    Self::send_backchannel_notification(
                        client_clone,
                        config_clone,
                        session_clone,
                        rp_config_clone,
                        logout_token_clone,
                    )
                    .await
                });

                tasks.push(task);
            }

            // Wait for all tasks in this batch to complete
            for task in tasks {
                match task.await {
                    Ok(Ok(notification_result)) => {
                        successful_notifications.push(notification_result);
                    }
                    Ok(Err(failed_notification)) => {
                        failed_notifications.push(failed_notification);
                    }
                    Err(e) => {
                        failed_notifications.push(FailedNotification {
                            client_id: "unknown".to_string(),
                            backchannel_logout_uri: "unknown".to_string(),
                            error: format!("Task execution failed: {}", e),
                            status_code: None,
                            retry_attempts: 0,
                        });
                    }
                }
            }
        }

        // Track this logout request
        self.active_logouts
            .insert(logout_token_jti.clone(), SystemTime::now());

        Ok(BackChannelLogoutResponse {
            success: failed_notifications.is_empty(),
            notified_rps: successful_notifications.len(),
            successful_notifications,
            failed_notifications,
            logout_token_jti,
        })
    }

    /// Generate logout token JWT (production implementation)
    ///
    /// This method creates RFC-compliant OIDC Back-Channel Logout tokens with:
    /// - Standard logout event claims (iss, sub, aud, iat, jti, events)
    /// - Support for additional custom events via BackChannelLogoutRequest.additional_events
    /// - Proper JWT structure (header.payload.signature)
    /// - Event data validation using the serde_from_value helper function
    fn generate_logout_token(
        &self,
        request: &BackChannelLogoutRequest,
        jti: &str,
    ) -> Result<String> {
        use base64::Engine as _;
        use base64::engine::general_purpose::URL_SAFE_NO_PAD;

        // Create proper logout token claims according to OIDC Back-Channel Logout spec
        let now = chrono::Utc::now().timestamp();

        // Build events claim with standard logout event
        let mut events = serde_json::json!({
            "http://schemas.openid.net/secevent/oauth/event-type/logout": {}
        });

        // Add additional events if provided, using our helper function for validation
        if let Some(ref additional_events) = request.additional_events {
            for (event_type, event_data) in additional_events {
                // Validate and deserialize additional event data using our helper
                let validated_event = serde_from_value::<serde_json::Value>(event_data.clone())?;
                events[event_type] = validated_event;
            }
        }

        let claims = serde_json::json!({
            "iss": request.iss,
            "sub": request.sub,
            "aud": request.initiating_client_id.as_ref().unwrap_or(&"default_client".to_string()),
            "iat": now,
            "jti": jti,
            "events": events,
            // Note: 'nonce' should NOT be included in logout tokens per spec
        });

        // Select algorithm based on whether an RSA key is available
        let alg = if self.rsa_signing_key.is_some() {
            "RS256"
        } else {
            "HS256"
        };

        // Create JWT header — algorithm MUST match the actual signing method
        let header = serde_json::json!({
            "alg": alg,
            "typ": "logout+jwt",
        });

        // Encode header and payload
        let header_b64 = URL_SAFE_NO_PAD.encode(header.to_string());
        let claims_b64 = URL_SAFE_NO_PAD.encode(claims.to_string());
        let signing_input = format!("{}.{}", header_b64, claims_b64);

        let signature = self.generate_logout_token_signature(&signing_input)?;
        let signature_b64 = URL_SAFE_NO_PAD.encode(&signature);

        Ok(format!("{}.{}.{}", header_b64, claims_b64, signature_b64))
    }

    /// Sign the logout token using RSA (RS256) if available, otherwise HMAC (HS256).
    fn generate_logout_token_signature(&self, signing_input: &str) -> Result<Vec<u8>> {
        if let Some(ref rsa_key) = self.rsa_signing_key {
            // RS256: RSA PKCS#1 v1.5 with SHA-256
            let rng = ring::rand::SystemRandom::new();
            let mut sig = vec![0u8; rsa_key.public().modulus_len()];
            rsa_key
                .sign(
                    &ring::signature::RSA_PKCS1_SHA256,
                    &rng,
                    signing_input.as_bytes(),
                    &mut sig,
                )
                .map_err(|e| AuthError::internal(format!("RSA signing error: {e}")))?;
            Ok(sig)
        } else {
            // Fallback: HS256
            use hmac::{Hmac, Mac};
            use sha2::Sha256;
            type HmacSha256 = Hmac<Sha256>;
            let mut mac = HmacSha256::new_from_slice(&self.signing_key)
                .map_err(|e| AuthError::internal(format!("HMAC key error: {}", e)))?;
            mac.update(signing_input.as_bytes());
            Ok(mac.finalize().into_bytes().to_vec())
        }
    }

    /// Send back-channel logout notification to a specific RP
    async fn send_backchannel_notification(
        client: crate::server::core::common_http::HttpClient,
        config: BackChannelLogoutConfig,
        session: OidcSession,
        rp_config: RpBackChannelConfig,
        logout_token: String,
    ) -> Result<NotificationResult, FailedNotification> {
        use std::collections::HashMap;

        let client_id = session.client_id.clone();
        let backchannel_logout_uri = rp_config.backchannel_logout_uri.clone();

        // Prepare form data for the logout token
        let mut form_data = HashMap::new();
        form_data.insert("logout_token".to_string(), logout_token);

        let mut retry_count = 0;
        let max_retries = config.max_retry_attempts;
        let start_time = std::time::Instant::now();

        loop {
            // Send POST request with form data
            let response = client.post_form(&backchannel_logout_uri, &form_data).await;

            match response {
                Ok(resp) => {
                    let status_code = resp.status().as_u16();
                    let response_time = start_time.elapsed().as_millis() as u64;

                    if resp.status().is_success() {
                        return Ok(NotificationResult {
                            client_id,
                            backchannel_logout_uri,
                            success: true,
                            status_code: Some(status_code),
                            retry_attempts: retry_count,
                            response_time_ms: response_time,
                        });
                    } else if retry_count < max_retries && Self::is_retryable_status(status_code) {
                        // Retry for retryable errors
                        retry_count += 1;
                        let delay = Duration::from_millis(100 * (2_u64.pow(retry_count)));
                        tokio::time::sleep(delay).await;
                        continue;
                    } else {
                        let body = resp.text().await.unwrap_or_default();
                        return Err(FailedNotification {
                            client_id,
                            backchannel_logout_uri,
                            error: format!("HTTP {}: {}", status_code, body),
                            status_code: Some(status_code),
                            retry_attempts: retry_count,
                        });
                    }
                }
                Err(e) => {
                    if retry_count < max_retries {
                        retry_count += 1;
                        let delay = Duration::from_millis(100 * (2_u64.pow(retry_count)));
                        tokio::time::sleep(delay).await;
                        continue;
                    } else {
                        return Err(FailedNotification {
                            client_id,
                            backchannel_logout_uri,
                            error: format!("Request failed: {}", e),
                            status_code: None,
                            retry_attempts: retry_count,
                        });
                    }
                }
            }
        }
    }

    /// Check if HTTP status code is retryable
    fn is_retryable_status(status_code: u16) -> bool {
        match status_code {
            // Rate limiting
            429 => true,
            // Request timeout
            408 => true,
            // Server errors are generally retryable
            500..=599 => true,
            _ => false,
        }
    }

    /// Clean up expired logout tracking
    pub fn cleanup_expired_logouts(&mut self) -> usize {
        let now = SystemTime::now();
        let initial_count = self.active_logouts.len();

        self.active_logouts.retain(|_, timestamp| {
            now.duration_since(*timestamp)
                .map(|d| d.as_secs() < 3600) // Keep for 1 hour
                .unwrap_or(false)
        });

        initial_count - self.active_logouts.len()
    }

    /// Get discovery metadata for back-channel logout
    pub fn get_discovery_metadata(&self) -> HashMap<String, serde_json::Value> {
        let mut metadata = HashMap::new();

        if self.config.enabled {
            metadata.insert(
                "backchannel_logout_supported".to_string(),
                serde_json::Value::Bool(true),
            );

            metadata.insert(
                "backchannel_logout_session_supported".to_string(),
                serde_json::Value::Bool(self.config.include_session_claims),
            );
        }

        metadata
    }
}

// Helper function to deserialize serde_json::Value to LogoutEvents
fn serde_from_value<T>(value: serde_json::Value) -> Result<T>
where
    T: serde::de::DeserializeOwned,
{
    serde_json::from_value(value)
        .map_err(|e| AuthError::internal(format!("JSON deserialization error: {}", e)))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::server::oidc::oidc_session_management::SessionManagementConfig;

    fn create_test_manager() -> Result<BackChannelLogoutManager> {
        let config = BackChannelLogoutConfig::default();
        let session_manager = SessionManager::new(SessionManagementConfig::default());
        BackChannelLogoutManager::new(config, session_manager)
    }

    #[test]
    fn test_retryable_status_codes() {
        // Server errors should be retryable
        assert!(BackChannelLogoutManager::is_retryable_status(500));
        assert!(BackChannelLogoutManager::is_retryable_status(502));
        assert!(BackChannelLogoutManager::is_retryable_status(503));

        // Rate limiting should be retryable
        assert!(BackChannelLogoutManager::is_retryable_status(429));

        // Client errors should not be retryable
        assert!(!BackChannelLogoutManager::is_retryable_status(400));
        assert!(!BackChannelLogoutManager::is_retryable_status(401));
        assert!(!BackChannelLogoutManager::is_retryable_status(404));

        // Success should not be retryable (already succeeded)
        assert!(!BackChannelLogoutManager::is_retryable_status(200));
        assert!(!BackChannelLogoutManager::is_retryable_status(204));
    }

    #[test]
    fn test_logout_token_generation() -> Result<()> {
        let manager = create_test_manager()?;

        let request = BackChannelLogoutRequest {
            session_id: "session123".to_string(),
            sub: "user123".to_string(),
            sid: Some("sid123".to_string()),
            iss: "https://op.example.com".to_string(),
            initiating_client_id: None,
            additional_events: None,
        };

        let token = manager.generate_logout_token(&request, "jti123")?;

        assert!(!token.is_empty());
        // Token should be a valid JWT format (3 base64 parts separated by dots)
        assert_eq!(token.split('.').count(), 3);

        Ok(())
    }

    #[test]
    fn test_logout_token_with_additional_events() -> Result<()> {
        let manager = create_test_manager()?;

        // Create additional events to test the serde_from_value helper function
        let mut additional_events = HashMap::new();
        additional_events.insert(
            "http://schemas.openid.net/secevent/risc/event-type/account-credential-change-required"
                .to_string(),
            serde_json::json!({
                "reason": "password_change",
                "timestamp": "2025-08-07T12:00:00Z"
            }),
        );
        additional_events.insert(
            "custom-event-type".to_string(),
            serde_json::json!({
                "custom_field": "custom_value"
            }),
        );

        let request = BackChannelLogoutRequest {
            session_id: "session123".to_string(),
            sub: "user123".to_string(),
            sid: Some("sid123".to_string()),
            iss: "https://op.example.com".to_string(),
            initiating_client_id: Some("client_456".to_string()),
            additional_events: Some(additional_events),
        };

        let token = manager.generate_logout_token(&request, "jti456")?;

        assert!(!token.is_empty());
        // Token should be a valid JWT format (3 base64 parts separated by dots)
        assert_eq!(token.split('.').count(), 3);

        // Decode and verify the token contains our additional events
        use base64::Engine as _;
        use base64::engine::general_purpose::URL_SAFE_NO_PAD;

        let parts: Vec<&str> = token.split('.').collect();
        assert_eq!(parts.len(), 3);

        // Decode the claims (payload) part
        let claims_json = String::from_utf8(URL_SAFE_NO_PAD.decode(parts[1]).unwrap()).unwrap();
        let claims: serde_json::Value = serde_json::from_str(&claims_json).unwrap();

        // Verify the events contain both standard and additional events
        let events = &claims["events"];
        assert!(events["http://schemas.openid.net/secevent/oauth/event-type/logout"].is_object());
        assert!(events["http://schemas.openid.net/secevent/risc/event-type/account-credential-change-required"].is_object());
        assert!(events["custom-event-type"].is_object());

        // Verify additional event data was properly processed by serde_from_value
        assert_eq!(
            events["http://schemas.openid.net/secevent/risc/event-type/account-credential-change-required"]
                ["reason"],
            "password_change"
        );
        assert_eq!(events["custom-event-type"]["custom_field"], "custom_value");

        Ok(())
    }

    #[test]
    fn test_discovery_metadata() -> Result<()> {
        let manager = create_test_manager()?;
        let metadata = manager.get_discovery_metadata();

        assert_eq!(
            metadata.get("backchannel_logout_supported"),
            Some(&serde_json::Value::Bool(true))
        );
        assert_eq!(
            metadata.get("backchannel_logout_session_supported"),
            Some(&serde_json::Value::Bool(true))
        );

        Ok(())
    }
}