@ti-engine/web-framework 1.27.0 → 1.32.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 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.32.0
+
+* fix(authorization)!: `applyAdminRole` now reconciles the `admin` role in **both** directions — granted when the
+  identity is on the allowlist, removed when it is not. It only ever added, and it is the only place the role is
+  granted, so it was also the only place it could be taken away: an identity removed from `auth.admins` kept `admin`
+  for the life of its session, reaching `/admin/config/*` and every admin-gated screen, and since 1.26.0's `rolling`
+  cookie that session need never end. Now that 1.29.0 re-applies the role on every request, removal takes effect on
+  the next one. Marked breaking because a session that previously retained the role loses it; an empty or absent
+  allowlist now means nobody is an administrator rather than that everybody keeps what they had. Raised by CodeRabbit
+  on the review of this branch, fixed here rather than in the consumer because the framework owns the role.
+
+## Version 1.31.0
+
+* feat(web-handlers): destroy a session that carries a user and fails `verifySession`, instead of only redirecting
+  it. `verifySession` had been a seam with a `TODO: Implement this!` and no consumer — the default returns true for
+  any session carrying a user, so the "carries a user but fails verification" branch was unreachable. An application
+  that overrides it needs the refusal to stick: leaving the session alive means re-deciding the same verdict on every
+  request while the shell, which reads `auth.isAuthenticated`, goes on believing the visitor is signed in, and the
+  redirect to `/` lands back on the application rather than on a login. The refusal shape is unchanged (`HX-Redirect`
+  for HTMX, `303` to `/` for HTML, `401` otherwise) and is served even if the destroy itself fails — a store that
+  cannot forget a session is no reason to honour it. **Nothing changes for a consumer using the default
+  `verifySession`**, which cannot produce the case; its documentation now describes the override contract rather than
+  carrying a TODO.
+
+## Version 1.30.0
+
+* feat(auth-manager)!: refuse an OpenID Connect sign-in whose e-mail the provider itself reports as unverified, and
+  expose the decision as the pure `AuthManager.isEmailReportedUnverified( userInfo )`. A consumer maps the
+  authenticated identity to an application principal by e-mail — competence resolves it against the employee
+  directory — so an address the provider has not verified is an unauthenticated claim to be someone, and nothing
+  checked it. **Only an explicit `email_verified: false` is a rejection.** An absent claim is not: Google emits the
+  claim, the Microsoft identity platform does not emit it at all, and the published competence image defaults to
+  Azure, so treating "absent" as "unverified" would refuse every sign-in on the default deployment. Marked breaking
+  because a sign-in that previously succeeded can now be refused — but only where the provider was already saying
+  the address was unverified. The residual assumption, for a provider that says nothing, is bound out the way
+  `INSTALL.md` already prescribes: a tenant-pinned discovery URL, a domain-restricted provider, or matching on the
+  stable `sub` rather than the mutable e-mail.
+
+## Version 1.29.0
+
+* feat(web-server): add `refreshSession( session, request )` — the per-request companion to `augmentSession` — and
+  the `sessionRefreshHandler` middleware that calls it. Roles derived once at sign-in are roles that cannot be taken
+  away: `augmentSession` runs inside `regenerateAndSaveSession` and nothing re-ran it, so an authority the
+  application withdrew stayed live in every session already holding it, and since 1.26.0's `rolling` cookie an active
+  user's session need never expire. The default hook is a no-op, so nothing changes for a consumer that does not
+  override it. The middleware is mounted **after** the static handlers and **before** the application routes: an
+  asset request carries the same cookie and has no reason to re-derive anything, while every route that can consult
+  roles has passed through the hook first. The additive `admin` allowlist role is re-applied immediately afterwards,
+  exactly as it is at sign-in, so a hook may replace `session.user.roles` wholesale without stranding an allowlisted
+  administrator. Unlike `augmentSession`, throwing does not refuse anything — there is no sign-in to refuse — so a
+  failing hook is logged, the session's application roles are dropped, and the request proceeds with the `admin` role
+  alone: fail closed on authority, without one failed lookup taking the whole application down.
+
+## Version 1.28.0
+
+* feat(deploy): add `bin/healthcheck.js`, the container liveness probe for any `TiWebServer` application. Point a
+  Dockerfile `HEALTHCHECK` at `node /app/node_modules/@ti-engine/web-framework/bin/healthcheck.js`. It belongs here
+  rather than in each application because every input it reads is the framework's: `TI_WEB_USE_TLS`, `TI_WEB_PORT`
+  and `TI_WEB_TLS_CERT_PATH` are the framework's environment overrides, and `/health` is the framework's own route,
+  served by `webHandlers.healthHandler`. The framework has always provided the endpoint and never anything to call
+  it, which left every consumer writing an inline `node -e` — and the obvious inline version hardcodes `http://`,
+  so it reports a TLS-enabled container unhealthy forever and Docker restarts a server that is answering correctly.
+  The transport comes from the same `tools.toBool` the server uses, so the two cannot drift. With TLS on the
+  certificate is verified rather than skipped: trust is anchored to the server's own certificate and the name to
+  check is read out of it, so one issued for a public hostname passes while the probe connects to `127.0.0.1`.
+  Without a configured certificate the probe falls back to establishing that the port accepts connections — weaker,
+  but it neither disables verification nor restarts a healthy container. Arrived in competence 3.34.0 and moved
+  here unchanged in behaviour.
+
 ## Version 1.27.0
 
 Session lifetime. Two defects that together threw a signed-in user out roughly ten minutes after sign-in, however

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_TLS_CERT_PATH` is also read by the container liveness probe (below), which verifies against that certificate.
 * `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).
