---
name: Passkey
description: Implement WebAuthn passkeys avoiding critical security and compatibility pitfalls.
metadata: {"clawdbot":{"emoji":"🔐","os":["linux","darwin","win32"]}}
---

## Security-Critical Rules
- Challenge must be unique per ceremony — reused challenges enable replay attacks
- Origin validation is mandatory — missing check allows phishing from similar domains
- Store and verify sign count — detects cloned authenticators when count doesn't increment
- Never implement CBOR parsing manually — use established libraries, crypto is hard

## Server Implementation
- Use battle-tested libraries — SimpleWebAuthn (JS), py_webauthn (Python), webauthn-rs (Rust)
- Challenges expire quickly — 60-120 seconds max, store server-side
- Store credential ID as base64 — binary data, needs encoding for database
- Store public key in COSE format — libraries handle this, don't transform it

## Credential Storage Requirements
- Credential ID — unique identifier, used in allowCredentials
- Public key — COSE format, for signature verification
- Sign count — integer, increment check detects cloning
- Transports hint — helps browser suggest correct authenticator

## Registration Traps
- `userVerification: "required"` enforces biometric/PIN — "preferred" may skip verification
- Attestation usually unnecessary — requiring it reduces device compatibility
- Allow multiple passkeys per account — users have multiple devices
- Resident key capability varies — don't assume all authenticators support discoverable credentials

## Authentication Traps
- Empty allowCredentials enables discoverable credentials — but not all passkeys are discoverable
- Timeout too short frustrates users — 120 seconds minimum for cross-device flows
- Cross-device auth (QR code) adds latency — don't timeout during Bluetooth handshake

## User Experience
- Provide password fallback — not all users have passkey-capable devices
- Conditional UI (`mediation: "conditional"`) for autocomplete — passkeys appear in username field
- Clear messaging on registration — users don't understand "security key" terminology
- Account recovery path required — hardware loss shouldn't lock out account forever

## Platform Sync Behavior
- Apple iCloud Keychain syncs across Apple devices — but not to Android/Windows
- Google Password Manager syncs Android + Chrome — but not to Apple devices
- Windows Hello is TPM-backed, local by default — doesn't sync
- 1Password/Bitwarden provide cross-platform sync — broadest compatibility option

## Testing
- Chrome DevTools > Application > WebAuthn — simulate authenticators without hardware
- Virtual authenticators in CI — no physical keys needed for automated tests
- Test both resident and non-resident credentials — different flows
- Cross-browser testing essential — Safari, Chrome, Firefox implementations vary