@vsaas/loopback 12.3.1 → 12.5.0

package/common/models/user.json

@@ -52,6 +52,12 @@
       "permission": "ALLOW",
       "property": "verifyTwoFactor"
     },
+    {
+      "principalType": "ROLE",
+      "principalId": "$authenticated",
+      "permission": "ALLOW",
+      "property": "getTwoFactorStatus"
+    },
     {
       "principalType": "ROLE",
       "principalId": "$authenticated",

package/dist/common/models/user.cjs

@@ -3,6 +3,7 @@ const require_runtime$1 = require("../../_virtual/_rolldown/runtime.cjs");
 const require_lib_globalize = require("../../lib/globalize.cjs");
 const require_lib_runtime = require("../../lib/runtime.cjs");
 const require_lib_utils = require("../../lib/utils.cjs");
+const require_lib_two_factor_service = require("../../lib/two-factor/service.cjs");
 //#region src/common/models/user.ts
 var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, module) => {
 	const path = require("path");
@@ -12,6 +13,7 @@ var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, mo
 	require("fs");
 	const isEmail = require("isemail");
 	const utils = require_lib_utils;
+	const { TWO_FACTOR_ENROLLMENT_SCOPE } = (require_lib_two_factor_service.init_service(), require_runtime$1.__toCommonJS(require_lib_two_factor_service.service_exports));
 	const qs = require("querystring");
 	const crypto = require("crypto");
 	const assert = require("assert");
@@ -209,6 +211,17 @@ var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, mo
 			process.nextTick(fn, null, true);
 			return fn.promise;
 		};
+		/**
+		* Whether the application requires `user` to use a second factor. Override
+		* it to enforce a policy: a user that has not enrolled yet logs in with a
+		* session restricted to the enrollment, and cannot disable the factor.
+		*/
+		User.isTwoFactorRequired = function(user, options, fn) {
+			if (typeof options === "function") fn = options;
+			fn = fn || utils.createPromiseCallback();
+			process.nextTick(fn, null, false);
+			return fn.promise;
+		};
 		User.buildTwoFactorLoginContext = function(credentials, options, fn) {
 			if (typeof options === "function") fn = options;
 			fn = fn || utils.createPromiseCallback();
@@ -235,6 +248,61 @@ var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, mo
 			}
 			return this._authenticationSecurity.verifyTwoFactor(verification, options || {}, fn);
 		};
