quart-security 2.0.6__tar.gz → 2.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. {quart_security-2.0.6 → quart_security-2.1.0}/PKG-INFO +21 -2
  2. {quart_security-2.0.6 → quart_security-2.1.0}/README.md +20 -1
  3. {quart_security-2.0.6 → quart_security-2.1.0}/pyproject.toml +1 -1
  4. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/core.py +38 -1
  5. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/datastore.py +6 -0
  6. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/forms.py +19 -0
  7. quart_security-2.1.0/quart_security/templates/security/confirm_email.html +8 -0
  8. quart_security-2.1.0/quart_security/templates/security/email/confirmation_instructions.txt +5 -0
  9. quart_security-2.1.0/quart_security/templates/security/email/register_conflict.txt +6 -0
  10. quart_security-2.1.0/quart_security/templates/security/email/reset_instructions.txt +5 -0
  11. quart_security-2.1.0/quart_security/templates/security/email/reset_notice.txt +3 -0
  12. quart_security-2.1.0/quart_security/templates/security/forgot_password.html +10 -0
  13. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/login_user.html +6 -0
  14. quart_security-2.1.0/quart_security/templates/security/reset_password.html +10 -0
  15. quart_security-2.1.0/quart_security/templates/security/send_confirmation.html +10 -0
  16. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/views.py +374 -44
  17. {quart_security-2.0.6 → quart_security-2.1.0}/LICENSE +0 -0
  18. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/__init__.py +0 -0
  19. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/breach.py +0 -0
  20. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/decorators.py +0 -0
  21. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/email.py +0 -0
  22. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/models.py +0 -0
  23. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/password.py +0 -0
  24. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/proxies.py +0 -0
  25. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/py.typed +0 -0
  26. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/signals.py +0 -0
  27. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/state.py +0 -0
  28. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/_macros.html +0 -0
  29. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/change_password.html +0 -0
  30. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/mf_recovery.html +0 -0
  31. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/mf_recovery_codes.html +0 -0
  32. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/register_user.html +0 -0
  33. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/two_factor_select.html +0 -0
  34. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/two_factor_setup.html +0 -0
  35. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/two_factor_verify_code.html +0 -0
  36. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/wan_register.html +0 -0
  37. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/wan_signin.html +0 -0
  38. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/templates/security/wan_verify.html +0 -0
  39. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/totp.py +0 -0
  40. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/utils.py +0 -0
  41. {quart_security-2.0.6 → quart_security-2.1.0}/quart_security/webauthn.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: quart-security
3
- Version: 2.0.6
3
+ Version: 2.1.0
4
4
  Summary: Native async auth for Quart
5
5
  Author: quart-security maintainers
6
6
  Requires-Python: >=3.11
@@ -167,6 +167,13 @@ Core:
167
167
  - `SECURITY_COOKIE_SECURE` (default: `True`; sets `SESSION_COOKIE_SECURE`)
168
168
  - `SECURITY_FRESHNESS` (default: `60` minutes)
169
169
 
170
+ Password reset and email confirmation:
171
+ - `SECURITY_RECOVERABLE` (default: `False`) - password reset by email at `/reset`
172
+ - `SECURITY_CONFIRMABLE` (default: `False`) - self-registered accounts sign in only after confirming their email; needs a `confirmed_at` column
173
+ - `SECURITY_PUBLIC_URL` (default: unset) - origin for links in email, e.g. `https://app.example.com`; required when either flow sends mail, and never taken from the request's Host header
174
+ - `SECURITY_RESET_PASSWORD_WITHIN` (default: 1 hour)
175
+ - `SECURITY_CONFIRM_EMAIL_WITHIN` (default: 1 day)
176
+
170
177
  Existing pbkdf2_sha512 and bcrypt hashes continue to verify after the argon2 default change. They are transparently rehashed to argon2id on the user's next successful login.
171
178
 
172
179
  Until then, a failed login for an account with a legacy hash takes a different time than one for an unknown email, which is checked against an argon2id dummy, so timing can reveal that the account exists. Apps that import hashes from another system should require a password reset rather than leave them in place.
@@ -200,7 +207,17 @@ Routing:
200
207
 
201
208
  A visit to `/login?next=/path` sends the user to `/path` after they sign in, through 2FA and passkey sign-in too. Only same-site paths are honored, the next visit to `/login` replaces the target, and a sign-in finishing more than 10 minutes after the form was shown ignores it.
202
209
 
