The urn:inbuxa:jmap capability on the signed-in account now carries passkeysAllowed (holds sysPasskeyCreate and no server, tenant or domain switch or external directory turns passkeys off for it) and maxPasskeys. Clients use it to say up front that passkeys are off or the account is at its limit, instead of offering an add the server will refuse. Older servers leave both out and clients fall back to the refusal.
17 KiB
Feature spec: passkeys
Status: approved, 2026-11-18 (John took the recommended answer to each decision below). inbuxa-server #334, asked for on the forum (t/242). Planned for the series after 27.1.
Provenance
This is inbuxa's own design, not a rebuild. Sources, and nothing else:
| Source | License | Used for |
|---|---|---|
W3C Web Authentication Level 3 (https://www.w3.org/TR/webauthn-3/) |
W3C document license | The ceremonies, relying-party id rules, flags, conditional mediation |
webauthn-rs documentation (https://docs.rs/webauthn-rs) |
MPL-2.0 | What the protocol crate checks for us, and what it leaves to the caller |
This repository: the OAuth sign-in path (crates/http/src/auth/oauth/auth.rs, crates/http/src/api/mod.rs), the built-in login page (resources/html-templates/login.html), the in-memory store keys for OAuth codes (KV_OAUTH, KV_OAUTH_DEVICE), the app-password view over account credentials (crates/jmap/src/registry/mapping/account.rs), token revocation by credential version (crates/common/src/auth/access_token.rs) and the audit layer (crates/jmap/src/inbuxa/audit.rs) |
AGPL-3.0-only | Where passkeys plug in, and what they reuse |
Upstream's passkey code (Stalwart 1.1 and later) was not read and must not be: the last upstream import was 0.16.27.
What it is
A user signs in to the browser apps (inbuxa Webmail, inbuxa Admin, any OAuth client) with a passkey instead of a password: one kept in a password manager or on the phone for daily use, and a hardware key as a backup. No external identity provider is needed.
Passkeys sign in on the server's own login page only. IMAP, SMTP, POP3, ManageSieve, CalDAV and CardDAV keep using the password or app passwords: those protocols have no passkey mechanism. The docs say so on the page that explains passkeys.
Data model
The passkey, inbuxa:Passkey
One record per registered passkey, in the fork's own data (_ subspace),
keyed by account. Decision: not a new variant of the account's
credentials list. A server that doesn't know passkeys then still reads every
account, and a passkey can be found by its credential id without loading
accounts.
| Field | Mutability | Meaning |
|---|---|---|
id |
server-set | The record id |
accountId |
create-only | The owning account |
name |
mutable | The user's label, ≤ 64 chars, e.g. "Phone" or "YubiKey" |
state |
server-set | pending until the browser part of registration completes, then active |
registrationUrl |
server-set, pending only |
Where the browser part of registration runs (PK-6) |
rpId |
server-set | The relying-party id it was registered for (PK-3) |
usable |
server-set | rpId equals the server's current one |
backedUp |
server-set | The authenticator said the key is synced (the BS flag) |
transports |
server-set | As reported at registration (usb, nfc, ble, internal, hybrid) |
createdAt |
server-set | When registration completed |
lastUsedAt |
server-set | When it last signed in, or null |
Kept with it, never returned over JMAP: the credential id, the public key (COSE), the signature counter, and the authenticator's AAGUID.
Per account, also in _: the user handle, 32 random bytes made at the
first registration and kept until the account is deleted. It's what the
authenticator stores as the user id. It is neither the account id nor the
address, so a passkey says nothing about the account to anyone who reads it.
Two indexes: credential id → passkey, and user handle → account.
Settings, on x:Authentication
| Field | Default | Meaning |
|---|---|---|
passkeysAllowed |
true | Server-wide on/off switch (PK-12) |
passkeyRpId |
null | The relying-party id. Null means the host of the server's public HTTPS URL (PK-3) |
maxPasskeys |
10 | Per account, 1 to 100 |
x:Domain and x:Tenant each have passkeysAllowed (default true) too.
These are off switches (decision 3): passkeys work for an account only when
the server, its tenant and its domain all allow them.
Permissions
sysPasskeyGet, sysPasskeyQuery, sysPasskeyCreate, sysPasskeyUpdate,
sysPasskeyDestroy, in the default user role for the user's own account,
like the app-password permissions. Reaching another account's passkeys takes
the same permissions plus the rights to manage that account, as for app
passwords.
Required behavior
Relying party
- PK-1. Registration and sign-in use discoverable credentials
(
residentKey: required) with user verification required. Attestation isnone. Algorithms: ES256, ES384, RS256, in that order: the set the WebAuthn library (webauthn-rs) calls tested. EdDSA waits until it does. - PK-2. The origin of every ceremony must be
https://with a host that equals the relying-party id or ends with.plus it, and is one of the server's own HTTP hostnames. Anything else is refused. - PK-3. The relying-party id is
passkeyRpId, or the host of the server's public HTTPS URL when that's unset.passkeyRpIdmay be that host or a registrable parent of it (mail.example.com→example.com), never a public suffix; a write that breaks this is refused withinvalidProperties. - PK-4. A passkey is bound to the relying-party id it was registered for.
When the id changes (the server renamed onto another domain, or
passkeyRpIdchanged), passkeys for the old id readusable: false, are not offered at sign-in, and the webmail and console show them as "Registered for the old name: add a new passkey". Nothing is deleted. The docs advise settingpasskeyRpIdto the parent domain before people register, so a later rename inside that domain keeps every passkey, and the installer's rename steps warn when the change will make passkeys unusable.
Registration
- PK-5.
inbuxa:Passkey/setcreate takesaccountIdandnameand makes apendingrecord with aregistrationUrl. Creating fails withoverQuotaatmaxPasskeys(pending ones count), and withforbiddenwhen passkeys are disabled for the account or the account signs in through an external directory (PK-13). - PK-6.
registrationUrlis a page the server serves itself, like the login page, carrying a single-use ticket valid for 10 minutes. The browser apps open it in a new window. The page asks for the passkey (the browser's own dialog), sends the result back, and says "Passkey added. You can close this window." The browser apps can't run the ceremony themselves: they're on other hostnames than the relying-party id (decision 1). - PK-7. Completing registration turns the record
active, fills the server-set fields, and refuses a credential id already registered to any account. A pending record whose ticket expired is removed. - PK-8. The registration page first asks for the account's password (and its TOTP code when it has one), or for one of its active passkeys, before it asks for the new passkey. A stolen session token alone can't add a passkey: it can start a registration, but not finish one.
Sign-in
- PK-9. The login page offers passkeys when they're allowed server-wide:
through autofill on the username field (conditional mediation) where the
browser supports it, and a "Sign in with a passkey" button. Both the OAuth
authorization-code flow and the device flow (
/device) accept them. - PK-10. The page asks the server for a challenge,
POST /api/auth/passkey, anonymous and limited like the other sign-in requests. The challenge lives in the in-memory store, beside the OAuth codes, for two minutes, and is deleted when used. Any node can answer the next step, as for OAuth codes today; nothing is kept in a node's memory. - PK-11. The login request then carries the assertion instead of a name
and password. The server finds the account by user handle and the passkey by
credential id, checks the signature, the origin (PK-2), the user-verified
flag, and the counter: when both the stored and the new counter are above
zero and the new one isn't higher, sign-in fails and the passkey is marked
as possibly cloned in its log event. Then the same checks run as for a
password: account disabled or locked, client registration, redirect URI,
PKCE, scope. On success, the code or device grant is issued exactly as after
a password, and
lastUsedAtis set. - PK-12. A passkey signs in on its own: it already proves possession and user verification, so an account with TOTP isn't asked for the code after a passkey (decision 2). Failures count toward the same sign-in limits and blocking as wrong passwords.
- PK-13. Passkeys work only for accounts in the server's own directory. A domain that signs in against LDAP, SQL or OIDC (per-domain directories) doesn't offer them: its directory owns sign-in.
Managing
- PK-14.
inbuxa:Passkey/getand/setupdate (nameonly) and destroy, with the permissions above. The request'saccountIdnames the account whose passkeys these are;getwithids: nulllists them. A passkey's id carries its account, so ids never collide across accounts. The ticket inregistrationUrlis returned once, by the create. - PK-15. Destroying a passkey ends every session of the account, the way a password change does today (tokens carry a credential version). Until the grant registry (#435) can end one session, this is the only way to cut off a lost device. The account's password still works.
- PK-16. An administrator can destroy any account's passkeys, which is the recovery path for a user who lost them all. Deleting an account deletes its passkeys, its user handle and both index entries.
- PK-19. The session's
urn:inbuxa:jmapcapability on the signed-in principal's own account carriespasskeysAllowed(it holdssysPasskeyCreateand PK-12 and PK-13 leave passkeys on for it) andmaxPasskeys. A client uses it to say up front that passkeys are off instead of offering an add that the server will refuse. An older server leaves both out; a client then offers the add and shows the refusal.
Recording
- PK-17. Creates, renames and removals are recorded in the audit log by the existing set-method layer, as for app passwords; an administrator reaching another account's passkeys is recorded as such.
- PK-18. Sign-in with a passkey raises the same
auth.successandauth.failedevents as a password, withtype = passkeyand the passkey id, so the Logs page and alerts treat both alike. A refused counter raisesauth.passkey-counter(warn).
Interfaces
- JMAP:
inbuxa:Passkeyas above, underurn:inbuxa:jmap. Like the fork's otherinbuxa:objects it isn't in the registry schema, so inbuxa Admin needs its own passkeys panel; the foursysPasskey*permissions are in the schema. - HTTP:
POST /api/auth/passkey(challenge for sign-in), the login request'spasskeyfield, and the registration page with its two requests (fetch options, send the result), all on the server's own hostname. - inbuxa Webmail: Settings › Security gets a Passkeys list: name, added,
last used, "synced" when backed up, "needs re-adding" when not usable;
add (opens the registration page), rename, remove. Shown only when the
server signs people in on its own page (
signIn: oauth): with the webmail's password form there's nowhere to use a passkey. - inbuxa Admin: the account page lists the account's passkeys with a
remove action and a "Remove all" for recovery. An administrator's own
account gets the same add, rename and remove as in the webmail. The
authentication settings get the three settings above, and domains and
tenants their
passkeysoverride.
Acceptance tests
- Register a passkey with a virtual authenticator from the registration
page: the record goes
pending→activewithrpId,transports,backedUpset (PK-5 to PK-7). - The registration page refuses to ask for a passkey until the password
(and TOTP code) or an active passkey is given (PK-8). At
maxPasskeys,overQuota(PK-5). - Sign in with the passkey through the authorization-code flow and through
/device: both issue tokens;lastUsedAtis set; an account with TOTP isn't asked for a code (PK-9 to PK-12). - An assertion from another origin, without the UV flag, with a counter that went backwards, or for an unknown credential id fails, and counts toward the sign-in limit (PK-2, PK-11, PK-12).
- A challenge issued on one node is completed on another; a used challenge can't be used again; an expired one fails (PK-10).
- Destroying a passkey ends the account's existing sessions; the password still signs in (PK-15).
- Changing
passkeyRpIdmakes older passkeysusable: falseand keeps them (PK-4). Setting it to a public suffix or an unrelated domain is refused (PK-3). - A domain on an external directory: create fails
forbidden, the login page offers no passkey for it (PK-13).passkeys: disabledon a domain does the same for its accounts. - Deleting an account removes its passkeys and user handle; another account can't use a passkey whose user handle belonged to it (PK-16).
- The audit log shows create, rename and destroy; the Logs page shows the
sign-in with
type = passkey(PK-17, PK-18). - The session says
passkeysAllowed: trueandmaxPasskeysfor an account that may add one, andfalseonce its domain switches passkeys off (PK-19). - A server built before this feature starts on a store holding passkeys and signs everyone in with passwords (rollback).
Decisions
Settled by John, 2026-11-18:
- The registration page lives on the mail host (PK-6). The browser apps
are on other hostnames than the relying-party id, so they can't call the
browser's passkey API for it; the server serves one small page for it, next
to the login page. This is the second exception to SPEC.md §5.3 (no web
interface on the mail host), after the login page. Related Origin Requests
(the server listing the webmail and console origins at
/.well-known/webauthn, so they run the ceremony themselves) may be added later as an option, once browsers support it widely. - A passkey signs in on its own (PK-12): no TOTP code after it, because user verification is a second factor already.
- On by default (
passkeysAllowed: true), with off switches per server, tenant and domain. Nobody gets a passkey without adding one.
Also decided in this spec: passkeys stored apart from account credentials; bound to the relying-party id with no automatic move on a rename (PK-4); removing a passkey ends the account's sessions (PK-15); the password stays (no passkey-only accounts); no passkeys for accounts on an external directory (PK-13); "require a passkey" for browser sign-in is later, after this ships.
Implementation status
Built, one PR each:
- Storage and
inbuxa:Passkeymanagement: records in_underN,getand/set(create pending with its registration URL, rename, remove), the four permissions (user, tenant and server administrators by default), removal ending the account's sessions through the credential version, and account deletion. Pending ones expire after 10 minutes. The limit is fixed at 10 until the settings arrive (step 4). - The registration page:
/passkey/registerserved by the server, andPOST /api/passkey/registerwith astartstep (ticket and password, plus the TOTP code when the account has one; anonymous, limited like the other sign-in requests) and afinishstep. Whatstartbegan waits in the in-memory store for up to 5 minutes and is good once. - Sign-in in the authorization-code flow:
POST /api/auth/passkeyfor a challenge, the login request'spasskeyfield (challengeIdand the browser's assertion) in place of the name and password, autofill on the username field and a "Sign in with a passkey" button. The registration page takes an active passkey instead of the password (PK-8), and an app password no longer opens it. Sign-ins by passkey are recorded withvia: passkey, and raiseauth.successwith typepasskey; a counter that didn't go up fails and is logged as a possible clone. - The device flow (
authDevicetakespasskeytoo), the settings above (passkeyRpIdchecked on write against the public URL and the public suffix list), the external-directory rule (PK-13: an account whose domain, or the server, signs in against a directory gets no passkeys), theauth.passkey-counterevent (id 664, warn), and failed passkey sign-ins taggedtype: passkey. The login page offers passkeys only when the challenge endpoint answers (it's 404 when they're off server-wide).
The server side is done.
Then the webmail and console pages.