<!--
SPDX-FileCopyrightText: 2026 Alembic Pty Ltd

SPDX-License-Identifier: MIT
-->

# Recovery Codes

Recovery codes are one-time backup codes that allow users to authenticate when
their primary two-factor method (e.g. TOTP authenticator app) is unavailable.
Each code can only be used once and is deleted after successful verification.

## Prerequisites

- AshAuthentication configured with a User resource
- A primary authentication strategy (e.g. password)
- Typically paired with TOTP for a complete 2FA setup

## Installation

<!-- tabs-open -->

### Using Igniter (recommended)

```sh
mix ash_authentication.add_strategy recovery_code
```

This creates a recovery code resource, adds the relationship and strategy to
your user resource, and generates a brute force preparation module.

### Manual Setup

Follow the steps below to set up recovery codes manually.

<!-- tabs-close -->

## Recovery Code Resource

Create a resource to store hashed recovery codes:

```elixir
# lib/my_app/accounts/recovery_code.ex
defmodule MyApp.Accounts.RecoveryCode do
  use Ash.Resource,
    data_layer: AshPostgres.DataLayer,
    domain: MyApp.Accounts

  attributes do
    uuid_primary_key :id

    attribute :code, :string do
      allow_nil? false
      sensitive? true
      public? false
    end

    timestamps()
  end

  relationships do
    belongs_to :user, MyApp.Accounts.User, allow_nil?: false
  end

  actions do
    defaults [:read, :destroy]

    create :create do
      primary? true
      accept [:code]
    end
  end

  postgres do
    table "recovery_codes"
    repo MyApp.Repo

    references do
      reference :user, on_delete: :delete
    end
  end
end
```

## Add Strategy to User Resource

Add a `has_many` relationship and the recovery code strategy:

```elixir
# lib/my_app/accounts/user.ex
defmodule MyApp.Accounts.User do
  # ...

  relationships do
    has_many :recovery_codes, MyApp.Accounts.RecoveryCode
  end

  authentication do
    strategies do
      recovery_code do
        recovery_code_resource MyApp.Accounts.RecoveryCode
        brute_force_strategy {:audit_log, :audit_log}
      end
    end
  end
end
```

With the default configuration, recovery codes are 12 characters from an
uppercase alphanumeric alphabet (A-Z, 0-9), hashed with SHA-256.

## Brute Force Protection

Recovery codes require a brute force protection strategy. The options are the
same as for TOTP:

**1. Audit Log (recommended)**

```elixir
brute_force_strategy {:audit_log, :audit_log}
```

Tracks failed verification attempts in the audit log and blocks requests that
exceed the configured failure threshold within a time window. This is the
default when using the Igniter installer, and requires an audit log add-on
(see the [Audit Log tutorial](/documentation/tutorials/audit-log.md)).

The window and threshold are configurable:

```elixir
recovery_code do
  recovery_code_resource MyApp.Accounts.RecoveryCode
  brute_force_strategy {:audit_log, :audit_log}
  audit_log_window {5, :minutes}
  audit_log_max_failures 5
end
```

**2. Rate Limiting (with AshRateLimiter)**

```elixir
brute_force_strategy :rate_limit
```

Requires the `AshRateLimiter` extension and rate limit configuration for the
verify action.

**3. Custom Preparation**

```elixir
brute_force_strategy {:preparation, MyApp.CustomBruteForcePreparation}
```

Create a preparation that implements your own protection logic. The preparation
must implement `supports/1` returning a list that includes `Ash.ActionInput`.

## Generated Actions

The strategy generates two actions on the user resource:

- **`verify_with_recovery_code`** — verifies a recovery code for a user. On
  success, deletes the used code and returns the user. On failure, returns nil.
- **`generate_recovery_code_codes`** — generates new recovery codes for a user.
  Deletes any existing codes and returns the plaintext codes in
  `user.__metadata__.recovery_codes`.

## Generating Codes

```elixir
strategy = AshAuthentication.Info.strategy!(MyApp.Accounts.User, :recovery_code)

{:ok, user} = AshAuthentication.Strategy.action(strategy, :generate, %{user: user}, [])

# The plaintext codes are in metadata (only available at generation time)
codes = user.__metadata__.recovery_codes
#=> ["AB3KMN7QR2XY", "CD5FGH8JT4WZ", ...]
```

Display these codes to the user and instruct them to save them securely. The
plaintext codes are only available at generation time — only hashed values are
stored in the database.

## Verifying Codes

```elixir
strategy = AshAuthentication.Info.strategy!(MyApp.Accounts.User, :recovery_code)

case AshAuthentication.Strategy.action(strategy, :verify, %{user: user, code: "AB3KMN7QR2XY"}, []) do
  {:ok, user} -> # Code valid, user authenticated
  {:error, _} -> # Code invalid or already used
end
```

## Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `recovery_code_resource` | — | The Ash resource that stores recovery codes. Required. |
| `hash_provider` | `SHA256Provider` | Hash provider for hashing codes. |
| `code_length` | `12` | Length of each generated code. |
| `code_alphabet` | `A-Z, 0-9` | Characters used when generating codes. |
| `recovery_code_count` | `10` | Number of codes to generate. |
| `code_field` | `:code` | Attribute on the recovery code resource that stores the hash. |
| `recovery_codes_relationship_name` | `:recovery_codes` | Name of the `has_many` relationship on the user. |
| `user_relationship_name` | `:user` | Name of the `belongs_to` relationship on the code resource. |
| `generate_enabled?` | `true` | Whether to generate the generate action. |
| `verify_action_name` | `:verify_with_<name>` | Name of the verify action. |
| `generate_action_name` | `:generate_<name>_codes` | Name of the generate action. |

## Using a Different Hash Provider

The default `AshAuthentication.SHA256Provider` requires codes with at least 60
bits of entropy. With the default 12-character alphabet of 36 characters, this
gives ~62 bits — comfortably above the minimum.

For shorter, more user-friendly codes, use a slow hash provider:

```elixir
recovery_code do
  recovery_code_resource MyApp.Accounts.RecoveryCode
  hash_provider AshAuthentication.BcryptProvider
  code_length 8
  brute_force_strategy {:audit_log, :audit_log}
end
```

> ### Slow hashes have performance implications {: .info}
>
> Bcrypt and Argon2 are deliberately slow. Verifying a code requires checking
> against each stored hash individually, which may take up to ~1 second with 10
> codes. SHA-256 verification is near-instant because it uses atomic database
> lookups.

See [Recovery Code Security](../topics/recovery-code-security.md) for a detailed
explanation of the trade-offs.

## Security Considerations

1. **Brute force protection is mandatory** — every configuration must specify a strategy
2. **Codes are hashed at rest** — plaintext codes are only available at generation time
3. **Codes are single-use** — each code is deleted after successful verification
4. **Store codes securely** — instruct users to save codes in a password manager or printed copy
5. **Regenerating codes invalidates old ones** — generating new codes deletes all existing codes
6. **Pair with TOTP** — recovery codes are most useful as a backup for TOTP authentication