feat(core): add TOTP verification to MFA endpoints

wangsijie · wangsijie · commit 68633420b41a · 2025-06-24T11:04:32.000+08:00
diff --git a/packages/core/src/routes/account/index.openapi.json b/packages/core/src/routes/account/index.openapi.json
@@ -284,22 +284,47 @@
       "post": {
         "operationId": "AddMfaVerification",
         "summary": "Add a MFA verification",
-        "description": "Add a MFA verification to the user, a logto-verification-id in header is required for checking sensitive permissions. Only WebAuthn is supported for now, a new identifier verification record is required for the webauthn registration verification.",
+        "description": "Add a MFA verification to the user, a logto-verification-id in header is required for checking sensitive permissions.",
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "properties": {
-                  "newIdentifierVerificationRecordId": {
-                    "description": "The identifier verification record ID for the new WebAuthn registration verification."
-                  },
-                  "type": {
-                    "description": "The type of the MFA verification."
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "enum": ["WebAuthn"],
+                        "description": "The type of the MFA verification."
+                      },
+                      "newIdentifierVerificationRecordId": {
+                        "type": "string",
+                        "description": "The identifier verification record ID for the new WebAuthn registration verification."
+                      },
+                      "name": {
+                        "type": "string",
+                        "description": "The name of the MFA verification, if not provided, the name will be generated from user agent."
+                      }
+                    },
+                    "required": ["type", "newIdentifierVerificationRecordId"]
                   },
-                  "name": {
-                    "description": "The name of the MFA verification, if not provided, the name will be generated from user agent."
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "enum": ["TOTP"],
+                        "description": "The type of the MFA verification, for TOTP, one user can only bind one TOTP factor."
+                      },
+                      "secret": {
+                        "type": "string",
+                        "description": "The TOTP secret for the MFA verification. Use the generate endpoint to create a secret, and verify the generated code with the user before binding to make sure the user has setup the secret in their authenticator app."
+                      }
+                    },
+                    "required": ["type", "secret"]
                   }
-                }
+                ]
               }
             }
           }
diff --git a/packages/core/src/routes/account/mfa-verifications.ts b/packages/core/src/routes/account/mfa-verifications.ts
@@ -15,7 +15,7 @@ import RequestError from '../../errors/RequestError/index.js';
 import { buildVerificationRecordByIdAndType } from '../../libraries/verification.js';
 import assertThat from '../../utils/assert-that.js';
 import { transpileUserMfaVerifications } from '../../utils/user.js';
-import { generateTotpSecret } from '../interaction/utils/totp-validation.js';
+import { generateTotpSecret, validateTotpSecret } from '../interaction/utils/totp-validation.js';
 import type { UserRouter, RouterInitArgs } from '../types.js';
 
 import { accountApiPrefix } from './constants.js';
