feat(auth): authenticate + lockout + operator data helpers

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

backend/operator_auth.py

@@ -26,6 +26,11 @@ LOCK_MINUTES = 15
 # Role ladder — a rank map so checks read naturally and 'operator' slots in later.
 _ROLE_RANK = {"operator": 10, "admin": 20, "superadmin": 30}
 
+# A throwaway hash used only to equalize verify time on the unknown-email path,
+# so a missing account can't be distinguished from a wrong password by timing
+# (no user-enumeration). The value never authenticates anything.
+_DUMMY_PASSWORD_HASH = hash_password("operator-auth-timing-equalizer")
+
 
 def role_at_least(role: str, minimum: str) -> bool:
     """True iff `role` ranks at or above `minimum`. Unknown roles rank as 0."""
@@ -61,3 +66,93 @@ def current_operator(request, db):
     if user.sessions_valid_from and datetime.utcfromtimestamp(int(iat)) < user.sessions_valid_from:
         return None
     return user
+
+
+def register_login_failure(db, user) -> None:
+    """Increment a user's failure counter and lock them out past the threshold."""
+    user.failed_login_count = (user.failed_login_count or 0) + 1
+    if user.failed_login_count >= MAX_LOGIN_FAILURES:
+        user.locked_until = datetime.utcnow() + timedelta(minutes=LOCK_MINUTES)
+    db.commit()
+
+
+def authenticate(db, email, password):
+    """Return (user, "ok") on success, (None, "locked") if locked out, else
+    (None, "bad"). Never reveals whether the email exists: an unknown email runs
+    the same argon2 verify (against a dummy hash) as a wrong password, so neither
+    the response text nor its timing distinguishes the two."""
+    user = db.query(OperatorUser).filter_by(email=_norm_email(email)).first()
+    if user and user.locked_until and user.locked_until > datetime.utcnow():
+        return None, "locked"
+    password_ok = verify_password(password, user.password_hash if user else _DUMMY_PASSWORD_HASH)
+    if not user or not user.active or not password_ok:
+        if user:
+            register_login_failure(db, user)
+        return None, "bad"
+    user.failed_login_count = 0
+    user.locked_until = None
+    user.last_login_at = datetime.utcnow()
+    db.commit()
+    return user, "ok"
+
+
+def create_operator(db, email, name, role, password=None, must_change=None):
+    """Create an operator. With no password, generate a temp one and force a change
+    (must_change defaults True). With a password, must_change defaults False.
+    Returns (user, raw_password_to_show_once). Raises ValueError on dup/bad role."""
+    email = _norm_email(email)
+    if role not in _ROLE_RANK:
+        raise ValueError(f"unknown role {role!r}")
+    if db.query(OperatorUser).filter_by(email=email).first():
+        raise ValueError(f"operator {email} already exists")
+    if password is None:
+        password = generate_password()
+        if must_change is None:
+            must_change = True
+    elif must_change is None:
+        must_change = False
+    user = OperatorUser(id=str(uuid.uuid4()), email=email, display_name=name,
+                        password_hash=hash_password(password), role=role,
+                        active=True, must_change_password=must_change)
+    db.add(user)
+    db.commit()
+    return user, password
+
+
+def reset_operator_password(db, user) -> str:
+    """Generate a fresh temp password, force a change, log the user out everywhere.
+    Returns the raw password to show once."""
+    raw = generate_password()
+    user.password_hash = hash_password(raw)
+    user.must_change_password = True
+    user.failed_login_count = 0
+    user.locked_until = None
+    user.sessions_valid_from = datetime.utcnow().replace(microsecond=0)
+    db.commit()
+    return raw
+
+
+def change_own_password(db, user, new_password) -> int:
+    """Set a user's own new password, clear the forced-change flag, and bump
+    sessions_valid_from to the returned iat — the caller mints the replacement
+    cookie with that exact iat so it stays valid while older cookies die."""
+    new_iat = int(time.time())
+    user.password_hash = hash_password(new_password)
+    user.must_change_password = False
+    user.sessions_valid_from = datetime.utcfromtimestamp(new_iat)
+    db.commit()
+    return new_iat
+
+
+def set_operator_active(db, user, active: bool):
+    user.active = bool(active)
+    db.commit()
+    return user
+
+
+def set_operator_role(db, user, role: str):
+    if role not in _ROLE_RANK:
+        raise ValueError(f"unknown role {role!r}")
+    user.role = role
+    db.commit()
+    return user