docs: publish session configuration guides

docs/.vitepress/config.mts

@@ -23,6 +23,7 @@ export default defineConfig({
                 nav: [
                     { text: "Accueil", link: "/fr/" },
                     { text: "Prérequis", link: "/fr/self-hosting/prerequisites" },
+                    { text: "Sessions", link: "/fr/self-hosting/authentication" },
                     { text: "Guide en anglais", link: "/" },
                     { text: "Code source", link: "https://github.com/TypeType-Video/TypeType" },
                 ],
@@ -35,6 +36,10 @@ export default defineConfig({
                                     text: "Prérequis et ressources",
                                     link: "/fr/self-hosting/prerequisites",
                                 },
+                                {
+                                    text: "Sessions de compte",
+                                    link: "/fr/self-hosting/authentication",
+                                },
                             ],
                         },
                     ],
@@ -81,6 +86,7 @@ export default defineConfig({
                 nav: [
                     { text: "Inicio", link: "/es/" },
                     { text: "Requisitos", link: "/es/self-hosting/prerequisites" },
+                    { text: "Sesiones", link: "/es/self-hosting/authentication" },
                     { text: "Guía en inglés", link: "/" },
                     { text: "Código fuente", link: "https://github.com/TypeType-Video/TypeType" },
                 ],
@@ -93,6 +99,10 @@ export default defineConfig({
                                     text: "Requisitos y recursos",
                                     link: "/es/self-hosting/prerequisites",
                                 },
+                                {
+                                    text: "Sesiones de cuenta",
+                                    link: "/es/self-hosting/authentication",
+                                },
                             ],
                         },
                     ],

docs/es/self-hosting/authentication.md

