feat: add passkeys support for web

auth0_flutter/EXAMPLES.md

@@ -38,6 +38,7 @@
   - [Sign up with database connection](#sign-up-with-database-connection)
   - [Log in with passkeys](#log-in-with-passkeys)
   - [Sign up with passkeys](#sign-up-with-passkeys)
+  - [Passkeys on the Web](#passkeys-on-the-web)
   - [Passwordless Login](#passwordless-login)
   - [Retrieve user information](#retrieve-user-information)
   - [Renew credentials](#renew-credentials)
@@ -1067,6 +1068,7 @@ final credentials = await auth0Web.credentials();
 - [Sign up with database connection](#sign-up-with-database-connection)
 - [Log in with passkeys](#log-in-with-passkeys)
 - [Sign up with passkeys](#sign-up-with-passkeys)
+- [Passkeys on the Web](#passkeys-on-the-web)
 - [Passwordless Login](#passwordless-login)
 - [Passwordless OTP on database connections](#passwordless-otp-on-database-connections)
 - [Retrieve user information](#retrieve-user-information)
@@ -1139,7 +1141,7 @@ final databaseUser = await auth0.api.signup(
 
 ### Log in with passkeys
 
-> This feature is available on **iOS 16.6+** and **Android 9+ (API 28)** only.
+> This feature is available on **iOS 16.6+**, **Android 9+ (API 28)**, and **Web** (modern browsers with WebAuthn support). See [Passkeys on the Web](#passkeys-on-the-web) below for the web-specific flow.
 
 [Passkeys](https://auth0.com/docs/authenticate/database-connections/passkeys) let an existing user log in with a biometric or device PIN instead of a password, using the platform authenticator (Face ID / Touch ID on iOS, the Credential Manager on Android).
 
@@ -1200,7 +1202,7 @@ final credentials = await auth0.api.passkeyCredentialExchange(
 
 ### Sign up with passkeys
 
-> This feature is available on **iOS 16.6+** and **Android 9+ (API 28)** only.
+> This feature is available on **iOS 16.6+**, **Android 9+ (API 28)**, and **Web** (modern browsers with WebAuthn support). See [Passkeys on the Web](#passkeys-on-the-web) below for the web-specific flow.
 
 [Passkeys](https://auth0.com/docs/authenticate/database-connections/passkeys) let users register with a biometric or device PIN instead of a password, using the platform authenticator (Face ID / Touch ID on iOS, the Credential Manager on Android).
 
@@ -1217,10 +1219,17 @@ The SDK exposes **two** methods for passkey signup — `passkeySignupChallenge`
 
 You can identify the new user with any combination of `email`, `phoneNumber`, `username`, `name`, `givenName`, `familyName`, `nickname`, and `picture`, depending on how your connection is configured.
 
+> ⚠️ **Only `email` is accepted by default.** A database connection accepts `email` as the signup identifier unless [Flexible Identifiers](https://auth0.com/docs/authenticate/database-connections/flexible-identifiers) is enabled for it, which additionally lets you sign up with `phoneNumber` and/or `username`. Passing an identifier your connection isn't configured for (for example, `phoneNumber` on an email-only connection) fails the signup challenge request with:
+> ```json
+> { "error": "invalid_request", "error_description": "Invalid user profile attribute: phone_number" }
+> ```
+> Enable Flexible Identifiers for the connection in the [Auth0 Dashboard](https://manage.auth0.com/#/connections/database) (**Authentication > Database > [your connection] > Settings**) if you need to sign up with `phoneNumber` or `username`.
+
 ```dart
 // 1. Request a registration challenge from Auth0. You can identify the new
 //    user with any combination of email, phoneNumber, username, name,
-//    givenName, familyName, nickname, and picture.
+//    givenName, familyName, nickname, and picture — see the note above on
+//    which of these your connection actually accepts.
 final challenge = await auth0.api.passkeySignupChallenge(
     email: 'jane.smith@example.com',
     name: 'Jane Smith',
@@ -1265,6 +1274,123 @@ final credentials = await auth0.api.passkeyCredentialExchange(
 
 </details>
 
+### Passkeys on the Web
+
+Passkeys are supported on web via `Auth0Web`, backed by `@auth0/auth0-spa-js`'s passkey API (requires **auth0-spa-js v2.24.0 or later** loaded on your page). The flow is the same three steps as native (challenge → credential manager → exchange), but step 2 uses the browser's built-in [WebAuthn API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) (`navigator.credentials.create()`/`.get()`) instead of a native platform authenticator.
+
+`Auth0Web.getTokenByPasskey`'s `authResponse` accepts the raw credential object returned directly by `navigator.credentials.create()`/`.get()` — no manual serialization needed (unlike native, which takes a JSON string).
+
+> ⚠️ `navigator.credentials.create()`/`.get()` require a user gesture, so call `passkeySignupChallenge`/`passkeyLoginChallenge` from within a click handler (not, for example, from `onLoad`).
+
+> ⚠️ **`passkeySignupChallenge` only accepts `email` unless Flexible Identifiers is enabled.** Just like native, the identifier you pass (`email`, `phoneNumber`, `username`) must be one your connection is configured to accept — see the note in [Sign up with passkeys](#sign-up-with-passkeys) above.
+
+```dart
+import 'package:auth0_flutter/auth0_flutter_web.dart';
+import 'package:web/web.dart' as web;
+
+final auth0Web = Auth0Web('YOUR_AUTH0_DOMAIN', 'YOUR_AUTH0_CLIENT_ID');
+
+Future<void> signUpWithPasskey() async {
+  // 1. Request a signup challenge from Auth0.
+  final challenge = await auth0Web.passkeySignupChallenge(
+      email: 'jane.smith@example.com',
+      name: 'Jane Smith',
+      givenName: 'Jane',
+      familyName: 'Smith',
+      connection: 'Username-Password-Authentication');
+
+  // 2. Present the browser's WebAuthn UI. `authParamsPublicKey` is already
+  //    decoded and ready to pass directly to navigator.credentials.create().
+  final credential = await web.window.navigator.credentials.create(
+      web.CredentialCreationOptions(
+          publicKey: challenge.authParamsPublicKey
+              as web.PublicKeyCredentialCreationOptions));
+
+  // 3. Exchange the raw credential for Auth0 tokens.
+  final credentials = await auth0Web.getTokenByPasskey(
+      authSession: challenge.authSession,
+      authResponse: credential,
+      connection: 'Username-Password-Authentication');
+}
+```
+
+<details>
+  <summary>Log in with an existing passkey on the web</summary>
+
+```dart
+Future<void> logInWithPasskey() async {
+  final challenge = await auth0Web.passkeyLoginChallenge(
+      connection: 'Username-Password-Authentication');
+
+  final credential = await web.window.navigator.credentials.get(
+      web.CredentialRequestOptions(
+          publicKey: challenge.authParamsPublicKey
+              as web.PublicKeyCredentialRequestOptions));
+
+  final credentials = await auth0Web.getTokenByPasskey(
+      authSession: challenge.authSession,
+      authResponse: credential,
+      connection: 'Username-Password-Authentication');
+}
+```
+
+</details>
+
+#### Handling errors on the web
+
+`passkeySignupChallenge`, `passkeyLoginChallenge`, and `getTokenByPasskey` all throw a [`WebException`](https://pub.dev/documentation/auth0_flutter/latest/auth0_flutter_web/WebException-class.html) on failure, decoded from whatever `auth0-spa-js` throws:
+
+| Source | `WebException.code` | Notes |
+| :--- | :--- | :--- |
+| Challenge request fails (`passkeySignupChallenge`/`passkeyLoginChallenge`) | `PASSKEY_ERROR` | `details['code']` carries the underlying `auth0-spa-js` code, e.g. `passkey_register_error`, `passkey_challenge_error`, `passkey_not_supported` (WebAuthn unavailable in this browser). |
+| `getTokenByPasskey`'s credential-shape check fails | `PASSKEY_ERROR` | `details['code'] == 'passkey_invalid_credential'` — the `authResponse` isn't a valid attestation or assertion response. |
+| `getTokenByPasskey`'s token exchange requires MFA | `MFA_REQUIRED` | Same shape as [`credentials()`/`customTokenExchange()`](#-multi-factor-authentication-mfa) — `details['mfaToken']` is ready to pass to `Auth0Web.mfa(mfaToken:)`. |
+| `getTokenByPasskey`'s token exchange fails for another reason (e.g. `invalid_grant`, `access_denied`, an expired `authSession`) | `AUTHENTICATION_ERROR` | `details['code']` carries the OAuth error code returned by `/oauth/token`. |
+
+```dart
+try {
+  final credentials = await auth0Web.getTokenByPasskey(
+      authSession: challenge.authSession,
+      authResponse: credential,
+      connection: 'Username-Password-Authentication');
+} on WebException catch (e) {
+  if (e.code == 'MFA_REQUIRED') {
+    final mfa = auth0Web.mfa(mfaToken: e.details['mfaToken'] as String);
+    // continue the MFA flow — see Multi-Factor Authentication (MFA) below
+  } else {
+    print('Passkey error: ${e.code} (${e.details['code']}) — ${e.message}');
+  }
+}
+```
+
+> ⚠️ **`navigator.credentials.create()`/`.get()` errors are not `WebException`s.** The WebAuthn ceremony (step 2) is a browser API call your app makes directly — `Auth0Web` has no visibility into it, so its failures surface as a raw [`DOMException`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException), not a `WebException`. Catch it separately and branch on `DOMException.name`, for example:
+> ```dart
+> import 'package:web/web.dart' as web;
+>
+> try {
+>   final credential = await web.window.navigator.credentials.create(
+>       web.CredentialCreationOptions(publicKey: challenge.authParamsPublicKey
+>           as web.PublicKeyCredentialCreationOptions));
+> } on web.DOMException catch (e) {
+>   switch (e.name) {
+>     case 'NotAllowedError':
+>       // The user cancelled the prompt, denied permission, or the operation
+>       // timed out — by far the most common case in practice.
+>       print('Passkey creation was cancelled.');
+>     case 'InvalidStateError':
+>       // A passkey for this account/authenticator already exists.
+>       print('A passkey already exists for this account.');
+>     case 'SecurityError':
+>       // The page's origin doesn't match the relying party ID (misconfigured
+>       // custom domain, or running on an origin other than the one the
+>       // connection's passkeys are configured for).
+>       print('Passkey security error: ${e.message}');
+>     default:
+>       print('Passkey error: ${e.name} — ${e.message}');
+>   }
+> }
+> ```
+
 ### Passwordless Login
 Passwordless is a two-step authentication flow that requires the **Passwordless OTP** grant to be enabled for your Auth0 application. Check [our documentation](https://auth0.com/docs/get-started/applications/application-grant-types) for more information.
 

auth0_flutter/README.md

@@ -9,9 +9,9 @@
 📚 <a href="#documentation">Documentation</a> • 🚀 <a href="#getting-started">Getting started</a> • 🌐 <a href="#api-reference">API reference</a> • 💬 <a href="#feedback">Feedback</a>
 </div>
 
-## What's New: v2.3.0
+## What's New
 
-**auth0_flutter v2.3.0** adds **Passkeys** support. You can now authenticate users with passkeys via the `webAuthentication()` flow on Android, iOS, and Web. See the [Auth0 passkeys documentation](https://auth0.com/docs/authenticate/database-connections/passkeys) for setup instructions.
+**auth0_flutter** supports **Passkeys** on Android, iOS, and Web. On mobile, use `Auth0.api.passkeyLoginChallenge`/`passkeySignupChallenge`/`passkeyCredentialExchange`; on web, use the equivalent `Auth0Web.passkeyLoginChallenge`/`passkeySignupChallenge`/`getTokenByPasskey` (requires `auth0-spa-js` v2.24.0+). See the [Auth0 passkeys documentation](https://auth0.com/docs/authenticate/database-connections/passkeys) for setup instructions.
 
 ## Documentation
 
@@ -588,8 +588,8 @@ void dispose() {
 - [Check for stored credentials](EXAMPLES.md#check-for-stored-credentials) - check if the user is already logged in when your app starts up.
 - [Retrieve stored credentials](EXAMPLES.md#retrieve-stored-credentials) - fetch the user's credentials from the storage, automatically renewing them if they have expired.
 - [Retrieve user information](EXAMPLES.md#retrieve-user-information) - fetch the latest user information from the `/userinfo` endpoint.
-- [Log in with passkeys](EXAMPLES.md#log-in-with-passkeys) - authenticate an existing user with a passkey using the platform authenticator (iOS/Android only).
-- [Sign up with passkeys](EXAMPLES.md#sign-up-with-passkeys) - register a new user with a passkey using the platform authenticator (iOS/Android only).
+- [Log in with passkeys](EXAMPLES.md#log-in-with-passkeys) - authenticate an existing user with a passkey using the platform authenticator (iOS/Android; see [Passkeys on the Web](EXAMPLES.md#passkeys-on-the-web) for the web equivalent).
+- [Sign up with passkeys](EXAMPLES.md#sign-up-with-passkeys) - register a new user with a passkey using the platform authenticator (iOS/Android; see [Passkeys on the Web](EXAMPLES.md#passkeys-on-the-web) for the web equivalent).
 - [Native to Web SSO](EXAMPLES.md#native-to-web-sso) - obtain a session transfer token to authenticate a WebView without re-prompting the user.
 - [Multi-Factor Authentication (MFA)](EXAMPLES.md#-multi-factor-authentication-mfa) - complete an MFA flow mid-login using an `mfa_token`: list, challenge, enroll, and verify factors.
 - [Handle Android process death](#android-handle-process-death-during-login) - recover credentials when the OS kills your app during login.
@@ -605,6 +605,7 @@ void dispose() {
 
 - [Handling credentials on the web](EXAMPLES.md#handling-credentials-on-the-web) - how to check and retrieve credentials on the web platform.
 - [Multi-Factor Authentication (MFA)](EXAMPLES.md#-multi-factor-authentication-mfa) - complete an MFA flow mid-login using an `mfa_token`. Backed by [auth0-spa-js](https://github.com/auth0/auth0-spa-js) and requires auth0-spa-js v2.21.0+ loaded on your page.
+- [Passkeys on the Web](EXAMPLES.md#passkeys-on-the-web) - authenticate with a passkey using the browser's WebAuthn API. Backed by [auth0-spa-js](https://github.com/auth0/auth0-spa-js) and requires auth0-spa-js v2.24.0+ loaded on your page.
 
 ## API reference
 
@@ -784,6 +785,9 @@ try {
 - [credentials](https://pub.dev/documentation/auth0_flutter/latest/auth0_flutter_web/Auth0Web/credentials.html)
 - [mfa](https://pub.dev/documentation/auth0_flutter/latest/auth0_flutter_web/Auth0Web/mfa.html) - drive a Multi-Factor Authentication flow with an `mfa_token`
 - [hasValidCredentials](https://pub.dev/documentation/auth0_flutter/latest/auth0_flutter_web/Auth0Web/hasValidCredentials.html)
+- [passkeySignupChallenge](https://pub.dev/documentation/auth0_flutter/latest/auth0_flutter_web/Auth0Web/passkeySignupChallenge.html) - request a WebAuthn registration challenge to sign up a new user with a passkey. Requires `auth0-spa-js` v2.24.0+.
+- [passkeyLoginChallenge](https://pub.dev/documentation/auth0_flutter/latest/auth0_flutter_web/Auth0Web/passkeyLoginChallenge.html) - request a WebAuthn assertion challenge to log in an existing user with a passkey. Requires `auth0-spa-js` v2.24.0+.
+- [getTokenByPasskey](https://pub.dev/documentation/auth0_flutter/latest/auth0_flutter_web/Auth0Web/getTokenByPasskey.html) - exchange a passkey credential from `navigator.credentials` for Auth0 tokens. Requires `auth0-spa-js` v2.24.0+.
 
 ## Feedback
 

auth0_flutter/example/lib/example_app.dart

@@ -34,7 +34,7 @@ class _ExampleAppState extends State<ExampleApp> {
         Auth0Web(dotenv.env['AUTH0_DOMAIN']!, dotenv.env['AUTH0_CLIENT_ID']!);
     webAuth =
         auth0.webAuthentication(scheme: dotenv.env['AUTH0_CUSTOM_SCHEME']);
-    if (Platform.isWindows) {
+    if (!kIsWeb && Platform.isWindows) {
       windowsWebAuth = auth0.windowsWebAuthentication();
     }
     if (kIsWeb) {
@@ -270,7 +270,7 @@ class _ExampleAppState extends State<ExampleApp> {
                       const SizedBox(height: 10),
                       // DPoP button — not shown on Windows
                       // (DPoP is not yet implemented on that platform)
-                      if (!Platform.isWindows)
+                      if (kIsWeb || !Platform.isWindows)
                         ElevatedButton(
                           style: ElevatedButton.styleFrom(
                             backgroundColor: Colors.deepPurple,