Add Phase 1 Identity & Access module (roles, tokens, panel auth, policies)

Implements T1.1-T1.4: Spatie role/permission seeding, Sanctum token
issuance for customer channels and the FastAPI agent (with an
ability-exact-match middleware to tell them apart), Filament admin
panel access restricted to admin-tier roles with the navigation group
order, and skeleton BookingPolicy/RoutePolicy gated on the seeded
permissions ahead of their models landing in later phases.

app-modules/booking/src/Policies/BookingPolicy.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Modules\Booking\Policies;
+
+use App\Models\User;
+
+/**
+ * Skeleton only — role/permission gates for now. Per-booking ownership
+ * checks (e.g. a customer may only view/cancel their own booking) are
+ * filled in against the real Booking model once it exists (Phase 4).
+ */
+class BookingPolicy
+{
+    public function viewAny(User $user): bool
+    {
+        return $user->can('view_bookings');
+    }
+
+    public function view(User $user, mixed $booking): bool
+    {
+        return $user->can('view_bookings');
+    }
+
+    public function create(User $user): bool
+    {
+        return true;
+    }
+
+    public function cancel(User $user, mixed $booking): bool
+    {
+        return $user->can('manage_bookings');
+    }
+
+    public function refund(User $user, mixed $booking): bool
+    {
+        return $user->can('process_refunds');
+    }
+}

app-modules/booking/src/Providers/BookingServiceProvider.php

@@ -2,11 +2,16 @@
 
 namespace Modules\Booking\Providers;
 
+use Illuminate\Contracts\Auth\Access\Gate;
 use Illuminate\Support\ServiceProvider;
+use Modules\Booking\Policies\BookingPolicy;
 
 class BookingServiceProvider extends ServiceProvider
 {
     public function register(): void {}
 
-    public function boot(): void {}
+    public function boot(Gate $gate): void
+    {
+        $gate->policy('Modules\Booking\Models\Booking', BookingPolicy::class);
+    }
 }

app-modules/booking/tests/Feature/BookingPolicyTest.php

@@ -0,0 +1,49 @@
+<?php
+
+use App\Models\User;
+use Modules\Booking\Policies\BookingPolicy;
+use Spatie\Permission\Models\Permission;
+
+beforeEach(function () {
+    foreach (['view_bookings', 'manage_bookings', 'process_refunds'] as $permission) {
+        Permission::findOrCreate($permission, 'web');
+    }
+});
+
+test('viewAny and view require the view_bookings permission', function () {
+    $policy = new BookingPolicy;
+
+    $withPermission = User::factory()->create()->givePermissionTo('view_bookings');
+    $withoutPermission = User::factory()->create();
+
+    expect($policy->viewAny($withPermission))->toBeTrue()
+        ->and($policy->view($withPermission, null))->toBeTrue()
+        ->and($policy->viewAny($withoutPermission))->toBeFalse()
+        ->and($policy->view($withoutPermission, null))->toBeFalse();
+});
+
+test('create is open to any authenticated user', function () {
+    $policy = new BookingPolicy;
+
+    expect($policy->create(User::factory()->create()))->toBeTrue();
+});
+
+test('cancel requires the manage_bookings permission', function () {
+    $policy = new BookingPolicy;
+
+    $withPermission = User::factory()->create()->givePermissionTo('manage_bookings');
+    $withoutPermission = User::factory()->create();
+
+    expect($policy->cancel($withPermission, null))->toBeTrue()
+        ->and($policy->cancel($withoutPermission, null))->toBeFalse();
+});
+
+test('refund requires the process_refunds permission', function () {
+    $policy = new BookingPolicy;
+
+    $withPermission = User::factory()->create()->givePermissionTo('process_refunds');
+    $withoutPermission = User::factory()->create();
+
+    expect($policy->refund($withPermission, null))->toBeTrue()
+        ->and($policy->refund($withoutPermission, null))->toBeFalse();
+});