203
- Registration answers the same way whether or not the email already has an account, so it cannot be used to find accounts. For an existing email nothing is created and `user_register_conflict` fires with the existing user; send the owner a notice from it in the background, because a receiver that waits on mail slows only that response.
210
+ Registration answers the same way whether or not the email already has an account. For an existing email nothing is created and `user_register_conflict` fires with the existing user. On its own that is not enough: someone can register an email and try to sign in with the password they chose, which works only if the account is new. Turn on `SECURITY_CONFIRMABLE` to close that gap.
211
+
212
+ ## Password reset and email confirmation
213
+
214
+ With `SECURITY_RECOVERABLE`, `/reset` asks for an email and always gives the same answer. The link goes to the address stored on the account, works once, expires after `SECURITY_RESET_PASSWORD_WITHIN`, and stops working if the account's email or password changes first. Opening it only shows the form, so mail scanners cannot spend it. A reset rotates `fs_uniquifier`, which signs out every session, clears a lockout, confirms the email, fires `password_changed` and sends a notice.
215
+
216
+ With `SECURITY_CONFIRMABLE` (and `SECURITY_REGISTERABLE`), a new account stores `confirmed_at = NULL` and cannot sign in until its owner opens the emailed link and presses the button on that page. The button is there because mail scanners open links: confirming on GET would let a scanner activate an account someone else registered with that address, with that person's password. Until then a login fails with the same message as a wrong password or a locked account, and `/confirm` sends a fresh link. Registering an existing email sends the owner a notice instead. Accounts created any other way should set `confirmed_at`; a column default does not work, because SQLAlchemy fills it in even when registration sets `None`.
217
+
218
+ Only token hashes are stored. Lookups, token writes, account creation and mail for these flows run after the response through `app.add_background_task`, so response time does not depend on whether an email has an account. The same goes for counting failed logins. As a result, `user_registered` and `user_register_conflict` fire after the response when confirmation is on, in an app context with no request.
219
+
220
+ Mail goes through `send_email` and the `MAIL_*` settings by default. Pass `Security(app, datastore, send_mail=fn)`, where `fn` is `async (subject, recipient, body)`, to use something else. Bodies come from `security/email/*.txt` templates, which the app can override.
204
221
 
205
222
  ## Route Map
206
223
 
@@ -209,6 +226,8 @@ Core:
209
226
  - `/register`
210
227
  - `/logout` (POST only)
211
228
  - `/change`
229
+ - `/reset`, `/reset/<token>` (with `SECURITY_RECOVERABLE`)
230
+ - `/confirm`, `/confirm/<token>` (with `SECURITY_CONFIRMABLE` and `SECURITY_REGISTERABLE`)
212
231
 
213
232
  2FA:
214
233
  - `/tf-setup`
@@ -137,6 +137,13 @@ Core:
137
137
  - `SECURITY_COOKIE_SECURE` (default: `True`; sets `SESSION_COOKIE_SECURE`)
138
138
  - `SECURITY_FRESHNESS` (default: `60` minutes)
139
139
 
140
+ Password reset and email confirmation:
141
+ - `SECURITY_RECOVERABLE` (default: `False`) - password reset by email at `/reset`
142
+ - `SECURITY_CONFIRMABLE` (default: `False`) - self-registered accounts sign in only after confirming their email; needs a `confirmed_at` column
143
+ - `SECURITY_PUBLIC_URL` (default: unset) - origin for links in email, e.g. `https://app.example.com`; required when either flow sends mail, and never taken from the request's Host header
144
+ - `SECURITY_RESET_PASSWORD_WITHIN` (default: 1 hour)
145
+ - `SECURITY_CONFIRM_EMAIL_WITHIN` (default: 1 day)
146
+
140
147
  Existing pbkdf2_sha512 and bcrypt hashes continue to verify after the argon2 default change. They are transparently rehashed to argon2id on the user's next successful login.
141
148
 
142
149
  Until then, a failed login for an account with a legacy hash takes a different time than one for an unknown email, which is checked against an argon2id dummy, so timing can reveal that the account exists. Apps that import hashes from another system should require a password reset rather than leave them in place.
@@ -170,7 +177,17 @@ Routing:
170
177
 
171
178
  A visit to `/login?next=/path` sends the user to `/path` after they sign in, through 2FA and passkey sign-in too. Only same-site paths are honored, the next visit to `/login` replaces the target, and a sign-in finishing more than 10 minutes after the form was shown ignores it.
172
179
 
173
- Registration answers the same way whether or not the email already has an account, so it cannot be used to find accounts. For an existing email nothing is created and `user_register_conflict` fires with the existing user; send the owner a notice from it in the background, because a receiver that waits on mail slows only that response.
180
+ Registration answers the same way whether or not the email already has an account. For an existing email nothing is created and `user_register_conflict` fires with the existing user. On its own that is not enough: someone can register an email and try to sign in with the password they chose, which works only if the account is new. Turn on `SECURITY_CONFIRMABLE` to close that gap.
181
+
182
+ ## Password reset and email confirmation
183
+
184
+ With `SECURITY_RECOVERABLE`, `/reset` asks for an email and always gives the same answer. The link goes to the address stored on the account, works once, expires after `SECURITY_RESET_PASSWORD_WITHIN`, and stops working if the account's email or password changes first. Opening it only shows the form, so mail scanners cannot spend it. A reset rotates `fs_uniquifier`, which signs out every session, clears a lockout, confirms the email, fires `password_changed` and sends a notice.
185
+
186
+ With `SECURITY_CONFIRMABLE` (and `SECURITY_REGISTERABLE`), a new account stores `confirmed_at = NULL` and cannot sign in until its owner opens the emailed link and presses the button on that page. The button is there because mail scanners open links: confirming on GET would let a scanner activate an account someone else registered with that address, with that person's password. Until then a login fails with the same message as a wrong password or a locked account, and `/confirm` sends a fresh link. Registering an existing email sends the owner a notice instead. Accounts created any other way should set `confirmed_at`; a column default does not work, because SQLAlchemy fills it in even when registration sets `None`.
187
+
188
+ Only token hashes are stored. Lookups, token writes, account creation and mail for these flows run after the response through `app.add_background_task`, so response time does not depend on whether an email has an account. The same goes for counting failed logins. As a result, `user_registered` and `user_register_conflict` fire after the response when confirmation is on, in an app context with no request.
189
+
190
+ Mail goes through `send_email` and the `MAIL_*` settings by default. Pass `Security(app, datastore, send_mail=fn)`, where `fn` is `async (subject, recipient, body)`, to use something else. Bodies come from `security/email/*.txt` templates, which the app can override.
174
191
 
