Feature Request: Native Support for "Identity Merging" (Auto-Link by Email)

[mocker12345]

Problem Description

In the current Medusa v2 architecture, utilizing multiple authentication providers (e.g., google, emailpass, phone) often creates a fragmented customer experience.

If a user logs in with [email protected] via Google, and later logs in with [email protected] via Email/Password (or OTP), Medusa currently treats these as two separate identities. Without custom logic, they may end up creating two distinct Customer records (if the unique email constraint doesn't block it) or failing to link the new identity to the existing customer.

Developers currently have to "shadow" (overwrite) the POST /store/customers route or write custom Callback Routes to manually query for existing customers and establish Remote Links.

Proposed Solution

We propose adding an optional configuration to the Auth/Customer modules (e.g., auto_merge_identities: true) or a standard "Linking Workflow" that provides this behavior out-of-the-box.

Logic Flow

1. Authentication: User authenticates via Provider A (e.g., Google).
2. Lookup: System checks if this AuthIdentity is linked to a Customer.
3. Fallback (The Feature): If no link exists, system searches the Customer table for a matching email.
4. Merge:
   • Match Found: Automatically link the new AuthIdentity to the existing Customer.
   • No Match: Create a new Customer.

Why is this important?

• Industry Standard: This mimics the behavior of major platforms like Shopify (Multipass) and Auth0, where Email is often treated as a unique identifier for merging accounts.
• Developer Experience: It removes the need for complex boilerplate code in every project that requires multi-provider support.

Our Current Workaround

We achieved this by:

1. Defining the Link: Manually defined the link between Auth and Customer.
2. Middleware Interceptor: Instead of shadowing routes, we used defineMiddlewares to intercept POST /store/customers.
   • If auth_context is present (Authenticated), we run our custom "Link Workflow" and return early.
   • If not, we call next() to let the core logic handle standard creation.
3. Shared Workflow: Implemented a find-and-link-step that performs the lookup and merge logic.

Technical Discovery: "isList: true" Requirement

If implementing this natively, please note a critical configuration detail we discovered:
When defining the link between AuthIdentity and Customer, the match MUST allow many-to-one relationships.
By default, defineLink seems to enforce One-to-One. We had to explicitly set isList: true:

// src/links/auth-customer.ts
export default defineLink(
    {
        linkable: AuthModule.linkable.authIdentity,
        isList: true // CRITICAL: Allows multiple identities (Google + OTP) to link to ONE customer
    },
    CustomerModule.linkable.customer
)

Without this, attempts to link a second identity fail with: Cannot create multiple links between 'auth' and 'customer'.

Reference Implementation

Here is a simplified version of the logic we implemented in our FindAndLink workflow step:

// simplified-link-logic.ts
const findAndLinkStep = createStep("find-and-link", async ({ email, authIdentity }, { container }) => {
  const customerService = container.resolve(Modules.CUSTOMER)
  const remoteLink = container.resolve(ContainerRegistrationKeys.REMOTE_LINK)

  // 1. Try to find existing customer by email
  const [existingCustomer] = await customerService.listCustomers({ email })

  let customerId = existingCustomer?.id

  // 2. If no customer, create one
  if (!customerId) {
    const newCustomer = await customerService.createCustomers({ email })
    customerId = newCustomer.id
  }

  // 3. Create the Link (AuthIdentity <-> Customer)
  // This allows future logins to "find" this customer via the link
  await remoteLink.create([{
    [Modules.AUTH]: { auth_identity_id: authIdentity.id },
    [Modules.CUSTOMER]: { customer_id: customerId },
  }])

  return new StepResponse({ customerId })
})

It would be great to see this pattern adopted or supported natively in the framework!

Considerations: No-Email Providers

We recognize that not all providers return an email (e.g., Phone Auth, some Twitter logins).
For the native implementation, we suggest:

1. Strict Mode: Only merge if a verified email matches.
2. Safety Check: If no email is returned, standard creation logic should apply (no merge), and developers must ensure they provide a unique dummy email (e.g., {provider_id}@no-email.com) to satisfy the unique constraint, or make the email field optional in the core.