Files
inbuxa-server/docs/spec/features/passkeys.md
jcoffey-dev d16d5982ea
ci / fork-checks (pull_request) Skipped
ci / build (pull_request) Skipped
github/ci (branch) GitHub Actions
ci / github (pull_request) Successful in 13m5s
Passkeys: say in the session whether adding one is allowed (PK-19)
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.
2026-11-18 22:56:34 -07:00

17 KiB
Raw Permalink Blame History

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 is none. 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. passkeyRpId may 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 with invalidProperties.
  • 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 passkeyRpId changed), passkeys for the old id read usable: 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 setting passkeyRpId to 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/set create takes accountId and name and makes a pending record with a registrationUrl. Creating fails with overQuota at maxPasskeys (pending ones count), and with forbidden when passkeys are disabled for the account or the account signs in through an external directory (PK-13).
  • PK-6. registrationUrl is 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 lastUsedAt is 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/get and /set update (name only) and destroy, with the permissions above. The request's accountId names the account whose passkeys these are; get with ids: null lists them. A passkey's id carries its account, so ids never collide across accounts. The ticket in registrationUrl is 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:jmap capability on the signed-in principal's own account carries passkeysAllowed (it holds sysPasskeyCreate and PK-12 and PK-13 leave passkeys on for it) and maxPasskeys. 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.success and auth.failed events as a password, with type = passkey and the passkey id, so the Logs page and alerts treat both alike. A refused counter raises auth.passkey-counter (warn).

Interfaces

  • JMAP: inbuxa:Passkey as above, under urn:inbuxa:jmap. Like the fork's other inbuxa: objects it isn't in the registry schema, so inbuxa Admin needs its own passkeys panel; the four sysPasskey* permissions are in the schema.
  • HTTP: POST /api/auth/passkey (challenge for sign-in), the login request's passkey field, 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 passkeys override.

Acceptance tests

  1. Register a passkey with a virtual authenticator from the registration page: the record goes pending → active with rpId, transports, backedUp set (PK-5 to PK-7).
  2. 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).
  3. Sign in with the passkey through the authorization-code flow and through /device: both issue tokens; lastUsedAt is set; an account with TOTP isn't asked for a code (PK-9 to PK-12).
  4. 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).
  5. A challenge issued on one node is completed on another; a used challenge can't be used again; an expired one fails (PK-10).
  6. Destroying a passkey ends the account's existing sessions; the password still signs in (PK-15).
  7. Changing passkeyRpId makes older passkeys usable: false and keeps them (PK-4). Setting it to a public suffix or an unrelated domain is refused (PK-3).
  8. A domain on an external directory: create fails forbidden, the login page offers no passkey for it (PK-13). passkeys: disabled on a domain does the same for its accounts.
  9. Deleting an account removes its passkeys and user handle; another account can't use a passkey whose user handle belonged to it (PK-16).
  10. The audit log shows create, rename and destroy; the Logs page shows the sign-in with type = passkey (PK-17, PK-18).
  11. The session says passkeysAllowed: true and maxPasskeys for an account that may add one, and false once its domain switches passkeys off (PK-19).
  12. 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:

  1. 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.
  2. A passkey signs in on its own (PK-12): no TOTP code after it, because user verification is a second factor already.
  3. 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:

  1. Storage and inbuxa:Passkey management: records in _ under N, get and /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).
  2. The registration page: /passkey/register served by the server, and POST /api/passkey/register with a start step (ticket and password, plus the TOTP code when the account has one; anonymous, limited like the other sign-in requests) and a finish step. What start began waits in the in-memory store for up to 5 minutes and is good once.
  3. Sign-in in the authorization-code flow: POST /api/auth/passkey for a challenge, the login request's passkey field (challengeId and 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 with via: passkey, and raise auth.success with type passkey; a counter that didn't go up fails and is logged as a possible clone.
  4. The device flow (authDevice takes passkey too), the settings above (passkeyRpId checked 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), the auth.passkey-counter event (id 664, warn), and failed passkey sign-ins tagged type: 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.