Sessions — l'état serveur qui recolle les requêtes

stable@nodefony/httpmis à jour 2026-07-19

HTTP n’a pas de mémoire : chaque requête arrive anonyme. Une session recolle ces requêtes à un même utilisateur au moyen d’un identifiant opaque porté par un cookie, tout l’état restant côté serveur. Nodefony fait vivre la même session en HTTP et en WebSocket, ne l’ouvre que si une route la demande, et applique par défaut les deux bornes de temps NIST/OWASP. Chaque fait de cette page est ancré sur le code.

📍 Documentation › @nodefony/http › Sessions

🧠 Le modèle mental — un ticket de vestiaire, pas un coffre#

Le cookie de session est un ticket de vestiaire : un numéro, rien d’autre. Il ne contient pas ton manteau, il permet juste de le retrouver. Le vestiaire — le store — est côté serveur.

Trois conséquences que tout le reste de la page décline :

1. Voler le ticket suffit pour repartir avec le manteau → le ticket se protège (HttpOnly, Secure, __Host-) et se périme (idle + absolute).
2. Le vestiaire peut déchirer un ticket à tout moment → la révocation est immédiate et centrale, pas une négociation avec le client.
3. Le contenu ne voyage jamais → un cookie Nodefony ne porte ni données, ni jeton signé, ni JWT.

Le point d’activation est unique et commun aux deux transports : HttpKernel.startSession() (^{http-kernel.ts:1131}). Il commence par la garde paresseuse if (!intent && !context.hasSession()) (^{http-kernel.ts:1137}) — sans intent de route ni cookie entrant, aucune session n’est ouverte.

📖 Lexique#

Qu’est-ce qu’une session — et quelles failles elle encadre#

Sans session, un utilisateur devrait re-prouver son identité à chaque requête (retaper son mot de passe pour chaque clic). La session résout ça : après connexion, le serveur garde l’état et le client ne présente plus qu’un identifiant opaque.

Cet identifiant devient donc une cible. Trois attaques classiques, trois garde-fous actifs par défaut dans Nodefony :

• Vol du cookie (hijacking). Un script injecté (XSS) ou un réseau en clair capte le cookie et rejoue la session. → HttpOnly et Secure sont à true par défaut (sessionCookieSchema, ^{config.ts:718-725}), et le nom du cookie prend le préfixe __Host- dès que le transport est TLS (Context.getSessionCookieName(), ^{Context.ts:714}).
• Fixation. L’attaquant pose lui-même un identifiant dans le navigateur de la victime, attend qu’elle se connecte, puis réutilise le même identifiant. → double défense : strictMode rejette tout identifiant inconnu du store (Session.resume(), ^{session.ts:189}), et le login régénère l’identifiant (AuthFlow — voir plus bas).
• Exploitation prolongée d’un identifiant volé. Une session maintenue artificiellement vivante resterait exploitable indéfiniment. → l’absolute timeout borne l’âge depuis la création et n’est jamais prolongé (Session.isValidSession(), ^{session.ts:366}), en plus de l’idle timeout.

❗ Important

Le cookie ne chiffre rien et n’a pas à le faire : il ne porte qu’un numéro. La sécurité repose sur la protection du cookie (les attributs ci-dessus), sur l’imprévisibilité de l’identifiant (32 octets CSPRNG) et sur le store — jamais sur un secret embarqué côté client.

La vision Nodefony#

Quatre partis pris, chacun vérifiable dans le code.

1. Le cookie ne transporte que l’identifiant. Session.getSession() lit la valeur brute du cookie, sans déchiffrement (^{session.ts:160}) ; l’identifiant vient de Session.generateId() (^{session.ts:226}). Modèle BFF : le web reste sur un cookie opaque, le JWT est réservé aux API et aux agents (voir Firewall).

2. La session est paresseuse. Elle n’existe que si une route la demande — @UseSession, ou la seule présence d’un paramètre @Session — ou si un cookie arrive déjà : c’est la garde de HttpKernel.startSession() (^{http-kernel.ts:1131}). Une route publique ne paie ni lecture de store, ni Set-Cookie.