175
192
  ## Route Map
176
193
 
@@ -179,6 +196,8 @@ Core:
179
196
  - `/register`
180
197
  - `/logout` (POST only)
181
198
  - `/change`
199
+ - `/reset`, `/reset/<token>` (with `SECURITY_RECOVERABLE`)
200
+ - `/confirm`, `/confirm/<token>` (with `SECURITY_CONFIRMABLE` and `SECURITY_REGISTERABLE`)
182
201
 
183
202
  2FA:
184
203
  - `/tf-setup`
@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
4
4
 
5
5
  [project]
6
6
  name = "quart-security"
7
- version = "2.0.6"
7
+ version = "2.1.0"
8
8
  description = "Native async auth for Quart"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -9,7 +9,14 @@ from uuid import uuid4
9
9
  from quart import abort, current_app, g, request, session
10
10
 
11
11
  from .datastore import SQLAlchemyUserDatastore
12
- from .forms import ChangePasswordForm, LoginForm, RegisterForm
12
+ from .email import send_email
13
+ from .forms import (
14
+ ChangePasswordForm,
15
+ EmailForm,
16
+ LoginForm,
17
+ RegisterForm,
18
+ ResetPasswordForm,
19
+ )
13
20
  from .password import init_password_context
14
21
  from .proxies import AnonymousUser, current_user
15
22
  from .signals import user_authenticated, user_logged_out
@@ -56,6 +63,15 @@ class Security:
56
63
  self.change_password_form_cls = kwargs.get(
57
64
  "change_password_form", ChangePasswordForm
58
65
  )
66
+ self.forgot_password_form_cls = kwargs.get("forgot_password_form", EmailForm)
67
+ self.reset_password_form_cls = kwargs.get(
68
+ "reset_password_form", ResetPasswordForm
69
+ )
70
+ self.send_confirmation_form_cls = kwargs.get(
71
+ "send_confirmation_form", EmailForm
72
+ )
73
+ # async (subject, recipient, body); runs as a background task.
74
+ self.send_mail = kwargs.get("send_mail", send_email)
59
75
  self.mail_util_cls = kwargs.get("mail_util_cls")
60
76
  self.state_store = kwargs.get("state_store")
61
77
 
@@ -74,6 +90,10 @@ class Security:
74
90
  self.change_password_form_cls = kwargs.get(
75
91
  "change_password_form", self.change_password_form_cls
76
92
  )
93
+ for name in ("forgot_password", "reset_password", "send_confirmation"):
94
+ attr = f"{name}_form_cls"
95
+ setattr(self, attr, kwargs.get(f"{name}_form", getattr(self, attr)))
96
+ self.send_mail = kwargs.get("send_mail", self.send_mail)
77
97
  self.mail_util_cls = kwargs.get("mail_util_cls", self.mail_util_cls)
78
98
  self.state_store = kwargs.get("state_store", self.state_store)
79
99
  if self.state_store is None:
@@ -103,6 +123,8 @@ class Security:
103
123
  required_fields.append("mf_recovery_codes")
104
124
  if app.config["SECURITY_WEBAUTHN"]:
105
125
  required_fields.append("fs_webauthn_user_handle")
126
+ if app.config["SECURITY_CONFIRMABLE"]:
127
+ required_fields.append("confirmed_at")
106
128
  missing = [
107
129
  name
108
130
  for name in required_fields
@@ -114,6 +136,16 @@ class Security:
114
136
  )
115
137
  if not app.secret_key:
116
138
  raise RuntimeError("Security requires SECRET_KEY")
139
+ sends_links = app.config["SECURITY_RECOVERABLE"] or (
140
+ app.config["SECURITY_CONFIRMABLE"] and app.config["SECURITY_REGISTERABLE"]
141
+ )
142
+ if sends_links and not app.config["SECURITY_PUBLIC_URL"]:
143
+ # Links in email must not come from the request's Host header, which
144
+ # the sender of a reset request controls.
145
+ raise RuntimeError(
146
+ "SECURITY_PUBLIC_URL is required for password reset and email"
147
+ " confirmation links"
148
+ )
117
149
  app.config["SESSION_COOKIE_SECURE"] = app.config["SECURITY_COOKIE_SECURE"]
118
150
  app.config["SESSION_COOKIE_HTTPONLY"] = True