@@ -59,11 +59,17 @@ export default function mfaVerificationsRoutes<T extends UserRouter>(
   router.post(
     `${accountApiPrefix}/mfa-verifications`,
     koaGuard({
-      body: z.object({
-        type: z.literal(MfaFactor.WebAuthn),
-        newIdentifierVerificationRecordId: z.string(),
-        name: z.string().optional(),
-      }),
+      body: z.discriminatedUnion('type', [
+        z.object({
+          type: z.literal(MfaFactor.WebAuthn),
+          newIdentifierVerificationRecordId: z.string(),
+          name: z.string().optional(),
+        }),
+        z.object({
+          type: z.literal(MfaFactor.TOTP),
+          secret: z.string(),
+        }),
+      ]),
       status: [204, 400, 401],
     }),
     async (ctx, next) => {
@@ -72,7 +78,6 @@ export default function mfaVerificationsRoutes<T extends UserRouter>(
         identityVerified,
         new RequestError({ code: 'verification_record.permission_denied', status: 401 })
       );
-      const { newIdentifierVerificationRecordId, name } = ctx.guard.body;
       const { fields } = ctx.accountCenter;
       assertThat(
         fields.mfa === AccountCenterControlValue.Edit,
@@ -84,39 +89,72 @@ export default function mfaVerificationsRoutes<T extends UserRouter>(
         new RequestError({ code: 'auth.unauthorized', status: 401 })
       );
 
-      // Check new identifier
-      const newVerificationRecord = await buildVerificationRecordByIdAndType({
-        type: VerificationType.WebAuthn,
-        id: newIdentifierVerificationRecordId,
-        queries,
-        libraries,
-      });
-      assertThat(newVerificationRecord.isVerified, 'verification_record.not_found');
-
-      const bindMfa = newVerificationRecord.toBindMfa();
+      // Feature flag check, throw 500
+      if (!EnvSet.values.isDevFeaturesEnabled && ctx.guard.body.type === MfaFactor.TOTP) {
+        throw new Error('TOTP is not supported yet');
+      }
 
       const user = await findUserById(userId);
 
-      // Check sign in experience, if webauthn is enabled
+      // Check sign in experience, if mfa factor is enabled
       const { mfa } = await findDefaultSignInExperience();
-      assertThat(
-        mfa.factors.includes(MfaFactor.WebAuthn),
-        new RequestError({ code: 'session.mfa.mfa_factor_not_enabled', status: 400 })
-      );
-
-      const updatedUser = await updateUserById(userId, {
-        mfaVerifications: [
-          ...user.mfaVerifications,
-          {
-            ...bindMfa,
-            id: generateStandardId(),
-            createdAt: new Date().toISOString(),
-            name,
-          },
-        ],
-      });
-
-      ctx.appendDataHookContext('User.Data.Updated', { user: updatedUser });
+      assertThat(mfa.factors.includes(ctx.guard.body.type), 'session.mfa.mfa_factor_not_enabled');
+
+      if (ctx.guard.body.type === MfaFactor.TOTP) {
+        // A user can only bind one TOTP factor
+        assertThat(
+          user.mfaVerifications.every(({ type }) => type !== MfaFactor.TOTP),
+          new RequestError({
+            code: 'user.totp_already_in_use',
+            status: 422,
+          })
+        );
+
+        // Check secret
+        assertThat(validateTotpSecret(ctx.guard.body.secret), 'user.totp_secret_invalid');
+
+        const updatedUser = await updateUserById(userId, {
+          mfaVerifications: [
+            ...user.mfaVerifications,
+            {
+              id: generateStandardId(),
+              createdAt: new Date().toISOString(),
+              type: MfaFactor.TOTP,
+              key: ctx.guard.body.secret,
+            },
+          ],
+        });
+
+        ctx.appendDataHookContext('User.Data.Updated', { user: updatedUser });
+
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      } else if (ctx.guard.body.type === MfaFactor.WebAuthn) {
+        const { newIdentifierVerificationRecordId, name } = ctx.guard.body;
+        // Check new identifier
+        const newVerificationRecord = await buildVerificationRecordByIdAndType({
+          type: VerificationType.WebAuthn,
+          id: newIdentifierVerificationRecordId,
+          queries,
+          libraries,
+        });
+        assertThat(newVerificationRecord.isVerified, 'verification_record.not_found');
+
+        const bindMfa = newVerificationRecord.toBindMfa();
+
+        const updatedUser = await updateUserById(userId, {
+          mfaVerifications: [
+            ...user.mfaVerifications,
+            {
+              ...bindMfa,
+              id: generateStandardId(),
+              createdAt: new Date().toISOString(),
+              name,
+            },
+          ],
+        });
+
+        ctx.appendDataHookContext('User.Data.Updated', { user: updatedUser });
+      }
 
       ctx.status = 204;
 
diff --git a/packages/integration-tests/src/api/account-center.ts b/packages/integration-tests/src/api/account-center.ts
@@ -40,6 +40,7 @@ export const enableAllAccountCenterFields = async (api: KyInstance = authedAdmin
         profile: AccountCenterControlValue.Edit,
         social: AccountCenterControlValue.Edit,
         customData: AccountCenterControlValue.Edit,
+        mfa: AccountCenterControlValue.Edit,
       },
     },
     api
diff --git a/packages/integration-tests/src/api/my-account.ts b/packages/integration-tests/src/api/my-account.ts
@@ -1,4 +1,4 @@
-import { type UserProfileResponse } from '@logto/schemas';
+import { type UserMfaVerificationResponse, type UserProfileResponse } from '@logto/schemas';
 import { type KyInstance } from 'ky';
 
 const verificationRecordIdHeader = 'logto-verification-id';
@@ -77,3 +77,16 @@ export const getUserInfo = async (api: KyInstance) =>
 
 export const generateTotpSecret = async (api: KyInstance) =>
   api.post('api/my-account/mfa-verifications/totp-secret/generate').json<{ secret: string }>();
+
+export const getMfaVerifications = async (api: KyInstance) =>
+  api.get('api/my-account/mfa-verifications').json<UserMfaVerificationResponse>();
+
+export const addMfaVerification = async (
+  api: KyInstance,
+  verificationRecordId: string,
+  body: Record<string, unknown>
+) =>
+  api.post('api/my-account/mfa-verifications', {
+    json: body,
+    headers: { [verificationRecordIdHeader]: verificationRecordId },
+  });
diff --git a/packages/integration-tests/src/tests/api/account/mfa.test.ts b/packages/integration-tests/src/tests/api/account/mfa.test.ts
@@ -2,8 +2,13 @@ import { UserScope } from '@logto/core-kit';
 import { MfaFactor } from '@logto/schemas';
 
 import { enableAllAccountCenterFields } from '#src/api/account-center.js';
-import { generateTotpSecret } from '#src/api/my-account.js';
 import {
+  addMfaVerification,
+  generateTotpSecret,
+  getMfaVerifications,
+} from '#src/api/my-account.js';
+import {
+  createVerificationRecordByPassword,
   createWebAuthnRegistrationOptions,
   verifyWebAuthnRegistration,
 } from '#src/api/verification-record.js';
@@ -46,6 +51,53 @@ describe('my-account (mfa)', () => {
     });
   });
 
+  devFeatureTest.describe('POST /my-account/mfa-verifications', () => {
+    devFeatureTest.it('should be able to add totp verification', async () => {
+      await enableAllAccountCenterFields();
+
+      const { user, username, password } = await createDefaultTenantUserWithPassword();
+      const api = await signInAndGetUserApi(username, password, {
+        scopes: [UserScope.Profile, UserScope.Identities],
+      });
+      const { secret } = await generateTotpSecret(api);
+      const verificationRecordId = await createVerificationRecordByPassword(api, password);
+
+      await addMfaVerification(api, verificationRecordId, {
+        type: MfaFactor.TOTP,
+        secret,
+      });
+      const mfaVerifications = await getMfaVerifications(api);
+
+      expect(mfaVerifications).toHaveLength(1);
+      expect(mfaVerifications[0]?.type).toBe(MfaFactor.TOTP);
+
+      await deleteDefaultTenantUser(user.id);
+    });
+
+    devFeatureTest.it('should fail if totp secret is invalid', async () => {
+      await enableAllAccountCenterFields();
+
+      const { user, username, password } = await createDefaultTenantUserWithPassword();
+      const api = await signInAndGetUserApi(username, password, {
+        scopes: [UserScope.Profile, UserScope.Identities],
+      });
+      const verificationRecordId = await createVerificationRecordByPassword(api, password);
+
+      await expectRejects(
+        addMfaVerification(api, verificationRecordId, {
+          type: MfaFactor.TOTP,
+          secret: 'invalid-totp-secret',
+        }),
+        {
+          code: 'user.totp_secret_invalid',
+          status: 400,
+        }
+      );
+
+      await deleteDefaultTenantUser(user.id);
+    });
+  });
+
   describe('POST /my-account/mfa-verifications/web-authn/registration', () => {
     it('should be able to get webauthn registration options', async () => {
       const { user, username, password } = await createDefaultTenantUserWithPassword();
