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 bypass phrase). Content sealed to the vault — and nothing else — is behind this door. See Sealed Vault.

Email activation gates every session-opening path. When activation_required_login is on, an unactivated account is refused a session by web sign-in (login_logic) and by API login (ApiAuth::attemptLogin, the door the native apps use) alike — same setting, same gate. Each refusal re-sends the activation email, and the refusal is only issued after the password verifies, so it discloses nothing about account existence. Pinned by tests/account_security/login_test.php (web) and tests/functional/api/session_keys_test.php (API).

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).

The divert runs on every request, and exempts its own hand-off. The pending state is stashed by the sign-in itself and by the remember-me cookie path (get_user_from_cookie()), so a browser remembered on an account that owes a factor is diverted on each request until the factor is proved — including after the trusted-device cookie is gone, which is what forgetting trusted devices leaves behind. Four requests are exempt, because they are how the factor is proved or abandoned: /verify-totp, the two passkey actions that page calls, and /logout. Diverting any of them is an infinite redirect. The pending state is stashed once per pending login rather than per request, because stashing rotates the session id that carries it.

Dual-role passkeys. Any live passkey may complete the second-factor step at sign-in — there is no per-credential role scoping — so a vault-active passkey necessarily also serves as a sign-in factor. The mitigations are structural, not advisory: vault unlock always demands device user verification (a stolen device without its PIN/biometric opens neither gate), and the possession-factor invariant keeps a second factor enrolled at all times.

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 bypass phrase): require an open unlock window, and code regeneration and bypass-phrase 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."
• Bypass phrase — optional fallback (Argon2id-derived, internally passphrase), for accounts that want a memorized unlocker alongside hardware. Never offered during vault setup — added deliberately from unlocker management, behind a warning that it lowers the vault's strength to the strength of the phrase. Like a recovery code, unlocking with it requires a recent step-up regardless of the 2FA cadence when the account has a second factor.

A code is spent once, everywhere. An activation or reset code is a bearer token: for as long as it resolves, it is the account. Consuming one (deleteTempCode) therefore has to end it for every caller, not only the flow that consumed it — checkTempCode, getIdFromTempCode, and getTempCodeInfo all treat act_deleted as part of what makes a code valid. This matters because Activation::ActivateUser() resolves a code without a separate validity call and is reached straight from login_logic, where an account with no password set is signed in and sent to /password-set. A resolver that honoured a spent code would make an already-used activation email a live credential until its expiry. Codes are never invalidated merely by being read, so re-clicking a link that was never completed still works.

Reset authorizers. "Forgot password" offers whichever the account holds, each routed through the one completion path (PasswordResetAuthorizers::issueResetUrl() mints a single-use account code consumed by password_reset_2_logic, never anything vault-scoped):

• 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.