rainier-auth 1.0.0

Authentication guards, user providers, password hashing and authorization gates for Rainier.
Documentation
//! The [`Authenticate`] middleware — `->middleware("auth")`.
//!
//! Resolves the user once, puts them in the request's extensions, and rejects
//! the request if there is nobody there. Doing it in middleware rather than in
//! each controller means the guard runs exactly once per request, and a handler
//! that is behind `auth` can read [`AuthenticatedUser`] without re-checking.

use std::sync::Arc;

use rainier_http::{FromRequest, IntoResponse, Request, Response};
use rainier_middleware::{Middleware, MiddlewareStack, Next};
use rainier_support::{BoxedFuture, Error, Result};

use crate::guard::AuthManager;
use crate::user::Authenticatable;

/// The user resolved for this request, stored in its extensions.
///
/// A newtype rather than a bare `U` so it cannot be confused with any other
/// value of the same type an application might attach.
#[derive(Debug)]
pub struct AuthenticatedUser<U>(pub Arc<U>);

/// Cloning shares the user rather than copying it, so this holds whatever `U`
/// is — a derived `Clone` would have demanded `U: Clone` for no reason.
impl<U> Clone for AuthenticatedUser<U> {
    fn clone(&self) -> Self {
        Self(Arc::clone(&self.0))
    }
}

impl<U> AuthenticatedUser<U> {
    /// The user.
    pub fn get(&self) -> &U {
        &self.0
    }
}

impl<U> std::ops::Deref for AuthenticatedUser<U> {
    type Target = U;

    fn deref(&self) -> &U {
        &self.0
    }
}

/// The authenticated user, as a **controller parameter**.
///
/// Laravel injects the user; this is that, and it is why an action can read
///
/// ```ignore
/// pub async fn me(user: AuthenticatedUser<User>) -> Result<Response> {
///     Ok(Response::json(user.get()))
/// }
/// ```
///
/// rather than taking the whole request and digging the user out of it.
///
/// Fails with `401` when there is none — which can only happen on a route with
/// no [`Authenticate`] middleware in front, so the message says so rather than
/// blaming the caller for a wiring mistake.
impl<U: Send + Sync + 'static> FromRequest for AuthenticatedUser<U> {
    fn from_request(request: Arc<Request>) -> BoxedFuture<Result<Self>> {
        Box::pin(async move {
            request
                .extension::<AuthenticatedUser<U>>()
                .cloned()
                .ok_or_else(|| Error::unauthenticated("Unauthenticated."))
        })
    }
}

/// Rejects unauthenticated requests, and attaches the user to authenticated
/// ones.
pub struct Authenticate<U: Authenticatable> {
    auth: Arc<AuthManager<U>>,
    /// The guard to use, or `None` for the manager's default — this is the
    /// `api` in `->middleware("auth:api")`.
    guard: Option<String>,
}

impl<U: Authenticatable> Authenticate<U> {
    /// Authenticate with the manager's default guard.
    pub fn new(auth: Arc<AuthManager<U>>) -> Self {
        Self { auth, guard: None }
    }

    /// Authenticate with a named guard.
    pub fn with_guard(auth: Arc<AuthManager<U>>, guard: impl Into<String>) -> Self {
        Self { auth, guard: Some(guard.into()) }
    }

    /// A stack that builds this middleware from the container.
    ///
    /// Routes are declared before the container is populated, so the
    /// `AuthManager` cannot be handed over at declaration time. This defers the
    /// resolve to when the router compiles:
    ///
    /// ```ignore
    /// router.get("/me", me).middleware(Authenticate::<User>::resolved());
    /// ```
    ///
    /// The replacement for Laravel's `->middleware('auth')`. The user type is
    /// named explicitly, which is the thing a string alias could never say.
    pub fn resolved() -> MiddlewareStack {
        MiddlewareStack::new().resolved(|auth: Arc<AuthManager<U>>| Self::new(auth))
    }

    /// [`resolved`](Self::resolved) with a named guard — `->middleware('auth:api')`.
    pub fn resolved_with_guard(guard: impl Into<String>) -> MiddlewareStack {
        let guard = guard.into();
        MiddlewareStack::new()
            .resolved(move |auth: Arc<AuthManager<U>>| Self::with_guard(auth, guard.clone()))
    }
}

#[async_trait::async_trait]
impl<U: Authenticatable> Middleware for Authenticate<U> {
    async fn handle(&self, mut request: Request, next: Next) -> Response {
        let resolved = match &self.guard {
            Some(name) => self.auth.user_via(name, &request).await,
            None => self.auth.user(&request).await,
        };

        match resolved {
            Ok(Some(user)) => {
                request.extensions_mut().insert(AuthenticatedUser(Arc::new(user)));
                next.run(request).await
            }
            Ok(None) => Error::unauthenticated("Unauthenticated.").into_response(),
            // A guard failure is a 500, not a 401: the user may well be
            // authenticated, and telling them they are not would be a lie that
            // sends them to a login page which will also fail.
            Err(e) => {
                tracing::error!(error = %e, "the authentication guard failed");
                e.into_response()
            }
        }
    }

    fn name(&self) -> &'static str {
        "Authenticate"
    }
}

/// Rejects *authenticated* requests — the `guest` middleware, for a login page
/// an already-logged-in user should not see.
pub struct RedirectIfAuthenticated<U: Authenticatable> {
    auth: Arc<AuthManager<U>>,
    to: String,
}

