Intégration du Dashboard Better Auth Infrastructure

Vue d’ensemble

Le plugin dash() de Better Auth Infrastructure fournit un dashboard web pour la gestion des utilisateurs, des sessions, des organisations et l’analyse de l’activité d’authentification.

Installation et Configuration

1. Installation du package

cd apps/web
pnpm add @better-auth/infra@latest

Note : Utiliser la version @latest pour garantir la compatibilité avec Better Auth 1.7.6 et Zod v4.

2. Configuration serveur

Le plugin dash() est intégré dans src/auth/index.ts avec activation conditionnelle :

import { dash } from "@better-auth/infra";

// Prepare plugins array
const plugins: any[] = [admin()];

// Add dash plugin if API key is provided
if (env.BETTER_AUTH_API_KEY) {
  plugins.push(dash({
    apiKey: env.BETTER_AUTH_API_KEY,
    activityTracking: {
      enabled: true,
      updateInterval: 300000 // 5 minutes
    }
  }));
}

3. Configuration client

Le plugin client sentinelClient() est intégré dans src/lib/auth-client.ts :

import { sentinelClient } from "@better-auth/infra/client";

export const authClient = createAuthClient({
  plugins: [
    adminClient(),
    sentinelClient()
  ]
});

4. Configuration baseURL

Le baseURL doit inclure le base path /api/auth selon la configuration du projet Better Auth Infrastructure :

baseURL: env.BETTER_AUTH_URL || (isProd
  ? 'https://amn-dev.anderson-metsanou.workers.dev/api/auth'
  : 'http://localhost:8787/api/auth')

5. Variables d’environnement

Ajouter dans .env :

BETTER_AUTH_API_KEY=<your-better-auth-infra-api-key>

6. Migration de base de données

Le plugin ajoute le champ last_active_at à la table user pour le tracking d’activité :

# Local
npx wrangler d1 migrations apply amn-auth-db-dev --local

# Remote
npx wrangler d1 migrations apply amn-auth-db-dev --remote

Résolution du conflit de versions Zod

Problème

Better Auth 1.7.6 utilise Zod v4.6.5, mais certaines versions de @better-auth/infra et les services form-handler/submission-processor utilisaient Zod v3.25.76, créant un conflit de versions.

Solution

1. Mettre à jour les services pour utiliser Zod v4 :

   cd services/form-handler
   pnpm add zod@^4.6.5
   
   cd ../submission-processor
   pnpm add zod@^4.6.5

2. Ajouter zod et @better-auth/infra aux dépendances du monorepo dans package.json :

   {
     "dependencies": {
       "better-auth": "1.7.6",
       "@better-auth/infra": "^0.4.12",
       "zod": "^4.6.5"
     }
   }

3. Reinstaller les dépendances :

   cd /home/anderson/PP
   rm -rf node_modules pnpm-lock.yaml
   pnpm install

GitHub Actions Workflows

Les workflows de déploiement ont été mis à jour pour injecter BETTER_AUTH_API_KEY :

deploy-dev.yml

Ajout de l’injection du secret :

echo "${{ secrets.BETTER_AUTH_API_KEY }}" | npx wrangler secret put BETTER_AUTH_API_KEY --env dev --cwd apps/web

deploy-prod.yml

Ajout de l’injection du secret :

echo "${{ secrets.BETTER_AUTH_API_KEY }}" | npx wrangler secret put BETTER_AUTH_API_KEY --env prod --cwd apps/web

Configuration GitHub Secrets

Ajouter le secret BETTER_AUTH_API_KEY dans les secrets du repository GitHub avec la valeur de votre clé API Better Auth Infrastructure.

Fonctionnalités du Dashboard

Une fois activé, le dashboard Better Auth Infrastructure offre :

• Gestion des utilisateurs : visualiser, rechercher, bannir et supprimer des utilisateurs
• Monitoring des sessions : voir les sessions actives et les révoquer
• Aperçu des organisations : gérer les organisations et leurs membres
• Analytics : suivre les inscriptions, connexions et utilisateurs actifs
• Logs d’audit : consulter l’historique des événements

Activation

Le plugin est activé uniquement si la variable d’environnement BETTER_AUTH_API_KEY est définie. Cela permet :

• Développement sans dashboard (pas d’API key requise)
• Production avec dashboard complet (API key configurée)
• Build réussi même sans API key

Procédure de connexion au Dashboard

1. Déployer l’application sur Cloudflare via GitHub Actions (branche main)
2. Accéder au dashboard Better Auth Infrastructure
3. Entrer l’URL de l’application : https://amn-dev.anderson-metsanou.workers.dev/api/auth
4. Cliquer sur “Retry connection” pour vérifier la propriété
5. Le dashboard sera accessible une fois la connexion établie

Test local

Pour tester localement avec le dashboard :

1. Ajouter BETTER_AUTH_API_KEY au fichier .env local
2. Lancer le serveur de développement : task dev:wrangler
3. Accéder au dashboard via l’URL fournie par Better Auth Infrastructure
4. Vérifier que les endpoints Better Auth fonctionnent correctement

Déploiement

Pour le déploiement sur Cloudflare :

1. Ajouter BETTER_AUTH_API_KEY aux secrets GitHub Actions
2. Commettre et pousser les changements (workflow deploy-dev déclenché automatiquement)
3. Le workflow injectera le secret et déploiera
4. Le dashboard sera automatiquement activé en production

Dépannage

Build échoue sans API key

Le plugin est conditionnellement chargé, donc le build fonctionne même sans API key.

Erreur “zod_default.url is not a function”

Cette erreur indique un conflit de versions Zod. S’assurer que :

• @better-auth/infra est en version 0.4.12 ou supérieure
• zod est en version 4.6.5 dans tout le workspace
• Les services form-handler et submission-processor utilisent Zod v4

Dashboard non accessible

• Vérifier que BETTER_AUTH_API_KEY est correctement configurée dans les secrets Cloudflare
• S’assurer que l’API key est valide et active
• Vérifier que le baseURL inclut le base path /api/auth
• Vérifier les logs du worker pour les erreurs de connexion

Typecheck échoue

Vérifier que l’import dans apps/web/auth.ts utilise le bon chemin :

import { dash } from "@better-auth/infra"; // Correct
// PAS import { dash } from "@better-auth/infra/plugins"; // Incorrect

Tracking d’activité non fonctionnel

• Vérifier que la migration last_active_at a été appliquée
• S’assurer que activityTracking.enabled est true dans la configuration