@ti-engine/web-framework 1.28.0 → 1.32.0

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 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

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.28.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/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;