@ti-engine/web-framework 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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.27.0
+
+Session lifetime. Two defects that together threw a signed-in user out roughly ten minutes after sign-in, however
+hard they were working.
+
+* fix(web-server): `cookies.maxAge` was `604800` — seven days expressed in **seconds**, written into a field
+  express-session reads as **milliseconds** (`set maxAge(ms)`). Every session therefore lasted 604.8 seconds. The
+  value is now `28800000`: eight hours, in the unit the field actually takes.
+* fix(web-server): enable `rolling: true`, making the window slide with use. express-session re-sends the cookie
+  only when the session is new, when `rolling` is on, or when the session data itself changed
+  (`shouldSetCookie`) — and nothing changes it after sign-in, since `augmentSession` runs once inside
+  `regenerateAndSaveSession` and the CSRF handler writes its token only when absent. The limit was therefore
+  absolute from sign-in rather than an idle timeout. The store side was never the problem: `SessionStore.touch`
+  slid the Redis TTL correctly the whole time, which is precisely why the fault was invisible from the server —
+  the browser was dropping an expired cookie the server still considered live. `resave: false` is unchanged, so
+  this adds no store writes.
+* feat(config): `TI_WEB_SESSION_IDLE_TIMEOUT` overrides the idle window, in whole **minutes**. The unit is named in
+  the variable and converted internally, so the confusion above is not expressible through it. A non-integer or
+  non-positive value is ignored, leaving the config value standing — the same posture as `TI_WEB_STATIC_MAX_AGE`.
+
+Note for consumers choosing a value: a rolling window is refreshed by requests, and a browser filling in a form
+makes none. Set it longer than the longest uninterrupted form-filling sitting your application expects, or that
+user loses unsaved work when they finally submit.
+
 ## Version 1.26.0
 
 * feat(config-management): report stored documents that no longer satisfy their registered schema.

package/README.md

@@ -17,6 +17,7 @@ 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_SESSION_IDLE_TIMEOUT` (whole minutes) sets how long a signed-in session survives **without activity**, overriding `cookies.maxAge`. The window is rolling: every response re-stamps the cookie, so a session ends only after that long with no request at all. Note that a user typing into a form makes no requests, so set this comfortably longer than the longest form a user fills in one sitting. Defaults to 480 (eight hours).
 * `TI_WEB_AUTH_METHODS` (comma-separated) **replaces** the enabled authentication methods (`auth.enabledMethods`), e.g. `openid-google` or `local,openid-google`.
 * `TI_WEB_AUTH_LOCAL_USERS_PATH` overrides the local user directory's file path (`auth.local.usersPath`), which backs `local` sign-in. An explicitly empty value means *no directory*, so every local sign-in is refused. See [Local (username/password) authentication](#local-usernamepassword-authentication).
 * `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*.

package/bin/web-server.js

@@ -319,6 +319,15 @@ class TiWebServer extends ServiceConsumer {
                     secret: this.serviceConfig.cookies.secret || randomBytes( 32 ).toString( "base64" ),
                     resave: false,
                     saveUninitialized: false,
+                    // Slide the window with use, rather than expiring a fixed interval after sign-in. Without this,
+                    // express-session re-sends the cookie only when the session data itself changes
+                    // (`shouldSetCookie`), and nothing changes it after login — `augmentSession` runs once inside
+                    // `regenerateAndSaveSession`, and the CSRF handler writes its token only when absent. The cookie
+                    // was therefore stamped at sign-in and never refreshed: an absolute limit that expired people
+                    // mid-task however hard they were working. `resave: false` keeps the store write-free; the
+                    // session's TTL there is kept alive by `SessionStore.touch`, which express-session calls per
+                    // request.
+                    rolling: true,
                     cookie: {
                         path: this.serviceConfig.cookies.path,
                         httpOnly: this.serviceConfig.cookies.httpOnly,

package/bin/web-server.json

@@ -39,7 +39,7 @@
     "path": "/",
     "httpOnly": true,
     "sameSite": "lax",
-    "maxAge": 604800
+    "maxAge": 28800000
   },
   "host": "127.0.0.1",
   "language": "en",

package/components/web-config-env.js

@@ -60,6 +60,17 @@ function applyWebConfigEnvOverrides( config, env = process.env ) {
         config.cookies = config.cookies || {};
         config.cookies.secret = env.TI_WEB_COOKIE_SECRET;
     }
+    if ( env.TI_WEB_SESSION_IDLE_TIMEOUT !== undefined ) {
+        // MINUTES, because that is the unit a deployment actually reasons in — and because the millisecond field it
+        // feeds is what went wrong here in the first place: `604800` was written into `cookies.maxAge` meaning seven
+        // days, and express-session read it as 604800 MILLISECONDS, giving every user a ten-minute session. Naming
+        // the unit in the variable and converting here keeps that mistake from being expressible.
+        const minutes = Number( env.TI_WEB_SESSION_IDLE_TIMEOUT );
+        if ( Number.isInteger( minutes ) && minutes > 0 ) {
+            config.cookies = config.cookies || {};
+            config.cookies.maxAge = minutes * 60 * 1000;
+        }
+    }
     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 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.26.0",
+  "version": "1.27.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!",
   "keywords": [
     "ti-engine",