@ti-engine/web-framework 1.28.0 → 1.33.0

package/CHANGELOG.md

@@ -2,6 +2,99 @@
 
 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.33.0
+
+* fix(web-handlers)!: refuse an OpenID Connect callback that cannot be completed through the normal error path
+  instead of answering `response.status(400).end()`. That was a bare status with an empty body: the visitor got a
+  blank page, nothing was logged, and the three distinct reasons a callback fails were collapsed into one
+  indistinguishable response. Whoever had to work out why had neither a message nor a log line to start from. A
+  refusal is now raised with an explicit `401`, so it presents exactly like every other sign-in failure — an
+  HTML `GET` lands back on the login page with `?error=<code>`, and an API client gets the standard payload.
+  Marked breaking because the status and body of a failed callback change; no caller should have been depending on
+  an empty 400, but a caller that was will see a `303` or a `401`.
+* feat(web-handlers): distinguish the three failure reasons in the log, with the fact that identifies each.
+  `E_WEB_INVALID_REQUEST_QUERY` when the provider returned no authorization code, naming the provider's own
+  `error` (usually `access_denied` — the visitor declined consent). `E_SEC_INVALID_EXPIRED_SESSION` when the
+  session carries no OAuth state, **naming the host the callback arrived on and why that matters**: a session
+  cookie is host-scoped, so a sign-in begun on one hostname and called back on another arrives with no cookie and
+  therefore nothing to verify against. A service reachable under more than one name produces exactly this — a
+  platform that assigns both a generated and a deterministic hostname, say — and so does a session that expired
+  while the visitor sat on the consent screen. `E_SEC_UNAUTHORIZED_ACCESS` when the state does not match the one
+  issued. The distinction is in the log rather than the response, because the visitor has no use for it and an
+  attacker probing the endpoint should not be handed it. **Nothing secret is logged** — never the authorization
+  code, the state values, the PKCE verifier or the nonce — and a test pins that.
+* fix(web-handlers): escape externally-supplied text before it reaches a log line or an error payload. The
+  previous two entries put two caller-controlled values into a `WARNING`: the provider's `error` query parameter
+  and the request's host headers. The callback endpoint is unprotected and accepts any query string, and query
+  parameters are percent-decoded before the handler sees them, so `%0A` arrives as a real newline. The console
+  appender writes one line per entry, which makes that newline the end of the line — everything after it reads as a
+  separate, entirely attacker-written entry, a forged `NOTICE - Sign-in succeeded for admin` sitting in the log
+  looking exactly like a real one. Every character outside printable ASCII is now rendered as a visible `\uXXXX`
+  escape and the value is capped at 100 characters, so a field stays diagnosable without being able to end the line
+  or flood the log. Escaping happens where the value enters rather than at each use, so nothing downstream can
+  reach the raw form. An allowlist of known OAuth error codes was the alternative and is worse: providers emit
+  non-standard codes, and the unfamiliar ones are precisely the ones worth reading. Raised by CodeRabbit on the
+  review of this branch.
+* fix(web-handlers)!: refuse a callback whose session holds a PKCE verifier but no expected state, rather than
+  skipping the comparison. The guard was `oidc.state && state !== oidc.state`, so an absent expected state
+  disabled the check entirely. Nothing in the framework produces such a session — `authenticationHandler` writes
+  the verifier and the state together — but an unverifiable callback is not a callback to trust, and a guard that
+  silently turns itself off when its own input is missing is the wrong shape. `openid-client` checks
+  `expectedState` as well; this keeps the refusal where it can be explained.
+
+## 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

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/local-user-directory.js