119
151
  app.config["SESSION_COOKIE_SAMESITE"] = (
@@ -187,6 +219,11 @@ class Security:
187
219
  "SECURITY_PASSWORD_LENGTH_MIN": 12,
188
220
  "SECURITY_REGISTERABLE": True,
189
221
  "SECURITY_CHANGEABLE": True,
222
+ "SECURITY_RECOVERABLE": False,
223
+ "SECURITY_CONFIRMABLE": False,
224
+ "SECURITY_RESET_PASSWORD_WITHIN": timedelta(hours=1),
225
+ "SECURITY_CONFIRM_EMAIL_WITHIN": timedelta(days=1),
226
+ "SECURITY_PUBLIC_URL": None,
190
227
  "SECURITY_TRACKABLE": True,
191
228
  "SECURITY_TWO_FACTOR": True,
192
229
  "SECURITY_WEBAUTHN": True,
@@ -279,6 +279,12 @@ class SQLAlchemyUserDatastore:
279
279
  async def commit(self):
280
280
  await self.session.commit()
281
281
 
282
+ async def rollback(self):
283
+ await self.session.rollback()
284
+
285
+ async def refresh(self, obj):
286
+ await self.session.refresh(obj)
287
+
282
288
  def begin_request(self):
283
289
  self._active_session.set(None)
284
290
 
@@ -89,6 +89,25 @@ class ChangePasswordForm(QuartForm):
89
89
  )
90
90
 
91
91
 
92
+ class EmailForm(QuartForm):
93
+ """One email field: asks for a password reset or a new confirmation link."""
94
+
95
+ email = StringField(
96
+ "Email", filters=[_strip_email], validators=[DataRequired(), Email()]
97
+ )
98
+
99
+
100
+ class ResetPasswordForm(QuartForm):
101
+ password = PasswordField("New Password", validators=[DataRequired()])
102
+ password_confirm = PasswordField(
103
+ "Confirm Password",
104
+ validators=[
105
+ DataRequired(),
106
+ EqualTo("password", message="Passwords must match"),
107
+ ],
108
+ )
109
+
110
+
92
111
  class TwoFactorSetupForm(QuartForm):
93
112
  token = StringField("Code", validators=[DataRequired()])
94
113
 
@@ -0,0 +1,8 @@
1
+ <!doctype html>
2
+ <title>Confirm email</title>
3
+ <h1>Confirm your email</h1>
4
+ <p>Confirm only if you created this account. If you did not, close this page.</p>
5
+ <form method="post" action="{{ url_for_security('confirm_email', token=confirm_email_token) }}">
6
+ {{ confirm_email_form.hidden_tag() }}
7
+ <button type="submit">Confirm my email</button>
8
+ </form>
@@ -0,0 +1,5 @@
1
+ Confirm this email address to finish creating your account:
2
+
3
+ {{ confirmation_link }}
4
+
5
+ If you did not sign up, ignore this email and the account stays unusable.
@@ -0,0 +1,6 @@
1
+ Someone tried to create an account with this email address. You already have one, so nothing changed.
2
+
3
+ Sign in: {{ login_link }}
4
+ {% if reset_link %}Forgot your password? Reset it: {{ reset_link }}
5
+ {% endif %}
6
+ If it was not you, you can ignore this email.
@@ -0,0 +1,5 @@
1
+ Someone asked to reset the password for this account. To choose a new one, open this link:
2
+
3
+ {{ reset_link }}
4
+
5
+ It works once and expires soon. If you did not ask for this, ignore this email; your password stays the same.
@@ -0,0 +1,3 @@
1
+ The password for this account was just reset, and every signed-in session was signed out.
2
+
3
+ If you did not do this, reset your password again right away and contact the site's administrator.
@@ -0,0 +1,10 @@
1
+ {% from 'security/_macros.html' import render_input %}
2
+ <!doctype html>
3
+ <title>Reset password</title>
4
+ <h1>Reset password</h1>
5
+ <form method="post" action="{{ url_for_security('forgot_password') }}">
6
+ {{ forgot_password_form.hidden_tag() }}
7
+ {{ render_input(forgot_password_form.email, 'email') }}
8
+ <button type="submit">Send reset link</button>
9
+ </form>
10
+ <p><a href="{{ url_for_security('login') }}">Back to sign in</a></p>
@@ -11,4 +11,10 @@
11
11
  {% if security.webauthn and security.wan_allow_as_first_factor %}
12
12
  <p><a href="{{ url_for_security('wan_signin') }}">Sign in with passkey</a></p>
13
13
  {% endif %}
14
+ {% if security.recoverable %}
15
+ <p><a href="{{ url_for_security('forgot_password') }}">Forgot password?</a></p>
16
+ {% endif %}
14
17
  <p><a href="{{ url_for_security('register') }}">Create account</a></p>
18
+ {% if security.registerable and security.confirmable %}
19
+ <p><a href="{{ url_for_security('send_confirmation') }}">Resend confirmation link</a></p>
20
+ {% endif %}
@@ -0,0 +1,10 @@
1
+ {% from 'security/_macros.html' import render_input %}
2
+ <!doctype html>
3
+ <title>Choose a new password</title>
4
+ <h1>Choose a new password</h1>
5
+ <form method="post" action="{{ url_for_security('reset_password', token=reset_password_token) }}">
6
+ {{ reset_password_form.hidden_tag() }}
7
+ {{ render_input(reset_password_form.password, 'password') }}
8
+ {{ render_input(reset_password_form.password_confirm, 'password') }}
9
+ <button type="submit">Reset password</button>
10
+ </form>
@@ -0,0 +1,10 @@
1
+ {% from 'security/_macros.html' import render_input %}
2
+ <!doctype html>
3
+ <title>Resend confirmation</title>
4
+ <h1>Resend confirmation link</h1>
5
+ <form method="post" action="{{ url_for_security('send_confirmation') }}">
6
+ {{ send_confirmation_form.hidden_tag() }}
7
+ {{ render_input(send_confirmation_form.email, 'email') }}
8
+ <button type="submit">Send link</button>
9
+ </form>
10
+ <p><a href="{{ url_for_security('login') }}">Back to sign in</a></p>
@@ -9,6 +9,7 @@ import hmac
9
9
  import json
