@ti-engine/web-framework 1.20.1 → 1.23.0

package/components/auth-manager.js

@@ -10,8 +10,10 @@ const tools = require( "@ti-engine/core/tools" );
 const logger = require( "@ti-engine/core/logger" );
 const exceptions = require( "@ti-engine/core/exceptions" );
 const { randomBytes } = require( "node:crypto" );
+const fs = require( "node:fs" );
 const openidClient = require( "openid-client" );
 const User = require( "#user" );
+const localUserDirectory = require( "#local-user-directory" );
 
 /** @import { SettingsAuth } from "#web-server" */
 
@@ -54,14 +56,48 @@ class AuthManager {
     #authSettings = {
         enabledMethods: [],
         local: {
-            username: undefined,
-            password: undefined
+            usersPath: undefined
         },
         oauth2: {}
     };
     #clientConfigOAuth2Google = {};
     #clientConfigOAuth2Azure = {};
 
+    // Whether the local user directory is genuinely usable: set true only after #loadLocalUserDirectory performs
+    // a successful reconcile that produced at least one record. Every other outcome — no 'usersPath' configured,
+    // an unreadable/unparseable file, a file that reconciles to zero records, or a Redis failure during reconcile
+    // — leaves this false. #authenticateLocal and authorize() both require it before consulting the directory,
+    // because localUserDirectory.findByUsername reads Redis directly: without this flag, records reconciled by
+    // an EARLIER successful boot would remain live and would still authenticate even though the CURRENT boot's
+    // log already told the operator "every local sign-in will be refused". A failed load deliberately still does
+    // not erase those stale Redis records (see #loadLocalUserDirectory's own doc comment) — this flag is what
+    // makes them inert instead of merely unmentioned.
+    #localDirectoryUsable = false;
+
+    // A fixed, valid encoding used only to spend comparable time on an unknown or disabled username. It corresponds
+    // to no usable password: the key material is random, so nothing can ever verify against it.
+    //
+    // It is ASSEMBLED, not hashed. `verifyPassword` reads N/r/p and the key length out of the encoded string and
+    // then derives asynchronously off the main thread, so the decoy only has to be *decodable* — the derive that
+    // equalizes the timing happens inside `verifyPassword` either way, at parameters identical to a real record's
+    // because they come from the same HASH_DEFAULTS. Calling `hashPassword` here would additionally run a
+    // ~100 ms blocking `scryptSync`, and it bought nothing: an earlier version paid that at class load (so every
+    // instance paid it, including one with 'local' disabled entirely — competence's shipped Azure-only image),
+    // and making it lazy only moved the same blocking cost onto the first refused login, i.e. onto a request path.
+    // Assembling it costs a few random bytes, so it can be eager again without the lazy-getter machinery.
+    //
+    // It MUST remain decodable: if `decodeHash` ever rejected it, `verifyPassword` would return false immediately
+    // without deriving, and the timing-equalization this exists for would silently stop working. A test asserts
+    // the decoy still round-trips through the directory's own validation.
+    static #timingDecoyHash = [
+        localUserDirectory.ALGORITHM,
+        localUserDirectory.HASH_DEFAULTS.N,
+        localUserDirectory.HASH_DEFAULTS.r,
+        localUserDirectory.HASH_DEFAULTS.p,
+        randomBytes( localUserDirectory.HASH_DEFAULTS.saltBytes ).toString( "base64" ),
+        randomBytes( localUserDirectory.HASH_DEFAULTS.keyBytes ).toString( "base64" )
+    ].join( "$" );
+
     /**
      * @constructor
      * @param {SettingsAuth} settings
@@ -71,14 +107,6 @@ class AuthManager {
             this.#authSettings = settings;
         }
 
-        // Set up local authentication configuration:
-        if ( this.isAuthEnabled( authMethodEnum.LOCAL ) ) {
-            // TODO: For testing purposes only! Implement real local auth later!
-            this.#authSettings.local = this.#authSettings.local || {};
-            this.#authSettings.local.username = "admin";
-            this.#authSettings.local.password = "admin";
-        }
-
         // Set up OAuth2 configuration:
         this.#authSettings.oauth2 = this.#authSettings.oauth2 || {};
         if ( this.isAuthEnabled( authMethodEnum.OPENID_GOOGLE ) ) {
@@ -113,6 +141,9 @@ class AuthManager {
         this.#dropUnconfiguredOpenIDProviders();
 
         let promises = [];
+        if ( this.isAuthEnabled( authMethodEnum.LOCAL ) ) {
+            promises.push( this.#loadLocalUserDirectory() );
+        }
         if ( this.isAuthEnabled( authMethodEnum.OPENID_GOOGLE ) ) {
             promises.push( this.#initializeOpenIDClient( this.#authSettings.oauth2.google ).then( ( configuration ) => {
                 this.#clientConfigOAuth2Google = configuration;
@@ -186,6 +217,13 @@ class AuthManager {
 
     /**
      * Used to set up user authorization according to the specified authentication method.
+     * <br/>
+     * NOTE: This presupposes a successful, immediately preceding {@link AuthManager#authenticate} call for the
+     * same credentials and is NOT an independent authentication check on its own — for `LOCAL` it performs no
+     * password verification. It refuses an absent, disabled, or (for `LOCAL`) not-yet-usable-directory record,
+     * but a caller that invokes it without having just authenticated bypasses password verification entirely.
+     * The framework's own login route always calls `authenticate()` first (see `web-handlers.js`); this method
+     * is public on both `AuthManager` and `TiWebServer`, so any other caller must preserve that ordering itself.
      *
      * @method
      * @param {TiAuthMethod} authMethod
@@ -198,7 +236,27 @@ class AuthManager {
     authorize( authMethod, currentUrl, oidc ) {
         switch ( authMethod ) {
             case authMethodEnum.LOCAL:
-                return Promise.resolve( new User( { userID: `local:${ tools.getUUID() }`, username: oidc.username } ) );
+                // Requires the same #localDirectoryUsable flag #authenticateLocal requires — see its declaration
+                // — so a stale Redis-backed record from an earlier successful boot cannot mint a session User
+                // merely because authorize() looks the username up independently of #authenticateLocal.
+                if ( !this.#localDirectoryUsable ) {
+                    return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
+                }
+                return localUserDirectory.findByUsername( oidc.username ).then( ( record ) => {
+                    // A disabled record must be refused here too, not only by #authenticateLocal: the two
+                    // lookups are independent reads of the same Redis-backed directory, and a reconcile that
+                    // flips 'disabled' between them would otherwise let authorize() admit what authenticate()
+                    // had just refused (or vice versa).
+                    if ( !record || record.disabled === true ) {
+                        throw exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 );
+                    }
+                    return new User( {
+                        userID: record.userID,
+                        username: record.username,
+                        email: record.email,
+                        name: record.name
+                    } );
+                } );
             case authMethodEnum.OPENID_GOOGLE:
                 return this.#authorizeOpenID( currentUrl, oidc, this.#clientConfigOAuth2Google );
             case authMethodEnum.OPENID_AZURE:
@@ -355,7 +413,83 @@ class AuthManager {
     }
 
     /**
-     * Used to verify the local authentication of a request.
+     * Loads the configured local users file and reconciles it into the directory. Every failure path leaves the
+     * directory unusable and logs why, so local authentication refuses rather than admits — the same fail-soft
+     * stance as {@link AuthManager#dropUnconfiguredOpenIDProviders}: a bad local-users file must not take down an
+     * instance whose other auth method works, and must not let anyone in either.
+     * <br/>
+     * "Unusable" is not just a log line: {@link AuthManager#localDirectoryUsable} is the flag that actually makes
+     * it so. `localUserDirectory.findByUsername` reads Redis directly, so without this flag a record reconciled
+     * by an EARLIER successful boot would remain live — and would still authenticate — even on a boot where this
+     * method logs that every local sign-in will be refused. The flag defaults to `false` and is set `true` only
+     * at the very end of a successful reconcile that yielded at least one record; every failure path below
+     * returns (or rejects) without ever setting it, so it stays `false`.
+     * <br/>
+     * A failed read deliberately does NOT reconcile, so a broken volume mount leaves the stored records untouched
+     * instead of destroying them. They are inert while the load is failing — not because they are gone, but
+     * because {@link AuthManager#localDirectoryUsable} stays `false` and #authenticateLocal/authorize() both
+     * require it before ever consulting the directory.
+     *
+     * @method
+     * @returns {Promise}
+     */
+    #loadLocalUserDirectory() {
+        const usersPath = this.#authSettings.local?.usersPath;
+        if ( !usersPath ) {
+            this.#localDirectoryUsable = false;
+            logger.log( "Local authentication is enabled but no 'auth.local.usersPath' is configured (see TI_WEB_AUTH_LOCAL_USERS_PATH) — every local sign-in will be refused.", logger.logSeverity.WARNING );
+            return Promise.resolve();
+        }
+
+        let raw;
+        try {
+            raw = JSON.parse( fs.readFileSync( usersPath, "utf8" ) );
+        } catch ( error ) {
+            this.#localDirectoryUsable = false;
+            logger.log( `Could not read the local users file '${ usersPath }' — every local sign-in will be refused. Previously stored records are left untouched.`, logger.logSeverity.WARNING, exceptions.raise( error ) );
+            return Promise.resolve();
+        }
+
+        const parsed = localUserDirectory.parseRecords( raw );
+        parsed.problems.forEach( ( problem ) => {
+            logger.log( `Local users file '${ usersPath }': ${ problem }`, logger.logSeverity.WARNING );
+        } );
+        if ( parsed.records.length === 0 ) {
+            logger.log( `The local users file '${ usersPath }' yielded no usable records — every local sign-in will be refused.`, logger.logSeverity.WARNING );
+        }
+
+        return localUserDirectory.reconcile( parsed.records ).then( ( result ) => {
+            // Usable only when the reconcile actually produced at least one record — a file that parses cleanly
+            // but yields zero valid records (logged above) must refuse just as completely as one that could not
+            // be read at all.
+            this.#localDirectoryUsable = parsed.records.length > 0;
+            logger.log( `Local user directory reconciled: ${ result.added.length } added, ${ result.updated.length } updated, ${ result.removed.length } removed.`, logger.logSeverity.NOTICE );
+        } ).catch( ( error ) => {
+            this.#localDirectoryUsable = false;
+            // Log only the error's message and code — never the raw error object or an exception wrapping it.
+            // ioredis attaches `err.command = { name, args }` to reply errors and connection aborts, and
+            // `tools.errorToJSON` (invoked when the logger's data argument is an Error, including one wrapped by
+            // exceptions.raise) copies every own property, `command` included. For this call `args` is
+            // `[ "JSON.SET", localUserDirectory.CACHE_KEY, "$", <the entire directory JSON> ]`, so passing the
+            // raw error through here would print every local user's salt and scrypt hash at WARNING level on a
+            // WRONGTYPE, OOM, ACL failure, or mid-command disconnect. Do not "simplify" this back to
+            // `exceptions.raise( error )` or `error` directly.
+            logger.log( "Could not reconcile the local user directory — every local sign-in will be refused.", logger.logSeverity.WARNING, { message: error?.message, code: error?.code } );
+        } );
+    }
+
+    /**
+     * Verifies a local sign-in against the user directory.
+     * <br/>
+     * An unknown username still performs a hash computation against a placeholder before failing, so a missing user
+     * and a wrong password take comparable time. Without it the response time answers "does this username exist?",
+     * which turns the login form into an enumeration oracle.
+     * <br/>
+     * Requires {@link AuthManager#localDirectoryUsable} in addition to {@link AuthManager#isAuthEnabled} before
+     * ever calling `findByUsername` — that function reads Redis directly, so without this check a record
+     * reconciled by an earlier successful boot would still authenticate on a boot whose own load just failed.
+     * This check is a boot-time configuration gate, not a per-request secret, so it refuses immediately rather
+     * than through the timing-decoy path below.
      *
      * @method
      * @param {string} username
@@ -363,13 +497,20 @@ class AuthManager {
      * @returns {Promise}
      */
     #authenticateLocal( username, password ) {
