Biometrics

The Biometrics feature simulates fingerprint and face ID authentication, allowing you to test WebAuthn and biometric authentication flows without physical biometric hardware. This feature intercepts the WebAuthn API and renders high-fidelity biometric prompt UI.

Overview

This feature provides three modes for biometric simulation:

• Disabled: Rejects all biometric requests immediately (Free tier default)
• Simulated: Shows mock biometric prompts (Face ID, Touch ID, Android Fingerprint)
• Physical: Delegates to real host device WebAuthn (Enterprise tier)

Supported Biometrics

• Face ID: iOS Dynamic Island-style prompt with animated corners
• Touch ID: iOS bottom sheet with fingerprint ridges
• Android Fingerprint: Material You bottom sheet with sensor glow
• Physical: Brief indicator, delegates to real host WebAuthn

Target Users

• Frontend developers implementing WebAuthn
• QA engineers testing biometric authentication
• Security researchers testing passkey security
• Mobile-first developers testing biometric UI

Use Cases

• Test WebAuthn registration and authentication
• Test Face ID simulation on iOS devices
• Test Touch ID simulation on iOS devices
• Test Android fingerprint simulation
• Test passkey implementation
• Debug biometric prompt UI issues

How It Works

Technical Implementation

The feature intercepts WebAuthn APIs in the MAIN world:

navigator.credentials.create(options)  // Registration
navigator.credentials.get(options)    // Authentication

WebAuthn Interception

Registration Flow (create):

1. Site calls navigator.credentials.create(options)
2. Engine intercepts and checks biometric mode
3. If Simulated mode:
   • Generates mock credential ID
   • Stores credential in sessionStorage
   • Shows biometric prompt UI
   • Waits for user approval
   • Returns mock credential
4. If Physical mode:
   • Delegates to original credentials.create
   • Uses real host device WebAuthn
5. If Disabled mode:
   • Rejects with error

Authentication Flow (get):

1. Site calls navigator.credentials.get(options)
2. Engine intercepts and checks biometric mode
3. If Simulated mode:
   • Retrieves stored credential from sessionStorage
   • Shows biometric prompt UI
   • Waits for user approval
   • Returns mock assertion
4. If Physical mode:
   • Delegates to original credentials.get
   • Uses real host device WebAuthn
5. If Disabled mode:
   • Rejects with error

Biometric Prompt Rendering

The feature renders device-specific biometric prompts via a separate rendering engine:

Face ID (iOS):

• Dim overlay with animated corner brackets
• "Face ID" text at top
• Approve/Cancel buttons
• Swipe-up animation for success
• Shake animation for failure

Touch ID (iOS):

• Bottom sheet with rounded corners
• Fingerprint ridges graphic
• "Touch ID" text
• Approve/Enter Password/Cancel buttons
• Press-and-hold animation

Android Fingerprint:

• Material You bottom sheet
• Sensor glow animation
• Fingerprint icon
• Approve/Use PIN/Cancel buttons
• Ripple effect on success

Conditional UI Handling

The engine reads device settings to determine which prompt to render:

window.__emx_biometric_mode  // 'simulated' | 'physical' | 'disabled'
window.__emx_device_features  // { faceId: true, touchId: false, ... }

Prompt Selection Logic:

1. Check device OS (iOS vs Android)
2. Check device features (faceId, touchId, fingerprint)
3. Render appropriate prompt based on combination
4. Fallback to generic prompt if feature not supported

Credential Storage

Mock credentials are stored in sessionStorage for session persistence:

sessionStorage.setItem('emuluxe_biometric_credentials', JSON.stringify([
  {
    id: base64url(credentialId),
    type: 'public-key',
    transports: ['internal'],
    userHandle: userId
  }
]))

Storage Duration: Session-scoped (cleared on page refresh)

Architecture-Specific Implementation

Chrome Extension (Primary)

Location: engine/biometric-engine.js + engine/rendering/biometric-prompt-engine.js

