feat: P2 RBAC defers — REST API + invitation workflow

Closes the P2 items from /tmp/service/new/01-TZ-rbac §4.1 §4.2.

== User invitation workflow ==

New columns on users: invited_at, invited_by_id (FK self), accepted_at,
invitation_token (sha256 hash, indexed). Migration is idempotent.

User::sendInvitation($invitedBy = auth()->user())
  - generates 64-char random token
  - stores sha256(token) in invitation_token column (never plaintext)
  - marks invited_at = now(), status = inactive
  - queues UserInvitationMail to the user's email with the signed accept URL
  - returns the raw token (for tests / API consumers)

User::findByInvitationToken($rawToken) hashes + lookups.
User::acceptInvitation($password) sets password (hashed cast), clears
invitation_token, marks accepted_at + email_verified_at, status = active.

Web routes (no auth — token IS the credential):
  GET  /invitations/{token}  → password-set form
  POST /invitations/{token}  → validates min:8 + confirmed, accepts

Tokens expire after 7 days (checked against invited_at). Expired and
invalid tokens render dedicated views (invitations/expired.blade.php,
invitations/invalid.blade.php) instead of generic 404 — so the user
knows to ask for a resend.

UserInvitationMail uses Filament's existing markdown layout; subject
includes the tenant display_name.

== REST API ==

Twenty new endpoints under /api/v1/ (Sanctum auth + tenant scoping
via the existing EnsureTokenMatchesTenant middleware). All gated by
ADMIN_USERS_* / ADMIN_ROLES_MANAGE permissions; mechanic-level token
gets 403.

Users:
  GET    /users                                  — paginated + role/status/q filters
  GET    /users/{u}                              — eager-loads roles + overrides + invitedBy
  POST   /users                                  — creates inactive user + sends invitation
  PATCH  /users/{u}                              — update name/email/role/status
  DELETE /users/{u}                              — soft delete
  POST   /users/{u}/activate
  POST   /users/{u}/deactivate                   — also revokes all sessions
  POST   /users/{u}/resend-invitation
  POST   /users/{u}/force-password-reset         — re-sends invitation
  GET    /users/{u}/sessions                     — list active sessions (from sessions table)
  DELETE /users/{u}/sessions                     — revoke all
  DELETE /users/{u}/sessions/{sessionId}         — revoke one
  GET    /users/{u}/roles                        — assigned roles
  POST   /users/{u}/roles                        — assign role
  DELETE /users/{u}/roles/{role}                 — remove role
  GET    /users/{u}/permissions                  — effective: role perms + grants - active denies
  POST   /users/{u}/permission-overrides         — add grant/deny (with optional expires_at)
  DELETE /users/{u}/permission-overrides/{perm}

Roles:
  apiResource roles                              — index/show/store/update/destroy
                                                   (system roles guarded against rename/delete)
  GET    /roles/{r}/permissions
  PUT    /roles/{r}/permissions                  — bulk sync
  GET    /permissions                            — catalog: flat list + grouped + labels + role labels

Authorization is uniform: every controller method calls $this->authorize()
which throws 403 if canDo(perm) is false. canDo() already honors the
overrides + admin bypass + audit log from earlier commits, so the API
behaves identically to the Filament UI.

== Tests ==

InvitationFlowTest (8): token generation + sha256 storage + queued mail,
findByInvitationToken happy/sad path, accept sets password + activates,
GET form renders, POST accepts + redirects, invalid token view,
backdated invited_at → expired view, password too short → validation error.

RbacApiTest (12): admin can list users, mechanic 403, create user
queues invitation, assign+remove role round-trip, effective permissions
endpoint subtracts active denies, add+remove override via API,
role index returns 7 system roles with permission counts (51 for owner),
role sync permissions, system role destroy rejected with 422,
permission catalog endpoint returns all 51 + grouped + labels,
revoke all sessions deletes only target user's rows.

Suite: 234 passed (659 assertions). Was 214.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/Models/Tenant/User.php

@@ -35,6 +35,7 @@ class User extends Authenticatable implements FilamentUser, HasAppAuthentication
         'email_verified_at', 'password', 'last_login_at',
         'email_authentication_at',
         'app_authentication_secret', 'app_authentication_recovery_codes',
+        'invited_at', 'invited_by_id', 'accepted_at', 'invitation_token',
     ];
 
     protected $hidden = [
@@ -47,6 +48,8 @@ class User extends Authenticatable implements FilamentUser, HasAppAuthentication
             'email_verified_at' => 'datetime',
             'last_login_at' => 'datetime',
             'email_authentication_at' => 'datetime',
+            'invited_at' => 'datetime',
+            'accepted_at' => 'datetime',
             'password' => 'hashed',
             'app_authentication_secret' => 'encrypted',
             'app_authentication_recovery_codes' => 'encrypted:array',
@@ -84,6 +87,16 @@ class User extends Authenticatable implements FilamentUser, HasAppAuthentication
         return $this->hasMany(UserPermissionOverride::class);
     }
 
+    public function invitedBy(): \Illuminate\Database\Eloquent\Relations\BelongsTo
+    {
+        return $this->belongsTo(self::class, 'invited_by_id');
+    }
+
+    public function company(): \Illuminate\Database\Eloquent\Relations\BelongsTo
+    {
+        return $this->belongsTo(\App\Models\Central\Company::class);
+    }
+
     /**
      * Permission check honoring (in order):
      *   1. Active deny-override → false
@@ -150,6 +163,50 @@ class User extends Authenticatable implements FilamentUser, HasAppAuthentication
         return $this->app_authentication_secret !== null;
     }
 
+    /** Pending invitation (sent but not yet accepted). */
+    public function isPendingInvitation(): bool
+    {
+        return $this->invited_at !== null && $this->accepted_at === null;
+    }
+
+    /**
+     * Create + send an invitation: generates a random token, marks invited_at,
+     * and queues the email with the signed accept link. Idempotent — calling
+     * again regenerates the token (useful for "resend invitation").
+     */
+    public function sendInvitation(?User $invitedBy = null): string
+    {
+        $token = bin2hex(random_bytes(32));   // 64 chars
+        $this->forceFill([
+            'invitation_token' => hash('sha256', $token),
+            'invited_at' => now(),
+            'invited_by_id' => $invitedBy?->id ?? auth()->id(),
+            'accepted_at' => null,
+            'status' => 'inactive',  // can't login until accepted
+        ])->saveQuietly();
+
+        \Illuminate\Support\Facades\Mail::to($this->email)
+            ->queue(new \App\Mail\UserInvitationMail($this, $token));
+
+        return $token;   // returned mainly for tests / API
+    }
+
+    public static function findByInvitationToken(string $rawToken): ?self
+    {
+        return self::where('invitation_token', hash('sha256', $rawToken))->first();
+    }
+
+    public function acceptInvitation(string $password): void
+    {
+        $this->forceFill([
+            'password' => $password,    // hashed cast handles it
+            'invitation_token' => null,
+            'accepted_at' => now(),
+            'status' => 'active',
+            'email_verified_at' => now(),
+        ])->save();
+    }
+
     public function hasEmailAuthentication(): bool
     {
         return $this->email_authentication_at !== null;