proposed core.account-verification

Verify an account's address after its correct password

A correct password proved an account whose address is not proved yet. The engine mails a 6-digit code to the transaction's identifier through the capped sender of PRO-14 and asks for it. A right code, answered outside the email-code ladder's wait and within 10 minutes, marks the address verified, and the sign-in goes on with no amr added. A wrong code is refused and counted, in the transaction and on the ladder; the 5th wrong answer of a transaction burns the code and ends the transaction. An answer without a code asks for a new one, once a minute.

What this view shows

the email_code step with the purpose verify_account, from the first code after a correct password to the address marked verified, round by round.

Open world: what is not drawn here is not ruled out. Only the guarantees below are binding.

Left out of this view:

what every round runs before rule 8, drawn by flows/core/sign-in: the transport's checks, the MFA policy, the limiters, the request checks, the bot challenge, the identifier, and the account read again, which ends the transaction for an account that is gone, of another user or disabled since
an MFA policy that requires a second factor the account lacks: the engine answers the set-up step before this flow starts (today a redirect, until #653 adds one), never a code; a second factor the account has is asked for after this flow (#653)
an account whose primary identity is a passkey or a wallet, or a transaction with no identifier: there is no address to prove, and the engine never starts this flow
a transport that does not serve email_code (a FiPA client that did not list it): the engine answers a redirect
the purposes recovery (#642) and verify_account at registration (#640), with 8 digits, and the FiPA endpoint's per-client confirm_sign_in after the password (PRO-22), which the Interaction API never offers: the same code rules, other flows. The forced password update of flows/core/sign-in (#635) runs these rounds with the purpose recovery and 8 digits, to prove the mailbox of an account whose only factor is its password; its right code marks the address verified all the same, which it already is
the send caps' tiers (#637): which of them answers quietly (the step, the mail dropped) and which answers 429; the mail is dispatched after the answer is built, so sent, dropped and not sent look alike
a failure to settle the ladder reservation: reported, and it changes no answer
a store failure while an audit record is written: the round fails, and the transport answers it as a failed round of its own
a rotation of the realm's cookie key while a code is live: the code's HMAC and the identifier's change with it, so the right code is refused once and a new code works

The main story

When: The send caps let the code through, or drop its mail quietly at the address-and-IP tier, the code was issued less than 10 minutes ago, the last code was issued less than a minute ago, the identifier is outside a wait of the email-code ladder, the account is the subject's, enabled, with its password credential.

Issue a code and ask the capped sender to mail it: the code is accepted: its HMAC is kept, its mail queued, and the floor is waited out
Ask for the code: the person types the code from the mail
Take the round's answer to the email_code step: the code is live
Reserve the answer on the email-code ladder: the attempt is reserved
Compare the answer with the held code, in constant time: the code is right: the reservation settles as a success
Mark the address verified: the address is verified: the code is consumed, email_code joins the transaction's verified steps with no amr, and the step is audited as passed under the subject

Result: Go on with the sign-in, the address verified.

The flow

Show failure paths and “the user closes the page”

blue line: the main storyred dashed line: a failure path (shown with “Show failure paths”)dotted line: decided by a rule, nobody actsdashed grey box: the server decides, nothing is shown

What each step answers

Step	The outside world sees
Ask for the code offeringCode	kind: step · body: {"current":{"step":"email_code","params":{"purpose":"verify_account","length":6,"expires_in":"the seconds the code has left, at most 600","resend_after":"the seconds until another code may be asked for, at most 60"}},"alternatives":[],"personal":{"identifier":"the transaction's identifier"}}
Ask for the code again codeRefused	kind: step · body: {"current":{"step":"email_code","params":{"purpose":"verify_account","length":6,"expires_in":"the seconds the code has left, at most 600","resend_after":"the seconds until another code may be asked for, at most 60"},"error":"invalid_credentials"},"alternatives":[],"personal":{"identifier":"the transaction's identifier"}}
Say the code has expired codeExpired	kind: step · body: {"current":{"step":"email_code","params":{"purpose":"verify_account","length":6,"expires_in":600,"resend_after":0},"error":"code_expired"},"alternatives":[],"personal":{"identifier":"the transaction's identifier"}}
Go on with the sign-in, the address verified verified	kind: continue · body: {"verified":"the transaction verified email_code with purpose verify_account; it adds no amr value","amr":"[\"pwd\"]","authTime":"when the password was verified, unchanged"}
Refuse the round for the send caps sendCapped	kind: refused · body: {"reason":"throttled","retryAfterSeconds":"the send cap's"}
Refuse the answer inside the email-code ladder's wait lockedOut	kind: refused · body: {"reason":"throttled","retryAfterSeconds":"the ladder's"}
Burn the code and end the transaction burned	kind: refused · body: {"reason":"transaction_ended","transaction":null}
End the transaction for an account that changed ended	kind: refused · body: {"reason":"transaction_ended","transaction":null}
Refuse a malformed answer answerRefused	kind: refused · body: {"reason":"invalid_answer"}
Refuse the round while a store is down unavailable	kind: refused · body: {"reason":"unavailable"}

How it decides what happens next

Take the round's answer to the email_code step

#	If	Then
1	the code has passed its 10 minutes: refused with code_expired, audited, neither compared nor counted	Say the code has expired
2	the code is live	Reserve the answer on the email-code ladder

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`expired`	`codeExpired`	76 of 152
2	otherwise	`reservingCodeAttempt`	76 of 152

expired: codeAge == 'expired'

Ask whether a new code is due

#	If	Then
1	less than a minute has passed: the same step, nothing mailed, and the floor is waited out	Ask for the code
2	a new code is due; the count of wrong answers stays	Issue a code and ask the capped sender to mail it

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`resendNotDue`	`offeringCode`	80 of 160
2	otherwise	`issuingCode`	80 of 160

resendNotDue: not resendDue

Compare the answer with the held code, in constant time

#	If	Then
1	the code is right: the reservation settles as a success	Mark the address verified

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	otherwise	`markingVerified`	38 of 38

Compare a wrong answer with the held code, in constant time

#	If	Then
1	the 5th wrong answer of the transaction: the code is burned, the transaction ends, and code_burned is audited under the subject	Burn the code and end the transaction
2	the first wrong answer: refused with invalid_credentials, audited as invalid_code	Ask for the code again
3	the second wrong answer: refused alike	Ask for the code again
4	the third wrong answer: refused alike	Ask for the code again
5	the fourth wrong answer: refused alike; the next wrong one burns the code	Ask for the code again

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`wrongFifth`	`burned`	8 of 38
2	`wrongZero`	`codeRefused`	6 of 38
3	`wrongOne`	`codeRefused`	8 of 38
4	`wrongTwo`	`codeRefused`	8 of 38
5	otherwise	`codeRefused`	8 of 38

wrongFifth: wrongAnswers == 'four'
wrongZero: wrongAnswers == 'zero'
wrongOne: wrongAnswers == 'one'
wrongTwo: wrongAnswers == 'two'

Take a wrong answer to the email_code step

#	If	Then
1	the code has passed its 10 minutes: refused with code_expired, neither compared nor counted	Say the code has expired
2	the code is live	Reserve a wrong answer on the email-code ladder

The first matching rule wins.

Exact conditions

#	Condition	Goes to	Situations
1	`expired`	`codeExpired`	76 of 152
2	otherwise	`reservingWrongAttempt`	76 of 152

expired: codeAge == 'expired'

Every way it can end

It ends with	When	What happens
Go on with the sign-in, the address verified ends here	The send caps let the code through, or drop its mail quietly at the address-and-IP tier, the code was issued less than 10 minutes ago, the last code was issued less than a minute ago, the identifier is outside a wait of the email-code ladder, the account is the subject's, enabled, with its password credential	Issue a code and ask the capped sender to mail it: the code is accepted: its HMAC is kept, its mail queued, and the floor is waited out Ask for the code: the person types the code from the mail Take the round's answer to the email_code step: the code is live Reserve the answer on the email-code ladder: the attempt is reserved Compare the answer with the held code, in constant time: the code is right: the reservation settles as a success Mark the address verified: the address is verified: the code is consumed, email_code joins the transaction's verified steps with no amr, and the step is audited as passed under the subject
Refuse the round for the send caps ends here	A tier that answers 429 is full: the per-IP, the per-client or the after-first-factor cap, the code was issued less than 10 minutes ago, the last code was issued less than a minute ago, the identifier is outside a wait of the email-code ladder, the account is the subject's, enabled, with its password credential	Issue a code and ask the capped sender to mail it: a tier that answers 429 is full: nothing is mailed, a code the transaction held stays, send_capped is audited, and the floor is waited out
Refuse the answer inside the email-code ladder's wait ends here	The send caps let the code through, or drop its mail quietly at the address-and-IP tier, the code was issued less than 10 minutes ago, the last code was issued less than a minute ago, fewer than its wait has passed since the identifier counted 5 or more wrong codes in a row, the account is the subject's, enabled, with its password credential	Issue a code and ask the capped sender to mail it: the code is accepted: its HMAC is kept, its mail queued, and the floor is waited out Ask for the code: the person types the code from the mail Take the round's answer to the email_code step: the code is live Reserve the answer on the email-code ladder: the identifier is inside a wait: refused, neither compared nor counted, audited as locked_out
Burn the code and end the transaction ends here	The send caps let the code through, or drop its mail quietly at the address-and-IP tier, the code was issued less than 10 minutes ago, the last code was issued less than a minute ago, the identifier is outside a wait of the email-code ladder, the account is the subject's, enabled, with its password credential	Issue a code and ask the capped sender to mail it: the code is accepted: its HMAC is kept, its mail queued, and the floor is waited out Ask for the code: the person types another code Take a wrong answer to the email_code step: the code is live Reserve a wrong answer on the email-code ladder: the attempt is reserved Compare a wrong answer with the held code, in constant time: the first wrong answer: refused with invalid_credentials, audited as invalid_code Ask for the code again: the person types another wrong code Take a wrong answer to the email_code step: the code is live Reserve a wrong answer on the email-code ladder: the attempt is reserved Compare a wrong answer with the held code, in constant time: the second wrong answer: refused alike Ask for the code again: the person types another wrong code Take a wrong answer to the email_code step: the code is live Reserve a wrong answer on the email-code ladder: the attempt is reserved Compare a wrong answer with the held code, in constant time: the third wrong answer: refused alike Ask for the code again: the person types another wrong code Take a wrong answer to the email_code step: the code is live Reserve a wrong answer on the email-code ladder: the attempt is reserved Compare a wrong answer with the held code, in constant time: the fourth wrong answer: refused alike; the next wrong one burns the code Ask for the code again: the person types another wrong code Take a wrong answer to the email_code step: the code is live Reserve a wrong answer on the email-code ladder: the attempt is reserved Compare a wrong answer with the held code, in constant time: the 5th wrong answer of the transaction: the code is burned, the transaction ends, and code_burned is audited under the subject
End the transaction for an account that changed ends here	The send caps let the code through, or drop its mail quietly at the address-and-IP tier, the code was issued less than 10 minutes ago, the last code was issued less than a minute ago, the identifier is outside a wait of the email-code ladder, the account was disabled or lost its password credential since the round read it	Issue a code and ask the capped sender to mail it: the code is accepted: its HMAC is kept, its mail queued, and the floor is waited out Ask for the code: the person types the code from the mail Take the round's answer to the email_code step: the code is live Reserve the answer on the email-code ladder: the attempt is reserved Compare the answer with the held code, in constant time: the code is right: the reservation settles as a success Mark the address verified: the account was disabled or changed since the read: nothing is written, and the transaction ends
Refuse a malformed answer ends here	The send caps let the code through, or drop its mail quietly at the address-and-IP tier, the code was issued less than 10 minutes ago, the last code was issued less than a minute ago, the identifier is outside a wait of the email-code ladder, the account is the subject's, enabled, with its password credential	Issue a code and ask the capped sender to mail it: the code is accepted: its HMAC is kept, its mail queued, and the floor is waited out Ask for the code: the otp is not of the offered length: refused as invalid_answer, nothing compared or counted
Refuse the round while a store is down ends here	The send caps let the code through, or drop its mail quietly at the address-and-IP tier, the code was issued less than 10 minutes ago, the last code was issued less than a minute ago, the identifier is outside a wait of the email-code ladder, the account is the subject's, enabled, with its password credential	Issue a code and ask the capped sender to mail it: it fails, because the send-cap store fails: nothing is mailed or kept; the floor is waited out

Each row is also a generated test: set the starting situation, send the events, expect the ending.

What is guaranteed

These hold in all 1862 situations the model can reach, from 32 different starting situations.

A code answered inside a wait of the email-code ladder never verifies the address
A code works only within its 10 minutes
Every compared code was reserved on the email-code ladder first
An expired code, an answer inside a wait, a capped send and a malformed answer compare no code
The fifth wrong answer of a transaction burns the code and ends the transaction
Once a wrong answer is counted, no resend and no new code sets the count back
A send the caps refuse mails nothing
A verified code adds no amr value, never counts toward mfa and never moves auth_time
The address is marked verified only by a right code, on the way to the verified exit
A code works once: the verified exit leaves no code in the transaction
Every refused or ended answer writes an audit record under the subject; so does an expired code answered, while a round with no answer that finds the code expired only says so
Every round that ends here answers no earlier than 500 ms after it arrived

Exact rules

Id	Never
`no-verification-inside-a-wait`	`state == 'verified' and ladder == 'inWait'`
`no-verification-after-ten-minutes`	`state == 'verified' and codeAge == 'expired'`
`reserve-before-compare`	`codeCompared and not attemptReserved`
`refusals-compare-nothing`	`state in ['codeExpired', 'lockedOut', 'sendCapped', 'answerRefused'] and codeCompared`
`the-fifth-wrong-answer-burns`	`wrongAnswers == 'five' and state != 'burned'`
`a-resend-never-resets-the-count`	`answeredWrong and wrongAnswers == 'zero'`
`nothing-mailed-when-capped`	`state == 'sendCapped' and mailQueued`
`a-code-is-never-a-factor`	`factorClaimed`
`the-address-is-verified-only-by-its-code`	`addressVerified and state != 'verified'`
`a-consumed-code-is-gone`	`state == 'verified' and codeHeld`
`every-refusal-is-audited`	`state in ['codeRefused', 'lockedOut', 'sendCapped', 'burned', 'ended', 'answerRefused'] and not audited`
`every-round-waits-the-floor`	`state in ['offeringCode', 'codeRefused', 'codeExpired', 'sendCapped', 'lockedOut', 'burned', 'ended', 'answerRefused', 'unavailable'] and not floorWaited`

Reference

All transitions (39)

From	Event	Guard	To	Effects	Taken
`issuingCode`	`DONE`	`capped`	`sendCapped`	`audit` `waitFloor`	yes
`issuingCode`	`DONE`		`offeringCode`	`holdCode` `queueMail` `waitFloor`	yes
`issuingCode`	`FAIL.store`		`unavailable`	`waitFloor`	yes
`takingAnswer`	`rule 1`	`expired`	`codeExpired`	`audit` `waitFloor`	yes
`takingAnswer`	`rule 2`		`reservingCodeAttempt`		yes
`checkingResend`	`rule 1`	`resendNotDue`	`offeringCode`	`waitFloor`	yes
`checkingResend`	`rule 2`		`issuingCode`		yes
`reservingCodeAttempt`	`DONE`	`inWait`	`lockedOut`	`audit` `waitFloor`	yes
`reservingCodeAttempt`	`DONE`		`comparingCode`	`reserveAttempt`	yes
`reservingCodeAttempt`	`FAIL.store`		`unavailable`	`waitFloor`	yes
`comparingCode`	`rule 1`		`markingVerified`	`compareCode`	yes
`comparingWrongCode`	`rule 1`	`wrongFifth`	`burned`	`compareCode` `countFifth` `audit` `waitFloor`	yes
`comparingWrongCode`	`rule 2`	`wrongZero`	`codeRefused`	`compareCode` `countFirst` `audit` `waitFloor`	yes
`comparingWrongCode`	`rule 3`	`wrongOne`	`codeRefused`	`compareCode` `countSecond` `audit` `waitFloor`	yes
`comparingWrongCode`	`rule 4`	`wrongTwo`	`codeRefused`	`compareCode` `countThird` `audit` `waitFloor`	yes
`comparingWrongCode`	`rule 5`		`codeRefused`	`compareCode` `countFourth` `audit` `waitFloor`	yes
`markingVerified`	`DONE`	`changed`	`ended`	`audit` `waitFloor`	yes
`markingVerified`	`DONE`		`verified`	`consumeCode` `markVerified` `audit`	yes
`markingVerified`	`FAIL.store`		`unavailable`	`waitFloor`	yes
`offeringCode`	`ROUND`		`offeringCode`	`newRound` `waitFloor`	yes
`offeringCode`	`RIGHT_CODE`		`takingAnswer`	`newRound`	yes
`offeringCode`	`WRONG_CODE`		`takingWrongAnswer`	`newRound`	yes
`offeringCode`	`RESEND`		`checkingResend`	`newRound` `moveOn`	yes
`offeringCode`	`MALFORMED`		`answerRefused`	`newRound` `audit` `waitFloor`	yes
`codeRefused`	`ROUND`		`offeringCode`	`newRound` `waitFloor`	yes
`codeRefused`	`RIGHT_CODE`		`takingAnswer`	`newRound` `moveOn`	yes
`codeRefused`	`WRONG_CODE`		`takingWrongAnswer`	`newRound` `moveOn`	yes
`codeRefused`	`RESEND`		`checkingResend`	`newRound` `moveOn`	yes
`codeRefused`	`MALFORMED`		`answerRefused`	`newRound` `audit` `waitFloor`	yes
`codeExpired`	`ROUND`		`codeExpired`	`newRound` `waitFloor`	yes
`codeExpired`	`RESEND`		`issuingCode`	`newRound` `moveOn`	yes
`codeExpired`	`RIGHT_CODE`		`takingAnswer`	`newRound`	yes
`codeExpired`	`WRONG_CODE`		`takingWrongAnswer`	`newRound`	yes
`codeExpired`	`MALFORMED`		`answerRefused`	`newRound` `audit` `waitFloor`	yes
`takingWrongAnswer`	`rule 1`	`expired`	`codeExpired`	`audit` `waitFloor`	yes
`takingWrongAnswer`	`rule 2`		`reservingWrongAttempt`		yes
`reservingWrongAttempt`	`DONE`	`inWait`	`lockedOut`	`audit` `waitFloor`	yes
`reservingWrongAttempt`	`DONE`		`comparingWrongCode`	`reserveAttempt`	yes
`reservingWrongAttempt`	`FAIL.store`		`unavailable`	`waitFloor`	yes