PixelPilot uiux-biometric-auth.instructions.md

Biometric Authentication UI

Passwords are dying. This file covers WebAuthn/passkeys, biometric prompts, passwordless flows, and how to design authentication that's both more secure AND easier to use than passwords.

---

CRITICAL RULES

1. Always provide fallback — Not all devices support biometrics.
2. Explain benefits — Users need to understand why passkeys are better.
3. Don't force — Offer passkeys, don't mandate them.
4. Clear error states — Biometric failures need specific guidance.
5. Cross-device — Handle device-specific UI gracefully.

---

WEBAUTHN BASICS

Support Detection

// webauthn.ts
export async function checkWebAuthnSupport(): Promise<{
  available: boolean;
  platformAuth: boolean;  // Built-in (fingerprint, Face ID)
  crossPlatform: boolean; // Security keys
}> {
  if (!window.PublicKeyCredential) {
    return { available: false, platformAuth: false, crossPlatform: false };
  }

  const available = true;
  
  // Check for platform authenticator (Touch ID, Face ID, Windows Hello)
  let platformAuth = false;
  try {
    platformAuth = await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
  } catch {}

  // Check for conditional mediation (autofill passkeys)
  let conditionalMediation = false;
  try {
    conditionalMediation = await PublicKeyCredential.isConditionalMediationAvailable?.() ?? false;
  } catch {}

  return {
    available,
    platformAuth,
    crossPlatform: true, // Security keys always available if WebAuthn is
  };
}

Registration Flow

// passkeyRegistration.ts
export async function registerPasskey(
  username: string,
  displayName: string
): Promise<{ success: boolean; error?: string }> {
  try {
    // Get challenge from server
    const options = await fetch('/api/webauthn/register-options', {
      method: 'POST',
      body: JSON.stringify({ username }),
    }).then(r => r.json());

    // Create credential
    const credential = await navigator.credentials.create({
      publicKey: {
        ...options,
        challenge: base64ToBuffer(options.challenge),
        user: {
          ...options.user,
          id: base64ToBuffer(options.user.id),
        },
      },
    }) as PublicKeyCredential;

    // Send to server for verification
    const response = await fetch('/api/webauthn/register-verify', {
      method: 'POST',
      body: JSON.stringify({
        id: credential.id,
        rawId: bufferToBase64(credential.rawId),
        response: {
          clientDataJSON: bufferToBase64(credential.response.clientDataJSON),
          attestationObject: bufferToBase64(
            (credential.response as AuthenticatorAttestationResponse).attestationObject
          ),
        },
        type: credential.type,
      }),
    });

    if (!response.ok) {
      throw new Error('Registration failed');
    }

    return { success: true };
  } catch (error: any) {
    return {
      success: false,
      error: getReadableError(error),
    };
  }
}

function getReadableError(error: Error): string {
  if (error.name === 'NotAllowedError') {
    return 'Registration was cancelled or timed out. Please try again.';
  }
  if (error.name === 'InvalidStateError') {
    return 'A passkey for this account already exists on this device.';
  }
  if (error.name === 'NotSupportedError') {
    return 'Your device doesn\'t support passkeys. Please use a password instead.';
  }
  return 'Something went wrong. Please try again or use a password.';
}