10
10
  import secrets
11
11
  import time
12
+ import uuid
12
13
  from urllib.parse import urlsplit
13
14
 
14
15
  from quart import (
@@ -21,6 +22,7 @@ from quart import (
21
22
  request,
22
23
  session,
23
24
  )
25
+ from sqlalchemy.exc import IntegrityError
24
26
  from werkzeug.routing import BuildError
25
27
 
26
28
  from . import webauthn as wan
@@ -103,6 +105,12 @@ async def _record_auth_failure(user):
103
105
  )
104
106
 
105
107
 
108
+ async def _record_failure_job(user_id):
109
+ user = await _find_user(fs_uniquifier=user_id)
110
+ if user is not None:
111
+ await _record_auth_failure(user)
112
+
113
+
106
114
  async def _reset_auth_failures(user):
107
115
  if hasattr(user, "failed_login_count"):
108
116
  user.failed_login_count = 0
@@ -168,6 +176,112 @@ async def _complete_login(user):
168
176
  return redirect(_safe_redirect_target(target, fallback=fallback))
169
177
 
170
178
 
179
+ RESET_SUBJECT = "Reset your password"
180
+ RESET_NOTICE_SUBJECT = "Your password was reset"
181
+ CONFIRM_SUBJECT = "Confirm your email address"
182
+ REGISTER_CONFLICT_SUBJECT = "Sign-up attempt with your email"
183
+
184
+
185
+ def _public_url(endpoint: str, **values) -> str:
186
+ """An absolute link for email, from SECURITY_PUBLIC_URL and never the Host
187
+ header, which whoever triggers the mail controls."""
188
+ base = current_app.config.get("SECURITY_PUBLIC_URL")
189
+ if not base:
190
+ raise RuntimeError("SECURITY_PUBLIC_URL is required to build email links")
191
+ return base.rstrip("/") + url_for_security(endpoint, **values)
192
+
193
+
194
+ def _token_key(raw: str) -> str:
195
+ # Only the hash is stored, so a copy of the state table cannot replay links.
196
+ return hashlib.sha256(raw.encode()).hexdigest()
197
+
198
+
199
+ def _password_fingerprint(user) -> str:
200
+ # Ties a reset link to the password it replaces: any change voids the link.
201
+ return hashlib.sha256((user.password or "").encode()).hexdigest()
202
+
203
+
204
+ def _new_link(endpoint: str) -> tuple[str, str]:
205
+ """A fresh single-use token and the emailed link that carries it. Built in
206
+ the request, where url_for works; stored later, only if an account needs it,
207
+ so making one costs the same whether or not the email has an account."""
208
+ raw = secrets.token_urlsafe(32)
209
+ return raw, _public_url(endpoint, token=raw)
210
+
211
+
212
+ async def _store_link(raw: str, payload: dict, within: str):
213
+ ttl = int(current_app.config[within].total_seconds())
214
+ await _security.state_store.put(payload, ttl=ttl, token=_token_key(raw))
215
+
216
+
217
+ def _defer(job, *args):
218
+ """Run `job(*args)` after the response, on its own datastore session. Work
219
+ that depends on whether an email has an account (lookups, token writes,
220
+ mail) happens here, so the response takes the same time either way."""
221
+ datastore = _security.datastore
222
+
223
+ async def run():
224
+ # The task inherits the request's context; give it its own session.
225
+ begin = getattr(datastore, "begin_request", None)
226
+ if begin:
227
+ begin()
228
+ try:
229
+ await job(*args)
230
+ finally:
231
+ close = getattr(datastore, "close", None)
232
+ if close:
233
+ await maybe_await(close())
234
+
235
+ current_app.add_background_task(run)
236
+
237
+
238
+ async def _mail(template: str, subject: str, user, **context):
239
+ """Render security/email/<template>.txt and send it. Runs in a deferred job,
240
+ outside any request, so links arrive already built in `context`."""
241
+ found = current_app.jinja_env.get_template(f"security/email/{template}.txt")
242
+ body = await found.render_async(user=user, **context)
243
+ await _security.send_mail(subject, user.email, body)
244
+
245
+
246
+ async def _send_confirmation_job(email: str, raw: str, link: str):
247
+ user = await _find_user(email=email)
248
+ if user is None or not getattr(user, "active", True):
249
+ return
250
+ if not _awaiting_confirmation(user):
251
+ return
252
+ await _store_confirmation(user, raw)
253
+ await _mail(
254
+ "confirmation_instructions", CONFIRM_SUBJECT, user, confirmation_link=link
255
+ )
256
+
257
+
258
+ async def _store_confirmation(user, raw: str):
259
+ await _store_link(
260
+ raw,
261
+ {"confirm_user_id": user.get_id(), "email": user.email},
262
+ "SECURITY_CONFIRM_EMAIL_WITHIN",
263
+ )
264
+
265
+
266
+ async def _password_errors(password: str) -> list[str]:
267
+ errors = validate_password(
268
+ password,
269
+ min_length=current_app.config.get("SECURITY_PASSWORD_LENGTH_MIN", 12),
270
+ )
271
+ if not errors and current_app.config.get("SECURITY_PASSWORD_BREACH_CHECK", True):
272
+ count_min = current_app.config.get("SECURITY_PASSWORD_BREACH_COUNT_MIN", 1)
273
+ if await password_is_breached(password, count_min=count_min):
274
+ errors = ["This password has appeared in a data breach. Choose another."]
275
+ return errors
276
+
277
+
278
+ def _awaiting_confirmation(user) -> bool:
279
+ return bool(
280
+ current_app.config.get("SECURITY_CONFIRMABLE")
281
+ and getattr(user, "confirmed_at", None) is None
282
+ )
283
+
284
+
171
285
  def _webauthn_rp_id() -> str:
