---

description: "Task list for SP-01 Authentication feature implementation"
---

# Tasks: Authentication (SP-01)

**Input**: Design documents from `/specs/001-authentication/`

**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, quickstart.md

**Tests**: Tests are REQUIRED for this feature (SC-005: "Feature tests achieve 100% pass rate")

**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.

## Format: `[ID] [P?] [Story] Description`

- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
- Include exact file paths in descriptions

---

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Project initialization and Sanctum installation

- [x] T001 [P] Install Laravel Sanctum via `php artisan install:api`
- [x] T002 [P] Configure `APP_TIMEZONE=Asia/Damascus` in `.env`
- [x] T003 Create Auth Domain directory structure `app/Domains/Auth/`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented

**⚠️ CRITICAL**: No user story work can begin until this phase is complete

- [x] T004 Create Admin model in `app/Domains/Auth/Models/Admin.php` (extends Authenticatable, uses HasApiTokens)
- [x] T005 [P] Create Admin migration `create_admins_table` in `database/migrations/`
- [x] T006 [P] Create AdminRepositoryInterface in `app/Domains/Auth/Repositories/Contracts/AdminRepositoryInterface.php`
- [x] T007 [P] Create EloquentAdminRepository in `app/Domains/Auth/Repositories/Eloquent/EloquentAdminRepository.php`
- [x] T008 Create AdminSeeder in `database/seeders/AdminSeeder.php` (idempotent, reads from env)
- [x] T009 Run AdminSeeder via `php artisan db:seed --class=AdminSeeder`
- [x] T010 Create base AdminResource in `app/Domains/Auth/Http/Resources/AdminResource.php`

**Checkpoint**: Foundation ready - user story implementation can now begin

---

## Phase 3: User Story 1 - Admin Login (Priority: P1) 🎯 MVP

**Goal**: Admin can authenticate with email/password and receive a Bearer token

**Independent Test**: Submit valid credentials to POST /api/v1/auth/login and verify 200 response with token

### Tests for User Story 1 ⚠️

> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

- [x] T011 [P] [US1] Create `test_admin_can_login_with_correct_credentials` in `tests/Feature/Auth/AuthenticationTest.php`
- [x] T012 [P] [US1] Create `test_login_fails_with_wrong_password` in `tests/Feature/Auth/AuthenticationTest.php`
- [x] T013 [P] [US1] Create `test_login_fails_with_invalid_email_format` in `tests/Feature/Auth/AuthenticationTest.php`
- [x] T014 [P] [US1] Create `test_login_fails_when_required_fields_missing` in `tests/Feature/Auth/AuthenticationTest.php`
- [x] T014a [P] [US1] Create `test_login_fails_with_empty_password` in `tests/Feature/Auth/AuthenticationTest.php` (edge case: password is empty string → 401)

### Implementation for User Story 1

- [x] T015 [US1] Create LoginRequest in `app/Domains/Auth/Http/Requests/LoginRequest.php` (email: required|email, password: required|string)
- [x] T016 [US1] Create AuthService in `app/Domains/Auth/Services/AuthService.php` with login() method
- [x] T017 [US1] Create AuthController in `app/Domains/Auth/Http/Controllers/AuthController.php` with login() method
- [x] T018 [US1] Register POST /api/v1/auth/login route with throttle:5,1 middleware in `routes/api.php`

**Checkpoint**: User Story 1 should be fully functional and testable independently

---

## Phase 4: User Story 2 - Admin Logout (Priority: P2)

**Goal**: Authenticated Admin can invalidate their current token

**Independent Test**: Authenticate, call DELETE /api/v1/auth/logout, then verify token no longer works on protected endpoint

### Tests for User Story 2 ⚠️

> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

- [x] T019 [P] [US2] Create `test_admin_can_logout` in `tests/Feature/Auth/AuthenticationTest.php`
- [x] T020 [P] [US2] Create `test_logout_fails_without_token` in `tests/Feature/Auth/AuthenticationTest.php`
- [x] T020a [P] [US2] Create `test_logout_deletes_only_current_token` in `tests/Feature/Auth/AuthenticationTest.php` (edge case: when admin has multiple tokens, logout deletes only the current token)

### Implementation for User Story 2

- [x] T021 [US2] Add logout() method to AuthService in `app/Domains/Auth/Services/AuthService.php`
- [x] T022 [US2] Add logout() method to AuthController in `app/Domains/Auth/Http/Controllers/AuthController.php`
- [x] T023 [US2] Register DELETE /api/v1/auth/logout route with auth:sanctum middleware in `routes/api.php`

**Checkpoint**: User Stories 1 AND 2 should both work independently

---

## Phase 5: User Story 3 - Verify Current Session (Priority: P3)

**Goal**: Authenticated Admin can verify their token and retrieve profile

