ADR: Transition vers Better Auth Cloudflare pour l'Authentification

Documentation technique

Statut : Proposé
Date : 2026-09-27
Auteur : Team (Agent)

1. Contexte et Problématique1/2

Le système d’authentification actuel utilise un Worker custom auth-handler avec des limitations importantes :

Credentials hardcodés : admin@example.com / password123 par défaut
Single user : Un seul administrateur sans gestion multi-users
Pas de base de données : Stockage sessions uniquement en KV
Maintenance complexe : Logique custom non standard
Pas de sign up : Impossible d’inscrire de nouveaux utilisateurs

1. Contexte et Problématique2/2

Better Auth Cloudflare offre une solution moderne et maintenable avec :

Support natif Cloudflare Workers, D1, KV
Gestion multi-users avec rôles
Schema Drizzle ORM pour migrations
CLI pour génération et migrations automatiques
Intégration transparente avec Astro

2. Décision Architecturale1/4

Nous décidons d’adopter l’architecture suivante :

Remplacement auth-handler par Better Auth Cloudflare :
- Installation de better-auth et better-auth-cloudflare
- Configuration avec D1 pour users/sessions
- Utilisation KV pour secondary storage (cache sessions)
- Migration des sessions existantes si nécessaire

2. Décision Architecturale2/4

Infrastructure Cloudflare :
- Création base D1 amn-auth-db pour stockage users/sessions
- Réutilisation KV existante AUTH_SESSIONS_KV pour secondary storage
- Configuration wrangler.toml avec bindings D1 + KV
- Migration automatique via CLI Better Auth

2. Décision Architecturale3/4