172
286
  configured = current_app.config.get("SECURITY_WAN_RP_ID")
173
287
  if configured:
@@ -382,21 +496,25 @@ async def login():
382
496
  if _is_post() and form.validate():
383
497
  user = await _find_user(email=_normalize_email(form.email.data))
384
498
 
385
- # Account lockout check
386
- if user and hasattr(user, "locked_until") and user.locked_until:
387
- if naive_utcnow() < user.locked_until:
388
- await flash("Account temporarily locked. Try again later.", "error")
389
- return await render_template(
390
- "security/login_user.html", login_user_form=form
391
- )
499
+ # A locked account fails like a wrong password, after the same work: a
500
+ # distinct "locked" answer would only ever appear for real accounts.
501
+ locked = user is not None and _account_is_locked(user)
502
+ if user and not locked and getattr(user, "locked_until", None):
392
503
  # Lock expired, reset
393
504
  user.failed_login_count = 0
394
505
  user.locked_until = None
395
506
  await _commit()
396
507
 
397
508
  # Always run one verify, so response time does not reveal which emails
398
- # have an active account.
399
- known = user is not None and getattr(user, "active", True)
509
+ # have an active account. An unconfirmed account fails like an unknown
510
+ # one: otherwise registering an email and trying its password would
511
+ # tell whether the email already had an account.
512
+ known = (
513
+ user is not None
514
+ and getattr(user, "active", True)
515
+ and not _awaiting_confirmation(user)
516
+ and not locked
517
+ )
400
518
  password_ok = await verify_password_async(
401
519
  form.password.data,
402
520
  user.password if known else await unknown_user_hash_async(),
@@ -418,11 +536,19 @@ async def login():
418
536
  await _reset_auth_failures(user)
419
537
  return await _complete_login(user)
420
538
 
421
- # Track failed login
422
- if user:
423
- await _record_auth_failure(user)
539
+ # Track failed login after the response: the write happens only for real
540
+ # accounts, and its time must not tell them apart.
541
+ if user and not locked:
542
+ _defer(_record_failure_job, user.get_id())
424
543
 
425
- await flash("Invalid email or password", "error")
544
+ if current_app.config.get("SECURITY_CONFIRMABLE"):
545
+ # One message for every failure, so it never says which case applied.
546
+ await flash(
547
+ "Invalid email or password, or the email is not confirmed yet",
548
+ "error",
549
+ )
550
+ else:
551
+ await flash("Invalid email or password", "error")
426
552
 
427
553
  return await render_template("security/login_user.html", login_user_form=form)
428
554
 
@@ -440,10 +566,7 @@ async def register():
440
566
  # Password checks come first and an existing email gets the same answer as
441
567
  # a new one, after the same hashing work, so the form never reveals which
442
568
  # emails have an account.
443
- errors = validate_password(
444
- form.password.data,
445
- min_length=current_app.config.get("SECURITY_PASSWORD_LENGTH_MIN", 12),
446
- )
569
+ errors = await _password_errors(form.password.data)
447
570
  if errors:
448
571
  for error in errors:
449
572
  await flash(error, "error")
@@ -451,42 +574,249 @@ async def register():
451
574
  "security/register_user.html", register_user_form=form
452
575
  )
453
576
 
454
- if current_app.config.get("SECURITY_PASSWORD_BREACH_CHECK", True):
455
- count_min = current_app.config.get("SECURITY_PASSWORD_BREACH_COUNT_MIN", 1)
456
- breached = await password_is_breached(
457
- form.password.data, count_min=count_min
458
- )
459
- if breached:
460
- await flash(
461
- "This password has appeared in a data breach."
462
- " Choose a different one.",
463
- "error",
464
- )
465
- return await render_template(
466
- "security/register_user.html", register_user_form=form
467
- )
468
-
469
577
  password = await hash_password_async(form.password.data)
578
+ name = (form.name.data or "").strip() if hasattr(form, "name") else ""
470
579
  app = current_app._get_current_object()
471
- existing = await _find_user(email=email)
472
- if existing:
473
- await user_register_conflict.send_async(app, user=existing)
580
+ confirmable = current_app.config.get("SECURITY_CONFIRMABLE")
581
+ if confirmable:
582
+ raw, confirm_link = _new_link("confirm_email")
583
+ recoverable = current_app.config.get("SECURITY_RECOVERABLE")
584
+ links = {
585
+ "confirm": confirm_link,
586
+ "login": _public_url("login"),
587
+ "reset": _public_url("forgot_password") if recoverable else None,
588
+ }
589
+ _defer(_register_job, app, email, password, name, raw, links)
474
590
  else:
