latchkey 0.3.0

Sans-IO sign-in building blocks and policy: Argon2id passwords, TOTP, recovery codes, passkeys, tokens, sealing, cookies, lockout, rate limits and sign-in flows as pure state machines
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

//! Sign-in by an emailed single-use link (15 minutes by default), which signs in directly.
//!
//! ```text
//! Start --Request--> Requested        (answer 202 whether or not a mail went out)
//! Start --Redeem---> SignedIn
//! ```

use rand_core::CryptoRng;
use time::OffsetDateTime;

use super::{
    Client, LinkKind, LinkToken, Refusal, Transition, UNEXPECTED, complete_sign_in, send_link,
};
use crate::Error;
use crate::account::Account;
use crate::config::Config;
use crate::session::{Session, SignInMethod};

/// Where an email-link sign-in is.
// States are moved once per request; boxing the large variants would only complicate
// matching on them.
#[allow(clippy::large_enum_variant)]
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum EmailLink {
    /// Nothing yet.
    Start,
    /// The request was handled; answer the same way whether or not a link was mailed.
    Requested,
    /// Signed in.
    SignedIn {
        /// Whose.
        account: Account,
        /// The full session.
        session: Session,
    },
}

/// What happened.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum EmailLinkEvent {
    /// Someone asked for a link to an address.
    Request {
        /// The account with that address, if any.
        account: Option<Account>,
        /// When the latest unexpired sign-in link to it was issued, for the resend cooldown.
        last_sent_at: Option<OffsetDateTime>,
        /// The client.
        client: Client,
    },
    /// A link was opened and its token posted back.
    Redeem {
        /// The link record the app deleted by the token's hash, if there was one.
        link: Option<LinkToken>,
        /// The account it belongs to.
        account: Option<Account>,
        /// The client.
        client: Client,
    },
}

impl EmailLink {
    /// Applies `event`.
    ///
    /// # Errors
    ///
    /// A [`Refusal`] with [`Error::SignInFailed`] for an unknown, used, expired or
    /// wrong-kind link or an inactive account; [`Error::InvalidRequest`] for an event the
    /// state does not take.
    #[allow(clippy::too_many_lines)] // one arm per (state, event) pair
    pub fn advance<R: CryptoRng + ?Sized>(
        self,
        config: &Config,
        event: EmailLinkEvent,
        now: OffsetDateTime,
        rng: &mut R,
    ) -> Result<Transition<EmailLink>, Refusal> {
        match (self, event) {
            (
                EmailLink::Start,
                EmailLinkEvent::Request {
                    account,
                    last_sent_at,
                    client,
                },
            ) => {
                let effects = account
                    .filter(|account| account.active)
                    .map(|account| {
                        send_link(
                            config,
                            &account,
                            LinkKind::SignIn,
                            last_sent_at,
                            &client,
                            now,
                            rng,
                        )
                    })
                    .unwrap_or_default();
                Ok(Transition {
                    state: EmailLink::Requested,
                    effects,
                })
            }
            (
                EmailLink::Start,
                EmailLinkEvent::Redeem {
                    link,
                    account,
                    client,
                },
            ) => {
                let valid = |account: &Account| {
                    account.active
                        && link.is_some_and(|link| {
                            link.is_redeemable(LinkKind::SignIn, now) && link.user_id == account.id
                        })
                };
                let Some(account) = account.filter(valid) else {
                    return Err(Error::SignInFailed.into());
                };
                let (session, effects) = complete_sign_in(
                    config,
                    &account,
                    &SignInMethod::EmailLink,
                    &client,
                    None,
                    now,
                    rng,
                );
                Ok(Transition {
                    state: EmailLink::SignedIn { account, session },
                    effects,
                })
            }
            _ => Err(UNEXPECTED.into()),
        }
    }
}