password reset by email: Settings → Email, Forgot password?, and a test-email button

The operator asked for self-service reset over SMTP. It reuses #5173's
password_resets table, /reset-password page, one-hour single-use token and
sign-out-everywhere.

- Settings (rule 25, not env): a new Email group (SMTP server, port,
  encryption as a choice, username, password, from), General → Public
  address, and Security → Reset emails per account. The registry gains
  `choices`, `secret` (the value is never sent back, `is_set` says one is
  saved, an empty save keeps it) and `url` (http(s), trailing slash
  stripped).
- mailer.py: stdlib smtplib on a worker thread, 20 s timeout,
  starttls | tls | none. mail_settings() is None until a server, a sender
  and the public address are set. Links are built from the public address
  because the Host header can be forged.
- POST /api/auth/forgot-password: the same answer at the same speed for
  any address. The link is made and mailed off the request (send_later).
  It is throttled like a sign-in per visitor address, and capped per typed
  email by reset_emails_per_account; past the cap it answers the same and
  sends nothing.
- POST /api/settings/test-email: mails the admin with the saved settings
  and shows the server's error if it fails.
- Public config `password_reset_by_email`. Sign-in shows "Forgot
  password?" only then, linking to a new /forgot-password page.
- docs/public-hosting.md: an "Email and forgotten passwords" section.

Tests: the secret stays server-side; emailed link → reset; the same
answer for unknown addresses; the cap; test email success and failure;
validation units. #5266.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/test_integration.py

@@ -17,19 +17,22 @@ from __future__ import annotations
 
 import asyncio
 import hashlib
+import re
+import smtplib
 import uuid
 from datetime import datetime, timedelta, timezone
 
 import pytest
 import pytest_asyncio
-from sqlalchemy import func, select, text, update
+from sqlalchemy import delete, func, select, text, update
 
-from inkwell import ratelimit
+from inkwell import mailer, ratelimit
 from inkwell.app import create_app
 from inkwell.config import Config
 from inkwell.db import dispose_engine, session_scope
 from inkwell.models.invite import Invite
 from inkwell.models.password_reset import PasswordReset
+from inkwell.models.settings import Setting
 from inkwell.models.share import Share
 from inkwell.models.label import NoteLabel
 from inkwell.models.note import Note
@@ -476,6 +479,7 @@ async def test_the_security_group_reaches_the_admin_ui(app_client, db):
         "signin_window_minutes",
         "register_limit_per_address",
         "register_window_minutes",
+        "reset_emails_per_account",
     }
     # The UI renders a number input from these, and it cannot offer a safe range it
     # was never told about.
@@ -1337,3 +1341,116 @@ async def test_a_share_names_someone_else_on_this_instance(app_client, db):
     other = await _owners_note(app_client, "another")
     sid = (await (await _share(app_client, nid, people["stranger"])).get_json())["shares"][-1]["id"]
     assert (await app_client.delete(f"/api/notes/{other}/shares/{sid}")).status_code == 404
