@nodefony/security 10.0.0-alpha.1

package/dist/nodefony/src/authenticator/peekIssuer.js

@@ -0,0 +1,56 @@
+//#region nodefony/src/authenticator/peekIssuer.ts
+/**
+* Lecture NON VÉRIFIÉE de l'émetteur d'un JWS compact.
+*
+* Sert à **choisir qui doit examiner un jeton**, jamais à décider de son sort.
+* Deux authenticators reconnaissent la même forme de credential — un
+* `Authorization: Bearer <jws>` — l'un pour les jetons que Nodefony a émis,
+* l'autre pour ceux d'un serveur d'autorisation tiers. Sans discriminant, le
+* premier listé dans la zone capture les deux et refuse la moitié des jetons :
+* l'ordre de la configuration deviendrait une décision de sécurité, et son
+* erreur ne se verrait qu'en production.
+*
+* ## Ce qui rend cette lecture sûre
+*
+* Rien de ce qui est lu ici ne devient une clé, une URL ou un algorithme. La
+* valeur ne sert qu'à sélectionner une entrée dans une liste **fermée**, écrite
+* en configuration ; le jeton est ensuite vérifié entièrement par
+* l'authenticator retenu, `iss` compris. Un attaquant qui ment sur `iss` ne
+* gagne donc que le droit d'être refusé par un autre maillon.
+*
+* La taille est bornée AVANT tout travail : `JSON.parse` sur une entrée non
+* fiable est le genre d'appel qu'on ne laisse pas grandir sans limite.
+*/
+/**
+* Plus grand jeton qu'on accepte de regarder (octets).
+*
+* Un jeton d'accès réaliste tient largement en deçà, y compris avec des rôles
+* et des groupes ; au-delà, refuser de décoder coûte moins cher que de
+* décoder pour refuser.
+*/
+const MAX_TOKEN_LENGTH = 8192;
+/**
+* Rend le claim `iss` d'un JWS compact, sans vérifier quoi que ce soit.
+*
+* @param raw - le jeton brut, tel que présenté
+* @returns l'émetteur revendiqué, ou `null` si le jeton est trop gros, mal
+*          formé, ou ne revendique pas d'émetteur exploitable
+*/
+function peekIssuer(raw) {
+	if (raw.length === 0 || raw.length > MAX_TOKEN_LENGTH) return null;
+	const first = raw.indexOf(".");
+	if (first <= 0) return null;
+	const second = raw.indexOf(".", first + 1);
+	if (second <= first + 1) return null;
+	try {
+		const json = Buffer.from(raw.slice(first + 1, second), "base64url").toString("utf8");
+		const claims = JSON.parse(json);
+		if (typeof claims !== "object" || claims === null) return null;
+		const iss = claims.iss;
+		return typeof iss === "string" && iss.length > 0 ? iss : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { peekIssuer as default, peekIssuer };

package/dist/nodefony/src/crypto/secretCipher.js

@@ -0,0 +1,79 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from "node:crypto";
+import { Buffer } from "node:buffer";
+//#region nodefony/src/crypto/secretCipher.ts
+/**
+* Chiffrement **réversible** de secrets applicatifs au repos — AES-256-GCM
+* (authentifié). Brique générique partagée par tous les domaines qui doivent
+* **relire** un secret en clair (≠ mots de passe, hachés à sens unique) : TOTP
+* (clé `K` relue à chaque vérification), webhooks (secret de signature relu à
+* chaque livraison), etc.
+*
+* GCM apporte confidentialité ET intégrité : un blob altéré, ou déchiffré avec
+* la mauvaise clé, fait échouer `final()` (tag invalide) → toute manipulation du
+* secret stocké est détectée.
+*
+* **Séparation de domaine cryptographique** : chaque domaine dérive sa clé via
+* {@link deriveKey} avec un `info`/`salt` HKDF distinct. Une même clé maître de
+* config produit ainsi des sous-clés **indépendantes** par domaine (un blob
+* webhook ne se déchiffre jamais avec la clé TOTP, par construction).
+*
+* Format du blob : `gcm1.<base64url(iv ‖ tag ‖ ciphertext)>` — préfixe versionné
+* pour permettre une rotation d'algorithme future sans casser les secrets existants.
+*/
+const VERSION = "gcm1";
+const IV_BYTES = 12;
+const KEY_BYTES = 32;
+/**
+* Dérive une clé AES-256 (32 octets) d'un matériel de clé applicatif via
+* HKDF-SHA256 (RFC 5869). Accepte toute longueur/forme (passphrase, hex, base64)
+* sans jamais l'utiliser brute comme clé AES. **Déterministe** : tous les pods
+* d'un cluster dérivent la même clé du même secret de config + même domaine
+* (secret lisible cross-pod). Domaines distincts (`info` différent) → clés
+* indépendantes.
+*
+* @param material - matériel de clé brut (secret de config).
+* @param derivation - sel + info propres au domaine (TOTP, webhook…).
+* @returns clé AES-256 (32 octets).
+*/
+function deriveKey(material, derivation) {
+	const ikm = typeof material === "string" ? Buffer.from(material, "utf8") : material;
+	const salt = typeof derivation.salt === "string" ? Buffer.from(derivation.salt) : derivation.salt;
+	const info = typeof derivation.info === "string" ? Buffer.from(derivation.info) : derivation.info;
+	return Buffer.from(hkdfSync("sha256", ikm, salt, info, KEY_BYTES));
+}
+/** Génère une clé éphémère 32 octets (dev sans clé configurée — non persistée). */
+function generateEphemeralKey() {
+	return randomBytes(KEY_BYTES);
+}
+/** Chiffre un secret en clair → blob opaque versionné (IV aléatoire à chaque appel). */
+function encryptSecret(plain, key) {
+	const iv = randomBytes(IV_BYTES);
+	const cipher = createCipheriv("aes-256-gcm", key, iv);
+	const ct = Buffer.concat([cipher.update(plain), cipher.final()]);
+	const tag = cipher.getAuthTag();
+	return `${VERSION}.${Buffer.concat([
+		iv,
+		tag,
+		ct
+	]).toString("base64url")}`;
+}
+/**
+* Déchiffre un blob produit par {@link encryptSecret}. Lève si le format/version
+* est invalide, le blob tronqué, ou le tag GCM non valide (altération OU mauvaise
+* clé — GCM ne distingue pas les deux, par construction).
+*/
+function decryptSecret(blob, key) {
+	const dot = blob.indexOf(".");
+	const version = dot === -1 ? "" : blob.slice(0, dot);
+	if (version !== VERSION) throw new Error(`secret cipher: format/version invalide (« ${version} »)`);
+	const raw = Buffer.from(blob.slice(dot + 1), "base64url");
+	if (raw.length < 28) throw new Error("secret cipher: blob tronqué");
+	const iv = raw.subarray(0, IV_BYTES);
+	const tag = raw.subarray(IV_BYTES, 28);
+	const ct = raw.subarray(28);
+	const decipher = createDecipheriv("aes-256-gcm", key, iv);
+	decipher.setAuthTag(tag);
+	return Buffer.concat([decipher.update(ct), decipher.final()]);
+}
+//#endregion
+export { decryptSecret, deriveKey, encryptSecret, generateEphemeralKey };

package/dist/nodefony/src/csp.js

@@ -0,0 +1,54 @@
+//#region nodefony/src/csp.ts
+/**
+* Parse une chaîne CSP en directives ordonnées `[nom, sources[]]`. L'ordre des
+* directives et des sources est préservé (déterminisme : header stable, tests
+* fiables). Les séparateurs multiples / espaces superflus sont normalisés.
+*/
+function parseCsp(csp) {
+	const out = [];
+	for (const part of csp.split(";")) {
+		const tokens = part.trim().split(/\s+/).filter(Boolean);
+		if (tokens.length === 0) continue;
+		const name = tokens[0];
+		out.push([name, tokens.slice(1)]);
+	}
+	return out;
+}
+/** Sérialise des directives ordonnées en chaîne CSP (`a b; c d`). */
+function serializeCsp(directives) {
+	return directives.map(([name, src]) => src.length ? `${name} ${src.join(" ")}` : name).join("; ");
+}
+/**
+* Fusionne un CSP de base avec des fragments additifs par module.
+*
+* - directive déjà dans la base → ses sources sont COMPLÉTÉES (dédupliquées,
+*   ordre base d'abord puis ajouts) ;
+* - directive absente → AJOUTÉE en fin (ordre d'apparition des fragments).
+*
+* Pur + déterministe : recalculé uniquement quand un module (dé)enregistre ses
+* origines (jamais par requête). Le résultat repart dans `SecurityHeaders`, qui
+* re-split autour de `{{nonce}}` au boot → 1 `join` par requête (hot-path inchangé).
+*
+* @param base - CSP de configuration (peut contenir `'nonce-{{nonce}}'`).
+* @param fragments - fragments additifs (un par module enregistré).
+* @returns la chaîne CSP fusionnée.
+*/
+function mergeCspFragments(base, fragments) {
+	const directives = parseCsp(base);
+	const index = /* @__PURE__ */ new Map();
+	for (const [name, src] of directives) index.set(name, src);
+	for (const fragment of fragments) for (const name in fragment) {
+		const additions = fragment[name];
+		if (additions.length === 0) continue;
+		let sources = index.get(name);
+		if (!sources) {
+			sources = [];
+			index.set(name, sources);
+			directives.push([name, sources]);
+		}
+		for (const src of additions) if (!sources.includes(src)) sources.push(src);
+	}
+	return serializeCsp(directives);
+}
+//#endregion
+export { mergeCspFragments, parseCsp, serializeCsp };

package/dist/nodefony/src/csrfToken.js

@@ -0,0 +1,65 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+//#region nodefony/src/csrfToken.ts
+/**
+* Jeton synchronizer CSRF — modèle **double-submit signé** (OWASP CSRF Prevention
+* Cheat Sheet, « Signed Double-Submit Cookie »). Le token est
+* `nonce.HMAC-SHA256(secret, nonce)` (base64url), posé dans un cookie LISIBLE
+* (`csrf-token`, non HttpOnly) ET rejoué par le client dans l'en-tête
+* `x-csrf-token`. La défense `@CsrfProtect` exige les deux PRÉSENTS, ÉGAUX
+* (double-submit) et la signature HMAC VALIDE.
+*
+* **Stateless** (aucune session requise) → couvre le BFF (cookie de session) ET
+* l'API JWT sans coupler au stockage de session. Le secret HMAC empêche un script
+* tiers de forger un token (il ne peut pas calculer la signature) ; le double
+* submit empêche un attaquant cross-site d'en injecter un (il ne peut ni écrire
+* l'en-tête custom — préflight CORS — ni lire le cookie de la victime — SameSite + SOP).
+*
+* Pure et synchrone (1 HMAC à l'émission, 1 à la vérif) — payé UNIQUEMENT sur les
+* routes `@CsrfProtect` (la défense globale Fetch Metadata reste primaire, hot-path
+* GET = 0).
+*
+* @see OWASP CSRF Prevention Cheat Sheet · RFC 9110 §15.5.4 (403).
+*/
+var CsrfTokenManager = class CsrfTokenManager {
+	#secret;
+	/** Octets aléatoires du nonce (144 bits) — imprévisible, compact en base64url. */
+	static #NONCE_BYTES = 18;
+	constructor(secret) {
+		this.#secret = Buffer.from(secret, "utf8");
+	}
+	/** Émet un token signé `nonce.signature` (base64url). */
+	issue() {
+		const nonce = randomBytes(CsrfTokenManager.#NONCE_BYTES).toString("base64url");
+		return `${nonce}.${this.#sign(nonce)}`;
+	}
+	/**
+	* Vérifie une mutation `@CsrfProtect` : en-tête ET cookie présents, ÉGAUX
+	* (double-submit, comparaison à temps constant) et signature HMAC valide. Tout
+	* écart → `false` (le firewall lève alors un 403). Jamais d'exception.
+	*
+	* @param headerToken - valeur de l'en-tête `x-csrf-token` rejouée par le client.
+	* @param cookieToken - valeur du cookie `csrf-token` posé par le serveur.
+	*/
+	verify(headerToken, cookieToken) {
+		if (!headerToken || !cookieToken) return false;
+		if (!CsrfTokenManager.#timingSafeEqual(headerToken, cookieToken)) return false;
+		const dot = headerToken.lastIndexOf(".");
+		if (dot < 1 || dot === headerToken.length - 1) return false;
+		const nonce = headerToken.slice(0, dot);
+		const signature = headerToken.slice(dot + 1);
+		return CsrfTokenManager.#timingSafeEqual(signature, this.#sign(nonce));
+	}
+	/** HMAC-SHA256 du nonce, base64url. */
+	#sign(nonce) {
+		return createHmac("sha256", this.#secret).update(nonce).digest("base64url");
+	}
+	/** Comparaison à temps constant (longueurs différentes → false sans fuite de timing). */
+	static #timingSafeEqual(a, b) {
+		const ba = Buffer.from(a, "utf8");
+		const bb = Buffer.from(b, "utf8");
+		if (ba.length !== bb.length) return false;
+		return timingSafeEqual(ba, bb);
+	}
+};
+//#endregion
+export { CsrfTokenManager, CsrfTokenManager as default };

package/dist/nodefony/src/net/ssrfGuard.js

@@ -0,0 +1,130 @@
+import { SsrfError } from "../../errors/SsrfError.js";
+import { BlockList, isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+//#region nodefony/src/net/ssrfGuard.ts
+/**
+* Protection **SSRF** (Server-Side Request Forgery) générique pour les URL
+* sortantes — endpoints webhook, fetch applicatif, futurs agents/RAG.
+*
+* Le danger : une URL fournie par un utilisateur peut viser une ressource
+* **interne** non destinée à être exposée (loopback `127.0.0.1`, réseau privé
+* `10.x`/`192.168.x`, et surtout l'endpoint de **métadonnées cloud**
+* `169.254.169.254` qui livre les credentials IAM d'une VM). Le serveur, lui,
+* peut atteindre ces cibles → il devient un proxy de l'attaquant.
+*
+* La défense résout le nom DNS **avant** toute connexion et rejette si une seule
+* des IP résolues est non publique. Les adresses résolues sont retournées pour
+* permettre un **pinning** à la connexion (anti DNS-rebinding : se connecter à
+* l'IP validée, pas re-résoudre).
+*/
+/** Plages IPv4 non routables sur l'Internet public (à bloquer). */
+const BLOCKED_V4 = [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["192.88.99.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+];
+/** Plages IPv6 non routables sur l'Internet public (à bloquer). */
+const BLOCKED_V6 = [
+	["::", 128],
+	["::1", 128],
+	["64:ff9b::", 96],
+	["2002::", 16],
+	["100::", 64],
+	["2001:db8::", 32],
+	["fc00::", 7],
+	["fe80::", 10],
+	["ff00::", 8]
+];
+let blockList = null;
+/** Construit (lazy, une fois) la liste de blocage des IP non publiques. */
+function getBlockList() {
+	if (blockList === null) {
+		const bl = new BlockList();
+		for (const [net, prefix] of BLOCKED_V4) bl.addSubnet(net, prefix, "ipv4");
+		for (const [net, prefix] of BLOCKED_V6) bl.addSubnet(net, prefix, "ipv6");
+		blockList = bl;
+	}
+	return blockList;
+}
+/**
+* Indique si une IP (littérale) est **non publique** (donc interdite comme cible
+* sortante). Une IP syntaxiquement invalide est considérée bloquée (fail-closed).
+*
+* `node:net` `BlockList` rabat **nativement** les IPv6 **IPv4-mapped** — toutes
+* notations confondues (`::ffff:127.0.0.1`, `::ffff:7f00:1`,
+* `0:0:0:0:0:ffff:127.0.0.1`…) — sur les règles IPv4 : `::ffff:169.254.169.254`
+* est bloqué sans traitement spécial (vérifié red-team `webhookSsrf.attack`).
+* ⚠️ NE PAS ajouter `::ffff:0:0/96` à la liste : Node ferait alors matcher TOUTE
+* adresse IPv4 (faux positif massif → 100 % des webhooks rejetés).
+*
+* @param ip - adresse IPv4 ou IPv6 (sans crochets).
+*/
+function isBlockedAddress(ip) {
+	const family = isIP(ip);
+	if (family === 0) return true;
+	return getBlockList().check(ip, family === 4 ? "ipv4" : "ipv6");
+}
+const defaultResolver = async (hostname) => {
+	return (await lookup(hostname, { all: true })).map((r) => r.address);
+};
+/** Retire les crochets d'un hostname IPv6 littéral (`[::1]` → `::1`). */
+function stripBrackets(hostname) {
+	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+/**
+* Valide qu'une URL sortante est sûre (anti-SSRF) : protocole autorisé, pas
+* d'identifiants embarqués, hôte résolvable, et **toutes** les IP résolues
+* publiques. Lève {@link SsrfError} (422) sinon.
+*
+* @param rawUrl - URL brute à valider.
+* @param options - politique (https-only, deny private, résolveur).
+* @returns l'URL normalisée + les IP résolues (pour pinning à la connexion).
+* @throws SsrfError si l'URL est malformée ou cible une ressource interdite.
+*/
+async function assertPublicUrl(rawUrl, options = {}) {
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		throw new SsrfError(`URL invalide : « ${rawUrl} »`);
+	}
+	const scheme = options.allowHttp ? ["https:", "http:"] : ["https:"];
+	if (!scheme.includes(url.protocol)) throw new SsrfError(`protocole « ${url.protocol} » interdit (attendu : ${scheme.join("/")})`);
+	if (url.username !== "" || url.password !== "") throw new SsrfError("identifiants embarqués dans l'URL interdits");
+	const host = stripBrackets(url.hostname);
+	if (host === "") throw new SsrfError("hôte absent");
+	if (options.allowPrivate) return {
+		url,
+		addresses: []
+	};
+	let addresses;
+	if (isIP(host) !== 0) addresses = [host];
+	else {
+		const resolver = options.resolver ?? defaultResolver;
+		try {
+			addresses = await resolver(host);
+		} catch {
+			throw new SsrfError(`hôte non résolvable : « ${host} »`);
+		}
+		if (addresses.length === 0) throw new SsrfError(`hôte sans adresse : « ${host} »`);
+	}
+	for (const ip of addresses) if (isBlockedAddress(ip)) throw new SsrfError(`cible non publique interdite : ${host} → ${ip}`);
+	return {
+		url,
+		addresses
+	};
+}
+//#endregion
+export { assertPublicUrl, isBlockedAddress };

package/dist/nodefony/src/oauth/oauthProviderRegistry.js

@@ -0,0 +1,37 @@
+import { createOidcProvider } from "./providers/oidc.js";
+import { createGithubProvider } from "./providers/github.js";
+//#region nodefony/src/oauth/oauthProviderRegistry.ts
+const factories = /* @__PURE__ */ new Map();
+/**
+* Enregistre (ou remplace) la fabrique d'un fournisseur OAuth. Appelée par les
+* builtins au chargement, et par une application pour ses fournisseurs.
+*/
+function registerOAuthProvider(name, factory) {
+	factories.set(name, factory);
+}
+/** Fabrique d'un fournisseur par nom, ou `undefined` si inconnu. */
+function getOAuthProviderFactory(name) {
+	return factories.get(name);
+}
+/** Noms enregistrés (validation boot, introspection Studio, tests). */
+function listOAuthProviders() {
+	return [...factories.keys()];
+}
+registerOAuthProvider("google", (ctx) => createOidcProvider({
+	name: "google",
+	client: new ctx.arctic.Google(ctx.clientId, ctx.clientSecret, ctx.redirectUri),
+	issuer: "https://accounts.google.com",
+	decodeIdToken: ctx.arctic.decodeIdToken
+}));
+registerOAuthProvider("keycloak", (ctx) => {
+	if (!ctx.issuer) throw new Error("OAuth provider \"keycloak\" : config \"issuer\" requise (URL du realm, ex. https://kc.example/realms/app).");
+	return createOidcProvider({
+		name: "keycloak",
+		client: new ctx.arctic.KeyCloak(ctx.issuer, ctx.clientId, ctx.clientSecret, ctx.redirectUri),
+		issuer: ctx.issuer,
+		decodeIdToken: ctx.arctic.decodeIdToken
+	});
+});
+registerOAuthProvider("github", createGithubProvider);
+//#endregion
+export { getOAuthProviderFactory, listOAuthProviders, registerOAuthProvider };

package/dist/nodefony/src/oauth/providers/github.js

@@ -0,0 +1,65 @@
+//#region nodefony/src/oauth/providers/github.ts
+/** Scopes minimaux : profil public + emails (l'email primaire peut être privé). */
+const DEFAULT_SCOPES = ["read:user", "user:email"];
+const API = "https://api.github.com";
+function ghHeaders(accessToken) {
+	return {
+		Authorization: `Bearer ${accessToken}`,
+		Accept: "application/vnd.github+json",
+		"User-Agent": "nodefony",
+		"X-GitHub-Api-Version": "2022-11-28"
+	};
+}
+async function ghGet(url, accessToken) {
+	const res = await fetch(url, { headers: ghHeaders(accessToken) });
+	if (!res.ok) throw new Error(`GitHub API ${url} → ${res.status}`);
+	return res.json();
+}
+/**
+* Fournisseur **GitHub** (OAuth 2.0 simple, NON-OIDC). Pas de PKCE, pas d'ID
+* token : le profil est lu via l'API REST (`/user`), et l'email — souvent privé —
+* via `/user/emails` (scope `user:email`). GitHub n'émet pas de paramètre `iss`
+* (`expectedIssuer = null`) : la défense anti-CSRF repose sur le `state`.
+*/
+function createGithubProvider(ctx) {
+	const client = new ctx.arctic.GitHub(ctx.clientId, ctx.clientSecret, ctx.redirectUri);
+	return {
+		usesPkce: false,
+		expectedIssuer: null,
+		defaultScopes: DEFAULT_SCOPES,
+		createAuthorizationURL(state, _codeVerifier, scopes) {
+			return client.createAuthorizationURL(state, scopes);
+		},
+		validateAuthorizationCode(code, _codeVerifier) {
+			return client.validateAuthorizationCode(code);
+		},
+		async fetchProfile(tokens) {
+			const accessToken = tokens.accessToken();
+			const user = await ghGet(`${API}/user`, accessToken);
+			const id = user.id;
+			if (typeof id !== "number" && typeof id !== "string") throw new Error("GitHub /user sans identifiant.");
+			const login = typeof user.login === "string" ? user.login : null;
+			const name = typeof user.name === "string" ? user.name : login;
+			let email = typeof user.email === "string" ? user.email : null;
+			let emailVerified = email !== null;
+			if (email === null) {
+				const list = await ghGet(`${API}/user/emails`, accessToken);
+				const primary = list.find((e) => e.primary === true) ?? list[0] ?? null;
+				if (primary && typeof primary.email === "string") {
+					email = primary.email;
+					emailVerified = primary.verified === true;
+				}
+			}
+			return {
+				provider: "github",
+				providerId: String(id),
+				email,
+				emailVerified,
+				name,
+				raw: user
+			};
+		}
+	};
+}
+//#endregion
+export { createGithubProvider };

package/dist/nodefony/src/oauth/providers/oidc.js

@@ -0,0 +1,48 @@
+//#region nodefony/src/oauth/providers/oidc.ts
+const DEFAULT_OIDC_SCOPES = [
+	"openid",
+	"profile",
+	"email"
+];
+/**
+* Fabrique un {@link IOAuthProvider} **générique OIDC** — couvre TOUT fournisseur
+* OpenID Connect sans code spécifique : le profil se lit toujours pareil (claims
+* standard `sub`/`email`/`email_verified`/`name` de l'ID token). Ajouter un
+* fournisseur OIDC = une entrée de quelques lignes (nom + classe arctic + issuer),
+* pas un fichier.
+*
+* PKCE S256 systématique (RFC 7636) ; le profil vient de l'ID token signé obtenu
+* du token endpoint via TLS (décodage suffisant en code flow, RFC 8725).
+*/
+function createOidcProvider(opts) {
+	const requireVerifier = (codeVerifier) => {
+		if (codeVerifier === null) throw new Error(`${opts.name}: code_verifier requis (PKCE OIDC).`);
+		return codeVerifier;
+	};
+	return {
+		usesPkce: true,
+		expectedIssuer: opts.issuer,
+		defaultScopes: opts.defaultScopes ?? DEFAULT_OIDC_SCOPES,
+		createAuthorizationURL(state, codeVerifier, scopes) {
+			return opts.client.createAuthorizationURL(state, requireVerifier(codeVerifier), scopes);
+		},
+		validateAuthorizationCode(code, codeVerifier) {
+			return opts.client.validateAuthorizationCode(code, requireVerifier(codeVerifier));
+		},
+		async fetchProfile(tokens) {
+			const claims = opts.decodeIdToken(tokens.idToken());
+			const sub = claims.sub;
+			if (typeof sub !== "string" || sub.length === 0) throw new Error(`${opts.name}: ID token sans claim 'sub'.`);
+			return {
+				provider: opts.name,
+				providerId: sub,
+				email: typeof claims.email === "string" ? claims.email : null,
+				emailVerified: claims.email_verified === true,
+				name: typeof claims.name === "string" ? claims.name : null,
+				raw: claims
+			};
+		}
+	};
+}
+//#endregion
+export { createOidcProvider };

package/dist/nodefony/src/realtime/UserRealtimeToken.js

@@ -0,0 +1,94 @@
+//#region nodefony/src/realtime/UserRealtimeToken.ts
+/** Aucun scope — figé et partagé (0 allocation pour le cas humain, le plus courant). */
+const EMPTY_SCOPES = Object.freeze([]);
+/**
+* Adaptateur `IUser` → `IRealtimeToken` (jeton realtime).
+*
+* Construit UNIQUEMENT pour un utilisateur **authentifié** (le
+* {@link FirewallRealtimeAuthenticator} ne l'instancie qu'après avoir vérifié
+* l'identité résolue par le firewall) → `isAuthenticated()` est toujours `true`.
+* Un visiteur non authentifié reste sur `ANONYMOUS_REALTIME_TOKEN` (posé par le
+* hub realtime), jamais ici.
+*
+* Les rôles ET les scopes sont des **copies** (pas de fuite de la structure
+* interne de l'utilisateur ni du jeton d'origine). Les deux axes voyagent :
+* les rôles disent qui l'on est, les scopes ce qu'une clé déléguée a le droit
+* de faire — et un agent qui perd ses scopes en passant sur la socket perd la
+* garantie même du mode machine.
+*/
+var UserRealtimeToken = class {
+	/**
+	* Mode d'authentification RÉEL de l'identité (`session`, `jwt`, `apikey`…),
+	* repris du jeton que le firewall a posé dans l'ALS.
+	*
+	* Il était jadis figé à `"session"`, ce qui faisait passer un agent authentifié
+	* par JWT pour un utilisateur à cookie — un mensonge sur l'identité, et la
+	* racine du bug qui révoquait les sockets machine à machine.
+	*/
+	type;
+	#user;
+	/**
+	* Fonction de re-validation Zero Trust, fournie par le
+	* {@link FirewallRealtimeAuthenticator} qui seul connaît le mode
+	* d'authentification et ce qu'il faut relire (session BFF, ou bornes et
+	* denylist d'un jeton porteur) — le token reste découplé : juste une closure.
+	* `null` = aucune re-validation câblée (best-effort).
+	*/
+	#revalidate;
+	/**
+	* Scopes délégués repris du jeton du firewall (clé API / JWT / OAuth). Vide
+	* pour une identité humaine, qui n'est pas downscopée.
+	*/
+	#scopes;
+	/**
+	* @param user - identité authentifiée résolue par le firewall.
+	* @param revalidate - preuve de vie de l'identité, adaptée à son mode.
+	* @param type - mode d'authentification réel (défaut `"session"`).
+	* @param scopes - scopes délégués du jeton d'origine (défaut aucun).
+	*/
+	constructor(user, revalidate = null, type = "session", scopes = EMPTY_SCOPES) {
+		this.#user = user;
+		this.#revalidate = revalidate;
+		this.type = type;
+		this.#scopes = scopes;
+	}
+	/**
+	* Zero Trust : l'identité qui a ouvert cette socket est-elle TOUJOURS vivante ?
+	*
+	* Selon le mode : une session BFF encore ouverte et toujours celle de ce compte
+	* (détecte la déconnexion et le changement de compte sur navigateur partagé),
+	* ou un jeton porteur non expiré et non révoqué. `true` si aucune re-validation
+	* n'a pu être câblée (best-effort, jamais un faux refus).
+	*
+	* @param nowMs - horloge injectable (epoch ms) ; par défaut l'heure courante.
+	*   Sert aux bornes temporelles d'un jeton, et rend le comportement testable
+	*   sans dépendre de l'horloge de la machine.
+	*/
+	isValid(nowMs) {
+		return this.#revalidate ? this.#revalidate(nowMs) : Promise.resolve(true);
+	}
+	getUserIdentifier() {
+		return this.#user.identifier;
+	}
+	isAuthenticated() {
+		return true;
+	}
+	getRoles() {
+		return [...this.#user.roles];
+	}
+	/**
+	* Scopes délégués — copie défensive.
+	*
+	* ⚠️ Ils doivent être RÉELS : `ScopeVoter` ne consulte cette liste que pour un
+	* jeton machine. Une liste vide sur un jeton `jwt`/`apikey` ne veut pas dire
+	* « tous les droits », elle veut dire « aucun scope » — donc refus.
+	*/
+	getScopes() {
+		return [...this.#scopes];
+	}
+	getAttribute(key) {
+		return key === "user" ? this.#user : void 0;
+	}
+};
+//#endregion
+export { UserRealtimeToken, UserRealtimeToken as default };