smart_ide/services/docv/enso-docs/docv/AUTH_SESSION.md

docv-back — Sessions OAuth, cookies et durées (référence unique)

Ce document centralise les durées et le contrôle d’accès via office_members (quels offices la métier GET /api/v1/offices retourne pour un jeton), ainsi que les variables de contournement pour bases de test.

Modèle produit : espaces, rôles et sociétés

• Sociétés (offices côté API) : ce sont les sociétés clientes du cabinet, pas des « rattachements personnels » au sens où un même déploiement docv peut servir plusieurs espaces (applications / contextes) selon le rôle porté par la session.
• Premier espace (périmètre cabinet actuel) : l’utilisateur connecté est un acteur du cabinet (collaborateur, stagiaire, comptable, expert-comptable, associé, administrateur, etc.). Il accède aux dossiers des sociétés clientes que le produit lui expose pour ce rôle — pas comme un utilisateur final « membre client » rattaché à sa société au même titre que dans l’espace dédié clients.
• Autres espaces (clients) : réservés aux utilisateurs clients, rattachés aux sociétés avec rôles et sous-rôles métier ; la charge utile et les écrans suivent ce modèle.
• Même e-mail, plusieurs rôles : le choix d’espace / de rôle au login est géré par docv (sélection lorsque plusieurs contextes s’appliquent).

La table office_members reste le mécanisme d’implémentation qui lie un user_uid à des office_uid pour qu’un jeton voie des sociétés ; elle ne documente pas à elle seule la sémantique métier « cabinet vs client » — celle-ci vient du contexte de session / de rôle docv. Les variables ci-dessous ne remplacent ni ce modèle ni le choix au login.

Variables d’environnement (docv-back)

Variable	Rôle	Défaut / valeurs
DOCV_OAUTH_ACCESS_TOKEN_TTL_SEC	Durée unique pour : (1) claims JWT exp et champ expires_in du POST /oauth/token ; (2) claims exp du JWT embarqué dans le cookie docv_oauth_session ; (3) attribut Max-Age de ce cookie après POST /oauth/sign-in.	900 (15 min). Plage 60–86400.
DOCV_DEMO_MEMBER_EMAILS	Contournement test / données incomplete : au démarrage, pour chaque email listé (virgules), si l’utilisateur n’a aucune ligne office_members, insertion sur le plus ancien office (ORDER BY created_at ASC) en rôle client (libellé technique BDD).	Vide = désactivé.
DOCV_LINK_ORPHAN_USERS_TO_FIRST_OFFICE	Contournement test uniquement : si 1, true, yes ou on (insensible à la casse), tous les utilisateurs sans office_members sont liés au plus ancien office en client. Ne représente pas le rattachement métier cabinet ↔ sociétés ni client ↔ sociétés ; à n’utiliser que pour aligner une BDD de test (ex. liste Sociétés vide alors que des offices existent).	Désactivé si absent.

Cohérence Bearer ↔ cookie navigateur

• Avant correction 0.0.87, le cookie docv_oauth_session utilisait 86400 s alors que le Bearer suivait DOCV_OAUTH_ACCESS_TOKEN_TTL_SEC : une session navigateur OAuth pouvait rester valable alors que le jeton API était expiré (ou l’inverse selon le scénario).
• Désormais un seul réglage pilote les deux : DOCV_OAUTH_ACCESS_TOKEN_TTL_SEC.

Schéma office_members avec role_uid (environnements IMPL / données réelles)

Certaines bases ont des tables folders sans colonne status (schéma IMPL). Au démarrage, ensure_folders_status_column exécute ADD COLUMN IF NOT EXISTS status … DEFAULT 'open' pour aligner les GET/POST /api/v1/folders.

