@harperfast/harper 5.0.0-alpha.10 → 5.0.0-beta.1

package/security/tokenAuthentication.ts

@@ -0,0 +1,228 @@
+import jwt, { type Algorithm, type JwtPayload, type Secret, type SignOptions } from 'jsonwebtoken';
+import fs from 'fs-extra';
+import path from 'node:path';
+import Joi from 'joi';
+import { validateBySchema } from '../validation/validationWrapper.js';
+import {
+	CONFIG_PARAMS,
+	JWT_ENUM,
+	LICENSE_KEY_DIR_NAME,
+	SYSTEM_SCHEMA_NAME,
+	SYSTEM_TABLE_NAMES,
+} from '../utility/hdbTerms.ts';
+import { ClientError, hdbErrors } from '../utility/errors/hdbError.js';
+const { HTTP_STATUS_CODES, AUTHENTICATION_ERROR_MSGS } = hdbErrors;
+import logger from '../utility/logging/harper_logger.js';
+import * as password from '../utility/password.ts';
+import { findAndValidateUser, type User } from './user.ts';
+import { update } from '../dataLayer/insert.js';
+import UpdateObject from '../dataLayer/UpdateObject.js';
+import signalling from '../utility/signalling.js';
+import { UserEventMsg } from '../server/threads/itc.js';
+import env from '../utility/environment/environmentManager.js';
+env.initSync();
+
+type StringValue = SignOptions['expiresIn'];
+const OPERATION_TOKEN_TIMEOUT: StringValue = env.get(CONFIG_PARAMS.AUTHENTICATION_OPERATIONTOKENTIMEOUT) || '1d';
+const REFRESH_TOKEN_TIMEOUT: StringValue = env.get(CONFIG_PARAMS.AUTHENTICATION_REFRESHTOKENTIMEOUT) || '30d';
+const RSA_ALGORITHM: Algorithm = 'RS256';
+
+const TOKEN_TYPE = {
+	OPERATION: 'operation',
+	REFRESH: 'refresh',
+};
+
+interface JWTRSAKeys {
+	publicKey: string;
+	privateKey: string;
+	passphrase: string;
+}
+
+interface AuthObject {
+	username?: string;
+	password?: string;
+	role?: string;
+	expires_in?: string | number;
+	bypass_auth?: boolean;
+	hdb_user?: User;
+}
+
+interface TokenObject {
+	refresh_token: string;
+}
+
+interface JWTTokens {
+	operation_token: string;
+	refresh_token?: string;
+}
+
+/**
+ * fetches the rsa keys from cache var or disk
+ * @returns {Promise<JWTRSAKeys>}
+ */
+let rsaKeys: JWTRSAKeys | undefined = undefined;
+export async function getJWTRSAKeys(): Promise<JWTRSAKeys> {
+	if (rsaKeys) return rsaKeys;
+	try {
+		const keysDir: string = path.join(env.getHdbBasePath(), LICENSE_KEY_DIR_NAME);
+		const passphrase: string = await fs.readFile(path.join(keysDir, JWT_ENUM.JWT_PASSPHRASE_NAME), 'utf8');
+		const privateKey: string = await fs.readFile(path.join(keysDir, JWT_ENUM.JWT_PRIVATE_KEY_NAME), 'utf8');
+		const publicKey: string = await fs.readFile(path.join(keysDir, JWT_ENUM.JWT_PUBLIC_KEY_NAME), 'utf8');
+		rsaKeys = { publicKey, privateKey, passphrase };
+		return rsaKeys;
+	} catch (err) {
+		logger.error(err);
+		throw new ClientError(AUTHENTICATION_ERROR_MSGS.NO_ENCRYPTION_KEYS, HTTP_STATUS_CODES.INTERNAL_SERVER_ERROR);
+	}
+}
+
+/**
+ * Creates a new operation token and refresh token.
+ * If there is no username and password, the hdb_user making the request is used in the token.
+ * An optional role can be provided which will be saved in the token payload.
+ * The token expires in the time specified in the expires_in field or the default time.
+ * @param authObj
+ */
+export async function createTokens(authObj: AuthObject): Promise<JWTTokens> {
+	const validation: any = validateBySchema(
+		authObj,
+		Joi.object({
+			username: Joi.string().optional(),
+			password: Joi.string().optional(),
+			role: Joi.string().optional(),
+			expires_in: Joi.alternatives(Joi.string(), Joi.number()).optional(),
+		})
+	);
+	if (validation) throw new ClientError(validation.message);
+
+	let user: any;
+	try {
+		// bypassAuth will be set to true if this is called from a component
+		let validatePassword: boolean = authObj.bypass_auth !== true;
+		if (!authObj.username && !authObj.password) {
+			// if the username and password are not provided, use the hdb_user making the request.
+			authObj.username = authObj.hdb_user?.username;
+			// the password would have been checked by authHandler before getting here
+			validatePassword = false;
+		}
+		user = await findAndValidateUser(authObj.username, authObj.password, validatePassword);
+	} catch (err) {
+		logger.error(err);
+		throw new ClientError(AUTHENTICATION_ERROR_MSGS.INVALID_CREDENTIALS, HTTP_STATUS_CODES.UNAUTHORIZED);
+	}
+	if (!user) throw new ClientError(AUTHENTICATION_ERROR_MSGS.INVALID_CREDENTIALS, HTTP_STATUS_CODES.UNAUTHORIZED);
+
+	let superUser: boolean = false;
+	if (user.role?.permission) {
+		superUser = user.role.permission.super_user === true;
+	}
+
+	const payload: {
+		username: string;
+		super_user: boolean;
+		role?: any;
+	} = { username: authObj.username, super_user: superUser };
+	if (authObj.role) payload.role = authObj.role;
+
+	const keys: JWTRSAKeys = await getJWTRSAKeys();
+	const operationToken = jwt.sign(
+		payload,
+		{ key: keys.privateKey, passphrase: keys.passphrase } satisfies Secret,
+		{
+			expiresIn: (authObj.expires_in ?? OPERATION_TOKEN_TIMEOUT) as StringValue,
+			algorithm: RSA_ALGORITHM,
+			subject: TOKEN_TYPE.OPERATION,
+		} satisfies SignOptions
+	);
+
+	const refreshToken = jwt.sign(
+		payload,
+		{ key: keys.privateKey, passphrase: keys.passphrase } satisfies Secret,
+		{
+			expiresIn: REFRESH_TOKEN_TIMEOUT,
+			algorithm: RSA_ALGORITHM,
+			subject: TOKEN_TYPE.REFRESH,
+		} satisfies SignOptions
+	);
+
+	// update the user refresh token
+	const hashedToken: string | Promise<string> = password.hash(refreshToken, password.HASH_FUNCTION.SHA256);
+	const updateResult: any = await update(
+		new UpdateObject(SYSTEM_SCHEMA_NAME, SYSTEM_TABLE_NAMES.USER_TABLE_NAME, [
+			{ username: authObj.username, refresh_token: hashedToken },
+		])
+	);
+
+	if (updateResult.skipped_hashes.length > 0)
+		throw new ClientError(AUTHENTICATION_ERROR_MSGS.REFRESH_TOKEN_SAVE_FAILED, HTTP_STATUS_CODES.INTERNAL_SERVER_ERROR);
+
+	signalling.signalUserChange(new UserEventMsg(process.pid));
+
+	return {
+		operation_token: operationToken,
+		refresh_token: refreshToken,
+	};
+}
+
+/**
+ * Refreshes the operation token using the refresh token.
+ * @param tokenObj
+ */
+export async function refreshOperationToken(tokenObj: TokenObject): Promise<JWTTokens> {
+	const validation: any = validateBySchema(tokenObj, Joi.object({ refresh_token: Joi.string().required() }).required());
+	if (validation) throw new ClientError(validation.message);
+	const { refresh_token } = tokenObj;
+	await validateRefreshToken(refresh_token);
+
+	const keys: JWTRSAKeys = await getJWTRSAKeys();
+	const decodedJWT = jwt.decode(refresh_token, { json: true });
+	const operationToken = jwt.sign(
+		{ username: decodedJWT.username, super_user: decodedJWT.super_user },
+		{ key: keys.privateKey, passphrase: keys.passphrase } satisfies Secret,
+		{
+			expiresIn: OPERATION_TOKEN_TIMEOUT as StringValue,
+			algorithm: RSA_ALGORITHM,
+			subject: TOKEN_TYPE.OPERATION,
+		} satisfies SignOptions
+	);
+
+	return { operation_token: operationToken };
+}
+
+export async function validateOperationToken(token: string): Promise<any> {
+	return validateToken(token, TOKEN_TYPE.OPERATION);
+}
+
+export async function validateRefreshToken(token: string): Promise<any> {
+	return validateToken(token, TOKEN_TYPE.REFRESH);
+}
+
+async function validateToken(token: string, tokenType: string): Promise<any> {
+	try {
+		const keys: JWTRSAKeys = await getJWTRSAKeys();
+		const tokenVerified = jwt.verify(token, keys.publicKey, {
+			algorithms: [RSA_ALGORITHM],
+			subject: tokenType,
+		}) as JwtPayload;
+
+		// If a role is present, it means the token is not an operation token. The validation of
+		// the token will happen in the respective function/component that uses the token.
+		if (tokenVerified.role) {
+			throw new Error('Invalid token');
+		}
+
+		const user: any = await findAndValidateUser(tokenVerified.username, undefined, false);
+		if (tokenType === TOKEN_TYPE.REFRESH && !password.validate(user.refresh_token, token)) {
+			throw new Error('Invalid token');
+		}
+
+		return user;
+	} catch (err) {
+		logger.warn(err);
+		if (err?.name === 'TokenExpiredError') {
+			throw new ClientError(AUTHENTICATION_ERROR_MSGS.TOKEN_EXPIRED, HTTP_STATUS_CODES.FORBIDDEN);
+		}
+
+		throw new ClientError(AUTHENTICATION_ERROR_MSGS.INVALID_TOKEN, HTTP_STATUS_CODES.UNAUTHORIZED);
+	}
+}

