Account Security

The one place the platform's identity-and-access doctrine is written down: what gets a user in, what each credential is allowed to open, and what every sensitive action demands. The mechanics live in their own docs — Passkeys for the WebAuthn ceremonies, Sealed Vault for the encryption capability — this doc owns the rules that tie them together. When a new feature needs to decide "what should this action require?", the answer comes from here.

The two doors

An account has up to two doors, and they are deliberately different:

• The session — proves identity. Opened by password sign-in (or passkey sign-in where allowed, below). A session reads and does everything that is not sealed.
• The vault — proves presence. Opened only by a live unlocker ceremony (a passkey assertion with user verification, a one-time recovery code, or an enrolled passphrase). Content sealed to the vault — and nothing else — is behind this door. See Sealed Vault.

The role split: a passkey never opens both doors

A passkey never opens both the session and the vault on the same account.

• An account without a vault may use a passkey for passwordless sign-in — there is nothing behind the second door, so the single credential guards a single door.
• Activating a vault flips it: setup refuses to start until the account has a working password, and from then on passkey_login_verify rejects passwordless sign-in for that account. The passkey remains fully usable as a step-up confirmation and as the vault unlocker — only passwordless sign-in is withdrawn. (Mechanics: Sealed Vault § The vault-activation flip.)

Step-up confirmation

Any feature can demand "re-confirm your second factor before this". Passkey and TOTP step-ups share one short-lived verified marker (session-bound, stored server-side in pks_passkey_ceremonies, kind stepup): a passkey step-up writes it via PasskeyService::verifyStepUp(), a TOTP step-up via SessionControl::stamp_second_factor(). Step-up proves the account owner is present at this keyboard now; a stolen session cookie cannot mint one.

SessionControl::require_recent_second_factor($return_url) is the shared gate a sensitive administration action calls: it returns a redirect to the /verify-stepup ceremony (which confirms with a passkey or a TOTP/backup code, stamps the marker, and returns to $return_url) when no recent confirmation exists, or proceeds otherwise. It is a no-op for an account with no second factor enrolled — there is nothing to step up with. The line the gate draws: *the vault gates plaintext redirection; the second factor gates administration. Domain security-level changes are gated this way today; the same helper is how the remaining sensitive-administration actions adopt the gate.

Fortress mandatory two-factor enrollment

A user who owns or holds a grant on a Fortress-level domain (InboundEmailDomain::maxSecurityLevelForUser()) must have a second factor enrolled that is independent of any single passkey: TOTP, or at least two passkeys (SessionControl::user_has_independent_second_factor()). One passkey alone does not satisfy it — the vault-holder password reset excludes the passkey that authorized it and demands another factor, so enrollment must guarantee that a lone stolen authenticator can never be both the reset authorizer and its own confirmation. Until a qualifying factor exists, SessionControl::must_enroll_2fa_for_fortress() blocks every page behind a redirect to /profile/security (the same session-cached, enrollment-surface pattern the admin-2FA requirement uses) — exempting only that page and /logout to avoid a loop. Enrolling a qualifying factor clears the gate immediately. The posture lookup is cached per session and dropped when the acting user changes a domain's level.

Second factor at sign-in

Whether a second factor is asked at password sign-in is the account's 2FA cadence (usr_2fa_cadence): every_login asks it on each sign-in; sensitive_only signs in password-only and defers the factor to the step-up gate above. When it is asked, the sign-in stashes a pending-login state and diverts to /verify-totp, which offers either a TOTP/backup code or a passkey step-up (login_2fa_passkey_options/_verify) — both finish through the same Login2fa::completePendingLogin(). The divert fires whenever the account holds any usable second factor (user_has_second_factor() — TOTP, or a live passkey while passkeys_enabled is on), so a passkey-only account is asked for its passkey at sign-in rather than silently skipping the second factor. Passkeys stop counting while passkey sign-in is disabled site-wide, so turning the setting off drops a passkey-only account to password-only sign-in instead of stranding it at a factor prompt it cannot complete. This is separate from the vault: a passkey used here confirms presence for the session; it does not open the vault (that is a distinct user-verification ceremony).

Separation nudge. When a passkey both signs the user in and unlocks their vault, one stolen device holds both gates. The security page warns — never blocks — steering toward a separate login factor (a phone authenticator) from the vault passkey (a laptop or hardware key).

Enrollment is guarded

Adding a credential is itself a sensitive action — a session thief must not be able to quietly enroll their own key:

• First passkey on an account: requires the account password re-entered.
• Additional passkeys: require a recent step-up with an existing passkey.
• Vault unlockers (another passkey wrapping, regenerated recovery codes, a passphrase): require an open unlock window, and code regeneration and passphrase changes additionally require a recent step-up.

