vultur_sso_api_client/

lib.rs

//! # VULTUR SSO API Client
//!
//! Rust library for integrating with VULTUR SSO in API backends.
//! Provides JWT validation, authentication middleware, and .well-known endpoint serving.
//!
//! ## Features
//!
//! - JWT token validation against vultur-ident-api
//! - Authentication middleware for bouncing unauthenticated requests
//! - .well-known endpoint serving for permission configurations
//! - Permission checking utilities
//! - Axum integration
//!
//! ## Basic Example (`Arc<VulturSSOClient>` state)
//!
//! ```rust,no_run
//! use vultur_sso_api_client::{VulturSSOClient, Config, auth_middleware};
//! use axum::{Router, routing::get, middleware};
//! use std::sync::Arc;
//!
//! #[tokio::main]
//! async fn main() {
//!     let config = Config::builder()
//!         .ident_api_url("https://ident.vultur.com")
//!         .application_name("my-app")
//!         .build()
//!         .unwrap();
//!     
//!     let client = Arc::new(VulturSSOClient::new(config));
//!     
//!     let app: Router<Arc<VulturSSOClient>> = Router::new()
//!         .route("/protected", get(protected_handler))
//!         .layer(middleware::from_fn_with_state(
//!             client.clone(),
//!             auth_middleware
//!         ))
//!         .with_state(client);
//! }
//!
//! async fn protected_handler() -> &'static str {
//!     "This is protected!"
//! }
//! ```
//!
//! ## Generic Example (Composite AppState)
//!
//! For applications that need composite state (recommended for new projects):
//!
//! ```rust,no_run
//! use vultur_sso_api_client::{VulturSSOClient, Config, auth_middleware_generic};
//! use axum::{Router, routing::get, middleware, extract::FromRef};
//! use std::sync::Arc;
//!
//! #[derive(Clone)]
//! struct AppState {
//!     sso_client: Arc<VulturSSOClient>,
//!     database_url: String,
//! }
//!
//! impl FromRef<AppState> for Arc<VulturSSOClient> {
//!     fn from_ref(app_state: &AppState) -> Arc<VulturSSOClient> {
//!         app_state.sso_client.clone()
//!     }
//! }
//!
//! #[tokio::main]
//! async fn main() {
//!     let config = Config::builder()
//!         .ident_api_url("https://ident.vultur.com")
//!         .application_name("my-app")
//!         .build()
//!         .unwrap();
//!     
//!     let app_state = AppState {
//!         sso_client: Arc::new(VulturSSOClient::new(config)),
//!         database_url: "sqlite://app.db".to_string(),
//!     };
//!     
//!     let app: Router<AppState> = Router::new()
//!         .route("/protected", get(protected_handler))
//!         .layer(middleware::from_fn_with_state(
//!             app_state.clone(),
//!             auth_middleware_generic::<AppState>
//!         ))
//!         .with_state(app_state);
//! }
//!
//! async fn protected_handler() -> &'static str {
//!     "This is protected!"
//! }
//! ```

pub mod client;
pub mod config;
pub mod error;
pub mod middleware;
pub mod permissions;
pub mod types;
pub mod well_known;

// Re-export main types and functions
pub use client::VulturSSOClient;
pub use config::{Config, ConfigBuilder};
pub use error::{Result, VulturSSOError};
pub use middleware::{
    auth_middleware, auth_middleware_generic, AuthenticatedUser, JwtToken, RequestExt, RequireAuth,
    RequirePermission,
};
pub use permissions::{
    PermissionChecker, PermissionConfigBuilder, PermissionPatterns, PermissionScopeBuilder,
};
pub use types::PermissionScope;
pub use types::{Permission, PermissionConfig, UserInfo, UserRole};
pub use well_known::{serve_well_known, WellKnownHandler};

/// Macro to create a permission extractor for a specific permission scope
///
/// # Example
///
/// ```rust,no_run
/// use vultur_sso_api_client::{require_permission, VulturSSOClient, Config};
/// use axum::{extract::State, routing::get, Router};
/// use std::sync::Arc;
///
/// require_permission!(CanManageUsers, "users.admin");
///
/// async fn admin_handler(
///     user: CanManageUsers,
///     State(client): State<Arc<VulturSSOClient>>,
/// ) -> String {
///     format!("Admin access granted to {}", user.user().character_name)
/// }
/// ```
#[macro_export]
macro_rules! require_permission {
    ($extractor_name:ident, $permission:expr) => {
        #[derive(Debug, Clone)]
        pub struct $extractor_name {
            user: $crate::UserInfo,
        }

        impl $extractor_name {
            pub fn user(&self) -> &$crate::UserInfo {
                &self.user
            }
        }

        impl $crate::middleware::AuthenticatedUser for $extractor_name {
            fn user(&self) -> &$crate::UserInfo {
                &self.user
            }
        }

        #[axum::async_trait]
        impl<S> axum::extract::FromRequestParts<S> for $extractor_name
        where
            S: Send + Sync,
            std::sync::Arc<$crate::VulturSSOClient>: axum::extract::FromRef<S>,
        {
            type Rejection = $crate::VulturSSOError;

            async fn from_request_parts(
                parts: &mut axum::http::request::Parts,
                state: &S,
            ) -> Result<Self, Self::Rejection> {
                use $crate::middleware::RequestExt;

                // Get user info from extensions
                let user = parts
                    .extensions
                    .get::<$crate::UserInfo>()
                    .ok_or_else(|| $crate::VulturSSOError::unauthorized("User not authenticated"))?
                    .clone();

                // Admin users have all permissions
                if user.is_admin {
                    return Ok($extractor_name { user });
                }

                // Get JWT token from extensions
                let token = parts
                    .extensions
                    .get::<$crate::JwtToken>()
                    .ok_or_else(|| $crate::VulturSSOError::unauthorized("JWT token not found"))?;

                // Extract the SSO client from state using FromRef
                let client: std::sync::Arc<$crate::VulturSSOClient> =
                    axum::extract::FromRef::from_ref(state);

                // Check permission
                let has_permission = client
                    .check_user_permission(&user.eth_address, $permission, &token.0)
                    .await?;

                if !has_permission {
                    return Err($crate::VulturSSOError::forbidden(format!(
                        "Permission '{}' required",
                        $permission
                    )));
                }

                Ok($extractor_name { user })
            }
        }
    };
}