3. Un seul modèle d’état pour le web et le temps réel. Le même startSession() sert HttpKernel.onRequestEnd() (^{http-kernel.ts:1391}) et HttpKernel.onConnect() (^{http-kernel.ts:1659}) ; l’activité HTTP ou WS prolonge la même session (Session.touchIfNeeded(), ^{session.ts:421}).

4. L’administration ne voit jamais un identifiant. Un opérateur manipule une ref, HMAC tronqué non réversible produit par computeSessionRef() (^{sessions-service.ts:100}) — comme la liste « appareils connectés » de GitHub ou Google montre une référence, jamais le jeton.

Compromis assumé : l’état serveur suppose un store partagé dès qu’on passe à plusieurs pods (redis/drizzle/mongoose) ; memory reste per-pod.

🚀 Démarrage rapide#

Dans une app générée par nodefony create app, la session est déjà configurée avec des défauts sûrs. Voici le chemin complet : configurer, écrire un contrôleur, observer.

1. Déclarer le store (facultatif — auto fait déjà le bon choix)#

// nodefony.config.ts — extrait
export default defineConfig(() => ({
  modules: [
    use("@nodefony/http", {
      session: {
        // "auto" (défaut) suit l'infra déclarée. On peut nommer le store :
        store: "drizzle",
        name: "monapp", // nom du cookie (préfixé __Host- sur TLS)
        idleTimeoutS: 1800, //  30 min d'inactivité  (NIST/OWASP)
        absoluteTimeoutS: 43200, //  12 h d'âge max, jamais prolongé
        cookie: { httpOnly: true, secure: true, hostPrefix: "auto" },
      },
    }),
    "@nodefony/framework",
    "@nodefony/drizzle", // fournit le store `drizzle` (il s'auto-enregistre)
  ],
}));

2. Écrire le contrôleur qui lit et écrit la session#

// nodefony/controllers/CartController.ts — complet, compile tel quel
import {
  Controller,
  controller,
  Get,
  Post,
  Delete,
  Session,
  Body,
  UseSession,
} from "@nodefony/framework";
import type { Session as HttpSession } from "@nodefony/http";

@controller("/panier")
class CartController extends Controller {
  // Lecture seule : la session est reprise mais JAMAIS réécrite (0 write store).
  @UseSession({ readOnly: true })
  @Get("/")
  async show(@Session() session: HttpSession) {
    return this.renderJson({ items: session.get("items") ?? [] });
  }

  // Le paramètre @Session suffit à déclarer l'intent : pas besoin de @UseSession.
  @Post("/ajouter")
  async add(@Session() session: HttpSession, @Body() body: { sku: string }) {
    const items = (session.get("items") as string[] | null) ?? [];
    items.push(body.sku);
    session.set("items", items); // marque la session « mutée » (dirty)
    session.setFlashBag("notice", `${body.sku} ajouté`); // lu UNE fois, puis effacé
    return this.renderJson({ count: items.length }); // save() écrit en fin de requête
  }

  @Delete("/")
  async clear(@Session() session: HttpSession) {
    await session.destroy(true); // détruit l'entrée store + efface le cookie
    return this.renderJson({ ok: true });
  }
}

export default CartController;

3. La même session en WebSocket#

Aucune API différente : le même décorateur, sur une route WebSocket.

// nodefony/controllers/LiveController.ts — complet, compile tel quel
import { Controller, controller, route, UseSession } from "@nodefony/framework";
import type { WebsocketContext } from "@nodefony/http";

@controller("/live")
class LiveController extends Controller {
  @route("live-panier", {
    path: "/panier",
    requirements: { methods: ["WEBSOCKET"] },
  })
  @UseSession() // session ouverte AU HANDSHAKE, réutilisée par toutes les frames
  async panier(message: string | Buffer | null) {
    const ws = this.context as WebsocketContext | undefined;
    const items = (this.session?.get("items") as string[] | null) ?? [];
    ws?.send(JSON.stringify({ items, echo: message?.toString() ?? null }));
  }
}

export default LiveController;

4. Ce qu’on observe#

# 1) Route SANS intent de session → aucun Set-Cookie (activation paresseuse)
curl -si https://localhost:5152/ -k | grep -ci 'set-cookie'
# 0

# 2) Première écriture → création de la session + cookie durci
curl -sik -c /tmp/jar -H 'Content-Type: application/json' \
  -d '{"sku":"NF-1"}' https://localhost:5152/panier/ajouter | grep -i set-cookie
