# MFA Recovery

> **Audience:** Studio users, administrators, and operators recovering account access

ZeroPress Studio requires a TOTP authenticator for every account. A registered
Passkey can serve as an alternative sign-in factor, but Studio does not issue
or accept recovery codes and does not fall back to password-only access.

The correct recovery path depends on what access remains:

| Situation | Recovery path |
| --- | --- |
| The current authenticator still works | Sign in normally; no recovery action is needed |
| TOTP is unavailable, but a Passkey works for this Studio hostname | Sign in with the Passkey and replace TOTP in **Account Security** |
| An Editor, Author, or non-final Administrator cannot use any registered MFA factor | Ask another Administrator to reset the account's access and issue a one-hour setup link |
| The last usable Administrator cannot sign in | Use the separately protected **Maintenance & Recovery** administrator-recovery workflow |
| The database has no Administrator account | Use recovery-only new-administrator bootstrap |

## Replace TOTP while a Passkey still works

If a Passkey is registered for the current Studio hostname, use it at the MFA
step after the normal email-and-password check. Then open **My Account → Account
Security** and replace the authenticator.

Replacing TOTP is a protected account change:

1. Confirm the current account password.
2. Complete the requested MFA step-up with the available Passkey, or use the
   recent successful MFA verification when Studio still considers it fresh.
3. Register the new TOTP secret in an authenticator.
4. Submit one current six-digit code to commit the replacement.

Studio keeps the current browser session, rotates the account's authentication
revision, and ends the account's other sessions. The code used to confirm the
new authenticator is consumed and cannot be reused in the same 30-second
counter step.

A Passkey is scoped to its WebAuthn relying-party ID. A credential registered
for another hostname is not a recovery factor for the current Studio hostname.

## Administrator-assisted recovery for another account

When no registered MFA factor is usable, an Administrator with `users.manage`
can open **Users**, select the affected account, and choose **Reset account
access**. An Administrator cannot use this workflow on their own account.

The reset is intentionally comprehensive. When it succeeds, Studio:

- changes the account to `pending`;
- rotates its authentication revision and ends every session;
- removes the current TOTP factor and every registered Passkey;
- clears outstanding WebAuthn challenges and lockout state; and
- creates a single setup link that expires after one hour.

The Administrator must deliver that link to the intended user through an
appropriate trusted channel. The user opens the link, chooses a new password,
registers a new TOTP authenticator, and completes setup before the link expires.
Reissuing recovery invalidates the previous setup link.

Studio blocks this account-management path when the target is the last active
Administrator. Removing the only usable administrative account would leave no
signed-in account able to complete ordinary user management; use the operator
workflow below instead.

## Recover the last usable Administrator

Administrator recovery is part of **Maintenance & Recovery**, not ordinary
sign-in. It is intended for a self-hosted operator who controls the Worker
configuration but cannot satisfy the selected Administrator account's normal
credentials or MFA.

Before starting:

1. Retain a current, reviewed Studio database backup.
2. Set `STUDIO_SITE_MODE=recovery` and deploy that configuration.
3. Enable the operations surface with its exact-IP allowlist and separate
   `STUDIO_OPERATIONS_TOKEN`.
4. Open `/system/operations` from an allowed address and authenticate with the
   operations token.

Recovery mode blocks normal sign-in and product APIs. The operations boundary
does not use an Administrator password or existing MFA factor to authorize this
specific workflow.

In **Administrator access recovery**:

1. Select the Administrator account.
2. Enter a new password that satisfies Studio's password policy.
3. Keep **Reset the authenticator** selected when the existing TOTP and
   Passkeys cannot be used, or when `STUDIO_AUTH_SECRET` has been replaced.
4. Enter the exact `RECOVER ADMINISTRATOR` confirmation phrase and execute the
   operation.

The operation replaces the password, returns the account to `active`, clears
lockout state, rotates authentication state, and ends all sessions. When MFA
reset is selected, it also removes the TOTP factor, Passkeys, and outstanding
WebAuthn challenges. It does not create a Studio session and does not change
`STUDIO_SITE_MODE`.

After completion:

1. Change `STUDIO_SITE_MODE` to `operational` and deploy the configuration.
2. Sign in with the new password.
3. If MFA was reset, complete the forced TOTP enrollment before using Studio.
4. Verify normal sign-in and Account Security.
5. Disable the operations surface when it is no longer required, or rotate and
   re-restrict its token and allowlist according to the site's operating
   policy.

If the Studio schema also requires an upgrade, recover administrator access in
`recovery` first. Then change to `maintenance`, retain the required backup, and
run the supported forward-only upgrade before returning to `operational`.

## When no Administrator account exists

If the recovery status finds zero users with the Administrator role,
Maintenance & Recovery offers **new-administrator bootstrap** instead of the
account-selection workflow. This is a recovery-only boundary, not a way to
promote an existing Editor or Author.

The operator must acknowledge the current Studio database backup, provide a
new unused email address and password, register and verify a new TOTP factor,
and enter the exact `CREATE RECOVERY ADMINISTRATOR` confirmation phrase. Studio
rechecks that the Administrator count is still zero before atomically creating
the new account and role assignment. Existing users, public Authors, and site
content are left unchanged.

## `STUDIO_AUTH_SECRET` and MFA recovery

`STUDIO_AUTH_SECRET` protects encrypted TOTP secrets and short-lived
authentication state. Replacing or losing it can make every existing TOTP
factor unusable. It does not encrypt WebAuthn public keys.

After configuring one stable replacement secret:

- use a working Passkey for the current hostname and replace TOTP from Account
  Security when possible;
- otherwise use administrator-assisted access reset for a non-final account;
- use the recovery-mode operator workflow for the last usable Administrator.

Other credentials protected by `STUDIO_AUTH_SECRET`, such as supported provider
credentials, may require their own replacement after account access is
restored.

## TOTP replay behavior still applies

Enrollment and replacement consume the submitted TOTP counter step. If a later
screen asks for TOTP while the authenticator still displays the same code, wait
for the next code rather than retrying the consumed one. See
[TOTP Verification](../totp-verification/index.md) for the fixed parameters,
adjacent-step tolerance, and replay policy.

For the full operations boundary and database runbooks, read
[Maintenance & Recovery](../../operations/maintenance-and-recovery/index.md).