Wire multi-tenant scope, audit-log observer, /api/v1/tenants/me

Why this commit is more than a controller: a tenant-scoped admin app
is only safe if every read goes through the tenant filter and every
mutation lands in the audit log automatically. Both belong in the
model layer, not in each controller, so the first endpoint can lean
on them rather than re-deriving the guard.

- TenantScope: global scope filtering by auth()->user()->tenant_id.
  Skips when unauthenticated (seeders, queue workers) so scope can
  be opted into by booted() without breaking those paths.
- AuditLogObserver: records create/update/delete with before/after
  attribute snapshots; attached to Registry in AppServiceProvider.
  Models without a tenant_id (e.g., Tenant itself) are skipped for
  now — a follow-up handles Tenant-level audit.
- Registry + AuditLogEntry now boot the global scope.
- config/auth.php gains an 'api' guard backed by Passport so the new
  route can stand behind auth:api. Passport runtime tables / keys
  are not required for Passport::actingAs() in tests.
- TenantController::me returns the auth user's tenant per the Tenant
  schema in docs/api/v1.yaml. Resource wrapping disabled so the
  response is flat (matches the schema; no 'data' envelope).
- Feature test covers 401 (unauthenticated) and 200 (returns the
  caller's tenant with all four schema fields).

phpunit: 9/9 green. pint --test: passed.

Author: imanimanyara

app/Http/Controllers/Api/V1/TenantController.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Http\Resources\TenantResource;
+use App\Models\Tenant;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class TenantController extends Controller
+{
+    /**
+     * GET /api/v1/tenants/me
+     *
+     * Returns the authenticated user's tenant. Conforms to the
+     * Tenant schema in docs/api/v1.yaml.
+     */
+    public function me(Request $request): JsonResponse
+    {
+        $user = $request->user();
+        if ($user === null) {
+            abort(Response::HTTP_UNAUTHORIZED);
+        }
+
+        $tenantId = $user->tenant_id;
+        if (! is_string($tenantId)) {
+            abort(Response::HTTP_FORBIDDEN, 'user has no tenant');
+        }
+
+        $tenant = Tenant::query()->findOrFail($tenantId);
+
+        TenantResource::withoutWrapping();
+
+        return (new TenantResource($tenant))
+            ->response()
+            ->setStatusCode(Response::HTTP_OK);
+    }
+}

app/Http/Resources/TenantResource.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Http\Resources;
+
+use App\Models\Tenant;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @mixin Tenant
+ */
+class TenantResource extends JsonResource
+{
+    /**
+     * Shape matches the Tenant schema in docs/api/v1.yaml.
+     *
+     * @return array<string,mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'slug' => $this->slug,
+            'name' => $this->name,
+            'created_at' => $this->created_at?->toIso8601String(),
+        ];
+    }
+}

app/Models/AuditLogEntry.php

@@ -2,6 +2,7 @@
 
 namespace App\Models;
 
+use App\Models\Scopes\TenantScope;
 use Illuminate\Database\Eloquent\Concerns\HasUuids;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -33,6 +34,11 @@ class AuditLogEntry extends Model
      */
     public const UPDATED_AT = null;
 
+    protected static function booted(): void
+    {
+        static::addGlobalScope(new TenantScope);
+    }
+
     protected $fillable = [
         'tenant_id', 'user_id', 'action',
         'target_type', 'target_id',

app/Models/Registry.php

@@ -2,6 +2,7 @@
 
 namespace App\Models;
 
+use App\Models\Scopes\TenantScope;
 use Illuminate\Database\Eloquent\Concerns\HasUuids;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -23,6 +24,11 @@ class Registry extends Model
 {
     use HasUuids;
 
+    protected static function booted(): void
+    {
+        static::addGlobalScope(new TenantScope);
+    }
+
     protected $fillable = ['tenant_id', 'name', 'schema_version', 'body'];
 
     /** @var array<string,string> */

app/Models/Scopes/TenantScope.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Models\Scopes;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Scope;
+
+/**
+ * Global scope that filters every query on a tenant-scoped model by
+ * the authenticated user's tenant_id.
+ *
+ * Models opt in via `static::addGlobalScope(new TenantScope)` in
+ * their `booted()` method. Currently applied on Registry and
+ * AuditLogEntry; Tenant + User are NOT scoped because:
+ *
+ * - Tenant: each user only sees their own, but lookup happens via
+ *   `auth()->user()->tenant`, not a query filter.
+ * - User: a tenant admin should see every user in their tenant, but
+ *   the auth flow (Passport bearer) already resolves to one user.
+ *
+ * When no user is authenticated (web sign-in pages, queue workers
+ * with explicit `withoutGlobalScope`), the scope is a no-op so we
+ * don't accidentally return zero rows for legitimate unscoped reads.
+ */
+class TenantScope implements Scope
+{
+    public function apply(Builder $builder, Model $model): void
+    {
+        $user = auth()->user();
+        if ($user === null) {
+            return;
+        }
+        $tenantId = $user->tenant_id ?? null;
+        if ($tenantId === null) {
+            return;
+        }
+        $builder->where(
+            $model->qualifyColumn('tenant_id'),
+            $tenantId,
+        );
+    }
+}

app/Observers/AuditLogObserver.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Observers;
+
+use App\Models\AuditLogEntry;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Records every create / update / delete on the models it's attached
+ * to into the audit_log_entries table. The actor (user_id) comes
+ * from the authenticated request; null when an unauthenticated path
+ * mutates (e.g., seeders, queue workers).
+ *
+ * Registered in AppServiceProvider::boot():
+ *
+ *   Registry::observe(AuditLogObserver::class);
+ *   Tenant::observe(AuditLogObserver::class);   // optional
+ */
+class AuditLogObserver
+{
+    public function created(Model $model): void
+    {
+        $this->record($model, 'create', null, $model->getAttributes());
+    }
+
+    public function updated(Model $model): void
+    {
+        $before = $model->getOriginal();
+        $after = $model->getAttributes();
+        $this->record($model, 'update', $before, $after);
+    }
+
+    public function deleted(Model $model): void
+    {
+        $this->record($model, 'delete', $model->getOriginal(), null);
+    }
+
+    /**
+     * @param  array<string,mixed>|null  $before
+     * @param  array<string,mixed>|null  $after
+     */
+    private function record(Model $model, string $action, ?array $before, ?array $after): void
+    {
+        $tenantId = $model->getAttribute('tenant_id');
+        if (! is_string($tenantId)) {
+            // Models without a tenant_id (Tenant itself when first
+            // created) need a different audit path; skip silently
+            // for now and surface in v0.2 when we audit Tenant ops.
+            return;
+        }
+
+        AuditLogEntry::create([
+            'tenant_id' => $tenantId,
+            'user_id' => auth()->id(),
+            'action' => $action,
+            'target_type' => $model::class,
+            'target_id' => (string) $model->getKey(),
+            'before' => $before,
+            'after' => $after,
+        ]);
+    }
+}

app/Providers/AppServiceProvider.php

@@ -2,23 +2,19 @@
 
 namespace App\Providers;
 
+use App\Models\Registry;
+use App\Observers\AuditLogObserver;
 use Illuminate\Support\ServiceProvider;
 
 class AppServiceProvider extends ServiceProvider
 {
-    /**
-     * Register any application services.
-     */
     public function register(): void
     {
         //
     }
 
-    /**
-     * Bootstrap any application services.
-     */
     public function boot(): void
     {
-        //
+        Registry::observe(AuditLogObserver::class);
     }
 }

config/auth.php

@@ -42,6 +42,10 @@
             'driver' => 'session',
             'provider' => 'users',
         ],
+        'api' => [
+            'driver' => 'passport',
+            'provider' => 'users',
+        ],
     ],
 
     /*

routes/api.php

@@ -1,8 +1,13 @@
 <?php
 
+use App\Http\Controllers\Api\V1\TenantController;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Route;
 
 Route::get('/user', function (Request $request) {
     return $request->user();
 })->middleware('auth:api');
+
+Route::middleware('auth:api')->prefix('v1')->group(function () {
+    Route::get('/tenants/me', [TenantController::class, 'me']);
+});

tests/Feature/Api/V1/TenantMeTest.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Tests\Feature\Api\V1;
+
+use App\Models\Tenant;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Laravel\Passport\Passport;
+use Tests\TestCase;
+
+class TenantMeTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_unauthenticated_request_is_rejected(): void
+    {
+        $this->getJson('/api/v1/tenants/me')->assertStatus(401);
+    }
+
+    public function test_returns_the_authenticated_user_tenant(): void
+    {
+        $tenant = Tenant::create(['slug' => 'acme', 'name' => 'Acme Inc.']);
+        $user = User::create([
+            'tenant_id' => $tenant->id,
+            'name' => 'Admin',
+            'email' => 'admin@acme.example',
+            'password' => 'hashed-not-real',
+            'role' => 'owner',
+        ]);
+
+        Passport::actingAs($user);
+
+        $this->getJson('/api/v1/tenants/me')
+            ->assertOk()
+            ->assertJson([
+                'id' => $tenant->id,
+                'slug' => 'acme',
+                'name' => 'Acme Inc.',
+            ])
+            ->assertJsonStructure(['id', 'slug', 'name', 'created_at']);
+    }
+}