**Independent Test**: Authenticate, call GET /api/v1/auth/me, verify response contains admin profile

### Tests for User Story 3 ⚠️

> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

- [x] T024 [P] [US3] Create `test_me_returns_admin_profile` in `tests/Feature/Auth/AuthenticationTest.php`
- [x] T025 [P] [US3] Create `test_me_fails_without_token` in `tests/Feature/Auth/AuthenticationTest.php`

### Implementation for User Story 3

- [x] T026 [US3] Add me() method to AuthService in `app/Domains/Auth/Services/AuthService.php`
- [x] T027 [US3] Add me() method to AuthController in `app/Domains/Auth/Http/Controllers/AuthController.php`
- [x] T028 [US3] Register GET /api/v1/auth/me route with auth:sanctum middleware in `routes/api.php`

**Checkpoint**: All user stories should now be independently functional

---

## Phase 6: Integration & Rate Limiting Tests

**Purpose**: Verify all endpoints work together and rate limiting functions

### Tests for Rate Limiting ⚠️

- [x] T029 [P] Create `test_rate_limit_blocks_after_5_attempts` in `tests/Feature/Auth/AuthenticationTest.php`

### Performance Criteria Note ⚠️

> SC-001 (authentication response <2s) and SC-002 (rate limit response <100ms) require load testing infrastructure (e.g., Laravel Dusk, benchmarking tools) beyond standard feature tests. These are marked as verification tasks rather than automated tests in this task list.

### Verification Tasks

- [x] T030 [P] Run `php artisan route:list` to verify all 3 routes registered correctly
- [x] T031 [P] Run `php artisan test --filter=AuthenticationTest` to verify all tests pass

**Checkpoint**: All tests green, ready for polish

---

## Phase 7: Polish & Cross-Cutting Concerns

**Purpose**: Final verification and cleanup

- [x] T032 Verify all PHPDoc blocks exist on public methods in AuthService, AuthController
- [x] T033 Verify Unified Response format used consistently across all endpoints
- [x] T034 [P] Verify AdminResource returns only: id, name, email, created_at
- [x] T035 Run full test suite to ensure no regressions

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies - can start immediately
- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
- **User Stories (Phase 3-5)**: All depend on Foundational phase completion
  - User stories can then proceed in parallel (if staffed)
  - Or sequentially in priority order (P1 → P2 → P3)
- **Integration (Phase 6)**: Depends on all user stories complete
- **Polish (Phase 7)**: Depends on Integration complete

### User Story Dependencies

- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Can test independently but uses same service/controller
- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Can test independently but uses same service/controller

### Within Each User Story

- Tests MUST be written and FAIL before implementation
- Models/Repositories before Services
- Services before Controllers
- Controllers before Routes
- Story complete before moving to next priority

### Parallel Opportunities

- All Setup tasks marked [P] can run in parallel
- All Foundational tasks marked [P] can run in parallel (within Phase 2)
- All tests for a user story marked [P] can run in parallel
- All User Story implementation tasks marked [P] can run in parallel

---

## Parallel Example: User Story 1

```bash
# Launch all tests for User Story 1 together:
Task: "test_admin_can_login_with_correct_credentials"
Task: "test_login_fails_with_wrong_password"
Task: "test_login_fails_with_invalid_email_format"
Task: "test_login_fails_when_required_fields_missing"

# Implementation is sequential (LoginRequest → AuthService → AuthController → Route)
```

---

## Implementation Strategy

### MVP First (User Story 1 Only)

1. Complete Phase 1: Setup
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
3. Complete Phase 3: User Story 1 (Login)
4. **STOP and VALIDATE**: Test User Story 1 independently
5. Deploy/demo if ready (login MVP complete)

### Incremental Delivery

1. Complete Setup + Foundational → Foundation ready
2. Add User Story 1 → Test independently → Deploy/Demo (Login MVP!)
3. Add User Story 2 → Test independently → Deploy/Demo (Logout added)
4. Add User Story 3 → Test independently → Deploy/Demo (Me added)
5. Integration tests + Polish → Full feature complete

### Parallel Team Strategy

With multiple developers:

1. Developer A: Phase 1 + Phase 2 (Setup + Foundational)
2. Once Foundational is done:
   - Developer A: User Story 1
   - Developer B: User Story 2
   - Developer C: User Story 3
3. All stories complete + Integration tests + Polish

---

## Notes

- [P] tasks = different files, no dependencies
- [Story] label maps task to specific user story for traceability
- Each user story should be independently completable and testable
- Tests must fail before implementation (TDD approach)
- Commit after each task or logical group
- Stop at any checkpoint to validate story independently
- AuthController must remain thin — delegates to AuthService only
- All business logic in AuthService, all data access via Repository