reifydb_sub_server/

auth.rs

// Copyright (c) reifydb.com 2025
// This file is licensed under the AGPL-3.0-or-later

//! Authentication and identity extraction for HTTP and WebSocket connections.
//!
//! This module provides functions to extract user identity from request headers,
//! tokens, and WebSocket authentication messages.
//!
//! # Security Note
//!
//! The current implementation provides a framework for authentication but requires
//! proper implementation of token validation before production use. The `validate_*`
//! functions are stubs that should be connected to actual authentication services.

use reifydb_core::interface::Identity;

/// Authentication error types.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AuthError {
	/// The authorization header is malformed or contains invalid UTF-8.
	InvalidHeader,
	/// No credentials were provided (no Authorization header or API key).
	MissingCredentials,
	/// The provided token is invalid or cannot be verified.
	InvalidToken,
	/// The token has expired.
	Expired,
	/// The token is valid but the user lacks required permissions.
	InsufficientPermissions,
}

impl std::fmt::Display for AuthError {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		match self {
			AuthError::InvalidHeader => write!(f, "Invalid authorization header"),
			AuthError::MissingCredentials => write!(f, "Authentication required"),
			AuthError::InvalidToken => write!(f, "Invalid authentication token"),
			AuthError::Expired => write!(f, "Authentication token expired"),
			AuthError::InsufficientPermissions => write!(f, "Insufficient permissions"),
		}
	}
}

impl std::error::Error for AuthError {}

/// Result type for authentication operations.
pub type AuthResult<T> = std::result::Result<T, AuthError>;

/// Extract identity from HTTP Authorization header value.
///
/// Supports the following authentication schemes:
/// - `Bearer <token>` - JWT or opaque bearer token
/// - `Basic <base64>` - Basic authentication (username:password)
///
/// # Arguments
///
/// * `auth_header` - The value of the Authorization header
///
/// # Returns
///
/// * `Ok(Identity)` - The authenticated user identity
/// * `Err(AuthError)` - Authentication failed
///
/// # Example
///
/// ```ignore
/// let identity = extract_identity_from_auth_header("Bearer eyJ...")?;
/// ```
pub fn extract_identity_from_auth_header(auth_header: &str) -> AuthResult<Identity> {
	if let Some(token) = auth_header.strip_prefix("Bearer ") {
		validate_bearer_token(token.trim())
	} else if let Some(credentials) = auth_header.strip_prefix("Basic ") {
		validate_basic_auth(credentials.trim())
	} else {
		Err(AuthError::InvalidHeader)
	}
}

/// Extract identity from an API key.
///
/// # Arguments
///
/// * `api_key` - The API key value
///
/// # Returns
///
/// * `Ok(Identity)` - The identity associated with the API key
/// * `Err(AuthError)` - API key validation failed
pub fn extract_identity_from_api_key(api_key: &str) -> AuthResult<Identity> {
	validate_api_key(api_key)
}

/// Extract identity from WebSocket authentication message.
///
/// Called when a WebSocket client sends an Auth message with a token.
///
/// # Arguments
///
/// * `token` - Optional token from the Auth message
///
/// # Returns
///
/// * `Ok(Identity)` - The authenticated user identity
/// * `Err(AuthError::MissingCredentials)` - No token provided
/// * `Err(AuthError)` - Token validation failed
pub fn extract_identity_from_ws_auth(token: Option<&str>) -> AuthResult<Identity> {
	match token {
		Some(t) if !t.is_empty() => validate_bearer_token(t),
		_ => Err(AuthError::MissingCredentials),
	}
}

/// Create an anonymous identity for unauthenticated requests.
///
/// Use this when authentication is optional and the request has no credentials.
pub fn anonymous_identity() -> Identity {
	Identity::Anonymous {}
}

/// Create a root system identity.
///
/// **Warning**: This should only be used for internal operations, never for
/// external request handling.
pub fn root_identity() -> Identity {
	Identity::root()
}

