@ti-engine/web-framework 1.13.1 → 1.14.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 This document will contain the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.14.1
+
+Security hardening for the web-server CodeQL findings raised after the scanner was modernized in CA-90 (CA-91).
+
+* fix(web-framework): rewrite the default unprotected static-asset route matchers from the ambiguous `(?:.+/)*` to segment-anchored `(?:[^/]+/)*` — the previous form backtracked exponentially and is evaluated against the raw request path in `isUnprotectedRoute()` before authentication, making it a pre-authentication denial-of-service vector (CodeQL js/redos); the matched language for realistic asset paths is unchanged, and the matchers are now the `RE_STATIC_UNPROTECTED` / `RE_WELL_KNOWN_UNPROTECTED` module constants
+* fix(web-framework): replace the login-fragment section stripper's `open[\s\S]*?close` global-regex removal with a linear `indexOf`-based `stripMarkerSpans()` helper (also used for the per-provider stripper), eliminating the polynomial-time rescan on hostile input (CodeQL js/polynomial-redos)
+* docs(web-framework): document that Helmet's built-in Content-Security-Policy is intentionally disabled because a per-request, nonce-based CSP is enforced by `cspHeaderHandler()` on the following middleware — added an explanatory comment and an inline CodeQL suppression (the alert is a false positive)
+* build(release): bump package version from `1.14.0` to `1.14.1`
+
+## Version 1.14.0
+
+`TI_WEB_*` environment-variable overrides for the web server configuration, enabling 12-factor container deployments without per-environment config files (CA-90).
+
+* feat(web-framework): add `applyWebConfigEnvOverrides( config, env = process.env )` (`#web-config-env`) — a pure helper applying `TI_WEB_HOST`, `TI_WEB_PORT`, `TI_WEB_USE_TLS`, `TI_WEB_TLS_CERT_PATH`, `TI_WEB_TLS_KEY_PATH`, and `TI_WEB_COOKIE_SECRET` overrides onto the merged `TiWebServer` configuration, only when each variable is defined (fully backward compatible)
+* fix(web-framework): skip an enabled OpenID Connect provider that has no client ID instead of crashing the instance during discovery — an OAuth-less deployment (e.g. a container started without OAuth credentials) now boots on its remaining methods, with a warning, and reports the dropped provider as unavailable so a sign-in attempt against it fails per-request rather than at startup
+* feat(web-framework): the login page now renders an OpenID provider button only when that provider is an effective enabled auth method — the web server passes the post-drop enabled methods to the app manager, which strips the Google/Azure button (and the whole "or continue with" section when no provider is available) from `frame-login.html` at render time
+* build(release): bump package version from `1.13.2` to `1.14.0`
+
 ## Version 1.13.0
 
 A reusable role-based screen gate and a per-screen title override (back the competence screen-access work and the evaluation/scores screen split).

package/README.md

@@ -8,6 +8,16 @@ Flexible framework for the creation of microservices with node.js.
 
 This is a customizable web framework based on the **ti-engine** framework. Currently under development.
 
+## Environment variables
+
+The web server configuration (host, port, TLS, cookies, etc.) is normally provided via the service configuration file merged in the `TiWebServer` constructor. The following environment variables can override individual values at runtime — useful for container/12-factor deployments where the same image is configured per environment:
+
+* `TI_WEB_HOST` overrides the bind address (e.g. `0.0.0.0` in a container). Defaults to the value in the web server config.
+* `TI_WEB_PORT` overrides the listen port.
+* `TI_WEB_USE_TLS` (`true`/`false`) toggles in-app TLS. Set `false` when a reverse proxy / ingress terminates TLS.
+* `TI_WEB_TLS_CERT_PATH` / `TI_WEB_TLS_KEY_PATH` override the TLS certificate/key paths (only used when TLS is enabled).
+* `TI_WEB_COOKIE_SECRET` sets the session cookie signing secret. Set a stable, private value for durable sessions and multi-replica deployments (otherwise a random per-process value is used).
+
 ## Configure HTTPS for development
 
 Use the `mkcert` tool to create a certificate for development.

