feat(core): enhanced user lookup by phone number

[simeng-li]

Summary

Enhanced user lookup by phone with phone number normalization.

In some countries, local phone numbers are often entered with a leading '0'. However, in the context of the international format this leading '0' should be stripped. E.g., +61 (0)2 1234 5678 should be normalized to +61 2 1234 5678.

In the previous implementation, Logto did not normalize the user's phone number during the user sign-up process. Both 61021345678 and 61212345678 were considered as valid phone numbers, and we do not normalize them before storing them in the database. This could lead to confusion when users try to sign-in with their phone numbers, as they may not remember the exact format they used during sign-up. Users may also end up with different accounts for the same phone number, depending on how they entered it during sign-up.

To address this issue, especially for legacy users, we have added a new enhanced user lookup by phone with either format (with or without leading '0') to the user sign-in process. This means that users can now sign-in with either format of their phone number, and Logto will try to match it with the one stored in the database, even if they might have different formats. This will help to reduce confusion and improve the user experience when logging in with phone numbers.

For example:

• If a user signs up with the phone number +61 2 1234 5678, they can now sign-in with either +61 2 1234 5678 or +61 02 1234 5678.
• The same applies to the phone number +61 02 1234 5678, which can be used to sign-in with either +61 2 1234 5678 or +61 02 1234 5678.

For users who might have created two different counts with the same phone number but different formats. The lookup process will always return the one with an exact match. This means that if a user has two accounts with the same phone number but different formats, they will still be able to sign-in with either format, but they will only be able to access the account that matches the format they used during sign-up.

For example:

• If a user has two accounts with the phone numbers +61 2 1234 5678 and +61 02 1234 5678. They will need to sign-in to each account using the exact format they used during sign-up.

related github issue #7371.

Testing

Integration tests and unit tests added

Checklist

• .changeset
• unit tests
• integration tests
• necessary TSDoc comments

[github-actions]

COMPARE TO master

Total Size Diff ⚠️ 📈 +13.41 KB

Diff by File

Name	Diff
.changeset/nice-houses-sneeze.md	📈 +2.25 KB
packages/core/src/libraries/social.ts	📈 +20 Bytes
packages/core/src/queries/user.ts	📈 +2.88 KB
packages/core/src/routes/experience/classes/utils.ts	📈 +10 Bytes
packages/integration-tests/src/tests/api/experience-api/sign-in-interaction/password.test.ts	📈 +2.18 KB
packages/shared/src/utils/phone.test.ts	📈 +3.05 KB
packages/shared/src/utils/phone.ts	📈 +3.02 KB

[Copilot]

Pull Request Overview

This PR implements enhanced user lookup by phone number with normalization, ensuring that phone numbers entered with or without a leading zero are matched correctly during sign-in. The key changes include updates to phone number parsing and normalization utilities, new tests for phone normalization, modifications in user queries and social library for normalized phone lookup, and an updated changeset.

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/shared/src/utils/phone.ts	Added parsing utilities and a PhoneNumberParser class for normalization.
packages/shared/src/utils/phone.test.ts	Added test cases to verify phone normalization behavior.
packages/integration-tests/src/tests/api/experience-api/sign-in-interaction/password.test.ts	Added integration tests covering various phone sign-in scenarios; one suite has been skipped and a debug statement remains.
packages/core/src/routes/experience/classes/utils.ts	Updated user lookup to use the normalized phone query.
packages/core/src/queries/user.ts	Introduced findUserByNormalizedPhone with normalization logic.
packages/core/src/libraries/social.ts	Modified social library to use normalized phone lookup.
.changeset/nice-houses-sneeze.md	Updated changeset documentation with details on phone normalization.

[gao-sun]

changeset LGTM