Passkey UX specification for AI coding agents.
AI agents generate passkey implementations that look correct but contain systematic errors — wrong enrollment timing, missing fallback paths, silent authenticator exclusions, and W3C privacy violations. This repository gives agents the rules they're missing.
PASSKEY.md is the core artifact: 12 anti-patterns with rationale, CORRECT/INCORRECT examples, and cross-references to the W3C and FIDO Alliance specs.
advanced-protection-program.md covers high-assurance account protection: what qualifies as an Advanced Protection Program, how to choose a recovery model, and six APP-specific anti-patterns for AI coding agents.
Reference PASSKEY.md from your agent's knowledge system before generating any passkey code.
Add it via your agent's config — for example, in Claude Code's CLAUDE.md:
@https://raw.githubusercontent.com/YubicoLabs/passkey-ux/main/PASSKEY.md
The same URL works in Cursor (.cursorrules), GitHub Copilot (.github/copilot-instructions.md),
and any RAG or custom agent system that accepts URL or file references.
examples/ contains three spec files. Together they give your agent a complete behavioral specification — independent of language or framework.
examples/
├── README.md ← start here: which files you need and how to use them
├── spec.md ← behavioral requirements and BDD acceptance scenarios
├── api.md ← server API contract: endpoints, request/response shapes, error rules
└── flows.md ← client state machine: navigation, nudge logic, conditional UI lifecycle
See examples/README.md for the 5-step workflow and a ready-to-use agent prompt.
| Use case | Start here |
|---|---|
| Add passkey rules to an AI agent | PASSKEY.md |
| Design a high-assurance authentication program | advanced-protection-program.md |
| Build a server-side implementation | examples/api.md |
| Build a client-side implementation | examples/flows.md |
| Write acceptance tests | examples/spec.md |
| Understand the full behavioral spec | examples/README.md |
AI agents produce these errors by default. Each maps to a numbered anti-pattern in PASSKEY.md.
| Anti-pattern | What breaks |
|---|---|
| AP-01 — No fallback path | Users are locked out on any device without a registered passkey |
| AP-02 — Passkey-only on new device | First login on a new device fails with no recovery path |
| AP-03 — Revealing credential existence | Error messages enable account enumeration; violates W3C §14.5 |
| AP-04 — Enrollment during registration | Passkey prompt appears before trust is established; conversion drops 3–4× |
| AP-05 — Conditional UI only | Sign-in is invisible on Firefox; no modal fallback |
| AP-06 — Platform-lock | authenticatorAttachment: "platform" silently excludes security keys and cross-device QR |
All 12 anti-patterns — with full rationale, CORRECT/INCORRECT examples, and references — are in PASSKEY.md.
Found an error in the spec or an anti-pattern we haven't documented? Open an issue with:
Platform: [iOS / Android / Chrome / Firefox / Safari / Security key / other]
Anti-pattern: [AP-XX or description]
Agent output: [code snippet]
Failure: [what went wrong for the user]