475
- user_kwargs = {"email": email, "password": password, "active": True}
476
- if hasattr(form, "name") and form.name.data:
477
- user_kwargs["name"] = form.name.data.strip()
591
+ # Without confirmation the new account signs in at once, which
592
+ # reveals it anyway; create it before answering.
593
+ await _register_job(app, email, password, name, None, {})
478
594
 
479
- user = await _create_user(**user_kwargs)
480
- if hasattr(user, "confirmed_at"):
481
- user.confirmed_at = naive_utcnow()
595
+ if confirmable:
596
+ await flash("Check your email to confirm your account.", "success")
597
+ else:
598
+ await flash("Registration successful. Please log in.", "success")
599
+ return redirect(_resolve_redirect("SECURITY_POST_REGISTER_VIEW", "login"))
600
+
601
+ return await render_template("security/register_user.html", register_user_form=form)
482
602
 
603
+
604
+ async def _register_job(app, email, password, name, confirm_raw, links):
605
+ """Create the account, or tell the owner of the existing one. With
606
+ confirmation on this runs after the response, so neither case is slower."""
607
+ confirmable = confirm_raw is not None
608
+ existing = await _find_user(email=email)
609
+ if existing is None:
610
+ user_kwargs = {"email": email, "password": password, "active": True}
611
+ if name:
612
+ user_kwargs["name"] = name
613
+ user = await _create_user(**user_kwargs)
614
+ if hasattr(user, "confirmed_at"):
615
+ # Set either way: a model default must not confirm a sign-up.
616
+ user.confirmed_at = None if confirmable else naive_utcnow()
617
+ try:
483
618
  await _commit()
619
+ except IntegrityError:
620
+ # Another request registered this email after the lookup above.
621
+ await maybe_await(_security.datastore.rollback())
622
+ existing = await _find_user(email=email)
623
+ if existing is None:
624
+ raise
625
+ else:
626
+ # Receivers run before the mail, so a mail failure cannot skip them;
627
+ # the owner can ask for a new link at /confirm.
484
628
  await user_registered.send_async(app, user=user)
629
+ if confirmable:
630
+ await _store_confirmation(user, confirm_raw)
631
+ await _mail(
632
+ "confirmation_instructions",
633
+ CONFIRM_SUBJECT,
634
+ user,
635
+ confirmation_link=links["confirm"],
636
+ )
637
+ if existing is not None:
638
+ await user_register_conflict.send_async(app, user=existing)
639
+ if confirmable:
640
+ await _mail(
641
+ "register_conflict",
642
+ REGISTER_CONFLICT_SUBJECT,
643
+ existing,
644
+ login_link=links["login"],
645
+ reset_link=links["reset"],
646
+ )
485
647
 
486
- await flash("Registration successful. Please log in.", "success")
487
- return redirect(_resolve_redirect("SECURITY_POST_REGISTER_VIEW", "login"))
488
648
 
