Skip to content
AMN Docs

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

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

Documentation technique

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
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare