feat(clerk-js,ui,shared,localizations): Support passkey as a second factor - #9127
feat(clerk-js,ui,shared,localizations): Support passkey as a second factor#9127dmoerner wants to merge 14 commits into
Conversation
…actor
The Clerk backend can now offer passkey in a sign-in's (and session
reverification's) supported_second_factors when the instance allows
passkeys to satisfy the second factor and the user has a registered
passkey. This adds client support end to end:
- Types: passkey variants in SignInSecondFactor,
Prepare/AttemptSecondFactorParams, SessionVerificationSecondFactor,
and the session verify param unions.
- signIn.authenticateWithPasskey() detects needs_second_factor (and
needs_client_trust) and runs the prepare/attempt second-factor flow
against the in-progress sign-in instead of creating a new one; the
flow param is ignored there. attemptSecondFactor serializes the
WebAuthn credential like attemptFirstFactor. The future API gains
mfa.passkey().
- session.verifyWithPasskey({ level: 'second_factor' }) completes a
multi-factor step-up with a passkey.
- Prebuilt UI: passkey cards for the sign-in factor-two and
user-verification factor-two steps, offered via the existing
totp/phone-first ladder (passkey is only the starting factor when it
is the sole option), listed under "Use another method", and hidden
when WebAuthn is unsupported. Fixes the alternative-methods label
switch that threw on unknown second-factor strategies.
- New signIn.passkeyMfa / reverification.passkeyMfa localization keys.
Part of USER-3966
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: 4f994ca The changes in this PR will be included in the next version bump. This PR includes changesets to release 23 packages
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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughPasskey second-factor support is added to sign-in and session reverification APIs, shared types, prebuilt sign-in and user-verification UIs, tests, localization resources, FAPI versioning, and release metadata. Changes
Estimated code review effort: 4 (Complex) | ~60 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-google-signin
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
API Changes Report
Summary
@clerk/sharedCurrent version: 4.29.2 Subpath
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
packages/ui/src/components/SignIn/__tests__/SignInFactorTwo.test.tsx (1)
407-424: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winTest may pass for the wrong reason — wrap in
mockWebAuthnto test priority ordering.Without
mockWebAuthn,isWebAuthnSupported()likely returns false in the test environment, so passkey is excluded from candidacy regardless of priority sorting against TOTP. This test currently can't distinguish "TOTP wins on priority" from "passkey is filtered out due to no WebAuthn support." Wrapping this inmockWebAuthn(() => { ... })(as done for the sibling tests below) would ensure the sorting/priority logic is actually exercised.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ui/src/components/SignIn/__tests__/SignInFactorTwo.test.tsx` around lines 407 - 424, Update the Passkey test “is never the starting factor when another second factor is available” to wrap its fixture setup, render, and assertions in mockWebAuthn, matching the sibling tests below. Keep supportTotp and supportPasskey enabled so the test validates priority ordering rather than passkey being excluded by unsupported WebAuthn.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts`:
- Around line 261-264: Restore direct static assignments in the passkey test
suites: update the authenticateWithPasskey and mfa.passkey cleanup to save the
original BaseResource._fetch and SignIn.clerk values before stubbing, then
reassign those originals in afterEach alongside vi.clearAllMocks() and
vi.unstubAllGlobals().
In `@packages/clerk-js/src/core/resources/Session.ts`:
- Around line 320-329: The verifyWithPasskey method silently treats invalid
levels as first-factor verification. Default level with nullish coalescing, then
explicitly validate that it is either 'first_factor' or 'second_factor' and
reject any other value before calling prepareFirstFactorVerification or
prepareSecondFactorVerification.
- Around line 320-329: Document the public verifyWithPasskey API with JSDoc
directly above the verifyWithPasskey method in Session, describing the
params.level options and default, the returned SessionVerificationResource, and
possible error behavior; flag the contract change for Docs-team review or
accompanying generated documentation updates.
In `@packages/clerk-js/src/core/resources/SignIn.ts`:
- Around line 575-610: Add or update JSDoc for the public
authenticateWithPasskey method to document that needs_second_factor and
needs_client_trust sign-ins reuse the in-progress sign-in via the second-factor
flow, and that the flow option is ignored in those states. Include the API
behavior change clearly and mark the documentation for Docs-team review.
In `@packages/ui/src/components/UserVerification/UVFactorTwoPasskeyCard.tsx`:
- Around line 32-41: Update handlePasskeysAttempt to guard against concurrent
passkey attempts: set the card’s loading state before calling verifyWithPasskey,
clear it in a finally handler regardless of success or failure, and disable the
passkey button while loading so additional clicks cannot abort the in-flight
ceremony.
---
Nitpick comments:
In `@packages/ui/src/components/SignIn/__tests__/SignInFactorTwo.test.tsx`:
- Around line 407-424: Update the Passkey test “is never the starting factor
when another second factor is available” to wrap its fixture setup, render, and
assertions in mockWebAuthn, matching the sibling tests below. Keep supportTotp
and supportPasskey enabled so the test validates priority ordering rather than
passkey being excluded by unsupported WebAuthn.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: c030f53b-d9cd-46b4-8a0f-e7f81cb887a2
📒 Files selected for processing (73)
.changeset/passkey-second-factor.mdpackages/clerk-js/src/core/resources/Session.tspackages/clerk-js/src/core/resources/SignIn.tspackages/clerk-js/src/core/resources/__tests__/Session.test.tspackages/clerk-js/src/core/resources/__tests__/SignIn.test.tspackages/localizations/src/ar-SA.tspackages/localizations/src/be-BY.tspackages/localizations/src/bg-BG.tspackages/localizations/src/bn-IN.tspackages/localizations/src/ca-ES.tspackages/localizations/src/cs-CZ.tspackages/localizations/src/da-DK.tspackages/localizations/src/de-DE.tspackages/localizations/src/el-GR.tspackages/localizations/src/en-GB.tspackages/localizations/src/en-US.tspackages/localizations/src/es-CR.tspackages/localizations/src/es-ES.tspackages/localizations/src/es-MX.tspackages/localizations/src/es-UY.tspackages/localizations/src/fa-IR.tspackages/localizations/src/fi-FI.tspackages/localizations/src/fr-FR.tspackages/localizations/src/he-IL.tspackages/localizations/src/hi-IN.tspackages/localizations/src/hr-HR.tspackages/localizations/src/hu-HU.tspackages/localizations/src/id-ID.tspackages/localizations/src/is-IS.tspackages/localizations/src/it-IT.tspackages/localizations/src/ja-JP.tspackages/localizations/src/kk-KZ.tspackages/localizations/src/ko-KR.tspackages/localizations/src/mn-MN.tspackages/localizations/src/ms-MY.tspackages/localizations/src/nb-NO.tspackages/localizations/src/nl-BE.tspackages/localizations/src/nl-NL.tspackages/localizations/src/pl-PL.tspackages/localizations/src/pt-BR.tspackages/localizations/src/pt-PT.tspackages/localizations/src/ro-RO.tspackages/localizations/src/ru-RU.tspackages/localizations/src/sk-SK.tspackages/localizations/src/sr-RS.tspackages/localizations/src/sv-SE.tspackages/localizations/src/ta-IN.tspackages/localizations/src/te-IN.tspackages/localizations/src/th-TH.tspackages/localizations/src/tr-TR.tspackages/localizations/src/uk-UA.tspackages/localizations/src/vi-VN.tspackages/localizations/src/zh-CN.tspackages/localizations/src/zh-TW.tspackages/shared/src/internal/clerk-js/errors.tspackages/shared/src/types/localization.tspackages/shared/src/types/session.tspackages/shared/src/types/sessionVerification.tspackages/shared/src/types/signInCommon.tspackages/shared/src/types/signInFuture.tspackages/ui/src/components/SignIn/SignInClientTrust.tsxpackages/ui/src/components/SignIn/SignInFactorTwo.tsxpackages/ui/src/components/SignIn/SignInFactorTwoAlternativeMethods.tsxpackages/ui/src/components/SignIn/SignInFactorTwoPasskeyCard.tsxpackages/ui/src/components/SignIn/__tests__/SignInFactorTwo.test.tsxpackages/ui/src/components/SignIn/shared.tspackages/ui/src/components/SignIn/utils.tspackages/ui/src/components/UserVerification/UVFactorTwoAlternativeMethods.tsxpackages/ui/src/components/UserVerification/UVFactorTwoPasskeyCard.tsxpackages/ui/src/components/UserVerification/UserVerificationFactorTwo.tsxpackages/ui/src/components/UserVerification/__tests__/UVFactorTwo.test.tsxpackages/ui/src/test/fixture-helpers.tspackages/ui/src/utils/factorSorting.ts
There was a problem hiding this comment.
🧹 Nitpick comments (1)
packages/shared/src/internal/clerk-js/errors.ts (1)
105-112: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDocument the exported error helper.
The new exported function has an empty JSDoc block. Add accurate
@param,@returns,@throws, and@exampledocumentation describing the supported verification levels and caller-facing error. If this export is reference-facing, please also have the Docs team review the generated API content.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/shared/src/internal/clerk-js/errors.ts` around lines 105 - 112, Document the exported clerkInvalidVerificationLevel helper with complete JSDoc: describe functionName and level via `@param`, state the never return behavior via `@returns`, document the thrown caller-facing error via `@throws`, and add an `@example` showing an invalid level and the supported first_factor and second_factor values. Keep the documentation aligned with the existing error message and request Docs review for the generated API content if this export is reference-facing.Sources: Coding guidelines, Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@packages/shared/src/internal/clerk-js/errors.ts`:
- Around line 105-112: Document the exported clerkInvalidVerificationLevel
helper with complete JSDoc: describe functionName and level via `@param`, state
the never return behavior via `@returns`, document the thrown caller-facing error
via `@throws`, and add an `@example` showing an invalid level and the supported
first_factor and second_factor values. Keep the documentation aligned with the
existing error message and request Docs review for the generated API content if
this export is reference-facing.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: 9bc817b9-9d9f-4562-931c-26016589d189
📒 Files selected for processing (9)
.changeset/passkey-second-factor.mdpackages/clerk-js/src/core/resources/Session.tspackages/clerk-js/src/core/resources/SignIn.tspackages/clerk-js/src/core/resources/__tests__/Session.test.tspackages/clerk-js/src/core/resources/__tests__/SignIn.test.tspackages/react/src/stateProxy.tspackages/shared/src/internal/clerk-js/errors.tspackages/shared/src/types/session.tspackages/ui/src/components/UserVerification/UVFactorTwoPasskeyCard.tsx
🚧 Files skipped from review as they are similar to previous changes (7)
- .changeset/passkey-second-factor.md
- packages/clerk-js/src/core/resources/tests/Session.test.ts
- packages/ui/src/components/UserVerification/UVFactorTwoPasskeyCard.tsx
- packages/clerk-js/src/core/resources/tests/SignIn.test.ts
- packages/shared/src/types/session.ts
- packages/clerk-js/src/core/resources/Session.ts
- packages/clerk-js/src/core/resources/SignIn.ts
If the environment variable on the backend is unset, the backend will not advertise passkeys for second factor. The javascript code, when on a new clerk js version that does support passkeys as second factor, was treating that as an error. Instead just fail gracefully, clients shouldn't be disrupted if the backend doesn't yet advertise support for something.
There was a problem hiding this comment.
🧹 Nitpick comments (1)
packages/clerk-js/src/core/resources/SignIn.ts (1)
594-619: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDuplicate second-factor passkey ceremony logic between
authenticateWithPasskeyandverifyMFAPasskey.Both blocks implement the same sequence (prepare second factor with
strategy: 'passkey'→ read/parse nonce → convert to public-key options → fetch credential → submit attempt), but diverge in error handling (clerkMissingWebAuthnPublicKeyOptions/rawthrow errorhere vs.ClerkRuntimeError/ClerkWebAuthnErrorthere). Extracting a shared private helper would prevent the two paths from drifting further as passkey second-factor logic evolves.Also applies to: 1563-1610
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/clerk-js/src/core/resources/SignIn.ts` around lines 594 - 619, Extract the duplicated second-factor passkey ceremony from authenticateWithPasskey and verifyMFAPasskey into a shared private helper on SignIn. Have both callers use the helper, preserving the existing prepareSecondFactor, nonce parsing, public-key option conversion, credential retrieval, and attemptSecondFactor flow while standardizing their error handling through the shared implementation.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@packages/clerk-js/src/core/resources/SignIn.ts`:
- Around line 594-619: Extract the duplicated second-factor passkey ceremony
from authenticateWithPasskey and verifyMFAPasskey into a shared private helper
on SignIn. Have both callers use the helper, preserving the existing
prepareSecondFactor, nonce parsing, public-key option conversion, credential
retrieval, and attemptSecondFactor flow while standardizing their error handling
through the shared implementation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: 37a94a0a-db64-4faf-8786-49a7017aba5d
📒 Files selected for processing (4)
.changeset/passkey-second-factor.mdpackages/clerk-js/src/core/resources/SignIn.tspackages/clerk-js/src/core/resources/__tests__/SignIn.test.tspackages/shared/src/internal/clerk-js/errors.ts
💤 Files with no reviewable changes (1)
- packages/shared/src/internal/clerk-js/errors.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- .changeset/passkey-second-factor.md
Covers the needs_second_factor path against the with-passkeys instance: registering a passkey for a 2FA-enabled user, passkey as the starting second factor, and passkey listed under "Use another method". Both suites now share one dev server instead of committing an app each.
The with-passkeys instance has no phone_number identifier, so BAPI rejects it at user creation. Enroll TOTP via BAPI after the passkey is registered instead; no test needs to enter a TOTP code.
…key-as-2fa-option # Conflicts: # packages/ui/bundlewatch.config.json
1 participant
Users who have a passkey and sign in with a password (or OAuth, or a reset-password code) cannot use that passkey as their second factor: the SDK treats passkeys purely as a first-factor strategy, and the prebuilt UI's factor-two step throws on any second-factor strategy it doesn't know. The Clerk backend (clerk/clerk_go#20312) can now offer
passkeyin a sign-in's and a session reverification'ssupportedSecondFactorswhen the instance allows passkeys to satisfy the second factor and the user has a registered passkey. This adds client support end to end:SignInSecondFactor,Prepare/AttemptSecondFactorParams,SessionVerificationSecondFactor, and the session verify param unions.signIn.authenticateWithPasskey()detectsneeds_second_factor(andneeds_client_trust) and runs the prepare/attempt second-factor flow against the in-progress sign-in instead of creating a new one; theflowparam is ignored there.attemptSecondFactorserializes the WebAuthn credential likeattemptFirstFactor. The future API gainsmfa.passkey().session.verifyWithPasskey({ level: 'second_factor' })completes a multi-factor step-up with a passkey.signIn.passkeyMfa/reverification.passkeyMfalocalization keys.This relies on the FAPI API version bump to
2026-08-20(SUPPORTED_FAPI_VERSION): the backend only offers the passkey second factor to SDKs that request at least that version, so older clerk-js builds keep their current behavior with no changes.Part of USER-3966
Tested end to end against local clerk running clerk/clerk_go#20312 (real WebAuthn ceremonies via a Chromium virtual authenticator), comparing this branch with the published clerk-js 6.29.2 (
2026-05-12):authenticateWithPasskey()on the in-progress sign-in; first factor stayspassword/reset_password_email_code.supportedSecondFactorsisemail_code+passkey, andauthenticateWithPasskey()completes the sign-in.verifyWithPasskey({ level: 'second_factor' }),multi_factor(password → passkey; passkey as first factor alone also completes),first_factor, and the prebuilt reverification modal (starts on the passkey card,afterVerificationfires).<SignIn />: factor-two step starts on the passkey card, "Use another method" lists "Sign in with your passkey" and "Use your authenticator app", and the flow ends signed in.needs_second_factorwith no session; an authenticator without a matching credential rejects and creates no session.twoFactorEnabledstaysfalse; password sign-in completes once TOTP is removed).fvais[0,0]after TOTP, passkey-2FA, and passkey-first sign-ins.Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change