@ti-engine/web-framework 1.20.1 → 1.23.0

package/bin/web-app-manager.js

@@ -14,8 +14,9 @@ const fs = require( "node:fs" );
 const configRegistry = require( "#config-registry" );
 const configService = require( "#config-service" );
 const authorization = require( "#authorization" );
+const applicationInfo = require( "#application-info" );
 
-/** @import { TiSession } from "#definitions" */
+/** @import { TiApplicationInfo, TiInfoSection, TiProfileInfo, TiSession } from "#definitions" */
 
 const RE_NONCE_ATTR = /\{ti-nonce-placeholder}/g;
 const RE_CSRF_ATTR = /\{ti-csrf-placeholder}/g;
@@ -124,6 +125,7 @@ class TiWebAppManager {
     #staticFileCache = {};
     #staticFileCacheEnabled;
     #enabledAuthMethods = [];
+    #baseApplicationInfo = null;
 
     /**
      * @constructor
@@ -165,6 +167,10 @@ class TiWebAppManager {
             title: "Profile",
             path: "fragments/frame-profile.html"
         };
+        this.#fragments[ 'about' ] = {
+            title: "About",
+            path: "fragments/frame-about.html"
+        };
         this.#fragments[ 'not-found' ] = {
             title: "Not Found",
             path: "fragments/frame-not-found.html"
@@ -393,13 +399,20 @@ class TiWebAppManager {
      * @public
      */
     processDataRequest( session, view, options = {} ) {
+        if ( view === "profile" ) {
+            return this.getProfileInfo( session );
+        }
+        if ( view === "about" ) {
+            return this.getApplicationInfo( session );
+        }
         return new Promise( ( resolve, reject ) => {
             if ( view === "config" ) {
                 resolve( {
                     labels: localization.getAllLabels( session?.language ),
                     auth: {
                         isAuthenticated: Boolean( session && session.user )
-                    }
+                    },
+                    componentsConfig: this.buildComponentsConfig( session )
                 } );
             } else {
                 reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, { view: view } ) );
@@ -407,6 +420,198 @@ class TiWebAppManager {
         } );
     }
 