@@ -129,3 +130,24 @@ mkcert localhost 127.0.0.1 ::1
 ## License
 
 Apache-2.0 © Boris Kostadinov. See [LICENSE](LICENSE).
+
+## Container liveness probe
+
+`bin/healthcheck.js` asks a running server whether it is still serving and exits 0 only if it says yes. Point a
+Dockerfile `HEALTHCHECK` at it:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
+  CMD ["node", "/app/node_modules/@ti-engine/web-framework/bin/healthcheck.js"]
+```
+
+It reads `TI_WEB_USE_TLS` through the same `tools.toBool` the server uses, so the probe's transport cannot drift
+from the server's, and calls `/health` — the unprotected route `webHandlers.healthHandler` serves. Writing this
+inline in a Dockerfile is the mistake it exists to prevent: an `http://` URL hardcoded there reports a TLS-enabled
+container unhealthy forever, and Docker restarts a server that is answering correctly.
+
+With TLS on it verifies the certificate rather than skipping verification, anchoring trust to the server's own
+certificate at `TI_WEB_TLS_CERT_PATH` and taking the name to check from that certificate — so a certificate issued
+for a public hostname still passes while the probe connects to `127.0.0.1`. Set that variable when you terminate
+TLS inside the container. Without it there is nothing to anchor to and the probe falls back to establishing that
+the port accepts connections, which is weaker but neither disables verification nor restarts a healthy container.

package/bin/healthcheck.js

