@ti-engine/web-framework 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.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.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`
+
+## Version 1.16.0
+
+Support explicitly trusted request origins so state-changing requests (e.g. login) work behind proxies that do not present the app's external host — most notably GitHub Codespaces port forwarding (CA-90).
+
+* feat(web-framework): add `TI_WEB_TRUSTED_ORIGINS` (comma-separated) / `config.trustedOrigins`. The `originRefererValidationHandler` now accepts a non-GET request whose `Origin`/`Referer` matches the server-reconstructed base URL **or** any configured trusted origin. Previously such a request behind a proxy that rewrote/omitted the forwarded host was rejected with `E_WEB_INVALID_REQUEST_PARAMETERS` (HTTP 403). Backward compatible (empty list = prior behavior); the CSRF double-submit token check is unchanged and still enforced
+* build(release): bump package version from `1.15.0` to `1.16.0`
+
 ## Version 1.15.0
 
 A dedicated health endpoint, a `TI_WEB_AUTH_METHODS` env override, and login-page gating for every auth method — completing the container-friendly auth/health story for the competence deployment (CA-90).

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

@@ -301,7 +301,7 @@ class TiWebServer extends ServiceConsumer {
                     store: new SessionStore()
                 } ) );
                 this.#webServer.use( webHandlers.csrfInitHandler( this ) );
-                this.#webServer.use( webHandlers.originRefererValidationHandler() );
+                this.#webServer.use( webHandlers.originRefererValidationHandler( this ) );
                 this.#webServer.use( webHandlers.csrfProtectionHandler() );
 
                 // Set up the web server routes:
@@ -493,21 +493,7 @@ class TiWebServer extends ServiceConsumer {
      */
     isUnprotectedRoute( route ) {
         const pathOnly = String( route || "" ).split( "?" )[ 0 ];
-        let result = false;
-        for ( let idx = 0; idx < this.#unprotectedRoutes.length; idx++ ) {
-            const pattern = this.#unprotectedRoutes[ idx ];
-            if ( _.isRegExp( pattern ) ) {
-                // Avoid stateful RegExp behavior when 'g' or 'y' flags are present:
-                pattern.lastIndex = 0;
-                result = pattern.test( pathOnly );
-            } else {
-                result = ( pattern === pathOnly );
-            }
-            if ( result ) {
-                break;
-            }
-        }
-        return result;
+        return TiWebServer.isRouteInList( this.#unprotectedRoutes, pathOnly );
     }
 
     /**
@@ -574,6 +560,113 @@ class TiWebServer extends ServiceConsumer {
         this.#unprotectedRoutes.push( RE_WELL_KNOWN_UNPROTECTED );
     }
 
+    /**
+     * Registers a custom application route on the underlying Express app.
+     * <br/>
+     * NOTE: Call this from a {@link TiWebServer#defineWebApplicationRoutes} override AFTER invoking the base method,
+     * so the framework's own routes keep priority and any catch-all route you add resolves last (it will still be
+     * registered before the framework's own `*splat` 404 handler). It is only valid once the Express app exists —
+     * i.e., from within {@link TiWebServer#defineWebApplicationRoutes}, which {@link TiWebServer#onStart} invokes.
+     *
+     * @method
+     * @param {string} method One of the supported routing verbs: get, post, put, patch, delete, options, head, all.
+     * @param {string|RegExp} path The route path or pattern.
+     * @param {...Function} handlers One or more Express route handlers/middleware.
+     * @returns {TiWebServer} This instance, to allow chaining.
+     * @public
+     */
+    registerRoute( method, path, ...handlers ) {
+        const verb = TiWebServer.normalizeRegistrableMethod( method );
+        if ( verb === null ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_INVALID_ARGUMENT_TYPE, { method: method } );
+        }
+        if ( !this.#webServer ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_NOT_INITIALIZED, { detail: "registerRoute() called before the Express app was created; call it from a defineWebApplicationRoutes() override." } );
+        }
+        this.#webServer[ verb ]( path, ...handlers );
+        return this;
+    }
+
+    /**
+     * Adds a pattern to the unprotected-routes list — routes that bypass the authentication gate. A string is
+     * matched exactly against the request path; a RegExp is tested against it. Consulted at request time by
+     * {@link TiWebServer#isUnprotectedRoute}.
+     * <br/>
+     * NOTE: Call this from a {@link TiWebServer#defineUnprotectedRoutes} override AFTER invoking the base method, to
+     * extend (rather than replace) the defaults.
+     *
+     * @method
+     * @param {string|RegExp} pattern The exact path (string) or path matcher (RegExp) to treat as unprotected.
+     * @returns {TiWebServer} This instance, to allow chaining.
+     * @public
+     */
+    addUnprotectedRoute( pattern ) {
+        if ( _.isString( pattern ) || _.isRegExp( pattern ) ) {
+            this.#unprotectedRoutes.push( pattern );
+        } else {
+            logger.log( `Ignored an invalid unprotected-route pattern of type '${ typeof pattern }'; expected a string or RegExp.`, logger.logSeverity.WARNING );
+        }
+        return this;
+    }
+
+    /* Static interface */
+
+    /**
+     * The Express routing verbs that {@link TiWebServer#registerRoute} will register. Deliberately limited to
+     * route-scoped methods — `use` (global middleware mounting) is intentionally excluded; add a dedicated seam if
+     * middleware mounting is ever needed.
+     *
+     * @type {Set<string>}
+     * @private
+     */
+    static #REGISTRABLE_METHODS = new Set( [ "get", "post", "put", "patch", "delete", "options", "head", "all" ] );
+
+    /**
+     * 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.
+     *
+     * @method
+     * @static
+     * @param {string} method
+     * @returns {string|null}
+     * @public
+     */
+    static normalizeRegistrableMethod( method ) {
+        const verb = String( method || "" ).trim().toLowerCase();
+        return TiWebServer.#REGISTRABLE_METHODS.has( verb ) ? verb : null;
+    }
+
+    /**
+     * Tests a request path against a list of unprotected-route patterns (string exact-match or RegExp test),
+     * returning true on the first match. A RegExp's `lastIndex` is reset defensively so a stateful 'g'/'y' flag
+     * cannot cause a match to be skipped. Pure and static; shared by {@link TiWebServer#isUnprotectedRoute} and
+     * exposed for unit testing — not part of the customization surface.
+     *
+     * @method
+     * @static
+     * @param {Array<string|RegExp>} patterns
+     * @param {string} pathOnly The request path with any query string already stripped.
+     * @returns {boolean}
+     * @public
+     */
+    static isRouteInList( patterns, pathOnly ) {
+        for ( let idx = 0; idx < patterns.length; idx++ ) {
+            const pattern = patterns[ idx ];
+            let matched;
+            if ( _.isRegExp( pattern ) ) {
+                // Avoid stateful RegExp behavior when 'g' or 'y' flags are present:
+                pattern.lastIndex = 0;
+                matched = pattern.test( pathOnly );
+            } else {
+                matched = ( pattern === pathOnly );
+            }
+            if ( matched === true ) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     /* Private interface */
 
     /**

package/components/web-config-env.js

@@ -1,60 +1,64 @@
-/*
- * 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, and the enabled authentication
- * methods without editing config files. Note `TI_WEB_AUTH_METHODS` fully REPLACES `auth.enabledMethods` (a clean
- * array replacement) 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 );
-    }
-    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, 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;

package/components/web-handlers.js

@@ -690,19 +690,30 @@ module.exports.webAppHandler = ( instance ) => {
  * @returns {ExpressHandler}
  * @public
  */
-module.exports.originRefererValidationHandler = () => {
+module.exports.originRefererValidationHandler = ( instance ) => {
     return ( request, response, next ) => {
         if ( request.method === "GET" || request.method === "HEAD" || request.method === "OPTIONS" ) {
             next();
         } else {
-            const expectedOrigin = getBaseUrl( request );
             const providedOrigin = getRequestOrigin( request );
-            // If the browser didn’t send Origin/Referer (normal for same-origin form POSTs), let CSRF middleware handle protection instead of blocking here:
-            if ( providedOrigin && String( providedOrigin ).trim().toLowerCase() !== String( expectedOrigin ).trim().toLowerCase() ) {
-                logger.log( `Issue identified with origin/referer mismatch. Expected '${ expectedOrigin }', received '${ providedOrigin }'.`, logger.logSeverity.WARNING );
-                next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, null, exceptions.httpCode.C_403 ) );
-            } else {
+            // If the browser didn't send Origin/Referer (normal for same-origin form POSTs), let CSRF middleware handle protection instead of blocking here:
+            if ( !providedOrigin ) {
                 next();
+            } else {
+                // Accept the origin the server reconstructs from the request, plus any explicitly trusted origins
+                // (TI_WEB_TRUSTED_ORIGINS / config.trustedOrigins). The trusted list is needed behind proxies that do
+                // not present the external host to the app (e.g. GitHub Codespaces port forwarding), where the browser
+                // Origin cannot be reconstructed from the forwarded headers.
+                const configured = ( instance && instance.serviceConfig && Array.isArray( instance.serviceConfig.trustedOrigins ) ) ? instance.serviceConfig.trustedOrigins : [];
+                const allowedOrigins = [ getBaseUrl( request ) ].concat( configured );
+                const normalizedProvided = String( providedOrigin ).trim().toLowerCase();
+                const isAllowed = allowedOrigins.some( ( origin ) => String( origin ).trim().toLowerCase() === normalizedProvided );
+                if ( isAllowed ) {
+                    next();
+                } else {
+                    logger.log( `Issue identified with origin/referer mismatch. Received '${ providedOrigin }'; expected one of [ ${ allowedOrigins.join( ", " ) } ].`, logger.logSeverity.WARNING );
+                    next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, null, exceptions.httpCode.C_403 ) );
+                }
             }
         }
     };

package/package.json

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