fix(auth): name the state and the address behind a refused sign-in (E9.5 S4)

"Your account is awaiting admin approval." was true and useless. It never said WHICH mailbox the
account was on, and on 2026-09-03 that silence hid a Gmail alias mismatch for a day: a registration
as np.temu@gmail.com met a Google claim of nptemu@gmail.com, and every screen in the funnel agreed
to say nothing about it.

Every refusal password-login can answer with now uses the codebase's structured {code, reason}
detail, built in one helper. The three that arrive AFTER the password is proven carry the address on
the account plus both gate flags; the two that answer before it (invalid, rate_limited) carry
nothing, so a wrong password and an unknown account stay byte-identical. The frontend renders the
first three as a named screen in place of the form — there is nothing to retype once the password is
correct — with an icon, the two-gate checklist, the address in monospace, and a resend CTA where one
helps. Reporting each gate from its own flag is the payoff of S1: approved-but-unverified is a real
state now, and a screen that assumed a sequence would send that user off to wait for an admin who
has already decided.

The Google access-request notice names the address too, and says so when the request was already on
file under ANOTHER spelling of the same mailbox — the honest version of "we didn't open a second
one", stated only when it applies. It moved from the query string to the fragment: the notice now
carries an address, and a query string lands in every reverse-proxy access log. Same reasoning that
put the verify/reset tokens there, and the same owner already clears it. urlencode, not an f-string,
because URLSearchParams reads a bare + in a fragment as a space and would mangle exactly the
+tag addresses this epic exists to protect.

upsert_pending_invite returns the row it settled on beside the is-new flag, since the row's stored
address is what the notice has to name and what mail will go to.

Deviation from the PendingScreen mockup, deliberately: no "Sign out" button and no separate "Not
your address?" link. The mockup drew the panel in the app shell; the accepted decision (a) keeps the
pending user session-less, so there is no session to end, and the address is named directly above a
"Back to sign in" that answers the same question.

UAT on localdev, both languages: all three refusals with the typed spelling deliberately differing
from the stored one (the panel named the stored one), the resend CTA carrying the typed address into
the resend form, and both access-request banners with a +tag address surviving the fragment round
trip. Throwaway accounts and the language switch reverted.

backend/app/routes/auth.py

@@ -6,6 +6,8 @@ helpers) stays in app/auth.py, imported below."""
 import ipaddress
 import secrets
 from datetime import datetime, timedelta, timezone
+from typing import NamedTuple
+from urllib.parse import urlencode
 
 from authlib.integrations.starlette_client import OAuth, OAuthError
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
@@ -148,9 +150,22 @@ def _client_ip(request: Request) -> str:
     return peer
 
 
-def upsert_pending_invite(db: Session, email: str) -> Invite | None:
-    """Idempotently record an access request. Returns the Invite if a *new* pending row
-    was created (so the caller can notify admins), else None for already-known emails.
+class InviteRequest(NamedTuple):
+    """What an access request settled on.
+
+    `invite` is the row the request now lives under — which is NOT always the address that was just
+    typed: one Gmail mailbox spelled two ways settles on whichever row already exists, and that row's
+    address is where mail will go. Callers that tell the user what happened need it (E9.5 S4).
+    `is_new` is the old boolean return in a name: true only when a row was created or a denied one
+    reopened, i.e. exactly when admins should hear about it. A repeat request must not re-spam them.
+    """
+
+    invite: Invite | None
+    is_new: bool
+
+
+def upsert_pending_invite(db: Session, email: str) -> InviteRequest:
+    """Idempotently record an access request.
 
     "Already known" is decided on the CANONICAL form: `npeter83.temu@` and `npeter83temu@` are one
     Gmail mailbox, and treating them as two is what put a second, silent access request in the admin
@@ -160,7 +175,7 @@ def upsert_pending_invite(db: Session, email: str) -> Invite | None:
     """
     email = (email or "").lower()
     if not valid_email(email):
-        return None
+        return InviteRequest(None, False)
     canon = canonical_email(email)
     rows = db.execute(select(Invite).where(Invite.email_canonical == canon)).scalars().all()
     # Prefer a decided row over a pending one, so a denied duplicate can't mask an approval.
@@ -173,12 +188,37 @@ def upsert_pending_invite(db: Session, email: str) -> Invite | None:
             inv.decided_at = None
             inv.decided_by = None
             db.commit()