@@ -0,0 +1,136 @@
+/*
+ * 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>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+*/
+
+/**
+ * Container liveness probe for any application built on {@link TiWebServer}: ask the server whether it is still
+ * serving, and exit 0 only if it says yes. Invoke it from a Dockerfile `HEALTHCHECK`, the way the competence image
+ * does:
+ * <br/>
+ * `HEALTHCHECK CMD ["node", "/app/node_modules/@ti-engine/web-framework/bin/healthcheck.js"]`
+ * <br/>
+ * It lives here rather than in an application because every input it reads is the framework's: `TI_WEB_USE_TLS`,
+ * `TI_WEB_PORT` and `TI_WEB_TLS_CERT_PATH` are the framework's environment overrides, `/health` is the framework's
+ * route, and the endpoint it calls is `webHandlers.healthHandler`. An application copying this file would be
+ * copying framework behaviour, and would silently keep the old behaviour when the framework's changed.
+ * <br/>
+ * The obvious implementation is an inline `node -e` in the Dockerfile, and the obvious mistake is what that
+ * encourages: hardcoding `require('http')` and an `http://` URL. That works for as long as TLS is off, and the
+ * moment an image is run with TLS on — supported, via a mounted certificate rather than terminating at a proxy —
+ * the probe speaks plain HTTP to a TLS listener, fails every time, and Docker reports a healthy container
+ * unhealthy, restarting it on a loop.
+ * <br/>
+ * The transport comes from the same variable and the same parser the server uses, so the two cannot drift:
+ * `tools.toBool` treats an unset value and `false`/`0`/`no`/`N` as false, and anything else as true.
+ * <br/>
+ * <b>On certificates.</b> The obvious way to make a loopback TLS probe work is `rejectUnauthorized: false`, and
+ * the obvious defence is that nothing can sit between a process and itself. Both are true and it is still the wrong
+ * line to write: it is the snippet that gets copied out of a health probe and into a client that does cross a
+ * network. So verification stays on and the trust anchor is narrowed instead — the server's own certificate, named
+ * by `TI_WEB_TLS_CERT_PATH`, is passed as the sole CA, and the name to verify is read out of that certificate
+ * rather than assumed to be `127.0.0.1` (a certificate issued for a public hostname is the normal case, and a probe
+ * that reported "dead" because of the name on it would be repeating the bug this file exists to fix).
+ * <br/>
+ * When no certificate path is configured there is nothing to anchor to, and the probe degrades to establishing that
+ * the port is accepting connections. That is weaker — it shows the listener is up, not that the application is
+ * answering — but it is honest, and it is the only remaining option that neither disables verification nor kills a
+ * container that is running perfectly well.
+ */
+
+const fs = require( "node:fs" );
+const net = require( "node:net" );
+const tools = require( "@ti-engine/core/tools" );
+
+const HOST = "127.0.0.1";
+const TIMEOUT_MS = 4000;   // below Docker's own --timeout, so a hung socket fails as unhealthy rather than being killed mid-probe
+const port = process.env.TI_WEB_PORT || 3000;
+const useTLS = tools.toBool( process.env.TI_WEB_USE_TLS );
+
+const alive = () => process.exit( 0 );
+const dead = () => process.exit( 1 );
+
+/**
+ * Reads the server's own certificate and works out what to trust and what name to verify against.
+ *
+ * @returns {{ca: Buffer, servername: (string|undefined)}|null} null when no certificate is configured or readable.
+ */
+function ownCertificate() {
+    const certPath = process.env.TI_WEB_TLS_CERT_PATH;
+    if ( !certPath ) {
+        return null;
+    }
+    try {
+        const pem = fs.readFileSync( certPath );
+        const certificate = new ( require( "node:crypto" ).X509Certificate )( pem );
+        // Connecting by IP verifies against an `IP Address:` entry, so a certificate that covers the loopback
+        // address needs no SNI at all. Otherwise the first DNS name it carries is the name it can satisfy; failing
+        // that, its common name.
+        const names = String( certificate.subjectAltName || "" ).split( "," ).map( ( entry ) => entry.trim() );
+        if ( names.includes( `IP Address:${ HOST }` ) ) {
+            return { ca: pem, servername: undefined };
+        }
+        const dnsName = names.find( ( entry ) => entry.startsWith( "DNS:" ) );
+        if ( dnsName ) {
+            return { ca: pem, servername: dnsName.slice( "DNS:".length ) };
+        }
+        const commonName = /CN=([^\n,]+)/.exec( String( certificate.subject || "" ) );
+        return { ca: pem, servername: commonName ? commonName[ 1 ].trim() : undefined };
+    } catch {
+        // Unreadable, or not a certificate. Nothing to anchor to.
+        return null;
+    }
+}
+
+/**
+ * Last resort when TLS is on and no certificate is available to verify against: prove the port accepts connections.
+ *
+ * @returns {void}
+ */
+function probeSocket() {
+    const socket = net.connect( { host: HOST, port: port } );
+    socket.setTimeout( TIMEOUT_MS );
+    socket.on( "connect", () => { socket.destroy(); alive(); } );
+    socket.on( "timeout", () => { socket.destroy(); dead(); } );
+    socket.on( "error", dead );
+}
+
+/**
+ * @param {Object} extraOptions Merged into the request options — the CA and server name for the TLS case.
+ * @returns {void}
+ */
+function probeHealthEndpoint( extraOptions ) {
+    const transport = useTLS ? require( "node:https" ) : require( "node:http" );
+    const request = transport.get( { host: HOST, port: port, path: "/health", ...extraOptions }, ( response ) => {
+        response.resume();
+        process.exit( response.statusCode === 200 ? 0 : 1 );
+    } );
+    request.setTimeout( TIMEOUT_MS, () => {
+        request.destroy();
+        dead();
+    } );
+    request.on( "error", dead );
+}
+
+if ( !useTLS ) {
+    probeHealthEndpoint( {} );
+} else {
+    const trust = ownCertificate();
+    if ( trust ) {
+        probeHealthEndpoint( { ca: trust.ca, servername: trust.servername } );
+    } else {
+        probeSocket();
+    }
+}

