@ti-engine/web-framework 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -2,11 +2,47 @@
 
 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).
+
+* 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,44 @@ 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.
+* `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
 

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:
@@ -516,12 +536,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.
@@ -621,9 +647,184 @@ 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. 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 +833,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

@@ -15,8 +15,8 @@ const tools = require( "@ti-engine/core/tools" );
  * 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
+ * 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
@@ -55,9 +55,30 @@ function applyWebConfigEnvOverrides( config, env = process.env ) {
         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;
 }
 

package/package.json

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