Middleware Astro : Contrôle d'accès et Authentification Starlight Docs

Objet : Middleware d’accès et authentification pour les documents Starlight (Public / Privé)
Type : ObjectData (DAT)
Couche : Couche 02 (Présentation - Astro)
Emplacement : apps/web/src/middleware.ts
Slice : Component 4 (Documentation Starlight)
Statut : DOC / Proposé

---

1. Vue d’ensemble (DOC)

1.1. Description

Ce middleware intercepte toutes les requêtes entrantes destinées aux sections de documentation (/docs/*, /gettingstarted/*, /getting-started/*, etc.). Il lit les métadonnées de visibilité du document (visibility: 'public' | 'private') via la Content Layer Astro (getEntry('docs', ...)) et vérifie l’état d’authentification auprès de Better Auth.

1.2. Objectif

• Intercepter les requêtes de consultation des documents techniques.
• Autoriser la consultation libre des documents déclarés publics (visibility: 'public').
• Restreindre l’accès aux documents déclarés privés (visibility: 'private', valeur par défaut) aux seuls utilisateurs authentifiés via Better Auth.
• Rediriger vers la page de connexion /login?callbackURL=<pathname> si l’accès à un document privé est tenté sans session authentifiée valide.

---

2. Configuration et Schéma (CODE)

2.1. Métadonnées Frontmatter des documents Starlight

Chaque fichier Markdown/MDX dans docs/ et GettingStarted/ possède un frontmatter :

---
title: "Titre du document"
description: "Description"
visibility: "private" # Valeurs acceptées: "public" | "private" (défaut: "private")
---

2.2. Interface App.Locals (TypeScript)

apps/web/src/env.d.ts

declare namespace App {
  interface Locals {
    env?: Env;
    user?: {
      id: string;
      email: string;
      role: string;
    } | null;
  }
}

---

3. Architecture et flux

Utilisateur -> HTTP Request (/docs/...)
                      │
                      ▼
            [Astro SSR Middleware]
                      │
                      ├── Document public ? ---> [Rendu Starlight OK]
                      │
                      └── Document privé ?
                                │
                                ▼
                    [Vérification Session Better Auth]
                                │
            ┌───────────────────┴───────────────────┐
            │ (Valide)                              │ (Invalide / Absent)
            ▼                                       ▼
    [Locals.user injecté]             [Redirect 302 -> /login?callbackURL=...]
            │
            ▼
    [Rendu Starlight Privé OK]

---

4. Contrats d’Entrée/Sortie (SPEC)

4.1. Inputs (Requête HTTP)

• URL Path : Ex. /docs/l1_contenu/... ou /gettingstarted/01-setup-local
• Cookies : Cookie de session Better Auth (better-auth.session_token)

4.2. Outputs (Réponse Middleware)

Condition	Action / Code HTTP	Destination
Route publique (visibility: 'public')	next() (200 OK)	Page Starlight affichée
Route privée + Session Better Auth valide	next() (200 OK)	Page Starlight affichée avec locals.user
Route privée + Session invalide/absente	302 Found	/login?callbackURL=<pathname>

---

5. Sécurité

1. Pas de rendu statique public pour les pages privées : Les routes protégées s’exécutent en mode SSR (prerender = false), empêchant la présence d’un fichier HTML statique lisible sur un CDN.
2. Cookies HttpOnly; Secure; SameSite=Lax : Better Auth gère les cookies de session avec protection CSRF et attributs sécurisés.
3. Privé par défaut : Tout document dont la visibilité n’est pas explicitement définie comme public est traité comme private.

---

6. Tests attendus (TEST)

1. Test unitaire / Fonctionnel (Middleware) :
   • Requête sur route publique sans session -> Accès autorisé (200 OK).
   • Requête sur route privée sans session -> Redirection /login?callbackURL=... (302 Found).
   • Requête sur route privée avec session valide -> Accès autorisé (200 OK).
2. Test d’intégration (Better Auth & D1/KV) :
   • Validation de session sur base D1 et cache KV.

---

7. Historique des modifications

Date	Version	Description	Auteur
2026-09-24	1.0	Création initiale DAT Starlight Auth Middleware	Team (Agent)
2026-09-27	1.1	Migration vers Better Auth et clarification visibilité	Team (Agent)
2026-10-12	1.2	Réintégration du contrôle de visibilité Starlight avec Better Auth	Antigravity