app-modules/identity/database/seeders/RolePermissionSeeder.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Modules\Identity\Database\Seeders;
+
+use Illuminate\Database\Seeder;
+use Spatie\Permission\Models\Permission;
+use Spatie\Permission\Models\Role;
+use Spatie\Permission\PermissionRegistrar;
+
+class RolePermissionSeeder extends Seeder
+{
+    /**
+     * @var list<string>
+     */
+    protected array $permissions = [
+        'manage_catalog',
+        'manage_routes',
+        'manage_pricing',
+        'view_bookings',
+        'manage_bookings',
+        'view_payments',
+        'process_refunds',
+        'view_audit_log',
+    ];
+
+    /**
+     * @var array<string, list<string>>
+     */
+    protected array $roles = [
+        'super_admin' => [
+            'manage_catalog',
+            'manage_routes',
+            'manage_pricing',
+            'view_bookings',
+            'manage_bookings',
+            'view_payments',
+            'process_refunds',
+            'view_audit_log',
+        ],
+        'admin' => [
+            'manage_catalog',
+            'manage_routes',
+            'manage_pricing',
+            'view_bookings',
+            'manage_bookings',
+            'view_payments',
+            'process_refunds',
+            'view_audit_log',
+        ],
+        'support' => [
+            'view_bookings',
+            'view_payments',
+            'view_audit_log',
+        ],
+    ];
+
+    public function run(): void
+    {
+        foreach ($this->permissions as $permission) {
+            Permission::findOrCreate($permission, 'web');
+        }
+
+        // WithoutModelEvents (used by DatabaseSeeder) suppresses the model
+        // events Spatie's permission cache relies on to invalidate itself,
+        // so the freshly created permissions above must be flushed manually.
+        app(PermissionRegistrar::class)->forgetCachedPermissions();
+
+        foreach ($this->roles as $role => $permissions) {
+            Role::findOrCreate($role, 'web')->syncPermissions($permissions);
+        }
+    }
+}

app-modules/identity/routes/identity-routes.php

@@ -1 +1,8 @@
 <?php
+
+use Illuminate\Support\Facades\Route;
+use Modules\Identity\Http\Controllers\TokenController;
+
+Route::prefix('api/v1')->middleware('api')->group(function () {
+    Route::post('/auth/token', [TokenController::class, 'store'])->name('identity.auth.token');
+});

app-modules/identity/src/Console/Commands/IssueFastApiAgentTokenCommand.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Modules\Identity\Console\Commands;
+
+use App\Models\User;
+use Illuminate\Console\Command;
+use Illuminate\Support\Str;
+use Modules\Identity\Enums\TokenAbility;
+
+class IssueFastApiAgentTokenCommand extends Command
+{
+    protected $signature = 'identity:issue-agent-token
+        {--email=fastapi-agent@system.internal : Email identifying the FastAPI agent service account}
+        {--name=fastapi-agent : Sanctum token name}';
+
+    protected $description = 'Provision a Sanctum token for the FastAPI AI agent, scoped to its restricted ability set';
+
+    public function handle(): int
+    {
+        $email = $this->option('email');
+        $tokenName = $this->option('name');
+
+        $agent = User::firstOrCreate(
+            ['email' => $email],
+            [
+                'name' => 'FastAPI Agent',
+                'password' => Str::password(40),
+            ],
+        );
+
+        $agent->tokens()->where('name', $tokenName)->delete();
+
+        $token = $agent->createToken($tokenName, TokenAbility::fastApiAgentAbilities());
+
+        $this->components->info('FastAPI agent token issued.');
+        $this->line($token->plainTextToken);
+
+        return self::SUCCESS;
+    }
+}

app-modules/identity/src/Enums/TokenAbility.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Modules\Identity\Enums;
+
+enum TokenAbility: string
+{
+    case RouteRead = 'route:read';
+    case BookingCreate = 'booking:create';
+    case BookingRead = 'booking:read';
+    case BookingCancel = 'booking:cancel';
+    case PaymentInitiate = 'payment:initiate';
+
+    /**
+     * Full ability set granted to customer channel tokens (mini app / mobile app).
+     *
+     * @return list<string>
+     */
+    public static function customerAbilities(): array
+    {
+        return [
+            self::RouteRead->value,
+            self::BookingCreate->value,
+            self::BookingRead->value,
+            self::BookingCancel->value,
+            self::PaymentInitiate->value,
+        ];
+    }
+
+    /**
+     * Restricted ability set granted to the FastAPI AI agent token — it must
+     * never be able to refund, cancel someone else's booking, or write
+     * catalog/pricing data.
+     *
+     * @return list<string>
+     */
+    public static function fastApiAgentAbilities(): array
+    {
+        return [
+            self::RouteRead->value,
+            self::BookingCreate->value,
+            self::BookingRead->value,
+        ];
+    }
+}