Intégration Astro :
- Configuration Better Auth avec middleware Astro
- Endpoints /api/auth/* gérés par Better Auth
- Session management via cookies HttpOnly + Secure
- TypeScript support automatique

2. Décision Architecturale4/4

Gestion des Secrets :
- Credentials via variables d’environnement
- Suppression des valeurs hardcodées
- Injection secrets via script @inject_secret_to_cloudflare.sh

3. Justification du choix

3.1. Pourquoi Better Auth Cloudflare ?

Natif Cloudflare : Optimisé pour Workers, D1, KV
Moderne et maintenable : Solution active et documentée
CLI puissante : Génération automatique de schéma et migrations
TypeScript support : Typage automatique complet
Flexible : Support D1 (Drizzle ou natif), Postgres, MySQL

3.2. Pourquoi D1 + KV ?

D1 : Base de données SQLite serverless, idéal pour users/sessions
KV : Edge storage pour cache sessions, performances optimales
Coût : D1 et KV sont gratuits/utilisation modérée
Performance : Read replication D1, edge cache KV

3.3. Pourquoi Drizzle ORM ?

Lightweight : Adapté pour Cloudflare Workers
TypeScript : Support typage complet
Migrations : Gestion automatique via CLI
Intégration : Support natif Better Auth

4. Architecture Cible

┌─────────────────────────────────────────────────────────────┐
│                     Application Astro                        │
│  ┌──────────────────┐         ┌──────────────────┐         │
│  │   Middleware     │         │   Pages Auth     │         │
│  │   Astro Auth     │         │   (login, etc)   │         │
│  └────────┬─────────┘         └────────┬─────────┘         │
│           │                            │                     │
│           └────────────┬───────────────┘                     │
│                        │                                     │
└────────────────────────┼─────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              Better Auth Cloudflare                          │
│  ┌──────────────────┐         ┌──────────────────┐         │
│  │   Auth Config    │         │   Endpoints      │         │
│  │   withCloudflare │         │   /api/auth/*    │         │
│  └────────┬─────────┘         └────────┬─────────┘         │
│           │                            │                     │
│           └────────────┬───────────────┘                     │
│                        │                                     │
└────────────────────────┼─────────────────────────────────────┘
                         │
            ┌────────────┴────────────┐
            │                         │
            ▼                         ▼
┌──────────────────────┐   ┌──────────────────────┐
│    Cloudflare D1     │   │   Cloudflare KV      │
│  (users, sessions)   │   │ (secondary storage)  │
└──────────────────────┘   └──────────────────────┘

5. Conséquences de la décision

Effets Positifs (Avantages)

Sécurité renforcée : Plus de credentials hardcodés
Multi-users : Support inscription et gestion multi-users
Maintenance simplifiée : Solution standard et documentée
TypeScript : Support typage complet
Scalabilité : D1 + KV adaptés pour la croissance
Performance : Read replication D1, edge cache KV

Effets Négatifs (Inconvénients & Risques)

Migration complexe : Transition depuis système custom
Learning curve : Nouvelle stack à apprendre
Dépendances : Ajout de packages Better Auth + Drizzle
Configuration : Setup initial D1 + KV + migrations

6. Migration Plan

6.1. Phase 1 : Infrastructure

Créer base D1 amn-auth-db
Configurer wrangler.toml avec bindings D1 + KV
Installer better-auth, better-auth-cloudflare, drizzle-orm

6.2. Phase 2 : Configuration Better Auth

Configurer Better Auth avec withCloudflare()
Setup Drizzle ORM avec schéma users/sessions
Configurer middleware Astro pour Better Auth
Migrer endpoints auth-handler vers Better Auth

6.3. Phase 3 : Migration Données

Créer scripts migration sessions existantes (si nécessaire)
Exécuter migrations D1 via script ./scripts/migrate-d1.sh
Tester flux login/logout/verify
Nettoyer auth-handler après validation

6.4. Phase 4 : Sécurité

Configurer variables d’environnement
Sécuriser cookies (HttpOnly, Secure, SameSite)
Supprimer credentials hardcodés
Tests sécurité complets

7. Alternatives Exclues

Conserver auth-handler custom : Exclus car non maintenable et limité
Utiliser Clerk/Auth0 : Exclus car dépendance externe et coût
Utiliser NextAuth.js : Exclus car non optimisé pour Cloudflare Workers
Base de données externe : Exclus car D1 est suffisant et intégré

8. Configuration Technique

8.1. wrangler.jsonc (apps/web)1/2

Conformément aux recommandations Cloudflare, nous utilisons wrangler.jsonc avec observabilité activée :

8.1. wrangler.jsonc (apps/web)2/2

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "amn-dev",
  "compatibility_date": "2026-09-01",
  "compatibility_flags": ["nodejs_compat"],

  "observability": {
    "enabled": true,
    "logs": {
      "head_sampling_rate": 1
    },
    "traces": {
      "enabled": true,
      "head_sampling_rate": 0.01
    }
  },

  "d1_databases": [
    {
      "binding": "AUTH_DB",
      "database_name": "amn-auth-db",
      "database_id": "<d1-id>",
      "migrations_dir": "drizzle"
    }
  ],

  "kv_namespaces": [
    {
      "binding": "AUTH_KV",
      "id": "4a990eb34db9430284b0961ac5d107dd"
    }
  ]
}

8.2. Configuration Better Auth

import { betterAuth } from "better-auth";
import { withCloudflare } from "better-auth-cloudflare";
import { drizzleAdapter } from "@better-auth/drizzle-adapter";
import { drizzle } from "drizzle-orm/d1";

export const auth = betterAuth({
  ...withCloudflare(
    {
      d1: {
        db: drizzle(env.AUTH_DB, { schema }),
        options: { usePlural: true }
      },
      kv: env.AUTH_KV,
      cf: request.cf
    },
    {
      database: drizzleAdapter(db, { provider: "sqlite" }),
      session: {
        expiresIn: 60 * 60 * 24 * 7, // 7 days
        updateAge: 60 * 60 * 24 // 1 day
      },
      advanced: {
        cookiePrefix: "amn-auth"
      }
    }
  )
});

8.3. Variables d’Environnement

# Better Auth
BETTER_AUTH_SECRET=<random-secret>
BETTER_AUTH_URL=http://localhost:4321

# Cloudflare
AUTH_DB_ID=<d1-database-id>
AUTH_KV_ID=4a990eb34db9430284b0961ac5d107dd

9. Historique des modifications

Date	Version	Description	Auteur
2026-09-27	1.0	Création initiale ADR Transition Better Auth	Team (Agent)