@ti-engine/web-framework 1.25.1 → 1.27.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 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.
+  `ConfigService.listSchemaViolations()` returns one entry per registered document whose **stored** value fails its
+  schema, and `ConfigRegistry.validateSchema( configKey, value )` exposes the schema half of validation on its own.
+  Nothing validated a stored value on the way out before this: the store hands back whatever it holds and a consumer
+  freezes it into its config exports, so a release that tightens a schema — adding a required top-level key, say —
+  leaves any deployment seeded before the change serving a document that can no longer be saved. The failure used to
+  surface much later, as an admin edit rejected for a key the admin never touched, in a screen unrelated to the
+  change. Schema-only by design: a semantic validator may need a `ValidatorContext` the caller has no reason to
+  build, and several are about an *edit* rather than the document standing alone. Read-only by design too —
+  reconciling a stale document is the drift panel's job, under audit; an automatic repair here would write config
+  outside the change-set machinery. A document that has never been stored is not a violation.
+* refactor(config-management): `ConfigRegistry.validate()` now delegates its schema step to `validateSchema()`, so
+  the two can never disagree about what is structurally admissible.
+
 ## Version 1.25.1
 
 * fix(ti-framework): resolve a label key whose own name contains a literal dot. `getLabel` split the key on every

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/config-registry.js

@@ -197,13 +197,7 @@ class ConfigRegistry {
             return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKey: configKey } ) );
         }
 
