@ti-engine/web-framework 1.13.1

package/components/admin-config-handlers.js

@@ -0,0 +1,92 @@
+/*
+ * 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-2026 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/>.
+*/
+
+/**
+ * Express handler factories for the admin configuration-management API. Each factory takes the {@link ConfigService}
+ * to delegate to (injected so the handlers are unit-testable), and returns an Express middleware that responds in the
+ * framework's convention — `{ isSuccessful: true, data }` on success — forwarding errors to the error middleware.
+ * Validation failures come back as `data` (`{ ok:false, errors }`) so the UI can render field-level messages; a
+ * version conflict maps to `409` and an unknown editor/document/change-set to `404`. These routes are gated by the
+ * `requireAdmin` guard and inherit the server's global auth + CSRF middleware.
+ *
+ * @module admin-config-handlers
+ */
+
+const exceptions = require( "@ti-engine/core/exceptions" );
+
+function sendData( response, data ) {
+    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: data } );
+}
+
+function forward( next, error ) {
+    const reason = error && error.data && error.data.reason;
+    const raised = exceptions.raise( error );
+    if ( reason === "version-conflict" ) {
+        raised.httpCode = exceptions.httpCode.C_409;
+    } else if ( reason === "unknown-editor" || reason === "unknown-changeset" || reason === "unknown-config" ) {
+        raised.httpCode = exceptions.httpCode.C_404;
+    }
+    next( raised );
+}
+
+function adminID( request ) {
+    return ( request.session && request.session.user ) ? request.session.user.userID : undefined;
+}
+
+/**
+ * @param {ConfigService} service
+ * @returns {ExpressHandler}
+ */
+module.exports.listEditors = ( service ) => ( request, response, next ) => {
+    try {
+        sendData( response, service.listEditors() );
+    } catch ( error ) {
+        forward( next, error );
+    }
+};
+
+module.exports.composeView = ( service ) => ( request, response, next ) => {
+    service.composeView( request.params.editorKey ).then( ( view ) => sendData( response, view ) ).catch( ( error ) => forward( next, error ) );
+};
+
+module.exports.saveEditorEdit = ( service ) => ( request, response, next ) => {
+    const body = request.body || {};
+    service.saveEditorEdit( request.params.editorKey, body.edited, { adminID: adminID( request ), note: body.note }, body.expectedVersions ).then( ( result ) => sendData( response, result ) ).catch( ( error ) => forward( next, error ) );
+};
+
+module.exports.getCurrent = ( service ) => ( request, response, next ) => {
+    service.getCurrent( request.params.configKey ).then( ( current ) => sendData( response, current ) ).catch( ( error ) => forward( next, error ) );
+};
+
+module.exports.getHistory = ( service ) => ( request, response, next ) => {
+    service.getHistory( request.params.configKey ).then( ( history ) => sendData( response, history ) ).catch( ( error ) => forward( next, error ) );
+};
+
+module.exports.listChanges = ( service ) => ( request, response, next ) => {
+    service.listChanges().then( ( changes ) => sendData( response, changes ) ).catch( ( error ) => forward( next, error ) );
+};
+
+module.exports.getChange = ( service ) => ( request, response, next ) => {
+    service.getChange( request.params.changeSetID ).then( ( change ) => sendData( response, change ) ).catch( ( error ) => forward( next, error ) );
+};
+
+module.exports.restoreChangeSet = ( service ) => ( request, response, next ) => {
+    const body = request.body || {};
+    service.restoreChangeSet( request.params.changeSetID, { adminID: adminID( request ), note: body.note } ).then( ( result ) => sendData( response, result ) ).catch( ( error ) => forward( next, error ) );
+};
+
+module.exports.exportBundle = ( service ) => ( request, response, next ) => {
+    service.exportBundle( { adminID: adminID( request ) } ).then( ( bundle ) => {
+        response.set( "Cache-Control", "no-store" );
+        response.set( "Content-Type", "application/json; charset=utf-8" );
+        response.set( "Content-Disposition", "attachment; filename=\"config-export.json\"" );
+        response.status( exceptions.httpCode.C_200 ).send( JSON.stringify( bundle, null, 2 ) );
+    } ).catch( ( error ) => forward( next, error ) );
+};

