Skip to content
AMN Docs

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

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

Documentation technique

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 Objectifs1/4

  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.

1. Périmètre et Objectifs2/4

  1. 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.

1. Périmètre et Objectifs3/4

  1. 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.

1. Périmètre et Objectifs4/4

  1. 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/3

  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.1. Microservice Backend L3 (services/auth-handler/)2/3

  1. 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" }

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

  1. 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/4

  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.2. Couche Présentation L2 (apps/web/)2/4

  1. 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=....

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

  1. 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é.

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

  1. 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/3

  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. Matrice de Test & Critères de Validation (TEST)2/3

  1. 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).

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

  1. 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.

  2. 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.

Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare