@spinajs/rbac 2.0.520 → 2.0.522

package/lib/cjs/actions.js

@@ -3,20 +3,31 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.E_CODES = void 0;
+exports.getUser = getUser;
+exports.getUserUnsafe = getUserUnsafe;
+exports.getSystemUser = getSystemUser;
+exports.getUsersByRole = getUsersByRole;
+exports.setUserMeta = setUserMeta;
+exports.getUserMeta = getUserMeta;
+exports.sendUserEmail = sendUserEmail;
+exports.updateUser = updateUser;
+exports.revokeUserSessions = revokeUserSessions;
 exports._get_system_user = _get_system_user;
 exports._get_users_by_role = _get_users_by_role;
 exports._get_user = _get_user;
+exports._user = _user;
+exports._user_unsafe = _user_unsafe;
 exports._set_user_meta = _set_user_meta;
 exports._get_user_meta = _get_user_meta;
 exports._user_email = _user_email;
 exports._user_ev = _user_ev;
 exports._user_update = _user_update;
-exports._user = _user;
-exports._user_unsafe = _user_unsafe;
-exports.revokeUserSessions = revokeUserSessions;
 exports.activate = activate;
 exports.deactivate = deactivate;
+exports.roleList = roleList;
+exports.assertRolesExist = assertRolesExist;
+exports.assertNoProtectedMetadata = assertNoProtectedMetadata;
+exports.assertUserUnique = assertUserUnique;
 exports.create = create;
 exports.deleteUser = deleteUser;
 exports.grant = grant;
@@ -25,10 +36,16 @@ exports.ban = ban;
 exports.unban = unban;
 exports.passwordChangeRequest = passwordChangeRequest;
 exports.confirmPasswordReset = confirmPasswordReset;
+exports.changeUserPassword = changeUserPassword;
 exports.changePassword = changePassword;
 exports.expirePassword = expirePassword;
+exports.notifyPasswordWillExpire = notifyPasswordWillExpire;
+exports.verifyPassword = verifyPassword;
 exports.passwordMatch = passwordMatch;
 exports.login = login;
+exports.assertNotLocked = assertNotLocked;
+exports.clearLoginThrottle = clearLoginThrottle;
+exports.registerFailedLogin = registerFailedLogin;
 const orm_1 = require("@spinajs/orm");
 const util_1 = require("@spinajs/util");
 const lodash_1 = __importDefault(require("lodash"));
@@ -37,193 +54,149 @@ const queue_1 = require("@spinajs/queue");
 const User_js_1 = require("./models/User.js");
 const configuration_1 = require("@spinajs/configuration");
 const index_js_1 = require("./events/index.js");
+const di_1 = require("@spinajs/di");
+const log_1 = require("@spinajs/log");
 const interfaces_js_1 = require("./interfaces.js");
 const luxon_1 = require("luxon");
 const exceptions_1 = require("@spinajs/exceptions");
+const exceptions_js_1 = require("./exceptions.js");
 const crypto_1 = require("crypto");
 const uuid_1 = require("uuid");
 const UserLoginFailed_js_1 = require("./events/UserLoginFailed.js");
 const UserMetadataChange_js_1 = require("./events/UserMetadataChange.js");
 const UserPasswordExpired_js_1 = require("./events/UserPasswordExpired.js");
 const model_token_js_1 = require("./model-token.js");
-var E_CODES;
-(function (E_CODES) {
-    E_CODES[E_CODES["E_TOKEN_EXPIRED"] = 0] = "E_TOKEN_EXPIRED";
-    E_CODES[E_CODES["E_TOKEN_INVALID"] = 1] = "E_TOKEN_INVALID";
-    E_CODES[E_CODES["E_PASSWORD_DOES_NOT_MEET_REQUIREMENTS"] = 2] = "E_PASSWORD_DOES_NOT_MEET_REQUIREMENTS";
-    E_CODES[E_CODES["E_USER_NOT_FOUND"] = 3] = "E_USER_NOT_FOUND";
-    E_CODES[E_CODES["E_USER_ALREADY_EXISTS"] = 4] = "E_USER_ALREADY_EXISTS";
-    E_CODES[E_CODES["E_USER_NOT_ACTIVE"] = 5] = "E_USER_NOT_ACTIVE";
-    E_CODES[E_CODES["E_USER_BANNED"] = 6] = "E_USER_BANNED";
-    E_CODES[E_CODES["E_METADATA_NOT_FOUND"] = 7] = "E_METADATA_NOT_FOUND";
-    E_CODES[E_CODES["E_METADATA_NOT_POPULATED"] = 8] = "E_METADATA_NOT_POPULATED";
-    E_CODES[E_CODES["E_EMAIL_NOT_CONFIGURED"] = 9] = "E_EMAIL_NOT_CONFIGURED";
-    E_CODES[E_CODES["E_NO_EMAIL_TEMPLATE"] = 10] = "E_NO_EMAIL_TEMPLATE";
-    E_CODES[E_CODES["E_NOT_LOGGED"] = 11] = "E_NOT_LOGGED";
-})(E_CODES || (exports.E_CODES = E_CODES = {}));
 /**
  * ===============================================
- *  HELPER FUNCTIONS
+ *  FUNDAMENTALS ( imperative helpers )
  * ===============================================
  */
 /**
+ * Resolves a user by identifier with metadata populated.
+ * If a {@link User} instance is passed it is returned as-is; otherwise the user is
+ * looked up by id, uuid, email, or login and its metadata relation is populated.
  *
- * Gets system user account
- *
- * @returns system user
+ * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
  */
-function _get_system_user() {
-    return (0, util_1._chain)((0, util_1._zip)((0, configuration_1._cfg)('rbac.systemRole'), (0, configuration_1._cfg)('rbac.roleColumn')), ([systemRole, roleColumn]) => {
-        const s = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(systemRole, 'rbac.systemRole');
-        const c = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(roleColumn, 'rbac.roleColumn');
-        return [s, c];
-    }, ([systemRole, roleColumn]) => User_js_1.User.query().where(roleColumn, systemRole).firstOrFail());
+async function getUser(identifier) {
+    const id = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_nil)())(identifier, 'identifier');
+    if (id instanceof User_js_1.User) {
+        return id;
+    }
+    return (0, model_token_js_1.userModel)().query().whereAnything(id).populate('Metadata').firstOrFail();
 }
 /**
+ * Unsafe user retrieval. It does not check for rbac permission, so this
+ * function can read ANY user in system. USE IT CAREFULLY
  *
- * Gets users by role helper func.
- *
- * @param role user role
- * @returns
+ * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
  */
-function _get_users_by_role(role) {
-    return () => (0, model_token_js_1.userModel)().select().withRole(role);
+async function getUserUnsafe(identifier) {
+    const id = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_nil)())(identifier, 'identifier');
+    if (id instanceof User_js_1.UserBase) {
+        return id;
+    }
+    return User_js_1.UserBase.query().whereAnything(id).populate('Metadata').firstOrFail();
 }
 /**
+ * Gets system user account
  *
- * Gets rbac user model
+ * @returns system user
+ */
+async function getSystemUser() {
+    const systemRole = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())((0, configuration_1.cfg)('rbac.systemRole'), 'rbac.systemRole');
+    const roleColumn = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())((0, configuration_1.cfg)('rbac.roleColumn'), 'rbac.roleColumn');
+    // base User on purpose: system account must resolve inside scoped request contexts
+    return User_js_1.User.query().where(roleColumn, systemRole).firstOrFail();
+}
+/**
+ * Gets users by role.
  *
- * @param user
- * @returns
+ * @param role user roles
  */