• Passkey — the everyday unlocker: one tap, user verification required.
• Recovery codes — one-time, for disasters, so the strictest path: when the account has a second factor, a recovery-code unlock requires a recent step-up regardless of the 2FA cadence (the API returns a second_factor_required flag that routes the user through /verify-stepup first). On use it ends every open window everywhere (VaultUnlock::lockAll()) and then opens one only for the recovering session, and emails a security alert to the account — so a stolen code lands the thief in a re-locked vault while the owner is notified. Consuming one drops the vault into a regenerate recommended state once fewer than 3 remain unused. Recovery codes are vault-only: they answer "give me my data," never "log me in."
• Passphrase — optional fallback (Argon2id-derived), for accounts that want a memorized unlocker alongside hardware.

• Email link — the reset link mailed to the account email (and to a verified recovery address, if set). Today's flow, unchanged.
• Passkey — a sessionless ceremony (password_reset_passkey_options/_verify), reusing the passwordless sign-in dispatch. For a vault holder the passkey is not enough on its own: the ceremony additionally requires an independent second factor (TOTP, or a passkey other than the one that authorized the reset) at /password-reset-2fa — without it a stolen authenticator could reset, sign in, and unlock with one key, the collapse the role split forbids. A vault holder with no independent factor accepts passkey-alone as their floor, consistent with declining 2FA everywhere else.
• TOTP alone — for accounts without a vault only (password_reset_totp_logic); a vault holder is refused and steered to the passkey path before any code is verified, so a denied reset never burns a backup code. Rate-limited.
• External recovery address — an out-of-band inbox the reset link is also sent to (usr_recovery_email, verified via recovery_verify_logic; set/removed under step-up in security_logic). Vault recovery codes are never account-reset authorizers — they answer "give me my data", never "log me in", and are only consumed by vault_unlock_recovery_logic.

Sealing protects content at rest — it does nothing about a setting that redirects a sealed mailbox's future mail before it is ever sealed. A filter's "Forward to" action, an alias's destination list, or its delivery mode all act at receive time on the plaintext parse, upstream of sealing entirely — a control-plane bypass that leaves the content encryption technically intact while quietly routing around it. So once a mailbox is sealed (its single owner holds a Sealed Vault), a mutation to any of these is refused unless the owner has an open unlock window — proof of active, in-the-moment consent to the routing change, not just a permission check.

This is enforced where the mutation happens (`plugins/mailbox/logic/ admin_mailbox_filters_logic.php's _filter_require_unlock()`, admin_mailbox_alias_logic.php's _mailbox_alias_require_unlock()), not as a new platform mechanism: both call the existing VaultUnlock::isOpen($owner_id). Because that check is scoped to the calling session, it can only ever be satisfied by the owner's own logged-in session — an admin managing someone else's sealed mailbox structurally cannot open that owner's vault, so the mutation is refused with a clear message rather than a raw permission error. A domain-wide filter scope (no single owner) and a brand-new alias (no established owner/grant relationship yet) are never gated. Outbound relay SMTP settings (mailbox_forwarding_smtp_*) — repointing the relay routes future outbound plaintext through an attacker's box — are gated too: the core settings-save (adm/logic/admin_settings_logic.php) refuses a change to any setting a plugin declares in its vaultGatedSettings manifest list (VaultGatedSettings) while the acting account holds a vault with no open window, saving the rest and prompting the user to unlock and save again. The list is plugin-declared, so the closed set of reroute settings never becomes a core dependency on any one plugin.

What each action requires

Native app: sessions and TOTP

The iOS member app's Security screen (ios/joinery-kit/Sources/JoineryMemberKit/SecurityScreen.swift, reached from Settings) renders app sessions and TOTP status natively, backed by two /api/v1 actions:

• security_overview (read) — TOTP enabled flag and enrollment time, backup-codes-remaining count, the app-session list (device label, created time, last-used time, an is_current flag on the key that made the request), passkey count, and vault-active flag. It is the only read surface for ApiKey — the model gets no CRUD exposure; this payload is it.
• security (mutation) — the same TOTP and app-session actions the web security page uses: start_enable / confirm_enable / cancel_enable / regenerate_backup_codes / disable for TOTP, revoke_app_session / revoke_all_app_sessions for sessions. The enable flow's response carries the provisioning_uri (an otpauth:// string) the native screen renders as a QR with CIFilter.qrCodeGenerator — the same value the web page's SVG QR encodes.

Passkey and Sealed Vault management stay web-only. WKWebView does not expose platform WebAuthn to an embedded webview, so the only possible native path is ASAuthorizationPlatformPublicKeyCredential (with PRF for the vault) — a policy decision of its own (passkey_register_options, passkey_rename, and passkey_revoke currently require the browser-session credential; see API § Two authorization axes). The native Security screen shows passkey count and vault status from security_overview and links out to the web security page for management; native enrollment and revocation belong to a dedicated future mobile_native_security_credentials spec.