veza/docs/archive/backend-sessions-2026/MIGRATION_HTTPONLY_COOKIES_BACKEND.md

Migration httpOnly Cookies - Guide Backend

🎯 Objectif

Modifier les endpoints /auth/login et /auth/refresh pour setter des cookies httpOnly au lieu de retourner les tokens dans le body JSON.

📋 Fichiers à Modifier

1. internal/handlers/auth.go - Handler Login

Localisation: Ligne ~121-133

Changements nécessaires:

// Après la génération des tokens (ligne ~121)
// Au lieu de retourner RefreshToken dans le body JSON, setter un cookie httpOnly

// SECURITY: Set refresh token in httpOnly cookie
refreshTokenExpires := 30 * 24 * time.Hour // 30 jours par défaut
if rememberMe {
    refreshTokenExpires = 90 * 24 * time.Hour // 90 jours si remember me
}

c.SetCookie(
    "refresh_token",                    // name
    tokens.RefreshToken,                // value
    int(refreshTokenExpires.Seconds()), // maxAge (en secondes)
    "/",                                // path
    "",                                 // domain (vide = domaine actuel)
    true,                               // secure (HTTPS only en production)
    true,                               // httpOnly (pas accessible via JS)
)

// Retourner uniquement l'access token dans le body (pas le refresh token)
RespondSuccess(c, http.StatusOK, dto.LoginResponse{
    User: dto.UserResponse{
        ID:       user.ID,
        Email:    user.Email,
        Username: user.Username,
    },
    Token: dto.TokenResponse{
        AccessToken: tokens.AccessToken,
        // RefreshToken: tokens.RefreshToken, // ❌ Ne plus retourner dans le body
        ExpiresIn:    int(authService.JWTService.GetConfig().AccessTokenTTL.Seconds()),
    },
})

2. internal/handlers/auth.go - Handler Refresh

Localisation: Ligne ~249-256

Changements nécessaires:

// Dans la fonction Refresh, après la génération des nouveaux tokens

// SECURITY: Set refresh token in httpOnly cookie
// Utiliser la même durée que le refresh token original
refreshTokenExpires := 30 * 24 * time.Hour // 30 jours par défaut
// Note: On pourrait récupérer la durée depuis le token original si nécessaire

c.SetCookie(
    "refresh_token",                    // name
    tokens.RefreshToken,                // value
    int(refreshTokenExpires.Seconds()), // maxAge
    "/",                                // path
    "",                                 // domain
    true,                               // secure
    true,                               // httpOnly
)

// Retourner uniquement l'access token dans le body
RespondSuccess(c, http.StatusOK, dto.TokenResponse{
    AccessToken: tokens.AccessToken,
    // RefreshToken: tokens.RefreshToken, // ❌ Ne plus retourner dans le body
    ExpiresIn:    900,
})

3. internal/handlers/auth.go - Handler Register

Localisation: Ligne ~136-247

Changements nécessaires:

// Après la génération des tokens (ligne ~231)
// Même logique que pour Login

refreshTokenExpires := 30 * 24 * time.Hour // 30 jours par défaut

c.SetCookie(
    "refresh_token",
    tokens.RefreshToken,
    int(refreshTokenExpires.Seconds()),
    "/",
    "",
    true, // secure
    true, // httpOnly
)

// Retourner uniquement l'access token dans le body
response := dto.RegisterResponse{
    User: dto.UserResponse{
        ID:       user.ID,
        Email:    user.Email,
        Username: user.Username,
    },
    Token: dto.TokenResponse{
        AccessToken: tokens.AccessToken,
        // RefreshToken: tokens.RefreshToken, // ❌ Ne plus retourner
        ExpiresIn:    tokens.ExpiresIn,
    },
}

4. internal/handlers/auth.go - Handler Logout

Localisation: À vérifier

Changements nécessaires:

// Lors du logout, supprimer le cookie refresh_token
c.SetCookie(
    "refresh_token",
    "",                    // valeur vide
    -1,                    // maxAge négatif = supprimer
    "/",
    "",
    true,                  // secure
    true,                  // httpOnly
)

5. internal/core/auth/handler.go - Handler Refresh (si utilisé)

Localisation: Ligne ~166-196

Changements similaires:

// Après la génération des nouveaux tokens (ligne ~189)
c.SetCookie(
    "refresh_token",
    tokens.RefreshToken,
    int(30 * 24 * time.Hour.Seconds()), // 30 jours
    "/",
    "",
    true, // secure
    true, // httpOnly
)

response := dto.TokenResponse{
    AccessToken: tokens.AccessToken,
    // RefreshToken: tokens.RefreshToken, // ❌ Ne plus retourner
    ExpiresIn:    900,
}

🔧 Configuration Environnement

Variables d'environnement à ajouter (optionnel)

# Cookie settings
COOKIE_SECURE=true          # true en production, false en dev
COOKIE_SAME_SITE=strict     # strict, lax, ou none
COOKIE_DOMAIN=              # vide pour domaine actuel, ou spécifier le domaine

Utilisation dans le code

// Dans config ou env
cookieSecure := os.Getenv("COOKIE_SECURE") == "true"
cookieSameSite := http.SameSiteStrictMode // ou depuis env

c.SetCookie(
    "refresh_token",
    tokens.RefreshToken,
    int(refreshTokenExpires.Seconds()),
    "/",
    cookieDomain,           // depuis env ou ""
    cookieSecure,           // depuis env
    true,                   // httpOnly toujours true
)

🔄 Compatibilité avec Frontend

Le frontend est déjà préparé pour cette migration :

• ✅ withCredentials: true activé dans apiClient
• ✅ tokenRefresh.ts détecte automatiquement les cookies httpOnly
• ✅ Mode hybride : fonctionne avec localStorage ET cookies httpOnly

⚠️ Notes Importantes

1. SameSite: Utiliser SameSiteStrictMode pour la sécurité maximale
2. Secure: Toujours true en production (HTTPS requis)
3. Domain: Laisser vide pour le domaine actuel, ou spécifier si cross-domain
4. Path: / pour que le cookie soit disponible sur tout le site
5. Tests: Mettre à jour les tests pour vérifier les cookies au lieu du body JSON

🧪 Tests à Mettre à Jour

1. Tests unitaires des handlers Login/Refresh
2. Tests d'intégration pour vérifier les cookies
3. Tests E2E pour vérifier la persistance de session

📝 Checklist

• Modifier handler Login pour setter cookie httpOnly
• Modifier handler Refresh pour setter cookie httpOnly
• Modifier handler Register pour setter cookie httpOnly
• Modifier handler Logout pour supprimer cookie
• Ajouter configuration environnement pour cookies
• Mettre à jour les tests unitaires
• Mettre à jour les tests d'intégration
• Tester avec le frontend
• Documenter les changements