+		function twoFactorUnavailable(Model, fn) {
+			fn = fn || utils.createPromiseCallback();
+			const error = /* @__PURE__ */ new Error("Two-factor authentication is not configured");
+			error.statusCode = Model.settings.twoFactor == null ? 404 : 503;
+			error.code = Model.settings.twoFactor == null ? "TWO_FACTOR_NOT_CONFIGURED" : "AUTHENTICATION_SECURITY_UNAVAILABLE";
+			process.nextTick(fn, error);
+			return fn.promise;
+		}
+		User.getTwoFactorStatus = function(userId, options, fn) {
+			if (typeof options === "function") {
+				fn = options;
+				options = void 0;
+			}
+			if (!this._authenticationSecurityReady || !this._authenticationSecurity) return twoFactorUnavailable(this, fn);
+			return this._authenticationSecurity.status(userId, options || {}, fn);
+		};
+		/**
+		* DANGER: removes the second factor of user `userId` and closes their
+		* sessions, so their account is protected by the password alone until they
+		* enroll again. Whoever can call this can strip 2FA from that user.
+		*
+		* It is deliberately not a remote method: an application that exposes it
+		* must declare its own endpoint and grant it to the narrowest roles. As a
+		* floor, this method requires an authenticated actor other than the user,
+		* who must prove themselves with `request.currentPassword` and, when they
+		* use 2FA, `request.totpCode`. It emits `twoFactorReset` with the actor.
+		*/
+		User.resetTwoFactor = function(userId, request, options, fn) {
+			if (typeof options === "function") {
+				fn = options;
+				options = void 0;
+			}
+			fn = fn || utils.createPromiseCallback();
+			const Model = this;
+			const token = options && options.accessToken;
+			if (!Model._authenticationSecurityReady || !Model._authenticationSecurity) return twoFactorUnavailable(Model, fn);
+			const ActorModel = token && token.principalType && token.principalType !== Model.modelName ? Model.app && Model.app.models[token.principalType] : Model;
+			if (!token || token.userId == null || !ActorModel) {
+				const error = /* @__PURE__ */ new Error("Authorization required");
+				error.statusCode = 401;
+				error.code = "AUTHORIZATION_REQUIRED";
+				process.nextTick(fn, error);
+				return fn.promise;
+			}
+			if (ActorModel === Model && String(token.userId) === String(userId)) {
+				const error = /* @__PURE__ */ new Error("Use disable to change your own factor");
+				error.statusCode = 403;
+				error.code = "TWO_FACTOR_RESET_SELF";
+				process.nextTick(fn, error);
+				return fn.promise;
+			}
+			if (!ActorModel._authenticationSecurityReady || !ActorModel._authenticationSecurity) return twoFactorUnavailable(ActorModel, fn);
+			ActorModel._authenticationSecurity.proveActor(token.userId, request || {}, options).then(() => Model._authenticationSecurity.reset(userId, options)).then((result) => fn(null, result), fn);
+			return fn.promise;
+		};
 		for (const method of [
 			"beginTwoFactorEnrollment",
 			"confirmTwoFactorEnrollment",
@@ -245,14 +313,7 @@ var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, mo
 				fn = options;
 				options = void 0;
 			}
-			if (!this._authenticationSecurityReady || !this._authenticationSecurity) {
-				fn = fn || utils.createPromiseCallback();
-				const error = /* @__PURE__ */ new Error("Two-factor authentication is not configured");
-				error.statusCode = this.settings.twoFactor == null ? 404 : 503;
-				error.code = this.settings.twoFactor == null ? "TWO_FACTOR_NOT_CONFIGURED" : "AUTHENTICATION_SECURITY_UNAVAILABLE";
-				process.nextTick(fn, error);
-				return fn.promise;
-			}
+			if (!this._authenticationSecurityReady || !this._authenticationSecurity) return twoFactorUnavailable(this, fn);
 			const serviceMethod = {
 				beginTwoFactorEnrollment: "beginEnrollment",
 				confirmTwoFactorEnrollment: "confirmEnrollment",
@@ -690,9 +751,33 @@ var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, mo
 					path: "/two-factor/verify"
 				}
 			});
