feat(clerk-js,localizations,types): email_code & email_link as 2FA when signing in on new device

[tmilewski]

Description

(NOTE: Currently behind a feature flag.)

Enables support for email_code and email_link as a second factor in the AIO components.

This flow is hit when a user is signing-in on a new device. If they are using email alongside password as their first factor, and don't have any MFA options enabled, they will be required to verify.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Email code and email link added as second-factor sign-in options with a verification flow and modal
  • New-device verification notice when signing in from an unfamiliar device

• Bug Fixes / UX

  • Improved warning/alert presentation and hover/border behavior across verification UI
  • Refined tag input hover/border behavior

• Localization

  • Added MFA and device-verification strings for 40+ locales

• Chores

  • Minor package version bumps and bundle size cap adjustment

[changeset-bot]

🦋 Changeset detected

Latest commit: 0d07fae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@clerk/localizations	Minor
@clerk/clerk-js	Minor
@clerk/types	Minor
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Nov 12, 2025 5:54pm

[coderabbitai]

Walkthrough

Adds email-based second-factor flows (email_code and email_link) with new UI cards and dynamic preparation/verification logic, expands localization keys across many locales, updates sign-in types and flow metadata, adjusts Alert/styling behavior, includes a changeset and a small bundle size cap bump.

Changes

Cohort / File(s)	Summary
Release Declarations \.changeset/bright-heads-start.md``	Adds changeset bumping @clerk/localizations, @clerk/clerk-js, and @clerk/types; documents support for email_code and email_link as second factors on new-device sign-in.
Core Sign-In Logic \packages/clerk-js/src/core/resources/SignIn.ts``	Switches email_link handling to a dynamic verification flow: chooses first/second-factor prepare based on needs_second_factor, tracks a dynamic verification key, reloads/reads status via that key.
Second-Factor UI Entry \packages/clerk-js/src/ui/components/SignIn/SignInFactorTwo.tsx`, `packages/clerk-js/src/ui/components/SignIn/SignInFactorTwoAlternativeMethods.tsx`, `packages/clerk-js/src/ui/components/SignIn/SignInFactorTwoCodeForm.tsx``	Adds email_code and email_link cases; centralizes factorAlreadyPrepared check; introduces isNewDevice helper and surfaces cardNotice for new-device notices; extends factor unions where needed.
New Second-Factor Cards \packages/clerk-js/src/ui/components/SignIn/SignInFactorTwoEmailCodeCard.tsx`, `packages/clerk-js/src/ui/components/SignIn/SignInFactorTwoEmailLinkCard.tsx``	Adds SignInFactorTwoEmailCodeCard (calls prepareSecondFactor with emailAddressId) and SignInFactorTwoEmailLinkCard (starts email-link flow, handles verification results, modal/activation/redirect); exports new props/type for link card.
Verification Elements \packages/clerk-js/src/ui/elements/VerificationCodeCard.tsx`, `packages/clerk-js/src/ui/elements/VerificationLinkCard.tsx``	Adds optional cardNotice?: LocalizationKey prop and conditional rendering of a warning Alert with caption text when provided.
Primitives & Styling \packages/clerk-js/src/ui/primitives/Alert.tsx`, `packages/clerk-js/src/ui/styledSystem/common.ts``	Refactors border variants to accept hoverStyles flag; computes normal-state borderColor/boxShadow dynamically (handles hasError/hasWarning); allows disabling hover styles.
Small UI Changes \packages/clerk-js/src/ui/components/OAuthConsent/OAuthConsent.tsx`, `packages/clerk-js/src/ui/elements/TagInput.tsx``	Replaces a custom Box warning with Alert in OAuthConsent; TagInput now passes hoverStyles: true into borderVariants.
Flow Metadata & Types \packages/clerk-js/src/ui/elements/contexts/index.tsx`, `packages/shared/src/types/localization.ts`, `packages/shared/src/types/signInCommon.ts``	Adds emailCode2Fa to FlowMetadata.part; adds emailCodeMfa, emailLinkMfa, and newDeviceVerificationNotice to localization types; extends SignInSecondFactor and PrepareSecondFactorParams to include EmailLink.
Localizations (many locales) \packages/localizations/src/*.ts``	Adds emailCodeMfa, emailLinkMfa, and newDeviceVerificationNotice keys across 40+ locale files (mix of translations and placeholders), expanding localization surface for email MFA and new-device notices.
Bundle Config \packages/clerk-js/bundlewatch.config.json``	Increases headless bundle size cap from 63KB to 63.2KB.
Machines / Type Suppression \packages/elements/src/internals/machines/sign-in/verification.machine.ts``	Adds // @ts-expect-error`` before calling attemptSecondFactor with `email_link` params to suppress a TypeScript error (type-check suppression only).

Sequence Diagram(s)

sequenceDiagram
    participant U as User
    participant C as Client / SDK
    participant S as Server
    participant UI as SignIn UI
    participant EC as EmailCodeCard
    participant EL as EmailLinkCard

    U->>C: submit credentials
    C->>S: prepareFirstFactor()
    S-->>C: status (ok | needs_second_factor)
    alt needs_second_factor
        C->>UI: load second-factor options
        UI->>EC: render when email_code available
        UI->>EL: render/init when email_link available
        EC->>S: prepareSecondFactor({ emailAddressId, strategy: email_code })
        EL->>C: startEmailLinkFlow(redirectUrl)
        EL->>S: prepareSecondFactor({ ...email_link config })
        Note right of EL: waits for verification callback or resend
        S-->>EL: verificationResult (verified | expired | error)
        alt verified (same client)
            EL->>C: show verification modal / activate session
            C->>U: redirect to afterSignInUrl
        else expired / error
            EL->>UI: surface error / allow restart
        end
    else continue_first_factor
        C->>S: continue first-factor verification
    end
    S-->>U: final auth result / redirect

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

• Review focus:
  • packages/clerk-js/src/core/resources/SignIn.ts — dynamic prepare/verification-key logic.
  • New components: SignInFactorTwoEmailCodeCard.tsx, SignInFactorTwoEmailLinkCard.tsx — state, verification, activation, redirect, error handling.
  • Type updates: packages/shared/src/types/signInCommon.ts, packages/shared/src/types/localization.ts.
  • UI prop changes: cardNotice in VerificationCodeCard / VerificationLinkCard.
  • Styling changes in styledSystem/common.ts and Alert.tsx.
  • // @ts-expect-error`` in verification.machine.ts — confirm intentionality.

Poem

"i hop to the inbox, ears alert and keen,
links and codes sparkle where the messages lean.
an alert whispers: new device in sight,
little paws prepare the session just right.
secure tiny hops — cozy, soft, and bright." 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main feature: adding email_code and email_link support as 2FA options when signing in on a new device, with affected packages specified.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch tom/supported-factors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7116

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7116

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7116

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7116

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7116

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7116

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7116

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@7116

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7116

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7116

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7116

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7116

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7116

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7116

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@7116

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7116

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@7116

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7116

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7116

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7116

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7116

@clerk/types

npm i https://pkg.pr.new/@clerk/types@7116

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7116

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7116

commit: 0d07fae