-function _get_user(user) {
-    if (lodash_1.default.isString(user)) {
-        return async () => (0, model_token_js_1.userModel)().where('Uuid', user).firstOrFail();
-    }
-    if (lodash_1.default.isNumber(user)) {
-        return async () => (0, model_token_js_1.userModel)().getOrFail(user);
-    }
-    return () => Promise.resolve(user);
+async function getUsersByRole(role) {
+    return (0, model_token_js_1.userModel)().select().withRole(role);
 }
 /**
  * Sets metadata key-value pairs on a user.
  * Accepts either an array of `{ key, value }` objects or a single metadata key string with a separate value.
  * Emits a {@link UserMetadataChange} event after the metadata is persisted.
  *
+ * @param u - user to modify
  * @param meta - metadata key (string) or array of `{ key, value }` entries to set
  * @param value - value to assign when `meta` is a single key string (default: `null`)
- * @returns a function that receives a {@link User} and returns the updated user
  */
-function _set_user_meta(meta, value = null) {
-    return async (u) => {
-        const mArgs = (0, util_1._check_arg)((0, util_1._non_nil)(new exceptions_1.ErrorCode(E_CODES.E_METADATA_NOT_POPULATED, 'User metadata not loaded', { user: u })), (0, util_1._to_array)())(meta, 'Metadata');
-        mArgs.forEach((m) => {
-            lodash_1.default.isString(m) ? (u.Metadata[m] = value) : (u.Metadata[m.key] = m.value);
-        });
-        await (0, util_1._chain)(u, (0, util_1._tap)(() => u.Metadata.update()), _user_ev(UserMetadataChange_js_1.UserMetadataChange, () => {
-            return mArgs.map((m) => {
-                return lodash_1.default.isString(m) ? { key: m, value } : m;
-            });
-        }));
-        return u;
-    };
+async function setUserMeta(u, meta, value = null) {
+    const mArgs = (0, util_1._check_arg)((0, util_1._non_nil)(new exceptions_js_1.MetadataNotPopulated('User metadata not loaded', { user: u.Uuid })), (0, util_1._to_array)())(meta, 'Metadata');
+    mArgs.forEach((m) => {
+        lodash_1.default.isString(m) ? (u.Metadata[m] = value) : (u.Metadata[m.key] = m.value);
+    });
+    await u.Metadata.update();
+    // the event carries the resolved entries, not the raw input - a single
+    // string key is normalised to a { key, value } pair
+    await (0, queue_1.ev)(new UserMetadataChange_js_1.UserMetadataChange(u, mArgs.map((m) => (lodash_1.default.isString(m) ? { key: m, value } : m))));
+    return u;
 }
 /**
  * Retrieves a single metadata value from a user by key.
  * Throws if the user's metadata has not been populated or the requested key does not exist.
  *
+ * @param u - user to read from
  * @param key - metadata key to retrieve
- * @returns a function that receives a {@link User} and returns the metadata value
  */
-function _get_user_meta(key) {
-    return async (u) => {
-        (0, util_1._check_arg)((0, util_1._non_nil)(new exceptions_1.ErrorCode(E_CODES.E_METADATA_NOT_POPULATED, 'User metadata not loaded', { user: u, key })))(u.Metadata, 'Metadata');
-        (0, util_1._check_arg)((0, util_1._non_nil)(new exceptions_1.ErrorCode(E_CODES.E_METADATA_NOT_FOUND, 'Metadata not found in user data', { user: u, key })))(u.Metadata[key], `Metadata.${key}`);
-        return u.Metadata[key];
-    };
+async function getUserMeta(u, key) {
+    (0, util_1._check_arg)((0, util_1._non_nil)(new exceptions_js_1.MetadataNotPopulated('User metadata not loaded', { user: u.Uuid, key })))(u.Metadata, 'Metadata');
+    (0, util_1._check_arg)((0, util_1._non_nil)(new exceptions_js_1.MetadataNotFound('Metadata not found in user data', { user: u.Uuid, key })))(u.Metadata[key], `Metadata.${key}`);
+    return u.Metadata[key];
 }
 /**
- * Helper function for sending user notification emails
- * Templates are defined in rbac configuration
+ * Sends a user notification email. Templates are defined in rbac configuration.
  *
- * @param cfgTemplate
- * @returns
- */
-function _user_email(cfgTemplate) {
-    // NOTE: tap semantics - the user flows through, the email send result is
-    // deliberately discarded. Actions end with this step and must resolve with
-    // the User, not with an EmailSend job.
-    return async (u) => {
-        await (0, util_1._chain)((0, util_1._use)((0, configuration_1._cfg)('rbac.email.connection', 'default'), 'connection'), (0, util_1._use)((0, configuration_1._cfg)(`rbac.email.${cfgTemplate}`), 'template'), ({ connection, template }) => {
-            (0, util_1._check_arg)((0, util_1._non_nil)(new exceptions_1.ErrorCode(E_CODES.E_NO_EMAIL_TEMPLATE, `Email template ${cfgTemplate} not configured. Check rbac.email in config`)))(template, 'template');
-            (0, util_1._check_arg)((0, util_1._is_string)((0, util_1._non_empty)(), (0, util_1._max_length)(128)))(template.template, 'email.template');
-            (0, util_1._check_arg)((0, util_1._is_string)((0, util_1._non_empty)(), (0, util_1._max_length)(128)))(template.subject, 'email.subject');
-            return (template.enabled &&
-                (0, email_1._email_deferred)({
-                    to: [u.Email],
-                    connection,
-                    model: u.toJSON(),
-                    tag: `rbac-user-${cfgTemplate}`,
-                    template: template.template,
-                    subject: template.subject,
-                }));
-        });
-        return u;
-    };
-}
-/**
- * Emits a user-related event through the queue service.
+ * The email send result is deliberately discarded - actions end with this step
+ * and must resolve with the User, not with an EmailSend job.
  *
- * @param event - constructor of the {@link UserEvent} subclass to emit
- * @param args - additional arguments forwarded to the event constructor
- * @returns a function that receives a {@link User}, emits the event, and returns the user
+ * @param u - recipient
+ * @param cfgTemplate - which `rbac.email.*` entry describes the message
+ * @param model - extra template variables merged over the user's own fields.
+ *   Given as a FUNCTION of the user so a caller can compute them from the row it
+ *   has just written ( the password-reset token is the case that needs it ).
+ *   Nothing here is persisted and nothing is logged: whatever it carries goes
+ *   straight into the rendered message.
  */
-function _user_ev(event, ...args) {
-    return async (u) => {
-        await (0, queue_1._ev)(new event(u, ...args))();
-        return u;
-    };
+async function sendUserEmail(u, cfgTemplate, model) {
+    const extra = model ? await model(u) : undefined;
+    const connection = (0, configuration_1.cfg)('rbac.email.connection', 'default');
+    let template;
+    try {
+        template = (0, configuration_1.cfg)(`rbac.email.${cfgTemplate}`);
+    }
+    catch (err) {
+        throw new exceptions_js_1.EmailTemplateNotConfigured(`Email template ${cfgTemplate} not configured. Check rbac.email in config`, undefined, err);
+    }
+    (0, util_1._check_arg)((0, util_1._is_string)((0, util_1._non_empty)(), (0, util_1._max_length)(128)))(template.template, 'email.template');
+    (0, util_1._check_arg)((0, util_1._is_string)((0, util_1._non_empty)(), (0, util_1._max_length)(128)))(template.subject, 'email.subject');
+    if (template.enabled) {
+        await (0, email_1.emailDeferred)({
+            to: [u.Email],
+            connection,
+            model: { ...u.toJSON(), ...(extra ?? {}) },
+            tag: `rbac-user-${cfgTemplate}`,
+            template: template.template,
+            subject: template.subject,
+        });
+    }
+    return u;
 }
 /**
  * Persists partial changes to a user record and emits a {@link UserChanged} event.
  *
+ * @param u - user to update
  * @param data - optional partial user fields to merge into the existing record
- * @returns a function that receives a {@link User}, applies the update, and returns the user
  */
-function _user_update(data) {
-    return async (u) => {
-        await (0, util_1._chain)(u, (0, orm_1._update)(data), _user_ev(index_js_1.UserChanged));
-        return u;
-    };
-}
-/**
- * Resolves a user by identifier with metadata populated.
- * If a {@link User} instance is passed it is returned as-is; otherwise the user is
- * looked up by id, uuid, email, or login and its metadata relation is populated.
- *
- * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
- * @returns a thunk that resolves to the {@link User}
- */
-function _user(identifier) {
-    const id = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_nil)())(identifier, 'identifier');
-    if (id instanceof User_js_1.User) {
-        return () => Promise.resolve(id);
-    }
-    return () => (0, model_token_js_1.userModel)().query().whereAnything(id).populate('Metadata').firstOrFail();
-}
-/**
- * Unsafe user retrieval. It does not chack for rbac permission, to this
- * function can read ANY user in system. USE IT CAREFULLY
- *
- * @param identifier
- * @returns
- */
-function _user_unsafe(identifier) {
-    const id = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_nil)())(identifier, 'identifier');
-    if (id instanceof User_js_1.UserBase) {
-        return () => Promise.resolve(id);
-    }
-    return () => User_js_1.UserBase.query().whereAnything(id).populate('Metadata').firstOrFail();
+async function updateUser(u, data) {
+    await (0, orm_1.updateModel)(u, data);
+    await (0, queue_1.ev)(new index_js_1.UserChanged(u));
+    return u;
 }
 /**
  * Destroys every session belonging to a user, on every device.
@@ -245,18 +218,83 @@ async function revokeUserSessions(user) {
     if (!userId) {
         return;
     }
-    const provider = await (0, configuration_1._service)('rbac.session', interfaces_js_1.SessionProvider)();
+    const provider = await (0, configuration_1.service)('rbac.session', interfaces_js_1.SessionProvider);
     await provider.deleteByUser(userId);
 }
 /**
- * Chain step form of {@link revokeUserSessions} — revokes and forwards the user.
+ * ===============================================
+ *  FP WRAPPERS ( kept for compatibility and for use in chains )
+ * ===============================================
+ */
+/**
+ * Thunk form of {@link getSystemUser}.
+ */
+function _get_system_user() {
+    return getSystemUser();
+}
+/**
+ * Thunk form of {@link getUsersByRole}.
  */
-function _revoke_sessions() {
+function _get_users_by_role(role) {
+    return () => getUsersByRole(role);
+}
+/**
+ * Gets rbac user model by uuid or id, WITHOUT metadata populated.
+ */
+function _get_user(user) {
+    if (lodash_1.default.isString(user)) {
+        return async () => (0, model_token_js_1.userModel)().where('Uuid', user).firstOrFail();
+    }
+    if (lodash_1.default.isNumber(user)) {
+        return async () => (0, model_token_js_1.userModel)().getOrFail(user);
+    }
+    return () => Promise.resolve(user);
+}
+/**
+ * Thunk form of {@link getUser}.
+ */
+function _user(identifier) {
+    return () => getUser(identifier);
+}
+/**
+ * Thunk form of {@link getUserUnsafe}.
+ */
+function _user_unsafe(identifier) {
+    return () => getUserUnsafe(identifier);
+}
+/**
+ * Chain step form of {@link setUserMeta}.
+ */
+function _set_user_meta(meta, value = null) {
+    return (u) => setUserMeta(u, meta, value);
+}
+/**
+ * Chain step form of {@link getUserMeta}.
+ */
+function _get_user_meta(key) {
+    return (u) => getUserMeta(u, key);
+}
+/**
+ * Chain step form of {@link sendUserEmail}.
+ */
+function _user_email(cfgTemplate, model) {
+    return (u) => sendUserEmail(u, cfgTemplate, model);
+}
+/**
+ * Chain step: emits a user-related event and forwards the user.
+ */
+function _user_ev(event, ...args) {
     return async (u) => {
-        await revokeUserSessions(u);
+        await (0, queue_1.ev)(new event(u, ...args));
         return u;
     };
 }
+/**
+ * Chain step form of {@link updateUser}.
+ */
+function _user_update(data) {
+    return (u) => updateUser(u, data);
+}
 /**
  * ===============================================
  * USER ACTIONS
@@ -269,7 +307,11 @@ function _revoke_sessions() {
  * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
  */
 async function activate(identifier) {
-    return (0, util_1._chain)(_user(identifier), _user_update({ IsActive: true }), _user_ev(index_js_1.UserActivated), _user_email('activated'));
+    const u = await getUser(identifier);
+    await updateUser(u, { IsActive: true });
+    await (0, queue_1.ev)(new index_js_1.UserActivated(u));
+    await sendUserEmail(u, 'activated');
+    return u;
 }
 /**
  * Deactivates a user account.
@@ -278,67 +320,269 @@ async function activate(identifier) {
  * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
  */
 async function deactivate(identifier) {
+    const u = await getUser(identifier);
+    await updateUser(u, { IsActive: false });
     // Sessions go with the account: a deactivated user must stop acting NOW, not
     // whenever their session happens to expire.
-    return (0, util_1._chain)(_user(identifier), _user_update({ IsActive: false }), _revoke_sessions(), _user_ev(index_js_1.UserDeactivated), _user_email('deactivated'));
+    await revokeUserSessions(u);
+    await (0, queue_1.ev)(new index_js_1.UserDeactivated(u));
+    await sendUserEmail(u, 'deactivated');
+    return u;
 }
 /**
  * Reads a create-middleware list from configuration.
  * An unset or empty `beforeCreate` / `afterCreate` list is a valid
- * "no middleware" result ( `_cfg` accepts empty arrays ).
+ * "no middleware" result ( `cfg` accepts empty arrays ).
  */
-function _create_middleware(path) {
-    const mw = (0, configuration_1._cfg)(path, [])();
+function middlewareList(path) {
+    const mw = (0, configuration_1.cfg)(path, []);
     return Array.isArray(mw) ? mw : [];
 }
+/**
+ * Runs the user through each middleware in turn, feeding each one the previous
+ * result.
+ */
+async function runCreateMiddleware(u, path) {
+    let current = u;
+    for (const mw of middlewareList(path)) {
+        current = await mw(current);
+    }
+    return current;
+}
+/**
+ * The roles a request denotes, whether it arrives as one name or a list.
+ *
+ * Trimmed, stripped of blanks and de-duplicated. Order is preserved so a caller
+ * that treats the first entry as the primary role keeps that meaning.
+ *
+ * De-duplication is not cosmetic: every downstream guard is charged per entry,
+ * so `['user', ' user ']` costs two checks for one role.
+ *
+ * @param role - a single role name or a list of them
+ */
+function roleList(role) {
+    if (role === undefined || role === null) {
+        return [];
+    }
+    const wanted = (Array.isArray(role) ? role : [role]).map((r) => String(r ?? '').trim()).filter((r) => r.length > 0);
+    return [...new Set(wanted)];
+}
+/**
+ * Refuses a role the application has not configured.
+ *
+ * A role counts as configured if it either holds grants in the resolved
+ * {@link AccessControl} instance or is merely declared in `rbac.roles` - the
+ * same definition of "known" `DefaultRoleGuard` (`@spinajs/rbac-http-admin`)
+ * already uses for its own route-level check. A role may legitimately be named
+ * before it is given any permission, and a narrower definition here would
+ * refuse a role the route layer of this same codebase already accepts.
+ * `hasRole` resolves roles defined only through `$extend`, so an
+ * inheritance-only role such as `system` is recognised.
+ *
+ * `rbac.requireKnownRole: false` turns the whole check off - see the comment
+ * at its first use below.
+ *
+ * @param roles - role names to check; every unknown name is reported at once
+ */
+function assertRolesExist(roles) {
+    // An application whose roles are defined at runtime rather than in static
+    // config turns this off wholesale. `rbac-http-admin`'s DefaultRoleGuard has
+    // carried the same escape hatch for its own route-level check since before
+    // this one existed; a library-level check that could not be turned off would
+    // make rbac unusable for those applications.
+    if ((0, configuration_1.cfg)('rbac.requireKnownRole', true) === false) {
+        return;
+    }
+    const ac = di_1.DI.get('AccessControl');
+    if (!ac) {
+        // No grants loaded at all means the application has not configured rbac, not
+        // that every role is invalid - refusing here would break bootstrap ordering.
+        return;
+    }
+    // "Known" the same way DefaultRoleGuard already means it: holding grants, or
+    // merely DECLARED. A role may legitimately be named before it is given any
+    // permission, and a narrower definition here would refuse roles the route
+    // layer of this same codebase already accepts.
+    //
+    // Guarded the way DefaultRoleGuard guards the same list: `rbac.roles` may be
+    // assembled dynamically, and one malformed entry must not turn every create()
+    // in the application into an unhandled TypeError. An entry without a `Name`
+    // simply never matches a real role.
+    const configured = (0, configuration_1.cfg)('rbac.roles', []);
+    const declared = (Array.isArray(configured) ? configured : []).map((r) => r?.Name).filter(Boolean);
+    const unknown = roles.filter((r) => !ac.hasRole(r) && !declared.includes(r));
+    if (unknown.length > 0) {
+        throw new exceptions_1.InvalidArgument(`Role(s) not configured in rbac.grants or rbac.roles: ${unknown.join(', ')}`, 'roles');
+    }
+}
+/**
+ * Refuses metadata keys that decide account access.
+ *
+ * `user:pwd_reset:token` is a bearer credential redeemable at the PUBLIC reset
+ * endpoint and `user:2fa:*` is the second factor itself — writing either through
+ * a generic key-value merge hands out an account rather than annotating one.
+ * Ban and lockout keys are refused for the same reason bans have their own
+ * action: written directly they skip the event, the email and the session
+ * revocation that make a ban mean something.
+ *
+ * Lives here rather than in one http controller because the keys it protects are
+ * rbac's own, and an account seeded with a known reset token is an account
+ * takeover no matter which caller planted it — a CLI, a migration and a route
+ * all need the same refusal.
+ *
+ * @param metadata - the key-value bag a caller wants attached to an account
+ */
+function assertNoProtectedMetadata(metadata) {
+    if (!metadata) {
+        return;
+    }
+    const offending = Object.keys(metadata).filter((key) => {
+        // A glob reaches the metadata relation's setter as a PATTERN and rewrites
+        // every matching entry, so `*` alone would overwrite the whole set —
+        // including the protected keys listed above.
+        if (key.includes('*') || key.includes('?')) {
+            return true;
+        }
+        return User_js_1.USER_SECURITY_METADATA_KEYS.includes(key);
+    });
+    if (offending.length > 0) {
+        throw new exceptions_1.InvalidArgument(`Protected metadata keys cannot be set directly: ${offending.join(', ')}`);
+    }
+}
+/**
+ * Refuses a login / email already taken by another account.
+ *
+ * Exported because uniqueness is not only a creation-time rule: an update that
+ * renames an account has to apply exactly the same one, and a second
+ * implementation of it would be a second thing to keep in step. `exceptUserId`
+ * is what an update passes so an account does not clash with itself.
+ *
+ * Queries the base {@link User} rather than `userModel()`: uniqueness is GLOBAL,
+ * and an application's scoped subclass would hide the clashing row — turning a
+ * clean refusal into a driver error on the unique index.
+ *
+ * Soft-deleted rows are included for the same reason. They still occupy the
+ * unique indexes, so ignoring them trades this error for that driver error.
+ *
+ * The thrown {@link UserAlreadyExists} carries `fields`, naming WHICH of login / email
+ * clashed, so an http caller can mark the offending input rather than reporting
+ * that something, somewhere, is already in use.
+ *
+ * @param login - login to check, or undefined to skip the login check
+ * @param email - email to check, or undefined to skip the email check
+ * @param exceptUserId - id of the account being updated, which may keep its own values
+ */
+async function assertUserUnique(login, email, exceptUserId) {
+    const clashes = [];
+    if (login) {
+        const found = await User_js_1.User.query().withDeleted().where('Login', login).first();
+        if (found && found.Id !== exceptUserId) {
+            clashes.push('Login');
+        }
+    }
+    if (email) {
+        const found = await User_js_1.User.query().withDeleted().where('Email', email).first();
+        if (found && found.Id !== exceptUserId) {
+            clashes.push('Email');
+        }
+    }
+    if (clashes.length > 0) {
+        throw new exceptions_js_1.UserAlreadyExists(`${clashes.join(' and ')} already in use`, { fields: clashes });
+    }
+}
 /**
  * Creates a new user account.
  *
- * Validates and normalises inputs, hashes the password, inserts the user record,
- * optionally sets metadata, runs configured `beforeCreate` / `afterCreate` middleware,
- * emits a {@link UserCreated} event, and sends the "created" email.
+ * Validates and normalises inputs, refuses a duplicate login / email and
+ * protected metadata keys, hashes the password, inserts the user record,
+ * optionally sets metadata, runs configured `beforeCreate` / `afterCreate`
+ * middleware, emits a {@link UserCreated} event, and sends the "created" email.
+ *
+ * When no password is given, one is generated AND a password-reset link is
+ * mailed to the address. Those two are one decision, not two: a generated
+ * password is a secret nobody knows, so an account created without the reset
+ * link is an account with no way in at all. Callers that pass a password know
+ * it and own delivery themselves, so they get no link — which is what a CLI
+ * service account or a fixture wants.
  *
  * @param email - user email address (max 64 chars)
  * @param login - user login name (max 32 chars)
- * @param password - plain-text password; if empty a random one is generated
  * @param roles - array of role names to assign
- * @param id - optional explicit user id (useful when migrating from another system)
- * @param metadata - optional key-value metadata to attach to the new user
+ * @param options - see {@link ICreateUserOptions}
  * @returns an object containing the persisted {@link User} and the plain-text password
  */
-async function create(email, login, password, roles, id, metadata) {
-    const sPassword = await (0, configuration_1._service)('rbac.password', interfaces_js_1.PasswordProvider)();
+async function create(email, login, roles, options) {
+    const sPassword = await (0, configuration_1.service)('rbac.password', interfaces_js_1.PasswordProvider);
+    // Whether the CALLER supplied a password decides who hands the account to its
+    // owner, so it is read before `_default` fills a generated one in and the two
+    // cases become indistinguishable.
+    const generated = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._default)(''))(options?.password, 'password') === '';
     email = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)(), (0, util_1._is_email)(), (0, util_1._max_length)(64))(email, 'email');
     login = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)(), (0, util_1._max_length)(32))(login, 'login');
