@ti-engine/web-framework 1.21.0 → 1.24.0

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.24.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",
@@ -15,6 +15,10 @@
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
   "license": "GPL-3.0-or-later",
   "exports": {
+    "./config-drift": {
+      "types": "./types/components/config-drift.d.ts",
+      "default": "./components/config-drift.js"
+    },
     "./config-management": {
       "types": "./types/components/config-service.d.ts",
       "default": "./components/config-service.js"
@@ -27,6 +31,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"
@@ -53,6 +61,10 @@
       "types": "./types/components/config-change-notifier.d.ts",
       "default": "./components/config-change-notifier.js"
     },
+    "#config-drift": {
+      "types": "./types/components/config-drift.d.ts",
+      "default": "./components/config-drift.js"
+    },
     "#config-registry": {
       "types": "./types/components/config-registry.d.ts",
       "default": "./components/config-registry.js"
@@ -69,6 +81,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 +154,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/admin-config-handlers.d.ts

@@ -7,5 +7,8 @@ export declare var listChanges: (service: any) => (request: any, response: any,
 export declare var getChange: (service: any) => (request: any, response: any, next: any) => void;
 export declare var restoreChangeSet: (service: any) => (request: any, response: any, next: any) => void;
 export declare var exportBundle: (service: any) => (request: any, response: any, next: any) => void;
+export declare var listDrift: (service: ConfigService) => ExpressHandler;
+export declare var getDrift: (service: ConfigService) => ExpressHandler;
+export declare var applyDefaults: (service: ConfigService) => ExpressHandler;
 import type ConfigService from "#config-service";
 import type { ExpressHandler } from "#web-handlers";

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/config-drift.d.ts

@@ -0,0 +1,27 @@
+export declare var diffDocument: (fileDefault: any, storedValue: any) => {
+    status: string;
+    entries: ConfigDriftEntry[];
+    counts: {
+        added: number;
+        removed: number;
+        changed: number;
+    };
+};
+export type ConfigDriftEntry = {
+    /**
+     * Dot/bracket data path, matching the dialect used for schema validation issues.
+     */
+    path: string;
+    /**
+     * One of "added", "removed", "changed".
+     */
+    kind: string;
+    /**
+     * For a primitive array: how many members the file default adds.
+     */
+    addedMembers?: number;
+    /**
+     * For a primitive array: how many members the file default drops.
+     */
+    removedMembers?: number;
+};