TenantAtlas/specs/064-auth-structure/tasks.md

Tasks: Auth Structure v1.0

Feature: 064-auth-structure Plan: plan.md Specification: 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.

• T001 Create migration for platform_users table in database/migrations/
• T002 Create PlatformUser model in app/Models/PlatformUser.php
• 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.

• T004 Define platform guard and platform_users provider in config/auth.php
• T005 [P] Create PlatformUserSeeder to seed an initial operator account in database/seeders/PlatformUserSeeder.php
• 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.

• T007 [US2] Create SystemPanelProvider in app/Providers/Filament/SystemPanelProvider.php and configure it to use the platform auth guard (path /system).
• T008 [US2] Register SystemPanelProvider in bootstrap/providers.php
• 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(...).
• T010 [US2] Create a basic dashboard page for the System Panel in app/Filament/System/Pages/Dashboard.php
• T011 [US2] Create SystemPanelAuthTest.php to verify platform user login and logout in tests/Feature/Auth/SystemPanelAuthTest.php
• T011b [US2] Implement audit logging for platform login attempts (success and failure) and add assertions to SystemPanelAuthTest.php.
• 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.

• T012 [US1] Create EnsureCorrectGuard middleware to enforce 404s on cross-panel access in app/Http/Middleware/EnsureCorrectGuard.php
• 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.
• 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).
• T015 [US1] Create CrossScopeAccessTest.php to verify 404 responses for both tenant->system and platform->admin access attempts in tests/Feature/Auth/CrossScopeAccessTest.php
• 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.

• T017 [US3] Define platform capabilities (e.g., platform.access_system_panel, platform.use_break_glass) in app/Support/Auth/PlatformCapabilities.php
• T018 [US3] Register gates for platform capabilities in app/Providers/AuthServiceProvider.php (do not introduce a new provider just for this).
• T019 [US3] Implement the session logic for starting, checking, and clearing the break-glass state (including capturing an operator-provided reason).
• T020 [US3] [P] Create the break-glass-banner.blade.php view component in resources/views/filament/system/components/
• 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().
• T022 [US3] Register a render hook in SystemPanelProvider to display the banner when in break-glass mode.
• T023 [US3] Implement AuditLog entries for break-glass state changes (enter, exit, expire).
• 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.

• T025 [P] Create IsPlatformSuperadminDeprecationTest.php as an architecture test to fail if users.is_platform_superadmin is used in tests/Deprecation/
• T026 Run formatting with ./vendor/bin/sail bin pint --dirty and keep the working tree clean.
• 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).