# Set-Cookie: __Host-monapp=Yk9t…43-caracteres-base64url…; Path=/; HttpOnly; Secure; SameSite=Lax

# 3) Rejouer avec le cookie → l'état est retrouvé
curl -sk -b /tmp/jar https://localhost:5152/panier
# {"items":["NF-1"]}

# 4) Une simple lecture n'écrit RIEN dans le store (dirty-tracking + touch throttlé)

Le cookie obtenu porte __Host-, HttpOnly, Secure, SameSite=Lax, Path=/ et aucun Domain : c’est exactement ce qu’assert le banc d’intégration session-runtime (« Set-Cookie de session sur TLS »). Sur un transport en clair (port 5151), le préfixe __Host- est omis — le navigateur le rejetterait faute de Secure (Context.getSessionCookieName(), ^{Context.ts:714}).

⚙️ Configuration#

Source unique des défauts : le schéma Zod sessionSchema (^{config.ts:761}) et son sous-schéma sessionCookieSchema (^{config.ts:727}).

SameSite n’est pas dans ce bloc : il vient des options de cookie génériques, dont le défaut est Lax (defaultCookieOptions, ^cookie.ts:48).

⚠️ Attention

idleTimeoutS: 0 et absoluteTimeoutS: 0 désactivent les deux bornes : une session ne meurt alors plus jamais côté serveur. Le banc d’attaque session-timeout.attack.test.ts verrouille les défauts NIST (« défauts NIST actifs — idle 1800, absolute 43200 ») justement pour qu’un changement silencieux se voie.

Comment store: "auto" se résout au boot#

auto n’est pas un store : c’est une sentinelle résolue une fois, au boot, par resolveAutoStore() (^{config/infra.ts:241}), puis journalisée. Elle suit l’infra que tu as déclarée, bornée aux stores réellement enregistrés (SessionsService.initializeStorage(), ^{sessions-service.ts:231}).

Deux comportements à connaître :

• Sans aucune infra déclarée, on ne tombe pas en memory : si @nodefony/drizzle est chargé, la session persiste en SQLite local — tes données survivent au redémarrage sans une ligne de config (^infra.ts:288).
• Un store explicite inconnu ne dégrade pas en silence : en production le boot est avorté, en développement il y a repli memory annoncé en WARNING (^{sessions-service.ts:252-273}).

🗂️ Choisir son store#

Le contrat est unique — ISessionStorage (^{ISession.ts:127}) — et tous les backends le portent. Ce qui change, c’est la topologie et la façon d’expirer.

¹ multi-pod dès que la base est partagée (PostgreSQL/MySQL) ; en SQLite local, mono-nœud.

🏗️ Architecture interne — le cycle de vie#

Reprise ou création. Session.start() (^{session.ts:144}) délègue à getSession() : cookie présent → resume() (^{session.ts:177}), sinon create() (^{session.ts:204}) qui tire un identifiant CSPRNG, pose le cookie et marque la session à persister.

Validation à la reprise. Session.isValidSession() (^{session.ts:365}) applique dans l’ordre le refererCheck (si activé), l’absolute (âge depuis created, ^{session.ts:381}), puis l’idle (depuis updated, ^{session.ts:394}). Échec → invalidate() (^{session.ts:284}) détruit l’entrée et recrée une session vierge.

Écriture minimale. SessionsService.saveSession() (^{sessions-service.ts:414}) n’écrit que si la session est dirty et non readOnly ; sinon il appelle Session.touchIfNeeded() (^{session.ts:421}), qui prolonge l’idle sans réécrire le blob, et seulement au-delà d’une demi-vie d’idle (^{session.ts:445}). Une requête de lecture coûte donc au pire un UPDATE d’horodatage toutes les 15 minutes (défaut).

Anti-résurrection, sur deux niveaux. Session.destroy() remet mutated = false (^{session.ts:307}) pour que la sauvegarde de fin de requête ne réécrive pas ce qu’on vient de supprimer. Surtout, tout store est décoré par RevocationGuardStorage (^{sessions-service.ts:279}) : destroy() pose une pierre tombale de 5 minutes (^{RevocationGuardStorage.ts:144}) qui refuse ensuite tout write (^{RevocationGuardStorage.ts:128}) et tout touch (^{RevocationGuardStorage.ts:151}) du même identifiant — ce qui couvre la requête « en vol » d’un autre client.

