mas_storage/oauth2/
access_token.rs

1// Copyright 2025, 2026 Element Creations Ltd.
2// Copyright 2024, 2025 New Vector Ltd.
3// Copyright 2021-2024 The Matrix.org Foundation C.I.C.
4//
5// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
6// Please see LICENSE files in the repository root for full details.
7
8use async_trait::async_trait;
9use chrono::{DateTime, Duration, Utc};
10use mas_data_model::{AccessToken, Clock, Session};
11use rand_core::RngCore;
12use ulid::Ulid;
13
14use crate::repository_impl;
15
16/// An [`OAuth2AccessTokenRepository`] helps interacting with [`AccessToken`]
17/// saved in the storage backend
18#[async_trait]
19pub trait OAuth2AccessTokenRepository: Send + Sync {
20    /// The error type returned by the repository
21    type Error;
22
23    /// Lookup an access token by its ID
24    ///
25    /// Returns the access token if it exists, `None` otherwise
26    ///
27    /// # Parameters
28    ///
29    /// * `id`: The ID of the access token to lookup
30    ///
31    /// # Errors
32    ///
33    /// Returns [`Self::Error`] if the underlying repository fails
34    async fn lookup(&mut self, id: Ulid) -> Result<Option<AccessToken>, Self::Error>;
35
36    /// Find an access token by its token
37    ///
38    /// Returns the access token if it exists, `None` otherwise
39    ///
40    /// # Parameters
41    ///
42    /// * `access_token`: The token of the access token to lookup
43    ///
44    /// # Errors
45    ///
46    /// Returns [`Self::Error`] if the underlying repository fails
47    async fn find_by_token(
48        &mut self,
49        access_token: &str,
50    ) -> Result<Option<AccessToken>, Self::Error>;
51
52    /// Add a new access token to the database
53    ///
54    /// Returns the newly created access token
55    ///
56    /// # Parameters
57    ///
58    /// * `rng`: A random number generator
59    /// * `clock`: The clock used to generate timestamps
60    /// * `session`: The session the access token is associated with
61    /// * `access_token`: The access token to add
62    /// * `expires_after`: The duration after which the access token expires. If
63    ///   [`None`] the access token never expires
64    ///
65    /// # Errors
66    ///
67    /// Returns [`Self::Error`] if the underlying repository fails
68    async fn add(
69        &mut self,
70        rng: &mut (dyn RngCore + Send),
71        clock: &dyn Clock,
72        session: &Session,
73        access_token: String,
74        expires_after: Option<Duration>,
75    ) -> Result<AccessToken, Self::Error>;
76
77    /// Revoke an access token
78    ///
79    /// Returns the revoked access token
80    ///
81    /// # Parameters
82    ///
83    /// * `clock`: The clock used to generate timestamps
84    /// * `access_token`: The access token to revoke
85    ///
86    /// # Errors
87    ///
88    /// Returns [`Self::Error`] if the underlying repository fails
89    async fn revoke(
90        &mut self,
91        clock: &dyn Clock,
92        access_token: AccessToken,
93    ) -> Result<AccessToken, Self::Error>;
94
95    /// Mark the access token as used, to track when it was first used
96    ///
97    /// # Parameters
98    ///
99    /// * `clock`: The clock used to generate timestamps
100    /// * `access_token`: The access token to mark as used
101    ///
102    /// # Errors
103    ///
104    /// Returns [`Self::Error`] if the underlying repository fails
105    async fn mark_used(
106        &mut self,
107        clock: &dyn Clock,
108        access_token: AccessToken,
109    ) -> Result<AccessToken, Self::Error>;
110
111    /// Cleanup revoked access tokens
112    ///
113    /// Returns the number of access tokens that were cleaned up, as well as the
114    /// timestamp of the last access token revoked
115    ///
116    /// # Parameters
117    ///
118    /// * `since`: An optional datetime since which to clean up revoked access
119    ///   tokens. This is useful to call this method multiple times in a row
120    /// * `until`: The datetime until which to clean up revoked access tokens
121    /// * `limit`: The maximum number of access tokens to clean up
122    ///
123    /// # Errors
124    ///
125    /// Returns [`Self::Error`] if the underlying repository fails
126    async fn cleanup_revoked(
127        &mut self,
128        since: Option<DateTime<Utc>>,
129        until: DateTime<Utc>,
130        limit: usize,
131    ) -> Result<(usize, Option<DateTime<Utc>>), Self::Error>;
132
133    /// Cleanup expired access tokens
134    ///
135    /// Returns the number of access tokens that were cleaned up, as well as the
136    /// timestamp of the last access token expiration
137    ///
138    /// # Parameters
139    ///
140    /// * `since`: An optional datetime since which to clean up expired access
141    ///   tokens. This is useful to call this method multiple times in a row
142    /// * `until`: The datetime until which to clean up expired access tokens
143    /// * `limit`: The maximum number of access tokens to clean up
144    ///
145    /// # Errors
146    ///
147    /// Returns [`Self::Error`] if the underlying repository fails
148    async fn cleanup_expired(
149        &mut self,
150        since: Option<DateTime<Utc>>,
151        until: DateTime<Utc>,
152        limit: usize,
153    ) -> Result<(usize, Option<DateTime<Utc>>), Self::Error>;
154}
155
156repository_impl!(OAuth2AccessTokenRepository:
157    async fn lookup(&mut self, id: Ulid) -> Result<Option<AccessToken>, Self::Error>;
158
159    async fn find_by_token(
160        &mut self,
161        access_token: &str,
162    ) -> Result<Option<AccessToken>, Self::Error>;
163
164    async fn add(
165        &mut self,
166        rng: &mut (dyn RngCore + Send),
167        clock: &dyn Clock,
168        session: &Session,
169        access_token: String,
170        expires_after: Option<Duration>,
171    ) -> Result<AccessToken, Self::Error>;
172
173    async fn revoke(
174        &mut self,
175        clock: &dyn Clock,
176        access_token: AccessToken,
177    ) -> Result<AccessToken, Self::Error>;
178
179    async fn mark_used(
180        &mut self,
181        clock: &dyn Clock,
182        access_token: AccessToken,
183    ) -> Result<AccessToken, Self::Error>;
184
185    async fn cleanup_revoked(
186        &mut self,
187        since: Option<DateTime<Utc>>,
188        until: DateTime<Utc>,
189        limit: usize,
190    ) -> Result<(usize, Option<DateTime<Utc>>), Self::Error>;
191
192    async fn cleanup_expired(
193        &mut self,
194        since: Option<DateTime<Utc>>,
195        until: DateTime<Utc>,
196        limit: usize,
197    ) -> Result<(usize, Option<DateTime<Utc>>), Self::Error>;
198);
mas_storage/oauth2/access_token.rs

mas_storage/oauth2/
access_token.rs