The Chrome Extension is the primary implementation with:

• MAIN world injection via content scripts
• Separate rendering engine for UI
• chrome.storage for configuration persistence
• Extension panel for biometric controls

Key Features:

• Dynamic prompt rendering based on device
• Message passing between engine and renderer
• Conditional UI for different device types
• Session storage for credential management

Web Platform

Location: Not currently implemented

The Web Platform does not currently include biometric simulation. This feature is only available in the Chrome Extension and VS Code Extension (via delegation).

VS Code Extension

Location: src/extension.ts (UI controls only)

The VS Code extension provides:

• UI controls for mode selection (Disabled/Simulated/Physical)
• Biometric type selection (Face ID/Touch ID/Android FP)
• Delegates actual simulation to Chrome Extension

Integration: Since Web Platform doesn't support biometrics, VS Code delegates to the Chrome Extension via platform coordination.

Testing Guide

Enabling the Feature

Chrome Extension:

1. Click Emuluxe toolbar icon
2. Expand "Biometrics" control
3. Use segmented control to select mode: Disabled, Simulated, or Physical
4. For Simulated mode, biometric type is auto-detected from device

VS Code Extension:

1. Open Emuluxe panel (Cmd+Alt+E)
2. Navigate to Device Features
3. Toggle Biometrics controls
4. Select mode and biometric type from dropdowns
5. Delegates to Chrome Extension for actual simulation

Testing Face ID Simulation

Steps:

1. Enable Biometrics in Simulated mode
2. Select an iOS device with Face ID (e.g., iPhone 15 Pro)
3. Navigate to WebAuthn demo site
4. Click "Register" or "Sign in with Face ID"
5. Face ID prompt appears with animated corners
6. Click "Approve" or swipe up
7. Registration/authentication succeeds

Expected Behavior:

• iOS Dynamic Island-style prompt
• Animated corner brackets
• "Face ID" text at top
• Approve/Cancel buttons
• Success animation on approval
• Mock credential returned

Testing Touch ID Simulation

Steps:

1. Enable Biometrics in Simulated mode
2. Select an iOS device with Touch ID (e.g., iPhone SE)
3. Navigate to WebAuthn demo site
4. Click "Register" or "Sign in with Touch ID"
5. Touch ID prompt appears as bottom sheet
6. Click "Approve" or press-and-hold
7. Registration/authentication succeeds

Expected Behavior:

• iOS bottom sheet with rounded corners
• Fingerprint ridges graphic
• "Touch ID" text
• Approve/Enter Password/Cancel buttons
• Press-and-hold animation
• Mock credential returned

Testing Android Fingerprint Simulation

Steps:

1. Enable Biometrics in Simulated mode
2. Select an Android device with fingerprint (e.g., Pixel 8 Pro)
3. Navigate to WebAuthn demo site
4. Click "Register" or "Sign in with Fingerprint"
5. Fingerprint prompt appears as Material You bottom sheet
6. Click "Approve"
7. Registration/authentication succeeds

Expected Behavior:

• Material You bottom sheet design
• Sensor glow animation
• Fingerprint icon
• Approve/Use PIN/Cancel buttons
• Ripple effect on success
• Mock credential returned

Testing WebAuthn Registration

Steps:

1. Enable Biometrics in Simulated mode
2. Navigate to WebAuthn registration demo
3. Enter username
4. Click "Register Passkey"
5. Biometric prompt appears
6. Approve the prompt
7. Passkey registered successfully

Verification:

• Check console for registration logs
• Verify credential stored in sessionStorage
• Test authentication with registered passkey
• Check credential ID format

Testing WebAuthn Authentication

Steps:

1. Enable Biometrics in Simulated mode
2. Ensure a passkey is registered (or use auto-registration)
3. Navigate to WebAuthn authentication demo
4. Enter username
5. Click "Sign in with Passkey"
6. Biometric prompt appears
7. Approve the prompt
8. Authentication succeeds

