latchkey 0.3.0-dev

//! The policy settings the flows apply, built and validated once.
//!
//! ```
//! use latchkey::Config;
//! use time::Duration;
//!
//! let config = Config::builder("owner@example.com", "https://home.example.com")
//!     .session_ttl(Duration::days(14))
//!     .build()?;
//! assert_eq!(config.rp_id(), "home.example.com");
//! assert_eq!(config.origin_string(), "https://home.example.com");
//! assert_eq!(config.setup_url().as_str(), "https://home.example.com/setup");
//! # Ok::<(), latchkey::Error>(())
//! ```

use time::Duration;
use url::Url;

use crate::Error;
use crate::account::{Email, LockoutPolicy};
use crate::flow::step_up::StepUpFailures;
use crate::http::CookieName;
use crate::limits::RateLimits;
use crate::password::PasswordParams;

/// Validated settings: the origin and relying party, cookie names, mailed link targets,
/// lifetimes, the lockout and step-up failure policies and the rate-limit and password
/// parameters. Build it with
/// [`Config::builder`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Config {
    origin: Url,
    rp_id: String,
    rp_name: String,
    owner_email: Email,
    owner_name: String,
    cookie_name: CookieName,
    device_cookie_name: CookieName,
    setup_url: Url,
    sign_in_link_url: Url,
    invite_url: Url,
    sessions_url: Url,
    durations: Durations,
    lockout: LockoutPolicy,
    step_up_failures: StepUpFailures,
    rate_limits: RateLimits,
    password: PasswordParams,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Durations {
    device_ttl: Duration,
    session_ttl: Duration,
    pending_ttl: Duration,
    setup_ttl: Duration,
    link_ttl: Duration,
    invite_ttl: Duration,
    resend_cooldown: Duration,
    step_up_window: Duration,
}

impl Default for Durations {
    fn default() -> Self {
        Self {
            device_ttl: Duration::days(400),
            session_ttl: Duration::days(30),
            pending_ttl: Duration::minutes(10),
            setup_ttl: Duration::hours(1),
            link_ttl: Duration::minutes(15),
            invite_ttl: Duration::days(3),
            resend_cooldown: Duration::minutes(1),
            step_up_window: Duration::minutes(5),
        }
    }
}

/// Builds a [`Config`]; every setting has the default latchkey 0.2 used.
#[derive(Debug, Clone)]
#[must_use = "call build() to get a Config"]
pub struct ConfigBuilder {
    owner_email: String,
    origin: String,
    rp_id: Option<String>,
    rp_name: Option<String>,
    owner_name: Option<String>,
    cookie_name: String,
    device_cookie_name: String,
    setup_path: String,
    sign_in_link_path: String,
    invite_path: String,
    sessions_path: String,
    durations: Durations,
    lockout: LockoutPolicy,
    step_up_failures: StepUpFailures,
    rate_limits: RateLimits,
    password: PasswordParams,
}

