Authentification & RBAC

Pulse ERP utilise Better Auth 1.4+ comme unique couche d'authentification, avec le plugin Organization pour le multi-tenant natif. Cette page est la référence développeur : ne touchez pas à server/lib/auth.ts sans avoir lu cette documentation.

Better Auth — pile et configuration

export const auth = betterAuth({
  database: prismaAdapter(prisma, { provider: 'postgresql' }),
  baseURL: process.env.AUTH_BASE_URL!,
  secret: process.env.AUTH_SECRET!,
  emailAndPassword: {
    enabled: true,
    requireEmailVerification: true,
    minPasswordLength: 12,
    autoSignIn: false,
  },
  session: {
    expiresIn: 60 * 60 * 24 * 30,       // 30 jours
    updateAge: 60 * 60 * 24,             // refresh quotidien
    cookieCache: { enabled: true, maxAge: 5 * 60 },
  },
  plugins: [
    organization({ allowUserToCreateOrganization: false, organizationLimit: 50 }),
    twoFactor({ issuer: 'Pulse ERP', skipVerificationOnEnable: false }),
    magicLink({ expiresIn: 15 * 60, sendMagicLink: /* email helper */ }),
    admin({ adminRoles: ['SUPERADMIN_PROVIDER', 'ADMIN_PROVIDER'], impersonationSessionDuration: 3600 }),
  ],
})

Endpoints Better Auth exposés

Le catch-all server/api/auth/[...all].ts délègue tout à auth.handler().

Composable front

export const useAuthClient = () => createAuthClient({
  baseURL: useRuntimeConfig().public.authBaseUrl,
  plugins: [organizationClient(), twoFactorClient(), magicLinkClient(), adminClient()],
})

Parcours utilisateur

Aucune auto-inscription publique — tout compte est créé par invitation ou par le super-admin Pulse.

1. Invitation : l'admin saisit email + rôle → email d'invitation → l'invité choisit son mot de passe, active MFA, accepte les CGU → Membership créé.
2. Première connexion : si Account.passwordResetRequired = true, redirection forcée vers /auth/set-password, puis écran MFA TOTP, puis acceptation CGU.
3. Connexion standard : email + mot de passe → code TOTP si MFA actif → sélection d'organisation si l'utilisateur appartient à plusieurs → dashboard selon rôle.

Multi-tenant — organisation active

Better Auth Organization plugin injecte session.activeOrganizationId dans chaque cookie de session. Toutes les routes API lisent cette valeur depuis la session ; elle n'est jamais acceptée depuis le corps de la requête.

// ✅ Correct
const organizationId = ctx.organizationId // injecté par defineApiHandler

// ❌ Interdit
const organizationId = body.organizationId

Un même utilisateur peut appartenir à plusieurs organisations (ex. : salarié Pulse + client en AUDITOR). Le composant OrganizationSwitcher dans la topbar appelle POST /api/auth/organization/set-active.

Modèle de rôles

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

Rôles globaux

Rôles métier (par Membership)

Les rôles métier sont modifiables par organisation via Role + RolePermission. Un rôle peut hériter des permissions d'un autre avec des ajustements.

Matrice de permissions (extrait)

Format des permissions : domain.entity:action. Légende : ✅ = oui · R = lecture · R/W = lecture+écriture · ❌ = aucun accès.

Ces valeurs sont les défauts du seed. Chaque organisation peut les personnaliser via son admin.

Vérification des permissions — defineApiHandler

Toute route API passe par defineApiHandler (dans server/lib/handler.ts). Il vérifie la session, résout organizationId, contrôle la permission déclarée, exécute le handler, puis écrit l'audit log si demandé.

export default defineApiHandler(
  {
    permission: 'asset:create',
    audit: { action: 'asset.create', targetType: 'Asset' },
  },
  async (event, ctx) => {
    const input = await validateBody(event, AssetCreateDto)
    return createAsset({ organizationId: ctx.organizationId!, actor: ctx.session.user, input })
  },
)

ctx expose :

• ctx.session — session Better Auth complète
• ctx.organizationId — string (jamais undefined si requireOrganization n'est pas désactivé)

Côté UI, la même permission est vérifiée dans les composables/pages via usePermission('asset:create') pour masquer les actions inaccessibles.

Garde-fous métier

lease.contract:unlock — cas particulier

Le déverrouillage d'un contrat signé est une action exceptionnelle.

Conditions obligatoires à chaque déverrouillage :

• Raison textuelle (min 20 caractères).
• Audit log dédié lease.contract.unlock avec unlockedAt, unlockedById, unlockReason.
• Notification à la direction Pulse (super-admin alerté par email).
• Re-verrouillage automatique après 24 heures.

Impersonation

Réservée à SUPERADMIN_PROVIDER (écriture) et ADMIN_PROVIDER (lecture seule via middleware impersonation-readonly.ts).

Garde-fous actifs :

• Bandeau visuel rouge persistant : « Vous impersonifiez X (admin : Y). Arrêter ».
• Session limitée à 1 heure.
• Chaque action porte impersonatorUserId ET actorUserId distincts dans l'audit log.
• Email de notification au compte impersonifié dans les 24 heures.

Audit log

Quand journaliser

Rétention

• 10 ans (couverture comptable + commerciale).
• Archive S3 mensuelle en Object Lock Compliance 10 ans.
• Consultation dans l'app sur 12 mois glissants ; restauration archive sur demande au-delà.

Affichage

• Page /admin/audit : filtres par acteur, action, période, cible.
• Onglet « Historique » sur chaque fiche entité (composant AuditTrail réutilisable).

Tokens API (ApiKey)

Format : pk_live_ + 24 caractères aléatoires. Le hash bcrypt est stocké, le préfixe est visible en UI.

• Scopes restrictifs : pas de token all-access.
• Expiration max 90 jours par défaut.
• lastUsedAt mis à jour à chaque appel.
• Révocation immédiate.

Tests attendus

Tests E2E Playwright obligatoires : login complet avec MFA, reset mot de passe, verrouillage après 5 échecs, switch organisation.