feat(auth): add support for custom verification token generation

Author: ochrstn

docs/authentication/email.mdx

@@ -32,10 +32,11 @@ export const Customers: CollectionConfig = {
 
 The following options are available:
 
-| Option                     | Description                                                                                                                                           |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`generateEmailHTML`**    | Allows for overriding the HTML within emails that are sent to users indicating how to validate their account. [More details](#generateemailhtml).     |
-| **`generateEmailSubject`** | Allows for overriding the subject of the email that is sent to users indicating how to validate their account. [More details](#generateemailsubject). |
+| Option                          | Description                                                                                                                                           |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`generateEmailHTML`**         | Allows for overriding the HTML within emails that are sent to users indicating how to validate their account. [More details](#generateemailhtml).     |
+| **`generateEmailSubject`**      | Allows for overriding the subject of the email that is sent to users indicating how to validate their account. [More details](#generateemailsubject). |
+| **`generateVerificationToken`** | Allows for overriding the verification token generation logic. [More details](#generateverificationtoken).                                            |
 
 #### generateEmailHTML
 
@@ -90,6 +91,32 @@ export const Customers: CollectionConfig = {
 }
 ```
 
+#### generateVerificationToken
+
+Function that allows for overriding the verification token generation logic. By default, Payload generates a random 40-character hex string. This function receives `{ req, user }` and must return a string that will be used as the verification token.
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const Customers: CollectionConfig = {
+  // ...
+  auth: {
+    verify: {
+      // highlight-start
+      generateVerificationToken: ({ req, user }) => {
+        return `custom-${user.id}-${Date.now()}`
+      },
+      // highlight-end
+    },
+  },
+}
+```
+
+<Banner type="info">
+  **Note:** The verification token must be unique and secure. Avoid predictable
+  patterns that could be exploited.
+</Banner>
+
 ## Forgot Password
 
 You can customize how the Forgot Password workflow operates with the following options on the `auth.forgotPassword` property:

packages/payload/src/auth/types.ts

@@ -138,6 +138,12 @@ export type ClientUser = {
 } & BaseUser
 
 export type UserSession = { createdAt: Date | string; expiresAt: Date | string; id: string }
+
+export type GenerateVerificationToken<TUser = any> = (args: {
+  req: PayloadRequest
+  user: TUser
+}) => Promise<string> | string
+
 type GenerateVerifyEmailHTML<TUser = any> = (args: {
   req: PayloadRequest
   token: string
@@ -297,13 +303,15 @@ export interface IncomingAuthType {
     | {
         generateEmailHTML?: GenerateVerifyEmailHTML
         generateEmailSubject?: GenerateVerifyEmailSubject
+        generateVerificationToken?: GenerateVerificationToken
       }
     | boolean
 }
 
 export type VerifyConfig = {
   generateEmailHTML?: GenerateVerifyEmailHTML
   generateEmailSubject?: GenerateVerifyEmailSubject
+  generateVerificationToken?: GenerateVerificationToken
 }
 
 export interface Auth

packages/payload/src/collections/operations/create.ts

@@ -252,7 +252,16 @@ export const createOperation = async <
     if (collectionConfig.auth && !collectionConfig.auth.disableLocalStrategy) {
       if (collectionConfig.auth.verify) {
         resultWithLocales._verified = Boolean(resultWithLocales._verified) || false
-        resultWithLocales._verificationToken = crypto.randomBytes(20).toString('hex')
+
+        const verify = collectionConfig.auth.verify
+        if (typeof verify === 'object' && typeof verify.generateVerificationToken === 'function') {
+          resultWithLocales._verificationToken = await verify.generateVerificationToken({
+            req,
+            user: resultWithLocales,
+          })
+        } else {
+          resultWithLocales._verificationToken = crypto.randomBytes(20).toString('hex')
+        }
       }
 
       doc = await registerLocalStrategy({

test/auth/config.ts

@@ -8,6 +8,8 @@ import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { devUser } from '../credentials.js'
 import {
   apiKeysSlug,
+  customVerificationTokenSlug,
+  expectedVerificationToken,
   namedSaveToJWTValue,
   partialDisableLocalStrategiesSlug,
   publicUsersSlug,
@@ -262,6 +264,15 @@ export default buildConfigWithDefaults({
         },
       ],
     },
+    {
+      slug: customVerificationTokenSlug,
+      auth: {
+        verify: {
+          generateVerificationToken: async () => Promise.resolve(expectedVerificationToken),
+        },
+      },
+      fields: [],
+    },
   ],
   onInit: async (payload) => {
     await payload.create({

test/auth/int.spec.ts

@@ -22,6 +22,8 @@ import { devUser } from '../credentials.js'
 import { initPayloadInt } from '../helpers/initPayloadInt.js'
 import {
   apiKeysSlug,
+  customVerificationTokenSlug,
+  expectedVerificationToken,
   namedSaveToJWTValue,
   partialDisableLocalStrategiesSlug,
   publicUsersSlug,
@@ -341,6 +343,60 @@ describe('Auth', () => {
         expect(afterToken).toBeNull()
       })
 
+      it('should allow custom verification token of a user', async () => {
+        const emailToVerify = 'verify@me.com'
+        const response = await restClient.POST(`/${customVerificationTokenSlug}`, {
+          body: JSON.stringify({
+            email: emailToVerify,
+            password,
+            roles: ['editor'],
+          }),
+          headers: {
+            Authorization: `JWT ${token}`,
+          },
+        })
+
+        expect(response.status).toBe(201)
+
+        const userResult = await payload.find({
+          collection: customVerificationTokenSlug,
+          limit: 1,
+          showHiddenFields: true,
+          where: {
+            email: {
+              equals: emailToVerify,
+            },
+          },
+        })
+
+        const { _verificationToken, _verified } = userResult.docs[0]
+
+        expect(_verified).toBe(false)
+        expect(_verificationToken).toBe(expectedVerificationToken)
+
+        const verificationResponse = await restClient.POST(
+          `/${customVerificationTokenSlug}/verify/${_verificationToken}`,
+        )
+
+        expect(verificationResponse.status).toBe(200)
+
+        const afterVerifyResult = await payload.find({
+          collection: customVerificationTokenSlug,
+          limit: 1,
+          showHiddenFields: true,
+          where: {
+            email: {
+              equals: emailToVerify,
+            },
+          },
+        })
+
+        const { _verificationToken: afterToken, _verified: afterVerified } =
+          afterVerifyResult.docs[0]
+        expect(afterVerified).toBe(true)
+        expect(afterToken).toBeNull()
+      })
+
       describe('User Preferences', () => {
         const key = 'test'
         const property = 'store'

test/auth/shared.ts

@@ -9,3 +9,7 @@ export const partialDisableLocalStrategiesSlug = 'partial-disable-local-strategi
 export const namedSaveToJWTValue = 'namedSaveToJWT value'
 
 export const saveToJWTKey = 'x-custom-jwt-property-name'
+
+export const customVerificationTokenSlug = 'custom-verification-token'
+
+export const expectedVerificationToken = 'custom-verification-token-12345'