package/security/user.ts

@@ -0,0 +1,449 @@
+'use strict';
+
+const USERNAME_REQUIRED = 'username is required';
+const ALTERUSER_NOTHING_TO_UPDATE = 'nothing to update, must supply active, role or password to update';
+const EMPTY_PASSWORD = 'password cannot be an empty string';
+const EMPTY_ROLE = 'If role is specified, it cannot be empty.';
+const ACTIVE_BOOLEAN = 'active must be true or false';
+
+export {
+	addUser,
+	alterUser,
+	dropUser,
+	getSuperUser,
+	userInfo,
+	listUsers,
+	listUsersExternal,
+	setUsersWithRolesCache,
+	findAndValidateUser,
+	getUsersWithRolesCache,
+	USERNAME_REQUIRED,
+	ALTERUSER_NOTHING_TO_UPDATE,
+	EMPTY_PASSWORD,
+	EMPTY_ROLE,
+	ACTIVE_BOOLEAN,
+};
+
+export interface User {
+	active?: boolean;
+	username: string;
+	role?: UserRole;
+	__updatedtime__?: number;
+	__createdtime__?: number;
+	[other: string]: unknown;
+}
+
+export interface UserRole {
+	permission: UserRoleNamedPermissions & UserRoleDatabasePermissions;
+	role: string;
+	id: string;
+	__updatedtime__: number;
+	__createdtime__: number;
+}
+
+export interface UserRoleNamedPermissions extends Partial<CRUDPermissions> {
+	super_user?: boolean;
+	cluster_user?: boolean;
+	structure_user?: boolean | string[];
+	operations?: string[];
+	/** Pre-expanded Set built from operations at cache-load time. Not persisted. */
+	_expandedOperations?: Set<string>;
+}
+
+export interface UserRoleDatabasePermissions {
+	[databaseName: string]: UserRoleSchemaRecord;
+}
+
+export interface UserRoleSchemaRecord extends Partial<CRUDPermissions> {
+	tables: Record<string, UserRolePermissionTable | UserLegacyRolePermissionTable>;
+}
+
+export interface UserRolePermissionTable extends CRUDPermissions {
+	attribute_permissions: UserRoleAttributePermissionTable[];
+}
+
+export interface UserRoleAttributePermissionTable extends Omit<CRUDPermissions, 'delete'> {
+	attribute_name: string;
+}
+
+export interface UserLegacyRolePermissionTable extends CRUDPermissions {
+	attribute_restrictions: UserLegacyRoleAttributePermissionTable[];
+}
+
+export interface UserLegacyRoleAttributePermissionTable extends CRUDPermissions {
+	attribute_name: string;
+}
+
+export interface CRUDPermissions {
+	read: boolean;
+	insert: boolean;
+	update: boolean;
+	delete: boolean;
+}
+
+//requires must be declared after module.exports to avoid cyclical dependency
+const insert = require('../dataLayer/insert.js');
+const delete_ = require('../dataLayer/delete.js');
+const validation = require('../validation/user_validation.js');
+const search = require('../dataLayer/search.js');
+const signalling = require('../utility/signalling.js');
+const hdbUtility = require('../utility/common_utils.js');
+const validate = require('validate.js');
+const logger = require('../utility/logging/harper_logger.js');
+const { promisify } = require('util');
+const env = require('../utility/environment/environmentManager.js');
+const systemSchema = require('../json/systemSchema.json');
+const { hdbErrors, ClientError } = require('../utility/errors/hdbError.js');
+const { HTTP_STATUS_CODES, AUTHENTICATION_ERROR_MSGS, HDB_ERROR_MSGS } = hdbErrors;
+const { UserEventMsg } = require('../server/threads/itc.js');
+const _ = require('lodash');
+const harperLogger = require('../utility/logging/harper_logger.js');
+
+// Need to use `.js` even for other TS files since TS compiler won't replace requires.
+// Whenever we can fix the cyclical dependency issue in this file (and switch to imports) we can use the correct file extensions.
+const password = require('../utility/password.js');
+const { server } = require('../server/Server.js');
+const terms = require('../utility/hdbTerms.js');
+const { expandOperationsPerms } = require('../utility/operationPermissions.js');
+
+server.getUser = (username: string, password?: string | null): Promise<User> => {
+	return findAndValidateUser(username, password, password != null);
+};
+
+server.authenticateUser = (username: string, password?: string | null): Promise<User> => {
+	return findAndValidateUser(username, password);
+};
+
+const USER_ATTRIBUTE_ALLOWLIST = {
+	username: true,
+	active: true,
+	role: true,
+	password: true,
+};
+const passwordHashCache = new Map();
+const promiseDelete = promisify(delete_.delete);
+const configuredHashFunction =
+	env.get(terms.CONFIG_PARAMS.AUTHENTICATION_HASHFUNCTION) ?? password.HASH_FUNCTION.SHA256;
+let usersWithRolesMap;
+
+async function addUser(user: User | any): Promise<string> {
+	let cleanUser = validate.cleanAttributes(user, USER_ATTRIBUTE_ALLOWLIST);
+	let validationResp = validation.addUserValidation(cleanUser);
+	if (validationResp) throw new ClientError(validationResp.message);
+
+	let searchRole = await search.searchByValue({
+		schema: 'system',
+		table: 'hdb_role',
+		attribute: 'role',
+		value: cleanUser.role,
+		get_attributes: ['id', 'permission', 'role'],
+	});
+
+	if (!searchRole || searchRole.length < 1) {
+		throw new ClientError(HDB_ERROR_MSGS.ROLE_NAME_NOT_FOUND(cleanUser.role), HTTP_STATUS_CODES.NOT_FOUND);
+	}
+
+	if (searchRole.length > 1) {
+		throw new ClientError(HDB_ERROR_MSGS.DUP_ROLES_FOUND(cleanUser.role), HTTP_STATUS_CODES.CONFLICT);
+	}
+
+	cleanUser.password = await password.hash(cleanUser.password, configuredHashFunction);
+	cleanUser.hash_function = configuredHashFunction;
+	cleanUser.role = searchRole[0].id;
+
+	const insertResponse = await insert.insert({
+		operation: 'insert',
+		schema: 'system',
+		table: 'hdb_user',
+		records: [cleanUser],
+	});
+	logger.debug(insertResponse);
+
+	await setUsersWithRolesCache();
+
+	if (insertResponse.skipped_hashes.length === 1) {
+		throw new ClientError(HDB_ERROR_MSGS.USER_ALREADY_EXISTS(cleanUser.username), HTTP_STATUS_CODES.CONFLICT);
+	}
+
+	await signalling.signalUserChange(new UserEventMsg(process.pid));
+	return `${cleanUser.username} successfully added`;
+}
+
+async function alterUser(jsonMessage) {
+	let cleanUser = validate.cleanAttributes(jsonMessage, USER_ATTRIBUTE_ALLOWLIST);
+
+	if (hdbUtility.isEmptyOrZeroLength(cleanUser.username)) {
+		throw new Error(USERNAME_REQUIRED);
+	}
+
+	if (
+		hdbUtility.isEmptyOrZeroLength(cleanUser.password) &&
+		hdbUtility.isEmptyOrZeroLength(cleanUser.role) &&
+		hdbUtility.isEmptyOrZeroLength(cleanUser.active)
+	) {
+		throw new Error(ALTERUSER_NOTHING_TO_UPDATE);
+	}
+
+	if (!hdbUtility.isEmpty(cleanUser.password) && hdbUtility.isEmptyOrZeroLength(cleanUser.password.trim())) {
+		throw new Error(EMPTY_PASSWORD);
+	}
+
+	if (!hdbUtility.isEmpty(cleanUser.active) && !hdbUtility.isBoolean(cleanUser.active)) {
+		throw new Error(ACTIVE_BOOLEAN);
+	}
+
+	if (!hdbUtility.isEmpty(cleanUser.password) && !hdbUtility.isEmptyOrZeroLength(cleanUser.password.trim())) {
+		cleanUser.password = await password.hash(cleanUser.password, configuredHashFunction);
+		cleanUser.hash_function = configuredHashFunction;
+	}
+
+	// the not operator will consider an empty string as undefined, so we need to check for an empty string explicitly
+	if (cleanUser.role === '') {
+		throw new Error(EMPTY_ROLE);
+	}
+	// Invalid roles will be found in the role search
+	if (cleanUser.role) {
+		const roleData = await search.searchByValue({
+			schema: 'system',
+			table: 'hdb_role',
+			attribute: 'role',
+			value: cleanUser.role,
+			get_attributes: ['*'],
+		});
+
+		if (!roleData || roleData.length === 0)
+			throw new ClientError(HDB_ERROR_MSGS.ALTER_USER_ROLE_NOT_FOUND(cleanUser.role), HTTP_STATUS_CODES.NOT_FOUND);
+
+		if (roleData.length > 1)
+			throw new ClientError(HDB_ERROR_MSGS.DUP_ROLES_FOUND(cleanUser.role), HTTP_STATUS_CODES.CONFLICT);
+
+		cleanUser.role = roleData[0].id;
+	}
+
+	const updateResponse = await insert.update({
+		operation: 'update',
+		schema: 'system',
+		table: 'hdb_user',
+		records: [cleanUser],
+	});
+
+	await setUsersWithRolesCache();
+	await signalling.signalUserChange(new UserEventMsg(process.pid));
+
+	return updateResponse;
+}
+
+async function dropUser(user: User | any): Promise<string> {
+	const validationResp = validation.dropUserValidation(user);
+	if (validationResp) throw new ClientError(validationResp.message);
+
+	if (usersWithRolesMap.get(user.username) === undefined)
+		throw new ClientError(HDB_ERROR_MSGS.USER_NOT_EXIST(user.username), HTTP_STATUS_CODES.NOT_FOUND);
+
+	const deleteResponse = await promiseDelete({
+		table: 'hdb_user',
+		schema: 'system',
+		hash_values: [user.username],
+	});
+
+	logger.debug(deleteResponse);
+	await setUsersWithRolesCache();
+	await signalling.signalUserChange(new UserEventMsg(process.pid));
+	return `${user.username} successfully deleted`;
+}
+
+async function userInfo(body): Promise<string | User> {
+	if (!body || !body.hdb_user) {
+		return 'There was no user info in the body';
+	}
+
+	let user = _.cloneDeep(body.hdb_user);
+	let roleData = await search.searchByHash({
+		schema: 'system',
+		table: 'hdb_role',
+		hash_values: [user.role.id],
+		get_attributes: ['*'],
+	});
+
+	user.role = roleData[0];
+	delete user.password;
+	delete user.refresh_token;
+	delete user.hash;
+	delete user.hash_function;
+
+	return user;
+}
+
+/**
+ * This function should be called by chooseOperation as it scrubs sensitive information before returning
+ * the results of list users.
+ */
+async function listUsersExternal(): Promise<User[]> {
+	const userData = await listUsers();
+	userData.forEach((user) => {
+		delete user.password;
+		delete user.hash;
+		delete user.refresh_token;
+		delete user.hash_function;
+	});
+
+	return [...userData.values()];
+}
+
+/**
+ * Queries system table for user records, adds role-based perms, scrubs list based on licensed role allowance and returns
+ * data in a Map with the username as the key for the entry
+ */
+async function listUsers(): Promise<Map<string, User>> {
+	const roles = await search.searchByValue({
+		schema: 'system',
+		table: 'hdb_role',
+		value: '*',
+		attribute: 'role',
+		get_attributes: ['*'],
+	});
+
+	const roleMapObj = {};
+	for (let role of roles) {
+		roleMapObj[role.id] = _.cloneDeep(role);
+	}
+	if (Object.keys(roleMapObj).length === 0) return null;
+
+	const users = await search.searchByValue({
+		schema: 'system',
+		table: 'hdb_user',
+		value: '*',
+		attribute: 'username',
+		get_attributes: ['*'],
+	});
+
+	const userMap: Map<string, User> = new Map();
+	for (let user of users) {
+		user = _.cloneDeep(user);
+		user.role = roleMapObj[user.role];
+		appendSystemTablesToRole(user.role);
+		cacheExpandedOperationsPerms(user.role);
+		userMap.set(user.username, user);
+	}
+
+	return userMap;
+}
+
+/**
+ * adds system table permissions to a role.  This is used to protect system tables by leveraging operationAuthorization.
+ * @param userRole - Role of the user found during auth.
+ */
+function appendSystemTablesToRole(userRole: UserRole) {
+	if (!userRole) {
+		logger.error(`invalid user role found.`);
+		return;
+	}
+	if (!userRole.permission.system) {
+		userRole.permission.system = {
+			tables: {},
+		};
+	}
+	if (!userRole.permission.system.tables) {
+		userRole.permission.system.tables = {};
+	}
+	for (let table of Object.keys(systemSchema)) {
+		let newProp = {
+			read: !!userRole.permission.super_user,
+			insert: false,
+			update: false,
+			delete: false,
+			attribute_permissions: [],
+		};
+
+		userRole.permission.system.tables[table] = newProp;
+	}
+}
+
+/**
+ * Pre-expands operations into a Set at cache-load time so verifyPerms can do an O(1) lookup
+ * instead of allocating and expanding on every request.
+ * @param userRole - Role of the user found during auth.
+ */
+function cacheExpandedOperationsPerms(userRole: UserRole) {
+	if (!userRole?.permission?.operations) return;
+	userRole.permission._expandedOperations = expandOperationsPerms(userRole.permission.operations);
+}
+
+async function setUsersWithRolesCache(cache = undefined) {
+	if (cache) usersWithRolesMap = cache;
+	else usersWithRolesMap = await listUsers();
+}
+
+async function getUsersWithRolesCache() {
+	if (!usersWithRolesMap) await setUsersWithRolesCache();
+	return usersWithRolesMap;
+}
+
+/**
+ * iterates global.hdb_users to find and validate the username & optionally the password as well as if they are active.
+ * @param {string} username
+ * @param {string} pw
+ * @param {boolean} validatePassword
+ */
+async function findAndValidateUser(username: string, pw?: string | null, validatePassword = true): Promise<User> {
+	if (!usersWithRolesMap) {
+		await setUsersWithRolesCache();
+	}
+
+	const userTmp = usersWithRolesMap.get(username);
+	if (!userTmp) {
+		if (!validatePassword) return { username };
+		throw new ClientError(AUTHENTICATION_ERROR_MSGS.GENERIC_AUTH_FAIL, HTTP_STATUS_CODES.UNAUTHORIZED);
+	}
+
+	if (userTmp && !userTmp.active)
+		throw new ClientError(AUTHENTICATION_ERROR_MSGS.USER_INACTIVE, HTTP_STATUS_CODES.UNAUTHORIZED);
+
+	const user: User = {
+		active: userTmp.active,
+		username: userTmp.username,
+	};
+	if (userTmp.refresh_token) user.refresh_token = userTmp.refresh_token;
+	// Shallow-clone the role and its permission so that verifyPerms can replace
+	// requestJson.hdb_user.role.permission with translated perms without mutating the cache.
+	// The _expandedOperations Set and operations array are shared by reference (read-only).
+	if (userTmp.role) user.role = { ...userTmp.role, permission: { ...userTmp.role.permission } };
+
+	if (validatePassword === true) {
+		// if matches the cached hash immediately return (the fast path)
+		if (passwordHashCache.get(pw) === userTmp.password) return user;
+		// if validates, cache the password
+		else {
+			let validated = password.validate(userTmp.password, pw, userTmp.hash_function || password.HASH_FUNCTION.MD5); // if no hashFunction default to legacy MD5
+			// argon2id hash validation is async so await it if it is a promise
+			if (validated?.then) validated = await validated;
+			if (validated === true) passwordHashCache.set(pw, userTmp.password);
+			else throw new ClientError(AUTHENTICATION_ERROR_MSGS.GENERIC_AUTH_FAIL, HTTP_STATUS_CODES.UNAUTHORIZED);
+		}
+	}
+	return user;
+}
+
+async function getSuperUser(): Promise<User | undefined> {
+	if (!usersWithRolesMap) {
+		await setUsersWithRolesCache();
+	}
+	for (let [, user] of usersWithRolesMap) {
+		if (user.role.role === 'super_user') return user;
+	}
+}
+
+let invalidateCallbacks = [];
+server.invalidateUser = function (user: User | any) {
+	for (let callback of invalidateCallbacks) {
+		try {
+			callback(user);
+		} catch (error) {
+			harperLogger.error('Error invalidating user', error);
+		}
+	}
+};
+
+server.onInvalidatedUser = function (callback) {
+	invalidateCallbacks.push(callback);
+};