error handling

pages/password-authentication.md

@@ -129,9 +129,11 @@ Finally, ensure a certain strength of passwords for users. Make sure passwords a
 
 ## Error handling
 
-As a good rule of thumb, error messages should be vague and generic. For example, a login form should display "Incorrect username or password" instead of "Incorrect username" or "Incorrect password." However, if your users' usernames or emails are public knowledge, it may make more sense to return a more specific error message. In most cases, anyone can already determine if an email address or username is valid by checking it in the registration form.
+As a good rule of thumb, error messages should be vague and generic. For example, a login form should display "Incorrect username or password" instead of "Incorrect username" or "Incorrect password." Similarly, a sign-in form shouldn't share whether a email is already used by an existing account.
 
-Even when returning a generic message, it may be possible to determine if a user exists or not by checking the response times of the login form. For example, if you only validate the password when the username is valid.
+However, from a user-experience perspective, it's more user-friendly to tell the user directly that their username or email is incorrect. This should be fine for websites where usernames are already public (e.g. social media) or where knowing the validity of a email isn't important (i.e. most sites). This slightly makes brute-force attacks easier since attackers only need to guess passwords, but you should already have [proper measures](#brute-force-attacks) implemented.
+
+If you need to keep the username or email private, make sure you do not leak such information via registration forms and password reset forms. For example, when creating an account, you can prompt the user with a message like "We've sent an email to your inbox with further instructions" regardless of whether the email is taken. If they already have an account, you can include that information in the email itself. Even when returning a generic message however, it may be possible to determine if a user exists or not by checking the response times. For example, if you only validate the password when the username is valid. Protecting against timing-attacks is hard so only go this route if strictly required.
 
 ## Other considerations
 

pages/password-reset.md

@@ -8,6 +8,7 @@ title: "Password reset"
 
 - [Overview](#overview)
 - [Password reset links](#password-reset-links)
+- [Error handling](#error-handling)
 - [Rate limiting](#rate-limiting)
 
 ## Overview
@@ -40,6 +41,10 @@ Make sure to set the [Referrer Policy](https://developer.mozilla.org/en-US/docs/
 
 If the user has implemented [multi-factor authentication](/mfa), such as via authenticator apps or passkeys, they should be prompted to authenticate using their second factor before entering their new password.
 
+## Error handling
+
+If the email is invalid, you can either tell the user that the email is invalid or keep the message vague (e.g. "We'll send a reset email if the account exists"). This will depend on whether you'd want to keep the validity of emails public or private. See [Error handling](/password-authentication#error-handling) in the Password authentication guide for more information.
+
 ## Rate limiting
 
 Any endpoint that can send emails should have strict rate limiting implemented. Use Captchas if necessary.