@ti-engine/web-framework 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 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.23.0
+
+Local (username/password) authentication is real. It had never been implemented: the constructor overwrote whatever
+was configured with `admin`/`admin` behind a "for testing purposes only" TODO, the check was a plain `===` on both
+fields, and the session user it produced carried no email — which since `competence` began resolving identity by
+email meant a local sign-in could not reach an application at all.
+
+* feat(local-user-directory): new `#local-user-directory` module — a JSON file of user records loaded on boot and
+  reconciled into Redis under `ti:web:auth:local-users`. Records carry `username`, `email`, `name` and a
+  `passwordHash`; `email` is required, because it is the field a consuming application resolves an identity by. The
+  file is the source of truth: a boot reconcile adds, updates and **removes**, so deleting a user revokes access
+* feat(local-user-directory): scrypt password hashing via `node:crypto` — no new dependency — with a per-user random
+  salt and the cost parameters recorded in each hash, so they can be raised later without invalidating existing
+  hashes. Verification is timing-safe, and an unknown username still performs a hash computation so the login form
+  is not a username-enumeration oracle
+* feat(auth-manager)!: **the hardcoded `admin`/`admin` pair is gone.** Local sign-ins are verified against the
+  directory, and `authorize()` returns a `User` carrying `userID`, `username`, `email` and `name` instead of a
+  random-UUID stub. Any deployment relying on the hardcoded credentials must provision a users file
+* fix(auth-manager): a local user's `userID` is stable across logins. It was a fresh UUID each time, so
+  `auth.admins` could never match a local user by userID — only by username
+* feat(build): `npm run hash-password` generates a record's hash, reading the password from **stdin** rather than
+  argv, which would put it in shell history and in `ps`
+* feat(web-config-env): `TI_WEB_AUTH_LOCAL_USERS_PATH` overrides `auth.local.usersPath`
+* fix(auth-manager): close a fail-open found by the whole-branch review — `#authenticateLocal` and `authorize()`
+  consulted the Redis-backed directory directly, so a users file that failed to load (missing, unreadable, or
+  unconfigured) still authenticated against records reconciled by an **earlier successful boot**, even while
+  logging that every local sign-in would be refused. A new `#localDirectoryUsable` flag is required by both
+  before any lookup, and is set only after a load that reconciled at least one record. `authorize()` also now
+  refuses a `disabled` record on its own, rather than relying on `authenticate()` having already been called
+* fix(auth-manager): a Redis error during directory reconcile is now logged with only its `message`/`code` —
+  the raw ioredis error carries the failed command's full arguments, which for this call includes every user's
+  salt and scrypt hash, so logging it verbatim printed the entire directory's credential material at WARNING level
+* build(release): bump package version from `1.22.0` to `1.23.0`
+
+**Not included, and required before `local` is the sole method on an internet-facing deployment:** rate limiting,
+lockout after repeated failures, and password policy.
+
+## Version 1.22.0
+
+An application may now refuse a sign-in from its `augmentSession` hook, and that refusal is genuinely fail-closed.
+Sign-in failures also present identically across every auth method, which local (username/password) auth needs before
+it can be offered as a production option.
+
+* fix(web-handlers): destroy the session when an augment hook throws. `session.user` is assigned in place before the
+  hook runs and `verifySession` only checks that it exists, so a merely-rejected session was still persisted by
+  express-session at response end and would have admitted the refused user
+* feat(web-server): document the `augmentSession` refusal contract — throwing refuses the login, destroys the session,
+  and redirects to the login page carrying the exception code
+* feat(web-handlers): redirect any HTML-accepting, non-HTMX **401** to `/?error=<code>`, not only `GET` requests, so a
+  local-auth POST failure presents exactly like an OAuth callback failure. Non-401 responses are unaffected
+* feat(web-app): render the sign-in failure message on the login page. `#ti-error` was an empty element and the
+  `getUrlParam` helper had no call sites, so a failed sign-in previously returned a blank login form
+* feat(exports): expose the authorization helpers as `@ti-engine/web-framework/authorization`, so an application can
+  reuse `isAdminIdentity` for its own allowlist decisions instead of reimplementing the match
+* build(release): bump package version from `1.21.0` to `1.22.0`
+
 ## Version 1.21.0
 
 Two read-only screens the framework now provides for every consumer: **Profile** — which has been a registered

package/README.md

@@ -18,6 +18,7 @@ The web server configuration (host, port, TLS, cookies, etc.) is normally provid
 * `TI_WEB_TLS_CERT_PATH` / `TI_WEB_TLS_KEY_PATH` override the TLS certificate/key paths (only used when TLS is enabled).
 * `TI_WEB_COOKIE_SECRET` sets the session cookie signing secret. Set a stable, private value for durable sessions and multi-replica deployments (otherwise a random per-process value is used).
 * `TI_WEB_AUTH_METHODS` (comma-separated) **replaces** the enabled authentication methods (`auth.enabledMethods`), e.g. `openid-google` or `local,openid-google`.