Purge hors requête. Un GcScheduler est armé au onReady, désarmé au onTerminate (^{sessions-service.ts:284-313}). La passe métier nue, SessionsService.runGc() (^{sessions-service.ts:470}), est publique exprès : un CronJob Kubernetes peut l’appeler à la place du timer (gcIntervalS: 0).

Entités de persistance#

Drizzle (SQL). La table est décrite une seule fois en spec logique (SESSION_TABLE_SPEC, ^{sessionEntity.ts:25}) et déclinée par dialecte par buildFrameworkTable() (^{colKit.ts:543}) — mêmes noms de colonnes partout, donc un store dialect-agnostique.

En MySQL/MariaDB, une colonne texte indexée devient varchar (un TEXT InnoDB n’est pas indexable sans préfixe) et le type JSON passe par un type compatible qui tolère MariaDB, laquelle stocke le JSON en LONGTEXT (^{colKit.ts:466-469}).

Mongoose (MongoDB). Schéma équivalent (@nodefony/mongoose/nodefony/entity/sessionEntity.ts:16) : session_id (String, index unique), Attributes/flashBag/metaBag (Object, défaut {}), user (String, défaut null), createdAt/updatedAt (Number, ms).

Le connecteur diffère volontairement entre les deux adaptateurs — "default" pour Drizzle (^{sessionEntity.ts:11}), "nodefony" pour Mongoose (@nodefony/mongoose/nodefony/entity/sessionEntity.ts:5) — parce que le registre d’entités est partagé par processus : deux noms distincts évitent la collision quand les deux ORM cohabitent.

🔌 HTTP et WebSocket — la même session#

C’est le différenciateur du framework appliqué à l’état de session : un seul modèle, deux transports.

<!-- prettier-ignore -->

La conséquence pratique la plus utile : côté WebSocket, la bulle AsyncLocalStorage ouverte au handshake par RequestContext.run() enveloppe aussi les messages (^{http-kernel.ts:431}). L’identité résolue une fois est donc disponible à chaque frame sans relire la base — c’est ce dont profite FirewallRealtimeAuthenticator.supports() (^{FirewallRealtimeAuthenticator.ts:80}), câblé automatiquement par le firewall sur les zones temps réel protégées (^{firewall.ts:300}).

⚠️ Attention

Rien à écrire dans initialize() : il n’existe pas de Controller.startSession(). La session WS se déclare comme en HTTP, par @UseSession() sur la route concernée. La poser globalement ferait persister une session pour chaque connexion, y compris les routes qui n’en ont aucun besoin — sous charge (broadcast), c’est une tempête d’écritures.

🔐 Sécurité#

Régénération d’identifiant à la connexion (anti-fixation)#

C’est la défense la plus importante et elle est active. AuthFlow.#openSession() (^{authFlow.ts:378}) : reprise ou ouverture de la session, mémorisation de l’ancien identifiant, puis appel inconditionnel de Session.regenerateId() (^{authFlow.ts:388}), et enfin destruction de l’ancienne entrée du store (^{authFlow.ts:390}). Un cookie pré-posé par un attaquant ne survit donc pas au login. Le nouvel identifiant est un CSPRNG frais, l’état applicatif est conservé (Session.regenerateId(), ^{session.ts:236}).

Au passage, la provenance est capturée dans le metaBag : ip (^{authFlow.ts:405}) et ua (^{authFlow.ts:407}), en mode « au mieux » — ce sont ces deux champs que la console d’administration affiche.

Révocation — immédiate et par construction#

Deux finesses valent d’être connues.

destroyByUser() ne fait pas un seul passage : il repasse jusqu’à ce qu’un passage complet ne détruise plus rien (^{sessions-service.ts:737}), car supprimer en parcourant décale les rangs sous un curseur offset. Une révocation « partout » qui en laisserait une n’est pas une imprécision, c’est une faille — on rend donc la main avec la preuve, pas l’espoir.

destroyOwnByRef() ferme l’IDOR par construction : parcours restreint aux sessions du demandeur, et appartenance re-vérifiée avant même de comparer la ref (^{sessions-service.ts:836}). Une ref d’autrui est structurellement introuvable.

