Passkeys

RP ID and origin come from the site's own domain (LibraryFunctions::get_absolute_url()) — there is no separate RP-ID/origin setting. Attestation conveyance is none; the credential's public key algorithm is restricted to ES256/RS256. Registration asks for a discoverable credential (residentKey: preferred — usernameless sign-in with an empty allowCredentials list only works with resident keys; preferred, not required, so old security keys still enroll).

Sign-count regression is flagged, not fatal (PasskeyFlaggingCounterChecker): synced passkeys (iCloud Keychain, Google Password Manager) legitimately report a counter of 0 on every use, so only a genuine same-or-lower nonzero counter logs a warning to the error log — no assertion is rejected on that basis alone.

The vault-activation flip (docs/sealed_vault.md): passwordless sign-in is withdrawn from any account that has a Sealed Vault — logic/passkey_login_verify_logic.php checks for one immediately after the assertion verifies and, if found, undoes the session verifyAuthentication() just established and rejects, pointing the user at their password. logic/passkey_login_options_logic.php makes the same check early for an email-scoped request as a friendlier rejection, but the verify-side check is the actual enforcement (a usernameless request has no account to check yet). Step-up and vault-unlock ceremonies are unaffected — only passwordless sign-in is withdrawn.

Persistence

data/passkeys_class.php defines Passkey / MultiPasskey over pkc_passkey_credentials. One row per enrolled credential:

Consumer contract

Every PRF consumer today is a Sealed Vault scope, one context each (ALLOWED_PRF_CONTEXTS): vault-kek (server-custody mail + chat, whose KEK is sent to the server), and the two client-custody contexts vault-passwords-kek (the password manager) and vault-drive-kek (Drive), whose KEK is derived and used only in the browser and never transmitted. The distinct per-scope context is what guarantees one scope's KEK can never unwrap another's key. Every derivation request sets `userVerification: required (not merely preferred`, unlike sign-in/step-up), since a vault unlock demands device user verification. A feature that wants a client-held encryption key beyond the vault is a PRF consumer in the same shape:

1. Call PasskeyService::getDerivationOptions($user, $context) / verifyDerivation($client_response_json, $context). $context must be one of PasskeyService::ALLOWED_PRF_CONTEXTS — add a new entry there when a new consumer enrolls. The context is hashed into a fixed, deterministic PRF salt, so the same context always evaluates the same secret for a given credential.
2. verifyDerivation() returns [User $user, Passkey $credential, string $prf_output_32]. The 32-byte output is per-credential — two enrolled passkeys derive two different secrets for the same context. A consumer must hold one wrapping of its protected key per enrolled PRF-capable credential (PasskeyService::listCredentials($user) to enumerate them, pkc_prf_capable to filter).
3. The derived secret is produced in the browser and transits TLS to the server, which uses it transiently (e.g. as a KEK) and holds it at most in session RAM — never at rest.

Revocation veto hook

Before soft-deleting a credential, PasskeyService::revoke() consults a registry of veto callbacks in registration order:

PasskeyService::onPreRevoke(function (int $user_id, int $credential_id) {
    // throw PasskeyRevocationVetoException('reason') to block the revocation
});

A callback throws PasskeyRevocationVetoException($reason) to refuse the revocation; revoke() re-throws it and does not delete the row. The message surfaces to the user verbatim. This is a plain callback registry rather than the platform signal bus (SignalBus::dispatch()) because the bus catches and logs subscriber exceptions rather than propagating them — it cannot veto synchronously. A consumer (e.g. the mail unlock floor) subscribes at bootstrap and vetoes when deleting its wrapping for that credential would strand its protected key.

API surface

Eight _logic_api() actions under /api/v1/action/* (see API for the full table) plus the free CRUD read GET /api/v1/Passkeys for the credential list — no bespoke listing endpoint. Enrollment always demands proof beyond the session cookie: a second (or later) passkey requires a fresh step-up assertion first, and the very first passkey (nothing to step up with yet) requires the account password (current_password in the passkey_register_options body). Accounts with no password (e.g. OAuth-only) have only the session as an anchor for the bootstrap enrollment. The profile UI always requests PRF at enrollment (prf_capable_requested) — the extension can only be enabled at creation time, and vault consumers need PRF-capable credentials.

JS helper

assets/js/passkeys.js defines window.JoineryPasskeys, a vanilla wrapper around navigator.credentials.create()/get():

JoineryPasskeys.isSupported()       // -> bool: window.PublicKeyCredential + navigator.credentials present
JoineryPasskeys.isPrfLikely()       // -> Promise<bool>, best-effort - never load-bearing
JoineryPasskeys.register(options)   // -> Promise<JSON-ready attestation response>
JoineryPasskeys.authenticate(options) // -> Promise<JSON-ready assertion response>
JoineryPasskeys.derive(options)     // -> Promise<{response, prfOutput}> - response is POSTable, prfOutput is base64url

options is the JSON-ready object a get*Options() service call returns verbatim (challenge, credential ids, and any PRF extension input are base64url strings; the helper decodes them to ArrayBuffers before calling the WebAuthn API and re-encodes the browser's response back to base64url JSON). Page scripts fetch options from the matching action, pass them through the helper, then POST the returned object — wrapped as { credential: ... } (register/step-up/login verify) or { credential: ..., label: ... } (register verify) — to the matching verify action.