app-modules/identity/src/Http/Controllers/TokenController.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Modules\Identity\Http\Controllers;
+
+use App\Models\User;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Validation\ValidationException;
+use Modules\Identity\Enums\TokenAbility;
+use Modules\Identity\Http\Requests\IssueTokenRequest;
+
+class TokenController extends Controller
+{
+    /**
+     * Exchange customer credentials (mini app / mobile app) for a Sanctum
+     * token carrying the full customer ability set.
+     */
+    public function store(IssueTokenRequest $request): array
+    {
+        $user = User::where('email', $request->string('email'))->first();
+
+        if (! $user || ! Hash::check($request->string('password'), $user->password)) {
+            throw ValidationException::withMessages([
+                'email' => ['The provided credentials are incorrect.'],
+            ]);
+        }
+
+        $token = $user->createToken(
+            $request->string('device_name')->toString(),
+            TokenAbility::customerAbilities(),
+        );
+
+        return [
+            'token' => $token->plainTextToken,
+        ];
+    }
+}

app-modules/identity/src/Http/Middleware/EnsureFastApiAgent.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Modules\Identity\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Modules\Identity\Enums\TokenAbility;
+use Symfony\Component\HttpFoundation\Response;
+
+class EnsureFastApiAgent
+{
+    /**
+     * Identify the FastAPI AI agent by its token's ability scope rather than
+     * a role — the agent has no admin-panel role, only a Sanctum token
+     * restricted to exactly route:read, booking:create, booking:read.
+     *
+     * A customer token also carries those three abilities (plus more), so
+     * membership alone can't tell agent and customer tokens apart — the
+     * ability set must match exactly.
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        $token = $request->user()?->currentAccessToken();
+
+        if (! $token) {
+            abort(403, 'This action requires a FastAPI agent token.');
+        }
+
+        $actual = collect($token->abilities)->sort()->values()->all();
+        $expected = collect(TokenAbility::fastApiAgentAbilities())->sort()->values()->all();
+
+        if ($actual !== $expected) {
+            abort(403, 'This action requires a FastAPI agent token.');
+        }
+
+        return $next($request);
+    }
+}

app-modules/identity/src/Http/Requests/IssueTokenRequest.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Identity\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class IssueTokenRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, array<int, string>>
+     */
+    public function rules(): array
+    {
+        return [
+            'email' => ['required', 'email'],
+            'password' => ['required', 'string'],
+            'device_name' => ['required', 'string', 'max:255'],
+        ];
+    }
+}

app-modules/identity/tests/Feature/EnsureFastApiAgentTest.php

@@ -0,0 +1,41 @@
+<?php
+
+use App\Models\User;
+use Illuminate\Support\Facades\Route;
+use Modules\Identity\Enums\TokenAbility;
+
+beforeEach(function () {
+    Route::middleware(['auth:sanctum', 'fastapi.agent'])
+        ->get('/__test/fastapi-agent-only', fn () => response()->json(['ok' => true]));
+});
+
+test('a token scoped to exactly the agent abilities is allowed through', function () {
+    $agent = User::factory()->create();
+    $token = $agent->createToken('fastapi-agent', TokenAbility::fastApiAgentAbilities())->plainTextToken;
+
+    $this->withHeader('Authorization', "Bearer {$token}")
+        ->getJson('/__test/fastapi-agent-only')
+        ->assertSuccessful();
+});
+
+test('a customer token carrying broader abilities is rejected', function () {
+    $customer = User::factory()->create();
+    $token = $customer->createToken('iphone', TokenAbility::customerAbilities())->plainTextToken;
+
+    $this->withHeader('Authorization', "Bearer {$token}")
+        ->getJson('/__test/fastapi-agent-only')
+        ->assertForbidden();
+});
+
+test('a token missing one of the agent abilities is rejected', function () {
+    $user = User::factory()->create();
+    $token = $user->createToken('partial', [TokenAbility::RouteRead->value, TokenAbility::BookingCreate->value])->plainTextToken;
+
+    $this->withHeader('Authorization', "Bearer {$token}")
+        ->getJson('/__test/fastapi-agent-only')
+        ->assertForbidden();
+});
+
+test('an unauthenticated request is rejected', function () {
+    $this->getJson('/__test/fastapi-agent-only')->assertUnauthorized();
+});

app-modules/identity/tests/Feature/TokenIssuanceTest.php

