semantic clean up

backend/src/services/auth_service.py

@@ -1,13 +1,16 @@
 # [DEF:backend.src.services.auth_service:Module]
 #
-# @SEMANTICS: auth, service, business-logic, login, jwt
-# @PURPOSE:   Orchestrates authentication business logic.
-# @LAYER:     Service
-# @RELATION:  USES -> backend.src.core.auth.repository.AuthRepository
-# @RELATION:  USES -> backend.src.core.auth.security
-# @RELATION:  USES -> backend.src.core.auth.jwt
+# @TIER:      CRITICAL
+# @SEMANTICS: auth, service, business-logic, login, jwt, adfs, jit-provisioning
+# @PURPOSE:   Orchestrates credential authentication and ADFS JIT user provisioning.
+# @LAYER:     Domain
+# @RELATION:  [DEPENDS_ON] ->[backend.src.core.auth.repository.AuthRepository]
+# @RELATION:  [DEPENDS_ON] ->[backend.src.core.auth.security.verify_password]
+# @RELATION:  [DEPENDS_ON] ->[backend.src.core.auth.jwt.create_access_token]
+# @RELATION:  [DEPENDS_ON] ->[backend.src.models.auth.User]
+# @RELATION:  [DEPENDS_ON] ->[backend.src.models.auth.Role]
 #
-# @INVARIANT: Authentication must verify both credentials and account status.
+# @INVARIANT: Authentication succeeds only for active users with valid credentials; issued sessions encode subject and scopes from assigned roles.
 
 # [SECTION: IMPORTS]
 from typing import Dict, Any
@@ -23,20 +26,25 @@ from ..core.logger import belief_scope
 # @PURPOSE: Provides high-level authentication services.
 class AuthService:
     # [DEF:__init__:Function]
-    # @PURPOSE: Initializes the service with a database session.
-    # @PARAM:   db (Session) - SQLAlchemy session.
+    # @PURPOSE: Initializes the authentication service with repository access over an active DB session.
+    # @PRE: db is a valid SQLAlchemy Session instance bound to the auth persistence context.
+    # @POST: self.repo is initialized and ready for auth user/role CRUD operations.
+    # @SIDE_EFFECT: Allocates AuthRepository and binds it to the provided Session.
+    # @DATA_CONTRACT: Input(Session) -> Model(AuthRepository)
+    # @PARAM: db (Session) - SQLAlchemy session.
     def __init__(self, db: Session):
         self.repo = AuthRepository(db)
     # [/DEF:__init__:Function]
 
     # [DEF:authenticate_user:Function]
-    # @PURPOSE: Authenticates a user with username and password.
-    # @PRE:     username and password are provided.
-    # @POST:    Returns User object if authentication succeeds, else None.
-    # @SIDE_EFFECT: Updates last_login timestamp on success.
-    # @PARAM:   username (str) - The username.
-    # @PARAM:   password (str) - The plain password.
-    # @RETURN:  Optional[User] - The authenticated user or None.
+    # @PURPOSE: Validates credentials and account state for local username/password authentication.
+    # @PRE: username and password are non-empty credential inputs.
+    # @POST: Returns User only when user exists, is active, and password hash verification succeeds; otherwise returns None.
+    # @SIDE_EFFECT: Persists last_login update for successful authentications via repository.
+    # @DATA_CONTRACT: Input(str username, str password) -> Output(User | None)
+    # @PARAM: username (str) - The username.
+    # @PARAM: password (str) - The plain password.
+    # @RETURN: Optional[User] - The authenticated user or None.
     def authenticate_user(self, username: str, password: str):
         with belief_scope("AuthService.authenticate_user"):
             user = self.repo.get_user_by_username(username)
@@ -54,11 +62,13 @@ class AuthService:
     # [/DEF:authenticate_user:Function]
 
     # [DEF:create_session:Function]
-    # @PURPOSE: Creates a JWT session for an authenticated user.
-    # @PRE:     user is a valid User object.
-    # @POST:    Returns a dictionary with access_token and token_type.
-    # @PARAM:   user (User) - The authenticated user.
-    # @RETURN:  Dict[str, str] - Session data.
+    # @PURPOSE: Issues an access token payload for an already authenticated user.
+    # @PRE: user is a valid User entity containing username and iterable roles with role.name values.
+    # @POST: Returns session dict with non-empty access_token and token_type='bearer'.
+    # @SIDE_EFFECT: Generates signed JWT via auth JWT provider.
+    # @DATA_CONTRACT: Input(User) -> Output(Dict[str, str]{access_token, token_type})
+    # @PARAM: user (User) - The authenticated user.
+    # @RETURN: Dict[str, str] - Session data.
     def create_session(self, user) -> Dict[str, str]:
         with belief_scope("AuthService.create_session"):
             # Collect role names for scopes
@@ -77,11 +87,13 @@ class AuthService:
     # [/DEF:create_session:Function]
 
     # [DEF:provision_adfs_user:Function]
-    # @PURPOSE: Just-In-Time (JIT) provisioning for ADFS users based on group mappings.
-    # @PRE:     user_info contains 'upn' (username), 'email', and 'groups'.
-    # @POST:    User is created/updated and assigned roles based on groups.
-    # @PARAM:   user_info (Dict[str, Any]) - Claims from ADFS token.
-    # @RETURN:  User - The provisioned user.
+    # @PURPOSE: Performs ADFS Just-In-Time provisioning and role synchronization from AD group mappings.
+    # @PRE: user_info contains identity claims where at least one of 'upn' or 'email' is present; 'groups' may be absent.
+    # @POST: Returns persisted user entity with roles synchronized to mapped AD groups and refreshed state.
+    # @SIDE_EFFECT: May insert new User, mutate user.roles, commit transaction, and refresh ORM state.
+    # @DATA_CONTRACT: Input(Dict[str, Any]{upn|email, email, groups[]}) -> Output(User persisted)
+    # @PARAM: user_info (Dict[str, Any]) - Claims from ADFS token.
+    # @RETURN: User - The provisioned user.
     def provision_adfs_user(self, user_info: Dict[str, Any]) -> User:
         with belief_scope("AuthService.provision_adfs_user"):
             username = user_info.get("upn") or user_info.get("email")