489
- return await render_template("security/register_user.html", register_user_form=form)
649
+ @security_bp.route("/reset", methods=["GET", "POST"])
650
+ async def forgot_password():
651
+ if not current_app.config.get("SECURITY_RECOVERABLE"):
652
+ abort(404)
653
+ form = await _security.forgot_password_form_cls.from_formdata()
654
+ await _enforce_csrf(getattr(form, "_submitted_csrf", None))
655
+
656
+ if _is_post() and form.validate():
657
+ raw, link = _new_link("reset_password")
658
+ _defer(_reset_job, _normalize_email(form.email.data), raw, link)
659
+ await flash(
660
+ "If an account uses that email, a link to reset its password is on"
661
+ " its way.",
662
+ "info",
663
+ )
664
+ return redirect(url_for_security("login"))
665
+
666
+ return await render_template(
667
+ "security/forgot_password.html", forgot_password_form=form
668
+ )
669
+
670
+
671
+ async def _reset_job(email: str, raw: str, link: str):
672
+ user = await _find_user(email=email)
673
+ if user is None or not getattr(user, "active", True):
674
+ return
675
+ await _store_link(
676
+ raw,
677
+ {
678
+ "reset_user_id": user.get_id(),
679
+ "email": user.email,
680
+ "password": _password_fingerprint(user),
681
+ },
682
+ "SECURITY_RESET_PASSWORD_WITHIN",
683
+ )
684
+ # To the stored address, never the one typed into the form.
685
+ await _mail("reset_instructions", RESET_SUBJECT, user, reset_link=link)
686
+
687
+
688
+ async def _reset_link_user(state):
689
+ if not state or "reset_user_id" not in state:
690
+ return None
691
+ user = await _find_user(fs_uniquifier=state["reset_user_id"])
692
+ if user is None:
693
+ return None
694
+ # The identity map may hold the copy loaded earlier in this request; read
695
+ # the row again so an email or password changed meanwhile is seen.
696
+ refresh = getattr(_security.datastore, "refresh", None)
697
+ if refresh:
698
+ await maybe_await(refresh(user))
699
+ if not getattr(user, "active", True):
700
+ return None
701
+ # A changed email or password voids the link: it was sent to the old inbox.
702
+ if user.email != state["email"]:
703
+ return None
704
+ if not hmac.compare_digest(state["password"], _password_fingerprint(user)):
705
+ return None
706
+ return user
707
+
708
+
709
+ @security_bp.route("/reset/<token>", methods=["GET", "POST"])
710
+ async def reset_password(token):
711
+ if not current_app.config.get("SECURITY_RECOVERABLE"):
712
+ abort(404)
713
+ key = _token_key(token)
714
+ # A GET only looks: mail scanners open links, and must not spend the token.
715
+ user = await _reset_link_user(await _security.state_store.get(key))
716
+ if user is None:
717
+ await flash("This reset link is invalid or has expired.", "error")
718
+ return redirect(url_for_security("forgot_password"))
719
+
720
+ form = await _security.reset_password_form_cls.from_formdata()
721
+ await _enforce_csrf(getattr(form, "_submitted_csrf", None))
722
+ if _is_post() and form.validate():
723
+ errors = await _password_errors(form.password.data)
724
+ for error in errors:
725
+ await flash(error, "error")
726
+ if not errors:
727
+ # Hash first: the slow step must not sit between the final check of
728
+ # the account and the update that rotates it.
729
+ password = await hash_password_async(form.password.data)
730
+ if await _reset_link_user(await _security.state_store.pop(key)) is None:
731
+ await flash("This reset link is invalid or has expired.", "error")
732
+ return redirect(url_for_security("forgot_password"))
733
+ user.password = password
734
+ # The link reached the inbox, which is what confirmation proves.
735
+ if hasattr(user, "confirmed_at") and user.confirmed_at is None:
736
+ user.confirmed_at = naive_utcnow()
737
+ if hasattr(user, "failed_login_count"):
738
+ user.failed_login_count = 0
739
+ user.locked_until = None
740
+ # Signs out every session, including whoever knew the old password.
741
+ rotated = await maybe_await(
742
+ _security.datastore.rotate_uniquifier(
743
+ user, user.get_id(), uuid.uuid4().hex
744
+ )
745
+ )
746
+ if not rotated:
747
+ abort(409)
748
+ app = current_app._get_current_object()
749
+ await password_changed.send_async(app, user=user)
750
+ _defer(_mail, "reset_notice", RESET_NOTICE_SUBJECT, user)
751
+ await flash("Your password was reset. Sign in with the new one.", "success")
752
+ return redirect(url_for_security("login"))
753
+
754
+ return await render_template(
755
+ "security/reset_password.html",
756
+ reset_password_form=form,
757
+ reset_password_token=token,
758
+ )
759
+
760
+
761
+ def _confirmation_routes_enabled() -> bool:
762
+ # Only sign-ups wait for confirmation, so the routes exist only with sign-up.
763
+ config = current_app.config
764
+ return bool(
765
+ config.get("SECURITY_CONFIRMABLE") and config.get("SECURITY_REGISTERABLE")
766
+ )
767
+
768
+
769
+ @security_bp.route("/confirm", methods=["GET", "POST"])
770
+ async def send_confirmation():
771
+ if not _confirmation_routes_enabled():
772
+ abort(404)
773
+ form = await _security.send_confirmation_form_cls.from_formdata()
774
+ await _enforce_csrf(getattr(form, "_submitted_csrf", None))
775
+
776
+ if _is_post() and form.validate():
777
+ raw, link = _new_link("confirm_email")
778
+ _defer(_send_confirmation_job, _normalize_email(form.email.data), raw, link)
779
+ await flash(
780
+ "If that email is waiting to be confirmed, a new link is on its way.",
781
+ "info",
782
+ )
783
+ return redirect(url_for_security("login"))
784
+
785
+ return await render_template(
786
+ "security/send_confirmation.html", send_confirmation_form=form
787
+ )
788
+
789
+
790
+ @security_bp.route("/confirm/<token>", methods=["GET", "POST"])
791
+ async def confirm_email(token):
792
+ if not _confirmation_routes_enabled():
793
+ abort(404)
794
+ form = await QuartForm.from_formdata()
795
+ await _enforce_csrf(getattr(form, "_submitted_csrf", None))
796
+ # A GET only shows a button. Mail scanners open every link, and confirming
797
+ # on GET would let one confirm an account someone else registered with this
798
+ # address, keeping that person's password.
799
+ key = _token_key(token)
800
+ store = _security.state_store
801
+ state = await (store.pop(key) if _is_post() else store.get(key))
802
+ user = None
803
+ if state and "confirm_user_id" in state:
804
+ user = await _find_user(fs_uniquifier=state["confirm_user_id"])
805
+ # A link sent before an email change does not confirm the new address.
806
+ if user is None or user.email != state.get("email"):
807
+ await flash("This confirmation link is invalid or has expired.", "error")
808
+ return redirect(url_for_security("send_confirmation"))
809
+ if not _is_post():
810
+ return await render_template(
811
+ "security/confirm_email.html",
812
+ confirm_email_form=form,
813
+ confirm_email_token=token,
814
+ )
815
+ if user.confirmed_at is None:
816
+ user.confirmed_at = naive_utcnow()
817
+ await _commit()
818
+ await flash("Your email is confirmed. You can sign in now.", "success")
819
+ return redirect(url_for_security("login"))
490
820
 
491
821
 
492
822
  @security_bp.route("/logout", methods=["POST"])
File without changes