Data model and repository for user registration tokens

Author: sandhose

crates/data-model/src/lib.rs

@@ -50,6 +50,6 @@ pub use self::{
     users::{
         Authentication, AuthenticationMethod, BrowserSession, Password, User, UserEmail,
         UserEmailAuthentication, UserEmailAuthenticationCode, UserRecoverySession,
-        UserRecoveryTicket, UserRegistration, UserRegistrationPassword,
+        UserRecoveryTicket, UserRegistration, UserRegistrationPassword, UserRegistrationToken,
     },
 };

crates/data-model/src/users.rs

@@ -201,13 +201,60 @@ pub struct UserRegistrationPassword {
     pub version: u16,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct UserRegistrationToken {
+    pub id: Ulid,
+    pub token: String,
+    pub usage_limit: Option<u32>,
+    pub times_used: u32,
+    pub created_at: DateTime<Utc>,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub revoked_at: Option<DateTime<Utc>>,
+}
+
+impl UserRegistrationToken {
+    /// Returns `true` if the token is still valid and can be used
+    #[must_use]
+    pub fn is_valid(&self, now: DateTime<Utc>) -> bool {
+        // Check if revoked
+        if self.revoked_at.is_some() {
+            return false;
+        }
+
+        // Check if expired
+        if let Some(expires_at) = self.expires_at {
+            if now >= expires_at {
+                return false;
+            }
+        }
+
+        // Check if usage limit exceeded
+        if let Some(usage_limit) = self.usage_limit {
+            if self.times_used >= usage_limit {
+                return false;
+            }
+        }
+
+        true
+    }
+
+    /// Returns `true` if the token can still be used (not expired and under
+    /// usage limit)
+    #[must_use]
+    pub fn can_be_used(&self, now: DateTime<Utc>) -> bool {
+        self.is_valid(now)
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub struct UserRegistration {
     pub id: Ulid,
     pub username: String,
     pub display_name: Option<String>,
     pub terms_url: Option<Url>,
     pub email_authentication_id: Option<Ulid>,
+    pub user_registration_token_id: Option<Ulid>,
     pub password: Option<UserRegistrationPassword>,
     pub post_auth_action: Option<serde_json::Value>,
     pub ip_address: Option<IpAddr>,

crates/storage-pg/.sqlx/query-5133f9c5ba06201433be4ec784034d222975d084d0a9ebe7f1b6b865ab2e09ef.json

@@ -0,0 +1,57 @@
+-- Copyright 2025 New Vector Ltd.
+--
+-- SPDX-License-Identifier: AGPL-3.0-only
+-- Please see LICENSE in the repository root for full details.
+
+-- Add a table for storing user registration tokens
+CREATE TABLE "user_registration_tokens" (
+  "user_registration_token_id" UUID PRIMARY KEY,
+
+  -- The token string that users need to provide during registration
+  "token" TEXT NOT NULL UNIQUE,
+
+  -- Optional limit on how many times this token can be used
+  "usage_limit" INTEGER,
+
+  -- How many times this token has been used
+  "times_used" INTEGER NOT NULL DEFAULT 0,
+
+  -- When the token was created
+  "created_at" TIMESTAMP WITH TIME ZONE NOT NULL,
+
+  -- When the token was last used
+  "last_used_at" TIMESTAMP WITH TIME ZONE,
+
+  -- Optional expiration time for the token
+  "expires_at" TIMESTAMP WITH TIME ZONE,
+
+  -- When the token was revoked
+  "revoked_at" TIMESTAMP WITH TIME ZONE
+);
+
+-- Create a few indices on the table, as we use those for filtering
+-- They are safe to create non-concurrently, as the table is empty at this point
+CREATE INDEX "user_registration_tokens_usage_limit_idx"
+  ON "user_registration_tokens" ("usage_limit");
+  
+CREATE INDEX "user_registration_tokens_times_used_idx"
+  ON "user_registration_tokens" ("times_used");
+
+CREATE INDEX "user_registration_tokens_created_at_idx"
+  ON "user_registration_tokens" ("created_at");
+
+CREATE INDEX "user_registration_tokens_last_used_at_idx"
+  ON "user_registration_tokens" ("last_used_at");
+
+CREATE INDEX "user_registration_tokens_expires_at_idx"
+  ON "user_registration_tokens" ("expires_at");
+
+CREATE INDEX "user_registration_tokens_revoked_at_idx"
+  ON "user_registration_tokens" ("revoked_at");
+
+-- Add foreign key reference to registration tokens in user registrations
+-- A second migration will add the index for this foreign key
+ALTER TABLE "user_registrations"
+  ADD COLUMN "user_registration_token_id" UUID
+    REFERENCES "user_registration_tokens" ("user_registration_token_id")
+    ON DELETE SET NULL;