# Identity Module

## Scope and invariants

Phase 2 owns authentication, account eligibility, email verification, password
recovery/change, privileged two-factor authentication, session revocation, and
the dedicated authentication security trail. Public self-registration remains
disabled; Phase 3 creates and manages staff accounts through authorized admin
flows.

The enforced invariants are:

- Only active accounts may authenticate, request usable recovery tokens, verify
  email, or keep an authenticated session.
- Login, recovery, and two-factor failures return generic public messages.
- Passwords require at least 12 characters, mixed case, a number, and a symbol.
- Password recovery tokens expire after 30 minutes and are throttled per account
  by the broker; the endpoint is additionally throttled per source IP.
- A password reset revokes every persisted session. An authenticated password
  change preserves the current session and revokes the others. Both operations
  rotate the remember token.
- Account deactivation rotates the remember token and deletes all sessions in
  the same database transaction.
- Super administrators cannot enter administration until email is verified, a
  temporary password is changed, and 2FA is confirmed.
- Recovery codes are encrypted at rest, single-use, and never copied to audit
  data.
- Verification and recovery mail is queued on the `notifications` queue after
  the surrounding transaction commits.

## Request flows

### Login

The credential callback normalizes email, validates password inside Laravel's
timebox, rejects inactive accounts with the same public error as invalid
credentials, and records a redacted event. Fortify then handles session ID
regeneration and the 2FA challenge. The successful login event is emitted only
after 2FA succeeds.

### Password recovery

The application-owned recovery controller deliberately replaces Fortify's
default reset-link endpoint. The password broker receives `is_active = true` as
part of its credentials, so inactive and unknown accounts receive the same
timed lookup and the same outward response without creating a token. A valid
reset runs under a row lock, rotates credentials, revokes sessions, consumes
the token, and writes the security event.

### Email verification and 2FA

Fortify supplies signed verification routes, TOTP verification, encrypted
secrets, and atomic recovery-code replacement. Application listeners translate
the lifecycle events into the authentication audit trail. All 2FA management
routes require a recent password confirmation.

## Security threat review

| Threat | Control |
|---|---|
| Account enumeration | generic recovery/login errors, timed broker and credential checks |
| Brute force / reset abuse | email+IP login limiter, IP recovery limiter, token throttle, 2FA limiter |
| Session fixation | Fortify regenerates the session after authentication |
| Stolen persistent cookie | remember-token rotation on password change/reset/deactivation |
| Stolen server session | authoritative database-session deletion |
| Recovery replay | hashed, expiring, single-use password reset token |
| 2FA secret exposure | encrypted columns, hidden model attributes, sensitive input redaction |
| Authorization bypass | verified/password-change/2FA/permission middleware enforced server-side |
| Audit PII leakage | HMAC-correlated email, bounded user agent, no credentials/tokens/codes |

## Operations

Production must use the database session driver until another session store has
an explicit, tested revocation adapter. Run at least one worker for the
`notifications` queue and monitor queue age/failures. The recovery drill is:

1. Submit recovery for an active test account and verify the generic response.
2. Confirm a notification job reaches the `notifications` queue and is delivered.
3. Reset through the 30-minute tokenized link and verify all prior sessions fail.
4. Confirm `password_reset_completed` exists without a plaintext email or token.
5. Repeat with an inactive and unknown email; neither may create a token/job.
6. Exercise TOTP and one recovery code; the code must fail on its second use.

Alerts should cover sustained login lockouts, reset volume anomalies, 2FA
failure spikes, notification queue latency, and failed notification jobs.

## Phase 2 test evidence

Feature coverage includes active/inactive login, redacted audit correlation,
login/reset/2FA throttling, uniform recovery responses, queued notification
contracts, signed verification, password reset and password change, complete
session revocation, deactivation revocation, 2FA challenge failure, and
single-use recovery-code authentication. A dedicated regression also proves
that deactivation between password validation and the 2FA response cannot
complete authentication.