Autorisations et matrice des droits

Le backend applique un contrôle d'accès par rôles (RBAC) complété par des contrôles de propriété. Cette page donne la matrice complète, route par route, relevée dans les fichiers *.routes.ts de backend/src/api. Elle explique ensuite les contrôles de propriété qui empêchent un partenaire d'agir sur les données d'un autre.

#Rôles

Aucune route ne permet de changer un rôle : cela se fait par le seed (backend/prisma/seed.ts) ou par une requête en base. L'élévation de privilèges par l'API est donc impossible par construction.

#Briques de contrôle

requireRoles() sans argument refuse tout le monde : l'oubli d'un rôle aboutit à un refus, pas à une ouverture.

Toutes les routes /api/... existent aussi sous /api/v1/... avec les mêmes contrôles, car le même routeur est monté deux fois dans backend/src/app.ts.

#Matrice complète

Légende : oui accès accordé, non refusé (401 sans jeton, 403 avec un rôle insuffisant), propre limité aux données du compte ou de ses entreprises, majeur limité aux données du compte et réservé à un âge vérifié.

#Système et documentation

#Authentification

#Loterie

#Boutique et partenaires

#Utilisateur et RGPD

Les routes « propres » de ce module n'acceptent aucun identifiant de compte en paramètre : elles utilisent toujours req.user.userId. Il n'existe donc pas de vecteur IDOR sur le profil ou l'export.

#Analytique, administration et webhooks

Toutes les routes ADMIN, y compris /api/lottery/draw, /api/lottery/refund et /api/analytics/dashboard, passent par requireRoles('ADMIN') et exigent donc la 2FA active sur le compte.

#Vérification d'âge

L'achat et le cadeau d'un ticket, l'échange d'une récompense et l'achat d'un ticket à gratter exigent que User.ageVerificationStatus vaille VERIFIED. Le middleware relit ce statut en base à chaque requête : il ne fait pas confiance au jeton ni au statut que le client garde en mémoire.

AGE_VERIFICATION_REQUIRED vaut true par défaut et ne peut pas valoir false en production : le schéma d'environnement arrête le processus. Seules les suites de tests la désactivent (backend/__tests__/setup-env.ts).

Le statut ne change que par une décision de la Mairie. Le parcours est le suivant :

La décision est prise dans une transaction qui ne s'applique qu'à une demande encore PENDING (updateMany conditionnel) : deux agents qui statuent en même temps ne produisent qu'une décision, l'autre reçoit 409. La même transaction efface le recto et le verso et met à jour le compte. Une entrée d'audit IDENTITY_VERIFICATION_DECISION est ensuite écrite, puis l'email identity-decision est envoyé au citoyen. L'interface est la page Identités de l'espace Mairie (frontend-web/src/app/mairie/identites/page.tsx).

Le contrôle ne couvre que les routes de l'API. Une adresse qui achète directement sur le contrat, sans passer par BlockLucky, n'est soumise à aucune vérification d'âge (voir Limites du contrat). Le retrait d'une cagnotte (/lottery/claim-prize) n'est pas non plus soumis au contrôle, puisqu'il suppose un ticket acheté.

#Contrôles de propriété (IDOR partenaires)

Une entreprise partenaire appartient au compte qui l'a créée, par la colonne Partner.ownerId (clé étrangère vers User, ON DELETE SET NULL). Le rôle PARTNER ne suffit pas : chaque opération sur une entreprise, une offre ou un code vérifie la propriété.

export const assertPartnerAccess = (
  partner: { ownerId?: string | null } | null | undefined,
  actor: PartnerActor
): void => {
  if (!partner) throw new AppError('Entreprise partenaire introuvable', 404);
  if (actor.role === 'ADMIN') return;
  if (!partner.ownerId || partner.ownerId !== actor.userId) {
    throw new AppError("Accès refusé : cette entreprise partenaire n'est pas rattachée à votre compte", 403);
  }
};

Une entreprise sans propriétaire (ownerId nul, par exemple après la suppression du compte propriétaire) n'est plus accessible qu'aux administrateurs. Le test empêche un partenaire d'agir sur l'entreprise d'un autre partenaire de backend/__tests__/api/auth-security.test.ts couvre ces contrôles ; backend/__tests__/api/partners.test.ts et backend/__tests__/api/admin.test.ts complètent la couverture des rôles.

#Autres contrôles d'appartenance

#Limites connues