WPB-22970: migrate activation-keys to PostGreSQL

changelog.d/0-release-notes/WPB-22970

@@ -0,0 +1 @@
+The background worker now cleans up expired activation keys from Postgres via a nightly cron job; new required config flag 'background-worker.config.activationKeysCleanup.schedule' (default '0 3 * * *').

changelog.d/5-internal/WPB-22970

@@ -0,0 +1 @@
+Migration of activation keys from cassandra to postgres

charts/wire-server/templates/background-worker/configmap.yaml

@@ -84,6 +84,7 @@ data:
     migrateConversationCodes: {{ .migrateConversationCodes }}
     migrateTeamFeatures: {{ .migrateTeamFeatures }}
     migrateDomainRegistration: {{ .migrateDomainRegistration }}
+    migrateActivationKeys: {{ .migrateActivationKeys }}
     migrationOptions:
 {{ toYaml .migrationOptions | indent 6 }}
 
@@ -111,6 +112,10 @@ data:
       workerStaleThreshold: {{ .jobs.workerStaleThreshold }}
     {{- with .meetingsCleanup }}
     meetingsCleanup:
+{{ toYaml . | indent 6 }}
+    {{- end }}
+    {{- with .activationKeysCleanup }}
+    activationKeysCleanup:
 {{ toYaml . | indent 6 }}
     {{- end }}
     {{- if $.Values.galley.config.postgresMigration }}

charts/wire-server/values.yaml

@@ -89,6 +89,7 @@ galley:
       conversationCodes: cassandra
       teamFeatures: cassandra
       domainRegistration: cassandra
+      activationKeys: cassandra
       user: cassandra
     settings:
       httpPoolSize: 128
@@ -1026,6 +1027,7 @@ background-worker:
     # It's important to set `settings.postgresMigration.domainRegistration` to `migration-to-postgresql`
     # before starting the migration.
     migrateDomainRegistration: false
+    migrateActivationKeys: false
 
     backendNotificationPusher:
       pushBackoffMinWait: 10000 # in microseconds, so 10ms
@@ -1075,6 +1077,10 @@ background-worker:
       # Cron schedule for the cleanup job (0 * * * * = every hour)
       schedule: "0 * * * *"
 
+    # Cleanup of expired activation keys in Postgres (nightly)
+    activationKeysCleanup:
+      schedule: "0 3 * * *"
+
   secrets: {}
 
   podSecurityContext:

docs/src/developer/reference/config-options.md

@@ -2150,13 +2150,18 @@ galley:
       conversationCodes: postgresql
       teamFeatures: postgresql
       domainRegistration: postgresql
+      activationKeys: postgresql
       user: postgresql
 background-worker:
   config:
     migrateConversations: false
     migrateConversationCodes: false
     migrateTeamFeatures: false
     migrateDomainRegistration: false
+    migrateActivationKeys: false
+    # Cleanup of expired activation keys in Postgres (nightly)
+    activationKeysCleanup:
+      schedule: "0 3 * * *"
 ```
 
 #### Migration for existing installations
@@ -2187,6 +2192,7 @@ The current settings and their background-worker flags are:
 - `conversationCodes` -> `migrateConversationCodes`
 - `teamFeatures` -> `migrateTeamFeatures`
 - `domainRegistration` -> `migrateDomainRegistration`
+- `activationKeys` -> `migrateActivationKeys`
 
 **Migration pattern per migration setting**
 
@@ -2205,13 +2211,15 @@ The current settings and their background-worker flags are:
          conversation: migration-to-postgresql
          conversationCodes: migration-to-postgresql
          teamFeatures: migration-to-postgresql
-         domainRegistration: cassandra
-   background-worker:
-     config:
-       migrateConversations: false
-       migrateConversationCodes: false
-       migrateTeamFeatures: false
-       migrateDomainRegistration: false
+        domainRegistration: cassandra
+        activationKeys: migration-to-postgresql
+  background-worker:
+    config:
+      migrateConversations: false
+      migrateConversationCodes: false
+      migrateTeamFeatures: false
+      migrateDomainRegistration: false
+      migrateActivationKeys: false
    ```
 
    This change should restart the affected pods, and new writes will follow the
@@ -2225,7 +2233,8 @@ The current settings and their background-worker flags are:
        migrateConversations: true
        migrateConversationCodes: true
        migrateTeamFeatures: true