package/bin/static/fragments/components/component-sidebar-flyout.html

@@ -1,37 +1,37 @@
-<div x-id="['component-flyout']"
-     x-data="tiComponentSidebarFlyout('{ti-config-key}')"
-     class="ti-sidebar-flyout-container">
-    <!--
-        Trigger slot. The placeholder consumer can replace this with any custom button — typically a user avatar
-        or app menu trigger. The trigger MUST set x-ref="flyoutButton" and call toggle() to integrate with the
-        encapsulated flyout state. If the consumer omits inner content, this default icon button is used.
-    -->
-    <ti-slot>
-        <button x-on:click.stop="toggle()"
-                x-on:ti-close-all-flyout="close()"
-                x-bind:aria-expanded="isOpen"
-                x-bind:aria-controls="$id('component-flyout')"
-                x-bind:aria-label="menuTitle"
-                x-ref="flyoutButton"
-                type="button" class="ti-sidebar-button">
-            <span class="ti-icon" x-bind:class="icon" aria-hidden="true"></span>
-        </button>
-    </ti-slot>
-    <div x-on:click.outside="close()"
-         x-bind:id="$id('component-flyout')"
-         x-show="isOpen"
-         x-ref="flyoutPanel"
-         role="menu" class="ti-sidebar-flyout">
-        <template x-for="(buttonConfig, index) in buttonConfigs">
-            <button x-on:click="close()"
-                    x-bind:hx-get="(!buttonConfig.action.method || buttonConfig.action.method === 'get') ? buttonConfig.action.href : null"
-                    x-bind:hx-post="(buttonConfig.action.method && buttonConfig.action.method === 'post') ? buttonConfig.action.href : null"
-                    x-bind:hx-target="buttonConfig.action.target"
-                    x-bind:hx-swap="buttonConfig.action.swap"
-                    hx-push-url="true"
-                    type="button" class="ti-sidebar-flyout-item">
-                <span class="ti-icon" x-bind:class="buttonConfig.icon" aria-hidden="true"></span><span x-text="buttonConfig.title"></span>
-            </button>
-        </template>
-    </div>
+<div x-id="['component-flyout']"
+     x-data="tiComponentSidebarFlyout('{ti-config-key}')"
+     class="ti-sidebar-flyout-container">
+    <!--
+        Trigger slot. The placeholder consumer can replace this with any custom button — typically a user avatar
+        or app menu trigger. The trigger MUST set x-ref="flyoutButton" and call toggle() to integrate with the
+        encapsulated flyout state. If the consumer omits inner content, this default icon button is used.
+    -->
+    <ti-slot>
+        <button x-on:click.stop="toggle()"
+                x-on:ti-close-all-flyout="close()"
+                x-bind:aria-expanded="isOpen"
+                x-bind:aria-controls="$id('component-flyout')"
+                x-bind:aria-label="menuTitle"
+                x-ref="flyoutButton"
+                type="button" class="ti-sidebar-button">
+            <span class="ti-icon" x-bind:class="icon" aria-hidden="true"></span>
+        </button>
+    </ti-slot>
+    <div x-on:click.outside="close()"
+         x-bind:id="$id('component-flyout')"
+         x-show="isOpen"
+         x-ref="flyoutPanel"
+         role="menu" class="ti-sidebar-flyout">
+        <template x-for="(buttonConfig, index) in buttonConfigs">
+            <button x-on:click="close()"
+                    x-bind:hx-get="(!buttonConfig.action.method || buttonConfig.action.method === 'get') ? buttonConfig.action.href : null"
+                    x-bind:hx-post="(buttonConfig.action.method && buttonConfig.action.method === 'post') ? buttonConfig.action.href : null"
+                    x-bind:hx-target="buttonConfig.action.target"
+                    x-bind:hx-swap="buttonConfig.action.swap"
+                    hx-push-url="true"
+                    type="button" class="ti-sidebar-flyout-item">
+                <span class="ti-icon" x-bind:class="buttonConfig.icon" aria-hidden="true"></span><span x-text="buttonConfig.title"></span>
+            </button>
+        </template>
+    </div>
 </div>

