Skip to content

Self-hosted monitoring for homelabs: host and container metrics and uptime checks from all your machines in one dashboard, with an optional AI agent that diagnoses incidents and suggests fixes.

refactor(main): move auth routes into routes/auth.py

karloks2005541d21f84cfb
diff --git a/src/backend/main.py b/src/backend/main.py
index 6fe4562..fdab989 100644
--- a/src/backend/main.py
+++ b/src/backend/main.py
@@ -471,167 +471,6 @@ def get_instance_name(db) -> str | None:
return f"{first}'s homelab" if first else None
[email protected]("/auth/config")
-def auth_config(db=Depends(get_db)):
- """What the sign-in pages show before anyone has signed in. Everything here is public by design: keep it to
- what a visitor may know (see SECURITY.md)."""
- return {
- "registration_enabled": registration_open(db), "bootstrap_required": db.query(User).count() == 0,
- "instance_name": get_instance_name(db), "server_count": db.query(Server).count(), "version": APP_VERSION,
- }
-
-
-def _valid_invite(db, token: str | None) -> Invite | None:
- if not token or not 20 <= len(token) <= 200:
- return None
- return db.query(Invite).filter(Invite.token_hash == _hash_secret(token.strip()), Invite.used_at.is_(None), Invite.expires_at > datetime.now(timezone.utc)).first()
-
-
[email protected]("/auth/invite")
-def auth_invite(token: Annotated[str, Query(min_length=20, max_length=200)], request: Request, db=Depends(get_db)):
- """Whether an invitation link still works and who it is for, so the register page can say so."""
- enforce_ip_limit(redis_client, scope="invite-check", ip_address=_client_ip(request), limit=30, window_seconds=3600)
- invite = _valid_invite(db, token)
- if not invite:
- raise HTTPException(status_code=404, detail="This invitation is no longer valid.")
- return {"email": invite.email, "role": invite.role}
-
-
[email protected]("/auth/register")
-def auth_register(payload: RegisterRequest, request: Request, response: Response, db=Depends(get_db)):
- invite = _valid_invite(db, payload.invite_token)
- if payload.invite_token and not invite:
- raise HTTPException(status_code=403, detail="This invitation is no longer valid. Ask for a new one.")
- if invite and invite.email != str(payload.email).strip().lower():
- raise HTTPException(status_code=403, detail="This invitation was made for a different email address.")
- if not invite and not registration_open(db):
- raise HTTPException(status_code=403, detail="Registration is disabled on this server.")
- enforce_register_limit(
- redis_client,
- ip_address=request.client.host if request.client else "unknown",
- limit=REGISTER_RATE_LIMIT,
- window_seconds=REGISTER_RATE_WINDOW_SECONDS,
- )
- first_account = db.query(User).count() == 0
- if first_account and not _bootstrap_token_valid(db, payload.bootstrap_token):
- raise HTTPException(status_code=403, detail="This install needs its setup token to create the first account. Find it in the backend log: docker compose logs backend | grep \"setup token\"")
- try:
- result = register_user(
- db,
- redis_client,
- name=payload.name,
- email=str(payload.email),
- password=payload.password,
- admin_requires_two_factor=two_factor_enforced(db),
- everyone_requires_two_factor=two_factor_required_for(db, "user"),
- role=invite.role if invite and not first_account else None,
- ip=_client_ip(request),
- user_agent=request.headers.get("user-agent"),
- )
- except ValueError as exc:
- raise HTTPException(status_code=400, detail=str(exc)) from exc
-
- if invite:
- invite.used_at = datetime.now(timezone.utc)
- db.commit()
- if first_account:
- ensure_bootstrap_token(db) # an account exists now: this removes the token
- _set_session_cookie(response, result.pop("session_id"))
- return result
-
-
-def _set_session_cookie(response: Response, session_id: str, lifetime: int = SESSION_TTL_SECONDS) -> None:
- response.set_cookie(
- key=SESSION_COOKIE_NAME,
- value=session_id,
- max_age=lifetime,
- httponly=True,
- secure=SESSION_COOKIE_SECURE,
- samesite="lax",
- path="/",
- )
-
-
-def _user_payload(user: User, **extra) -> dict:
- return {"id": user.id, "name": user.name, "email": user.email, "role": user.role, "is_active": user.is_active, **extra}
-
-
-def _complete_login(db, request: Request, response: Response, user: User, how: str = "", remember: bool = False) -> dict:
- """Open the session after every required step has passed.
-
- An administrator without two-factor, while it is required, gets an enrollment session: it can reach
- the two-factor setup and nothing else until setup is done.
- """
- stage = STAGE_ENROLLMENT if not user.totp_enabled and two_factor_required_for(db, user.role) else STAGE_FULL
- user.last_seen_at = datetime.now(timezone.utc)
- session_id, _public_id = create_session(redis_client, user, stage=stage, ip=_client_ip(request), user_agent=request.headers.get("user-agent"), remember=remember)
- # The cookie lasts exactly as long as the session behind it.
- _set_session_cookie(response, session_id, session_lifetime(stage, remember))
- record_audit_log(db, user_id=user.id, level="INFO", message=f"User signed in{how}{' (staying signed in for 30 days)' if remember and stage == STAGE_FULL else ''}", source="auth")
- return {"user": _user_payload(user), "setup_required": stage == STAGE_ENROLLMENT}
-
-
[email protected]("/auth/login")
-def auth_login(payload: LoginRequest, request: Request, response: Response, db=Depends(get_db)):
- limit_keys = enforce_login_limit(
- redis_client,
- ip_address=request.client.host if request.client else "unknown",
- email=str(payload.email),
- limit=LOGIN_RATE_LIMIT,
- window_seconds=LOGIN_RATE_WINDOW_SECONDS,
- )
- try:
- user = verify_credentials(db, email=str(payload.email), password=payload.password)
- except ValueError as exc:
- raise HTTPException(status_code=401, detail=str(exc)) from exc
-
- # This email's counter is cleared. The address's counter only gets this one successful attempt back: clearing it
- # would let anyone with an account of their own reset the limit between guesses at someone else's password.
- reset_limits(redis_client, limit_keys[1])
- refund_attempt(redis_client, limit_keys[0])
- if user.totp_enabled:
- # No session exists until the second step passes; this token only carries the login between the steps.
- return {"status": "two_factor_required", "pending_token": create_pending_two_factor(redis_client, user.id, payload.remember)}
- return _complete_login(db, request, response, user, remember=payload.remember)
-
-
-def _second_factor_or_error(db, user: User, code: str) -> str:
- """Verify a code for the user, with the shared brute-force limit. Raises 401 (or 429/503); returns "totp" or "recovery"."""
- limit_key = enforce_limit(redis_client, scope="2fa-user", subject=user.id, limit=TWO_FACTOR_ATTEMPTS, window_seconds=TWO_FACTOR_WINDOW_SECONDS)
- try:
- method = verify_second_factor(db, user, code)
- except secrets_box.SecretsUnavailable as exc:
- raise HTTPException(status_code=503, detail="Two-factor codes can't be checked on this server right now (a SECRETS_KEY problem). A recovery code still works.") from exc
- if method is None:
- record_audit_log(db, user_id=user.id, level="WARNING", message="A wrong two-factor code was entered", source="auth")
- raise HTTPException(status_code=401, detail="Invalid code.")
- reset_limits(redis_client, limit_key)
- return method
-
-
[email protected]("/auth/login/2fa")
-def auth_login_two_factor(payload: TwoFactorLoginRequest, request: Request, response: Response, db=Depends(get_db)):
- enforce_ip_limit(redis_client, scope="2fa-ip", ip_address=_client_ip(request), limit=20, window_seconds=TWO_FACTOR_WINDOW_SECONDS)
- expired = HTTPException(status_code=401, detail="Sign-in expired. Please sign in again.")
- user_id = read_pending_two_factor(redis_client, payload.pending_token)
- if user_id is None:
- raise expired
- if not count_pending_attempt(redis_client, payload.pending_token):
- raise HTTPException(status_code=401, detail="Too many wrong codes. Please sign in again.")
- user = db.get(User, user_id)
- if not user or not user.is_active or not user.totp_enabled:
- raise expired
- method = _second_factor_or_error(db, user, payload.code)
- db.commit() # the code that was just accepted is now spent
- remember = pending_two_factor_remember(redis_client, payload.pending_token)
- delete_pending_two_factor(redis_client, payload.pending_token)
- if method == "recovery":
- record_audit_log(db, user_id=user.id, level="WARNING", message="A two-factor recovery code was used to sign in", source="auth")
- result = _complete_login(db, request, response, user, " with two-factor", remember=remember)
- result["recovery_codes_left"] = recovery_codes_left(db, user)
- return result
-
-
def _account_session(session_id, db, *, allow_limited: bool = False) -> tuple[dict, User]:
"""The caller's session and account for the account endpoints. Enrollment sessions only where allowed."""
session = get_session(redis_client, session_id)
@@ -645,190 +484,6 @@ def _account_session(session_id, db, *, allow_limited: bool = False) -> tuple[di
return session, user
[email protected]("/auth/me")
-def auth_me(
- session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None,
- db=Depends(get_db),
-):
- session, account = _account_session(session_id, db, allow_limited=True)
- # Role and status come from the database so admin changes apply without a new login.
- return {"user": _user_payload(account, setup_required=session["stage"] != STAGE_FULL, two_factor_enabled=account.totp_enabled)}
-
-
[email protected]("/auth/logout")
-def auth_logout(
- response: Response,
- session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None,
-):
- if not session_id:
- raise HTTPException(status_code=400, detail="No session id supplied.")
- delete_session(redis_client, session_id)
- response.delete_cookie(key=SESSION_COOKIE_NAME, path="/")
- return {"status": "ok"}
-
-
[email protected]("/auth/2fa/status")
-def two_factor_status(session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- session, user = _account_session(session_id, db, allow_limited=True)
- return {
- "enabled": user.totp_enabled, "available": secrets_box.available(),
- "required": two_factor_required_for(db, user.role),
- "recovery_codes_left": recovery_codes_left(db, user) if user.totp_enabled else 0,
- "setup_required": session["stage"] != STAGE_FULL,
- }
-
-
[email protected]("/auth/2fa/setup")
-def two_factor_setup(payload: SetupRequest | None = None, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- session, user = _account_session(session_id, db, allow_limited=True)
- if not secrets_box.available():
- raise HTTPException(status_code=503, detail="Two-factor needs SECRETS_KEY to be configured on the server. See docs/accounts.md (Two-factor sign-in).")
- if user.totp_enabled:
- raise HTTPException(status_code=409, detail="Two-factor is already turned on. Turn it off first to set it up again.")
- if session.get("stage") != STAGE_ENROLLMENT:
- # Turning two-factor on from a normal session needs the password again. Otherwise a stolen session could
- # enrol its own authenticator, which signs out the real owner and locks them out.
- _confirm_password(db, user, payload.password if payload else None)
- enforce_limit(redis_client, scope="2fa-setup", subject=user.id, limit=10, window_seconds=3600)
- secret = totp.new_secret()
- # Stored encrypted and inactive until a code from the app has been confirmed.
- user.totp_secret_enc, user.totp_last_step = secrets_box.encrypt(secret), None
- db.commit()
- return {"secret": secret, "otpauth_uri": totp.otpauth_uri(secret, user.email)}
-
-
[email protected]("/auth/2fa/enable")
-def two_factor_enable(payload: CodeRequest, request: Request, response: Response, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- session, user = _account_session(session_id, db, allow_limited=True)
- if user.totp_enabled:
- raise HTTPException(status_code=409, detail="Two-factor is already turned on.")
- if not user.totp_secret_enc:
- raise HTTPException(status_code=400, detail="Start the setup first.")
- limit_key = enforce_limit(redis_client, scope="2fa-user", subject=user.id, limit=TWO_FACTOR_ATTEMPTS, window_seconds=TWO_FACTOR_WINDOW_SECONDS)
- try:
- step = totp.verify(secrets_box.decrypt(user.totp_secret_enc), payload.code)
- except secrets_box.SecretsUnavailable as exc:
- raise HTTPException(status_code=503, detail="Two-factor can't be set up on this server right now (a SECRETS_KEY problem).") from exc
- if step is None:
- raise HTTPException(status_code=400, detail="That code is not valid. Check the clock on your phone and try again.")
- reset_limits(redis_client, limit_key)
- user.totp_enabled, user.totp_last_step = True, step
- codes = issue_recovery_codes(db, user)
- db.commit()
- record_audit_log(db, user_id=user.id, level="INFO", message="Two-factor was turned on", source="auth")
- # A fresh session ID: this is the moment an enrollment session becomes a full one, and other sessions end.
- new_session_id, new_public_id = create_session(redis_client, user, stage=STAGE_FULL, ip=_client_ip(request), user_agent=request.headers.get("user-agent"))
- delete_session(redis_client, session_id)
- revoke_other_sessions(redis_client, user.id, new_public_id)
- _set_session_cookie(response, new_session_id)
- return {"recovery_codes": codes, "setup_required": False}
-
-
-def _confirm_password(db, user: User, password: str | None) -> None:
- """Ask for the current password again before a sensitive change. Every try counts toward the two-factor lockout,
- the right password included, so a locked-out session can't keep guessing until it is right."""
- limit_key = enforce_limit(redis_client, scope="2fa-user", subject=user.id, limit=TWO_FACTOR_ATTEMPTS, window_seconds=TWO_FACTOR_WINDOW_SECONDS)
- if not password or not verify_password(user, password):
- record_audit_log(db, user_id=user.id, level="WARNING", message="A wrong or missing password was given while setting up two-factor", source="auth")
- raise HTTPException(status_code=401, detail="Enter your current password to set up two-factor.")
- reset_limits(redis_client, limit_key)
-
-
-def _reauthenticate(db, user: User, password: str, code: str) -> None:
- """Password plus a second-factor code, for changes to the two-factor setup. One generic error for either being wrong."""
- wrong = HTTPException(status_code=401, detail="The password or the code is not correct.")
- if not verify_password(user, password):
- enforce_limit(redis_client, scope="2fa-user", subject=user.id, limit=TWO_FACTOR_ATTEMPTS, window_seconds=TWO_FACTOR_WINDOW_SECONDS)
- record_audit_log(db, user_id=user.id, level="WARNING", message="A wrong password was entered while changing two-factor", source="auth")
- raise wrong
- try:
- _second_factor_or_error(db, user, code)
- except HTTPException as exc:
- if exc.status_code == 401:
- raise wrong from exc
- raise
-
-
[email protected]("/auth/2fa/disable")
-def two_factor_disable(payload: ReauthRequest, request: Request, response: Response, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- session, user = _account_session(session_id, db)
- if not user.totp_enabled:
- raise HTTPException(status_code=409, detail="Two-factor is not turned on.")
- if two_factor_required_for(db, user.role):
- raise HTTPException(status_code=403, detail="Two-factor is required for administrators on this server.")
- _reauthenticate(db, user, payload.password, payload.code)
- user.totp_enabled, user.totp_secret_enc, user.totp_last_step = False, None, None
- db.query(RecoveryCode).filter(RecoveryCode.user_id == user.id).delete(synchronize_session=False)
- db.commit()
- # A fresh session ID for this one too, and every other session ends.
- new_session_id, new_public_id = create_session(redis_client, user, stage=STAGE_FULL, ip=_client_ip(request), user_agent=request.headers.get("user-agent"))
- delete_session(redis_client, session_id)
- revoked = revoke_other_sessions(redis_client, user.id, new_public_id)
- _set_session_cookie(response, new_session_id)
- record_audit_log(db, user_id=user.id, level="WARNING", message=f"Two-factor was turned off ({revoked} other sessions signed out)", source="auth")
- return {"status": "ok"}
-
-
[email protected]("/auth/2fa/recovery-codes")
-def two_factor_new_recovery_codes(payload: ReauthRequest, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- _session, user = _account_session(session_id, db)
- if not user.totp_enabled:
- raise HTTPException(status_code=409, detail="Two-factor is not turned on.")
- _reauthenticate(db, user, payload.password, payload.code)
- codes = issue_recovery_codes(db, user)
- db.commit()
- record_audit_log(db, user_id=user.id, level="INFO", message="Two-factor recovery codes were regenerated", source="auth")
- return {"recovery_codes": codes}
-
-
[email protected]("/auth/password")
-def change_password(payload: PasswordChangeRequest, request: Request, response: Response, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- session, user = _account_session(session_id, db)
- enforce_limit(redis_client, scope="pw-change", subject=user.id, limit=5, window_seconds=600)
- if not verify_password(user, payload.current_password):
- record_audit_log(db, user_id=user.id, level="WARNING", message="A wrong current password was entered while changing the password", source="auth")
- raise HTTPException(status_code=400, detail="The current password is not correct.")
- try:
- validate_password(payload.new_password)
- except ValueError as exc:
- raise HTTPException(status_code=400, detail=str(exc)) from exc
- if payload.new_password == payload.current_password:
- raise HTTPException(status_code=400, detail="The new password must be different from the current one.")
- user.password_hash, user.password_changed_at = hash_password(payload.new_password), datetime.now(timezone.utc)
- db.commit()
- # A fresh session ID for this browser, and every other session ends: whoever had the old password is out.
- new_session_id, new_public_id = create_session(redis_client, user, stage=STAGE_FULL, ip=_client_ip(request), user_agent=request.headers.get("user-agent"))
- delete_session(redis_client, session_id)
- revoked = revoke_other_sessions(redis_client, user.id, new_public_id)
- _set_session_cookie(response, new_session_id)
- record_audit_log(db, user_id=user.id, level="INFO", message=f"Password was changed ({revoked} other sessions signed out)", source="auth")
- return {"status": "ok", "other_sessions_signed_out": revoked}
-
-
[email protected]("/auth/sessions")
-def auth_sessions(session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- session, user = _account_session(session_id, db)
- return {"sessions": list_user_sessions(redis_client, user.id, session["public_id"])}
-
-
[email protected]("/auth/sessions/revoke-others")
-def auth_revoke_other_sessions(session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- session, user = _account_session(session_id, db)
- revoked = revoke_other_sessions(redis_client, user.id, session["public_id"])
- record_audit_log(db, user_id=user.id, level="INFO", message=f"Signed out {revoked} other sessions", source="auth")
- return {"signed_out": revoked}
-
-
[email protected]("/auth/sessions/{public_id}")
-def auth_revoke_session(public_id: str, response: Response, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
- session, user = _account_session(session_id, db)
- if not revoke_user_session(redis_client, user.id, public_id):
- raise HTTPException(status_code=404, detail="Session not found.")
- if public_id == session["public_id"]:
- response.delete_cookie(key=SESSION_COOKIE_NAME, path="/")
- return {"status": "ok"}
-
-
_TOKEN_WRITE_PATH = re.compile(r"/incidents/\d{1,10}/(acknowledge|resolve|mute|unmute)")
_TOKEN_FORBIDDEN = ("/admin", "/auth", "/account", "/agent", "/conversations", "/logs")
@@ -2730,10 +2385,11 @@ def root():
# Routes split out of this file; imported last so they can reference this module's shared helpers (see routes/).
-from .routes import account as account_routes, admin as admin_routes, availability as availability_routes, chat as chat_routes, incidents as incidents_routes, statistics as statistics_routes # noqa: E402
+from .routes import account as account_routes, admin as admin_routes, auth as auth_routes, availability as availability_routes, chat as chat_routes, incidents as incidents_routes, statistics as statistics_routes # noqa: E402
app.include_router(availability_routes.router)
app.include_router(incidents_routes.router)
app.include_router(account_routes.router)
app.include_router(statistics_routes.router)
app.include_router(chat_routes.router)
app.include_router(admin_routes.router)
+app.include_router(auth_routes.router)
diff --git a/src/backend/routes/auth.py b/src/backend/routes/auth.py
new file mode 100644
index 0000000..4475635
--- /dev/null
+++ b/src/backend/routes/auth.py
@@ -0,0 +1,339 @@
+"""Sign-in, registration, logout, two-factor setup/verification, password change and session management. The
+session/token/TOTP logic lives in auth.py, sessions.py and totp.py; the bootstrap-token, instance-name and
+`_account_session` helpers stay in main (used across the app). This module reaches those through `main.`."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Annotated
+
+from fastapi import APIRouter, Cookie, Depends, HTTPException, Query, Request, Response
+
+from .. import main, secrets_box, totp
+from ..config import SESSION_COOKIE_NAME
+from ..db import get_db
+from ..models import Invite, RecoveryCode, Server, User
+
+router = APIRouter()
+
+
[email protected]("/auth/config")
+def auth_config(db=Depends(get_db)):
+ """What the sign-in pages show before anyone has signed in. Everything here is public by design: keep it to
+ what a visitor may know (see SECURITY.md)."""
+ return {
+ "registration_enabled": main.registration_open(db), "bootstrap_required": db.query(User).count() == 0,
+ "instance_name": main.get_instance_name(db), "server_count": db.query(Server).count(), "version": main.APP_VERSION,
+ }
+
+def _valid_invite(db, token: str | None) -> Invite | None:
+ if not token or not 20 <= len(token) <= 200:
+ return None
+ return db.query(Invite).filter(Invite.token_hash == main._hash_secret(token.strip()), Invite.used_at.is_(None), Invite.expires_at > datetime.now(timezone.utc)).first()
+
[email protected]("/auth/invite")
+def auth_invite(token: Annotated[str, Query(min_length=20, max_length=200)], request: Request, db=Depends(get_db)):
+ """Whether an invitation link still works and who it is for, so the register page can say so."""
+ main.enforce_ip_limit(main.redis_client, scope="invite-check", ip_address=main._client_ip(request), limit=30, window_seconds=3600)
+ invite = _valid_invite(db, token)
+ if not invite:
+ raise HTTPException(status_code=404, detail="This invitation is no longer valid.")
+ return {"email": invite.email, "role": invite.role}
+
[email protected]("/auth/register")
+def auth_register(payload: main.RegisterRequest, request: Request, response: Response, db=Depends(get_db)):
+ invite = _valid_invite(db, payload.invite_token)
+ if payload.invite_token and not invite:
+ raise HTTPException(status_code=403, detail="This invitation is no longer valid. Ask for a new one.")
+ if invite and invite.email != str(payload.email).strip().lower():
+ raise HTTPException(status_code=403, detail="This invitation was made for a different email address.")
+ if not invite and not main.registration_open(db):
+ raise HTTPException(status_code=403, detail="Registration is disabled on this server.")
+ main.enforce_register_limit(
+ main.redis_client,
+ ip_address=request.client.host if request.client else "unknown",
+ limit=main.REGISTER_RATE_LIMIT,
+ window_seconds=main.REGISTER_RATE_WINDOW_SECONDS,
+ )
+ first_account = db.query(User).count() == 0
+ if first_account and not main._bootstrap_token_valid(db, payload.bootstrap_token):
+ raise HTTPException(status_code=403, detail="This install needs its setup token to create the first account. Find it in the backend log: docker compose logs backend | grep \"setup token\"")
+ try:
+ result = main.register_user(
+ db,
+ main.redis_client,
+ name=payload.name,
+ email=str(payload.email),
+ password=payload.password,
+ admin_requires_two_factor=main.two_factor_enforced(db),
+ everyone_requires_two_factor=main.two_factor_required_for(db, "user"),
+ role=invite.role if invite and not first_account else None,
+ ip=main._client_ip(request),
+ user_agent=request.headers.get("user-agent"),
+ )
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+ if invite:
+ invite.used_at = datetime.now(timezone.utc)
+ db.commit()
+ if first_account:
+ main.ensure_bootstrap_token(db) # an account exists now: this removes the token
+ _set_session_cookie(response, result.pop("session_id"))
+ return result
+
+def _set_session_cookie(response: Response, session_id: str, lifetime: int = main.SESSION_TTL_SECONDS) -> None:
+ response.set_cookie(
+ key=SESSION_COOKIE_NAME,
+ value=session_id,
+ max_age=lifetime,
+ httponly=True,
+ secure=main.SESSION_COOKIE_SECURE,
+ samesite="lax",
+ path="/",
+ )
+
+def _user_payload(user: User, **extra) -> dict:
+ return {"id": user.id, "name": user.name, "email": user.email, "role": user.role, "is_active": user.is_active, **extra}
+
+def _complete_login(db, request: Request, response: Response, user: User, how: str = "", remember: bool = False) -> dict:
+ """Open the session after every required step has passed.
+
+ An administrator without two-factor, while it is required, gets an enrollment session: it can reach
+ the two-factor setup and nothing else until setup is done.
+ """
+ stage = main.STAGE_ENROLLMENT if not user.totp_enabled and main.two_factor_required_for(db, user.role) else main.STAGE_FULL
+ user.last_seen_at = datetime.now(timezone.utc)
+ session_id, _public_id = main.create_session(main.redis_client, user, stage=stage, ip=main._client_ip(request), user_agent=request.headers.get("user-agent"), remember=remember)
+ # The cookie lasts exactly as long as the session behind it.
+ _set_session_cookie(response, session_id, main.session_lifetime(stage, remember))
+ main.record_audit_log(db, user_id=user.id, level="INFO", message=f"User signed in{how}{' (staying signed in for 30 days)' if remember and stage == main.STAGE_FULL else ''}", source="auth")
+ return {"user": _user_payload(user), "setup_required": stage == main.STAGE_ENROLLMENT}
+
[email protected]("/auth/login")
+def auth_login(payload: main.LoginRequest, request: Request, response: Response, db=Depends(get_db)):
+ limit_keys = main.enforce_login_limit(
+ main.redis_client,
+ ip_address=request.client.host if request.client else "unknown",
+ email=str(payload.email),
+ limit=main.LOGIN_RATE_LIMIT,
+ window_seconds=main.LOGIN_RATE_WINDOW_SECONDS,
+ )
+ try:
+ user = main.verify_credentials(db, email=str(payload.email), password=payload.password)
+ except ValueError as exc:
+ raise HTTPException(status_code=401, detail=str(exc)) from exc
+
+ # This email's counter is cleared. The address's counter only gets this one successful attempt back: clearing it
+ # would let anyone with an account of their own reset the limit between guesses at someone else's password.
+ main.reset_limits(main.redis_client, limit_keys[1])
+ main.refund_attempt(main.redis_client, limit_keys[0])
+ if user.totp_enabled:
+ # No session exists until the second step passes; this token only carries the login between the steps.
+ return {"status": "two_factor_required", "pending_token": main.create_pending_two_factor(main.redis_client, user.id, payload.remember)}
+ return _complete_login(db, request, response, user, remember=payload.remember)
+
+def _second_factor_or_error(db, user: User, code: str) -> str:
+ """Verify a code for the user, with the shared brute-force limit. Raises 401 (or 429/503); returns "totp" or "recovery"."""
+ limit_key = main.enforce_limit(main.redis_client, scope="2fa-user", subject=user.id, limit=main.TWO_FACTOR_ATTEMPTS, window_seconds=main.TWO_FACTOR_WINDOW_SECONDS)
+ try:
+ method = main.verify_second_factor(db, user, code)
+ except secrets_box.SecretsUnavailable as exc:
+ raise HTTPException(status_code=503, detail="Two-factor codes can't be checked on this server right now (a SECRETS_KEY problem). A recovery code still works.") from exc
+ if method is None:
+ main.record_audit_log(db, user_id=user.id, level="WARNING", message="A wrong two-factor code was entered", source="auth")
+ raise HTTPException(status_code=401, detail="Invalid code.")
+ main.reset_limits(main.redis_client, limit_key)
+ return method
+
[email protected]("/auth/login/2fa")
+def auth_login_two_factor(payload: main.TwoFactorLoginRequest, request: Request, response: Response, db=Depends(get_db)):
+ main.enforce_ip_limit(main.redis_client, scope="2fa-ip", ip_address=main._client_ip(request), limit=20, window_seconds=main.TWO_FACTOR_WINDOW_SECONDS)
+ expired = HTTPException(status_code=401, detail="Sign-in expired. Please sign in again.")
+ user_id = main.read_pending_two_factor(main.redis_client, payload.pending_token)
+ if user_id is None:
+ raise expired
+ if not main.count_pending_attempt(main.redis_client, payload.pending_token):
+ raise HTTPException(status_code=401, detail="Too many wrong codes. Please sign in again.")
+ user = db.get(User, user_id)
+ if not user or not user.is_active or not user.totp_enabled:
+ raise expired
+ method = _second_factor_or_error(db, user, payload.code)
+ db.commit() # the code that was just accepted is now spent
+ remember = main.pending_two_factor_remember(main.redis_client, payload.pending_token)
+ main.delete_pending_two_factor(main.redis_client, payload.pending_token)
+ if method == "recovery":
+ main.record_audit_log(db, user_id=user.id, level="WARNING", message="A two-factor recovery code was used to sign in", source="auth")
+ result = _complete_login(db, request, response, user, " with two-factor", remember=remember)
+ result["recovery_codes_left"] = main.recovery_codes_left(db, user)
+ return result
+
[email protected]("/auth/me")
+def auth_me(
+ session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None,
+ db=Depends(get_db),
+):
+ session, account = main._account_session(session_id, db, allow_limited=True)
+ # Role and status come from the database so admin changes apply without a new login.
+ return {"user": _user_payload(account, setup_required=session["stage"] != main.STAGE_FULL, two_factor_enabled=account.totp_enabled)}
+
[email protected]("/auth/logout")
+def auth_logout(
+ response: Response,
+ session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None,
+):
+ if not session_id:
+ raise HTTPException(status_code=400, detail="No session id supplied.")
+ main.delete_session(main.redis_client, session_id)
+ response.delete_cookie(key=SESSION_COOKIE_NAME, path="/")
+ return {"status": "ok"}
+
[email protected]("/auth/2fa/status")
+def two_factor_status(session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ session, user = main._account_session(session_id, db, allow_limited=True)
+ return {
+ "enabled": user.totp_enabled, "available": secrets_box.available(),
+ "required": main.two_factor_required_for(db, user.role),
+ "recovery_codes_left": main.recovery_codes_left(db, user) if user.totp_enabled else 0,
+ "setup_required": session["stage"] != main.STAGE_FULL,
+ }
+
[email protected]("/auth/2fa/setup")
+def two_factor_setup(payload: main.SetupRequest | None = None, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ session, user = main._account_session(session_id, db, allow_limited=True)
+ if not secrets_box.available():
+ raise HTTPException(status_code=503, detail="Two-factor needs SECRETS_KEY to be configured on the server. See docs/accounts.md (Two-factor sign-in).")
+ if user.totp_enabled:
+ raise HTTPException(status_code=409, detail="Two-factor is already turned on. Turn it off first to set it up again.")
+ if session.get("stage") != main.STAGE_ENROLLMENT:
+ # Turning two-factor on from a normal session needs the password again. Otherwise a stolen session could
+ # enrol its own authenticator, which signs out the real owner and locks them out.
+ _confirm_password(db, user, payload.password if payload else None)
+ main.enforce_limit(main.redis_client, scope="2fa-setup", subject=user.id, limit=10, window_seconds=3600)
+ secret = totp.new_secret()
+ # Stored encrypted and inactive until a code from the app has been confirmed.
+ user.totp_secret_enc, user.totp_last_step = secrets_box.encrypt(secret), None
+ db.commit()
+ return {"secret": secret, "otpauth_uri": totp.otpauth_uri(secret, user.email)}
+
[email protected]("/auth/2fa/enable")
+def two_factor_enable(payload: main.CodeRequest, request: Request, response: Response, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ session, user = main._account_session(session_id, db, allow_limited=True)
+ if user.totp_enabled:
+ raise HTTPException(status_code=409, detail="Two-factor is already turned on.")
+ if not user.totp_secret_enc:
+ raise HTTPException(status_code=400, detail="Start the setup first.")
+ limit_key = main.enforce_limit(main.redis_client, scope="2fa-user", subject=user.id, limit=main.TWO_FACTOR_ATTEMPTS, window_seconds=main.TWO_FACTOR_WINDOW_SECONDS)
+ try:
+ step = totp.verify(secrets_box.decrypt(user.totp_secret_enc), payload.code)
+ except secrets_box.SecretsUnavailable as exc:
+ raise HTTPException(status_code=503, detail="Two-factor can't be set up on this server right now (a SECRETS_KEY problem).") from exc
+ if step is None:
+ raise HTTPException(status_code=400, detail="That code is not valid. Check the clock on your phone and try again.")
+ main.reset_limits(main.redis_client, limit_key)
+ user.totp_enabled, user.totp_last_step = True, step
+ codes = main.issue_recovery_codes(db, user)
+ db.commit()
+ main.record_audit_log(db, user_id=user.id, level="INFO", message="Two-factor was turned on", source="auth")
+ # A fresh session ID: this is the moment an enrollment session becomes a full one, and other sessions end.
+ new_session_id, new_public_id = main.create_session(main.redis_client, user, stage=main.STAGE_FULL, ip=main._client_ip(request), user_agent=request.headers.get("user-agent"))
+ main.delete_session(main.redis_client, session_id)
+ main.revoke_other_sessions(main.redis_client, user.id, new_public_id)
+ _set_session_cookie(response, new_session_id)
+ return {"recovery_codes": codes, "setup_required": False}
+
+def _confirm_password(db, user: User, password: str | None) -> None:
+ """Ask for the current password again before a sensitive change. Every try counts toward the two-factor lockout,
+ the right password included, so a locked-out session can't keep guessing until it is right."""
+ limit_key = main.enforce_limit(main.redis_client, scope="2fa-user", subject=user.id, limit=main.TWO_FACTOR_ATTEMPTS, window_seconds=main.TWO_FACTOR_WINDOW_SECONDS)
+ if not password or not main.verify_password(user, password):
+ main.record_audit_log(db, user_id=user.id, level="WARNING", message="A wrong or missing password was given while setting up two-factor", source="auth")
+ raise HTTPException(status_code=401, detail="Enter your current password to set up two-factor.")
+ main.reset_limits(main.redis_client, limit_key)
+
+def _reauthenticate(db, user: User, password: str, code: str) -> None:
+ """Password plus a second-factor code, for changes to the two-factor setup. One generic error for either being wrong."""
+ wrong = HTTPException(status_code=401, detail="The password or the code is not correct.")
+ if not main.verify_password(user, password):
+ main.enforce_limit(main.redis_client, scope="2fa-user", subject=user.id, limit=main.TWO_FACTOR_ATTEMPTS, window_seconds=main.TWO_FACTOR_WINDOW_SECONDS)
+ main.record_audit_log(db, user_id=user.id, level="WARNING", message="A wrong password was entered while changing two-factor", source="auth")
+ raise wrong
+ try:
+ _second_factor_or_error(db, user, code)
+ except HTTPException as exc:
+ if exc.status_code == 401:
+ raise wrong from exc
+ raise
+
[email protected]("/auth/2fa/disable")
+def two_factor_disable(payload: main.ReauthRequest, request: Request, response: Response, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ session, user = main._account_session(session_id, db)
+ if not user.totp_enabled:
+ raise HTTPException(status_code=409, detail="Two-factor is not turned on.")
+ if main.two_factor_required_for(db, user.role):
+ raise HTTPException(status_code=403, detail="Two-factor is required for administrators on this server.")
+ _reauthenticate(db, user, payload.password, payload.code)
+ user.totp_enabled, user.totp_secret_enc, user.totp_last_step = False, None, None
+ db.query(RecoveryCode).filter(RecoveryCode.user_id == user.id).delete(synchronize_session=False)
+ db.commit()
+ # A fresh session ID for this one too, and every other session ends.
+ new_session_id, new_public_id = main.create_session(main.redis_client, user, stage=main.STAGE_FULL, ip=main._client_ip(request), user_agent=request.headers.get("user-agent"))
+ main.delete_session(main.redis_client, session_id)
+ revoked = main.revoke_other_sessions(main.redis_client, user.id, new_public_id)
+ _set_session_cookie(response, new_session_id)
+ main.record_audit_log(db, user_id=user.id, level="WARNING", message=f"Two-factor was turned off ({revoked} other sessions signed out)", source="auth")
+ return {"status": "ok"}
+
[email protected]("/auth/2fa/recovery-codes")
+def two_factor_new_recovery_codes(payload: main.ReauthRequest, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ _session, user = main._account_session(session_id, db)
+ if not user.totp_enabled:
+ raise HTTPException(status_code=409, detail="Two-factor is not turned on.")
+ _reauthenticate(db, user, payload.password, payload.code)
+ codes = main.issue_recovery_codes(db, user)
+ db.commit()
+ main.record_audit_log(db, user_id=user.id, level="INFO", message="Two-factor recovery codes were regenerated", source="auth")
+ return {"recovery_codes": codes}
+
[email protected]("/auth/password")
+def change_password(payload: main.PasswordChangeRequest, request: Request, response: Response, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ session, user = main._account_session(session_id, db)
+ main.enforce_limit(main.redis_client, scope="pw-change", subject=user.id, limit=5, window_seconds=600)
+ if not main.verify_password(user, payload.current_password):
+ main.record_audit_log(db, user_id=user.id, level="WARNING", message="A wrong current password was entered while changing the password", source="auth")
+ raise HTTPException(status_code=400, detail="The current password is not correct.")
+ try:
+ main.validate_password(payload.new_password)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc)) from exc
+ if payload.new_password == payload.current_password:
+ raise HTTPException(status_code=400, detail="The new password must be different from the current one.")
+ user.password_hash, user.password_changed_at = main.hash_password(payload.new_password), datetime.now(timezone.utc)
+ db.commit()
+ # A fresh session ID for this browser, and every other session ends: whoever had the old password is out.
+ new_session_id, new_public_id = main.create_session(main.redis_client, user, stage=main.STAGE_FULL, ip=main._client_ip(request), user_agent=request.headers.get("user-agent"))
+ main.delete_session(main.redis_client, session_id)
+ revoked = main.revoke_other_sessions(main.redis_client, user.id, new_public_id)
+ _set_session_cookie(response, new_session_id)
+ main.record_audit_log(db, user_id=user.id, level="INFO", message=f"Password was changed ({revoked} other sessions signed out)", source="auth")
+ return {"status": "ok", "other_sessions_signed_out": revoked}
+
[email protected]("/auth/sessions")
+def auth_sessions(session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ session, user = main._account_session(session_id, db)
+ return {"sessions": main.list_user_sessions(main.redis_client, user.id, session["public_id"])}
+
[email protected]("/auth/sessions/revoke-others")
+def auth_revoke_other_sessions(session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ session, user = main._account_session(session_id, db)
+ revoked = main.revoke_other_sessions(main.redis_client, user.id, session["public_id"])
+ main.record_audit_log(db, user_id=user.id, level="INFO", message=f"Signed out {revoked} other sessions", source="auth")
+ return {"signed_out": revoked}
+
[email protected]("/auth/sessions/{public_id}")
+def auth_revoke_session(public_id: str, response: Response, session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None, db=Depends(get_db)):
+ session, user = main._account_session(session_id, db)
+ if not main.revoke_user_session(main.redis_client, user.id, public_id):
+ raise HTTPException(status_code=404, detail="Session not found.")
+ if public_id == session["public_id"]:
+ response.delete_cookie(key=SESSION_COOKIE_NAME, path="/")
+ return {"status": "ok"}
diff --git a/tests/accounts/test_auth_backend.py b/tests/accounts/test_auth_backend.py
index 0049bea..b98bbd4 100644
--- a/tests/accounts/test_auth_backend.py
+++ b/tests/accounts/test_auth_backend.py
@@ -99,14 +99,14 @@ def test_registration_closed_still_allows_first_account(monkeypatch):
monkeypatch.setattr(main, "ALLOW_REGISTRATION", False)
public = {"server_count": 0, "version": main.APP_VERSION}
- assert main.auth_config(db=session) == {"registration_enabled": True, "bootstrap_required": True, "instance_name": None, **public}
+ assert auth_routes.auth_config(db=session) == {"registration_enabled": True, "bootstrap_required": True, "instance_name": None, **public}
session.add(User(name="Owner", email="[email protected]", password_hash="x"))
session.commit()
# The first account is not an admin here, so there is nobody to name the install after.
- assert main.auth_config(db=session) == {"registration_enabled": False, "bootstrap_required": False, "instance_name": None, **public}
+ assert auth_routes.auth_config(db=session) == {"registration_enabled": False, "bootstrap_required": False, "instance_name": None, **public}
with pytest.raises(HTTPException) as exc:
- main.auth_register(main.RegisterRequest(name="Stranger", email="[email protected]", password="correct-horse-battery-staple"), request=None, response=None, db=session)
+ auth_routes.auth_register(main.RegisterRequest(name="Stranger", email="[email protected]", password="correct-horse-battery-staple"), request=None, response=None, db=session)
assert exc.value.status_code == 403
@@ -146,7 +146,7 @@ def _register(main, session, token, email="[email protected]"):
from types import SimpleNamespace
from fastapi import Response
request = SimpleNamespace(client=SimpleNamespace(host="1.2.3.4"), headers={})
- return main.auth_register(main.RegisterRequest(name="Owner", email=email, password="correct-horse-battery-staple", bootstrap_token=token), request=request, response=Response(), db=session)
+ return auth_routes.auth_register(main.RegisterRequest(name="Owner", email=email, password="correct-horse-battery-staple", bootstrap_token=token), request=request, response=Response(), db=session)
def test_fresh_install_generates_a_token_and_stores_only_its_hash(monkeypatch):
@@ -213,6 +213,7 @@ def test_existing_installs_need_no_token_and_leftovers_are_cleaned_up(monkeypatc
# --- password policy ------------------------------------------------------------------------
+from src.backend.routes import auth as auth_routes
from src.backend import auth as auth_module