Passkey

---

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