@gov-cy/govcy-express-services 0.1.1

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@gov-cy/govcy-express-services",
+  "version": "0.1.1",
+  "description": "An Express-based system that dynamically renders services using @gov-cy/govcy-frontend-renderer and posts data to a submission API.",
+  "author": "DMRID - DSF Team",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "module": "./src/index.mjs",
+  "exports": {
+    "import": "./src/index.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "govcy",
+    "cyprus",
+    "unified design system",
+    "uds",
+    "dsf",
+    "digital service framework",
+    "forms",
+    "dynamic-rendering",
+    "service",
+    "renderer",
+    "frontend",
+    "express services",
+    "express",
+    "builder"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gov-cy/govcy-express-services.git"
+  },
+  "homepage": "https://github.com/gov-cy/govcy-express-services",
+  "scripts": {
+    "dev": "nodemon src/standalone.mjs",
+    "start": "node src/standalone.mjs",
+    "start:mock": "node tests/mocks/mockApiServer.mjs",
+    "test": "mocha --timeout 60000 tests/**/*.test.mjs --exit",
+    "test:report": "mocha --timeout 60000 --reporter mochawesome tests/**/*.test.mjs --exit",
+    "test:unit": "mocha --recursive tests/unit/**/*.test.mjs",
+    "test:integration": "mocha --recursive tests/integration/**/*.test.mjs",
+    "test:package": "mocha --recursive tests/package/**/*.test.mjs",
+    "test:functional": "mocha --timeout 30000 --recursive tests/functional/**/*.test.mjs",
+    "test:watch": "mocha --watch --timeout 60000 tests/**/*.test.mjs"
+  },
+  "dependencies": {
+    "@gov-cy/dsf-email-templates": "^2.1.0",
+    "@gov-cy/govcy-frontend-renderer": "^1.17.0",
+    "axios": "^1.9.0",
+    "cookie-parser": "^1.4.7",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "express-session": "^1.17.3",
+    "openid-client": "^6.3.4",
+    "puppeteer": "^24.6.0"
+  },
+  "devDependencies": {
+    "chai": "^5.2.0",
+    "chai-http": "^5.1.1",
+    "mocha": "^11.1.0",
+    "mochawesome": "^7.1.3",
+    "nodemon": "^3.0.2",
+    "pa11y": "^8.0.0",
+    "sinon": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/auth/cyLoginAuth.mjs

@@ -0,0 +1,123 @@
+import * as client from 'openid-client';
+import { getEnvVariable } from '../utils/govcyEnvVariables.mjs';
+import { logger } from "../utils/govcyLogger.mjs";
+
+
+// OpenID Configuration
+const issuerUrl = getEnvVariable('CYLOGIN_ISSUER_URL');
+const clientId = getEnvVariable('CYLOGIN_CLIENT_ID');
+const clientSecret = getEnvVariable('CYLOGIN_CLIENT_SECRET');
+const scope = getEnvVariable('CYLOGIN_SCOPE');
+const redirect_uri = getEnvVariable('CYLOGIN_REDIRECT_URI');
+
+// Discover OpenID settings with error handling and retry mechanism
+let config = null; // Changed: Initialize config as null
+async function initializeConfig() {
+    try {
+        config = await client.discovery(new URL(issuerUrl), clientId, clientSecret);
+        logger.info('OpenID configuration successfully discovered.');
+    } catch (error) {
+        logger.error('Failed to discover OpenID configuration:', error);
+        logger.debug('Failed to discover OpenID configuration:', issuerUrl, error)
+        config = null; // Ensure config remains null if discovery fails
+    }
+}
+
+// Initial attempt to load config
+await initializeConfig();
+
+// Retry mechanism to reinitialize config if it fails
+setInterval(async () => {
+    if (!config) {
+        logger.debug('Retrying OpenID configuration discovery...');
+        await initializeConfig();
+    }
+}, 60000); // Retry every 60 seconds (adjust as needed)
+
+/**
+ * Generate login URL
+ */
+export async function getLoginUrl(req) {
+    try {
+        if (!config) throw new Error('OpenID configuration is unavailable.');
+
+        let code_verifier = client.randomPKCECodeVerifier();  // Generate random PKCE per request
+        let code_challenge = await client.calculatePKCECodeChallenge(code_verifier); // Ensure `await` is here
+
+        let nonce = client.randomNonce();  // Generate per request 
+
+        // Store these in session
+        req.session.pkce = { code_verifier, nonce };
+
+        let parameters = {
+            redirect_uri,
+            scope,
+            code_challenge,
+            code_challenge_method: getEnvVariable('CYLOGIN_CODE_CHALLENGE_METHOD'),
+            nonce,
+            ui_locales: req.globalLang || 'el',  // Default to 'el' if req.globalLang is not set
+        };
+
+        return client.buildAuthorizationUrl(config, parameters).href;
+    } catch (error) {
+        throw new Error('Unable to generate login URL at this time.');
+    }
+}
+
+
+
+/**
+ * Handle authorization code and exchange it for tokens
+ */
+export async function handleCallback(req) {
+    try {
+        if (!config) throw new Error('OpenID configuration is unavailable.');
+
+        let currentUrl = new URL(`${req.protocol}://${req.get('host')}${req.originalUrl}`);
+
+        let { code_verifier, nonce } = req.session.pkce || {};  // Retrieve from session
+
+        let tokens = await client.authorizationCodeGrant(config, currentUrl, {
+            pkceCodeVerifier: code_verifier,  // Validate PKCE
+            expectedNonce: nonce,  // Validate nonce
+            idTokenExpected: true,
+        });
+
+        delete req.session.pkce;  // Clear PKCE data after successful login
+
+        logger.debug('Token Endpoint Response', tokens);
+
+        let { access_token } = tokens;
+        let claims = tokens.claims();
+        logger.debug('ID Token Claims', claims);
+
+        let { sub } = claims;
+        let userInfo = await client.fetchUserInfo(config, access_token, sub);
+        logger.debug('UserInfo Response', userInfo);
+
+        return { tokens, claims, userInfo };
+    } catch (error) {
+        logger.debug('Error processing login callback:', error);
+        throw new Error('Unable to process login callback at this time.');
+    }
+}
+
+
+/**
+ * Logout and build end session URL
+ */
+export function getLogoutUrl(id_token_hint = '') {
+    try {
+        if (!config) throw new Error('OpenID configuration is unavailable.');
+
+        return client.buildEndSessionUrl(config, {
+            post_logout_redirect_uri: getEnvVariable('CYLOGIN_POST_LOGOUR_REIDRECT_URI'),
+            id_token_hint, // Send ID token if available
+        }).href;
+    } catch (error) {
+        throw new Error('Unable to generate logout URL at this time.');
+    }
+}
+
+// Export config if needed elsewhere
+export { config };

package/src/index.mjs

@@ -0,0 +1,188 @@
+import express from 'express';
+import session from 'express-session';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import cookieParser from 'cookie-parser'; // Required to read cookies
+import https from 'https';
+import { requestTimer } from './middleware/govcyRequestTimer.mjs';
+import { noCacheAndSecurityHeaders } from "./middleware/govcyHeadersControl.mjs";
+import { renderGovcyPage } from "./middleware/govcyPageRender.mjs";
+import { govcyPageHandler } from './middleware/govcyPageHandler.mjs';
+import { govcyPDFRender } from './middleware/govcyPDFRender.mjs';
+import { govcyFormsPostHandler } from './middleware/govcyFormsPostHandler.mjs';
+import { govcyReviewPostHandler } from './middleware/govcyReviewPostHandler.mjs';
+import { govcyReviewPageHandler } from './middleware/govcyReviewPageHandler.mjs';
+import { govcySuccessPageHandler } from './middleware/govcySuccessPageHandler.mjs';
+import { requestLogger } from './middleware/govcyLogger.mjs';
+import { govcyCsrfMiddleware } from './middleware/govcyCsrf.mjs';
+import { govcySessionData } from './middleware/govcySessionData.mjs';
+import { govcyHttpErrorHandler } from './middleware/govcyHttpErrorHandler.mjs';
+import { govcyLanguageMiddleware } from './middleware/govcyLanguageMiddleware.mjs';
+import { requireAuth, naturalPersonPolicy,handleLoginRoute, handleSigninOidc, handleLogout } from './middleware/cyLoginAuth.mjs';
+import { serviceConfigDataMiddleware } from './middleware/govcyConfigSiteData.mjs';
+import { govcyManifestHandler } from './middleware/govcyManifestHandler.mjs';
+import { govcyRoutePageHandler } from './middleware/govcyRoutePageHandler.mjs';
+import { govcyServiceEligibilityHandler } from './middleware/govcyServiceEligibilityHandler.mjs';
+import { isProdOrStaging , getEnvVariable, whatsIsMyEnvironment } from './utils/govcyEnvVariables.mjs';
+import { logger } from "./utils/govcyLogger.mjs";
+
+import fs from 'fs';
+
+export default function initializeGovCyExpressService(){
+  const app = express();
+  
+  // Get the directory name of the current module
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  // Construct the absolute path to local certificate files
+  logger.debug('Current directory:', __dirname);
+  logger.debug('Current working directory:', process.cwd());
+  const  certPath = join(process.cwd(),'server');
+  
+  // Determine environment settings
+  const ENV = whatsIsMyEnvironment();
+  // Set port
+  const PORT = getEnvVariable('PORT') || 44319;
+  // Use HTTPS if isProdOrStaging or certificate files exist
+  const USE_HTTPS = isProdOrStaging() || (fs.existsSync(certPath + '.cert') && fs.existsSync(certPath + '.key'));
+  
+  
+  // Middleware
+  // Enable parsing of URL-encoded data (data from HTML form submissions with application/x-www-form-urlencoded encoding)
+  app.use(express.urlencoded({ extended: true }));
+  // Enable parsing of JSON request bodies
+  app.use(express.json());
+  // Enable session management
+  app.use(
+    session({
+      secret: getEnvVariable('SESSION_SECRET'), // Use environment variable or fallback for dev. To generate a secret, run: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'));"`
+      resave: false,  // Prevents unnecessary session updates
+      saveUninitialized: false, // Don't save empty sessions
+      cookie: { 
+        secure: USE_HTTPS, // Secure cookies only if HTTPS is used
+        httpOnly: true,   // Prevents XSS attacks
+        maxAge: 1800000,  // Session expires after 30 mins
+        sameSite:  'lax' // Prevents CSRF by default
+      } 
+    })
+  );
+  // Enable cookie parsing
+  app.use(cookieParser()); 
+  // Apply language middleware
+  app.use(govcyLanguageMiddleware); 
+  // Add request timing middleware
+  app.use(requestTimer);
+  // add csrf middleware
+  app.use(govcyCsrfMiddleware);
+  // Enable security headers
+  app.use(noCacheAndSecurityHeaders);
+  
+  // 🔒 cyLogin ----------------------------------------
+  
+  // 🔒 -- ROUTE: Redirect to Login
+  app.get('/login', handleLoginRoute() );
+  
+  // 🔒 -- ROUTE: Handle login Callback
+  app.get('/signin-oidc', handleSigninOidc() );
+  
+  // 🔒 -- ROUTE: Handle Logout
+  app.get('/logout', handleLogout() );
+  
+  //----------------------------------------------------------------------
+  
+  
+  // 🛠️ Debugging routes -----------------------------------------------------
+  // 🙍🏻‍♂️ -- ROUTE: Debugging route Protected Route
+  if (!isProdOrStaging()) {
+    app.get('/user', requireAuth, naturalPersonPolicy, (req, res) => {
+      res.send(`
+        User name: ${req.session.user.name}
+        <br> Sub: ${req.session.user.sub}
+        <br> Profile type: ${req.session.user.profile_type}
+        <br> Clinent ip: ${req.session.user.client_ip}
+        <br> Unique Identifier: ${req.session.user.unique_identifier}
+        <br> Email: ${req.session.user.email}
+        <br> Id Token: ${req.session.user.id_token}
+        <br> Access Token: ${req.session.user.access_token}
+        `);
+    });
+  }
+  //----------------------------------------------------------------------
+  
+  
+  // ✅ Ensures session structure exists
+  app.use(govcySessionData);  
+  // add logger middleware
+  app.use(requestLogger);
+  
+  // Construct the absolute path to the public directory
+  const publicPath = join(__dirname, 'public');
+  // 🌐 -- ROUTE: Serve static files in the public directory. Route for `/js/`
+  app.use(express.static(publicPath));
+  
+  // 🏡 -- ROUTE: handle the route `/`
+   app.get('/', govcyRoutePageHandler);
+
+  // 📝 -- ROUTE: Serve manifest.json dynamically for each site
+  app.get('/:siteId/manifest.json', serviceConfigDataMiddleware, govcyManifestHandler());
+  
+  // 🏠 -- ROUTE: Handle route with only siteId (/:siteId or /:siteId/)
+  app.get('/:siteId', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(true),govcyPageHandler(), renderGovcyPage());
+  
+  // 👀 -- ROUTE: Add Review Page Route (BEFORE the dynamic route)
+  app.get('/:siteId/review',serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(), govcyReviewPageHandler(), renderGovcyPage());
+  
+  // ✅📄 -- ROUTE: Add Success PDF Route (BEFORE the dynamic route)
+  app.get('/:siteId/success/pdf',serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(), govcySuccessPageHandler(true), govcyPDFRender());
+  
+  // ✅ -- ROUTE: Add Success Page Route (BEFORE the dynamic route)
+  app.get('/:siteId/success',serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(), govcySuccessPageHandler(), renderGovcyPage());
+  
+  // 📝 -- ROUTE: Dynamic route to render pages based on siteId and pageUrl, using govcyPageHandler middleware
+  app.get('/:siteId/:pageUrl', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(true), govcyPageHandler(), renderGovcyPage());
+  
+  // 📥 -- ROUTE: Handle POST requests for review page
+  app.post('/:siteId/review', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(), govcyReviewPostHandler());
+  
+  // 👀📥 -- ROUTE: Handle POST requests (Form Submissions) based on siteId and pageUrl, using govcyFormsPostHandler middleware
+  app.post('/:siteId/:pageUrl', serviceConfigDataMiddleware, requireAuth, naturalPersonPolicy, govcyServiceEligibilityHandler(true), govcyFormsPostHandler());
+  
+  
+  // post for /:siteId/review
+  
+  // 🔹 Catch 404 errors (must be after all routes)
+  app.use((req, res, next) => {
+    next({ status: 404, message: "Page not found" });
+  });
+  
+  // 🔹 Centralized error handling (must be the LAST middleware)
+  app.use(govcyHttpErrorHandler);
+  
+  let server = null;
+
+  return {
+    app,
+    startServer: () => {
+      // Start Server
+      if (USE_HTTPS) {
+        const options = {
+          key: fs.readFileSync(certPath + '.key'),
+          cert: fs.readFileSync(certPath + '.cert'),
+        };
+        server = https.createServer(options, app).listen(PORT, () => {
+          logger.info(`🔒 Server running at https://localhost:${PORT} (${ENV})`);
+        });
+      } else {
+        server = app.listen(PORT, () => {
+          logger.info(`⚡ Server running at http://localhost:${PORT} (${ENV})`);
+        });
+      }
+    }, 
+    stopServer: () => {
+      if (server) {
+        server.close(() => {
+          logger.info('Server stopped');
+        });
+      }
+    }
+  };
+}

package/src/middleware/cyLoginAuth.mjs

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview This module provides middleware functions for authentication and authorization in an Express application.
+ * It includes functions to check if a user is logged in, handle login and logout routes, and enforce natural person policy.
+ * 
+ * @module cyLoginAuth
+ */
+import { getLoginUrl, handleCallback, getLogoutUrl } from '../auth/cyLoginAuth.mjs';
+import { logger } from "../utils/govcyLogger.mjs";
+import { handleMiddlewareError } from "../utils/govcyUtils.mjs";
+
+/**
+ * Middleware to check if the user is authenticated. If not, redirect to the login page.
+ * 
+ * @param {object} req The request object
+ * @param {object} res The response object
+ * @param {object} next The next middleware function 
+ */
+export function requireAuth(req, res, next) {
+    if (!req.session.user) {
+        // Store the original URL before redirecting to login
+        req.session.redirectAfterLogin = req.originalUrl;
+        return res.redirect('/login');
+    }
+    next();
+}
+
+/**
+ * Middleware to enforce natural person policy. If the user is not a natural person, return a 403 error.
+ * 
+ * @param {object} req The request object
+ * @param {object} res The response object
+ * @param {object} next The next middleware function
+ */
+export function naturalPersonPolicy(req, res, next) {
+    // // allow only natural persons with approved profiles
+    // if (req.session.user.profile_type == 'Individual' && req.session.user.unique_identifier) {
+    //     next();
+    // } else {
+    //     return handleMiddlewareError("🚨 Access Denied: natural person policy not met.", 403, next);
+    // }
+    // https://dev.azure.com/cyprus-gov-cds/Documentation/_wiki/wikis/Documentation/42/For-Cyprus-Natural-or-Legal-person
+    const { profile_type, unique_identifier } = req.session.user || {};
+     // Allow only natural persons with approved profiles
+     if (profile_type === 'Individual' && unique_identifier) {
+        
+        // Validate Cypriot Citizen (starts with "00" and is 10 characters long)
+        if (unique_identifier.startsWith('00') && unique_identifier.length === 10) {
+            return next();
+        }
+
+        // Validate Foreigner with ARN (starts with "05" and is 10 characters long)
+        if (unique_identifier.startsWith('05') && unique_identifier.length === 10) {
+            return next();
+        }
+    }
+
+    // Deny access if validation fails
+    return handleMiddlewareError("🚨 Access Denied: natural person policy not met.", 403, next);
+}
+
+/**
+ * Middleware to handle the login route. Redirects the user to the login URL.
+ * 
+ * @param {object} req The request object
+ * @param {object} res The response object
+ * @param {object} next The next middleware function
+ */
+export function handleLoginRoute() {
+    return async (req, res, next) => {
+        try {
+            let loginUrl = await getLoginUrl(req);
+            res.redirect(loginUrl);
+        } catch (error) {
+            next(error); // Pass any errors to Express error handler
+        }
+    };
+}
+
+/**
+ * Middleware to handle the sign-in callback from the authentication provider.
+ * 
+ * @param {object} req The request object
+ * @param {object} res The response object
+ * @param {object} next The next middleware function
+ */
+export function handleSigninOidc() {
+    return async (req, res, next) => {
+        try {
+            const { tokens, claims, userInfo } = await handleCallback(req);
+            // Store user information in session
+            req.session.user = {
+                ...userInfo,
+                id_token: tokens.id_token,
+                access_token: tokens.access_token,
+                refresh_token: tokens.refresh_token || null,
+            };
+
+            // Redirect to the stored URL after login or fallback to '/'
+            const redirectUrl = req.session.redirectAfterLogin || '/';
+            // Clean up session for redirect after login
+            delete req.session.redirectAfterLogin; 
+            // Redirect to the stored URL
+            res.redirect(redirectUrl);
+        } catch (error) {
+            logger.debug('Token exchange failed:', error,req);
+            res.status(500).send('Authentication failed');
+        }
+    }
+}
+
+/**
+ * Middleware to handle the logout route. Destroys the session and redirects the user to the logout URL.
+ * 
+ * @param {object} req The request object
+ * @param {object} res The response object
+ * @param {object} next The next middleware function
+ */
+export function handleLogout() {
+    return (req, res, next) => {
+        if (!req.session.user) {
+            return res.redirect('/'); // Redirect if not logged in
+        }
+
+        const id_token_hint = req.session.user.id_token; // Retrieve ID token
+
+        req.session.destroy(() => {
+            const logoutUrl = getLogoutUrl(id_token_hint);
+            res.redirect(logoutUrl);
+        });
+    };
+}

package/src/middleware/govcyConfigSiteData.mjs

@@ -0,0 +1,38 @@
+import { getServiceConfigData } from "../utils/govcyLoadConfigData.mjs";
+
+/**
+ * Middleware to load service configuration data based on siteId and language.
+ * This middleware fetches the service data and attaches it to the request object.
+ *  
+ * @param {object} req The request object
+ * @param {object} res The response object
+ * @param {object} next The next middleware function
+ */
+export async function serviceConfigDataMiddleware(req, res, next) {
+    try {
+        const { siteId } = req.params;
+        req.serviceData = await getServiceConfigData(siteId, req.globalLang);
+
+        // Store current service 
+        if (siteId) {
+            //create a cookie for current service
+            res.cookie('cs', siteId, {
+                maxAge: 365 * 24 * 60 * 60 * 1000, // 1 year
+                httpOnly: true,
+                sameSite: 'lax'
+            });
+            // req.session.homeRedirectPage = req.serviceData.site.homeRedirectPage;
+        } else {
+            // delete the cookie if id is not available
+            res.clearCookie('cs', {
+                httpOnly: true,
+                sameSite: 'lax'
+            });
+        }
+
+        next();
+    } catch (error) {
+        return next(error)
+    }
+
+}

package/src/middleware/govcyCsrf.mjs

@@ -0,0 +1,36 @@
+
+import { handleMiddlewareError } from "../utils/govcyUtils.mjs";
+/**
+ * Middleware to handle CSRF token generation and validation.
+ * 
+ * @param {object} req The request object
+ * @param {object} res The response object
+ * @param {object} next The next middleware function
+ */
+export function govcyCsrfMiddleware(req, res, next) {
+  // Generate token on first request per session
+  if (!req.session.csrfToken) {
+    req.session.csrfToken = generateRandonToken();
+  }
+
+  req.csrfToken = () => req.session.csrfToken;
+
+  // Check token on POST requests
+  if (req.method === 'POST') {
+    const tokenFromBody = req.body._csrf;
+    if (!tokenFromBody || tokenFromBody !== req.session.csrfToken) {
+      return handleMiddlewareError("🚨 Invalid CSRF token", 403, next); // Pass error to govcyHttpErrorHandler
+    }
+  }
+
+  next();
+}
+
+/**
+ * Generate a random token string.
+ * 
+ * @returns {string} A random token string
+ */
+export function generateRandonToken() {
+  return [...Array(32)].map(() => Math.random().toString(36)[2]).join('');
+}

package/src/middleware/govcyFormsPostHandler.mjs

@@ -0,0 +1,83 @@
+import { getPageConfigData } from "../utils/govcyLoadConfigData.mjs";
+import * as govcyResources from "../resources/govcyResources.mjs";
+import { validateFormElements  } from "../utils/govcyValidator.mjs"; // Import your validator
+import * as dataLayer from "../utils/govcyDataLayer.mjs";
+import { logger } from "../utils/govcyLogger.mjs";
+import { handleMiddlewareError } from "../utils/govcyUtils.mjs";
+import { getFormData } from "../utils/govcyFormHandling.mjs"
+
+/**
+ * Middleware to handle page form submission
+ */
+export function govcyFormsPostHandler() {
+    return (req, res, next) => {
+        try {
+            const { siteId, pageUrl } = req.params;
+    
+            // ⤵️ Load service and check if it exists
+            const service = req.serviceData;
+    
+            // ⤵️ Find the current page based on the URL
+            const page = getPageConfigData(service, pageUrl);
+    
+            // 🔍 Find the form definition inside `pageTemplate.sections`
+            let formElement = null;
+            for (const section of page.pageTemplate.sections) {
+                formElement = section.elements.find(el => el.element === "form");
+                if (formElement) break;
+            }
+    
+            if (!formElement) {
+                return handleMiddlewareError("🚨 Form definition not found.", 500, next);
+            }
+    
+            // const formData = req.body; // Submitted data
+            const formData = getFormData(formElement.params.elements, req.body); // Submitted data
+
+            // ☑️ Start validation from top-level form elements
+            const validationErrors = validateFormElements(formElement.params.elements, formData);
+    
+            // ❌ Return validation errors if any exist
+            if (Object.keys(validationErrors).length > 0) {
+                logger.debug("🚨 Validation errors:", validationErrors, req);
+                logger.info("🚨 Validation errors on:", req.originalUrl);
+                // store the validation errors
+                dataLayer.storePageValidationErrors(req.session, siteId, pageUrl, validationErrors, formData);
+                //redirect to the same page with error summary
+                return res.redirect(govcyResources.constructErrorSummaryUrl(req.originalUrl));
+            }
+    
+            //⤴️ Store validated form data in session
+            dataLayer.storePageData(req.session, siteId, pageUrl, formData);
+
+            
+            logger.debug("✅ Form submitted successfully:", dataLayer.getPageData(req.session, siteId, pageUrl), req);
+            logger.info("✅ Form submitted successfully:", req.originalUrl);
+            
+            // 🔍 Determine next page (if applicable)
+            let nextPage = null;
+            for (const section of page.pageTemplate.sections) {
+                const form = section.elements.find(el => el.element === "form");
+                if (form) {
+                    //handle review route
+                    if (req.query.route === "review") {
+                        nextPage = govcyResources.constructPageUrl(siteId, "review");
+                    } else {
+                        nextPage = page.pageData.nextPage;
+                        //nextPage = form.params.elements.find(el => el.element === "button" && el.params?.prototypeNavigate)?.params.prototypeNavigate;
+                    }
+                }
+            }
+            
+            // ➡️ Redirect to the next page if defined, otherwise return success
+            if (nextPage) {
+                logger.debug("🔄 Redirecting to next page:", nextPage, req);
+                // 🛠 Fix relative paths
+                return res.redirect(govcyResources.constructPageUrl(siteId, `${nextPage.split('/').pop()}`));
+            }
+            res.json({ success: true, message: "Form submitted successfully" });
+        } catch (error) {
+            return next(error); // Pass error to govcyHttpErrorHandler
+        }
+    };
+}