SECURITY & AUTH

Passkeys & WebAuthn (FIDO2 Biometrics)

Implement passwordless biometric authentication (Touch ID, Face ID, Windows Hello, and hardware keys) with zero SMS/email costs and full phishing resistance.

1. How Passkeys Work in HVT

HVT implements the FIDO2 / WebAuthn standard using asymmetric COSE public-key cryptography. When a user registers a passkey, their device generates a private key that never leaves its secure enclave (Apple Secure Enclave, TPM). The browser returns only the public key to HVT.

During sign-in, HVT issues a cryptographic challenge. The user touches their fingerprint or looks at their camera, the hardware signs the challenge, and HVT verifies the signature.

2. One-Line Sign-in with React SDK

Use the useHVTAuth hook to trigger biometric authentication:

tsx
import { useHVTAuth } from '@hvt/sdk/react';

export function PasskeySignInButton() {
  const { loginWithPasskey } = useHVTAuth();

  const handleSignIn = async () => {
    try {
      // Triggers browser Touch ID / Face ID prompt
      await loginWithPasskey();
      window.location.href = '/dashboard';
    } catch (err) {
      console.error('Passkey auth failed or canceled:', err);
    }
  };

  return (
    <button onClick={handleSignIn} className="passkey-btn">
      Sign in with Fingerprint / Face ID
    </button>
  );
}

3. Registering New Passkeys in Settings

Users can register multiple passkeys (e.g. MacBook Touch ID, iPhone, and a YubiKey backup):

tsx
import { useHVTAuth } from '@hvt/sdk/react';

export function AddPasskeyButton() {
  const { registerPasskey } = useHVTAuth();

  const handleAddPasskey = async () => {
    const res = await registerPasskey({ name: 'MacBook Touch ID' });
    alert('Passkey added: ' + res.name);
  };

  return <button onClick={handleAddPasskey}>Add New Passkey</button>;
}

4. Replay & Cloning Attack Prevention

Every passkey record in HVT tracks an incrementing sign_count. If an attacker attempts to clone a physical authenticator, HVT detects the duplicate or lower sequence counter and immediately blocks the authentication session.