refactor(core): implement verification records map (#6289)

* refactor(core): implement verificaiton records map

implement verification records map

* fix(core): fix invalid verification type error

fix invalid verificaiton type error

* fix(core): update the verification record map

update the verification record map

* fix(core): update some comments

update some comments

* refactor(core): polish promise dependency

polish promise dependency

* fix(core): fix the social/sso syncing profile logic

fix the social/sso syncing profile logic

* refactor(core): optimize the verification records map

optimize the verification records map

* fix(core): fix set method of VerificationRecord map
fix set method of VerificationRecord map

packages/core/src/routes/experience/classes/experience-interaction.ts

@@ -1,5 +1,5 @@
 import { type ToZodObject } from '@logto/connector-kit';
-import { InteractionEvent, type User, type VerificationType } from '@logto/schemas';
+import { InteractionEvent, type User } from '@logto/schemas';
 import { conditional } from '@silverhand/essentials';
 import { z } from 'zod';
 
@@ -24,7 +24,9 @@ import {
  verificationRecordDataGuard,
  type VerificationRecord,
  type VerificationRecordData,
+ type VerificationRecordMap,
 } from './verifications/index.js';
+import { VerificationRecordsMap } from './verifications/verification-records-map.js';
 
 type InteractionStorage = {
  interactionEvent?: InteractionEvent;
@@ -52,7 +54,7 @@ export default class ExperienceInteraction {
  public readonly provisionLibrary: ProvisionLibrary;
 
  /** The user verification record list for the current interaction. */
- private readonly verificationRecords = new Map<VerificationType, VerificationRecord>();
+ private readonly verificationRecords = new VerificationRecordsMap();
  /** The userId of the user for the current interaction. Only available once the user is identified. */
  private userId?: string;
  private userCache?: User;
@@ -101,7 +103,7 @@ export default class ExperienceInteraction {
 
  for (const record of verificationRecords) {
  const instance = buildVerificationRecord(libraries, queries, record);
- this.verificationRecords.set(instance.type, instance);
+ this.verificationRecords.setValue(instance);
  }
  }
 
@@ -182,13 +184,21 @@ export default class ExperienceInteraction {
  * If a record with the same type already exists, it will be replaced.
  */
  public setVerificationRecord(record: VerificationRecord) {
- const { type } = record;
-
- this.verificationRecords.set(type, record);
+ this.verificationRecords.setValue(record);
  }
 
- public getVerificationRecordById(verificationId: string) {
- return this.verificationRecordsArray.find((record) => record.id === verificationId);
+ public getVerificationRecordByTypeAndId<K extends keyof VerificationRecordMap>(
+ type: K,
+ verificationId: string
+ ): VerificationRecordMap[K] {
+ const record = this.verificationRecords.get(type);
+
+ assertThat(
+ record?.id === verificationId,
+ new RequestError({ code: 'session.verification_session_not_found', status: 404 })
+ );
+
+ return record;
  }
 
  /**
@@ -298,7 +308,7 @@ export default class ExperienceInteraction {
  }
 
  private get verificationRecordsArray() {
- return [...this.verificationRecords.values()];
+ return this.verificationRecords.array();
  }
 
  /**
@@ -389,4 +399,8 @@ export default class ExperienceInteraction {
  this.userCache = user;
  return this.userCache;
  }
+
+ private getVerificationRecordById(verificationId: string) {
+ return this.verificationRecordsArray.find((record) => record.id === verificationId);
+ }
 }

packages/core/src/routes/experience/classes/helpers.ts

@@ -16,8 +16,8 @@ import type { InteractionProfile } from '../types.js';
 import { type VerificationRecord } from './verifications/index.js';
 
 /**
- * @throws {RequestError} -400 if the verification record type is not supported for user creation.
- * @throws {RequestError} -400 if the verification record is not verified.
+ * @throws {RequestError} with status 400 if the verification record type is not supported for user creation.
+ * @throws {RequestError} with status 400 if the verification record is not verified.
  */
 export const getNewUserProfileFromVerificationRecord = async (
  verificationRecord: VerificationRecord
@@ -30,8 +30,13 @@ export const getNewUserProfileFromVerificationRecord = async (
  }
  case VerificationType.EnterpriseSso:
  case VerificationType.Social: {
- const identityProfile = await verificationRecord.toUserProfile();
- const syncedProfile = await verificationRecord.toSyncedProfile(true);
+ const [identityProfile, syncedProfile] = await Promise.all([
+ verificationRecord.toUserProfile(),
+ // Set `isNewUser` to true to specify syncing profile from the
+ // social/enterprise SSO identity for a new user.
+ verificationRecord.toSyncedProfile(true),
+ ]);
+
  return { ...identityProfile, ...syncedProfile };
  }
  default: {
@@ -95,8 +100,9 @@ export const identifyUserByVerificationRecord = async (
  // Auto fallback to identify the related user if the user does not exist for enterprise SSO.
  if (error instanceof RequestError && error.code === 'user.identity_not_exist') {
  const user = await verificationRecord.identifyRelatedUser();
+
  const syncedProfile = {
- ...(await verificationRecord.toUserProfile()),
+ ...verificationRecord.toUserProfile(),
  ...(await verificationRecord.toSyncedProfile()),
  };
  return { user, syncedProfile };

packages/core/src/routes/experience/classes/validators/provision-library.ts

@@ -43,7 +43,7 @@ export class ProvisionLibrary {
  /**
  * Insert a new user into the Logto database using the provided profile.
  *
- * - provision the organization for the new user based on the profile
+ * - Provision the organization for the new user based on the profile
  * - OSS only, new user provisioning
  */
  async provisionNewUser(profile: InteractionProfile) {

packages/core/src/routes/experience/classes/verifications/enterprise-sso-verification.ts

@@ -173,7 +173,7 @@ export class EnterpriseSsoVerification
  /**
  * Returns the use SSO identity as a new user profile.
  */
- async toUserProfile(): Promise<Required<Pick<InteractionProfile, 'enterpriseSsoIdentity'>>> {
+ toUserProfile(): Required<Pick<InteractionProfile, 'enterpriseSsoIdentity'>> {
  assertThat(
  this.enterpriseSsoUserInfo && this.issuer,
  new RequestError({ code: 'session.verification_failed', status: 400 })

packages/core/src/routes/experience/classes/verifications/index.ts

@@ -41,6 +41,7 @@ import {
  totpVerificationRecordDataGuard,
  type TotpVerificationRecordData,
 } from './totp-verification.js';
+import { type VerificationRecord as GenericVerificationRecord } from './verification-record.js';
 
 export type VerificationRecordData =
  | PasswordVerificationRecordData
@@ -52,23 +53,33 @@ export type VerificationRecordData =
  | BackupCodeVerificationRecordData
  | NewPasswordIdentityVerificationRecordData;
 
+// This is to ensure the keys of the map are the same as the type of the verification record
+type VerificationRecordInterfaceMap = {
+ [K in VerificationType]?: GenericVerificationRecord<K>;
+};
+type AssertVerificationMap<T extends VerificationRecordInterfaceMap> = T;
+
+export type VerificationRecordMap = AssertVerificationMap<{
+ [VerificationType.Password]: PasswordVerification;
+ [VerificationType.EmailVerificationCode]: EmailCodeVerification;
+ [VerificationType.PhoneVerificationCode]: PhoneCodeVerification;
+ [VerificationType.Social]: SocialVerification;
+ [VerificationType.EnterpriseSso]: EnterpriseSsoVerification;
+ [VerificationType.TOTP]: TotpVerification;
+ [VerificationType.BackupCode]: BackupCodeVerification;
+ [VerificationType.NewPasswordIdentity]: NewPasswordIdentityVerification;
+}>;
+
+type ValueOf<T> = T[keyof T];
 /**
  * Union type for all verification record types
  *
- * @remark This is a discriminated union type.
- * The VerificationRecord generic class can not narrow down the type of a verification record instance by its type property.
+ * @remarks This is a discriminated union type.
+ * The `VerificationRecord` generic class can not narrow down the type of a verification record instance by its type property.
  * This union type is used to narrow down the type of the verification record.
- * Used in the ExperienceInteraction class to store and manage all the verification records. With a given verification type, we can narrow down the type of the verification record.
+ * Used in the `ExperienceInteraction` class to store and manage all the verification records. With a given verification type, we can narrow down the type of the verification record.
  */
-export type VerificationRecord =
- | PasswordVerification
- | EmailCodeVerification
- | PhoneCodeVerification
- | SocialVerification
- | EnterpriseSsoVerification
- | TotpVerification
- | BackupCodeVerification
- | NewPasswordIdentityVerification;
+export type VerificationRecord = ValueOf<VerificationRecordMap>;
 
 export const verificationRecordDataGuard = z.discriminatedUnion('type', [
  passwordVerificationRecordDataGuard,

packages/core/src/routes/experience/classes/verifications/verification-records-map.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview
+ *
+ * Since `Map` in TS does not support key value type mapping,
+ * we have to manually define a `setValue` method to ensure correct key will be set
+ * This class is used to store and manage all the verification records.
+ *
+ * Extends the Map class and adds a `setValue` method to ensure the key value type mapping.
+ */
+
+import { type VerificationType } from '@logto/schemas';
+
+import { type VerificationRecord, type VerificationRecordMap } from './index.js';
+
+export class VerificationRecordsMap extends Map<VerificationType, VerificationRecord> {
+ setValue(value: VerificationRecord) {
+ return super.set(value.type, value);
+ }
+
+ override get<K extends keyof VerificationRecordMap>(
+ key: K
+ ): VerificationRecordMap[K] | undefined {
+ // eslint-disable-next-line no-restricted-syntax
+ return super.get(key) as VerificationRecordMap[K] | undefined;
+ }
+
+ override set(): never {
+ throw new Error('Use `setValue` method to set the value');
+ }
+
+ array(): VerificationRecord[] {
+ return [...this.values()];
+ }
+}

packages/core/src/routes/experience/verification-routes/enterprise-sso-verification.ts

@@ -80,12 +80,13 @@ export default function enterpriseSsoVerificationRoutes<T extends WithLogContext
  const { connectorData, verificationId } = ctx.guard.body;
 
  const enterpriseSsoVerificationRecord =
- ctx.experienceInteraction.getVerificationRecordById(verificationId);
+ ctx.experienceInteraction.getVerificationRecordByTypeAndId(
+ VerificationType.EnterpriseSso,
+ verificationId
+ );
 
  assertThat(
- enterpriseSsoVerificationRecord &&
- enterpriseSsoVerificationRecord.type === VerificationType.EnterpriseSso &&
- enterpriseSsoVerificationRecord.connectorId === connectorId,
+ enterpriseSsoVerificationRecord.connectorId === connectorId,
  new RequestError({ code: 'session.verification_session_not_found', status: 404 })
  );
 

packages/core/src/routes/experience/verification-routes/social-verification.ts

@@ -75,13 +75,13 @@ export default function socialVerificationRoutes<T extends WithLogContext>(
  const { connectorId } = ctx.params;
  const { connectorData, verificationId } = ctx.guard.body;
 
- const socialVerificationRecord =
- ctx.experienceInteraction.getVerificationRecordById(verificationId);
+ const socialVerificationRecord = ctx.experienceInteraction.getVerificationRecordByTypeAndId(
+ VerificationType.Social,
+ verificationId
+ );
 
  assertThat(
- socialVerificationRecord &&
- socialVerificationRecord.type === VerificationType.Social &&
- socialVerificationRecord.connectorId === connectorId,
+ socialVerificationRecord.connectorId === connectorId,
  new RequestError({ code: 'session.verification_session_not_found', status: 404 })
  );
 

packages/core/src/routes/experience/verification-routes/totp-verification.ts

@@ -75,13 +75,13 @@ export default function totpVerificationRoutes<T extends WithLogContext>(
 
  // Verify new generated secret
  if (verificationId) {
- const totpVerificationRecord =
- experienceInteraction.getVerificationRecordById(verificationId);
+ const totpVerificationRecord = experienceInteraction.getVerificationRecordByTypeAndId(
+ VerificationType.TOTP,
+ verificationId
+ );
 
  assertThat(
- totpVerificationRecord &&
- totpVerificationRecord.type === VerificationType.TOTP &&
- totpVerificationRecord.userId === experienceInteraction.identifiedUserId,
+ totpVerificationRecord.userId === experienceInteraction.identifiedUserId,
  new RequestError({
  code: 'session.verification_session_not_found',
  status: 404,

packages/core/src/routes/experience/verification-routes/verification-code.ts

@@ -2,11 +2,9 @@ import { InteractionEvent, verificationCodeIdentifierGuard } from '@logto/schema
 import type Router from 'koa-router';
 import { z } from 'zod';
 
-import RequestError from '#src/errors/RequestError/index.js';
 import { type WithLogContext } from '#src/middleware/koa-audit-log.js';
 import koaGuard from '#src/middleware/koa-guard.js';
 import type TenantContext from '#src/tenants/TenantContext.js';
-import assertThat from '#src/utils/assert-that.js';
 
 import { codeVerificationIdentifierRecordTypeMap } from '../classes/utils.js';
 import { createNewCodeVerificationRecord } from '../classes/verifications/code-verification.js';
@@ -71,14 +69,9 @@ export default function verificationCodeRoutes<T extends WithLogContext>(
  async (ctx, next) => {
  const { verificationId, code, identifier } = ctx.guard.body;
 
- const codeVerificationRecord =
- ctx.experienceInteraction.getVerificationRecordById(verificationId);
-
- assertThat(
- codeVerificationRecord &&
- // Make the Verification type checker happy
- codeVerificationRecord.type === codeVerificationIdentifierRecordTypeMap[identifier.type],
- new RequestError({ code: 'session.verification_session_not_found', status: 404 })
+ const codeVerificationRecord = ctx.experienceInteraction.getVerificationRecordByTypeAndId(
+ codeVerificationIdentifierRecordTypeMap[identifier.type],
+ verificationId
  );
 
  await codeVerificationRecord.verify(identifier, code);