# Phase 4: Authentication, Roles and Permissions

## Completed

- Institution-scoped role assignments using Spatie Laravel Permission team support.
- Stable global catalogue with 28 granular permissions.
- All 32 requested default institutional roles and initial permission maps.
- Custom role creation and permission assignment interface.
- Tenant-scoped user access administration.
- Active, inactive, and suspended account states.
- Mandatory reason and timestamp for suspensions.
- Immediate logout of users whose account becomes inactive or suspended.
- Successful, failed, suspended, and rate-locked login audit outcomes.
- IP address, user agent, institution, user, session, and occurrence-time evidence.
- Append-only security audits for role, permission, and account-state changes.
- Strong passwords: at least 12 characters with mixed case, numbers, and symbols.
- Public self-registration control, disabled by default.
- Encrypted fields for future two-factor secrets and recovery codes.

## Authorization architecture

Permissions are global stable identifiers. Roles and user assignments are scoped by
`institution_id`. Request middleware establishes the permission team before policies
and cache lookups. Policies still verify tenant ownership in addition to permissions.

Super administrators have an explicit Gate override. The flag is never inferred from
a role name.

## Default roles

The seeder creates Institution Administrator, Registrar, Deputy Registrar, Bursar,
Accountant, Provost, Vice-Chancellor, Rector, Dean, Head of Department, Programme
Coordinator, Director of Studies, Lecturer, Adjunct Lecturer, CBT Administrator,
Admission Officer, Examination Officer, Transcript Officer, Certificate Officer,
Librarian, Student Affairs Officer, ICT Administrator, Quality Assurance Officer,
Chaplain, Hostel Administrator, Staff Member, Student, Applicant, Alumni, Sponsor or
Parent, External Examiner, and Accreditation Inspector.

These are editable starting templates.

## Database changes

- Permission tables with `institution_id` team keys.
- User status, suspension, last-login, and encrypted two-factor fields.
- Institution registration-control setting.
- Append-only `login_audits` and `security_audits`.

## Honest limitations

- Two-factor fields are readiness infrastructure only. Enrollment, QR setup, recovery
  code rotation, and login challenge screens are not yet implemented.
- A later security phase will add anomaly detection, retention jobs, and consolidated
  domain audit reporting.
- Applicant self-registration belongs to Phase 5 and remains disabled in the general
  user registration flow by default.

## Phase boundary

Admission cycles, applicant profiles, documents, payments, reviews, interviews,
offers, and student conversion belong to Phase 5.