# Phase 2 implementation

## Scope

Phase 2 extends the Phase 1 modular monolith with tenant-scoped authentication, persisted and remembered sessions, password recovery, airline organization and base setup, user administration, role-based access control, permission-aware navigation, login history, and audit history.

## Authentication lifecycle

- Login requires airline code plus email to prevent cross-airline identity ambiguity.
- Passwords use PHP's current `PASSWORD_DEFAULT` algorithm and are transparently rehashed when needed.
- Failed attempts are stored and throttled by airline code, normalized email, and IP address.
- Successful login regenerates the PHP session and creates a revocable `user_sessions` record.
- Remember-me cookies contain a selector and one-time validator. Only the validator hash is stored, and a successful remembered login rotates both values.
- Disabled/deleted users, inactive airlines, revoked sessions, and expired sessions are rejected on every protected request.
- Reset tokens use selector/validator pairs, store only SHA-256 validator hashes, expire, and are single-use.
- Password reset/change revokes existing sessions. Administrator resets also force a password change.

## Authorization

Permissions use the `module.action` convention. Route middleware performs server-side authorization, and services repeat authorization before sensitive business actions. Tenant ownership is included in repository queries and assignment validation.

The navigation uses the already-authorized request identity and displays only modules granted to the current user. Navigation visibility is not treated as an access control.

## Upgrade behavior

The Phase 2 migration preserves Phase 1 tables and columns. Existing airlines without an airline code receive the ICAO code, IATA code, or an `AIR{id}` fallback. Existing Phase 1 administrator accounts without role assignments receive the tenant's Super Administrator role when seeders run.

## Password reset delivery

The reset workflow and secure tokens are complete, but production email delivery is intentionally adapter-ready rather than coupled to an email provider. Development mode can display the generated token; production always returns a generic response and does not expose it.