Passkey Authentication

Chipi wallets support two authentication methods:

| Method | Security | UX | Recommended | |--------|----------|-----|-------------| | Passkey (biometric) | Strong — device-bound, 256-bit key | One-tap fingerprint/face | Yes | | PIN (4-digit) | Weak — limited entropy | Manual input | No |

Passkeys use the WebAuthn PRF extension to derive a deterministic 256-bit encryption key from the user's biometric. The private key is encrypted with this key and stored in Clerk metadata. No secrets leave the device.

1. Registration: Browser creates a passkey credential with PRF extension enabled
2. Authentication: User scans fingerprint/face, browser evaluates PRF with a salt
3. Key derivation: PRF output (256-bit) is converted to a hex encryption key
4. Encryption: Wallet private key is AES-encrypted with this key
5. Storage: Encrypted key stored in Clerk unsafeMetadata.chipiWallet.encryptedPrivateKey

The same passkey + salt always produces the same encryption key. This is what makes multi-device work — register the same user on multiple devices, and each can decrypt the wallet.

Not all browsers support the PRF extension. The SDK auto-detects:

• - Chrome 116+: Supported
• - Edge 116+: Supported
• - Safari 17.4+: Supported
• - Firefox: Not yet supported
• - Expo (native): Uses device biometrics + secure storage (not WebAuthn)

If PRF is not supported, the component falls back to PIN.

typescriptimport { isPRFSupported } from "@/lib/prf-encryption";

const canUsePasskey = await isPRFSupported();

Users can register passkeys on multiple devices:

1. Create wallet with passkey on iPhone
2. Register a new passkey on laptop (same Clerk account)
3. Both devices can sign transactions

Each credential is stored in passkeys.credentials[]. All PRF-enabled credentials can decrypt the wallet because they use the same salt to derive the same key.

Passkey Manager: The passkey-manager component lets users add, view, and delete passkeys across devices.

• - PIN is not recommended: 4-digit PIN = 10,000 possible combinations. Use passkeys.
• - Passkey = device-bound: The encryption key never leaves the device hardware.
• - No recovery: If all passkeys are lost and no PIN backup exists, the wallet is locked.
• - Always recommend backup: Encourage users to register a security key (USB/NFC) as a backup.
• - Don't store PINs: Never log, persist, or transmit the PIN or encryption key.