@@ -0,0 +1,46 @@
+<?php
+
+use App\Models\User;
+use Illuminate\Support\Facades\Hash;
+use Modules\Identity\Enums\TokenAbility;
+
+test('customer token endpoint issues a token with the full customer ability set', function () {
+    $user = User::factory()->create([
+        'password' => Hash::make('secret-password'),
+    ]);
+
+    $response = $this->postJson('/api/v1/auth/token', [
+        'email' => $user->email,
+        'password' => 'secret-password',
+        'device_name' => 'iphone',
+    ]);
+
+    $response->assertSuccessful()->assertJsonStructure(['token']);
+
+    $accessToken = $user->tokens()->sole();
+    expect($accessToken->abilities)->toEqualCanonicalizing(TokenAbility::customerAbilities());
+});
+
+test('customer token endpoint rejects invalid credentials', function () {
+    $user = User::factory()->create([
+        'password' => Hash::make('secret-password'),
+    ]);
+
+    $response = $this->postJson('/api/v1/auth/token', [
+        'email' => $user->email,
+        'password' => 'wrong-password',
+        'device_name' => 'iphone',
+    ]);
+
+    $response->assertUnprocessable();
+    expect($user->tokens()->count())->toBe(0);
+});
+
+test('identity:issue-agent-token command provisions a token scoped to the agent ability set', function () {
+    $this->artisan('identity:issue-agent-token')->assertSuccessful();
+
+    $agent = User::where('email', 'fastapi-agent@system.internal')->sole();
+    $token = $agent->tokens()->sole();
+
+    expect($token->abilities)->toEqualCanonicalizing(TokenAbility::fastApiAgentAbilities());
+});

app-modules/routing/src/Policies/RoutePolicy.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Modules\Routing\Policies;
+
+use App\Models\User;
+
+/**
+ * Skeleton only — the EvRoute model doesn't exist yet (Phase 3). Gates on
+ * the manage_routes permission; catalog/route mutation is staff-only.
+ */
+class RoutePolicy
+{
+    public function viewAny(User $user): bool
+    {
+        return $user->can('manage_routes');
+    }
+
+    public function create(User $user): bool
+    {
+        return $user->can('manage_routes');
+    }
+
+    public function update(User $user, mixed $route): bool
+    {
+        return $user->can('manage_routes');
+    }
+
+    public function delete(User $user, mixed $route): bool
+    {
+        return $user->can('manage_routes');
+    }
+}

app-modules/routing/src/Providers/RoutingServiceProvider.php

@@ -2,11 +2,16 @@
 
 namespace Modules\Routing\Providers;
 
+use Illuminate\Contracts\Auth\Access\Gate;
 use Illuminate\Support\ServiceProvider;
+use Modules\Routing\Policies\RoutePolicy;
 
 class RoutingServiceProvider extends ServiceProvider
 {
     public function register(): void {}
 
-    public function boot(): void {}
+    public function boot(Gate $gate): void
+    {
+        $gate->policy('Modules\Routing\Models\EvRoute', RoutePolicy::class);
+    }
 }

app-modules/routing/tests/Feature/RoutePolicyTest.php

@@ -0,0 +1,28 @@
+<?php
+
+use App\Models\User;
+use Modules\Routing\Policies\RoutePolicy;
+use Spatie\Permission\Models\Permission;
+
+beforeEach(function () {
+    Permission::findOrCreate('manage_routes', 'web');
+});
+
+test('every gate requires the manage_routes permission', function (string $method) {
+    $policy = new RoutePolicy;
+
+    $withPermission = User::factory()->create()->givePermissionTo('manage_routes');
+    $withoutPermission = User::factory()->create();
+
+    $args = $method === 'viewAny' || $method === 'create'
+        ? [$withPermission]
+        : [$withPermission, null];
+
+    expect($policy->{$method}(...$args))->toBeTrue();
+
+    $args = $method === 'viewAny' || $method === 'create'
+        ? [$withoutPermission]
+        : [$withoutPermission, null];
+
+    expect($policy->{$method}(...$args))->toBeFalse();
+})->with(['viewAny', 'create', 'update', 'delete']);

app/Models/User.php

@@ -4,17 +4,31 @@ namespace App\Models;
 
 // use Illuminate\Contracts\Auth\MustVerifyEmail;
 use Database\Factories\UserFactory;
+use Filament\Models\Contracts\FilamentUser;
+use Filament\Panel;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
 use Laravel\Sanctum\HasApiTokens;
 use Spatie\Permission\Traits\HasRoles;
 
