refactor(auth): centralize token hashing, email validation & admin gating

- app/utils.py: shared valid_email() + now_utc() (one email regex, was duplicated
  in auth.py and admin.py with a looser "@"-in check elsewhere).
- security.hash_token(): one SHA-256 token hasher (was duplicated in auth.py + state.py).
- auth.admin_user dependency + count_admins() helper, replacing the inline role
  checks and the last-admin count query repeated across admin.py/me.py/tags.py.

backend/app/auth.py

@@ -1,6 +1,4 @@
-import hashlib
 import logging
-import re
 import secrets
 from datetime import datetime, timedelta, timezone
 
@@ -8,7 +6,7 @@ import httpx
 from authlib.integrations.starlette_client import OAuth, OAuthError
 from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
 from fastapi.responses import JSONResponse, RedirectResponse
-from sqlalchemy import delete, select
+from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 
 from app import email as email_mod
@@ -17,7 +15,8 @@ from app.config import settings
 from app.db import get_db
 from app.models import AuthToken, DemoWhitelist, Invite, OAuthToken, User
 from app.ratelimit import RateLimiter
-from app.security import decrypt, encrypt, hash_password, verify_password
+from app.security import decrypt, encrypt, hash_password, hash_token, verify_password
+from app.utils import valid_email
 
 # Email+password auth tuning.
 PASSWORD_MIN_LEN = 10
@@ -43,8 +42,6 @@ def _notify_suspended(background: BackgroundTasks, email: str) -> None:
     if _suspend_email_limiter.allow(email):
         background.add_task(email_mod.send_account_suspended, email, operator_contact())
 
-_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
-
 # The single shared demo account's stable identity. The row is created lazily on first
 # demo login (see get_or_create_demo_user); these are just its sentinel keys.
 DEMO_GOOGLE_SUB = "__demo__"
@@ -184,7 +181,7 @@ 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."""
     email = (email or "").lower()
-    if not _EMAIL_RE.match(email):
+    if not valid_email(email):
         return None
     inv = db.execute(select(Invite).where(Invite.email == email)).scalar_one_or_none()
     if inv is not None:
@@ -443,7 +440,7 @@ async def request_access(
     """Public: ask for access. Idempotent — repeat requests for the same email don't
     duplicate or re-spam admins (upsert returns None for an already-pending row)."""
     email = (payload.get("email") or "").strip().lower()
-    if not _EMAIL_RE.match(email):
+    if not valid_email(email):
         raise HTTPException(status_code=400, detail="Enter a valid email address.")
     if is_allowed(db, email):
         return {"status": "approved"}  # already allowed — just sign in
@@ -465,7 +462,7 @@ def demo_login(payload: dict, request: Request, db: Session = Depends(get_db)) -
     if not _demo_limiter.allow(_client_ip(request)):
         return {"authenticated": False}
     email = (payload.get("email") or "").strip().lower()
-    if _EMAIL_RE.match(email) and is_demo_allowed(db, email):
+    if valid_email(email) and is_demo_allowed(db, email):
         demo = get_or_create_demo_user(db)
         request.session["user_id"] = demo.id
         log.info("Demo login (key=%s, demo_id=%s)", email, demo.id)
@@ -487,10 +484,6 @@ def _app_base() -> str:
     return settings.app_base
 
 
-def _hash_token(raw: str) -> str:
-    return hashlib.sha256(raw.encode()).hexdigest()
-
-
 def _issue_token(db: Session, user: User, kind: str, ttl: timedelta) -> str:
     """Create a single-use token of `kind`; only its hash is stored. Returns the raw token
     (goes only into the emailed link)."""
@@ -499,7 +492,7 @@ def _issue_token(db: Session, user: User, kind: str, ttl: timedelta) -> str:
         AuthToken(
             user_id=user.id,
             kind=kind,
-            token_hash=_hash_token(raw),
+            token_hash=hash_token(raw),
             expires_at=datetime.now(timezone.utc) + ttl,
         )
     )
@@ -513,7 +506,7 @@ def _consume_token(db: Session, raw: str | None, kind: str) -> User | None:
         return None
     row = db.execute(
         select(AuthToken).where(
-            AuthToken.token_hash == _hash_token(raw), AuthToken.kind == kind
+            AuthToken.token_hash == hash_token(raw), AuthToken.kind == kind
         )
     ).scalar_one_or_none()
     if row is None or row.used_at is not None or row.expires_at < datetime.now(timezone.utc):
@@ -537,7 +530,7 @@ def register(
     email = (payload.get("email") or "").strip().lower()
     password = payload.get("password") or ""
     # Input validation is safe to reveal (independent of whether the email exists).
-    if not _EMAIL_RE.match(email):
+    if not valid_email(email):
         raise HTTPException(status_code=400, detail="Enter a valid email address.")
     if len(password) < PASSWORD_MIN_LEN:
         raise HTTPException(
@@ -633,7 +626,7 @@ def password_reset_request(
     if not _reset_limiter.allow(_client_ip(request)):
         return {"status": "ok"}
     email = (payload.get("email") or "").strip().lower()
-    if _EMAIL_RE.match(email):
+    if valid_email(email):
         user = db.execute(select(User).where(User.email == email)).scalar_one_or_none()
         if user is not None and user.password_hash and not user.is_demo:
             raw = _issue_token(db, user, "reset", RESET_TTL)
@@ -694,6 +687,23 @@ def require_human(user: User = Depends(current_user)) -> User:
     return user
 
 
+def admin_user(user: User = Depends(current_user)) -> User:
+    """Dependency: require the signed-in user to be an admin. Single source of truth for the
+    admin gate — every admin route/action depends on this rather than re-checking the role."""
+    if user.role != "admin":
+        raise HTTPException(status_code=403, detail="Admin only")
+    return user
+
+
+def count_admins(db: Session, *, active_only: bool = False) -> int:
+    """How many admins exist (optionally only un-suspended ones). Used by the 'can't remove /
+    suspend / delete the last admin' guards so they don't each re-spell the count query."""
+    q = select(func.count()).select_from(User).where(User.role == "admin")
+    if active_only:
+        q = q.where(User.is_suspended.is_(False))
+    return db.scalar(q) or 0
+
+
 @router.get("/link")
 async def link_google(
     request: Request,