..  include:: ../Includes.rst.txt

..  _usage-recovery:

Recovery
========

If a user loses access to all their passkey devices, they can regain
access using recovery codes.

Recovery codes
--------------

Recovery codes are one-time-use alphanumeric codes generated by the
user. Each set contains 10 codes. The codes are stored in the TYPO3
database as bcrypt hashes -- the plaintext is shown only once at
generation time.

Generating recovery codes
--------------------------

1. Navigate to the passkey management page.
2. Click :guilabel:`Generate recovery codes`.
3. The codes are shown once. **Save them in a secure location.**
4. Click :guilabel:`I have saved my recovery codes` to confirm.

..  warning::

    Recovery codes are shown exactly once. If you lose them, you must
    generate a new set, which invalidates the previous set.

Using a recovery code
----------------------

1. Visit the login page.
2. Click :guilabel:`Use a recovery code` (on the passkey login form or
   felogin integration).
3. Enter your username and one recovery code.
4. You are logged in.
5. The used code is marked as consumed and cannot be used again.

After using a recovery code, enroll a new passkey immediately to
restore full passkey-first authentication.

Code lifecycle
--------------

- Each code can be used exactly once.
- Generating a new set invalidates all previous codes.
- Codes do not expire (but are invalidated on new set generation).
- Used codes are stored as consumed (not deleted) for audit purposes.

See :ref:`ADR-003 <adr-003>` for the design decision on the triple
recovery mechanism.