SPEC — Intégration Starlight Documentation & Worker Cloudflare d'Authentification (Public / Privé)

Cycle : DOC → SPEC → CODE → TEST → INTÉG
Composant : Composant 4 (Documentation Starlight & Microservice Auth L3)
Destination Spec : docs/PM/phase0-starlight-docs-auth.spec.md

---

1. Périmètre et Objectifs

1. Montage des sources de documentation :

   • Brancher les dossiers racine ../../docs et ../../GettingStarted dans la couche de contenu Astro (src/content.config.ts) à l’aide de chargeurs glob().
   • Exposer l’arborescence dans l’interface Starlight.

2. Politique de Visibilité & Sécurité (Public vs Privé) :

   • Définir le schéma frontmatter Starlight avec visibility: z.enum(['public', 'private']).default('private').
   • Public : Consultable librement sans authentification (ex: aperçus, guides généraux).
   • Privé (par défaut) : Restreint aux seuls utilisateurs connectés ayant une session valide.

3. Microservice d’Authentification L3 (services/auth-handler) :

   • Créer le Worker Cloudflare services/auth-handler (amn-auth-handler).
   • Endpoints : POST /api/auth/login, POST /api/auth/logout, GET /api/auth/verify, GET /health.
   • Bindings : AUTH_SESSIONS_KV (KV Namespace), AUTH_SECRET (Secret).
   • Cookies : auth_session avec attributs HttpOnly; Secure; SameSite=Lax.
   • Environnements Cloudflare : dev et prod.

4. Middleware SSR Astro (apps/web/src/middleware.ts) :

   • Intercepter les requêtes ciblant /docs/* et /getting-started/*.
   • Consulter la visibilité du document demandé.
   • Pour les documents private : vérifier la validité de la session via le Service Binding AUTH_HANDLER (en prod) ou HTTP fetch direct vers http://localhost:8790 (en dev).
   • Rediriger les requêtes non authentifiées vers /login?redirectTo=....

---

2. Spécification détaillée des Fichiers à Modifier & Créer

2.1. Microservice Backend L3 (services/auth-handler/)

1. services/auth-handler/package.json :

   • Déclarer le package @amn/auth-handler avec les scripts build, dev, typecheck, deploy:dev, deploy:prod.
   • Dépendances : zod, @cloudflare/workers-types.

2. services/auth-handler/wrangler.toml :

   name = "amn-auth-handler"
   main = "src/index.ts"
   compatibility_date = "2025-07-18"
   compatibility_flags = ["nodejs_compat"]
   
   [vars]
   ENVIRONMENT = "dev"
   
   [[kv_namespaces]]
   binding = "AUTH_SESSIONS_KV"
   id = "auth-sessions-kv-id"
   
   [env.dev]
   name = "amn-auth-handler-dev"
   vars = { ENVIRONMENT = "dev" }
   
   [env.prod]
   name = "amn-auth-handler-prod"
   vars = { ENVIRONMENT = "prod" }

3. services/auth-handler/src/index.ts :

   • Logique de validation Zod des identifiants (ex: email, password).
   • Génération du token de session crypto.randomUUID(), stockage dans AUTH_SESSIONS_KV avec TTL (24h).
   • Invalidation lors du logout (AUTH_SESSIONS_KV.delete()).
   • Verification rapide de session pour apps/web.

2.2. Couche Présentation L2 (apps/web/)

1. apps/web/astro.config.mjs & src/content.config.ts :

   • Étendre Starlight et content.config.ts pour charger la collection docs depuis ../../docs et ../../GettingStarted.
   • Intégrer le schéma visibility: z.enum(['public', 'private']).default('private').

2. apps/web/src/middleware.ts :

   • Détecter si l’URL requêtée appartient à la documentation.
   • Déterminer la visibilité de la page.
   • En cas de page private, valider le cookie auth_session avec le worker AUTH_HANDLER (Service Binding en prod, HTTP localhost en dev).
   • Si valide : alimenter context.locals.user.
   • Si invalide : rediriger vers /login?redirectTo=....

3. apps/web/src/pages/login.astro :

   • Page simple de connexion avec formulaire (email / password) qui POST vers /api/auth/login pour établir la session et rediriger l’utilisateur vers le document initialement demandé.

4. Taskfile.yaml :

   • Ajouter la tâche dev:auth (cd services/auth-handler && pnpm dev --port 8790).
   • Mettre à jour la tâche dev pour démarrer conjointement apps/web, sanity studio et services/auth-handler.

---

3. Matrice de Test & Critères de Validation (TEST)

1. Test d’accès aux documents publics :

   • Un utilisateur non connecté peut accéder directement aux documents marqués visibility: 'public' (HTTP 200 OK).

2. Test d’accès restreint aux documents privés :

   • Un utilisateur non connecté tentant d’accéder à un document privé (ou par défaut sans tag public) est redirigé vers /login?redirectTo=....

3. Test d’authentification & session :

   • Soumission des identifiants sur /login -> création du cookie auth_session et session enregistrée dans KV.
   • Redirection automatique vers le document privé initialement demandé. Accessibilité confirmée (HTTP 200 OK).

4. Test de déconnexion :

   • Appel /api/auth/logout -> suppression du cookie et d’enregistrement KV -> tentative ultérieure d’accès au document privé redirige à nouveau vers /login.

5. Validation Typecheck & Build :

   • npx pnpm typecheck retourne 0 erreur.
   • npx pnpm --filter ./apps/web build et build du service auth-handler s’exécutent avec succès.

---

4. Documentation des Instructions de Test (INTÉG)

Rédiger le guide de test pas-à-pas dans GettingStarted/13-phase0-starlight-docs-auth-test.md.