# 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.