ahmido
210cf5ce8b
Implements 064-auth-structure (Auth Structure v1.0): Adds platform_users + PlatformUser identity (factory + seeder) for platform operators Introduces platform auth guard/provider in auth.php Adds a dedicated Filament v5 System panel at system using guard platform (custom login + dashboard) Enforces strict cross-scope isolation between /admin and system (deny-as-404) Adds platform capability gating (platform.access_system_panel, platform.use_break_glass) + gates in AuthServiceProvider Implements audited break-glass mode (enter/exit/expire), banner via render hook, feature flag + TTL config Removes legacy users.is_platform_superadmin runtime usage and adds an architecture test to prevent regressions Updates tenant membership pivot usage where needed (tenant_memberships) Testing: vendor/bin/sail artisan test --compact tests/Feature/Auth (28 passed) vendor/bin/sail bin pint --dirty Notes: Filament v5 / Livewire v4 compatible. Panel providers registered in providers.php. Destructive actions use ->action(...) + ->requiresConfirmation() where applicable. Co-authored-by: Ahmed Darrazi <ahmeddarrazi@MacBookPro.fritz.box> Reviewed-on: #77
103 lines
6.1 KiB
Markdown
103 lines
6.1 KiB
Markdown
# Implementation Plan: Auth Structure v1.0
|
|
|
|
**Branch**: `064-auth-structure` | **Date**: Tuesday, January 27, 2026 | **Spec**: [spec.md](./spec.md)
|
|
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/064-auth-structure/spec.md`
|
|
|
|
## Summary
|
|
|
|
This feature will implement a strict separation between Tenant and Platform administrator identities by creating two distinct Filament panels: `/admin` for Entra OIDC-authenticated tenants and `/system` for locally authenticated platform operators. The technical approach involves creating a new `PlatformUser` model and `platform_users` table, configuring custom authentication guards and providers in Laravel, and implementing middleware to enforce routing isolation. A secure, session-based "break-glass" mode for emergency recovery will be added to the system panel, gated by a feature flag and fully audited. The /admin panel MUST not expose break-glass or local password login UI; it remains tenant-user Entra OIDC only.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: PHP 8.4
|
|
**Primary Dependencies**: Laravel 12, Filament v5, Livewire v4
|
|
**Storage**: PostgreSQL (with a new `platform_users` table)
|
|
**Testing**: Pest
|
|
**Target Platform**: Web Application (deployed via Dokploy)
|
|
**Project Type**: Monolithic web application
|
|
**Performance Goals**: Standard web application responsiveness for authentication and panel loading.
|
|
**Constraints**: Must enforce strict identity and panel separation. Cross-panel access attempts must result in 404 Not Found errors to prevent information leakage. All enforcement must be implemented using files/locations that exist in this repo (no assumptions about RouteServiceProvider).
|
|
**Scale/Scope**: Two distinct user authentication stacks within a single Laravel application.
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- **Inventory-first**: Not applicable.
|
|
- **Read/write separation**: **PASS**. The "break-glass" feature, which allows privileged actions, is designed with explicit safety gates: it requires a feature flag (`BREAK_GLASS_ENABLED`), user confirmation, is time-limited, and all state changes (enter, exit, expire) are audited. Tenant recovery actions are also explicitly audited.
|
|
- **Graph contract path**: **PASS**. No new Graph calls are introduced.
|
|
- **Deterministic capabilities**: **PASS**. Platform authorization will be handled via a testable, capability-based system (`platform_users.capabilities` column and associated Gates).
|
|
- **Tenant isolation**: **PASS**. This is the core goal. The plan enforces isolation via separate guards, providers, and middleware that returns 404 on cross-scope access.
|
|
- **Run observability**: **PASS**. While login and break-glass actions do not create `OperationRun` records, the spec mandates they create detailed `AuditLog` entries, aligning with the constitution's requirements for security-relevant actions.
|
|
- **Automation**: Not applicable.
|
|
- **Data minimization**: **PASS**. No new sensitive data is being stored beyond what is necessary for authentication.
|
|
- **Badge semantics (BADGE-001)**: Not applicable.
|
|
|
|
*(Note: Apply the repo's governance/constitution rules for identity separation, break-glass recovery-only posture, and deny-as-not-found isolation. This plan assumes the constitution exists and is authoritative.)*
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/064-auth-structure/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0 output
|
|
├── data-model.md # Phase 1 output
|
|
├── quickstart.md # Phase 1 output
|
|
├── contracts/ # Phase 1 output (N/A for this feature)
|
|
└── tasks.md # Phase 2 output (/speckit.tasks command)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
This is a monolithic Laravel application. The changes will be integrated into the existing structure.
|
|
|
|
```text
|
|
app/
|
|
├── Filament/
|
|
│ └── System/ # System panel pages/resources (guard=platform, path=/system)
|
|
├── Http/
|
|
│ └── Middleware/
|
|
│ └── EnsureCorrectGuard.php # New middleware for 404 enforcement
|
|
├── Models/
|
|
│ └── PlatformUser.php # New Eloquent model
|
|
└── Providers/
|
|
├── AuthServiceProvider.php # Modified to register platform capability gates (and existing tenant gates)
|
|
└── Filament/
|
|
├── AdminPanelProvider.php # Existing tenant panel provider
|
|
└── SystemPanelProvider.php # New platform panel provider
|
|
config/
|
|
├── auth.php # Modified for new guards and providers
|
|
database/
|
|
├── factories/
|
|
│ └── PlatformUserFactory.php # New factory
|
|
├── migrations/
|
|
│ └── ..._create_platform_users_table.php # New migration
|
|
└── seeders/
|
|
├── DatabaseSeeder.php # Modified to call PlatformUserSeeder
|
|
└── PlatformUserSeeder.php # New seeder for initial platform admin
|
|
resources/
|
|
└── views/
|
|
└── filament/
|
|
└── system/
|
|
└── components/
|
|
└── break-glass-banner.blade.php # New view for banner
|
|
routes/
|
|
├── web.php # Modified to apply per-panel guard middleware and deny-as-not-found (404) cross-scope isolation
|
|
tests/
|
|
└── Feature/
|
|
├── Auth/
|
|
│ ├── AdminPanelAuthTest.php # New
|
|
│ ├── SystemPanelAuthTest.php # New
|
|
│ ├── BreakGlassModeTest.php # New
|
|
│ └── CrossScopeAccessTest.php # New (assert 404 deny-as-not-found on cross-scope access)
|
|
└── Deprecation/
|
|
└── IsPlatformSuperadminDeprecationTest.php # New arch test
|
|
```
|
|
|
|
**Structure Decision**: The implementation will extend the existing monolithic Laravel application structure. New concepts like the System Panel and Platform User will be encapsulated in their own directories (`app/Filament/System`, `app/Models/PlatformUser.php`, `app/Providers/Filament/SystemPanelProvider.php`) to maintain organization, following standard Laravel and Filament conventions.
|
|
|
|
## Complexity Tracking
|
|
|
|
No constitutional violations requiring justification. |