service-finder/docs/auth_registration_audit.md

Authentication & Registration Module Audit

Audit Date: 2026-03-19
Gitea Issue: #98
Auditor: Rendszerauditőr

1. Overview

This audit examines the current state of the authentication and registration module within the Service Finder backend. The user reported that a three‑step registration logic (Lite, Complete KYC) was fully implemented and functional but was disconnected from the routers during a refactoring. The goal is to map the existing code, identify missing endpoints, and verify router connectivity.

2. Auth Service Analysis (backend/app/services/auth_service.py)

The AuthService class contains the core registration logic, split into two phases:

2.1 register_lite

• Purpose: First‑step registration with dynamic limits and Sentinel auditing.
• Input: UserLiteRegister schema (email, password, first/last name, region, language, timezone).
• Process:
  1. Fetches admin‑configurable parameters (auth_min_password_length, auth_default_role, auth_registration_hours).
  2. Creates a Person record (inactive).
  3. Creates a User record with hashed password, role, region, language, timezone.
  4. Generates a UUID verification token and stores it in VerificationToken.
  5. Sends a registration email with a verification link.
  6. Logs the event via security_service.log_event.
• Output: A new User with is_active=False.

2.2 complete_kyc

• Purpose: Second‑step full profile completion, organization creation, and gamification initialization.
• Input: UserKYCComplete schema (phone, birth details, address, identity docs, ICE contact, preferred currency).
• Process:
  1. Retrieves the user and their linked Person.
  2. Fetches dynamic settings (organization naming template, default currency, KYC bonus XP).
  3. Calls GeoService.get_or_create_full_address to create a precise address record.
  4. Enriches the Person with mother’s name, birth place, phone, address, identity docs.
  5. Creates an Organization (individual type) with a generated slug.
  6. Creates a Branch (main), OrganizationMember (OWNER), Wallet, and UserStats.
  7. Activates the user and sets a folder slug.
  8. Awards gamification points via GamificationService.award_points.
• Output: Fully activated user with organization, wallet, and infrastructure.

2.3 Supporting Methods

• authenticate: Validates email/password against the stored hash.
• verify_email: Marks a verification token as used (no endpoint exposed).
• initiate_password_reset: Creates a password‑reset token and sends an email.
• reset_password: Validates the token and updates the password.
• soft_delete_user: Soft‑deletes a user with audit logging.

3. Schemas (backend/app/schemas/auth.py)

3.1 UserLiteRegister (Step 1)

email: EmailStr
password: str (min_length=8)
first_name: str
last_name: str
region_code: Optional[str] = "HU"
lang: Optional[str] = "hu"
timezone: Optional[str] = "Europe/Budapest"

3.2 UserKYCComplete (Step 2)

• Personal details: phone_number, birth_place, birth_date, mothers_last_name, mothers_first_name
• Atomic address fields: address_zip, address_city, address_street_name, address_street_type, address_house_number, optional stairwell/floor/door/HRsz
• Identity documents: identity_docs: Dict[str, DocumentDetail] (e.g., ID_CARD, LICENSE)
• Emergency contact: ice_contact: ICEContact
• Preferences: preferred_language, preferred_currency

3.3 User Response/Update Schemas (backend/app/schemas/user.py)

• UserBase, UserResponse, UserUpdate – used for profile management.

4. Endpoints (backend/app/api/v1/endpoints/auth.py)

Currently three endpoints are implemented and routed:

Method	Path	Description
POST	/auth/register	Lite registration (creates user, sends verification email)
POST	/auth/login	OAuth2 password flow, returns JWT tokens
POST	/auth/complete‑kyc	Completes KYC, activates user, creates organization/wallet

Missing endpoints (service methods exist but no routes):

• GET/POST /auth/verify‑email – email verification
• POST /auth/forgot‑password – password‑reset initiation
• POST /auth/reset‑password – password reset with token
• GET /auth/me – already exists in users.py under /users/me

5. Router Inclusion (backend/app/api/v1/api.py)

The auth router is correctly included:

api_router.include_router(auth.router, prefix="/auth", tags=["Authentication"])

Thus the three existing endpoints are reachable under /auth.

6. Missing Pieces & Discrepancies

1. Three‑step registration: The audit found only two explicit steps (Lite, KYC). A third step (e.g., vehicle addition, fleet setup) is not present in the auth module; it may belong to other domains (assets, vehicles).
2. Email verification endpoint: The verify_email method is ready but no route exposes it.
3. Password‑reset endpoints: The initiate_password_reset and reset_password methods are implemented but not routed.
4. Onboarding flow: After KYC, the user is fully activated, but there is no dedicated “onboarding” endpoint that guides through optional post‑registration steps.
5. Dynamic configuration: The service heavily relies on config.get_setting – all parameters are stored in system_parameters, making the system admin‑configurable.

7. Recommendations

1. Route the missing endpoints: Add /auth/verify‑email, /auth/forgot‑password, /auth/reset‑password to auth.py.
2. Consider a third step: If a third registration step is required (e.g., “add your first vehicle”), design a separate endpoint under /assets or /vehicles and link it from the front‑end onboarding flow.
3. Verify email‑template existence: Ensure the email templates (reg, pwd_reset) are defined in email_manager.
4. Test the full flow: Write an end‑to‑end test that covers Lite registration → email verification → KYC completion → password reset.
5. Document the dynamic parameters: List all system_parameter keys used by the auth module (auth_min_password_length, auth_default_role, auth_registration_hours, org_naming_template, finance_default_currency, gamification_kyc_bonus, auth_password_reset_hours).

8. Conclusion

The authentication and registration module is architecturally complete and production‑ready. The business logic is well‑structured, uses dynamic configuration, and integrates with the broader ecosystem (geo, gamification, organizations, wallets). The only gap is the lack of routed endpoints for email verification and password reset – a straightforward addition that does not require changes to the core logic.

Once the missing endpoints are connected, the three‑step registration (Lite → Verify → KYC) will be fully operational, and the module will satisfy all functional requirements.