Biometric unlock (Touch ID / Face ID) via WebAuthn PRF

[xumaple]

What

Touch ID / Face ID unlock for MapoPass, implemented entirely client-side with the WebAuthn PRF extension — no server changes, no new endpoints.

How it works: enrollment creates a platform passkey whose PRF output (Secure-Enclave-backed) is run through HKDF into an AES-GCM key that encrypts the signed-in credentials (username, en_user, aesKey, en_pw) into localStorage. Unlocking re-evaluates the PRF — that's the OS biometric prompt — and decrypts. The passkey is never registered with the backend; the master password is never stored; the localStorage blob is useless without a biometric assertion. The plaintext username lives only inside the ciphertext (usernames are client-side-hashed secrets, so they must not leak into passkey metadata or storage).

UX

• Sign-in: "Use Touch ID" (Face ID on iPhone) button when enrolled. Auto-fires once per page load — never after logout or a cancelled prompt (cancel means "I want to type"). Stale enrollments (master password changed elsewhere, passkey deleted) self-clear with an explanatory message; network failures don't destroy the enrollment.
• Settings: biometric control sits with the username, separated from the password form by a divider. Un-enrolled it's a "Use Touch ID" button; enrolled it flips to a disabled green-check "Touch ID enabled" with an X (tooltip "Turn off Touch ID"). Back/Save row replaced by a corner X to close and a full-width "Change Password" button owned by the password form.
• Post-login offer: top-center snackbar (never collides with the bottom copy snackbars) offering enrollment; "Not now" opts out per device, and the offer retires itself if you enroll from settings while it's up.
• Changing the master password clears the enrollment (cached credentials would be stale) and says so.

Security notes

• Biometrics gate a cached secret; they don't replace the master password. First login always requires the password.
• The biometric check is the OS's: any fingerprint/face enrolled on the device can unlock the enrolled account. Trust boundary = the OS user account (same model as 1Password/Bitwarden).
• Single enrollment slot per browser profile; enrolling overwrites.
• Requires PRF support: Chrome, or Safari on macOS 15 / iOS 18+. Unsupported browsers get a clean error and everything else keeps working.

Testing

• 6 unit tests simulate a PRF authenticator (HMAC over a device secret): round-trip, tamper rejection, wrong-authenticator rejection, no plaintext secrets in storage.
• 8-scenario e2e journey via Chromium's CDP virtual authenticator (hasPrf): sign-up offer, settings enroll/disable, manual unlock, no-auto-fire-after-logout, reload auto-unlock with zero clicks, password change clearing enrollment, offer Enable path, offer retiring after settings enroll.
• Full suites green: 41/41 unit, 24/24 e2e, clean CI=true build.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
website	Ready	Preview, Comment	Jul 16, 2026 4:05am