Redaction — l’identifiant ne sort jamais du process#

Trois barrières superposées :

1. Le contrat impose que listPage() rende Attributes et flashBag vides (^{ISession.ts:203}) — les stores SQL/NoSQL ne les sélectionnent même pas.
2. La projection vers l’extérieur passe par toSessionSummary() (^{sessions-service.ts:112}), bâtie en liste blanche : ref, user, authenticated, ip, ua, dates. Jamais un delete après coup.
3. La ref elle-même est un HMAC tronqué non réversible (computeSessionRef(), ^{sessions-service.ts:100}) ; la clé est dérivée du certificat au boot et n’est jamais sérialisée (SessionsService.sessionRef(), ^{sessions-service.ts:511}).

Récapitulatif des défenses actives par défaut#

🧰 API publique#

Les signatures vivent dans .ai/symbols.json (jamais recopiées ici). Voici les usages réels.

Depuis un contrôleur — this.session est un getter sur le contexte (^{Controller.ts:229}) ; un paramètre @Session() suffit à déclarer l’intent.

Intent de route — UseSession(options) (^{routerDecorators.ts:761}) s’applique à une classe ou à une méthode ; la méthode l’emporte, par fusion et non par remplacement (resolveSessionIntent(), ^{routerDecorators.ts:819}). Une seule option (SessionIntent, ^{ISession.ts:17}) :

• readOnly: true — la session est reprise et lue mais jamais persistée ; une mutation tentée est journalisée en WARNING sans écriture (Session.save(), ^{session.ts:255-264}). C’est le seul champ propagé par le kernel (^{http-kernel.ts:1482}).

En décorateur de classe, @UseSession se place sous @controller (^{routerDecorators.ts:761}).

🧩 Extension — brancher son propre store#

Le registre est une inversion de contrôle complète : @nodefony/http ne connaît aucun backend. Chaque module fournisseur se déclare lui-même au chargement, par SessionsService.registerStorage(nom, ctor) (^{sessions-service.ts:174}) — exactement ce que fait la dernière ligne de chaque adaptateur (@nodefony/redis/nodefony/src/SessionStorage.ts:323).

Pour ajouter un backend :

1. Implémenter ISessionStorage (^{ISession.ts:127}). Le noyau obligatoire est court : read/start/write/open/close/destroy/gc.
2. Ajouter les capacités optionnelles utiles : touch (idle glissant sans réécriture, ^{ISession.ts:158}), listPage + countSessions (administration paginée, ^{ISession.ts:203}), listAll (dump).
3. Appeler SessionsService.registerStorage("mon-store", MonStore) au chargement du module.
4. Exécuter les bancs de contrat partagés (sessionStoreContract.ts, sessionPaginationContract.ts) contre l’implémentation — c’est ce qui garantit la parité.

Trois règles de conception se dégagent du contrat, et méritent d’être respectées :

• Une capacité absente s’annonce. Ne pas implémenter listPage fait répondre 501 à l’endpoint d’administration (refus honnête) plutôt qu’une liste vide trompeuse (^{ISession.ts:221}).
• On n’invente pas ce qu’on ignore. countSessions() renvoie -1 quand compter coûterait trop cher — Redis le fait (^{ISession.ts:236}).
• Une page ne matérialise jamais plus qu’une page. C’est ce qui rend le coût d’une requête d’administration indépendant du nombre de sessions.

📜 Normes appliquées#

⚡ Performance & mémoire#

Le coût d’une session est payé seulement quand elle sert :

• Zéro par défaut — sans intent ni cookie, startSession() sort immédiatement (^{http-kernel.ts:1131}) : ni objet Session, ni lecture de store.
• Objet léger — trois sacs {} à plat, pas de container DI par session (^{session.ts:100-104}).
• Zéro écriture en lecture — le dirty-tracking court-circuite save() (^{session.ts:266}) ; le touch est throttlé à une écriture par demi-vie d’idle (^{session.ts:445}).
• GC hors requête — timer déterministe avec jitter par process, à la place du tirage probabiliste hérité de PHP (^{sessions-service.ts:306-312}).
• Révocation quasi gratuite — la Map de pierres tombales est paresseuse : sans révocation, write ne paie qu’une comparaison === null, sans même un Date.now() (^{RevocationGuardStorage.ts:146-151}).
• Administration bornée — jamais plus de SCAN_PAGE = 200 enregistrements en mémoire (^{sessions-service.ts:75}), garde-fou à 5 000 pages (^{sessions-service.ts:83}), parcours interrompu journalisé.

