@ti-engine/web-framework 1.18.1 → 1.19.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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.19.0
+
+`/static` was served with `max-age=1y, immutable` for every consumer of the framework. `immutable` is a promise that the bytes behind a URL will never change, and browsers honour it so completely that not even a manual reload revalidates — so the promise is only true for a content-addressed URL (`app.a1b2c3.css`). None of the framework's own assets are named that way (`/static/scripts/ti-framework.js`, the theme sheets), which made this an unsafe default that shipped to npm: a deployed CSS or JS fix would never reach anyone who had already visited, for up to a year, with no way to tell them otherwise. The standalone author's site had worked around it privately by fingerprinting its own asset URLs; every other consumer still inherited the bug.
+
+* fix(web-server)!: the default `/static` cache policy is now `public, max-age=0, must-revalidate` instead of `max-age=1y, immutable`, so a deployed asset change actually reaches a returning visitor. `express.static` still attaches an `ETag`/`Last-Modified`, so a revalidation of an unchanged asset is answered with a `304` — headers, no body. **A consumer whose asset filenames are content-addressed should opt back in** with `staticCache: { maxAge: 31536000, immutable: true }`; one that appends a content hash to its asset URLs (rather than to the filenames) is equally entitled to it
+* feat(web-server): add the `staticCache` configuration block — `maxAge` (whole **seconds**, mapping 1:1 onto the `Cache-Control` directive; an express-style `"1y"` duration string is reported rather than silently reinterpreted as milliseconds), `immutable`, and `immutablePaths` (path prefixes served long-lived and `immutable` regardless of the other two). `immutable` combined with a `maxAge` of 0 is a contradiction and is dropped with a warning, so a half-configured deployment costs a revalidation rather than a year of unreachable assets
+* feat(web-server): `staticCache.immutablePaths` defaults to `[ "/fonts/" ]` — a released `.woff2` is an artifact rather than something edited in place, and its filename already carries the family, weight and style. Configurable, and clearable with an explicitly empty array, because that is a statement about how a given deployment manages its font files
+* feat(web-framework): add the `TI_WEB_STATIC_MAX_AGE`, `TI_WEB_STATIC_IMMUTABLE`, and `TI_WEB_STATIC_IMMUTABLE_PATHS` environment overrides, so the cache policy is settable per deployment like every other web setting; `TI_WEB_STATIC_IMMUTABLE_PATHS` **replaces** the array, and an explicitly empty value means no long-lived paths
+* refactor(web-server): the `/static` mounts write `Cache-Control` per file through `express.static`'s `setHeaders` rather than its `maxAge`/`immutable` options, since the policy is no longer uniform across the tree; the decision itself lives in the pure, unit-tested `TiWebServer.resolveStaticCachePolicy()` (config → policy + warnings, which the caller logs) and `TiWebServer.staticCacheControlFor()` (policy + file → header). The `staticCache` defaults deliberately live on the class rather than in `web-server.json`, because the constructor's `_.merge` merges arrays by index and a consumer's empty `immutablePaths` could otherwise never clear a default entry
+* docs(web-framework): document the `staticCache` block, the revalidating default and the reasoning behind it, and the fingerprinting opt-in in the README
+* build(release): bump package version from `1.18.1` to `1.19.0`
+
 ## 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).

package/README.md

