README

Package Laravel plug-and-play pour les projets API.
Installez-le et tout est prêt : authentification, profil, réinitialisation OTP, rôles, et logs d'activité.

📦 Fonctionnalités

🚀 Installation

1. Ajouter le package

composer require s3tech/laravel-auth-kit

En développement local (path repository) :

"repositories": [{ "type": "path", "url": "../laravel-auth-kit" }],
"require": { "s3tech/laravel-auth-kit": "*" }

2. Publier la configuration

php artisan vendor:publish --tag=auth-kit-config

3. Publier et exécuter les migrations

# Sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

# Spatie
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

# Auth Kit
php artisan vendor:publish --tag=auth-kit-migrations

php artisan migrate

4. Configurer le modèle User

<?php
// app/Models/User.php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;
use Spatie\Permission\Traits\HasRoles;
use S3Tech\AuthKit\Traits\HasAuthKit;

class User extends Authenticatable
{
    use HasApiTokens, HasRoles, HasAuthKit;

    protected $fillable = ['first_name', 'last_name', 'phone', 'email', 'password', 'must_change_password', 'status'];

    protected $hidden = ['password', 'remember_token'];
}

5. Guard Sanctum pour Spatie

Dans config/permission.php :

'guard_name' => 'sanctum',

Dans config/auth.php, s'assurer que le guard existe :

'guards' => [
    'sanctum' => ['driver' => 'sanctum', 'provider' => 'users'],
],

6. Créer le seeder de rôles initiaux

// database/seeders/RoleSeeder.php
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;

// Rôles
Role::firstOrCreate(['name' => 'super-admin', 'guard_name' => 'sanctum']);
Role::firstOrCreate(['name' => 'manager',     'guard_name' => 'sanctum']);
Role::firstOrCreate(['name' => 'user',        'guard_name' => 'sanctum']);

// Permissions
$permissions = ['manage-roles', 'create-user', 'update-user'];
foreach ($permissions as $perm) {
    Permission::firstOrCreate(['name' => $perm, 'guard_name' => 'sanctum']);
}

// Assigner toutes les permissions au super-admin
Role::findByName('super-admin', 'sanctum')->givePermissionTo($permissions);

⚙️ Configuration (config/auth-kit.php)

return [
    'route_prefix'     => 'api',
    'route_middleware' => ['api'],
    'user_model'       => \App\Models\User::class,

    'token' => ['name' => 'auth_token'],

    'otp' => [
        'length'     => 6,
        'expires_in' => 10,  // minutes
    ],

    'password_rules' => ['min:8'],

    'messages' => [
        'default_locale' => 'en',
        'supported_locales' => ['en', 'fr'],
    ],

    'registration' => [
        'mode'         => 'self',   // 'self' | 'admin'  — mutuellement exclusifs
        'default_role' => 'user',
    ],

    'profile' => [
        // Champs modifiables via PUT /profile et PUT /users/{user}
        // Ajouter 'phone', 'avatar'… selon votre table users
        'editable_fields' => ['first_name', 'last_name', 'email', 'phone'],
    ],

    'activity_log' => [
        'enabled'        => true,
        'retention_days' => 90,     // null = indéfini
        'log_events'     => [
            'register'           => true,
            'login'              => true,
            'logout'             => true,
            'login_failed'       => true,
            'profile_updated'    => true,
            'password_changed'   => true,
            'password_reset'     => true,
            'otp_requested'      => true,
            'admin_created_user' => true,
            'role_assigned'      => true,
            'role_revoked'       => true,
        ],
    ],

    'permissions' => [
        'manage_roles'      => 'manage-roles',
        'create_user'       => 'create-user',
        'update_other_user' => 'update-user',
    ],
];

🌍 Messages API bilingues

Toutes les réponses textuelles du package sont maintenant bilingues anglais/français.

• message ou error retourne la langue résolue
• l'anglais est utilisé par défaut
• message_translations ou error_translations expose les versions en et fr
• les erreurs de validation des FormRequest suivent aussi ce fonctionnement
• errors retourne les messages de validation dans la langue résolue
• errors_translations expose les variantes en et fr

Ordre de résolution de la langue :

1. Header X-Auth-Kit-Locale
2. Query string ?lang=fr
3. Header Accept-Language
4. config('auth-kit.messages.default_locale')

Exemple de réponse succès :

{
  "message": "Role 'manager' assigned to user #12.",
  "locale": "en",
  "message_translations": {
    "en": "Role 'manager' assigned to user #12.",
    "fr": "Rôle 'manager' assigné à l'utilisateur #12."
  }
}

Exemple pour forcer le français :

POST /api/users/12/roles?lang=fr
X-Auth-Kit-Locale: fr

