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