Passkeys
32 files2 packages1 dependency
This pack adds passkeys to your app as a way to sign in without a password. Signed-in users add passkeys from their security settings, and the login page gains a "Sign in with a passkey" button.
- The device picks the account at sign-in, so there is no email to type.
- A passkey sign-in completes the login on its own, since the device already checked the user's fingerprint, face, or screen lock.
- New passkeys are named after the password manager or device that holds them, such as iCloud Keychain, and users can rename or remove them.
- The account owner gets an email whenever a passkey is added or removed.
- Every sign-in keeps the user's password manager in sync, so a passkey removed in your app disappears from their devices.
Apply the passkeys pack with Flow. Start a new session in your selected coding agent and execute the following slash command inside it.
$ npx @adonisplus/flow apply --pack=passkeys --agent=claude
$ npx @adonisplus/flow apply --pack=passkeys --agent=codex
$ npx @adonisplus/flow apply --pack=passkeys --agent=cursor
$ npx @adonisplus/flow apply --pack=passkeys --agent=opencode
After applying, Flow will make the following changes to your app.
- Ask you for your app name and the passkey domain and origins for each environment, offering defaults from your config.
- Establish a Security page to host the passkeys section, wherever your app is missing one.
- Land the backend as shipped, from the migrations and model mixin through the validators, controllers, routes, and the change-notification mailer.
- Add the passkey signals to your login and every other action that completes a login, and share them with the frontend through your Inertia middleware.
- Restyle the passkeys section and the sign-in button to your design system.
- Run the tests, then walk adding, renaming, and removing a passkey and signing in with it, and show you the result.
Delta will differ
Flow adapts the pack to your app, so the exact set of created and edited files depends on what you already have. This is the shape of an apply onto the Vue starter kit with the auth pack in place.
Foundation
security_controller.tsapp/controllers/security_controller.tsRenders the Security page with the user's passkeys.createdsecurity.vueinertia/pages/account/security.vueSecurity page inside the settings layout, rendering the passkeys section.createdsettings.vueinertia/layouts/settings.vueLists the Security page in the settings sidebar.editedapp.vueinertia/layouts/app.vueLinks the settings area in the navigation and renders the passkey signals component.edited
Migrations
xxxx_add_webauthn_user_handle_to_users.tsdatabase/migrations/xxxx_add_webauthn_user_handle_to_users.tsAdds the WebAuthn user handle column to the users table.createdxxxx_create_passkeys.tsdatabase/migrations/xxxx_create_passkeys.tsCreates thepasskeystable.createdxxxx_create_passkey_challenges.tsdatabase/migrations/xxxx_create_passkey_challenges.tsCreates thepasskey_challengestable.created
Environment
env.tsstart/env.tsDeclaresPASSKEY_RP_IDandPASSKEY_ORIGINS.edited.env.envSets the passkey domain and origins for development.edited.env.example.env.exampleDocuments the passkey domain and origins.edited
Model & validators
user.tsapp/models/user.tsAdds thewithPasskeyManagement()mixin and thepasskeysprovider.editedpasskey_transformer.tsapp/transformers/passkey_transformer.tsSerializes the passkeys the Security page lists.createduser.tsapp/validators/user.tsAdds the registration, sign-in, and rename validators.edited
Controllers
passkey_registration_challenges_controller.tsapp/controllers/passkey_registration_challenges_controller.tsIssues the rate-limited registration challenge.createdpasskeys_controller.tsapp/controllers/passkeys_controller.tsAdds, renames, and removes passkeys.createdpasskey_login_challenges_controller.tsapp/controllers/passkey_login_challenges_controller.tsIssues the rate-limited sign-in challenge.createdpasskey_session_controller.tsapp/controllers/passkey_session_controller.tsVerifies a passkey and logs its owner in.createdsession_controller.tsapp/controllers/session_controller.tsFlashes the passkey signals after a password login.edited
Mailer & email template
passkey_changed_notification.tsapp/mails/passkey_changed_notification.tsThe change-notification email for an added or removed passkey.createdpasskey_changed.edgeresources/views/emails/passkey_changed.edgeBody of the change-notification email.created
Routes
routes.tsstart/routes.tsAdds the passkey sign-in and management routes.edited
Passkey signals
inertia_middleware.tsapp/middleware/inertia_middleware.tsShares the flashed passkey signals with the frontend.editedpasskey_signals.vueinertia/components/passkey_signals.vueForwards the passkey signals to the browser.createdauth.vueinertia/layouts/auth.vueRenders the passkey signals component.edited
Screens
passkeys_settings.vueinertia/components/passkeys_settings.vuePasskeys section with the list, rename, remove, and add controls.createdpasskey_sign_in.vueinertia/components/passkey_sign_in.vueThe "Sign in with a passkey" button.createdlogin.vueinertia/pages/auth/login.vueRenders the sign-in button below the login form.edited
Tests
types.tstests/helpers/types.tsType of a recorded passkey signal.createdpasskeys.tstests/helpers/passkeys.tsVirtual authenticator, passkey, and signal-recording helpers.createdregistration.spec.tstests/browser/passkeys/registration.spec.tsAdding a passkey and refusing a duplicate.createdmanagement.spec.tstests/browser/passkeys/management.spec.tsListing, renaming, and removing passkeys.createdlogin.spec.tstests/browser/passkeys/login.spec.tsPasskey sign-in, signals, and rate limiting.created
Configuration
Section titled "Configuration"The withPasskeyManagement() mixin on the User model backs the whole feature. All three options are required.
rpNamestringrequiredrpIdstringrequiredexample.com works on example.com and all its subdomains. Read from the PASSKEY_RP_ID environment variable.originsstring[]requiredrpId domain or a subdomain of it. Read from the comma-separated PASSKEY_ORIGINS environment variable.withPasskeyManagement({
rpName: 'ACME',
rpId: env.get('PASSKEY_RP_ID'),
origins: env.get('PASSKEY_ORIGINS').split(','),
})The DbPasskeysProvider stores passkeys and challenges. Pass an options object as the second argument of forModel to change its defaults.
passkeysTablestringpasskeys.challengesTablestringpasskey_challenges.challengeTtlstring | number5 minutes.static passkeys = DbPasskeysProvider.forModel(User, { challengeTtl: '2 minutes' }) The relying party ID cannot change
Every passkey is bound to the PASSKEY_RP_ID it was created under. Changing it later makes every registered passkey stop working. Pick the final domain before users add passkeys, and use the parent domain (example.com rather than app.example.com) if passkeys must work across subdomains.
Passkeys are named after their authenticator
Section titled "Passkeys are named after their authenticator"A new passkey takes the name of the password manager or device that created it, such as iCloud Keychain or Google Password Manager, and falls back to Passkey for an unknown one. When the user already has a passkey with that name, a number is appended (Passkey 2). Override getDefaultPasskeyName on the User model to name them differently.
getDefaultPasskeyName(aaguid: string, existingNames: string[]) {
return `Passkey ${existingNames.length + 1}`
}The account picker shows the user's email and name
Section titled "The account picker shows the user's email and name"When the user creates or picks a passkey, the device shows the account name and display name stored inside it. getPasskeyUserDetails on the User model sets both. Change it to show a username or another field.
getPasskeyUserDetails() {
return { name: this.email, displayName: this.fullName ?? this.email }
}A passkey sign-in completes the login on its own
Section titled "A passkey sign-in completes the login on its own"A passkey already combines the device with the user's fingerprint, face, or screen lock, so it counts as a full login. It does not go through a second step, even when the account has two-factor authentication turned on.
One passkey per device
Section titled "One passkey per device"Adding a passkey from a device that already holds one for the account shows This device already has a passkey for your account. A passkey already registered to another account is refused too.
Challenges are single-use
Section titled "Challenges are single-use"Every passkey request starts with a challenge the device signs. A challenge works once and expires after five minutes, so a captured response cannot be replayed. A registration challenge is bound to the signed-in user, and a sign-in challenge cannot complete a registration.
Challenge requests are rate limited
Section titled "Challenge requests are rate limited"Each challenge is a database row, so both challenge endpoints allow 10 requests a minute and respond with a 429 after that. The registration limit is per user and the sign-in limit is per IP.
await limiter
.use({ requests: 10, duration: '1 minute' })
.consume(`passkey_login_challenges_${request.ip()}`)Failed sign-ins share one message
Section titled "Failed sign-ins share one message"Every passkey sign-in that the server refuses shows the same Unable to verify the passkey. Please try again message, whatever the cause. A failure in the browser, before the server checks the passkey, shows Unable to sign in with this passkey. A cancelled device prompt shows nothing.
Every sign-in re-syncs the password manager
Section titled "Every sign-in re-syncs the password manager"After any sign-in, with a passkey or a password, the page tells the browser which of the user's passkeys your app still accepts and their current name and email. Password managers that support these signals remove passkeys the user deleted in your app and update the account details they show.
Signing in with a passkey your app no longer has fails, and also tells the password manager to delete that passkey from the device.
Adding or removing a passkey emails the owner
Section titled "Adding or removing a passkey emails the owner"A passkey keeps working after a password reset, so this email is often the only way an owner notices a passkey added by someone who took over their session. The email says so and asks them to remove any passkey they do not recognize. Renaming a passkey sends nothing.
Flow 1.1.0
Section titled "Flow 1.1.0"- The security page now loads the passkeys inside the
passkeysprop, so a partial reload of the page's other props no longer runs that query.
Flow 0.4.0
Section titled "Flow 0.4.0"- Added the pack.