Exemple de réponse de validation :

{
  "error": "Les donnees fournies sont invalides.",
  "locale": "fr",
  "error_translations": {
    "en": "The given data was invalid.",
    "fr": "Les donnees fournies sont invalides."
  },
  "errors": {
    "email": [
      "Le champ adresse e-mail est obligatoire."
    ]
  },
  "errors_translations": {
    "en": {
      "email": [
        "The email address field is required."
      ]
    },
    "fr": {
      "email": [
        "Le champ adresse e-mail est obligatoire."
      ]
    }
  }
}

🛣️ Routes disponibles

Publiques

Protégées (auth:sanctum)

Administration rôles (permission manage-roles)

🔌 Modes de déconnexion

// Session courante uniquement (défaut)
{ "mode": "current" }

// Une session précise (visible via GET /auth/sessions)
{ "mode": "specific", "token_id": 12 }

// Toutes les sessions (déconnexion totale)
{ "mode": "all" }

👤 Modes d'inscription

Mode self (défaut)

L'utilisateur s'inscrit via POST /api/auth/register avec son propre mot de passe. La route est publique.

Mode admin

• POST /api/auth/register est désactivée
• Seul un utilisateur avec la permission create-user peut créer des comptes via POST /api/users
• Un mot de passe temporaire est généré et envoyé par email
• L'utilisateur devra changer son mot de passe à la première connexion (must_change_password = true)

📊 Logs d'activité

Données collectées par action

{
  "id": 42,
  "user_id": 7,
  "event": "profile_updated",
  "action": "update",
  "subject_type": "App\\Models\\User",
  "subject_id": 12,
  "subject": {
    "type": "App\\Models\\User",
    "id": 12,
    "label": "Jane Doe"
  },
  "ip_address": "41.82.12.45",
  "device_type": "mobile",
  "device_name": "Android — Chrome",
  "browser": "Chrome",
  "os": "Android",
  "country": "Senegal",
  "country_code": "SN",
  "region": "Dakar",
  "city": "Dakar",
  "latitude": 14.6928,
  "longitude": -17.4467,
  "metadata": null,
  "created_at": "2024-11-20T14:32:11.000000Z"
}

Vous pouvez aussi journaliser n'importe quel modèle Eloquent de votre application comme ressource cible:

$this->logger->log($request, 'budget_updated', auth()->id(), 'update', $budget, [
    'updated_fields' => ['amount', 'status'],
]);

Dans ce cas, la liste des logs retournera automatiquement subject_type, subject_id et un objet subject compact pour identifier la ressource concernée (Budget, Project, Invoice, etc.).

Filtres disponibles (query string)

GET /api/activity-logs?event=login&from=2024-01-01&to=2024-12-31&per_page=50

🏗️ Arborescence du package

laravel-auth-kit/
├── composer.json
├── README.md
├── database/
│   └── migrations/
│       ├── ..._create_password_reset_otps_table.php
│       └── ..._create_activity_logs_table.php
├── resources/
│   └── views/emails/
│       ├── otp.blade.php                    Email code OTP
│       └── temporary-password.blade.php     Email mot de passe temporaire (mode admin)
└── src/
    ├── AuthKitServiceProvider.php
    ├── Config/
    │   └── auth-kit.php
    ├── Http/
    │   ├── Controllers/
    │   │   ├── AuthController.php           login, register, logout, me, sessions, adminCreateUser
    │   │   ├── ProfileController.php        updateOwnProfile, updateOwnPassword, updateUserProfile
    │   │   ├── PasswordResetController.php  sendOtp, verifyOtp, resetPassword
    │   │   ├── RolePermissionController.php CRUD rôles/permissions + assignations
    │   │   └── ActivityLogController.php    myLogs, userLogs, allLogs
    │   ├── Requests/
    │   │   ├── LoginRequest.php
    │   │   ├── RegisterRequest.php
    │   │   ├── AdminCreateUserRequest.php
    │   │   ├── UpdateProfileRequest.php
    │   │   ├── AdminUpdateUserProfileRequest.php
    │   │   ├── UpdatePasswordRequest.php
    │   │   └── ResetPasswordRequest.php
    │   └── Resources/
    │       └── UserResource.php
    ├── Mail/
    │   ├── OtpMail.php
    │   └── TemporaryPasswordMail.php
    ├── Models/
    │   ├── PasswordResetOtp.php
    │   └── ActivityLog.php
    ├── Routes/
    │   └── api.php
    ├── Services/
    │   └── ActivityLogService.php           Cœur du système de logs
    └── Traits/
        └── HasAuthKit.php                   À ajouter sur App\Models\User

📄 Licence

MIT