@ti-engine/web-framework 1.21.0 → 1.24.0

package/CHANGELOG.md

@@ -2,6 +2,88 @@
 
 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.24.0
+
+A configuration file change shipped in a release could never reach a deployment that had already been seeded. The
+store writes a file default only when the document has never been written, and the consuming application then lets
+the stored value overwrite the file value on every boot — so the file default is consulted exactly once in a
+deployment's lifetime. Restore could not help either, since it replays a previous version and the oldest version
+*is* the stale one. The framework now detects that difference and lets an admin apply it deliberately.
+
+* feat(config-drift): new `#config-drift` module — a pure structural diff between a document's registered file
+  default and its stored value. Recurses into objects to report leaf paths, **set-diffs arrays of primitives** so a
+  code-list change reads as `+27 codes` rather than an opaque "changed", and compares arrays of objects atomically.
+  Paths use the same dot/bracket dialect as schema validation issues
+* feat(config-service): `getDrift`, `listDrift` and `applyDefaults`. Applying routes through `applyEdits`, so a
+  file default lands validated, versioned, correlated into one change-set, in the audit feed, and restorable —
+  never as a side-channel write
+* feat(config-service): interdependent documents apply as a **single** change-set, which is required rather than
+  merely convenient: a semantic validator resolves its siblings at their *pending* value, so a document whose
+  constraint spans another can only pass when both are applied together
+* feat(admin-config-handlers): `GET /admin/config/drift`, `GET /admin/config/drift/:configKey` and
+  `POST /admin/config/drift/apply`, all admin-gated
+* build(release): bump package version from `1.23.0` to `1.24.0`
+
+**Note on statuses:** `absent` (never seeded) is deliberately distinct from `drifted`. A document that is registered
+but never seeded is not a problem to act on, and folding the two together would flag it on every boot of a clean
+install — training operators to ignore exactly the signal this feature exists to raise.
+
+## 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
@@ -568,6 +585,9 @@ class TiWebServer extends ServiceConsumer {
         this.#webServer.get( "/admin/config/changes/:changeSetID", requireAdmin, adminConfigHandlers.getChange( service ) );
         this.#webServer.post( "/admin/config/changes/:changeSetID/restore", requireAdmin, adminConfigHandlers.restoreChangeSet( service ) );
         this.#webServer.get( "/admin/config/export", requireAdmin, adminConfigHandlers.exportBundle( service ) );
+        this.#webServer.get( "/admin/config/drift", requireAdmin, adminConfigHandlers.listDrift( service ) );
+        this.#webServer.get( "/admin/config/drift/:configKey", requireAdmin, adminConfigHandlers.getDrift( service ) );
+        this.#webServer.post( "/admin/config/drift/apply", requireAdmin, adminConfigHandlers.applyDefaults( service ) );
     }
 
     /**

package/bin/web-server.json

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

package/components/admin-config-handlers.js

@@ -93,3 +93,34 @@ module.exports.exportBundle = ( service ) => ( request, response, next ) => {
         response.status( exceptions.httpCode.C_200 ).send( JSON.stringify( bundle, null, 2 ) );
     } ).catch( ( error ) => forward( next, error ) );
 };
+
+/**
+ * `GET /admin/config/drift` — drift summaries for every registered document.
+ *
+ * @param {ConfigService} service
+ * @returns {ExpressHandler} The Express handler.
+ */
+module.exports.listDrift = ( service ) => ( request, response, next ) => {
+    service.listDrift().then( ( drift ) => sendData( response, drift ) ).catch( ( error ) => forward( next, error ) );
+};
+
+/**
+ * `GET /admin/config/drift/:configKey` — one document's drift, including the full entry list.
+ *
+ * @param {ConfigService} service
+ * @returns {ExpressHandler} The Express handler.
+ */
+module.exports.getDrift = ( service ) => ( request, response, next ) => {
+    service.getDrift( request.params.configKey ).then( ( drift ) => sendData( response, drift ) ).catch( ( error ) => forward( next, error ) );
+};
+
+/**
+ * `POST /admin/config/drift/apply` — applies the file defaults for the named documents as one change-set.
+ *
+ * @param {ConfigService} service
+ * @returns {ExpressHandler} The Express handler.
+ */
+module.exports.applyDefaults = ( service ) => ( request, response, next ) => {
+    const body = request.body || {};
+    service.applyDefaults( body.configKeys, { adminID: adminID( request ), note: body.note } ).then( ( result ) => sendData( response, result ) ).catch( ( error ) => forward( next, error ) );
+};

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();
+            } );
         } );
     }