package/bin/static/fragments/frame-login.html

@@ -46,6 +46,7 @@
                 </button>
             </form>
 
+            <!--ti-auth-oauth-section-->
             <!-- Divider -->
             <div class="ti-login-divider">
                 <div class="ti-login-divider-line"></div>
@@ -55,6 +56,7 @@
 
             <!-- Social auth -->
             <div class="ti-login-social">
+                <!--ti-auth-method:openid-google-->
                 <a href="/login/openid-google" class="ti-btn full">
                     <svg width="16" height="16" viewBox="0 0 24 24" fill="none" aria-hidden="true">
                         <path d="M21.6 12.23c0-.68-.06-1.33-.17-1.96H12v3.71h5.39a4.6 4.6 0 0 1-2 3.02v2.51h3.23c1.9-1.74 2.98-4.31 2.98-7.28Z" fill="#4285F4"/>
@@ -67,13 +69,17 @@
                     </svg>
                     <span x-text-label="interface.default.login.sign-in-google">Sign in with Google</span>
                 </a>
+                <!--/ti-auth-method-->
+                <!--ti-auth-method:openid-azure-->
                 <a href="/login/openid-azure" class="ti-btn full">
                     <svg width="16" height="16" viewBox="0 0 24 24" fill="none" aria-hidden="true">
                         <path d="M11.5 2L4 8.5l4 1-4 6.5h8l-2-4 4-1-2.5 8H20L14 2h-2.5Z" fill="#0078D4"/>
                     </svg>
                     <span x-text-label="interface.default.login.sign-in-azure">Sign in with Azure</span>
                 </a>
+                <!--/ti-auth-method-->
             </div>
+            <!--/ti-auth-oauth-section-->
         </div>
 
         <!-- TEMPORARY: Test user selector for augmentSession() experimentation. Remove once AD-driven identity is wired up. -->

package/bin/web-app-manager.js

@@ -20,6 +20,71 @@ const RE_CSRF_ATTR = /\{ti-csrf-placeholder}/g;
 const RE_HTMX_CONFIG = /\{ti-htmx-config-placeholder}/g;
 const RE_CSP_NONCE = /^[A-Za-z0-9+/=_-]{16,}$/;
 const TI_NESTED_FRAME_PLACEHOLDER = "ti-nested-frame-placeholder";
