ZeroPress Studio Guide

Documentation

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 for the fixed parameters, adjacent-step tolerance, and replay policy.

For the full operations boundary and database runbooks, read Maintenance & Recovery.