-        const errors = [];
-        const validateSchema = this.#schemaValidator( registration );
-        if ( !validateSchema( value ) ) {
-            for ( const error of ( validateSchema.errors || [] ) ) {
-                errors.push( { path: error.dataPath || instancePathToDataPath( error.instancePath ), message: error.message || "schema violation", code: "schema", params: error.params } );
-            }
-        }
+        const errors = this.validateSchema( configKey, value ).errors.slice();
 
         return Promise.all( registration.validators.map( ( validator ) => {
             return Promise.resolve( validator( value, context ) ).then( ( issues ) => ( Array.isArray( issues ) ? issues : [] ) );
@@ -217,6 +211,38 @@ class ConfigRegistry {
         } );
     }
 
+    /**
+     * Validates a value against a document's registered schema **only**, skipping the semantic validators.
+     * <br/>
+     * Separate from {@link ConfigRegistry#validate} because the two answer different questions. A semantic validator
+     * may need a {@link ValidatorContext} the caller has no reason to build, and several of them are about an edit
+     * (did the version move? does this removal orphan a reference?) rather than about the document standing alone.
+     * A caller that just wants to know whether a value is structurally admissible — a boot-time check on what the
+     * store already holds, say — needs this half and not the other.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} value
+     * @returns {{valid: boolean, errors: ConfigValidationIssue[]}}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    validateSchema( configKey, value ) {
+        const registration = this.#registrations.get( configKey );
+        if ( !registration ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_PARAMETERS, { reason: "unknown-config", configKey: configKey } );
+        }
+
+        const errors = [];
+        const validateSchema = this.#schemaValidator( registration );
+        if ( !validateSchema( value ) ) {
+            for ( const error of ( validateSchema.errors || [] ) ) {
+                errors.push( { path: error.dataPath || instancePathToDataPath( error.instancePath ), message: error.message || "schema violation", code: "schema", params: error.params } );
+            }
+        }
+        return { valid: errors.length === 0, errors: errors };
+    }
+
     /* Private interface */
 
     /**

package/components/config-service.js

@@ -21,6 +21,7 @@ const configDrift = require( "#config-drift" );
 /** @import ConfigChangeNotifier from "#config-change-notifier" */
 /** @import ConfigRegistry from "#config-registry" */
 /** @import ConfigStore from "#config-store" */
+/** @import { ConfigValidationIssue } from "#config-registry" */
 
 /**
  * Orchestrates validated, versioned configuration edits on top of {@link ConfigStore} and {@link ConfigRegistry}.
@@ -374,6 +375,37 @@ class ConfigService {
         } ) );
     }
 
+    /**
+     * Reports every registered document whose **stored** value no longer satisfies its registered schema.
+     * <br/>
+     * Nothing validates a stored value on the way out: the store hands back whatever it holds, and a consumer
+     * freezes it into its config exports. That is fine until a release tightens a schema — adds a required
+     * top-level key, say — at which point a deployment seeded before the change keeps serving a document that
+     * cannot be saved any more. The failure surfaces much later, as an admin edit rejected for a key the admin
+     * never touched, in a screen that has nothing to do with the change.
+     * <br/>
+     * This answers that question at a moment when it is cheap to act on. It is deliberately schema-only (see
+     * {@link ConfigRegistry#validateSchema}) and deliberately read-only: reconciling a stale document is what the
+     * drift panel is for, and an automatic repair here would write config outside the audited change-set machinery.
+     * A document that has never been stored is not a violation and is omitted.
+     *
+     * @method
+     * @returns {Promise<Array<{configKey: string, errors: ConfigValidationIssue[]}>>} Empty when every stored
+     *          document validates.
+     * @public
+     */
+    listSchemaViolations() {
+        return Promise.all( this.#registry.list().map( ( configKey ) => {
+            return this.#store.getCurrent( configKey ).then( ( current ) => {
+                if ( !current ) {
+                    return null;
+                }
+                const result = this.#registry.validateSchema( configKey, current.value );
+                return result.valid ? null : { configKey: configKey, errors: result.errors };
+            } );
+        } ) ).then( ( results ) => results.filter( Boolean ) );
+    }
+
     /**
      * Applies the registered file defaults for the given documents, as a single validated change-set.
      * <br/>

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.25.1",
+  "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",

package/types/components/config-registry.d.ts

@@ -142,6 +142,26 @@ declare class ConfigRegistry {
         valid: boolean;
         errors: ConfigValidationIssue[];
     }>;
+    /**
+     * Validates a value against a document's registered schema **only**, skipping the semantic validators.
+     * <br/>
+     * Separate from {@link ConfigRegistry#validate} because the two answer different questions. A semantic validator
+     * may need a {@link ValidatorContext} the caller has no reason to build, and several of them are about an edit
+     * (did the version move? does this removal orphan a reference?) rather than about the document standing alone.
+     * A caller that just wants to know whether a value is structurally admissible — a boot-time check on what the
+     * store already holds, say — needs this half and not the other.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} value
+     * @returns {{valid: boolean, errors: ConfigValidationIssue[]}}
+     * @throws {TiException.E_WEB_INVALID_REQUEST_PARAMETERS} If the document is not registered.
+     * @public
+     */
+    validateSchema(configKey: string, value: Object): {
+        valid: boolean;
+        errors: ConfigValidationIssue[];
+    };
 }
 declare namespace ConfigRegistry {
     export { instance };

package/types/components/config-service.d.ts

@@ -2,9 +2,11 @@ export = ConfigService;
 import type ConfigChangeNotifier from "#config-change-notifier";
 import type ConfigRegistry from "#config-registry";
 import type ConfigStore from "#config-store";
+import type { ConfigValidationIssue } from "#config-registry";
 /** @import ConfigChangeNotifier from "#config-change-notifier" */
 /** @import ConfigRegistry from "#config-registry" */
 /** @import ConfigStore from "#config-store" */
+/** @import { ConfigValidationIssue } from "#config-registry" */
 /**
  * Orchestrates validated, versioned configuration edits on top of {@link ConfigStore} and {@link ConfigRegistry}.
  *
@@ -223,6 +225,29 @@ declare class ConfigService {
      * @public
      */
     listDrift(): Promise<Array<Object>>;
+    /**
+     * Reports every registered document whose **stored** value no longer satisfies its registered schema.
+     * <br/>
+     * Nothing validates a stored value on the way out: the store hands back whatever it holds, and a consumer
+     * freezes it into its config exports. That is fine until a release tightens a schema — adds a required
+     * top-level key, say — at which point a deployment seeded before the change keeps serving a document that
+     * cannot be saved any more. The failure surfaces much later, as an admin edit rejected for a key the admin
+     * never touched, in a screen that has nothing to do with the change.
+     * <br/>
+     * This answers that question at a moment when it is cheap to act on. It is deliberately schema-only (see
+     * {@link ConfigRegistry#validateSchema}) and deliberately read-only: reconciling a stale document is what the
+     * drift panel is for, and an automatic repair here would write config outside the audited change-set machinery.
+     * A document that has never been stored is not a violation and is omitted.
+     *
+     * @method
+     * @returns {Promise<Array<{configKey: string, errors: ConfigValidationIssue[]}>>} Empty when every stored
+     *          document validates.
+     * @public
+     */
+    listSchemaViolations(): Promise<Array<{
+        configKey: string;
+        errors: ConfigValidationIssue[];
+    }>>;
     /**
      * Applies the registered file defaults for the given documents, as a single validated change-set.
      * <br/>