+    /**
+     * Returns the configuration for the shared UI components the application shell renders — currently the sidebar
+     * user flyout menu. Shipped as part of the `config` data payload and merged into the `tiComponentsConfig`
+     * Alpine store on the client.
+     * <br/>
+     * The default menu links the two screens the framework itself provides (Profile and About) plus sign-out, so a
+     * consuming application gets a working user menu without configuring one. Override to replace it; a subclass
+     * that supplies its own `componentsConfig` naturally supersedes this.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {Object}
+     * @virtual
+     * @public
+     */
+    buildComponentsConfig( session ) {
+        const language = session && session.language;
+        return {
+            userProfileMenu: {
+                menuTitle: localization.getLabel( "interface.topbar.user-profile", language, "Your profile" ),
+                placement: "right-end",
+                offset: 0,
+                buttonConfigs: [ {
+                    title: localization.getLabel( "interface.user-menu.profile", language, "Your profile" ),
+                    icon: "user-profile",
+                    action: { href: "/app/profile", target: "#ti-content", swap: "innerHTML" }
+                }, {
+                    title: localization.getLabel( "interface.user-menu.about", language, "About" ),
+                    icon: "info-circle",
+                    action: { href: "/app/about", target: "#ti-content", swap: "innerHTML" }
+                }, {
+                    title: localization.getLabel( "interface.user-menu.logout", language, "Logout" ),
+                    icon: "logout",
+                    action: { href: "/logout", method: "post", target: "body", swap: "outerHTML" }
+                } ]
+            }
+        };
+    }
+
+    /**
+     * Returns the descriptor rendered by the "Profile" screen — the identity header plus an ordered list of titled
+     * label/value sections. Every string in it is display-ready: the server resolves labels and formats values,
+     * because this is where the session language and the label catalogue are (see {@link resolveLabel}).
+     * <br/>
+     * The default implementation reports what the framework itself knows about the session user — name, username,
+     * e-mail, language and roles. Override in subclasses to show application-owned data instead; the screen, its
+     * Alpine component and its styling are inherited unchanged, so an override only decides the content.
+     * <br/>
+     * NOTE: The descriptor is always about the SESSION user. There is deliberately no "whose profile" parameter —
+     * viewing another person's record belongs to an application screen that carries its own scoping rules.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {Promise<TiProfileInfo>}
+     * @exception {TiException.E_SEC_UNAUTHORIZED_ACCESS} (401) When the session carries no user.
+     * @virtual
+     * @public
+     */
+    getProfileInfo( session ) {
+        return new Promise( ( resolve, reject ) => {
+            const user = session && session.user;
+            if ( !user ) {
+                return reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
+            }
+            resolve( {
+                identity: this.buildSessionIdentity( session ),
+                sections: this.buildAccountSections( session )
+            } );
+        } );
+    }
+
+    /**
+     * Returns the descriptor rendered by the "About" screen — the application's own identity (name, version,
+     * release date, description, license, homepage) plus the ti-engine component versions it runs on, and any
+     * extra sections the application contributes.
+     * <br/>
+     * The baseline is resolved once from the consuming application's `package.json`, overridable through
+     * `TI_WEB_APP_NAME` / `TI_WEB_APP_VERSION` / `TI_WEB_APP_RELEASE_DATE` (see `#application-info`), and cached —
+     * the manifest cannot change while the process runs.
+     * <br/>
+     * NOTE: Runtime facts (node version, platform, instance identity) are attached only for an `admin` session.
+     * They are operational detail that helps support and means nothing to an ordinary user, so they are not handed
+     * to every signed-in visitor. Override in subclasses to append application-specific sections; call `super` and
+     * extend the result rather than rebuilding it.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {Promise<TiApplicationInfo>}
+     * @virtual
+     * @public
+     */
+    getApplicationInfo( session ) {
+        return new Promise( ( resolve ) => {
+            if ( !this.#baseApplicationInfo ) {
+                this.#baseApplicationInfo = applicationInfo.buildApplicationInfo( {
+                    manifest: applicationInfo.readApplicationManifest(),
+                    env: process.env,
+                    components: TiWebAppManager.resolveFrameworkComponents()
+                } );
+            }
+
+            const info = structuredClone( this.#baseApplicationInfo );
+            if ( authorization.hasAnyRole( session, [ authorization.ADMIN_ROLE ] ) ) {
+                info.runtime = {
+                    node: process.version,
+                    platform: `${ process.platform } · ${ process.arch }`,
+                    application: this.#webAppIdentifier
+                };
+            }
+            resolve( info );
+        } );
+    }
+
+    /**
+     * Builds the identity header of the Profile screen from the session user. Kept separate from
+     * {@link TiWebAppManager#getProfileInfo} so a subclass that replaces the sections can still reuse — or fall
+     * back to — the framework's identity block when the application has no richer identity to show.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {Object}
+     * @public
+     */
+    buildSessionIdentity( session ) {
+        const user = ( session && session.user ) || {};
+        return {
+            name: String( user.name || user.username || user.userID || "" ),
+            subtitle: "",
+            caption: String( user.email || "" ),
+            avatarSeed: String( user.userID || user.username || "" ),
+            // No pills by default: the framework knows roles only as opaque codes, and a stack of pills reading
+            // "1" / "2" beside the name is noise. The Access section lists them, and an application that has
+            // meaningful status to show (employment state, an ID, a badge) supplies its own.
+            tags: []
+        };
+    }
+
+    /**
+     * Builds the framework's account-level Profile sections from the session user. A subclass showing richer
+     * application data can append these so the account facts remain visible alongside it.
+     *
+     * @method
+     * @param {TiSession} session
+     * @returns {TiInfoSection[]}
+     * @public
+     */
+    buildAccountSections( session ) {
+        const user = ( session && session.user ) || {};
+        const language = session && session.language;
+        const roles = Array.isArray( user.roles ) ? user.roles : [];
+
+        return [ {
+            title: localization.getLabel( "interface.profile.section-account", language, "Account" ),
+            icon: "user",
+            items: [
+                { label: localization.getLabel( "interface.profile.field-name", language, "Full name" ), value: String( user.name || "" ) },
+                { label: localization.getLabel( "interface.profile.field-username", language, "Username" ), value: String( user.username || "" ) },
+                { label: localization.getLabel( "interface.profile.field-email", language, "E-mail" ), value: String( user.email || "" ), wide: true },
+                { label: localization.getLabel( "interface.profile.field-user-id", language, "User ID" ), value: String( user.userID || "" ), mono: true },
+                { label: localization.getLabel( "interface.profile.field-language", language, "Language" ), value: String( user.language || language || "" ) }
+            ]
+        }, {
+            title: localization.getLabel( "interface.profile.section-access", language, "Access" ),
+            icon: "check-circle",
+            items: [
+                { label: localization.getLabel( "interface.profile.field-roles", language, "Roles" ), value: roles.join( " · " ), wide: true }
+            ]
+        } ];
+    }
+
+    /**
+     * Resolves the versions of the ti-engine packages the running application is built on, for the About screen.
+     * <br/>
+     * NOTE: `@ti-engine/core` does not expose `./package.json` through its exports map, so its manifest is located
+     * by walking up from a module it *does* export. A package that cannot be resolved is simply omitted — an
+     * informational screen must never be the reason a request fails.
+     *
+     * @method
+     * @static
+     * @returns {Array<{name: string, version: string}>}
+     * @public
+     */
+    static resolveFrameworkComponents() {
+        const manifests = [
+            applicationInfo.readApplicationManifest( path.join( __dirname, ".." ) ),
+            TiWebAppManager.#readManifestForModule( "@ti-engine/core/tools" )
+        ];
+        return manifests
+            .filter( ( manifest ) => manifest && manifest.name && manifest.version )
+            .map( ( manifest ) => ( { name: manifest.name, version: manifest.version } ) );
+    }
+
     /**
      * Used to process an application service request.
      *
@@ -452,6 +657,34 @@ class TiWebAppManager {
 
     /* Private interface */
 