-            return inv
-        return None
+            return InviteRequest(inv, True)
+        return InviteRequest(inv, False)
     inv = Invite(email=email, status="pending")
     db.add(inv)
     db.commit()
-    return inv
+    return InviteRequest(inv, True)
+
+
+def _access_notice_url(kind: str, email: str = "", inv: Invite | None = None) -> str:
+    """The landing URL for a Google sign-in that did not reach an account: `requested` (we recorded
+    the request) or `denied` (nothing to record).
+
+    It rides the FRAGMENT, not the query string, for the same reason the verify/reset tokens do
+    (SB3): a fragment never reaches the server, a proxy access log or a Referer header — and this
+    notice now carries the user's address. Naming it is the point of E9.5 S4: on 2026-09-03 a
+    registration as `npeter83.temu@` met an OAuth claim of `npeter83temu@`, and a screen that said
+    "request recorded" without saying FOR WHAT hid the mismatch for a day.
+
+    `linked` names the address the request actually lives under, and ONLY when that differs from the
+    one Google just returned — the honest version of "we didn't open a second request". Same
+    spelling twice is just a repeat, and saying anything there would be noise.
+
+    urlencode (not an f-string): a `+tag` address must arrive as %2B, or the SPA's URLSearchParams
+    would read it back as a space and mangle exactly the address this epic exists to protect.
+    """
+    params = {"access": kind}
+    if email:
+        params["email"] = email
+    if inv is not None and inv.email != email:
+        params["linked"] = inv.email
+    return "/#" + urlencode(params)
 
 
 _DEV_OAUTH_HOSTS = frozenset(
@@ -294,12 +334,12 @@ async def callback(
         # A denied Google login doubles as an access request: record it for the admin and
         # land the user on a friendly "request received" screen instead of a raw 403.
         if email:
-            inv = upsert_pending_invite(db, email)
+            req = upsert_pending_invite(db, email)
             admins = admin_notify_emails(db)
-            if inv is not None and admins:
+            if req.is_new and admins:
                 background.add_task(email_mod.send_admin_new_request, admins, email)
-            return RedirectResponse(url="/?access=requested")
-        return RedirectResponse(url="/?access=denied")
+            return RedirectResponse(url=_access_notice_url("requested", email, req.invite))
+        return RedirectResponse(url=_access_notice_url("denied"))
 
     user = db.query(User).filter(User.google_sub == sub).one_or_none()
     if user is None:
@@ -323,7 +363,7 @@ async def callback(
                 # A different Google identity is already bound to this email — refuse rather than
                 # hijack it. (Near-impossible with real Google accounts: email↔sub is stable.)
                 log.warning("Google login email collision (different sub): %s", email)
-                return RedirectResponse(url="/?access=denied")
+                return RedirectResponse(url=_access_notice_url("denied"))
             if not userinfo.get("email_verified", False):
                 # Adopting (and activating) a pre-existing password account requires Google to
                 # actually attest the address — otherwise an unverified Google email that merely
@@ -332,7 +372,7 @@ async def callback(
                     "Google login: unverified email, refusing to adopt account: %s",
                     email,
                 )
-                return RedirectResponse(url="/?access=denied")
+                return RedirectResponse(url=_access_notice_url("denied"))
             user = existing
             user.google_sub = sub
             # SEC-10: drop any password pre-set on this account while its email was still unverified,
@@ -538,9 +578,9 @@ async def request_access(
         return {"status": "pending"}
     if is_allowed(db, email):
         return {"status": "pending"}  # already allowed — don't reveal it
-    inv = upsert_pending_invite(db, email)
+    req = upsert_pending_invite(db, email)
     admins = admin_notify_emails(db)
-    if inv is not None and admins:
+    if req.is_new and admins:
         background.add_task(email_mod.send_admin_new_request, admins, email)
     return {"status": "pending"}
 
@@ -776,6 +816,33 @@ def _resend_verify_if_eligible(email: str) -> None:
             email_mod.send_verify_email(user.email, f"{_app_base()}/#verify={raw}")
 
 
+def _login_refused(status: int, reason: str, user: User | None = None, **extra) -> HTTPException:
+    """Every refusal password_login can answer with, in the codebase's structured `{code, reason}`
+    shape so the SPA can say it in the user's own language (the old bare English strings were
+    unreadable under a bilingual UI, and unusable as anything but a one-line error).
+
+    The account-shaped reasons carry the address ON THE ACCOUNT plus both gate flags. That is what
+    turns a flat 403 into an honest screen — it names the mailbox and says which of the two gates is
+    still shut. It is not an enumeration leak: this branch is only reachable once the password has
+    been proven, so the caller already knows the account exists. The two reasons that answer BEFORE
+    that proof (`invalid`, `rate_limited`) carry nothing at all, so they stay byte-identical for a
+    real account and an unknown one.
+
+    Since E9.5 S1 the two gates are order-independent, so `approved` really can be true while
+    `email_verified` is false, and vice versa — the SPA renders whichever is actually outstanding
+    rather than assuming a sequence.
+    """
+    detail: dict = {"code": "login", "reason": reason}
+    if user is not None:
+        detail |= {
+            "email": user.email,
+            "email_verified": user.email_verified,
+            "approved": user.is_active,
+        }
+    detail |= {k: v for k, v in extra.items() if v is not None}
+    return HTTPException(status_code=status, detail=detail)
+
+
 @router.post("/password-login")
 def password_login(
     body: EmailPasswordIn,
@@ -787,7 +854,7 @@ def password_login(
     Once the password is proven correct, the owner gets a specific reason if their account is
     still pending or suspended — that's not an enumeration leak (they already hold the password)."""
     if not _login_limiter.allow(_client_ip(request)):
-        raise HTTPException(status_code=429, detail="Too many attempts. Try again shortly.")
+        raise _login_refused(429, "rate_limited")
     email = (body.email or "").strip().lower()
     password = body.password or ""
     user = find_user_by_email(db, email)
@@ -796,20 +863,14 @@ def password_login(
     candidate_hash = user.password_hash if (user and not user.is_demo) else None
     password_ok = verify_password(password, candidate_hash or _DECOY_PASSWORD_HASH)
     if user is None or user.is_demo or not password_ok:
-        raise HTTPException(status_code=401, detail="Invalid email or password.")
+        raise _login_refused(401, "invalid")
     if user.is_suspended:
         _notify_suspended(background, user.email)
-        op = operator_contact()
-        detail = "Your account has been suspended."
-        if op:
-            detail += f" If you have questions, contact the operator at {op}."
-        raise HTTPException(status_code=403, detail=detail)
+        raise _login_refused(403, "suspended", user, operator=operator_contact() or None)
     if not user.email_verified:
-        raise HTTPException(
-            status_code=403, detail="Please verify your email first (check your inbox)."
-        )
+        raise _login_refused(403, "email_unverified", user)
     if not user.is_active:
-        raise HTTPException(status_code=403, detail="Your account is awaiting admin approval.")
+        raise _login_refused(403, "pending_approval", user)
     _establish_session(request, user)
     log.info("Password login: %s (id=%s, role=%s)", email, user.id, user.role)
     return {"ok": True}

backend/tests/test_auth_session.py

@@ -134,7 +134,7 @@ def test_an_approved_but_unverified_account_still_cannot_sign_in(client, make_us
     r = _login(client, "notyet@example.com", "attacker-chosen")
 
     assert r.status_code == 403
-    assert "verify" in r.json()["detail"].lower()
+    assert r.json()["detail"]["reason"] == "email_unverified"
 
 
 def test_verifying_afterwards_lets_the_original_password_in(client, db, make_user):

backend/tests/test_email_canonical.py

@@ -137,9 +137,10 @@ def test_a_second_spelling_does_not_open_a_second_access_request(db):
     db.add(Invite(email="already.approved@gmail.com", status="approved"))
     db.commit()
 
-    created = upsert_pending_invite(db, "alreadyapproved@gmail.com")
+    req = upsert_pending_invite(db, "alreadyapproved@gmail.com")
 
-    assert created is None  # nothing new to notify an admin about
+    assert req.is_new is False  # nothing new to notify an admin about
+    assert req.invite is not None and req.invite.email == "already.approved@gmail.com"
     assert len(db.execute(select(Invite)).scalars().all()) == 1
 
 

backend/tests/test_login_states.py

@@ -0,0 +1,107 @@
+"""What a refused sign-in SAYS (E9.5 S4), DB-lane.
+
+The states behind a 403 were true and useless: "Your account is awaiting admin approval." never
+revealed WHICH mailbox the account was on. On 2026-09-03 a registration as `npeter83.temu@gmail.com`
+met a Google claim of `npeter83temu@gmail.com`, and that missing address hid the mismatch for a day.
+So these pin the DETAIL, not just the status code — the address, and both gates, since E9.5 S1 made
+the two order-independent and the screen must report whichever is actually outstanding.
+
+The two refusals that answer BEFORE the password is proven carry nothing, and that is the security
+half of the same contract: `invalid` must stay byte-identical for a real account and an unknown one.
+"""
+
+from app.config import settings
+from app.models import Invite
+from app.routes.auth import _access_notice_url, upsert_pending_invite
+
+_PW = "correct horse battery"
+
+
+def _login(client, email, password=_PW):
+    return client.post("/auth/password-login", json={"email": email, "password": password})
+
+
+def test_pending_approval_names_the_address_the_account_is_on(client, make_user):
+    # The typed spelling and the stored one are the same mailbox; the screen must show the STORED
+    # one, because that is the mismatch a user cannot otherwise see.
+    make_user(email="np.temu@gmail.com", password=_PW, is_active=False)
+
+    detail = _login(client, "nptemu@gmail.com").json()["detail"]
+
+    assert detail["reason"] == "pending_approval"
+    assert detail["email"] == "np.temu@gmail.com"
+    assert detail["email_verified"] is True and detail["approved"] is False
+
+
+def test_an_already_approved_account_still_reports_its_missing_verification(client, make_user):
+    # S1 made the gates order-independent, so this really happens: approved, not yet verified. A
+    # screen that assumed a sequence would tell this user to wait for an admin who already decided.
+    make_user(
+        email="approved.first@example.com", password=_PW, email_verified=False, is_active=True
+    )
+
+    detail = _login(client, "approved.first@example.com").json()["detail"]
+
+    assert detail["reason"] == "email_unverified"
+    assert detail["email_verified"] is False and detail["approved"] is True
+
+
+def test_a_suspended_account_is_told_who_to_contact(client, make_user, monkeypatch):
+    monkeypatch.setattr(settings, "admin_emails", "ops@example.com")
+    make_user(email="banned@example.com", password=_PW, is_suspended=True)
+
+    r = _login(client, "banned@example.com")
+
+    assert r.status_code == 403
+    assert r.json()["detail"]["reason"] == "suspended"
+    assert r.json()["detail"]["operator"] == "ops@example.com"
+
+
+def test_a_refusal_before_the_password_is_proven_carries_no_account_detail(client, make_user):
+    make_user(email="real@example.com", password=_PW, is_active=False)
+
+    wrong_pw = _login(client, "real@example.com", "not the password").json()["detail"]
+    unknown = _login(client, "nobody@example.com").json()["detail"]
+
+    # No address, no flags — the pending state above must not leak through the wrong-password door.
+    assert wrong_pw == unknown == {"code": "login", "reason": "invalid"}
+
+
+# --- the access-request notice -------------------------------------------------------------------
+
+
+def test_the_access_notice_names_the_address_and_rides_the_fragment():
+    url = _access_notice_url("requested", "someone@example.com")
+
+    # A fragment never reaches a proxy access log or a Referer header — the same reasoning that put
+    # the verify/reset tokens there (SB3), applied to an address.
+    assert url == "/#access=requested&email=someone%40example.com"
+
+
+def test_a_plus_tagged_address_survives_the_round_trip():
+    # URLSearchParams reads a bare `+` in a fragment as a SPACE, so the encoder must emit %2B — or
+    # the very address family this epic exists to protect arrives mangled.
+    url = _access_notice_url("requested", "me+siftlode@gmail.com")
+
+    assert "me%2Bsiftlode%40gmail.com" in url and "+siftlode" not in url
+
+
+def test_a_request_already_on_file_under_another_spelling_says_so(db):
+    db.add(Invite(email="hartmann.peter@gmail.com", status="pending"))
+    db.commit()
+
+    req = upsert_pending_invite(db, "hartmannpeter@gmail.com")
+    url = _access_notice_url("requested", "hartmannpeter@gmail.com", req.invite)
+
+    assert req.is_new is False  # one mailbox, one request — no second row for the admin queue
+    assert "linked=hartmann.peter%40gmail.com" in url
+
+
+def test_the_same_spelling_twice_is_just_a_repeat_and_says_nothing_extra(db):
+    db.add(Invite(email="same@example.com", status="pending"))
+    db.commit()
+
+    req = upsert_pending_invite(db, "same@example.com")
+
+    # Nothing to explain: telling this user we "linked" their request to itself would be noise.
+    assert "linked" not in _access_notice_url("requested", "same@example.com", req.invite)