ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
759c9950c4
TenantAtlas/specs/064-auth-structure/research.md
ahmido 210cf5ce8b feat: implement auth structure system panel (#77) 
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
2026-01-27 21:49:18 +00:00

3.6 KiB
Raw Blame History

Research: Auth Structure v1.0

This document summarizes the technical decisions made during the planning phase for the 064-auth-structure feature. The feature specification was highly detailed, so this research phase primarily serves to confirm and document the rationale behind the chosen implementation patterns.

Decision 1: Use Two Separate Filament Panels

  • Decision: Implement two distinct Filament Panel Providers: AdminPanelProvider for /admin and a new SystemPanelProvider for /system. Each panel will be configured with its own authentication guard.
  • Rationale: This is the standard and recommended architecture in Filament v5 for applications requiring strict separation between different user audiences or identity stacks. It provides the strongest possible isolation at multiple layers:
    • Routing: Each panel has its own route prefix.
    • Authentication: Each panel is tied to a specific Laravel authentication guard (web vs. platform), ensuring that sessions are not shared or interchangeable.
    • Middleware: Allows for panel-specific middleware stacks, which is essential for the "break-glass" banner and cross-scope access checks.
  • Alternatives Considered:
    • Single Panel with Role-Based Visibility: Using a single panel and hiding/showing navigation items and resources based on a user's role (e.g., is_platform_user). This was rejected because it does not provide true authentication separation, complicates authorization logic, and increases the risk of information leakage if visibility rules are not perfectly implemented. It would not satisfy the core "Two Panels, Two Identities" principle from the specification.

Decision 2: Create a Dedicated platform_users Table and PlatformUser Model

  • Decision: A new platform_users database table and a corresponding App\Models\PlatformUser Eloquent model will be created for the platform operators.
  • Rationale: This directly addresses the "Kein users.is_platform_superadmin" principle. It physically separates platform operator identities from tenant identities, preventing the users table from becoming a mix of unrelated identity types. This simplifies the domain model and makes future development cleaner.
  • Alternatives Considered:
    • Adding a type column to the users table: This would involve keeping all users in one table and differentiating them with a column like user_type ('tenant' or 'platform'). This was rejected as it violates the spirit of the specification and leads to a "God" user table, where nullability and attribute relevance become confusing (e.g., a platform user wouldn't have a tenant_id).

Decision 3: Implement "Break-Glass" as a Temporary Session State

  • Decision: The "break-glass" mode will be implemented as a set of temporary keys stored in the user's session, not as a persistent database state.
  • Rationale: This approach enhances security by ensuring that elevated privileges are ephemeral and automatically expire. Storing this state in the session avoids creating highly-privileged database records that could be forgotten or misused. It is also easier to clear on logout, timeout, or manual exit. All state transitions are still captured in the permanent AuditLog.
  • Alternatives Considered:
    • A is_in_break_glass_mode column on platform_users: This was rejected because it introduces persistent, high-risk state into the database. A server restart, crash, or logic error could leave an account in a privileged state indefinitely. Session-based state is inherently safer for temporary privilege escalation.