Le banc session-load.test.ts verrouille ces propriétés sur serveur réel (200 sessions HTTP, 100 ouvertures/fermetures WebSocket) en mesurant le drainage des scopes DI — immunisé au bruit du GC — plus un plafond de croissance du tas.

ℹ️ Note

Les trois sacs sont des objets littéraux et non Object.create(null). C’est délibéré : drizzle-orm déréférence le prototype via is(), et un objet sans prototype ferait échouer l’écriture (^{session.ts:95-98}).

📡 Observabilité — Studio#

Data plane — createHttpAdminApi() (^{HttpAdminApi.ts:141}) expose la surface d’administration sous /nodefony/http/api/ :

Les deux routes mine ne demandent pas de rôle, mais ne sont pas anonymes : la zone firewall des API d’administration n’accepte que l’authenticator session (pas d’anonymous), et le périmètre est pris sur l’identité ALS, jamais sur un paramètre client (^{HttpAdminApi.ts:451-457}).

Chaque ligne rendue porte current — vrai pour LA session qui a émis la requête, et pour elle seule. C’est le « cet appareil » des consoles d’appareils connectés, et le client ne peut pas le déduire : la référence est un HMAC du cookie, que le navigateur ne sait pas calculer. Sans lui, aucune ligne n’est désignable — ni celle qu’on ferme, ni celle qu’il ne faut pas fermer. Comparer les utilisateurs ne le remplace pas : dans sessions/mine, toutes les lignes portent le même. La dérivation est faite une fois par page (sessions-service.ts currentSessionRef) ; false quand la requête ne porte pas de session (appel interne, invocation CLI).

Codes de réponse à connaître : 501 si le store courant ne sait pas s’énumérer (supportsEnumeration() faux — ^{HttpAdminApi.ts:352}), 503 si le service de session est absent, 404 pour une ref inconnue ou une révocation sans effet, 401 sur mine sans identité.

Écrans — la page Sessions (/nodefony/sessions) de Studio liste les sessions vivantes par ref et permet la révocation unitaire ou en masse (@nodefony/studio/frontend/src/routes/sessions/). L’écran Stores affiche le backend réellement résolu, sa provenance et son emplacement physique : ces informations sont publiées au boot par registerStoreResolution() (^{sessions-service.ts:290}), avec le chemin du fichier SQLite quand c’est pertinent (SessionStorage.location, @nodefony/drizzle/nodefony/src/SessionStorage.ts:43).

⚠️ Pièges (symptôme → cause → correction)#

🧪 Tests & couverture#

Les six familles sont présentes — les chiffres exacts vivent dans la carte de l’aperçu, régénérée depuis vitest, jamais figés ici.

<!-- prettier-ignore -->

🛑 Prudence

Les suites E2E se skippent sans leurs variables d’infra, et un skip compte comme vert. Avant de conclure « tout passe » sur les dialectes PostgreSQL/MySQL, vérifier que NF_PG_URL/NF_MYSQL_URL étaient bien posées (source unique : vitest.gates.ts à la racine).

Skills utiles : nodefony-load-test (rejouer ou étendre la charge), nodefony-check-memory-health (gate mémoire), nodefony-security-review (fixation, timeouts, révocation).

Couverture : npm run coverage dans @nodefony/http (vitest, reporter json-summary). Le pourcentage vit dans le rapport, jamais figé dans ce Markdown.

🔗 Pour aller plus loin#

• ⬆️ Retour au hub : @nodefony/http — vue du module · Toute la documentation
• 🧭 Pages sœurs : qui authentifie la session → Firewall · Authenticators · rejeu de mutation → Idempotence
• 🗄️ Les stores en détail : @nodefony/drizzle · @nodefony/redis · @nodefony/mongoose
• 🧰 Guide pratique : choisir et configurer son stockage de session
• 🏗️ Où la session s’insère : pipeline de requête