Context
JSS supports passkeys via src/idp/passkey.js (using @simplewebauthn/server v13.2.2). The implementation works correctly with cross-platform hardware security keys including YubiKey, but there is no documentation specifically calling this out. Users interested in hardware-rooted identity may not realise the support exists.
Deliverable
A user-facing guide (docs/yubikey.md or expansion of docs/authentication.md) covering registration and use of FIDO2 / WebAuthn hardware security keys with JSS. End-to-end, practical, with screenshots / sample flows where helpful.
Verification of current support
Code-level evidence that YubiKey and other cross-platform hardware authenticators work today:
- No
authenticatorAttachment restriction: registration options accept both platform authenticators (Touch ID, Windows Hello) AND cross-platform authenticators (YubiKey USB/NFC, etc.)
- Multi-authenticator per account:
account.passkeys is an array; users can register multiple keys (e.g., YubiKey 5 USB + YubiKey 5C Nano + Touch ID on same account)
- Transport handling:
transports field stored faithfully from the authenticator response (handles usb, nfc, ble, internal)
- Counter-based replay protection: validates monotonic counter per authenticator
- Resident-key / discoverable credential support:
residentKey: 'preferred' allows username-less login flows
- IPv4 / IPv6 RP ID extraction: properly handles edge cases
- DoS protection: bounded challenge storage with expiry and cleanup
- Race protection: unique challenge keys per ceremony
Proposed guide contents
- Brief statement that JSS supports hardware security keys via WebAuthn
- Compatibility list (FIDO2 / WebAuthn-compliant devices: YubiKey 5 series, YubiKey Bio, YubiKey for Mobile, and equivalents from other vendors)
- End-to-end flow: register a YubiKey from the IDP UI
- End-to-end flow: log in with YubiKey (with and without username)
- Multi-authenticator setup notes (key + Touch ID, multiple keys)
- NFC support note (mobile flows)
- Troubleshooting (PIN prompts, browser compatibility, transport edge cases)
- Cross-reference to
src/idp/passkey.js and @simplewebauthn/server
Out of scope (deferred)
- Attestation requirements (some enterprises require attested credentials; separate config option / issue)
- YubiKey-backed Nostr / Schnorr signing (requires native Schnorr support in the device firmware, not yet available)
- Hardware-rooted did:nostr identity (longer-term substrate work)
References
Context
JSS supports passkeys via
src/idp/passkey.js(using@simplewebauthn/serverv13.2.2). The implementation works correctly with cross-platform hardware security keys including YubiKey, but there is no documentation specifically calling this out. Users interested in hardware-rooted identity may not realise the support exists.Deliverable
A user-facing guide (
docs/yubikey.mdor expansion ofdocs/authentication.md) covering registration and use of FIDO2 / WebAuthn hardware security keys with JSS. End-to-end, practical, with screenshots / sample flows where helpful.Verification of current support
Code-level evidence that YubiKey and other cross-platform hardware authenticators work today:
authenticatorAttachmentrestriction: registration options accept both platform authenticators (Touch ID, Windows Hello) AND cross-platform authenticators (YubiKey USB/NFC, etc.)account.passkeysis an array; users can register multiple keys (e.g., YubiKey 5 USB + YubiKey 5C Nano + Touch ID on same account)transportsfield stored faithfully from the authenticator response (handlesusb,nfc,ble,internal)residentKey: 'preferred'allows username-less login flowsProposed guide contents
src/idp/passkey.jsand@simplewebauthn/serverOut of scope (deferred)
References
src/idp/passkey.js@simplewebauthn/serverv13.2.2 (well-maintained, full WebAuthn spec)