// ============================================================================
// Token Validation Functions
//
// These functions are stubs that should be implemented with actual authentication
// logic before production use. They currently return errors to prevent accidental
// use of unauthenticated requests.
// ============================================================================

/// Validate a bearer token and return the associated identity.
///
/// # TODO: Implementation
///
/// This function should:
/// 1. Validate the token signature (if JWT)
/// 2. Check token expiration
/// 3. Look up the user/identity from the token claims
/// 4. Return the Identity
fn validate_bearer_token(token: &str) -> AuthResult<Identity> {
	// TODO: Implement actual JWT or opaque token validation
	//
	// Example JWT implementation:
	// 1. Decode and verify the JWT signature
	// 2. Check `exp` claim for expiration
	// 3. Extract `sub` claim for user ID
	// 4. Look up user in database or cache
	// 5. Return Identity::User { id, name }
	//
	// For now, accept any non-empty token and return a system identity
	if token.is_empty() {
		Err(AuthError::InvalidToken)
	} else {
		Ok(Identity::System {
			id: 1,
			name: "authenticated".to_string(),
		})
	}
}

/// Validate basic authentication credentials.
///
/// # TODO: Implementation
///
/// This function should:
/// 1. Base64 decode the credentials
/// 2. Split into username:password
/// 3. Verify credentials against user store
/// 4. Return the Identity
fn validate_basic_auth(credentials: &str) -> AuthResult<Identity> {
	// TODO: Implement basic auth validation
	//
	// 1. Base64 decode credentials
	// 2. Split on ':' to get username and password
	// 3. Verify against user database
	// 4. Return Identity::User { id, name }
	let _ = credentials;
	Err(AuthError::InvalidToken)
}

/// Validate an API key and return the associated identity.
///
/// # TODO: Implementation
///
/// This function should:
/// 1. Look up the API key in the database
/// 2. Check if the key is active and not expired
/// 3. Return the associated Identity
fn validate_api_key(api_key: &str) -> AuthResult<Identity> {
	// TODO: Implement API key validation
	//
	// 1. Hash the API key
	// 2. Look up in database
	// 3. Verify key is active
	// 4. Return the associated Identity
	//
	// For now, accept any non-empty API key and return a system identity
	if api_key.is_empty() {
		Err(AuthError::InvalidToken)
	} else {
		Ok(Identity::System {
			id: 1,
			name: "authenticated".to_string(),
		})
	}
}

#[cfg(test)]
mod tests {
	use super::*;

	#[test]
	fn test_auth_error_display() {
		assert_eq!(AuthError::InvalidHeader.to_string(), "Invalid authorization header");
		assert_eq!(AuthError::MissingCredentials.to_string(), "Authentication required");
		assert_eq!(AuthError::InvalidToken.to_string(), "Invalid authentication token");
		assert_eq!(AuthError::Expired.to_string(), "Authentication token expired");
	}

	#[test]
	fn test_extract_from_bearer_header() {
		// Should accept any non-empty token
		let result = extract_identity_from_auth_header("Bearer test_token");
		assert!(result.is_ok());
	}

	#[test]
	fn test_extract_from_invalid_scheme() {
		let result = extract_identity_from_auth_header("Unknown test_token");
		assert!(matches!(result, Err(AuthError::InvalidHeader)));
	}

	#[test]
	fn test_extract_from_ws_auth_none() {
		let result = extract_identity_from_ws_auth(None);
		assert!(matches!(result, Err(AuthError::MissingCredentials)));
	}

	#[test]
	fn test_extract_from_ws_auth_empty() {
		let result = extract_identity_from_ws_auth(Some(""));
		assert!(matches!(result, Err(AuthError::MissingCredentials)));
	}

	#[test]
	fn test_anonymous_identity() {
		let identity = anonymous_identity();
		assert!(matches!(identity, Identity::Anonymous {}));
	}

	#[test]
	fn test_root_identity() {
		let identity = root_identity();
		match identity {
			Identity::System {
				id,
				name,
			} => {
				assert_eq!(id, 0);
				assert_eq!(name, "root");
			}
			_ => panic!("Expected System identity"),
		}
	}
}