@nodefony/http 10.0.0-alpha.1

package/dist/nodefony/src/session/session.js

@@ -0,0 +1,390 @@
+import Cookie from "../cookies/cookie.js";
+import { extend } from "nodefony";
+import { randomBytes } from "node:crypto";
+//#region nodefony/src/session/session.ts
+const defaultSessionOptions = {
+	name: "nodefony",
+	strictMode: true,
+	refererCheck: false
+};
+/** Taille de l'identifiant opaque (octets CSPRNG → base64url, 43 chars). */
+const SESSION_ID_BYTES = 32;
+/**
+* Session serveur Nodefony — état persistant lié à une identité, indexé par un
+* identifiant **opaque** (porté par le cookie) dans un {@link ISessionStorage}
+* pluggable (File / Redis / SQL). Modèle BFF : le cookie ne transporte qu'un
+* secret aléatoire, jamais de données ni de JWT.
+*
+* Objet **léger** : trois sacs `{}` (attributs / métas / flash)
+* au lieu d'un `Container` DI par session.
+*
+* Dirty-tracking : toute mutation (`set` / `setFlashBag` / `setMetaBag` /
+* `getFlashBag` qui consomme / …) lève {@link dirty} ; {@link save} n'écrit dans
+* le storage **que** si `dirty`. Une requête qui ne touche pas la session ne
+* déclenche aucune écriture (supprime la contention `write`/requête).
+*/
+var Session = class {
+	id = "";
+	name = "";
+	status = "none";
+	storage;
+	manager;
+	saved = false;
+	migrated = false;
+	/**
+	* Lecture seule (intent `@UseSession({ readOnly })`) : la session est reprise et
+	* lue mais **jamais persistée** — {@link save} devient un no-op. Différenciateur
+	* perf : une route qui ne fait que LIRE la session (afficher le user…) ne paie
+	* aucune écriture storage.
+	*/
+	readOnly = false;
+	context;
+	created;
+	updated;
+	options;
+	cookieSession = null;
+	lifetime;
+	user;
+	strategy;
+	/** Sac d'attributs applicatifs (clé/valeur) — exposé via {@link getAttributes}. */
+	attributesBag = {};
+	/** Sac de métadonnées techniques (host, ip, ua…) — exposé via {@link getMetas}. */
+	metaBagStore = {};
+	/** Sac de messages flash (consommés à la lecture). Public : lu par les storages. */
+	flashBag = {};
+	/** Drapeau dirty-tracking — lu via le getter {@link dirty}. */
+	mutated = false;
+	constructor(name, options, manager) {
+		this.options = extend({}, defaultSessionOptions, options);
+		this.manager = manager;
+		this.storage = this.manager.storage;
+		if (!this.storage) this.status = "disabled";
+		this.setName(name);
+		this.strategy = this.manager.sessionStrategy;
+	}
+	/** Vrai si la session a été mutée sans être encore persistée (dirty-tracking). */
+	get dirty() {
+		return this.mutated;
+	}
+	log(pci, severity) {
+		this.manager.log(pci, severity, `SESSION ${this.name}`);
+	}
+	/**
+	* Démarre (ou reprend) la session. Cookie présent → reprise depuis le storage ;
+	* sinon → nouvelle session.
+	*
+	* @param context - contexte HTTP/HTTP2/WS courant.
+	*/
+	async start(context) {
+		this.context = context;
+		const ret = this.checkStatus();
+		if (ret === false) return this;
+		if (ret === "restart") return this.start(context);
+		return this.getSession();
+	}
+	/**
+	* Lit l'identifiant opaque du cookie puis reprend la session, ou en crée une
+	* neuve si aucun cookie. Cookie-only : aucun identifiant lu depuis l'URL.
+	*/
+	async getSession() {
+		if (this.context?.cookieSession) {
+			this.id = this.context.cookieSession.value;
+			this.cookieSession = this.context.cookieSession;
+		}
+		if (this.id) return this.resume();
+		this.clear();
+		return this.create(this.lifetime ?? 0);
+	}
+	/**
+	* Reprend la session `id` depuis le storage. Invalide (→ session neuve) si
+	* introuvable en strict mode, ou expirée/illégitime.
+	*/
+	async resume() {
+		const data = await this.storage.start(this.id);
+		if (data && Object.keys(data).length) {
+			this.deSerialize(data);
+			if (!this.isValidSession(data, this.context)) {
+				this.log(`INVALID SESSION ==> ${this.name} : ${this.id}`, "WARNING");
+				await this.invalidate();
+				return this;
+			}
+			this.status = "active";
+			return this;
+		}
+		if (this.options.strictMode) {
+			this.log(`SESSION strict_mode unknown id ==> ${this.name}`, "DEBUG");
+			await this.invalidate();
+			return this;
+		}
+		this.status = "active";
+		return this;
+	}
+	/**
+	* Crée une session neuve : identifiant opaque CSPRNG, cookie, métadonnées.
+	* Marquée `dirty` (sauf `saveUninitialized:false`) → persistée + `Set-Cookie`
+	* au prochain {@link save}.
+	*/
+	create(lifetime, id, settingsCookie = {}) {
+		this.id = id || this.generateId();
+		const settings = extend({}, this.options.cookie, settingsCookie);
+		this.log(`NEW SESSION CREATE : ${this.id}`, "DEBUG");
+		this.cookieSession = this.setCookieSession(lifetime, settings);
+		this.setMetasSession(settings);
+		this.status = "active";
+		this.mutated = true;
+		return this;
+	}
+	/** Génère un identifiant de session opaque (32 octets CSPRNG → base64url). */
+	generateId() {
+		return randomBytes(SESSION_ID_BYTES).toString("base64url");
+	}
+	/**
+	* Régénère l'identifiant (nouveau secret opaque) en conservant l'état courant.
+	* Anti session-fixation (OWASP) — appelée à chaque ouverture de session
+	* authentifiée par `AuthFlow.#openSession()` (`@nodefony/security`), qui
+	* détruit ensuite l'ancienne entrée de storage. Repositionne le cookie et
+	* marque la session `dirty`.
+	*/
+	regenerateId() {
+		this.id = this.generateId();
+		this.mutated = true;
+		if (this.context?.response) this.cookieSession = this.setCookieSession(this.lifetime ?? 0, this.options.cookie ?? {});
+	}
+	/**
+	* Persiste la session **si elle est dirty** (sinon no-op). Réécrit le blob
+	* sérialisé dans le storage, repositionne created/updated, lève l'événement
+	* `onSaveSession`.
+	*
+	* @param user - principal authentifié (string) lié au blob ; défaut courant.
+	*/
+	async save(user) {
+		if (this.readOnly) {
+			if (this.mutated) this.log(`READONLY SESSION mutated — write skipped : ${this.name}`, "WARNING");
+			return this;
+		}
+		if (!this.mutated) return this;
+		const stored = await this.storage.write(this.id, this.serialize(user));
+		this.created = stored.createdAt ?? this.created;
+		this.updated = stored.updatedAt ?? this.updated;
+		this.mutated = false;
+		this.saved = true;
+		if (this.context) await this.context.fireAsync("onSaveSession", this);
+		return this;
+	}
+	/**
+	* Détruit la session courante (storage) et en recrée une neuve (nouvel
+	* identifiant + cookie). État applicatif réinitialisé.
+	*/
+	async invalidate(lifetime = this.lifetime ?? 0, id, settingsCookie = {}) {
+		this.log(`INVALIDATE SESSION ==> ${this.name} : ${this.id}`, "DEBUG");
+		const oldId = this.id;
+		this.clear();
+		await this.storage.destroy(oldId);
+		return this.create(lifetime, id, settingsCookie);
+	}
+	/**
+	* Détruit la session : vide les sacs, supprime l'entrée storage, et (option)
+	* efface le cookie.
+	*/
+	async destroy(cookieDelete = false) {
+		this.clear();
+		await this.storage.destroy(this.id);
+		this.mutated = false;
+		this.status = "disabled";
+		if (cookieDelete) this.deleteCookieSession();
+		return true;
+	}
+	setCookieSession(leftTime, options = {}) {
+		if (this.context && this.context.response) {
+			const settings = extend({}, this.options.cookie, options);
+			if (leftTime) settings.maxAge = leftTime;
+			const cookie = new Cookie(this.context.getSessionCookieName(), this.id, settings);
+			this.context.response.addCookie(cookie);
+			this.cookieSession = cookie;
+			this.context.cookieSession = cookie;
+			return cookie;
+		}
+		return null;
+	}
+	deleteCookieSession() {
+		if (this.context && this.context.response) {
+			let cookie = this.cookieSession;
+			if (cookie) cookie.expires = /* @__PURE__ */ new Date(0);
+			else cookie = new Cookie(this.context.getSessionCookieName(), "", { expires: /* @__PURE__ */ new Date(0) });
+			this.context.response.setCookie(cookie);
+			this.cookieSession = null;
+			this.context.cookieSession = null;
+			return cookie;
+		}
+		return this.cookieSession;
+	}
+	isValidSession(_data, context) {
+		if (this.options.refererCheck) try {
+			return this.checkSecureReferer(context);
+		} catch {
+			this.log(`SESSION REFERER MISMATCH ==> ${this.name} : ${this.id}`, "WARNING");
+			return false;
+		}
+		const now = Date.now();
+		if (this.options.absoluteTimeoutS && this.created) {
+			if (now - new Date(this.created).getTime() > this.options.absoluteTimeoutS * 1e3) {
+				this.log(`SESSION EXPIRED (absolute) ==> ${this.name} : ${this.id}`, "WARNING");
+				return false;
+			}
+		}
+		const idleS = this.options.idleTimeoutS;
+		if (idleS && idleS > 0 && this.updated) {
+			const lastUsed = new Date(this.updated).getTime();
+			if (lastUsed && lastUsed + idleS * 1e3 < now) {
+				this.log(`SESSION EXPIRED (idle) ==> ${this.name} : ${this.id}`, "WARNING");
+				return false;
+			}
+		}
+		return true;
+	}
+	/**
+	* Prolonge l'idle timeout de la session active sur l'activité courante, **de
+	* façon throttlée** (1 écriture par tranche d'idle, jamais par requête) et
+	* **sans réécrire le blob** (write léger `touch` du storage) — l'activité
+	* HTTP/WS réelle, **y compris en lecture seule**, empêche l'expiration d'une
+	* session utilisée (NIST/OWASP : idle « since the last request »). N'affecte
+	* **jamais** l'absolute timeout (borné à la création).
+	*
+	* No-op si : pas active, pas d'entrée storage à prolonger (`!updated`), idle
+	* désactivé, store sans `touch`, ou dernière activité trop récente (throttle =
+	* mi-vie de l'idle). Met à jour `updated` localement → le throttle compte
+	* depuis ce touch.
+	*/
+	async touchIfNeeded() {
+		if (this.status !== "active") return;
+		const idleS = this.options.idleTimeoutS;
+		if (!idleS || idleS <= 0) return;
+		const storage = this.storage;
+		if (typeof storage.touch !== "function") return;
+		if (!this.updated) return;
+		const now = Date.now();
+		const lastUsed = new Date(this.updated).getTime();
+		if (lastUsed && now - lastUsed < idleS * 1e3 / 2) return;
+		await storage.touch(this.id, idleS);
+		this.updated = new Date(now);
+	}
+	checkSecureReferer(context) {
+		const host = context.getHost();
+		const meta = this.getMetaBag("host");
+		if (host === meta) return true;
+		this.log(`SESSION REFERER NOT SAME, HOST: ${host} META: ${String(meta)}`, "WARNING");
+		throw new Error("session referer mismatch");
+	}
+	setMetasSession(cookieSetting = {}) {
+		this.setMetaBag("lifetime", cookieSetting.maxAge ?? this.options.cookie?.maxAge);
+		const ctx = this.context;
+		this.setMetaBag("request", ctx?.type);
+		try {
+			this.setMetaBag("remoteAddress", ctx?.getRemoteAddress());
+			this.setMetaBag("host", ctx?.getHost());
+			this.setMetaBag("user_agent", ctx?.getUserAgent() || "Not Defined");
+		} catch (e) {
+			this.log(e, "DEBUG");
+		}
+	}
+	get(key) {
+		const v = this.attributesBag[key];
+		return v === void 0 ? null : v;
+	}
+	set(key, value) {
+		this.attributesBag[key] = value;
+		this.mutated = true;
+		return value;
+	}
+	getAttributes() {
+		return this.attributesBag;
+	}
+	getMetaBag(key) {
+		const v = this.metaBagStore[key];
+		return v === void 0 ? null : v;
+	}
+	setMetaBag(key, value) {
+		this.metaBagStore[key] = value;
+		this.mutated = true;
+	}
+	getMetas() {
+		return this.metaBagStore;
+	}
+	getFlashBag(key) {
+		const v = this.flashBag[key];
+		if (v !== void 0) {
+			delete this.flashBag[key];
+			this.mutated = true;
+			return v;
+		}
+		return null;
+	}
+	setFlashBag(key, value) {
+		if (!key) throw new Error(`FlashBag key must be define : ${key}`);
+		this.flashBag[key] = value;
+		this.mutated = true;
+		return value;
+	}
+	flashBags() {
+		return this.flashBag;
+	}
+	clearFlashBag(key) {
+		if (!key) throw new Error(`clearFlashBag key must be define : ${key}`);
+		if (this.flashBag[key] !== void 0) {
+			delete this.flashBag[key];
+			this.mutated = true;
+		}
+	}
+	clearFlashBags() {
+		this.flashBag = {};
+		this.mutated = true;
+	}
+	serialize(user) {
+		return {
+			Attributes: this.attributesBag,
+			metaBag: this.metaBagStore,
+			flashBag: this.flashBag,
+			user: user ?? this.user ?? ""
+		};
+	}
+	deSerialize(data) {
+		if (data.Attributes) for (const k in data.Attributes) this.attributesBag[k] = data.Attributes[k];
+		if (data.metaBag) for (const k in data.metaBag) this.metaBagStore[k] = data.metaBag[k];
+		if (data.flashBag) for (const k in data.flashBag) this.flashBag[k] = data.flashBag[k];
+		this.created = data.createdAt ?? this.created;
+		this.updated = data.updatedAt ?? this.updated;
+		if (data.user) this.user = data.user;
+	}
+	/** Réinitialise les trois sacs (attributs, métas, flash) — état vide. */
+	clear() {
+		this.attributesBag = {};
+		this.metaBagStore = {};
+		this.flashBag = {};
+	}
+	getName() {
+		return this.name;
+	}
+	setName(name) {
+		this.name = name || this.options.name;
+	}
+	checkStatus() {
+		switch (this.status) {
+			case "active":
+				this.log(`SESSION ALREADY STARTED ==> ${this.name} : ${this.id}`, "WARNING");
+				return false;
+			case "disabled": {
+				const storage = this.manager.initializeStorage();
+				if (storage) {
+					this.storage = storage;
+					this.status = "none";
+					return "restart";
+				}
+				this.log("SESSION STORAGE HANDLER NOT FOUND", "ERROR");
+				throw new Error("SESSION STORAGE HANDLER NOT FOUND");
+			}
+			default: return true;
+		}
+	}
+};
+//#endregion
+export { Session as default };

