data-model: have more structs use a state machine

crates/data-model/src/compat/device.rs

@@ -1,4 +1,4 @@
-// Copyright 2022 The Matrix.org Foundation C.I.C.
+// Copyright 2023 The Matrix.org Foundation C.I.C.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -12,7 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use chrono::{DateTime, Utc};
 use oauth2_types::scope::ScopeToken;
 use rand::{
     distributions::{Alphanumeric, DistString},
@@ -20,8 +19,6 @@ use rand::{
 };
 use serde::Serialize;
 use thiserror::Error;
-use ulid::Ulid;
-use url::Url;
 
 static DEVICE_ID_LENGTH: usize = 10;
 
@@ -79,50 +76,3 @@ impl TryFrom<String> for Device {
         Ok(Self { id })
     }
 }
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
-pub struct CompatSession {
-    pub id: Ulid,
-    pub user_id: Ulid,
-    pub device: Device,
-    pub created_at: DateTime<Utc>,
-    pub finished_at: Option<DateTime<Utc>>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CompatAccessToken {
-    pub id: Ulid,
-    pub token: String,
-    pub created_at: DateTime<Utc>,
-    pub expires_at: Option<DateTime<Utc>>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CompatRefreshToken {
-    pub id: Ulid,
-    pub token: String,
-    pub created_at: DateTime<Utc>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
-pub enum CompatSsoLoginState {
-    Pending,
-    Fulfilled {
-        fulfilled_at: DateTime<Utc>,
-        session: CompatSession,
-    },
-    Exchanged {
-        fulfilled_at: DateTime<Utc>,
-        exchanged_at: DateTime<Utc>,
-        session: CompatSession,
-    },
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
-pub struct CompatSsoLogin {
-    pub id: Ulid,
-    pub redirect_uri: Url,
-    pub login_token: String,
-    pub created_at: DateTime<Utc>,
-    pub state: CompatSsoLoginState,
-}

crates/data-model/src/compat/mod.rs

@@ -0,0 +1,41 @@
+// Copyright 2022, 2023 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use chrono::{DateTime, Utc};
+use ulid::Ulid;
+
+mod device;
+mod session;
+mod sso_login;
+
+pub use self::{
+    device::Device,
+    session::{CompatSession, CompatSessionState},
+    sso_login::{CompatSsoLogin, CompatSsoLoginState},
+};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CompatAccessToken {
+    pub id: Ulid,
+    pub token: String,
+    pub created_at: DateTime<Utc>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CompatRefreshToken {
+    pub id: Ulid,
+    pub token: String,
+    pub created_at: DateTime<Utc>,
+}

crates/data-model/src/compat/session.rs

@@ -0,0 +1,79 @@
+// Copyright 2023 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use chrono::{DateTime, Utc};
+use serde::Serialize;
+use ulid::Ulid;
+
+use super::Device;
+use crate::InvalidTransitionError;
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
+pub enum CompatSessionState {
+    #[default]
+    Valid,
+    Finished {
+        finished_at: DateTime<Utc>,
+    },
+}
+
+impl CompatSessionState {
+    /// Returns `true` if the compta session state is [`Valid`].
+    ///
+    /// [`Valid`]: ComptaSessionState::Valid
+    #[must_use]
+    pub fn is_valid(&self) -> bool {
+        matches!(self, Self::Valid)
+    }
+
+    /// Returns `true` if the compta session state is [`Finished`].
+    ///
+    /// [`Finished`]: ComptaSessionState::Finished
+    #[must_use]
+    pub fn is_finished(&self) -> bool {
+        matches!(self, Self::Finished { .. })
+    }
+
+    pub fn finish(self, finished_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
+        match self {
+            Self::Valid => Ok(Self::Finished { finished_at }),
+            Self::Finished { .. } => Err(InvalidTransitionError),
+        }
+    }
+
+    #[must_use]
+    pub fn finished_at(&self) -> Option<DateTime<Utc>> {
+        match self {
+            CompatSessionState::Valid => None,
+            CompatSessionState::Finished { finished_at } => Some(*finished_at),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct CompatSession {
+    pub id: Ulid,
+    pub state: CompatSessionState,
+    pub user_id: Ulid,
+    pub device: Device,
+    pub created_at: DateTime<Utc>,
+}
+
+impl std::ops::Deref for CompatSession {
+    type Target = CompatSessionState;
+
+    fn deref(&self) -> &Self::Target {
+        &self.state
+    }
+}

crates/data-model/src/compat/sso_login.rs

@@ -0,0 +1,148 @@
+// Copyright 2023 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use chrono::{DateTime, Utc};
+use serde::Serialize;
+use ulid::Ulid;
+use url::Url;
+
+use super::CompatSession;
+use crate::InvalidTransitionError;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub enum CompatSsoLoginState {
+    Pending,
+    Fulfilled {
+        fulfilled_at: DateTime<Utc>,
+        session: CompatSession,
+    },
+    Exchanged {
+        fulfilled_at: DateTime<Utc>,
+        exchanged_at: DateTime<Utc>,
+        session: CompatSession,
+    },
+}
+
+impl CompatSsoLoginState {
+    /// Returns `true` if the compat sso login state is [`Pending`].
+    ///
+    /// [`Pending`]: CompatSsoLoginState::Pending
+    #[must_use]
+    pub fn is_pending(&self) -> bool {
+        matches!(self, Self::Pending)
+    }
+
+    /// Returns `true` if the compat sso login state is [`Fulfilled`].
+    ///
+    /// [`Fulfilled`]: CompatSsoLoginState::Fulfilled
+    #[must_use]
+    pub fn is_fulfilled(&self) -> bool {
+        matches!(self, Self::Fulfilled { .. })
+    }
+
+    /// Returns `true` if the compat sso login state is [`Exchanged`].
+    ///
+    /// [`Exchanged`]: CompatSsoLoginState::Exchanged
+    #[must_use]
+    pub fn is_exchanged(&self) -> bool {
+        matches!(self, Self::Exchanged { .. })
+    }
+
+    #[must_use]
+    pub fn fulfilled_at(&self) -> Option<DateTime<Utc>> {
+        match self {
+            Self::Pending => None,
+            Self::Fulfilled { fulfilled_at, .. } | Self::Exchanged { fulfilled_at, .. } => {
+                Some(*fulfilled_at)
+            }
+        }
+    }
+
+    #[must_use]
+    pub fn exchanged_at(&self) -> Option<DateTime<Utc>> {
+        match self {
+            Self::Pending | Self::Fulfilled { .. } => None,
+            Self::Exchanged { exchanged_at, .. } => Some(*exchanged_at),
+        }
+    }
+
+    #[must_use]
+    pub fn session(&self) -> Option<&CompatSession> {
+        match self {
+            Self::Pending => None,
+            Self::Fulfilled { session, .. } | Self::Exchanged { session, .. } => Some(session),
+        }
+    }
+
+    pub fn fulfill(
+        self,
+        fulfilled_at: DateTime<Utc>,
+        session: CompatSession,
+    ) -> Result<Self, InvalidTransitionError> {
+        match self {
+            Self::Pending => Ok(Self::Fulfilled {
+                fulfilled_at,
+                session,
+            }),
+            Self::Fulfilled { .. } | Self::Exchanged { .. } => Err(InvalidTransitionError),
+        }
+    }
+
+    pub fn exchange(self, exchanged_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
+        match self {
+            Self::Fulfilled {
+                fulfilled_at,
+                session,
+            } => Ok(Self::Exchanged {
+                fulfilled_at,
+                exchanged_at,
+                session,
+            }),
+            Self::Pending { .. } | Self::Exchanged { .. } => Err(InvalidTransitionError),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct CompatSsoLogin {
+    pub id: Ulid,
+    pub redirect_uri: Url,
+    pub login_token: String,
+    pub created_at: DateTime<Utc>,
+    pub state: CompatSsoLoginState,
+}
+
+impl std::ops::Deref for CompatSsoLogin {
+    type Target = CompatSsoLoginState;
+
+    fn deref(&self) -> &Self::Target {
+        &self.state
+    }
+}
+
+impl CompatSsoLogin {
+    pub fn fulfill(
+        mut self,
+        fulfilled_at: DateTime<Utc>,
+        session: CompatSession,
+    ) -> Result<Self, InvalidTransitionError> {
+        self.state = self.state.fulfill(fulfilled_at, session)?;
+        Ok(self)
+    }
+
+    pub fn exchange(mut self, exchanged_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
+        self.state = self.state.exchange(exchanged_at)?;
+        Ok(self)
+    }
+}

crates/data-model/src/lib.rs

@@ -1,4 +1,4 @@
-// Copyright 2021, 2022 The Matrix.org Foundation C.I.C.
+// Copyright 2021-2023 The Matrix.org Foundation C.I.C.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -37,16 +37,17 @@ pub struct InvalidTransitionError;
 
 pub use self::{
     compat::{
-        CompatAccessToken, CompatRefreshToken, CompatSession, CompatSsoLogin, CompatSsoLoginState,
-        Device,
+        CompatAccessToken, CompatRefreshToken, CompatSession, CompatSessionState, CompatSsoLogin,
+        CompatSsoLoginState, Device,
     },
     oauth2::{
         AuthorizationCode, AuthorizationGrant, AuthorizationGrantStage, Client,
-        InvalidRedirectUriError, JwksOrJwksUri, Pkce, Session,
+        InvalidRedirectUriError, JwksOrJwksUri, Pkce, Session, SessionState,
     },
     tokens::{AccessToken, RefreshToken, TokenFormatError, TokenType},
     upstream_oauth2::{
-        UpstreamOAuthAuthorizationSession, UpstreamOAuthLink, UpstreamOAuthProvider,
+        UpstreamOAuthAuthorizationSession, UpstreamOAuthAuthorizationSessionState,
+        UpstreamOAuthLink, UpstreamOAuthProvider,
     },
     users::{
         Authentication, BrowserSession, Password, User, UserEmail, UserEmailVerification,

crates/data-model/src/oauth2/mod.rs

@@ -1,4 +1,4 @@
-// Copyright 2021, 2022 The Matrix.org Foundation C.I.C.
+// Copyright 2021-2023 The Matrix.org Foundation C.I.C.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -19,5 +19,5 @@ pub(self) mod session;
 pub use self::{
     authorization_grant::{AuthorizationCode, AuthorizationGrant, AuthorizationGrantStage, Pkce},
     client::{Client, InvalidRedirectUriError, JwksOrJwksUri},
-    session::Session,
+    session::{Session, SessionState},
 };

crates/data-model/src/oauth2/session.rs

@@ -1,4 +1,4 @@
-// Copyright 2021 The Matrix.org Foundation C.I.C.
+// Copyright 2021-2023 The Matrix.org Foundation C.I.C.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -19,22 +19,69 @@ use ulid::Ulid;
 
 use crate::InvalidTransitionError;
 
+trait T {
+    type State;
+}
+
+impl T for Session {
+    type State = SessionState;
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
+pub enum SessionState {
+    #[default]
+    Valid,
+    Finished {
+        finished_at: DateTime<Utc>,
+    },
+}
+
+impl SessionState {
+    /// Returns `true` if the session state is [`Valid`].
+    ///
+    /// [`Valid`]: SessionState::Valid
+    #[must_use]
+    pub fn is_valid(&self) -> bool {
+        matches!(self, Self::Valid)
+    }
+
+    /// Returns `true` if the session state is [`Finished`].
+    ///
+    /// [`Finished`]: SessionState::Finished
+    #[must_use]
+    pub fn is_finished(&self) -> bool {
+        matches!(self, Self::Finished { .. })
+    }
+
+    pub fn finish(self, finished_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
+        match self {
+            Self::Valid => Ok(Self::Finished { finished_at }),
+            Self::Finished { .. } => Err(InvalidTransitionError),
+        }
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub struct Session {
     pub id: Ulid,
+    pub state: SessionState,
+    pub created_at: DateTime<Utc>,
     pub user_session_id: Ulid,
     pub client_id: Ulid,
     pub scope: Scope,
-    pub finished_at: Option<DateTime<Utc>>,
+}
+
+impl std::ops::Deref for Session {
+    type Target = SessionState;
+
+    fn deref(&self) -> &Self::Target {
+        &self.state
+    }
 }
 
 impl Session {
     pub fn finish(mut self, finished_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
-        if self.finished_at.is_some() {
-            return Err(InvalidTransitionError);
-        }
-
-        self.finished_at = Some(finished_at);
+        self.state = self.state.finish(finished_at)?;
         Ok(self)
     }
 }

crates/data-model/src/upstream_oauth2/link.rs

@@ -0,0 +1,26 @@
+// Copyright 2023 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use chrono::{DateTime, Utc};
+use serde::Serialize;
+use ulid::Ulid;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct UpstreamOAuthLink {
+    pub id: Ulid,
+    pub provider_id: Ulid,
+    pub user_id: Option<Ulid>,
+    pub subject: String,
+    pub created_at: DateTime<Utc>,
+}

crates/data-model/src/upstream_oauth2/mod.rs

@@ -1,4 +1,4 @@
-// Copyright 2022 The Matrix.org Foundation C.I.C.
+// Copyright 2022, 2023 The Matrix.org Foundation C.I.C.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -12,55 +12,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use chrono::{DateTime, Utc};
-use mas_iana::{jose::JsonWebSignatureAlg, oauth::OAuthClientAuthenticationMethod};
-use oauth2_types::scope::Scope;
-use serde::Serialize;
-use ulid::Ulid;
+mod link;
+mod provider;
+mod session;
 
-#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
-pub struct UpstreamOAuthProvider {
-    pub id: Ulid,
-    pub issuer: String,
-    pub scope: Scope,
-    pub client_id: String,
-    pub encrypted_client_secret: Option<String>,
-    pub token_endpoint_signing_alg: Option<JsonWebSignatureAlg>,
-    pub token_endpoint_auth_method: OAuthClientAuthenticationMethod,
-    pub created_at: DateTime<Utc>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
-pub struct UpstreamOAuthLink {
-    pub id: Ulid,
-    pub provider_id: Ulid,
-    pub user_id: Option<Ulid>,
-    pub subject: String,
-    pub created_at: DateTime<Utc>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
-pub struct UpstreamOAuthAuthorizationSession {
-    pub id: Ulid,
-    pub provider_id: Ulid,
-    pub link_id: Option<Ulid>,
-    pub state: String,
-    pub code_challenge_verifier: Option<String>,
-    pub nonce: String,
-    pub created_at: DateTime<Utc>,
-    pub completed_at: Option<DateTime<Utc>>,
-    pub consumed_at: Option<DateTime<Utc>>,
-    pub id_token: Option<String>,
-}
-
-impl UpstreamOAuthAuthorizationSession {
-    #[must_use]
-    pub const fn completed(&self) -> bool {
-        self.completed_at.is_some()
-    }
-
-    #[must_use]
-    pub const fn consumed(&self) -> bool {
-        self.consumed_at.is_some()
-    }
-}
+pub use self::{
+    link::UpstreamOAuthLink,
+    provider::UpstreamOAuthProvider,
+    session::{UpstreamOAuthAuthorizationSession, UpstreamOAuthAuthorizationSessionState},
+};

crates/data-model/src/upstream_oauth2/provider.rs

@@ -0,0 +1,31 @@
+// Copyright 2023 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use chrono::{DateTime, Utc};
+use mas_iana::{jose::JsonWebSignatureAlg, oauth::OAuthClientAuthenticationMethod};
+use oauth2_types::scope::Scope;
+use serde::Serialize;
+use ulid::Ulid;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct UpstreamOAuthProvider {
+    pub id: Ulid,
+    pub issuer: String,
+    pub scope: Scope,
+    pub client_id: String,
+    pub encrypted_client_secret: Option<String>,
+    pub token_endpoint_signing_alg: Option<JsonWebSignatureAlg>,
+    pub token_endpoint_auth_method: OAuthClientAuthenticationMethod,
+    pub created_at: DateTime<Utc>,
+}

crates/data-model/src/upstream_oauth2/session.rs

@@ -0,0 +1,170 @@
+// Copyright 2023 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use chrono::{DateTime, Utc};
+use serde::Serialize;
+use ulid::Ulid;
+
+use super::UpstreamOAuthLink;
+use crate::InvalidTransitionError;
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
+pub enum UpstreamOAuthAuthorizationSessionState {
+    #[default]
+    Pending,
+    Completed {
+        completed_at: DateTime<Utc>,
+        link_id: Ulid,
+        id_token: Option<String>,
+    },
+    Consumed {
+        completed_at: DateTime<Utc>,
+        consumed_at: DateTime<Utc>,
+        link_id: Ulid,
+        id_token: Option<String>,
+    },
+}
+
+impl UpstreamOAuthAuthorizationSessionState {
+    pub fn complete(
+        self,
+        completed_at: DateTime<Utc>,
+        link: &UpstreamOAuthLink,
+        id_token: Option<String>,
+    ) -> Result<Self, InvalidTransitionError> {
+        match self {
+            Self::Pending => Ok(Self::Completed {
+                completed_at,
+                link_id: link.id,
+                id_token,
+            }),
+            Self::Completed { .. } | Self::Consumed { .. } => Err(InvalidTransitionError),
+        }
+    }
+
+    pub fn consume(self, consumed_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
+        match self {
+            Self::Completed {
+                completed_at,
+                link_id,
+                id_token,
+            } => Ok(Self::Consumed {
+                completed_at,
+                link_id,
+                consumed_at,
+                id_token,
+            }),
+            Self::Pending | Self::Consumed { .. } => Err(InvalidTransitionError),
+        }
+    }
+
+    #[must_use]
+    pub fn link_id(&self) -> Option<Ulid> {
+        match self {
+            Self::Pending => None,
+            Self::Completed { link_id, .. } | Self::Consumed { link_id, .. } => Some(*link_id),
+        }
+    }
+
+    #[must_use]
+    pub fn completed_at(&self) -> Option<DateTime<Utc>> {
+        match self {
+            Self::Pending => None,
+            Self::Completed { completed_at, .. } | Self::Consumed { completed_at, .. } => {
+                Some(*completed_at)
+            }
+        }
+    }
+
+    #[must_use]
+    pub fn id_token(&self) -> Option<&str> {
+        match self {
+            Self::Pending => None,
+            Self::Completed { id_token, .. } | Self::Consumed { id_token, .. } => {
+                id_token.as_deref()
+            }
+        }
+    }
+
+    #[must_use]
+    pub fn consumed_at(&self) -> Option<DateTime<Utc>> {
+        match self {
+            Self::Pending | Self::Completed { .. } => None,
+            Self::Consumed { consumed_at, .. } => Some(*consumed_at),
+        }
+    }
+
+    /// Returns `true` if the upstream oauth authorization session state is
+    /// [`Pending`].
+    ///
+    /// [`Pending`]: UpstreamOAuthAuthorizationSessionState::Pending
+    #[must_use]
+    pub fn is_pending(&self) -> bool {
+        matches!(self, Self::Pending)
+    }
+
+    /// Returns `true` if the upstream oauth authorization session state is
+    /// [`Completed`].
+    ///
+    /// [`Completed`]: UpstreamOAuthAuthorizationSessionState::Completed
+    #[must_use]
+    pub fn is_completed(&self) -> bool {
+        matches!(self, Self::Completed { .. })
+    }
+
+    /// Returns `true` if the upstream oauth authorization session state is
+    /// [`Consumed`].
+    ///
+    /// [`Consumed`]: UpstreamOAuthAuthorizationSessionState::Consumed
+    #[must_use]
+    pub fn is_consumed(&self) -> bool {
+        matches!(self, Self::Consumed { .. })
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct UpstreamOAuthAuthorizationSession {
+    pub id: Ulid,
+    pub state: UpstreamOAuthAuthorizationSessionState,
+    pub provider_id: Ulid,
+    pub state_str: String,
+    pub code_challenge_verifier: Option<String>,
+    pub nonce: String,
+    pub created_at: DateTime<Utc>,
+}
+
+impl std::ops::Deref for UpstreamOAuthAuthorizationSession {
+    type Target = UpstreamOAuthAuthorizationSessionState;
+
+    fn deref(&self) -> &Self::Target {
+        &self.state
+    }
+}
+
+impl UpstreamOAuthAuthorizationSession {
+    pub fn complete(
+        mut self,
+        completed_at: DateTime<Utc>,
+        link: &UpstreamOAuthLink,
+        id_token: Option<String>,
+    ) -> Result<Self, InvalidTransitionError> {
+        self.state = self.state.complete(completed_at, link, id_token)?;
+        Ok(self)
+    }
+
+    pub fn consume(mut self, consumed_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
+        self.state = self.state.consume(consumed_at)?;
+        Ok(self)
+    }
+}