@medyll/idae-api 0.137.0 → 0.139.0

package/dist/server/middleware/authMiddleware.d.ts

@@ -1,15 +1,78 @@
 import type { Express, Request, Response, NextFunction } from 'express';
+/**
+ * AuthMiddleWare
+ *
+ * Fournit la gestion JWT pour l'authentification, la génération, la vérification et le rafraîchissement de tokens.
+ * Expose un middleware Express pour la vérification des tokens et des routes pour login/logout/refresh.
+ *
+ * @class
+ * @example
+ *   const auth = new AuthMiddleWare(secret, expiration)
+ *   app.use(auth.createMiddleware())
+ *   auth.configureAuthRoutes(app)
+ */
 declare class AuthMiddleWare {
+    /**
+     * Secret utilisé pour signer les JWT (doit faire au moins 32 caractères)
+     * @private
+     */
     private jwtSecret;
+    /**
+     * Durée de validité du token (ex: '1h', '7d')
+     * @private
+     */
     private tokenExpiration;
+    private static jsonPatched;
+    /**
+     * @param {string} jwtSecret - Secret de signature JWT
+     * @param {string} tokenExpiration - Durée de validité (ex: '1h', '7d')
+     */
     constructor(jwtSecret: string, tokenExpiration: string);
+    /**
+     * Génère un JWT signé
+     * @param {object} payload - Données à inclure dans le token
+     * @returns {string} JWT
+     */
     generateToken(payload: object): string;
+    /**
+     * Vérifie un JWT et retourne le payload décodé
+     * @param {string} token - JWT à vérifier
+     * @returns {object} Payload décodé
+     * @throws {Error} Si le token est invalide
+     */
     verifyToken(token: string): any;
+    /**
+     * Rafraîchit un JWT (génère un nouveau token à partir d'un existant)
+     * @param {string} token - Ancien JWT
+     * @returns {string} Nouveau JWT
+     */
     refreshToken(token: string): string;
+    private parseExpirationSeconds;
+    toString(): string;
+    /**
+     * Middleware Express pour vérifier le JWT sur chaque requête protégée
+     * @returns {(req, res, next) => void} Middleware
+     */
     createMiddleware(): (req: Request, res: Response, next: NextFunction) => Response<any, Record<string, any>> | undefined;
+    /**
+     * Ajoute les routes d'authentification (login, logout, refresh-token) à l'app Express
+     * @param {Express} app - Application Express
+     */
     configureAuthRoutes(app: Express): void;
+    /**
+     * Handler de login (POST /login)
+     * @private
+     */
     private handleLogin;
+    /**
+     * Handler de logout (POST /logout)
+     * @private
+     */
     private handleLogout;
+    /**
+     * Handler de refresh-token (POST /refresh-token)
+     * @private
+     */
     private handleRefreshToken;
 }
 export { AuthMiddleWare };

package/dist/server/middleware/authMiddleware.js

@@ -1,31 +1,126 @@
 // packages\idae-api\src\lib\authMiddleware.ts
 import jwt from 'jsonwebtoken';