@@ -20,9 +20,42 @@ The web server configuration (host, port, TLS, cookies, etc.) is normally provid
 * `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.
+* `TI_WEB_STATIC_MAX_AGE` (whole seconds) overrides `staticCache.maxAge`. See [Static asset caching](#static-asset-caching).
+* `TI_WEB_STATIC_IMMUTABLE` (`true`/`false`) overrides `staticCache.immutable`.
+* `TI_WEB_STATIC_IMMUTABLE_PATHS` (comma-separated) **replaces** `staticCache.immutablePaths`. An explicitly empty value means *no long-lived paths*.
 
 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.
 
+## Static asset caching
+
+Everything under `/static` is served with a `Cache-Control` policy configured by the `staticCache` block:
+
+```json
+{
+  "staticCache": {
+    "maxAge": 0,
+    "immutable": false,
+    "immutablePaths": [ "/fonts/" ]
+  }
+}
+```
+
+* `maxAge` — the `max-age` in **whole seconds** (not an express-style `"1y"` duration string; one is rejected with a warning rather than reinterpreted as milliseconds). `0`, the default, emits `public, max-age=0, must-revalidate`.
+* `immutable` — adds the `immutable` directive. Defaults to `false`, and is **ignored with a warning when `maxAge` is 0**, since a response that is stale on arrival cannot also promise never to change.
+* `immutablePaths` — path prefixes under `/static` (matched case-sensitively, on a path-segment boundary) served `public, max-age=31536000, immutable` regardless of the two settings above. Defaults to `[ "/fonts/" ]`. This **replaces** rather than merges, so `[]` means no long-lived paths.
+
+**The default revalidates, and that is deliberate.** `immutable` tells a browser the bytes behind a URL will never change, and browsers honour it so completely that not even a manual reload revalidates. On a stable filename — which is what the framework's own assets use (`/static/scripts/ti-framework.js`, the theme sheets) — the promise is false, and a deployed CSS or JS fix simply never reaches anyone who has already visited, for up to a year, with no way to tell them otherwise. Revalidating costs a conditional request per asset, answered with a `304` from the `ETag`/`Last-Modified` that `express.static` still attaches — headers, no body.
+
+**Opt back into `immutable` once your filenames are content-addressed.** If your build emits `app.a1b2c3.css`, or your application appends a content hash to each asset URL, the promise becomes true and there is real value in making it:
+
+```json
+{
+  "staticCache": { "maxAge": 31536000, "immutable": true }
+}
+```
+
+Fonts are the default exception because a released `.woff2` is an artifact rather than something edited in place, and its filename already carries the family, weight and style. If that is not how a given deployment manages its fonts, clear the list.
+
 ## 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/web-server.js

@@ -39,6 +39,7 @@ const applyWebConfigEnvOverrides = require( "#web-config-env" );
  * @property {number} port
  * @property {string} publicPath
  * @property {number} requestTimeout
+ * @property {SettingsStaticCache} staticCache
  * @property {string} tlsCertPath
  * @property {string} tlsKeyPath
  * @property {boolean} useTLS
@@ -75,6 +76,13 @@ const applyWebConfigEnvOverrides = require( "#web-config-env" );
  * @property {TiTokenEndpointAuthMethod} [tokenEndpointAuthMethod]
  */
 
+/**
+ * @typedef {Object} SettingsStaticCache
+ * @property {number} maxAge The `max-age` for `/static` responses, in SECONDS (not a duration string). `0` means every use is revalidated.
+ * @property {boolean} immutable Whether to add `immutable`. Only correct when the `/static` filenames are content-addressed.
+ * @property {string[]} immutablePaths Path prefixes under `/static` that are served long-lived and `immutable` regardless of the two settings above.
+ */
+
 /**
  * @typedef {Object} SettingsCookies
  * @property {string} secret
@@ -310,8 +318,20 @@ class TiWebServer extends ServiceConsumer {
                 this.#webServer.use( "/.well-known", express.static( path.join( this.#staticContentPaths[ 0 ], ".well-known" ), { dotfiles: "allow" } ) );
 
                 // Static content routes are registered in reverse order to ensure that custom assets can override the default ones and be served first:
+                const staticCachePolicy = TiWebServer.resolveStaticCachePolicy( this.serviceConfig.staticCache );
+                staticCachePolicy.warnings.forEach( ( warning ) => logger.log( warning, logger.logSeverity.WARNING ) );
                 _.forEachRight( this.#staticContentPaths, ( staticContentPath ) => {
-                    this.#webServer.use( "/static", express.static( staticContentPath, { maxAge: "1y", immutable: true } ) );
+                    // `Cache-Control` is written per file rather than through express.static's `maxAge`/`immutable`
+                    // options, because the policy is not uniform across the tree (see resolveStaticCachePolicy). A
+                    // header set here wins: `send` emits its "headers" event BEFORE its own `Cache-Control` block,
+                    // which then skips a header that is already present. `ETag`/`Last-Modified` are still added by
+                    // `send`, so the revalidating default costs a conditional request answered with a 304, not a
+                    // re-download.
+                    this.#webServer.use( "/static", express.static( staticContentPath, {
+                        setHeaders: ( response, filePath ) => {
+                            response.setHeader( "Cache-Control", TiWebServer.staticCacheControlFor( staticContentPath, filePath, staticCachePolicy ) );
+                        }
+                    } ) );
                 } );
 
                 // Set up the web application routes:
@@ -627,6 +647,178 @@ class TiWebServer extends ServiceConsumer {
      */
     static #REGISTRABLE_METHODS = new Set( [ "get", "post", "put", "patch", "delete", "options", "head", "all" ] );
 
+    /**
+     * The default `/static` cache policy: revalidate every use, with a long-lived exception for web fonts.
+     * <br/>
+     * The default used to be `max-age=1y, immutable`, which was wrong for every consumer that does not hash its asset
+     * filenames — and none of them do by default, since the framework's own assets ship under stable names
+     * (`/static/scripts/ti-framework.js`, the theme sheets, …). `immutable` promises that the bytes behind THIS URL
+     * will never change, and browsers honour it so completely that not even a manual reload revalidates: a deployed
+     * CSS or JS fix would simply never reach anyone who had already visited, for up to a year, with no way to tell
+     * them otherwise. Revalidating is the only default that is true for a stable filename; `send` still attaches an
+     * `ETag`/`Last-Modified`, so the cost is a conditional request answered with a 304, not a re-download.
+     * <br/>
+     * A consumer that fingerprints its filenames (`app.a1b2c3.css`) makes the promise true and should opt back in via
+     * `staticCache: { maxAge: 31536000, immutable: true }`.
+     * <br/>
+     * NOTE: These defaults deliberately live here rather than in `web-server.json`, because the constructor merges the
+     * service config with `_.merge`, which merges arrays BY INDEX — a consumer's `immutablePaths: []` could then never
+     * clear a default entry. Absent from the config file, an explicitly empty array means exactly that.
+     *
+     * @type {Object}
+     * @private
+     */
+    static #STATIC_CACHE_DEFAULTS = Object.freeze( {
+        maxAge: 0,
+        immutable: false,
+        // Fonts are the one genuinely content-addressed-in-practice class under `/static`: a released `.woff2` is an
+        // artifact, not something that gets edited in place, and its filename already carries the family, weight and
+        // style. Configurable, because that is a statement about how a given deployment manages its font files.
+        immutablePaths: Object.freeze( [ "/fonts/" ] )
+    } );
+
+    /**
+     * The `max-age` applied to a path matched by `staticCache.immutablePaths`, in seconds (one year — the longest
+     * value any cache treats as meaningful, and the conventional pairing for `immutable`).
+     *
+     * @type {number}
+     * @private
+     */
+    static #IMMUTABLE_MAX_AGE = 31536000;
+
+    /**
+     * Normalizes an `immutablePaths` entry to a rooted, slash-terminated prefix (`fonts` -> `/fonts/`), or null when
+     * it is not usable. The trailing slash is what keeps `/fonts` from also matching `/fonts-legacy/a.woff2`.
+     *
+     * @method
+     * @static
+     * @param {string} entry
+     * @returns {string|null}
+     * @private
+     */
+    static #normalizeImmutablePath( entry ) {
+        if ( typeof entry !== "string" || entry.trim() === "" ) {
+            return null;
+        }
+        const trimmed = entry.trim();
+        const rooted = trimmed.startsWith( "/" ) ? trimmed : "/" + trimmed;
+        return rooted.endsWith( "/" ) ? rooted : rooted + "/";
+    }
+
+    /**
+     * Derives the served path of a static file (the part after the `/static` mount, always slash-separated) from the
+     * directory it is served out of and its absolute location on disk. A file resolving outside the root yields a
+     * `/../`-prefixed path, which matches no normalized prefix and therefore falls back to the default policy.
+     *
+     * @method
+     * @static
+     * @param {string} rootPath
+     * @param {string} filePath
+     * @returns {string}
+     * @private
+     */
+    static #toServedPath( rootPath, filePath ) {
+        // Split on the platform separator only: on POSIX a backslash is a legal filename character, not a delimiter.
+        return "/" + path.relative( String( rootPath || "" ), String( filePath || "" ) ).split( path.sep ).join( "/" );
+    }
+
+    /**
+     * Resolves a `staticCache` configuration block into the policy the `/static` mounts apply, filling in
+     * {@link TiWebServer.#STATIC_CACHE_DEFAULTS} per key and rejecting values that cannot be honored. Pure: problems
+     * are returned as `warnings` rather than logged, so the caller decides how to surface them and a test can assert
+     * on them. Static and exposed for unit testing — not part of the customization surface.
+     * <br/>
+     * `maxAge` is a whole number of SECONDS, mapping 1:1 onto the `Cache-Control` directive — express's `"1y"`-style
+     * duration strings are NOT accepted, and are reported rather than silently reinterpreted as milliseconds.
+     * <br/>
+     * `immutable` is dropped (with a warning) when `maxAge` is 0, because a response that is stale on arrival yet
+     * promises never to change is a contradiction. Dropping it fails safe: the misconfiguration costs a revalidation,
+     * not a year of unreachable assets.
+     *
+     * @method
+     * @static
+     * @param {SettingsStaticCache} [staticCache] The configured block, if any.
+     * @returns {{maxAge: number, immutable: boolean, immutablePaths: string[], warnings: string[]}}
+     * @public
+     */
+    static resolveStaticCachePolicy( staticCache ) {
+        const defaults = TiWebServer.#STATIC_CACHE_DEFAULTS;
+        const config = _.isObjectLike( staticCache ) ? staticCache : {};
+        const warnings = [];
+
+        let maxAge = defaults.maxAge;
+        if ( config.maxAge !== undefined ) {
+            if ( Number.isInteger( config.maxAge ) && config.maxAge >= 0 ) {
+                maxAge = config.maxAge;
+            } else {
+                warnings.push( `Ignored an invalid 'staticCache.maxAge' value of '${ config.maxAge }'; it must be a whole, non-negative number of seconds (a duration string such as '1y' is not accepted). Using ${ defaults.maxAge } instead.` );
+            }
+        }
+
+        let immutable = defaults.immutable;
+        if ( config.immutable !== undefined ) {
+            if ( typeof config.immutable === "boolean" ) {
+                immutable = config.immutable;
+            } else {
+                warnings.push( `Ignored a non-boolean 'staticCache.immutable' value of '${ config.immutable }'. Using ${ defaults.immutable } instead.` );
+            }
+        }
+        if ( immutable === true && maxAge === 0 ) {
+            warnings.push( `Ignored 'staticCache.immutable' because 'staticCache.maxAge' is 0 — a response that is stale on arrival cannot also promise never to change. Set a positive 'staticCache.maxAge' (and hash your asset filenames) to serve '/static' as immutable.` );
+            immutable = false;
+        }
+
+        let immutablePaths = defaults.immutablePaths.slice();
+        if ( config.immutablePaths !== undefined ) {
+            if ( Array.isArray( config.immutablePaths ) ) {
+                immutablePaths = [];
+                config.immutablePaths.forEach( ( entry ) => {
+                    const normalized = TiWebServer.#normalizeImmutablePath( entry );
+                    if ( normalized === null ) {
+                        warnings.push( `Ignored an invalid 'staticCache.immutablePaths' entry of type '${ typeof entry }'; expected a non-empty path prefix such as '/fonts/'.` );
+                    } else {
+                        immutablePaths.push( normalized );
+                    }
+                } );
+            } else {
+                warnings.push( `Ignored a non-array 'staticCache.immutablePaths' value of type '${ typeof config.immutablePaths }'. Using the default [ ${ defaults.immutablePaths.join( ", " ) } ] instead.` );
+            }
+        }
+
+        return { maxAge: maxAge, immutable: immutable, immutablePaths: immutablePaths, warnings: warnings };
+    }
+
+    /**
+     * Builds the `Cache-Control` value for one static file: the long-lived immutable policy when its served path sits
+     * under a configured `immutablePaths` prefix (matched case-sensitively, so a case mismatch falls back to the safe
+     * side), otherwise the policy's own `maxAge`/`immutable`. A `maxAge` of 0 is emitted as an explicit
+     * `must-revalidate` rather than a bare `max-age=0`, matching what the sibling `web-content` package serves.
+     * Pure and static; exposed for unit testing — not part of the customization surface.
+     *
+     * @method
+     * @static
+     * @param {string} rootPath The directory this `/static` mount serves.
+     * @param {string} filePath The absolute path of the file being served.
+     * @param {Object} policy A policy as returned by {@link TiWebServer.resolveStaticCachePolicy}.
+     * @returns {string}
+     * @public
+     */
+    static staticCacheControlFor( rootPath, filePath, policy ) {
+        const resolved = _.isObjectLike( policy ) ? policy : {};
+        const immutablePaths = Array.isArray( resolved.immutablePaths ) ? resolved.immutablePaths : [];
+        const servedPath = TiWebServer.#toServedPath( rootPath, filePath );
+
+        if ( immutablePaths.some( ( prefix ) => servedPath.startsWith( prefix ) ) === true ) {
+            return `public, max-age=${ TiWebServer.#IMMUTABLE_MAX_AGE }, immutable`;
+        }
+
+        const maxAge = ( Number.isInteger( resolved.maxAge ) && resolved.maxAge >= 0 ) ? resolved.maxAge : 0;
+        if ( maxAge === 0 ) {
+            return "public, max-age=0, must-revalidate";
+        }
+        return ( resolved.immutable === true ) ? `public, max-age=${ maxAge }, immutable` : `public, max-age=${ maxAge }`;
+    }
+
     /**
      * Normalizes an HTTP method to a lower-case Express routing verb, or returns null if it is not a supported,
      * registrable verb. Anything that is not a string is rejected outright rather than coerced — otherwise a value

package/components/web-config-env.js

@@ -1,68 +1,85 @@
-/*
- * 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;
+/*
+ * 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, the trusted request origins, and the `/static` cache policy without editing config files. Note `TI_WEB_AUTH_METHODS`,
+ * `TI_WEB_AUTH_ADMINS`, `TI_WEB_TRUSTED_ORIGINS`, and `TI_WEB_STATIC_IMMUTABLE_PATHS` fully REPLACE their config arrays (`auth.enabledMethods` / `auth.admins` / `trustedOrigins` / `staticCache.immutablePaths`) 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 );
+    }
+    if ( env.TI_WEB_STATIC_MAX_AGE !== undefined ) {
+        // Seconds, matching the `Cache-Control` directive itself. A non-integer is left to the config value rather
+        // than coerced, exactly as TI_WEB_PORT is — `TiWebServer.resolveStaticCachePolicy` reports the bad value.
+        const maxAge = Number( env.TI_WEB_STATIC_MAX_AGE );
+        if ( Number.isInteger( maxAge ) && maxAge >= 0 ) {
+            config.staticCache = config.staticCache || {};
+            config.staticCache.maxAge = maxAge;
+        }
+    }
+    if ( env.TI_WEB_STATIC_IMMUTABLE !== undefined ) {
+        config.staticCache = config.staticCache || {};
+        config.staticCache.immutable = tools.toBool( env.TI_WEB_STATIC_IMMUTABLE );
+    }
+    if ( env.TI_WEB_STATIC_IMMUTABLE_PATHS !== undefined ) {
+        config.staticCache = config.staticCache || {};
+        config.staticCache.immutablePaths = env.TI_WEB_STATIC_IMMUTABLE_PATHS.split( "," ).map( ( prefix ) => prefix.trim() ).filter( ( prefix ) => prefix.length > 0 );
+    }
+    return config;
+}
+
+module.exports = applyWebConfigEnvOverrides;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.18.1",
+  "version": "1.19.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",
@@ -33,7 +33,7 @@
     "cookie-parser": "^1.4.7",
     "express": "^5.2.1",
     "express-session": "^1.19.0",
-    "helmet": "^8.2.0",
+    "helmet": "^8.3.0",
     "lodash": "^4.18.1",
     "openid-client": "^6.8.4"
   },