package/components/auth-manager.js

@@ -0,0 +1,344 @@
+/*
+ * 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 tools = require( "@ti-engine/core/tools" );
+const logger = require( "@ti-engine/core/logger" );
+const exceptions = require( "@ti-engine/core/exceptions" );
+const { randomBytes } = require( "node:crypto" );
+const openidClient = require( "openid-client" );
+const User = require( "#user" );
+
+/**
+ * Enum for specifying the authentication method.
+ *
+ * @readonly
+ * @enum {string}
+ * @typedef {string} TiAuthMethod
+ */
+const authMethodEnum = tools.enum( {
+    LOCAL: [ "local", "local", "Local authentication with username and password." ],
+    OPENID_AZURE: [ "openid-azure", "openid-azure", "Authentication to Azure Cloud using OpenID Connect." ],
+    OPENID_GOOGLE: [ "openid-google", "openid-google", "Authentication to Google Cloud using OpenID Connect." ]
+} );
+
+/**
+ * Enum for specifying the OpenID Connect client authentication method.
+ *
+ * @readonly
+ * @enum {string}
+ * @typedef {string} TiTokenEndpointAuthMethod
+ */
+const openIDTokenEndpointAuthMethodEnum = tools.enum( {
+    BASIC: [ "client_secret_basic", "basic", "Uses 'client_secret_basic' token endpoint authentication method." ],
+    POST: [ "client_secret_post", "post", "Uses 'client_secret_post' token endpoint authentication method." ],
+    NONE: [ "none", "none", "Uses 'none' token endpoint authentication method." ]
+} );
+
+/**
+ * The AuthManager class is used to manage authentication and authorization.
+ *
+ * @class AuthManager
+ * @public
+ */
+class AuthManager {
+
+    #initialized = false;
+    /** @type {SettingsAuth} */
+    #authSettings = {
+        enabledMethods: [],
+        local: {
+            username: undefined,
+            password: undefined
+        },
+        oauth2: {}
+    };
+    #clientConfigOAuth2Google = {};
+    #clientConfigOAuth2Azure = {};
+
+    /**
+     * @constructor
+     * @param {SettingsAuth} settings
+     */
+    constructor( settings ) {
+        if ( settings ) {
+            this.#authSettings = settings;
+        }
+
+        // Set up local authentication configuration:
+        if ( this.isAuthEnabled( authMethodEnum.LOCAL ) ) {
+            // TODO: For testing purposes only! Implement real local auth later!
+            this.#authSettings.local = this.#authSettings.local || {};
+            this.#authSettings.local.username = "admin";
+            this.#authSettings.local.password = "admin";
+        }
+
+        // Set up OAuth2 configuration:
+        this.#authSettings.oauth2 = this.#authSettings.oauth2 || {};
+        if ( this.isAuthEnabled( authMethodEnum.OPENID_GOOGLE ) ) {
+            this.#authSettings.oauth2.google = this.#authSettings.oauth2.google || {};
+            this.#authSettings.oauth2.google.clientID = process.env.TI_GCLOUD_AUTH_CLIENT_ID || this.#authSettings.oauth2.google.clientID;
+            this.#authSettings.oauth2.google.clientSecret = process.env.TI_GCLOUD_AUTH_CLIENT_SECRET || this.#authSettings.oauth2.google.clientSecret;
+            this.#authSettings.oauth2.google.callbackUrl = process.env.TI_GCLOUD_AUTH_CALLBACK_URL || this.#authSettings.oauth2.google.callbackUrl;
+            this.#authSettings.oauth2.google.discoveryUrl = process.env.TI_GCLOUD_AUTH_DISCOVERY_URL || this.#authSettings.oauth2.google.discoveryUrl;
+        }
+        if ( this.isAuthEnabled( authMethodEnum.OPENID_AZURE ) ) {
+            this.#authSettings.oauth2.azure = this.#authSettings.oauth2.azure || {};
+            this.#authSettings.oauth2.azure.clientID = process.env.TI_AZURE_AUTH_CLIENT_ID || this.#authSettings.oauth2.azure.clientID;
+            this.#authSettings.oauth2.azure.clientSecret = process.env.TI_AZURE_AUTH_CLIENT_SECRET || this.#authSettings.oauth2.azure.clientSecret;
+            this.#authSettings.oauth2.azure.callbackUrl = process.env.TI_AZURE_AUTH_CALLBACK_URL || this.#authSettings.oauth2.azure.callbackUrl;
+            this.#authSettings.oauth2.azure.discoveryUrl = process.env.TI_AZURE_AUTH_DISCOVERY_URL || this.#authSettings.oauth2.azure.discoveryUrl;
+        }
+    }
+
+    /* Public interface */
+
+    /**
+     * Used to initialize the authentication manager.
+     *
+     * @method
+     * @returns {Promise}
+     * @public
+     */
+    initialize() {
+        let promises = [];
+        if ( this.isAuthEnabled( authMethodEnum.OPENID_GOOGLE ) ) {
+            promises.push( this.#initializeOpenIDClient( this.#authSettings.oauth2.google ).then( ( configuration ) => {
+                this.#clientConfigOAuth2Google = configuration;
+                logger.log( "Enabled OpenID Connect authentication with Google Cloud.", logger.logSeverity.NOTICE );
+            } ) );
+        }
+        if ( this.isAuthEnabled( authMethodEnum.OPENID_AZURE ) ) {
+            promises.push( this.#initializeOpenIDClient( this.#authSettings.oauth2.azure ).then( ( configuration ) => {
+                this.#clientConfigOAuth2Azure = configuration;
+                logger.log( "Enabled OpenID Connect authentication with Azure Cloud.", logger.logSeverity.NOTICE );
+            } ) );
+        }
+
+        return Promise.all( promises ).then( () => {
+            this.#initialized = true;
+        } );
+    }
+
+    /**
+     * Used to check whether the specified authentication method is enabled.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @returns {boolean}
+     * @public
+     */
+    isAuthEnabled( authMethod ) {
+        return this.#authSettings.enabledMethods.includes( authMethod );
+    }
+
+    /**
+     * Used to authenticate a user via the specified authentication method.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @param {Object} authDetails
+     * @returns {Promise<Object>}
+     * @throws {TiException.E_SEC_UNRECOGNIZED_AUTH_METHOD} If the authentication method is not recognized or enabled.
+     * @throws {TiException.E_GEN_NOT_INITIALIZED} If the auth manager was not properly initialized.
+     * @public
+     */
+    authenticate( authMethod, authDetails ) {
+        if ( !this.#initialized ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_NOT_INITIALIZED );
+        }
+        switch ( authMethod ) {
+            case authMethodEnum.LOCAL:
+                return this.#authenticateLocal( authDetails.username, authDetails.password );
+            case authMethodEnum.OPENID_GOOGLE:
+                return this.#authenticateOpenID( authDetails.baseUrl, this.#authSettings.oauth2.google, this.#clientConfigOAuth2Google );
+            case authMethodEnum.OPENID_AZURE:
+                return this.#authenticateOpenID( authDetails.baseUrl, this.#authSettings.oauth2.azure, this.#clientConfigOAuth2Azure );
+            default: {
+                throw exceptions.raise( exceptions.exceptionCode.E_SEC_UNRECOGNIZED_AUTH_METHOD );
+            }
+        }
+    }
+
+    /**
+     * Used to set up user authorization according to the specified authentication method.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @param {URL} currentUrl
+     * @param {Object} oidc
+     * @returns {Promise<User>}
+     * @throws {TiException.E_SEC_UNRECOGNIZED_AUTH_METHOD} If the authentication method is not recognized.
+     * @public
+     */
+    authorize( authMethod, currentUrl, oidc ) {
+        switch ( authMethod ) {
+            case authMethodEnum.LOCAL:
+                return Promise.resolve( new User( { userID: `local:${ tools.getUUID() }`, username: oidc.username } ) );
+            case authMethodEnum.OPENID_GOOGLE:
+                return this.#authorizeOpenID( currentUrl, oidc, this.#clientConfigOAuth2Google );
+            case authMethodEnum.OPENID_AZURE:
+                return this.#authorizeOpenID( currentUrl, oidc, this.#clientConfigOAuth2Azure );
+            default: {
+                throw exceptions.raise( exceptions.exceptionCode.E_SEC_UNRECOGNIZED_AUTH_METHOD );
+            }
+        }
+    }
+
+    /**
+     * Used to get the callback URL for the specified OAuth2 authentication method.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @returns {string}
+     * @throws {TiException.E_SEC_UNRECOGNIZED_AUTH_METHOD} If the requested OAuth2 method is not recognized or enabled.
+     * @public
+     */
+    getOAuth2CallbackUrl( authMethod ) {
+        if ( authMethod === authMethodEnum.OPENID_GOOGLE && this.isAuthEnabled( authMethodEnum.OPENID_GOOGLE ) ) {
+            return this.#authSettings.oauth2.google.callbackUrl;
+        } else if ( authMethod === authMethodEnum.OPENID_AZURE && this.isAuthEnabled( authMethodEnum.OPENID_AZURE ) ) {
+            return this.#authSettings.oauth2.azure.callbackUrl;
+        } else {
+            throw exceptions.raise( exceptions.exceptionCode.E_SEC_UNRECOGNIZED_AUTH_METHOD );
+        }
+    }
+
+    /* Private interface */
+
+    /**
+     * Used to initialize the OpenID Connect client for the specified OAuth2 authentication method.
+     * <br/>
+     * NOTE: A Google Cloud guide available here: https://developers.google.com/identity/openid-connect/openid-connect
+     * <br/>
+     * NOTE: An Azure Cloud guide available here: https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols
+     *
+     * @method
+     * @param {SettingsOAuth2Client} oauth2
+     * @returns {Promise<openidClient.Configuration>}
+     * @private
+     */
+    #initializeOpenIDClient( oauth2 ) {
+        return new Promise( ( resolve, reject ) => {
+            // TODO: Public clients are not fully supported yet!
+            let clientAuthentication;
+            let metaData;
+            if ( oauth2.isPublic === true ) {
+                metaData = { token_endpoint_auth_method: openIDTokenEndpointAuthMethodEnum.NONE };
+                clientAuthentication = openidClient.None();
+            } else {
+                const method = oauth2.tokenEndpointAuthMethod || openIDTokenEndpointAuthMethodEnum.POST;
+                switch ( method ) {
+                    case openIDTokenEndpointAuthMethodEnum.POST: {
+                        clientAuthentication = openidClient.ClientSecretPost( oauth2.clientSecret );
+                        metaData = { token_endpoint_auth_method: openIDTokenEndpointAuthMethodEnum.POST };
+                    }
+                        break;
+                    case openIDTokenEndpointAuthMethodEnum.BASIC: {
+                        clientAuthentication = openidClient.ClientSecretBasic( oauth2.clientSecret );
+                        metaData = { token_endpoint_auth_method: openIDTokenEndpointAuthMethodEnum.BASIC };
+                    }
+                        break;
+                    default: {
+                        return reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNRECOGNIZED_AUTH_METHOD ) );
+                    }
+                }
+            }
+
+            openidClient.discovery( new URL( oauth2.discoveryUrl ), oauth2.clientID, metaData, clientAuthentication, { algorithm: "oidc" } ).then( ( configuration ) => {
+                resolve( configuration );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to verify the local authentication of a request.
+     *
+     * @method
+     * @param {string} username
+     * @param {string} password
+     * @returns {Promise}
+     * @private
+     */
+    #authenticateLocal( username, password ) {
+        return new Promise( ( resolve, reject ) => {
+            // TODO: Implement this!
+            if ( this.isAuthEnabled( authMethodEnum.LOCAL ) && ( username === this.#authSettings.local.username && password === this.#authSettings.local.password ) ) {
+                resolve();
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
+            }
+        } );
+    }
+
+    /**
+     * Used to perform the actual OpenID Connect authentication.
+     *
+     * @method
+     * @param {string} baseUrl
+     * @param {SettingsOAuth2Client} oauth2
+     * @param {openidClient.Configuration} clientConfig
+     * @returns {Promise<Object>}
+     * @private
+     */
+    #authenticateOpenID( baseUrl, oauth2, clientConfig ) {
+        return new Promise( ( resolve, reject ) => {
+            const codeVerifier = openidClient.randomPKCECodeVerifier();
+            const nonce = ( typeof openidClient.randomNonce === "function" ) ? openidClient.randomNonce() : randomBytes( 16 ).toString( "base64" );
+            const redirectUri = new URL( oauth2.callbackUrl, baseUrl ).toString();
+            openidClient.calculatePKCECodeChallenge( codeVerifier ).then( ( codeChallenge ) => {
+                const parameters = {
+                    redirect_uri: redirectUri,
+                    response_type: "code",
+                    scope: "openid email profile",
+                    state: openidClient.randomState(),
+                    code_challenge: codeChallenge,
+                    code_challenge_method: "S256",
+                    nonce: nonce
+                };
+                const redirectTo = openidClient.buildAuthorizationUrl( clientConfig, parameters );
+                resolve( { redirectTo: redirectTo, codeVerifier: codeVerifier, state: parameters.state, nonce: nonce } );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to perform the actual OpenID Connect authorization.
+     *
+     * @method
+     * @param {URL} currentUrl
+     * @param {Object} oidc
+     * @param {openidClient.Configuration} clientConfig
+     * @returns {Promise<User>}
+     * @private
+     */
+    #authorizeOpenID( currentUrl, oidc, clientConfig ) {
+        return new Promise( ( resolve, reject ) => {
+            openidClient.authorizationCodeGrant( clientConfig, currentUrl, {
+                pkceCodeVerifier: oidc.codeVerifier,
+                expectedState: oidc.state,
+                expectedNonce: oidc.nonce
+            } ).then( ( token ) => {
+                const claims = token.claims();
+                return openidClient.fetchUserInfo( clientConfig, token.access_token, claims.sub );
+            } ).then( ( userInfo ) => {
+                const username = userInfo.preferred_username ?? userInfo.email ?? userInfo.name ?? `sub:${ userInfo.sub }`;
+                resolve( new User( { userID: `oauth2:${ userInfo.sub }`, username: username, email: userInfo.email, name: userInfo.name } ) );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+}
+
+module.exports = AuthManager;
+module.exports.authMethod = authMethodEnum;

package/components/authorization.js

@@ -0,0 +1,135 @@
+/*
+ * 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-2026 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/>.
+*/
+
+/**
+ * Framework-level authorization helpers. Provides the privileged `admin` role used to gate configuration-editing
+ * (and other administrative) routes, plus Express guards. The `admin` role is sourced from a deployment allowlist
+ * (`auth.admins` in the web-server config) and applied to the session *after* the application's `augmentSession`
+ * hook runs, so it is additive and cannot be clobbered by an app's own (domain) role assignment.
+ *
+ * @module authorization
+ */
+
+const exceptions = require( "@ti-engine/core/exceptions" );
+
+/**
+ * The privileged role required to administer configuration. A string value so it never collides with an
+ * application's own role codes (e.g. competence uses numeric role codes).
+ *
+ * @type {string}
+ */
+const ADMIN_ROLE = "admin";
+
+/**
+ * @param {*} value
+ * @returns {string} Trimmed, lower-cased string form (so email/username matching is case-insensitive).
+ */
+function normalizeIdentity( value ) {
+    return String( value == null ? "" : value ).trim().toLowerCase();
+}
+
+/**
+ * Returns `true` if the user matches any entry in the admin allowlist. An entry may match the user's `userID`,
+ * `username`, or `email` (case-insensitive).
+ *
+ * @param {Object} user A session user (`{ userID, username, email, roles, ... }`).
+ * @param {string[]} admins The configured allowlist of admin identifiers.
+ * @returns {boolean}
+ */
+function isAdminIdentity( user, admins ) {
+    if ( !user || !Array.isArray( admins ) || admins.length === 0 ) {
+        return false;
+    }
+    const candidates = new Set( [ user.userID, user.username, user.email ].map( normalizeIdentity ).filter( ( value ) => value.length > 0 ) );
+    return admins.some( ( entry ) => candidates.has( normalizeIdentity( entry ) ) );
+}
+
+/**
+ * Adds the `admin` role to the session user (additively, no duplicates) when the user is in the allowlist.
+ * Safe to call with an empty/missing allowlist or session — it is then a no-op. Returns the session for chaining.
+ *
+ * @param {Object} session
+ * @param {string[]} [admins]
+ * @returns {Object} The (possibly modified) session.
+ */
+function applyAdminRole( session, admins ) {
+    if ( session && session.user && isAdminIdentity( session.user, admins ) ) {
+        const roles = Array.isArray( session.user.roles ) ? session.user.roles.slice() : [];
+        if ( !roles.includes( ADMIN_ROLE ) ) {
+            roles.push( ADMIN_ROLE );
+        }
+        session.user.roles = roles;
+    }
+    return session;
+}
+
+/**
+ * @param {Object} session
+ * @param {Array<string|number>} roles
+ * @returns {boolean} `true` if the session user holds any of the given roles.
+ */
+function hasAnyRole( session, roles ) {
+    const userRoles = ( session && session.user && Array.isArray( session.user.roles ) ) ? session.user.roles : [];
+    return roles.some( ( role ) => userRoles.includes( role ) );
+}
+
+/**
+ * Pure access decision for a resource (e.g. an HTML fragment) that declares a set of required roles. A resource with
+ * no required roles (`null` / `undefined` / empty) is public — any (authenticated) user may access it; otherwise the
+ * user must hold at least one of the required roles. Roles are treated opaquely, so this works equally for numeric
+ * application role codes and the string `admin` role — there is no implicit hierarchy (an `admin`-gated resource is
+ * reachable only by holders of the `admin` role, never by a high numeric role). Backs {@link TiWebAppManager#verifyAccess}.
+ *
+ * @param {Array<string|number>} [requiredRoles] The roles permitted to access the resource; empty/absent = public.
+ * @param {Array<string|number>} [userRoles] The roles held by the current session user.
+ * @returns {boolean}
+ */
+function isAccessAllowed( requiredRoles, userRoles ) {
+    if ( requiredRoles === null || requiredRoles === undefined ) {
+        return true;
+    }
+    if ( !Array.isArray( requiredRoles ) ) {
+        return false;
+    }
+    if ( requiredRoles.length === 0 ) {
+        return true;
+    }
+    const roles = Array.isArray( userRoles ) ? userRoles : [];
+    return requiredRoles.some( ( role ) => roles.includes( role ) );
+}
+
+/**
+ * Express middleware factory that admits a request only if its session user holds at least one of the given roles.
+ * Responds `401` when unauthenticated (no session user) and `403` when authenticated but lacking the role.
+ *
+ * @param {...(string|number)} roles
+ * @returns {function(Object, Object, Function): void}
+ */
+function requireRole( ...roles ) {
+    return ( request, response, next ) => {
+        const user = request && request.session && request.session.user;
+        if ( !user ) {
+            response.status( exceptions.httpCode.C_401 ).end();
+            return;
+        }
+        if ( !hasAnyRole( request.session, roles ) ) {
+            response.status( exceptions.httpCode.C_403 ).end();
+            return;
+        }
+        next();
+    };
+}
+
+/**
+ * Express middleware that admits only `admin`-role users.
+ *
+ * @type {function(Object, Object, Function): void}
+ */
+const requireAdmin = requireRole( ADMIN_ROLE );
+
+module.exports = { ADMIN_ROLE, isAdminIdentity, applyAdminRole, hasAnyRole, isAccessAllowed, requireRole, requireAdmin };

package/components/config-change-notifier.js

@@ -0,0 +1,98 @@
+/*
+ * 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-2026 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 { EventEmitter } = require( "node:events" );
+const logger = require( "@ti-engine/core/logger" );
+
+/**
+ * @typedef {Object} ConfigChangeEvent
+ * @property {string} changeSetID
+ * @property {string[]} configKeys The configuration documents affected by the change.
+ * @property {string} adminID Who committed the change.
+ * @property {string} timestamp ISO timestamp.
+ */
+
+const CONFIG_CHANGED = "config:changed";
+
+/**
+ * Notifies subscribers that configuration changed, so they can react (e.g. invalidate an in-memory cache, or push a
+ * live update to an admin UI). This is the **in-process** implementation of a deliberately transport-agnostic
+ * contract — `publish(event)` (fire-and-forget) and `subscribe(listener) → unsubscribe`.
+ *
+ * **Designed for an eventual switch to a reusable core pub/sub.** Cross-instance propagation is out of scope for v1
+ * (the store-backed model already makes a committed change visible to every instance via the shared Redis cache;
+ * this emitter exists to invalidate optional *in-memory* caches and drive live UI within a process). When a Redis
+ * (or other) pub/sub primitive lands in `@ti-engine/core`, a drop-in implementation of this same contract can be
+ * provided and injected into {@link ConfigService} — no change to publishers or subscribers. To keep that swap
+ * behavior-safe, **delivery here is already asynchronous** (matching cross-instance transports); subscribers must
+ * not assume synchronous delivery, and the event payload is plain serializable JSON so it survives a wire transport.
+ *
+ * @class ConfigChangeNotifier
+ * @public
+ */
+class ConfigChangeNotifier {
+
+    #emitter = new EventEmitter();
+
+    constructor() {
+        this.#emitter.setMaxListeners( 0 );
+    }
+
+    /**
+     * Publishes a configuration-change event to all subscribers. Fire-and-forget; delivery is asynchronous.
+     *
+     * @method
+     * @param {ConfigChangeEvent} event
+     * @returns {ConfigChangeEvent} The (frozen) event that will be delivered.
+     * @public
+     */
+    publish( event ) {
+        const payload = Object.freeze( { ...event } );
+        setImmediate( () => {
+            for ( const listener of this.#emitter.listeners( CONFIG_CHANGED ) ) {
+                try {
+                    listener( payload );
+                } catch ( error ) {
+                    // A misbehaving subscriber must not break delivery to the others or crash the process.
+                    logger.log( `Config-change subscriber threw: ${ error && error.message ? error.message : error }`, logger.logSeverity.WARNING );
+                }
+            }
+        } );
+        return payload;
+    }
+
+    /**
+     * Subscribes a listener to configuration-change events.
+     *
+     * @method
+     * @param {function(ConfigChangeEvent): void} listener
+     * @returns {function(): void} An unsubscribe function.
+     * @public
+     */
+    subscribe( listener ) {
+        this.#emitter.on( CONFIG_CHANGED, listener );
+        return () => {
+            this.#emitter.off( CONFIG_CHANGED, listener );
+        };
+    }
+
+    /**
+     * @method
+     * @returns {number} The current number of subscribers.
+     * @public
+     */
+    subscriberCount() {
+        return this.#emitter.listenerCount( CONFIG_CHANGED );
+    }
+
+}
+
+const instance = new ConfigChangeNotifier();
+module.exports = ConfigChangeNotifier;
+module.exports.instance = instance;
+module.exports.CONFIG_CHANGED = CONFIG_CHANGED;