Splinter REST API Authorization

/// The possible outcomes of attempting to authorize a client
enum AuthorizationResult {
    /// The client was authorized to the given identity based on the authorization header
    Authorized(Identity),
    /// The requested endpoint does not require authorization
    NoAuthorizationNecessary,
    /// The authorization header is empty or invalid
    Unauthorized,
    /// The request endpoint is not defined
    UnknownEndpoint,
}

/// Uses the given identity providers to check authorization for the request. This function is
/// backend-agnostic and intended as a helper for the backend REST API implementations.
///
/// # Arguments
///
/// * `method` - The HTTP method used for the request
/// * `endpoint` - The endpoint that is being requested. Example: "/endpoint/path"
/// * `auth_header` - The value of the Authorization HTTP header for the request
/// * `identity_providers` - The identity providers that will be used to check the client's identity
/// * `authorization_handlers` - The authorization handlers that will be used to check the client's
///   permissions
fn authorize(
    method: &Method,
    endpoint: &str,
    auth_header: Option<&str>,
    permission_map: &PermissionMap,
    identity_providers: &[Box<dyn IdentityProvider>],
    authorization_handlers: &[Box<dyn AuthorizationHandler>],
) -> AuthorizationResult {
    // contents omitted for brevity
}

/// A permission assigned to an endpoint
pub enum Permission {
    /// Check that the authenticated client has the specified permission.
    Check {
        /// The permission ID that's passed to [`AuthorizationHandler::has_permission`]
        permission_id: &'static str,
        /// The human-readable name for the permission
        permission_display_name: &'static str,
        /// A description for the permission
        permission_description: &'static str,
    },
    /// Allow any request that has been authenticated (the client's identity has been determined).
    /// This may be used by endpoints that need to know the client's identity but do not require a
    /// special permission to be checked (the Biome key management and OAuth logout routes are an
    /// example of this).
    AllowAuthenticated,
    /// Allow any request without checking for authorization.
    AllowUnauthenticated,
}

/// A map used to correlate requests with the permissions that guard them.
pub(in crate::rest_api) struct PermissionMap {
    internal: Vec<(RequestDefinition, Permission)>,
}

impl PermissionMap {
    pub fn new() -> Self {
        // contents omitted for brevity
    }

    /// Gets a list of all permissions.
    pub fn permissions(&self) -> impl Iterator<Item = Permission> + '_ {
        // contents omitted for brevity
    }

    /// Sets the permission for the given (method, endpoint) pair. The endpoint may contain path
    /// variables surrounded by `{}`.
    pub fn add_permission(&mut self, method: Method, endpoint: &str, permission: Permission) {
        // contents omitted for brevity
    }

    /// Gets the permission for a request. This will attempt to match the method and endpoint to a
    /// known (method, endpoint) pair, considering path variables of known endpoints.
    pub fn get_permission(&self, method: &Method, endpoint: &str) -> Option<&Permission> {
        // contents omitted for brevity
    }

    /// Takes the contents of another `PermissionMap` and merges them into itself. This consumes the
    /// contents of the other map.
    pub fn append(&mut self, other: &mut PermissionMap) {
        // contents omitted for brevity
    }
}

/// A (method, endpoint) definition that will be used to match requests
struct RequestDefinition {
    method: Method,
    path: Vec<PathComponent>,
}

impl RequestDefinition {
    pub fn new(method: Method, endpoint: &str) -> Self {
        // contents omitted for brevity
    }

    /// Checks if the given request matches this definition, considering any variable path
    /// components.
    pub fn matches(&self, method: &Method, endpoint: &str) -> bool {
        // contents omitted for brevity
    }
}

/// A component of an endpoint path
enum PathComponent {
    /// A standard path component where matching is done on the internal string
    Text(String),
    /// A variable path component that matches any string
    Variable,
}

impl From<&str> for PathComponent {
    // contents omitted for brevity
}

impl PartialEq<&str> for PathComponent {
    // contents omitted for brevity
}

/// A service that fetches identities from a backing provider
pub trait IdentityProvider: Send + Sync {
    /// Attempts to get the identity that corresponds to the given authorization header. This method
    /// will return `Ok(None)` if the identity provider was not able to resolve the authorization
    /// to an identity.
    fn get_identity(
        &self,
        authorization: &AuthorizationHeader,
    ) -> Result<Option<Identity>, InternalError>;
}

