@contember/engine-tenant-api 2.1.0-rc.3 → 2.2.0-alpha.10

package/src/model/service/OtpManager.ts

@@ -1,32 +1,104 @@
-import { PersonRow } from '../queries'
-import { ConfirmOtpCommand, DisableOtpCommand, PrepareOtpCommand } from '../commands'
-import { DatabaseContext } from '../utils'
-import { OtpAuthenticator, OtpData } from './OtpAuthenticator'
+import { PersonRow } from '../queries/index.js'
+import { ConfirmOtpCommand, DisableOtpCommand, PrepareOtpCommand, ReEncryptOtpSecretCommand } from '../commands/index.js'
+import { DatabaseContext } from '../utils/index.js'
+import { OtpAuthenticator, OtpData } from './OtpAuthenticator.js'
+import { Providers } from '../providers.js'
+import { URI } from 'otpauth'
+
+type SecretLike = { uri: string } | { secret: string }
+
+/**
+ * Result of resolving a stored secret: the material the authenticator can
+ * validate against, plus (optionally) the base32 secret and the version it was
+ * stored under, so a successful verify can opportunistically re-encrypt it.
+ */
+type ResolvedSecret = {
+	secretLike: SecretLike
+	/** Set when the active secret should be re-encrypted after a successful verify. */
+	reEncrypt?: { oldVersion: number; base32: string }
+}
 
 export class OtpManager {
 	constructor(
 		private readonly otpAuthenticator: OtpAuthenticator,
+		private readonly providers: Pick<Providers, 'decrypt' | 'encrypt' | 'encryptionEnabled'>,
 	) {}
 
 	async prepareOtp(dbContext: DatabaseContext, person: PersonRow, label: string): Promise<OtpData> {
 		const otp = await this.otpAuthenticator.create(person.email ?? person.name ?? 'unnamed', label)
-		await dbContext.commandBus.execute(new PrepareOtpCommand(person.id, otp.uri))
+		if (this.providers.encryptionEnabled) {
+			// A key is configured: store the base32 secret encrypted (version >= 1).
+			const encrypted = await this.providers.encrypt(Buffer.from(otp.secret, 'utf8'))
+			await dbContext.commandBus.execute(new PrepareOtpCommand(person.id, encrypted.value, encrypted.version))
+		} else {
+			// No key: store the plaintext otpauth URI as version 0, exactly like legacy
+			// (pre-encryption) secrets. Opportunistic re-encryption upgrades it once a key
+			// becomes available.
+			await dbContext.commandBus.execute(new PrepareOtpCommand(person.id, Buffer.from(otp.uri, 'utf8'), 0))
+		}
 		return otp
 	}
 
-	async confirmOtp(dbContext: DatabaseContext, person: PersonRow): Promise<void> {
-		await dbContext.commandBus.execute(new ConfirmOtpCommand(person.id))
+	/** Promotes the pending TOTP secret to active. Returns false if there was no pending secret to promote (e.g. a lost concurrent confirm). */
+	async confirmOtp(dbContext: DatabaseContext, person: PersonRow): Promise<boolean> {
+		return await dbContext.commandBus.execute(new ConfirmOtpCommand(person.id))
 	}
 
 	async disableOtp(dbContext: DatabaseContext, person: PersonRow): Promise<void> {
 		await dbContext.commandBus.execute(new DisableOtpCommand(person.id))
 	}
 
-	verifyOtp(person: PersonRow, token: string): boolean {
-		if (!person.otp_uri) {
+	/** Verifies a token against the person's *active* TOTP secret. */
+	async verifyOtp(dbContext: DatabaseContext, person: PersonRow, token: string): Promise<boolean> {
+		const resolved = await this.resolveSecret(person.otp_secret, person.otp_secret_version)
+		const valid = this.otpAuthenticator.validate(resolved.secretLike, token)
+		if (valid && resolved.reEncrypt) {
+			// Best-effort: re-encryption must never affect the verify result and any
+			// failure (encrypt or update) is swallowed so the user still signs in.
+			try {
+				const { oldVersion, base32 } = resolved.reEncrypt
+				const encrypted = await this.providers.encrypt(Buffer.from(base32, 'utf8'))
+				await dbContext.commandBus.execute(
+					new ReEncryptOtpSecretCommand(person.id, encrypted.value, encrypted.version, oldVersion),
+				)
+			} catch {
+				// ignore — re-encryption is opportunistic
+			}
+		}
+		return valid
+	}
+
+	/** Verifies a token against the person's *pending* TOTP secret (used during enrollment). */
+	async verifyPendingOtp(person: PersonRow, token: string): Promise<boolean> {
+		const resolved = await this.resolveSecret(person.otp_pending_secret, person.otp_pending_version)
+		return this.otpAuthenticator.validate(resolved.secretLike, token)
+	}
+
+	/**
+	 * Resolves the stored secret bytes into something the authenticator understands.
+	 * Version 0 = legacy plaintext otpauth URI. Version >= 1 = encrypted base32 secret.
+	 *
+	 * Also surfaces whether the active secret warrants opportunistic re-encryption:
+	 * version-0 (legacy plaintext) always does; version>=1 does when the encryption
+	 * layer signals the key has rotated (`needsReEncrypt`).
+	 */
+	private async resolveSecret(secret: Buffer | null, version: number | null): Promise<ResolvedSecret> {
+		if (!secret || version === null) {
 			throw new OtpError('not configured')
 		}
-		return this.otpAuthenticator.validate({ uri: person.otp_uri }, token)
+		if (version === 0) {
+			const uri = secret.toString('utf8')
+			return {
+				secretLike: { uri },
+				reEncrypt: { oldVersion: 0, base32: URI.parse(uri).secret.base32 },
+			}
+		}
+		const decrypted = await this.providers.decrypt(secret, version)
+		const base32 = decrypted.value.toString('utf8')
+		return {
+			secretLike: { secret: base32 },
+			...(decrypted.needsReEncrypt ? { reEncrypt: { oldVersion: version, base32 } } : {}),
+		}
 	}
 }
 

package/src/model/service/PanelAccessResolver.ts

@@ -0,0 +1,32 @@
+import { DatabaseContext } from '../utils/index.js'
+import { AllProjectRolesByIdentityQuery, ConfigurationQuery } from '../queries/index.js'
+import { Providers } from '../providers.js'
+
+/**
+ * Decides whether an identity may enter the management panel served by the engine.
+ *
+ * This is an **entry gate for the console, not an authorization system**: everything the panel shows
+ * still goes through the tenant ACL, and whoever gets in could equally call `/tenant` directly. Its
+ * job is to keep the console door shut for accounts that have no business there, so an admin surface
+ * on a public API port does not look like a leak.
+ *
+ * An identity is allowed when it holds one of `globalRoles`, or a membership with one of
+ * `projectRoles` in **any** project. Empty lists mean nobody.
+ */
+export class PanelAccessResolver {
+	constructor(private readonly providers: Providers) {}
+
+	async isAllowed(db: DatabaseContext, identityId: string, globalRoles: readonly string[]): Promise<boolean> {
+		const config = await db.queryHandler.fetch(new ConfigurationQuery(this.providers))
+		const policy = config.panel
+
+		if (policy.globalRoles.some(role => globalRoles.includes(role))) {
+			return true
+		}
+		if (policy.projectRoles.length === 0) {
+			return false
+		}
+		const projectRoles = await db.queryHandler.fetch(new AllProjectRolesByIdentityQuery(identityId))
+		return projectRoles.some(it => policy.projectRoles.includes(it.role))
+	}
+}

package/src/model/service/PasswordChangeManager.ts

@@ -1,10 +1,10 @@
-import { ChangeMyPasswordErrorCode, ChangePasswordErrorCode, WeakPasswordReason } from '../../schema'
-import { ChangePasswordCommand } from '../commands'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { ConfigurationQuery, PersonRow } from '../queries'
-import { Providers } from '../providers'
-import { DatabaseContext } from '../utils'
-import { PasswordStrengthValidator } from './PasswordStrengthValidator'
+import { ChangeMyPasswordErrorCode, ChangePasswordErrorCode, WeakPasswordReason } from '../../schema/index.js'
+import { ChangePasswordCommand } from '../commands/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { ConfigurationQuery, PersonRow } from '../queries/index.js'
+import { Providers } from '../providers.js'
+import { DatabaseContext } from '../utils/index.js'
+import { PasswordStrengthValidator } from './PasswordStrengthValidator.js'
 
 class PasswordChangeManager {
 	constructor(
@@ -17,7 +17,7 @@ class PasswordChangeManager {
 		person: PersonRow,
 		password: string,
 	): Promise<PasswordChangeManager.PasswordChangeResponse<ChangePasswordErrorCode>> {
-		const config = await dbContext.queryHandler.fetch(new ConfigurationQuery())
+		const config = await dbContext.queryHandler.fetch(new ConfigurationQuery(dbContext.providers))
 		const passwordVerifyResult = await this.passwordStrengthVerifier.verify(password, config.password, 'TOO_WEAK')
 		if (!passwordVerifyResult.ok) {
 			return passwordVerifyResult
@@ -32,7 +32,7 @@ class PasswordChangeManager {
 		currentPassword: string,
 		password: string,
 	): Promise<PasswordChangeManager.PasswordChangeResponse<ChangeMyPasswordErrorCode>> {
-		const config = await dbContext.queryHandler.fetch(new ConfigurationQuery())
+		const config = await dbContext.queryHandler.fetch(new ConfigurationQuery(dbContext.providers))
 		const passwordVerifyResult = await this.passwordStrengthVerifier.verify(password, config.password, 'TOO_WEAK')
 		if (!passwordVerifyResult.ok) {
 			return passwordVerifyResult

package/src/model/service/PasswordResetManager.ts

@@ -1,16 +1,17 @@
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { UserMailer } from '../mailing'
-import { ConfigurationQuery, PersonRow } from '../queries'
-import { PermissionContext } from '../authorization'
-import { ProjectManager } from './ProjectManager'
-import { DatabaseContext } from '../utils'
-import { ImplementationException } from '../../exceptions'
-import { getPreferredProject } from './helpers/getPreferredProject'
-import { CreatePersonTokenCommand, ResetPasswordCommand } from '../commands/personToken'
-import { PasswordStrengthValidator } from './PasswordStrengthValidator'
-import { ResetPasswordErrorCode, WeakPasswordReason } from '../../schema'
-import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery'
-import { AuthLogService } from './AuthLogService'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { UserMailer } from '../mailing/index.js'
+import { ConfigurationQuery, LocalAuthDisablingIdpsQuery, PersonRow } from '../queries/index.js'
+import { PermissionContext } from '../authorization/index.js'
+import { ProjectManager } from './ProjectManager.js'
+import { DatabaseContext } from '../utils/index.js'
+import { ImplementationException } from '../../exceptions.js'
+import { getPreferredProject } from './helpers/getPreferredProject.js'
+import { CreatePersonTokenCommand, ResetPasswordCommand } from '../commands/personToken/index.js'
+import { PasswordStrengthValidator } from './PasswordStrengthValidator.js'
+import { ResetPasswordErrorCode, WeakPasswordReason } from '../../schema/index.js'
+import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery.js'
+import { AuthLogService } from './AuthLogService.js'
+import { NextMailAttemptQuery } from '../queries/authLog/NextMailAttemptQuery.js'
 
 interface MailOptions {
 	project?: string
@@ -30,13 +31,32 @@ export class PasswordResetManager {
 		person: PersonRow,
 		mailOptions: MailOptions = {},
 	): Promise<void> {
-		const result = await dbContext.commandBus.execute(CreatePersonTokenCommand.createPasswordResetRequest(person.id))
-		const projects = await this.projectManager.getProjectsByIdentity(dbContext, person.identity_id, permissionContext)
-		const project = getPreferredProject(projects, mailOptions.project ?? null)
 		if (!person.email) {
 			throw new ImplementationException()
 		}
 
+		// A person federated through a provider with `disableLocalAuthentication`
+		// cannot sign in with a password, so a reset mail would only offer them a
+		// credential the tenant refuses — and one more link worth phishing.
+		const exclusiveIdps = await dbContext.queryHandler.fetch(new LocalAuthDisablingIdpsQuery(person.id))
+		if (exclusiveIdps.length > 0) {
+			return
+		}
+
+		// Per-email exponential backoff on outbound mails — don't spam a real
+		// user with reset mails just because attackers keep poking the
+		// endpoint. Reuses login_* backoff config against person_auth_log.
+		const retryAfter = await dbContext.queryHandler.fetch(
+			new NextMailAttemptQuery(person.email, 'password_reset_init', 'password_reset'),
+		)
+		if (retryAfter > 0) {
+			return
+		}
+
+		const result = await dbContext.commandBus.execute(CreatePersonTokenCommand.createPasswordResetRequest(person.id))
+		const projects = await this.projectManager.getProjectsByIdentity(dbContext, person.identity_id, permissionContext)
+		const project = getPreferredProject(projects, mailOptions.project ?? null)
+
 		await this.mailer.sendPasswordResetEmail(
 			dbContext,
 			{
@@ -53,7 +73,7 @@ export class PasswordResetManager {
 	}
 
 	public async resetPassword(dbContext: DatabaseContext, token: string, password: string): Promise<ResetPasswordResponse> {
-		const config = await dbContext.queryHandler.fetch(new ConfigurationQuery())
+		const config = await dbContext.queryHandler.fetch(new ConfigurationQuery(dbContext.providers))
 		const tokenRow = await dbContext.queryHandler.fetch(PersonTokenQuery.byToken(token, 'password_reset'))
 		if (!tokenRow) {
 			return new ResponseError('TOKEN_NOT_FOUND', 'Token not found', {

package/src/model/service/PasswordStrengthValidator.ts

@@ -1,9 +1,14 @@
-import { Config } from '../type/Config'
-import { blacklist } from '../utils/blacklist'
-import { WeakPasswordReason } from '../../schema'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
+import { Config } from '../type/Config.js'
+import { blacklist } from '../utils/blacklist.js'
+import { WeakPasswordReason } from '../../schema/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { HibpChecker, NoopHibpChecker } from './HibpChecker.js'
 
 export class PasswordStrengthValidator {
+	constructor(
+		private readonly hibpChecker: HibpChecker = new NoopHibpChecker(),
+	) {}
+
 	public async verify<const Code extends string>(
 		password: string,
 		passwordConfig: Config['password'],
@@ -58,6 +63,11 @@ export class PasswordStrengthValidator {
 			developerMessage.push(`Password is blacklisted.`)
 		}
 
+		if (passwordConfig.checkHibp && await this.hibpChecker.isCompromised(password)) {
+			failureReasons.push('COMPROMISED')
+			developerMessage.push(`Password has appeared in a known data breach.`)
+		}
+
 		if (failureReasons.length > 0) {
 			return new ResponseError(errorCode as any, developerMessage.join(' '), {
 				weakPasswordReasons: failureReasons,

package/src/model/service/PasswordlessSignInManager.ts

@@ -1,32 +1,42 @@
-import { ApiKeyManager } from './apiKey'
-import { ConfigurationQuery, PersonQuery, PersonRow } from '../queries'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
+import { ApiKeyManager } from './apiKey/index.js'
+import { ConfigurationQuery, LocalAuthDisablingIdpsQuery, PersonQuery, PersonRow } from '../queries/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
 import {
 	ActivatePasswordlessOtpErrorCode,
-	ConfigPolicy,
 	InitSignInPasswordlessErrorCode,
 	InitSignInPasswordlessResult,
 	SignInPasswordlessErrorCode,
-} from '../../schema'
-import { DatabaseContext, validateToken } from '../utils'
-import { UserMailer } from '../mailing'
-import { ActivateOtpCommand, CreatePersonTokenCommand, IncreaseOtpAttemptCommand, InvalidateTokenCommand } from '../commands'
-import { getPreferredProject } from './helpers/getPreferredProject'
-import { ProjectManager } from './ProjectManager'
-import { PermissionContext } from '../authorization'
-import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery'
-import { ImplementationException } from '../../exceptions'
-import { OtpAuthenticator } from './OtpAuthenticator'
-import { PersonToken } from '../type'
-import { AuthLogService } from './AuthLogService'
-import { intervalToSeconds } from '../utils/interval'
+} from '../../schema/index.js'
+import { DatabaseContext, validateToken } from '../utils/index.js'
+import { UserMailer } from '../mailing/index.js'
+import {
+	ActivateOtpCommand,
+	ApiKeyRequestInfo,
+	CreatePersonTokenCommand,
+	IncreaseOtpAttemptCommand,
+	InvalidateTokenCommand,
+	MarkEmailVerifiedCommand,
+} from '../commands/index.js'
+import { getPreferredProject } from './helpers/getPreferredProject.js'
+import { isPasswordlessEnabled } from './helpers/isPasswordlessEnabled.js'
+import { ProjectManager } from './ProjectManager.js'
+import { PermissionContext } from '../authorization/index.js'
+import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery.js'
+import { ImplementationException } from '../../exceptions.js'
+import { OtpManager } from './OtpManager.js'
+import { BackupCodeManager } from './BackupCodeManager.js'
+import { PersonToken } from '../type/index.js'
+import { AuthLogService } from './AuthLogService.js'
+import { intervalToSeconds } from '../utils/interval.js'
+import { NextMailAttemptQuery } from '../queries/authLog/NextMailAttemptQuery.js'
 
 class PasswordlessSignInManager {
 	constructor(
 		private readonly apiKeyManager: ApiKeyManager,
 		private readonly mailer: UserMailer,
 		private readonly projectManager: ProjectManager,
-		private readonly otpAuthenticator: OtpAuthenticator,
+		private readonly otpManager: OtpManager,
+		private readonly backupCodeManager: BackupCodeManager,
 	) {}
 
 	async initSignInPasswordless({ db, permissionContext, mailVariant, mailProject, email }: {
@@ -37,7 +47,7 @@ class PasswordlessSignInManager {
 		mailProject?: string
 	}): Promise<PasswordlessSignInManager.InitSignInPasswordlessResponse> {
 		return db.transaction(async (db): Promise<PasswordlessSignInManager.InitSignInPasswordlessResponse> => {
-			const configuration = await db.queryHandler.fetch(new ConfigurationQuery())
+			const configuration = await db.queryHandler.fetch(new ConfigurationQuery(db.providers))
 			if (configuration.passwordless.enabled === 'never') {
 				return new ResponseError('PASSWORDLESS_DISABLED', 'Passwordless sign-in is disabled', {
 					[AuthLogService.Key]: new AuthLogService.Bag({}),
@@ -52,7 +62,17 @@ class PasswordlessSignInManager {
 					}),
 				})
 			}
-			if (!this.isEnabled(configuration.passwordless.enabled, person.passwordless_enabled)) {
+			const exclusiveIdps = await db.queryHandler.fetch(new LocalAuthDisablingIdpsQuery(person.id))
+			if (exclusiveIdps.length > 0) {
+				return new ResponseError('IDP_REQUIRED', `Sign in using ${exclusiveIdps.join(' or ')}`, {
+					[AuthLogService.Key]: new AuthLogService.Bag({
+						personInput: email,
+						personId: person.id,
+					}),
+				})
+			}
+
+			if (!isPasswordlessEnabled(configuration.passwordless.enabled, person.passwordless_enabled)) {
 				return new ResponseError('PASSWORDLESS_DISABLED', 'Passwordless sign-in is disabled for this person', {
 					[AuthLogService.Key]: new AuthLogService.Bag({
 						personInput: email,
@@ -61,6 +81,26 @@ class PasswordlessSignInManager {
 				})
 			}
 
+			// Per-email exponential backoff on outbound mails — bound the spam
+			// pressure on a real user even if attackers spray the endpoint.
+			// Reuses login_* backoff config against person_auth_log.
+			const retryAfter = await db.queryHandler.fetch(
+				new NextMailAttemptQuery(email, 'passwordless_login_init', 'passwordless_login'),
+			)
+			if (retryAfter > 0) {
+				const retryAfterSeconds = Math.max(1, retryAfter)
+				return new ResponseError(
+					'RATE_LIMIT_EXCEEDED',
+					`Too many passwordless sign-in requests for this email. Retry after ${retryAfterSeconds}s.`,
+					{
+						[AuthLogService.Key]: new AuthLogService.Bag({
+							personInput: email,
+							personId: person.id,
+						}),
+					},
+				)
+			}
+
 			const createTokenCommand = CreatePersonTokenCommand.createPasswordlessRequest(
 				person.id,
 				intervalToSeconds(configuration.passwordless.expiration) / 60,
@@ -108,20 +148,22 @@ class PasswordlessSignInManager {
 		return urlObj.toString()
 	}
 
-	async signInPasswordless({ db, expiration, token, requestId, mfaOtp, validationType }: {
+	async signInPasswordless({ db, expiration, token, requestId, mfaOtp, backupCode, validationType, requestInfo, trustForwardedInfo }: {
 		db: DatabaseContext
 		validationType: PersonToken.ValidationType
 		requestId: string
 		token: string
 		mfaOtp?: string
+		backupCode?: string
 		expiration?: number
+		requestInfo?: ApiKeyRequestInfo
+		trustForwardedInfo?: boolean
 	}): Promise<PasswordlessSignInManager.SignInPasswordlessResponse> {
 		return db.transaction(async (db): Promise<PasswordlessSignInManager.SignInPasswordlessResponse> => {
 			const tokenResult = await db.queryHandler.fetch(PersonTokenQuery.byId(requestId, 'passwordless'))
 			const tokenValidationResult = validateToken({
 				entry: tokenResult,
 				token,
-				now: db.providers.now(),
 				validationType,
 			})
 			if (!tokenValidationResult.ok) {
@@ -152,18 +194,41 @@ class PasswordlessSignInManager {
 				})
 			}
 
-			if (personRow.otp_uri && personRow.otp_activated_at) {
-				if (!mfaOtp) {
-					return new ResponseError('OTP_REQUIRED', `2FA is enabled. OTP token is required`, {
-						[AuthLogService.Key]: new AuthLogService.Bag({
-							personId: personRow.id,
-							tokenId: tokenResult?.id,
-						}),
-					})
-				}
+			// Re-checked here and not only at init: a link created while this magic link
+			// was in flight would otherwise still mint a locally authenticated session.
+			const exclusiveIdps = await db.queryHandler.fetch(new LocalAuthDisablingIdpsQuery(personRow.id))
+			if (exclusiveIdps.length > 0) {
+				return new ResponseError('IDP_REQUIRED', `Sign in using ${exclusiveIdps.join(' or ')}`, {
+					[AuthLogService.Key]: new AuthLogService.Bag({
+						personId: personRow.id,
+						tokenId: tokenResult?.id,
+					}),
+				})
+			}
 
-				if (!this.otpAuthenticator.validate({ uri: personRow.otp_uri }, mfaOtp)) {
-					return new ResponseError('INVALID_OTP_TOKEN', 'OTP token validation has failed', {
+			let usedBackupCode = false
+			if (personRow.otp_secret && personRow.otp_activated_at) {
+				if (mfaOtp) {
+					if (!await this.otpManager.verifyOtp(db, personRow, mfaOtp)) {
+						return new ResponseError('INVALID_OTP_TOKEN', 'OTP token validation has failed', {
+							[AuthLogService.Key]: new AuthLogService.Bag({
+								personId: personRow.id,
+								tokenId: tokenResult?.id,
+							}),
+						})
+					}
+				} else if (backupCode) {
+					if (!await this.backupCodeManager.verifyAndConsume(db, personRow, backupCode)) {
+						return new ResponseError('INVALID_OTP_TOKEN', 'OTP token validation has failed', {
+							[AuthLogService.Key]: new AuthLogService.Bag({
+								personId: personRow.id,
+								tokenId: tokenResult?.id,
+							}),
+						})
+					}
+					usedBackupCode = true
+				} else {
+					return new ResponseError('OTP_REQUIRED', `2FA is enabled. OTP token is required`, {
 						[AuthLogService.Key]: new AuthLogService.Bag({
 							personId: personRow.id,
 							tokenId: tokenResult?.id,
@@ -171,16 +236,34 @@ class PasswordlessSignInManager {
 					})
 				}
 			}
+			// NOTE: passwordless sign-in does NOT enforce mandatory-MFA enrollment.
+			// A person with no MFA factor is let through even when an auth_policy would
+			// require MFA — enroll-via-sign-in is password-only, and passwordless email
+			// access is itself a possession factor. An existing factor (TOTP/backup
+			// code, handled above) is still verified. Documented limitation (A06).
 
 			await db.commandBus.execute(new InvalidateTokenCommand(tokenValidationResult.result.id))
-			const sessionToken = await this.apiKeyManager.createSessionApiKey(db, personRow.identity_id, expiration)
+			// Receiving and clicking the magic link proves ownership of the address,
+			// so a successful passwordless sign-in also satisfies the e-mail
+			// verification requirement. Without this, a required-but-unverified
+			// account could obtain a session here while being blocked from password
+			// sign-in (SignInManager) — an inconsistent, exploitable gap.
+			const emailVerifiedNow = personRow.email_verified_at === null
+			if (emailVerifiedNow) {
+				await db.commandBus.execute(new MarkEmailVerifiedCommand(personRow.id))
+			}
+			const sessionToken = await this.apiKeyManager.createSessionApiKey(db, personRow.identity_id, expiration, requestInfo, trustForwardedInfo)
 
 			return new ResponseOk({
 				person: personRow,
 				token: sessionToken,
+				usedBackupCode,
 				[AuthLogService.Key]: new AuthLogService.Bag({
 					personId: personRow.id,
 					tokenId: tokenResult?.id,
+					// Record that this sign-in also satisfied e-mail verification, so
+					// the audit trail shows when/how the address became verified.
+					eventData: emailVerifiedNow ? { emailVerified: true } : undefined,
 				}),
 			})
 		})
@@ -197,7 +280,6 @@ class PasswordlessSignInManager {
 			const tokenValidationResult = validateToken({
 				entry: tokenResult,
 				token,
-				now: db.providers.now(),
 				validationType: 'token',
 			})
 			if (!tokenValidationResult.ok) {
@@ -221,19 +303,6 @@ class PasswordlessSignInManager {
 			})
 		})
 	}
-
-	private isEnabled(globalValue: ConfigPolicy, personValue: boolean | null): boolean {
-		switch (globalValue) {
-			case 'always':
-				return true
-			case 'never':
-				return false
-			case 'optIn':
-				return personValue === true
-			case 'optOut':
-				return personValue !== false
-		}
-	}
 }
 
 namespace PasswordlessSignInManager {
@@ -250,6 +319,8 @@ namespace PasswordlessSignInManager {
 	interface SignInPasswordlessResult {
 		readonly person: PersonRow
 		readonly token: string
+		/** True when MFA was satisfied by consuming a backup code (instead of a TOTP token). */
+		readonly usedBackupCode?: boolean
 		[AuthLogService.Key]: AuthLogService.Bag
 	}
 	export type SignInPasswordlessResponse = Response<SignInPasswordlessResult, SignInPasswordlessErrorCode, {

package/src/model/service/PersonAccessManager.ts

@@ -1,10 +1,11 @@
 import { Logger } from '@contember/logger'
-import { PersonQuery, PersonRow } from '../queries'
-import { DatabaseContext } from '../utils'
-import { DisablePersonCommand } from '../commands/person/DisablePersonCommand'
-import { ApiKeyManager } from './apiKey'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { DisablePersonErrorCode } from '../../schema'
+import { PersonQuery, PersonRow } from '../queries/index.js'
+import { DatabaseContext } from '../utils/index.js'
+import { DisablePersonCommand } from '../commands/person/DisablePersonCommand.js'
+import { EnablePersonCommand } from '../commands/person/EnablePersonCommand.js'
+import { ApiKeyManager } from './apiKey/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { DisablePersonErrorCode, EnablePersonErrorCode } from '../../schema/index.js'
 
 class PersonAccessManager {
 	constructor(private readonly apiKeyManager: ApiKeyManager) {}
@@ -25,6 +26,17 @@ class PersonAccessManager {
 		}, { retry: { logger } })
 	}
 
+	async enablePerson(dbContext: DatabaseContext, person: PersonRow): Promise<PersonEnableAccessResponse> {
+		if (person.disabled_at === null) {
+			return new ResponseError('PERSON_ALREADY_ENABLED', 'Person is already enabled')
+		}
+
+		// Only clears the disabled flag — api keys revoked while disabling stay revoked, the person has to sign in again.
+		await dbContext.commandBus.execute(new EnablePersonCommand(person.id))
+
+		return new ResponseOk(null)
+	}
+
 	private async disablePersonAccount(dbContext: DatabaseContext, personId: string) {
 		await dbContext.commandBus.execute(new DisablePersonCommand(personId))
 	}
@@ -35,5 +47,6 @@ class PersonAccessManager {
 }
 
 export type PersonDisableAccessResponse = Response<null, DisablePersonErrorCode>
+export type PersonEnableAccessResponse = Response<null, EnablePersonErrorCode>
 
 export { PersonAccessManager }

package/src/model/service/PersonManager.ts

@@ -1,9 +1,10 @@
-import { ChangeProfileCommand, ChangeProfileData } from '../commands/person/ChangeProfileCommand'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { PersonQuery, PersonRow } from '../queries'
-import { DatabaseContext } from '../utils'
-import { EmailValidator, EmailValidatorError } from './EmailValidator'
-import { TogglePersonPasswordlessCommand } from '../commands'
+import { ChangeProfileCommand, ChangeProfileData } from '../commands/person/ChangeProfileCommand.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { PersonListRow, PersonQuery, PersonRow, PersonsQuery, PersonsQueryFilter } from '../queries/index.js'
+import { DatabaseContext } from '../utils/index.js'
+import { EmailValidator, EmailValidatorError } from './EmailValidator.js'
+import { TogglePersonPasswordlessCommand } from '../commands/index.js'
+import { normalizeEmail } from '../utils/email.js'
 
 class PersonManager {
 	constructor(
@@ -17,14 +18,31 @@ class PersonManager {
 		)
 	}
 
+	async listPersons(
+		dbContext: DatabaseContext,
+		filter: PersonsQueryFilter = {},
+		limit?: number | null,
+		offset?: number | null,
+	): Promise<PersonListRow[]> {
+		return await dbContext.queryHandler.fetch(new PersonsQuery(filter, limit, offset))
+	}
+
 	async changeProfile(dbContext: DatabaseContext, person: PersonRow, data: ChangeProfileData): Promise<PersonManager.ProfileChangeResponse> {
-		if (data.email !== undefined && person.email !== data.email) {
-			const validationError = await this.emailValidator.validateEmail(dbContext, data.email)
+		// Compare normalized: a case-/whitespace-only edit is not a real change, so
+		// it neither needs re-validation nor should drop the verified status.
+		const emailChanging = data.email !== undefined && person.email !== normalizeEmail(data.email)
+		if (emailChanging) {
+			const validationError = await this.emailValidator.validateEmail(dbContext, data.email!)
 			if (validationError !== null) {
 				return new ResponseError(validationError.error, validationError.errorMessage)
 			}
 		}
-		await dbContext.commandBus.execute(new ChangeProfileCommand(person.id, data))
+		// On a real e-mail change via the direct path (admin changeProfile, or
+		// changeMyProfile when no verification applies) the new address has not
+		// been proven, so any prior verification no longer holds — clear it. For
+		// verification-required accounts this re-arms the sign-in gate; for the
+		// rest email_verified_at was already null, so it is a harmless no-op.
+		await dbContext.commandBus.execute(new ChangeProfileCommand(person.id, data, emailChanging))
 		return new ResponseOk(null)
 	}