Skip to content

feat(auth): generate the signed-in user's MFA recovery codes - #626

Merged
Tr00d merged 1 commit into
masterfrom
feat/auth.mfa_recovery_codes.generate
Nov 2, 2026
Merged

Tr00d merged 1 commit into
masterfrom
feat/auth.mfa_recovery_codes.generate

Conversation

@Tr00d

@Tr00d Tr00d commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Summary

A signed-in user at aal2 can generate their single set of MFA recovery codes. The plaintext codes are returned once.

Capability: auth.mfa_recovery_codes.generate: MFA Recovery Codes Generate. No capability spec exists; the contract is the auth OpenAPI (POST /factors/recovery-codes).

Public API

// IGotrueClient<TUser, TSession>
Task<RecoveryCodes> GenerateRecoveryCodesAsync(GenerateRecoveryCodesOptions? options = null, CancellationToken cancellationToken = default);

// IGotrueApi<TUser, TSession>
Task<RecoveryCodes> GenerateRecoveryCodesAsync(string jwt, GenerateRecoveryCodesOptions? options = null, CancellationToken cancellationToken = default);

New types:

  • Supabase.Gotrue.Common.RecoveryCodes (sealed record): string FactorId, string FriendlyName, IReadOnlyList<string> Codes (never null). It sits in Common/ from the start because regenerate (auth.mfa_recovery_codes.regenerate) returns the same shape.
  • Supabase.Gotrue.GenerateRecoveryCodes.GenerateRecoveryCodesOptions (sealed record): string? FriendlyName.
await client.ChallengeAndVerify(new MfaChallengeAndVerifyParams { FactorId = totpFactorId, Code = code });
var recoveryCodes = await client.GenerateRecoveryCodesAsync(new GenerateRecoveryCodesOptions { FriendlyName = "Backup codes" });
foreach (var recoveryCode in recoveryCodes.Codes)
{
    // show each code once; they cannot be retrieved again
}

Behavior

  • Operation: POST /factors/recovery-codes with the session's access token as Bearer and the apikey header.

  • Inputs: FriendlyName is optional. When it is null, or no options are given, no body is sent; the server treats the body as optional and names the factor Recovery codes. When it is set, the body is {"friendly_name":"..."}.

  • Output: MFARecoveryCodesSchema maps to RecoveryCodes: id becomes FactorId, friendly_name becomes FriendlyName, and codes becomes Codes. An absent codes maps to an empty list. A 200 with no body throws GotrueException("The auth server returned no recovery codes.").

  • Failures before the wire:

    • GotrueException with Reason Offline when the client is offline.
    • GotrueException with Reason NoSessionFound when there is no session or access token. No request is sent.
  • Failures from the server, surfaced as GotrueException with ErrorCode:

    Status ErrorCode When
    403 insufficient_aal the session is not at aal2
    403 no_authorization anonymous user
    422 mfa_recovery_codes_sole_factor the user has no other verified factor
    422 mfa_verified_factor_exists the user already has recovery codes
    422 mfa_factor_name_conflict another factor has the same friendly name
    422 too_many_enrolled_mfa_factors the user has reached the factor limit
    422 mfa_recovery_codes_enroll_not_enabled recovery codes are disabled on the server

    No new FailureHint.Reason values are added.

  • State: none local. The new recovery_code factor is not in the cached CurrentSession.User.Factors, which ListFactors() reads, until the session is refreshed or the user is fetched again. The XML docs say so.

  • Instrumentation: the gotrue.generate_recovery_codes domain span parents the HTTP span.

Deviations from supabase-js

  • No experimental.recoveryCodes opt-in flag, consistent with the shipped GetRecoveryCodesStatusAsync and UnenrollRecoveryCodesAsync. The XML docs say the feature is experimental on the server.
  • type (always recovery_code) and total (equal to Codes.Count) are not exposed.
  • Failures throw GotrueException instead of returning { data, error }.

Tests

Tier Class Pins
E2E GenerateRecoveryCodesTests live stack: mfa_recovery_codes_enroll_not_enabled for a signed-up user, no_authorization for an anonymous user
Contract GenerateRecoveryCodesContractTests method, path, Bearer and apikey; result mapping; absent codes; empty 200; insufficient_aal, mfa_recovery_codes_sole_factor, mfa_verified_factor_exists; no session or access token (no request sent); offline; cancellation; no context capture
Contract GenerateRecoveryCodesApprovalTests exact body: {"friendly_name":"Backup codes"}, and no body without a name
Contract ObservabilityContractTests the domain span parents POST /factors/recovery-codes

Changed-line coverage: 100% (29 lines). Mutation: 12/12 on changed lines (11 killed, 1 timeout), 0 survivors.

Notes

The local and CI stack cannot generate recovery codes. The auth server leaves GOTRUE_MFA_RECOVERY_CODES_ENROLL_ENABLED off by default, and the Supabase CLI (2.120.0 and current master) exposes no config.toml key for it, so no stack configuration change is possible. A successful generation is therefore pinned by contract tests only, as for the status and unenroll neighbours.

@Tr00d
Tr00d marked this pull request as ready for review November 2, 2026 12:32
@Tr00d
Tr00d merged commit 0772b24 into master Nov 2, 2026
6 checks passed
@Tr00d
Tr00d deleted the feat/auth.mfa_recovery_codes.generate branch November 2, 2026 12:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant