@ti-engine/web-framework 1.14.1 → 1.16.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.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).
+
+* feat(web-framework): add an unprotected `GET /health` endpoint (`healthHandler`) that returns `200` with `{ status, broker, uptime }` — a purpose-built liveness/readiness probe for container and orchestrator health checks, so probes no longer have to hit the user-facing login route; `broker` reports the Redis connection state
+* feat(web-framework): add the `TI_WEB_AUTH_METHODS` env override (comma-separated) which REPLACES `auth.enabledMethods` — a clean, 12-factor way to select enabled auth methods per deployment (the config-file merge is by-index and cannot cleanly override an array)
+* feat(web-framework): extend login-page auth gating from the OAuth buttons to every method — the `local` credentials form and the "or continue with" divider are now gated too, and a "no method configured" fallback is shown when nothing is enabled, so an SSO-only deployment presents no dead local form
+* build(release): bump package version from `1.14.1` to `1.15.0`
+
 ## Version 1.14.1
 
 Security hardening for the web-server CodeQL findings raised after the scanner was modernized in CA-90 (CA-91).

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

@@ -14,6 +14,7 @@
             <!-- Error message -->
             <div id="ti-error" class="ti-login-error"></div>
 
+            <!--ti-auth-method:local-->
             <!-- Local auth form -->
             <form id="ti-login-form" action="/login/local" method="post" class="ti-login-form">
                 <input type="hidden" name="_csrf" value='{ti-csrf-placeholder}'>
@@ -45,15 +46,18 @@
                     <span x-text-label="interface.default.login.sign-in">Sign In</span>
                 </button>
             </form>
+            <!--/ti-auth-method-->
 
-            <!--ti-auth-oauth-section-->
+            <!--ti-auth-divider-->
             <!-- Divider -->
             <div class="ti-login-divider">
                 <div class="ti-login-divider-line"></div>
                 <span class="ti-login-divider-label">or continue with</span>
                 <div class="ti-login-divider-line"></div>
             </div>
+            <!--/ti-auth-divider-->
 
+            <!--ti-auth-social-->
             <!-- Social auth -->
             <div class="ti-login-social">
                 <!--ti-auth-method:openid-google-->
@@ -79,7 +83,12 @@
                 </a>
                 <!--/ti-auth-method-->
             </div>
-            <!--/ti-auth-oauth-section-->
+            <!--/ti-auth-social-->
+
+            <!--ti-auth-none-->
+            <!-- Shown only when no authentication method is enabled/configured. -->
+            <div class="ti-login-empty">No sign-in method is configured. Please contact your administrator.</div>
+            <!--/ti-auth-none-->
         </div>
 
         <!-- TEMPORARY: Test user selector for augmentSession() experimentation. Remove once AD-driven identity is wired up. -->

package/bin/web-app-manager.js

