Skip to content

feat(auth): verify an MFA recovery code to reach aal2 - #627

Merged
Tr00d merged 2 commits into
masterfrom
feat/auth.mfa_recovery_codes.verify
Nov 2, 2026
Merged

Tr00d merged 2 commits into
masterfrom
feat/auth.mfa_recovery_codes.verify

Conversation

@Tr00d

@Tr00d Tr00d commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Summary

A signed-in user can redeem one of their single-use MFA recovery codes to upgrade the session to aal2, for example after losing their authenticator app.

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

Public API

// IGotrueClient<TUser, TSession>
Task<TSession> VerifyRecoveryCodeAsync(string code, CancellationToken cancellationToken = default);

// IGotrueApi<TUser, TSession>
Task<TSession?> VerifyRecoveryCodeAsync(string jwt, string code, CancellationToken cancellationToken = default);

New types: none.

await client.SignIn(email, password);
var session = await client.VerifyRecoveryCodeAsync("K4M9-X7QP-2AB8-HT3Z");
// the session is now at aal2

Behavior

  • Operation: POST /factors/recovery-codes/verify with body {"code":"..."}, the session's access token as Bearer, and the apikey header.

  • Inputs: code is required and sent exactly as typed. The server ignores letter case, whitespace and -.

  • Output: the 200 AccessTokenResponse deserializes into a Session, which is returned.

  • State on success:

    • The new session replaces CurrentSession and is persisted.
    • Listeners receive UserUpdated and then MfaChallengeVerified, the same sequence as the TOTP Verify.
    • The server signs out the user's other aal1 sessions.
  • Failures before the wire:

    • ArgumentException (ParamName = "code") when the code is null, empty or whitespace.
    • 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 in any of these cases.

  • Failures from the server or response. The current session is kept on every failure.

    Answer Reason ErrorCode
    200 with no body, or without access_token MfaChallengeUnverified (none; message "Could not verify MFA.")
    422, wrong, used or unknown code MfaChallengeUnverified mfa_verification_failed
    403, rejected by the verification hook MfaChallengeUnverified mfa_verification_rejected
    429, verification locked UserTooManyRequests mfa_recovery_codes_locked
    429, rate limited UserTooManyRequests over_request_rate_limit
    422, verification disabled on the server mfa_recovery_codes_verify_not_enabled
    403, anonymous user no_authorization

    These reasons come from the existing mappings; no new FailureHint.Reason values are added.

  • Cancellation: the CancellationToken reaches the HTTP call. It is not passed to the local store and announce steps, which run only after the server has consumed the code. This matches the TOTP Verify.

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

Deviations from supabase-js

  • No experimental.recoveryCodes opt-in flag, consistent with the shipped recovery codes methods.
  • Events: UserUpdated then MfaChallengeVerified, matching the C# Verify. supabase-js emits only MFA_CHALLENGE_VERIFIED.
  • An empty code is rejected with ArgumentException before the wire. supabase-js sends it and gets validation_failed.
  • Failures throw instead of returning { data, error }.

Tests

Tier Class Pins
E2E VerifyRecoveryCodeTests live stack: mfa_recovery_codes_verify_not_enabled for a signed-up user, no_authorization for an anonymous user
Contract VerifyRecoveryCodeContractTests method, path, Bearer and apikey; returned session; session replaced, persisted, and announced as UserUpdated then MfaChallengeVerified; empty 200 and session without access token; mfa_verification_failed, mfa_verification_rejected (session kept), mfa_recovery_codes_locked, verify_not_enabled; missing code; no session; offline; cancellation; no context capture, including with a synchronous transport and a session store that saves asynchronously
Contract VerifyRecoveryCodeApprovalTests exact body {"code":"K4M9-X7QP-2AB8-HT3Z"}
Contract ObservabilityContractTests the domain span parents POST /factors/recovery-codes/verify

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

Notes

  • The local and CI stack cannot verify recovery codes. The auth server leaves GOTRUE_MFA_RECOVERY_CODES_VERIFY_ENABLED off by default, and the Supabase CLI exposes no config.toml key for it. A successful verification is therefore pinned by contract tests only.
  • The two synchronous-transport tests kill the ConfigureAwait(false) mutants after the request. Over a real HTTP call those mutants are unobservable, because the continuation has already left the caller's context.

@Tr00d
Tr00d force-pushed the feat/auth.mfa_recovery_codes.verify branch from c7eec4e to d336d05 Compare November 2, 2026 12:34
@Tr00d
Tr00d marked this pull request as ready for review November 2, 2026 12:46
@Tr00d
Tr00d merged commit d01c630 into master Nov 2, 2026
6 checks passed
@Tr00d
Tr00d deleted the feat/auth.mfa_recovery_codes.verify branch November 2, 2026 13:01
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