feat: add phone number validation to user APIs (#5882)

Author: darcyYe

.changeset/big-games-deny.md

@@ -0,0 +1,9 @@
+---
+"@logto/integration-tests": minor
+"@logto/experience": minor
+"@logto/console": minor
+"@logto/shared": minor
+"@logto/core": minor
+---
+
+add phone number validation and parsing to ensure the correct format when updating an existing user’s primary phone number or creating a new user with a phone number

packages/console/package.json

@@ -80,7 +80,7 @@
     "jest-transformer-svg": "^2.0.0",
     "just-kebab-case": "^4.2.0",
     "ky": "^1.2.3",
-    "libphonenumber-js": "^1.10.51",
+    "libphonenumber-js": "^1.12.6",
     "lint-staged": "^15.0.0",
     "mermaid": "^10.9.1",
     "nanoid": "^5.0.9",

packages/console/src/pages/UserDetails/UserSettings/index.tsx

@@ -2,7 +2,7 @@ import { emailRegEx, usernameRegEx } from '@logto/core-kit';
 import type { User } from '@logto/schemas';
 import { parsePhoneNumber } from '@logto/shared/universal';
 import { conditionalString, trySafe } from '@silverhand/essentials';
-import { parsePhoneNumberWithError } from 'libphonenumber-js';
+import { parsePhoneNumberWithError } from 'libphonenumber-js/mobile';
 import { useForm, useController } from 'react-hook-form';
 import { toast } from 'react-hot-toast';
 import { Trans, useTranslation } from 'react-i18next';

packages/core/src/libraries/user.ts

@@ -1,11 +1,11 @@
 import type { BindMfa, CreateUser, Scope, User } from '@logto/schemas';
-import { RoleType, Users, UsersPasswordEncryptionMethod } from '@logto/schemas';
-import { generateStandardId, generateStandardShortId } from '@logto/shared';
-import { condArray, deduplicateByKey, type Nullable } from '@silverhand/essentials';
+import { RoleType, UsersPasswordEncryptionMethod } from '@logto/schemas';
+import { generateStandardShortId, generateStandardId } from '@logto/shared';
+import type { Nullable } from '@silverhand/essentials';
+import { deduplicateByKey, condArray } from '@silverhand/essentials';
 import { argon2Verify, bcryptVerify, md5, sha1, sha256 } from 'hash-wasm';
 import pRetry from 'p-retry';
 
-import { buildInsertIntoWithPool } from '#src/database/insert-into.js';
 import { EnvSet } from '#src/env-set/index.js';
 import RequestError from '#src/errors/RequestError/index.js';
 import { type JitOrganization } from '#src/queries/organization/email-domains.js';
@@ -33,6 +33,7 @@ export const createUserLibrary = (queries: Queries) => {
       hasUserWithIdentity,
       findUsersByIds,
       updateUserById,
+      insertUser: insertUserQuery,
       findUserById,
     },
     usersRoles: { findUsersRolesByRoleId, findUsersRolesByUserId },
@@ -70,10 +71,6 @@ export const createUserLibrary = (queries: Queries) => {
     assertThat(parameterRoles.length === roleNames.length, 'role.default_role_missing');
 
     return pool.transaction(async (connection) => {
-      const insertUserQuery = buildInsertIntoWithPool(connection)(Users, {
-        returning: true,
-      });
-
       const user = await insertUserQuery(data);
       const roles = deduplicateByKey([...parameterRoles, ...defaultRoles], 'id');
 

packages/core/src/queries/user.ts

@@ -1,7 +1,7 @@
 import type { User, CreateUser } from '@logto/schemas';
 import { Users } from '@logto/schemas';
 import { PhoneNumberParser } from '@logto/shared';
-import { conditionalArray, type Nullable, pick } from '@silverhand/essentials';
+import { cond, conditionalArray, type Nullable, pick } from '@silverhand/essentials';
 import type { CommonQueryMethods } from '@silverhand/slonik';
 import { sql } from '@silverhand/slonik';
 
@@ -12,6 +12,9 @@ import type { Search } from '#src/utils/search.js';
 import { buildConditionsFromSearch } from '#src/utils/search.js';
 import type { OmitAutoSetFields } from '#src/utils/sql.js';
 import { conditionalSql, convertToIdentifiers } from '#src/utils/sql.js';
+import { validatePhoneNumber } from '#src/utils/user.js';
+
+import { buildInsertIntoWithPool } from '../database/insert-into.js';
 
 const { table, fields } = convertToIdentifiers(Users);
 
@@ -337,7 +340,43 @@ export const createUserQueries = (pool: CommonQueryMethods) => {
     id: string,
     set: Partial<OmitAutoSetFields<CreateUser>>,
     jsonbMode: 'replace' | 'merge' = 'merge'
-  ) => updateUser({ set, where: { id }, jsonbMode });
+  ) => {
+    if (set.primaryPhone) {
+      validatePhoneNumber(set.primaryPhone);
+    }
+
+    return updateUser({
+      set: {
+        ...set,
+        ...cond(
+          set.primaryPhone && {
+            primaryPhone: new PhoneNumberParser(set.primaryPhone).internationalNumber,
+          }
+        ),
+      },
+      where: { id },
+      jsonbMode,
+    });
+  };
+
+  const insertUserQuery = buildInsertIntoWithPool(pool)(Users, {
+    returning: true,
+  });
+
+  const insertUser = async (data: OmitAutoSetFields<CreateUser>) => {
+    if (data.primaryPhone) {
+      validatePhoneNumber(data.primaryPhone);
+    }
+
+    return insertUserQuery({
+      ...data,
+      ...cond(
+        data.primaryPhone && {
+          primaryPhone: new PhoneNumberParser(data.primaryPhone).internationalNumber,
+        }
+      ),
+    });
+  };
 
   const deleteUserById = async (id: string) => {
     const { rowCount } = await pool.query(sql`
@@ -395,6 +434,7 @@ export const createUserQueries = (pool: CommonQueryMethods) => {
     findUsers,
     findUsersByIds,
     updateUserById,
+    insertUser,
     deleteUserById,
     deleteUserIdentity,
     hasActiveUsers,

packages/core/src/routes/admin-user/mfa-verifications.test.ts

@@ -38,17 +38,20 @@ await mockEsmWithActual('../interaction/utils/backup-code-validation.js', () =>
   generateBackupCodes: jest.fn().mockReturnValue(['code']),
 }));
 
-const usersLibraries = {
-  generateUserId: jest.fn(async () => 'fooId'),
-  insertUser: jest.fn(
-    async (user: CreateUser): Promise<InsertUserResult> => [
-      {
-        ...mockUser,
-        ...removeUndefinedKeys(user), // No undefined values will be returned from database
-      },
-    ]
-  ),
-} satisfies Partial<Libraries['users']>;
+const mockLibraries = {
+  users: {
+    generateUserId: jest.fn(async () => 'fooId'),
+    insertUser: jest.fn(
+      async (user: CreateUser): Promise<InsertUserResult> => [
+        {
+          ...mockUser,
+          ...removeUndefinedKeys(user), // No undefined values will be returned from database
+        },
+      ]
+    ),
+    addUserMfaVerification: jest.fn(),
+  },
+} satisfies Partial2<Libraries>;
 
 const codes = [
   'd94c2f29ae',
@@ -66,9 +69,7 @@ const codes = [
 const adminUserRoutes = await pickDefault(import('./mfa-verifications.js'));
 
 describe('adminUserRoutes', () => {
-  const tenantContext = new MockTenant(undefined, mockedQueries, undefined, {
-    users: usersLibraries,
-  });
+  const tenantContext = new MockTenant(undefined, mockedQueries, undefined, mockLibraries);
   const userRequest = createRequester({ authedRoutes: adminUserRoutes, tenantContext });
 
   afterEach(() => {

packages/core/src/routes/interaction/utils/single-sign-on.ts

@@ -18,7 +18,6 @@ import { type WithLogContext } from '#src/middleware/koa-audit-log.js';
 import SamlConnector from '#src/sso/SamlConnector/index.js';
 import { ssoConnectorFactories, type SingleSignOnConnectorSession } from '#src/sso/index.js';
 import { type ExtendedSocialUserInfo } from '#src/sso/types/saml.js';
-import type Queries from '#src/tenants/Queries.js';
 import type TenantContext from '#src/tenants/TenantContext.js';
 import assertThat from '#src/utils/assert-that.js';
 import { safeParseUnknownJson } from '#src/utils/json.js';
@@ -223,7 +222,7 @@ export const handleSsoAuthentication = async (
 
   // SignIn
   if (userSsoIdentity) {
-    return signInWithSsoAuthentication(ctx, queries, {
+    return signInWithSsoAuthentication(ctx, tenant, {
       connectorData,
       userSsoIdentity,
       ssoAuthentication,
@@ -252,7 +251,7 @@ export const handleSsoAuthentication = async (
 
 const signInWithSsoAuthentication = async (
   ctx: WithInteractionHooksContext<WithLogContext>,
-  { userSsoIdentities: userSsoIdentitiesQueries, users: usersQueries }: Queries,
+  { queries: { userSsoIdentities: userSsoIdentitiesQueries, users: usersQueries } }: TenantContext,
   {
     connectorData: { id: connectorId, syncProfile },
     userSsoIdentity: { id, userId },

packages/core/src/utils/user.ts

@@ -6,8 +6,11 @@ import {
   type User,
   type UserMfaVerificationResponse,
 } from '@logto/schemas';
+import { PhoneNumberParser } from '@logto/shared/universal';
 import { pick } from '@silverhand/essentials';
 
+import RequestError from '#src/errors/RequestError/index.js';
+
 export const transpileUserMfaVerifications = (
   mfaVerifications: User['mfaVerifications']
 ): UserMfaVerificationResponse => {
@@ -62,3 +65,20 @@ export const transpileUserProfileResponse = (
     ...(ssoIdentities && { ssoIdentities }),
   };
 };
+
+// Not used yet, may be used in the future, keep as a individual method.
+const getValidPhoneNumber = (phone: string): string => {
+  if (!phone) {
+    return phone;
+  }
+
+  try {
+    return PhoneNumberParser.parse(phone).number;
+  } catch (error) {
+    throw new RequestError({ code: 'user.invalid_phone', status: 422 }, error);
+  }
+};
+
+export const validatePhoneNumber = (phone: string): void => {
+  getValidPhoneNumber(phone);
+};

packages/experience/package.json

@@ -27,6 +27,7 @@
     "@logto/phrases": "workspace:^1.19.0",
     "@logto/phrases-experience": "workspace:^1.10.0",
     "@logto/schemas": "workspace:^1.27.0",
+    "@logto/shared": "workspace:^3.1.4",
     "@react-spring/shared": "^9.6.1",
     "@react-spring/web": "^9.6.1",
     "@silverhand/eslint-config": "6.0.1",
@@ -64,7 +65,7 @@
     "jest-transformer-svg": "^2.0.0",
     "js-base64": "^3.7.5",
     "ky": "^1.2.3",
-    "libphonenumber-js": "^1.10.51",
+    "libphonenumber-js": "^1.12.6",
     "lint-staged": "^15.0.0",
     "postcss": "^8.4.31",
     "postcss-modules": "^6.0.0",

packages/experience/src/utils/country-code.ts

@@ -1,10 +1,7 @@
+import { PhoneNumberParser } from '@logto/shared/universal';
 import i18next from 'i18next';
 import type { CountryCode, CountryCallingCode } from 'libphonenumber-js/mobile';
-import {
-  getCountries,
-  getCountryCallingCode,
-  parsePhoneNumberWithError,
-} from 'libphonenumber-js/mobile';
+import { getCountries, getCountryCallingCode } from 'libphonenumber-js/mobile';
 
 export const fallbackCountryCode = 'US';
 
@@ -86,17 +83,9 @@ export const getCountryList = (): CountryMetaData[] => {
   ];
 };
 
-export const parseE164Number = (value: string) => {
-  if (!value || value.startsWith('+')) {
-    return value;
-  }
-
-  return `+${value}`;
-};
-
 export const formatPhoneNumberWithCountryCallingCode = (number: string) => {
   try {
-    const phoneNumber = parsePhoneNumberWithError(parseE164Number(number));
+    const phoneNumber = PhoneNumberParser.parse(number);
 
     return `+${phoneNumber.countryCallingCode} ${phoneNumber.nationalNumber}`;
   } catch {
@@ -106,7 +95,7 @@ export const formatPhoneNumberWithCountryCallingCode = (number: string) => {
 
 export const parsePhoneNumber = (value: string) => {
   try {
-    const phoneNumber = parsePhoneNumberWithError(parseE164Number(value));
+    const phoneNumber = PhoneNumberParser.parse(value);
 
     return {
       countryCallingCode: phoneNumber.countryCallingCode,

packages/experience/src/utils/form.ts

@@ -1,12 +1,13 @@
 import { usernameRegEx, emailRegEx } from '@logto/core-kit';
 import { SignInIdentifier } from '@logto/schemas';
+import { PhoneNumberParser } from '@logto/shared/universal';
 import i18next from 'i18next';
 import type { TFuncKey } from 'i18next';
-import { parsePhoneNumberWithError, ParseError } from 'libphonenumber-js/mobile';
+import { ParseError } from 'libphonenumber-js/mobile';
 
 import type { ErrorType } from '@/components/ErrorMessage';
 import type { IdentifierInputType } from '@/components/InputFields/SmartInputField';
-import { parseE164Number, parsePhoneNumber } from '@/utils/country-code';
+import { parsePhoneNumber } from '@/utils/country-code';
 
 const { t } = i18next;
 
@@ -32,7 +33,7 @@ export const validateEmail = (email: string): ErrorType | undefined => {
 
 export const validatePhone = (value: string): ErrorType | undefined => {
   try {
-    const phoneNumber = parsePhoneNumberWithError(parseE164Number(value));
+    const phoneNumber = PhoneNumberParser.parse(value);
 
     if (!phoneNumber.isValid()) {
       return 'invalid_phone';