Add storage for Personal Access Tokens (#5106)

Defines a token format for PATs and implements the base storage functionality for PATs and 'Personal Sessions' which are conceptually the parent containers of PATs.

Personal Sessions survive across regenerations of PATs and are the entities associated with the device ID. In virtually every way they are functionally the same as Compat or OAuth2 Sessions.

Author: reivilibre

Cargo.lock

@@ -11,6 +11,7 @@ use thiserror::Error;
 pub mod clock;
 pub(crate) mod compat;
 pub mod oauth2;
+pub mod personal;
 pub(crate) mod policy_data;
 mod site_config;
 pub(crate) mod tokens;

crates/data-model/src/lib.rs

@@ -0,0 +1,32 @@
+// Copyright 2025 New Vector Ltd.
+//
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+// Please see LICENSE files in the repository root for full details.
+
+pub mod session;
+
+use chrono::{DateTime, Utc};
+use ulid::Ulid;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PersonalAccessToken {
+    pub id: Ulid,
+    pub session_id: Ulid,
+    pub created_at: DateTime<Utc>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub revoked_at: Option<DateTime<Utc>>,
+}
+
+impl PersonalAccessToken {
+    #[must_use]
+    pub fn is_valid(&self, now: DateTime<Utc>) -> bool {
+        if self.revoked_at.is_some() {
+            return false;
+        }
+        if let Some(expires_at) = self.expires_at {
+            expires_at > now
+        } else {
+            true
+        }
+    }
+}

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

@@ -0,0 +1,132 @@
+// Copyright 2025 New Vector Ltd.
+//
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+// Please see LICENSE files in the repository root for full details.
+
+use std::net::IpAddr;
+
+use chrono::{DateTime, Utc};
+use oauth2_types::scope::Scope;
+use serde::Serialize;
+use ulid::Ulid;
+
+use crate::{Client, InvalidTransitionError, User};
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
+pub enum SessionState {
+    #[default]
+    Valid,
+    Revoked {
+        revoked_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 [`Revoked`].
+    ///
+    /// [`Revoked`]: SessionState::Revoked
+    #[must_use]
+    pub fn is_revoked(&self) -> bool {
+        matches!(self, Self::Revoked { .. })
+    }
+
+    /// Transitions the session state to [`Revoked`].
+    ///
+    /// # Parameters
+    ///
+    /// * `revoked_at` - The time at which the session was revoked.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the session state is already [`Revoked`].
+    ///
+    /// [`Revoked`]: SessionState::Revoked
+    pub fn revoke(self, revoked_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
+        match self {
+            Self::Valid => Ok(Self::Revoked { revoked_at }),
+            Self::Revoked { .. } => Err(InvalidTransitionError),
+        }
+    }
+
+    /// Returns the time the session was revoked, if any
+    ///
+    /// Returns `None` if the session is still [`Valid`].
+    ///
+    /// [`Valid`]: SessionState::Valid
+    #[must_use]
+    pub fn revoked_at(&self) -> Option<DateTime<Utc>> {
+        match self {
+            Self::Valid => None,
+            Self::Revoked { revoked_at } => Some(*revoked_at),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct PersonalSession {
+    pub id: Ulid,
+    pub state: SessionState,
+    pub owner: PersonalSessionOwner,
+    pub actor_user_id: Ulid,
+    pub human_name: String,
+    /// The scope for the session, identical to OAuth 2 sessions.
+    /// May or may not include a device scope
+    /// (personal sessions can be deviceless).
+    pub scope: Scope,
+    pub created_at: DateTime<Utc>,
+    pub last_active_at: Option<DateTime<Utc>>,
+    pub last_active_ip: Option<IpAddr>,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize)]
+pub enum PersonalSessionOwner {
+    /// The personal session is owned by the user with the given `user_id`.
+    User(Ulid),
+    /// The personal session is owned by the OAuth 2 Client with the given
+    /// `oauth2_client_id`.
+    OAuth2Client(Ulid),
+}
+
+impl<'a> From<&'a User> for PersonalSessionOwner {
+    fn from(value: &'a User) -> Self {
+        PersonalSessionOwner::User(value.id)
+    }
+}
+
+impl<'a> From<&'a Client> for PersonalSessionOwner {
+    fn from(value: &'a Client) -> Self {
+        PersonalSessionOwner::OAuth2Client(value.id)
+    }
+}
+
+impl std::ops::Deref for PersonalSession {
+    type Target = SessionState;
+
+    fn deref(&self) -> &Self::Target {
+        &self.state
+    }
+}
+
+impl PersonalSession {
+    /// Marks the session as revoked.
+    ///
+    /// # Parameters
+    ///
+    /// * `revoked_at` - The time at which the session was finished.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the session is already finished.
+    pub fn finish(mut self, revoked_at: DateTime<Utc>) -> Result<Self, InvalidTransitionError> {
+        self.state = self.state.revoke(revoked_at)?;
+        Ok(self)
+    }
+}

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

@@ -240,6 +240,9 @@ pub enum TokenType {
 
     /// A legacy refresh token
     CompatRefreshToken,
+
+    /// A personal access token.
+    PersonalAccessToken,
 }
 
 impl std::fmt::Display for TokenType {
@@ -249,6 +252,7 @@ impl std::fmt::Display for TokenType {
             TokenType::RefreshToken => write!(f, "refresh token"),
             TokenType::CompatAccessToken => write!(f, "compat access token"),
             TokenType::CompatRefreshToken => write!(f, "compat refresh token"),
+            TokenType::PersonalAccessToken => write!(f, "personal access token"),
         }
     }
 }
@@ -260,6 +264,7 @@ impl TokenType {
             TokenType::RefreshToken => "mar",
             TokenType::CompatAccessToken => "mct",
             TokenType::CompatRefreshToken => "mcr",
+            TokenType::PersonalAccessToken => "mpt",
         }
     }
 
@@ -269,6 +274,7 @@ impl TokenType {
             "mar" => Some(TokenType::RefreshToken),
             "mct" | "syt" => Some(TokenType::CompatAccessToken),
             "mcr" | "syr" => Some(TokenType::CompatRefreshToken),
+            "mpt" => Some(TokenType::PersonalAccessToken),
             _ => None,
         }
     }
@@ -335,7 +341,9 @@ impl PartialEq<OAuthTokenTypeHint> for TokenType {
         matches!(
             (self, other),
             (
-                TokenType::AccessToken | TokenType::CompatAccessToken,
+                TokenType::AccessToken
+                    | TokenType::CompatAccessToken
+                    | TokenType::PersonalAccessToken,
                 OAuthTokenTypeHint::AccessToken
             ) | (
                 TokenType::RefreshToken | TokenType::CompatRefreshToken,

crates/data-model/src/tokens.rs

@@ -24,6 +24,8 @@ static MESSAGE_QUEUE_SIZE: usize = 1000;
 enum SessionKind {
     OAuth2,
     Compat,
+    /// Session associated with personal access tokens
+    Personal,
     Browser,
 }
 
@@ -32,6 +34,7 @@ impl SessionKind {
         match self {
             SessionKind::OAuth2 => "oauth2",
             SessionKind::Compat => "compat",
+            SessionKind::Personal => "personal",
             SessionKind::Browser => "browser",
         }
     }
@@ -108,6 +111,28 @@ impl ActivityTracker {
         }
     }
 
+    /// Record activity in a personal access token session.
+    pub async fn record_personal_access_token_session(
+        &self,
+        clock: &dyn Clock,
+        session: &Session,
+        ip: Option<IpAddr>,
+    ) {
+        let res = self
+            .channel
+            .send(Message::Record {
+                kind: SessionKind::Personal,
+                id: session.id,
+                date_time: clock.now(),
+                ip,
+            })
+            .await;
+
+        if let Err(e) = res {
+            tracing::error!("Failed to record Personal session: {}", e);
+        }
+    }
+
     /// Record activity in a compat session.
     pub async fn record_compat_session(
         &self,

crates/handlers/src/activity_tracker/mod.rs

@@ -224,6 +224,7 @@ impl Worker {
         let mut browser_sessions = Vec::new();
         let mut oauth2_sessions = Vec::new();
         let mut compat_sessions = Vec::new();
+        let mut personal_sessions = Vec::new();
 
         for ((kind, id), record) in pending_records {
             match kind {
@@ -236,6 +237,9 @@ impl Worker {
                 SessionKind::Compat => {
                     compat_sessions.push((*id, record.end_time, record.ip));
                 }
+                SessionKind::Personal => {
+                    personal_sessions.push((*id, record.end_time, record.ip));
+                }
             }
         }
 
@@ -253,6 +257,7 @@ impl Worker {
         repo.compat_session()
             .record_batch_activity(compat_sessions)
             .await?;
+        // TODO: personal sessions: record
 
         repo.save().await?;
         self.pending_records.clear();

crates/handlers/src/activity_tracker/worker.rs

@@ -625,6 +625,11 @@ pub(crate) async fn post(
                 device_id: session.device.map(Device::into),
             }
         }
+
+        TokenType::PersonalAccessToken => {
+            // TODO
+            return Err(RouteError::UnknownToken(TokenType::PersonalAccessToken));
+        }
     };
 
     repo.save().await?;