@ti-engine/web-framework 1.19.0 → 1.20.0

package/components/web-handlers.js

@@ -1,800 +1,803 @@
-/*
- * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
-
-const logger = require( "@ti-engine/core/logger" );
-const exceptions = require( "@ti-engine/core/exceptions" );
-const localization = require( "@ti-engine/core/localization" );
-const { randomBytes, timingSafeEqual } = require( "node:crypto" );
-const URL = require( "node:url" ).URL;
-const _ = require( "lodash" );
-const helmet = require( "helmet" );
-const cache = require( "@ti-engine/core/cache" );
-const authMethod = require( "#auth-manager" ).authMethod;
-const authorization = require( "#authorization" );
-
-/** @typedef {import("express").Request} ExpressRequest */
-/** @typedef {import("express").res} ExpressResponse */
-
-/**
- * Express middleware callback.
- *
- * @callback ExpressHandler
- * @param {ExpressRequest} request
- * @param {ExpressResponse} response
- * @param {function( Error | null )} next
- * @returns {void}
- */
-
-/**
- * Express middleware callback with an error.
- *
- * @callback ExpressErrorHandler
- * @param {Error} error
- * @param {ExpressRequest} request
- * @param {ExpressResponse} response
- * @param {function( Error | null )} next
- * @returns {void}
- */
-
-/**
- * Default HTTP status for specific exception codes that do not carry an explicit `httpCode`.
- *
- * @type {Object<number, TiHttpCode>}
- */
-const DEFAULT_HTTP_CODE_BY_EXCEPTION = {
-    [ exceptions.exceptionCode.E_WEB_INVALID_REQUEST_METHOD ]: exceptions.httpCode.C_405,
-    [ exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI ]: exceptions.httpCode.C_404,
-    [ exceptions.exceptionCode.E_WEB_INVALID_REQUEST_CONTENT_TYPE ]: exceptions.httpCode.C_415,
-    [ exceptions.exceptionCode.E_WEB_INVALID_REQUEST_CONTENT_LENGTH ]: exceptions.httpCode.C_413,
-    [ exceptions.exceptionCode.E_APP_RESOURCE_NOT_FOUND ]: exceptions.httpCode.C_404,
-    [ exceptions.exceptionCode.E_APP_RESOURCE_ALREADY_EXISTS ]: exceptions.httpCode.C_409
-};
-
-/**
- * Resolves the HTTP status to report for an exception. An explicit `httpCode` on the exception always wins; otherwise
- * the status is derived from the exception code so that client and application errors surface as 4xx — request and
- * application-logic failures as `422 Unprocessable Content`, security as `403` — instead of being misreported as a
- * generic `500`. Only genuine internal, communication, and unknown errors default to `500`.
- *
- * @method
- * @param {TiException} exception
- * @returns {TiHttpCode}
- */
-const resolveHttpCode = ( exception ) => {
-    if ( exception.httpCode ) {
-        return exception.httpCode;
-    }
-    const code = exception.code;
-    if ( DEFAULT_HTTP_CODE_BY_EXCEPTION[ code ] ) {
-        return DEFAULT_HTTP_CODE_BY_EXCEPTION[ code ];
-    }
-    if ( code >= 2000 && code < 3000 ) {
-        return exceptions.httpCode.C_403; // security / authorization
-    }
-    if ( code >= 4000 && code < 6000 ) {
-        return exceptions.httpCode.C_422; // request validation + application logic → unprocessable content
-    }
-    return exceptions.httpCode.C_500; // general, communication, or unknown → internal server error
-};
-
-/**
- * Used to assemble the current URL of a request.
- *
- * @method
- * @param {ExpressRequest} request
- * @returns {string}
- * @private
- */
-let getBaseUrl = ( request ) => {
-    const xfProtocol = String( request.get( "x-forwarded-proto" ) || "" ).toLowerCase();
-    const xfHost = request.get( "x-forwarded-host" );
-    const protocol = ( request.secure || xfProtocol === "https" ) ? "https" : "http";
-    const host = xfHost || request.get( "host" );
-    return `${ protocol }://${ host }`;
-};
-
-/**
- * Timing-safe token comparison.
- *
- * @method
- * @param {string} first
- * @param {string} second
- * @returns {boolean}
- * @private
- */
-let safeEquals = ( first, second ) => {
-    try {
-        const ba = Buffer.from( String( first || "" ) );
-        const bb = Buffer.from( String( second || "" ) );
-        return ( ba.length !== bb.length ) ? false : timingSafeEqual( ba, bb );
-    } catch {
-        return false;
-    }
-};
-
-/**
- * Extract origin to validate. Prefer Origin, fallback to Referer origin.
- *
- * @method
- * @param {ExpressRequest} request
- * @returns {string|undefined} e.g., "https://example.com:8443"
- * @private
- */
-let getRequestOrigin = ( request ) => {
-    let result = undefined;
-    const rawOrigin = request.get( "origin" );
-    const origin = String( rawOrigin || "" ).trim().toLowerCase();
-
-    // Ignore explicit "null" or empty origins:
-    if ( origin && origin !== "null" ) {
-        result = rawOrigin;
-    } else {
-        const referer = request.get( "referer" );
-        if ( referer ) {
-            try {
-                const refererUrl = new URL( referer );
-                result = `${ refererUrl.protocol }//${ refererUrl.host }`;
-            } catch {
-                // do nothing here...
-            }
-        }
-    }
-
-    return result;
-};
-
-/**
- * Used to regenerate the session and save it.
- *
- * @method
- * @param {ExpressRequest} request
- * @param {string} redirectTo
- * @param {function( TiSession ): TiSession} modifier
- * @returns {Promise<string>}
- * @private
- */
-let regenerateAndSaveSession = ( request, redirectTo, modifier ) => {
-    return new Promise( ( resolve, reject ) => {
-        request.session.regenerate( ( error ) => {
-            if ( error ) {
-                reject( error );
-            } else {
-                try {
-                    if ( modifier && typeof modifier === "function" ) {
-                        request.session = modifier( request.session );
-                    }
-                } catch ( error ) {
-                    reject( error );
-                    return;
-                }
-                request.session.save( ( error ) => {
-                    if ( error ) {
-                        reject( error );
-                    } else {
-                        resolve( redirectTo );
-                    }
-                } )
-            }
-        } )
-    } );
-};
-
-/**
- * Check if the request is an HTMX request.
- *
- * @method
- * @param {ExpressRequest} request
- * @returns {boolean}
- * @private
- */
-let isHtmxRequest = ( request ) => {
-    return String( request.get( "HX-Request" ) || "" ).toLowerCase() === "true";
-};
-
-/**
- * Used to determine if the request accepts the specified response type.
- *
- * @method
- * @param {ExpressRequest} request
- * @param {string} type
- * @return {boolean}
- * @private
- */
-let isAcceptingResponseType = ( request, type ) => {
-    const accept = String( request.get( "accept" ) || "" ).toLowerCase();
-    if ( accept ) {
-        return request.accepts( type ) === type;
-    } else {
-        return false;
-    }
-};
-
-/**
- * Safely convert a URI to a string.
- *
- * @method
- * @param {URL|string} uri
- * @return {string}
- * @private
- */
-let convertUriToString = ( uri ) => {
-    return ( typeof uri === "string" ) ? uri : ( uri && typeof uri.toString === "function" ) ? uri.toString() : "/";
-};
-
-/**
- * Handler for requests that are received while the web server is shutting down.
- *
- * @method
- * @param {TiWebServer} instance
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.onShutDownHandler = ( instance ) => {
-    return ( request, response, next ) => {
-        if ( !instance.isShuttingDown ) {
-            next();
-        } else {
-            response.set( "Connection", "close" );
-            response.status( exceptions.httpCode.C_503 ).end();
-        }
-    };
-};
-
-/**
- * Handler that verifies if the requested resource requires authentication or is freely accessible.
- *
- * @method
- * @param {TiWebServer} instance
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.resourceProtectionHandler = ( instance ) => {
-    return ( request, response, next ) => {
-        if ( instance.isUnprotectedRoute( request.url ) || instance.verifySession( request.session ) ) {
-            next();
-        } else {
-            const redirectTo = "/";
-            if ( isHtmxRequest( request ) ) {
-                response.set( "HX-Redirect", redirectTo );
-                response.status( exceptions.httpCode.C_204 ).end();
-            } else if ( isAcceptingResponseType( request, "html" ) ) {
-                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
-            } else {
-                response.status( exceptions.httpCode.C_401 ).end();
-            }
-        }
-    };
-};
-
-/**
- * Handler for server-side authentication.
- *
- * @method
- * @param {TiWebServer} instance
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.authenticationHandler = ( instance ) => {
-    return ( request, response, next ) => {
-        const method = request.params.method;
-        if ( method === authMethod.LOCAL ) {
-            const username = String( ( request.body && request.body.username ) || "" ).trim();
-            const password = String( ( request.body && request.body.password ) || "" );
-            instance.authenticate( authMethod.LOCAL, { username: username, password: password } ).then( () => {
-                return instance.authorize( authMethod.LOCAL, new URL( request.originalUrl, getBaseUrl( request ) ), { username: username } );
-            } ).then( ( user ) => {
-                return regenerateAndSaveSession( request, "/", ( session ) => {
-                    session.user = user.asJSON();
-                    session.language = user.language || instance.serviceConfig.language;
-
-                    return authorization.applyAdminRole( instance.augmentSession( session, request ), instance.serviceConfig?.auth?.admins );
-                } );
-            } ).then( ( redirectTo ) => {
-                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
-            } ).catch( ( error ) => {
-                next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
-            } );
-        } else if ( method === authMethod.OPENID_GOOGLE || method === authMethod.OPENID_AZURE ) {
-            instance.authenticate( method, { baseUrl: getBaseUrl( request ) } ).then( ( result ) => {
-                return regenerateAndSaveSession( request, result.redirectTo, ( session ) => {
-                    session.oidc = { codeVerifier: result.codeVerifier, state: result.state, nonce: result.nonce };
-                    return session;
-                } );
-            } ).then( ( redirectTo ) => {
-                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
-            } ).catch( ( error ) => {
-                next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
-            } );
-        } else {
-            next();
-        }
-    };
-};
-
-/**
- * Used to handle the callback from the Google OpenID authentication.
- *
- * @method
- * @param {TiWebServer} instance
- * @param {TiAuthMethod} authMethod
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.authorizedOAuth2CallbackHandler = ( instance, authMethod ) => {
-    return ( request, response, next ) => {
-        const code = request.query.code;
-        const state = request.query.state;
-        const oidc = request.session.oidc || {};
-        if ( !code || !oidc?.codeVerifier ) {
-            response.status( exceptions.httpCode.C_400 ).end();
-        } else if ( oidc.state && state !== oidc.state ) {
-            response.status( exceptions.httpCode.C_400 ).end();
-        } else {
-            instance.authorize( authMethod, new URL( request.originalUrl, getBaseUrl( request ) ), oidc ).then( ( user ) => {
-                return regenerateAndSaveSession( request, "/", ( session ) => {
-                    session.user = user.asJSON();
-                    session.language = user.language || instance.serviceConfig.language;
-
-                    delete session.oidc;
-
-                    return authorization.applyAdminRole( instance.augmentSession( session, request ), instance.serviceConfig?.auth?.admins );
-                } );
-            } ).then( ( redirectTo ) => {
-                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
-            } ).catch( ( error ) => {
-                next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
-            } );
-        }
-    };
-};
-
-/**
- * Handler for server-side logout.
- *
- * @method
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.logoutHandler = () => {
-    return ( request, response, next ) => {
-        const done = ( error ) => {
-            response.redirect( exceptions.httpCode.C_303, "/" );
-        };
-        if ( request.session ) {
-            request.session.destroy( done );
-        } else {
-            done();
-        }
-    };
-};
-
-/**
- * Handler for a lightweight, unauthenticated health probe. Responds `200` whenever the web server is serving
- * (a liveness signal for container/orchestrator probes), and reports the message-broker (Redis) connection state
- * in the body so it can double as a readiness signal without hitting a user-facing route like the login page.
- *
- * @method
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.healthHandler = () => {
-    return ( request, response ) => {
-        const broker = ( cache.instance && cache.instance.isOperational === true ) ? "connected" : "disconnected";
-        response.status( exceptions.httpCode.C_200 ).send( {
-            isSuccessful: true,
-            data: {
-                status: "ok",
-                broker: broker,
-                uptime: Math.round( process.uptime() )
-            }
-        } );
-    };
-};
-
-/**
- * Handler for retrieving authenticated user information.
- *
- * @method
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.userInformationHandler = () => {
-    return ( request, response, next ) => {
-        if ( request.session && request.session.user ) {
-            response.status( exceptions.httpCode.C_200 ).send( { isSuccessful: true, data: { user: _.cloneDeep( request.session.user ) } } );
-        } else {
-            next( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
-        }
-    };
-};
-
-/**
- * Handler for redirecting HTTP requests to HTTPS. Also works behind proxies using X-Forwarded-Proto.
- *
- * @method
- * @param {TiWebServer} instance
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.httpRedirectHandler = ( instance ) => {
-    return ( request, response, next ) => {
-        const xfProto = String( request.get ? request.get( "x-forwarded-proto" ) : ( request.headers[ "x-forwarded-proto" ] || "" ) ).toLowerCase();
-        const isSecure = request.secure === true || xfProto === "https";
-        if ( isSecure ) {
-            next();
-        } else {
-            if ( instance.isAllowedHost( request.hostname ) !== true ) {
-                response.status( exceptions.httpCode.C_404 ).end();
-            } else {
-                const host = request.get ? request.get( "host" ) : request.headers.host;
-                const location = new URL( request.url, "https://" + host );
-                response.set( "Cache-Control", "no-store" );
-                response.redirect( exceptions.httpCode.C_308, convertUriToString( location ) );
-            }
-        }
-    }
-};
-
-/**
- * Handler for processing of API service calls.
- * <br/>
- * NOTE: This will send a new {@link ServiceCall} to the microservice network handled by the ti-engine.
- *
- * @method
- * @param {TiWebServer} instance
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.serviceCallHandler = ( instance ) => {
-    return ( request, response, next ) => {
-        let serviceAddress = instance.getServiceAddress( request.params.version, request.params.name );
-        if ( !serviceAddress ) {
-            next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, null, exceptions.httpCode.C_404 ) );
-        } else {
-            request.setTimeout( instance.serviceConfig.api.requestTimeout );
-            instance.callService( serviceAddress, request.body || {}, {
-                authToken: request.sessionID,
-            } ).then( ( result ) => {
-                if ( result.isSuccessful !== true ) {
-                    next( exceptions.raise( result.exception || exceptions.exceptionCode.E_COM_SERVICE_EXEC_FAILED, null, result.exception?.httpCode || exceptions.httpCode.C_400 ) );
-                } else {
-                    response.status( exceptions.httpCode.C_200 ).send( result );
-                }
-            } ).catch( ( error ) => {
-                next( error );
-            } );
-        }
-    };
-};
-
-/**
- * Handler to intercept and handle all remaining requests to invalid URLs.
- *
- * @method
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.invalidRouteHandler = () => {
-    return ( request, response, next ) => {
-        next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, null, exceptions.httpCode.C_404 ) );
-    };
-};
-
-/**
- * Handler to intercept any errors that have not been resolved by previous middleware. Should be the last in the sequence.
- *
- * @method
- * @returns {ExpressErrorHandler}
- * @public
- */
-module.exports.defaultErrorHandler = () => {
-    return ( error, request, response, next ) => {
-        const exception = exceptions.raise( error );
-        const payload = {
-            isSuccessful: false,
-            exception: exception.asJSON(),
-            message: localization.getLabel( exception.label, request.session?.language )
-        };
-
-        if ( exception.httpCode === exceptions.httpCode.C_404 ) {
-            logger.log( `Received request to an invalid route: "${ request.originalUrl }"`, logger.logSeverity.DEBUG, exception );
-
-            if ( isHtmxRequest( request ) ) {
-                response.set( "HX-Redirect", "/not-found" );
-                response.status( exceptions.httpCode.C_204 ).end();
-            } else if ( isAcceptingResponseType( request, "html" ) && request.method === "GET" ) {
-                response.redirect( exceptions.httpCode.C_303, "/not-found" );
-            } else {
-                response.status( exceptions.httpCode.C_404 ).send( payload );
-            }
-        } else {
-            logger.log( "Received request caused an exception.", logger.logSeverity.DEBUG, exception );
-            const status = resolveHttpCode( exception );
-
-            if ( isHtmxRequest( request ) ) {
-                response.set( {
-                    "HX-Reswap": "none",
-                    "HX-Retarget": "#ti-notifications",
-                    "HX-Trigger": JSON.stringify( {
-                        "ti:error": payload
-                    } )
-                } );
-                return response.status( status ).send( "" );
-            } else if ( isAcceptingResponseType( request, "html" ) && request.method === "GET" ) {
-                response.redirect( exceptions.httpCode.C_303, "/?error=" + encodeURIComponent( exception.code ) );
-            } else {
-                response.status( status ).send( payload );
-            }
-        }
-    };
-};
-
-/**
- * Handler for generating a nonce for CSP.
- *
- * @method
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.nonceGenerationHandler = () => {
-    return ( request, response, next ) => {
-        if ( request.method === "GET" || request.method === "HEAD" ) {
-            try {
-                const nonce = randomBytes( 16 ).toString( "base64" );
-                request.cspNonce = nonce;
-                request.nonce = request.nonce || nonce;
-                response.locals = response.locals || {};
-                response.locals.cspNonce = nonce;
-                response.locals.nonce = response.locals.nonce || nonce;
-                next();
-            } catch ( error ) {
-                next( error );
-            }
-        } else {
-            next();
-        }
-    };
-};
-
-/**
- * Handler for setting the Content-Security-Policy header.
- *
- * @method
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.cspHeaderHandler = () => {
-    return ( request, response, next ) => {
-        const nonce = response?.locals?.cspNonce;
-
-        // Build script-src directive:
-        const scriptSrc = [ "'strict-dynamic'", "'self'", "https:" ];
-        if ( nonce ) {
-            scriptSrc.push( `'nonce-${ nonce }'` );
-        }
-
-        // Build style-src-elem directive:
-        const styleSrcElem = [ "'self'", "https:" ];
-        if ( nonce ) {
-            styleSrcElem.push( `'nonce-${ nonce }'` );
-        }
-
-        // Build directives object:
-        const directives = {
-            defaultSrc: [ "'self'" ],
-            scriptSrc: scriptSrc,
-            styleSrc: [ "'self'", "https:" ],
-            styleSrcElem: styleSrcElem,
-            imgSrc: [ "'self'", "data:", "https:" ],
-            connectSrc: [ "'self'", "https:", "ws:", "wss:" ],
-            fontSrc: [ "'self'", "https:", "data:" ],
-            objectSrc: [ "'none'" ],
-            frameAncestors: [ "'self'" ]
-        };
-
-        const csp = helmet.contentSecurityPolicy( {
-            useDefaults: true,
-            directives
-        } );
-        return csp( request, response, next );
-    };
-};
-
-/**
- * Handler for requests that should be processed by the web application manager.
- *
- * @method
- * @param {TiWebServer} instance
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.webAppHandler = ( instance ) => {
-    return ( request, response, next ) => {
-        /**
-         * @param {TiException} exception
-         * @return {TiException}
-         */
-        const formatException = ( exception ) => {
-            exception.httpCode = resolveHttpCode( exception );
-            return exception;
-        };
-
-        if ( request.method === "GET" || request.method === "HEAD" ) {
-            if ( isAcceptingResponseType( request, "html" ) ) {
-                // HEAD: set headers only:
-                if ( request.method === "HEAD" ) {
-                    response.set( "Cache-Control", "no-store" );
-                    response.set( "Content-Type", "text/html; charset=utf-8" );
-                    response.status( exceptions.httpCode.C_200 ).end();
-                } else {
-                    // GET: load and render:
-                    const resLocals = ( response && response.locals ) || {};
-                    const isPartial = isHtmxRequest( request );
-                    const nonceHeader = request.get( "x-csp-nonce" ) || "";
-                    const nonce = isPartial ? nonceHeader : ( request.cspNonce || request.nonce || resLocals.cspNonce || resLocals.nonce );
-                    instance.webAppManager.assembleHtmlView( request.session, instance.staticContentPaths, request.path, {
-                        nonce: nonce,
-                        isPartial: isPartial,
-                        view: request.params.view,
-                        csrfToken: request.session?.csrfToken
-                    } ).then( ( html ) => {
-                        response.set( "Cache-Control", "no-store" );
-                        response.set( "Content-Type", "text/html; charset=utf-8" );
-                        response.status( exceptions.httpCode.C_200 ).send( html );
-                    } ).catch( ( error ) => {
-                        next( formatException( exceptions.raise( error ) ) );
-                    } );
-                }
-            } else if ( isAcceptingResponseType( request, "json" ) ) {
-                const requestContext = {
-                    query: request.query,
-                    params: request.params,
-                    headers: request.headers,
-                    url: request.originalUrl,
-                    method: request.method
-                };
-                instance.webAppManager.processDataRequest( request.session, request.params?.view, requestContext ).then( ( result ) => {
-                    response.set( "Cache-Control", "no-store" );
-                    response.set( "Content-Type", "application/json; charset=utf-8" );
-                    response.status( exceptions.httpCode.C_200 ).send( { isSuccessful: true, data: result } );
-                } ).catch( ( error ) => {
-                    next( formatException( exceptions.raise( error ) ) );
-                } );
-            } else {
-                next();
-            }
-        } else if ( request.method === "POST" ) {
-            instance.webAppManager.processServiceRequest( request.session, request.params?.service, request.body || {} ).then( ( result ) => {
-                response.set( "Cache-Control", "no-store" );
-                response.set( "Content-Type", "application/json; charset=utf-8" );
-                response.status( exceptions.httpCode.C_200 ).send( { isSuccessful: true, data: result } );
-            } ).catch( ( error ) => {
-                next( formatException( exceptions.raise( error ) ) );
-            } );
-        } else {
-            next();
-        }
-    };
-};
-
-/**
- * Validate Origin/Referer for non-GET/HEAD/OPTIONS requests.
- * Origin must match the current request origin (protocol + host[:port]).
- *
- * @method
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.originRefererValidationHandler = ( instance ) => {
-    return ( request, response, next ) => {
-        if ( request.method === "GET" || request.method === "HEAD" || request.method === "OPTIONS" ) {
-            next();
-        } else {
-            const providedOrigin = getRequestOrigin( request );
-            // If the browser didn't send Origin/Referer (normal for same-origin form POSTs), let CSRF middleware handle protection instead of blocking here:
-            if ( !providedOrigin ) {
-                next();
-            } else {
-                // Accept the origin the server reconstructs from the request, plus any explicitly trusted origins
-                // (TI_WEB_TRUSTED_ORIGINS / config.trustedOrigins). The trusted list is needed behind proxies that do
-                // not present the external host to the app (e.g. GitHub Codespaces port forwarding), where the browser
-                // Origin cannot be reconstructed from the forwarded headers.
-                const configured = ( instance && instance.serviceConfig && Array.isArray( instance.serviceConfig.trustedOrigins ) ) ? instance.serviceConfig.trustedOrigins : [];
-                const allowedOrigins = [ getBaseUrl( request ) ].concat( configured );
-                const normalizedProvided = String( providedOrigin ).trim().toLowerCase();
-                const isAllowed = allowedOrigins.some( ( origin ) => String( origin ).trim().toLowerCase() === normalizedProvided );
-                if ( isAllowed ) {
-                    next();
-                } else {
-                    logger.log( `Issue identified with origin/referer mismatch. Received '${ providedOrigin }'; expected one of [ ${ allowedOrigins.join( ", " ) } ].`, logger.logSeverity.WARNING );
-                    next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, null, exceptions.httpCode.C_403 ) );
-                }
-            }
-        }
-    };
-};
-
-/**
- * Ensure a per-session CSRF token and expose it to the client via a non-HTTPOnly cookie (double-submit token).
- * Set only on GET/HEAD to avoid caching/set-cookie noise on API calls.
- *
- * @method
- * @param {TiWebServer} instance
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.csrfInitHandler = ( instance ) => {
-    return ( request, response, next ) => {
-        if ( request.method !== "GET" && request.method !== "HEAD" ) {
-            next();
-        } else {
-            try {
-                const session = request.session;
-                if ( session ) {
-                    if ( !session.csrfToken ) {
-                        session.csrfToken = randomBytes( 32 ).toString( "base64url" );
-                    }
-                    // Expose the token via a readable cookie for front-end code (double-submit pattern):
-                    const xfProto = String( request.get( "x-forwarded-proto" ) || "" ).toLowerCase();
-                    const isSecure = ( request.secure === true ) || ( xfProto === "https" );
-                    const cookieOptions = {
-                        path: instance.serviceConfig.cookies.path,
-                        sameSite: instance.serviceConfig.cookies.sameSite,
-                        secure: isSecure,
-                        httpOnly: false
-                    };
-                    if ( cookieOptions.sameSite === "none" && !cookieOptions.secure ) {
-                        logger.log( "CSRF cookie may be blocked: SameSite=None requires Secure; ensure HTTPS or adjust config.", logger.logSeverity.WARNING );
-                    }
-                    if ( Number.isFinite( instance.serviceConfig.cookies.maxAge ) ) {
-                        cookieOptions.maxAge = instance.serviceConfig.cookies.maxAge;
-                    }
-                    response.cookie( "ti-xsrf-token", session.csrfToken, cookieOptions );
-                }
-                next();
-            } catch ( error ) {
-                next( exceptions.raise( error, null, exceptions.httpCode.C_500 ) );
-            }
-        }
-    };
-};
-
-/**
- * Require and validate the CSRF token on state-changing requests.
- * Accept from the header 'X-CSRF-Token' or 'X-XSRF-Token', or body/query 'csrfToken'.
- * Token must match the one in the current session set by {@link csrfInitHandler}.
- *
- * @method
- * @returns {ExpressHandler}
- * @public
- */
-module.exports.csrfProtectionHandler = () => {
-    return ( request, response, next ) => {
-        if ( request.method === "GET" || request.method === "HEAD" || request.method === "OPTIONS" ) {
-            next();
-        } else {
-            const expected = request.session && request.session.csrfToken;
-            if ( !expected ) {
-                next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_HEADERS, null, exceptions.httpCode.C_403 ) );
-            } else {
-                // Try to locate the CSRF token in the request:
-                const provided =
-                    request.get( "x-csrf-token" ) ||
-                    request.get( "x-xsrf-token" ) ||
-                    ( request.body && ( request.body.csrfToken || request.body._csrf ) ) ||
-                    ( request.query && ( request.query.csrfToken || request.query._csrf ) );
-                if ( !safeEquals( provided, expected ) ) {
-                    logger.log( "Issue identified with CSRF token validation fail.", logger.logSeverity.WARNING );
-                    next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_HEADERS, null, exceptions.httpCode.C_403 ) );
-                } else {
-                    next();
-                }
-            }
-        }
-    };
-};
+/*
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+const logger = require( "@ti-engine/core/logger" );
+const exceptions = require( "@ti-engine/core/exceptions" );
+const localization = require( "@ti-engine/core/localization" );
+const { randomBytes, timingSafeEqual } = require( "node:crypto" );
+const URL = require( "node:url" ).URL;
+const _ = require( "lodash" );
+const helmet = require( "helmet" );
+const cache = require( "@ti-engine/core/cache" );
+const authMethod = require( "#auth-manager" ).authMethod;
+const authorization = require( "#authorization" );
+
+/** @import { TiAuthMethod } from "#auth-manager" */
+/** @import TiWebServer from "#web-server" */
+
+/** @typedef {import("express").Request} ExpressRequest */
+/** @typedef {import("express").Response} ExpressResponse */
+
+/**
+ * Express middleware callback.
+ *
+ * @callback ExpressHandler
+ * @param {ExpressRequest} request
+ * @param {ExpressResponse} response
+ * @param {(error: Error|null) => void} next
+ * @returns {void}
+ */
+
+/**
+ * Express middleware callback with an error.
+ *
+ * @callback ExpressErrorHandler
+ * @param {Error} error
+ * @param {ExpressRequest} request
+ * @param {ExpressResponse} response
+ * @param {(error: Error|null) => void} next
+ * @returns {void}
+ */
+
+/**
+ * Default HTTP status for specific exception codes that do not carry an explicit `httpCode`.
+ *
+ * @type {Object<number, TiHttpCode>}
+ */
+const DEFAULT_HTTP_CODE_BY_EXCEPTION = {
+    [ exceptions.exceptionCode.E_WEB_INVALID_REQUEST_METHOD ]: exceptions.httpCode.C_405,
+    [ exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI ]: exceptions.httpCode.C_404,
+    [ exceptions.exceptionCode.E_WEB_INVALID_REQUEST_CONTENT_TYPE ]: exceptions.httpCode.C_415,
+    [ exceptions.exceptionCode.E_WEB_INVALID_REQUEST_CONTENT_LENGTH ]: exceptions.httpCode.C_413,
+    [ exceptions.exceptionCode.E_APP_RESOURCE_NOT_FOUND ]: exceptions.httpCode.C_404,
+    [ exceptions.exceptionCode.E_APP_RESOURCE_ALREADY_EXISTS ]: exceptions.httpCode.C_409
+};
+
+/**
+ * Resolves the HTTP status to report for an exception. An explicit `httpCode` on the exception always wins; otherwise
+ * the status is derived from the exception code so that client and application errors surface as 4xx — request and
+ * application-logic failures as `422 Unprocessable Content`, security as `403` — instead of being misreported as a
+ * generic `500`. Only genuine internal, communication, and unknown errors default to `500`.
+ *
+ * @method
+ * @param {TiException} exception
+ * @returns {TiHttpCode}
+ */
+const resolveHttpCode = ( exception ) => {
+    if ( exception.httpCode ) {
+        return exception.httpCode;
+    }
+    const code = exception.code;
+    if ( DEFAULT_HTTP_CODE_BY_EXCEPTION[ code ] ) {
+        return DEFAULT_HTTP_CODE_BY_EXCEPTION[ code ];
+    }
+    if ( code >= 2000 && code < 3000 ) {
+        return exceptions.httpCode.C_403; // security / authorization
+    }
+    if ( code >= 4000 && code < 6000 ) {
+        return exceptions.httpCode.C_422; // request validation + application logic → unprocessable content
+    }
+    return exceptions.httpCode.C_500; // general, communication, or unknown → internal server error
+};
+
+/**
+ * Used to assemble the current URL of a request.
+ *
+ * @method
+ * @param {ExpressRequest} request
+ * @returns {string}
+ * @private
+ */
+let getBaseUrl = ( request ) => {
+    const xfProtocol = String( request.get( "x-forwarded-proto" ) || "" ).toLowerCase();
+    const xfHost = request.get( "x-forwarded-host" );
+    const protocol = ( request.secure || xfProtocol === "https" ) ? "https" : "http";
+    const host = xfHost || request.get( "host" );
+    return `${ protocol }://${ host }`;
+};
+
+/**
+ * Timing-safe token comparison.
+ *
+ * @method
+ * @param {string} first
+ * @param {string} second
+ * @returns {boolean}
+ * @private
+ */
+let safeEquals = ( first, second ) => {
+    try {
+        const ba = Buffer.from( String( first || "" ) );
+        const bb = Buffer.from( String( second || "" ) );
+        return ( ba.length !== bb.length ) ? false : timingSafeEqual( ba, bb );
+    } catch {
+        return false;
+    }
+};
+
+/**
+ * Extract origin to validate. Prefer Origin, fallback to Referer origin.
+ *
+ * @method
+ * @param {ExpressRequest} request
+ * @returns {string|undefined} e.g., "https://example.com:8443"
+ * @private
+ */
+let getRequestOrigin = ( request ) => {
+    let result = undefined;
+    const rawOrigin = request.get( "origin" );
+    const origin = String( rawOrigin || "" ).trim().toLowerCase();
+
+    // Ignore explicit "null" or empty origins:
+    if ( origin && origin !== "null" ) {
+        result = rawOrigin;
+    } else {
+        const referer = request.get( "referer" );
+        if ( referer ) {
+            try {
+                const refererUrl = new URL( referer );
+                result = `${ refererUrl.protocol }//${ refererUrl.host }`;
+            } catch {
+                // do nothing here...
+            }
+        }
+    }
+
+    return result;
+};
+
+/**
+ * Used to regenerate the session and save it.
+ *
+ * @method
+ * @param {ExpressRequest} request
+ * @param {string} redirectTo
+ * @param {(session: TiSession) => TiSession} modifier
+ * @returns {Promise<string>}
+ * @private
+ */
+let regenerateAndSaveSession = ( request, redirectTo, modifier ) => {
+    return new Promise( ( resolve, reject ) => {
+        request.session.regenerate( ( error ) => {
+            if ( error ) {
+                reject( error );
+            } else {
+                try {
+                    if ( modifier && typeof modifier === "function" ) {
+                        request.session = modifier( request.session );
+                    }
+                } catch ( error ) {
+                    reject( error );
+                    return;
+                }
+                request.session.save( ( error ) => {
+                    if ( error ) {
+                        reject( error );
+                    } else {
+                        resolve( redirectTo );
+                    }
+                } )
+            }
+        } )
+    } );
+};
+
+/**
+ * Check if the request is an HTMX request.
+ *
+ * @method
+ * @param {ExpressRequest} request
+ * @returns {boolean}
+ * @private
+ */
+let isHtmxRequest = ( request ) => {
+    return String( request.get( "HX-Request" ) || "" ).toLowerCase() === "true";
+};
+
+/**
+ * Used to determine if the request accepts the specified response type.
+ *
+ * @method
+ * @param {ExpressRequest} request
+ * @param {string} type
+ * @return {boolean}
+ * @private
+ */
+let isAcceptingResponseType = ( request, type ) => {
+    const accept = String( request.get( "accept" ) || "" ).toLowerCase();
+    if ( accept ) {
+        return request.accepts( type ) === type;
+    } else {
+        return false;
+    }
+};
+
+/**
+ * Safely convert a URI to a string.
+ *
+ * @method
+ * @param {URL|string} uri
+ * @return {string}
+ * @private
+ */
+let convertUriToString = ( uri ) => {
+    return ( typeof uri === "string" ) ? uri : ( uri && typeof uri.toString === "function" ) ? uri.toString() : "/";
+};
+
+/**
+ * Handler for requests that are received while the web server is shutting down.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.onShutDownHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        if ( !instance.isShuttingDown ) {
+            next();
+        } else {
+            response.set( "Connection", "close" );
+            response.status( exceptions.httpCode.C_503 ).end();
+        }
+    };
+};
+
+/**
+ * Handler that verifies if the requested resource requires authentication or is freely accessible.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.resourceProtectionHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        if ( instance.isUnprotectedRoute( request.url ) || instance.verifySession( request.session ) ) {
+            next();
+        } else {
+            const redirectTo = "/";
+            if ( isHtmxRequest( request ) ) {
+                response.set( "HX-Redirect", redirectTo );
+                response.status( exceptions.httpCode.C_204 ).end();
+            } else if ( isAcceptingResponseType( request, "html" ) ) {
+                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
+            } else {
+                response.status( exceptions.httpCode.C_401 ).end();
+            }
+        }
+    };
+};
+
+/**
+ * Handler for server-side authentication.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.authenticationHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        const method = request.params.method;
+        if ( method === authMethod.LOCAL ) {
+            const username = String( ( request.body && request.body.username ) || "" ).trim();
+            const password = String( ( request.body && request.body.password ) || "" );
+            instance.authenticate( authMethod.LOCAL, { username: username, password: password } ).then( () => {
+                return instance.authorize( authMethod.LOCAL, new URL( request.originalUrl, getBaseUrl( request ) ), { username: username } );
+            } ).then( ( user ) => {
+                return regenerateAndSaveSession( request, "/", ( session ) => {
+                    session.user = user.asJSON();
+                    session.language = user.language || instance.serviceConfig.language;
+
+                    return authorization.applyAdminRole( instance.augmentSession( session, request ), instance.serviceConfig?.auth?.admins );
+                } );
+            } ).then( ( redirectTo ) => {
+                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
+            } ).catch( ( error ) => {
+                next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
+            } );
+        } else if ( method === authMethod.OPENID_GOOGLE || method === authMethod.OPENID_AZURE ) {
+            instance.authenticate( method, { baseUrl: getBaseUrl( request ) } ).then( ( result ) => {
+                return regenerateAndSaveSession( request, result.redirectTo, ( session ) => {
+                    session.oidc = { codeVerifier: result.codeVerifier, state: result.state, nonce: result.nonce };
+                    return session;
+                } );
+            } ).then( ( redirectTo ) => {
+                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
+            } ).catch( ( error ) => {
+                next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
+            } );
+        } else {
+            next();
+        }
+    };
+};
+
+/**
+ * Used to handle the callback from the Google OpenID authentication.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @param {TiAuthMethod} authMethod
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.authorizedOAuth2CallbackHandler = ( instance, authMethod ) => {
+    return ( request, response, next ) => {
+        const code = request.query.code;
+        const state = request.query.state;
+        const oidc = request.session.oidc || {};
+        if ( !code || !oidc?.codeVerifier ) {
+            response.status( exceptions.httpCode.C_400 ).end();
+        } else if ( oidc.state && state !== oidc.state ) {
+            response.status( exceptions.httpCode.C_400 ).end();
+        } else {
+            instance.authorize( authMethod, new URL( request.originalUrl, getBaseUrl( request ) ), oidc ).then( ( user ) => {
+                return regenerateAndSaveSession( request, "/", ( session ) => {
+                    session.user = user.asJSON();
+                    session.language = user.language || instance.serviceConfig.language;
+
+                    delete session.oidc;
+
+                    return authorization.applyAdminRole( instance.augmentSession( session, request ), instance.serviceConfig?.auth?.admins );
+                } );
+            } ).then( ( redirectTo ) => {
+                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
+            } ).catch( ( error ) => {
+                next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
+            } );
+        }
+    };
+};
+
+/**
+ * Handler for server-side logout.
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.logoutHandler = () => {
+    return ( request, response, next ) => {
+        const done = ( error ) => {
+            response.redirect( exceptions.httpCode.C_303, "/" );
+        };
+        if ( request.session ) {
+            request.session.destroy( done );
+        } else {
+            done();
+        }
+    };
+};
+
+/**
+ * Handler for a lightweight, unauthenticated health probe. Responds `200` whenever the web server is serving
+ * (a liveness signal for container/orchestrator probes), and reports the message-broker (Redis) connection state
+ * in the body so it can double as a readiness signal without hitting a user-facing route like the login page.
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.healthHandler = () => {
+    return ( request, response ) => {
+        const broker = ( cache.instance && cache.instance.isOperational === true ) ? "connected" : "disconnected";
+        response.status( exceptions.httpCode.C_200 ).send( {
+            isSuccessful: true,
+            data: {
+                status: "ok",
+                broker: broker,
+                uptime: Math.round( process.uptime() )
+            }
+        } );
+    };
+};
+
+/**
+ * Handler for retrieving authenticated user information.
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.userInformationHandler = () => {
+    return ( request, response, next ) => {
+        if ( request.session && request.session.user ) {
+            response.status( exceptions.httpCode.C_200 ).send( { isSuccessful: true, data: { user: _.cloneDeep( request.session.user ) } } );
+        } else {
+            next( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
+        }
+    };
+};
+
+/**
+ * Handler for redirecting HTTP requests to HTTPS. Also works behind proxies using X-Forwarded-Proto.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.httpRedirectHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        const xfProto = String( request.get ? request.get( "x-forwarded-proto" ) : ( request.headers[ "x-forwarded-proto" ] || "" ) ).toLowerCase();
+        const isSecure = request.secure === true || xfProto === "https";
+        if ( isSecure ) {
+            next();
+        } else {
+            if ( instance.isAllowedHost( request.hostname ) !== true ) {
+                response.status( exceptions.httpCode.C_404 ).end();
+            } else {
+                const host = request.get ? request.get( "host" ) : request.headers.host;
+                const location = new URL( request.url, "https://" + host );
+                response.set( "Cache-Control", "no-store" );
+                response.redirect( exceptions.httpCode.C_308, convertUriToString( location ) );
+            }
+        }
+    }
+};
+
+/**
+ * Handler for processing of API service calls.
+ * <br/>
+ * NOTE: This will send a new {@link ServiceCall} to the microservice network handled by the ti-engine.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.serviceCallHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        let serviceAddress = instance.getServiceAddress( request.params.version, request.params.name );
+        if ( !serviceAddress ) {
+            next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, null, exceptions.httpCode.C_404 ) );
+        } else {
+            request.setTimeout( instance.serviceConfig.api.requestTimeout );
+            instance.callService( serviceAddress, request.body || {}, {
+                authToken: request.sessionID,
+            } ).then( ( result ) => {
+                if ( result.isSuccessful !== true ) {
+                    next( exceptions.raise( result.exception || exceptions.exceptionCode.E_COM_SERVICE_EXEC_FAILED, null, result.exception?.httpCode || exceptions.httpCode.C_400 ) );
+                } else {
+                    response.status( exceptions.httpCode.C_200 ).send( result );
+                }
+            } ).catch( ( error ) => {
+                next( error );
+            } );
+        }
+    };
+};
+
+/**
+ * Handler to intercept and handle all remaining requests to invalid URLs.
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.invalidRouteHandler = () => {
+    return ( request, response, next ) => {
+        next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, null, exceptions.httpCode.C_404 ) );
+    };
+};
+
+/**
+ * Handler to intercept any errors that have not been resolved by previous middleware. Should be the last in the sequence.
+ *
+ * @method
+ * @returns {ExpressErrorHandler}
+ * @public
+ */
+module.exports.defaultErrorHandler = () => {
+    return ( error, request, response, next ) => {
+        const exception = exceptions.raise( error );
+        const payload = {
+            isSuccessful: false,
+            exception: exception.asJSON(),
+            message: localization.getLabel( exception.label, request.session?.language )
+        };
+
+        if ( exception.httpCode === exceptions.httpCode.C_404 ) {
+            logger.log( `Received request to an invalid route: "${ request.originalUrl }"`, logger.logSeverity.DEBUG, exception );
+
+            if ( isHtmxRequest( request ) ) {
+                response.set( "HX-Redirect", "/not-found" );
+                response.status( exceptions.httpCode.C_204 ).end();
+            } else if ( isAcceptingResponseType( request, "html" ) && request.method === "GET" ) {
+                response.redirect( exceptions.httpCode.C_303, "/not-found" );
+            } else {
+                response.status( exceptions.httpCode.C_404 ).send( payload );
+            }
+        } else {
+            logger.log( "Received request caused an exception.", logger.logSeverity.DEBUG, exception );
+            const status = resolveHttpCode( exception );
+
+            if ( isHtmxRequest( request ) ) {
+                response.set( {
+                    "HX-Reswap": "none",
+                    "HX-Retarget": "#ti-notifications",
+                    "HX-Trigger": JSON.stringify( {
+                        "ti:error": payload
+                    } )
+                } );
+                return response.status( status ).send( "" );
+            } else if ( isAcceptingResponseType( request, "html" ) && request.method === "GET" ) {
+                response.redirect( exceptions.httpCode.C_303, "/?error=" + encodeURIComponent( exception.code ) );
+            } else {
+                response.status( status ).send( payload );
+            }
+        }
+    };
+};
+
+/**
+ * Handler for generating a nonce for CSP.
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.nonceGenerationHandler = () => {
+    return ( request, response, next ) => {
+        if ( request.method === "GET" || request.method === "HEAD" ) {
+            try {
+                const nonce = randomBytes( 16 ).toString( "base64" );
+                request.cspNonce = nonce;
+                request.nonce = request.nonce || nonce;
+                response.locals = response.locals || {};
+                response.locals.cspNonce = nonce;
+                response.locals.nonce = response.locals.nonce || nonce;
+                next();
+            } catch ( error ) {
+                next( error );
+            }
+        } else {
+            next();
+        }
+    };
+};
+
+/**
+ * Handler for setting the Content-Security-Policy header.
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.cspHeaderHandler = () => {
+    return ( request, response, next ) => {
+        const nonce = response?.locals?.cspNonce;
+
+        // Build script-src directive:
+        const scriptSrc = [ "'strict-dynamic'", "'self'", "https:" ];
+        if ( nonce ) {
+            scriptSrc.push( `'nonce-${ nonce }'` );
+        }
+
+        // Build style-src-elem directive:
+        const styleSrcElem = [ "'self'", "https:" ];
+        if ( nonce ) {
+            styleSrcElem.push( `'nonce-${ nonce }'` );
+        }
+
+        // Build directives object:
+        const directives = {
+            defaultSrc: [ "'self'" ],
+            scriptSrc: scriptSrc,
+            styleSrc: [ "'self'", "https:" ],
+            styleSrcElem: styleSrcElem,
+            imgSrc: [ "'self'", "data:", "https:" ],
+            connectSrc: [ "'self'", "https:", "ws:", "wss:" ],
+            fontSrc: [ "'self'", "https:", "data:" ],
+            objectSrc: [ "'none'" ],
+            frameAncestors: [ "'self'" ]
+        };
+
+        const csp = helmet.contentSecurityPolicy( {
+            useDefaults: true,
+            directives
+        } );
+        return csp( request, response, next );
+    };
+};
+
+/**
+ * Handler for requests that should be processed by the web application manager.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.webAppHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        /**
+         * @param {TiException} exception
+         * @return {TiException}
+         */
+        const formatException = ( exception ) => {
+            exception.httpCode = resolveHttpCode( exception );
+            return exception;
+        };
+
+        if ( request.method === "GET" || request.method === "HEAD" ) {
+            if ( isAcceptingResponseType( request, "html" ) ) {
+                // HEAD: set headers only:
+                if ( request.method === "HEAD" ) {
+                    response.set( "Cache-Control", "no-store" );
+                    response.set( "Content-Type", "text/html; charset=utf-8" );
+                    response.status( exceptions.httpCode.C_200 ).end();
+                } else {
+                    // GET: load and render:
+                    const resLocals = ( response && response.locals ) || {};
+                    const isPartial = isHtmxRequest( request );
+                    const nonceHeader = request.get( "x-csp-nonce" ) || "";
+                    const nonce = isPartial ? nonceHeader : ( request.cspNonce || request.nonce || resLocals.cspNonce || resLocals.nonce );
+                    instance.webAppManager.assembleHtmlView( request.session, instance.staticContentPaths, request.path, {
+                        nonce: nonce,
+                        isPartial: isPartial,
+                        view: request.params.view,
+                        csrfToken: request.session?.csrfToken
+                    } ).then( ( html ) => {
+                        response.set( "Cache-Control", "no-store" );
+                        response.set( "Content-Type", "text/html; charset=utf-8" );
+                        response.status( exceptions.httpCode.C_200 ).send( html );
+                    } ).catch( ( error ) => {
+                        next( formatException( exceptions.raise( error ) ) );
+                    } );
+                }
+            } else if ( isAcceptingResponseType( request, "json" ) ) {
+                const requestContext = {
+                    query: request.query,
+                    params: request.params,
+                    headers: request.headers,
+                    url: request.originalUrl,
+                    method: request.method
+                };
+                instance.webAppManager.processDataRequest( request.session, request.params?.view, requestContext ).then( ( result ) => {
+                    response.set( "Cache-Control", "no-store" );
+                    response.set( "Content-Type", "application/json; charset=utf-8" );
+                    response.status( exceptions.httpCode.C_200 ).send( { isSuccessful: true, data: result } );
+                } ).catch( ( error ) => {
+                    next( formatException( exceptions.raise( error ) ) );
+                } );
+            } else {
+                next();
+            }
+        } else if ( request.method === "POST" ) {
+            instance.webAppManager.processServiceRequest( request.session, request.params?.service, request.body || {} ).then( ( result ) => {
+                response.set( "Cache-Control", "no-store" );
+                response.set( "Content-Type", "application/json; charset=utf-8" );
+                response.status( exceptions.httpCode.C_200 ).send( { isSuccessful: true, data: result } );
+            } ).catch( ( error ) => {
+                next( formatException( exceptions.raise( error ) ) );
+            } );
+        } else {
+            next();
+        }
+    };
+};
+
+/**
+ * Validate Origin/Referer for non-GET/HEAD/OPTIONS requests.
+ * Origin must match the current request origin (protocol + host[:port]).
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.originRefererValidationHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        if ( request.method === "GET" || request.method === "HEAD" || request.method === "OPTIONS" ) {
+            next();
+        } else {
+            const providedOrigin = getRequestOrigin( request );
+            // If the browser didn't send Origin/Referer (normal for same-origin form POSTs), let CSRF middleware handle protection instead of blocking here:
+            if ( !providedOrigin ) {
+                next();
+            } else {
+                // Accept the origin the server reconstructs from the request, plus any explicitly trusted origins
+                // (TI_WEB_TRUSTED_ORIGINS / config.trustedOrigins). The trusted list is needed behind proxies that do
+                // not present the external host to the app (e.g. GitHub Codespaces port forwarding), where the browser
+                // Origin cannot be reconstructed from the forwarded headers.
+                const configured = ( instance && instance.serviceConfig && Array.isArray( instance.serviceConfig.trustedOrigins ) ) ? instance.serviceConfig.trustedOrigins : [];
+                const allowedOrigins = [ getBaseUrl( request ) ].concat( configured );
+                const normalizedProvided = String( providedOrigin ).trim().toLowerCase();
+                const isAllowed = allowedOrigins.some( ( origin ) => String( origin ).trim().toLowerCase() === normalizedProvided );
+                if ( isAllowed ) {
+                    next();
+                } else {
+                    logger.log( `Issue identified with origin/referer mismatch. Received '${ providedOrigin }'; expected one of [ ${ allowedOrigins.join( ", " ) } ].`, logger.logSeverity.WARNING );
+                    next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, null, exceptions.httpCode.C_403 ) );
+                }
+            }
+        }
+    };
+};
+
+/**
+ * Ensure a per-session CSRF token and expose it to the client via a non-HTTPOnly cookie (double-submit token).
+ * Set only on GET/HEAD to avoid caching/set-cookie noise on API calls.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.csrfInitHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        if ( request.method !== "GET" && request.method !== "HEAD" ) {
+            next();
+        } else {
+            try {
+                const session = request.session;
+                if ( session ) {
+                    if ( !session.csrfToken ) {
+                        session.csrfToken = randomBytes( 32 ).toString( "base64url" );
+                    }
+                    // Expose the token via a readable cookie for front-end code (double-submit pattern):
+                    const xfProto = String( request.get( "x-forwarded-proto" ) || "" ).toLowerCase();
+                    const isSecure = ( request.secure === true ) || ( xfProto === "https" );
+                    const cookieOptions = {
+                        path: instance.serviceConfig.cookies.path,
+                        sameSite: instance.serviceConfig.cookies.sameSite,
+                        secure: isSecure,
+                        httpOnly: false
+                    };
+                    if ( cookieOptions.sameSite === "none" && !cookieOptions.secure ) {
+                        logger.log( "CSRF cookie may be blocked: SameSite=None requires Secure; ensure HTTPS or adjust config.", logger.logSeverity.WARNING );
+                    }
+                    if ( Number.isFinite( instance.serviceConfig.cookies.maxAge ) ) {
+                        cookieOptions.maxAge = instance.serviceConfig.cookies.maxAge;
+                    }
+                    response.cookie( "ti-xsrf-token", session.csrfToken, cookieOptions );
+                }
+                next();
+            } catch ( error ) {
+                next( exceptions.raise( error, null, exceptions.httpCode.C_500 ) );
+            }
+        }
+    };
+};
+
+/**
+ * Require and validate the CSRF token on state-changing requests.
+ * Accept from the header 'X-CSRF-Token' or 'X-XSRF-Token', or body/query 'csrfToken'.
+ * Token must match the one in the current session set by {@link csrfInitHandler}.
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.csrfProtectionHandler = () => {
+    return ( request, response, next ) => {
+        if ( request.method === "GET" || request.method === "HEAD" || request.method === "OPTIONS" ) {
+            next();
+        } else {
+            const expected = request.session && request.session.csrfToken;
+            if ( !expected ) {
+                next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_HEADERS, null, exceptions.httpCode.C_403 ) );
+            } else {
+                // Try to locate the CSRF token in the request:
+                const provided =
+                    request.get( "x-csrf-token" ) ||
+                    request.get( "x-xsrf-token" ) ||
+                    ( request.body && ( request.body.csrfToken || request.body._csrf ) ) ||
+                    ( request.query && ( request.query.csrfToken || request.query._csrf ) );
+                if ( !safeEquals( provided, expected ) ) {
+                    logger.log( "Issue identified with CSRF token validation fail.", logger.logSeverity.WARNING );
+                    next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_HEADERS, null, exceptions.httpCode.C_403 ) );
+                } else {
+                    next();
+                }
+            }
+        }
+    };
+};