package/bin/web-server.js

@@ -364,6 +364,11 @@ class TiWebServer extends ServiceConsumer {
                     } ) );
                 } );
 
+                // Re-derive the session's application state before any application route can consult it. Deliberately
+                // AFTER the static handlers: an asset request carries the same session cookie, and there is no reason
+                // to re-derive a viewer's roles to serve them a stylesheet.
+                this.#webServer.use( webHandlers.sessionRefreshHandler( this ) );
+
                 // Set up the web application routes:
                 this.defineWebApplicationRoutes();
 
@@ -438,15 +443,22 @@ class TiWebServer extends ServiceConsumer {
     }
 
     /**
-     * Used to verify the session of a request.
+     * Decides whether a session may continue to hold access. Consulted by `resourceProtectionHandler` on every
+     * protected request; an unprotected route short-circuits it, so a static asset never pays for the check.
+     * <br/>
+     * The default accepts any session carrying a user. **Override it to add an application's own liveness rule** —
+     * whether the principal behind the session still exists and is still entitled to one. Returning `false` for a
+     * session that carries a user does not merely block the request: the framework destroys that session, so the
+     * refusal lands on a real sign-in rather than re-deciding itself on every subsequent request while the shell goes
+     * on believing the visitor is signed in. Keep it synchronous and free of I/O — it runs on the request path.
      *
      * @method
+     * @virtual
      * @param {TiSession} session
      * @returns {boolean}
      * @public
      */
     verifySession( session ) {
-        // TODO: Implement this!
         return Boolean( session && session.user );
     }
 
@@ -471,6 +483,39 @@ class TiWebServer extends ServiceConsumer {
         return session;
     }
 
