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)
```python
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:
```python
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.