+* `TI_WEB_AUTH_LOCAL_USERS_PATH` overrides the local user directory's file path (`auth.local.usersPath`), which backs `local` sign-in. An explicitly empty value means *no directory*, so every local sign-in is refused. See [Local (username/password) authentication](#local-usernamepassword-authentication).
 * `TI_WEB_AUTH_ADMINS` (comma-separated) **replaces** the admin allowlist (`auth.admins`). Entries are matched against the session user's user ID, username or email, so an OpenID deployment lists emails. An explicitly empty value means *no admins*.
 * `TI_WEB_TRUSTED_ORIGINS` (comma-separated) **replaces** the trusted request origins (`trustedOrigins`) — needed behind proxies that do not present the real external origin.
 * `TI_WEB_STATIC_MAX_AGE` (whole seconds) overrides `staticCache.maxAge`. See [Static asset caching](#static-asset-caching).
@@ -26,6 +27,57 @@ The web server configuration (host, port, TLS, cookies, etc.) is normally provid
 
 OpenID Connect providers are configured with their own variables — `TI_AZURE_AUTH_CLIENT_ID` / `TI_AZURE_AUTH_CLIENT_SECRET` / `TI_AZURE_AUTH_CALLBACK_URL` / `TI_AZURE_AUTH_DISCOVERY_URL`, and the `TI_GCLOUD_AUTH_*` equivalents. A callback URL may be given either as the full absolute URL registered with the provider (`https://your-host/login/azure-callback`) or as a path (`/login/azure-callback`): the server always listens on the path, while the `redirect_uri` sent to the provider is the absolute value verbatim if one was configured, and otherwise assembled from the request's forwarded protocol/host.
 
+## Authentication and authorization
+
+`TiWebServer#augmentSession` is the hook through which an application derives its own session roles — from an identity store, the org chart, or wherever a deployment keeps that mapping — once per login, before the framework's own additive `admin` role (`auth.admins`, see [Environment variables](#environment-variables)) is applied on top; the default is a no-op that returns the session unchanged. Throwing from the hook refuses the sign-in rather than admitting a session the application could not map to a principal: the framework destroys the freshly regenerated session so nothing usable survives the refusal, the login handler responds `401`, and the error handler sends the browser back to the login page with the exception code in the `?error=` query parameter — the same path a failed OpenID callback takes, regardless of which auth method was used.
+
+## Local (username/password) authentication
+
+`local` is one of the configurable `auth.enabledMethods` sign-in methods (see [Environment variables](#environment-variables), `TI_WEB_AUTH_METHODS`). It is backed by a JSON file of user records — there is no built-in account of any kind.
+
+### The users file
+
+`auth.local.usersPath` (override: `TI_WEB_AUTH_LOCAL_USERS_PATH`) points at a JSON file holding an array of records:
+
+```json
+[
+  {
+    "username": "jdoe",
+    "email": "jane.doe@example.com",
+    "name": "Jane Doe",
+    "passwordHash": "scrypt$16384$8$1$<salt-base64>$<hash-base64>"
+  }
+]
+```
+
+* `username`, `email`, `name` and `passwordHash` are required. `email` is required because a consuming application resolves the signed-in identity by it, the same way it would for an OpenID identity — a record with no email cannot reach an application at all.
+* `userID` is optional. When omitted, one is derived from the username, so it stays stable across restarts and logins; supply it explicitly only when something else needs to match a specific value (e.g. `auth.admins`).
+* `disabled: true` keeps the record (and its username) in the file while refusing every sign-in for it.
+
+Generate `passwordHash` with the bundled CLI. It reads the password from **stdin**, never an argument, so it never lands in shell history or a process listing (`ps`), and it never echoes the password back:
+
+```bash
+npm run hash-password -w @ti-engine/web-framework
+```
+
+Type or pipe the password, then EOF; only the resulting hash is written to stdout.
+
+That `npm run` form only works inside this monorepo (it is a workspace script). A consumer of the published `@ti-engine/web-framework` package has no `bin` entry to run it by name — the script ships under `bin/build/` regardless, so invoke it by its path inside `node_modules` instead:
+
+```bash
+node ./node_modules/@ti-engine/web-framework/bin/build/hash-password.js
+```
+
+### The file is the source of truth
+
+On every boot, the file is read and reconciled into the running directory: an added record starts working, a changed `passwordHash` takes effect, and — this is the point — **a record removed from the file is removed from the directory**, revoking that user's access on the next restart. Editing the file and restarting is the whole revocation mechanism; there is no separate delete action.
+
+### Every failure refuses rather than admits
+
+`local` enabled with no `auth.local.usersPath` configured, a file that cannot be read, a file that is not valid JSON, or a file that yields zero valid records after validation — each of these logs a startup **WARNING** and refuses every local sign-in, rather than admitting one or falling back to a default. A failed *read* deliberately does not reconcile, so a temporarily broken volume mount leaves previously stored records untouched instead of wiping them; those records stay inert (unused) while the load keeps failing, because sign-ins are refused anyway.
+
+**There is no rate limiting, no lockout after repeated failures, and no password policy.** Treat `local` on an internet-facing deployment as a deliberate risk until those exist.
+
 ## Static asset caching
 
 Everything under `/static` is served with a `Cache-Control` policy configured by the `staticCache` block:

package/bin/build/hash-password.js

@@ -0,0 +1,36 @@
+/*
+ * 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";
+
+/**
+ * Generates a password hash for a local-users file entry.
+ *
+ * Usage: npm run hash-password -w @ti-engine/web-framework
+ *
+ * The password is read from stdin, never from an argument: an argv value lands in shell history and is visible to
+ * every other user on the machine through `ps`. Only the resulting hash is written to stdout — the password itself
+ * is never echoed, logged, or written to a file by this tool.
+ */
+
+const directory = require( "#local-user-directory" );
+
+let input = "";
+process.stdin.setEncoding( "utf8" );
+process.stdin.on( "data", ( chunk ) => {
+    input += chunk;
+} );
+process.stdin.on( "end", () => {
+    // Strip only the trailing newline a shell or editor adds; a password may legitimately contain spaces.
+    const password = input.replace( /\r?\n$/, "" );
+    if ( password.length === 0 ) {
+        process.stderr.write( "hash-password: no password on stdin\n" );
+        process.exit( 1 );
+    }
+    process.stdout.write( directory.hashPassword( password ) + "\n" );
+} );

package/bin/config/local-users.example.json

@@ -0,0 +1,8 @@
+[
+  {
+    "username": "REPLACE-ME",
+    "email": "replace-me@example.com",
+    "name": "Replace Me",
+    "passwordHash": "GENERATE-WITH-npm-run-hash-password"
+  }
+]

package/bin/localization/web-server-labels.json

@@ -2,6 +2,10 @@
   "interface": {
     "default": {
       "login": {
+        "error-sign-in-failed": {
+          "en": "We couldn't sign you in. Check your credentials, or contact your administrator if your account is not set up for this application.",
+          "bg": "Неуспешно влизане. Проверете данните си за достъп или се свържете с администратора, ако акаунтът ви не е настроен за това приложение."
+        },
         "password": {
           "en": "Password",
           "bg": "Парола"

package/bin/static/fragments/frame-login.html

@@ -12,7 +12,12 @@
         <!-- Login card -->
         <div class="ti-login-card">
             <!-- Error message -->
-            <div id="ti-error" class="ti-login-error"></div>
+            <div id="ti-error"
+                 class="ti-login-error"
+                 x-data="tiLoginError"
+                 x-bind:class="{ visible: hasError }"
+                 role="alert"
+                 x-text-label="interface.default.login.error-sign-in-failed"></div>
 
             <!--ti-auth-method:local-->
             <!-- Local auth form -->

package/bin/static/scripts/ti-framework.css

@@ -2549,6 +2549,10 @@ body {
     border-radius: var(--r-md);
 }
 
+.ti-login-error.visible {
+    display: block;
+}
+
 .ti-login-form {
     display: flex;
     flex-direction: column;

package/bin/static/scripts/ti-framework.js

@@ -1615,6 +1615,28 @@ const configureScreenAbout = () => {
     };
 };
 
+/**
+ * Returns a configuration object for the login screen error message.
+ * <br/>
+ * The login handlers answer a failed sign-in with a `303` to `/?error=<code>` (see `defaultErrorHandler`). This reads
+ * that parameter and reveals the message element; the copy itself stays declarative via `x-text-label` so it localizes
+ * through the normal path. Deliberately independent of the throwaway test-user panel so it survives that panel's removal.
+ *
+ * @method
+ * @returns {Object}
+ * @public
+ */
+const configureLoginError = () => {
+    return {
+        hasError: false,
+
+        init() {
+            const tiToolbox = Alpine.store( "tiToolbox" );
+            this.hasError = Boolean( tiToolbox.getUrlParam( "error" ) );
+        }
+    };
+};
+
 /**
  * Returns a configuration object for the login screen test user pill panel.
  * <br/>
@@ -1738,6 +1760,7 @@ document.addEventListener( "alpine:init", () => {
     Alpine.data( "tiComponentNotificationBar", configureComponentNotificationBar );
     Alpine.data( "tiComponentTooltip", configureComponentTooltip );
     Alpine.data( "tiLoginTestUserPanel", configureLoginTestUserPanel );
+    Alpine.data( "tiLoginError", configureLoginError );
     Alpine.data( "tiScreenProfile", configureScreenProfile );
     Alpine.data( "tiScreenAbout", configureScreenAbout );
 } );

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

@@ -0,0 +1,428 @@
+/*
+ * 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/>.
+*/
+
+const crypto = require( "node:crypto" );
+const tools = require( "@ti-engine/core/tools" );
+const cache = require( "@ti-engine/core/cache" );
+
+/**
+ * @typedef {Object} LocalUserRecord
+ * @property {string} userID
+ * @property {string} username
+ * @property {string} email
+ * @property {string} name
+ * @property {string} passwordHash
+ * @property {boolean} disabled
+ */
+
+const ALGORITHM = "scrypt";
+
+const CACHE_KEY = "ti:web:auth:local-users";
+
+// scrypt at N=16384, r=8 needs 128 * N * r = 16 MiB, comfortably inside node's 32 MiB default `maxmem`.
+const HASH_DEFAULTS = Object.freeze( { N: 16384, r: 8, p: 1, saltBytes: 16, keyBytes: 64 } );
+
+// Minimums enforced by decodeHash so a truncated or hand-edited record is rejected at load time — where
+// parseRecords can report it — rather than silently authenticating with far less entropy than the encoding
+// implies (e.g. a copy-pasted base64 key cut short: Buffer.from() shortens it instead of throwing).
+const MIN_SALT_BYTES = 8;
+const MIN_KEY_BYTES = 32;
+
+// p multiplies scrypt's CPU cost linearly and sits outside node's `maxmem` guard, so a mistyped value would
+// hog a threadpool slot proportionally with no upper bound otherwise. The default is 1; 16 is ample headroom.
+const MAX_P = 16;
+
+// The lower bound a stored hash's N must clear before it is trusted, mirroring the salt/key length floors above:
+// the security level of a record must come from policy, not from whatever survived into the stored string.
+// Hardcoded to the same cost as HASH_DEFAULTS.N — deliberately NOT derived from it (e.g. `HASH_DEFAULTS.N`
+// itself), so an edit to HASH_DEFAULTS.N in isolation is caught by the invariant check below instead of the
+// floor silently tracking whatever the default becomes. Without this floor, `N & (N - 1)` still accepts any
+// power of two, so a truncated or mistyped N (16384 -> 16) loads clean and verifies almost for free.
+const MIN_N = 16384;
+
+// A hard ceiling on N, kept for two narrow reasons: `N & (N - 1)` coerces both operands to int32 to test the
+// power-of-two invariant, so it is only reliable strictly below 2^31 — at or above that a non-power-of-two value
+// can pass the check anyway — and N is scrypt's dominant CPU-cost multiplier with no cap of its own.
+// NOTE: this is NOT the effective ceiling, and an earlier version of this comment wrongly claimed it prevented
+// the "loads clean, then fails every verifyPassword call forever" lockout. It does not: the memory budget below
+// binds first by a wide margin. At the shipped r=8, N=32768 — a mere 2x the default and 32x below this value —
+// already exceeds the memory limit. Treat MAX_N as a backstop, not as a description of the usable range.
+const MAX_N = 2 ** 20;
+
+// scrypt's memory requirement, and the budget it must fit inside.
+//
+// `crypto.scrypt` rejects parameters needing more than `maxmem`, which Node defaults to 32 MiB. Neither
+// `deriveKey` nor `hashPassword` passes `maxmem`, so that default governs — deliberately: raising it would widen
+// what this published package permits and multiply peak memory across concurrent logins, each holding its budget
+// on a threadpool slot. The bound therefore matches the runtime's real limit rather than a limit of our choosing.
+//
+// The formula is the one OpenSSL actually applies — `128 * r * (N + 2 + p)`, the V array plus the B buffer — NOT
+// the frequently-quoted `128 * N * r`. That distinction is load-bearing: for N=16384/r=16 the naive form computes
+// exactly 33554432, at or under the 32 MiB budget, so a check written from it would ADMIT the very parameters it
+// exists to reject, while the true requirement is 33560576 and OpenSSL refuses. Verified against
+// `crypto.scryptSync` across the boundary; the accepted/rejected split matches this expression exactly.
+//
+// Without this bound a record whose parameters exceed the budget loads with zero reported problems and then makes
+// every verification fail forever — `verifyPassword`'s `.catch( () => false )` turns the
+// ERR_CRYPTO_INVALID_SCRYPT_PARAMS into an ordinary "wrong password", so the account is permanently locked out
+// and indistinguishable from a typo. With it, the record is rejected at load and named in the operator's warning.
+const SCRYPT_MAX_MEMORY_BYTES = 32 * 1024 * 1024;
+
+/**
+ * The memory `crypto.scrypt` requires for the given cost parameters, in bytes.
+ *
+ * @method
+ * @param {number} N
+ * @param {number} r
+ * @param {number} p
+ * @returns {number}
+ * @private
+ */
+function scryptMemoryRequirement( N, r, p ) {
+    return 128 * r * ( N + 2 + p );
+}
+
+// Invariant: MIN_N must never be stricter than the cost this module itself mints new hashes at, or a hash
+// produced by hashPassword() today could be rejected by decodeHash() tomorrow. Asserted at module load, not
+// only documented in the comment above, so a future edit to either constant that breaks the relationship fails
+// loudly at require() time instead of silently shipping a directory that can never authenticate its own
+// freshly-hashed passwords.
+if ( MIN_N > HASH_DEFAULTS.N ) {
+    throw new Error( "local-user-directory: MIN_N must not exceed HASH_DEFAULTS.N — every hash minted by hashPassword() must clear decodeHash()'s own floor" );
+}
+
+/**
+ * Derives a key with scrypt. Asynchronous on purpose: `scryptSync` blocks the event loop for roughly 100 ms at
+ * these parameters, which on a login endpoint is a self-inflicted denial of service.
+ *
+ * @param {string} password
+ * @param {Buffer} salt
+ * @param {{N: number, r: number, p: number}} parameters
+ * @param {number} keyBytes
+ * @returns {Promise<Buffer>}
+ */
+function deriveKey( password, salt, parameters, keyBytes ) {
+    return new Promise( ( resolve, reject ) => {
+        crypto.scrypt( password, salt, keyBytes, parameters, ( error, key ) => {
+            if ( error ) {
+                reject( error );
+            } else {
+                resolve( key );
+            }
+        } );
+    } );
+}
+
+/**
+ * Splits an encoded hash into its parameters and material, or returns `null` when it is not a recognized
+ * encoding — including a structurally valid one whose cost parameters or material fall outside the minimums
+ * this module enforces (a non-power-of-two `N`, an excessive `p`, or salt/key material too short to trust).
+ *
+ * @param {string} encoded
+ * @returns {{parameters: {N: number, r: number, p: number}, salt: Buffer, key: Buffer}|null}
+ */
+function decodeHash( encoded ) {
+    if ( typeof encoded !== "string" ) {
+        return null;
+    }
+    const parts = encoded.split( "$" );
+    if ( parts.length !== 6 || parts[ 0 ] !== ALGORITHM ) {
+        return null;
+    }
+    const [ , rawN, rawR, rawP, rawSalt, rawKey ] = parts;
+    const N = Number( rawN );
+    const r = Number( rawR );
+    const p = Number( rawP );
+    // N is bounded on both sides by MIN_N/MAX_N (see their comments above) before the power-of-two test below —
+    // a value outside that range must never reach it, since the bitwise check alone is silently unreliable past
+    // the int32 boundary and provides no floor against a cost that is technically a power of two but far too
+    // cheap to trust.
+    if ( !Number.isInteger( N ) || !Number.isInteger( r ) || !Number.isInteger( p ) || N < MIN_N || N > MAX_N || r < 1 || p < 1 || p > MAX_P ) {
+        return null;
+    }
+    // crypto.scrypt requires N to be a power of two; anything else throws ERR_CRYPTO_INVALID_SCRYPT_PARAMS at
+    // derive time. verifyPassword's `.catch(() => false)` swallows that into an ordinary "wrong password", so
+    // without this check an operator would see permanent, silent failed logins with nothing reported anywhere.
+    if ( ( N & ( N - 1 ) ) !== 0 ) {
+        return null;
+    }
+    // The memory bound. Reached only once N/r/p are individually sane, because it is the combination that matters:
+    // every one of N=16384/r=16, N=32768/r=8 and N=65536/r=8 has each value in range yet needs more than the
+    // budget, and each one would otherwise load clean and then never verify again. There is deliberately no
+    // separate ceiling on `r` — r only matters through this requirement, and a standalone limit would either
+    // duplicate this one or contradict it.
+    if ( scryptMemoryRequirement( N, r, p ) > SCRYPT_MAX_MEMORY_BYTES ) {
+        return null;
+    }
+    try {
+        const salt = Buffer.from( rawSalt, "base64" );
+        const key = Buffer.from( rawKey, "base64" );
+        // Minimum lengths, not just non-empty: the security level of a record must come from policy, not from
+        // whatever happened to survive into the stored string. A truncated key still decodes without error
+        // (Buffer.from() shortens rather than throwing on invalid/incomplete base64), so length is the only
+        // signal left to catch it.
+        if ( salt.length < MIN_SALT_BYTES || key.length < MIN_KEY_BYTES ) {
+            return null;
+        }
+        return { parameters: { N: N, r: r, p: p }, salt: salt, key: key };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Hashes a password for storage in a local-users file. Synchronous because its only caller is the one-shot CLI,
+ * where blocking is free — never call it on a request path.
+ *
+ * @method
+ * @param {string} password
+ * @returns {string} The encoded hash: `scrypt$N$r$p$salt$hash`, base64 salt and key.
+ * @throws {TypeError} If `password` is empty or not a string — `verifyPassword` refuses empty passwords, so
+ *         hashing one here would only mint a hash that can never be logged into.
+ * @public
+ */
+function hashPassword( password ) {
+    if ( typeof password !== "string" || password.length === 0 ) {
+        throw new TypeError( "hashPassword requires a non-empty string password" );
+    }
+    const salt = crypto.randomBytes( HASH_DEFAULTS.saltBytes );
+    const parameters = { N: HASH_DEFAULTS.N, r: HASH_DEFAULTS.r, p: HASH_DEFAULTS.p };
+    const key = crypto.scryptSync( password, salt, HASH_DEFAULTS.keyBytes, parameters );
+    return [ ALGORITHM, parameters.N, parameters.r, parameters.p, salt.toString( "base64" ), key.toString( "base64" ) ].join( "$" );
+}
+
+/**
+ * Verifies a password against an encoded hash. The cost parameters come from the stored string rather than the
+ * current defaults, so raising the defaults never invalidates an existing hash.
+ *
+ * @method
+ * @param {string} password
+ * @param {string} encoded
+ * @returns {Promise<boolean>} `false` for a malformed encoding or an absent password — never a throw, because a
+ *          bad stored value must read as "does not match", not as a server error on the login path.
+ * @public
+ */
+function verifyPassword( password, encoded ) {
+    const decoded = decodeHash( encoded );
+    if ( !decoded || typeof password !== "string" || password.length === 0 ) {
+        return Promise.resolve( false );
+    }
+    return deriveKey( password, decoded.salt, decoded.parameters, decoded.key.length )
+        // Compared as base64 strings, not raw Buffers: constantTimeEquals coerces each argument with
+        // `String(x || "")`, which would utf8-decode a key Buffer lossily (through U+FFFD replacement for any
+        // byte sequence that is not valid UTF-8) instead of comparing its bytes — silently breaking the
+        // comparison. Base64 text round-trips through String() exactly, so it stays safe to pass here.
+        .then( ( key ) => tools.constantTimeEquals( key.toString( "base64" ), decoded.key.toString( "base64" ) ) )
+        .catch( () => false );
+}
+
+// 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,
+// 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` —
+//   `JSON.stringify( _.toPlainObject( decycle( value ) ) )` in @ti-engine/core/utils/tools.js. `decycle`'s
+//   object-copy branch built each replica with `newItem = {}; newItem[ name ] = derez( ... )`; for
+//   `name === "__proto__"` that assignment invoked the inherited accessor setter instead of creating an own key,
+//   repointing the replica's own prototype to the record. `_.toPlainObject` then flattened that prototype chain
+//   back into own keys, so the record's fields were spliced into the top level of the *entire* stored directory
+//   rather than merely dropped.
+//   **core 1.11.0 fixed that** (its `decycle` builds the replica with `Object.create( null )`), so against a
+//   current core the round-trip is intact — the test in local-user-directory.store.test.js now pins the fixed
+//   behaviour. The rejection stays regardless, and not as vague defence in depth: this package declares
+//   `"@ti-engine/core": "*"`, so a consumer of the published web-framework may pair it with any core, including
+//   a pre-1.11.0 one that still corrupts. web-framework cannot guarantee the serializer beneath it is fixed, so
+//   it must not accept a record it might be unable to represent.
+// - 'constructor' and 'prototype' round-trip through that same pipeline correctly (verified the same way).
+//   'constructor' is hazardous only for an *unguarded read* (`stored.constructor` resolves to the inherited
+//   Object constructor function when absent) — exactly what the hasOwnProperty guards in reconcile/
+//   findByUsername below exist to prevent — and 'prototype' collides with nothing in a plain object's
+//   prototype chain at all. Both are rejected anyway so this stays the same trio as everywhere else in the
+//   codebase, rather than a bespoke subset that has to be re-derived from this file's current implementation
+//   details every time something downstream changes.
+// Do not "simplify" this back down to just '__proto__' on the assumption that only it is provably broken
+// today — re-verify all three empirically first, the same way this comment's claims were verified, before
+// removing any of them (including after @ti-engine/core's decycle/stringifyJSON pipeline is eventually fixed).
+const RESERVED_USERNAMES = new Set( [ "__proto__", "constructor", "prototype" ] );
+
+/**
+ * Validates raw file content into records, reporting why any entry was excluded. Never throws: a malformed row is
+ * data, not a crash, so one bad entry cannot take an instance down.
+ *
+ * @method
+ * @param {*} raw
+ * @returns {{records: LocalUserRecord[], problems: string[]}}
+ * @public
+ */
+function parseRecords( raw ) {
+    const problems = [];
+    if ( !Array.isArray( raw ) ) {
+        return { records: [], problems: [ "the local users file must contain a JSON array of user records" ] };
+    }
+
+    const records = [];
+    const seen = new Set();
+    raw.forEach( ( entry, index ) => {
+        if ( !entry || typeof entry !== "object" || Array.isArray( entry ) ) {
+            problems.push( `entry ${ index } is not an object` );
+            return;
+        }
+        const username = typeof entry.username === "string" ? entry.username.trim() : "";
+        const email = typeof entry.email === "string" ? entry.email.trim() : "";
+        const passwordHash = typeof entry.passwordHash === "string" ? entry.passwordHash.trim() : "";
+
+        if ( !username ) {
+            problems.push( `entry ${ index } has no username` );
+            return;
+        }
+        // See the RESERVED_USERNAMES comment above: the storage layer cannot represent one of these three
+        // names without corrupting the directory (confirmed for '__proto__'; the other two are rejected for
+        // consistency), so a record using one is refused here — at load, where an operator sees why — rather
+        // than accepted and silently corrupted or lost the first time it is actually written.
+        if ( RESERVED_USERNAMES.has( username ) ) {
+            problems.push( `user '${ username }' cannot be stored — '${ username }' is a reserved name that collides with JavaScript's object model, not a typo` );
+            return;
+        }
+        if ( !email ) {
+            problems.push( `user '${ username }' has no email, which is the field an application resolves identity by` );
+            return;
+        }
+        if ( !passwordHash || !decodeHash( passwordHash ) ) {
+            problems.push( `user '${ username }' has no usable passwordHash — generate one with \`npm run hash-password -w @ti-engine/web-framework\`` );
+            return;
+        }
+        // Usernames are matched exactly, so a repeat is a genuine duplicate. Keyed storage would silently keep the
+        // last one and leave the operator unable to tell which password is live, so it is reported instead.
+        //
+        // A duplicate *email* is deliberately not checked here, unlike a duplicate username: two credentials
+        // sharing an email still resolve deterministically to the same person, so there is no "which password
+        // is live" ambiguity the way there is for a repeated username. This asymmetry is intentional, not an
+        // oversight.
+        if ( seen.has( username ) ) {
+            problems.push( `duplicate username '${ username }' at entry ${ index } — ignored, the first occurrence is kept` );
+            return;
+        }
+        seen.add( username );
+
+        records.push( {
+            userID: ( typeof entry.userID === "string" && entry.userID.trim() ) || `local:${ username }`,
+            username: username,
+            email: email,
+            name: ( typeof entry.name === "string" && entry.name.trim() ) || username,
+            passwordHash: passwordHash,
+            disabled: entry.disabled === true
+        } );
+    } );
+
+    return { records: records, problems: problems };
+}
+
+/**
+ * Reads the whole stored directory, or an empty object when it has never been written.
+ * <br/>
+ * `cache.instance.getJSON` queries the `$` root, and RedisJSON's JSONPath contract wraps that result in a
+ * single-element array on a hit — mirrored deliberately by the in-memory test double (see its own doc comment)
+ * and already unwrapped once in this package by `ConfigStore#readJSON`. The same unwrap happens here, otherwise
+ * every read after the first write would misread a populated directory as empty.
+ * <br/>
+ * A genuine Redis failure is deliberately left to propagate rather than caught here: swallowing it into `{}`
+ * would make an outage indistinguishable from "no users configured", silently failing every local login as
+ * "no such user" instead of surfacing the outage to the caller.
+ *
+ * @returns {Promise<Object>}
+ */
+function readStored() {
+    return cache.instance.getJSON( CACHE_KEY ).then( ( result ) => {
+        const stored = Array.isArray( result ) ? ( result[ 0 ] ?? null ) : ( result ?? null );
+        return ( stored && typeof stored === "object" && !Array.isArray( stored ) ) ? stored : {};
+    } );
+}
+
+/**
+ * Writes the records as the complete directory, keyed by username, and reports what changed.
+ * <br/>
+ * The whole set is written rather than patched because the file is the source of truth: a username absent from
+ * `records` must disappear, which is what makes revocation-by-file-edit work. `@ti-engine/core/cache` exposes no
+ * delete, so a whole-object write is also the only way to remove a key.
+ * <br/>
+ * Usernames are attacker-influenceable (the local sign-in handler resolves them from request input), so both the write
+ * and every read below are guarded against `Object.prototype`'s reserved names rather than trusting plain bracket
+ * access:
+ * <br/>
+ * - `incoming` is built with a null prototype (`Object.create( null )`) so it inherits nothing. On an ordinary
+ *   `{}`, `incoming[ "__proto__" ] = record` would not create an own key at all — it would invoke the inherited
+ *   `__proto__` setter and silently repoint the object's own prototype to `record`, so the record never shows up
+ *   in `Object.keys`/`JSON.stringify` and is never persisted, without error. On a null-prototype object that
+ *   setter does not exist anywhere on the (empty) prototype chain, so the assignment falls back to creating a
+ *   perfectly ordinary own data property instead — confirmed empirically (see the test file) that this still
+ *   `JSON.stringify`s and round-trips normally.
+ * - Every classification read below checks ownership with `Object.prototype.hasOwnProperty.call(...)` rather than
+ *   relying on truthiness, because `stored` comes back from `readStored()` — ultimately a `JSON.parse` result —
+ *   with the ordinary `Object.prototype` chain. An unguarded `stored[ "constructor" ]` would resolve to the
+ *   inherited `Object` constructor function (always truthy) rather than "not present", misclassifying a
+ *   first-time `constructor`-named user as `updated` instead of `added`, and hiding its removal from `removed`.
+ *
+ * @method
+ * @param {LocalUserRecord[]} records
+ * @returns {Promise<{added: string[], updated: string[], removed: string[]}>}
+ * @public
+ */
+function reconcile( records ) {
+    const incoming = Object.create( null );
+    ( Array.isArray( records ) ? records : [] ).forEach( ( record ) => {
+        incoming[ record.username ] = record;
+    } );
+
+    return readStored().then( ( stored ) => {
+        const added = [];
+        const updated = [];
+        Object.keys( incoming ).forEach( ( username ) => {
+            // Ownership check, not truthiness — see the function doc comment: `stored[ username ]` alone would
+            // resolve a username of 'constructor' to the inherited Object constructor instead of "not present".
+            if ( !Object.prototype.hasOwnProperty.call( stored, username ) ) {
+                added.push( username );
+            } else if ( JSON.stringify( stored[ username ] ) !== JSON.stringify( incoming[ username ] ) ) {
+                updated.push( username );
+            }
+        } );
+        // Same reasoning in the other direction: `incoming` is null-prototype, so this is already safe, but the
+        // explicit ownership check keeps both classification directions visibly consistent for the same reason.
+        const removed = Object.keys( stored ).filter( ( username ) => !Object.prototype.hasOwnProperty.call( incoming, username ) );
+
+        return cache.instance.setJSON( CACHE_KEY, incoming ).then( () => {
+            return { added: added, updated: updated, removed: removed };
+        } );
+    } );
+}
+
+/**
+ * Looks a user up by exact username.
+ * <br/>
+ * `username` here is attacker-influenceable — this is the function the local sign-in handler calls with the
+ * value a client typed into the username field. Checked with `Object.prototype.hasOwnProperty.call(...)` rather than
+ * `stored[ username ] || null`, because `stored` carries the ordinary `Object.prototype` chain and an unguarded
+ * bracket read would resolve `findByUsername( "constructor" )` to the inherited `Object` constructor function
+ * instead of `null`, violating the declared return type for nearly every real query.
+ *
+ * @method
+ * @param {string} username
+ * @returns {Promise<LocalUserRecord|null>}
+ * @public
+ */
+function findByUsername( username ) {
+    if ( typeof username !== "string" || username.length === 0 ) {
+        return Promise.resolve( null );
+    }
+    return readStored().then( ( stored ) => {
+        return Object.prototype.hasOwnProperty.call( stored, username ) ? stored[ username ] : null;
+    } );
+}
+
+module.exports = { ALGORITHM, CACHE_KEY, HASH_DEFAULTS, hashPassword, verifyPassword, parseRecords, reconcile, findByUsername };

package/components/web-config-env.js

@@ -15,7 +15,7 @@ const tools = require( "@ti-engine/core/tools" );
  * Each override is applied ONLY when its environment variable is defined, so an absent variable leaves the
  * configured/default value untouched (fully backward compatible). This gives ti-engine web servers 12-factor,
  * container-friendly control over network binding, TLS, the session cookie secret, the enabled authentication
- * methods, the admin allowlist, the trusted request origins, and the `/static` cache policy without editing config files. Note `TI_WEB_AUTH_METHODS`,
+ * methods, the admin allowlist, the local auth users file path, the trusted request origins, and the `/static` cache policy without editing config files. Note `TI_WEB_AUTH_METHODS`,
  * `TI_WEB_AUTH_ADMINS`, `TI_WEB_TRUSTED_ORIGINS`, and `TI_WEB_STATIC_IMMUTABLE_PATHS` fully REPLACE their config arrays (`auth.enabledMethods` / `auth.admins` / `trustedOrigins` / `staticCache.immutablePaths`) rather than
  * merging — the config-file merge is by-index and cannot cleanly override an array.
  *
@@ -59,6 +59,11 @@ function applyWebConfigEnvOverrides( config, env = process.env ) {
         config.auth = config.auth || {};
         config.auth.admins = env.TI_WEB_AUTH_ADMINS.split( "," ).map( ( entry ) => entry.trim() ).filter( ( entry ) => entry.length > 0 );
     }
+    if ( env.TI_WEB_AUTH_LOCAL_USERS_PATH !== undefined ) {
+        config.auth = config.auth || {};
+        config.auth.local = config.auth.local || {};
+        config.auth.local.usersPath = env.TI_WEB_AUTH_LOCAL_USERS_PATH;
+    }
     if ( env.TI_WEB_TRUSTED_ORIGINS !== undefined ) {
         config.trustedOrigins = env.TI_WEB_TRUSTED_ORIGINS.split( "," ).map( ( origin ) => origin.trim() ).filter( ( origin ) => origin.length > 0 );
     }

package/components/web-handlers.js

@@ -172,7 +172,13 @@ let regenerateAndSaveSession = ( request, redirectTo, modifier ) => {
                         request.session = modifier( request.session );
                     }
                 } catch ( error ) {
-                    reject( error );
+                    // The application's augment hook refused this login. `session.user` was already assigned in place
+                    // before the hook ran, and `verifySession` only checks that it exists — so a merely-rejected
+                    // session would still be persisted by express-session at response end and would admit the user.
+                    // Destroy it before rejecting so a refusal is genuinely fail-closed.
+                    request.session.destroy( () => {
+                        reject( error );
+                    } );
                     return;
                 }
                 request.session.save( ( error ) => {
@@ -528,7 +534,9 @@ module.exports.defaultErrorHandler = () => {
                     } )
                 } );
                 return response.status( status ).send( "" );
-            } else if ( isAcceptingResponseType( request, "html" ) && request.method === "GET" ) {
+                // A 401 on an HTML request means "you are not signed in" whatever the method — the useful answer is the
+                // sign-in page carrying the reason, so local auth's POST presents exactly like the OAuth callback's GET.
+            } else if ( isAcceptingResponseType( request, "html" ) && ( request.method === "GET" || status === exceptions.httpCode.C_401 ) ) {
                 response.redirect( exceptions.httpCode.C_303, "/?error=" + encodeURIComponent( exception.code ) );
             } else {
                 response.status( status ).send( payload );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/web-framework",
-  "version": "1.21.0",
+  "version": "1.23.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",
@@ -27,6 +27,10 @@
       "types": "./types/bin/web-server.d.ts",
       "default": "./bin/web-server.js"
     },
+    "./authorization": {
+      "types": "./types/components/authorization.d.ts",
+      "default": "./components/authorization.js"
+    },
     "./definitions": {
       "types": "./types/components/definitions.types.d.ts",
       "default": "./components/definitions.types.js"
@@ -69,6 +73,10 @@
       "types": "./types/components/definitions.types.d.ts",
       "default": "./components/definitions.types.js"
     },
+    "#local-user-directory": {
+      "types": "./types/components/local-user-directory.d.ts",
+      "default": "./components/local-user-directory.js"
+    },
     "#session-store": {
       "types": "./types/components/session-store.d.ts",
       "default": "./components/session-store.js"
@@ -138,6 +146,7 @@
   "scripts": {
     "postinstall": "node ./bin/build/post-install.js",
     "test": "node --test test/*.test.js",
-    "build:types": "tsc -p tsconfig.types.json"
+    "build:types": "tsc -p tsconfig.types.json",
+    "hash-password": "node ./bin/build/hash-password.js"
   }
 }

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

@@ -13,12 +13,19 @@ export type ApiConfig = {
 };
 export type SettingsAuth = {
     enabledMethods: string[];
-    local: Object;
+    local: SettingsAuthLocal;
     oauth2: {
         azure?: SettingsOAuth2Client;
         google?: SettingsOAuth2Client;
     };
 };
+export type SettingsAuthLocal = {
+    /**
+     * 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.
+     */
+    usersPath?: string;
+};
 export type SettingsOAuth2Client = {
     clientID?: string;
     clientSecret?: string;
@@ -179,6 +186,11 @@ declare 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
@@ -200,6 +212,12 @@ declare class TiWebServer extends ServiceConsumer {
     authenticate(authMethod: TiAuthMethod, authDetails?: Object): Promise<any>;
     /**
      * 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/types/components/auth-manager.d.ts

@@ -70,6 +70,13 @@ declare class AuthManager {
     authenticate(authMethod: TiAuthMethod, authDetails: Object): Promise<Object>;
     /**
      * 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

package/types/components/local-user-directory.d.ts

@@ -0,0 +1,111 @@
+declare const _exports: {
+    ALGORITHM: string;
+    CACHE_KEY: string;
+    HASH_DEFAULTS: Readonly<{
+        N: 16384;
+        r: 8;
+        p: 1;
+        saltBytes: 16;
+        keyBytes: 64;
+    }>;
+    hashPassword: typeof hashPassword;
+    verifyPassword: typeof verifyPassword;
+    parseRecords: typeof parseRecords;
+    reconcile: typeof reconcile;
+    findByUsername: typeof findByUsername;
+};
+export = _exports;
+export type LocalUserRecord = {
+    userID: string;
+    username: string;
+    email: string;
+    name: string;
+    passwordHash: string;
+    disabled: boolean;
+};
+/**
+ * Hashes a password for storage in a local-users file. Synchronous because its only caller is the one-shot CLI,
+ * where blocking is free — never call it on a request path.
+ *
+ * @method
+ * @param {string} password
+ * @returns {string} The encoded hash: `scrypt$N$r$p$salt$hash`, base64 salt and key.
+ * @throws {TypeError} If `password` is empty or not a string — `verifyPassword` refuses empty passwords, so
+ *         hashing one here would only mint a hash that can never be logged into.
+ * @public
+ */
+declare function hashPassword(password: string): string;
+/**
+ * Verifies a password against an encoded hash. The cost parameters come from the stored string rather than the
+ * current defaults, so raising the defaults never invalidates an existing hash.
+ *
+ * @method
+ * @param {string} password
+ * @param {string} encoded
+ * @returns {Promise<boolean>} `false` for a malformed encoding or an absent password — never a throw, because a
+ *          bad stored value must read as "does not match", not as a server error on the login path.
+ * @public
+ */
+declare function verifyPassword(password: string, encoded: string): Promise<boolean>;
+/**
+ * Validates raw file content into records, reporting why any entry was excluded. Never throws: a malformed row is
+ * data, not a crash, so one bad entry cannot take an instance down.
+ *
+ * @method
+ * @param {*} raw
+ * @returns {{records: LocalUserRecord[], problems: string[]}}
+ * @public
+ */
+declare function parseRecords(raw: any): {
+    records: LocalUserRecord[];
+    problems: string[];
+};
+/**
+ * Writes the records as the complete directory, keyed by username, and reports what changed.
+ * <br/>
+ * The whole set is written rather than patched because the file is the source of truth: a username absent from
+ * `records` must disappear, which is what makes revocation-by-file-edit work. `@ti-engine/core/cache` exposes no
+ * delete, so a whole-object write is also the only way to remove a key.
+ * <br/>
+ * Usernames are attacker-influenceable (the local sign-in handler resolves them from request input), so both the write
+ * and every read below are guarded against `Object.prototype`'s reserved names rather than trusting plain bracket
+ * access:
+ * <br/>
+ * - `incoming` is built with a null prototype (`Object.create( null )`) so it inherits nothing. On an ordinary
+ *   `{}`, `incoming[ "__proto__" ] = record` would not create an own key at all — it would invoke the inherited
+ *   `__proto__` setter and silently repoint the object's own prototype to `record`, so the record never shows up
+ *   in `Object.keys`/`JSON.stringify` and is never persisted, without error. On a null-prototype object that
+ *   setter does not exist anywhere on the (empty) prototype chain, so the assignment falls back to creating a
+ *   perfectly ordinary own data property instead — confirmed empirically (see the test file) that this still
+ *   `JSON.stringify`s and round-trips normally.
+ * - Every classification read below checks ownership with `Object.prototype.hasOwnProperty.call(...)` rather than
+ *   relying on truthiness, because `stored` comes back from `readStored()` — ultimately a `JSON.parse` result —
+ *   with the ordinary `Object.prototype` chain. An unguarded `stored[ "constructor" ]` would resolve to the
+ *   inherited `Object` constructor function (always truthy) rather than "not present", misclassifying a
+ *   first-time `constructor`-named user as `updated` instead of `added`, and hiding its removal from `removed`.
+ *
+ * @method
+ * @param {LocalUserRecord[]} records
+ * @returns {Promise<{added: string[], updated: string[], removed: string[]}>}
+ * @public
+ */
+declare function reconcile(records: LocalUserRecord[]): Promise<{
+    added: string[];
+    updated: string[];
+    removed: string[];
+}>;
+/**
+ * Looks a user up by exact username.
+ * <br/>
+ * `username` here is attacker-influenceable — this is the function the local sign-in handler calls with the
+ * value a client typed into the username field. Checked with `Object.prototype.hasOwnProperty.call(...)` rather than
+ * `stored[ username ] || null`, because `stored` carries the ordinary `Object.prototype` chain and an unguarded
+ * bracket read would resolve `findByUsername( "constructor" )` to the inherited `Object` constructor function
+ * instead of `null`, violating the declared return type for nearly every real query.
+ *
+ * @method
+ * @param {string} username
+ * @returns {Promise<LocalUserRecord|null>}
+ * @public
+ */
+declare function findByUsername(username: string): Promise<LocalUserRecord | null>;

package/types/components/web-config-env.d.ts

@@ -4,7 +4,7 @@ export = applyWebConfigEnvOverrides;
  * Each override is applied ONLY when its environment variable is defined, so an absent variable leaves the
  * configured/default value untouched (fully backward compatible). This gives ti-engine web servers 12-factor,
  * container-friendly control over network binding, TLS, the session cookie secret, the enabled authentication
- * methods, the admin allowlist, the trusted request origins, and the `/static` cache policy without editing config files. Note `TI_WEB_AUTH_METHODS`,
+ * methods, the admin allowlist, the local auth users file path, the trusted request origins, and the `/static` cache policy without editing config files. Note `TI_WEB_AUTH_METHODS`,
  * `TI_WEB_AUTH_ADMINS`, `TI_WEB_TRUSTED_ORIGINS`, and `TI_WEB_STATIC_IMMUTABLE_PATHS` fully REPLACE their config arrays (`auth.enabledMethods` / `auth.admins` / `trustedOrigins` / `staticCache.immutablePaths`) rather than
  * merging — the config-file merge is by-index and cannot cleanly override an array.
  *