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

Implementation Plan: Auth Structure v1.0

Branch: 064-auth-structure | Date: Tuesday, January 27, 2026 | Spec: 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)

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.

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.