-class User extends Authenticatable
+class User extends Authenticatable implements FilamentUser
 {
+    /**
+     * Roles permitted to sign in to the Filament admin panel.
+     *
+     * @var list<string>
+     */
+    public const ADMIN_TIER_ROLES = ['super_admin', 'admin', 'support'];
+
     /** @use HasFactory<UserFactory> */
     use HasApiTokens, HasFactory, HasRoles, Notifiable;
 
+    public function canAccessPanel(Panel $panel): bool
+    {
+        return $this->hasAnyRole(self::ADMIN_TIER_ROLES);
+    }
+
     /**
      * The attributes that are mass assignable.
      *

app/Providers/Filament/AdminPanelProvider.php

@@ -6,6 +6,7 @@ use Filament\Http\Middleware\Authenticate;
 use Filament\Http\Middleware\AuthenticateSession;
 use Filament\Http\Middleware\DisableBladeIconComponents;
 use Filament\Http\Middleware\DispatchServingFilamentEvent;
+use Filament\Navigation\NavigationGroup;
 use Filament\Pages\Dashboard;
 use Filament\Panel;
 use Filament\PanelProvider;
@@ -31,6 +32,13 @@ class AdminPanelProvider extends PanelProvider
             ->colors([
                 'primary' => Color::Amber,
             ])
+            ->navigationGroups([
+                NavigationGroup::make()->label('Catalog'),
+                NavigationGroup::make()->label('Routing'),
+                NavigationGroup::make()->label('Operations'),
+                NavigationGroup::make()->label('Access'),
+            ])
+            ->plugins([])
             ->discoverResources(in: app_path('Filament/Resources'), for: 'App\Filament\Resources')
             ->discoverPages(in: app_path('Filament/Pages'), for: 'App\Filament\Pages')
             ->pages([

bootstrap/app.php

@@ -3,6 +3,7 @@
 use Illuminate\Foundation\Application;
 use Illuminate\Foundation\Configuration\Exceptions;
 use Illuminate\Foundation\Configuration\Middleware;
+use Modules\Identity\Http\Middleware\EnsureFastApiAgent;
 
 return Application::configure(basePath: dirname(__DIR__))
     ->withRouting(
@@ -12,7 +13,9 @@ return Application::configure(basePath: dirname(__DIR__))
         health: '/up',
     )
     ->withMiddleware(function (Middleware $middleware): void {
-        //
+        $middleware->alias([
+            'fastapi.agent' => EnsureFastApiAgent::class,
+        ]);
     })
     ->withExceptions(function (Exceptions $exceptions): void {
         //

database/seeders/DatabaseSeeder.php

@@ -5,6 +5,7 @@ namespace Database\Seeders;
 use App\Models\User;
 use Illuminate\Database\Console\Seeds\WithoutModelEvents;
 use Illuminate\Database\Seeder;
+use Modules\Identity\Database\Seeders\RolePermissionSeeder;
 
 class DatabaseSeeder extends Seeder
 {
@@ -15,6 +16,8 @@ class DatabaseSeeder extends Seeder
      */
     public function run(): void
     {
+        $this->call(RolePermissionSeeder::class);
+
         // User::factory(10)->create();
 
         User::factory()->create([

phpunit.xml

@@ -1,9 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
-         bootstrap="vendor/autoload.php"
-         colors="true"
->
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true">
     <testsuites>
         <testsuite name="Unit">
             <directory>tests/Unit</directory>
@@ -11,7 +7,7 @@
         <testsuite name="Feature">
             <directory>tests/Feature</directory>
         </testsuite>
-    </testsuites>
+    <testsuite name="Modules"><directory suffix="Test.php">./app-modules/*/tests</directory></testsuite></testsuites>
     <source>
         <include>
             <directory>app</directory>

tests/Feature/AdminPanelAccessTest.php

@@ -0,0 +1,19 @@
+<?php
+
+use App\Models\User;
+use Spatie\Permission\Models\Role;
+
+test('a user with an admin-tier role can access the admin panel', function (string $role) {
+    Role::findOrCreate($role, 'web');
+
+    $user = User::factory()->create();
+    $user->assignRole($role);
+
+    $this->actingAs($user)->get('/admin')->assertSuccessful();
+})->with(['super_admin', 'admin', 'support']);
+
+test('a user without an admin-tier role cannot access the admin panel', function () {
+    $user = User::factory()->create();
+
+    $this->actingAs($user)->get('/admin')->assertForbidden();
+});

tests/Pest.php

@@ -1,5 +1,8 @@
 <?php
 
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
 /*
 |--------------------------------------------------------------------------
 | Test Case
@@ -11,10 +14,14 @@
 |
 */
 
-pest()->extend(Tests\TestCase::class)
- // ->use(Illuminate\Foundation\Testing\RefreshDatabase::class)
+pest()->extend(TestCase::class)
+    ->use(RefreshDatabase::class)
     ->in('Feature');
 
+pest()->extend(TestCase::class)
+    ->use(RefreshDatabase::class)
+    ->in('../app-modules/*/tests/Feature');
+
 /*
 |--------------------------------------------------------------------------
 | Expectations