startPasswordReset method

Future<UuidValue> startPasswordReset(Session session, { required String email, Transaction? transaction, })

Requests a password reset for email.

If the email address is registered, an email with reset instructions will be send out. If the email is unknown, this method will have no effect.

Always returns a password reset request ID, which can be used to complete the reset. If the email is not registered, the returned ID will not be valid.

Throws an EmailAccountPasswordResetException in case of errors, with reason:

• EmailAccountPasswordResetExceptionReason.tooManyAttempts if the user has made too many attempts trying to request a password reset.

Implementation

Future<UuidValue> startPasswordReset(
  final Session session, {
  required final String email,
  final Transaction? transaction,
}) async {
  return DatabaseUtil.runInTransactionOrSavepoint(
    session.db,
    transaction,
    (final transaction) => EmailIdpUtils.withReplacedServerEmailException(
      () async {
        try {
          return await utils.passwordReset.startPasswordReset(
            session,
            email: email,
            transaction: transaction,
          );
        } on EmailPasswordResetEmailNotFoundException catch (_) {
          // The details of the operation are intentionally not given to the caller, in order to not leak the existence of accounts.
          // Clients should always show something like "check your email to proceed with the password reset".
          session.log(
            'Failed to start password reset for $email, reason: email does not exist',
            level: LogLevel.debug,
          );

          // NOTE: It is necessary to keep the version of the uuid in sync with the
          // one used by the [EmailAccountPasswordResetRequestAttempt] model to
          // prevent attackers from using the difference on the version bit of the
          // uuid to determine whether an email is registered or not.
          return const Uuid().v7obj();
        }
      },
    ),
  );
}