@@ -21,7 +21,8 @@ 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;
+const ALL_METHODS = [ "local", "openid-google", "openid-azure" ];
+const RE_AUTH_MARKERS = /<!--\/?ti-auth-(?:divider|social|none|method(?::[a-z-]+)?)-->/g;
 
 /**
  * Removes every `<openMarker>…<closeMarker>` span (inclusive) from `html` in a single linear pass. The markers are
@@ -57,12 +58,15 @@ function stripMarkerSpans( html, openMarker, closeMarker ) {
 }
 
 /**
- * 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.
+ * Gates the login-page authentication markup to the effective enabled methods. The login fragment delimits blocks
+ * with HTML-comment markers: `<!--ti-auth-method:METHOD-->…<!--/ti-auth-method-->` around each method's control
+ * (the `local` credentials form and each OpenID provider button), `<!--ti-auth-divider-->…<!--/ti-auth-divider-->`
+ * around the "or continue with" separator, `<!--ti-auth-social-->…<!--/ti-auth-social-->` around the SSO button
+ * group, and `<!--ti-auth-none-->…<!--/ti-auth-none-->` around a "no method configured" fallback. It removes the
+ * block for any method that is not enabled, drops the social group when no SSO provider is enabled, shows the
+ * divider only when a local form AND at least one SSO provider are both present, and shows the fallback only when
+ * nothing is enabled. 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.
@@ -71,18 +75,31 @@ function stripMarkerSpans( html, openMarker, closeMarker ) {
 function applyAuthMethodVisibility( html, enabledMethods ) {
     let result = String( html );
     const enabled = Array.isArray( enabledMethods ) ? enabledMethods : [];
+    const localEnabled = enabled.includes( "local" );
+    const anyOAuth = OAUTH_METHODS.some( ( method ) => enabled.includes( method ) );
 
-    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 ) => {
+    // Drop the block for each authentication method that is not enabled.
+    ALL_METHODS.forEach( ( method ) => {
         if ( !enabled.includes( method ) ) {
             result = stripMarkerSpans( result, "<!--ti-auth-method:" + method + "-->", "<!--/ti-auth-method-->" );
         }
     } );
+
+    // Drop the SSO button group when no OpenID provider is enabled.
+    if ( !anyOAuth ) {
+        result = stripMarkerSpans( result, "<!--ti-auth-social-->", "<!--/ti-auth-social-->" );
+    }
+
+    // Show the "or continue with" divider only when BOTH a local form and at least one SSO provider are present.
+    if ( !( localEnabled && anyOAuth ) ) {
+        result = stripMarkerSpans( result, "<!--ti-auth-divider-->", "<!--/ti-auth-divider-->" );
+    }
+
+    // Show the "no method configured" fallback only when nothing is enabled.
+    if ( localEnabled || anyOAuth ) {
+        result = stripMarkerSpans( result, "<!--ti-auth-none-->", "<!--/ti-auth-none-->" );
+    }
+
     return result.replace( RE_AUTH_MARKERS, "" );
 }
 

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:
@@ -528,6 +528,7 @@ class TiWebServer extends ServiceConsumer {
         this.#webServer.get( "/login/:method", webHandlers.authenticationHandler( this ) );
         this.#webServer.post( "/login/:method", webHandlers.authenticationHandler( this ) );
         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 ) );
@@ -568,6 +569,7 @@ class TiWebServer extends ServiceConsumer {
         this.#unprotectedRoutes.push( "/app/config" );
         this.#unprotectedRoutes.push( /^\/login\/[^/]+$/i );
         this.#unprotectedRoutes.push( "/logout" );
+        this.#unprotectedRoutes.push( "/health" );
         this.#unprotectedRoutes.push( RE_STATIC_UNPROTECTED );
         this.#unprotectedRoutes.push( RE_WELL_KNOWN_UNPROTECTED );
     }

package/components/web-config-env.js

@@ -14,7 +14,10 @@ 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.
+ * 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).
@@ -48,6 +51,13 @@ function applyWebConfigEnvOverrides( config, env = process.env ) {
         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;
 }
 

package/components/web-handlers.js

@@ -13,6 +13,7 @@ const { randomBytes, timingSafeEqual } = require( "node:crypto" );
 const URL = require( "node:url" ).URL;
 const _ = require( "lodash" );
 const helmet = require( "helmet" );
+const cache = require( "@ti-engine/core/cache" );
 const authMethod = require( "#auth-manager" ).authMethod;
 const authorization = require( "#authorization" );
 
@@ -372,6 +373,29 @@ module.exports.logoutHandler = () => {
     };
 };
 
+/**
+ * Handler for a lightweight, unauthenticated health probe. Responds `200` whenever the web server is serving
+ * (a liveness signal for container/orchestrator probes), and reports the message-broker (Redis) connection state
+ * in the body so it can double as a readiness signal without hitting a user-facing route like the login page.
+ *
+ * @method
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.healthHandler = () => {
+    return ( request, response ) => {
+        const broker = ( cache.instance && cache.instance.isOperational === true ) ? "connected" : "disconnected";
+        response.status( exceptions.httpCode.C_200 ).send( {
+            isSuccessful: true,
+            data: {
+                status: "ok",
+                broker: broker,
+                uptime: Math.round( process.uptime() )
+            }
+        } );
+    };
+};
+
 /**
  * Handler for retrieving authenticated user information.
  *
@@ -666,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.14.1",
+  "version": "1.16.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",