/// A parsed authorization header
pub enum AuthorizationHeader {
    Bearer(BearerToken),
    Custom(String),
}

/// A bearer token of a specific type
pub enum BearerToken {
    /// Contains a Biome JWT
    Biome(String),
    /// Contains a custom token, which is any bearer token that does not match one of the other
    /// variants of this enum
    Custom(String),
    /// Contains a Cylinder JWT
    Cylinder(String),
    /// Contains an OAuth2 token
    OAuth2(String),
}

use crate::error::InternalError;

use super::identity::Identity;

/// An authorization handler's decision about whether to allow, deny, or pass on the request
pub enum AuthorizationHandlerResult {
    /// The authorization handler has granted the requested permission
    Allow,
    /// The authorization handler has denied the requested permission
    Deny,
    /// The authorization handler is not able to determine if the requested permission should be
    /// granted or denied
    Continue,
}

/// Determines if a client has some permissions
pub trait AuthorizationHandler: Send + Sync {
    /// Determines if the given identity has the requested permission
    fn has_permission(
        &self,
        identity: &Identity,
        permission_id: &str,
    ) -> Result<AuthorizationHandlerResult, InternalError>;=
}

use std::time::SystemTime;

use crate::error::InternalError;
use crate::rest_api::auth::identity::Identity;

use super::{AuthorizationHandler, AuthorizationHandlerResult};

/// A file-backed authorization handler that permits admin keys
pub struct AllowKeysAuthorizationHandler {
    internal: Arc<Mutex<Internal>>,
}

impl AllowKeysAuthorizationHandler {
    /// Constructs a new `AllowKeysAuthorizationHandler`. If the backing file already exists, it
    /// will be loaded and cached; if the backing file doesn't already exist, it will be created.
    ///
    /// # Arguments
    ///
    /// * `file_path` - The path of the backing allow keys file.
    pub fn new(file_path: &str) -> Result<Self, InternalError> {
        // contents omitted for brevity
    }
}

impl AuthorizationHandler for AllowKeysAuthorizationHandler {
    fn has_permission(
        &self,
        identity: &Identity,
        _permission_id: &str,
    ) -> Result<AuthorizationHandlerResult, InternalError> {
        // Allow if `identity` is in the internal list of keys, otherwise continue
    }
}

/// Internal state of the authorization handler
struct Internal {
    file_path: String,
    cached_keys: Vec<String>,
    last_read: SystemTime,
}

impl Internal {
    fn new(file_path: &str) -> Result<Self, InternalError> {
        // load keys from file or create file if necessary
    }

    /// Gets the internal list of keys. If the backing file has been modified since the last read,
    /// attempts to refresh the cache. If the file is unavailable, clears the cache.
    fn get_keys(&mut self) -> &[String] {
        // contents omitted for brevity
    }

    /// Reads the backing file and caches its contents, logging an error for any key that can't be
    /// read
    fn read_keys(&mut self) -> Result<(), InternalError> {
        // contents omitted for brevity
    }
}

use crate::error::InternalError;
use crate::rest_api::auth::authorization::{AuthorizationHandler, AuthorizationHandlerResult};

use super::store::RoleBasedAuthorizationStore;

/// A Role-based authorization handler.
pub struct RoleBasedAuthorizationHandler {
    role_based_auth_store: Box<dyn RoleBasedAuthorizationStore>,
}

impl RoleBasedAuthorizationHandler {
    /// Construct a new role-based authorization handler with the given store.
    pub fn new(role_based_auth_store: Box<dyn RoleBasedAuthorizationStore>) -> Self {
        // contents omitted for brevity
    }
}

impl AuthorizationHandler for RoleBasedAuthorizationHandler {
    fn has_permission(
        identity: &str,
        permission_id: &str
    ) -> Result<AuthorizationHandlerResult, AuthorizationHandlerError> {
        // Allow if `identity` has been assigned a role with the given permission in the store,
        // otherwise continue
    }
}

pub use error::RoleBasedAuthorizationStoreError;