+    /**
+     * Locates the `package.json` owning a resolvable module specifier by walking up from the resolved file.
+     *
+     * @method
+     * @static
+     * @param {string} moduleSpecifier
+     * @returns {Object} The manifest, or an empty object when it cannot be located.
+     */
+    static #readManifestForModule( moduleSpecifier ) {
+        try {
+            let directory = path.dirname( require.resolve( moduleSpecifier ) );
+            for ( let depth = 0; depth < 8; depth++ ) {
+                const manifest = applicationInfo.readApplicationManifest( directory );
+                if ( manifest && manifest.name ) {
+                    return manifest;
+                }
+                const parent = path.dirname( directory );
+                if ( parent === directory ) {
+                    break;
+                }
+                directory = parent;
+            }
+        } catch {
+            // An unresolvable package simply does not appear in the component list.
+        }
+        return {};
+    }
+
     /**
      * Returns the HTML fragment for the requested route.
      *

package/bin/web-server.js

@@ -60,12 +60,18 @@ const applyWebConfigEnvOverrides = require( "#web-config-env" );
 /**
  * @typedef {Object} SettingsAuth
  * @property {string[]} enabledMethods
- * @property {Object} local
+ * @property {SettingsAuthLocal} local
  * @property {Object} oauth2
  * @property {SettingsOAuth2Client} [oauth2.azure]
  * @property {SettingsOAuth2Client} [oauth2.google]
  */
 