@@ -233,7 +233,8 @@ function verifyPassword( password, encoded ) {
 // Usernames that JavaScript's object model treats specially, rejected here because the storage layer this
 // module writes through cannot represent all of them safely — reusing the exact trio ('__proto__',
 // 'constructor', 'prototype') this codebase already treats as reserved at every other prototype-pollution
-// boundary (see the CA-91 employee field-path guards in packages/competence). Verified empirically per name,
+// boundary (see the CA-91 employee field-path guards in the competence application, now its own repository).
+// Verified empirically per name,
 // not assumed uniformly:
 // - '__proto__' is the one that corrupted storage, in @ti-engine/core **before 1.11.0**.
 //   `cache.instance.setJSON` serializes through `tools.stringifyJSON` —

package/components/web-handlers.js

@@ -94,6 +94,39 @@ const resolveHttpCode = ( exception ) => {
     return exceptions.httpCode.C_500; // general, communication, or unknown → internal server error
 };
 
+/**
+ * Longest run of externally-supplied text to put in one log line. Long enough that a real OAuth error code or
+ * hostname survives whole, short enough that nobody can flood the log through one field.
+ *
+ * @type {number}
+ */
+const LOG_VALUE_MAX_LENGTH = 100;
+
+/**
+ * Renders a value that came from outside safe to interpolate into a log message or echo in an error payload.
+ * <br/>
+ * The console appender writes one line per entry, so a newline inside an interpolated value ends that line and
+ * everything after it reads as a separate, entirely attacker-written entry — a forged `NOTICE - sign-in succeeded`,
+ * say, sitting in the log looking exactly like a real one. Query parameters are percent-decoded before they reach
+ * us, so `%0A` arrives as a genuine line break.
+ * <br/>
+ * Every character outside printable ASCII becomes a visible `\uXXXX` escape rather than being dropped, so the value
+ * stays diagnosable — the point of logging it at all — while losing the ability to end the line. An allowlist of
+ * known OAuth error codes was the other option and is worse: providers emit non-standard codes, and the unfamiliar
+ * ones are precisely the ones worth reading.
+ *
+ * @method
+ * @param {*} value
+ * @returns {string}
+ * @private
+ */
+const sanitizeExternalValue = ( value ) => {
+    const escaped = String( value ?? "" ).replace( /[^\x20-\x7E]/g, ( character ) => {
+        return "\\u" + character.charCodeAt( 0 ).toString( 16 ).padStart( 4, "0" );
+    } );
+    return ( escaped.length > LOG_VALUE_MAX_LENGTH ) ? escaped.slice( 0, LOG_VALUE_MAX_LENGTH ) + "..." : escaped;
+};
+
 /**
  * Used to assemble the current URL of a request.
  *
@@ -274,9 +307,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 +320,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();
     };
 };
 
@@ -335,7 +389,18 @@ module.exports.authenticationHandler = ( instance ) => {
 };
 
 /**
- * Used to handle the callback from the Google OpenID authentication.
+ * Used to handle the callback from an OpenID Connect provider.
+ * <br/>
+ * A callback that cannot be completed is refused through the normal error path — `next( … )` with an explicit
+ * `401` — so it presents exactly like every other sign-in failure: an HTML `GET` lands back on the login page with
+ * `?error=<code>`, and an API client gets the standard payload. It used to answer `response.status(400).end()`: a
+ * bare status with an empty body, no log line, and the three distinct reasons below collapsed into one blank page
+ * that said nothing to the person seeing it and nothing to whoever had to work out why.
+ * <br/>
+ * The three reasons are distinguished in the log rather than in the response, because the visitor has no use for
+ * the difference and an attacker probing the endpoint should not be handed it. Nothing secret is logged — never
+ * the authorization code, the state values, the PKCE verifier or the nonce — only the facts that identify which
+ * case this is.
  *
  * @method
  * @param {TiWebServer} instance
@@ -347,27 +412,54 @@ module.exports.authorizedOAuth2CallbackHandler = ( instance, authMethod ) => {
     return ( request, response, next ) => {
         const code = request.query.code;
         const state = request.query.state;
-        const oidc = request.session.oidc || {};
-        if ( !code || !oidc?.codeVerifier ) {
-            response.status( exceptions.httpCode.C_400 ).end();
-        } else if ( oidc.state && state !== oidc.state ) {
-            response.status( exceptions.httpCode.C_400 ).end();
-        } else {
-            instance.authorize( authMethod, new URL( request.originalUrl, getBaseUrl( request ) ), oidc ).then( ( user ) => {
-                return regenerateAndSaveSession( request, "/", ( session ) => {
-                    session.user = user.asJSON();
-                    session.language = user.language || instance.serviceConfig.language;
+        const oidc = request.session?.oidc || {};
+
+        // The provider did not return an authorization code. Usually the visitor declined consent, or the provider
+        // refused the request outright; either way it says so in `error`, which is the single most useful thing to
+        // record and is not sensitive.
+        if ( !code ) {
+            const providerError = sanitizeExternalValue( request.query.error || "none" );
+            logger.log( `Refusing an OpenID sign-in via '${ authMethod }': the provider returned no authorization code (error='${ providerError }').`, logger.logSeverity.WARNING );
+            next( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_QUERY, { detail: "The identity provider returned no authorization code.", providerError: providerError }, exceptions.httpCode.C_401 ) );
+            return;
+        }
 
-                    delete session.oidc;
+        // The session holds nothing to verify the callback against. This is the case that used to be hardest to
+        // diagnose, so the log names the likely cause: a session cookie is scoped to one host, so a sign-in begun
+        // on one hostname and called back on another arrives with no cookie and therefore no state. A service
+        // reachable under more than one name — a platform that assigns both a generated and a deterministic
+        // hostname, say — produces exactly this, and so does a session that expired while the visitor sat on the
+        // provider's consent screen.
+        if ( !oidc.codeVerifier ) {
+            logger.log( `Refusing an OpenID sign-in via '${ authMethod }': the session carries no OAuth state. The callback arrived on host '${ sanitizeExternalValue( request.get( "x-forwarded-host" ) || request.get( "host" ) || "unknown" ) }' — a session cookie is host-scoped, so check that the sign-in began on this same host and that the session had not expired.`, logger.logSeverity.WARNING );
+            next( exceptions.raise( exceptions.exceptionCode.E_SEC_INVALID_EXPIRED_SESSION, { detail: "The session carries no OAuth state for this callback." }, exceptions.httpCode.C_401 ) );
+            return;
+        }
 
-                    return authorization.applyAdminRole( instance.augmentSession( session, request ), instance.serviceConfig?.auth?.admins );
-                } );
-            } ).then( ( redirectTo ) => {
-                response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
-            } ).catch( ( error ) => {
-                next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
-            } );
+        // The state does not match the one issued for this session. A missing expected state is refused too rather
+        // than skipped: a session holding a verifier but no state is inconsistent, and an unverifiable callback is
+        // not a callback to trust. (`openid-client` checks `expectedState` as well; this keeps the refusal here,
+        // where it can be explained.)
+        if ( !oidc.state || state !== oidc.state ) {
+            logger.log( `Refusing an OpenID sign-in via '${ authMethod }': the callback's state does not match the one issued for this session.`, logger.logSeverity.WARNING );
+            next( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, { detail: "The callback state does not match the one issued for this session." }, exceptions.httpCode.C_401 ) );
+            return;
         }
+
+        instance.authorize( authMethod, new URL( request.originalUrl, getBaseUrl( request ) ), oidc ).then( ( user ) => {
+            return regenerateAndSaveSession( request, "/", ( session ) => {
+                session.user = user.asJSON();
+                session.language = user.language || instance.serviceConfig.language;
+
+                delete session.oidc;
+
+                return authorization.applyAdminRole( instance.augmentSession( session, request ), instance.serviceConfig?.auth?.admins );
+            } );
+        } ).then( ( redirectTo ) => {
+            response.redirect( exceptions.httpCode.C_303, convertUriToString( redirectTo ) );
+        } ).catch( ( error ) => {
+            next( exceptions.raise( error, null, exceptions.httpCode.C_401 ) );
+        } );
     };
 };
 
@@ -702,6 +794,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.28.0",
+  "version": "1.33.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/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;