@@ -0,0 +1,46 @@
+# Sesiones de cuenta
+
+Después de iniciar sesión de forma local o mediante OIDC, el token de acceso de
+TypeType dura una hora. Una sesión de actualización renueva automáticamente ese
+token sin pedir otro inicio de sesión.
+
+## Duración de la sesión
+
+La sesión de actualización dura 30 días de forma predeterminada. Puedes elegir una
+duración de 1 a 365 días en `.env`:
+
+```dotenv
+AUTH_SESSION_TTL_DAYS=90
+```
+
+La nueva duración se aplica a las sesiones creadas o renovadas después del cambio.
+Vuelve a crear Server para aplicar la configuración:
+
+```sh
+docker compose up -d --force-recreate typetype-server
+```
+
+## HTTPS y redes locales
+
+De forma predeterminada, la cookie de actualización es `HttpOnly`, `Secure` y
+`SameSite=None`. Usa HTTPS para cualquier instancia pública.
+
+En una red local de confianza que no pueda usar HTTPS, una opción de compatibilidad
+permite que la cookie funcione mediante HTTP con `SameSite=Lax`:
+
+```dotenv
+AUTH_ALLOW_INSECURE_COOKIES=true
+```
+
+::: danger
+No actives esta opción en Internet ni en una red que no sea de confianza. La cookie
+podría viajar por una conexión HTTP sin cifrar.
+:::
+
+Un cierre de sesión exactamente después de una hora suele indicar que la cookie de
+actualización no fue enviada o aceptada. Comprueba también que `ALLOWED_ORIGINS`
+contenga exactamente el origen del navegador.
+
+La guía completa en inglés explica la
+[autenticación](/self-hosting/authentication) y la
+[resolución de cierres de sesión](/self-hosting/troubleshooting#unexpected-sign-outs).

docs/fr/self-hosting/authentication.md

@@ -0,0 +1,46 @@
+# Sessions de compte
+
+Après une connexion locale ou OIDC, le jeton d'accès TypeType est valable pendant
+une heure. Une session de rafraîchissement renouvelle automatiquement ce jeton, sans
+demander une nouvelle connexion.
+
+## Durée de la session
+
+La session de rafraîchissement dure 30 jours par défaut. Vous pouvez choisir une
+durée de 1 à 365 jours dans `.env` :
+
+```dotenv
+AUTH_SESSION_TTL_DAYS=90
+```
+
+La nouvelle durée s'applique aux sessions créées ou renouvelées après le changement.
+Recréez Server pour appliquer la configuration :
+
+```sh
+docker compose up -d --force-recreate typetype-server
+```
+
+## HTTPS et réseaux locaux
+
+Par défaut, le cookie de rafraîchissement est `HttpOnly`, `Secure` et
+`SameSite=None`. Utilisez HTTPS pour toute instance publique.
+
+Sur un réseau local de confiance qui ne peut pas utiliser HTTPS, une option de
+compatibilité permet au cookie de fonctionner en HTTP avec `SameSite=Lax` :
+
+```dotenv
+AUTH_ALLOW_INSECURE_COOKIES=true
+```
+
+::: danger
+N'activez pas cette option sur Internet ou sur un réseau non fiable. Le cookie peut
+alors circuler dans une connexion HTTP non chiffrée.
+:::
+
+Une déconnexion exactement après une heure indique généralement que le cookie de
+rafraîchissement n'a pas été envoyé ou accepté. Vérifiez aussi que
+`ALLOWED_ORIGINS` contient exactement l'origine du navigateur.
+
+Le guide complet en anglais détaille
+[l'authentification](/self-hosting/authentication) et le
+[dépannage des déconnexions](/self-hosting/troubleshooting#unexpected-sign-outs).

docs/self-hosting/authentication.md

@@ -95,15 +95,41 @@ reference and the current provider documentation for its exact schema.
 ## Session lifetime
 
 After local or OIDC login, the access token lasts one hour. The browser also receives
-a rotating refresh cookie valid for 30 days, so normal access-token expiry should be
-silent. There is no separate “remember me” duration setting.
+a rotating refresh cookie, so normal access-token expiry should be silent. The refresh
+session lasts 30 days by default. Set `AUTH_SESSION_TTL_DAYS` in `.env` to choose a
+value from 1 to 365 days:
+
+```dotenv
+AUTH_SESSION_TTL_DAYS=90
+```
+
+This duration applies to newly issued and renewed sessions. Existing database rows
+keep their current expiry until the next successful refresh or login.
 
 The refresh cookie is `HttpOnly`, `Secure`, and `SameSite=None`. A public deployment
 therefore needs HTTPS, the correct `ALLOWED_ORIGINS`, and proxy handling that keeps
 credentialed requests intact. See
 [Unexpected sign-outs](./troubleshooting#unexpected-sign-outs) if a user is logged out
 while active.
 
+For a trusted local network that cannot use HTTPS, an explicit compatibility option
+can issue the refresh cookie without `Secure` and with `SameSite=Lax`:
+
+```dotenv
+AUTH_ALLOW_INSECURE_COOKIES=true
+```
+
+::: danger
+Do not enable this option on a public or untrusted network. Account refresh cookies
+can travel over unencrypted HTTP. HTTPS remains the supported default.
+:::
+
+After changing either variable, recreate Server:
+
+```sh
+docker compose up -d --force-recreate typetype-server
+```
+
 This explanation follows the behavior questioned by
 [Toni-Vide in discussion #162](https://github.com/TypeType-Video/TypeType/discussions/162)
 and verified in the current authentication source.

docs/self-hosting/configuration.md

@@ -50,6 +50,27 @@ docker compose up -d --force-recreate typetype-server
 This diagnostic was confirmed through
 [hulmgulm's first-admin report](https://github.com/TypeType-Video/TypeType/discussions/151).
 
+## Account sessions
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `AUTH_SESSION_TTL_DAYS` | `30` | Refresh-session lifetime in days, clamped to `1`–`365` |
+| `AUTH_ALLOW_INSECURE_COOKIES` | `false` | Allows refresh cookies over plain HTTP with `SameSite=Lax` |
+
+Access tokens always last one hour. A valid refresh session renews them silently, so
+`AUTH_SESSION_TTL_DAYS` controls how long an account can remain signed in without a
+new login.
+
+Keep `AUTH_ALLOW_INSECURE_COOKIES=false` for HTTPS and every public deployment. Set
+it to `true` only when a trusted local-only instance must run over plain HTTP. This
+weakens transport security; see [Session lifetime](./authentication#session-lifetime).
+
+Recreate Server after changing either value:
+
+```sh
+docker compose up -d --force-recreate typetype-server
+```
+
 ## Database and cache
 
 The bundled PostgreSQL service uses these values:

docs/self-hosting/troubleshooting.md

@@ -92,13 +92,13 @@ original [community diagnosis](https://github.com/TypeType-Video/TypeType/discus
 
 ## Unexpected sign-outs {#unexpected-sign-outs}
 
-An account access token lasts one hour, but the refresh session lasts 30 days. The
-Frontend refreshes automatically when an authenticated request returns `401`, so a
-sign-out at the one-hour mark is not expected normal behavior.
+An account access token lasts one hour, but the refresh session lasts 30 days by
+default. The Frontend refreshes automatically when an authenticated request returns
+`401`, so a sign-out at the one-hour mark is not expected normal behavior.
 
 Check:
 
-1. The page uses HTTPS on a public domain. The refresh cookie is `Secure`.
+1. The page uses HTTPS. The refresh cookie is `Secure` by default.
 2. `ALLOWED_ORIGINS` contains the exact browser origin.
 3. Login and `/api/auth/refresh` requests include credentials and are not stripped by
    a custom proxy.
@@ -110,9 +110,15 @@ sets `JWT_SECRET`. That invalidates the old one-hour access token, but the norma
 refresh flow should recover immediately when the PostgreSQL session and refresh
 cookie are still present. A restart alone should therefore not require a new login.
 
-There is no admin setting that extends the 30-day lifetime. If the problem continues,
-capture Server logs around `/auth/refresh`, the browser response status, and the
-deployed revisions. Do not include the cookie or any bearer token.
+For a trusted local-only instance that cannot use HTTPS, set
+`AUTH_ALLOW_INSECURE_COOKIES=true` and recreate `typetype-server`. This deliberately
+weakens cookie transport security and must not be used on a public or untrusted
+network. `AUTH_SESSION_TTL_DAYS` can change the refresh lifetime from 1 to 365 days.
+See [Session lifetime](./authentication#session-lifetime).
+
+If the problem continues, capture Server logs around `/auth/refresh`, the browser
+response status, and the deployed revisions. Do not include the cookie or any bearer
+token.
 
 This checklist follows the unexpected behavior reported by
 [Toni-Vide in discussion #162](https://github.com/TypeType-Video/TypeType/discussions/162).