Repository navigation
feat(auth): generate the signed-in user's MFA recovery codes - #626
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A signed-in user at
aal2can 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
New types:
Supabase.Gotrue.Common.RecoveryCodes(sealed record):string FactorId,string FriendlyName,IReadOnlyList<string> Codes(never null). It sits inCommon/from the start because regenerate (auth.mfa_recovery_codes.regenerate) returns the same shape.Supabase.Gotrue.GenerateRecoveryCodes.GenerateRecoveryCodesOptions(sealed record):string? FriendlyName.Behavior
Operation:
POST /factors/recovery-codeswith the session's access token as Bearer and theapikeyheader.Inputs:
FriendlyNameis optional. When it is null, or no options are given, no body is sent; the server treats the body as optional and names the factorRecovery codes. When it is set, the body is{"friendly_name":"..."}.Output:
MFARecoveryCodesSchemamaps toRecoveryCodes:idbecomesFactorId,friendly_namebecomesFriendlyName, andcodesbecomesCodes. An absentcodesmaps to an empty list. A 200 with no body throwsGotrueException("The auth server returned no recovery codes.").Failures before the wire:
GotrueExceptionwith ReasonOfflinewhen the client is offline.GotrueExceptionwith ReasonNoSessionFoundwhen there is no session or access token. No request is sent.Failures from the server, surfaced as
GotrueExceptionwithErrorCode:ErrorCodeinsufficient_aalaal2no_authorizationmfa_recovery_codes_sole_factormfa_verified_factor_existsmfa_factor_name_conflicttoo_many_enrolled_mfa_factorsmfa_recovery_codes_enroll_not_enabledNo new
FailureHint.Reasonvalues are added.State: none local. The new
recovery_codefactor is not in the cachedCurrentSession.User.Factors, whichListFactors()reads, until the session is refreshed or the user is fetched again. The XML docs say so.Instrumentation: the
gotrue.generate_recovery_codesdomain span parents the HTTP span.Deviations from supabase-js
experimental.recoveryCodesopt-in flag, consistent with the shippedGetRecoveryCodesStatusAsyncandUnenrollRecoveryCodesAsync. The XML docs say the feature is experimental on the server.type(alwaysrecovery_code) andtotal(equal toCodes.Count) are not exposed.GotrueExceptioninstead of returning{ data, error }.Tests
GenerateRecoveryCodesTestsmfa_recovery_codes_enroll_not_enabledfor a signed-up user,no_authorizationfor an anonymous userGenerateRecoveryCodesContractTestsinsufficient_aal,mfa_recovery_codes_sole_factor,mfa_verified_factor_exists; no session or access token (no request sent); offline; cancellation; no context captureGenerateRecoveryCodesApprovalTests{"friendly_name":"Backup codes"}, and no body without a nameObservabilityContractTestsPOST /factors/recovery-codesChanged-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_ENABLEDoff by default, and the Supabase CLI (2.120.0 and current master) exposes noconfig.tomlkey 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.