+const OAUTH_METHODS = [ "openid-google", "openid-azure" ];
+const RE_AUTH_MARKERS = /<!--\/?ti-auth-(?:oauth-section|method(?::[a-z-]+)?)-->/g;
+
+/**
+ * Removes every `<openMarker>…<closeMarker>` span (inclusive) from `html` in a single linear pass. The markers are
+ * matched as fixed strings via `indexOf`, so — unlike an `openMarker[\s\S]*?closeMarker` regular expression under a
+ * global replace — this cannot exhibit super-linear backtracking on hostile input containing many opening markers
+ * (CodeQL js/polynomial-redos). Matches the lazy-regex semantics: each opening marker pairs with the *next* closing
+ * marker after it. An opening marker with no matching closing marker is left untouched (the caller strips any stray
+ * markers afterwards with {@link RE_AUTH_MARKERS}).
+ *
+ * @param {string} html
+ * @param {string} openMarker
+ * @param {string} closeMarker
+ * @returns {string}
+ */
+function stripMarkerSpans( html, openMarker, closeMarker ) {
+    let result = "";
+    let cursor = 0;
+    for ( ; ; ) {
+        const open = html.indexOf( openMarker, cursor );
+        if ( open === -1 ) {
+            result += html.slice( cursor );
+            break;
+        }
+        const close = html.indexOf( closeMarker, open + openMarker.length );
+        if ( close === -1 ) {
+            result += html.slice( cursor );
+            break;
+        }
+        result += html.slice( cursor, open );
+        cursor = close + closeMarker.length;
+    }
+    return result;
+}
+
+/**
+ * Removes login-page OpenID provider markup for any OAuth method that is not currently enabled, and removes the
+ * entire "or continue with" section when no OAuth method is enabled at all. The login fragment delimits the
+ * relevant blocks with HTML-comment markers: `<!--ti-auth-method:METHOD-->…<!--/ti-auth-method-->` around each
+ * provider button, and `<!--ti-auth-oauth-section-->…<!--/ti-auth-oauth-section-->` around the divider + social
+ * block. Any remaining markers are stripped so clean HTML ships. Fragments without these markers (every non-login
+ * fragment) are returned unchanged.
+ *
+ * @param {string} html
+ * @param {string[]} [enabledMethods] The effective enabled authentication methods.
+ * @returns {string}
+ */
+function applyAuthMethodVisibility( html, enabledMethods ) {
+    let result = String( html );
+    const enabled = Array.isArray( enabledMethods ) ? enabledMethods : [];
+
+    if ( !OAUTH_METHODS.some( ( method ) => enabled.includes( method ) ) ) {
+        // No OAuth providers available — drop the whole "or continue with" section, then any stray markers.
+        return stripMarkerSpans( result, "<!--ti-auth-oauth-section-->", "<!--/ti-auth-oauth-section-->" ).replace( RE_AUTH_MARKERS, "" );
+    }
+
+    // Drop the button block for each OAuth method that is not enabled, then strip the remaining markers.
+    OAUTH_METHODS.forEach( ( method ) => {
+        if ( !enabled.includes( method ) ) {
+            result = stripMarkerSpans( result, "<!--ti-auth-method:" + method + "-->", "<!--/ti-auth-method-->" );
+        }
+    } );
+    return result.replace( RE_AUTH_MARKERS, "" );
+}
 
 /**
  * A generic web application manager that handles the rendering and behavior of web application views. It is designed to be extended by specific web application
@@ -39,6 +104,7 @@ class TiWebAppManager {
     #fragments = {};
     #staticFileCache = {};
     #staticFileCacheEnabled;
+    #enabledAuthMethods = [];
 
     /**
      * @constructor
@@ -173,6 +239,18 @@ class TiWebAppManager {
         this.#staticFileCache = {};
     }
 
+    /**
+     * Sets the effective enabled authentication methods used to gate login-page provider buttons. The web server
+     * calls this at startup, after the auth manager has dropped any enabled-but-unconfigured OpenID providers.
+     *
+     * @method
+     * @param {string[]} methods
+     * @public
+     */
+    setEnabledAuthMethods( methods ) {
+        this.#enabledAuthMethods = Array.isArray( methods ) ? [ ...methods ] : [];
+    }
+
     /**
      * Optional HTML transformation hook.
      * <br/>
@@ -212,6 +290,9 @@ class TiWebAppManager {
 
             transformedHtml = transformedHtml.replace( "{ti-title-placeholder}", options.title || "" );
 
+            // Gate login-page OpenID provider buttons to the effective enabled auth methods (no-op on other fragments).
+            transformedHtml = applyAuthMethodVisibility( transformedHtml, this.#enabledAuthMethods );
+
             resolve( transformedHtml );
         } );
     }
@@ -562,3 +643,4 @@ class TiWebAppManager {
 }
 
 module.exports = TiWebAppManager;
+module.exports.applyAuthMethodVisibility = applyAuthMethodVisibility;

package/bin/web-server.js

@@ -24,6 +24,7 @@ const authMethod = require( "#auth-manager" ).authMethod;
 const authorization = require( "#authorization" );
 const adminConfigHandlers = require( "#admin-config-handlers" );
 const configService = require( "#config-service" );
+const applyWebConfigEnvOverrides = require( "#web-config-env" );
 
 /** @typedef {import("node:http").Server} NodeServer */
 