package/dist/nodefony/src/session/storage/MemorySessionStorage.js

@@ -0,0 +1,185 @@
+import { SESSION_DEFAULT_ORDER, SESSION_SORTABLE_FIELDS } from "./sessionSort.js";
+import { assertPageQuery, compareByOrder, pickOrder } from "nodefony";
+//#region nodefony/src/session/storage/MemorySessionStorage.ts
+/**
+* Store de sessions **en mémoire** (Map process) — implémentation de référence
+* d'{@link ISessionStorage}, pendant `session` des `Memory*Store` de sécurité.
+*
+* **Volatil** : les sessions vivent dans la RAM du process et disparaissent au
+* redémarrage ET ne sont PAS partagées entre pods/workers. Cible : **tests de
+* charge** (mesurer le framework sans le goulot disque/SQL), CI, environnements
+* éphémères. Pour la persistance mono-nœud → `drizzle` (sqlite) ; multi-nœud →
+* `redis`/`drizzle`/`mongoose`.
+*
+* Bornes NIST/OWASP portées par des horodatages internes : `updatedAt` = dernière
+* activité (idle, rafraîchi par {@link touch}), `createdAt` = création (absolute,
+* JAMAIS prolongé). Même sémantique que les stores SQL — l'idle glissant et
+* l'absolute s'appliquent identiquement.
+*/
+var MemorySessionStorage = class {
+	manager;
+	idleTimeoutS;
+	absoluteTimeoutS;
+	/** id → session sérialisée (source de vérité, horodatages inclus). */
+	#sessions = /* @__PURE__ */ new Map();
+	/**
+	* Trie sur tout le vocabulaire public : les données sont déjà en RAM, aucun
+	* champ n'est plus coûteux qu'un autre. Aucune traduction — les clés internes
+	* portent déjà ces noms (`id` étant la clé de la Map).
+	*/
+	sortableFields = SESSION_SORTABLE_FIELDS;
+	constructor(manager) {
+		this.manager = manager;
+		this.idleTimeoutS = manager.options.idleTimeoutS;
+		this.absoluteTimeoutS = manager.options.absoluteTimeoutS;
+	}
+	/** Lecture par id — copie superficielle (le consommateur ne mute pas le store). */
+	read(id) {
+		const stored = this.#sessions.get(id);
+		return Promise.resolve(stored ? { ...stored } : {});
+	}
+	start(id) {
+		return this.read(id);
+	}
+	/**
+	* Écrit (upsert) le blob. `createdAt` est FIXÉ à la création et préservé aux
+	* updates (borne absolute) ; `updatedAt` est posé à chaque écriture (borne idle).
+	*/
+	write(id, data) {
+		const now = /* @__PURE__ */ new Date();
+		const existing = this.#sessions.get(id);
+		const record = {
+			...data,
+			createdAt: existing?.createdAt ?? data.createdAt ?? now,
+			updatedAt: now
+		};
+		this.#sessions.set(id, record);
+		return Promise.resolve(data);
+	}
+	/** Compte des sessions présentes (+ passe GC comme les autres stores à l'open). */
+	async open() {
+		await this.gc();
+		this.manager.log(`SESSIONS STORAGE ==> ${this.manager.options.store.toUpperCase()} COUNT SESSIONS : ${this.#sessions.size}`);
+		return this.#sessions.size;
+	}
+	close() {
+		return true;
+	}
+	destroy(id) {
+		this.#sessions.delete(id);
+		return Promise.resolve(true);
+	}
+	/**
+	* Prolonge l'idle (timeout glissant) : rafraîchit `updatedAt` SANS toucher
+	* `createdAt` (borne absolute intacte). Session absente (purgée) → no-op.
+	*/
+	touch(id) {
+		const stored = this.#sessions.get(id);
+		if (stored) stored.updatedAt = /* @__PURE__ */ new Date();
+		return Promise.resolve();
+	}
+	/**
+	* Purge idle (inactivité depuis `updatedAt`) ET absolute (âge depuis `createdAt`,
+	* jamais prolongé). Une borne à 0 = désactivée. Déterministe (synchrone).
+	*/
+	gc(idleSeconds, absoluteSeconds) {
+		const idleMs = (idleSeconds ?? this.idleTimeoutS) * 1e3;
+		const absoluteMs = (absoluteSeconds ?? this.absoluteTimeoutS) * 1e3;
+		const now = Date.now();
+		let deleted = 0;
+		for (const [id, s] of this.#sessions) {
+			const updated = s.updatedAt ? s.updatedAt.getTime() : now;
+			const created = s.createdAt ? s.createdAt.getTime() : now;
+			const idleExpired = idleMs > 0 && updated + idleMs < now;
+			const absoluteExpired = absoluteMs > 0 && created + absoluteMs < now;
+			if (idleExpired || absoluteExpired) {
+				this.#sessions.delete(id);
+				deleted++;
+			}
+		}
+		if (deleted > 0) this.manager.log(`MEMORY SESSIONS STORAGE GARBAGE COLLECTOR ==> ${deleted} DELETED`);
+		return Promise.resolve();
+	}
+	/** Énumération admin — filtre `user` appliqué en mémoire. */
+	listAll(filter) {
+		const records = [];
+		for (const [id, data] of this.#sessions) {
+			if (filter?.user !== void 0 && data.user !== filter.user) continue;
+			records.push({
+				id,
+				data: { ...data }
+			});
+		}
+		return Promise.resolve(records);
+	}
+	/**
+	* `true` si l'entrée passe les filtres — prédicat partagé par {@link listPage}
+	* et {@link countSessions} (une seule définition du périmètre : compter et
+	* lister ne peuvent pas diverger).
+	*/
+	#matches(data, query) {
+		if (!query) return true;
+		if (query.user !== void 0 && data.user !== query.user) return false;
+		if (query.authenticated !== void 0) {
+			if (!!data.user !== query.authenticated) return false;
+		}
+		return true;
+	}
+	/**
+	* Pagination **offset** avec `total` exact, ordre `updatedAt` DESC (id ASC en
+	* départage). Les données étant déjà en RAM par conception, le coût par requête
+	* est celui du tri des **références** filtrées — aucune copie de blob n'est
+	* faite hors de la page rendue.
+	*
+	* **Redaction par construction** (garantie du contrat, pas une optimisation) :
+	* `Attributes`/`flashBag` sortent VIDES, comme chez les stores SQL/NoSQL qui ne
+	* les SELECTent pas. Ici c'est gratuit — on ne recopie simplement pas ces deux
+	* bags — et ça aligne le store mémoire sur la même garantie : un record
+	* d'énumération admin ne porte jamais de donnée métier.
+	*/
+	listPage(query) {
+		assertPageQuery(query, "offset");
+		const limit = Math.max(0, query.limit);
+		const offset = Math.max(0, query.offset ?? 0);
+		const matched = [];
+		for (const entry of this.#sessions) if (this.#matches(entry[1], query)) matched.push(entry);
+		const order = pickOrder(query.order, this.sortableFields, SESSION_DEFAULT_ORDER);
+		matched.sort(compareByOrder(order, ([id, data], field) => field === "id" ? id : data[field]));
+		const items = matched.slice(offset, offset + limit).map(([id, data]) => ({
+			id,
+			data: {
+				...data,
+				Attributes: {},
+				flashBag: {}
+			}
+		}));
+		return Promise.resolve({
+			items,
+			total: query.withTotal === false ? void 0 : matched.length,
+			limit: query.limit,
+			offset,
+			hasNext: offset + items.length < matched.length
+		});
+	}
+	/** `COUNT` filtré — parcourt sans allouer (aucun record matérialisé). */
+	countSessions(query) {
+		let count = 0;
+		for (const data of this.#sessions.values()) if (this.#matches(data, query)) count++;
+		return Promise.resolve(count);
+	}
+	/**
+	* `COUNT(DISTINCT user)` en mémoire. Le `Set` est alloué à l'appel et relâché
+	* aussitôt : c'est un chemin d'administration, appelé à l'ouverture d'un
+	* écran, jamais dans le pipeline de requête.
+	*/
+	countDistinctUsers(query) {
+		const users = /* @__PURE__ */ new Set();
+		for (const data of this.#sessions.values()) {
+			if (!this.#matches(data, query)) continue;
+			if (typeof data.user === "string" && data.user) users.add(data.user);
+		}
+		return Promise.resolve(users.size);
+	}
+};
+//#endregion
+export { MemorySessionStorage as default };