# Tasks: Auth Structure v1.0

**Feature**: `064-auth-structure`
**Plan**: [plan.md](./plan.md)
**Specification**: [spec.md](./spec.md)

This document breaks down the implementation of the Auth Structure feature into actionable, dependency-ordered tasks.

## Phase 1: Foundational Setup (Prerequisites)

These tasks create the core data structure and must be completed before any auth logic is built.

- [X] T001 Create migration for `platform_users` table in `database/migrations/`
- [X] T002 Create `PlatformUser` model in `app/Models/PlatformUser.php`
- [X] T003 Create `PlatformUserFactory` in `database/factories/PlatformUserFactory.php`

## Phase 2: Core Authentication Configuration

These tasks configure Laravel's authentication system to recognize the new user type and guard.

- [X] T004 Define `platform` guard and `platform_users` provider in `config/auth.php`
- [X] T005 [P] Create `PlatformUserSeeder` to seed an initial operator account in `database/seeders/PlatformUserSeeder.php`
- [X] T006 [P] Update `DatabaseSeeder` to call the `PlatformUserSeeder` in `database/seeders/DatabaseSeeder.php`

## Phase 3: User Story 2 - Platform Panel Implementation (P1)

**Goal**: A platform operator can log in to a new, separate `/system` panel.
**Independent Test**: A seeded user can authenticate at `/system/login` and access a system dashboard, while being denied access to `/admin/t/*` routes.

- [X] T007 [US2] Create `SystemPanelProvider` in `app/Providers/Filament/SystemPanelProvider.php` and configure it to use the `platform` auth guard (path `/system`).
- [X] T008 [US2] Register `SystemPanelProvider` in `bootstrap/providers.php`
- [X] T009 [US2] Create Filament v5 System login page at `app/Filament/System/Pages/Auth/Login.php` (local email+password) and wire it via `SystemPanelProvider->login(...)`.
- [X] T010 [US2] Create a basic dashboard page for the System Panel in `app/Filament/System/Pages/Dashboard.php`
- [X] T011 [US2] Create `SystemPanelAuthTest.php` to verify platform user login and logout in `tests/Feature/Auth/SystemPanelAuthTest.php`
- [X] T011b [US2] Implement audit logging for platform login attempts (success and failure) and add assertions to `SystemPanelAuthTest.php`.
- [X] T018b [US2] Enforce minimum capability `platform.access_system_panel` for any authenticated platform session to use `/system` (otherwise deny-as-not-found / 404). Depends on T017 + T018. Add a small test case to `SystemPanelAuthTest.php`.

## Phase 4: User Story 1 - Admin Panel Isolation & Cross-Scope Enforcement (P1)

**Goal**: A tenant admin can log in via Entra ID and cannot access the system panel.
**Independent Test**: An Entra-authenticated user can access `/admin/t/{tenant}` but receives a 404 upon visiting `/system`.

- [X] T012 [US1] Create `EnsureCorrectGuard` middleware to enforce 404s on cross-panel access in `app/Http/Middleware/EnsureCorrectGuard.php`
- [X] T013 [US1] Apply `EnsureCorrectGuard` to BOTH panels deterministically (preferred: panel middleware stack in each PanelProvider; acceptable: explicit route-group middleware in routes/web.php). Cross-scope MUST return 404.
- [X] T014 [US1] [P] Verify `/admin/login` is Entra-only: no password inputs rendered and no break-glass link/banner appears in the admin login surface (assert via feature test or DOM assertions).
- [X] T015 [US1] Create `CrossScopeAccessTest.php` to verify 404 responses for both tenant->system and platform->admin access attempts in `tests/Feature/Auth/CrossScopeAccessTest.php`
- [X] T016 [US1] Create `AdminPanelAuthTest.php` to confirm Entra-only login flow works as expected in `tests/Feature/Auth/AdminPanelAuthTest.php`

## Phase 5: User Story 3 - Break-glass Mode (P2)

**Goal**: A privileged platform operator can enter a temporary, audited "break-glass" session.
**Independent Test**: An operator with the correct capability can start the session, see a banner, and have the session expire or exit, with all events being logged.

- [X] T017 [US3] Define platform capabilities (e.g., `platform.access_system_panel`, `platform.use_break_glass`) in `app/Support/Auth/PlatformCapabilities.php`
- [X] T018 [US3] Register gates for platform capabilities in `app/Providers/AuthServiceProvider.php` (do not introduce a new provider just for this).
- [X] T019 [US3] Implement the session logic for starting, checking, and clearing the break-glass state (including capturing an operator-provided reason).
- [X] T020 [US3] [P] Create the `break-glass-banner.blade.php` view component in `resources/views/filament/system/components/`
- [X] T021 [US3] Add the "Enter break-glass mode" `Action` to a page in the System Panel, visible only to users with the `platform.use_break_glass` capability, and include `->requiresConfirmation()`.
- [X] T022 [US3] Register a render hook in `SystemPanelProvider` to display the banner when in break-glass mode.
- [X] T023 [US3] Implement `AuditLog` entries for break-glass state changes (enter, exit, expire).
- [X] T024 [US3] Create `BreakGlassModeTest.php` to test the full lifecycle of the break-glass feature in `tests/Feature/Auth/BreakGlassModeTest.php`

## Phase 6: Deprecation & Polish

Final checks, cleanup, and architectural enforcement.

- [X] T025 [P] Create `IsPlatformSuperadminDeprecationTest.php` as an architecture test to fail if `users.is_platform_superadmin` is used in `tests/Deprecation/`
- [X] T026 Run formatting with `./vendor/bin/sail bin pint --dirty` and keep the working tree clean.
- [X] T027 [P] Add/verify `BREAK_GLASS_ENABLED` and `BREAK_GLASS_TTL_MINUTES` in `.env.example` (required). Optionally document in README.md.

## Dependencies & Implementation Strategy

-   **MVP**: The MVP consists of completing **Phase 1, 2, 3, and 4**. This delivers the core value of two separate, isolated authentication panels.
-   **Dependencies**:
    -   `Phase 3 (US2)` and `Phase 4 (US1)` can be developed in parallel after `Phase 2` is complete. However, the final cross-scope tests (`T015`) depend on both panels being functional.
    -   `Phase 5 (US3)` is strictly dependent on the completion of `Phase 3 (US2)`.
    -   `T018b` depends on `T017` + `T018` (capability definitions + gate registration).
-   **Parallel Execution**: Within phases, tasks marked with `[P]` can be worked on concurrently. For example, after the migration is created (T001), the Model (T002) and Factory (T003) can be created in parallel.

This structure allows for incremental delivery. The core platform panel (US2) can be delivered first, followed by the admin panel isolation (US1) and finally the break-glass enhancement (US3).