-			function registerTwoFactorManagementMethod(name, path, description) {
+			const enrollmentScopes = ["DEFAULT", TWO_FACTOR_ENROLLMENT_SCOPE];
+			UserModel.remoteMethod("getTwoFactorStatus", {
+				description: "Two-factor state of the current user.",
+				accepts: [{
+					arg: "userId",
+					type: "any",
+					http: getUserIdFromRequestContext
+				}, {
+					arg: "options",
+					type: "object",
+					http: buildAuthenticationOptions
+				}],
+				returns: {
+					arg: "status",
+					type: "object",
+					root: true
+				},
+				accessScopes: enrollmentScopes,
+				http: {
+					verb: "get",
+					path: "/two-factor/status"
+				}
+			});
+			function registerTwoFactorManagementMethod(name, path, description, accessScopes) {
 				UserModel.remoteMethod(name, {
 					description,
+					...accessScopes ? { accessScopes } : {},
 					accepts: [
 						{
 							arg: "userId",
@@ -722,13 +807,14 @@ var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, mo
 					}
 				});
 			}
-			registerTwoFactorManagementMethod("beginTwoFactorEnrollment", "/two-factor/setup", "Begin two-factor enrollment.");
-			registerTwoFactorManagementMethod("confirmTwoFactorEnrollment", "/two-factor/confirm", "Confirm two-factor enrollment.");
+			registerTwoFactorManagementMethod("beginTwoFactorEnrollment", "/two-factor/setup", "Begin two-factor enrollment.", enrollmentScopes);
+			registerTwoFactorManagementMethod("confirmTwoFactorEnrollment", "/two-factor/confirm", "Confirm two-factor enrollment.", enrollmentScopes);
 			registerTwoFactorManagementMethod("regenerateTwoFactorRecoveryCodes", "/two-factor/recovery-codes", "Regenerate two-factor recovery codes.");
 			registerTwoFactorManagementMethod("disableTwoFactor", "/two-factor/disable", "Disable two-factor authentication.");
 			for (const method of [
 				"login",
 				"verifyTwoFactor",
+				"getTwoFactorStatus",
 				"beginTwoFactorEnrollment",
 				"confirmTwoFactorEnrollment",
 				"regenerateTwoFactorRecoveryCodes",
@@ -741,6 +827,7 @@ var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, mo
 			for (const method of [
 				"login",
 				"verifyTwoFactor",
+				"getTwoFactorStatus",
 				"beginTwoFactorEnrollment",
 				"confirmTwoFactorEnrollment",
 				"regenerateTwoFactorRecoveryCodes",
@@ -765,6 +852,7 @@ var require_user = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports, mo
 					},
 					description: "Do not supply this argument, it is automatically extracted from request headers."
 				}],
+				accessScopes: enrollmentScopes,
 				http: { verb: "all" }
 			});
 			UserModel.remoteMethod("prototype.verify", {

package/dist/common/models/user2.cjs

@@ -48,6 +48,12 @@ var require_user = /* @__PURE__ */ require("../../_virtual/_rolldown/runtime.cjs
 				"permission": "ALLOW",
 				"property": "verifyTwoFactor"
 			},
+			{
+				"principalType": "ROLE",
+				"principalId": "$authenticated",
+				"permission": "ALLOW",
+				"property": "getTwoFactorStatus"
+			},
 			{
 				"principalType": "ROLE",
 				"principalId": "$authenticated",

package/dist/lib/loopback.cjs

@@ -311,6 +311,7 @@ var require_loopback = /* @__PURE__ */ require_runtime$1.__commonJSMin(((exports
 	*/
 	require_lib_builtin_models(loopback);
 	loopback.DataSource = juggler.DataSource;
+	loopback.registerNormalizer = juggler.registerNormalizer;
 	function getPackageRoot() {
 		return path.join(__dirname, "..", "..");
 	}

package/dist/lib/rate-limit/remote.cjs

@@ -150,9 +150,11 @@ function installRemoteRateLimiting(app) {
 			});
 		}
 	}
-	app.on("modelRemoted", function() {
-		app.models().forEach(installForModel);
-	});
+	function installForSharedClass(sharedClass) {
+		installForModel(sharedClass?.ctor);
+	}
+	app.on("modelRemoted", installForSharedClass);
+	app.on("remoteMethodAdded", installForSharedClass);
 	app.installRemoteRateLimits = function() {
 		app.models().forEach(installForModel);
 		return app;

package/dist/lib/two-factor/service.cjs

@@ -5,6 +5,10 @@ const require_lib_two_factor_crypto = require("./crypto.cjs");
 const require_lib_two_factor_totp = require("./totp.cjs");
 const require_lib_two_factor_recovery_codes = require("./recovery-codes.cjs");
 //#region src/lib/two-factor/service.ts
+var service_exports = /* @__PURE__ */ require_runtime.__exportAll({
+	TWO_FACTOR_ENROLLMENT_SCOPE: () => TWO_FACTOR_ENROLLMENT_SCOPE,
+	TwoFactorService: () => TwoFactorService
+});
 function count(result) {
 	return typeof result === "number" ? result : Number(result?.count || 0);
 }
@@ -30,6 +34,9 @@ function invoke(target, name, args) {
 		if (result && typeof result.then === "function") result.then((value) => done(null, value), done);
 	});
 }
+function hasEnrollmentScope(token) {
+	return Array.isArray(token?.scopes) && token.scopes.includes("two-factor-enrollment");
+}
 function includeUser(include) {
 	if (Array.isArray(include)) return include.map(String).map((v) => v.toLowerCase()).includes("user");
 	return String(include || "").toLowerCase() === "user";
@@ -40,12 +47,13 @@ function loginError() {
 	error.code = "LOGIN_FAILED";
 	return error;
 }
-var TwoFactorService;
+var TWO_FACTOR_ENROLLMENT_SCOPE, TwoFactorService;
 var init_service = require_runtime.__esmMin((() => {
 	require_lib_two_factor_errors.init_errors();
 	require_lib_two_factor_crypto.init_crypto();
 	require_lib_two_factor_totp.init_totp();
 	require_lib_two_factor_recovery_codes.init_recovery_codes();
+	TWO_FACTOR_ENROLLMENT_SCOPE = "two-factor-enrollment";
 	TwoFactorService = class {
 		User;
 		config;
@@ -84,12 +92,31 @@ var init_service = require_runtime.__esmMin((() => {
 		confirmEnrollment(userId, request, options, callback) {
 			return optionalCallback(this.confirmEnrollmentInternal(userId, request || {}, options || {}), callback);
 		}
+		status(userId, options, callback) {
+			return optionalCallback(this.statusInternal(userId, options || {}), callback);
+		}
 		regenerateRecoveryCodes(userId, request, options, callback) {
 			return optionalCallback(this.regenerateRecoveryCodesInternal(userId, request || {}, options || {}), callback);
 		}
 		disable(userId, request, options, callback) {
 			return optionalCallback(this.disableInternal(userId, request || {}, options || {}), callback);
 		}
+		/**
+		* Removes the second factor of another user, e.g. after the device and the
+		* recovery codes were lost. Called through `User.resetTwoFactor` once the
+		* actor proved itself (`proveActor`); see its warning.
+		*/
+		reset(principalId, options, callback) {
+			return optionalCallback(this.resetInternal(String(principalId), options || {}), callback);
+		}
+		/**
+		* Step-up for an operation on another user: the actor of `options` signs
+		* it with their password, and with their authenticator code when they use
+		* a second factor. Recovery codes are not accepted here.
+		*/
+		proveActor(actorId, request, options, callback) {
+			return optionalCallback(this.proveActorInternal(String(actorId), request || {}, options || {}), callback);
+		}
 		deletePrincipals(principalIds, callback) {
 			return optionalCallback(this.deletePrincipalsInternal(principalIds.map(String)), callback);
 		}
@@ -147,6 +174,7 @@ var init_service = require_runtime.__esmMin((() => {
 			} }) : null;
 			if (!credential) {
 				if (this.rateLimiter) await this.rateLimiter.reset(observed);
+				if (await this.isRequired(user, options)) return this.issueEnrollmentToken(user, normalizedInclude);
 				return this.issueAccessToken(user, credentials, normalizedInclude, false);
 			}
 			const secondFactorObserved = [];
@@ -268,6 +296,32 @@ var init_service = require_runtime.__esmMin((() => {
 			if (includeUser(include)) token.__data.user = user;
 			return token;
 		}
+		/**
+		* Issues the session of a user that must enroll before using the API. The
+		* token has to come back restricted: an application `createAccessToken`
+		* override may swap the scope (e.g. a forced password change), but an
+		* unrestricted token would bypass the requirement, so it is revoked.
+		*/
+		async issueEnrollmentToken(user, include) {
+			const config = this.requireConfig(true);
+			const token = await invoke(user, "createAccessToken", [{
+				ttl: Math.ceil(config.enrollmentTtlMs / 1e3),
+				scopes: [TWO_FACTOR_ENROLLMENT_SCOPE]
+			}, {}]);
+			if (!token?.id) throw require_lib_two_factor_errors.authError("AUTHENTICATION_SECURITY_UNAVAILABLE", 503);
+			const scopes = token.scopes;
+			if (!Array.isArray(scopes) || !scopes.length || scopes.includes("DEFAULT")) {
+				await this.revokeToken(token);
+				throw require_lib_two_factor_errors.authError("AUTHENTICATION_SECURITY_UNAVAILABLE", 503);
+			}
+			if (includeUser(include)) token.__data.user = user;
+			return token;
+		}
+		/** Enrollment can only be demanded while users are able to enroll. */
+		async isRequired(user, options) {
+			if (this.config?.mode !== "enroll-and-verify") return false;
+			return await invoke(this.User, "isTwoFactorRequired", [user, options]) === true;
+		}
 		async buildTwoFactorTokenOptions(credentials, options) {
 			return invoke(this.User, "buildTwoFactorLoginContext", [credentials, options]);
 		}
@@ -607,6 +661,21 @@ var init_service = require_runtime.__esmMin((() => {
 				throw require_lib_two_factor_errors.authError("AUTHENTICATION_SECURITY_UNAVAILABLE", 503, "Authentication security reconciliation required");
 			}
 		}
+		async statusInternal(userId, options) {
+			const config = this.requireConfig();
+			const user = await this.authenticatedUser(userId, options);
+			const enabled = config.mode !== "disabled" && await this.Credential.count({
+				principalType: this.User.modelName,
+				principalId: String(userId),
+				provider: "totp",
+				status: "enabled"
+			}) > 0;
+			return {
+				mode: config.mode,
+				enabled,
+				required: await this.isRequired(user, options)
+			};
+		}
 		async beginEnrollmentInternal(userId, request, options) {
 			const config = this.requireConfig(true);
 			const user = await this.authenticatedUser(userId, options);
@@ -707,7 +776,7 @@ var init_service = require_runtime.__esmMin((() => {
 			const generated = require_lib_two_factor_recovery_codes.generateRecoveryCodes(config.recoveryCodeCount, config.recoveryCodeBytes);
 			await this.persistRecoverySet(credential, generated);
 			try {
-				await this.revokeSessions(principalId, options, config.sessions.onEnable);
+				await this.revokeSessions(principalId, options, hasEnrollmentScope(options.accessToken) ? "revoke-all" : config.sessions.onEnable);
 				if (count(await this.Credential.updateAll({
 					id: credential.id,
 					status: "pending",
@@ -941,8 +1010,44 @@ var init_service = require_runtime.__esmMin((() => {
 				status: "unused"
 			}) !== rows.length) throw new Error("Incomplete recovery code set");
 		}
+		async proveActorInternal(actorId, request, options) {
+			const config = this.requireConfig();
+			const actor = await this.authenticatedUser(actorId, options);
+			const observed = await this.reauthenticateManagement(actor, request.currentPassword);
+			const credential = config.mode === "disabled" ? null : await this.Credential.findOne({ where: {
+				principalType: this.User.modelName,
+				principalId: actorId,
+				provider: "totp",
+				status: "enabled"
+			} });
+			if (credential) {
+				if (!(await this.verifyCredentialFactor(credential, "totp", request.totpCode, `management:${require_lib_two_factor_crypto.randomToken(16)}`)).valid) {
+					await this.consumeManagementFailure(actorId);
+					throw require_lib_two_factor_errors.invalidFactor();
+				}
+			}
+			if (this.rateLimiter && observed) await this.rateLimiter.reset([observed]);
+		}
+		async resetInternal(principalId, options) {
+			this.requireConfig();
+			const token = options.accessToken;
+			if (!token || token.userId == null) throw require_lib_two_factor_errors.authError("AUTHORIZATION_REQUIRED", 401, "Authorization required");
+			if (String(token.userId) === principalId && (!("principalType" in token) || token.principalType === this.User.modelName)) throw require_lib_two_factor_errors.authError("TWO_FACTOR_RESET_SELF", 403, "Use disable to change your own factor");
+			if (!await this.User.findById(principalId)) throw require_lib_two_factor_errors.authError("NOT_FOUND", 404, "User not found");
+			await this.revokeSessions(principalId, {}, "revoke-all");
+			await this.destroyFactors([principalId]);
+			this.audit("twoFactorReset", {
+				principalId,
+				actorPrincipalType: token.principalType ?? this.User.modelName,
+				actorPrincipalId: String(token.userId)
+			});
+			return { enabled: false };
+		}
 		async deletePrincipalsInternal(principalIds) {
 			if (!principalIds.length) return;
+			await Promise.all([this.destroyFactors(principalIds), this.rateLimiter ? Promise.all(principalIds.map((principalId) => this.rateLimiter.deletePrincipal(principalId))) : Promise.resolve()]);
+		}
+		async destroyFactors(principalIds) {
 			const credentialIds = (await this.Credential.find({
 				where: {
 					principalType: this.User.modelName,
@@ -959,8 +1064,7 @@ var init_service = require_runtime.__esmMin((() => {
 				this.Credential.destroyAll({
 					principalType: this.User.modelName,
 					principalId: { inq: principalIds }
-				}),
-				this.rateLimiter ? Promise.all(principalIds.map((principalId) => this.rateLimiter.deletePrincipal(principalId))) : Promise.resolve()
+				})
 			]);
 		}
 		async rotateEncryptionInternal(options) {
@@ -1099,6 +1203,7 @@ var init_service = require_runtime.__esmMin((() => {
 }));
 //#endregion
 init_service();
+exports.TWO_FACTOR_ENROLLMENT_SCOPE = TWO_FACTOR_ENROLLMENT_SCOPE;
 exports.TwoFactorService = TwoFactorService;
 Object.defineProperty(exports, "init_service", {
 	enumerable: true,
@@ -1106,3 +1211,9 @@ Object.defineProperty(exports, "init_service", {
 		return init_service;
 	}
 });
+Object.defineProperty(exports, "service_exports", {
+	enumerable: true,
+	get: function() {
+		return service_exports;
+	}
+});

package/dist/lib/two-factor/service.d.cts

@@ -1,6 +1,12 @@
 import { NormalizedTwoFactorConfig } from "./config.cjs";
 import { AuthenticationRateLimiter } from "./rate-limit.cjs";
 //#region src/lib/two-factor/service.d.ts
+/**
+ * Scope of the access token issued at login when the application requires a
+ * second factor (`User.isTwoFactorRequired`) and the user has not enrolled yet.
+ * It only reaches the methods that complete the enrollment.
+ */
+declare const TWO_FACTOR_ENROLLMENT_SCOPE = "two-factor-enrollment";
 declare class TwoFactorService {
   private readonly User;
   private readonly config;
@@ -23,12 +29,31 @@ declare class TwoFactorService {
     enabled: boolean;
     recoveryCodes: string[];
   }>;
+  status(userId: any, options: any, callback?: Function): Promise<{
+    mode: "disabled" | "verify-only" | "enroll-and-verify";
+    enabled: boolean;
+    required: boolean;
+  }>;
   regenerateRecoveryCodes(userId: any, request: any, options: any, callback?: Function): Promise<{
     recoveryCodes: any;
   }>;
   disable(userId: any, request: any, options: any, callback?: Function): Promise<{
     enabled: boolean;
   }>;
+  /**
+   * Removes the second factor of another user, e.g. after the device and the
+   * recovery codes were lost. Called through `User.resetTwoFactor` once the
+   * actor proved itself (`proveActor`); see its warning.
+   */
+  reset(principalId: any, options: any, callback?: Function): Promise<{
+    enabled: boolean;
+  }>;
+  /**
+   * Step-up for an operation on another user: the actor of `options` signs
+   * it with their password, and with their authenticator code when they use
+   * a second factor. Recovery codes are not accepted here.
+   */
+  proveActor(actorId: any, request: any, options: any, callback?: Function): Promise<void>;
   deletePrincipals(principalIds: ReadonlyArray<any>, callback?: Function): Promise<void>;
   rotateEncryption(options?: any, callback?: Function): Promise<{
     credentialsReencrypted: number;
@@ -45,6 +70,15 @@ declare class TwoFactorService {
   private resolveSource;
   private hasPassword;
   private issueAccessToken;
+  /**
+   * Issues the session of a user that must enroll before using the API. The
+   * token has to come back restricted: an application `createAccessToken`
+   * override may swap the scope (e.g. a forced password change), but an
+   * unrestricted token would bypass the requirement, so it is revoked.
+   */
+  private issueEnrollmentToken;
+  /** Enrollment can only be demanded while users are able to enroll. */
+  private isRequired;
   private buildTwoFactorTokenOptions;
   private secretAad;
   private challengeAad;
@@ -58,6 +92,7 @@ declare class TwoFactorService {
   private confirmRecoveryReservation;
   private releaseRecoveryReservation;
   private compensateChallengeFailure;
+  private statusInternal;
   private beginEnrollmentInternal;
   private confirmEnrollmentInternal;
   private regenerateRecoveryCodesInternal;
@@ -67,7 +102,10 @@ declare class TwoFactorService {
   private consumeManagementFailure;
   private enabledCredential;
   private persistRecoverySet;
+  private proveActorInternal;
+  private resetInternal;
   private deletePrincipalsInternal;
+  private destroyFactors;
   private rotateEncryptionInternal;
   private revokeSessions;
   private revokeToken;
@@ -75,4 +113,4 @@ declare class TwoFactorService {
   private audit;
 }
 //#endregion
-export { TwoFactorService };
+export { TWO_FACTOR_ENROLLMENT_SCOPE, TwoFactorService };

package/dist/package.cjs

@@ -2,7 +2,7 @@
 var require_package = /* @__PURE__ */ require("./_virtual/_rolldown/runtime.cjs").__commonJSMin(((exports, module) => {
 	module.exports = {
 		"name": "@vsaas/loopback",
-		"version": "12.3.1",
+		"version": "12.5.0",
 		"description": "Fork of LoopBack 3 framework for building APIs and microservices in Node.js",
 		"keywords": [
 			"StrongLoop",

package/docs/application-guide.md

@@ -1031,6 +1031,132 @@ that the validation entrypoint itself remains callback-oriented. In
 promise-first codebases, persisting with `await` is usually the cleanest way to
 run `validatePromise` rules.
 
+### Property normalization
+
+String properties can declare `normalize`, an ordered list of steps applied
+before validation and persistence. With `trim`, a `required` property rejects
+`"   "` instead of storing it.
+
+```json
+"properties": {
+  "email": { "type": "string", "required": true, "normalize": ["trim", "lowercase"] },
+  "name": { "type": "string", "normalize": ["trim", "collapseSpaces", "nfc"] },
+  "nickname": { "type": "string", "normalize": ["trim", "emptyToNull"] },
+  "bio": { "type": "string", "normalize": ["stripHtml", "trim"] },
+  "tags": { "type": ["string"], "normalize": ["trim", "lowercase"] }
+}
+```
+
+Built-in steps:
+
+| Name             | Effect                                                                |
+| ---------------- | --------------------------------------------------------------------- |
+| `trim`           | Remove leading and trailing whitespace                                |
+| `lowercase`      | Lowercase                                                             |
+| `uppercase`      | Uppercase                                                             |
+| `nfc`            | Unicode NFC normalization                                             |
+| `unaccent`       | Remove diacritics (`Ñandú` → `Nandu`)                                 |
+| `collapseSpaces` | Replace whitespace runs, newlines included, with one space            |
+| `emptyToNull`    | Store `""` as `null`; place it after `trim` to also catch blanks      |
+| `stripInvisible` | Remove control, zero-width, bidi-override and BOM characters          |
+| `numeric`        | Keep digits only                                                      |
+| `alphanumeric`   | Keep letters and digits only                                          |
+| `stripHtml`      | Drop tags, comments and `script`/`style` content; keep the plain text |
+
+`stripHtml` neither decodes nor escapes entities: `Tom & Jerry` stays as is
+and `a < b` is kept. It is data hygiene, not XSS protection; still escape on
+output. It keeps no markup, so it is not meant for rich-text fields.
+
+Register project-specific steps before models are defined, for example at the
+top of `server/server.js`, and reference them by name. Inline functions also
+work in programmatic models. A step returning `null` or `undefined` ends the
+pipeline with that value.
+
+```js
+loopback.registerNormalizer('rut', (value) => value.replace(/[.\s]/g, '').toUpperCase());
+```
+
+When it runs:
+
+- On every assignment through the model: `create`, `createAll`, `save`,
+  `patchAttributes`/`updateAttributes`, `updateAttribute`, `replaceById`,
+  `replaceOrCreate`, `patchOrCreate`/`upsert`, `upsertWithWhere`,
+  `findOrCreate`, relation and embedded-model writes, and values set by
+  `before save` hooks. `persist` hooks already see normalized data.
+- On partial updates, only the properties present in the payload are
+  normalized; other stored values are untouched. `updateAll` normalizes its
+  data, and validates the same values it persists.
+- On `where` filters, values compared for equality (`eq`, `neq`, `inq`, `nin`
+  and plain values) are normalized like stored values, so
+  `{ email: ' Ana@X.com ' }` matches `ana@x.com`. Pattern and range operators
+  (`like`, `ilike`, `regexp`, `gt`, `between`, …) are left as written.
+- Not on reads: rows written before a property gained `normalize` are returned
+  as stored. They are normalized the next time they are written through
+  `save()`, so migrate existing data when you add a step that changes it,
+  especially `lowercase`, since equality filters will no longer match the old
+  values.
+- Not inside extended operators (`$set`, `$push`, …) or custom property
+  setters; both receive the value as written.
+
+Unknown step names, or `normalize` on a non-string property, throw when the
+model is defined.
+
+### Property constraints
+
+Properties can declare the JSON Schema keywords that the API explorer already
+publishes, and they are enforced as model validations. They are checked after
+normalization, so `"normalize": "trim"` with `"maxLength": 128` validates the
+trimmed value.
+
+```json
+"properties": {
+  "name": { "type": "string", "required": true, "maxLength": 128, "normalize": "trim" },
+  "code": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{4}$" },
+  "contact": { "type": "string", "format": "email" },
+  "operability": { "type": "number", "min": 0, "max": 100 },
+  "mode": { "type": "string", "enum": ["NONE", "CRON"] },
+  "tags": { "type": ["string"], "maxItems": 20, "maxLength": 32 }
+}
+```
+
+| Keyword                          | Applies to              | Error code                                  |
+| -------------------------------- | ----------------------- | ------------------------------------------- |
+| `minLength`, `maxLength`         | strings                 | `length.min`, `length.max`                  |
+| `pattern`                        | strings                 | `format`                                    |
+| `format`                         | strings                 | `format.email`, `format.uri`, `format.uuid` |
+| `minimum`/`min`, `maximum`/`max` | numbers                 | `range.min`, `range.max`                    |
+| `enum`                           | string, number, boolean | `inclusion`                                 |
+| `minItems`, `maxItems`           | arrays                  | `items.min`, `items.max`                    |
+
+- Lengths count Unicode characters, so an emoji counts as one.
+- Bounds are inclusive. `min`/`max` are aliases of `minimum`/`maximum`.
+- On array properties, `minItems`/`maxItems` apply to the array and the other
+  keywords to each item.
+- `format` validates `email`, `uri` (absolute) and `uuid`. Other formats, such
+  as `date-time` or `int32`, are documentation only.
+- Constraints only check present values: `null` and `undefined` pass, and
+  `required` decides whether a value must be present. An empty string is a
+  value; use `"normalize": ["trim", "emptyToNull"]` to treat blanks as absent.
+- A keyword on a property of the wrong type, or an invalid limit, throws when
+  the model is defined.
+
+Failures are regular validation errors: the write is rejected with
+`ValidationError` (HTTP 422) and `error.details.codes` lists the codes above
+per property.
+
+Constraints run wherever model validation runs: `create`, `save`,
+`patchAttributes`, `replaceById`, `replaceOrCreate`, `upsertWithWhere`, and
+`patchOrCreate` with `validateUpsert: true`. Two writes skip full validation by
+default because their partial data would fail `required`: `updateAll` (unless
+`validateUpdate: true`) and `patchOrCreate` (unless `validateUpsert: true`).
+They still check the constraints of the properties they write. Passing
+`{ validate: false }`, or setting `validateUpdate`/`validateUpsert` or
+`automaticValidation` to `false`, skips both.
+
+Constraints declared on existing models start being enforced when you upgrade.
+Writes of values outside them, including a `patchAttributes` that leaves an
+invalid stored value untouched, will be rejected, so fix stored data first.
+
 ## Optional packages
 
 ### `@vsaas/loopback-component-storage`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsaas/loopback",
-  "version": "12.3.1",
+  "version": "12.5.0",
   "description": "Fork of LoopBack 3 framework for building APIs and microservices in Node.js",
   "keywords": [
     "StrongLoop",
@@ -104,9 +104,9 @@
     "nodemailer": "^9.1.1",
     "otplib": "13.4.1",
     "serve-favicon": "^2.5.1",
-    "@vsaas/remoting": "^13.0.2",
-    "@vsaas/loopback-datasource-juggler": "^13.0.3",
-    "@vsaas/loopback-connector-remote": "^12.0.2"
+    "@vsaas/loopback-connector-remote": "^12.0.2",
+    "@vsaas/loopback-datasource-juggler": "^13.1.0",
+    "@vsaas/remoting": "^13.0.2"
   },
   "devDependencies": {
     "@types/node": "25.5.0",