Identity & multi-tenant

Périmètre : authentification (email/mot de passe, magic link, MFA TOTP), organisations (multi-tenant), membres & équipes, RBAC (rôles + permissions), API keys, audit log, RGPD.

Vocabulaire & entités

Le schéma Prisma complet est dans docs/04-data-model.md §3. Les tables techniques Better Auth (Account, Verification, TwoFactor) ne sont pas exposées directement.

Écrans

Espace personnel (/account)

Administration d'organisation (/workspace/admin, rôle ADMIN)

Modèle de données (points clés)

• Membership est unique sur (userId, organizationId) — doublons rejetés.
• Role.isSystem = true → lecture seule (seed uniquement, pas d'édition en prod sauf super-admin).
• ApiKey : seul le préfixe est stocké en clair, le reste est hashé bcrypt.
• User.anonymizedAt : champ de traçabilité RGPD ; l'audit log est conservé intact même après anonymisation.
• User.cguVersion / cguAcceptedAt : re-acceptation forcée à la prochaine connexion après changement de version CGU.

Pile d'authentification — Better Auth

Better Auth 1.4+ est la source unique d'authentification (server/lib/auth.ts).

Endpoints Better Auth (consommés via useAuthClient()) :

POST /api/auth/sign-in/email
POST /api/auth/sign-out
POST /api/auth/forget-password
POST /api/auth/reset-password
POST /api/auth/verify-email
POST /api/auth/magic-link/send
POST /api/auth/two-factor/enable · /verify
POST /api/auth/organization/set-active
POST /api/auth/admin/impersonate · /stop-impersonating

Modèle de rôles (RBAC)

Niveaux

Deux niveaux distincts : rôles globaux Pulse (transverses, hors org) et rôles métier (par Membership).

Rôles métier standard livrés en seed : ADMIN, MANAGER, COMMERCIAL, SALES_BACK, ACCOUNTANT, LEASE_OFFICER, FINANCE_OFFICER, TECHNICIAN, SERVICE_MANAGER, LOGISTICS, CLIENT_USER, CLIENT_ADMIN, LENDER_USER, PARTNER_USER, SUPPLIER_USER, AUDITOR.

Format des permissions

domain.entity:action — exemples : identity.user:invite, lease.contract:sign, crm.opportunity:read.

Matrice rôles métier (extrait)

Légende : ✅ = oui, R = lecture seule, R/W = lecture + écriture, ❌ = aucun accès. Matrice modifiable par l'admin d'organisation.

API

curl -s -X POST "$API/api/workspace/users/invite" \
  -H "Content-Type: application/json" -H "Cookie: $SESSION" \
  -d '{"email":"alice@example.com","roleCode":"COMMERCIAL"}'

{ "id": "inv_…", "email": "alice@example.com", "expiresAt": "2026-06-23T10:00:00Z" }

Workflows

Invitation d'un utilisateur

Admin saisit email + rôle
  → Vérif unicité Membership (409 si doublon)
  → Création Invitation (token signé, 7 jours)
  → Email envoyé à l'invité
  → Invité clique → /auth/invitation?token=…
  → Setup compte (ou login si existant) + acceptation CGU
  → Membership créé · Invitation.acceptedAt rempli
  → Notification in-app à l'inviteur

Connexion standard

Email + mot de passe
  → Better Auth valide
  → MFA TOTP si activé
  → Session créée (cookie) · lastLoginAt/Ip mis à jour
  → 1 org → org active auto
  → N orgs → écran sélection org
  → Redirect dashboard (selon rôle)

Magic link

/auth/magic-link → email saisi
  → Lien signé (15 min) envoyé
  → Clic → session ouverte directement
  → MFA toujours exigée si activée

Switch d'organisation

Clic OrganizationSwitcher (topbar)
  → POST /api/auth/organization/set-active { organizationId }
  → Cookie session mis à jour
  → Refresh page (toutes les requêtes API utilisent le nouvel activeOrganizationId)

Désactivation d'un utilisateur

Admin → User.status = SUSPENDED
  → Sessions actives invalidées immédiatement
  → Connexion impossible
  → Historique conservé (factures, contrats, audit)
  → Réactivation possible

Anonymisation RGPD

Demande via /account/data-export ou par admin
  → Période de grâce 30 jours (annulable)
  → Anonymisation (pas suppression) :
     email → anonymized-<id>@deleted.pulsegroup.fr
     name/firstName/lastName → "Utilisateur supprimé"
     phone → null · image → null
     User.anonymizedAt = now()
  → Sessions invalidées
  → Audit log conservé tel quel (obligation légale)

Règles métier

• Unicité email globale (Better Auth) — un email ne peut appartenir qu'à un seul User.
• Unicité Membership sur (userId, organizationId) — un user a un seul rôle par org.
• Au moins 1 ADMIN actif par organisation : impossible de supprimer ou désactiver le dernier ADMIN.
• Rôles système non éditables : Role.isSystem = true est lecture seule (sauf super-admin).
• Invitation expirée : token rejeté avec message clair, possibilité de renvoyer.
• Suspension : sessions invalidées, audit log conservé.
• Multi-tenant strict : activeOrganizationId lu exclusivement depuis la session — jamais depuis le body. Pas de fallback : sans org active, 401. Accès cross-tenant → 404 (pas 403, pour ne pas confirmer l'existence).
• Impersonation : uniquement SUPERADMIN_PROVIDER (full) et ADMIN_PROVIDER (lecture seule). Bandeau rouge persistant. Session d'impersonation limitée à 1 heure. Notification email au user impersonifié dans les 24 h.
• lease.contract:unlock : raison textuelle obligatoire (min 20 caractères), audit log dédié, notification super-admin, re-verrouillage automatique sous 24 h.

Audit log

Systématique sur toute mutation sensible via auditLog(…) dans defineApiHandler. Rétention 10 ans (archive S3 Object Lock Compliance). Consultable sur 12 mois depuis l'app ; au-delà, restauration sur demande.