+
+
+# --- Password reset by email (#5266) ------------------------------------------
+#
+# The SMTP hand-off is replaced by a list; everything up to it is real.
+
+_MAIL_SETTINGS = {
+    "smtp_host": "smtp.example.test",
+    "smtp_from": "inkwell@example.test",
+    "smtp_password": "hunter2",
+    "public_url": "https://notes.example.test/",
+}
+
+
+async def _mail_off() -> None:
+    """Settings outlive the per-test truncate, so each email test starts from none."""
+    async with session_scope() as fresh:
+        await fresh.execute(delete(Setting).where(Setting.key.in_([*_MAIL_SETTINGS, "smtp_security"])))
+        await fresh.commit()
+
+
+def _outbox(monkeypatch) -> list:
+    sent: list = []
+    monkeypatch.setattr(mailer, "_deliver", lambda cfg, msg: sent.append(msg))
+    return sent
+
+
+async def _forgot(email: str):
+    return await create_app().test_client().post("/api/auth/forgot-password", json={"email": email})
+
+
+async def test_the_smtp_password_never_leaves_the_server(app_client, db):
+    await _mail_off()
+    await _admin_with_invite(app_client)
+    saved = await app_client.patch("/api/settings", json=_MAIL_SETTINGS)
+    assert saved.status_code == 200, await saved.get_data(as_text=True)
+    rows = {r["key"]: r for r in (await saved.get_json())["settings"]}
+    assert (rows["smtp_password"]["value"], rows["smtp_password"]["is_set"]) == ("", True)
+    assert rows["public_url"]["value"] == "https://notes.example.test"
+
+    # Saving the form again sends the password field empty, which keeps it.
+    assert (await app_client.patch("/api/settings", json={"smtp_password": ""})).status_code == 200
+    async with session_scope() as fresh:
+        assert await get_setting(fresh, "smtp_password") == "hunter2"
+
+    assert (await app_client.patch("/api/settings", json={"smtp_security": "ssl3"})).status_code == 400
+    assert (await app_client.patch("/api/settings", json={"public_url": "notes.example.test"})).status_code == 400
+
+
+async def test_a_forgotten_password_is_reset_from_an_emailed_link(app_client, db, monkeypatch):
+    await _mail_off()
+    outbox = _outbox(monkeypatch)
+    token = await _admin_with_invite(app_client)
+    assert (await _register("guest@example.test", token)).status_code == 201
+
+    # Off until the server can send: no link on sign-in, and the route says so.
+    assert (await (await app_client.get("/api/config")).get_json())["password_reset_by_email"] is False
+    assert (await _forgot("guest@example.test")).status_code == 400
+
+    await app_client.patch("/api/settings", json=_MAIL_SETTINGS)
+    assert (await (await app_client.get("/api/config")).get_json())["password_reset_by_email"] is True
+
+    known = await _forgot("Guest@Example.test")
+    unknown = await _forgot("nobody@example.test")
+    assert known.status_code == unknown.status_code == 200
+    assert await known.get_json() == await unknown.get_json()
+    await mailer.drain()
+
+    assert [m["To"] for m in outbox] == ["guest@example.test"]
+    text = outbox[0].get_content()
+    link = re.search(r"https://notes\.example\.test/reset-password\?token=([\w-]+)", text)
+    assert link, text
+    async with session_scope() as fresh:
+        assert await fresh.scalar(select(PasswordReset.created_by)) is None
+
+    reset = await create_app().test_client().post(
+        "/api/auth/reset-password", json={"token": link.group(1), "password": "chosen-by-email"}
+    )
+    assert reset.status_code == 200
+    assert (await reset.get_json())["email"] == "guest@example.test"
+
+
+async def test_reset_emails_stop_at_the_cap_without_saying_so(app_client, db, monkeypatch):
+    await _mail_off()
+    outbox = _outbox(monkeypatch)
+    token = await _admin_with_invite(app_client)
+    assert (await _register("guest@example.test", token)).status_code == 201
+    await app_client.patch("/api/settings", json=_MAIL_SETTINGS)
+
+    answers = [await _forgot("guest@example.test") for _ in range(4)]
+    assert [a.status_code for a in answers] == [200, 200, 200, 200]
+    await mailer.drain()
+    assert len(outbox) == 3  # reset_emails_per_account defaults to 3
+
+
+async def test_the_test_email_goes_to_the_admin_and_reports_a_failure(app_client, db, monkeypatch):
+    await _mail_off()
+    outbox = _outbox(monkeypatch)
+    await _admin_with_invite(app_client)
+    assert (await app_client.post("/api/settings/test-email")).status_code == 400
+
+    await app_client.patch("/api/settings", json=_MAIL_SETTINGS)
+    sent = await app_client.post("/api/settings/test-email")
+    assert sent.status_code == 200
+    assert [m["To"] for m in outbox] == ["owner@example.test"]
+
+    def refuse(cfg, msg):
+        raise smtplib.SMTPAuthenticationError(535, b"bad credentials")
+
+    monkeypatch.setattr(mailer, "_deliver", refuse)
+    failed = await app_client.post("/api/settings/test-email")
+    assert failed.status_code == 502
+    assert "bad credentials" in (await failed.get_json())["error"]