-        return new Promise( ( resolve, reject ) => {
-            // TODO: Implement this!
-            if ( this.isAuthEnabled( authMethodEnum.LOCAL ) && ( username === this.#authSettings.local.username && password === this.#authSettings.local.password ) ) {
-                resolve();
-            } else {
-                reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
+        if ( !this.isAuthEnabled( authMethodEnum.LOCAL ) || !this.#localDirectoryUsable ) {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
+        }
+
+        const refuse = () => Promise.reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_401 ) );
+
+        return localUserDirectory.findByUsername( username ).then( ( record ) => {
+            if ( !record || record.disabled === true ) {
+                // Burn comparable time before refusing, so timing does not reveal whether the username exists.
+                return localUserDirectory.verifyPassword( password, AuthManager.#timingDecoyHash ).then( () => refuse() );
             }
+            return localUserDirectory.verifyPassword( password, record.passwordHash ).then( ( matches ) => {
+                return matches ? Promise.resolve() : refuse();
+            } );
         } );
     }
 

package/components/definitions.types.js

@@ -26,3 +26,68 @@
  * @property {(callback: TiSessionCallback) => TiSession} destroy
  * @property {(callback?: TiSessionCallback) => TiSession} save
  */
+
+/**
+ * One label/value pair inside a {@link TiInfoSection}. Both strings are display-ready — already localized and
+ * already formatted by the server, since that is where the session language and the label catalogue live. The
+ * three flags are purely presentational; an empty `value` renders the screen's placeholder.
+ *
+ * @typedef {Object} TiInfoItem
+ * @property {string} label
+ * @property {string} [value]
+ * @property {string} [href] Renders the value as a link to this target. Only `http:`, `https:` and `mailto:` are
+ * honoured — any other scheme is dropped client-side and the item degrades to plain text.
+ * @property {boolean} [wide] Span the full width of the section grid instead of one column.
+ * @property {boolean} [mono] Render the value in the monospaced face (IDs, versions, hashes).
+ * @property {boolean} [muted] Render the value as a dimmed hint rather than primary text.
+ */
+
+/**
+ * A titled group of label/value pairs. The framework's Profile and About screens render an array of these
+ * generically, so an application contributes content without contributing layout.
+ *
+ * @typedef {Object} TiInfoSection
+ * @property {string} title
+ * @property {string} [description] Optional intro line under the section title.
+ * @property {string} [icon] Optional `ti-icon` variant name for the section head.
+ * @property {boolean} [wide] Claim the full row of the two-up section grid instead of one column.
+ * @property {TiInfoItem[]} items A section with no items is dropped rather than rendered empty.
+ */
+
+/**
+ * The identity header of the Profile screen — the avatar/name block and the pills beside it.
+ *
+ * @typedef {Object} TiProfileIdentity
+ * @property {string} name
+ * @property {string} [subtitle] Meta line under the name (e.g. `role family · specialization · unit`).
+ * @property {string} [caption] Secondary line under the subtitle (e.g. the corporate e-mail).
+ * @property {string} [avatarSeed] Stable seed for the deterministic avatar colour; defaults to the name.
+ * @property {{text: string, tone?: string}} [badge] Small qualifier rendered inside the meta line.
+ * @property {Array<{text: string, tone?: string, dot?: boolean, mono?: boolean}>} [tags] Pills beside the name.
+ */
+
+/**
+ * The descriptor backing the framework Profile screen.
+ *
+ * @typedef {Object} TiProfileInfo
+ * @property {TiProfileIdentity} identity
+ * @property {TiInfoSection[]} sections
+ */
+
+/**
+ * The descriptor backing the framework About screen. Produced by `buildApplicationInfo` and optionally extended by
+ * the application through {@link TiWebAppManager#getApplicationInfo}.
+ *
+ * @typedef {Object} TiApplicationInfo
+ * @property {string} name Display name of the application.
+ * @property {string} packageName The npm package name it was resolved from.
+ * @property {string} version
+ * @property {string} releaseDate
+ * @property {string} description
+ * @property {string} license
+ * @property {string} homepage
+ * @property {string} author
+ * @property {Array<{name: string, version: string}>} components Framework component versions.
+ * @property {Object|null} runtime Runtime facts (node/platform/instance), or `null` when withheld.
+ * @property {TiInfoSection[]} sections Application-contributed extra sections.
+ */