Verification:

• Check console for authentication logs
• Verify credential retrieved from sessionStorage
• Test with wrong credential (should fail)
• Check assertion signature format

Testing Conditional UI

Test Cases:

1. iOS with Face ID: Renders Face ID prompt
2. iOS with Touch ID: Renders Touch ID prompt
3. Android with Fingerprint: Renders Android fingerprint prompt
4. Desktop without biometrics: Shows generic prompt or error
5. Disabled mode: Rejects immediately without UI

Verification:

• Switch between device types
• Verify correct prompt renders
• Check device feature detection
• Test fallback behavior

Common Issues and Troubleshooting

Issue: Biometric prompt doesn't appear

• Cause: Engine not injected or mode is Disabled
• Fix: Enable Simulated mode, reload page, check console for errors

Issue: Prompt shows wrong type (e.g., Touch ID on Face ID device)

• Cause: Device features not correctly detected
• Fix: Check device selection, verify device feature flags, reload simulation

Issue: Registration succeeds but authentication fails

• Cause: Credential not stored correctly in sessionStorage
• Fix: Check sessionStorage for credentials, verify credential ID format

Issue: "NotSupportedError" from WebAuthn

• Cause: Browser doesn't support WebAuthn or feature disabled
• Fix: Check browser compatibility, ensure HTTPS, verify feature enabled

Issue: Physical mode fails with "NotAllowedError"

• Cause: Host device doesn't support WebAuthn or no biometric hardware
• Fix: Use Simulated mode, check host device WebAuthn support

Issue: Prompt appears but buttons don't respond

• Cause: Rendering engine not receiving click events
• Fix: Check console for renderer errors, verify message passing, reload page

Recommended Testing Sites

WebAuthn Testing

WebAuthn.io - https://webauthn.io/

• Comprehensive WebAuthn testing suite
• Test registration and authentication
• Verify credential storage
• Check error handling

Yubico WebAuthn Demo - https://demo.yubico.com/webauthn/

• Yubico's official WebAuthn demo
• Test passkey registration
• Verify authentication flow
• Check credential management

Passkey Testing

Google Passkeys Demo - https://passkeys.dev/

• Google's passkey demonstration
• Test passkey creation
• Verify cross-device sync
• Check UI flows

Apple Passkeys Demo - https://developer.apple.com/passkeys/

• Apple's passkey documentation and demos
• Test iCloud Keychain integration
• Verify iOS-specific flows
• Check Safari compatibility

Biometric Authentication

FIDO2 Testing Tools - https://webauthn.dene.dev.org/

• FIDO2 Alliance testing tools
• Test various WebAuthn scenarios
• Verify credential formats
• Check compliance

WebAuthn Playground - https://webauthn.guide/

• Interactive WebAuthn playground
• Test registration/authentication
• Verify parameter handling
• Check error states

Benefits for Users

Test Biometric Flows Without Hardware

• No need for devices with biometric sensors
• Test on any device type
• Simulate unavailable biometrics
• No dependency on hardware

Test WebAuthn Implementation

• Verify registration flow
• Test authentication flow
• Check credential storage
• Validate error handling

Debug Biometric Prompt UI Issues

• Inspect prompt rendering
• Test prompt animations
• Verify device-specific styling
• Check accessibility features

Test Passkey Registration/Authentication

• Test passkey creation
• Verify cross-device behavior
• Test credential management
• Check passkey UI flows

Device-Specific Prompt Simulation

• iOS Face ID with Dynamic Island
• iOS Touch ID with bottom sheet
• Android Material You fingerprint
• Authentic user experience

Conditional UI Testing

• Test different device types
• Verify feature detection
• Check fallback behavior
• Validate responsive design

Cross-Platform Consistency

• Same behavior across Extension and VS Code
• Reproducible biometric flows
• Consistent mock credentials
• No reliance on real biometric hardware