@ti-engine/web-framework 1.17.0 → 1.18.1

package/CHANGELOG.md

@@ -2,11 +2,35 @@
 
 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.18.1
+
+Enabling Azure SSO took the instance down at startup: the OAuth2 callback was registered by handing the configured callback value straight to Express as a route path, and the installation docs tell operators to set that value to the full absolute URL registered with the identity provider. Express 5 parses route patterns with path-to-regexp v8, where `:` opens a parameter name — so `https://host/login/azure-callback` throws `Missing parameter name at index 6` and the web server never starts. Google was affected identically, which also made this a prerequisite for the competence Cloud Run deployment, whose `deploy.sh` patches in an absolute callback URL (CA-97).
+
+* fix(web-framework): register an OAuth2 callback by its **path** rather than by the configured value verbatim, so a callback given as the absolute URL registered with the provider no longer crashes startup; a callback that yields no usable path now logs a WARNING and skips that provider's endpoint instead of taking the instance down, matching how an enabled-but-unconfigured provider is already handled
+* feat(web-framework): add `AuthManager.getOAuth2CallbackPath( authMethod )` and the pure, unit-tested `AuthManager.toCallbackPath( callbackUrl )` — reduces an absolute, protocol-relative, path or bare relative callback to its route path (query string and fragment stripped), or `null` when no usable path can be derived. The `redirect_uri` sent to the provider is deliberately left as configured, so an absolute callback keeps matching the provider registration exactly instead of depending on the forwarded protocol/host being correct
+* docs(web-framework): document the OpenID Connect provider variables in the README, and state in the README, the competence `INSTALL.md` and `.env.example` that a callback URL may be given as either the absolute registered URL or a path — including what each implies for the `redirect_uri`, and that the path must be the one the app actually receives when a proxy strips a prefix
+* build(release): bump package version from `1.18.0` to `1.18.1`
+
+## Version 1.18.0
+
+Every web-server setting a container deployment needs could be supplied per environment except one: the admin allowlist. `auth.admins` was readable only from the config file baked into the image, so a containerized deployment had no way to name an administrator — leaving the admin configuration screens unreachable, or forcing a real identity to be committed to the repository. This closes that gap in the existing `TI_WEB_*` override set (CA-94).
+
+* feat(web-framework): add the `TI_WEB_AUTH_ADMINS` environment override — comma-separated, **replaces** `auth.admins` (matched against the session user's user ID, username or email), so the admin allowlist is configurable per environment like every other web setting; an explicitly empty value means no admins
+* docs(web-framework): document `TI_WEB_AUTH_METHODS` and `TI_WEB_TRUSTED_ORIGINS` in the README's environment-variable list, which had never listed them
+* build(release): bump package version from `1.17.1` to `1.18.0`
+
+## Version 1.17.1
+
+A validator that needs to compare its own config document against its previously committed state had no way to do so: `applyEdits`'s cross-document context resolves `getConfig` to the *pending* value for any document inside the current edit batch — by design, so a validator can check a sibling document's post-edit state — but a document is always part of its own edit batch, so calling `getConfig` on itself just hands back the same incoming value already passed as the validator's argument, never its prior state. This silently defeated the competence `research-consent` config's version-bump guard (CA-93).
+
+* feat(web-framework): add `getStoredConfig(key)` to the `applyEdits` validator context (`ConfigService`) — always resolves the current *committed* value from the store, even for the document currently under validation, so a validator comparing its own document against its previous state has a way to do it; purely additive — `getConfig`'s existing cross-document (pending-value) semantics are unchanged
+* build(release): bump package version from `1.17.0` to `1.17.1`
+
 ## Version 1.17.0
 
 Route-registration seams so an application subclass can add its own Express routes and unprotected-route patterns — enabling public, content-driven sites (the first consumer being the standalone author's site) to layer a catch-all content resolver over the framework without reaching into private state.
 
-* feat(web-server): add `TiWebServer.registerRoute( method, path, ...handlers )` — registers a custom route on the underlying Express app from a `defineWebApplicationRoutes()` override (after `super()`), so a catch-all resolver can be mounted after the framework's own routes but before its `*splat` 404 handler. Limited to route-scoped verbs (get/post/put/patch/delete/options/head/all); raises `E_GEN_INVALID_ARGUMENT_TYPE` for any other method and `E_GEN_NOT_INITIALIZED` if called before the Express app exists
+* feat(web-server): add `TiWebServer.registerRoute( method, path, ...handlers )` — registers a custom route on the underlying Express app from a `defineWebApplicationRoutes()` override (after `super()`), so a catch-all resolver can be mounted after the framework's own routes but before its `*splat` 404 handler. Limited to route-scoped verbs (get/post/put/patch/delete/options/head/all); raises `E_GEN_INVALID_ARGUMENT_TYPE` for any other method and `E_GEN_NOT_INITIALIZED` if called before the Express app exists. The method must be a **string** — a non-string is rejected outright rather than coerced, so a value whose `toString()` happens to yield a verb (`[ "get" ]`, `new String( "get" )`) cannot slip past the allowlist and register a route
 * feat(web-server): add `TiWebServer.addUnprotectedRoute( pattern )` — appends a string (exact-match) or RegExp (tested) pattern to the unprotected-routes list from a `defineUnprotectedRoutes()` override, so a public-by-default site can invert the framework's protect-by-default stance; non-string/non-RegExp values are ignored with a warning
 * refactor(web-server): extract the unprotected-route matching loop from `isUnprotectedRoute()` into the pure, unit-tested `isRouteInList()` helper (behavior unchanged, including the defensive `lastIndex` reset), and add the `normalizeRegistrableMethod()` helper — both exported for testing alongside the existing `RE_*` matcher constants
 * build(release): bump package version from `1.16.0` to `1.17.0`

package/README.md

@@ -17,6 +17,11 @@ The web server configuration (host, port, TLS, cookies, etc.) is normally provid
 * `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).
+* `TI_WEB_AUTH_METHODS` (comma-separated) **replaces** the enabled authentication methods (`auth.enabledMethods`), e.g. `openid-google` or `local,openid-google`.
+* `TI_WEB_AUTH_ADMINS` (comma-separated) **replaces** the admin allowlist (`auth.admins`). Entries are matched against the session user's user ID, username or email, so an OpenID deployment lists emails. An explicitly empty value means *no admins*.
+* `TI_WEB_TRUSTED_ORIGINS` (comma-separated) **replaces** the trusted request origins (`trustedOrigins`) — needed behind proxies that do not present the real external origin.
+
+OpenID Connect providers are configured with their own variables — `TI_AZURE_AUTH_CLIENT_ID` / `TI_AZURE_AUTH_CLIENT_SECRET` / `TI_AZURE_AUTH_CALLBACK_URL` / `TI_AZURE_AUTH_DISCOVERY_URL`, and the `TI_GCLOUD_AUTH_*` equivalents. A callback URL may be given either as the full absolute URL registered with the provider (`https://your-host/login/azure-callback`) or as a path (`/login/azure-callback`): the server always listens on the path, while the `redirect_uri` sent to the provider is the absolute value verbatim if one was configured, and otherwise assembled from the request's forwarded protocol/host.
 
 ## Configure HTTPS 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/web-server.js

@@ -516,12 +516,18 @@ class TiWebServer extends ServiceConsumer {
         this.#webServer.post( "/logout", webHandlers.logoutHandler() );
         this.#webServer.get( "/health", webHandlers.healthHandler() );
         this.#webServer.get( "/me", webHandlers.userInformationHandler() );
-        if ( this.#authManager.isAuthEnabled( authMethod.OPENID_GOOGLE ) ) {
-            this.#webServer.get( this.#authManager.getOAuth2CallbackUrl( authMethod.OPENID_GOOGLE ), webHandlers.authorizedOAuth2CallbackHandler( this, authMethod.OPENID_GOOGLE ) );
-        }
-        if ( this.#authManager.isAuthEnabled( authMethod.OPENID_AZURE ) ) {
-            this.#webServer.get( this.#authManager.getOAuth2CallbackUrl( authMethod.OPENID_AZURE ), webHandlers.authorizedOAuth2CallbackHandler( this, authMethod.OPENID_AZURE ) );
-        }
+        // NOTE: A callback is registered by its path, never by the configured value verbatim — that value is commonly
+        // the absolute URL registered with the identity provider, which Express cannot parse as a route pattern.
+        [ authMethod.OPENID_GOOGLE, authMethod.OPENID_AZURE ].forEach( ( method ) => {
+            if ( this.#authManager.isAuthEnabled( method ) === true ) {
+                const callbackPath = this.#authManager.getOAuth2CallbackPath( method );
+                if ( callbackPath ) {
+                    this.#webServer.get( callbackPath, webHandlers.authorizedOAuth2CallbackHandler( this, method ) );
+                } else {
+                    logger.log( `Authentication method '${ method }' is enabled but its callback URL yields no usable route path; its callback endpoint was not registered and sign-in through it will fail.`, logger.logSeverity.WARNING );
+                }
+            }
+        } );
 
         // Admin configuration-management API. Gated by the admin role; these paths are not in the unprotected-routes
         // list, so they also inherit the server's global authentication + CSRF middleware.
@@ -623,7 +629,10 @@ class TiWebServer extends ServiceConsumer {
 
     /**
      * Normalizes an HTTP method to a lower-case Express routing verb, or returns null if it is not a supported,
-     * registrable verb. Pure and static; exposed for unit testing — not part of the customization surface.
+     * registrable verb. Anything that is not a string is rejected outright rather than coerced — otherwise a value
+     * whose `toString()` happens to yield a verb (`[ "get" ]`, `new String( "get" )`) would register a route and
+     * bypass the `E_GEN_INVALID_ARGUMENT_TYPE` that {@link TiWebServer#registerRoute} raises for a bad method.
+     * Pure and static; exposed for unit testing — not part of the customization surface.
      *
      * @method
      * @static
@@ -632,7 +641,10 @@ class TiWebServer extends ServiceConsumer {
      * @public
      */
     static normalizeRegistrableMethod( method ) {
-        const verb = String( method || "" ).trim().toLowerCase();
+        if ( typeof method !== "string" ) {
+            return null;
+        }
+        const verb = method.trim().toLowerCase();
         return TiWebServer.#REGISTRABLE_METHODS.has( verb ) ? verb : null;
     }
 

package/components/auth-manager.js

@@ -226,6 +226,51 @@ class AuthManager {
         }
     }
 
+    /**
+     * Used to get the local route path of the callback for the specified OAuth2 authentication method.
+     * <br/>
+     * A callback can legitimately be configured either as a path or as the full absolute URL registered with the
+     * identity provider. The absolute form is what the provider expects as the redirect URI, but it is not a usable
+     * Express route pattern, so this reduces whatever is configured to the path the server must actually listen on.
+     *
+     * @method
+     * @param {TiAuthMethod} authMethod
+     * @returns {string|null} The route path, or null if the configured callback yields no usable path.
+     * @throws {TiException.E_SEC_UNRECOGNIZED_AUTH_METHOD} If the requested OAuth2 method is not recognized or enabled.
+     * @public
+     */
+    getOAuth2CallbackPath( authMethod ) {
+        return AuthManager.toCallbackPath( this.getOAuth2CallbackUrl( authMethod ) );
+    }
+
+    /**
+     * Reduces a configured OAuth2 callback value to the local route path it corresponds to. Accepts an absolute URL
+     * ('https://host/login/azure-callback'), a protocol-relative URL, or a path with or without its leading slash,
+     * and strips any query string or fragment. Pure and static; exposed for unit testing.
+     * <br/>
+     * NOTE: This exists because Express 5 parses a route pattern with path-to-regexp v8, where ':' opens a parameter
+     * name — so an absolute URL used verbatim as a route path throws 'Missing parameter name' at startup.
+     *
+     * @method
+     * @static
+     * @param {string} callbackUrl
+     * @returns {string|null} The route path, or null if no usable path can be derived.
+     * @public
+     */
+    static toCallbackPath( callbackUrl ) {
+        const value = String( callbackUrl || "" ).trim();
+        if ( value === "" ) {
+            return null;
+        }
+        try {
+            // The base is only a parsing anchor — an absolute or protocol-relative value overrides it, while a
+            // path or bare relative value resolves against it. Either way only the pathname is used.
+            return new URL( value, "http://localhost" ).pathname;
+        } catch {
+            return null;
+        }
+    }
+
     /* Private interface */
 
     /**

package/components/config-registry.js

@@ -41,9 +41,23 @@ const instancePathToDataPath = ( instancePath ) => {
  */
 
 /**
- * @typedef {function(Object, Object): (ConfigValidationIssue[]|Promise<ConfigValidationIssue[]>)} SemanticValidator
- * A semantic validator receives the candidate value and a context object (e.g. `{ getConfig(key) }` to read other
- * current configs for cross-document checks) and returns the issues it found (empty array = OK). May be async.
+ * The cross-document read context passed to every {@link SemanticValidator}, built fresh for each
+ * {@link ConfigService#applyEdits} call.
+ *
+ * @typedef {Object} ValidatorContext
+ * @property {function(string): Promise<*>} getConfig Resolves the *pending* value of `key` when it is part of the
+ *      current edit batch, otherwise its current committed value. Lets a validator check a sibling document's
+ *      post-edit state — but calling this for the document being validated itself just returns the same incoming
+ *      value already passed as the validator's first argument, not its prior state.
+ * @property {function(string): Promise<*>} getStoredConfig Always resolves the current committed value of `key`,
+ *      even when `key` is the document currently under validation. Use this to compare a document against its own
+ *      previous state (e.g. detecting an edit that should have bumped a version marker).
+ */
+
+/**
+ * @typedef {function(Object, ValidatorContext): (ConfigValidationIssue[]|Promise<ConfigValidationIssue[]>)} SemanticValidator
+ * A semantic validator receives the candidate value and a {@link ValidatorContext} and returns the issues it found
+ * (empty array = OK). May be async.
  */
 
 /**
@@ -163,7 +177,7 @@ class ConfigRegistry {
      * @method
      * @param {string} configKey
      * @param {Object} value
-     * @param {Object} [context] Passed to each semantic validator (e.g. `{ getConfig(key) }`).
+     * @param {ValidatorContext} [context] Passed to each semantic validator.
      * @returns {Promise<{valid: boolean, errors: ConfigValidationIssue[]}>}
      * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
      * @public

package/components/config-service.js

@@ -13,9 +13,11 @@ const exceptions = require( "@ti-engine/core/exceptions" );
  *
  * Two layers:
  *  - **Document level** — {@link ConfigService#applyEdits}: validate every affected document (schema + semantic,
- *    with a cross-document context that sees the *pending* values of the same edit) and, only if all pass, commit
- *    them as one change-set. Validation failures return `{ ok:false, errors }` and write nothing; a version
- *    conflict from the store surfaces as a rejection.
+ *    with a cross-document {@link ValidatorContext} whose `getConfig` sees the *pending* values of the same edit —
+ *    letting a validator check a sibling document's post-edit state — while `getStoredConfig` always returns the
+ *    committed value, even for the document currently under validation) and, only if all pass, commit them as one
+ *    change-set. Validation failures return `{ ok:false, errors }` and write nothing; a version conflict from the
+ *    store surfaces as a rejection.
  *  - **Entity level** — composite editors registered with `compose(docs)→view` / `decompose(edited, docs)→{key:value}`,
  *    so the UI edits a domain entity (e.g. a "competency") that is projected from, and scattered back into, several
  *    documents. {@link ConfigService#saveEditorEdit} decomposes the edit and routes it through `applyEdits`.
@@ -61,8 +63,13 @@ class ConfigService {
             return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "invalid-apply-input" } ) );
         }
 
-        // Cross-document validation context: a document being edited is seen at its *pending* value; others are read
-        // from the store. This lets a validator on one document check against the post-edit state of its siblings.
+        // Cross-document validation context: a document being edited is seen at its *pending* value via getConfig —
+        // even when that document is the one currently under validation, so calling getConfig on "yourself" just
+        // hands back the same incoming value already passed as the validator's first argument, not its prior state.
+        // This lets a validator on one document check against the post-edit state of its siblings. getStoredConfig
+        // is the counterpart: it always resolves the committed value, so a validator that must compare its own
+        // document against its previous state (e.g. detecting an edit that should have bumped a version marker)
+        // uses that instead.
         const pending = {};
         for ( const edit of edits ) {
             pending[ edit.configKey ] = edit.value;
@@ -73,7 +80,11 @@ class ConfigService {
                     return Promise.resolve( clone( pending[ key ] ) );
                 }
                 return this.#store.getCurrent( key ).then( ( current ) => ( current ? current.value : null ) );
-            }
+            },
+            // Always the committed value, even for a document inside this edit batch. A validator comparing its own
+            // document against its previous state must use this; getConfig would hand back the pending value it is
+            // currently validating.
+            getStoredConfig: ( key ) => this.#store.getCurrent( key ).then( ( current ) => ( current ? current.value : null ) )
         };
 
         return Promise.all( edits.map( ( edit ) => {

package/components/web-config-env.js

@@ -1,64 +1,68 @@
-/*
- * 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, the session cookie secret, the enabled authentication
- * methods, and the trusted request origins without editing config files. Note `TI_WEB_AUTH_METHODS` and
- * `TI_WEB_TRUSTED_ORIGINS` fully REPLACE their config arrays (`auth.enabledMethods` / `trustedOrigins`) rather than
- * merging — the config-file merge is by-index and cannot cleanly override an array.
- *
- * @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;
-    }
-    if ( env.TI_WEB_AUTH_METHODS !== undefined ) {
-        config.auth = config.auth || {};
-        config.auth.enabledMethods = env.TI_WEB_AUTH_METHODS.split( "," ).map( ( method ) => method.trim() ).filter( ( method ) => method.length > 0 );
-    }
-    if ( env.TI_WEB_TRUSTED_ORIGINS !== undefined ) {
-        config.trustedOrigins = env.TI_WEB_TRUSTED_ORIGINS.split( "," ).map( ( origin ) => origin.trim() ).filter( ( origin ) => origin.length > 0 );
-    }
-    return config;
-}
-
-module.exports = applyWebConfigEnvOverrides;
+/*
+ * 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, the session cookie secret, the enabled authentication
+ * methods, the admin allowlist, and the trusted request origins without editing config files. Note `TI_WEB_AUTH_METHODS`,
+ * `TI_WEB_AUTH_ADMINS`, and `TI_WEB_TRUSTED_ORIGINS` fully REPLACE their config arrays (`auth.enabledMethods` / `auth.admins` / `trustedOrigins`) rather than
+ * merging — the config-file merge is by-index and cannot cleanly override an array.
+ *
+ * @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;
+    }
+    if ( env.TI_WEB_AUTH_METHODS !== undefined ) {
+        config.auth = config.auth || {};
+        config.auth.enabledMethods = env.TI_WEB_AUTH_METHODS.split( "," ).map( ( method ) => method.trim() ).filter( ( method ) => method.length > 0 );
+    }
+    if ( env.TI_WEB_AUTH_ADMINS !== undefined ) {
+        config.auth = config.auth || {};
+        config.auth.admins = env.TI_WEB_AUTH_ADMINS.split( "," ).map( ( entry ) => entry.trim() ).filter( ( entry ) => entry.length > 0 );
+    }
+    if ( env.TI_WEB_TRUSTED_ORIGINS !== undefined ) {
+        config.trustedOrigins = env.TI_WEB_TRUSTED_ORIGINS.split( "," ).map( ( origin ) => origin.trim() ).filter( ( origin ) => origin.length > 0 );
+    }
+    return config;
+}
+
+module.exports = applyWebConfigEnvOverrides;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.17.0",
+  "version": "1.18.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",