-    password = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._default)(() => sPassword.generate()))(password, 'password');
+    const roleNames = roleList(roles);
+    if (roleNames.length === 0) {
+        throw new exceptions_1.InvalidArgument('At least one role must be given', 'roles');
+    }
+    assertRolesExist(roleNames);
+    const password = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._default)(() => sPassword.generate()))(options?.password, 'password');
+    // Only the SUPPLIED branch is checked. A generated password is asserted
+    // against the same rule inside `generate()`, and re-checking it here would
+    // only re-report a configuration fault as a caller mistake.
+    if (!generated) {
+        const validator = await (0, configuration_1.service)('rbac.password.validation', interfaces_js_1.PasswordValidationProvider);
+        if (!validator.check(password)) {
+            throw new exceptions_1.InvalidArgument('Password does not meet requirements', 'password');
+        }
+    }
     const hPassword = await sPassword.hash(password);
-    return (0, util_1._chain)(
-    // create user
-    () => Promise.resolve(new User_js_1.User({
-        Id: id,
+    const metadata = options?.metadata;
+    // Ahead of everything else, and ahead of `beforeCreate` in particular: a
+    // request that is about to be refused must not first run middleware that
+    // writes to another system ( the legacy-user mirror is one ).
+    assertNoProtectedMetadata(metadata);
+    await assertUserUnique(login, email);
+    let u = new User_js_1.User({
+        Id: options?.id,
         Email: email,
         Login: login,
         Password: hPassword,
-        Role: roles,
+        Role: roleNames,
         RegisteredAt: luxon_1.DateTime.now(),
         CreatedAt: luxon_1.DateTime.now(),
         IsActive: false,
         Uuid: (0, uuid_1.v4)(),
-    })), 
-    // run before create middleware
-    (u) => (0, util_1._chain)(u, ..._create_middleware('rbac.actions.create.beforeCreate')), 
-    // insert to db
-    (0, orm_1._insert)(), (0, util_1._either)(() => metadata !== undefined, _set_user_meta(metadata ? Object.entries(metadata).map(([key, value]) => ({ key, value })) : []), async (u) => u), 
-    // run after create middleware
-    (u) => (0, util_1._chain)(u, ..._create_middleware('rbac.actions.create.afterCreate')), 
-    // send event
-    _user_ev(index_js_1.UserCreated, (u) => u.toJSON()), 
-    // send email
-    (0, util_1._tap)(_user_email('created')), 
-    // return user & password - if generated we want to know not hashed password
-    (u) => {
-        return { User: u, Password: password };
     });
+    u = await runCreateMiddleware(u, 'rbac.actions.create.beforeCreate');
+    await (0, orm_1.insertModel)(u);
+    if (metadata !== undefined) {
+        await setUserMeta(u, Object.entries(metadata).map(([key, value]) => ({ key, value })));
+    }
+    u = await runCreateMiddleware(u, 'rbac.actions.create.afterCreate');
+    await (0, queue_1.ev)(new index_js_1.UserCreated(u));
+    await sendUserEmail(u, 'created');
+    // Hand the account to its owner when nobody else can: the password above was
+    // invented here and immediately hashed, so without this the account is
+    // unreachable until an administrator remembers a second screen.
+    //
+    // AFTER the "created" email so the two arrive in the order they are meant to
+    // be read, and BY UUID rather than by the instance in hand — the reset writes
+    // three metadata entries, and `getUser()` re-reads with `Metadata` populated,
+    // which an instance built by `new User(...)` never is. Handing it the
+    // instance stored nothing, silently, and left the account with no token.
+    //
+    // Swallowed on purpose: the account EXISTS by now. Throwing would tell the
+    // caller creation failed when it did not, inviting a retry that then fails on
+    // the duplicate login. A link that could not be issued can be re-sent.
+    if (generated) {
+        try {
+            await passwordChangeRequest(u.Uuid);
+        }
+        catch (err) {
+            di_1.DI.resolve(log_1.Log, ['rbac']).error(err, `Could not issue the initial password reset for ${u.Uuid}. The account exists but its owner has no way in yet.`);
+        }
+    }
+    // if generated we want to know not hashed password
+    return { User: u, Password: password };
 }
 /**
  * Permanently deletes a user from the database.
@@ -347,13 +591,16 @@ async function create(email, login, password, roles, id, metadata) {
  * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
  */
 async function deleteUser(identifier) {
-    return (0, util_1._chain)(_user(identifier), (0, util_1._tap)((u) => u.destroy()), 
+    const u = await getUser(identifier);
+    await u.destroy();
     // Same reason a deactivation revokes: the account may no longer act. A live
     // session outlasting the deletion is worse here than there — the session
     // middleware resolves its user through `isActiveUser()`, which no longer
     // matches a soft-deleted row, so every request from that session dies in
     // the middleware instead of being cleanly logged out.
-    _revoke_sessions(), _user_ev(index_js_1.UserDeleted), _user_email('deleted'));
+    await revokeUserSessions(u);
+    await (0, queue_1.ev)(new index_js_1.UserDeleted(u));
+    await sendUserEmail(u, 'deleted');
 }
 /**
  * Grants an additional role to a user.
@@ -365,7 +612,14 @@ async function deleteUser(identifier) {
  */
 async function grant(identifier, role) {
     role = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(role, 'role');
-    return (0, util_1._chain)(_user(identifier), (0, util_1._tap)(async (u) => (u.Role = lodash_1.default.uniq([...u.Role, role]))), _user_update(), _user_ev(index_js_1.UserRoleGranted, role));
+    // A role you cannot create an account with must not be one you can add
+    // afterwards - otherwise grant is a way around the creation check.
+    assertRolesExist([role]);
+    const u = await getUser(identifier);
+    u.Role = lodash_1.default.uniq([...u.Role, role]);
+    await updateUser(u);
+    await (0, queue_1.ev)(new index_js_1.UserRoleGranted(u, role));
+    return u;
 }
 /**
  * Revokes a role from a user.
@@ -377,74 +631,118 @@ async function grant(identifier, role) {
  */
 async function revoke(identifier, role) {
     role = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(role, 'role');
-    return (0, util_1._chain)(_user(identifier), (0, util_1._tap)(async (u) => (u.Role = u.Role.filter((r) => r !== role))), _user_update(), _user_ev(index_js_1.UserRoleRevoked, role));
+    const u = await getUser(identifier);
+    u.Role = u.Role.filter((r) => r !== role);
+    await updateUser(u);
+    await (0, queue_1.ev)(new index_js_1.UserRoleRevoked(u, role));
+    return u;
 }
 /**
- *
- * Bans user for specified time. If duration is 0 user is banned for 24h
+ * Bans user for specified time. If duration is not given user is banned for 24h
  *
  * @param identifier user identifier one of : id, uuid, email, login
- * @param reason reson for ban
+ * @param reason reason for ban
  * @param duration duration in seconds
- * @returns
  */
 async function ban(identifier, reason, duration) {
     duration = (0, util_1._check_arg)((0, util_1._default)(24 * 60 * 60), (0, util_1._is_number)((0, util_1._gt)(0)))(duration, 'duration');
     reason = (0, util_1._check_arg)((0, util_1._default)('NO_REASON'), (0, util_1._max_length)(255))(reason, 'reason');
-    return (0, util_1._chain)(_user(identifier), (u) => {
-        if (u.Metadata[User_js_1.USER_COMMON_METADATA.USER_BAN_IS_BANNED]) {
-            throw new exceptions_1.ErrorCode(E_CODES.E_USER_BANNED, `User is already banned`, { user: u });
-        }
-        return u;
-    }, _set_user_meta([
+    const u = await getUser(identifier);
+    // duration-aware: an EXPIRED ban must not block re-banning ( the raw flag
+    // stays behind until an explicit unban clears it )
+    if (u.IsBanned) {
+        throw new exceptions_js_1.UserIsBanned(`User is already banned`, { user: u.Uuid });
+    }
+    await setUserMeta(u, [
         { key: User_js_1.USER_COMMON_METADATA.USER_BAN_DURATION, value: duration },
         { key: User_js_1.USER_COMMON_METADATA.USER_BAN_REASON, value: reason },
         { key: User_js_1.USER_COMMON_METADATA.USER_BAN_IS_BANNED, value: true },
         { key: User_js_1.USER_COMMON_METADATA.USER_BAN_START_DATE, value: luxon_1.DateTime.now() },
-    ]), 
+    ]);
     // A ban that leaves the banned user's session alive bans nothing until that
     // session expires — `isActiveUser` does not filter on the ban flag, so the
     // session would keep resolving happily.
-    _revoke_sessions(), _user_ev(index_js_1.UserBanned), _user_email('banned'));
+    await revokeUserSessions(u);
+    await (0, queue_1.ev)(new index_js_1.UserBanned(u));
+    await sendUserEmail(u, 'banned');
+    return u;
 }
 /**
- *
  * Unban user
  *
- * @param identifier
- * @returns
+ * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
  */
 async function unban(identifier) {
-    return (0, util_1._chain)(_user(identifier), 
-    // guard must return the user so the chain can keep flowing it downstream
-    (0, util_1._tap)(async (u) => {
-        if (!u.Metadata[User_js_1.USER_COMMON_METADATA.USER_BAN_IS_BANNED]) {
-            throw new exceptions_1.ErrorCode(E_CODES.E_USER_BANNED, `User is already unbanned`, { user: u });
-        }
-    }), 
+    const u = await getUser(identifier);
+    if (!u.Metadata[User_js_1.USER_COMMON_METADATA.USER_BAN_IS_BANNED]) {
+        throw new exceptions_js_1.UserIsBanned(`User is already unbanned`, { user: u.Uuid });
+    }
     // actually remove the ban metadata from the DB. Assigning a regex-like
     // string key never cleared anything; delete() removes each key from store.
-    (0, util_1._tap)(async (u) => {
-        await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_BAN_IS_BANNED);
-        await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_BAN_START_DATE);
-        await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_BAN_DURATION);
-        await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_BAN_REASON);
-    }), _user_ev(index_js_1.UserUnbanned));
+    await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_BAN_IS_BANNED);
+    await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_BAN_START_DATE);
+    await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_BAN_DURATION);
+    await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_BAN_REASON);
+    await (0, queue_1.ev)(new index_js_1.UserUnbanned(u));
+    await sendUserEmail(u, 'unbanned');
+    return u;
+}
+/**
+ * Builds the link a reset mail sends the user to.
+ *
+ * `rbac.password.resetUrl` is the application's own redemption page. The token
+ * and the address are appended as query parameters because that page has to send
+ * both back to `POST /auth/password/reset`, and it has no other way of knowing
+ * them. Returns an empty string when no url is configured — the template then
+ * renders whatever it does without one, rather than a link to nowhere.
+ */
+function passwordResetUrl(email, token) {
+    const base = (0, configuration_1.cfg)('rbac.password.resetUrl', '');
+    if (!base) {
+        return '';
+    }
+    const url = new URL(base);
+    url.searchParams.set('token', token);
+    url.searchParams.set('email', email);
+    return url.toString();
 }
 /**
  * Initiates a password-change request for a user.
  * Generates a reset token, stores it along with the current timestamp and configured
- * wait time in the user's metadata, and emits a {@link UserPasswordChangeRequest} event.
+ * wait time in the user's metadata, emits a {@link UserPasswordChangeRequest} event and
+ * sends the `changePassword` mail carrying the token.
+ *
+ * THE MAIL IS THE POINT. The token is issued into metadata and never returned over HTTP —
+ * possession of the mailbox is what authorizes the reset — so an installation that does not
+ * deliver it has a reset flow nobody can complete. It used to be the application's job, via
+ * the event, and every application that had not written that subscriber silently issued
+ * tokens into the void. `rbac.email.changePassword.enabled: false` still turns it off for an
+ * application that really does deliver it some other way.
+ *
+ * The token reaches the template through the model and is NOT logged: it is a bearer
+ * credential for `POST /auth/password/reset`.
  *
  * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
  */
 async function passwordChangeRequest(identifier) {
-    const pwdWaitTime = await (0, configuration_1._cfg)('rbac.password.passwordResetWaitTime')();
-    return (0, util_1._chain)(_user(identifier), _set_user_meta([
+    const pwdWaitTime = (0, configuration_1.cfg)('rbac.password.passwordResetWaitTime');
+    const token = (0, uuid_1.v4)();
+    const u = await getUser(identifier);
+    await setUserMeta(u, [
         { key: User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_START_DATE, value: luxon_1.DateTime.now() },
-        { key: User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_TOKEN, value: (0, uuid_1.v4)() },
+        { key: User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_TOKEN, value: token },
         { key: User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_WAIT_TIME, value: pwdWaitTime },
-    ]), _user_ev(index_js_1.UserPasswordChangeRequest));
+    ]);
+    await (0, queue_1.ev)(new index_js_1.UserPasswordChangeRequest(u));
+    await sendUserEmail(u, 'changePassword', (usr) => ({
+        Token: token,
+        ResetUrl: passwordResetUrl(usr.Email, token),
+        // Minutes rather than the raw seconds: a template writes "the link is
+        // valid for X minutes", and doing the arithmetic in a handlebars
+        // expression is not something every template engine can do.
+        ExpiresInMinutes: Math.round(pwdWaitTime / 60),
+    }));
+    return u;
 }
 /**
  * Confirms a password reset by validating the token and expiration, then changing the password.
@@ -455,45 +753,46 @@ async function passwordChangeRequest(identifier) {
  * @param token - the reset token that was issued by {@link passwordChangeRequest}
  */
 async function confirmPasswordReset(identifier, newPassword, token) {
-    return (0, util_1._chain)(_user(identifier), 
+    const u = await getUser(identifier);
     // A reset must not resurrect an account that is banned, deactivated or
     // deleted — otherwise the reset flow is a way around every one of those
-    // states. Same ErrorCode family the caller already collapses into one
+    // states. Same exception family the caller already collapses into one
     // opaque failure, so this does not become an account-state oracle.
-    (0, util_1._tap)(async (u) => {
-        if (u.Metadata[User_js_1.USER_COMMON_METADATA.USER_BAN_IS_BANNED]) {
-            throw new exceptions_1.ErrorCode(E_CODES.E_USER_BANNED, `Password reset refused: user is banned`, { user: u });
-        }
-        if (!u.IsActive || u.DeletedAt) {
-            throw new exceptions_1.ErrorCode(E_CODES.E_USER_NOT_ACTIVE, `Password reset refused: user is not active`, { user: u });
-        }
-    }), (0, util_1._tap)((u) => (0, util_1._chain)(u, (0, util_1._zip)(_get_user_meta(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_START_DATE), _get_user_meta(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_WAIT_TIME)), ([dueDate, waitTime]) => {
-        if (dueDate.plus({ seconds: waitTime }) < luxon_1.DateTime.now()) {
-            throw new exceptions_1.ErrorCode(E_CODES.E_TOKEN_EXPIRED, `Password change token expired, token expiration date is: ${dueDate.toISO()}`, {
-                dueDate,
-                waitTime,
-                time: luxon_1.DateTime.now(),
-                user: u,
-            });
-        }
-    })), (0, util_1._tap)((u) => (0, util_1._chain)(u, _get_user_meta(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_TOKEN), async (resetToken) => {
-        if (!_secure_compare(String(resetToken), token)) {
-            throw new exceptions_1.ErrorCode(E_CODES.E_TOKEN_INVALID, `Password change token invalid, operation not permitted`, {
-                token,
-                resetToken,
-                user: u,
-            });
-        }
-    })), changePassword(newPassword), 
+    // duration-aware: a user whose ban has expired can log in again, so they
+    // must be able to reset their password too
+    if (u.IsBanned) {
+        throw new exceptions_js_1.UserIsBanned(`Password reset refused: user is banned`, { user: u.Uuid });
+    }
+    if (!u.IsActive || u.DeletedAt) {
+        throw new exceptions_js_1.UserNotActive(`Password reset refused: user is not active`, { user: u.Uuid });
+    }
+    const dueDate = await getUserMeta(u, User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_START_DATE);
+    const waitTime = await getUserMeta(u, User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_WAIT_TIME);
+    if (dueDate.plus({ seconds: waitTime }) < luxon_1.DateTime.now()) {
+        throw new exceptions_js_1.TokenExpired(`Password change token expired, token expiration date is: ${dueDate.toISO()}`, {
+            dueDate,
+            waitTime,
+            time: luxon_1.DateTime.now(),
+            user: u.Uuid,
+        });
+    }
+    const resetToken = await getUserMeta(u, User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_TOKEN);
+    if (!secureCompare(String(resetToken), token)) {
+        // the STORED token is a live bearer credential and the submitted one may
+        // be a near miss of it - neither belongs in a payload that gets logged
+        throw new exceptions_js_1.TokenInvalid(`Password change token invalid, operation not permitted`, {
+            user: u.Uuid,
+        });
+    }
+    await changeUserPassword(u, newPassword);
     // Burn the token. Validating it and leaving it in place made it a
     // multi-use credential for the whole `passwordResetWaitTime` window:
     // anyone who saw the reset mail once could keep re-taking the account.
-    (0, util_1._tap)(async (u) => {
-        await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_TOKEN);
-        await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_START_DATE);
-        await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_WAIT_TIME);
-        await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET);
-    }));
+    await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_TOKEN);
+    await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_START_DATE);
+    await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_WAIT_TIME);
+    await u.Metadata.delete(User_js_1.USER_COMMON_METADATA.USER_PWD_RESET);
+    return u;
 }
 /**
  * Length-independent, constant-time string comparison for secrets.
@@ -505,7 +804,7 @@ async function confirmPasswordReset(identifier, newPassword, token) {
  * @param a - value read from storage
  * @param b - value supplied by the caller
  */
