Module email_auth 

The endpoints that reach somebody through their mailbox.

Three flows, one premise: holding a link sent to an address is proof of controlling that address, and that proof is worth as much as a password for exactly one action.

Flow	Endpoints
Invite somebody into an organisation	POST <base>/auth/invitations, GET <base>/auth/invitations/{token}, POST <base>/auth/invitations/{token}/accept
Confirm an address	POST <base>/auth/verify-email, POST <base>/auth/verify-email/resend
Reset a forgotten password	POST <base>/auth/password/forgot, POST <base>/auth/password/reset

None of this is mounted without a mailer

Every route here is registered only when the app has an [email] provider and the matching [auth] flag is on — see AppState::invitations_enabled and its neighbours. A deployment that cannot send mail does not answer 500 on a password reset, it does not answer at all, and the dashboard and console are told through the admin manifest so they never show the button. A door that cannot open is worse than one that isn’t there.

What the tokens are

Random 256-bit strings, mailed once, stored only as a SHA-256 hash (see Authenticator::generate_link_token). Each is single-use and expires; spending one stamps the row so the copy left in a mailbox is inert. A password reset additionally invalidates every other outstanding reset for that account, because “I asked twice and used the first” should not leave a second key under the mat.

What is deliberately not said out loud

POST /auth/password/forgot and /auth/verify-email/resend answer 202 whatever happens. Answering “no such account” would turn either endpoint into a membership oracle for any address somebody cares to try. The person who really owns the address learns the truth in the only place they should: their inbox.

Functions

accept_invitation

POST <base>/auth/invitations/{token}/accept — take the invitation up.

create_invitation

POST <base>/auth/invitations — invite an address into the active organisation.

forgot_password

POST <base>/auth/password/forgot — mail a reset link.

preview_invitation

GET <base>/auth/invitations/{token} — what a link is for, before anyone commits to it.

resend_verification

POST <base>/auth/verify-email/resend — send the confirmation again.

reset_password

POST <base>/auth/password/reset — spend a reset token and set the password.

send_verification

Mint a confirmation token for user_id and mail it to address.

verify_email

POST <base>/auth/verify-email — spend a confirmation token.