Add passkeys (WebAuthn): register from the profile, log in without email

New library dependency: lbuchs/webauthn (^2.2, MIT, zero transitive deps
beyond PHP+OpenSSL+Mbstring, both already required). 'none' attestation --
this only confirms "the same device that registered", not hardware
provenance, the standard trust model for a public site's own passkey login.

Backend
- migrations/010: `passkeys` (one row per registered credential: owner,
  credential_id, public_key, sign_count, label) and `webauthn_challenges`
  (short-lived, single-use, bridging each ceremony's "options" and "verify"
  calls -- user_id set for a registration, null for a login since who's
  signing in isn't known until the credential comes back).
- Config: WEBAUTHN_RP_ID (defaults to APP_URL's host) and WEBAUTHN_RP_NAME.
- PasskeyRepository, WebAuthnChallengeRepository, PasskeyController:
  GET/POST /api/passkeys, POST /api/passkeys/options, DELETE
  /api/passkeys/{id} (all auth), plus the public POST /api/auth/passkey/
  options and /verify for login. Registration always asks for a
  discoverable, user-verified credential -- what makes login usernameless:
  the browser offers whatever passkeys it has for the site, no email first.
- SessionPayload now also exposes `has_passkey` on every user object
  (PasskeyRepository::countForUser() > 0), reused by both the profile page
  and the dismissible notice.
- PasskeyTest: auth guards, options response shape, challenge single-use/
  expiry/purpose/cross-user rules, malformed-input handling, list/remove
  CRUD (seeded rows) -- everything short of a real signature, which isn't
  practical from PHPUnit. 73 tests pass.

Frontend
- lib/webauthn.ts: base64url <-> ArrayBuffer conversion and the two
  ceremonies (registerPasskey, loginWithPasskey), matching the API's wire
  format exactly.
- ProfileView: a Passkeys section -- list with Remove buttons, an "Add a
  passkey" form (label pre-filled from a UA guess).
- LoginView: a "Log in with a passkey" button above the email form, shown
  only when the browser supports WebAuthn.
- PasskeyNotice.vue: dismissible banner across the top of the page
  (`user.has_passkey === false`); dismissal is a week-long localStorage
  timestamp.

Verified against the rebuilt container using a Chrome DevTools Protocol
*virtual authenticator* (real ECDSA signing, no human interaction) end to
end: notice shown -> register a passkey -> notice gone (same page and after
navigating) -> log out -> "Log in with a passkey" with no email typed ->
correct account, notice still gone -> remove the passkey -> notice back ->
dismiss -> stays hidden for ~7 days across pages. Along the way, caught and
fixed a real bug: AuthenticatorData::getCredentialId() returns a raw binary
string, not a ByteBuffer like most of this library's other binary fields --
bin2hex() it directly rather than calling ->getHex().

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-09-04 19:34:53 +01:00
co-authored by Claude Sonnet 5
parent 7da881bb78
commit afdd53ec4c
22 changed files with 1366 additions and 22 deletions
+48 -11
View File
@@ -37,9 +37,11 @@ src/stores/cards.ts Pinia store: one project's cards (CRUD; no reordering --
src/stores/inbox.ts Pinia store: the caller's global inbox (fetch + create)
src/lib/api.ts fetch wrapper, bearer token, typed ApiError
src/lib/cardOrder.ts reorderColumn() -- PUT /api/cards/order, shared by the sidebar and kanban board
src/lib/webauthn.ts base64url <-> ArrayBuffer + the register/login passkey ceremonies
src/components/AppSidebar.vue left nav: Dashboard link, project dropdown, Inbox + form
src/components/CardRow.vue editable text + status chip + delete, one card
src/components/KanbanCard.vue small draggable card for the board columns and the inbox
src/components/PasskeyNotice.vue dismissible "add a passkey" banner across the top of the page
src/views/ DashboardView, ProjectView, LoginView, ProfileView,
VerifyEmailView
```
@@ -111,10 +113,13 @@ side of the move.
## Auth flow
There is no password and no separate sign-up — `LoginView` is just an email
field and a "Send sign-in link" button (`POST /api/auth/magic-link`), for a new
There is no password and no separate sign-up — `LoginView` is an email field
and a "Send sign-in link" button (`POST /api/auth/magic-link`), for a new
address or a returning one alike. On success it shows a "check your email"
message; it does not sign the caller in itself.
message; it does not sign the caller in itself. If the browser supports
WebAuthn, a **"Log in with a passkey"** button sits above the form (see
[Passkeys](#passkeys)) — that one *does* sign the caller in directly, no email
round trip.
- `/verify-email?token=…` is the target for every magic link (sign-in and
email-change confirmation both). `VerifyEmailView` POSTs the token via
@@ -124,14 +129,46 @@ message; it does not sign the caller in itself.
On load, `fetchMe()` validates it via `GET /api/me`; a failure clears it.
- Routes with `meta.requiresAuth` redirect to `/login` (preserving the intended
path) when there is no authenticated user.
- Because the only way to get a session is opening a link, `user.email_verified`
is always `true` for a signed-in user — the frontend doesn't show any
verification nagging or resend UI.
- Because the only way to get a session is opening a link or using a passkey
(which itself requires a prior link-based sign-in to register), `user.
email_verified` is always `true` for a signed-in user — the frontend doesn't
show any verification nagging or resend UI.
## Passkeys
`src/lib/webauthn.ts` wraps the two ceremonies. Both fetch a `{ challenge_id,
options }` pair from the API, decode `options.publicKey`'s base64url fields
(`challenge`, `user.id`, `*Credentials[].id`) into `ArrayBuffer`s, call
`navigator.credentials.create()` / `.get()`, then base64url-encode the
resulting `PublicKeyCredential`'s response back into JSON for the API
(`{ id, response: { clientDataJSON, ... } }`). `passkeysSupported()` is a
one-line `window.PublicKeyCredential` check gating the UI everywhere below.
- **Register** (`ProfileView`, "Passkeys" section) — lists the caller's
passkeys (`GET /api/passkeys`) with a **Remove** button each
(`DELETE /api/passkeys/{id}`), and an "Add a passkey" form: a label input
(pre-filled with a guess from `navigator.userAgent`, e.g. "Mac") and a
button calling `registerPasskey(label)`. On success it appends to the local
list and calls `auth.fetchMe()` so `user.has_passkey` (and the notice below)
updates immediately.
- **Login** (`LoginView`) — the passkey button calls
`auth.loginWithPasskey()`, which adopts the returned session exactly like
`verifyEmail()`, then redirects to `route.query.redirect` or `/`. A
cancelled prompt (`DOMException` named `NotAllowedError`) shows "Cancelled."
rather than a generic error.
- **`PasskeyNotice.vue`** (mounted in `App.vue`, between the header and the
sidebar/main body — spans the full page width) shows when signed in with
`user.has_passkey === false`. Dismissing it writes
`localStorage['passkeyNoticeDismissedUntil'] = Date.now() + 7 days`; the
banner stays hidden until that passes, and reappears immediately (no reload
needed, since `has_passkey` is reactive on the shared `auth.user`) if every
passkey is later removed.
## Profile
`/profile` (`ProfileView`) shows the current address and a **Change email**
form (new address only, no password). On success the API has emailed a
confirmation link to the *new* address and set `user.pending_email` (shown as a
notice until it's opened); the change only lands once that link is opened. The
button shows a live countdown driven by `retry_after` and by `429` responses.
`/profile` (`ProfileView`) shows the current address, the **Passkeys** section
described above, and a **Change email** form (new address only, no password).
On success the API has emailed a confirmation link to the *new* address and
set `user.pending_email` (shown as a notice until it's opened); the change
only lands once that link is opened. The button shows a live countdown driven
by `retry_after` and by `429` responses.