service-finder/docs/v201/05_AUTH_AND_IDENTITY_SPEC.md

05. AUTH & IDENTITY SPECIFICATION

Current State (E2E Tested and Verified)

1. Lite Registration Flow

• Endpoint: POST /auth/register
• Logic: Creates a User and Person record in the identity schema.
• Initial State: Both User.is_active and Person.is_active are explicitly set to False. The password must meet dynamic complexity requirements defined in system.system_parameters (auth_password_strict, auth_min_password_length).

2. Email Verification Flow

• Endpoint: POST /auth/verify-email
• Logic: Validates the UUID token from identity.verification_tokens.
• Action: Marks the token as used, and activates both the User and Person records (is_active = True).

3. Login & JWT / Cookie Hybrid System

• Endpoint: POST /auth/login
• Logic: Implements the OAuth2 Password Flow. If remember_me=True is provided (via form data), it generates tokens with extended lifespans based on SSoT config (auth_remember_me_days).
• Token Delivery:
  • access_token: Returned in JSON body (Bearer).
  • refresh_token: Returned as a secure HttpOnly cookie with SameSite=lax and dynamic Max-Age.

4. Soft Delete / Anonymization

• Method: AuthService.soft_delete_user
• Logic: The user is NOT physically deleted. The email is anonymized (e.g., deleted_[ID]_[DATE]_[original_email]).
• State: is_active = False and is_deleted = True. Also performs cascading logic handling audit_logs and verification_tokens to respect constraints.