Certaines bases ont office_members.role_uid (NOT NULL, FK vers roles) et joined_at. Au démarrage, docv-back applique une table roles minimale si besoin, assure au moins une ligne roles par office via ensure_impl_role_rows_for_all_offices (également après création des offices démo) et ensure_one_office_scoped_role_row_if_impl sur chaque INSERT INTO offices des chemins seed/migration. insert_office_member exige une ligne roles pour office_uid (require_office_scoped_role_uid) ; en cas d’absence, l’erreur remonte (pas de repli sur un rôle global ni succès feint). DOCV_LINK_ORPHAN_USERS_TO_FIRST_OFFICE interrompt le lot si l’office cible n’a pas de rôle d’office. Un schéma roles tiers (colonnes incompatibles) peut imposer une migration manuelle.

Liste « Sociétés » vide (GET /api/v1/offices)

L’API ne renvoie que les offices pour lesquels une ligne office_members existe pour le sub du JWT (UUID utilisateur), dans le contexte de session courant.

Causes fréquentes en test / données incomplètes :

1. Offices déjà présents en base alors que seed_demo_office_if_needed ne s’exécute que lorsque COUNT(offices) = 0. Les comptes utilisés pour la recette n’ont alors pas de ligne office_members (alors que le modèle métier cible suppose des rattachements gérés par le produit ou par des scripts d’administration).
2. Le compte de test n’est pas celui couvert par le seed démo (client@example.com, etc.).

Pistes de correction (uniquement alignement technique BDD / recette) :

• Liste d’emails : DOCV_DEMO_MEMBER_EMAILS (ciblage fin ; reste un contournement).
• Test : DOCV_LINK_ORPHAN_USERS_TO_FIRST_OFFICE=1 pour créer des office_members sur le plus ancien office uniquement — avec multi-offices démo, un compte ainsi « orphelin » ne verra pas les neuf sociétés ; il faut des memberships explicites par société ou un jeu de données cohérent avec le périmètre du rôle. Ne pas activer en production sans validation.

Après modification du .env sur la machine cible : systemctl --user restart enso-docv-back (ou équivalent).

Déconnexion navigateur (docv_oauth_session)

Le jeton Bearer et le sessionStorage enso-front peuvent être effacés côté client, mais le cookie HttpOnly docv_oauth_session restait valide : une visite sur /oauth/authorize pouvait délivrer un code sans re-saisie du mot de passe.

• GET /oauth/sign-out?return_url=… : pose un Set-Cookie qui expire docv_oauth_session, puis redirige vers return_url.
• return_url doit avoir la même origine (scheme://host[:port]) qu’au moins une entrée de OAUTH_REDIRECT_URIS — en pratique /?signed_out=1 sur le même hôte (redirection vers /dashboard?signed_out=1 puis /login?signed_out=1).
• enso-front : après logout, redirection vers …/docv-api/oauth/sign-out?return_url=… (voir docvOAuthSignOutUrl).

Déploiement test et DOCV_LINK_ORPHAN_USERS_TO_FIRST_OFFICE

Le script deploy/scripts_v2/deploy.sh exporte DOCV_LINK_ORPHAN_USERS_TO_FIRST_OFFICE=1 par défaut pour l’environnement test (sauf si la clé est déjà définie dans enso-deploy.env, y compris à 0 pour désactiver). Le script distant sync-docv-deploy-opts-to-docv-env.sh recopie cette valeur dans docv/docv-back/.env avant le restart de docv-back. Sur pprod / prod, aucune valeur par défaut : la clé n’est écrite que si elle est non vide dans enso-deploy.env.

Ce défaut test reste un raccourci technique ; il ne substitute pas le rattachement métier (cabinet vs clients, plusieurs sociétés visibles pour un rôle cabinet) ni la sélection de rôle / d’espace au login (docv).

Front enso (hors docv-back)

• Le délai d’affichage avant relance SSO lorsque signed_out=1 arrive sur /login est uniquement côté client (LoginPageInner, constante SIGNED_OUT_AUTO_SSO_MS). Il n’est pas lié aux TTL ci-dessus ; son rôle est l’UX (laisser lire le message, puis enchaîner).
• Voir aussi ENSO_FRONT_BACKEND_CONTRACT.md (flux OAuth / déconnexion).

Références croisées

• docv/docv-back/.env.example
• INSTALLATION_ENVIRONNEMENT.md — tableau des variables docv-back
• IMPLEMENTATION.md §5.4 OAuth2