README

Nemesis est un package Laravel complet pour l’authentification par tokens multi-modèles utilisant le système de Directives (CLI flexible). Contrairement à Sanctum ou Passport, Nemesis permet à n’importe quel modèle Eloquent (User, CheckPoint, ApiClient, Admin, etc.) de générer, valider et gérer ses propres tokens d’API avec une sécurité renforcée : expiration, permissions (abilities), restrictions CORS par origine, métadonnées, soft delete pour révocation, et nettoyage automatique.

📦 Installation

composer require andydefer/laravel-nemesis

Vérification de l'installation

# Lister les directives disponibles
./vendor/bin/directive --list

# Installer le package
./vendor/bin/directive install-nemesis --force

Publication manuelle des ressources (alternative)

# Configuration
php artisan vendor:publish --tag=nemesis-config

# Migrations
php artisan vendor:publish --tag=nemesis-migrations

# Exécuter les migrations
php artisan migrate

🚀 Démarrage rapide

1. Ajouter l’interface à vos modèles

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use AndyDefer\Nemesis\Contracts\MustNemesis;
use AndyDefer\DomainStructures\Abstracts\AbstractData;

class User extends Model implements MustNemesis
{
    /**
     * Définir ce qui est exposé par l'API.
     * Cette méthode est OBLIGATOIRE (imposée par l'interface).
     */
    public function nemesisFormat(): AbstractData
    {
        return new UserData(
            id: $this->id,
            name: $this->name,
            email: $this->email,
            createdAt: $this->created_at,
        );
    }
}

class CheckPoint extends Model implements MustNemesis
{
    /**
     * Format différent pour les points de contrôle.
     */
    public function nemesisFormat(): AbstractData
    {
        return new CheckPointData(
            id: $this->id,
            name: $this->name,
            location: $this->location,
            status: $this->is_active ? 'active' : 'inactive',
            lastSeen: $this->last_ping_at,
        );
    }
}

2. Créer un token

use AndyDefer\Nemesis\Records\NemesisTokenRecord;

$user = User::find(1);

$record = NemesisTokenRecord::from([
    'name' => 'Application Mobile',
    'source' => 'mobile',
    'abilities' => ['scan_ticket', 'view_stats'],
    'metadata' => ['app_version' => '2.1.0'],
]);

[$token, $plainToken] = $nemesisService->createWithPlainToken($record, $user);

// Afficher le token une seule fois
echo $plainToken; // stocker en clair côté client

3. Protéger une route

// Dans routes/api.php
use AndyDefer\Nemesis\Facades\NemesisHelper;

Route::middleware(['nemesis.token'])->group(function () {
    Route::get('/profile', function () {
        // Version formatée via le Facade
        return response()->json(NemesisHelper::getCurrentAuthenticatableFormat());
    });
});

// Avec vérification d’une ability
Route::post('/scan', function () {
    // ...
})->middleware('nemesis.token:scan_ticket');

4. Utiliser le token

GET /api/profile
Authorization: Bearer <token>

5. Utilisation du Facade NemesisHelper

use AndyDefer\Nemesis\Facades\NemesisHelper;

// Récupérer le token actuel
$token = NemesisHelper::getCurrentToken();

// Récupérer le modèle authentifié (User, CheckPoint, etc.)
$authenticatable = NemesisHelper::getCurrentAuthenticatable();

// Récupérer la version formatée (recommandée pour les APIs)
$formatted = NemesisHelper::getCurrentAuthenticatableFormat();

// Vérifier si authentifié
if (NemesisHelper::hasCurrentAuthenticatable()) {
    // ...
}

// Vérifier si un token est présent
if (NemesisHelper::hasCurrentToken()) {
    // ...
}

🎯 Révocation granulaire des tokens

Nemesis permet de révoquer sélectivement les tokens par source, nom ou critères personnalisés via le service NemesisService.

Méthodes de révocation

Filtres disponibles

$filters = new NemesisTokenFilterRecord(
    tokenable_type: 'App\\Models\\User',
    tokenable_id: 1,
    source: 'web',
    name: 'session_token',
    is_expired: true,
    is_revoked: false,
    created_before: DateTimeVO::from(now()->subDays(30)->toIso8601String()),
);