-function _secure_compare(a, b) {
+function secureCompare(a, b) {
     const ha = (0, crypto_1.createHash)('sha256')
         .update(a ?? '')
         .digest();
@@ -517,63 +816,106 @@ function _secure_compare(a, b) {
     return (0, crypto_1.timingSafeEqual)(ha, hb);
 }
 /**
- * Returns a function that changes a user's password.
+ * Changes a user's password.
  * The new password is validated against the configured {@link PasswordValidationProvider},
  * hashed via the configured {@link PasswordProvider}, persisted, and a
  * {@link UserPasswordChanged} event is emitted.
  *
+ * @param u - user to change the password for
  * @param password - new plain-text password
- * @returns a function that receives a {@link User} and returns the updated user
  */
-function changePassword(password) {
+async function changeUserPassword(u, password) {
     password = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(password, 'password');
-    return async (u) => {
-        return (0, util_1._chain)((0, util_1._use)((0, configuration_1._service)('rbac.password', interfaces_js_1.PasswordProvider), 'pwd'), (0, util_1._use)((0, configuration_1._service)('rbac.password.validation', interfaces_js_1.PasswordValidationProvider), 'validator'), (0, util_1._tap)(async ({ validator }) => {
-            if (!validator.check(password)) {
-                throw new Error('Password does not meet requirements');
-            }
-        }), 
-        // update password
-        ({ pwd }) => pwd.hash(password), (hPassword) => (0, util_1._chain)(u, (0, orm_1._update)({ Password: hPassword }), _set_user_meta([
-            { key: User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_LAST_ATTEMPT, value: luxon_1.DateTime.now().toISO() },
-            // a successful password change clears the login throttle: the
-            // credential the failures were counted against no longer exists
-            { key: User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS, value: 0 },
-            { key: User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL, value: null },
-        ]), 
-        // Every session was authorized by the OLD password. Whoever holds one
-        // — including whoever the user is changing the password because of —
-        // loses it here. Callers that want the acting user to stay logged in
-        // ( eg. PATCH /user/password ) mint a fresh session afterwards.
-        _revoke_sessions(), _user_ev(index_js_1.UserPasswordChanged)));
-    };
+    const pwd = await (0, configuration_1.service)('rbac.password', interfaces_js_1.PasswordProvider);
+    const validator = await (0, configuration_1.service)('rbac.password.validation', interfaces_js_1.PasswordValidationProvider);
+    if (!validator.check(password)) {
+        // `InvalidArgument`, not a bare `Error`: a password the caller typed is
+        // invalid INPUT, and @spinajs/http maps this class to 400 ( BadRequestResponse
+        // via `@HandleException` ) while an unmapped error becomes a 500. Every route
+        // that lets a user pick a password - `PATCH /user/password`, the reset flow -
+        // answered "internal server error" for a password that was merely too weak,
+        // which reads to the user as a broken screen rather than as a rule they can
+        // satisfy. The field name and error code travel in the response body ( the
+        // error handler spreads the exception's own enumerable props ), so a client
+        // can point at the field and branch on the code instead of matching English.
+        throw new exceptions_1.InvalidArgument('Password does not meet requirements', 'password', 'E_PASSWORD_DOES_NOT_MEET_REQUIREMENTS');
+    }
+    const hPassword = await pwd.hash(password);
+    await (0, orm_1.updateModel)(u, { Password: hPassword });
+    await setUserMeta(u, [
+        { key: User_js_1.USER_COMMON_METADATA.USER_PWD_RESET_LAST_ATTEMPT, value: luxon_1.DateTime.now().toISO() },
+        // a successful password change clears the login throttle: the
+        // credential the failures were counted against no longer exists
+        { key: User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS, value: 0 },
+        { key: User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL, value: null },
+    ]);
+    // Every session was authorized by the OLD password. Whoever holds one
+    // — including whoever the user is changing the password because of —
+    // loses it here. Callers that want the acting user to stay logged in
+    // ( eg. PATCH /user/password ) mint a fresh session afterwards.
+    await revokeUserSessions(u);
+    await (0, queue_1.ev)(new index_js_1.UserPasswordChanged(u));
+    return u;
+}
+/**
+ * Chain step form of {@link changeUserPassword}.
+ *
+ * @param password - new plain-text password
+ */
+function changePassword(password) {
+    return (u) => changeUserPassword(u, password);
 }
 /**
+ * Expire password for user.
  *
- * Expire password for user
+ * The stored credential is replaced with a freshly generated random one, so the
+ * expired password stops working even if the account is re-activated without a
+ * reset. The account is deactivated, {@link UserPasswordExpired} is emitted and
+ * the 'passwordExpired' mail is sent.
  *
- * @param identifier
+ * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
  */
 async function expirePassword(identifier) {
-    return await (0, util_1._chain)(_user(identifier), (user) => deactivate(user), _user_ev(UserPasswordExpired_js_1.UserPasswordExpired));
+    const u = await getUser(identifier);
+    const sPassword = await (0, configuration_1.service)('rbac.password', interfaces_js_1.PasswordProvider);
+    const hPassword = await sPassword.hash(sPassword.generate());
+    await (0, orm_1.updateModel)(u, { Password: hPassword });
+    await deactivate(u);
+    await (0, queue_1.ev)(new UserPasswordExpired_js_1.UserPasswordExpired(u));
+    await sendUserEmail(u, 'passwordExpired');
 }
 /**
- * Check if password match user password stored in db
+ * Sends the 'passwordWillExpire' warning mail. No account state changes -
+ * this is the notification half of the expiry flow, meant to be called by an
+ * application scheduler ahead of {@link expirePassword}.
  *
- * @param identifier
- * @param password
- * @returns
+ * @param identifier - numeric id, uuid / email / login string, or an existing {@link User} instance
+ * @param expiresAt - optional instant the password expires, passed to the template
  */
-function passwordMatch(password) {
+async function notifyPasswordWillExpire(identifier, expiresAt) {
+    const u = await getUser(identifier);
+    await sendUserEmail(u, 'passwordWillExpire', () => ({ ExpiresAt: expiresAt?.toISO() ?? null }));
+    return u;
+}
+/**
+ * Checks if password matches the user's password stored in db.
+ *
+ * @param u - user to check against
+ * @param password - plain-text password to verify
+ */
+async function verifyPassword(u, password) {
     password = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(password, 'password');
-    return async (u) => {
-        // NOTE: _chain forwards exactly ONE value from step to step, so the second
-        // parameter of the last step was always undefined and every call died with
-        // "Cannot read properties of undefined (reading 'Password')" — including
-        // the happy path of PATCH /user/password. The user is taken from the
-        // closure instead.
-        return await (0, util_1._chain)((0, configuration_1._service)('rbac.password', interfaces_js_1.PasswordProvider), async (sPwd) => sPwd.verify(u.Password, password));
-    };
+    const sPwd = await (0, configuration_1.service)('rbac.password', interfaces_js_1.PasswordProvider);
+    return sPwd.verify(u.Password, password);
+}
+/**
+ * Chain step form of {@link verifyPassword}. The user is taken from the step
+ * argument - a regression once read it from a never-passed second parameter.
+ *
+ * @param password - plain-text password to verify
+ */
+function passwordMatch(password) {
+    return (u) => verifyPassword(u, password);
 }
 /**
  * Authenticates a user with the given password.
@@ -587,63 +929,67 @@ function passwordMatch(password) {
  */
 async function login(identifier, password) {
     password = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(password, 'password');
-    return await (0, util_1._chain)(_login_lookup(identifier), (0, util_1._catch)((u) => {
-        return (0, util_1._chain)(async () => {
-            // Refuse before the password is even checked, so a locked account
-            // cannot be probed at all during the lockout window.
-            await _assert_not_locked(u);
-            return (0, configuration_1._service)('rbac.auth', interfaces_js_1.AuthProvider)();
-        }, async (sAuth) => sAuth.authenticate(u.Email, password), (0, orm_1._update)({ LastLoginAt: luxon_1.DateTime.now() }), _clear_login_throttle(), _user_ev(index_js_1.UserLogged));
-    }, (err, u) => {
-        return (0, util_1._chain)(() => u, 
+    // A lookup failure ( unknown account ) is NOT counted as a failed login -
+    // there is no account to count it against.
+    const u = await loginLookup(identifier);
+    try {
+        // Refuse before the password is even checked, so a locked account
+        // cannot be probed at all during the lockout window.
+        assertNotLocked(u);
+        const sAuth = await (0, configuration_1.service)('rbac.auth', interfaces_js_1.AuthProvider);
+        // the authenticated user is a FRESH row read by the auth provider ( with
+        // metadata populated ) - every step below acts on it, not on the lookup
+        const authenticated = await sAuth.authenticate(u.Email, password);
+        await (0, orm_1.updateModel)(authenticated, { LastLoginAt: luxon_1.DateTime.now() });
+        await clearLoginThrottle(authenticated);
+        await (0, queue_1.ev)(new index_js_1.UserLogged(authenticated));
+        return authenticated;
+    }
+    catch (err) {
         // count the failure and lock the account once the configured
-        // threshold is reached
-        _register_failed_login(err), 
-        // send event of failed login
-        _user_ev(UserLoginFailed_js_1.UserLoginFailed, err), 
-        // rethrow error for caller
-        () => {
-            throw err;
-        });
-    }));
+        // threshold is reached, then notify and rethrow for the caller
+        await registerFailedLogin(u, err);
+        await (0, queue_1.ev)(new UserLoginFailed_js_1.UserLoginFailed(u, err));
+        throw err;
+    }
 }
 /**
  * Resolves the user a login attempt names, answering an authentication failure
  * rather than an orm one when no such account exists.
  *
- * {@link _user_unsafe} ends in `firstOrFail()`, whose `OrmNotFoundException` is
- * neither `ErrorCode` nor `InvalidArgument`: the login controller cannot read it
+ * {@link getUserUnsafe} ends in `firstOrFail()`, whose `OrmNotFoundException` is
+ * neither a rbac exception nor `InvalidArgument`: the login controller cannot read it
  * as an authentication failure, so it rethrows and `@spinajs/orm-http` maps it to
  * a 404 while a wrong password answers 401. That difference is an
  * account-enumeration oracle — the status code alone tells a caller whether an
- * address is registered. Both cases carry `E_INVALID_CREDENTIALS`, exactly as
+ * address is registered. Both cases throw {@link InvalidCredentials}, exactly as
  * {@link SimpleDbAuthProvider.authenticate} already does for the password it
  * cannot verify.
  *
  * @param identifier - numeric id, uuid / email / login string, or an existing {@link User}
  */
-function _login_lookup(identifier) {
+async function loginLookup(identifier) {
     const id = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_nil)())(identifier, 'identifier');
     if (id instanceof User_js_1.UserBase) {
-        return () => Promise.resolve(id);
+        return id;
     }
-    return () => User_js_1.UserBase.query().whereAnything(id).populate('Metadata').firstOrThrow(new exceptions_1.ErrorCode(interfaces_js_1.AthenticationErrorCodes.E_INVALID_CREDENTIALS, 'no user with given email'));
+    return User_js_1.UserBase.query().whereAnything(id).populate('Metadata').firstOrThrow(new exceptions_js_1.InvalidCredentials('no user with given email'));
 }
 /**
  * Throws when the account is inside a lockout window opened by
- * {@link _register_failed_login}.
+ * {@link registerFailedLogin}.
  *
  * @param u - user attempting to authenticate
  */
-async function _assert_not_locked(u) {
+function assertNotLocked(u) {
     const raw = u?.Metadata?.[User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL];
     if (!raw) {
         return;
     }
     const lockedUntil = raw instanceof luxon_1.DateTime ? raw : luxon_1.DateTime.fromISO(String(raw));
     if (lockedUntil.isValid && lockedUntil > luxon_1.DateTime.now()) {
-        throw new exceptions_1.ErrorCode(interfaces_js_1.AthenticationErrorCodes.E_LOGIN_ATTEMPTS_EXCEEDED, `Too many failed login attempts, account is temporarily locked until ${lockedUntil.toISO()}`, {
-            user: u,
+        throw new exceptions_js_1.LoginAttemptsExceeded(`Too many failed login attempts, account is temporarily locked until ${lockedUntil.toISO()}`, {
+            user: u.Uuid,
             lockedUntil,
         });
     }
@@ -651,21 +997,18 @@ async function _assert_not_locked(u) {
 /**
  * Clears the failure counter and any expired lock after a successful login.
  */
-function _clear_login_throttle() {
-    return async (u) => {
-        const meta = u?.Metadata;
-        if (!meta) {
-            return u;
-        }
-        const hasAttempts = Number(meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS] ?? 0) > 0;
-        const hasLock = Boolean(meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL]);
-        if (!hasAttempts && !hasLock) {
-            return u;
-        }
-        await meta.delete(User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS);
-        await meta.delete(User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL);
-        return u;
-    };
+async function clearLoginThrottle(u) {
+    const meta = u?.Metadata;
+    if (!meta) {
+        return;
+    }
+    const hasAttempts = Number(meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS] ?? 0) > 0;
+    const hasLock = Boolean(meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL]);
+    if (!hasAttempts && !hasLock) {
+        return;
+    }
+    await meta.delete(User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS);
+    await meta.delete(User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL);
 }
 /**
  * Records one failed authentication and, at `rbac.password.blockAfterAttempts`
@@ -676,32 +1019,30 @@ function _clear_login_throttle() {
  * itself the lockout is not counted — otherwise hammering a locked account
  * would keep extending the lock indefinitely.
  *
+ * @param u - user whose failed attempt is recorded
  * @param err - the error that ended the login attempt
  */
-function _register_failed_login(err) {
-    return async (u) => {
-        const meta = u?.Metadata;
-        if (!meta) {
-            return u;
-        }
-        if (err instanceof exceptions_1.ErrorCode && err.code === interfaces_js_1.AthenticationErrorCodes.E_LOGIN_ATTEMPTS_EXCEEDED) {
-            return u;
-        }
-        const blockAfter = await (0, configuration_1._cfg)('rbac.password.blockAfterAttempts', 5)();
-        const lockoutTime = await (0, configuration_1._cfg)('rbac.password.lockoutTime', 15 * 60)();
-        if (!blockAfter || blockAfter <= 0) {
-            return u;
-        }
-        const attempts = Number(meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS] ?? 0) + 1;
-        if (attempts >= blockAfter) {
-            meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS] = 0;
-            meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL] = luxon_1.DateTime.now().plus({ seconds: lockoutTime }).toISO();
-        }
-        else {
-            meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS] = attempts;
-        }
-        await meta.update();
-        return u;
-    };
+async function registerFailedLogin(u, err) {
+    const meta = u?.Metadata;
+    if (!meta) {
+        return;
+    }
+    if (err instanceof exceptions_js_1.LoginAttemptsExceeded) {
+        return;
+    }
+    const blockAfter = (0, configuration_1.cfg)('rbac.password.blockAfterAttempts', 5);
+    const lockoutTime = (0, configuration_1.cfg)('rbac.password.lockoutTime', 15 * 60);
+    if (!blockAfter || blockAfter <= 0) {
+        return;
+    }
+    const attempts = Number(meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS] ?? 0) + 1;
+    if (attempts >= blockAfter) {
+        meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS] = 0;
+        meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_LOCKED_UNTIL] = luxon_1.DateTime.now().plus({ seconds: lockoutTime }).toISO();
+    }
+    else {
+        meta[User_js_1.USER_COMMON_METADATA.USER_LOGIN_ATTEMPTS] = attempts;
+    }
+    await meta.update();
 }
 //# sourceMappingURL=actions.js.map