feat: Passport (OAuth) + multi-tenant data model + first models

INITIALIZE.md steps 2 + 4 land:

**Passport** (step 2):
- composer require laravel/passport
- php artisan install:api --passport (OAuth client tables + routes)
- php artisan passport:keys (RSA keypair in storage/)
- User model gets the HasApiTokens trait

**Multi-tenant data model** (step 4):
- Tenant model + migration: uuid pk, slug (unique), name, timestamps.
  Each Tenant owns Users, Registries, AuditLogEntries.
- Registry model + migration: uuid pk, tenant_id FK (cascadeOnDelete),
  name, schema_version (default 1), body (JSON cast to array),
  unique (tenant_id, name).
- AuditLogEntry model + migration: uuid pk, tenant_id FK, user_id
  FK (nullable, nullOnDelete), action enum (create|update|delete),
  target_type + target_id (polymorphic-ish), before/after JSON.
  Append-only: `const UPDATED_AT = null`.
- User model + migration update: tenant_id FK (nullable for now —
  the first seeded admin pre-exists the first tenant), oauth_subject
  (indexed), role enum (owner|admin|editor|viewer, default viewer).

Indexes on audit_log_entries (tenant_id, created_at) and
(tenant_id, target_type, target_id) for fast tenant-scoped reads.

5 new feature tests (7 total): tenant UUID generation, tenant
relationships (registries + users), registry body round-trips as
array (the JSON cast), audit-log before/after persistence,
audit-log tenant relationship.

Next: AuditLogObserver (records every Registry mutation
automatically), TenantScope global scope on each model, first
controller for /api/v1/tenants/me per docs/api/v1.yaml.

Author: imanimanyara

app/Models/AuditLogEntry.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * One row per tenant-scoped mutation. Append-only; never deleted.
+ *
+ * Created by the AuditLogObserver when a Registry / Tenant is
+ * created / updated / deleted (observer lives in
+ * App\Observers\AuditLogObserver, registered in AppServiceProvider).
+ *
+ * @property string                    $id
+ * @property string                    $tenant_id
+ * @property int|null                  $user_id
+ * @property string                    $action       create|update|delete
+ * @property string                    $target_type
+ * @property string                    $target_id
+ * @property array<string,mixed>|null  $before
+ * @property array<string,mixed>|null  $after
+ */
+class AuditLogEntry extends Model
+{
+    use HasUuids;
+
+    /**
+     * Audit log is append-only: it has no `updated_at` semantic; the
+     * record is immutable from creation. We still let Laravel manage
+     * `created_at` via timestamps but never expose an update path.
+     */
+    public const UPDATED_AT = null;
+
+    protected $fillable = [
+        'tenant_id', 'user_id', 'action',
+        'target_type', 'target_id',
+        'before', 'after',
+    ];
+
+    /** @var array<string,string> */
+    protected $casts = [
+        'before' => 'array',
+        'after' => 'array',
+    ];
+
+    /** @return BelongsTo<Tenant, $this> */
+    public function tenant(): BelongsTo
+    {
+        return $this->belongsTo(Tenant::class);
+    }
+
+    /** @return BelongsTo<User, $this> */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+}

app/Models/Registry.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * A get-installer registry owned by one Tenant.
+ *
+ * `body` holds the full registry.json payload; the controller layer
+ * validates it against the get-installer registry.schema.json before
+ * persisting.
+ *
+ * @property string $id
+ * @property string $tenant_id
+ * @property string $name
+ * @property int    $schema_version
+ * @property array<string,mixed> $body
+ */
+class Registry extends Model
+{
+    use HasUuids;
+
+    protected $fillable = ['tenant_id', 'name', 'schema_version', 'body'];
+
+    /** @var array<string,string> */
+    protected $casts = [
+        'body' => 'array',
+        'schema_version' => 'integer',
+    ];
+
+    /** @return BelongsTo<Tenant, $this> */
+    public function tenant(): BelongsTo
+    {
+        return $this->belongsTo(Tenant::class);
+    }
+}

app/Models/Tenant.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * One Tenant per organisation. Holds Users, Registries, and the
+ * AuditLogEntries that record every mutation in that org's scope.
+ *
+ * Resolved per-request by the TenantScope middleware:
+ * `auth()->user()?->tenant`. Models filtered by global scope (see
+ * Registry::booted + AuditLogEntry::booted).
+ *
+ * @property string $id
+ * @property string $slug
+ * @property string $name
+ */
+class Tenant extends Model
+{
+    use HasUuids;
+
+    protected $fillable = ['slug', 'name'];
+
+    /** @return HasMany<User, $this> */
+    public function users(): HasMany
+    {
+        return $this->hasMany(User::class);
+    }
+
+    /** @return HasMany<Registry, $this> */
+    public function registries(): HasMany
+    {
+        return $this->hasMany(Registry::class);
+    }
+
+    /** @return HasMany<AuditLogEntry, $this> */
+    public function auditLog(): HasMany
+    {
+        return $this->hasMany(AuditLogEntry::class);
+    }
+}

app/Models/User.php

@@ -5,25 +5,41 @@
 // use Illuminate\Contracts\Auth\MustVerifyEmail;
 use Database\Factories\UserFactory;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
+use Laravel\Passport\HasApiTokens;
 
+/**
+ * @property string|null $tenant_id
+ * @property string|null $oauth_subject
+ * @property string $role  owner|admin|editor|viewer
+ */
 class User extends Authenticatable
 {
     /** @use HasFactory<UserFactory> */
-    use HasFactory, Notifiable;
+    use HasApiTokens, HasFactory, Notifiable;
 
     /**
      * The attributes that are mass assignable.
      *
      * @var list<string>
      */
     protected $fillable = [
+        'tenant_id',
         'name',
         'email',
         'password',
+        'oauth_subject',
+        'role',
     ];
 
+    /** @return BelongsTo<Tenant, $this> */
+    public function tenant(): BelongsTo
+    {
+        return $this->belongsTo(Tenant::class);
+    }
+
     /**
      * The attributes that should be hidden for serialization.
      *

bootstrap/app.php

@@ -7,6 +7,7 @@
 return Application::configure(basePath: dirname(__DIR__))
     ->withRouting(
         web: __DIR__.'/../routes/web.php',
+        api: __DIR__.'/../routes/api.php',
         commands: __DIR__.'/../routes/console.php',
         health: '/up',
     )

composer.json

@@ -20,6 +20,7 @@
     "require": {
         "php": "^8.2",
         "laravel/framework": "^12.0",
+        "laravel/passport": "^13.0",
         "laravel/tinker": "^2.10.1"
     },
     "require-dev": {