# Auth — Implementation Tasks

> Produced by the Reversa **Writer** (phase: generation) · doc_level: `complete`
> Generated on 2026-09-19

**Confidence scale:** 🟢 CONFIRMED · 🟡 INFERRED · 🔴 GAP

## Prerequisites

- [ ] Dependencies listed in `design.md` are available (Encore\Admin-equivalent guard/view, Laravel session + CSRF middleware, session store).
- [ ] `admin_users` table (and RBAC tables) migrated — see `admin` tables migration and `_reversa_sdd/erd-complete.md`.
- [ ] Config documented: `admin.route.prefix` (`''`), `admin.route.middleware` (`['web','admin']`), `admin.secure` (`ADMIN_SECURE`, default `true`), `admin` guard driver `session` → provider `Administrator`.
- [ ] A seeded/first administrator account exists (do NOT ship the `admin`/`admin` default to production — BR-09).

## Tasks

> Each task references the legacy file the behavior was extracted from.

- [ ] T-01 — Register the auth routes (login/logout/setting) under the admin prefix + middleware.
  - Legacy origin: `routes/web.php:20`, `vendor/salipropham/laravel55-admin/src/Admin.php:232-258`
  - Done when: `GET/POST auth/login`, `GET auth/logout`, `GET/PUT auth/setting` resolve to the auth controller within the `['web','admin']`-guarded group.
  - Confidence: 🟢

- [ ] T-02 — Configure the `admin` session guard backed by the `Administrator` model on `admin_users`.
  - Legacy origin: `config/admin.php:50-64`
  - Done when: `Auth::guard('admin')` authenticates against `admin_users` with the session driver.
  - Confidence: 🟢

- [ ] T-03 — Implement `GET auth/login`: redirect if already authenticated, else render the login view with a `username`/`password` form.
  - Legacy origin: `vendor/…/AuthController.php:23-30`
  - Done when: authenticated users are redirected to the post-login path; anonymous users get the form.
  - Confidence: 🟢

- [ ] T-04 — Implement `POST auth/login`: validate `username`+`password` required, `guard()->attempt()`, on success regenerate session + redirect intended/`/pos`, on failure redirect back with a generic error + preserved input.
  - Legacy origin: `vendor/…/AuthController.php:39-60,172-179`
  - Done when: valid creds authenticate and land on `/pos`; invalid creds show one generic message (BR-04) and keep the username input.
  - Confidence: 🟢

- [ ] T-05 — Implement the generic failed-login message helper (`auth.failed` fallback string), identical for unknown-user and wrong-password.
  - Legacy origin: `vendor/…/AuthController.php:144-149`
  - Done when: both failure modes return the same text (no user enumeration).
  - Confidence: 🟢

- [ ] T-06 — Implement `GET auth/logout`: `guard()->logout()`, `session()->invalidate()`, redirect to admin root.
  - Legacy origin: `vendor/…/AuthController.php:67-74`
  - Done when: after logout the session is empty and protected routes redirect to login.
  - Confidence: 🟢

- [ ] T-07 — Apply the `admin` auth middleware to the whole application route group so anonymous access to any app route redirects to login.
  - Legacy origin: `routes/web.php:23-27`, `config/admin.php:29`
  - Done when: `GET /pos` (and any other app route) while anonymous redirects to `auth/login`.
  - Confidence: 🟢

- [ ] T-08 — Implement `GET/PUT auth/setting`: self-edit form (`username` read-only, `name` required, `avatar` image, `password`+`password_confirmation` `confirmed|required`); re-hash password with bcrypt only when changed; ignore `password_confirmation`; success toast + redirect back.
  - Legacy origin: `vendor/…/AuthController.php:81-139`
  - Done when: a user can change their own name/avatar/password; unchanged password is not re-hashed; wrong confirmation is rejected.
  - Confidence: 🟢

- [ ] T-09 — Wire the effective post-login landing: root `/` 301-redirects to `/pos`.
  - Legacy origin: `routes/web.php:22`
  - Done when: navigating to `/` after login lands on the POS terminal.
  - Confidence: 🟢

- [ ] T-10 — Ensure HTTPS/secure-cookie posture is configurable via `ADMIN_SECURE` (default true) and CSRF applies to `POST auth/login` and `PUT auth/setting`.
  - Legacy origin: `config/admin.php` (`secure`), `app/Http/Middleware/VerifyCsrfToken.php`
  - Done when: state-changing auth requests require a valid CSRF token; secure flag honored per env.
  - Confidence: 🟢

- [ ] T-11 — Do NOT reimplement the dead framework auth stack (`app/Http/Controllers/Auth/*`, `web` guard → `App\User`, `RedirectIfAuthenticated`→`/home`, self-registration). Explicitly exclude it.
  - Legacy origin: `config/auth.php:71`, `app/Http/Controllers/Auth/*`, `app/Http/Middleware/RedirectIfAuthenticated.php`
  - Done when: the reimplementation has a single auth stack; no self-registration or framework-guard routes exist.
  - Confidence: 🟢

## Test Tasks

- [ ] TT-01 — Happy path: valid login starts a session and redirects to `/pos` (see `requirements.md` Acceptance Criteria).
- [ ] TT-02 — Wrong password returns the generic error and preserves the username; no session started.
- [ ] TT-03 — Missing `username`/`password` fails validation before any login attempt.
- [ ] TT-04 — Anonymous request to a protected route (`/pos`, `/orders`) redirects to `auth/login`.
- [ ] TT-05 — Logout invalidates the session; subsequent protected request redirects to login.
- [ ] TT-06 — `PUT auth/setting` with a new, confirmed password bcrypt-hashes and stores it; unchanged password is not re-hashed.
- [ ] TT-07 — Already-authenticated `GET auth/login` redirects instead of rendering the form.
- [ ] TT-08 — Session id is regenerated across a successful login.

## Data Migration Tasks (if applicable)

- [ ] TM-01 — Migrate existing `admin_users` rows (bcrypt hashes are portable; preserve `username`, `password`, `name`, `avatar`, `remember_token`). Reference: `database/migrations/2016_01_04_173148_create_admin_tables.php`, `_reversa_sdd/data-dictionary.md`.
- [ ] TM-02 — Decide the fate of seeded RBAC rows (roles/permissions/menu). They are decorative today (BR-02); migrate as-is or drop per the target authorization decision.

## Suggested Order

1. T-01 → T-02 (routes + guard) — foundation everything else needs.
2. T-03 → T-05 (login page, login handler, failure message) — the core flow.
3. T-06 → T-07 (logout + route protection) — session lifecycle and the app-wide gate.
4. T-08 (self-setting) — depends on an authenticated session.
5. T-09 → T-10 (landing + transport security).
6. T-11 (exclusion) — verify no dead stack leaked in.

## Pending Gaps (🔴)

- 🟢 Brute-force / rate-limiting and failed-login logging are absent in the legacy. Decided 2026-09-25 (`questions.md#question-15`): **not needed** in the reimplementation either — kept as legacy behaviour.
- 🔴 Whether login validation errors should stay redirect-based (302 + error bag) or become JSON `422` in a modernized API — human/architecture decision.