v4.0.0 Release: Case Normalization for Email Addresses (Breaking Change)

[treeder]

We have released v4.0.0 of passkeys. This release introduces a breaking change regarding how email addresses are handled.

Summary

Historically, email addresses were stored and looked up using whatever casing the user entered (e.g., User@Example.com and user@example.com were treated as distinct). In v4.0.0, we now consistently trim whitespace and lowercase all email addresses on both the client and server side before saving, looking them up, or passing them to callbacks.

Why this change was made

Without case normalization, users who registered an account or passkey with a specific casing (e.g., User@Example.com) would find that typing user@example.com during login would create a completely separate session, bypassing their existing registered passkeys. Lowercasing emails is standard practice to avoid these casing mismatch issues.

Breaking Changes & Migration Risk

• Case-Sensitive KV Store: The default userId logic falls back to the email address if no custom emailStart callback is provided. Because Cloudflare KV is case-sensitive, looking up users-user@example.com (lowercased) will not find an existing record stored under users-User@Example.com (mixed case).
• If you use a custom database / custom userId: If your emailStart callback returns a case-insensitive user identifier (like a UUID or database ID), your application will remain backwards-compatible. However, if your database user lookups by email are case-sensitive, you may need to update them or run a one-time migration to lowercase existing email fields.

If you have existing production users with mixed-cased email records, please ensure you migrate their email keys/IDs to lowercase when upgrading to v4.x.