93 lines
4.3 KiB
Markdown
93 lines
4.3 KiB
Markdown
# internal-authentication Specification
|
|
|
|
## Purpose
|
|
Provide session-based authentication for the internal Filament panel at `/admin`, limited to two roles (admin and assistant), with unique emails, password reset without enumeration, inactive users denied, and user management restricted to admins.
|
|
## Requirements
|
|
### Requirement: Internal users authenticate via Filament panel
|
|
|
|
The system SHALL provide authenticated access to the internal panel at `/admin` using Laravel's session-based authentication integrated with Filament 5.
|
|
|
|
#### Scenario: Active admin logs in successfully
|
|
|
|
- **WHEN** an active user with role `admin` submits valid credentials on the login page
|
|
- **THEN** the system authenticates the user and redirects to the Filament dashboard
|
|
|
|
#### Scenario: Active assistant logs in successfully
|
|
|
|
- **WHEN** an active user with role `assistant` submits valid credentials on the login page
|
|
- **THEN** the system authenticates the user and redirects to the Filament dashboard
|
|
|
|
#### Scenario: Inactive user is denied panel access
|
|
|
|
- **WHEN** a user with `is_active` set to false submits valid credentials
|
|
- **THEN** the system MUST NOT grant access to the Filament panel
|
|
|
|
### Requirement: User roles are limited to admin and assistant
|
|
|
|
The system SHALL store user roles using the `UserRole` enum with exactly two cases: `admin` and `assistant`. The system MUST NOT implement a granular permission system in the MVP.
|
|
|
|
#### Scenario: User is created with a valid role
|
|
|
|
- **WHEN** an administrator creates a user with role `admin` or `assistant`
|
|
- **THEN** the role is persisted and enforced on subsequent authorization checks
|
|
|
|
### Requirement: Email addresses are unique per user
|
|
|
|
The system SHALL enforce a unique constraint on user email addresses.
|
|
|
|
#### Scenario: Duplicate email rejected
|
|
|
|
- **WHEN** a user is created or updated with an email already assigned to another user
|
|
- **THEN** the system MUST reject the operation with a validation error
|
|
|
|
### Requirement: Password reset is available for internal users
|
|
|
|
The system SHALL support secure password reset for internal users using Laravel's built-in reset flow.
|
|
|
|
#### Scenario: User requests password reset
|
|
|
|
- **WHEN** a user submits a registered email on the password reset form
|
|
- **THEN** the system sends a reset link without revealing whether the email exists
|
|
|
|
### Requirement: Only admin manages internal users
|
|
|
|
The system SHALL restrict user management (create, update, deactivate) to users with role `admin`. Users with role `assistant` MUST NOT manage other users.
|
|
|
|
#### Scenario: Assistant cannot access user management
|
|
|
|
- **WHEN** an authenticated assistant attempts to access user management in the panel
|
|
- **THEN** the system MUST deny access via authorization policy
|
|
|
|
### Requirement: Verified email is required for panel access
|
|
|
|
Internal users MUST have a verified email address to access the Filament panel (SPEC §12.1, ADM-01). Active users with unverified email MUST be denied panel access. Development seeds MUST mark local demo users as verified.
|
|
|
|
#### Scenario: Unverified active user is denied panel access
|
|
|
|
- **WHEN** an active user with null `email_verified_at` authenticates
|
|
- **THEN** the system MUST NOT grant access to the Filament panel
|
|
|
|
#### Scenario: Verified active user can access the panel
|
|
|
|
- **WHEN** an active user with a non-null `email_verified_at` submits valid credentials
|
|
- **THEN** the system authenticates the user and allows Filament panel access subject to role rules
|
|
|
|
#### Scenario: Local seed users are verified
|
|
|
|
- **WHEN** `DatabaseSeeder` creates the local admin and assistant
|
|
- **THEN** both users MUST have `email_verified_at` set
|
|
|
|
### Requirement: Password reset flow is covered by automated tests
|
|
|
|
The secure password reset flow for internal users MUST be covered by feature tests that assert a reset request for a registered email queues/sends a reset notification without revealing whether the email exists to the client (SPEC §12.1; existing password-reset requirement).
|
|
|
|
#### Scenario: Reset request does not reveal account existence
|
|
|
|
- **WHEN** a visitor submits a password reset for an unknown email
|
|
- **THEN** the response MUST not disclose that the email is unregistered
|
|
|
|
#### Scenario: Registered email receives reset notification
|
|
|
|
- **WHEN** a visitor submits a password reset for a registered email
|
|
- **THEN** the system MUST dispatch the password reset notification (faked in tests)
|