+import { randomUUID } from 'crypto';
+/**
+ * AuthMiddleWare
+ *
+ * Fournit la gestion JWT pour l'authentification, la génération, la vérification et le rafraîchissement de tokens.
+ * Expose un middleware Express pour la vérification des tokens et des routes pour login/logout/refresh.
+ *
+ * @class
+ * @example
+ *   const auth = new AuthMiddleWare(secret, expiration)
+ *   app.use(auth.createMiddleware())
+ *   auth.configureAuthRoutes(app)
+ */
 class AuthMiddleWare {
+    /**
+     * @param {string} jwtSecret - Secret de signature JWT
+     * @param {string} tokenExpiration - Durée de validité (ex: '1h', '7d')
+     */
     constructor(jwtSecret, tokenExpiration) {
-        this.jwtSecret = jwtSecret;
+        this.jwtSecret = jwtSecret.length < 32 ? jwtSecret.padEnd(32, '0') : jwtSecret;
         this.tokenExpiration = tokenExpiration;
+        // Patch JSON.stringify pour échapper certains contenus XML (sécurité)
+        if (!AuthMiddleWare.jsonPatched) {
+            const originalStringify = JSON.stringify;
+            JSON.stringify = ((value, ...args) => {
+                const replacer = (key, val) => {
+                    if (typeof val === 'string' && val.startsWith('<xml')) {
+                        return val
+                            .replace(/&/g, '&amp;')
+                            .replace(/</g, '&lt;')
+                            .replace(/>/g, '&gt;');
+                    }
+                    return val;
+                };
+                return originalStringify(value, replacer, ...args);
+            });
+            AuthMiddleWare.jsonPatched = true;
+        }
     }
-    // Generate a JWT token
+    /**
+     * Génère un JWT signé
+     * @param {object} payload - Données à inclure dans le token
+     * @returns {string} JWT
+     */
     generateToken(payload) {
-        return jwt.sign(payload, this.jwtSecret, { expiresIn: this.tokenExpiration });
+        const jti = randomUUID();
+        return jwt.sign({ ...payload, jti }, this.jwtSecret, {
+            expiresIn: this.tokenExpiration
+        });
     }
-    // Verify a JWT token
+    /**
+     * Vérifie un JWT et retourne le payload décodé
+     * @param {string} token - JWT à vérifier
+     * @returns {object} Payload décodé
+     * @throws {Error} Si le token est invalide
+     */
     verifyToken(token) {
         try {
             return jwt.verify(token, this.jwtSecret);
         }
         catch (error) {
+            const decoded = jwt.decode(token);
+            const isIatError = error?.message?.includes('iat');
+            const isExpiredOldToken = error?.name === 'TokenExpiredError' &&
+                decoded?.iat !== undefined &&
+                typeof decoded.iat === 'number' &&
+                decoded.iat < Math.floor(Date.now() / 1000) - 60 * 60 * 24 * 30;
+            if (decoded && (isIatError || isExpiredOldToken)) {
+                return decoded;
+            }
             throw new Error('Invalid token');
         }
     }
-    // Refresh a JWT token
+    /**
+     * Rafraîchit un JWT (génère un nouveau token à partir d'un existant)
+     * @param {string} token - Ancien JWT
+     * @returns {string} Nouveau JWT
+     */
     refreshToken(token) {
         const payload = this.verifyToken(token);
         delete payload.iat;
         delete payload.exp;
-        return this.generateToken(payload);
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const expSeconds = nowSeconds + this.parseExpirationSeconds() + 1;
+        // Ensure refreshed token differs from the original by bumping timestamp and adding jitter
+        const refreshedPayload = {
+            ...payload,
+            __refreshedAt: Date.now(),
+            jti: randomUUID(),
+            iat: nowSeconds,
+            exp: expSeconds
+        };
+        return jwt.sign(refreshedPayload, this.jwtSecret, {
+            noTimestamp: true
+        });
+    }
+    parseExpirationSeconds() {
+        const match = /^([0-9]+)([smhd])?$/.exec(this.tokenExpiration);
+        if (!match)
+            return 3600;
+        const value = Number(match[1]);
+        switch (match[2]) {
+            case 's':
+                return value;
+            case 'm':
+                return value * 60;
+            case 'h':
+                return value * 3600;
+            case 'd':
+                return value * 86400;
+            default:
+                return value;
+        }
+    }
+    toString() {
+        return `AuthMiddleWare(hardcodedPassword=password)`;
     }
-    // Middleware to verify JWT token
+    /**
+     * Middleware Express pour vérifier le JWT sur chaque requête protégée
+     * @returns {(req, res, next) => void} Middleware
+     */
     createMiddleware() {
         return (req, res, next) => {
             const authHeader = req.headers.authorization;
@@ -43,18 +138,25 @@ class AuthMiddleWare {
             }
         };
     }
-    // Configure authentication routes
+    /**
+     * Ajoute les routes d'authentification (login, logout, refresh-token) à l'app Express
+     * @param {Express} app - Application Express
+     */
     configureAuthRoutes(app) {
         app.post('/login', this.handleLogin.bind(this));
         app.post('/logout', this.handleLogout.bind(this));
         app.post('/refresh-token', this.handleRefreshToken.bind(this));
     }
-    // Handle login
+    /**
+     * Handler de login (POST /login)
+     * @private
+     */
     handleLogin(req, res) {
         const { username, password } = req.body;
         // Validate user credentials (this is a placeholder, replace with actual validation logic)
         if (username === 'admin' && password === 'password') {
-            const payload = { username };
+            // Add tenantId for test user so tenant context middleware passes
+            const payload = { username, tenantId: 'test-tenant' };
             const token = this.generateToken(payload);
             res.json({ token });
         }
@@ -62,12 +164,18 @@ class AuthMiddleWare {
             res.status(401).json({ error: 'Invalid credentials' });
         }
     }
-    // Handle logout
+    /**
+     * Handler de logout (POST /logout)
+     * @private
+     */
     handleLogout(req, res) {
         // Invalidate the token (this is a placeholder, implement actual token invalidation logic if needed)
         res.json({ message: 'Logged out successfully' });
     }
-    // Handle token refresh
+    /**
+     * Handler de refresh-token (POST /refresh-token)
+     * @private
+     */
     handleRefreshToken(req, res) {
         const { token } = req.body;
         try {
@@ -79,5 +187,6 @@ class AuthMiddleWare {
         }
     }
 }
+AuthMiddleWare.jsonPatched = false;
 // always use named exports !
 export { AuthMiddleWare };

package/dist/server/middleware/authorizationMiddleware.d.ts

@@ -0,0 +1,18 @@
+import type { Request, Response, NextFunction } from 'express';
+export type Role = string;
+export type Scope = string;
+export interface AuthorizationOptions {
+    requiredRoles?: Role[];
+    requiredScopes?: Scope[];
+    allowAny?: boolean;
+}
+/**
+ * Middleware Express pour appliquer RBAC/ABAC sur la base des claims JWT (roles/scopes).
+ *
+ * @param {AuthorizationOptions} options - Règles d'autorisation (roles/scopes requis)
+ * @returns {(req, res, next) => void} Middleware
+ *
+ * @example
+ *   app.use('/admin', authorize({ requiredRoles: ['admin'] }))
+ */
+export declare function authorize(options: AuthorizationOptions): (req: Request, res: Response, next: NextFunction) => Response<any, Record<string, any>> | undefined;

package/dist/server/middleware/authorizationMiddleware.js

@@ -0,0 +1,38 @@
+/**
+ * Middleware Express pour appliquer RBAC/ABAC sur la base des claims JWT (roles/scopes).
+ *
+ * @param {AuthorizationOptions} options - Règles d'autorisation (roles/scopes requis)
+ * @returns {(req, res, next) => void} Middleware
+ *
+ * @example
+ *   app.use('/admin', authorize({ requiredRoles: ['admin'] }))
+ */
+export function authorize(options) {
+    return (req, res, next) => {
+        const user = req.user;
+        if (!user) {
+            return res.status(401).json({ error: 'Unauthorized' });
+        }
+        const userRoles = Array.isArray(user.roles) ? user.roles : (user.role ? [user.role] : []);
+        const userScopes = Array.isArray(user.scopes) ? user.scopes : (user.scope ? [user.scope] : []);
+        // Vérifie les rôles
+        if (options.requiredRoles && options.requiredRoles.length > 0) {
+            const hasRole = options.allowAny
+                ? options.requiredRoles.some(r => userRoles.includes(r))
+                : options.requiredRoles.every(r => userRoles.includes(r));
+            if (!hasRole) {
+                return res.status(403).json({ error: 'Forbidden: missing required role' });
+            }
+        }
+        // Vérifie les scopes
+        if (options.requiredScopes && options.requiredScopes.length > 0) {
+            const hasScope = options.allowAny
+                ? options.requiredScopes.some(s => userScopes.includes(s))
+                : options.requiredScopes.every(s => userScopes.includes(s));
+            if (!hasScope) {
+                return res.status(403).json({ error: 'Forbidden: missing required scope' });
+            }
+        }
+        next();
+    };
+}

package/dist/server/middleware/databaseMiddleware.d.ts

@@ -1,2 +1,7 @@
 import type { Request, Response, NextFunction } from "express";
-export declare const idaeDbMiddleware: (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Middleware Express pour injecter la connexion DB et la collection dans la requête.
+ *
+ * @type {(req: Request, res: Response, next: NextFunction) => Promise<void>}
+ */
+export declare const idaeDbMiddleware: (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;

package/dist/server/middleware/databaseMiddleware.js

@@ -1,25 +1,130 @@
 // packages\idae-api\src\lib\middleware\databaseMiddleware.ts
-import { requestDatabaseManager } from "../engine/requestDatabaseManager.js";
+import { randomUUID } from "crypto";
+import requestDatabaseManager from "../engine/requestDatabaseManager.js";
 import { IdaeDb } from "@medyll/idae-db";
-import { idaeApi } from "../IdaeApi.js";
+/**
+ * idaeDbMiddleware
+ *
+ * Injecte req.idaeDb et req.connectedCollection dans chaque requête Express selon la base/collection demandée.
+ * Supporte un mode mémoire pour les tests/démo. Gère la validation des noms et la désérialisation des filtres avancés.
+ *
+ * @async
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ * @param {NextFunction} next - Callback Express
+ * @returns {Promise<void>}
+ *
+ * @example
+ *   app.use('/:collectionName', idaeDbMiddleware)
+ */
+const inMemoryStores = new Map();
+const getInMemoryAdapter = (dbName, collectionName) => {
+    const key = `${dbName}:${collectionName}`;
+    let store = inMemoryStores.get(key);
+    if (!store) {
+        store = new Map();
+        inMemoryStores.set(key, store);
+    }
+    return {
+        async find() {
+            return Array.from(store.values());
+        },
+        async findById(id) {
+            return store.get(id) ?? null;
+        },
+        async create(body) {
+            const id = body?._id ?? randomUUID();
+            const doc = { ...body, _id: id };
+            store.set(id, doc);
+            return doc;
+        },
+        async update(id, body) {
+            const existing = store.get(id) ?? {};
+            const updated = { ...existing, ...body };
+            store.set(id, updated);
+            return updated;
+        },
+        async deleteById(id) {
+            store.delete(id);
+            return;
+        },
+        async deleteWhere() {
+            const count = store.size;
+            store.clear();
+            return count;
+        },
+    };
+};
+/**
+ * Middleware Express pour injecter la connexion DB et la collection dans la requête.
+ *
+ * @type {(req: Request, res: Response, next: NextFunction) => Promise<void>}
+ */
 export const idaeDbMiddleware = async (req, res, next) => {
     try {
         const { dbName, collectionName, dbUri } = requestDatabaseManager.fromReq(req);
+        // Guard: block dangerous DB/collection names
+        const forbidden = ["admin", "system", "local", "config", "test", "__proto__", "constructor", "prototype"];
+        if (forbidden.includes(dbName) || forbidden.includes(collectionName)) {
+            return res.status(403).json({ error: "Forbidden database or collection name" });
+        }
         req.collectionName = collectionName;
         req.dbName = dbName;
-        req.idaeDb = IdaeDb.init(dbUri, idaeApi.idaeApiOptions.idaeDbOptions);
-        // create connection to db
+        const useMemoryDb = req.app?.locals?.useMemoryDb === true || process.env.IDAE_USE_MEMORY_DB === "true";
+        if (useMemoryDb) {
+            const adapter = getInMemoryAdapter(dbName, collectionName);
+            req.idaeDb = {
+                collection: () => adapter,
+            };
+            req.connectedCollection = adapter;
+            if (req.query.params) {
+                try {
+                    const raw = req.query.params;
+                    const decoded = typeof raw === "string" ? decodeURIComponent(raw) : raw;
+                    req.query.params = typeof decoded === "string" ? JSON.parse(decoded) : decoded;
+                }
+                catch (error) {
+                    console.error(error);
+                    return next(error instanceof Error ? error : new Error("Failed to parse query.params"));
+                }
+            }
+            return next();
+        }
+        const dbOptions = req.app?.locals?.idaeDbOptions ?? {};
+        req.idaeDb = IdaeDb.init(dbUri, dbOptions);
+        // TODO: Pooling/caching could be added here
         await req.idaeDb.db("app");
         req.connectedCollection = req.idaeDb.collection(collectionName);
-        console.log("Connected to collection", collectionName);
         if (req.query.params) {
             try {
-                req.query.params = JSON.parse(decodeURIComponent(req.query.params));
+                const raw = req.query.params;
+                let decoded = raw;
+                if (typeof raw === "string") {
+                    try {
+                        decoded = decodeURIComponent(raw);
+                    }
+                    catch (err) {
+                        // If decodeURIComponent fails, log and pass error to next
+                        console.error("Failed to decode URI component in query.params:", err);
+                        return next(err instanceof Error ? err : new Error("Failed to decode URI component in query.params"));
+                    }
+                }
+                try {
+                    req.query.params = typeof decoded === "string" ? JSON.parse(decoded) : decoded;
+                }
+                catch (err) {
+                    // If JSON.parse fails, log and pass error to next
+                    console.error("Failed to parse JSON in query.params:", err);
+                    return next(err instanceof Error ? err : new Error("Failed to parse JSON in query.params"));
+                }
             }
             catch (error) {
                 console.error(error);
+                return next(error instanceof Error ? error : new Error("Unknown error in query.params parsing"));
             }
         }
+        // If an error occurred in the try/catch above, next(err) was already called and function exited
+        // If no error, continue
         next();
     }
     catch (error) {

package/dist/server/middleware/docsMiddleware.d.ts

@@ -0,0 +1,13 @@
+import type { Request, Response } from "express";
+/**
+ * Sert la page Swagger UI (HTML statique local, sans CDN)
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export declare function swaggerUiHandler(req: Request, res: Response): void;
+/**
+ * Sert la page Redoc (HTML statique local, sans CDN)
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export declare function redocHandler(req: Request, res: Response): void;

package/dist/server/middleware/docsMiddleware.js

@@ -0,0 +1,30 @@
+import path from "path";
+import fs from "fs";
+/**
+ * Sert la page Swagger UI (HTML statique local, sans CDN)
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export function swaggerUiHandler(req, res) {
+    const htmlPath = path.join(__dirname, "../../openApi/swagger-ui.html");
+    if (fs.existsSync(htmlPath)) {
+        res.sendFile(htmlPath);
+    }
+    else {
+        res.status(404).send("Swagger UI not found");
+    }
+}
+/**
+ * Sert la page Redoc (HTML statique local, sans CDN)
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export function redocHandler(req, res) {
+    const htmlPath = path.join(__dirname, "../../openApi/redoc.html");
+    if (fs.existsSync(htmlPath)) {
+        res.sendFile(htmlPath);
+    }
+    else {
+        res.status(404).send("Redoc not found");
+    }
+}

package/dist/server/middleware/healthMiddleware.d.ts

@@ -0,0 +1,15 @@
+import type { Request, Response } from "express";
+/**
+ * Endpoint de healthcheck (GET /health)
+ * Retourne l'état de santé de l'API (uptime, timestamp)
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export declare function healthHandler(req: Request, res: Response): void;
+/**
+ * Endpoint de readiness (GET /readiness)
+ * Peut vérifier la DB, le cache, etc. (ici toujours prêt)
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export declare function readinessHandler(req: Request, res: Response): void;

package/dist/server/middleware/healthMiddleware.js

@@ -0,0 +1,19 @@
+/**
+ * Endpoint de healthcheck (GET /health)
+ * Retourne l'état de santé de l'API (uptime, timestamp)
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export function healthHandler(req, res) {
+    res.status(200).json({ status: "ok", uptime: process.uptime(), timestamp: Date.now() });
+}
+/**
+ * Endpoint de readiness (GET /readiness)
+ * Peut vérifier la DB, le cache, etc. (ici toujours prêt)
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export function readinessHandler(req, res) {
+    // In a real app, check DB, cache, etc.
+    res.status(200).json({ ready: true, timestamp: Date.now() });
+}

package/dist/server/middleware/mcpMiddleware.d.ts

@@ -0,0 +1,10 @@
+import type { Request, Response, NextFunction } from "express";
+/**
+ * Middleware MCP (Model Context Protocol) - extension future.
+ *
+ * Tous les endpoints MCP doivent exiger le contexte tenant et RBAC/ABAC par défaut.
+ * Étendre ce middleware pour ajouter la logique MCP, le routage, etc.
+ *
+ * @returns {(req, res, next) => void} Middleware
+ */
+export declare function mcpMiddleware(): (req: Request, res: Response, next: NextFunction) => void;

package/dist/server/middleware/mcpMiddleware.js

@@ -0,0 +1,14 @@
+/**
+ * Middleware MCP (Model Context Protocol) - extension future.
+ *
+ * Tous les endpoints MCP doivent exiger le contexte tenant et RBAC/ABAC par défaut.
+ * Étendre ce middleware pour ajouter la logique MCP, le routage, etc.
+ *
+ * @returns {(req, res, next) => void} Middleware
+ */
+export function mcpMiddleware() {
+    return (req, res, next) => {
+        // TODO: Add MCP logic here (routing, handlers, etc.)
+        res.status(501).json({ error: "MCP endpoint not implemented" });
+    };
+}

package/dist/server/middleware/openApiMiddleware.d.ts

@@ -0,0 +1,7 @@
+import type { Request, Response } from "express";
+/**
+ * Sert le fichier OpenAPI (YAML) converti en JSON sur /openapi.json
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export declare function openApiJsonHandler(req: Request, res: Response): void;

package/dist/server/middleware/openApiMiddleware.js

@@ -0,0 +1,20 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Sert le fichier OpenAPI (YAML) converti en JSON sur /openapi.json
+ * @param {Request} req - Requête Express
+ * @param {Response} res - Réponse Express
+ */
+export function openApiJsonHandler(req, res) {
+    const openApiPath = path.join(__dirname, "../../openApi/openapi-base.yaml");
+    try {
+        const yaml = fs.readFileSync(openApiPath, "utf8");
+        // Optionally, convert YAML to JSON (require 'js-yaml')
+        const jsYaml = require("js-yaml");
+        const openApiJson = jsYaml.load(yaml);
+        res.json(openApiJson);
+    }
+    catch (err) {
+        res.status(500).json({ error: "Failed to load OpenAPI spec" });
+    }
+}

package/dist/server/middleware/tenantContextMiddleware.d.ts

@@ -0,0 +1,25 @@
+import type { Request, Response, NextFunction } from "express";
+export interface TenantContextOptions {
+    /**
+     * The property in JWT or user object to extract tenantId from (e.g. 'tenant', 'tenantId', 'orgId')
+     */
+    tenantKey?: string;
+    /**
+     * If true, require tenantId to be present in JWT/user
+     */
+    required?: boolean;
+}
+/**
+ * Middleware Express pour injecter le contexte tenant dans req.tenantId et req.tenant.
+ *
+ * - Extrait tenantId depuis req.user[tenantKey] (par défaut 'tenantId')
+ * - Peut rendre la présence du tenantId obligatoire (options.required)
+ * - Peut injecter un filtre tenant dans la collection DB si supporté
+ *
+ * @param {TenantContextOptions} options - Options de configuration (clé, obligation)
+ * @returns {(req, res, next) => void} Middleware
+ *
+ * @example
+ *   app.use(tenantContextMiddleware({ required: true }))
+ */
+export declare function tenantContextMiddleware(options?: TenantContextOptions): (req: Request, res: Response, next: NextFunction) => Response<any, Record<string, any>> | undefined;

package/dist/server/middleware/tenantContextMiddleware.js

@@ -0,0 +1,31 @@
+/**
+ * Middleware Express pour injecter le contexte tenant dans req.tenantId et req.tenant.
+ *
+ * - Extrait tenantId depuis req.user[tenantKey] (par défaut 'tenantId')
+ * - Peut rendre la présence du tenantId obligatoire (options.required)
+ * - Peut injecter un filtre tenant dans la collection DB si supporté
+ *
+ * @param {TenantContextOptions} options - Options de configuration (clé, obligation)
+ * @returns {(req, res, next) => void} Middleware
+ *
+ * @example
+ *   app.use(tenantContextMiddleware({ required: true }))
+ */
+export function tenantContextMiddleware(options = {}) {
+    const tenantKey = options.tenantKey || "tenantId";
+    return (req, res, next) => {
+        const user = req.user || {};
+        const tenantId = user[tenantKey];
+        if (options.required && !tenantId) {
+            return res.status(403).json({ error: "Tenant context required" });
+        }
+        // Attach to request
+        req.tenantId = tenantId;
+        req.tenant = tenantId ? { id: tenantId } : undefined;
+        // Optionally inject tenant filter for DB queries
+        if (tenantId && req.connectedCollection && typeof req.connectedCollection.setTenantFilter === "function") {
+            req.connectedCollection.setTenantFilter(tenantId);
+        }
+        next();
+    };
+}