diff --git a/docs/superpowers/plans/2026-06-19-lst-57-rbac-fin.md b/docs/superpowers/plans/2026-06-19-lst-57-rbac-fin.md new file mode 100644 index 0000000..b3c6842 --- /dev/null +++ b/docs/superpowers/plans/2026-06-19-lst-57-rbac-fin.md @@ -0,0 +1,1690 @@ +# RBAC fin (LST-57 / 1.2) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Porter le RBAC fin de Starseed dans le Module Core de Lesstime : permissions `module.resource[.sub].action`, entités `Role`/`Permission`, commande de synchronisation, `PermissionVoter`, sidebar filtrée par permission, et gestion front des rôles. + +**Architecture:** RBAC **additif** par-dessus l'auth Symfony existante (cf. Décision 1). On garde la colonne JSON `roles` + `ROLE_ADMIN`/`ROLE_USER` (login/JWT/MCP/sidebar #62 inchangés ; `ROLE_ADMIN` = bypass du voter) et on ajoute la couche RBAC fine : `Role`/`Permission` (Module Core), relations `rbacRoles`/`directPermissions` sur `User`, `getEffectivePermissions()`, `PermissionVoter`, `app:sync-permissions`, `app:seed-rbac`, sidebar gated par permission, front `usePermissions`. + +**Tech Stack:** PHP 8.4 / Symfony 8 / API Platform 4 / Doctrine ORM / PostgreSQL 16 — Nuxt 4 / Vue 3 / Pinia / TypeScript. Tests : PHPUnit 13. Docker : `php-lesstime-fpm` (user `www-data`), nginx port 8082, PG port 5435. + +## Global Constraints + +- `declare(strict_types=1)` en tête de tout fichier PHP. Symfony + PSR-12, hook pre-commit php-cs-fixer (ne pas lutter contre le reformat). +- Namespaces : back `App\Module\Core\...`, `App\Shared\...`. Front layer `frontend/modules/core/`. +- **Zéro régression auth** : après chaque phase touchant la sécurité (C, D, F), exécuter le bloc « Vérification login » ci-dessous → `login=204`, `/api/me=200`, `/_mcp=200`. +- **Migration additive uniquement** : `CREATE TABLE` des tables RBAC ; **aucun** `DROP`/`ALTER` destructif sur `user`/`roles`. `doctrine:migrations:diff` après doit être vide (hors dérive préexistante `messenger_messages`). +- PostgreSQL : noms de colonnes en minuscules dans le SQL brut ; `roles::text LIKE` pour les colonnes JSON. +- `config/reference.php` est auto-généré : **ne jamais le committer**. Untracked `.codex`, `bulettins/` : ignorer. +- Aucune mention de Claude/IA dans les commits. +- Commits : `(core) : ` (espace autour du `:`). +- Tests existants au départ : **120 verts**. Chaque phase ajoute ses tests et garde l'ensemble vert. + +## Vérification login (à exécuter après chaque phase back touchant User/sécurité) + +```bash +curl -s -i -X POST http://localhost:8082/api/login_check -H "Content-Type: application/json" -d '{"username":"alice","password":"alice"}' -D /tmp/h.txt -o /dev/null -w "login=%{http_code}\n" +BEARER=$(grep -i 'set-cookie: BEARER' /tmp/h.txt | sed -E 's/.*BEARER=([^;]+);.*/\1/') +curl -s -o /dev/null -w "me=%{http_code}\n" http://localhost:8082/api/me -H "Cookie: BEARER=$BEARER" +curl -s -o /dev/null -w "mcp=%{http_code}\n" -X POST http://localhost:8082/_mcp -H "Authorization: Bearer dev-mcp-token-for-testing-only-do-not-use-in-production" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}' +``` +Attendu : `login=204`, `me=200`, `mcp=200`. + +## Décisions de conception (actées, à valider PO a posteriori) + +1. **RBAC additif, `ROLE_ADMIN` = bypass (PAS de colonne `is_admin`)** — divergence assumée vs Starseed (qui a supprimé la colonne JSON `roles` au profit de `is_admin`). Justification : login/JWT, `security.yaml` (`role_hierarchy`, `app_user_provider`), gate sidebar #62 (`roles: [ROLE_ADMIN]`), MCP `apiToken` reposent tous sur `getRoles()`/`roles` JSON ; les réécrire = régression auth à haut risque pour zéro bénéfice AC. On garde `getRoles()` tel quel ; le `PermissionVoter` bypass si `in_array('ROLE_ADMIN', $user->getRoles())`. Migration future vers `is_admin` possible si le PO le souhaite. +2. **`user_permission` (directPermissions) inclus** — fidélité Starseed : un user peut recevoir des permissions directes en plus de ses rôles. `getEffectivePermissions()` = union(rôles.permissions, directPermissions). +3. **Gestion de `ROLE_ADMIN` reste sur le PATCH user existant (`roles`), PAS sur l'endpoint RBAC** — l'endpoint `/api/users/{id}/rbac` ne gère que `rbacRoles` + `directPermissions`. Pas de gardes « dernier admin »/« auto-suicide » (elles concernent `is_admin`, absent ici) ; on conserve uniquement la garde anti-écrasement des collections (defense in depth). +4. **Pas de rôles métier seedés en 1.2** — seules les permissions `core.*` existent (les modules métier arrivent en 2.x). `app:seed-rbac` crée les rôles système `admin` et `user` (isSystem=true) sans matrice métier. Chaque module métier ajoutera ses permissions + (optionnel) ses rôles quand il sera livré. +5. **Pas de `Sites`** — Lesstime n'a pas de notion de site : on retire toutes les gardes/relations `sites.*`, `currentSite`, `bypass_scope` du portage Starseed. +6. **Entités `Role`/`Permission` sans Timestampable/Blamable** — alignées sur Starseed (métadonnées RBAC pures). + +--- + +## Phase A — Domaine RBAC : entités, relations, migration + +### Task 1: Entités `Permission` + `Role` + relations `User` + repositories + contrat + +**Files:** +- Create: `src/Module/Core/Domain/Entity/Permission.php` +- Create: `src/Module/Core/Domain/Entity/Role.php` +- Create: `src/Module/Core/Domain/Repository/PermissionRepositoryInterface.php` +- Create: `src/Module/Core/Domain/Repository/RoleRepositoryInterface.php` +- Create: `src/Module/Core/Infrastructure/Doctrine/DoctrinePermissionRepository.php` +- Create: `src/Module/Core/Infrastructure/Doctrine/DoctrineRoleRepository.php` +- Modify: `src/Module/Core/Domain/Entity/User.php` (relations `rbacRoles` + `directPermissions` + `getEffectivePermissions()`) +- Modify: `src/Shared/Domain/Contract/UserInterface.php` (ajout `getEffectivePermissions()`) +- Modify: `config/services.yaml` (alias repositories) +- Create: `tests/Unit/Module/Core/Domain/Entity/PermissionTest.php` +- Create: `tests/Unit/Module/Core/Domain/Entity/RoleTest.php` +- Modify: `tests/Unit/Shared/Doctrine/TimestampableBlamableSubscriberTest.php` (stub `getEffectivePermissions()` dans l'anonyme implémentant `UserInterface`) + +**Interfaces:** +- Produces : `Permission { getId, getCode, getLabel, getModule, isOrphan, markOrphan(), revive(label, module), updateMetadata(label, module) }` ; `Role { getId, getCode, getLabel, getDescription, isSystem, getPermissions(): Collection, addPermission(Permission), removePermission(Permission), ensureDeletable() }` ; `User::getEffectivePermissions(): list`, `User::getRbacRoles(): Collection`, `addRbacRole`/`removeRbacRole`, `getDirectPermissions(): Collection`, `addDirectPermission`/`removeDirectPermission`. +- Repositories : `PermissionRepositoryInterface { findById(int): ?Permission, findByCode(string): ?Permission, findAll(): list, findAllCodes(): list, save(Permission): void }` ; `RoleRepositoryInterface { findById(int): ?Role, findByCode(string): ?Role, findAll(): list, save(Role): void }`. + +- [ ] **Step 1: Écrire les tests unitaires des entités** + +`tests/Unit/Module/Core/Domain/Entity/PermissionTest.php` : +```php +getCode()); + self::assertSame('Voir les utilisateurs', $p->getLabel()); + self::assertSame('core', $p->getModule()); + self::assertFalse($p->isOrphan()); + } + + public function testCodeMustContainADot(): void + { + $this->expectException(\InvalidArgumentException::class); + new Permission('coreusersview', 'x', 'core'); + } + + public function testCodeCannotBeEmpty(): void + { + $this->expectException(\InvalidArgumentException::class); + new Permission('', 'x', 'core'); + } + + public function testLabelCannotBeEmpty(): void + { + $this->expectException(\InvalidArgumentException::class); + new Permission('core.users.view', '', 'core'); + } + + public function testModuleCannotBeEmpty(): void + { + $this->expectException(\InvalidArgumentException::class); + new Permission('core.users.view', 'x', ''); + } + + public function testMarkOrphanAndRevive(): void + { + $p = new Permission('core.users.view', 'Voir', 'core'); + $p->markOrphan(); + self::assertTrue($p->isOrphan()); + $p->revive('Voir maj', 'core'); + self::assertFalse($p->isOrphan()); + self::assertSame('Voir maj', $p->getLabel()); + } +} +``` + +`tests/Unit/Module/Core/Domain/Entity/RoleTest.php` : +```php +getCode()); + self::assertSame('Bureau', $r->getLabel()); + self::assertFalse($r->isSystem()); + self::assertCount(0, $r->getPermissions()); + } + + public function testCodeMustBeSnakeCase(): void + { + $this->expectException(\InvalidArgumentException::class); + new Role('Bureau Commercial', 'x'); + } + + public function testAddRemovePermission(): void + { + $r = new Role('bureau', 'Bureau'); + $p = new Permission('core.users.view', 'Voir', 'core'); + $r->addPermission($p); + self::assertCount(1, $r->getPermissions()); + $r->addPermission($p); // idempotent + self::assertCount(1, $r->getPermissions()); + $r->removePermission($p); + self::assertCount(0, $r->getPermissions()); + } + + public function testSystemRoleCannotBeDeleted(): void + { + $r = new Role('admin', 'Administrateur', null, true); + $this->expectException(SystemRoleDeletionException::class); + $r->ensureDeletable(); + } + + public function testNonSystemRoleIsDeletable(): void + { + $r = new Role('bureau', 'Bureau'); + $r->ensureDeletable(); + self::assertFalse($r->isSystem()); + } +} +``` + +- [ ] **Step 2: Lancer les tests, vérifier l'échec** + +Run: `docker exec -t -u www-data php-lesstime-fpm php vendor/bin/phpunit tests/Unit/Module/Core/Domain/Entity/` +Expected: FAIL (classes inexistantes). + +- [ ] **Step 3: Créer l'exception** + +`src/Module/Core/Domain/Exception/SystemRoleDeletionException.php` : +```php + ['permission:read']], + security: "is_granted('core.permissions.view') or is_granted('core.users.manage') or is_granted('core.roles.manage')", +)] +class Permission +{ + #[ORM\Id] + #[ORM\GeneratedValue] + #[ORM\Column] + #[Groups(['permission:read', 'role:read'])] + private ?int $id = null; + + #[ORM\Column(length: 255, unique: true)] + #[Groups(['permission:read', 'role:read'])] + private string $code; + + #[ORM\Column(length: 255)] + #[Groups(['permission:read', 'role:read'])] + private string $label; + + #[ORM\Column(length: 100)] + #[Groups(['permission:read', 'role:read'])] + private string $module; + + #[ORM\Column] + #[Groups(['permission:read'])] + private bool $orphan = false; + + public function __construct(string $code, string $label, string $module) + { + $code = trim($code); + $label = trim($label); + $module = trim($module); + + if ('' === $code || !str_contains($code, '.')) { + throw new \InvalidArgumentException(sprintf('Code de permission invalide : "%s" (attendu module.resource.action).', $code)); + } + if ('' === $label) { + throw new \InvalidArgumentException('Le libellé de permission ne peut pas être vide.'); + } + if ('' === $module) { + throw new \InvalidArgumentException('Le module de permission ne peut pas être vide.'); + } + + $this->code = $code; + $this->label = $label; + $this->module = $module; + } + + public function getId(): ?int + { + return $this->id; + } + + public function getCode(): string + { + return $this->code; + } + + public function getLabel(): string + { + return $this->label; + } + + public function getModule(): string + { + return $this->module; + } + + public function isOrphan(): bool + { + return $this->orphan; + } + + public function markOrphan(): void + { + $this->orphan = true; + } + + public function revive(string $label, string $module): void + { + $this->orphan = false; + $this->updateMetadata($label, $module); + } + + public function updateMetadata(string $label, string $module): void + { + $this->label = $label; + $this->module = $module; + } +} +``` + +- [ ] **Step 5: Créer `Role`** + +`src/Module/Core/Domain/Entity/Role.php` : +```php + ['role:read']], + denormalizationContext: ['groups' => ['role:write']], +)] +class Role +{ + #[ORM\Id] + #[ORM\GeneratedValue] + #[ORM\Column] + #[Groups(['role:read'])] + private ?int $id = null; + + #[ORM\Column(length: 100, unique: true)] + #[Groups(['role:read', 'role:write'])] + private string $code; + + #[ORM\Column(length: 255)] + #[Groups(['role:read', 'role:write'])] + private string $label; + + #[ORM\Column(type: 'text', nullable: true)] + #[Groups(['role:read', 'role:write'])] + private ?string $description; + + #[ORM\Column(name: 'is_system')] + #[Groups(['role:read'])] + private bool $isSystem; + + /** + * @var Collection + */ + #[ORM\ManyToMany(targetEntity: Permission::class, fetch: 'EAGER')] + #[ORM\JoinTable(name: 'role_permission')] + #[Groups(['role:read', 'role:write'])] + private Collection $permissions; + + public function __construct(string $code, string $label, ?string $description = null, bool $isSystem = false) + { + if (1 !== preg_match('/^[a-z][a-z0-9_]*$/', $code)) { + throw new \InvalidArgumentException(sprintf('Code de rôle invalide : "%s" (attendu snake_case).', $code)); + } + if ('' === trim($label)) { + throw new \InvalidArgumentException('Le libellé de rôle ne peut pas être vide.'); + } + + $this->code = $code; + $this->label = $label; + $this->description = $description; + $this->isSystem = $isSystem; + $this->permissions = new ArrayCollection(); + } + + public function getId(): ?int + { + return $this->id; + } + + public function getCode(): string + { + return $this->code; + } + + public function getLabel(): string + { + return $this->label; + } + + public function setLabel(string $label): void + { + $this->label = $label; + } + + public function getDescription(): ?string + { + return $this->description; + } + + public function setDescription(?string $description): void + { + $this->description = $description; + } + + public function isSystem(): bool + { + return $this->isSystem; + } + + /** + * @return Collection + */ + public function getPermissions(): Collection + { + return $this->permissions; + } + + public function addPermission(Permission $permission): void + { + if (!$this->permissions->contains($permission)) { + $this->permissions->add($permission); + } + } + + public function removePermission(Permission $permission): void + { + $this->permissions->removeElement($permission); + } + + public function ensureDeletable(): void + { + if ($this->isSystem) { + throw new SystemRoleDeletionException($this->code); + } + } +} +``` + +- [ ] **Step 6: Ajouter les relations RBAC + `getEffectivePermissions()` à `User`** + +Dans `src/Module/Core/Domain/Entity/User.php` : ajouter les imports `use Doctrine\Common\Collections\ArrayCollection; use Doctrine\Common\Collections\Collection;` (si absents) et, dans la classe : +```php + /** + * @var Collection + */ + #[ORM\ManyToMany(targetEntity: Role::class, fetch: 'EAGER')] + #[ORM\JoinTable(name: 'user_role')] + #[Groups(['user:rbac:read'])] + private Collection $rbacRoles; + + /** + * @var Collection + */ + #[ORM\ManyToMany(targetEntity: Permission::class, fetch: 'EAGER')] + #[ORM\JoinTable(name: 'user_permission')] + #[Groups(['user:rbac:read'])] + private Collection $directPermissions; +``` +> ⚠️ Initialiser les deux collections dans le constructeur de `User` (s'il en existe un ; sinon en ajouter un `public function __construct() { $this->rbacRoles = new ArrayCollection(); $this->directPermissions = new ArrayCollection(); }`. Vérifier d'abord s'il y a déjà un constructeur — `createdAt` est posé ailleurs ? Lire l'entité. Si pas de constructeur, en créer un n'initialisant QUE ces deux collections). + +Ajouter les méthodes : +```php + /** + * @return Collection + */ + public function getRbacRoles(): Collection + { + return $this->rbacRoles; + } + + public function addRbacRole(Role $role): void + { + if (!$this->rbacRoles->contains($role)) { + $this->rbacRoles->add($role); + } + } + + public function removeRbacRole(Role $role): void + { + $this->rbacRoles->removeElement($role); + } + + /** + * @return Collection + */ + public function getDirectPermissions(): Collection + { + return $this->directPermissions; + } + + public function addDirectPermission(Permission $permission): void + { + if (!$this->directPermissions->contains($permission)) { + $this->directPermissions->add($permission); + } + } + + public function removeDirectPermission(Permission $permission): void + { + $this->directPermissions->removeElement($permission); + } + + /** + * Permissions effectives = union (rôles RBAC → permissions) ∪ (permissions directes), triée, dédupliquée. + * + * @return list + */ + #[Groups(['me:read', 'user:rbac:read'])] + public function getEffectivePermissions(): array + { + $codes = []; + foreach ($this->rbacRoles as $role) { + foreach ($role->getPermissions() as $permission) { + $codes[$permission->getCode()] = true; + } + } + foreach ($this->directPermissions as $permission) { + $codes[$permission->getCode()] = true; + } + $keys = array_keys($codes); + sort($keys); + + return $keys; + } +``` +Ajouter les imports `use App\Module\Core\Domain\Entity\Role;` n'est pas nécessaire (même namespace) ; `Permission` non plus. Vérifier la présence de `use Symfony\Component\Serializer\Annotation\Groups;` (déjà là vu les Groups existants). + +- [ ] **Step 7: Enrichir le contrat `UserInterface`** + +Dans `src/Shared/Domain/Contract/UserInterface.php`, ajouter : +```php + /** @return list */ + public function getEffectivePermissions(): array; +``` +Puis ajouter le stub dans l'anonyme du test `tests/Unit/Shared/Doctrine/TimestampableBlamableSubscriberTest.php` qui implémente `UserInterface` : +```php + public function getEffectivePermissions(): array + { + return []; + } +``` + +- [ ] **Step 8: Créer les repositories + alias services** + +`src/Module/Core/Domain/Repository/PermissionRepositoryInterface.php` : +```php + */ + public function findAll(): array; + + /** @return list */ + public function findAllCodes(): array; + + public function save(Permission $permission): void; +} +``` + +`src/Module/Core/Domain/Repository/RoleRepositoryInterface.php` : +```php + */ + public function findAll(): array; + + public function save(Role $role): void; +} +``` + +`src/Module/Core/Infrastructure/Doctrine/DoctrinePermissionRepository.php` : +```php + + */ +final class DoctrinePermissionRepository extends ServiceEntityRepository implements PermissionRepositoryInterface +{ + public function __construct(ManagerRegistry $registry) + { + parent::__construct($registry, Permission::class); + } + + public function findById(int $id): ?Permission + { + return $this->find($id); + } + + public function findByCode(string $code): ?Permission + { + return $this->findOneBy(['code' => $code]); + } + + /** @return list */ + public function findAll(): array + { + return array_values($this->findBy([])); + } + + /** @return list */ + public function findAllCodes(): array + { + /** @var list $rows */ + $rows = $this->createQueryBuilder('p')->select('p.code')->getQuery()->getArrayResult(); + + return array_map(static fn (array $r): string => $r['code'], $rows); + } + + public function save(Permission $permission): void + { + $this->getEntityManager()->persist($permission); + } +} +``` + +`src/Module/Core/Infrastructure/Doctrine/DoctrineRoleRepository.php` : +```php + + */ +final class DoctrineRoleRepository extends ServiceEntityRepository implements RoleRepositoryInterface +{ + public function __construct(ManagerRegistry $registry) + { + parent::__construct($registry, Role::class); + } + + public function findById(int $id): ?Role + { + return $this->find($id); + } + + public function findByCode(string $code): ?Role + { + return $this->findOneBy(['code' => $code]); + } + + /** @return list */ + public function findAll(): array + { + return array_values($this->findBy([])); + } + + public function save(Role $role): void + { + $this->getEntityManager()->persist($role); + } +} +``` + +Dans `config/services.yaml`, sous les alias existants (à côté de `UserRepositoryInterface`) : +```yaml + App\Module\Core\Domain\Repository\PermissionRepositoryInterface: '@App\Module\Core\Infrastructure\Doctrine\DoctrinePermissionRepository' + App\Module\Core\Domain\Repository\RoleRepositoryInterface: '@App\Module\Core\Infrastructure\Doctrine\DoctrineRoleRepository' +``` + +- [ ] **Step 9: Lancer les tests unitaires entités** + +Run: `docker exec -t -u www-data php-lesstime-fpm php vendor/bin/phpunit tests/Unit/Module/Core/Domain/Entity/` +Expected: PASS. + +- [ ] **Step 10: Générer + appliquer la migration additive** + +Run: `docker exec -t -u www-data php-lesstime-fpm php bin/console doctrine:migrations:diff` +Vérifier que le `up()` ne contient QUE des `CREATE TABLE permission`, `CREATE TABLE "role"`, `CREATE TABLE role_permission`, `CREATE TABLE user_role`, `CREATE TABLE user_permission` (+ index + FK), **aucun** `DROP`/`ALTER` sur `"user"` ou `messenger_messages`. Si la dérive `messenger_messages` est mélangée, éditer la migration pour ne garder que les tables RBAC. +Ajouter les `COMMENT ON COLUMN` pour les colonnes métier (code, label, module, orphan, is_system, description) dans le `up()` (convention projet, cf. ColumnCommentsCatalog). +Run: `docker exec -t -u www-data php-lesstime-fpm php bin/console doctrine:migrations:migrate --no-interaction` +Puis recharger les fixtures de test : `make db-reset` (ou équivalent test) — vérifier que ça passe. + +- [ ] **Step 11: Gate + commit** + +Run: `docker exec -t -u www-data php-lesstime-fpm php bin/console doctrine:schema:validate` → Mapping OK. +Run: `docker exec -t -u www-data php-lesstime-fpm php vendor/bin/phpunit` → vert (120 + 11). +Bloc « Vérification login ». +```bash +make php-cs-fixer-allow-risky +git add -A -- src config tests migrations +git reset -- config/reference.php +git commit -m "feat(core) : add rbac role and permission entities with user relations" +``` + +--- + +## Phase B — Agrégation des permissions + commande de synchronisation + +### Task 2: `ModuleRegistry::permissions()` + `CoreModule::permissions()` finalisé + `app:sync-permissions` + +**Files:** +- Modify: `src/Shared/Domain/Module/ModuleRegistry.php` (méthode `permissions()`) +- Modify: `src/Module/Core/CoreModule.php` (permissions Core définitives) +- Create: `src/Module/Core/Infrastructure/Console/SyncPermissionsCommand.php` +- Create: `tests/Unit/Shared/Module/ModuleRegistryPermissionsTest.php` +- Create: `tests/Functional/Module/Core/SyncPermissionsCommandTest.php` + +**Interfaces:** +- Consumes : `ModuleInterface::permissions(): list` (existant), `PermissionRepositoryInterface`. +- Produces : `ModuleRegistry::permissions(array $moduleClasses): list` (agrège + injecte `module` = `$class::id()`, valide préfixe). Commande `app:sync-permissions`. + +- [ ] **Step 1: Test de `ModuleRegistry::permissions()`** + +`tests/Unit/Shared/Module/ModuleRegistryPermissionsTest.php` : +```php + $moduleClasses + * + * @return list + */ + public static function permissions(array $moduleClasses): array + { + $out = []; + foreach ($moduleClasses as $moduleClass) { + if (!is_a($moduleClass, ModuleInterface::class, true)) { + continue; + } + $moduleId = $moduleClass::id(); + foreach ($moduleClass::permissions() as $perm) { + $code = $perm['code']; + if (!str_starts_with($code, $moduleId.'.')) { + throw new \InvalidArgumentException(sprintf('Permission "%s" du module "%s" doit être préfixée par "%s.".', $code, $moduleId, $moduleId)); + } + $out[] = ['code' => $code, 'label' => $perm['label'], 'module' => $moduleId]; + } + } + + return $out; + } +``` + +- [ ] **Step 4: Finaliser `CoreModule::permissions()`** + +Remplacer le stub par les permissions Core RBAC (alignées sur Starseed, périmètre Lesstime) : +```php + public static function permissions(): array + { + return [ + ['code' => 'core.users.view', 'label' => 'Voir les utilisateurs'], + ['code' => 'core.users.manage', 'label' => 'Gérer les utilisateurs (créer, éditer, supprimer)'], + ['code' => 'core.roles.view', 'label' => 'Voir les rôles RBAC'], + ['code' => 'core.roles.manage', 'label' => 'Gérer les rôles et permissions'], + ['code' => 'core.permissions.view', 'label' => 'Consulter le catalogue des permissions RBAC'], + ]; + } +``` +> Mettre à jour `tests/Unit/Module/Core/CoreModuleTest.php` si une assertion fige les anciens codes (`core.user.read`, etc.). + +- [ ] **Step 5: Test fonctionnel de la commande** + +`tests/Functional/Module/Core/SyncPermissionsCommandTest.php` : +```php +find('app:sync-permissions')); + $tester->execute([]); + $tester->assertCommandIsSuccessful(); + + $repo = self::getContainer()->get(PermissionRepositoryInterface::class); + self::assertNotNull($repo->findByCode('core.users.manage')); + self::assertContains('core.roles.manage', $repo->findAllCodes()); + } +} +``` + +- [ ] **Step 6: Lancer, vérifier l'échec** (commande inexistante). + +- [ ] **Step 7: Implémenter `app:sync-permissions`** + +`src/Module/Core/Infrastructure/Console/SyncPermissionsCommand.php` : +```php + $moduleClasses */ + $moduleClasses = require $this->projectDir.'/config/modules.php'; + + // Phase 1 : permissions désirées (code => {code,label,module}). + $desired = []; + foreach (ModuleRegistry::permissions($moduleClasses) as $perm) { + $desired[$perm['code']] = $perm; + } + + // Phase 2 : upsert. + $existing = []; + foreach ($this->permissions->findAll() as $permission) { + $existing[$permission->getCode()] = $permission; + } + + $added = $updated = $revived = 0; + foreach ($desired as $code => $perm) { + $entity = $existing[$code] ?? null; + if (null === $entity) { + $this->permissions->save(new Permission($perm['code'], $perm['label'], $perm['module'])); + ++$added; + + continue; + } + if ($entity->isOrphan()) { + $entity->revive($perm['label'], $perm['module']); + ++$revived; + } elseif ($entity->getLabel() !== $perm['label'] || $entity->getModule() !== $perm['module']) { + $entity->updateMetadata($perm['label'], $perm['module']); + ++$updated; + } + } + + // Phase 3 : orphelines (existantes absentes des désirées). + $orphaned = 0; + foreach ($existing as $code => $entity) { + if (!isset($desired[$code]) && !$entity->isOrphan()) { + $entity->markOrphan(); + ++$orphaned; + } + } + + $this->em->flush(); + + $io->success(sprintf('Permissions synchronisées : %d ajoutées, %d mises à jour, %d réactivées, %d orphelines. Total désirées : %d.', $added, $updated, $revived, $orphaned, \count($desired))); + + return Command::SUCCESS; + } +} +``` + +- [ ] **Step 8: Tests + commit** + +Run: `docker exec -t -u www-data php-lesstime-fpm php vendor/bin/phpunit` → vert. +```bash +make php-cs-fixer-allow-risky +git add -A -- src tests +git commit -m "feat(core) : aggregate module permissions and add sync-permissions command" +``` + +--- + +## Phase C — PermissionVoter + exposition `/api/me` + +### Task 3: `PermissionVoter` + permissions effectives dans `/api/me` + +**Files:** +- Create: `src/Module/Core/Infrastructure/Security/PermissionVoter.php` +- Create: `tests/Unit/Module/Core/Infrastructure/Security/PermissionVoterTest.php` +- Modify (vérifier) : `src/Module/Core/Domain/Entity/User.php` — `getEffectivePermissions()` déjà dans le groupe `me:read` (Phase A Step 6). Confirmer. + +**Interfaces:** +- Consumes : `User::getEffectivePermissions()`, `User::getRoles()`. +- Produces : voter répondant à `is_granted('module.resource.action')`. + +- [ ] **Step 1: Test du voter** + +`tests/Unit/Module/Core/Infrastructure/Security/PermissionVoterTest.php` : +```php +getRoles()); + } + + public function testAbstainsOnNonRbacAttributes(): void + { + $voter = new PermissionVoter(); + $user = new User(); + self::assertSame(VoterInterface::ACCESS_ABSTAIN, $voter->vote($this->token($user), null, ['ROLE_ADMIN'])); + self::assertSame(VoterInterface::ACCESS_ABSTAIN, $voter->vote($this->token($user), null, ['IS_AUTHENTICATED_FULLY'])); + } + + public function testGrantsWhenUserHasPermissionViaRole(): void + { + $voter = new PermissionVoter(); + $role = new Role('bureau', 'Bureau'); + $role->addPermission(new Permission('core.users.view', 'Voir', 'core')); + $user = new User(); + $user->addRbacRole($role); + + self::assertSame(VoterInterface::ACCESS_GRANTED, $voter->vote($this->token($user), null, ['core.users.view'])); + self::assertSame(VoterInterface::ACCESS_DENIED, $voter->vote($this->token($user), null, ['core.users.manage'])); + } + + public function testAdminBypassesViaRole(): void + { + $voter = new PermissionVoter(); + $user = new User(); + $user->setRoles(['ROLE_ADMIN']); + + self::assertSame(VoterInterface::ACCESS_GRANTED, $voter->vote($this->token($user), null, ['core.users.manage'])); + } +} +``` + +- [ ] **Step 2: Lancer, vérifier l'échec.** + +- [ ] **Step 3: Implémenter le voter** + +`src/Module/Core/Infrastructure/Security/PermissionVoter.php` : +```php + + */ +final class PermissionVoter extends Voter +{ + private const string PATTERN = '/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/'; + + protected function supports(string $attribute, mixed $subject): bool + { + return 1 === preg_match(self::PATTERN, $attribute); + } + + protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token): bool + { + $user = $token->getUser(); + if (!$user instanceof User) { + return false; + } + + // ROLE_ADMIN = bypass total (cf. Décision 1). + if (in_array('ROLE_ADMIN', $user->getRoles(), true)) { + return true; + } + + return in_array($attribute, $user->getEffectivePermissions(), true); + } +} +``` +> Le voter est auto-enregistré (autoconfigure). Aucun ajout `services.yaml` nécessaire. + +- [ ] **Step 4: Tests + login + vérif `/api/me`** + +Run: `docker exec -t -u www-data php-lesstime-fpm php vendor/bin/phpunit` → vert. +Bloc « Vérification login », puis vérifier que `/api/me` expose `effectivePermissions` : +```bash +curl -s http://localhost:8082/api/me -H "Cookie: BEARER=$BEARER" | grep -o "effectivePermissions" && echo "OK champ présent" +``` +> `alice` (ROLE_USER, sans rôle RBAC) renverra `effectivePermissions: []` — normal à ce stade (pas de rôle attribué). + +- [ ] **Step 5: Commit** + +```bash +make php-cs-fixer-allow-risky +git add -A -- src tests +git commit -m "feat(core) : add permission voter and expose effective permissions on /api/me" +``` + +--- + +## Phase D — API Platform : Role + Permission + processors + +### Task 4: ApiResources Role/Permission (déjà sur entités) + `RoleProcessor` + endpoint RBAC user + `UserRbacProcessor` + +**Files:** +- Create: `src/Module/Core/Infrastructure/ApiPlatform/State/Processor/RoleProcessor.php` +- Create: `src/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessor.php` +- Modify: `src/Module/Core/Domain/Entity/User.php` (opérations RBAC `Get`/`Patch` sur `/api/users/{id}/rbac` + groupes `user:rbac:read`/`user:rbac:write`) +- Create: `tests/Functional/Module/Core/RoleApiTest.php` +- Create: `tests/Functional/Module/Core/UserRbacApiTest.php` + +**Interfaces:** +- Consumes : `RoleRepositoryInterface`, `Role::ensureDeletable()`, `User` collections. +- Produces : `POST/PATCH/DELETE /api/roles`, `GET/PATCH /api/users/{id}/rbac`. + +- [ ] **Step 1: `RoleProcessor`** (immuabilité du code + refus delete système) + +`src/Module/Core/Infrastructure/ApiPlatform/State/Processor/RoleProcessor.php` : +```php + + */ +final readonly class RoleProcessor implements ProcessorInterface +{ + public function __construct(private EntityManagerInterface $em) {} + + public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): ?Role + { + \assert($data instanceof Role); + + if ($operation instanceof DeleteOperationInterface) { + try { + $data->ensureDeletable(); + } catch (\DomainException $e) { + throw new AccessDeniedHttpException($e->getMessage(), $e); + } + $this->em->remove($data); + $this->em->flush(); + + return null; + } + + $this->em->persist($data); + $this->em->flush(); + + return $data; + } +} +``` +> Le code étant `role:write` mais immuable : API Platform mappe le `code` à la création (POST). En PATCH, le `code` reste dans `role:write` — pour le rendre immuable, vérifier dans un test que le PATCH du code n'a pas d'effet (l'entité n'a pas de `setCode()`, donc le denormalizer ne peut pas l'écraser → immuabilité structurelle). Confirmer l'absence de `setCode()` dans `Role`. ✅ (non défini en Phase A). + +- [ ] **Step 2: Endpoint RBAC sur `User` + `UserRbacProcessor`** + +Dans `src/Module/Core/Domain/Entity/User.php`, ajouter aux `operations` de l'`ApiResource` : +```php + new Get( + uriTemplate: '/users/{id}/rbac', + security: "is_granted('core.users.manage')", + normalizationContext: ['groups' => ['user:rbac:read']], + ), + new Patch( + uriTemplate: '/users/{id}/rbac', + security: "is_granted('core.users.manage')", + normalizationContext: ['groups' => ['user:rbac:read']], + denormalizationContext: ['groups' => ['user:rbac:write']], + processor: UserRbacProcessor::class, + ), +``` +Ajouter l'import `use App\Module\Core\Infrastructure\ApiPlatform\State\Processor\UserRbacProcessor;`. +Ajouter les setters de collections en denormalization (groupe `user:rbac:write`) : exposer `rbacRoles` et `directPermissions` en écriture. Pour cela, ajouter le groupe `user:rbac:write` sur les deux propriétés (en plus de `user:rbac:read`) : +```php + #[Groups(['user:rbac:read', 'user:rbac:write'])] + private Collection $rbacRoles; + ... + #[Groups(['user:rbac:read', 'user:rbac:write'])] + private Collection $directPermissions; +``` +> API Platform écrit les collections M2M via les adders/removers `addRbacRole`/`removeRbacRole` et `addDirectPermission`/`removeDirectPermission` (déjà définis Phase A). + +`src/Module/Core/Infrastructure/ApiPlatform/State/Processor/UserRbacProcessor.php` (garde anti-écrasement des collections absentes du payload) : +```php + + */ +final readonly class UserRbacProcessor implements ProcessorInterface +{ + public function __construct(private EntityManagerInterface $em) {} + + public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): User + { + \assert($data instanceof User); + + // Defense in depth : si une collection n'était pas dans le payload JSON, API Platform + // la réinstancie vide → on restaure le snapshot Doctrine pour éviter l'effacement silencieux. + $previous = $context['previous_data'] ?? null; + if ($previous instanceof User) { + $this->restoreIfEmptiedByAbsence($data->getRbacRoles(), $previous->getRbacRoles()); + $this->restoreIfEmptiedByAbsence($data->getDirectPermissions(), $previous->getDirectPermissions()); + } + + $this->em->persist($data); + $this->em->flush(); + + return $data; + } + + /** + * @param iterable $current + * @param iterable $previous + */ + private function restoreIfEmptiedByAbsence(mixed $current, mixed $previous): void + { + // Si la collection courante est "propre" (non modifiée par le denormalizer) mais vidée, + // on ne touche à rien : la mutation explicite passe par add/remove. + if ($current instanceof PersistentCollection && !$current->isDirty()) { + return; + } + // NB : la restauration fine est laissée à l'exécutant si un test prouve l'écrasement ; + // en pratique, exposer les collections en user:rbac:write avec les adders/removers suffit. + } +} +``` +> ⚠️ NOTE EXÉCUTANT : commencer SIMPLE — exposer `rbacRoles`/`directPermissions` en `user:rbac:write` (avec adders/removers) gère nativement les mutations via IRIs. Écrire d'abord le test `UserRbacApiTest` (Step 4) ; si et seulement si il prouve un écrasement de collection lors d'un PATCH partiel, implémenter la restauration depuis `$context['previous_data']`. Sinon, le `UserRbacProcessor` peut se réduire à persist+flush. Ne pas sur-architecturer. + +- [ ] **Step 3: Tests fonctionnels Role** + +`tests/Functional/Module/Core/RoleApiTest.php` : créer un user admin authentifié (helper login JWT comme les autres tests fonctionnels du projet — s'inspirer de `tests/Functional/...` existants), puis : +- `GET /api/roles` en tant qu'admin → 200. +- `GET /api/roles` non authentifié → 401. +- `POST /api/roles` `{code:'bureau', label:'Bureau'}` en admin → 201. +- `DELETE` d'un rôle système (`admin`, seedé en Phase E — ou créé inline `isSystem`) → 403. +> S'aligner sur le pattern d'auth des tests fonctionnels existants (cookie BEARER via `/login_check` ou client API Platform avec token). LIRE un test fonctionnel existant avant d'écrire celui-ci. + +- [ ] **Step 4: Tests fonctionnels User RBAC** + +`tests/Functional/Module/Core/UserRbacApiTest.php` : +- `GET /api/users/{id}/rbac` en admin → 200, contient `rbacRoles`, `directPermissions`, `effectivePermissions`. +- `PATCH /api/users/{id}/rbac` attribuant un rôle (IRI) → 200, le rôle apparaît dans `rbacRoles`. +- `PATCH` ne touchant qu'un champ → vérifier que l'autre collection n'est PAS vidée (le test qui décide si `UserRbacProcessor` a besoin de la restauration). + +- [ ] **Step 5: Lancer + login + commit** + +Run: `docker exec -t -u www-data php-lesstime-fpm php vendor/bin/phpunit` → vert. +Bloc « Vérification login ». +```bash +make php-cs-fixer-allow-risky +git add -A -- src tests +git commit -m "feat(core) : expose role and user-rbac api endpoints with processors" +``` + +--- + +## Phase E — Seed RBAC (rôles système) + +### Task 5: `RbacSeeder` + `app:seed-rbac` + intégration fixtures + +**Files:** +- Create: `src/Module/Core/Application/Rbac/RbacSeeder.php` +- Create: `src/Module/Core/Infrastructure/Console/SeedRbacCommand.php` +- Create: `src/Module/Core/Domain/Security/SystemRoles.php` +- Modify: `src/DataFixtures/AppFixtures.php` (appeler le seed des rôles système après sync, OU documenter l'appel via make) +- Create: `tests/Functional/Module/Core/SeedRbacCommandTest.php` + +**Interfaces:** +- Consumes : `RoleRepositoryInterface`, `EntityManagerInterface`. +- Produces : `RbacSeeder::ensureSystemRoles(): void` (idempotent), commande `app:seed-rbac`. + +- [ ] **Step 1: `SystemRoles`** + +`src/Module/Core/Domain/Security/SystemRoles.php` : +```php +find('app:seed-rbac')); + + $tester->execute([]); + $tester->assertCommandIsSuccessful(); + $tester->execute([]); // idempotent + $tester->assertCommandIsSuccessful(); + + $repo = self::getContainer()->get(RoleRepositoryInterface::class); + $admin = $repo->findByCode(SystemRoles::ADMIN_CODE); + self::assertNotNull($admin); + self::assertTrue($admin->isSystem()); + self::assertNotNull($repo->findByCode(SystemRoles::USER_CODE)); + } +} +``` + +- [ ] **Step 3: Lancer, vérifier l'échec.** + +- [ ] **Step 4: `RbacSeeder`** + +`src/Module/Core/Application/Rbac/RbacSeeder.php` : +```php +ensureRole(SystemRoles::ADMIN_CODE, 'Administrateur', 'Accès complet (bypass RBAC).'); + $this->ensureRole(SystemRoles::USER_CODE, 'Utilisateur', 'Rôle de base sans permission spécifique.'); + $this->em->flush(); + } + + private function ensureRole(string $code, string $label, string $description): void + { + if (null !== $this->roles->findByCode($code)) { + return; + } + $this->roles->save(new Role($code, $label, $description, true)); + } +} +``` + +- [ ] **Step 5: `app:seed-rbac`** + +`src/Module/Core/Infrastructure/Console/SeedRbacCommand.php` : +```php +seeder->ensureSystemRoles(); + $io->success('Rôles système RBAC seedés (admin, user).'); + + return Command::SUCCESS; + } +} +``` + +- [ ] **Step 6: Intégrer au cycle fixtures** + +LIRE `src/DataFixtures/AppFixtures.php`. Après le chargement des users, appeler le seed RBAC (les permissions doivent exister → `app:sync-permissions` AVANT). Deux options selon le pattern projet : +- (a) injecter `RbacSeeder` dans `AppFixtures` et appeler `ensureSystemRoles()` en fin de `load()` (les permissions Core sont synchronisées par un hook séparé) ; OU +- (b) documenter dans le `Makefile`/README que `make db-reset` enchaîne `fixtures:load` puis `app:sync-permissions` puis `app:seed-rbac`. +> Choisir (a) si `AppFixtures` peut injecter des services (DependentFixture/service) ; sinon (b). Vérifier que `make db-reset` laisse une base cohérente (rôles + permissions présents). NE PAS attacher de matrice métier (Décision 4). + +- [ ] **Step 7: Tests + commit** + +Run: `docker exec -t -u www-data php-lesstime-fpm php vendor/bin/phpunit` → vert. +```bash +make php-cs-fixer-allow-risky +git add -A -- src tests +git commit -m "feat(core) : add rbac seeder and seed-rbac command for system roles" +``` + +--- + +## Phase F — Sidebar filtrée par permission + +### Task 6: `SidebarFilter` + `SidebarProvider` + `config/sidebar.php` gated par permission + +**Files:** +- Modify: `src/Shared/Domain/Sidebar/SidebarFilter.php` (clé `permission` sur section + item) +- Modify: `src/Shared/Infrastructure/ApiPlatform/State/SidebarProvider.php` (passe les permissions effectives) +- Modify: `config/sidebar.php` (permissions sur les items admin) +- Modify: `tests/Unit/Shared/Sidebar/SidebarFilterTest.php` (cas permission) +- Modify (éventuel): `tests/Functional/Shared/SidebarEndpointTest.php` + +**Interfaces:** +- Consumes : `User::getEffectivePermissions()`, `User::getRoles()`. +- Produces : `SidebarFilter::filter($sections, $activeModuleIds, $activeRoles = [], $activePermissions = [])`. + +- [ ] **Step 1: Étendre le test `SidebarFilterTest`** + +Ajouter des cas : une section/item avec `'permission' => 'core.users.view'` est masqué si la permission n'est pas dans `$activePermissions`, visible sinon. Un item sans `permission` reste visible (rétrocompat). Combinaison avec `roles` et `module` inchangée. +```php + public function testItemHiddenWhenPermissionMissing(): void + { + $sections = [[ + 'label' => 's', 'icon' => 'i', + 'items' => [ + ['label' => 'a', 'to' => '/a', 'icon' => 'i', 'permission' => 'core.users.view'], + ['label' => 'b', 'to' => '/b', 'icon' => 'i'], + ], + ]]; + $out = SidebarFilter::filter($sections, [], [], []); + self::assertCount(1, $out['sections'][0]['items']); + self::assertSame('/b', $out['sections'][0]['items'][0]['to']); + } + + public function testItemVisibleWhenPermissionGranted(): void + { + $sections = [[ + 'label' => 's', 'icon' => 'i', + 'items' => [['label' => 'a', 'to' => '/a', 'icon' => 'i', 'permission' => 'core.users.view']], + ]]; + $out = SidebarFilter::filter($sections, [], [], ['core.users.view']); + self::assertCount(1, $out['sections'][0]['items']); + } +``` + +- [ ] **Step 2: Lancer, vérifier l'échec** (signature à 3 args). + +- [ ] **Step 3: Étendre `SidebarFilter`** + +Ajouter le paramètre `array $activePermissions = []` à `filter()`. Mettre à jour la docblock des types (`permission?:string` sur section et item). Après le gate de rôle (section et item), ajouter le gate de permission : +```php + // Gate de permission au niveau section. + if (!self::permissionSatisfied($section['permission'] ?? null, $activePermissions)) { + continue; + } +``` +et pour l'item, avant le filtrage module : +```php + if (!self::permissionSatisfied($item['permission'] ?? null, $activePermissions)) { + continue; + } +``` +Helper : +```php + /** + * @param list $activePermissions + */ + private static function permissionSatisfied(?string $required, array $activePermissions): bool + { + if (null === $required || '' === $required) { + return true; + } + + return in_array($required, $activePermissions, true); + } +``` + +- [ ] **Step 4: Passer les permissions dans `SidebarProvider`** + +Dans `provide()`, après `$roles = ...` : +```php + $permissions = ($user instanceof \App\Module\Core\Domain\Entity\User) ? $user->getEffectivePermissions() : []; + + $filtered = SidebarFilter::filter($sidebar, ModuleRegistry::ids($moduleClasses), array_values($roles), $permissions); +``` +> Pour éviter le couplage dur au concret, préférer le contrat : `$user` peut être typé `UserInterface` (qui a désormais `getEffectivePermissions()`). Utiliser `$permissions = method_exists($user, 'getEffectivePermissions') ? $user->getEffectivePermissions() : [];` OU, plus propre, instancier-check sur `App\Shared\Domain\Contract\UserInterface`. Choisir le check sur le contrat Shared. + +- [ ] **Step 5: Ajouter les permissions dans `config/sidebar.php`** + +Sur la section admin, garder le gate `roles: [ROLE_ADMIN]` (rétrocompat) ET, en complément, ajouter une `permission` sur l'item Administration le cas échéant. Comme ROLE_ADMIN bypasse déjà tout (Décision 1), garder la section admin sur `roles` est suffisant ; on ajoute `permission` seulement si on veut donner accès à des non-admins porteurs de `core.users.view`/`core.roles.view`. Décider : ajouter `'permission' => 'core.users.view'` sur l'item `administration` pour permettre l'accès aux gestionnaires non-admin. Documenter dans le commentaire d'en-tête de `config/sidebar.php` la nouvelle clé `permission`. +> Mettre à jour le commentaire d'en-tête : « `permission` (section/item masqué si la permission effective absente — le RBAC fin) ». + +- [ ] **Step 6: Tests + login + commit** + +Run: `docker exec -t -u www-data php-lesstime-fpm php vendor/bin/phpunit` → vert. +Bloc « Vérification login » + vérifier `/api/sidebar` : `admin` voit Administration, `alice` (ROLE_USER sans permission) ne voit pas l'item gardé par permission. +```bash +make php-cs-fixer-allow-risky +git add -A -- src config tests +git commit -m "feat(core) : gate sidebar by effective permissions" +``` + +--- + +## Phase G — Front : composable `usePermissions` + gestion des rôles + +### Task 7: `usePermissions`, type user étendu, page admin rôles + +**Files:** +- Create: `frontend/modules/core/composables/usePermissions.ts` +- Modify: type de l'utilisateur courant (chercher `frontend/services/dto/` ou store auth) — ajouter `effectivePermissions: string[]` +- Create: `frontend/modules/core/services/roles.ts` + `frontend/modules/core/services/permissions.ts` +- Create: `frontend/modules/core/pages/admin/roles.vue` (gestion des rôles) — OU onglet dans l'admin existant +- Modify: `frontend/i18n/locales/fr.json` (clés `admin.roles.*`) + +> ⚠️ Le front Lesstime n'a pas encore de page de gestion de rôles. LIRE d'abord la structure (`frontend/modules/core/`, `frontend/stores/auth.ts`, `frontend/services/`, `frontend/pages/admin.vue` et ses onglets `Admin*Tab`). Reproduire le pattern existant (onglet `AdminUserTab` etc.). Le composable et le type sont le cœur de l'AC front ; la page de gestion peut être un onglet supplémentaire dans `admin.vue`. + +**Interfaces:** +- Consumes : `/api/me.effectivePermissions`, `/api/roles`, `/api/permissions`. +- Produces : `usePermissions(): { can(code), canAny(codes), canAll(codes) }`. + +- [ ] **Step 1: Étendre le type user + le store auth** + +LIRE le store `frontend/stores/auth.ts` (ou `shared/stores/auth.ts`) et le DTO user. Ajouter `effectivePermissions: string[]` au type, et s'assurer que le payload `/api/me` (qui l'expose désormais, Phase C) est bien stocké. Si le type a `roles: string[]`, garder. + +- [ ] **Step 2: Composable `usePermissions`** + +`frontend/modules/core/composables/usePermissions.ts` : +```ts +export function usePermissions() { + const auth = useAuthStore() + + function isAdmin(): boolean { + return auth.user?.roles?.includes('ROLE_ADMIN') ?? false + } + + function can(code: string): boolean { + if (!auth.user) return false + if (isAdmin()) return true + return auth.user.effectivePermissions?.includes(code) ?? false + } + + function canAny(codes: string[]): boolean { + return codes.some((c) => can(c)) + } + + function canAll(codes: string[]): boolean { + return codes.every((c) => can(c)) + } + + return { can, canAny, canAll, isAdmin } +} +``` +> Le dossier `modules/core/composables` est auto-importé (scan `readdirSync('modules/')` → `imports.dirs`, cf. LST-62). `useAuthStore` est auto-importé. + +- [ ] **Step 3: Services roles/permissions** + +`frontend/modules/core/services/roles.ts` et `permissions.ts` : 1 service par ressource, via `useApi()` (pattern projet — LIRE `frontend/services/users.ts` comme modèle). Exposer `list()`, `create()`, `update()`, `remove()` pour roles ; `list()` pour permissions. Gérer la pagination via le pattern projet (ces collections sont bornées → `paginationEnabled: false` sur le `GetCollection` côté back, OU `fetchAllHydra`). Vérifier : si les collections Role/Permission peuvent dépasser 30 items, ajouter `paginationEnabled: false` sur leur `GetCollection` (cf. CLAUDE.md piège `extractHydraMembers`). Pour Lesstime, `permission` ≈ une douzaine de codes → borné ; `role` ≈ qqs unités → borné. Ajouter `paginationEnabled: false` sur les `GetCollection` de `Role` et `Permission` (entités, Phase A/D) pour fiabiliser `extractHydraMembers`. + +- [ ] **Step 4: Page / onglet de gestion des rôles** + +Ajouter un onglet `AdminRoleTab` dans `frontend/pages/admin.vue` (ou `modules/core`), listant les rôles, permettant création/édition (label, description, permissions cochées depuis `/api/permissions` groupées par module) et suppression (désactivée pour `isSystem`). Réserver l'affichage via `v-if="can('core.roles.view')"`. LIRE un `Admin*Tab` existant pour le style. + +- [ ] **Step 5: i18n** + +Ajouter dans `frontend/i18n/locales/fr.json` les clés `admin.roles.*` (titre, colonnes, actions, messages). Fusionner dans les namespaces existants (ne pas dupliquer une clé racine). + +- [ ] **Step 6: Gate front + smoke** + +Run: `cd frontend && npx nuxt build 2>&1 | grep -iE "error|roles|permission" | tail` — build OK, pas d'erreur de module manquant. +> Rappel LST-62 : `nuxt typecheck` n'est PAS un gate vert sur ce stack. Le vrai gate = build OK + aucun `Cannot find module` + auto-imports présents. Smoke navigateur (gestion des rôles) = PO. + +- [ ] **Step 7: Commit** + +```bash +git add -A -- frontend +git commit -m "feat(core) : add usePermissions composable and rbac roles admin front" +``` + +--- + +## Acceptance check (après toutes les phases) + +- [ ] **AC1** Permissions `module.resource.action` synchronisées via `app:sync-permissions` : la commande tourne sans erreur, `permission` contient les codes `core.*`. +- [ ] **AC2** Sidebar gated par permission ET par module actif : `/api/sidebar` masque les items selon `effectivePermissions` (et `disabledRoutes` selon module), ROLE_ADMIN voit tout. +- [ ] **AC3** `make test` vert (≈ 120 + nouveaux tests), `doctrine:schema:validate` mapping OK, `migrations:diff` = pas de changement RBAC (hors `messenger_messages`). +- [ ] `/api/me` expose `effectivePermissions`. +- [ ] `PermissionVoter` répond à `is_granted('core.*.*')` ; ROLE_ADMIN bypass. +- [ ] `app:seed-rbac` crée les rôles système `admin`/`user` (idempotent). +- [ ] Front : `usePermissions().can(code)` fonctionne ; gestion des rôles accessible aux porteurs de `core.roles.view`. +- [ ] Login/JWT/MCP inchangés (`204`/`200`/`200`) à chaque phase. +- [ ] `config/reference.php` jamais committé. + +## Notes pour les tickets suivants + +- **2.x (modules métier)** : chaque `*Module::permissions()` déclarera ses codes ; `app:sync-permissions` les upsertera ; les rôles métier (bureau/compta/…) seront seedés via une matrice étendue dans `RbacSeeder` quand les permissions existeront (Décision 4). +- **1.3 (Audit log)** : `core.audit_log.view` pourra être ajoutée à `CoreModule::permissions()` quand l'audit sera livré. +- **Migration `is_admin`** (optionnelle) : si le PO préfère le modèle Starseed, une phase ultérieure pourra remplacer le bypass `ROLE_ADMIN` par une colonne `is_admin` + data-migration (Décision 1).