[ECUK In-App 3DS] Add Passkeys/WebAuthn support for multifactor biometric authentication by dariusz-biela · Pull Request #84610 · Expensify/App

dariusz-biela · 2026-03-09T16:37:19Z

Explanation of Change

This PR adds Passkeys/WebAuthn as a new authentication method for in-app 3DS card transaction authorization on Web/mWeb, alongside the existing NativeBiometrics (iOS/Android). A platform-specific useBiometrics() hook abstracts both methods behind a shared UseBiometricsReturn interface so the MFA context is unaware of the underlying technology. The Biometrics/ module is refactored into NativeBiometrics/, Passkeys/, and shared/ directories. Passkeys are currently enabled only in the BiometricsTest scenario. Localization and tests are updated accordingly.

Detailed breakdown

usePasskeys hook — Manages the full Passkeys lifecycle (registration and authorization) by bridging low-level WebAuthn browser APIs with the MultifactorAuthenticationContext. Handles frontend ↔ backend credential exchange including challenge request/response flows.
WebAuthn helpers — Passkeys/WebAuthn.ts provides ArrayBuffer ↔ base64url conversions, builds PublicKeyCredentialCreationOptions/RequestOptions, and wraps navigator.credentials.create/get. A separate Passkeys/helpers.ts module maps common WebAuthn DOMException errors to internal error codes.
Shared biometrics abstraction — Extracts common types (UseBiometricsReturn, RegisterResult, AuthorizeResult, AuthorizeParams) and a useServerCredentials hook into biometrics/shared/ so that both useNativeBiometrics and usePasskeys share the same contract with the MFA context.
Platform-specific useBiometrics split — biometrics/useBiometrics/index.ts (web) re-exports usePasskeys, while index.native.ts re-exports useNativeBiometrics, so the MultifactorAuthenticationContext calls a single useBiometrics() hook and the platform decides which implementation runs.
MultifactorAuthenticationContext extension — Wires in the new useBiometrics() abstraction. Device eligibility is now checked in two steps: (2a) doesDeviceSupportAuthenticationMethod() verifies platform support, and (2b) the scenario's allowedAuthenticationMethods array is checked against deviceVerificationType. Prompt navigation now uses a PROMPT_TYPE_MAP to pick the correct prompt type (biometrics vs passkeys).
Scenario configuration — Extends the BiometricsTest scenario's allowedAuthenticationMethods from [BIOMETRICS] to [BIOMETRICS, PASSKEYS]. Other scenarios remain unchanged, so Passkeys are currently only available in the test flow.
NativeBiometrics refactor — Renames the Biometrics/ directory to NativeBiometrics/ and extracts native-specific types, helpers (Expo error decoding), and VALUES into dedicated files. Shared types and challenge types are moved to shared/. A new barrel file (MultifactorAuthentication/VALUES.ts) merges shared + NativeBiometrics + Passkeys values. The unused Observer.ts and MultifactorAuthenticationCallbacks are removed.
Registration flow change — keyInfo construction (previously in processing.ts via createKeyInfoObject) is now performed inside each hook (useNativeBiometrics / usePasskeys), and processRegistration receives the ready-made keyInfo object directly.
Prompt content updates — PromptContent.tsx now supports both Lottie animations and SVG illustrations (animation prop renamed to illustration). Passkeys use a new SVG asset (simple-illustration__encryption-passkeys.svg); native biometrics continue using the existing Lottie fingerprint animation.
Field renames — localPublicKey → localCredentialID, getLocalPublicKey → getLocalCredentialID, doesDeviceSupportBiometrics → doesDeviceSupportAuthenticationMethod, resetKeysForAccount → deleteLocalKeysForAccount across hooks, pages, selectors, and tests.
3DS navigation simplification — useNavigateTo3DSAuthorizationChallenge replaces the per-method switch-case with a single doesDeviceSupportAuthenticationMethod() && allowedAuthenticationMethods.includes(deviceVerificationType) check, removing the previous TODO comment about passkey support.
Type safety improvements — userVerification narrowed from string to UserVerificationRequirement, pubKeyCredParams.type narrowed from string to PublicKeyCredentialType, AuthTypeInfo.code made optional (passkeys don't use SecureStore codes). Added COSE_ALGORITHM constants (EDDSA, ES256, RS256) to CONST.
Selector changes — Removed hasBiometricsRegisteredSelector and isAccountLoadingSelector from selectors/Account.ts; added mfaCredentialIDsSelector used by the new useServerCredentials hook.
Localization — Adds Passkey-related user-facing strings (verifyYourself.passkeys, enableQuickVerification.passkeys, authType.passkey) across all supported languages.
Tests — Adds unit tests for processRegistration/processScenarioAction (processing.test.ts), NativeBiometrics Expo error decoding (NativeBiometrics/helpers.test.ts), and shared parseHttpRequest (shared/helpers.test.ts). Updates existing test suites for renamed fields and import paths. Removes obsolete Observer.test.ts and old Biometrics/helpers.test.ts.

Fixed Issues

$ #79464
$ #79467
$ #79469
PROPOSAL:

Tests

All of these PRs have already been deployed to production:

Prerequisites: The backend is not yet ready — testing requires the Auth and Web-Expensify PRs:
https://github.com/Expensify/Auth/pull/19657
https://github.com/Expensify/Web-Expensify/pull/51463
https://github.com/Expensify/Auth/pull/20520

Passkeys registration (Web / mWeb):

Open Expensify App on Web (Chrome/Safari)
Navigate to Settings → Troubleshoot
Click on the "Test" button next to the "Passkeys (Not registered)" text
Click on the "Test" button in the RHP view
Fill the magic code input
Click on the "Got it" button
Authenticate using your browser's passkey/WebAuthn prompt (e.g. Touch ID, Windows Hello, security key)
Verify that the Authentication was successful
Verify that the registered label is now displayed

Passkeys authorization (Web / mWeb): 10. Repeat steps 3 and 4 11. Verify that the validate code step is no longer required 12. Authenticate using the passkey prompt 13. Verify that the Authentication was successful

Failure scenarios (Web / mWeb): 14. Cancel the passkey prompt during registration (step 7) — verify the Authentication failed 15. Cancel the passkey prompt during authorization (step 12) — verify the Authentication failed 16. Exit the flow using the back button or by clicking the overlay — verify a confirmation modal is displayed 17. Enter a wrong validate code during registration — verify an error text is displayed and the magic code input is shown again to allow re-entry

NativeBiometrics regression (iOS / Android native): 18. Open Expensify App on a native mobile device 19. Navigate to Settings → Troubleshoot 20. Click on the "Test" button next to the "Biometrics (Not registered)" text 21. Click on the "Test" button in the RHP view 22. Fill the magic code input 23. Click on the "Got it" button 24. Authenticate using device credentials or biometry (Face ID / Touch ID / fingerprint) 25. Verify that the Authentication was successful 26. Verify that the registered label is now displayed 27. Repeat steps 20 and 21 28. Verify that validate code is no longer required 29. Authenticate using device biometrics 30. Verify that the Authentication was successful

Verify that no errors appear in the JS console

Offline tests

N/A, D - Full Page Blocking UI Pattern for this project.

QA Steps

Same as tests

PR Author Checklist

Screenshots/Videos

Android: Native

Android: mWeb Chrome

iOS: Native

iOS: mWeb Safari

MacOS: Chrome / Safari

Extract biometrics logic from Context/useNativeBiometrics into a dedicated biometrics/ module with platform-specific implementations (useBiometrics.ts for native, useBiometrics.web.ts for web). Add passkey stub implementation, WebAuthn error handling, and include PASSKEYS in allowed 3DS auth methods.

Implement WebAuthn-based passkey registration and authentication as a new MFA method alongside existing biometrics. Add passkey scenario configuration, translations, and SecureStore integration.

Strengthen source types in RegistrationChallenge and AuthenticationChallenge to use PublicKeyCredentialType and UserVerificationRequirement. Replace PublicKeyCredential casts with instanceof type guard. Derive SupportedTransport from CONST.PASSKEY_TRANSPORT with runtime guard for type narrowing.

Replace as casts for AuthenticatorAttestationResponse and AuthenticatorAssertionResponse with instanceof type guards. Use isSupportedTransport guard for getTransports() filtering.

Private keys should not leak beyond the registration function. For native biometrics the key is stored in SecureStore internally, for passkeys it never leaves the authenticator. No consumer of RegisterResult ever reads privateKey.

These debug logs were development artifacts that could leak sensitive authentication data (credential IDs, challenge content, backend responses) to the browser console in production.

Passkeys don't use SecureStore at all — the PASSKEY entry was misplaced. Define PASSKEY_AUTH_TYPE in WebAuthn.ts, make AuthTypeInfo.code optional (only relevant for native biometrics), and update derived types to include passkey via union.

melvin-bot · 2026-03-09T16:37:27Z

Hey, I noticed you changed src/languages/en.ts in a PR from a fork. For security reasons, translations are not generated automatically for PRs from forks.

If you want to automatically generate translations for other locales, an Expensify employee will have to:

Look at the code and make sure there are no malicious changes.
Run the Generate static translations GitHub workflow. If you have write access and the K2 extension, you can simply click: [this button]

Alternatively, if you are an external contributor, you can run the translation script locally with your own OpenAI API key. To learn more, try running:

npx ts-node ./scripts/generateTranslations.ts --help

Typically, you'd want to translate only what you changed by running npx ts-node ./scripts/generateTranslations.ts --compare-ref main

codecov · 2026-03-09T16:50:27Z

Codecov Report

✅ Changes either increased or maintained existing code coverage, great job!

Files with missing lines	Coverage Δ
src/CONST/index.ts	`95.20% <ø> (+1.60%)`	⬆️
src/components/Icon/chunks/illustrations.chunk.ts	`0.00% <ø> (ø)`
...tication/biometrics/shared/useServerCredentials.ts	`100.00% <100.00%> (ø)`
...orAuthentication/biometrics/useNativeBiometrics.ts	`100.00% <100.00%> (ø)`
...ion/components/AuthenticationMethodDescription.tsx	`50.00% <ø> (ø)`
...nts/OutcomeScreen/SuccessScreen/defaultScreens.tsx	`100.00% <ø> (ø)`
...tication/config/scenarios/DefaultUserInterface.tsx	`100.00% <ø> (ø)`
...ultifactorAuthentication/config/scenarios/names.ts	`100.00% <ø> (ø)`
...uthentication/observability/trackMFAFlowOutcome.ts	`0.00% <ø> (ø)`
src/components/TestToolMenu.tsx	`90.32% <100.00%> (ø)`
... and 26 more
... and 92 files with indirect coverage changes

Reconcile server-known credential IDs with local Onyx credentials and pass the result as excludeCredentials to navigator.credentials.create, preventing the same authenticator from being registered twice.

…eTypes.ts These types (SignedChallenge, RegistrationChallenge, AuthenticationChallenge, etc.) are algorithm-agnostic and shared by both ED25519 (native biometrics) and ES256 (passkeys) flows. Moving them to a neutral location removes the misleading coupling to the ED25519 module.

Separate platform-specific logic into dedicated modules: - NativeBiometrics: Expo SecureStore, ED25519, native key management - Passkeys: WebAuthn API, passkey credential helpers - shared: challenge types, observers, HTTP helpers, common types Update all imports across source and test files.

JakubKorytko

some NITs, overall LGTM

tests/unit/libs/MultifactorAuthentication/shared/helpers.test.ts

src/libs/MultifactorAuthentication/VALUES.ts

src/libs/MultifactorAuthentication/shared/types.ts

src/libs/MultifactorAuthentication/Passkeys/WebAuthn.ts

src/libs/MultifactorAuthentication/Passkeys/helpers.ts

src/components/MultifactorAuthentication/Context/Main.tsx

src/components/MultifactorAuthentication/biometrics/shared/types.ts

src/components/MultifactorAuthentication/biometrics/usePasskeys.ts

… tests Remove unnecessary KeyStore mock, add tests for processPasskeyRegistration and processScenarioAction to cover the full processing module.

- Rename biometrics/common/ to biometrics/shared/ for consistency - Use spread in VALUES.ts barrel file - Rename MultifactorAuthenticationKeyInfo to NativeBiometricsKeyInfo - Replace `as` with type guard in Passkeys/helpers.ts - Remove redundant credentials.length check in usePasskeys - Rename (p) to (param) in WebAuthn.ts - Split shared/helpers.test.ts into NativeBiometrics/ and shared/ dirs - Unify processRegistration and processPasskeyRegistration: hooks now build keyInfo internally, processing.ts has one shared function

…s/passkeys-mfa # Conflicts: # src/components/MultifactorAuthentication/Context/Main.tsx # src/components/MultifactorAuthentication/biometrics/useNativeBiometrics.ts # src/libs/MultifactorAuthentication/shared/VALUES.ts

…tion Expose a platform-specific constant (BIOMETRICS on native, PASSKEYS on web) so consumers can check whether the scenario allows the current device's verification type, replacing the redundant switch-case fallthrough.

…r wrapper React Compiler handles memoization automatically, so useMemo and the module-level selector function are unnecessary.

Replace magic number -8 with CONST.COSE_ALGORITHM.EDDSA in types and runtime code. Add ES256 and RS256 constants for passkey use.

…directly

… responses

chuckdries · 2026-03-19T17:20:58Z

That worked!!

iOS Safari: success ✅

ios.safari.passkey.success.mp4

DylanDylann · 2026-03-19T18:11:01Z

Screenshots/Videos

Android: mWeb Chrome

Still got failed

iOS: mWeb Safari

Still got failed

MacOS: Chrome / Safari

Screen.Recording.2026-03-20.at.01.08.42.mov

github-actions · 2026-03-19T18:38:44Z

🚧 @rafecolton has triggered a test Expensify/App build. You can view the workflow run here.

github-actions · 2026-03-19T18:43:28Z

🧪🧪 Use the links below to test this adhoc build on Android, iOS, and Web. Happy testing! 🧪🧪
Built from App PR #84610.

Android 🤖	iOS 🍎
⏩ SKIPPED ⏩	⏩ SKIPPED ⏩
The build for Android was skipped	The build for iOS was skipped

Web 🕸️
https://84610.pr-testing.expensify.com

👀 View the workflow run that generated this build 👀

rafecolton

@Expensify/design please review 🙏

dubielzyk-expensify · 2026-03-19T22:07:39Z

This feels real lovely! Two things:

There's a jump when clicking the button. Let's ensure that the button is accounted for even when it goes away so the shift in layout don't happen.

CleanShot.2026-03-20.at.08.07.13.mp4

The spinner thing is a bit too big. Instead of 40x40, can we do 28x28? Curious if @Expensify/design agrees.

cc @Expensify/design

dubielzyk-expensify · 2026-03-19T22:11:32Z

Also @Expensify/design I know this is our unlock illustration cause in some causes unlock means bad, but I think in this instance having the red is real confusing:

I'd actually suggest we quickly replace this specific one with something like this:

Not override, but add an alternative for when unlock means good.

rafecolton · 2026-03-20T02:36:36Z

This has conflicts now, probably from #84120 being merged. Once those are resolved and Jon's design comments are addressed, this can be merged 👍

…s/passkeys-mfa

…ns, size 28px

dariusz-biela · 2026-03-20T11:13:37Z

@dubielzyk-expensify

I have made these changes to this PR:

There's a jump when clicking the button. Let's ensure that the button is accounted for even when it goes away so the shift in layout don't happen.

The spinner thing is a bit too big. Instead of 40x40, can we do 28x28?

If you decide to do this, I will be very grateful if you send me the appropriate SVG, because I currently cannot find this icon variant in Figma:

Also @Expensify/design I know this is our unlock illustration cause in some causes unlock means bad, but I think in this instance having the red is real confusing:

passkeys.mov

dannymcclain · 2026-03-20T14:00:44Z

Agree with all your feedback Jon!

dariusz-biela · 2026-03-20T14:10:33Z

@dannymcclain
Could you send me this illustration as SVG?
Then I would be able to make changes immediately

dannymcclain · 2026-03-20T15:39:40Z

@dariusz-biela

Try this one!
simple-illustration__unlocked-green-large.svg.zip

@dubielzyk-expensify I made some tweaks to harmonize the colors a bit more 🙃 🤷‍♂️ (also published this version in our Simple Illustrations file)

…creen

… shared

github-actions · 2026-03-20T21:10:14Z

🚧 @rafecolton has triggered a test Expensify/App build. You can view the workflow run here.

github-actions · 2026-03-20T21:14:46Z

🧪🧪 Use the links below to test this adhoc build on Android, iOS, and Web. Happy testing! 🧪🧪
Built from App PR #84610.

Android 🤖	iOS 🍎
https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-android-Adhoc-6e4dc2e-9be7b50-aa48244787d8863913559889813414fafa8ea867/index.html	https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-ios-device-AdHoc-6e4dc2e-9be7b50-c2e4e52dd4c3b18d9aa456573fc568050ff894b6/index.html

Web 🕸️
https://84610.pr-testing.expensify.com

👀 View the workflow run that generated this build 👀

OSBotify · 2026-03-20T21:18:12Z

✋ This PR was not deployed to staging yet because QA is ongoing. It will be automatically deployed to staging after the next production release.

OSBotify · 2026-03-23T09:50:18Z

🚀 Deployed to staging by https://github.com/rafecolton in version: 9.3.42-0 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

Bundle Size Analysis (Sentry):

Android
iOS

dariusz-biela added 8 commits March 6, 2026 16:10

Add passkey authentication support for MFA

18f0cb7

Implement WebAuthn-based passkey registration and authentication as a new MFA method alongside existing biometrics. Add passkey scenario configuration, translations, and SecureStore integration.

Add as const to PROMPT_NAMES for literal type inference

2852952

Remove type assertions from usePasskeys.ts

41f1caa

Replace as casts for AuthenticatorAttestationResponse and AuthenticatorAssertionResponse with instanceof type guards. Use isSupportedTransport guard for getTransports() filtering.

Remove privateKey from BaseRegisterResult

2c2f281

Private keys should not leak beyond the registration function. For native biometrics the key is stored in SecureStore internally, for passkeys it never leaves the authenticator. No consumer of RegisterResult ever reads privateKey.

Remove console.debug calls from MFA components

f4c0494

These debug logs were development artifacts that could leak sensitive authentication data (credential IDs, challenge content, backend responses) to the browser console in production.

melvin-bot bot assigned dariusz-biela Mar 9, 2026

dariusz-biela added 4 commits March 10, 2026 11:01

Remove useCallback from usePasskeys — React Compiler handles memoization

2bf98b4

Pass excludeCredentials to passkey registration to prevent duplicates

fdd40fe

Reconcile server-known credential IDs with local Onyx credentials and pass the result as excludeCredentials to navigator.credentials.create, preventing the same authenticator from being registered twice.

JakubKorytko approved these changes Mar 11, 2026

View reviewed changes

dariusz-biela added 3 commits March 11, 2026 13:42

Rename helpers.test.ts to processing.test.ts and add passkey/scenario…

2541cca

… tests Remove unnecessary KeyStore mock, add tests for processPasskeyRegistration and processScenarioAction to cover the full processing module.

dariusz-biela force-pushed the dariusz-biela/feat/3ds/passkeys-mfa branch from 18da419 to 8171acc Compare March 11, 2026 21:23

dariusz-biela added 7 commits March 12, 2026 14:53

Simplify useServerCredentials — remove manual memoization and selecto…

8e2846e

…r wrapper React Compiler handles memoization automatically, so useMemo and the module-level selector function are unnecessary.

Extract COSE algorithm identifiers into CONST.COSE_ALGORITHM

9e5d340

Replace magic number -8 with CONST.COSE_ALGORITHM.EDDSA in types and runtime code. Add ES256 and RS256 constants for passkey use.

Remove redundant getLocalCredentials helper — inline null coalescing …

d82dfb5

…directly

Replace thrown errors with onResult callbacks for unexpected WebAuthn…

69022cd

… responses

Add EDDSA to cspell dictionary

2b7dbe3

Add WEBAUTHN.REGISTRATION_REQUIRED reason and use it in usePasskeys

1c5c930

rafecolton previously approved these changes Mar 19, 2026

View reviewed changes

chuckdries previously approved these changes Mar 19, 2026

View reviewed changes

chuckdries mentioned this pull request Mar 19, 2026

Chuckdries/3ds rhp click outside handling software-mansion-labs/expensify-app-fork#317

Closed

52 tasks

Merge remote-tracking branch 'origin/main' into dariusz-biela/feat/3d…

3fb6ae5

…s/passkeys-mfa

dariusz-biela dismissed stale reviews from chuckdries and rafecolton via 3fb6ae5 March 20, 2026 10:25

dariusz-biela added 2 commits March 20, 2026 12:06

Fix PromptPage spinner: stable height matching button, size 28px

53de200

Fix AuthorizeTransactionActions spinner: stable height matching butto…

82f7532

…ns, size 28px

dariusz-biela added 3 commits March 20, 2026 20:12

Replace OpenPadlock illustration with green variant for MFA success s…

4c4c70c

…creen

Replace OpenPadlock illustration with green variant for MFA success s…

3fba7ec

…creen

Fix broken import path in OutcomePage after Biometrics types moved to…

a2742eb

… shared

rafecolton approved these changes Mar 20, 2026

View reviewed changes

rafecolton merged commit 6e4dc2e into Expensify:main Mar 20, 2026
31 checks passed

OSBotify mentioned this pull request Mar 23, 2026

Deploy Checklist: New Expensify 2026-03-23 #86080

Open

69 tasks

lanitochka17 mentioned this pull request Mar 23, 2026

Android - Biometrics - Cannot register biometrics #86108

Open

7 tasks

Conversation

dariusz-biela commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation of Change

Fixed Issues

Tests

Offline tests

QA Steps

PR Author Checklist

Screenshots/Videos

Uh oh!

melvin-bot bot commented Mar 9, 2026

Uh oh!

codecov bot commented Mar 9, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

JakubKorytko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chuckdries commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DylanDylann commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Screenshots/Videos

Uh oh!

github-actions bot commented Mar 19, 2026

Uh oh!

github-actions bot commented Mar 19, 2026

Uh oh!

rafecolton left a comment

Choose a reason for hiding this comment

Uh oh!

dubielzyk-expensify commented Mar 19, 2026

Uh oh!

dubielzyk-expensify commented Mar 19, 2026

Uh oh!

rafecolton commented Mar 20, 2026

Uh oh!

dariusz-biela commented Mar 20, 2026

Uh oh!

dannymcclain commented Mar 20, 2026

Uh oh!

dariusz-biela commented Mar 20, 2026

Uh oh!

dannymcclain commented Mar 20, 2026

Uh oh!

Uh oh!

github-actions bot commented Mar 20, 2026

Uh oh!

github-actions bot commented Mar 20, 2026

Uh oh!

OSBotify commented Mar 20, 2026

Uh oh!

OSBotify commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

dariusz-biela commented Mar 9, 2026 •

edited

Loading

codecov bot commented Mar 9, 2026 •

edited by github-actions bot

Loading

chuckdries commented Mar 19, 2026 •

edited

Loading

DylanDylann commented Mar 19, 2026 •

edited

Loading