impl<U: Authenticatable> RedirectIfAuthenticated<U> {
    /// Send authenticated users to `to`.
    pub fn new(auth: Arc<AuthManager<U>>, to: impl Into<String>) -> Self {
        Self { auth, to: to.into() }
    }
}

#[async_trait::async_trait]
impl<U: Authenticatable> Middleware for RedirectIfAuthenticated<U> {
    async fn handle(&self, request: Request, next: Next) -> Response {
        match self.auth.user(&request).await {
            Ok(Some(_)) => rainier_http::Redirect::to(self.to.clone()).into_response(),
            // A guard failure here is not a reason to block a login attempt —
            // failing open to the login page is the safe direction.
            Ok(None) | Err(_) => next.run(request).await,
        }
    }

    fn name(&self) -> &'static str {
        "RedirectIfAuthenticated"
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::guard::TokenGuard;
    use crate::user::{Credentials, UserProvider};
    use rainier_http::StatusCode;
    use rainier_middleware::Pipeline;
    use rainier_support::Result;

    #[derive(Debug, Clone, PartialEq)]
    struct User {
        id: u64,
    }

    impl Authenticatable for User {
        fn auth_identifier(&self) -> String {
            self.id.to_string()
        }
        fn auth_password_hash(&self) -> Option<&str> {
            None
        }
    }

    struct Provider {
        fail: bool,
    }

    #[async_trait::async_trait]
    impl UserProvider<User> for Provider {
        async fn retrieve_by_id(&self, _: &str) -> Result<Option<User>> {
            Ok(None)
        }
        async fn retrieve_by_credentials(&self, _: &Credentials) -> Result<Option<User>> {
            Ok(None)
        }
        async fn validate_credentials(&self, _: &User, _: &Credentials) -> Result<bool> {
            Ok(false)
        }
        async fn retrieve_by_token(&self, token: &str) -> Result<Option<User>> {
            if self.fail {
                return Err(Error::internal("database is down"));
            }
            Ok((token == "good").then_some(User { id: 7 }))
        }
    }

    fn manager(fail: bool) -> Arc<AuthManager<User>> {
        Arc::new(
            AuthManager::new("api")
                .register(Arc::new(TokenGuard::new("api", Arc::new(Provider { fail })))),
        )
    }

    async fn reveal_user(request: Request) -> Response {
        match request.extension::<AuthenticatedUser<User>>() {
            Some(user) => Response::text(user.id.to_string()),
            None => Response::text("anonymous"),
        }
    }

    async fn body_of(response: Response) -> String {
        String::from_utf8(response.into_http().into_body().collect().await.unwrap().to_vec())
            .unwrap()
    }

    fn bearer(token: &str) -> Request {
        Request::builder().header("authorization", &format!("Bearer {token}")).build()
    }

    #[tokio::test]
    async fn an_authenticated_request_reaches_the_handler_with_its_user() {
        let response = Pipeline::new()
            .through(Authenticate::new(manager(false)))
            .then(reveal_user)
            .run(bearer("good"))
            .await;

        assert_eq!(response.status(), StatusCode::OK);
        assert_eq!(body_of(response).await, "7");
    }

    #[tokio::test]
    async fn an_unauthenticated_request_is_rejected_before_the_handler() {
        let response = Pipeline::new()
            .through(Authenticate::new(manager(false)))
            .then(|_: Request| async { panic!("the handler must not run") })
            .run(bearer("bad"))
            .await;

        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
    }

    #[tokio::test]
    async fn a_guard_failure_is_a_500_not_a_401() {
        // Telling an authenticated user they are not sends them to a login
        // page that will also fail. Report the outage instead.
        let response = Pipeline::new()
            .through(Authenticate::new(manager(true)))
            .then(reveal_user)
            .run(bearer("good"))
            .await;

        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
    }

    #[tokio::test]
    async fn a_named_guard_can_be_selected() {
        let middleware = Authenticate::with_guard(manager(false), "api");
        let response =
            Pipeline::new().through(middleware).then(reveal_user).run(bearer("good")).await;

        assert_eq!(body_of(response).await, "7");
    }

    #[tokio::test]
    async fn an_unknown_named_guard_fails_loudly() {
        let middleware = Authenticate::with_guard(manager(false), "nope");
        let response =
            Pipeline::new().through(middleware).then(reveal_user).run(bearer("good")).await;

        assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
    }

    #[tokio::test]
    async fn the_guest_middleware_redirects_an_authenticated_user() {
        let response = Pipeline::new()
            .through(RedirectIfAuthenticated::new(manager(false), "/dashboard"))
            .then(|_: Request| async { Response::text("login form") })
            .run(bearer("good"))
            .await;

        assert_eq!(response.status(), StatusCode::FOUND);
        assert_eq!(response.header("location"), Some("/dashboard"));
    }

    #[tokio::test]
    async fn the_guest_middleware_lets_a_guest_through() {
        let response = Pipeline::new()
            .through(RedirectIfAuthenticated::new(manager(false), "/dashboard"))
            .then(|_: Request| async { Response::text("login form") })
            .run(Request::builder().build())
            .await;

        assert_eq!(body_of(response).await, "login form");
    }

    #[tokio::test]
    async fn the_guest_middleware_fails_open_to_the_login_page() {
        // If the guard is broken, blocking the login page helps nobody.
        let response = Pipeline::new()
            .through(RedirectIfAuthenticated::new(manager(true), "/dashboard"))
            .then(|_: Request| async { Response::text("login form") })
            .run(bearer("good"))
            .await;

        assert_eq!(body_of(response).await, "login form");
    }
}