/// A Role is a named set of permissions.
pub struct Role {
    id: String,
    display_name: String,
    permissions: Vec<String>,
}

impl Role {
    // contents omitted for brevity
}

pub struct RoleBuilder {
    // contents omitted for brevity
}

impl RoleBuilder {
    // contents omitted for brevity
}

pub struct RoleUpdateBuilder {
    // contents omitted for brevity
}

impl RoleUpdateBuilder {
    with_display_name(mut self, display_name: String) -> Self {
        // contents omitted for brevity
    }

    with_permissionss(mut self, permissions: Vec<String>) -> Self {
        // contents omitted for brevity
    }

    build(self) -> Role {
        // contents omitted for brevity
    }
}

/// An identity that may be assigned roles.
pub enum Identity {
    /// A public key-based identity.
    Key(String),
    /// A user ID-based identity.
    User(String),
}

/// An assignment of roles to a particular identity.
pub struct Assignment {
    identity: Identity,
    roles: Vec<String>,
}

impl Assignment {
    // contents omitted for brevity
}

pub struct AssignmentBuilder {
    // contents omitted for brevity
}

impl AssignmentBuilder {
    // contents omitted for brevity
}

pub struct AssignmentUpdateBuilder {
    // contents omitted for brevity
}

impl AssignmentUpdateBuilder {
    with_roles(mut self, roles: Vec<String>) -> Self {
        // contents omitted for brevity
    }

    build(self) -> Assignment {
        // contents omitted for brevity
    }
}

/// Defines methods for CRUD operations on Role and assignment data.
pub trait RoleBasedAuthorizationStore: Send + Sync {
    /// Returns the role for the given ID, if one exists.
    fn get_role(&self, id: &str) -> Result<Option<Role>, RoleBasedAuthorizationStoreError>;

    /// Lists all roles.
    fn list_roles(
        &self,
    ) -> Result<Box<dyn ExactSizeIterator<Item = Role>>, RoleBasedAuthorizationStoreError>;

    /// Adds a role.
    ///
    /// # Errors
    ///
    /// Returns a `ConstraintViolation` error if a duplicate role ID is added.
    fn add_role(&self, role: Role) -> Result<(), RoleBasedAuthorizationStoreError>;

    /// Updates a role.
    ///
    /// # Errors
    ///
    /// Returns a `InvalidState` error if the role does not exist.
    fn update_role(&self, role: Role) -> Result<(), RoleBasedAuthorizationStoreError>;

    /// Removes a role.
    ///
    /// # Errors
    ///
    /// Returns a `InvalidState` error if the role does not exist.
    fn remove_role(&self, role_id: &str) -> Result<(), RoleBasedAuthorizationStoreError>;

    /// Returns the role for the given Identity, if one exists.
    fn get_assignment(
        &self,
        identity: &Identity,
    ) -> Result<Option<Assignment>, RoleBasedAuthorizationStoreError>;

    /// Returns the assigned roles for the given Identity.
    fn get_assigned_roles(
        &self,
        identity: &Identity,
    ) -> Result<Box<dyn ExactSizeIterator<Item = Role>>, RoleBasedAuthorizationStoreError>;

    /// Lists all assignments.
    fn list_assignments(
        &self,
    ) -> Result<Box<dyn ExactSizeIterator<Item = Assignment>>, RoleBasedAuthorizationStoreError>;

    /// Adds an assignment.
    ///
    /// # Errors
    ///
    /// Returns a `ConstraintViolation` error if there is a duplicate assignment of a role to an
    /// identity.
    fn add_assignment(
        &self,
        assignment: Assignment,
    ) -> Result<(), RoleBasedAuthorizationStoreError>;

    /// Updates an assignment.
    ///
    /// # Errors
    ///
    /// Returns a `InvalidState` error if the assignment does not exist.
    fn update_assignment(
        &self,
        assignment: Assignment,
    ) -> Result<(), RoleBasedAuthorizationStoreError>;

    /// Removes an assignment.
    ///
    /// # Errors
    ///
    /// Returns a `InvalidState` error if the assignment does not exist.
    fn remove_assignment(
        &self,
        identity: &Identity,
    ) -> Result<(), RoleBasedAuthorizationStoreError>;
}