+/**
+ * @typedef {Object} SettingsAuthLocal
+ * @property {string} [usersPath] Path to the JSON file of local user records (see `TI_WEB_AUTH_LOCAL_USERS_PATH`).
+ *           Local sign-in refuses everyone whenever this is absent, unreadable, or yields no usable records.
+ */
+
 /**
  * @typedef {Object} SettingsOAuth2Client
  * @property {string} [clientID]
@@ -430,6 +436,11 @@ class TiWebServer extends ServiceConsumer {
      * Hook for the application to augment the freshly-authenticated session (e.g. derive domain roles from an
      * identity store or the org chart). Runs synchronously, once per login, before the framework's additive `admin`
      * role is applied. The default is a no-op. Any test-user role injection is an override of whatever the app derives.
+     * <br/>
+     * **Refusing a login.** Throwing from this hook refuses the sign-in: the framework destroys the freshly regenerated
+     * session (so no usable session survives the refusal), the login handler raises `401`, and the error handler
+     * redirects the browser to the login page with the exception code in `?error=`. Throw when the authenticated
+     * identity cannot be mapped to an application principal; return the session unchanged to accept it.
      *
      * @method
      * @virtual
@@ -457,6 +468,12 @@ class TiWebServer extends ServiceConsumer {
 
     /**
      * Used to set up user authorization according to the specified auth method.
+     * <br/>
+     * NOTE: This presupposes a successful, immediately preceding {@link TiWebServer#authenticate} call for the same
+     * credentials — it is **not** an independent authentication check. For the `local` method it builds the session
+     * user from the directory record named by `oidc.username`, verifying that the record exists and is not disabled
+     * but performing no password comparison of its own; the framework's own login route calls `authenticate` first.
+     * Calling this directly without that preceding step would mint a session for any known username.
      *
      * @method
      * @param {TiAuthMethod} authMethod

package/bin/web-server.json

@@ -18,6 +18,9 @@
       "openid-google"
     ],
     "admins": [],
+    "local": {
+      "usersPath": ""
+    },
     "oauth2": {
       "azure": {
         "tokenEndpointAuthMethod": "client_secret_post",

package/components/application-info.js

@@ -0,0 +1,190 @@
+/*
+ * 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>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+"use strict";
+
+const path = require( "node:path" );
+const fs = require( "node:fs" );
+
+/** @import { TiApplicationInfo } from "#definitions" */
+
+/**
+ * Matches the leading npm scope of a package name (`@ti-engine/competence` → `competence`).
+ *
+ * @type {RegExp}
+ */
+const RE_PACKAGE_SCOPE = /^@[^/]+\//;
+
+/**
+ * Matches the first character that can open the contact suffix of a `package.json` author string — the `<` of the
+ * e-mail or the `(` of the homepage.
+ *
+ * @type {RegExp}
+ */
+const RE_AUTHOR_CONTACT_START = /[<(]/;
+
+/**
+ * Turns an npm package name into a human-readable display name — the scope is dropped and each dash/underscore
+ * separated word is capitalized (`@ti-engine/web-framework` → `Web Framework`). Used only when neither the manifest
+ * nor the environment supplies an explicit display name.
+ *
+ * @method
+ * @param {string} packageName
+ * @returns {string}
+ * @private
+ */
+function toDisplayName( packageName ) {
+    const bare = String( packageName || "" ).replace( RE_PACKAGE_SCOPE, "" ).trim();
+    if ( !bare ) {
+        return "";
+    }
+    return bare
+        .split( /[-_.\s]+/ )
+        .filter( ( word ) => word.length > 0 )
+        .map( ( word ) => word.charAt( 0 ).toUpperCase() + word.slice( 1 ) )
+        .join( " " );
+}
+
+/**
+ * Reduces a `package.json` author entry — either the string form or the object form — to a bare display name,
+ * dropping the e-mail address and homepage that npm allows to be inlined in the string form.
+ * <br/>
+ * NOTE: npm's string form is `Name <email> (url)`, where both bracketed parts are optional **suffixes** — they are
+ * never embedded inside the name. So the name is simply everything before the first `<` or `(`. This deliberately
+ * does NOT globally remove `<…>` spans: a replace of that shape reads as an attempt to strip HTML tags, which
+ * CodeQL flags as an incomplete multi-character sanitizer (`js/incomplete-multi-character-sanitization`, high) —
+ * correctly, since one pass over `<<a>b>` leaves a stray `<`. Truncating at the delimiter matches the actual
+ * grammar and cannot leave a partial span behind.
+ *
+ * @method
+ * @param {string|Object} author
+ * @returns {string}
+ * @private
+ */
+function toAuthorName( author ) {
+    if ( author && typeof author === "object" ) {
+        return String( author.name || "" ).trim();
+    }
+    const declared = String( author || "" );
+    const contactStart = declared.search( RE_AUTHOR_CONTACT_START );
+    return ( contactStart === -1 ? declared : declared.slice( 0, contactStart ) ).trim();
+}
+
+/**
+ * Reduces a `package.json` repository entry — either the string shorthand or the object form — to a plain URL,
+ * stripping the `git+` prefix and `.git` suffix npm accepts so the result is browser-openable.
+ *
+ * @method
+ * @param {string|Object} repository
+ * @returns {string}
+ * @private
+ */
+function toRepositoryUrl( repository ) {
+    const raw = ( repository && typeof repository === "object" ) ? repository.url : repository;
+    const url = String( raw || "" ).trim();
+    if ( !url ) {
+        return "";
+    }
+    return url.replace( /^git\+/, "" ).replace( /\.git$/, "" );
+}
+
+/**
+ * Returns the trimmed string value of `value`, or `fallback` when it is absent or blank. Keeps the builder below
+ * free of repeated `String( … ).trim() || …` noise while treating a whitespace-only manifest field as absent.
+ *
+ * @method
+ * @param {*} value
+ * @param {string} [fallback=""]
+ * @returns {string}
+ * @private
+ */
+function text( value, fallback = "" ) {
+    const resolved = String( value === undefined || value === null ? "" : value ).trim();
+    return resolved || fallback;
+}
+
+/**
+ * Builds the normalized application-information descriptor that backs the framework "About" screen.
+ * <br/>
+ * The function is PURE — everything it needs is injected — so the whole resolution order (manifest → environment
+ * override) is unit-testable without touching the filesystem or `process.env`. The impure half, reading the
+ * consuming application's manifest, is {@link readApplicationManifest}.
+ * <br/>
+ * Resolution order for the three overridable fields is manifest first, environment last:
+ * - `TI_WEB_APP_NAME` overrides `manifest.displayName` / a display name derived from `manifest.name`;
+ * - `TI_WEB_APP_VERSION` overrides `manifest.version`;
+ * - `TI_WEB_APP_RELEASE_DATE` overrides `manifest.releaseDate`.
+ * <br/>
+ * The environment wins because it is how a container image stamps facts that its baked-in manifest cannot know —
+ * most importantly the build/release date, for which `package.json` has no standard field at all.
+ *
+ * @method
+ * @param {Object} [options]
+ * @param {Object} [options.manifest] A `package.json`-shaped object for the consuming application.
+ * @param {Object} [options.env] The environment source (injectable for testing).
+ * @param {Array<{name: string, version: string}>} [options.components] Framework component versions to list.
+ * @param {Object} [options.runtime] Runtime facts (node/platform/instance). Included verbatim when present; the
+ * caller decides whether the current session is allowed to see them.
+ * @returns {TiApplicationInfo}
+ * @public
+ */
+function buildApplicationInfo( options = {} ) {
+    const manifest = ( options.manifest && typeof options.manifest === "object" ) ? options.manifest : {};
+    const env = ( options.env && typeof options.env === "object" ) ? options.env : {};
+
+    const packageName = text( manifest.name );
+    const name = text( env.TI_WEB_APP_NAME, text( manifest.displayName, toDisplayName( packageName ) ) );
+    const author = toAuthorName( manifest.author );
+    const homepage = text( manifest.homepage, toRepositoryUrl( manifest.repository ) );
+
+    const components = ( Array.isArray( options.components ) ? options.components : [] )
+        .map( ( component ) => ( {
+            name: text( component && component.name ),
+            version: text( component && component.version )
+        } ) )
+        .filter( ( component ) => component.name.length > 0 );
+
+    return {
+        name: name,
+        packageName: packageName,
+        version: text( env.TI_WEB_APP_VERSION, text( manifest.version ) ),
+        releaseDate: text( env.TI_WEB_APP_RELEASE_DATE, text( manifest.releaseDate ) ),
+        description: text( manifest.description ),
+        license: text( manifest.license ),
+        homepage: homepage,
+        author: author,
+        components: components,
+        runtime: ( options.runtime && typeof options.runtime === "object" ) ? { ...options.runtime } : null,
+        sections: []
+    };
+}
+
+/**
+ * Reads the consuming application's `package.json`. This is the one impure function in this module.
+ * <br/>
+ * NOTE: A missing or malformed manifest resolves to an empty object rather than throwing — an informational screen
+ * must never be the reason a request fails, and {@link buildApplicationInfo} produces a usable (if sparse)
+ * descriptor from `{}`.
+ *
+ * @method
+ * @param {string} [directory=process.cwd()] The directory holding the manifest.
+ * @returns {Object}
+ * @public
+ */
+function readApplicationManifest( directory = process.cwd() ) {
+    try {
+        const manifestPath = path.join( directory, "package.json" );
+        const contents = fs.readFileSync( manifestPath, "utf8" );
+        const parsed = JSON.parse( contents );
+        return ( parsed && typeof parsed === "object" ) ? parsed : {};
+    } catch {
+        return {};
+    }
+}
+
+module.exports = { buildApplicationInfo, readApplicationManifest };