-       migrateDomainRegistration: true
+      migrateDomainRegistration: true
+      migrateActivationKeys: true
    ```
 
    During migration, Cassandra rows are not deleted. Writes and migration share
@@ -2241,6 +2250,7 @@ The current settings and their background-worker flags are:
    - `conversationCodes`: `wire_conv_codes_migration_finished`
    - `teamFeatures`: `wire_team_features_migration_finished`
    - `domainRegistration`: `wire_domain_registration_migration_finished`
+  - `activationKeys`: `wire_activation_keys_migration_finished`
 
 3. Cut over reads and writes to PostgreSQL for the selected migration
    setting(s). This configuration must be used from now on for every new
@@ -2273,6 +2283,7 @@ The current settings and their background-worker flags are:
 - Some settings cover multiple Cassandra tables. For example,
   `postgresMigration.domainRegistration` covers `domain_registration`,
   `domain_registration_by_team`, and `domain_registration_challenge`.
+  `postgresMigration.activationKeys` covers the `activation_keys` table.
 
 ## Configure Cells
 

hack/helm_vars/common.yaml.gotmpl

@@ -18,6 +18,7 @@ conversationStore: {{ $preferredStore }}
 conversationCodesStore: {{ $preferredStore }}
 teamFeaturesStore: {{ $preferredStore }}
 domainRegistration: {{ $preferredStore }}
+activationKeysStore: {{ $preferredStore }}
 userStore: {{ $preferredStore }}
 
 {{- if (eq (env "UPLOAD_XML_S3_BASE_URL") "") }}

hack/helm_vars/wire-server/values.yaml.gotmpl

@@ -305,6 +305,7 @@ galley:
       conversationCodes: {{ .Values.conversationCodesStore }}
       teamFeatures: {{ .Values.teamFeaturesStore }}
       domainRegistration: {{ .Values.domainRegistration }}
+      activationKeys: {{ .Values.activationKeysStore }}
       user: {{ .Values.userStore }}
     settings:
       maxConvAndTeamSize: 16
@@ -685,6 +686,8 @@ background-worker:
       cleanOlderThanHours: 0.0014
       batchSize: 100
       schedule: "* * * * *"
+    activationKeysCleanup:
+      schedule: "* * * * *"
     # Cassandra clusters used by background-worker
     cassandra:
       host: {{ .Values.cassandraHost }}

integration/integration.cabal

@@ -177,6 +177,7 @@ library
     Test.Login
     Test.Meetings
     Test.MessageTimer
+    Test.Migration.ActivationKeys
     Test.Migration.Conversation
     Test.Migration.ConversationCodes
     Test.Migration.DomainRegistration

integration/test/Test/Migration/ActivationKeys.hs

@@ -0,0 +1,104 @@
+-- This file is part of the Wire Server implementation.
+--
+-- Copyright (C) 2026 Wire Swiss GmbH <opensource@wire.com>
+--
+-- This program is free software: you can redistribute it and/or modify it under
+-- the terms of the GNU Affero General Public License as published by the Free
+-- Software Foundation, either version 3 of the License, or (at your option) any
+-- later version.
+--
+-- This program is distributed in the hope that it will be useful, but WITHOUT
+-- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+-- FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+-- details.
+--
+-- You should have received a copy of the GNU Affero General Public License along
+-- with this program. If not, see <https://www.gnu.org/licenses/>.
+
+module Test.Migration.ActivationKeys where
+
+import qualified API.Brig as Brig
+import qualified API.BrigInternal as BrigI
+import API.Common (randomEmail)
+import Control.Monad.Codensity
+import Control.Monad.Reader (asks)
+import Test.Migration.Util (waitForMigration)
+import Testlib.Prelude
+import Testlib.ResourcePool
+import Text.Printf (printf)
+
+testActivationKeysMigration :: (HasCallStack) => App ()
+testActivationKeysMigration = do
+  resourcePool <- asks (.resourcePool)
+  runCodensity (acquireResources 1 resourcePool) $ \[backend] -> do
+    let domain = backend.berDomain
+
+    -- cassandra: two pending registrations
+    (k1, c1) <-
+      runCodensity (startDynamicBackend backend (conf "cassandra" False))
+        . const
+        $ newPendingActivation domain
+    (k2, c2) <-
+      runCodensity (startDynamicBackend backend (conf "cassandra" False))
+        . const
+        $ newPendingActivation domain
+
+    -- dual-write, worker off: one wrong attempt on the second registration
+    -- (retries 3 -> 2, mirrored to Postgres)
+    runCodensity (startDynamicBackend backend (conf "migration-to-postgresql" False)) . const $ do
+      wrongActivationCodeFails domain (k2, c2)
+
+    -- dual-write, worker on: copy Cassandra rows; create a fresh pending
+    -- registration
+    (k4, c4) <-
+      runCodensity (startDynamicBackend backend (conf "migration-to-postgresql" True)) . const $ do
+        waitForMigration domain counterName
+        newPendingActivation domain
+
+    -- postgresql: pre-migration codes activate from Postgres; retry state
+    -- converged; exhaustion deletes the row
+    runCodensity (startDynamicBackend backend (conf "postgresql" False)) . const $ do
+      -- code created in cassandra mode activates (copied by the worker)
+      activateCode domain (k1, c1)
+      -- code that was wrong-attempted once in dual-write activates
+      -- (mirrored writes kept Postgres in sync)
+      activateCode domain (k2, c2)
+      -- brute-force exhaustion: 3 wrong attempts decrement to 0, correct code
+      -- still works, the 4th wrong attempt deletes the row, correct then fails
+      forM_ [1 :: Int .. 3] $ \_ -> wrongActivationCodeFails domain (k4, c4)
+      activateCode domain (k4, c4)
+      wrongActivationCodeFails domain (k4, c4)
+      bindResponse (Brig.activate domain k4 c4) $ \resp -> do
+        resp.status `shouldMatchInt` 404
+        resp.json %. "label" `shouldMatch` "invalid-code"
+  where
+    -- create a pending registration for a random email, then fetch its
+    -- (key, code) via the internal API
+    newPendingActivation domain = do
+      email <- randomEmail
+      Brig.activateSend domain email Nothing >>= assertSuccess
+      bindResponse (BrigI.getActivationCode domain email) $ \resp -> do
+        resp.status `shouldMatchInt` 200
+        (,)
+          <$> (resp.json %. "key" >>= asString)
+          <*> (resp.json %. "code" >>= asString)
+
+    activateCode domain (k, c) = Brig.activate domain k c >>= assertSuccess
+
+    -- wrong code must 404 with 'invalid-code'
+    wrongActivationCodeFails domain (k, c) = do
+      let wrong = printf "%06d" $ (read @Int c + 1) `mod` 1000000
+      bindResponse (Brig.activate domain k wrong) $ \resp -> do
+        resp.status `shouldMatchInt` 404
+        resp.json %. "label" `shouldMatch` "invalid-code"
+    conf :: String -> Bool -> ServiceOverrides
+    conf db runMigration =
+      def
+        { brigCfg = setField "postgresMigration.activationKeys" db,
+          backgroundWorkerCfg =
+            setField "postgresMigration.activationKeys" db
+              >=> setField "migrateActivationKeys" runMigration
+        }
+
+    counterName :: String
+    counterName = "^wire_activation_keys_migration_finished"

libs/wire-api/src/Wire/API/Jobs.hs

@@ -50,6 +50,12 @@ type ConversationsQueueName = "conversations"
 conversationsQueueName :: Text
 conversationsQueueName = Text.pack $ symbolVal (Proxy @ConversationsQueueName)
 
+-- | The queue/table for jobs that operate on activation keys.
+type ActivationKeysQueueName = "activation-keys"
+
+activationKeysQueueName :: Text
+activationKeysQueueName = Text.pack $ symbolVal (Proxy @ActivationKeysQueueName)
+
 -- | Empty payload because the schedule itself carries all execution context.
 data MeetingsCleanupJob = MeetingsCleanupJob
   deriving stock (Eq, Generic, Show)
@@ -61,6 +67,17 @@ instance ToSchema MeetingsCleanupJob where
 instance Arbitrary MeetingsCleanupJob where
   arbitrary = pure MeetingsCleanupJob
 
+-- | Empty payload because the schedule itself carries all execution context.
+data ActivationKeysCleanupJob = ActivationKeysCleanupJob
+  deriving stock (Eq, Generic, Show)
+  deriving (ToJSON, FromJSON, S.ToSchema) via (Schema ActivationKeysCleanupJob)
+
+instance ToSchema ActivationKeysCleanupJob where
+  schema = object $ pure ActivationKeysCleanupJob
+
+instance Arbitrary ActivationKeysCleanupJob where
+  arbitrary = pure ActivationKeysCleanupJob
+
 -- | Payload for adminless deletions.
 -- Arbiter persists these payloads and workers decode them later, so changes to
 -- field names or shapes require a coordinated rollout. The origin user is
@@ -193,6 +210,47 @@ deriving via (Schema MeetingsJobPayload) instance S.ToSchema MeetingsJobPayload
 instance Arbitrary MeetingsJobPayload where
   arbitrary = MeetingsCleanup <$> arbitrary
 
+-- | Payload for the activation-keys queue.
+data ActivationKeysJobPayload
+  = ActivationKeysCleanup ActivationKeysCleanupJob
+  deriving stock (Eq, Generic, Show)
+
+data ActivationKeysJobPayloadTag
+  = ActivationKeysCleanupTag
+  deriving stock (Eq, Ord, Bounded, Enum, Show, Generic)
+  deriving (Arbitrary) via GenericUniform ActivationKeysJobPayloadTag
+
+instance ToSchema ActivationKeysJobPayloadTag where
+  schema =
+    enum @Text $
+      element "activation_keys_cleanup" ActivationKeysCleanupTag
+
+makePrisms ''ActivationKeysJobPayload
+
+activationKeysJobPayloadObjectSchema :: ObjectSchema SwaggerDoc ActivationKeysJobPayload
+activationKeysJobPayloadObjectSchema = taggedJobPayloadObjectSchema toTag toSchema
+  where
+    toTag :: ActivationKeysJobPayload -> ActivationKeysJobPayloadTag
+    toTag =
+      \case
+        ActivationKeysCleanup {} -> ActivationKeysCleanupTag
+
+    toSchema :: ActivationKeysJobPayloadTag -> ObjectSchema SwaggerDoc ActivationKeysJobPayload
+    toSchema = \case
+      ActivationKeysCleanupTag -> tag _ActivationKeysCleanup (field "data" schema)
+
+instance ToSchema ActivationKeysJobPayload where
+  schema = object activationKeysJobPayloadObjectSchema
+
+deriving via (Schema ActivationKeysJobPayload) instance FromJSON ActivationKeysJobPayload
+
+deriving via (Schema ActivationKeysJobPayload) instance ToJSON ActivationKeysJobPayload
+
+deriving via (Schema ActivationKeysJobPayload) instance S.ToSchema ActivationKeysJobPayload
+
+instance Arbitrary ActivationKeysJobPayload where
+  arbitrary = ActivationKeysCleanup <$> arbitrary
+
 -- | Payload persisted in the conversations queue. Keep the type tags and
 -- nested data shapes stable when changing job payloads.
 data ConversationsJobPayload
@@ -250,5 +308,6 @@ instance Arbitrary ConversationsJobPayload where
 -- | Registry for the jobs we expose via Arbiter.
 type JobRegistry =
   '[ Queue MeetingsQueueName MeetingsJobPayload,
-     Queue ConversationsQueueName ConversationsJobPayload
+     Queue ConversationsQueueName ConversationsJobPayload,
+     Queue ActivationKeysQueueName ActivationKeysJobPayload
    ]

libs/wire-api/src/Wire/API/User/Activation.hs

@@ -39,10 +39,12 @@ import Data.Data (Proxy (Proxy))
 import Data.OpenApi (ToParamSchema)
 import Data.OpenApi qualified as S
 import Data.Schema
+import Data.Text (pack)
 import Data.Text.Ascii
 import Imports
 import Servant (FromHttpApiData (..))
 import Wire.API.Locale
+import Wire.API.PostgresMarshall
 import Wire.API.User.Identity
 import Wire.Arbitrary (Arbitrary, GenericUniform (..))
 
@@ -76,6 +78,12 @@ instance FromHttpApiData ActivationKey where
 
 deriving instance C.Cql ActivationKey
 
+instance PostgresMarshall Text ActivationKey where
+  postgresMarshall = toText . fromActivationKey
+
+instance PostgresUnmarshall Text ActivationKey where
+  postgresUnmarshall = bimap pack ActivationKey . validateBase64Url
+
 --------------------------------------------------------------------------------
 -- ActivationCode
 
@@ -101,6 +109,12 @@ deriving instance C.Cql ActivationCode
 -- | A pair of 'ActivationKey' and 'ActivationCode' as required for activation.
 type ActivationPair = (ActivationKey, ActivationCode)
 
+instance PostgresMarshall Text ActivationCode where
+  postgresMarshall = toText . fromActivationCode
+
+instance PostgresUnmarshall Text ActivationCode where
+  postgresUnmarshall = bimap pack ActivationCode . validateBase64Url
+
 --------------------------------------------------------------------------------
 -- Activate