Cas d'usage concrets

1. Déconnexion de tous les navigateurs (garder l'app mobile active)

$nemesisService->revokeTokensBySource($user, 'web');

2. Révocation sélective par type de token

$nemesisService->revokeTokensBySourceAndName($user, 'web', 'web_session');
$nemesisService->revokeTokensByName($user, 'admin_token');

3. Garder un type de token actif

$nemesisService->revokeAllTokensExceptSource($user, 'api');

4. Suppression définitive (force delete)

$nemesisService->revokeTokensBySource($user, 'web', force: true);
$nemesisService->deleteAllTokens($user, force: true);

5. Nettoyage par filtres avancés

$filter = new NemesisTokenFilterRecord(
    created_before: DateTimeVO::from(now()->subDays(30)->toIso8601String()),
);
$nemesisService->forceDeleteBulk($filter);

🛡️ Sécurité multi-origines (CORS)

Nemesis permet de restreindre un token à des origines spécifiques.

$nemesisService->addAllowedOrigin($token, 'https://monapp.com');
$nemesisService->addAllowedOrigin($token, 'https://*.example.com'); // wildcard

// Vérification
if ($nemesisService->canUseFromOrigin($token, 'https://monapp.com')) {
    // origine autorisée
}

🔑 Système d’abilities (permissions fines)

Chaque token peut avoir une liste d’abilities.

// Création avec abilities
$record = NemesisTokenRecord::from([
    'name' => 'Scanner Billeterie',
    'source' => 'kiosk',
    'abilities' => ['scan_ticket', 'validate_entry'],
]);

// Vérifier une ability
if ($nemesisService->can($token, 'scan_ticket')) {
    // autorisé
}

Utilisation en middleware :

Route::post('/validate', fn() => ...)
    ->middleware('nemesis.token:validate_entry');

📦 Métadonnées enrichies

Stockez des informations contextuelles avec validation automatique (taille max 64KB, profondeur max 5, max 100 clés).

$record = NemesisTokenRecord::from([
    'name' => 'API Session',
    'metadata' => [
        'device' => 'iPhone 15',
        'os' => 'iOS 17',
        'location' => 'Paris',
        'preferences' => ['lang' => 'fr']
    ],
]);

// Modifier après création
$nemesisService->setMetadata($token, 'last_login_ip', '192.168.1.1');
$ip = $nemesisService->getMetadata($token, 'last_login_ip');
$nemesisService->mergeMetadata($token, ['new_key' => 'value']);

🧹 Nettoyage automatique des tokens expirés

Configuration dans config/nemesis.php :

'cleanup' => [
    'auto_cleanup' => true,       // nettoyage auto par schedule
    'frequency' => 60,            // toutes les heures
    'keep_expired_for_days' => 30, // garder 30 jours pour audit
],

Directive manuelle :

./vendor/bin/directive clean-tokens --force
./vendor/bin/directive clean-tokens --days=15
./vendor/bin/directive clean-tokens --keep-expired
./vendor/bin/directive nemesis-clean --force  # alias

📋 Directives disponibles

# Lister les directives Nemesis
./vendor/bin/directive --list | grep -E "nemesis|token|clean"

# Aide sur une directive
./vendor/bin/directive help clean-tokens

🔗 Scénario concret : Billeterie avec User et CheckPoint

Modèles

// User (client billetterie)
class User extends Model implements MustNemesis
{
    public function nemesisFormat(): UserData
    {
        return new UserData(
            id: $this->id,
            name: $this->name,
            email: $this->email,
        );
    }
}

// CheckPoint (point de contrôle physique)
class CheckPoint extends Model implements MustNemesis
{
    public function nemesisFormat(): CheckPointData
    {
        return new CheckPointData(
            id: $this->id,
            name: $this->name,
            location: $this->location,
            status: $this->is_active ? 'active' : 'inactive',
        );
    }
}

Création des tokens

// Pour un utilisateur (application mobile)
$record = NemesisTokenRecord::from([
    'name' => 'App Mobile Client',
    'source' => 'mobile',
    'abilities' => ['buy_ticket', 'view_tickets'],
]);
[$token, $plainToken] = $nemesisService->createWithPlainToken($record, $user);

// Pour un point de contrôle (kiosque)
$record = NemesisTokenRecord::from([
    'name' => 'Scanner Portique',
    'source' => 'kiosk',
    'abilities' => ['scan_ticket', 'validate_entry', 'reject_entry'],
    'metadata' => ['hardware_id' => 'SCAN-01', 'location' => 'Entrée A'],
]);
[$token, $plainToken] = $nemesisService->createWithPlainToken($record, $checkpoint);

Routes protégées

Route::middleware('nemesis.token:buy_ticket')->post('/tickets', [TicketController::class, 'buy']);
Route::middleware('nemesis.token:scan_ticket')->post('/scan', [ScanController::class, 'validate']);

Dans ScanController

use AndyDefer\Nemesis\Facades\NemesisHelper;

public function validate(Request $request)
{
    $checkpoint = NemesisHelper::getCurrentAuthenticatable(); // instance de CheckPoint
    $token = NemesisHelper::getCurrentToken();

    if (!$token || !$nemesisService->can($token, 'validate_entry')) {
        return response()->json(['error' => 'Permission refusée'], 403);
    }

    // scanner le billet...
    return response()->json([
        'status' => 'entrée validée',
        'checkpoint' => NemesisHelper::getCurrentAuthenticatableFormat()
    ]);
}

Révocation depuis le point de contrôle

use AndyDefer\Nemesis\Facades\NemesisHelper;

public function logoutCheckPoint()
{
    $token = NemesisHelper::getCurrentToken();
    
    if ($token && $nemesisService->revoke($token)) {
        return response()->json(['message' => 'Token révoqué avec succès']);
    }
    
    return response()->json(['error' => 'Aucun token actif trouvé'], 404);
}

📊 API complète du service

NemesisService

NemesisHelper (Facade)

⚙️ Configuration (config/nemesis.php)

return [
    // Génération des tokens
    'token_length' => 64,
    'hash_algorithm' => 'sha256',
    'expiration' => 60, // null = jamais, sinon minutes

    // Middleware
    'middleware' => [
        'parameter_name' => 'nemesis_auth',
        'token_header' => 'Authorization',
        'security_headers' => true,
        'validate_origin' => true,
    ],

    // CORS
    'cors' => [
        'allow_credentials' => true,
        'max_age' => 86400,
        'expose_token_info' => false,
    ],

    // Nettoyage
    'cleanup' => [
        'auto_cleanup' => true,
        'frequency' => 60,
        'keep_expired_for_days' => 30,
    ],
];

📁 Structure des migrations

CREATE TABLE nemesis_tokens (
    id BIGINT PRIMARY KEY,
    token_hash VARCHAR(255) UNIQUE NOT NULL,
    tokenable_type VARCHAR(255) NOT NULL,
    tokenable_id BIGINT NOT NULL,
    name VARCHAR(255) NULL,
    source VARCHAR(255) NULL,
    abilities TEXT NULL,           -- JSON
    metadata TEXT NULL,            -- JSON
    allowed_origins TEXT NULL,     -- JSON
    last_used_at TIMESTAMP NULL,
    expires_at TIMESTAMP NULL,
    deleted_at TIMESTAMP NULL,     -- Soft delete
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,
    
    INDEX idx_tokenable (tokenable_type, tokenable_id),
    INDEX idx_expires_at (expires_at),
    INDEX idx_source (source),
    INDEX idx_last_used (last_used_at),
    UNIQUE INDEX idx_token_hash (token_hash)
);

🧠 Ce que Nemesis résout concrètement

🔄 Comparaison rapide avec Laravel Sanctum

🧪 Tests

# Exécuter tous les tests
./vendor/bin/phpunit

# Exécuter les tests d'une directive
./vendor/bin/phpunit --filter CleanTokensDirectiveTest

# Exécuter les tests en mode debug
./vendor/bin/phpunit --debug --filter Unit

🤝 Contribution

1. Fork + branche feature/ma-fonctionnalité
2. composer test (246 tests doivent passer)
3. Pull request vers main

📄 Licence

MIT © andydefer

---