+    /**
+     * Hook for the application to re-derive the session's application-owned state on **every** request — the
+     * companion to {@link TiWebServer#augmentSession}, which runs only at sign-in. The default is a no-op.
+     * <br/>
+     * It exists because roles derived once at login are roles that cannot be taken away. `augmentSession` runs inside
+     * `regenerateAndSaveSession` and nothing re-runs it, so an authority the application withdraws — a revoked grant,
+     * a manager who no longer manages anything — stayed live in every session already holding it. With a `rolling`
+     * cookie an active user's session need never expire, so "until they sign out" can mean indefinitely. Deriving
+     * per request makes withdrawal take effect on the next click instead.
+     * <br/>
+     * **Contract.** Runs synchronously on each request that carries a session user, after the static handlers and
+     * before any application route, so it must stay cheap and free of I/O — read in-memory state, not a store. The
+     * framework re-applies the additive `admin` role immediately afterwards, so an implementation may replace
+     * `session.user.roles` wholesale without stranding an allowlisted administrator. Assign only when the value
+     * actually changes: express-session persists a session whose serialized form differs, so rewriting an equal array
+     * is free but rewriting a *new* value on every request is a store write on every request.
+     * <br/>
+     * **Failure is fail-closed, not fatal.** Throwing does not refuse the request the way it does at sign-in — there
+     * is no sign-in to refuse. The framework logs the failure, strips the session's application roles, and lets the
+     * request continue with the `admin` allowlist role alone. A viewer who cannot be authorized keeps no authority,
+     * while an administrator retains the access that exists precisely to repair broken application data.
+     *
+     * @method
+     * @virtual
+     * @param {TiSession} session
+     * @param {Object} [request] Optional Express request object.
+     * @returns {TiSession}
+     * @public
+     */
+    refreshSession( session, request ) {
+        return session;
+    }
+
     /**
      * Used to authenticate a user via the specified auth method.
      *

package/components/auth-manager.js

@@ -555,6 +555,29 @@ class AuthManager {
         } );
     }
 
+    /**
+     * Whether an OpenID Connect `userinfo` response carries an e-mail address the provider itself reports as
+     * unverified. Pure, so the decision is testable without a provider.
+     * <br/>
+     * A consumer maps the authenticated identity to an application principal by e-mail — competence resolves it
+     * against the employee directory — so an address the provider has not verified is an unauthenticated claim to be
+     * someone, and a sign-in carrying one is refused.
+     * <br/>
+     * **An ABSENT claim is not a rejection.** Google emits `email_verified`; the Microsoft identity platform does not
+     * emit it at all, so treating "absent" as "unverified" would refuse every Azure sign-in — the default method of
+     * the published container image. Only an explicit `false` is a rejection. That leaves a residual assumption for a
+     * provider that says nothing: bind it out with a tenant-pinned discovery URL (what `INSTALL.md` prescribes for
+     * Azure), a domain-restricted provider, or by matching on the stable `sub` rather than the mutable e-mail.
+     *
+     * @method
+     * @param {Object} userInfo The provider's `userinfo` response.
+     * @returns {boolean}
+     * @public
+     */
+    static isEmailReportedUnverified( userInfo ) {
+        return !!userInfo && userInfo.email_verified === false;
+    }
+
     /**
      * Used to perform the actual OpenID Connect authorization.
      *
@@ -574,6 +597,10 @@ class AuthManager {
                 const claims = token.claims();
                 return openidClient.fetchUserInfo( clientConfig, token.access_token, claims.sub );
             } ).then( ( userInfo ) => {
+                if ( AuthManager.isEmailReportedUnverified( userInfo ) ) {
+                    logger.log( `Refusing an OpenID sign-in for subject '${ userInfo.sub }': the provider reports its e-mail address as unverified.`, logger.logSeverity.WARNING );
+                    throw exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, { details: "The identity provider reports this e-mail address as unverified." }, exceptions.httpCode.C_401 );
+                }
                 const username = userInfo.preferred_username ?? userInfo.email ?? userInfo.name ?? `sub:${ userInfo.sub }`;
                 resolve( new User( { userID: `oauth2:${ userInfo.sub }`, username: username, email: userInfo.email, name: userInfo.name } ) );
             } ).catch( ( error ) => {

package/components/authorization.js

@@ -59,21 +59,35 @@ function isAdminIdentity( user, admins ) {
 }
 
 /**
- * Adds the `admin` role to the session user (additively, no duplicates) when the user is in the allowlist.
- * Safe to call with an empty/missing allowlist or session — it is then a no-op. Returns the session for chaining.
+ * Reconciles the `admin` role on the session user against the allowlist: granted when the identity is on it, removed
+ * when it is not. Authoritative in both directions — this is the only place the role is ever granted, so it is also
+ * the only place it can be taken away. Safe with a missing session; an empty or absent allowlist means nobody is an
+ * administrator, which removes the role rather than preserving it. Returns the session for chaining.
  *
  * @param {Object} session
  * @param {string[]} [admins]
  * @returns {Object} The (possibly modified) session.
  */
 function applyAdminRole( session, admins ) {
-    if ( session && session.user && isAdminIdentity( session.user, admins ) ) {
-        const roles = Array.isArray( session.user.roles ) ? session.user.roles.slice() : [];
-        if ( !roles.includes( ADMIN_ROLE ) ) {
-            roles.push( ADMIN_ROLE );
-        }
+    if ( !session || !session.user ) {
+        return session;
+    }
+
+    const roles = Array.isArray( session.user.roles ) ? session.user.roles.slice() : [];
+    const holdsRole = roles.includes( ADMIN_ROLE );
+    const isAdmin = isAdminIdentity( session.user, admins );
+
+    // Authoritative in BOTH directions, not additive. This is the only place the `admin` role is ever granted, so it
+    // has to be the place it is taken away: while it only added, an identity removed from the allowlist kept the role
+    // for the life of its session — and with a rolling cookie that need never end. Now that the framework re-applies
+    // this per request (see sessionRefreshHandler), removal takes effect on the next request instead.
+    if ( isAdmin && !holdsRole ) {
+        roles.push( ADMIN_ROLE );
         session.user.roles = roles;
+    } else if ( !isAdmin && holdsRole ) {
+        session.user.roles = roles.filter( ( role ) => role !== ADMIN_ROLE );
     }
+
     return session;
 }
 

package/components/web-handlers.js

@@ -274,9 +274,11 @@ module.exports.onShutDownHandler = ( instance ) => {
 module.exports.resourceProtectionHandler = ( instance ) => {
     return ( request, response, next ) => {
         if ( instance.isUnprotectedRoute( request.url ) || instance.verifySession( request.session ) ) {
-            next();
-        } else {
-            const redirectTo = "/";
+            return next();
+        }
+
+        const redirectTo = "/";
+        const refuse = () => {
             if ( isHtmxRequest( request ) ) {
                 response.set( "HX-Redirect", redirectTo );
                 response.status( exceptions.httpCode.C_204 ).end();
@@ -285,7 +287,26 @@ module.exports.resourceProtectionHandler = ( instance ) => {
             } else {
                 response.status( exceptions.httpCode.C_401 ).end();
             }
+        };
+
+        // A session that carries a user and STILL fails verification has been judged invalid — the application looked
+        // at who it belongs to and said no. Leaving it alive would mean re-deciding the same refusal on every request
+        // while the shell, which reads `auth.isAuthenticated`, goes on believing the visitor is signed in. Destroy it,
+        // so the redirect lands on a real login instead of a loop. The default `verifySession` cannot produce this
+        // case (it returns true whenever a user is present), so nothing changes for a consumer that does not override
+        // it; a destroy that fails is logged and the refusal is served regardless.
+        if ( request.session && request.session.user && typeof request.session.destroy === "function" ) {
+            logger.log( `Ending a session that failed verification for user '${ request.session.user.userID || request.session.user.employeeID }'.`, logger.logSeverity.NOTICE );
+            request.session.destroy( ( error ) => {
+                if ( error ) {
+                    logger.log( "Failed to destroy a session that did not pass verification.", logger.logSeverity.WARNING, error );
+                }
+                refuse();
+            } );
+            return;
         }
+
+        refuse();
     };
 };
 
@@ -702,6 +723,42 @@ module.exports.webAppHandler = ( instance ) => {
     };
 };
 
+/**
+ * Re-derives the session's application-owned state on each request by calling {@link TiWebServer#refreshSession},
+ * then re-applies the additive `admin` allowlist role — the same order sign-in uses, so a hook that replaces
+ * `session.user.roles` cannot strand an allowlisted administrator.
+ * <br/>
+ * Mounted after the static handlers and before the application routes: a session-less request (a stylesheet, the
+ * health probe, the login page) never reaches the hook, and every request that can consult roles has passed through
+ * it first.
+ * <br/>
+ * A throwing hook is fail-closed rather than fatal: the failure is logged, the session's application roles are
+ * dropped, and the request proceeds with the `admin` role alone. Taking the whole application down because one
+ * authority lookup failed would be worse than serving it without authority — and the administrator's access is the
+ * one that exists to repair the data that broke.
+ *
+ * @method
+ * @param {TiWebServer} instance
+ * @returns {ExpressHandler}
+ * @public
+ */
+module.exports.sessionRefreshHandler = ( instance ) => {
+    return ( request, response, next ) => {
+        const session = request.session;
+        if ( !session || !session.user ) {
+            return next();
+        }
+        try {
+            instance.refreshSession( session, request );
+        } catch ( error ) {
+            logger.log( `Failed to refresh the session for user '${ session.user.userID || session.user.employeeID }'; continuing without application roles.`, logger.logSeverity.ERROR, error );
+            session.user.roles = [];
+        }
+        authorization.applyAdminRole( session, instance.serviceConfig?.auth?.admins );
+        next();
+    };
+};
+
 /**
  * Validate Origin/Referer for non-GET/HEAD/OPTIONS requests.
  * Origin must match the current request origin (protocol + host[:port]).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.27.0",
+  "version": "1.32.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/bin/healthcheck.d.ts

@@ -0,0 +1 @@
+export {};

package/types/bin/web-server.d.ts

@@ -174,9 +174,17 @@ declare class TiWebServer extends ServiceConsumer {
      */
     reportHealthy(): void;
     /**
-     * Used to verify the session of a request.
+     * Decides whether a session may continue to hold access. Consulted by `resourceProtectionHandler` on every
+     * protected request; an unprotected route short-circuits it, so a static asset never pays for the check.
+     * <br/>
+     * The default accepts any session carrying a user. **Override it to add an application's own liveness rule** —
+     * whether the principal behind the session still exists and is still entitled to one. Returning `false` for a
+     * session that carries a user does not merely block the request: the framework destroys that session, so the
+     * refusal lands on a real sign-in rather than re-deciding itself on every subsequent request while the shell goes
+     * on believing the visitor is signed in. Keep it synchronous and free of I/O — it runs on the request path.
      *
      * @method
+     * @virtual
      * @param {TiSession} session
      * @returns {boolean}
      * @public
@@ -200,6 +208,36 @@ declare class TiWebServer extends ServiceConsumer {
      * @public
      */
     augmentSession(session: TiSession, request?: Object): TiSession;
+    /**
+     * Hook for the application to re-derive the session's application-owned state on **every** request — the
+     * companion to {@link TiWebServer#augmentSession}, which runs only at sign-in. The default is a no-op.
+     * <br/>
+     * It exists because roles derived once at login are roles that cannot be taken away. `augmentSession` runs inside
+     * `regenerateAndSaveSession` and nothing re-runs it, so an authority the application withdraws — a revoked grant,
+     * a manager who no longer manages anything — stayed live in every session already holding it. With a `rolling`
+     * cookie an active user's session need never expire, so "until they sign out" can mean indefinitely. Deriving
+     * per request makes withdrawal take effect on the next click instead.
+     * <br/>
+     * **Contract.** Runs synchronously on each request that carries a session user, after the static handlers and
+     * before any application route, so it must stay cheap and free of I/O — read in-memory state, not a store. The
+     * framework re-applies the additive `admin` role immediately afterwards, so an implementation may replace
+     * `session.user.roles` wholesale without stranding an allowlisted administrator. Assign only when the value
+     * actually changes: express-session persists a session whose serialized form differs, so rewriting an equal array
+     * is free but rewriting a *new* value on every request is a store write on every request.
+     * <br/>
+     * **Failure is fail-closed, not fatal.** Throwing does not refuse the request the way it does at sign-in — there
+     * is no sign-in to refuse. The framework logs the failure, strips the session's application roles, and lets the
+     * request continue with the `admin` allowlist role alone. A viewer who cannot be authorized keeps no authority,
+     * while an administrator retains the access that exists precisely to repair broken application data.
+     *
+     * @method
+     * @virtual
+     * @param {TiSession} session
+     * @param {Object} [request] Optional Express request object.
+     * @returns {TiSession}
+     * @public
+     */
+    refreshSession(session: TiSession, request?: Object): TiSession;
     /**
      * Used to authenticate a user via the specified auth method.
      *

package/types/components/auth-manager.d.ts

@@ -126,6 +126,26 @@ declare class AuthManager {
      * @public
      */
     static toCallbackPath(callbackUrl: string): string | null;
+    /**
+     * Whether an OpenID Connect `userinfo` response carries an e-mail address the provider itself reports as
+     * unverified. Pure, so the decision is testable without a provider.
+     * <br/>
+     * A consumer maps the authenticated identity to an application principal by e-mail — competence resolves it
+     * against the employee directory — so an address the provider has not verified is an unauthenticated claim to be
+     * someone, and a sign-in carrying one is refused.
+     * <br/>
+     * **An ABSENT claim is not a rejection.** Google emits `email_verified`; the Microsoft identity platform does not
+     * emit it at all, so treating "absent" as "unverified" would refuse every Azure sign-in — the default method of
+     * the published container image. Only an explicit `false` is a rejection. That leaves a residual assumption for a
+     * provider that says nothing: bind it out with a tenant-pinned discovery URL (what `INSTALL.md` prescribes for
+     * Azure), a domain-restricted provider, or by matching on the stable `sub` rather than the mutable e-mail.
+     *
+     * @method
+     * @param {Object} userInfo The provider's `userinfo` response.
+     * @returns {boolean}
+     * @public
+     */
+    static isEmailReportedUnverified(userInfo: Object): boolean;
 }
 declare namespace AuthManager {
     export { authMethodEnum as authMethod };

package/types/components/authorization.d.ts

@@ -18,8 +18,10 @@ export = _exports;
  */
 declare function isAdminIdentity(user: Object, admins: string[]): boolean;
 /**
- * Adds the `admin` role to the session user (additively, no duplicates) when the user is in the allowlist.
- * Safe to call with an empty/missing allowlist or session — it is then a no-op. Returns the session for chaining.
+ * Reconciles the `admin` role on the session user against the allowlist: granted when the identity is on it, removed
+ * when it is not. Authoritative in both directions — this is the only place the role is ever granted, so it is also
+ * the only place it can be taken away. Safe with a missing session; an empty or absent allowlist means nobody is an
+ * administrator, which removes the role rather than preserving it. Returns the session for chaining.
  *
  * @param {Object} session
  * @param {string[]} [admins]

package/types/components/web-handlers.d.ts

@@ -12,6 +12,7 @@ export declare var defaultErrorHandler: () => ExpressErrorHandler;
 export declare var nonceGenerationHandler: () => ExpressHandler;
 export declare var cspHeaderHandler: () => ExpressHandler;
 export declare var webAppHandler: (instance: TiWebServer) => ExpressHandler;
+export declare var sessionRefreshHandler: (instance: TiWebServer) => ExpressHandler;
 export declare var originRefererValidationHandler: (instance: any) => ExpressHandler;
 export declare var csrfInitHandler: (instance: TiWebServer) => ExpressHandler;
 export declare var csrfProtectionHandler: () => ExpressHandler;