backend.auth

Authentication and authorisation utilities.

Provides JWT-based access and refresh token handling, password hashing (bcrypt with legacy SHA-1 fallback), user lookup and all FastAPI dependency helpers required by the API routers.

Constants:

ACCESS_TOKEN_EXPIRE_MINUTES (int): Lifetime of an access token in minutes (15). REFRESH_TOKEN_EXPIRE_DAYS (int): Lifetime of a refresh token in days (30). RESET_PASSWORD_TOKEN_EXPIRE_MINUTES (int): Lifetime of a password-reset token (15). ALGORITHM (str): JWT signing algorithm (HS256).

backend.auth.get_token_from_cookie_or_header(request)

Extract a Bearer token from the Authorization header or the access_token cookie.

The header is checked first; the cookie serves as a backwards- compatible fallback.

Parameter:

request (Request) – The incoming FastAPI request object.

Rückgabe:

The raw JWT string, or None if no token was found.

Rückgabetyp:

str | None

backend.auth.hash_pw(plain_pw)

Hash a plain-text password using bcrypt.

Parameter:

plain_pw (str) – The plain-text password to hash.

Rückgabe:

The bcrypt hash string.

Rückgabetyp:

str

backend.auth.verify_password(plain, hashed)

Verify a plain-text password against a stored hash.

Supports bcrypt hashes ($2b$, $2a$, $2y$ prefix) and, until LEGACY_HASH_DEADLINE, LDAP-style SHA-1 hashes ({SHA} prefix).

Parameter:

• plain (str) – The plain-text password provided by the user.

• hashed (str) – The stored password hash.

Rückgabe:

True if the password matches, False otherwise.

Rückgabetyp:

bool

backend.auth.authenticate_user(db, username, password)

Look up a user by username and verify their password.

If the stored hash uses a legacy format it is automatically upgraded to bcrypt on successful login.

Parameter:

• db (Session) – Active database session.

• username (str) – The username to look up.

• password (str) – The plain-text password to verify.

Rückgabe:

The authenticated user, or None if the credentials are invalid.

Rückgabetyp:

models.User | None

backend.auth.create_access_token(data)

Create a signed JWT access token.

The token expires after ACCESS_TOKEN_EXPIRE_MINUTES minutes.

Parameter:

data (dict) – Payload to encode (must contain at least sub and role).

Rückgabe:

The encoded JWT string.

Rückgabetyp:

str

backend.auth.create_refresh_token(user_id, db)

Create a refresh token, persist its hash in the database and return the raw token string.

Parameter:

• user_id (int) – Primary key of the user the token belongs to.

• db (Session) – Active database session.

Rückgabe:

The raw (unhashed) refresh token.

Rückgabetyp:

str

backend.auth.verify_refresh_token(token, db)

Validate a refresh token and return the associated user.

Parameter:

• token (str) – The raw refresh token string.

• db (Session) – Active database session.

Rückgabe:

The user associated with the token.

Rückgabetyp:

models.User

Verursacht:

HTTPException 401 – If the token is invalid, revoked or expired.

backend.auth.revoke_refresh_token(token, db)

Mark a refresh token as revoked in the database.

Parameter:

• token (str) – The raw refresh token string.

• db (Session) – Active database session.

backend.auth.blacklist_access_token(token, db)

Add an access token to the blacklist so it cannot be reused after logout.

Only tokens that have not yet expired are stored; already-expired tokens are silently ignored.

Parameter:

• token (str) – The raw JWT access token string.

• db (Session) – Active database session.

backend.auth.create_password_reset_token(user_name)

Create a short-lived JWT token scoped to password reset.

Parameter:

user_name (str) – The username for which the reset is requested.

Rückgabe:

The encoded JWT string with scope="password_reset_token".

Rückgabetyp:

str

backend.auth.get_db()

FastAPI dependency that yields a database session.

Yields:

Session – An active SQLAlchemy database session.

backend.auth.get_current_user(request, db=Depends(dependency=<function get_db>, use_cache=True, scope=None))

FastAPI dependency that validates the access token and returns the current user’s payload.

Checks both the token blacklist and the JWT signature/expiry.

Parameter:

• request (Request) – The incoming request (token read from header or cookie).

• db (Session) – Active database session.

Rückgabe:

A dictionary with keys user_name and user_group.

Rückgabetyp:

dict

Verursacht:

HTTPException 401 – If the token is missing, invalid or blacklisted.

async backend.auth.get_current_user_dep(request, db=Depends(dependency=<function get_db>, use_cache=True, scope=None))

Async wrapper for router-level dependencies

Parameter:

• request (Request) – The incoming request.

• db (Session) – Active database session.

Rückgabe:

A dictionary with keys user_name and user_group.

Rückgabetyp:

dict

backend.auth.check_user_role(token, expected_role)

Verify that a JWT token carries a specific role.

Parameter:

• token (str) – The raw JWT string.

• expected_role (str) – The role to check against (e.g. "admin").

Rückgabe:

True if the token’s role claim matches expected_role.

Rückgabetyp:

bool

Verursacht:

HTTPException 401 – If the token cannot be decoded.

backend.auth.verify_password_reset_token(token=Depends(dependency=<fastapi.security.oauth2.OAuth2PasswordBearer object>, use_cache=True, scope=None), db=Depends(dependency=<function get_db>, use_cache=True, scope=None))

Validate a password-reset token and ensure it has not been used before.

Parameter:

• token (str) – The raw password-reset JWT.

• db (Session) – Active database session.

Rückgabe:

A tuple of (username, raw_token).

Rückgabetyp:

tuple[str, str]

Verursacht:

HTTPException 400 – If the token is invalid, expired, has the wrong scope or has already been used.