@@ -89,6 +90,25 @@ const configService = require( "#config-service" );
 
 const webServerConfig = require( "#web-server-config" );
 
+/**
+ * Default unprotected static-asset route matchers. The path segments are matched with `(?:[^/]+\/)*` rather than
+ * `(?:.+\/)*`: the inner `[^/]+` cannot also consume the "/" delimiter, so the pattern is unambiguous and matches
+ * in linear time. The previous `.+` form was ambiguous and backtracked exponentially on hostile request paths such
+ * as `/static/a/a/…/a/x` (no trailing extension) — and these matchers run against the raw request path in
+ * {@link TiWebServer#isUnprotectedRoute} BEFORE authentication, so that was a pre-auth denial-of-service vector
+ * (CodeQL js/redos). The matched language for realistic asset paths is unchanged.
+ *
+ * @type {RegExp}
+ */
+const RE_STATIC_UNPROTECTED = /^\/static\/(?:[^/]+\/)*[^/]+\.[^/]+$/i;
+
+/**
+ * Default unprotected `/.well-known/` route matcher. See {@link RE_STATIC_UNPROTECTED} for the ReDoS rationale.
+ *
+ * @type {RegExp}
+ */
+const RE_WELL_KNOWN_UNPROTECTED = /^\/\.well-known\/(?:[^/]+\/)*[^/]+\.[^/]+$/i;
+
 /**
  * A web server microservice based on the ti-engine.
  * <br/>
@@ -121,7 +141,7 @@ class TiWebServer extends ServiceConsumer {
      * @throws {TiException.E_GEN_JS_INTERNAL_ERROR} If the web application manager cannot be loaded.
      */
     constructor( serviceDomainName, serviceConfig ) {
-        super( serviceDomainName, _.merge( {}, webServerConfig, ( _.isObjectLike( serviceConfig ) ) ? serviceConfig : {} ) );
+        super( serviceDomainName, applyWebConfigEnvOverrides( _.merge( {}, webServerConfig, ( _.isObjectLike( serviceConfig ) ) ? serviceConfig : {} ) ) );
 
         // Include the current host in the list of allowed hosts:
         this.#allowedHosts.push( this.serviceConfig.host );
@@ -255,6 +275,12 @@ class TiWebServer extends ServiceConsumer {
 
                 // Set up security and session middlewares first:
                 this.#webServer.use( webHandlers.nonceGenerationHandler() );
+                // Helmet's built-in Content-Security-Policy is intentionally disabled here because a per-request,
+                // nonce-based CSP is enforced on the very next line by webHandlers.cspHeaderHandler() (see
+                // components/web-handlers.js) — Helmet's static config cannot express per-response nonces. Every other
+                // Helmet header (HSTS, X-Content-Type-Options, X-Frame-Options, …) still applies. This is a deliberate
+                // architecture, not missing CSP; do not enable Helmet's static CSP here, as that would drop the nonce.
+                // codeql[js/insecure-helmet-configuration]
                 this.#webServer.use( helmet( { contentSecurityPolicy: false } ) );
                 this.#webServer.use( webHandlers.cspHeaderHandler() );
                 this.#webServer.use( express.json( { limit: "1mb" } ) );
@@ -305,6 +331,11 @@ class TiWebServer extends ServiceConsumer {
 
                 return this.#authManager.initialize();
             } ).then( () => {
+                // Hand the web application manager the effective enabled auth methods (after any unconfigured OpenID
+                // providers were dropped) so the login page only renders providers a user can actually complete.
+                if ( this.#webAppManager && typeof this.#webAppManager.setEnabledAuthMethods === "function" ) {
+                    this.#webAppManager.setEnabledAuthMethods( this.#authManager.getEnabledMethods() );
+                }
                 return this.#beginListening( this.#netServer, this.serviceConfig.port, this.serviceConfig.host );
             } ).then( ( server ) => {
                 if ( server.listening === true ) {
@@ -537,8 +568,8 @@ class TiWebServer extends ServiceConsumer {
         this.#unprotectedRoutes.push( "/app/config" );
         this.#unprotectedRoutes.push( /^\/login\/[^/]+$/i );
         this.#unprotectedRoutes.push( "/logout" );
-        this.#unprotectedRoutes.push( /^\/static\/(?:.+\/)*[^/]+\.[^/]+$/i );
-        this.#unprotectedRoutes.push( /^\/\.well-known\/(?:.+\/)*[^/]+\.[^/]+$/i );
+        this.#unprotectedRoutes.push( RE_STATIC_UNPROTECTED );
+        this.#unprotectedRoutes.push( RE_WELL_KNOWN_UNPROTECTED );
     }
 
     /* Private interface */
@@ -601,4 +632,7 @@ class TiWebServer extends ServiceConsumer {
 
 }
 
-module.exports = TiWebServer;
+module.exports = TiWebServer;
+// Exported for unit testing of the ReDoS-hardened matchers; not part of the customization surface.
+module.exports.RE_STATIC_UNPROTECTED = RE_STATIC_UNPROTECTED;
+module.exports.RE_WELL_KNOWN_UNPROTECTED = RE_WELL_KNOWN_UNPROTECTED;

package/components/auth-manager.js

@@ -105,6 +105,11 @@ class AuthManager {
      * @public
      */
     initialize() {
+        // Drop any OpenID Connect provider that is enabled but not configured (missing a client ID) so the
+        // instance boots with the remaining methods instead of crashing during discovery — e.g. a container
+        // started without OAuth credentials falls back to whatever else is enabled rather than failing to start.
+        this.#dropUnconfiguredOpenIDProviders();
+
         let promises = [];
         if ( this.isAuthEnabled( authMethodEnum.OPENID_GOOGLE ) ) {
             promises.push( this.#initializeOpenIDClient( this.#authSettings.oauth2.google ).then( ( configuration ) => {
@@ -136,6 +141,19 @@ class AuthManager {
         return this.#authSettings.enabledMethods.includes( authMethod );
     }
 
+    /**
+     * Returns the list of currently enabled authentication methods, reflecting any OpenID providers dropped by
+     * {@link AuthManager#initialize} for being enabled but unconfigured. Callers (e.g. the login-page renderer)
+     * use this to present only the methods a user can actually complete.
+     *
+     * @method
+     * @returns {TiAuthMethod[]}
+     * @public
+     */
+    getEnabledMethods() {
+        return [ ...this.#authSettings.enabledMethods ];
+    }
+
     /**
      * Used to authenticate a user via the specified authentication method.
      *
@@ -210,6 +228,41 @@ class AuthManager {
 
     /* Private interface */
 
+    /**
+     * Removes any OpenID Connect provider that is enabled but not configured (missing a client ID) from the set
+     * of enabled authentication methods, logging a warning for each. This prevents a startup crash during OpenID
+     * discovery when an enabled provider has no credentials (e.g. a container started without OAuth env vars): the
+     * instance boots on its remaining methods, and `isAuthEnabled` then correctly reports the dropped provider as
+     * unavailable so a sign-in attempt against it is rejected per-request instead of taking down startup.
+     *
+     * @method
+     * @private
+     */
+    #dropUnconfiguredOpenIDProviders() {
+        const providers = [
+            { method: authMethodEnum.OPENID_GOOGLE, oauth2: this.#authSettings.oauth2.google, label: "Google" },
+            { method: authMethodEnum.OPENID_AZURE, oauth2: this.#authSettings.oauth2.azure, label: "Azure" }
+        ];
+        providers.forEach( ( provider ) => {
+            if ( this.isAuthEnabled( provider.method ) && !this.#isOpenIDConfigured( provider.oauth2 ) ) {
+                this.#authSettings.enabledMethods = this.#authSettings.enabledMethods.filter( ( method ) => method !== provider.method );
+                logger.log( `OpenID Connect (${ provider.label }) is enabled but not configured (missing client ID); skipping this provider.`, logger.logSeverity.WARNING );
+            }
+        } );
+    }
+
+    /**
+     * Checks whether an OpenID Connect provider has the minimum configuration required to initialize (a non-empty client ID).
+     *
+     * @method
+     * @param {SettingsOAuth2Client} [oauth2] The provider's OAuth2 settings.
+     * @returns {boolean}
+     * @private
+     */
+    #isOpenIDConfigured( oauth2 ) {
+        return !!( oauth2 && typeof oauth2.clientID === "string" && oauth2.clientID.trim() !== "" );
+    }
+
     /**
      * Used to initialize the OpenID Connect client for the specified OAuth2 authentication method.
      * <br/>

package/components/web-config-env.js

@@ -0,0 +1,54 @@
+/*
+ * 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/>.
+*/
+
+"use strict";
+
+const tools = require( "@ti-engine/core/tools" );
+
+/**
+ * Applies TI_WEB_* environment-variable overrides onto an (already-merged) web server configuration object.
+ * Each override is applied ONLY when its environment variable is defined, so an absent variable leaves the
+ * configured/default value untouched (fully backward compatible). This gives ti-engine web servers 12-factor,
+ * container-friendly control over network binding, TLS, and the session cookie secret without editing config files.
+ *
+ * @method
+ * @param {Object} config The web server configuration to augment (mutated in place and returned).
+ * @param {Object} [env=process.env] The environment source (injectable for testing).
+ * @returns {Object} The same config object, with any present overrides applied.
+ * @public
+ */
+function applyWebConfigEnvOverrides( config, env = process.env ) {
+    if ( !config || typeof config !== "object" ) {
+        return config;
+    }
+    if ( env.TI_WEB_HOST !== undefined ) {
+        config.host = env.TI_WEB_HOST;
+    }
+    if ( env.TI_WEB_PORT !== undefined ) {
+        const port = Number( env.TI_WEB_PORT );
+        if ( Number.isInteger( port ) ) {
+            config.port = port;
+        }
+    }
+    if ( env.TI_WEB_USE_TLS !== undefined ) {
+        config.useTLS = tools.toBool( env.TI_WEB_USE_TLS );
+    }
+    if ( env.TI_WEB_TLS_CERT_PATH !== undefined ) {
+        config.tlsCertPath = env.TI_WEB_TLS_CERT_PATH;
+    }
+    if ( env.TI_WEB_TLS_KEY_PATH !== undefined ) {
+        config.tlsKeyPath = env.TI_WEB_TLS_KEY_PATH;
+    }
+    if ( env.TI_WEB_COOKIE_SECRET !== undefined ) {
+        config.cookies = config.cookies || {};
+        config.cookies.secret = env.TI_WEB_COOKIE_SECRET;
+    }
+    return config;
+}
+
+module.exports = applyWebConfigEnvOverrides;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.13.1",
+  "version": "1.14.1",
   "description": "A web-framework based on the ti-engine. It provides a customizable ready-to-use web-server microservice and a set of tools for creating web applications. NOTICE: This is still a work in progress and the full architecture, design, and functionality are not available!",
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
   "license": "GPL-3.0-or-later",
@@ -20,12 +20,15 @@
     "#session-store": "./components/session-store.js",
     "#user": "./components/user.js",
     "#web-app-manager": "./bin/web-app-manager.js",
+    "#web-config-env": "./components/web-config-env.js",
     "#web-handlers": "./components/web-handlers.js",
     "#web-server": "./bin/web-server.js",
     "#web-server-config": "./bin/web-server.json"
   },
   "dependencies": {
     "@ti-engine/core": "*",
+    "@alpinejs/csp": "^3.15.12",
+    "htmx.org": "^2.0.10",
     "ajv": "^8.20.0",
     "cookie-parser": "^1.4.7",
     "express": "^5.2.1",
@@ -35,8 +38,6 @@
     "openid-client": "^6.8.4"
   },
   "devDependencies": {
-    "@alpinejs/csp": "^3.15.12",
-    "htmx.org": "^2.0.10"
   },
   "files": [
     "bin/",