macro_rules! durations {
    ($($(#[$doc:meta])* $name:ident),* $(,)?) => {
        impl ConfigBuilder {
            $(
                $(#[$doc])*
                pub fn $name(mut self, value: Duration) -> Self {
                    self.durations.$name = value;
                    self
                }
            )*
        }

        impl Config {
            $(
                $(#[$doc])*
                #[must_use]
                pub fn $name(&self) -> Duration {
                    self.durations.$name
                }
            )*
        }
    };
}

durations!(
    /// How long a device stays known after its last sign-in. Default 400 days.
    device_ttl,
    /// Lifetime of a signed-in session. Default 30 days.
    session_ttl,
    /// Lifetime of a session waiting for its second factor. Default 10 minutes.
    pending_ttl,
    /// Lifetime of a setup session. Default 1 hour.
    setup_ttl,
    /// Lifetime of a setup or sign-in link. Default 15 minutes.
    link_ttl,
    /// Lifetime of an invite link. Default 3 days.
    invite_ttl,
    /// Minimum time between two setup or sign-in links to one account. Default 1 minute.
    resend_cooldown,
    /// How long a sign-in or step-up counts as recent. Default 5 minutes.
    step_up_window,
);

impl ConfigBuilder {
    /// The relying party id for passkeys. Default: the origin's host.
    pub fn rp_id(mut self, rp_id: &str) -> Self {
        self.rp_id = Some(rp_id.to_owned());
        self
    }

    /// The name passkey prompts show. Default: the relying party id.
    pub fn rp_name(mut self, rp_name: &str) -> Self {
        self.rp_name = Some(rp_name.to_owned());
        self
    }

    /// The owner's display name. Default: the owner's address.
    pub fn owner_name(mut self, name: &str) -> Self {
        self.owner_name = Some(name.to_owned());
        self
    }

    /// The session cookie's name; must start with `__Host-`. Default `__Host-latchkey`.
    pub fn cookie_name(mut self, name: &str) -> Self {
        name.clone_into(&mut self.cookie_name);
        self
    }

    /// The device cookie's name; must start with `__Host-` and differ from the session
    /// cookie's. Default `__Host-latchkey_device`.
    pub fn device_cookie_name(mut self, name: &str) -> Self {
        name.clone_into(&mut self.device_cookie_name);
        self
    }

    /// The page that receives `?token=` from setup links, relative to the origin. Default
    /// `/setup`.
    pub fn setup_path(mut self, path: &str) -> Self {
        path.clone_into(&mut self.setup_path);
        self
    }

    /// The page for sign-in links. Default `/sign-in/link`.
    pub fn sign_in_link_path(mut self, path: &str) -> Self {
        path.clone_into(&mut self.sign_in_link_path);
        self
    }

    /// The page for invite links. Default `/invite`.
    pub fn invite_path(mut self, path: &str) -> Self {
        path.clone_into(&mut self.invite_path);
        self
    }

    /// The sessions page the new-device mail links to. Default `/settings/sessions`.
    pub fn sessions_path(mut self, path: &str) -> Self {
        path.clone_into(&mut self.sessions_path);
        self
    }

    /// The lockout policy. Default: 5 failures lock for 5 minutes, doubling up to an hour.
    pub fn lockout(mut self, lockout: LockoutPolicy) -> Self {
        self.lockout = lockout;
        self
    }

    /// Where wrong step-up guesses count. Default [`StepUpFailures::AccountLockout`], as in
    /// latchkey 0.2.
    pub fn step_up_failures(mut self, policy: StepUpFailures) -> Self {
        self.step_up_failures = policy;
        self
    }

    /// The rate limits and wrong-password throttle.
    pub fn rate_limits(mut self, rate_limits: RateLimits) -> Self {
        self.rate_limits = rate_limits;
        self
    }

    /// Argon2id parameters. Default 64 MiB, t=3, p=2.
    pub fn password(mut self, params: PasswordParams) -> Self {
        self.password = params;
        self
    }

    /// Validates everything.
    ///
    /// # Errors
    ///
    /// [`Error::Config`] when the origin is not an `https` URL (or `http://localhost`), the
    /// owner address or a cookie name is invalid, the cookie names are equal, or a path does
    /// not join onto the origin, or a [`StepUpFailures::PerSession`] limit is 0.
    /// [`Error::InvalidRequest`] with `email` for a bad owner
    /// address.
    pub fn build(self) -> Result<Config, Error> {
        let origin = Url::parse(&self.origin).map_err(|_| Error::Config("origin is not a URL"))?;
        let host = origin
            .host_str()
            .ok_or(Error::Config("origin has no host"))?
            .to_owned();
        let local = host == "localhost";
        if origin.scheme() != "https" && !local {
            return Err(Error::Config("origin must be https"));
        }
        let owner_email =
            Email::parse(&self.owner_email).map_err(|_| Error::Config("owner email"))?;
        let cookie_name = CookieName::new(&self.cookie_name)?;
        let device_cookie_name = CookieName::new(&self.device_cookie_name)?;
        if cookie_name == device_cookie_name {
            return Err(Error::Config(
                "device cookie name must differ from the cookie name",
            ));
        }
        let join = |path: &str| {
            origin
                .join(path)
                .map_err(|_| Error::Config("a path does not join onto the origin"))
        };
        if self.step_up_failures == (StepUpFailures::PerSession { limit: 0 }) {
            return Err(Error::Config(
                "the step-up failure limit must be at least 1",
            ));
        }
        let rp_id = self.rp_id.unwrap_or(host);
        Ok(Config {
            setup_url: join(&self.setup_path)?,
            sign_in_link_url: join(&self.sign_in_link_path)?,
            invite_url: join(&self.invite_path)?,
            sessions_url: join(&self.sessions_path)?,
            rp_name: self.rp_name.unwrap_or_else(|| rp_id.clone()),
            rp_id,
            owner_name: self
                .owner_name
                .unwrap_or_else(|| owner_email.as_str().to_owned()),
            owner_email,
            cookie_name,
            device_cookie_name,
            origin,
            durations: self.durations,
            lockout: self.lockout,
            step_up_failures: self.step_up_failures,
            rate_limits: self.rate_limits,
            password: self.password,
        })
    }
}

impl Config {
    /// Starts a builder for the owner's address and the single origin the app is served
    /// from, such as `https://home.example.com`.
    pub fn builder(owner_email: &str, origin: &str) -> ConfigBuilder {
        ConfigBuilder {
            owner_email: owner_email.to_owned(),
            origin: origin.to_owned(),
            rp_id: None,
            rp_name: None,
            owner_name: None,
            cookie_name: "__Host-latchkey".to_owned(),
            device_cookie_name: "__Host-latchkey_device".to_owned(),
            setup_path: "/setup".to_owned(),
            sign_in_link_path: "/sign-in/link".to_owned(),
            invite_path: "/invite".to_owned(),
            sessions_path: "/settings/sessions".to_owned(),
            durations: Durations::default(),
            lockout: LockoutPolicy::default(),
            step_up_failures: StepUpFailures::default(),
            rate_limits: RateLimits::default(),
            password: PasswordParams::default(),
        }
    }

    /// The origin.
    #[must_use]
    pub fn origin(&self) -> &Url {
        &self.origin
    }

    /// The origin as browsers send it in `Origin`, e.g. `https://home.example.com`.
    #[must_use]
    pub fn origin_string(&self) -> String {
        self.origin.origin().ascii_serialization()
    }

    /// The passkey relying party id.
    #[must_use]
    pub fn rp_id(&self) -> &str {
        &self.rp_id
    }

    /// The passkey relying party name.
    #[must_use]
    pub fn rp_name(&self) -> &str {
        &self.rp_name
    }

    /// The owner's address: setup links only ever go here.
    #[must_use]
    pub fn owner_email(&self) -> &Email {
        &self.owner_email
    }

    /// The owner's display name.
    #[must_use]
    pub fn owner_name(&self) -> &str {
        &self.owner_name
    }

    /// The session cookie's name.
    #[must_use]
    pub fn cookie_name(&self) -> &CookieName {
        &self.cookie_name
    }

    /// The device cookie's name.
    #[must_use]
    pub fn device_cookie_name(&self) -> &CookieName {
        &self.device_cookie_name
    }

    /// Where setup links point.
    #[must_use]
    pub fn setup_url(&self) -> &Url {
        &self.setup_url
    }

    /// Where sign-in links point.
    #[must_use]
    pub fn sign_in_link_url(&self) -> &Url {
        &self.sign_in_link_url
    }

    /// Where invite links point.
    #[must_use]
    pub fn invite_url(&self) -> &Url {
        &self.invite_url
    }

    /// The sessions page the new-device mail links to.
    #[must_use]
    pub fn sessions_url(&self) -> &Url {
        &self.sessions_url
    }

    /// The lockout policy.
    #[must_use]
    pub fn lockout(&self) -> &LockoutPolicy {
        &self.lockout
    }

    /// Where wrong step-up guesses count.
    #[must_use]
    pub fn step_up_failures(&self) -> StepUpFailures {
        self.step_up_failures
    }

    /// The rate limits.
    #[must_use]
    pub fn rate_limits(&self) -> &RateLimits {
        &self.rate_limits
    }

    /// The Argon2id parameters.
    #[must_use]
    pub fn password(&self) -> PasswordParams {
        self.password
    }
}

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

    #[test]
    fn defaults_match_latchkey_0_2() -> Result<(), Error> {
        let config = Config::builder("o@example.com", "https://home.example.com").build()?;
        assert_eq!(config.cookie_name().as_str(), "__Host-latchkey");
        assert_eq!(
            config.device_cookie_name().as_str(),
            "__Host-latchkey_device"
        );
        assert_eq!(config.session_ttl(), Duration::days(30));
        assert_eq!(config.step_up_window(), Duration::minutes(5));
        assert_eq!(config.link_ttl(), Duration::minutes(15));
        assert_eq!(
            config.invite_url().as_str(),
            "https://home.example.com/invite"
        );
        assert_eq!(config.owner_name(), "o@example.com");
        assert_eq!(config.rp_name(), "home.example.com");
        assert_eq!(config.step_up_failures(), StepUpFailures::AccountLockout);
        Ok(())
    }

    #[test]
    fn rejects_bad_cookie_names_and_plain_http() {
        let builder = || Config::builder("o@example.com", "https://home.example.com");
        assert!(builder().cookie_name("session").build().is_err());
        assert!(
            builder()
                .device_cookie_name("__Host-latchkey")
                .build()
                .is_err()
        );
        assert!(
            Config::builder("o@example.com", "http://home.example.com")
                .build()
                .is_err()
        );
        assert!(
            Config::builder("o@example.com", "http://localhost:3000")
                .build()
                .is_ok()
        );
        assert!(
            Config::builder("not an email", "https://h.example")
                .build()
                .is_err()
        );
        assert!(
            Config::builder("o@example.com", "not a url")
                .build()
                .is_err()
        );
        assert_eq!(
            builder()
                .step_up_failures(StepUpFailures::PerSession { limit: 0 })
                .build()
                .err(),
            Some(Error::Config(
                "the step-up failure limit must be at least 1"
            ))
        );
        assert!(
            builder()
                .step_up_failures(StepUpFailures::PerSession { limit: 5 })
                .build()
                .is_ok()
        );
    }
}